Files
frameledger/FrameLedger.LayoutDump.targets
poli0981andClaude Opus 5 bff0f6a81c feat(ipc): the C# mirror exists, and the gate that guards it stops being a Test-Path (#47)
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>
2026-08-05 13:02:47 +07:00

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>