diff --git a/CLAUDE.md b/CLAUDE.md index 3a6a31e7..1a5045b8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -79,9 +79,13 @@ Dependency direction unchanged: `App/Agent → Application → Domain`; `Infrast **C++ —** `clang-format` (LLVM base, 4-space, 120 col) enforced in CI. No STL containers that allocate in hook paths. No `std::mutex` in hook paths. `-D_HAS_EXCEPTIONS=0` in the Overlay target. Every hook entry point wrapped per the `FL_HOOK_GUARD` macro (`17_HOOK_ENGINE`). Static analysis: `/analyze` + clang-tidy (`bugprone-*`, `cert-*`, `concurrency-*`). -**Struct mirroring —** `FlFrameRecord` is **specified** to exist twice (C++ header, C# `[StructLayout(LayoutKind.Sequential)]`), with a test asserting `sizeof` and every field offset on both sides, and a version constant in the shm header that must match or the Agent refuses to attach. +**Struct mirroring —** `FlFrameRecord`, `FlShmHandshake`, `FlWriterState` and `FlControlBlock` each exist twice: `src/native/FrameLedger.Shm/include/fl_shm.h` (**normative**) and `src/FrameLedger.Shared/ShmLayout.cs` as `[StructLayout(LayoutKind.Sequential)]`. `ShmLayoutMirrorTests` asserts size and every field offset on both sides **against JSON emitted by `tools/fl-layout-dump`**, never a transcribed table, and walks the field list in both directions so a field added on either side alone fails. -**It exists once.** This paragraph was in the present tense until 2026-08-05 and was false: `src/FrameLedger.Shared/` holds a `.csproj` and no `.cs` files, `grep -rn FlFrameRecord src tests --include=*.cs` returns nothing, and `FL_BUILD_ID` — the input to the refuse-to-attach comparison — has a producer and no reader. `build.ps1:324-329` enumerates **nine** files that described the mechanism as live, including `fl_shm.h` (normative) and `fl-layout-dump/CMakeLists.txt` (a build file); `build.ps1:335-342` skips the gate loudly instead of pretending it runs. Tracked as `20_OPEN_QUESTIONS` §R10 and scheduled in §S24. **Until it lands, changing a field in `fl_shm.h` breaks the Agent at runtime rather than at build time** — treat the layout as frozen unless you are the one building the mirror. Same reading rule as §Dev mode below, and the same reason: a doc that says a gate runs is worse than one that says it is missing. +It also asserts **blittability** (`RuntimeHelpers.IsReferenceOrContainsReferences`), because offsets cannot see it: measured 2026-08-05, swapping the `fixed byte BuildId[32]` for this repo's own `[MarshalAs(ByValTStr)] string` idiom keeps `Marshal.SizeOf` at 64 and every offset correct while `Unsafe.SizeOf` collapses to **40** — a mirror that passes the obvious checks and cannot be read out of a memory-mapped view. + +`build.ps1`'s `struct-mirror` gate reads the run's `.trx` and fails when that test class did not execute, so **deleting the test is red too** — it used to `Test-Path` a source file and report on a test it never looked for. + +> **Still open:** the version handshake is only half wired. `FL_BUILD_ID` has a producer and the mirror can now read it out of the handshake, but the Agent has **no build id of its own** to compare against, so `07_IPC`'s refuse-to-attach-on-mismatch cannot yet run (`20_OPEN_QUESTIONS` §S23-1). The drain PR owns that. **Dev mode —** `FL_MOCK=1` is **specified but not implemented** — `grep -rn FL_MOCK src tests tools build.ps1` returns nothing (recorded 2026-08-04). When it exists it runs the whole app with a synthetic frame source and no injection at all, and it is how the UI is meant to be developed; until then, do not plan work on the assumption that it is there. `tools/hook-harness` is a dummy **D3D11 + D3D12** app used to exercise hooks without a real game; Vulkan and OpenGL modes are unwritten (`docs/12_BUILD.md` §Targets is the accurate list). diff --git a/FrameLedger.LayoutDump.targets b/FrameLedger.LayoutDump.targets new file mode 100644 index 00000000..bf9f440c --- /dev/null +++ b/FrameLedger.LayoutDump.targets @@ -0,0 +1,52 @@ + + + + + $(MSBuildThisFileDirectory)build\native\x64-release\tools\fl-layout-dump\ + + + + + fl-layout-dump.exe + PreserveNewest + + + + + + + + + diff --git a/build.ps1 b/build.ps1 index 07aab44d..58c3bdfb 100644 --- a/build.ps1 +++ b/build.ps1 @@ -234,8 +234,11 @@ function Invoke-Managed([bool]$FixFormat) { # Clear them so the gate below sees this run and only this run. Get-ChildItem (Join-Path $repo 'tests') -Directory -Filter 'TestResults' -Recurse -ErrorAction SilentlyContinue | Remove-Item -Recurse -Force -ErrorAction SilentlyContinue + # --logger trx so downstream gates can assert that a NAMED test executed, + # not merely that the run was green. The struct-mirror gate below reads it. Invoke-Checked 'dotnet test' { - dotnet test $solution -c $Configuration --no-build --collect:"XPlat Code Coverage" + dotnet test $solution -c $Configuration --no-build --collect:"XPlat Code Coverage" ` + --logger 'trx;LogFileName=results.trx' } # The cobertura reports above were produced and ignored from the day the @@ -322,25 +325,45 @@ function Invoke-ProjectGates { } # The shared-memory struct mirror. CLAUDE.md §Struct mirroring calls this the - # mechanism protecting the shm ABI, and NINE files describe it in the present - # tense — including fl_shm.h itself, which is normative, and - # fl-layout-dump/CMakeLists.txt, which says a test consumes its output. None - # of it exists: src/FrameLedger.Shared holds only a .csproj, nothing under - # tests/ references FlFrameRecord, and fl-layout-dump has no add_test. + # mechanism protecting the shm ABI, and NINE files described it in the present + # tense while none of it existed. It exists as of 2026-08-05. # - # Named and SKIPPED LOUDLY rather than omitted, which is the discipline - # 20_OPEN_QUESTIONS §R10 asks for: a doc that says a gate runs is worse than - # one that says it is missing, because the second prompts someone to write it. - # Not urgent — the ring is P1 and there is nothing to mirror yet. + # THIS GATE USED TO BE A Test-Path ON A SOURCE FILE, and printed "covered by + # dotnet test" from that alone. It never looked for the test. So creating an + # EMPTY ShmLayout.cs would have turned the loud skip into a silent green, and + # deleting or renaming the mirror test afterwards would have kept it green + # forever — a gate whose verdict is decided before it looks, guarding the one + # mechanism CLAUDE.md calls the protection for the shm ABI. + # + # It now reads the trx from the run that just happened and requires the named + # test class to have EXECUTED and passed. `dotnet test` is what makes a + # regression red; this makes DELETING the regression test red too, which is a + # different failure and the one a Test-Path can never see. Write-Step 'struct-mirror' - $mirrorTest = Join-Path $repo 'src/FrameLedger.Shared/ShmLayout.cs' - if (Test-Path $mirrorTest) { - Write-Host ' covered by dotnet test (FrameLedger.Infrastructure.Tests)' -ForegroundColor DarkGray + $trx = Get-ChildItem (Join-Path $repo 'tests') -Recurse -Filter 'results.trx' -ErrorAction SilentlyContinue + if (-not $trx) { + throw "struct-mirror: no results.trx from this run — the gate cannot confirm the mirror test executed" } - else { - Skip-Gate 'struct-mirror' 'the C# mirror of fl_shm.h does not exist yet (20_OPEN_QUESTIONS §R10) — the shm ABI has no drift gate' + + $mirrorResults = @() + foreach ($file in $trx) { + $xml = [xml](Get-Content -LiteralPath $file.FullName -Raw) + $mirrorResults += $xml.TestRun.Results.UnitTestResult | + Where-Object { $_ -and $_.testName -and $_.testName -match 'ShmLayoutMirrorTests' } } + if ($mirrorResults.Count -eq 0) { + # The failure mode the old gate could not express: the mirror test is + # gone, renamed or filtered out, and everything else is still green. + throw "struct-mirror: ShmLayoutMirrorTests did not run. The shm ABI has no drift gate — a mirror test that is absent must fail, not pass quietly (20_OPEN_QUESTIONS §R10)" + } + + $failed = @($mirrorResults | Where-Object { $_.outcome -ne 'Passed' }) + if ($failed.Count -gt 0) { + throw "struct-mirror: $($failed.Count) of $($mirrorResults.Count) mirror assertions did not pass" + } + Write-Host " $($mirrorResults.Count) mirror assertion(s) executed and passed (fl_shm.h vs FrameLedger.Shared)" -ForegroundColor DarkGray + Write-Step 'placeholder guard' # {{RELEASE_DATE}} is substituted at release time and is the only token # allowed to survive. Anything else in a document FR-11 displays for diff --git a/docs/12_BUILD.md b/docs/12_BUILD.md index 9e215c8c..b86debdf 100644 --- a/docs/12_BUILD.md +++ b/docs/12_BUILD.md @@ -49,9 +49,9 @@ Compiler/linker flags (enforced in CMake, not per-target ad hoc): `/std:c++20 /M - **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) and `/FrameLedger.Rules.targets` (the blocklist seed). 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 `` 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 — ⏳ SPECIFIED, NOT BUILT.** The intent: a test in `FrameLedger.Infrastructure.Tests` reads offsets emitted by a generated header dump from the native build and asserts they match the C# `[StructLayout]` mirror. Struct drift between the two layers is the most dangerous silent bug in this architecture. +- **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. - > **The last clause used to read "the build catches it", in the present tense, and it does not.** `src/FrameLedger.Shared/` holds a `.csproj` and no `.cs` files; nothing under `tests/` references `FlFrameRecord`; `build.ps1` skips the gate loudly for exactly this reason. **This document contradicted itself** — line 138 below has said so correctly all along. `20_OPEN_QUESTIONS` §R10 tracks it and §S24 schedules it. When the mirror lands, this bullet and the eight other present-tense sites `build.ps1:324-329` enumerates flip together. + > 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 diff --git a/docs/14_TESTING.md b/docs/14_TESTING.md index 5a874903..3c94cf98 100644 --- a/docs/14_TESTING.md +++ b/docs/14_TESTING.md @@ -20,7 +20,7 @@ The anti-cheat guard is the one component where a bug can cost someone an accoun - **Ring buffer:** SPSC correctness under a hammering writer thread; seqlock torn-read detection; wrap and overwrite-oldest semantics; power-of-two capacity assumptions. Include the **one-full-lap case**: a reader stalled exactly `capacity` records must not validate a different frame as unchanged (this is what the never-reset `seq` counter defends, `07_IPC` §Protocol rules). - **Drop accounting:** the reader-side computation (`writeIndex - readIndex > capacity`) reports the right count and resumes at the right index. The writer has no drop counter to test — by design. - **Torn records produce gap markers,** not silently shortened streams; a golden test asserts the gap does not appear as a stutter. -- **Record and header layout:** `static_assert(sizeof(...) == 64)` and `offsetof` assertions for `FlFrameRecord` **and all three header structs** (`FlShmHandshake`, `FlWriterState`, `FlControlBlock`) — the Agent reads across the process boundary in every one of them. The native half is done — `layout_test.cpp` plus the `static_assert`s in `fl_shm.h`, ctest `fl_shm_layout`. **The managed half is not: `tools/fl-layout-dump` emits the runtime offset dump and nothing consumes it** (`20_OPEN_QUESTIONS` §R10, scheduled in §S24). This clause read "Runtime offset dump consumed by the managed struct-mirror test" until 2026-08-05, which described a consumer that does not exist. +- **Record and header layout:** `static_assert(sizeof(...) == 64)` and `offsetof` assertions for `FlFrameRecord` **and all three header structs** (`FlShmHandshake`, `FlWriterState`, `FlControlBlock`) — the Agent reads across the process boundary in every one of them. Both halves exist as of 2026-08-05: the native side is `layout_test.cpp` plus the `static_assert`s (ctest `fl_shm_layout`), and the runtime offset dump from `tools/fl-layout-dump` is consumed by `ShmLayoutMirrorTests`, which walks the field list in **both directions** and additionally asserts blittability — `Marshal.SizeOf` and every offset stay correct for a mirror that uses `[MarshalAs(ByValTStr)] string`, while `Unsafe.SizeOf` drops from 64 to 40 and the struct can no longer be read from a mapped view. - **Fault policy:** injected SEH faults in a fake hook body → counter increments, original still called, self-disable at 3. - **Hook index verification, by behaviour.** A vtable slot carries no identity, so "check that slot 8 *is* `Present`" is not a question the runtime can answer — the earlier wording here required something unimplementable. What is answerable: patch the slot, call the method, see whether the detour ran (`17_HOOK_ENGINE` §Getting vtable addresses; proved for slots 8, 13 and 22 in `spike-notes.md` §H4). Runs headless on CI via WARP and `CreateSwapChainForComposition`. A deliberate mismatch aborts installation instead of patching. - **Every probe must be shown to fail.** A probe that ends in an unconditional assertion is green by construction and its ctest is decorative — `fl_proxy_swapchain` shipped in exactly that state. Before a probe counts as a regression net, break the thing it watches and watch it go red. diff --git a/docs/20_OPEN_QUESTIONS.md b/docs/20_OPEN_QUESTIONS.md index fcc076b7..fbcec34a 100644 --- a/docs/20_OPEN_QUESTIONS.md +++ b/docs/20_OPEN_QUESTIONS.md @@ -57,7 +57,7 @@ or it becomes the next stale status claim this file exists to record. | **S13(c)** | 🅓 **deferred, rationale written** | Same decision as S1; (a) and (b) were already settled | | **S19(b)** | 🅓 **deferred, rationale written** | Its true shape is a `CryptCATAdmin*` PR, and `WinVerifyTrust`'s default revocation check does network I/O from inside the hard gate (NFR-10) | | **S14** | 🔨 **scheduled — exe-name half only** | Owner decision 2026-08-05: wire it, empty list, unresolvable identity refuses. The **store-id half is blocked** on the platform metadata extractors and cannot be reached through the guard ABI by design | -| **S23-1** | 🔨 **scheduled** | `FL_BUILD_ID` gets its first reader with the C# mirror | +| **S23-1** | ◐ **half closed 2026-08-05** | The C# mirror can now READ `buildId` out of the handshake. The Agent still has **no build id of its own** to compare it against, so `07_IPC`'s refuse-to-attach-on-mismatch still cannot run. The drain PR owns the other half | | **S23-4** | ✅ **resolved 2026-08-05** | `19_SAFETY` §During a session said "the module scan and the driver scan"; `EvaluateImpl` runs four. Reworded to "every pre-injection check" so it cannot go stale when a check is added, with the two omissions named — `services` is the only tier measured firing on real anti-cheat, and the pre-scan is the only one touching the filesystem | | **S2 part three** | ⏳ **open, sequenced** | In-layer supervision lands with `vkQueuePresentKHR` (P1). Building it sooner would be a predicate whose wrong answer changes nothing observable | | **S4 signing** | ⏳ **open, residual accepted** | HTTPS authenticates the host, not the content. Recorded rather than closed — needs a rationale written or a decision | diff --git a/src/FrameLedger.Shared/FrameLedger.Shared.csproj b/src/FrameLedger.Shared/FrameLedger.Shared.csproj index eeef2a98..b205ac77 100644 --- a/src/FrameLedger.Shared/FrameLedger.Shared.csproj +++ b/src/FrameLedger.Shared/FrameLedger.Shared.csproj @@ -4,21 +4,71 @@ IPC contracts (System.Text.Json source-generated contexts, docs/07_IPC.md) and the C# mirrors of the native shared-memory structs. - THIS PROJECT IS EMPTY. It contains no .cs files, and the paragraph below - described its intended contents in the PRESENT TENSE until 2026-08-05: - "each exist twice", "a test ... asserts". Neither is true: the mirrors exist - only in C++ (src/native/FrameLedger.Shm/include/fl_shm.h) and no managed - test references FlFrameRecord. build.ps1:335-342 skips the gate loudly and - says why; build.ps1:324-329 enumerates the nine files that claimed - otherwise, of which this was one. + The mirrors are the dangerous part: FlFrameRecord, FlShmHandshake, + FlWriterState and FlControlBlock each exist twice, once in C++ + (src/native/FrameLedger.Shm/include/fl_shm.h, which is NORMATIVE) and once + here as [StructLayout(LayoutKind.Sequential)]. ShmLayoutMirrorTests asserts + size AND every field offset on both sides against the JSON emitted by + tools/fl-layout-dump, and asserts that every mirror is BLITTABLE — offsets + alone cannot see the difference between a fixed buffer and a marshalled + string, and only one of those can be read out of a memory-mapped view. - THE INTENT, unchanged and now scheduled (20_OPEN_QUESTIONS §R10, §S24): - FlFrameRecord, FlShmHandshake, FlWriterState and FlControlBlock each exist - twice, once in C++ and once here as [StructLayout(LayoutKind.Sequential)], - with a test in FrameLedger.Infrastructure.Tests asserting sizeof AND every - field offset on both sides against the dump emitted by tools/fl-layout-dump. Struct drift between the two layers is the most dangerous silent bug in this - architecture (CLAUDE.md §Struct mirroring, docs/12_BUILD.md §Managed build). + architecture: nothing crashes, the Agent just reads garbage into fields that + look plausible (CLAUDE.md §Struct mirroring, docs/12_BUILD.md §Managed build). + + The IPC contracts half is still unwritten; only the mirrors are here. --> + + + true + + + $(NoWarn);CA1028;CA1711;CA1716;MA0048;CA1051;CA1815 + + diff --git a/src/FrameLedger.Shared/ShmLayout.cs b/src/FrameLedger.Shared/ShmLayout.cs new file mode 100644 index 00000000..33e75706 --- /dev/null +++ b/src/FrameLedger.Shared/ShmLayout.cs @@ -0,0 +1,304 @@ +// The C# half of the shared-memory ABI. The C++ half is +// src/native/FrameLedger.Shm/include/fl_shm.h and it is NORMATIVE: where the two +// disagree, that header is right and this file is the bug. +// +// WHY THESE ARE FIXED BUFFERS AND NOT [MarshalAs(ByValTStr)] string. +// +// The obvious idiom for a native `char[32]` is +// `[MarshalAs(UnmanagedType.ByValTStr, SizeConst = 32)] public string BuildId`, +// and this repository already uses it once (NativeAntiCheatGuard's FlGuardResult, +// which is fine there -- that struct crosses a P/Invoke boundary, where the +// marshaller runs). It would pass every offset assertion in the mirror test and +// still be wrong here, because a struct containing a `string` is NOT BLITTABLE: +// it cannot be read straight out of a MemoryMappedViewAccessor, which is the one +// thing this type exists to do. The test asserts blittability directly +// (RuntimeHelpers.IsReferenceOrContainsReferences) precisely because offsets +// cannot see the difference. +// +// Every struct is `Size = 64` to match `alignas(64)` on the native side. The +// three header regions are separate cache lines on purpose (fl_shm.h): the +// Overlay writes region 2 every frame while the Agent writes region 3 every +// second, and sharing a line would put a cross-process cache-line bounce on the +// hot path. + +using System.Runtime.InteropServices; + +namespace FrameLedger.Shared; + +/// Constants mirrored from fl_shm.h. Drift here is caught by the mirror test. +public static class ShmLayout +{ + /// + /// Bumped whenever ANY struct below changes. The Agent refuses to attach on mismatch and tells the + /// user to restart the game — the DLL lives inside a running process, so the two sides cannot be + /// assumed to update in lockstep. + /// + public const uint LayoutVersion = 2u; + + public const uint HandshakeOffset = 0x00u; + public const uint WriterOffset = 0x40u; + public const uint ControlOffset = 0x80u; + public const uint RingOffset = 0xC0u; + + /// 8192 × 64 B = 512 KiB, ≈16 s at 500 fps. + public const uint DefaultCapacity = 8192u; + + /// + /// How long a capture side keeps observing without seeing guardTicks advance: two missed + /// 30 s scans, because one late tick is noise and a tick is late whenever the machine is busy. + /// + public const uint GuardTickDeadlineMs = 65000u; + + /// Total mapping size for a given ring capacity. Mirrors FlShmSizeForCapacity. + public static long SizeForCapacity(uint capacity) => RingOffset + ((long)capacity * 64L); +} + +/// Values published in . +public enum FlStatus : uint +{ + Init = 0, + Ready = 1, + + /// Three hook faults; see 17_HOOK_ENGINE §Fault policy. + SelfDisabled = 2, + Unhooked = 3, +} + +/// Bits in , and the value of . +public enum FlApi : byte +{ + Unknown = 0, + D3D11 = 1, + D3D12 = 2, + Vulkan = 3, + OpenGL = 4, + + // No D3D9: those titles are almost entirely 32-bit and the Overlay is x64-only. +} + +public enum FlUpscaler : byte +{ + None = 0, + Dlss = 1, + DlssRr = 2, + Fsr2 = 3, + Fsr3 = 4, + Fsr4 = 5, + XeSS = 6, + Nis = 7, + + /// A hook ran and could not identify what it saw. Different from "not measured". + Unknown = 0xFF, +} + +public enum FlFgMode : byte +{ + None = 0, + DlssG = 1, + FsrFg = 2, + XeFg = 3, + + /// A hook ran and could not identify what it saw. Different from "not measured". + Unknown = 0xFF, + + // No AFMF: driver-side frame generation happens after present and is invisible to an in-process hook. +} + +/// Bits in . +[Flags] +public enum FlRtFlags : byte +{ + None = 0, + + /// Catches inline RayQuery, which DispatchRays alone misses. + AsBuild = 1 << 0, + DispatchRays = 1 << 1, + PsoAlive = 1 << 2, + + /// + /// "We did not look." When this is set the other three carry no information and the Agent must map + /// the frame to N/A, never to No — zero would otherwise be a MEASURED negative, and a present-only + /// writer with no RT hooks would assert "this title does not ray-trace" ~118 times a second. + /// + NotMeasured = 1 << 3, +} + +/// +/// Which fields a frame actually MEASURED. A bit CLEAR means "not measured": render N/A and do not +/// aggregate. The zero-defaults elsewhere in the record are affirmative negatives, and a writer that has +/// not installed the corresponding hook is not entitled to make them. +/// +[Flags] +public enum FlMeasured : byte +{ + None = 0, + Upscaler = 1 << 0, + Fg = 1 << 1, + Rt = 1 << 2, + Pso = 1 << 3, + Vram = 1 << 4, + Latency = 1 << 5, + + /// From the swapchain description, not a feature hook. + OutputRes = 1 << 6, + Hdr = 1 << 7, +} + +/// Region 1 — write-once by the Overlay at init, except . +[StructLayout(LayoutKind.Sequential, Size = 64)] +public unsafe struct FlShmHandshake +{ + public uint LayoutVersion; + public uint RecordSize; + public uint Capacity; + public uint Pid; + + /// + /// FL_BUILD_ID, from the git description of the commit the DLL was built from. NUL-terminated + /// ASCII. Read it with rather than marshalling the struct. + /// + public fixed byte BuildId[32]; + + /// Session time base, shared with sensor samples. + public ulong QpcEpoch; + + /// + /// 0 = NOT YET KNOWN, and it stays 0 until the first present, when the swapchain is known. The Agent + /// must not resolve adapter-scoped telemetry against 0 — at init the Overlay is two steps before any + /// graphics module is resolved, and a confident answer about the wrong GPU is worse than an admission. + /// + public ulong AdapterLuid; + + /// The build id as a string, stopping at the first NUL. Empty if the field is unset. + public string BuildIdString() + { + fixed (byte* p = BuildId) + { + int n = 0; + while (n < 32 && p[n] != 0) + { + n++; + } + + return System.Text.Encoding.ASCII.GetString(p, n); + } + } +} + +/// +/// Region 2 — Overlay-written; is touched every present. Plain integers, not +/// atomics: std::atomic<T> has no guaranteed layout and could not be mirrored here at all. +/// +[StructLayout(LayoutKind.Sequential, Size = 64)] +public unsafe struct FlWriterState +{ + /// Monotonic; release-stored by the writer. Read it with Volatile.Read. + public ulong WriteIndex; + + public uint Status; + public uint ApiMask; + public uint FaultCount; + + /// + /// IDXGIAdapter3 Budget, refreshed at 1 Hz. NOTE: no producer exists yet — the Overlay + /// installs no QueryVideoMemoryInfo call, so this reads 0 and 0 means "nobody wrote it". + /// + public uint VramBudgetMb; + + /// Must be zero; room for additive fields. + public fixed uint Reserved[10]; + + // There is deliberately NO droppedRecords here. The writer has no reader index and cannot know + // whether the slot it overwrites was ever consumed; the Agent computes drops from its own read index. +} + +/// Region 3 — Agent-written. +[StructLayout(LayoutKind.Sequential, Size = 64)] +public unsafe struct FlControlBlock +{ + public uint PauseRequested; + + /// Set when the guard fires mid-session. The capture side removes its hooks. + public uint UnhookRequested; + + /// In-game overlay draw toggle (v1.1). No consumer yet. + public uint OverlayEnabled; + + /// + /// COMPLETED GUARD EVALUATIONS, not a timer, and the difference is the whole point of the field. A + /// timer-driven tick attests that the Agent PROCESS is alive, which is not the question: the guard + /// loop can be dead — a swallowed exception, a blocked service query, a stall on one unreadable + /// process — while a timer keeps bumping, and the capture side would keep observing precisely + /// because the thing supervising it had stopped. Increment at exactly one site, after a verdict + /// returns. + /// + public uint GuardTicks; + + /// Must be zero. + public fixed uint Reserved[12]; +} + +/// Region 4 — the ring. Exactly 64 bytes, no implicit padding. +[StructLayout(LayoutKind.Sequential, Size = 64)] +public struct FlFrameRecord +{ + /// Present entry timestamp. + public ulong Qpc; + + public uint FrameIndex; + public uint PresentFlags; + public ushort SyncInterval; + + /// 0 = unknown. Only meaningful when is set. + public ushort RenderW; + + public ushort RenderH; + public ushort OutputW; + public ushort OutputH; + public byte Api; + public byte Upscaler; + + /// Vendor enum; 0xFF unknown. + public byte UpscalerQuality; + + public byte FgMode; + public byte RtFlags; + public byte Hdr; + + /// + /// Sum of W×H×D this frame — a VOLUME, not a call count, and 32-bit for a reason: one 3840×2160 + /// primary-ray dispatch is 8,294,400 rays, 126× a ushort's range. + /// + public uint DispatchRaysVolume; + + /// Compile COUNT, not a flag. + public ushort PsoCreatedThisFrame; + + public byte MaxTraceRecursionDepth; + + /// — which fields this frame actually measured. + public byte MeasuredMask; + + public ulong VramUsedBytes; + + /// 0 = unavailable. + public uint ReflexLatencyUs; + + /// FG feature evaluations this frame. F_app = presents − Σ fgEvaluations. + public uint FgEvaluations; + + /// + /// Seqlock counter. Monotonic per slot and NEVER reset, so a full lap of the ring always changes it — + /// otherwise a reader stalled exactly one lap would validate a different frame as unchanged. Odd + /// means a write is in progress. + /// + public uint Seq; + + /// + /// Stable per-swapchain id; 0 = unidentified, which the Agent must treat as "one undifferentiated + /// stream" and never as a valid id. Patching a vtable slot patches the SHARED class vtable, so one + /// hook sees every swapchain in the process and a title with a separate UI or video swapchain would + /// otherwise inflate Displayed FPS. + /// + public uint SwapchainId; +} diff --git a/src/native/FrameLedger.Shm/include/fl_shm.h b/src/native/FrameLedger.Shm/include/fl_shm.h index 5fe50c19..39571152 100644 --- a/src/native/FrameLedger.Shm/include/fl_shm.h +++ b/src/native/FrameLedger.Shm/include/fl_shm.h @@ -1,21 +1,20 @@ // FrameLedger shared-memory layout. // // NORMATIVE. This header and docs/07_IPC.md must agree; the static_asserts -// below are what enforce it. +// below are what enforce it. Mirrored in C# by FrameLedger.Shared's +// ShmLayout.cs, and ShmLayoutMirrorTests compares both sides against the +// offsets emitted by tools/fl-layout-dump (CLAUDE.md §Struct mirroring). // -// THE C# MIRROR DOES NOT EXIST YET. Until 2026-08-05 the line above continued -// "Mirrored in C# by FrameLedger.Shared, and a test in -// FrameLedger.Infrastructure.Tests compares both sides against the offsets -// emitted by tools/fl-layout-dump" -- present tense, in the file that defines -// the ABI, about a mirror and a test that do not exist. src/FrameLedger.Shared -// holds a .csproj and no .cs files. That is the intent (CLAUDE.md -// §Struct mirroring), tracked as 20_OPEN_QUESTIONS §R10 and scheduled in §S24; -// build.ps1 skips the gate loudly rather than pretending it runs. +// That sentence was present tense and FALSE from the day this file was written +// until 2026-08-05 -- there was no mirror and no test. It is true now, and the +// reason it is worth a note is where the false claim sat: in the normative +// header, where a reader is most entitled to trust it. build.ps1:324-329 +// enumerates the other eight sites. // -// Read the consequence, not just the correction: the static_asserts below bind -// this header to itself and to 07_IPC. NOTHING binds it to a managed reader, -// so until the mirror lands, changing a field here breaks the Agent silently -// and at runtime rather than at build time. +// SO: A FIELD CHANGED HERE MUST BE CHANGED IN ShmLayout.cs, and the build tells +// you. Add it to tools/fl-layout-dump too -- the test walks the dump's field +// list in BOTH directions, so a field this header gains and the dump does not +// report is a field the mirror silently stops checking. // // Header-only by design: the Overlay writes these structs from inside a game // process and the Agent reads them from outside, so there must be exactly one diff --git a/src/native/tools/fl-layout-dump/CMakeLists.txt b/src/native/tools/fl-layout-dump/CMakeLists.txt index 8d91ab38..7a038707 100644 --- a/src/native/tools/fl-layout-dump/CMakeLists.txt +++ b/src/native/tools/fl-layout-dump/CMakeLists.txt @@ -1,17 +1,22 @@ -# Emits the native struct offsets as JSON. +# Emits the native struct offsets as JSON. FrameLedger.Infrastructure.Tests +# (ShmLayoutMirrorTests) runs this and asserts the C# [StructLayout] mirrors +# match field for field. Struct drift between the two layers is the most +# dangerous silent bug in this architecture (CLAUDE.md §Struct mirroring) -- +# this is what catches it. # -# NOTHING CONSUMES THIS YET. The comment here used to say -# "FrameLedger.Infrastructure.Tests reads this and asserts the C# [StructLayout] -# mirrors match field for field ... this is what catches it" -- present tense, in -# a build file, about a test that does not exist. src/FrameLedger.Shared holds a -# .csproj and no .cs files, and no managed test references FlFrameRecord. -# build.ps1:324-329 enumerates the nine files that made this claim; this was one -# of the two strongest sites, because a build file reads as a wiring fact rather -# than as prose. +# True since 2026-08-05, and it was written here in the present tense long +# before it was: this was one of nine sites claiming a mechanism that did not +# exist (build.ps1:324-329), and one of the two strongest, because a build file +# reads as a wiring fact rather than as prose. # -# Struct drift between the two layers is still the most dangerous silent bug in -# this architecture (CLAUDE.md §Struct mirroring) -- which is the reason the gap -# is named here rather than left implied. 20_OPEN_QUESTIONS §R10 tracks it, -# §S24 schedules it. This tool is the intended input when it lands. +# NO add_test HERE, deliberately. fl_shm.h's static_asserts already pin every +# size and offset at compile time and layout_test.cpp says compiling IS the +# test, so a ctest over this tool's stdout would be a second hand-maintained +# copy of the same constants -- the exact thing the mirror exists to prevent. +# The consumer that changes a verdict is the managed test. +# +# FrameLedger.LayoutDump.targets stages the exe beside that test. It is NOT +# shipped: nothing in the product runs it, and an executable that dumps internal +# layout has no business in a release. add_executable(fl-layout-dump main.cpp) target_link_libraries(fl-layout-dump PRIVATE FrameLedger.Shm fl_native_flags) diff --git a/src/native/tools/fl-layout-dump/main.cpp b/src/native/tools/fl-layout-dump/main.cpp index 7db23550..9669b866 100644 --- a/src/native/tools/fl-layout-dump/main.cpp +++ b/src/native/tools/fl-layout-dump/main.cpp @@ -1,9 +1,17 @@ // Emits the native shared-memory struct layout as JSON. // -// FrameLedger.Infrastructure.Tests consumes this and asserts that the C# -// [StructLayout(LayoutKind.Sequential)] mirrors in FrameLedger.Shared match -// field for field. CLAUDE.md §Struct mirroring requires a test that checks -// sizeof AND every field offset on both sides; this is the native half. +// FrameLedger.Infrastructure.Tests consumes this (ShmLayoutMirrorTests) and +// asserts that the C# [StructLayout(LayoutKind.Sequential)] mirrors in +// FrameLedger.Shared match field for field. CLAUDE.md §Struct mirroring requires +// a test that checks sizeof AND every field offset on both sides; this is the +// native half, and as of 2026-08-05 the managed half exists -- this comment was +// present tense about a consumer that did not, which is what +// 20_OPEN_QUESTIONS §R10 recorded. +// +// EMIT EVERY FIELD, including the reserved tails. The test walks this list in +// both directions: a field here and not in C# fails, and a field in C# and not +// here fails too. A dump that quietly stops reporting a field would otherwise +// shrink what the mirror checks while every assertion still passed. // // Struct drift between C++ and C# is the most dangerous silent bug in this // architecture: nothing crashes, the Agent just reads garbage into fields that @@ -45,14 +53,20 @@ int main() { Field("status", offsetof(FlWriterState, status), sizeof(uint32_t)); Field("apiMask", offsetof(FlWriterState, apiMask), sizeof(uint32_t)); Field("faultCount", offsetof(FlWriterState, faultCount), sizeof(uint32_t)); - Field("vramBudgetMb", offsetof(FlWriterState, vramBudgetMb), sizeof(uint32_t), true); + Field("vramBudgetMb", offsetof(FlWriterState, vramBudgetMb), sizeof(uint32_t)); + // The reserved tail is emitted too. It is part of the layout -- "room for + // additive fields" is a promise about WHERE they may go -- and a mirror that + // declares it while the dump stays silent cannot be checked in both + // directions. Found by the managed test's reverse walk on 2026-08-05. + Field("reserved", offsetof(FlWriterState, reserved), sizeof(uint32_t) * 10, true); std::printf(" ] },\n"); std::printf(" \"FlControlBlock\": { \"size\": %zu, \"fields\": [\n", sizeof(FlControlBlock)); Field("pauseRequested", offsetof(FlControlBlock, pauseRequested), sizeof(uint32_t)); Field("unhookRequested", offsetof(FlControlBlock, unhookRequested), sizeof(uint32_t)); Field("overlayEnabled", offsetof(FlControlBlock, overlayEnabled), sizeof(uint32_t)); - Field("guardTicks", offsetof(FlControlBlock, guardTicks), sizeof(uint32_t), true); + Field("guardTicks", offsetof(FlControlBlock, guardTicks), sizeof(uint32_t)); + Field("reserved", offsetof(FlControlBlock, reserved), sizeof(uint32_t) * 12, true); std::printf(" ] },\n"); std::printf(" \"FlFrameRecord\": { \"size\": %zu, \"fields\": [\n", sizeof(FlFrameRecord)); diff --git a/tests/FrameLedger.Infrastructure.Tests/FrameLedger.Infrastructure.Tests.csproj b/tests/FrameLedger.Infrastructure.Tests/FrameLedger.Infrastructure.Tests.csproj index 0ceabce9..3db64a96 100644 --- a/tests/FrameLedger.Infrastructure.Tests/FrameLedger.Infrastructure.Tests.csproj +++ b/tests/FrameLedger.Infrastructure.Tests/FrameLedger.Infrastructure.Tests.csproj @@ -36,4 +36,11 @@ --> + + + diff --git a/tests/FrameLedger.Infrastructure.Tests/ShmLayoutMirrorTests.cs b/tests/FrameLedger.Infrastructure.Tests/ShmLayoutMirrorTests.cs new file mode 100644 index 00000000..2d9595e9 --- /dev/null +++ b/tests/FrameLedger.Infrastructure.Tests/ShmLayoutMirrorTests.cs @@ -0,0 +1,191 @@ +using System.Diagnostics; +using System.Runtime.CompilerServices; +using System.Runtime.InteropServices; +using System.Text.Json; +using FluentAssertions; +using FrameLedger.Shared; + +namespace FrameLedger.Infrastructure.Tests; + +/// +/// The struct-mirror gate. CLAUDE.md §Struct mirroring calls this the mechanism protecting the +/// shared-memory ABI; until 2026-08-05 nine files described it in the present tense and none of it +/// existed (20_OPEN_QUESTIONS §R10). +/// +/// The native side is tools/fl-layout-dump, which is RUN rather than transcribed. A hand-written +/// offset table here would be a second statement of the layout, and two statements of one fact drift — +/// which is the defect this test exists to catch, reintroduced inside the catcher. +/// +/// +/// Every failure to obtain the native answer is a FAILURE, never a skip. "Could not look" reading as +/// "looked and it matched" is the defect class this repository keeps recording, and a mirror test that +/// silently skips on a machine without the native build is a gate that cannot fail. +/// +/// +public sealed class ShmLayoutMirrorTests +{ + private static readonly Lazy _nativeLayout = new(RunLayoutDump); + + private static JsonElement RunLayoutDump() + { + string exe = Path.Combine(AppContext.BaseDirectory, "fl-layout-dump.exe"); + File.Exists(exe).Should().BeTrue( + "fl-layout-dump.exe must sit beside the test binary (FrameLedger.LayoutDump.targets). " + + "Run build.ps1 native first. This is a FAILURE and not a skip on purpose: without the " + + "native answer this test would assert the C# mirror against itself."); + + using var process = new Process + { + StartInfo = new ProcessStartInfo(exe) + { + RedirectStandardOutput = true, + RedirectStandardError = true, + UseShellExecute = false, + CreateNoWindow = true, + }, + }; + + process.Start().Should().BeTrue("fl-layout-dump.exe must be launchable"); + string json = process.StandardOutput.ReadToEnd(); + process.WaitForExit(30_000).Should().BeTrue("fl-layout-dump.exe must exit promptly"); + process.ExitCode.Should().Be(0, "fl-layout-dump.exe must succeed, not print a partial layout"); + json.Should().NotBeNullOrWhiteSpace("an empty dump would make every offset assertion vacuous"); + + // Parse failure throws, which is the intended outcome — a malformed dump must not read as clean. + using var document = JsonDocument.Parse(json); + return document.RootElement.Clone(); + } + + private static JsonElement StructOf(string name) + { + JsonElement structs = _nativeLayout.Value.GetProperty("structs"); + structs.TryGetProperty(name, out JsonElement element).Should().BeTrue( + $"fl-layout-dump must emit {name}; a struct that disappears from the dump would otherwise " + + "silently stop being checked"); + return element; + } + + private static void AssertMirror(string nativeName) + where T : struct + { + JsonElement native = StructOf(nativeName); + + // Size, both ways. Marshal.SizeOf is the marshalled size; Unsafe.SizeOf is what the runtime + // actually lays out and therefore what a memory-mapped read sees. They can differ, and only the + // second one is the property the reader depends on. + int nativeSize = native.GetProperty("size").GetInt32(); + nativeSize.Should().Be(64, $"{nativeName} is one cache line in fl_shm.h"); + Marshal.SizeOf().Should().Be(nativeSize, $"{typeof(T).Name} marshalled size must match {nativeName}"); + Unsafe.SizeOf().Should().Be(nativeSize, $"{typeof(T).Name} runtime size must match {nativeName}"); + + // BLITTABILITY, which offsets structurally cannot see. + // + // The repository's existing idiom for a native char[N] is + // [MarshalAs(ByValTStr, SizeConst = N)] public string (NativeAntiCheatGuard's FlGuardResult, + // where it is correct because that struct crosses a P/Invoke boundary and the marshaller runs). + // Used here it would satisfy every offset assertion above and below, and then fail to read out + // of a MemoryMappedViewAccessor — which is the one thing these types exist for. + RuntimeHelpers.IsReferenceOrContainsReferences().Should().BeFalse( + $"{typeof(T).Name} must be blittable: it is read straight out of a memory-mapped view, and a " + + "managed reference anywhere inside it makes that impossible. Offsets cannot detect this."); + + foreach (JsonElement field in native.GetProperty("fields").EnumerateArray()) + { + string nativeField = field.GetProperty("name").GetString()!; + int nativeOffset = field.GetProperty("offset").GetInt32(); + + // The C# names are PascalCase mirrors of the native camelCase ones. + string managedField = char.ToUpperInvariant(nativeField[0]) + nativeField[1..]; + typeof(T).GetField(managedField).Should().NotBeNull( + $"{typeof(T).Name} must mirror {nativeName}.{nativeField}; a field present natively and " + + "absent here means the Agent reads a value nobody mapped"); + + int managedOffset = Marshal.OffsetOf(managedField).ToInt32(); + managedOffset.Should().Be( + nativeOffset, + $"{typeof(T).Name}.{managedField} must sit at the same offset as {nativeName}.{nativeField}"); + } + } + + [Fact] + public void TheLayoutVersionMatches() + { + // The version the Agent compares against the handshake before attaching. If this drifts, the + // Agent refuses every session or accepts an incompatible one — and 11_UPDATER makes it a SemVer + // MAJOR, so it must never move by accident. + _nativeLayout.Value.GetProperty("layoutVersion").GetUInt32().Should().Be(ShmLayout.LayoutVersion); + } + + [Fact] + public void TheRegionOffsetsMatch() + { + JsonElement regions = _nativeLayout.Value.GetProperty("regions"); + regions.GetProperty("handshake").GetUInt32().Should().Be(ShmLayout.HandshakeOffset); + regions.GetProperty("writer").GetUInt32().Should().Be(ShmLayout.WriterOffset); + regions.GetProperty("control").GetUInt32().Should().Be(ShmLayout.ControlOffset); + regions.GetProperty("ring").GetUInt32().Should().Be(ShmLayout.RingOffset); + } + + [Fact] + public void TheHandshakeMirrorMatches() => AssertMirror("FlShmHandshake"); + + [Fact] + public void TheWriterStateMirrorMatches() => AssertMirror("FlWriterState"); + + [Fact] + public void TheControlBlockMirrorMatches() => AssertMirror("FlControlBlock"); + + [Fact] + public void TheFrameRecordMirrorMatches() => AssertMirror("FlFrameRecord"); + + [Fact] + public void EveryNativeFieldIsMirrored() + { + // AssertMirror walks the NATIVE field list, so a field added natively and forgotten here fails. + // This walks the other way: a field added HERE that the dump does not emit means either the + // mirror invented something or fl-layout-dump stopped reporting it, and the second is how the + // check above would quietly start testing less than it claims. + (string Native, Type Managed)[] pairs = + [ + ("FlShmHandshake", typeof(FlShmHandshake)), + ("FlWriterState", typeof(FlWriterState)), + ("FlControlBlock", typeof(FlControlBlock)), + ("FlFrameRecord", typeof(FlFrameRecord)), + ]; + + foreach ((string nativeName, Type managed) in pairs) + { + HashSet nativeFields = StructOf(nativeName) + .GetProperty("fields") + .EnumerateArray() + .Select(f => f.GetProperty("name").GetString()!) + .Select(n => char.ToUpperInvariant(n[0]) + n[1..]) + .ToHashSet(StringComparer.Ordinal); + + nativeFields.Should().NotBeEmpty($"{nativeName} must report fields, or its assertions are vacuous"); + + IEnumerable managedFields = managed + .GetFields(System.Reflection.BindingFlags.Public | System.Reflection.BindingFlags.Instance) + .Select(f => f.Name); + + foreach (string name in managedFields) + { + nativeFields.Should().Contain( + name, + $"{managed.Name}.{name} has no counterpart in {nativeName} — either it was invented " + + "here, or fl-layout-dump stopped emitting it and the offset walk silently shrank"); + } + } + } + + [Fact] + public void TheRecordSizeUsedForRingArithmeticMatches() + { + // SizeForCapacity is what the reader will use to bound the mapping. Deriving it from a hardcoded + // 64 would be a third statement of the record size. + int recordSize = StructOf("FlFrameRecord").GetProperty("size").GetInt32(); + ShmLayout.SizeForCapacity(ShmLayout.DefaultCapacity) + .Should() + .Be(ShmLayout.RingOffset + ((long)ShmLayout.DefaultCapacity * recordSize)); + } +}