* 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>
61 KiB
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 runtools/vklayer-blastradius.ps1) (corrected 2026-10-04: the layer builds against the vendoredthird_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=1is specified but not implemented —grep -rn FL_MOCK src tests tools build.ps1returns 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 ishook-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.dllFrameLedger.VkLayer→FrameLedger.VkLayer.dll+VkLayer_FRAMELEDGER_overlay.jsonFrameLedger.Injector→ static lib only. There is noFrameLedger.Injector.exeand none ships (20_OPEN_QUESTIONS§S9, decided 2026-08-02). A standaloneLoadLibraryWinjector 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 useshook-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 linksnvapi64.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_flagsonly, not the hostile-environment set.versioninfo-check.ps1requires its version block like the otherthreeshipped natives (five in all since beta.12 — corrected 2026-10-04). ctestfl_nvapi_bridge(src/native/tests/nvapi_bridge_test.cpp) exercises every export and requiresBRANCH: AVAILABLEorBRANCH: DEGRADEDin the output, so a bridge gutted toreturn 0is 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) andFrameLedger.ProcessStats→FrameLedger.ProcessStats.dll(beta.12, D43: the game process's memory, read by the Agent from outside the game; probefl-probe-processstats) (both bullets added 2026-10-04; they were missing)the ctest executables inFrameLedger.Overlay.Testssrc/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 toohook-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 Nsince 2026-09-06 (P1 item 3): a real swapchain on a hidden window through the real loader, reached byLoadLibraryW("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 Nsince 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:cfand-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 ofspike-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--realalso prints which image the two getter addresses lie in (nvapi64_impl.dll, not thenvapi64.dllthat is asked). What it was written as: the call sequence Reflex route D would put into the Overlay — findnvapi64.dllonly 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.--stubruns it againstfl_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 itsnvapi64.libis never beside the vendored one's name) and is ctestfl_reflex_probe_stub;--realruns 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 linknvapi64.lib. Nothing shipped includes its header.fl_stub_sl_interposer→sl.interposer.dll, andfl_stub_sl_common→sl.common.dll(src/native/tools/vendor-stubs/). Fixtures, never shipped, built underFL_BUILD_TOOLS; nothing12_BUILDpublishes references them. They export the measured vendor names fromdocs/vendor-exports.jsonso 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_resourcetakes the real filename so a file calledsl.interposer.dllin our build tree still says plainly that it is FrameLedger's, which19_SAFETYrequires 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 — andfl_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-ffxcan 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 namesSpeaksFsr3Hostprobes for through the vendoredfsr3-v3.0.4header's ownFFX_API;--ffx-topology fsr3host|fsr3host+monodrives it, andhookinventory-checkPass 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.libis vendored — andhookinventory-checkPass C reads the Overlay's export table becauseffx_api.hdeclares 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_APIentry points areextern "C"imports, and linking one would makesl.interposer.dlla load-time dependency ofFrameLedger.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/"containsCMakeLists.txtandvulkan-headersonly". 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 and18_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 guardNvAPI_Initializefailure 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 every shipped native — the five FrameLedger.Overlay.dll and FrameLedger.VkLayer.dlltools/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.jsonpins the SDK band (11.0.xsince beta.37 —10.0.xbefore —rollForward: latestFeature,allowPrerelease: false). Without itdotnet buildpicks the newest installed SDK — on a machine with a preview of the next .NET installed that silently changes analyzer behaviour underTreatWarningsAsErrors, and makes local and CI disagree for reasons nobody can see in a diff. (Thealphabranch 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) andSupportedOSPlatformVersion=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 rejectsSupportedOSPlatformVersionaboveTargetPlatformVersion(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 barenet11.0-windowsis wrong for a different reason: it resolves tonet11.0-windows7.0, and CA1416 would then error on Mica,MiniDumpWriteDumpandQueryVideoMemoryInfo— 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-x64on the publish command.RuntimeIdentifieris 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.Agentand nowFrameLedger.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,ContinuousIntegrationBuildon CI.
-
-
Directory.Packages.props: central package management, all versions pinned (includingWPF-UI= 4.3.0 exactly —16_WPFUI_SYNTAX§Version hygiene). -
Native output reaches the managed side through
.targetsfiles imported byFrameLedger.Agent, not throughFrameLedger.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 frombuild.ps1, which runs the native build first — not from the solution:FrameLedger.slnxcontains 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 inFrameLedger.Infrastructure.csproj, which contains no<Target>at all. It said the copies happen there, when the guard DLL was deliberately moved out to a.targetsfile 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.
ShmLayoutMirrorTestsrunstools/fl-layout-dump, reads its JSON, and asserts size plus every field offset against the C#[StructLayout]mirrors inFrameLedger.Shared— in both directions, so a field on either side alone fails. It also asserts blittability, which offsets cannot see. Thestruct-mirrorgate reads the run's.trxand 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.csprojand no.csfiles — 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 againsthook-harness."Harness + Overlay" — startshook-harnessunder 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
PATHbreaks the native build.vcvars64prepends to whateverPATHit inherits, and MSVC shipslink.exe— there is nold.exeto shadow MinGW's. CMake then picks MinGW's linker and the build dies withcannot find /nologo: No such file or directory, a failure a long way from its cause.build.ps1strips only the MinGW entries before importing the MSVC environment, sodotnet,gitandcmakesurvive. vcvars64exportsPlatform=x64, which is meaningful for.vcxprojbuilds. We have none, and MSBuild reads it as a solution platform, sodotnet build FrameLedger.slnxthen fails withMSB4126 solution configuration "Release|x64" is invalid.build.ps1clears it after import; project-level x64 comes fromDirectory.Build.props.ninjaandclang-formatboth ship inside the VS C++ workload but are on neither the defaultPATHnor thevcvarsone.build.ps1locates 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), (the App's — --diagFrameLedger.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):
--serveand--console; the other five answer "not implemented in P2" with exit 2 rather than being silently accepted (--diagis the App's anyway,10_LOGGING). The console surface, pinned byAgentCommandLineSurfaceTests: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--consoleonly (HANDOFF §P2 decision D6):--servenever takes one, so the product's%LOCALAPPDATA%\FrameLedgeris not selectable and an integration test cannot point the product at a profile.AgentEndToEndTestsruns the shippedFrameLedger.Agent.exeagainsthook-harnesswith a scratch--data-dirand reads the onesessionsrow back — the milestone's technical half, in the merge gate.
The print verbs open the ledger read-only (2026-09-16).
sessions,consent listandkillswitch statusmigrate nothing and refuse — exit 7, the reason on stderr — a ledger at a schema older or newer than the build;db pathopens no file at all. Until then every verb went through the migrating open, andsessionsrun against the owner's ledger applied two scripts to it (06_DATA_MODEL§Migrations).AgentReadOnlyVerbsTestspins the set.
One capturing process per data folder (2026-09-17).
--serve,capture,launchandrecoverclaim 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-taskdoes.OneAgentPerDataFolderTestsruns the shipped binary against a claimed scratch folder (01_ARCHITECTURE§Lifecycle).
Bundled assets
-
— 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, andassets/native/PresentMon.exe(pinned, SHA-256 verified at build) for the Tier-2 fallbacktools/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,EtwFrameSourceis deleted from the design, and whether a shipped build ever regains a no-injection measurement is20_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, andEtwFrameSourceis 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
LoadLibrarysvulkan-1.dll— read by the Agent's detection sweep intocapability_flagsasvulkan(17_HOOK_ENGINE§Vulkan built note).Application.Vulkan.VkLayerReconcilerregisters 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:
SupportedOSPlatformVersionstays10.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.RunAsyncrethrows the exception of aBackgroundServicethat failed, so the Agent's--serveleaves through its crash report where on .NET 10 it exited 0 (10_LOGGING§Crash handling;HostBackgroundFailureTestsholds it);Microsoft.Data.Sqlite11 declares SQLitePCLRaw 3.0.5, whose engine is SourceGear'sSQLitepackage; nineMicrosoft.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
alphabranch differs from main inRELEASE_LINEalone (git diff main alpha --name-onlyprints 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.propsstamps itsFlAlphaLineRestsproperty (true on main since beta.37) into every assembly,Shared.AlphaLine.Restsreads 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
alphadiffers from main in while it tries a newer .NET, and nothing else:RELEASE_LINE(alpha);global.json(that SDK, withallowPrerelease: truewhen it is a prerelease); the TFM inDirectory.Build.props(SupportedOSPlatformVersionstays10.0.19045.0); the three Microsoft packages inDirectory.Packages.propsthat 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 oflegal/THIRD_PARTY_NOTICES.md;FlAlphaLineRestsset tofalseinDirectory.Build.props; and a fix only the newer .NET can take, if one is ever forced. As it stood for .NET 11 RC3: SDK11.0.100-rc.3.26522.148,net11.0-windows10.0.22621.0, the three packages at11.0.0-rc.3.26522.148(spike-notes§24). No newer language syntax and no preview feature onalpha(D76): the source is main's, and main compiles with its own SDK. - Everything else lives on main, dormant on the main line.
RELEASE_LINEis read likeVERSIONand stamped into every assembly as theFrameLedger.ReleaseLinemetadata (Directory.Build.propsrefuses any value butmainandalpha);Shared.BuildLinereads 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
alphawith 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 onalpha(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, leavingRELEASE_LINE. - Building it locally: check out
alphawith the SDK itsglobal.jsonnames installed and run./build.ps1 checkas 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.propsreads it into<Version>(assembly, file and informational versions; SourceLink's+shasuffix is off so About,Helloand the bug bundle print the version a user can find on the releases page). The read is conditional on$(Version)being empty, sorelease.ymlpasses-p:Version=0.1.0-beta.1for a pre-release and the assemblies carry the tag's full version.src/native/CMakeLists.txtreads the same file intoproject(VERSION …), which the.rctemplate turns into every VERSIONINFO block. CMake'sproject()accepts numbers only, so the nativeFileVersionis the numeric core even for a pre-release.tools/versioninfo-check.ps1compares every built binary'sFileVersionagainst the file (x.y.z.0), so a read that silently produced0.0.0on either side is red in the gate.release.ymlrefuses a tag whose numeric core is not the file's. Bumping the version is one edit toVERSION, 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 isreleases.alpha.json, which no beta reads. The main line's pack keeps the command above exactly (no--channel: Velopack's default on Windows iswin). §The alpha line.
Run by
release.ymlsince 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.icodoes 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 tomain. Since beta.14 the Agent takes it too, becauseDirectory.Build.propsstamps it on every assembly and both publishes build the same libraries intoout/app(§Version, Identity).The package id is
FrameLedger.App, and this line saidFrameLedgeruntil 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%\FrameLedgeris 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 takeledger.dbwith it, without the question below. The title users see stays "FrameLedger" (--packTitle); the installer isFrameLedger.App-win-Setup.exe.UninstallHook.AreSeparaterefuses 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, andtools/package-closure-check.ps1is 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. AProjectReferencefrom 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.slnxis never passed todotnet publish, and leaving the host out of it would exclude it fromdotnet build,dotnet format, the analyzers anddotnet 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">, notDirectory.Build.props. This repository's idiom for putting a foreign binary beside a project's output is exactly an imported.targetswith a<None … CopyToOutputDirectory>item, so a.targetsthat stagedFrameLedger.CaptureHost.exeinto 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_SAFETYforbids 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 pack1.2.0 over that tree, run by hand the same day with the workflow's arguments:FrameLedger.App-win-Setup.exe104 MB, the full.nupkgand the portable zip 100 MB each, plusreleases.win.json/RELEASES/assets.win.json; vpk's own pre-process step verifiedVelopackApp.Run()inFrameLedger.App.Program::Main(). From the hosted runner on the first tag (2026-09-16,v0.1.0-beta.1): the tree 252 MB,Setup.exe110 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-writtenProgram.Mainbefore 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 runsUninstallHook:Shutdownto 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:
cmake --build --preset x64-release(C++/W4 /WX) — since beta.12 alsoFrameLedger.ProcessStats.dll(the game process's memory, D43; staged beside the Agent, CaptureHost and Infrastructure.Tests byFrameLedger.ProcessStats.targets), its ctestfl_process_stats(GPU_INSTANCE on a machine with a hardware adapter, NO_GPU_INSTANCE elsewhere) and the instrumentfl-probe-processstats(spike-notes§16)- native tests (Catch2)
clang-format --dry-run -Werroroversrc/nativedotnet restore+ build (warnings as errors)dotnet format --verify-no-changesdotnet test --logger trx— includingShmLayoutMirrorTests; with no switches it also runs theCategory=Integrationclasses,which CI excludeswhich CI runs too (corrected 2026-10-04:ci.ymlandrelease.ymlcall./build.ps1 checkwith no switches since 2026-09-06, as the paragraph after this list says; only-SkipIntegration, which nobody passes, leaves them out, loudly)tools/coverage-gate.ps1— reads this run's cobertura reports; self-arming, and armed today forFrameLedger.DomainandFrameLedger.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'ssonarcloudjob takes them from the gate's artifact,13_CI_CD§SonarCloud. This gate still reads Cobertura only.)tools/rules-validate.ps1(schema +anticheatblock sanity — a malformed or empty blocklist is a safety bug)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 everyFileVersionagainst theVERSIONfile (§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-SkipNativethe managed half still runstools/chokepoint-check.ps1— injection and evasion primitives confined to one file, native and managed, plus theFL_GUARD_TESTABLEsymbol check against the shipped artifactstools/hookinventory-check.ps1— three passes: A resolves every vendor symbol the Overlay names againstdocs/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 againtools/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 transitiveProjectReferenceclosure of the two publish roots below and fails on anything outside the allowlist, naming the reference edge.FrameLedger.CaptureHostis an injecting entry point kept out of the package by construction, and20_OPEN_QUESTIONS§S27 is closed on exactly that basistools/license-check.ps1— asserts every vendored third-party has a licence copy inlegal/licenses/, and that no Intel IGCL / AMD ADLX material has appeared in the tree; since P4 PR-6 (§3) also thatlegal/licenses/nuget/is exactly whattools/license-gather.ps1writes for this build's restore output — every NuGet package the App and the Agent ship (77), both directions.license-gather.ps1 -SelfTestruns first:fourteensixteen fixture cases,fivesix 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, andtools/license-overrides/Markdig.txtis the project's ownlicense.txtat the packaged commit 13b.tools/accuracy-check.ps1 -SelfTest, then live — the accuracy block is ONE text (legal/ACCURACY.md) embedded verbatim inREADME.mdandlegal/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, minussrc/native/third_party/) opens withSPDX-License-Identifier: GPL-3.0-onlyandCopyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICEin its own comment syntax, because GPLv3 §7 wants additional terms named "in the relevant source files" (NOTICEcarries 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 -Fixwrites a missing header, andtools/resx-gen.ps1generates 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 fromwiki/,guide/,LIMITATIONS.mdand (beta.35)ACCESSIBILITY.mdinto a temporary folder, aswiki.ymldoes 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 thanguide/README.md, a backticked repository path in awiki/page that names nothing, and a version number written into awiki/page (the footer says which release the wiki shows).NineTen self-test cases since beta.35 (the statement's page, D88), both directionstools/changelog-check.ps1 -SelfTest— nine cases, five expected RED. The live half needs a pull request's changed-file list and is supplied byci.yml14b.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 owndocs/changelog/<version>.mdis read from it, one without fromCHANGELOG.md, a prefix of a file name is not that file. The live half needs a tag's version and runs inrelease.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) — everyNvAPI_*call insrc/native/FrameLedger.NvapiBridge/src/fl_nvapi_bridge.cpp, the one translation unit that linksnvapi64.libinto a shipped binary, is ontools/nvapi-allowed-calls.txtand 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 ontools/input-allowed-calls.txt; every name there is declared; a name that sends to a controller (XInputSetState, anyHidD_*), 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 outsidesrc/FrameLedger.Infrastructure/Input/names an input function at all, andNativeMethods.txtasks CsWin32 for none; raw input is registered for joysticks and gamepads only —InputReader.RegisteredUsagesis 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 ontools/overlay-allowed-fields.txt; every name there is read; the parameters are not aliased and->reaches nothing butdescand the Overlay's ownregion; 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 neithersl::ConstantsnorffxDispatchDescFrameGenerationPrepareV2is copied by value or measured withsizeof. 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 is17_HOOK_ENGINE§Which struct version carries which field and ctestfl_adv_fields14d.tools/docs-split-check.ps1 -SelfTest, then live (beta.24, owner decision D66) —CHANGELOG.mdholds no released section beside[Unreleased]; eachdocs/changelog/<version>.mdholds one##heading, its own## [<version>] - date, and no relative link (the App renders release notes asCHANGELOG.md);CHANGELOG.mdand the files underdocs/changelog/, anddocs/HANDOFF.mdand the files underdocs/handoff/— and since PR-5docs/20_OPEN_QUESTIONS.mdanddocs/open-questions/,docs/spike-notes.mdanddocs/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 inrelease.ymlover the published tree (§Release-time token substitution)tools/resx-audit.ps1—skipped loudly; it does not exist, and nobuilt 2026-09-13 (P3 PR-2):.resxfile does either-SelfTestfirst (11 fixture cases, both directions), then the live pass over everyStrings.resxfamily undersrc/— key sets equal across en/vi/ja,Safety_*injamarked for review or signed,Strings.Designer.cscurrent withtools/resx-gen.ps1. A tree with no family is red (09_I18N§Translation workflow)- struct-mirror — reads this run's
.trxand fails whenShmLayoutMirrorTestsdid not execute, so deleting the mirror test is red as well as breaking it 16b.tools/test-artifacts-check.ps1—-SelfTestfirst (seven cases, two RED), then live: anoverlay-*.logcreated since this gate started, still in the real%LOCALAPPDATA%\FrameLedger\logsafter the tests, whose first line names ahook-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 - Placeholder guard — fails if any
{{token other than{{RELEASE_DATE}}survives inREADME.mdorlegal/*.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.ps1declares and skips it loudly" — while line 52 of this same document, andbuild.ps1itself, 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-checkandchangelog-check. A document whose job is to be the list of whatcheckdoes was missing 40% of it, which is worse than having no list: a reader plans against it.13_CI_CD.mdrepeats 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.