Files
frameledger/docs/01_ARCHITECTURE.md
T
poli0981andClaude Opus 5.5 2ce8251d31 feat: the game's own memory, measured from outside the game in every session - a C++ reader of the GPU Process Memory counters and GetProcessMemoryInfo, median and mean, schema 0018 (D43, beta.12 PR-2) (#254)
- FrameLedger.ProcessStats.dll (C++20, loaded by the Agent, never into a game): the game process's dedicated and shared
  GPU memory from the documented `GPU Process Memory` performance counters (no handle to the game, every instance of the
  pid summed) and its private working set / working set / commit from GetProcessMemoryInfo (EX2, falling back to EX)
  through PROCESS_QUERY_LIMITED_INFORMATION only (a sentinel refuses an EX2 answer whose private working set was not
  filled). Not D3DKMTQueryStatistics ("Reserved for system use").
  ctest fl_process_stats (GPU_INSTANCE on a hardware adapter, NO_GPU_INSTANCE on CI) and fl-probe-processstats.
- Measured first, decision table in spike-notes §16 written before the runs: +512.0 MiB for a 512 MiB buffer,
  private working set equal to Windows' own counter, 0.1 ms per read, nothing leaked over 600 reads; dedicated reads a
  constant 4.5 MiB above DXGI's local usage, so it is never compared with a budget.
- NativeProcessStats (third facade), GameMemoryReader: a pinned session reads through its held handle; an unpinned
  Tier-2 hold opens each process of the executable for the read, refuses a reused pid, sums. CaptureSession tells the
  observer which process (ICaptureObserver.Measuring), the recorder forwards it to the poller (ITelemetryPoller.Follow).
- TelemetrySample.Game; five sensor series; schema 0018 (game_vram_dedicated_*, game_ram_private_*, ..., sensor_stats_json);
  SeriesAggregates gains Median and Min; a wide .partial sensors chunk (type 8) with type 4 still read; SessionProgress
  and SessionHeld carry the game's memory live.
- notice-check accepts a contributor's own copyright line in the same form.
- Tests: the two classes that open a LibreHardwareMonitor Computer run one at a time - GenericCpu.Update threw a
  NullReferenceException in the local gate when they ran in parallel (the Agent's own read is already contained).
- Docs corrected in place: 03_METRICS, 18_GPU_VENDOR_APIS, 17_HOOK_ENGINE, 20_OPEN_QUESTIONS (§M7, §H10, new §M11),
  04_CAPTURE, 19_SAFETY, 06_DATA_MODEL, 07_IPC, 02_SPEC, 01_ARCHITECTURE, 12_BUILD, CLAUDE.md; the accuracy block and
  LIMITATIONS.md.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-03 23:21:45 +07:00

15 KiB
Raw 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)                 │
└───────────────────────────────────────────────────────────────────────────┘

* 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 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 field reads N/A (FR-4.9) 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.

  • Single instance via named mutexes; the ring name is per-PID so multiple games can be captured simultaneously (rare but supported).

    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, 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 → 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

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       pre-injection breadcrumb (19_SAFETY §Crash safety)
tmp\<sessionGuid>.partial    crash-safety flush of raw buffers, every 60 s (04_CAPTURE §Ring draining)
covers\*.jpg

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/1 — 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.