CLAUDE.md calls the struct mirror the mechanism protecting the shared-memory ABI. NINE files described it in the present tense and none of it existed (20_OPEN_QUESTIONS R10): src/FrameLedger.Shared held a .csproj and no .cs files. The ring, the handshake and a real writer landed in #40-#44, so there is now a live ABI with nothing binding it to a managed reader -- which is the state the gate exists to prevent, not the one that made it unnecessary. ShmLayout.cs mirrors all four structs and their enums. It is driven by tools/fl-layout-dump's JSON rather than a transcribed table: a hand-written offset table in C# is a SECOND statement of the layout, and two statements of one fact drift, which is the defect the mirror exists to catch reintroduced inside the catcher. Same choice rules-validate.ps1 makes for the rules bounds. THE TEST ASSERTS BLITTABILITY, AND THAT IS NOT DECORATION. MEASURED: swap the `fixed byte BuildId[32]` for [MarshalAs(ByValTStr, SizeConst = 32)] public string -- the idiom this repository ALREADY USES, correctly, on NativeAntiCheatGuard's P/Invoke struct -- and Marshal.SizeOf stays 64 while every single Marshal.OffsetOf assertion still passes. Unsafe.SizeOf collapses to 40, because the string is an 8-byte reference rather than 32 inline bytes. That mirror looks correct by every obvious check and cannot be read out of a MemoryMappedViewAccessor, which is the one thing it exists for. Offsets structurally cannot see this, so RuntimeHelpers.IsReferenceOrContainsReferences and Unsafe.SizeOf are asserted alongside them. BOTH DIRECTIONS. The offset walk iterates the NATIVE field list, so a field added natively and forgotten here fails. A second test walks the other way, and it caught something on its first run: fl-layout-dump was not emitting the `reserved` tails, so the C# mirror declared members the dump could not confirm. Fixed in the dump rather than excluded from the check -- a dump that quietly stops reporting a field would otherwise shrink what the mirror verifies while every assertion still passed. THE GATE WAS THE BIGGER FINDING. build.ps1's struct-mirror step was `Test-Path src/FrameLedger.Shared/ShmLayout.cs` and then printed "covered by dotnet test". It never looked for the test. So creating an EMPTY ShmLayout.cs would have turned an honest 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 mechanism CLAUDE.md calls the protection for the shm ABI. It now reads the trx from the run that just happened (--logger trx added to the test step) and requires the named class to have EXECUTED and passed. dotnet test makes a regression red; this makes DELETING the regression test red, which is a different failure and the one a Test-Path can never see. THREE CANARIES, EACH PROVEN RED, PLUS RECOVERY: RED offsets swap OutputW/OutputH -> "Expected 22 ... but found 24" RED blittability ByValTStr string -> "Expected Unsafe.SizeOf to be 64 ... found 40" RED the GATE rename the test class away The third is the one that matters and it had to be built carefully: with the class renamed, the build succeeds, dotnet format is clean, and ALL 132 MANAGED TESTS PASS -- all 8 mirror assertions included, just under another name. The only thing that fails is the gate, at build.ps1:358. Restored: PASSED WITH 1 SKIPPED GATE(S), 8 mirror assertions executed. The skip count drops from 2 to 1. MY CANARY HARNESS WAS BROKEN TWICE BEFORE IT PROVED ANYTHING, which is the fourth and fifth time on this project. First the renamed class tripped MA0048 (file name must match type name) and the run died at BUILD, never reaching the gate. Then `sed` rewrote the file with LF endings and the run died at dotnet format, also never reaching the gate. Both printed a failure, and a failure that stops before the gate proves nothing about the gate. The restore stamps LastWriteTime for the same family of reason. Analyzer suppressions are scoped to FrameLedger.Shared and each is justified in the csproj: obeying CA1028 (widen the enum), CA1711 (rename FlRtFlags), CA1051 (properties instead of fields) or CA1815 (implement Equals) would BREAK the mirror or make it unaddressable by Marshal.OffsetOf. MA0048 and CA1716 are scoped-down style rules. AnalysisLevel is not turned down. STILL OPEN, and marked half-closed rather than closed: S23-1. The mirror can now READ buildId out of the handshake, but the Agent 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 that half. The eight remaining present-tense claims are flipped in the same commit -- CLAUDE.md, fl_shm.h, the Shared csproj, 12_BUILD (which contradicted itself across 86 lines), 14_TESTING, fl-layout-dump's CMakeLists and main.cpp, and build.ps1's own explanatory comment. build.ps1 check: PASSED WITH 1 SKIPPED GATE(S) in 54s, 15/15 ctests, 132 managed tests. The one remaining skip is resx-audit. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
53 lines
2.4 KiB
XML
53 lines
2.4 KiB
XML
<Project>
|
|
|
|
<!--
|
|
Ships fl-layout-dump.exe beside the importing project's output.
|
|
|
|
It emits the native shared-memory struct layout as JSON, and
|
|
ShmLayoutMirrorTests consumes it to assert that the C# mirrors in
|
|
FrameLedger.Shared match fl_shm.h field for field. That is the mechanism
|
|
CLAUDE.md §Struct mirroring calls the protection for the shm ABI, and until
|
|
2026-08-05 it did not exist: nine files described it in the present tense
|
|
while src/FrameLedger.Shared held only a .csproj.
|
|
|
|
WHY THE DUMP AND NOT A TABLE IN THE TEST. A hand-written offset table in C#
|
|
is a SECOND statement of the layout, and two statements of one fact drift —
|
|
which is the defect the whole mirror exists to catch, reintroduced in the
|
|
thing catching it. tools/rules-validate.ps1 makes the same choice for the
|
|
rules bounds: extract the constants from the header, and FAIL rather than
|
|
skip if they cannot be read.
|
|
|
|
Imported by exactly one project: FrameLedger.Infrastructure.Tests.
|
|
|
|
Unlike FrameLedger.Guard.targets this stages a TOOL, not a shipped artifact.
|
|
It never reaches out/app: nothing in the product runs it, and an executable
|
|
that dumps internal layout has no business in a release.
|
|
-->
|
|
<PropertyGroup>
|
|
<FlLayoutDumpDir>$(MSBuildThisFileDirectory)build\native\x64-release\tools\fl-layout-dump\</FlLayoutDumpDir>
|
|
</PropertyGroup>
|
|
|
|
<ItemGroup>
|
|
<None Include="$(FlLayoutDumpDir)fl-layout-dump.exe" Condition="Exists('$(FlLayoutDumpDir)fl-layout-dump.exe')">
|
|
<Link>fl-layout-dump.exe</Link>
|
|
<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
|
|
</None>
|
|
</ItemGroup>
|
|
|
|
<!--
|
|
Warn at BUILD time, fail at TEST time. build.ps1 runs the native build first,
|
|
so by the time this evaluates the exe exists; a hard error here would make
|
|
`dotnet build` on a fresh clone fail for a reason unrelated to managed code.
|
|
|
|
The test itself does NOT extend that courtesy: a mirror test that cannot find
|
|
its native input reports FAILED, never "skipped", because "could not look"
|
|
reading as "looked and it matched" is exactly the defect class this
|
|
repository keeps recording.
|
|
-->
|
|
<Target Name="FlWarnOnMissingLayoutDump" AfterTargets="Build"
|
|
Condition="!Exists('$(FlLayoutDumpDir)fl-layout-dump.exe')">
|
|
<Warning Text="fl-layout-dump.exe was not found at $(FlLayoutDumpDir). Run build.ps1 native first; ShmLayoutMirrorTests will fail without it." />
|
|
</Target>
|
|
|
|
</Project>
|