Files
frameledger/docs/01_ARCHITECTURE.md
poli0981andClaude Fable 5.2 f780738bc2 feat(advanced): the switch - Settings > Recording > Advanced metrics (telemetry.advanced, off by default); on, a session holds the Agent's one reader and stores its series and facts; Privacy Policy 2.15 and Disclaimer 2.15 (Advanced PR-5, D101/D109) (#391)
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>
2026-11-11 12:11:57 +00:00

18 KiB
Raw Permalink Blame History

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, and CreateStateObject and pipeline creation are unwritten rows of 17_HOOK_ENGINE §Hook inventory. What the Overlay does install: the DXGI present path, wglSwapBuffers, the Streamline and FidelityFX entry points, the two ID3D12GraphicsCommandList4 ray-tracing methods, and the LoadLibraryExW wake.

* AntiCheatGuard is a facade, not an implementation. The guard is native (20_OPEN_QUESTIONS §S13(a)); the box above is the P/Invoke wrapper in Infrastructure that 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). ProcessWatcher is Application.Watch (CaptureOrchestrator over ToolhelpProcessSnapshotSource); Injector is the guard facade reached through HookedCaptureGate; ShmReader is CaptureSession over ShmRingReader; VendorTelemetry is the L1 + L2 + L3 composite; SessionRecorder is Application.Recording. The named pipe on the left is not built (P3, 07_IPC), so today's Agent has no UI client: --serve logs, --console prints. The pipe's read half is built 2026-09-13 (P3 PR-1): --serve listens on \\.\pipe\FrameLedger.v2, answers Hello / GetStatus / Ping, and narrates every session (SessionStarted at the attach, SessionProgress at 1 Hz, the safety and error events, SessionCompleted); --console still prints and hosts no pipe. The command half — the messages a client sends to change a state — is PR-1b is built the same day (PR-1b: SetWatchlist, LaunchGame, SetHookEnabled with 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 /PT evidence, per-process VRAM, PSO stutter attribution, Reflex latency, present flags (corrected 2026-10-04: path tracing, the in-game VRAM, PSO attribution and Reflex latency have no producer — 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 measured frame field reads 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 Shutdown. (Corrected 2026-10-04: closing the UI never stops the Agent. Shutdown is 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 --serve waits for the Alpha notice (D74, 2026-10-31): it reads legal_acceptance after 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-task and 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 --serve and 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-dir beside 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 fault flag in handshake block 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; dropped count published in the ring header the Agent counts drops from its own read index (corrected 2026-10-04: the writer keeps no reader index and publishes no count — 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's FrameType as 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. The IFrameSource abstraction 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_ROADMAP P5.
  • ADR-6: UI toolkit = WPF UI (lepoco Wpf.Ui ≥ 4.3.0, MIT) — see 16_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 (/1 until 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) — LaunchGame reaches 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 (TokenPrivileges reads them; tools/chokepoint-check.ps1 forbids the enablers under src/). 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.