telemetry.advanced becomes RecorderOptions.AdvancedMetrics at each session's start. The Agent registers one AdvancedHardwareHub; SessionRecorder holds it for a session's length only when the option is on, and the session's TelemetryPoller gets it on the same condition. A session's facts are read once, off the capture loop, fifteen seconds after the game's process is known or at the session's end; which display is the game's comes from Windows (WindowGeometryProbe.MonitorDeviceOf). Off: not held, not asked, no chunk 9 or 10, no session_advanced row. Settings gains the row (off in a viewer), strings in en/vi/ja, the guide's settings page. Privacy Policy 2.15 names what is read and stored only while the option is on, and what never is. Disclaimer 2.15 (the owner's answer of 2026-11-11, D109): PawnIO and the admin mode are no longer "for the CPU temperature" alone; the admin mode's disclosure follows (agent-admin-dialog/2), with Settings, the first run, the guide and LIMITATIONS.md. The accuracy block gains an item. Nothing in src/native changes. Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
18 KiB
01 — Architecture
Component model
┌──────────────────────────┐ named pipe ┌──────────────────────────────┐
│ FrameLedger.exe (UI) │ FrameLedger.v2 │ FrameLedger.Agent.exe │
│ standard user │◄───────────────►│ standard user (elev. optional)│
│ WPF · Wpf.Ui · ScottPlot │ │ ├ ProcessWatcher │
└──────────────────────────┘ │ ├ AntiCheatGuard* ◄─ 19_SAFETY│
│ ├ Injector (launch / attach) │
SQLite (WAL) ◄────────────────┤ ├ ShmReader (10 Hz drain) │
│ ├ VendorTelemetry (NVAPI/…) │
│ ├ SessionRecorder │
│ (no Tier-2 source: none exists) │
└───────────▲──────────────────┘
shared memory │ Local\FrameLedger.Ring.<pid>
(lock-free SPSC) │
┌────────────────────────────────────────────────────────┴──────────────────┐
│ GAME PROCESS │
│ FrameLedger.Overlay.dll (C++20, injected) or VK_LAYER_FRAMELEDGER_* │
│ ├ present hooks: DXGI (D3D11/12) / OpenGL (Vulkan: implicit layer) │
│ ├ upscaler hooks: NGX · Streamline · FFX · XeSS │
│ ├ RT hooks: CreateStateObject · DispatchRays · BuildRaytracingAS │
│ ├ PSO hooks: pipeline creation (stutter attribution) │
│ ├ (per-process VRAM via QueryVideoMemoryInfo: never built — D43 reads │
│ │ the game's memory from outside, in the Agent's ProcessStats.dll) │
│ └ ring writer (allocation-free, lock-free, SEH-guarded) │
└───────────────────────────────────────────────────────────────────────────┘
Corrected 2026-10-04 — the game-process box names hooks that were never built.
NGX · XeSS · CreateStateObject · PSO hooks: NGX is licence-blocked, XeSS stops at the runtime census by licence, andCreateStateObjectand pipeline creation are unwritten rows of17_HOOK_ENGINE§Hook inventory. What the Overlay does install: the DXGI present path,wglSwapBuffers, the Streamline and FidelityFX entry points, the twoID3D12GraphicsCommandList4ray-tracing methods, and theLoadLibraryExWwake.
*AntiCheatGuardis a facade, not an implementation. The guard is native (20_OPEN_QUESTIONS§S13(a)); the box above is the P/Invoke wrapper inInfrastructurethat the Agent calls. Nothing managed parses rules or matches a blocklist — two matchers that can disagree is a fail-open by construction, and a test asserts there is only one (§S15 item 1).
The Agent box exists as of 2026-09-10 (P2 PR-F).
ProcessWatcherisApplication.Watch(CaptureOrchestratoroverToolhelpProcessSnapshotSource);Injectoris the guard facade reached throughHookedCaptureGate;ShmReaderisCaptureSessionoverShmRingReader;VendorTelemetryis the L1 + L2 + L3 composite;SessionRecorderisApplication.Recording.The named pipe on the left is not built (P3,The pipe's read half is built 2026-09-13 (P3 PR-1):07_IPC), so today's Agent has no UI client:--servelogs,--consoleprints.--servelistens on\\.\pipe\FrameLedger.v2, answersHello/GetStatus/Ping, and narrates every session (SessionStartedat the attach,SessionProgressat 1 Hz, the safety and error events,SessionCompleted);--consolestill prints and hosts no pipe. The command half — the messages a client sends to change a state —is PR-1bis built the same day (PR-1b:SetWatchlist,LaunchGame,SetHookEnabledwith the pre-scan and no stamp until PR-4, pause/resume,StopSession,UpdateRules,Shutdown), and the App that connects is PR-2.
Why this shape
- Hooking in-process is the only way to get the facts we care about. Render resolution vs output resolution, upscaler identity and quality preset, whether frame generation is actually running, whether rays are actually being traced — none of these are observable from outside the process. The previous ETW-only design could only guess from file/module presence, which measured badly against real games.
- The DLL does as little as possible. It records; it does not analyze, log, allocate, or block. All interpretation happens in the Agent. This keeps the game-side risk surface tiny and the overhead near zero.
- Shared memory, not pipes, on the hot path. A present hook must not make a syscall. It writes 64 bytes into a ring and returns.
- The Agent no longer needs elevation for its primary path. Injecting into a same-integrity process, and reading GPU telemetry through vendor user-mode APIs, both work unprivileged. Elevation is optional and unlocks: CPU/board temperatures (LHM + PawnIO) and attaching to games that themselves run elevated.
and the Tier-2 ETW source— and as of 2026-08-28 the honest consequence this sentence used to carry is gone with it. It read: "the fallback tier is the part that needs elevation, so an unelevated Agent whose Tier-1 attempt fails degrades to Tier 3, not Tier 2". There is no ETW tier and no Tier 3, so no capture tier needs elevation at all (04_CAPTURE§Frame source abstraction).
Capture tiers
| Tier | Mechanism | Gets you | When used |
|---|---|---|---|
| 1 | Injected hooks (default when the user enabled it and the guard passed) | Everything: exact render/output res, upscaler + quality, FG ground truth, RT 05_DETECTION §Runtime facts) |
Offline/single-player titles the user opted in |
| 2 | None | Session duration, whatever hardware telemetry this machine can provide, and the REASON there is nothing else — which check refused, or that the hook failed, was not enabled, or the target is 32-bit. Every N/A (FR-4.9) (corrected 2026-10-04: two facts are measured from outside the game in both tiers — the display mode (beta.10) and the game process's memory (beta.12, D43)) |
Guard refused, hook failed, user chose not to hook, or a target the Overlay structurally cannot enter |
Tier is recorded per session (sessions.capture_tier) and shown in the UI, because metric availability differs and comparing across tiers must be explicit.
Injection flow
watcher sees tracked exe launch
→ is hooking enabled for this game? no → Tier 2 (nothing measured)
→ AntiCheatGuard.Check(pid) fail → refuse + explain + Tier 2 (19_SAFETY)
→ Injector.Attach(pid, dllPath) fail → log + Tier 2
OpenProcess(CREATE_THREAD|VM_OPERATION|VM_WRITE|VM_READ|QUERY_LIMITED)
VirtualAllocEx → WriteProcessMemory(dllPath) → CreateRemoteThread(LoadLibraryW)
→ DLL init thread: install hooks, create ring, publish handshake block
→ Agent maps Local\FrameLedger.Ring.<pid>, validates layout version + build id
→ first frame record → session starts
Launch mode (preferred when FrameLedger starts the game): CreateProcess(CREATE_SUSPENDED) → guard → inject → ResumeThread. This catches swapchain creation and early upscaler init, which attach mode can miss. Attach mode remains for games launched from Steam/GOG directly.
Built 2026-09-06 as start → the guard waits for a presentation runtime → the full guard → inject (
FlGuardedInjectWhenReady, P1 item 2), because a suspended target has loaded nothing for the module scan to read (20_OPEN_QUESTIONS§S1). What it costs is measured by the session itself:FlWriterState.dxgiPresentsBeforeHook.04_CAPTURE§Launch mode carries the shape.
Guard re-runs every 30 s for the life of the session; anti-cheat appearing late ⇒ clean unhook (19_SAFETY §During a session).
Lifecycle
-
Agent idles at ~0% CPU: 1 Hz process poll. No capture machinery exists until a tracked game launches.
-
Session ends when the process tree exits, or on safety unhook, or on user stop.
-
The DLL is not unloaded from a live process after unhooking (threads may still be inside trampolines). It disables its hooks, stops writing, and goes dormant until the process exits. Documented, deliberate.
-
UI exit does not stop the Agent when background capture is enabled; otherwise UI sends(Corrected 2026-10-04: closing the UI never stops the Agent.Shutdown.Shutdownis sent only for an update, by the uninstall hook and for the admin mode's restart; the background-capture setting was read by nothing, and its switch is gone since beta.12 —06_DATA_MODEL§Settings registry.) -
Single instance via named mutexes; the ring name is per-PID so multiple games can be captured simultaneously (rare but supported).
-
An alpha build's
--servewaits for the Alpha notice (D74, 2026-10-31): it readslegal_acceptanceafter opening the ledger and, until the App's Legal Gate has recorded the notice at the version the build carries (Shared.AlphaNotice), logs why and exits 8 — the logon task or the admin mode's prompt can start it before the App ever showed the notice. The App holds its own start of the Agent while the gate is open and starts it at the Accept; the maintenance verbs (--register-vklayer,--install-taskand their reverses) are not held. The main line serves as before.The single instance was specified here and not built until 2026-09-17, and 0.1.0-beta.1 ran four Agents: an App started as administrator was refused by the pipe of the Agent already serving (
07_IPC§C, amended the same day), took the refusal for an absent Agent, and started another on each connect round — and every game launched in the next hour was injected, read and recorded by all four. Built:Infrastructure.Startup.AgentInstanceLock, one named mutex per data folder (Local\FrameLedger.Agent.<hash of the folder>), claimed by--serveand the console's capturing verbs (capture,launch,recover) before logging, rules or the ledger; a second process exits 10 with one line on stderr. The App probes the same claim before it starts an Agent (07_IPC§Client behavior). What it does not cover: two Agents on two data folders (a developer's--console --data-dirbeside the installed Agent) can still both attach to one game's ring —20_OPEN_QUESTIONS§G, Agent lifecycle.
Failure domains
| Failure | Behavior |
|---|---|
| Anti-cheat detected pre-injection | Refuse, explain which signal fired, offer Tier 2 |
| Anti-cheat detected mid-session | Immediate clean unhook, exit_status = unhooked_safety, prominent notice |
| Injection API fails (access denied, protected process) | Log, no retry loop, offer Tier 2 + "run Agent elevated" hint — elevation here is about attaching to an elevated target, not about reaching a tier; Tier 2 needs none |
| Hook faults 3× | DLL self-disables, sets FlWriterState.status to SELF_DISABLED (corrected 2026-10-04), Agent finalizes session as degraded |
| Game crashes ≤ 60 s after injection, twice | Hooking auto-disabled for that game, Tier 2 takes over |
| Ring overflow (Agent stalled) | Overwrite-oldest; 04_CAPTURE §Ring draining) → session flagged with a data-quality warning |
| Layout/version mismatch DLL ↔ Agent | Agent refuses to attach, tells user to restart the game after update |
| Vendor API unavailable (no NVAPI etc.) | GPU telemetry degrades to N/A; frame metrics unaffected |
| DB locked/corrupt | Integrity check + backup~~-and-recreate~~ in Tools ▸ Database maintenance (corrected 2026-10-04: there is no recreate action) |
Data directory
%LOCALAPPDATA%\FrameLedger\
ledger.db SQLite (WAL)
rules\detection-rules.json engine/platform/feature + anticheat blocklist
logs\ui-*.log, agent-*.log, overlay-<pid>-*.log (native log flushed at session end, never mid-frame)
crashdumps\*.dmp
breadcrumbs\<pid>.json (corrected 2026-10-04: never created — the breadcrumb is the .partial file's header and notes)
tmp\<sessionGuid>.partial crash-safety flush of raw buffers, every 60 s (04_CAPTURE §Ring draining)
covers\game-<id>-<ms>.png the images users chose for their games (beta.23, D60) — ~~covers\*.jpg, never created~~;
a store app's own artwork is shown from where that app keeps it, never copied here
backups\ledger-before-<v>.db an alpha build's copy of ledger.db before it first opened it, newest three (D73,
2026-10-31; 06_DATA_MODEL §Migrations) — the alpha shares this folder with the beta
(beta.15, D52: FrameLedger.exe --data-dir <folder> reads a COPY of this folder instead — a viewer that starts and
contacts no Agent and changes nothing on the PC, with its own logs\ and crashdumps\ beside the copy; 08_UI §Shell.
The profile's own folder is refused there.)
Key design decisions (ADR)
- ADR-1 (superseded):
Passive ETW only; injection out of scope.Replaced by ADR-7. - ADR-2: WPF over WinUI 3 — Velopack maturity, ecosystem stability, portfolio reuse.
- ADR-3 (revised three times, and this one retires it):
ETW is the Tier-2 fallback, not the primary source.There is no ETW tier. Owner decision 2026-08-28: the ladder is two rungs — hooked, or not measured — and Tier 2 carries duration, sensors and the reason. The abstraction below survives; the second implementation it was justified by never existed and is now not planned.ETW/PresentMon— the tool is no longer named: §S31 retired PresentMon'sFrameTypeas an oracle on 2026-08-20–27 and the owner dropped it on 2026-08-27, so Tier 2 has a tier and no implementation. TheIFrameSourceabstraction that made this cheap to change is retained and vindicated a second time: the mechanism changed underneath it and no consumer moved. - ADR-4: Raw frame series stored as compressed blobs with retention; aggregates kept forever.
- ADR-5 (revised): In-game overlay is now possible (we are already in the process) and is planned as an opt-in feature after the data path is stable — see
15_ROADMAPP5. - ADR-6: UI toolkit = WPF UI (lepoco
Wpf.Ui≥ 4.3.0, MIT) — see16_WPFUI_SYNTAX.md. - ADR-7 (2026-07, core change): Capture moves to in-process graphics-API hooking, C++20 DLL + MinHook, with a Vulkan implicit layer for Vulkan. Rationale: passive detection of DLSS/upscaling/frame-generation/RT state showed large errors against real games; those states are only knowable at the API boundary. Trade-offs accepted: anti-cheat exposure (mitigated by the hard guard in
19_SAFETY, offline titles only), crash risk in the host process (mitigated by SEH guards + fault policy + auto-disable), a second toolchain in the build, and per-API maintenance as vendors change SDKs. Scope limited to titles the user explicitly opts in. - ADR-8: No evasion, ever (
19_SAFETY§What we will never build). This is an architectural constraint, not a preference — it defines what "correct" means for this codebase. - ADR-9: Elevation demoted from required to optional; the Agent runs as a standard user by default.
Chosen, not inherited, since beta.10 (owner decision D34, 2026-09-27): Settings ▸ Capture agent ▸ Run the agent as
administrator (
capture.run_elevated, off by default, a versioned disclosure —agent-admin-dialog/2(/1until 2026-11-11, when Advanced metrics widened what the option adds — D101) — before it turns on). With it on, Windows is asked every time the Agent starts — a UAC prompt owned by the App's window when the App starts it, flashing on the taskbar when the logon task does — and there is no silent path: no "highest privileges" task, no service. The elevated Agent is started for one user (--serve --for-user <SID>) and refuses to run as another account (exit 11: a standard user answered with an administrator's password, and that account's%LOCALAPPDATA%is not this user's ledger); a declined prompt leaves a standard user's Agent that says so (--elevation declined,HelloAck.ElevationOutcome). With it off, an App started as administrator starts the Agent with the desktop shell's token. A game an elevated Agent starts gets the shell's token too (Infrastructure.Startup.UnelevatedProcess) —LaunchGamereaches the Agent over a pipe any process of the user may open, so an elevated launch would be a silent elevation — and nothing enables a privilege (TokenPrivilegesreads them;tools/chokepoint-check.ps1forbids the enablers undersrc/). It buys what it always did: attaching to a game that runs as administrator, and the CPU temperature with PawnIO. It does not open a process an anti-cheat driver protects (D21), and a Vulkan game that runs as administrator stays unmeasured — the Khronos loader ignores the HKCU implicit layers for an elevated process.