docs(render): S3 chunk 1 contract — transcript kinds, fixtures, print-only emitter

Runs after chunk 3 (LC/SC need per-cell terrain). One print-only flag,
the FW0 parser extended for the OH kinds, the five captures as fixtures
in the existing still-frame conformance harness, and an offline signature
diff as the transcript gate. No validator, no canonical format.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
Erik 2026-09-03 07:49:56 +02:00
parent 542b049b15
commit bbe41d5993

View file

@ -592,3 +592,82 @@ DELETE (no retail counterpart):
their read sites removed together (the test enforces both directions);
- the register: no row is added (every deletion removes an acdream-only
rule); any KEEP item still lacking a CPU/GPU equivalence pin gets one.
## 11. Chunk 1 contract — transcript kinds, fixtures, and the print-only emitter (lead, 2026-09-03; runs AFTER chunk 3, because `LC`/`SC` only exist once terrain is per cell)
### 11.1 What exists (verified in the tree at `542b049b`)
- The FW0 test-side parser `tests/AcDream.App.Tests/Rendering/Walk/WalkOracleTrace.cs`
parses `F`, `P`, `LS`, `BLD`, `DI`, `DC` and drops the truncated detach
frame; `WalkTraceReplay.cs` rebuilds the camera from the `P` pose (retail
projection globals, +Y forward) and drives `RetailFrameWalk` over
DAT-adapter world data; `WalkTraceConformanceTests` (InstalledDat lane)
already proves the FW0 still fixtures' first frames position-for-position
and `WalkOracleTraceTests` pins per-fixture facts. `Load(name)` is rooted
at `docs/research/2026-08-30-fw-walk-oracle/`.
- The five OH captures are committed under
`docs/research/2026-09-01-overhaul/oh-capture/` (README there): per pose a
walk log (adds `LC`/`SC`/`EC`/`OC` to the FW0 kinds), a parts log (`PD`,
`DM`), and an alpha-depth log (`AM`, `FL`, `PM`, `PC`); line formats are in
`tools/walk-oracle/oh/*.cdb.template`. Same `F`/`P` framing; same detach
rule.
### 11.2 Production behavior change (the one allowed piece of evidence infrastructure)
- **B1 — one print-only flag, `ACDREAM_DUMP_WALK_TRANSCRIPT=1`**, read once
into `RuntimeOptions` (rule 4) and owned by `RenderingDiagnostics` (rule
5), with its `docs/launch-options.md` row in the same commit
(`LaunchOptionsDocumentationTests` enforces both directions). When set,
the production walk prints, to the existing diagnostics sink, exactly the
OH line kinds at the points retail's breakpoints sit: `F n` + `P …` at
the frame root (`SmartBox::RenderNormalMode` @0x00453aa0 — the camera
cell, origin and quaternion in retail's storage order), `LS` at the
landscape turn, `LC <cell>` / `SC <cell>` per land cell (chunk 3's events,
with the LOD id `x*8+y+1`), `BLD <cell>` at the building turn, `DI <cell>`
at DrawInside, `DC pv=<0|1> ov=<n> n=<k>: <cells…>` at every DrawCells
(pv 0 = interior pview, 1 = outdoor pview — a stable stand-in for
retail's pointer, which the parser already ignores), `EC <cell>` per shell
draw, `OC <cell>` per object-list turn. NOTHING else changes: no admission,
depth state, or draw order may depend on the flag (the print sits AFTER
each decision, never inside it).
- **B2 — parser extension.** `WalkOracleTrace` learns `LC`, `SC`, `EC`, `OC`
as event kinds and gains `Load(root, name)` (or a fixture-set enum) so the
OH captures load from their own directory; the parts and alpha-depth
kinds get their own small readers (`PD`/`DM` → gfx id, force, bound, cell;
`AM`/`FL`/`PM`/`PC` per the template's documented fields) — read-only
records, no validator, no canonical JSONL, no new tool
([[feedback-evidence-infrastructure-sink]]).
- **B3 — fixtures + pins.** The five walk captures join
`WalkOracleTraceTests.AllFixtures` (parse + complete-frame pin) and the
four kit poses join `WalkTraceConformanceTests`' still-fixture theory at
the DI/DC/BLD/LS level (first complete frame, position-for-position, the
SAME harness as FW0 — the cathedral-arrival capture's root is `f4180108`,
not FW0's `f4180106`, so it is a NEW pose row, not a replacement). The
`LC`/`SC` sequences of both cathedral poses become the chunk-3 order pin's
fixture (§9 T1) if chunk 3 landed with a hand-extracted one. The parts
and alpha-depth logs are imported and parsed (B2) but pinned only where a
later chunk/S4 names a consumer — no speculative assertions.
- **B4 — the automated transcript gate (§6).** A Release run with the flag at
the four kit poses (session-config login + `/teleloc` from the self-gate
kit) produces acdream transcripts; the test-side comparison is the
existing signature diff (`WalkTraceReplayContext.Signature`) extended to
the new kinds, run offline over the two files — a FACT-level report per
pose (first divergent event and position), consumed by the S3 review and
G3. It is a test-side script, not a client subsystem.
### 11.3 Tests
- T1: the flag off → zero output and zero allocation on the walk path
(the existing `WalkFrameDriver` allocation pins stay green).
- T2: the flag on, one synthetic interior frame → the printed lines parse
with the extended `WalkOracleTrace` into the same events the driver
recorded (emitter/parser round trip).
- T3: `AllFixtures` + the still-fixture theory rows for the four OH kit
poses (InstalledDat lane); the two cathedral `LC`/`SC` order pins.
- T4: `LaunchOptionsDocumentationTests` green with the one new row.
### 11.4 Out of scope
Any validator, canonical format, or dashboard; any behavior change; any
second flag. If the gate report shows a divergence, that is a finding for
the S3 review round, fixed in the owning chunk's follow-up — not in chunk 1.