* feat(input): the arithmetic of controller statistics - classes, batteries, makers, one pad seen twice (D155-D163) Nothing reads a device yet. Domain.Input says whether an XInput state or a DualSense report is a pad in use and what its battery is, adds a battery's readings up, counts switches and decides when two entries are one pad; Application.Input holds one session's slices and turns them into a reading a second; InputSessionBuilder turns a session's readings into its totals, its controllers as JSON and its timeline. TelemetrySample can carry a reading. Every byte and reading under test was written by hand: no report from a real controller has passed through this code. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * feat(input): a session can store what it was played with - schema 0024, the .partial file's chunk 11, both tiers (D160) Nine columns on sessions (the time in front and its four classes, the switches of method, the sources that answered, the controllers as JSON) and three on games (what a store lists of controller support), ADD COLUMN only. The .partial file gains chunk 11, so a session recovered after the Agent died keeps its readings. SessionFinalizer.Build stores them before the tier branch: hooked, unhooked and recovered sessions alike. The input series are sensor_blobs rows named input.*, which the sensors' read now leaves out and FindInputSensorsAsync returns. Nothing produces a reading yet. A ledger this build has opened cannot be opened by 0.1.0-beta.49 or earlier. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * feat(input): the input reader, which the Agent does not start yet - raw input for controllers, XInput, the time of the last input (D155, D158, D159) Application.Input.InputReader takes a slice about ten times a second from Infrastructure.Input.Win32InputBackend, on the thread of InputDeviceHub, which exists only while a session has a view of it. It opens no device, sends nothing to one and registers for no keyboard or mouse. tools/input-readonly-check.ps1 holds its Windows calls to a list. With no controller at hand, what the reader does with one connected is not established. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * fix(input): an arm of XInputPad.Battery's switch said what the default says (Qodana, on #464 after it merged) Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * test(input): no using that makes the file's own qualified names redundant (InspectCode) Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * test(input): what InspectCode reported in the reader's tests - redundant casts, a hub disposed twice, a suppression not needed Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * wip(input): the Agent records what a session was played with - the switch, the terms, the legal texts Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * style(input): import order in the Agent's composition; no redundant qualifier in a test (InspectCode) Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * wip(input): what a store lists of controller support, the input libraries, the game page's three rows * wip(input): the game page's details tests expect the three controller rows; the library names test without ToLowerInvariant Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * docs(guide): the settings page listed Controllers and input twice Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * feat(input): a session's summary says what it was played with - the shares, the controllers and their batteries, two charts, marks on the frame-time chart; Trend, Compare and the CSV export (D155-D163) Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * release: 0.1.0-beta.50 - what a session was played with: controllers and input, read from outside the game; owner-only item 48 (D155-D163; with D152, D154) Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * test(app): the bar's gap is named by the class that has it; one sentence for the frames session's own sensors Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * test(app): the fixture's constant is named as the format check wants Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * test(input): the last-input time is asked not to go back, not to match .NET's tick - the two differ by the time the PC slept; the finding in 21_INPUT_DEVICES and HANDOFF's traps Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * refactor(app): the notes of a session's input need its controllers' record, not its row Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * docs(handoff): auto-merge does not wait for Qodana - the trap, and what was fixed here Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
44 KiB
CLAUDE.md — AI build instructions for FrameLedger
You are implementing FrameLedger, a Windows tool that measures game performance by hooking graphics APIs inside the game process, records sessions (frame times, upscaler/FG/RT ground truth, hardware telemetry), and visualizes them over time.
Read this file first, then the reading order at the bottom. docs/19_SAFETY_AND_ANTICHEAT.md is not optional — it constrains everything the hook does.
Architecture in one paragraph
A C++ DLL (FrameLedger.Overlay.dll) is injected into games the user explicitly enabled. It hooks the presentation path (DXGI for D3D11/D3D12, plus OpenGL) and the upscaler/RT APIs, writes fixed-size frame records into a lock-free shared-memory ring, and never blocks. A C# Agent drains that ring at ~10 Hz, enriches with GPU telemetry from vendor APIs, and writes sessions to SQLite. A WPF UI reads SQLite. Vulkan uses an implicit layer instead of hooking. If injection is refused or fails there is no measurement: the session records duration, hardware telemetry and the reason, and every measured field reads N/A (Tier 2, owner decision 2026-08-28) — and, since owner decision D161 (2026-11-14), what the Agent reads from outside the game: the game process's memory (beta.12, D43) and which controllers, or the keyboard and mouse, the session was played with (docs/21_INPUT_DEVICES.md). Nothing measured inside the game is among them.
Non-negotiable rules
-
Injection is opt-in, per game, never automatic. The user must add the game and enable hooking for it. There is no "hook everything" mode, no global auto-inject.
-
The anti-cheat guard is a hard gate, not a warning. Before injecting, scan the target for known anti-cheat/anti-tamper modules (
19_SAFETY). If any is found → refuse, log, tell the user why. There is no override switch, no "I understand, continue anyway" button. Do not add one.Amended 2026-09-22 (owner decision): the override of 2026-09-21 is withdrawn, and the sentence above is the rule again. For one day (releases
0.1.0-beta.3andbeta.4) a per-game override existed. The owner withdrew it: no entry point, no message, no column (schema 0008 drops 0007's five), no string. Do not add one in any form.A finding turns the game's hooking off (
19_SAFETY§What a finding does to the game). An anti-cheat named in the game itself — its process, its title lists, its folder — is written to the row exactly as the pre-scan always wrote it (hook_enabled = 0,hook_blocked_reason,hook_prescan_state = 'blocked'), and since 2026-09-22 also when the guard finds it at a session's start or at the 30 s re-scan (AntiCheatVerdict.IsFindingAboutTheGame). A machine-wide driver or service refuses that session only. The notice, the game's page, the session's notes and the Agent's log all say it happened. Nothing clears the block, as before. Amended 2026-09-26 (owner decision D33): one narrow, evidence-bound exception. Asked with the 2026-09-22 withdrawal and this rule quoted back, the owner chose a per-game exception for anti-cheat that is user-mode throughout — a Settings option off by default, then the user ticks each eligible game through a versioned disclosure (bans are possible and can arrive days later). Eligible only when every finding about the game isBlockedModule/AntiCheatFile/AntiCheatDirectoryof ONE family whose floor-and-file footprint has no driver, service or.sys(fl::guard::FamilyIsUserModeOnly— the GUARD decides, from a family NAME the caller passes), no.sysis anywhere in the install tree (within check 4's reach: three levels under the install root and, since 2026-10-13, under the executable's own folder), no title list names the game, and the ledger holds ≥ 2 successful Tier-1 sessions of it. Drivers, services, title lists, the.sysrule, the fuzzy tier, scan failures,TargetUnreadable, 32-bit, the kill switch and Vulkan are never excepted. The guard runs every check and keeps scanning past the tolerated family (kAllowedUserModeException, reason 28); the Overlay learns the family fromLocal\FrameLedger.Tolerate.<pid>before its loader detour exists. A new finding, a crash / safety unhook / floor stop under it, or an executable change ends it; the block is never cleared. No other form of override is to be added (19_SAFETY§The user-mode exception). Amended 2026-10-03 (owner decision D38): the evidence moved from before the grant to its trial. "≥ 2 successful Tier-1 sessions" above could never be met by a game blocked at add time — since beta.8 that is every blocked game — nor after a ledger reset. Asked with that, the owner chose: a grant needs no session; the first two hooked sessions under it are a trial, and any end during the trial (a crash, a safety unhook, a floor stop, a new finding, or a stored hooked session with no frames or an abnormal exit) ends the exception for good (games.ac_exception_trial_failed_at, schema 0017, never cleared). Every other condition above is unchanged, and so is the last sentence. -
Never implement evasion. No manual mapping, no PE header erasure, no thread hiding, no signature obfuscation, no unlinking from the PEB module list. Injection uses documented
LoadLibraryW. The DLL keeps its real name, real exports, and version info. A performance tool must be visible to anti-cheat, not hidden from it. Any PR that makes FrameLedger harder to detect is rejected on principle. -
Never read or write game memory outside our own hooks. We read arguments passed to APIs we hooked and COM/handle objects we legitimately own. No pattern scanning for game internals, no reading player/entity state, no writing to game memory. Ever.
Amended 2026-11-13 (owner decision D132): a driver's read-only getter, with the device of the swap chain we hook. Asked with this rule quoted, the owner ruled that calling NVIDIA's two latency getters (
NvAPI_D3D_GetLatency,NvAPI_D3D_GetSleepStatus) with the device behind a swap chain the Overlay hooks is inside this rule: it reads the driver's report, not game memory, and writes nothing.Nothing shipped does it yetShipped since 0.1.0-beta.47 (owner decisions D136, D138–D141), after the spike onhook-harness, a stub and the installed driver (spike-notes§31): only while a session records Advanced metrics (no switch of its own), about once a second on the presenting thread, through annvapi64.dllthe game had loaded — one in the game's own folder is refused, and a fault or a call of 2 ms or more ends it until the game exits (17_HOOK_ENGINE§Calls the Overlay makes into a driver). It is the only call of its kind; another needs a ruling of the same kind. Getters only, never a setter, a marker or a sleep, and never a call that loadsnvapi64.dllinto a game. -
The hook must never crash the game. Every hook body: SEH-guarded, allocation-free, lock-free, no logging, no exceptions crossing the boundary. On repeated faults, self-disable (
17_HOOK_ENGINE§Fault policy). -
FPS display rule (product requirement): wherever FPS is shown and Frame Generation is active, show Native FPS, Displayed FPS, and the FG factor together (
62 → 118 FPS (×1.9 FG)). Never a single inflated number. Seedocs/03_METRICS.md.Amended 2026-09-03 (owner decision). When frame generation is not measured —
FL_MEASURED_FGclear,which is every title on today's writerwhich is every title with no Streamline or FidelityFX hook live (corrected 2026-10-04: the writer sets it since #103, 2026-09-03) — the one number that may stand alone is Presented FPS (presents / D), with a mandatory qualifier from the runtime census (FlWriterState.runtimeCensus): "no frame-generation runtime was loaded, so this cannot include in-process generated frames" or "a frame-generation runtime is loaded and nothing was observed — this MAY include generated frames". The word "Native" never appears alone. The census never producesnone: a statically linked FSR has no module to see, and a census-nonethere would be exactly the inflated number this rule forbids.Amended 2026-09-05. A counted
none(presents = application frames) is withheld — Presented FPS with a third qualifier, "this number counts application frames; the Displayed rate is unknown" — on the one shape measured to produce a falsenone: Streamline ≥ 2.8.0 withsl.dlss_g.dllloaded (Dying Light: The Beast, five captures, DLSS FG ×4 per the owner).docs/03_METRICS.md§Frame Generation carries the key and why it is the Streamline plugin rather thannvngx_dlssg.dll;20_OPEN_QUESTIONS§H5 carries the session that keeps or withdraws it.Amended 2026-09-06 (Leg 0 landed): narrowed, not withdrawn.
sl.dlss_g.dllis a startup-time load on that title (frame generation off, census unchanged, twice), and the same morning's ×4 capture measured the discriminator the gate lacked: the 2.8.0 pacer's generated presents are DXGI presents on the hooked chain (§H5 row P1-DXGI), counted throughdxgiUnseenintoNative 70.52 → Displayed 282.08 (×4 FG). So a countednonebeside a READIDXGISwapChain::GetLastPresentCountwith zero unseen isnone, printed with DXGI's agreement; it is withheld only when the counter was not read.Amended 2026-09-17 (owner decision): the steady state. A session whose frame-generation state changed (menus, loading, a settings change) has no session-wide factor — averaging ×1 menus with ×4 gameplay is the inflated-or-deflated single number this rule forbids — but it is no longer left with none: Native → Displayed (×N FG) is shown for the state the session spent most of its generating time in, always with the share of the session it covers (
62 → 118 FPS (×1.9 FG · 75%)), never as a session average (docs/03_METRICS.md§The steady state).Amended 2026-10-19 (owner decision D62): the mix. Beside the steady state, the session summary lists every frame-generation state the session held — each with its own Native → Displayed, its factor and its share of the presenting time (
×4.0 frame generation · 35.33% · 70 → 282 FPS) — then the time with no frame generation and the time no state claims. Every row is one state's own numbers; nothing is averaged across states, and a state's factor never appears without its rates (docs/03_METRICS.md§The mix). -
RT / PT / RR are tri-state (
Yes/No/N/A) with manual override. They are now measured, not guessed — but where measurement is genuinely impossible, the honest answer is stillN/A. Never fabricateYes.Amended 2026-08-20 with the PR that wrote the hooks, per the owner ruling of 2026-08-14. This rule named "inline RayQuery without DXIL scan" as one of the impossible cases, and that conflated two questions. Whether rays are being traced is measurable —
BuildRaytracingAccelerationStructureis called by RayQuery titles and byDispatchRaystitles alike, which is why both hooks exist and why theNobranch requires the AS-build hook to have been installed. What needs a DXIL scan is classifying the technique as RayQuery, and that staysN/A. So the impossible cases are: naming the technique, and path-tracing classification, which has no API-level signature at all (03_METRICS§RT/PT/RR — a confidence score that may only ever suggest). -
No telemetry, no analytics, no silent network calls. Permitted: GitHub release check, detection-rules fetch, opt-in store metadata. Nothing else.
-
No obfuscation of our own binaries. GPLv3 project; ship self-contained + ReadyToRun, publish checksums.
Pinned stack
| Concern | Choice |
|---|---|
| Managed runtime | .NET 11 (STS, pinned via global.json: the 11.0 SDK band) and C# 15 since 0.1.0-beta.37 (owner decisions D94 and D96, 2026-11-11; .NET 10 and C# 14 until beta.36), TFM net11.0-windows10.0.22621.0 with SupportedOSPlatformVersion=10.0.19045.0 (NFR-8 as D95 amended it: Windows 11 is the supported platform; Windows 10 22H2 is not blocked, and is neither tested nor supported), x64 only — docs/12_BUILD.md §The main line's .NET. No preview feature (runtime-async, the updated memory-safety rules). No C# 15 construct is used yet — collection expression arguments, closed, union, labeled jumps: a construct is used only where the build, CodeQL and Qodana all read it, and Qodana's engine reads none of the four (docs/13_CI_CD.md §C# 15 and the analyses). .NET 11's API is used freely. The alpha branch (D73–D76, 2026-10-31) builds a released beta's source to try a newer .NET; it rests since 0.1.0-alpha.4 (D98) and then differs from main in RELEASE_LINE alone — docs/12_BUILD.md §The alpha line |
| Native | C++20, MSVC v143+, /MT static CRT, /GS, /guard:cf, no RTTI, no C++ exceptions in hook paths |
| Hooking | MinHook (BSD-2-Clause) for inline hooks; direct vtable-entry swap for COM interfaces |
| Vulkan | Implicit Vulkan layer (VK_LAYER_FRAMELEDGER_overlay), not hooking — 17_HOOK_ENGINE §Vulkan |
| UI | WPF + WPF UI (WPF-UI pinned = 4.3.0) + CommunityToolkit.Mvvm — docs/16_WPFUI_SYNTAX.md |
| App composition | .NET Generic Host + DI in FrameLedger.App |
| Charts | ScottPlot 5 |
| Markdown in the App | Markdig (BSD-2-Clause, pinned FlowDocument, HTML off, no image fetched — the Legal Gate, the user guide, Help ▸ Limitations, Help ▸ Accessibility (beta.35, D88), the update notes, About (beta.12; row added 2026-10-04) |
| GPU telemetry | The game process's own memory since beta.12 (D43): FrameLedger.ProcessStats.dll (C++, loaded by the Agent, never into a game) reads its dedicated/shared GPU memory from the GPU Process Memory counters and its working sets from GetProcessMemoryInfo — 18_GPU_VENDOR_APIS §The game process's memory. Layered: DXGI + PDH counters (all vendors) → LibreHardwareMonitorLib (MPL-2.0, all vendors) → NVAPI (MIT, headers + amd64/nvapi64.lib vendored 2026-08-05 at src/native/third_party/nvapi/, consumed via the fl_nvapi target; NVIDIA extras + Reflex). No AMD/Intel vendor SDK — docs/18_GPU_VENDOR_APIS.md. LhmTelemetrySource (L2) exists since 2026-09-03 (20_OPEN_QUESTIONS §M5 row R1, eight GPU fields unelevated); L1 (BaselineTelemetrySource: DXGI identity + the PDH adapter-memory counter, the first CsWin32 consumer), CompositeTelemetrySource and the 1 Hz TelemetryPoller since 2026-09-09; L3 (NvapiTelemetrySource over the native FrameLedger.NvapiBridge.dll — the only shipped binary linking nvapi64.lib, loaded by the Agent into its own process and never into a game) since 2026-09-10 (PR-E2) — ctest fl_nvapi_probe was the only NVAPI consumer until then, and it exists so the vendoring is verified rather than asserted. This row said no source existed for six days after one did, recorded 2026-09-09 rather than repaired quietly. This row previously claimed the vendoring in the present tense while third_party/ held only vulkan-headers; legal/ had already caught the identical claim about itself and gained a bidirectional gate, which is what made the real vendoring a red-then-green |
| CPU/board sensors | LibreHardwareMonitorLib ≥ 0.9.6 (PawnIO) — optional, elevated only |
| Tier-2 fallback | There is none, and Tier 2 is not a measurement. Owner decision 2026-08-28: the ladder is two rungs — hooked, or duration + sensors + the reason. docs/20_OPEN_QUESTIONS.md §G |
| Storage | SQLite via Microsoft.Data.Sqlite + Dapper (no EF) |
| Shared memory IPC | CreateFileMapping + lock-free SPSC ring — docs/07_IPC.md |
| Logging | Serilog (managed); ring-buffer + deferred flush (native) |
| Packaging | Velopack, GitHub Releases, unsigned + SHA256SUMS |
| Win32 interop (C#) | CsWin32 source generator |
| i18n | .resx: en (default), vi, ja |
| Tray | H.NotifyIcon.Wpf |
Solution layout
FrameLedger.slnx # XML solution format (SDK default since .NET 10)
NOTICE # copyright + the GPLv3 section 7 additional terms (beta.12, D45)
CONTRIBUTING.md FORKING.md CODE_OF_CONDUCT.md # for people who build, contribute or redistribute
LIMITATIONS.md ACCESSIBILITY.md # what the software cannot do; the accessibility statement (D36, D88)
global.json # pins the SDK band — see 12_BUILD
RELEASE_LINE # `main`, or `alpha` on the alpha branch (D73, 2026-10-31) — 12_BUILD §The alpha line
build.ps1 # the quality gate; CI runs this identical script
SonarQube.Analysis.xml # SonarCloud's settings for ci.yml's sonarcloud job (D68, 2026-10-25; it replaced
.config/dotnet-tools.json # .sonarcloud.properties) and the scanner it runs — 13_CI_CD §SonarCloud
qodana-native.yaml # the same for the native job: the C++ of src/native, through the Visual Studio solution
# CMake writes for it (preset x64-vs-analysis), a report of its own (D99)
qodana.yaml # Qodana's settings for the managed job of .github/workflows/qodana.yml (D93; Qodana for
# .NET on the Ultimate licence since 2026-11-11, D99): the linter, the solution, a gate
# of zero problems, and what is switched off that .editorconfig has no key for —
# ReSharper's inspections are .editorconfig's resharper_* keys (D100) — 13_CI_CD §Qodana
src/
native/
FrameLedger.Overlay/ # C++20 DLL injected into the game (hooks + ring writer + optional overlay)
FrameLedger.Injector/ # C++20 static lib: launch/attach injection, AC guard probe; also builds
# FrameLedger.Guard.dll, the guard's C ABI the Agent loads (line added 2026-10-14)
FrameLedger.VkLayer/ # C++20 Vulkan implicit layer DLL + manifest JSON
FrameLedger.Shm/ # header-only: ring buffer + record layout, shared by native & C# (mirrored)
FrameLedger.NvapiBridge/ # C++ DLL loaded by the Agent (never a game): NVAPI telemetry, NGX state (P2 PR-E2)
FrameLedger.ProcessStats/ # C++ DLL loaded by the Agent (never a game): the game process's memory (beta.12, D43)
tests/ tools/ third_party/ # ctest suites; probes, hook-harness, vendor stubs; vendored headers
# (these three lines added 2026-10-04 — the list stopped at Shm)
FrameLedger.Domain/ # entities, metric calculators — zero dependencies
# (Metrics/ WRITTEN 2026-09-09, P2 PR-A: frame times,
# percentiles, lows, stutter, the FG window and its
# refusals, extent, segments, RT/HDR tri-states,
# aggregates — over Domain's own FrameSample, under the
# 95% per-class floor. The CaptureHost's consumer now
# calls it; the FG ladder's prose is still there, PR-D's)
FrameLedger.Application/ # use cases, ports — incl. Capture/ since 2026-09-09 (P2 PR-C):
# CaptureSession (the loop: gate -> inject -> attach -> drain
# under the 30 s re-scan), ICaptureSink and the ports the Agent
# composes it from, SessionEndReason, the census/NGX/marker facts;
# and Recording/ since 2026-09-10 (PR-D): SessionRecorder,
# SessionAggregator + FgLadder, SessionFinalizer, the .partial
# writer and PartialRecovery, ExitStatusMapper, the crash policy;
# and Advanced/ since 2026-11-11 (D101): AdvancedMetricCatalog, the one
# list "Advanced metrics" reads - what is read, and what is not with the
# reason (18_GPU_VENDOR_APIS §Advanced metrics) - and the value model
# (AdvancedValue / AdvancedFact / AdvancedReading / AdvancedSnapshot) and
# the port IAdvancedHardware. Infrastructure implements it: AdvancedHardwareHub
# (one reader for the Agent, on its own thread, only while held - D107) over
# NvapiAdvancedReader (the bridge's ABI 3) and LhmAdvancedReader (LhmGroups:
# the card; as administrator with PawnIO the processor, memory and board -
# never storage, D103). The Agent composes it since the switch, `telemetry.advanced`
# (PR-5, 2026-11-11: off by default; on, a session holds the hub), and
# Ipc/AdvancedMachineResponder answers GetAdvancedMachine from the hub's last
# snapshot - each request is the page's hold on it (PR-6, D107). Recording/
# AdvancedSessionBuilder stores what a session's samples carried (schema 0023:
# machine_profiles + session_advanced, adv.* series with NaN for a gap, D102).
# Train B (0.1.0-beta.40, D111): Capture/InGameAdvancedSampler turns the shared
# memory's region 5 - what a hooked game told DLSS and FSR, read by the Overlay
# only while the session asks (ICaptureObserver.WantsInGameAdvanced) - into session
# facts and two adv.* series; reach `Game` in the catalog; no schema change.
# Since 0.1.0-beta.43 also what the game tells Streamline each frame and how it
# configures FSR frame generation, from two calls hooked only once Advanced has been
# asked for; AdvancedInGameCall says of each: read, never called, or not hooked.
# Since 0.1.0-beta.44 also what Streamline answers when the game asks about a
# feature (its version, what it requires), from two more calls hooked the same
# way; ~~a game asks while it starts, so "never called" is the usual answer there~~
# (the games run since ask again later, and are read).
# Since 0.1.0-beta.45 also whether Streamline says a feature is supported and
# loaded, the game switching it, its resources allocated and freed and Streamline
# shut down, from six more calls hooked the same way (D130); slInit is not hooked
# and its entry says why (AdvancedReach.BeforeAttach, D129).
# Since 0.1.0-beta.47 (train C, D136-D141) also what NVIDIA's driver reports about
# a frame's stages - NOT an argument of a hooked call: the Overlay calls two
# read-only getters of the driver itself (reach GameDriver); seven adv.* series
# and one table, and AdvancedDriverRead says what became of the read.
# Since 0.1.0-beta.48 (D142-D144) also two figures the driver works out itself, of
# the same report - no further call: an entry of their own, nvapi.reflex.gpu_times,
# two adv.* series; and the table lists every frame-generation multiplier seen.
# Since 0.1.0-beta.49 (D148-D151) the Overlay also counts each frame of that report
# by its GPU span and the driver's active time - for its native log ONLY
# (LATENCY_FRAMES, a batch per state of the sleep status; nothing published or
# stored); its watchdog's periodic tick is on a grid (fl_watchdog_tick.h), and
# Recording/PendingInGameReadings keeps the reading that waits for a sample.
# Controllers and input (0.1.0-beta.50, owner decisions D155-D163, docs/21_INPUT_DEVICES):
# Input/ - InputReader (a slice ten times a second over the port IInputBackend),
# InputTickAccumulator (one session's slices into a reading a tick), InputTerms (the
# reading waits for Privacy Policy 2.22, D156), the ports IInputDevices /
# IInputActivitySource; Recording/InputSessionBuilder (totals, the controllers as JSON,
# the input.* series; schema 0024). Domain/Input holds the arithmetic and the two
# parsers (an XInput state, a DualSense report). Infrastructure/Input is the Windows
# side: Win32InputBackend (raw input for joysticks and gamepads, three XInput getters,
# GetLastInputInfo - it opens no device and sends nothing to one) and InputDeviceHub
# (one thread for the Agent, only while a session has a view). Read from OUTSIDE the
# game, both tiers; `capture.input_devices`, on by default.
# The App shows it since the same release: Services/InputPresentation (a session's
# "Played with", from the stored row), Controls/ShareBar with InputShareBar and FgMixBar,
# Charts/InputSeries with two charts and the controller marks on FrametimeChart,
# Services/ControllerEvidence (a game's page: three pieces of evidence, no verdict, D163).
FrameLedger.Infrastructure/ # SQLite, shm reader, vendor APIs, injector interop, parsers,
# and Capture/ (PR-C): ShmRingAttacher/ShmCaptureSink over the
# reader, HeldProcessLivenessSource, TargetResolver (path only,
# never a pid), ProcessLauncher, the module snapshot, the marker scan
FrameLedger.Shared/ # IPC contracts (System.Text.Json source-gen) + the struct mirror (ShmLayout.cs;
# it said "ShmRecord", a type that never existed, until 2026-10-04)
FrameLedger.Agent/ # capture orchestrator: watcher, injector control, shm drain, recorder
# BUILT 2026-09-10 (P2 PR-F): a Generic Host. `--serve` = watcher
# (Application.Watch: ProcessWatcher, ProcessTree, DescendantElection,
# CaptureOrchestrator over ISessionRecorder) -> recorder -> the gate;
# `--console` = the operator's verbs incl. `consent grant` (decision D4,
# ConsentProvenance.AgentConsoleOperator — the DEVELOPER path since P3 PR-4
# built FR-2.1's dialog, ConsentProvenance.ConsentDialog) and `killswitch` (FR-2.4,
# the gate's FOURTH input, decision D7). --data-dir under --console only.
FrameLedger.App/ # WPF UI — the SHELL since 2026-09-13 (P3 PR-2): Generic Host,
# FluentWindow + TitleBar/Menu/NavigationView, theme + language
# persisted in `settings`, the Agent pill over the pipe (starts
# `FrameLedger.Agent.exe --serve` beside itself when absent),
# ~~five pages of which four are empty states~~ — every 08_UI screen
# is built as of 2026-09-14 (PR-5 Games/Dashboard, PR-6 summary +
# charts, PR-7 trend/compare, PR-8a Settings/safety notices/Logs/
# --diag, PR-8b tray + the Agent's maintenance flags, PR-9 first run
# + Legal Gate FR-11); Strings.resx en/vi/ja. The Advanced page
# (2026-11-11, D101/D105: Pages/AdvancedPage, there and on Ctrl+6 only
# while `telemetry.advanced` is on - 08_UI §Advanced). `--data-dir <copy>`
# (beta.15, D52) = a VIEWER: no Agent started or contacted,
# nothing on the PC changed, the profile's own folder refused
FrameLedger.CaptureHost/ # UNSHIPPED, and since P2 PR-C (2026-09-09) a THIN SHELL: verbs,
# the operator disclosure, the report consumer, and the composition
# of Application.Capture.CaptureSession over Infrastructure's
# adapters — the loop itself no longer lives here. Its consent
# store is SQLite (PR-B) over its OWN ledger.db beside the binary,
# never the Agent's (D5). 12_BUILD publishes App and Agent ONLY,
# and neither references this — tools/package-closure-check.ps1
# keeps that true. §S27 was closed on that basis and is RESTATED
# there: the consent adapter AND the loop now ship, so packaging
# is not what holds rule 1.
tests/
FrameLedger.Domain.Tests/ FrameLedger.Application.Tests/ FrameLedger.Infrastructure.Tests/
FrameLedger.Agent.Tests/ FrameLedger.App.Tests/
FrameLedger.CaptureHost.Tests/ # incl. the Category=Integration end-to-end case
Shared/ fixtures/ # test helpers; the detection corpus and other fixtures
~~native/FrameLedger.Overlay.Tests/~~ # never existed (corrected 2026-10-04): the native tests are
# src/native/tests/ (ctest, mostly Catch2 — ring, guard, layout,
# vklayer, unhook, rules budget, NVAPI bridge, process stats)
tools/ # accuracy-check, changelog-check, chokepoint-check, coverage-gate,
# gen-ac-floor, hookinventory-check, license-check, license-gather
# (+ license-overrides/), notice-check, package-closure-check,
# release-notes, rules-validate, test-artifacts-check, vendor-exports,
# versioninfo-check, vklayer-blastradius, fps-impact-runbook,
# wiki-build (beta.17: builds and checks the wiki; the wiki-check gate),
# buildid-check (beta.18: the release's build id in the shipped natives),
# docs-split-check (beta.24, D66: CHANGELOG/HANDOFF and their parts agree),
# agent-cost (D110, 2026-11-11: a developer tool, not a gate - what the shipped
# Agent costs per second of session, Advanced metrics off and on),
# nvapi-readonly-check (D108, 2026-11-11: every NVAPI call of the bridge is on
# nvapi-allowed-calls.txt, and none there writes or identifies; since beta.47 also
# the Overlay - no NvAPI call by name, and the only interface ids it may name are
# the two on overlay-nvapi-allowed.txt),
# overlay-fields-check (D116, 2026-11-12: every member of a vendor's struct the
# Overlay reads for Advanced metrics is in fl_adv_fields.h and on
# overlay-allowed-fields.txt; a camera's position, axes and matrices nowhere),
# input-readonly-check (D155-D163, 2026-11-14: every Windows function the input reader
# calls is declared in Infrastructure/Input/Win32Input.cs and on input-allowed-calls.txt;
# none sends to a device, injects input or reads a key; raw input is registered for
# joysticks and gamepads only; no native source names an input function)
# (six names added 2026-10-04)
# (PowerShell). This line used to name three, one of which
# — resx-audit — ~~does not exist~~ exists since 2026-09-13 with
# resx-gen (the committed Strings.Designer.cs generator).
# native tooling lives under src/native/tools:
# fl-layout-dump -> struct offsets for the C# mirror test
# hook-harness -> dummy D3D11 + D3D12 + Vulkan + OpenGL app
# (--vulkan since #140, --opengl since #141)
# fl-probe-* -> guard, hook profile, interposer, NVAPI, process
# stats, signer, Vulkan layer; fl-baseline-probe;
# and fl-probe-reflex (2026-11-13, D132: the spike of Reflex route D,
# spike-notes §31 - unshipped, with a stand-in nvapi64.dll among the stubs;
# built from the Overlay's own fl_reflex.h since beta.47);
# vendor-stubs/ -> fixture DLLs with the vendors' export names
rules/detection-rules.json # engine/platform/capability + anticheat blocklist
guide/ # the user guide (beta.12, D44): ~~eight~~ short English pages for players, embedded in the
# App (Help > User guide); README.md is its contents. docs/ is for developers.
# (twelve since beta.17, D54: the screens, every setting, troubleshooting, a glossary;
# and the guide is the wiki's End-user part)
# (since 0.1.0-beta.50 also 13-controllers.md, Controllers and input)
wiki/ # the wiki's own pages (beta.17, D53): Home, _Sidebar, the developer pages. wiki.yml
# publishes them with guide/, LIMITATIONS.md and ACCESSIBILITY.md to the Wiki tab at a release;
# tools/wiki-build.ps1 assembles and checks them (build.ps1 wiki-check)
docs/ legal/ legal/licenses/
Dependency direction: App/Agent → Application → Domain; Application → Shared since 2026-09-09 (P2 PR-A, decision D1 — Application.Metrics.FrameSampleMapper is where FlFrameRecord becomes Domain's FrameSample, and Application.Capture.CaptureSession, hosted there since PR-C the same day, is written over the record; DrainResult moved to Shared with it); Infrastructure implements Application ports; Domain references nothing. The native layer is reachable only through Infrastructure — no P/Invoke anywhere else. Two Three facades since 2026-09-10 2026-10-03: NativeAntiCheatGuard (required — absent throws), NativeNvapiBridge (optional — absent is a missing telemetry layer that reports itself) and, since beta.12 (D43), NativeProcessStats (optional — the game process's own memory, read from outside the game; absent reads N/A), all by absolute path beside the assembly through its one DllImport resolver, Infrastructure.Native.BesideThisAssembly; the runtime allows one resolver per assembly, which is why the third facade claims a name there rather than setting its own.
Coding conventions
C# — Nullable enable, TreatWarningsAsErrors, AnalysisLevel latest-all, file-scoped namespaces, Roslynator + Meziantou + VS Threading analyzers, dotnet format clean. Qodana reads the C# and the XAML in an advisory workflow of its own, with a gate of zero problems (since 2026-11-10, D93; Qodana for .NET on the Ultimate licence since 2026-11-11, D99 — 13_CI_CD §Qodana): fix what it reports, or switch the inspection off with the reason on the line above, in the place the engine that raised it reads (D100) — one of ReSharper's (C#, XAML, .resx, the C++) in .editorconfig; what has no key there (the hints as a severity, the Markdown and XML inspections, the files JetBrains' security rules were read in) in qodana.yaml — never anywhere else, never without a reason. A new file that starts a process fails ProcessStartSitesTests, and Qodana's security rule reports it: read what it starts and where the path and the arguments come from, then list it in the test, in qodana.yaml and in 13_CI_CD §Qodana. Async suffixed Async, ConfigureAwait(false) off the UI. All user-visible strings from .resx. Timestamps UTC (unix-ms in SQLite); QPC ticks only inside the capture pipeline.
C++ — clang-format (LLVM base, 4-space, 120 col) enforced in CI. No STL containers that allocate in hook paths. No std::mutex in hook paths. -D_HAS_EXCEPTIONS=0 in the Overlay target. Every hook entry point wrapped per the FL_HOOK_GUARD macro (17_HOOK_ENGINE). Static analysis: CodeQL (/analyze + clang-tidy (bugprone-*, cert-*, concurrency-*)codeql.yml, a required check); /analyze and clang-tidy are not configured (corrected 2026-10-04). SonarCloud analyses the C++ too, from CMake's compilation database, in ci.yml's advisory sonarcloud job (since 2026-10-25, D68 — 13_CI_CD §SonarCloud). Qodana reads it as well, in a report of its own (since 2026-11-11, D99: ReSharper's C++ inspections and the clang-tidy checks they run, advisory, a gate of zero — 13_CI_CD §Qodana): fix what it reports, or switch the inspection off in .editorconfig with the reason above it; in code loaded into a game only a defect is fixed, in a pull request of its own with the overhead measured (D100).
Licence header — every first-party source file (.cs .cpp .h .inl .ps1 .xaml) opens with two comment lines, SPDX-License-Identifier: GPL-3.0-only and Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE (beta.12, owner decision D45). GPLv3 §7 requires additional terms to be named in the source files, and NOTICE holds them — (b) preserve the notices, (c) mark modified versions, (e) no trademark rights in the name. tools/notice-check.ps1 is a build.ps1 gate; -Fix writes a missing header. src/native/third_party/ is excluded.
Struct mirroring — FlFrameRecord, FlShmHandshake, FlWriterState and FlControlBlockFlShmHandshake, FlWriterState, FlControlBlock, FlDisplayState (layout 4, beta.10), FlAdvancedState (layout 5, 2026-11-11, Advanced metrics train B), FlFrameRecord and FlTolerance (D33, beta.9) each exist twice (corrected 2026-10-04): src/native/FrameLedger.Shm/include/fl_shm.h / fl_tolerance.h (normative) and src/FrameLedger.Shared/ShmLayout.cs as [StructLayout(LayoutKind.Sequential)]. ShmLayoutMirrorTests asserts size and every field offset on both sides against JSON emitted by tools/fl-layout-dumpsrc/native/tools/fl-layout-dump, never a transcribed table, and walks the field list in both directions so a field added on either side alone fails.
It also asserts blittability (RuntimeHelpers.IsReferenceOrContainsReferences), because offsets cannot see it: measured 2026-08-05, swapping the fixed byte BuildId[32] for this repo's own [MarshalAs(ByValTStr)] string idiom keeps Marshal.SizeOf at 64 and every offset correct while Unsafe.SizeOf collapses to 40 — a mirror that passes the obvious checks and cannot be read out of a memory-mapped view.
build.ps1's struct-mirror gate reads the run's .trx and fails when that test class did not execute, so deleting the test is red too — it used to Test-Path a source file and report on a test it never looked for.
The version handshake is wired end to end as of 2026-08-05: FlGuardBuildId gives the Agent a build id of its own and ShmHandshakeValidator performs the refuse-to-attach comparison 07_IPC specifies (§S23-1). Its default is NotEvaluated, not Ok — a result nobody produced has validated nothing, the same rule AntiCheatVerdict follows.
Dev mode — FL_MOCK=1 is specified but not implemented — grep -rn FL_MOCK src tests tools build.ps1 returns nothing (recorded 2026-08-04). When it exists it runs the whole app with a synthetic frame source and no injection at all, and it is how the UI is meant to be developed; until then, do not plan work on the assumption that it is there. tools/hook-harnesssrc/native/tools/hook-harness (path corrected 2026-10-04) is a dummy D3D11 + D3D12 + Vulkan + OpenGL app used to exercise hooks without a real game — --vulkan since #140 and --opengl since #141 (2026-09-06); this sentence said both were unwritten until 2026-09-09 (docs/12_BUILD.md §Targets is the accurate list).
Definition of done (per PR)
- Builds warning-free (C# and C++); tests green;
dotnet format+clang-formatclean. - Hook-path changes state measured overhead in the PR body (
14_TESTING§Hook overhead). - Any new hook is listed in
17_HOOK_ENGINE§Hook inventory and justified against rule 4. - New user-visible strings exist in
en,vi,ja. - A change to what the App shows keeps
ACCESSIBILITY.md§For contributors (names, theme colours, nothing by colour alone, keyboard reach) and updates that page when it moves what works or what does not (D88). - Any deviation from a doc updates that doc in the same PR.
Reading order
docs/HANDOFF.md— what to do next and in what order. It carries sequencing, decisions that live in no other file, and the traps that cost a cycle each. It deliberately carries no status: it points at the four files that do. Start there if you are picking up work; start at 1 if you are learning the system. (Since beta.24, D66, the history of every train, the passed owner-only items and the traps live indocs/handoff/; HANDOFF.md's §How this file is split and §Decisions index resolve every old citation. CHANGELOG.md likewise keeps[Unreleased]and links each release's file underdocs/changelog/.)docs/19_SAFETY_AND_ANTICHEAT.md— the guard, the refusal list, what we will not builddocs/01_ARCHITECTURE.md— processes, injection flow, lifecycledocs/02_SPEC.md— FR/NFR ids used everywheredocs/03_METRICS.md— metric math, source of truthdocs/17_HOOK_ENGINE.md— the C++ hook layerdocs/04_CAPTURE.md— capture orchestration (Agent side)docs/05_DETECTION.md— runtime API interception → engine/upscaler/FG/RT factsdocs/18_GPU_VENDOR_APIS.md— layered GPU telemetry (DXGI/PDH · LHM · NVAPI) + vendor-SDK licence rulesdocs/06_DATA_MODEL.md·docs/07_IPC.md·docs/08_UI.md·docs/16_WPFUI_SYNTAX.md- Remaining (
09–15). LIMITATIONS.md(repository root; shown in the App under Help ▸ Limitations) — what the WHOLE software cannot do, in the user's words, each item linked to its details. When a change moves a limit, the page changes in the same PR (D36, 2026-09-27).ACCESSIBILITY.md(repository root; Help ▸ Accessibility) — the accessibility statement: WCAG 2.2 AA through WCAG2ICT as a goal, never a claim; what works with the keyboard, a screen reader and contrast themes, what does not, how a barrier is reported (D88, 2026-11-09);docs/08_UI.md§Accessibility holds its checks.docs/LIST_GAME_TESTED.md— the real games FrameLedger has been run with and what each session measured, from a copy of the owner's ledger and the repository's own evidence (D35).
Before writing native or capture code, read docs/20_OPEN_QUESTIONS.md (its open entries; since beta.24 the
resolved ones are in docs/open-questions/, a table at the end of each series lists them). It
lists the defects and gaps that survived the doc audit — things the other
documents cannot answer because they need an empirical result or a decision. The
S-series items are safety items and block the first real injection. If you are
about to implement something in the hook layer, check whether it is already
listed there as unresolved rather than implementing the version the doc describes.