Files
poli0981andClaude Fable 5.2 e3dab94834 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) (#467)
* 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>

---------

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-14 16:20:55 +00:00

61 KiB
Raw Permalink Blame History

12 — Build & development environment

Mixed toolchain: .NET 11 for managed projects (since 0.1.0-beta.37, owner decision D94, 2026-11-11; .NET 10 until 0.1.0-beta.36 — §The main line's .NET), MSVC for the native layer.

Prerequisites

  • Windows 11 (dev), .NET 11 SDK (11.0.100 or a later 11.0 feature band), Visual Studio 2026 with: .NET desktop development, Desktop development with C++ (MSVC v143+, Windows 11 SDK ≥ 10.0.22621), C++ ATL not required.
  • Vulkan SDK (for the layer + validation layers during development, and to run tools/vklayer-blastradius.ps1) (corrected 2026-10-04: the layer builds against the vendored third_party/vulkan-headers; CI installs no SDK).
  • CMake ≥ 3.28 (native projects use CMake; consumed by the solution via a build target — see below).
  • Optional: PawnIO for CPU-temperature testing; an NVIDIA GPU for the NVAPI/Reflex paths (dev machine: RTX 5080). AMD/Intel telemetry paths need no SDK — if you have such hardware, testing L1/L2 coverage there is valuable.
  • No admin needed for normal development. FL_MOCK=1 is specified but not implemented — grep -rn FL_MOCK src tests tools build.ps1 returns nothing (CLAUDE.md §Dev mode records the same, and this line contradicted it in the present tense until 2026-08-05). When it exists it runs the whole app with a synthetic source and zero injection. Until then the no-injection development path is hook-harness, which needs no admin either.

Native build

src/native/ is CMake-based (CMakePresets.json, presets x64-debug, x64-release):

cmake --preset x64-release
cmake --build --preset x64-release

A third preset, x64-vs-analysis (2026-11-11), builds nothing that ships: it has CMake write a Visual Studio solution (build/native/x64-vs-analysis/FrameLedgerNative.slnx, generator "Visual Studio 18 2026", tests and tools on) for Qodana's native report, which reads C++ through a solution (13_CI_CD §Qodana). It needs Visual Studio 18; the gate and the release never use it.

Targets:

  • FrameLedger.Overlay → FrameLedger.Overlay.dll
  • FrameLedger.VkLayer → FrameLedger.VkLayer.dll + VkLayer_FRAMELEDGER_overlay.json
  • FrameLedger.Injector → static lib only. There is no FrameLedger.Injector.exe and none ships (20_OPEN_QUESTIONS §S9, decided 2026-08-02). A standalone LoadLibraryW injector that users can run is a path into a game process that the guard does not stand in front of — a bypass, and a bad look for a project whose position is "we refuse where we are not welcome". The Agent links the static lib; the guard owns the chokepoint inside it (§S13(b)), so there is no callable entry point that skips the gate. Manual testing uses hook-harness, never a real game (§Debugging).
  • FrameLedger.NvapiBridge → FrameLedger.NvapiBridge.dll (2026-09-10, P2 PR-E2): the C ABI the Agent reaches NVAPI through (18_GPU_VENDOR_APIS §L3) and the only shipped binary that links nvapi64.lib. Read-only by construction, loaded by the Agent into its own process by absolute path through /FrameLedger.NvapiBridge.targets, and never into a game — its name carries none of the words the guard's §S18 heuristic scans for. fl_native_flags only, not the hostile-environment set. versioninfo-check.ps1 requires its version block like the other three shipped natives (five in all since beta.12 — corrected 2026-10-04). ctest fl_nvapi_bridge (src/native/tests/nvapi_bridge_test.cpp) exercises every export and requires BRANCH: AVAILABLE or BRANCH: DEGRADED in the output, so a bridge gutted to return 0 is red on a runner without the driver too.
  • FrameLedger.Guard → FrameLedger.Guard.dll (the guard's C ABI over the Injector library, src/native/FrameLedger.Injector/CMakeLists.txt; loaded by the Agent) and FrameLedger.ProcessStats → FrameLedger.ProcessStats.dll (beta.12, D43: the game process's memory, read by the Agent from outside the game; probe fl-probe-processstats) (both bullets added 2026-10-04; they were missing)
  • FrameLedger.Overlay.Tests the ctest executables in src/native/tests/ (fl_ring_test, fl_guard_test, fl_vklayer_test, … — corrected 2026-10-04: no target of that name has existed) → Catch2 unit tests (ring buffer, record layout, fault filter, seqlock) and the guard's fail-closed matrix (14_TESTING §Safety-guard tests) — the guard is native, so its tests are too
  • hook-harness → the dummy D3D11 + D3D12 app, WARP + composition swapchain so it runs headless on CI (17_HOOK_ENGINE §Test harness). D3D12 is device → command queue → swapchain, which is the acquisition asymmetry a D3D11-only fixture cannot exercise. Vulkan and OpenGL modes to follow as those hooks land. --vulkan --hold-presenting N since 2026-09-06 (P1 item 3): a real swapchain on a hidden window through the real loader, reached by LoadLibraryW("vulkan-1.dll") so only the vendored headers are needed and CI (no loader) still builds it; exit 77 = cannot run here, which the ctest reads as SKIP. --opengl --hold-presenting N since the same day (P1 item 4): a real context on a hidden window, SwapBuffers'd through gdi32 as a title does, on Microsoft's generic renderer — so it runs on CI.
  • fl-probe-hookprofile → build-profile probes for /guard:cf and -D_HAS_EXCEPTIONS=0 (20_OPEN_QUESTIONS §H1/§H3)
  • fl-probe-guard → measures the Windows APIs the guard is built on, unelevated (spike-notes.md §1). Not the guard, and takes no injection rights.
  • fl-probe-reflex → the instrument of spike-notes §31 (2026-11-13, owner decision D132) — since the owner said go (D136) it is built from the Overlay's own header, FrameLedger.Overlay/include/fl_reflex.h, so its ctest runs the shipped call sequence with Control Flow Guard enforced; its --real also prints which image the two getter addresses lie in (nvapi64_impl.dll, not the nvapi64.dll that is asked). What it was written as: the call sequence Reflex route D would put into the Overlay — find nvapi64.dll only if the process already holds it, resolve the driver's two getters by interface id, call them — in an unshipped probe built with the Overlay's flags. --stub runs it against fl_stub_nvapi64 → nvapi64.dll (a stand-in with knobs for a missing getter, an empty report, an error and a call that does not return; its outputs in a directory of their own, so that its nvapi64.lib is never beside the vendored one's name) and is ctest fl_reflex_probe_stub; --real runs it against the installed driver on an NVIDIA adapter, with the probe setting the latency markers a game would, in its own process — a measurement, never a test. It takes the vendored NVAPI headers' include directory and does not link nvapi64.lib. Nothing shipped includes its header.
  • fl_stub_sl_interposer → sl.interposer.dll, and fl_stub_sl_common → sl.common.dll (src/native/tools/vendor-stubs/). Fixtures, never shipped, built under FL_BUILD_TOOLS; nothing 12_BUILD publishes references them. They export the measured vendor names from docs/vendor-exports.json so the Overlay's symbol resolution is observable, and the second is a decoy exporting the same name from a different module — without it, "we resolve module-scoped" is a property no test can falsify. Their output filenames are the vendor's and their version blocks are ours: fl_add_version_resource takes the real filename so a file called sl.interposer.dll in our build tree still says plainly that it is FrameLedger's, which 19_SAFETY requires of everything we build.
  • fl_stub_ffx_dx12 → amd_fidelityfx_dx12.dll, fl_stub_ffx_upscaler → amd_fidelityfx_upscaler_dx12.dll, fl_stub_ffx_fg → amd_fidelityfx_framegeneration_dx12.dll — the three AMD leaves — and fl_stub_ffx_loader → amd_fidelityfx_loader_dx12.dll, a forwarding stand-in bound to the two 2.x leaves through their FrameLedger-named direct entry — the way the real loader was measured to bypass the leaves' exports — so --hold-presenting-ffx can push every dispatch through a loader that is hooked along with the leaves and prove the count reads 1× (2026-09-04). Same rules as the Streamline stubs: fixtures, never shipped, vendor filenames with our version blocks. fl_stub_ffx_fsr3_host → ffx_fsr3_x64.dll (2026-09-05): the FSR 3.0 host facade, exporting the four names SpeaksFsr3Host probes for through the vendored fsr3-v3.0.4 header's own FFX_API; --ffx-topology fsr3host|fsr3host+mono drives it, and hookinventory-check Pass C reads it as the export parser's second positive control.
  • fl_fidelityfx_headers → an INTERFACE target over the five vendored FidelityFX ffx-api headers (src/native/third_party/fidelityfx/, tag v2.3.0, MIT by exception). Three include directories because upstream's headers include each other by relative path; include directories only and nothing to link — no .lib is vendored — and hookinventory-check Pass C reads the Overlay's export table because ffx_api.h declares its entry points __declspec(dllexport) unconditionally.
  • fl_streamline_headers → an INTERFACE target over the vendored MIT Streamline headers (src/native/third_party/streamline/). Include directories only, never linked: SL_API entry points are extern "C" imports, and linking one would make sl.interposer.dll a load-time dependency of FrameLedger.Overlay.dll, which would stop the Overlay loading in every game that ships no Streamline — in the loader, before any of our code runs, with no message anywhere.

Compiler/linker flags (enforced in CMake, not per-target ad hoc): /std:c++20 /MT /O2 /GS /guard:cf /Qspectre /GR- /W4 /WX, -D_HAS_EXCEPTIONS=0 for the Overlay target. Link /DYNAMICBASE /NXCOMPAT /HIGHENTROPYVA.

MinHook is fetched by CMake FetchContent and built from source, pinned to the commit behind tag v1.3.4 (c3fcafdc) rather than to the tag name — a tag can be moved, a commit cannot. FetchContent over a submodule so a fresh clone needs no extra step and CI has nothing to remember. Upstream warnings are not subjected to our /W4 /WX: warnings in third-party code are upstream's to fix, and failing our build on them would only tempt someone to patch the fetched copy, which drags it out of "consumed unmodified". The BSD-2-Clause notice ships in legal/licenses/, and tools/license-check.ps1 fails the build if it goes missing while the FetchContent declaration is still present.

NVAPI SDK (MIT) is vendored at src/native/third_party/nvapi/ — headers, amd64/nvapi64.lib, License.txt, consumed through fl_nvapi, proven by ctest fl_nvapi_probe, and linked by a shipped binary since 2026-09-10 (FrameLedger.NvapiBridge, above). legal/licenses/nvapi-MIT.txt carries the notice and license-check.ps1 binds the two bidirectionally.

This paragraph said "is not vendored yet" until 2026-08-09, in the present tense, and added that src/native/third_party/ "contains CMakeLists.txt and vulkan-headers only". Both were false from #55 (2026-08-05) onward. The sentence was itself a correction — of an earlier claim that NVAPI was vendored when it was not — so this file has now been wrong in both directions about the same fact, which is worth more than the fix: CLAUDE.md's pinned stack and 18_GPU_VENDOR_APIS §L3 were updated when the vendoring landed and this one was not. legal/ is gated bidirectionally and caught its own version; docs/ is not gated, and this is what that costs. Link it normally; do not resolve NVAPI by ordinal (that was a workaround for a licensing constraint that no longer exists, and it breaks across driver versions). Still guard NvAPI_Initialize failure as a normal path — plenty of users have no NVIDIA GPU.

No AMD or Intel GPU telemetry SDK is vendored. Those vendors' sensors are covered by LibreHardwareMonitor and the DXGI/PDH baseline (18_GPU_VENDOR_APIS). A build that pulls in Intel IGCL or AMD ADLX material is a licensing regression, not a feature — CI greps for it. The AMD FidelityFX ffx-api headers (MIT by exception, tag v2.3.0) ARE vendored since 2026-09-04, for the Overlay's upscaler hook and for types only — fl_fidelityfx_headers above, 18_GPU_VENDOR_APIS §AMD for the licence reading, and license-check.ps1 §2d for the per-file gate. Intel's XeSS SDK failed the checklist and nothing of it is here.

VERSIONINFO is mandatory on FrameLedger.Overlay.dll and FrameLedger.VkLayer.dll every shipped native — the five tools/versioninfo-check.ps1 lists (corrected 2026-10-04): real CompanyName, ProductName=FrameLedger, FileDescription, version. Identifiability is a requirement (19_SAFETY), and a CI check fails the build if the resource block is missing. Since beta.14 (D50) the managed binaries are held to the same — §Version, Identity.

Managed build & native integration

  • global.json pins the SDK band (11.0.x since beta.37 — 10.0.x before — rollForward: latestFeature, allowPrerelease: false). Without it dotnet build picks the newest installed SDK — on a machine with a preview of the next .NET installed that silently changes analyzer behaviour under TreatWarningsAsErrors, and makes local and CI disagree for reasons nobody can see in a diff. (The alpha branch carries the same file while its line rests, and pins the SDK it is trying when it does not — §The alpha line.)

  • Directory.Build.props:

    • TargetFramework = net11.0-windows10.0.22621.0 (net10.0-… until beta.36) and SupportedOSPlatformVersion = 10.0.19045.0. These are two different knobs and must not be conflated: the TFM platform version selects which Windows API projections are available to compile against, while the supported version is the floor CA1416 enforces. NFR-8 names Windows 10 22H2 = build 19045 as the oldest Windows the code is held to (since D95, 2026-11-11: not blocked there, and neither tested nor supported — Microsoft supports .NET 11 on Windows 11); letting the supported version default to the TFM's would silently accept installs below that floor. Two constraints pin the target to 22621 rather than something closer to the floor: the SDK rejects SupportedOSPlatformVersion above TargetPlatformVersion (NETSDK1135), and 19045 is not a targeting-pack version in any case — the packs are cut at 19041, 20348, 22000, 22621, 26100. The Windows 11 SDK ≥ 10.0.22621 is already a prerequisite above, so this costs nothing. A bare net11.0-windows is wrong for a different reason: it resolves to net11.0-windows7.0, and CA1416 would then error on Mica, MiniDumpWriteDump and QueryVideoMemoryInfo — every Windows-10-era API this app is built on.

    • Platforms/PlatformTarget = x64. "x64 only" is asserted in CLAUDE.md and NFR-8 but was previously enforced nowhere except an ad-hoc -r win-x64 on the publish command.

      RuntimeIdentifier is NOT set here, and this bullet claimed it was until 2026-08-06. The props file's own comment explains why: forcing a RID onto class libraries pulls RID-specific assets into their restore for no benefit, so each executable sets it — FrameLedger.App, FrameLedger.Agent and now FrameLedger.CaptureHost, plus its test project, which needs the same RID to reference a RID'd exe. A new project copying this document rather than the props file would have inherited nothing.

    • Nullable enable, ImplicitUsings enable, TreatWarningsAsErrors=true, AnalysisLevel=latest-all, deterministic, ContinuousIntegrationBuild on CI.

  • Directory.Packages.props: central package management, all versions pinned (including WPF-UI = 4.3.0 exactly — 16_WPFUI_SYNTAX §Version hygiene).

  • Native output reaches the managed side through .targets files imported by FrameLedger.Agent, not through FrameLedger.Infrastructure: /FrameLedger.Guard.targets (the guard DLL), /FrameLedger.Overlay.targets (the payload, §S22), /FrameLedger.Rules.targets (the blocklist seed) and, since 2026-09-10, /FrameLedger.NvapiBridge.targets (the L3 bridge; it warns rather than fails when the DLL is absent, because a missing telemetry layer reports itself where a missing guard would be a safety hole), and since beta.12 /FrameLedger.ProcessStats.targets (the game-memory reader, D43; it also warns rather than fails — an absent reader reads N/A; added 2026-10-04). Ordering comes from build.ps1, which runs the native build first — not from the solution: FrameLedger.slnx contains no native project.

    This bullet was wrong in four ways and is corrected 2026-08-04. It named a copy of FrameLedger.Injector.exe, which §S9 closed and which line 25 above says does not exist, 24 lines earlier in the same document. It attributed the copying to a build target in FrameLedger.Infrastructure.csproj, which contains no <Target> at all. It said the copies happen there, when the guard DLL was deliberately moved out to a .targets file so it would stop flowing to every referencing project (§S18 blocker 3). And it credited the solution with an ordering the solution cannot express.

  • Struct mirror check — ✅ built 2026-08-05. ShmLayoutMirrorTests runs tools/fl-layout-dump, reads its JSON, and asserts size plus every field offset against the C# [StructLayout] mirrors in FrameLedger.Shared — in both directions, so a field on either side alone fails. It also asserts blittability, which offsets cannot see. The struct-mirror gate reads the run's .trx and fails when that test class did not execute, so deleting the test is red as well as breaking it. Struct drift between the two layers is the most dangerous silent bug in this architecture; the build now genuinely catches it.

    Until 2026-08-05 this bullet ended "the build catches it" in the present tense, while src/FrameLedger.Shared/ held a .csproj and no .cs files — and this document contradicted itself, because line 138 below said correctly all along that the gate did not exist. 20_OPEN_QUESTIONS §R10 has the history.

Debugging

Launch profiles:

  • "UI + Mock" — FL_MOCK=1, no Agent, no injection. Default for UI work.
  • "UI + Agent" — both managed processes, real capture against hook-harness.
  • "Harness + Overlay" — starts hook-harness under the debugger with the Overlay injected at launch; attach a second native debugger to step hook code.

(Corrected 2026-10-04: none of these is committed, and "UI + Mock" needs FL_MOCK, which §Prerequisites says is not implemented. What exists: FrameLedger.exe starts FrameLedger.Agent.exe --serve beside itself. To capture against the harness, run hook-harness.exe --real --hold-presenting N, then the Agent's --console --data-dir <scratch> verbs consent grant --exe and capture --exe, as AgentEndToEndTests does — never against your own data folder.)

To look at real data with a build of your own (beta.15, D52): FrameLedger.exe --data-dir <copy>. Make the copy with SQLite's online backup, which is consistent while the Agent writes — in Python, sqlite3.connect("file:C:/Users/<you>/AppData/Local/FrameLedger/ledger.db?mode=ro", uri=True).backup(sqlite3.connect(r"<copy>\ledger.db")) — or copy the whole folder with every FrameLedger process stopped (closing the App does not stop the Agent). A copy of the database alone has no covers\: the games whose image the user chose show the store's artwork instead (beta.23), and choosing one in the viewer writes into the copy's own covers\. The App opens the copy, migrating it if your build is newer, which is exactly why it must be a copy, and writes its log and crash dumps beside it. It is a viewer: no Agent is started or contacted and nothing on the PC is changed (08_UI §Shell). It refuses the profile's own folder however it is spelled, and a folder that does not exist.

Toolchain gotchas, both hit on a real machine and both handled by build.ps1:

  • msys2 / MinGW on PATH breaks the native build. vcvars64 prepends to whatever PATH it inherits, and MSVC ships link.exe — there is no ld.exe to shadow MinGW's. CMake then picks MinGW's linker and the build dies with cannot find /nologo: No such file or directory, a failure a long way from its cause. build.ps1 strips only the MinGW entries before importing the MSVC environment, so dotnet, git and cmake survive.
  • vcvars64 exports Platform=x64, which is meaningful for .vcxproj builds. We have none, and MSBuild reads it as a solution platform, so dotnet build FrameLedger.slnx then fails with MSB4126 solution configuration "Release|x64" is invalid. build.ps1 clears it after import; project-level x64 comes from Directory.Build.props.
  • ninja and clang-format both ship inside the VS C++ workload but are on neither the default PATH nor the vcvars one. build.ps1 locates both, so the C++ workload alone is enough to run every gate.

Native debugging notes: use hook-harness, never a real game, for step-through debugging — a breakpoint inside a present hook of a real game freezes it in ways anti-cheat and drivers both dislike. Enable the Vulkan validation layers when touching FrameLedger.VkLayer. Application Verifier + PageHeap on the harness catches ring-buffer bugs early.

Agent flags: --serve (since beta.10 with at most one of --for-user <SID> — the account an Agent started as administrator must be, else it exits 11 — or --elevation declined|other-account|failed — its starter asked Windows and got this; both from the admin mode, 01_ARCHITECTURE ADR-9), --console, --write-crash-dump <file> (2026-09-17: the crash-dump helper a crashing App or Agent starts; it dumps its parent and takes no pid — 10_LOGGING §Crash handling), --diag (the App's — FrameLedger.exe --diag, 10_LOGGING; the Agent answers exit 2 for it), --install-task, --uninstall-task, --register-vklayer, --unregister-vklayer (all four real since 2026-09-14, P3 PR-8b: the task is \FrameLedger\FrameLedger.Agent through the Task Scheduler COM API — schtasks /Create /SC ONLOGON is "Access is denied" unelevated on the dev box, measured — this user's logon trigger, interactive token, lowest run level; the layer registration is 17_HOOK_ENGINE §Vulkan's HKCU value).

Built 2026-09-10 (P2 PR-F): --serve and --console; the other five answer "not implemented in P2" with exit 2 rather than being silently accepted (--diag is the App's anyway, 10_LOGGING). The console surface, pinned by AgentCommandLineSurfaceTests: consent list | grant --exe | revoke --exe, capture --exe [--seconds n], launch --exe [--args "…"] [--seconds n], recover, sessions [--last n], db path, games add --exe, killswitch on | off | status, and --data-dir <dir> — under --console only (HANDOFF §P2 decision D6): --serve never takes one, so the product's %LOCALAPPDATA%\FrameLedger is not selectable and an integration test cannot point the product at a profile. AgentEndToEndTests runs the shipped FrameLedger.Agent.exe against hook-harness with a scratch --data-dir and reads the one sessions row back — the milestone's technical half, in the merge gate.

The print verbs open the ledger read-only (2026-09-16). sessions, consent list and killswitch status migrate nothing and refuse — exit 7, the reason on stderr — a ledger at a schema older or newer than the build; db path opens no file at all. Until then every verb went through the migrating open, and sessions run against the owner's ledger applied two scripts to it (06_DATA_MODEL §Migrations). AgentReadOnlyVerbsTests pins the set.

One capturing process per data folder (2026-09-17). --serve, capture, launch and recover claim the data folder (AgentInstanceLock) before logging, rules or the ledger, and exit 10 — one line on stderr, nothing written — when another process holds it; the other verbs run beside a serving Agent, as the App's --install-task does. OneAgentPerDataFolderTests runs the shipped binary against a claimed scratch folder (01_ARCHITECTURE §Lifecycle).

Bundled assets

  • assets/native/PresentMon.exe (pinned, SHA-256 verified at build) for the Tier-2 fallback — DROPPED 2026-08-27, and there are no bundled native assets at all. §S31 measured PresentMon classifying every frame of a ×4 capture as an application frame (row P2); the owner then dropped it outright. It is not bundled, not fetched, not used, and tools/frametype-oracle.ps1 — the parser that consumed its output — is deleted with it. assets/ does not exist and now has no reason to. And since 2026-08-28 Tier 2 is not a measurement at all: the ladder is two rungs, EtwFrameSource is deleted from the design, and whether a shipped build ever regains a no-injection measurement is 20_OPEN_QUESTIONS §G.

    The struck text is kept because the reason it was written is still live. What it said next, and what remains true:

    planned, not present. assets/ does not exist, nothing fetches or verifies the binary, and EtwFrameSource is unwritten. 20_OPEN_QUESTIONS §M2 (does the pinned console binary still exist, run unelevated, and emit the 2.x column set?) is unanswered, so this is not merely unpinned — there is nothing to pin yet.

  • Vulkan layer manifest, written with the installed layer path at install time (Velopack hook) — but not registered there. The install hook writes nothing (P4 PR-5): the manifest is written by the registrar the first time the ledger asks for the layer (VkLayerRegistrar.Register, P4 PR-2), so an install that never enables a Vulkan game has no manifest either. Registration is a separate, later act.

The Vulkan layer is not registered at install time

20_OPEN_QUESTIONS §S10. An implicit layer is machine-wide by nature: once registered, the loader maps it into every Vulkan process on the system, including ones the user never added to FrameLedger. Registering it as a side effect of installation would put our DLL into unrelated Vulkan applications before the user has enabled a single game — and before any consent dialog has been shown, which contradicts FR-2.1 and 19_SAFETY §User-facing consent.

The correct rule is the one 17_HOOK_ENGINE §Vulkan already states, and it is now the only rule: registered only while at least one Vulkan game has hooking enabled, unregistered when the last such game is disabled, and unregistered on uninstall. Under HKCU — never HKLM, never requiring admin.

This governs all three places that touched registration: the install hook above, the --register-vklayer Agent flag (§Agent flags — a manual repair tool, not the normal path), and the Settings button (08_UI §Settings — it reflects and repairs state, it does not grant machine-wide reach on its own).

Enforced 2026-09-14 (P4 PR-2). "A Vulkan game" is a static fact of the executable — it imports or LoadLibrarys vulkan-1.dll — read by the Agent's detection sweep into capability_flags as vulkan (17_HOOK_ENGINE §Vulkan built note). Application.Vulkan.VkLayerReconciler registers when the first hook-enabled game carries it and unregisters when the last one is disabled, after every consent change and after every sweep; the flag and the button run the same rule. The uninstall hook is still the updater's (P4, Velopack).

The main line's .NET (owner decisions D94 and D95, 2026-11-11)

The main line — the betas and the first release — builds on .NET 11 since 0.1.0-beta.37: SDK 11.0.100 (the band global.json pins), runtime and Windows Desktop 11.0.0, C# 15 by LangVersion latest, and the three packages that are serviced with the runtime (Microsoft.Extensions.Hosting, System.Diagnostics.EventLog, Microsoft.Data.Sqlite) at 11.0.0. .NET 11 shipped on 2026-11-10; the owner moved the line the next day.

  • What decided it, and what did not. 20_OPEN_QUESTIONS §G held a decision table written on 2026-10-31, before any evidence: move only after (a) two alphas on the released runtime had passed the gate and an owner's run of a hooked title, (b) the owner's word on Windows 10, and (c) something .NET 11 brings being wanted. The owner set (a) aside — no alpha had run on the released runtime; three had run on Release Candidate 3 (alpha.1 to alpha.3, the gate green each time) — decided (b) as D95, below, and for (c) asked for C# 15 in the same release (D96). What stands in for (a) is this release's own gate on 11.0.100 (spike-notes §28) and owner-only item 34.
  • Windows 10 (D95). Microsoft supports .NET 11 on Windows 11, and on Windows 10 only in its LTSC and IoT editions. FrameLedger does not block Windows 10 22H2: SupportedOSPlatformVersion stays 10.0.19045.0, so CA1416 still holds the code to it, and nothing checks the Windows version at start. It is untested there — it always was (ACCESSIBILITY.md, 08_UI §Accessibility) — and now unsupported too; NFR-8, LIMITATIONS.md, the README and the guide say so.
  • The processor. .NET 11 needs x86-64-v2 — SSE4.2 and POPCNT among its instruction sets — and does not start without it ("The current CPU is missing one or more of the baseline instruction sets"). Its ReadyToRun code targets x86-64-v3 (AVX2 among others); Microsoft says a processor that lacks those may pay for it at start-up, where that code is compiled again. Every processor Windows 11 accepts has x86-64-v2.
  • What .NET 11 changes in the software, measured or read: IHost.RunAsync rethrows the exception of a BackgroundService that failed, so the Agent's --serve leaves through its crash report where on .NET 10 it exited 0 (10_LOGGING §Crash handling; HostBackgroundFailureTests holds it); Microsoft.Data.Sqlite 11 declares SQLitePCLRaw 3.0.5, whose engine is SourceGear's SQLite package; nine Microsoft.Extensions.* libraries are part of the runtime and no longer packages beside it (legal/licenses/nuget/: 78 packages became 69).
  • C# 15 (D96) is the language the main line compiles, and none of its constructs is used yet: the analyses do not read them (13_CI_CD §C# 15 and the analyses, spike-notes §29). What beta.37 takes from .NET 11 is API.
  • Going back is installing 0.1.0-beta.36 over a later build: the ledger's schema did not move with the runtime.

The alpha line (owner decisions D73–D76, 2026-10-31; resting since D98, 2026-11-11)

The owner, 2026-10-31: an alpha build, "a place where new .NET versions are tried", with code updated where needed and a warning that it is an experiment used at one's own risk. The alpha line is the source of a released beta built to try a newer .NET — at times a prerelease one — from the long-lived alpha branch, published as vX.Y.Z-alpha.N GitHub pre-releases on Velopack's alpha channel (13_CI_CD §The alpha line, 11_UPDATER §Channels). It tried .NET 11: Release Candidate 3 in alpha.1 to alpha.3 (2026-10-31 to 2026-11-06), the release itself in alpha.4.

  • The line rests since 0.1.0-alpha.4 (D98, 2026-11-11). The main line moved to .NET 11 the day after it shipped (§The main line's .NET), so alpha.4 is 0.1.0-beta.37's source on the same .NET 11.0.0 — published so that a copy of alpha.3 leaves the release candidate by an update, since an alpha never updates to a beta. After it no alpha is cut until a newer .NET has a preview to try (.NET 12's, expected in 2027). While the line rests, the alpha branch differs from main in RELEASE_LINE alone (git diff main alpha --name-only prints that one name), and a resting alpha gets no update: its anti-cheat list, which reaches a user only inside a release (13_CI_CD §rules-publish.yml), stays the one it shipped with. Its notes, the guide and the Alpha notice tell its user to install the beta — and the build itself does: Directory.Build.props stamps its FlAlphaLineRests property (true on main since beta.37) into every assembly, Shared.AlphaLine.Rests reads it, and an alpha cut while it is true shows a banner that says the line is paused and to install the beta, in place of the experimental-build one (App/Services/AlphaTexts; D97: the words "a prerelease .NET" appear only where the runtime's own description is a prerelease's).
  • The switch — what alpha differs from main in while it tries a newer .NET, and nothing else: RELEASE_LINE (alpha); global.json (that SDK, with allowPrerelease: true when it is a prerelease); the TFM in Directory.Build.props (SupportedOSPlatformVersion stays 10.0.19045.0); the three Microsoft packages in Directory.Packages.props that are serviced with the runtime (Microsoft.Extensions.Hosting, System.Diagnostics.EventLog, Microsoft.Data.Sqlite); legal/licenses/nuget/ regenerated for that package set and the Transitive row of legal/THIRD_PARTY_NOTICES.md; FlAlphaLineRests set to false in Directory.Build.props; and a fix only the newer .NET can take, if one is ever forced. As it stood for .NET 11 RC3: SDK 11.0.100-rc.3.26522.148, net11.0-windows10.0.22621.0, the three packages at 11.0.0-rc.3.26522.148 (spike-notes §24). No newer language syntax and no preview feature on alpha (D76): the source is main's, and main compiles with its own SDK.
  • Everything else lives on main, dormant on the main line. RELEASE_LINE is read like VERSION and stamped into every assembly as the FrameLedger.ReleaseLine metadata (Directory.Build.props refuses any value but main and alpha); Shared.BuildLine reads it back for the App and the Agent, which compose with it rather than reading it where they act, so a test hands either line to the code it tests. On the alpha line they act on it (D74): the Alpha notice in the Legal Gate with its own tick box, the Agent's wait for it, the ALPHA badge and banner, the locked update channel (08_UI), and the ledger's copy before an alpha first opens it (D73, 06_DATA_MODEL §Migrations). What the alpha's SDK asks of the source and main's can also take lands on main.
  • The native layer does not change. MSVC builds it from the same source; only its build id differs (the alpha's tag). The hook, the guard and the Vulkan layer in an alpha are the beta's.
  • Sync, and the cadence while it tries a .NET. After each beta release a pull request merges main into alpha with a merge commit (the repository allows them; the linear rule is main's) and the next alpha is cut from it — one alpha per beta, never several in a row, because Velopack reads only the newest ten releases (11_UPDATER §Channels). A conflict in a switch file is resolved for the switch; legal/licenses/nuget/ by regenerating it on alpha (tools/license-gather.ps1). An alpha older than the ledger's schema refuses to open it (LedgerSchemaException), so a beta that adds a migration is followed by an alpha soon. The sync that ended the .NET 11 trial (alpha.4) went the other way round: every switch file conflicted and main's version was taken for each, leaving RELEASE_LINE.
  • Building it locally: check out alpha with the SDK its global.json names installed and run ./build.ps1 check as on main.
  • Starting the next trial (a preview of the next .NET): the switch above on alpha, the whole gate in a throwaway worktree first (spike-notes §24 is the pattern, with its decision table written before the run), and the Alpha notice's sentence naming the .NET.
  • Whether the main line follows a trial is the owner's each time: 20_OPEN_QUESTIONS §G, The main line's .NET, holds the table and what happened to it for .NET 11.

Version

One source: the VERSION file at the repository root (MAJOR.MINOR.PATCH, nothing else — P4 PR-5, 2026-09-14). Before it, the managed assemblies carried the SDK's default 1.0.0 while CMake said 0.1.0, two products claiming to be one.

  • Directory.Build.props reads it into <Version> (assembly, file and informational versions; SourceLink's +sha suffix is off so About, Hello and the bug bundle print the version a user can find on the releases page). The read is conditional on $(Version) being empty, so release.yml passes -p:Version=0.1.0-beta.1 for a pre-release and the assemblies carry the tag's full version.
  • src/native/CMakeLists.txt reads the same file into project(VERSION …), which the .rc template turns into every VERSIONINFO block. CMake's project() accepts numbers only, so the native FileVersion is the numeric core even for a pre-release.
  • tools/versioninfo-check.ps1 compares every built binary's FileVersion against the file (x.y.z.0), so a read that silently produced 0.0.0 on either side is red in the gate.
  • release.yml refuses a tag whose numeric core is not the file's. Bumping the version is one edit to VERSION, in the same commit as the changelog section, before the tag.

Identity (beta.14, D50). Every binary names the product, says what it is and carries one copyright line. Until beta.14 only the native blocks did: the managed ones carried the SDK's defaults — the Agent's company and product read FrameLedger.Agent, each library's its own assembly name — and no copyright, and those blocks are what Explorer's Properties ▸ Details and Task Manager show (Task Manager lists the Agent by its file description).

Field Native (src/native/CMakeLists.txt) Managed (Directory.Build.props, the two entry points' csproj)
CompanyName, ProductName FL_COMPANY_NAME, FL_PRODUCT_NAME = FrameLedger Company, Product = FrameLedger
LegalCopyright FL_COPYRIGHT Copyright — the same line, word for word
FileDescription each target's fl_add_version_resource description AssemblyTitle: FrameLedger (App), FrameLedger Agent (Agent); a library keeps its assembly name
Comments the identification sentence Description — the same sentence for a library, a line of its own for each entry point
FileVersion / ProductVersion the numeric core, x.y.z.0 x.y.z.0 / the full version (-p:Version, a pre-release's tag included)
OriginalFilename the file's own name the assembly's (FrameLedger.dll) — the apphost .exe carries a copy of its assembly's block

Also stamped on every assembly: AssemblyMetadata("RepositoryUrl") (the SDK, from RepositoryUrl; the App test holds it equal to IssueLink.Repository) and, when release.yml passes it, FrameLedgerSourceRef — the App csproj's alone until beta.14, now Directory.Build.props', and passed to both publishes. tools/versioninfo-check.ps1 reads all of it from the BUILT binaries — the native five and, with -ManagedDir, the managed eight (FrameLedger.exe/.dll, FrameLedger.Agent.exe/.dll, Domain, Application, Infrastructure, Shared) — and is red when a copyright differs anywhere, when a managed ProductVersion is not -ExpectedProductVersion (required: a comparison with nothing passes everything), or when an apphost does not carry its assembly's block; its -SelfTest (ten cases, nine RED, each for the reason it names) runs first. AssemblyIdentityTests (App and Agent) pins the source against FL_COPYRIGHT.

The Velopack package version is the tag's (vpk pack --packVersion), and UpdateManager.CurrentVersion reads the installed package's manifest — not the assembly — which is why the two are made to agree here rather than assumed to.

Publish & package

cmake --build --preset x64-release
dotnet publish src/FrameLedger.App   -c Release -r win-x64 --self-contained -p:PublishReadyToRun=true -p:FrameLedgerSourceRef={tag} -o out/app
dotnet publish src/FrameLedger.Agent -c Release -r win-x64 --self-contained -p:PublishReadyToRun=true -p:FrameLedgerSourceRef={tag} -o out/app
vpk download github --repoUrl https://github.com/poli0981/frameledger --channel win --pre --outputDir out/release   # beta.13: the previous release, for a delta
vpk pack --packId FrameLedger.App --packVersion {ver} --packDir out/app --mainExe FrameLedger.exe --packTitle FrameLedger --packAuthors FrameLedger --releaseNotes out/notes.md --outputDir out/release

On the alpha line (D73, 2026-10-31) both vpk commands take --channel alpha — the download, so an alpha's delta is made from the previous alpha, and the pack, so its feed is releases.alpha.json, which no beta reads. The main line's pack keeps the command above exactly (no --channel: Velopack's default on Windows is win). §The alpha line.

Run by release.yml since 2026-09-14 (P4 PR-5) — 13_CI_CD §release.yml carries the steps around it (the version gate, {{RELEASE_DATE}}, the published-tree assertion, checksums, the release). Both publishes take -p:Version=<tag> (§Version). No --icon: assets/icon.ico does not exist, and this line named it for six weeks. Since beta.12 the App also takes -p:FrameLedgerSourceRef — the tag, or for a rehearsal the commit — stamped as assembly metadata so its links into the repository open THIS version's documents (Services/RepositoryLinks); a build without it links to main. Since beta.14 the Agent takes it too, because Directory.Build.props stamps it on every assembly and both publishes build the same libraries into out/app (§Version, Identity).

The package id is FrameLedger.App, and this line said FrameLedger until 2026-09-14 — which would have deleted every user's ledger on uninstall. Velopack installs into %LOCALAPPDATA%\<packId> and removes that directory when the app is uninstalled; %LOCALAPPDATA%\FrameLedger is the data folder (LedgerPaths, 07_IPC, legal/PRIVACY_POLICY.md §1). With the same id the install would live inside the ledger's folder and the uninstaller would take ledger.db with it, without the question below. The title users see stays "FrameLedger" (--packTitle); the installer is FrameLedger.App-win-Setup.exe. UninstallHook.AreSeparate refuses the data delete if the two ever overlap again, so a future id change fails safe rather than silently.

Exactly two roots, and a gate now says so. src/FrameLedger.CaptureHost — the unshipped capture host — is outside the package because neither root references it, and tools/package-closure-check.ps1 is what keeps that true rather than remembered. It matters more than an ordinary layering rule: §S27 was closed on the grounds that no shipped binary carries an injecting entry point, and the host is one. A ProjectReference from either root would reopen §S27 silently, so the gate names the edge. Proven both directions — a reference from the Agent leaves the build green and turns the gate red.

Solution membership is NOT the mechanism and must not be confused with it: FrameLedger.slnx is never passed to dotnet publish, and leaving the host out of it would exclude it from dotnet build, dotnet format, the analyzers and dotnet test — a far larger hole than the one it would appear to close.

What the gate does not see, said here rather than left to be discovered. It resolves <ProjectReference> and nothing else — not <Import Project="…targets">, not Directory.Build.props. This repository's idiom for putting a foreign binary beside a project's output is exactly an imported .targets with a <None … CopyToOutputDirectory> item, so a .targets that staged FrameLedger.CaptureHost.exe into a publish root would be invisible to it. Narrower than it sounds — staging a binary is not referencing a project, the shipped assemblies would still hold no code path to it, and the copy would be a visible new <Import> in a root csproj — but it is a hole, and a gate that overstates its reach is the thing this one exists to prevent.

  • No trimming (WPF + reflection), no NativeAOT (WPF unsupported), no obfuscation (GPLv3 policy, and 19_SAFETY forbids making our binaries harder to identify).
  • SatelliteResourceLanguages=en;vi;ja. Expected package ≈ 95–130 MB self-contained. Measured 2026-09-14 (P4 PR-5): the published tree is 250 MB in 362 files (App + Agent, self-contained, ReadyToRun roughly doubles the IL). vpk pack 1.2.0 over that tree, run by hand the same day with the workflow's arguments: FrameLedger.App-win-Setup.exe 104 MB, the full .nupkg and the portable zip 100 MB each, plus releases.win.json / RELEASES / assets.win.json; vpk's own pre-process step verified VelopackApp.Run() in FrameLedger.App.Program::Main(). From the hosted runner on the first tag (2026-09-16, v0.1.0-beta.1): the tree 252 MB, Setup.exe 110 MB, the nupkg and the zip 105 MB — the same shape, a few MB heavier for two more days of code.
  • Velopack hooks (built 2026-09-14, P4 PR-5: App/Update/VelopackHooks, wired in the hand-written Program.Main before any window; since beta.14 Velopack's apply-at-start is off and an update it starts itself stops the Agent first — 11_UPDATER §The update audit). Install registers nothing — the first-run flow is the offer (Agent setup), and the layer follows the ledger (§The Vulkan layer is not registered at install time); this line used to say "offer Agent setup + Vulkan layer registration", and the second half was the thing the section below forbids. Uninstall runs UninstallHook: Shutdown to a running Agent over the pipe (best effort, it holds the install directory), unregister the layer (HKCU), remove the logon task, remove the Start FrameLedger with Windows Run value (beta.14 — it named the executable being deleted), then ask about the data folder — deleted on Yes only, never when it and the install overlap (AreSeparate), and a question unanswered inside Velopack's 30 s callback budget keeps it.

Release-time token substitution

{{RELEASE_DATE}} in legal/*.md is the only placeholder that survives into the repository, and it is deliberate: the effective date of a legal document is the date it ships, which is not knowable at authoring time. release.yml (built 2026-09-14, P4 PR-5 — the step runs before the build, because the App embeds legal/*.md) substitutes it with the tag date the run's UTC date (corrected 2026-10-04) when packaging, and ci.yml fails the build if any other {{ token appears in README.md or legal/*.md (13_CI_CD.md §ci.yml). Everything else — repository URL, slug, developer identity, contact address — is resolved in the source files, because an unsubstituted token in a document the app displays for acceptance (FR-11) is a defect, not a template.

The build id is read before it (beta.18). The substitution edits tracked files, and the native build id is git describe --dirty at CMake's configure (src/native/FrameLedger.Shm/CMakeLists.txt): every release until beta.18 shipped <tag>-dirty — the owner's Dashboard read Overlay build v0.1.0-beta.17-dirty, and that run's log printed FL_BUILD_ID = v0.1.0-beta.17-dirty two lines after RELEASE_DATE = 2026-10-07 in 3 file(s). release.yml now reads describe from the clean checkout first, refuses one that is already dirty or longer than 31 characters, and passes it as the environment's FL_BUILD_ID, which CMake takes as given (checked for the characters a C string literal carries); after the publish, tools/buildid-check.ps1 reads it back out of the four native binaries that compile it, by their bytes — nothing is loaded. A developer's build still runs describe itself (+ marks a dirty tree when the long form would not fit).

Local quality gate (pre-push)

./build.ps1 check:

  1. cmake --build --preset x64-release (C++ /W4 /WX) — since beta.12 also FrameLedger.ProcessStats.dll (the game process's memory, D43; staged beside the Agent, CaptureHost and Infrastructure.Tests by FrameLedger.ProcessStats.targets), its ctest fl_process_stats (GPU_INSTANCE on a machine with a hardware adapter, NO_GPU_INSTANCE elsewhere) and the instrument fl-probe-processstats (spike-notes §16)
  2. native tests (Catch2)
  3. clang-format --dry-run -Werror over src/native
  4. dotnet restore + build (warnings as errors)
  5. dotnet format --verify-no-changes
  6. dotnet test --logger trx — including ShmLayoutMirrorTests; with no switches it also runs the Category=Integration classes, which CI excludes which CI runs too (corrected 2026-10-04: ci.yml and release.yml call ./build.ps1 check with no switches since 2026-09-06, as the paragraph after this list says; only -SkipIntegration, which nobody passes, leaves them out, loudly)
  7. tools/coverage-gate.ps1 — reads this run's cobertura reports; self-arming, and armed today for FrameLedger.Domain and FrameLedger.Application. (Since 2026-10-25 step 6 writes OpenCover beside each Cobertura report — --collect:"XPlat Code Coverage;Format=cobertura,opencover" — for SonarCloud, whose C# importer reads no Cobertura; ci.yml's sonarcloud job takes them from the gate's artifact, 13_CI_CD §SonarCloud. This gate still reads Cobertura only.)
  8. tools/rules-validate.ps1 (schema + anticheat block sanity — a malformed or empty blocklist is a safety bug)
  9. tools/versioninfo-check.ps1 — reads the built binary, because what ships is what an anti-cheat vendor sees; since P4 PR-5 it also compares every FileVersion against the VERSION file (§Version); since beta.14 (D50) both halves run — the self-test, then the native five and the managed eight from the App's and the Agent's build output (-ManagedDir, -ExpectedProductVersion = VERSION), one copyright across all of them (§Version, Identity). Under -SkipNative the managed half still runs
  10. tools/chokepoint-check.ps1 — injection and evasion primitives confined to one file, native and managed, plus the FL_GUARD_TESTABLE symbol check against the shipped artifacts
  11. tools/hookinventory-check.ps1 — three passes: A resolves every vendor symbol the Overlay names against docs/vendor-exports.json, B sweeps for stray literals, C reads the BUILT Overlay's import table and asserts it imports no vendor module. C skips loudly under -SkipNative. Missing from this list until 2026-08-28, which is §R10 happening again
  12. tools/package-closure-check.ps1 — both halves: the self-test (5 cases, 4 of which must go RED) and a live pass over this repository. It walks the transitive ProjectReference closure of the two publish roots below and fails on anything outside the allowlist, naming the reference edge. FrameLedger.CaptureHost is an injecting entry point kept out of the package by construction, and 20_OPEN_QUESTIONS §S27 is closed on exactly that basis
  13. tools/license-check.ps1 — asserts every vendored third-party has a licence copy in legal/licenses/, and that no Intel IGCL / AMD ADLX material has appeared in the tree; since P4 PR-6 (§3) also that legal/licenses/nuget/ is exactly what tools/license-gather.ps1 writes for this build's restore output — every NuGet package the App and the Agent ship (77), both directions. license-gather.ps1 -SelfTest runs first: fourteen sixteen fixture cases, five six that must be RED (a hand edit, a package that no longer ships, a URL-only licence with no reviewed override, an expression with no text in the script and no reviewed override, an applied MPL Exhibit B, a missing restore output), and one run under tr-TR in a child process, because the output must not depend on the machine's culture. Since beta.12 (78 packages): a reviewed override also answers for an expression the script has no text for — Markdig declares BSD-2-Clause and ships no file, and tools/license-overrides/Markdig.txt is the project's own license.txt at the packaged commit 13b. tools/accuracy-check.ps1 -SelfTest, then live — the accuracy block is ONE text (legal/ACCURACY.md) embedded verbatim in README.md and legal/DISCLAIMER.md §4; a copy that drifted, a copy with no markers, or an empty source is red. Four self-test cases, both directions (§S23-6, 2026-09-06) 13c. tools/notice-check.ps1 -SelfTest, then live (beta.12, owner decision D45, 2026-10-03) — every first-party source file (.cs .cpp .h .inl .ps1 .xaml, tracked or new, minus src/native/third_party/) opens with SPDX-License-Identifier: GPL-3.0-only and Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE in its own comment syntax, because GPLv3 §7 wants additional terms named "in the relevant source files" (NOTICE carries them); the second line may name another holder and year in the same form (a contributor's own file). Seven self-test cases, both directions; ./tools/notice-check.ps1 -Fix writes a missing header, and tools/resx-gen.ps1 generates the accessor with it 13d. tools/wiki-build.ps1 -SelfTest, then -Check (beta.17, owner decisions D53/D54, 2026-10-07) — assembles the GitHub Wiki from wiki/, guide/, LIMITATIONS.md and (beta.35) ACCESSIBILITY.md into a temporary folder, as wiki.yml does at a release (13_CI_CD §wiki.yml), and fails on a link to a file, folder or section that does not exist, two sources for one page, a page that neither Home nor the sidebar leads to, a sidebar that lists the guide in another order than guide/README.md, a backticked repository path in a wiki/ page that names nothing, and a version number written into a wiki/ page (the footer says which release the wiki shows). Nine Ten self-test cases since beta.35 (the statement's page, D88), both directions
  14. tools/changelog-check.ps1 -SelfTest — nine cases, five expected RED. The live half needs a pull request's changed-file list and is supplied by ci.yml 14b. tools/release-notes.ps1 -SelfTest — five cases over a fixture changelog (a dated and an undated section, a missing one, a prefix that must not match, an empty one), and since beta.24 three over a temporary tree: a version with its own docs/changelog/<version>.md is read from it, one without from CHANGELOG.md, a prefix of a file name is not that file. The live half needs a tag's version and runs in release.yml, where a missing or empty section is a red release (P4 PR-5) 14e. tools/nvapi-readonly-check.ps1 -SelfTest, then live (owner decision D108, 2026-11-11) — every NvAPI_* call in src/native/FrameLedger.NvapiBridge/src/fl_nvapi_bridge.cpp, the one translation unit that links nvapi64.lib into a shipped binary, is on tools/nvapi-allowed-calls.txt and every name there is called; a name that sets, saves, restores, deletes, registers, resets, enables, disables or controls something is red even when the list names it, and so is one that returns an identifier (D104) — three reads the verb rule would refuse are exempt by name, each with its reason. Comments and string literals are taken out first, so a setter named in the comment that says it is never called is not a call. Seventeen self-test cases, both directions. Text only: it runs with or without the native build. 18_GPU_VENDOR_APIS §Runtime policy's "never call a setter", which was a sentence until the bridge went from fourteen calls to forty-four 14g. tools/input-readonly-check.ps1 -SelfTest, then live (owner decisions D155–D163, 2026-11-14) — what FrameLedger asks Windows about controllers, the keyboard and the mouse. Every Windows function the input reader calls is declared in ONE file, src/FrameLedger.Infrastructure/Input/Win32Input.cs, and is on tools/input-allowed-calls.txt; every name there is declared; a name that sends to a controller (XInputSetState, any HidD_*), injects input (SendInput), reads a key (GetAsyncKeyState, GetKeyState, GetKeyboardState, XInputGetKeystroke) or installs a hook is red even when the list names it; no managed source outside src/FrameLedger.Infrastructure/Input/ names an input function at all, and NativeMethods.txt asks CsWin32 for none; raw input is registered for joysticks and gamepads only — InputReader.RegisteredUsages is exactly usage page 1, usages 4 and 5, and the backend builds its registration from it and writes no usage as a number; and no native source names an input function — nothing loaded into a game reads input. Comments and string literals are taken out first. Seventeen self-test cases, both directions. Text only; it does not look at the tests, which may drive a real keyboard for the App's own shortcuts. 21_INPUT_DEVICES §What is never read, which the Privacy Policy repeats to the user 14f. tools/overlay-fields-check.ps1 -SelfTest, then live (owner decision D116, 2026-11-12) — the same for the code loaded into a game: every member of a vendor's struct the Overlay reads for Advanced metrics is read in ONE header, src/native/FrameLedger.Overlay/include/fl_adv_fields.h, through parameters with fixed names, and is on tools/overlay-allowed-fields.txt; every name there is read; the parameters are not aliased and -> reaches nothing but desc and the Overlay's own region; no other Overlay or Vulkan-layer source reads a listed member; a camera's position, axes and matrices (cameraPos, cameraUp, cameraRight, cameraFwd, the five matrices, cameraPinholeOffset, cameraPosition, cameraForward) are named nowhere in those sources and not on the list, whatever the list says; and neither sl::Constants nor ffxDispatchDescFrameGenerationPrepareV2 is copied by value or measured with sizeof. Comments and string literals are taken out first. Nineteen self-test cases, both directions. Text only. It reads names, not types — which struct version carries a member is 17_HOOK_ENGINE §Which struct version carries which field and ctest fl_adv_fields 14d. tools/docs-split-check.ps1 -SelfTest, then live (beta.24, owner decision D66) — CHANGELOG.md holds no released section beside [Unreleased]; each docs/changelog/<version>.md holds one ## heading, its own ## [<version>] - date, and no relative link (the App renders release notes as CHANGELOG.md); CHANGELOG.md and the files under docs/changelog/, and docs/HANDOFF.md and the files under docs/handoff/ — and since PR-5 docs/20_OPEN_QUESTIONS.md and docs/open-questions/, docs/spike-notes.md and docs/spike-notes/ — name each other in both directions. Eleven self-test cases, both directions 14c. tools/buildid-check.ps1 -SelfTest (beta.18) — eight cases, both directions: a binary built from a dirty tree (-dirty, or the short form's +), one with no id, a missing one, and an expected id that is dirty or not an id are red. The live half needs the release's clean-checkout id and runs in release.yml over the published tree (§Release-time token substitution)
  15. tools/resx-audit.ps1 — skipped loudly; it does not exist, and no .resx file does either built 2026-09-13 (P3 PR-2): -SelfTest first (11 fixture cases, both directions), then the live pass over every Strings.resx family under src/ — key sets equal across en/vi/ja, Safety_* in ja marked for review or signed, Strings.Designer.cs current with tools/resx-gen.ps1. A tree with no family is red (09_I18N §Translation workflow)
  16. struct-mirror — reads this run's .trx and fails when ShmLayoutMirrorTests did not execute, so deleting the mirror test is red as well as breaking it 16b. tools/test-artifacts-check.ps1 — -SelfTest first (seven cases, two RED), then live: an overlay-*.log created since this gate started, still in the real %LOCALAPPDATA%\FrameLedger\logs after the tests, whose first line names a hook-harness* image, fails the gate. It is what makes a test binary without its log sweep red (17_HOOK_ENGINE §Native logging, 2026-09-15); a game's log never counts
  17. Placeholder guard — fails if any {{ token other than {{RELEASE_DATE}} survives in README.md or legal/*.md

This list was wrong in two ways until 2026-08-06 and both were the same kind of wrong. Step 6 said the struct-mirror check "does not exist; build.ps1 declares and skips it loudly" — while line 52 of this same document, and build.ps1 itself, had it as a hard throwing gate since 2026-08-05. And the list omitted four gates the script actually runs: coverage-gate, versioninfo-check, chokepoint-check and changelog-check. A document whose job is to be the list of what check does was missing 40% of it, which is worse than having no list: a reader plans against it. 13_CI_CD.md repeats the struct-mirror claim and is corrected with it.

CI runs the identical script (13_CI_CD) with no switches since 2026-09-06 — -SkipIntegration was CI's from 2026-08-05 until §S19(b)'s signer half removed the refusal behind it — so a green CI is now evidence for the managed drain too, and ./build.ps1 check with no switches is what a developer runs before pushing.

Gates skip loudly. A gate whose tool is not installed (no cl.exe) or not yet written prints SKIPPED, is listed again in the summary, and the run ends with PASSED WITH N SKIPPED GATE(S) rather than a clean ALL GATES PASSED. A gate that silently passes because it did nothing is worse than no gate: it reads as "checked" in CI output when nothing was checked.

Gates are proven red-green, not just green. license-check and rules-validate were each verified to fail on a planted violation — an IGCL header dropped into the tree, and an emptied anticheat.modules list — before being wired in. A safety gate that has only ever been observed passing has not been tested.