xenia-rs/audit-runs/phase-b-state-equivalence/validation.md

Phase B — Validation record

All gates executed on 2026-05-13 against the patched canary (build-cross/bin/Windows/Debug/xenia_canary.exe + renamed xenia_canary_phaseB.exe) and ours (target/release/xenia-rs + renamed target/release/xenia-rs-phaseB).

Gate 1: cvar-OFF determinism

ours

• Pre-patch digest: audit-runs/phase-a-diff-harness/digest-post-patch-cvaroff.json (Phase A baseline; Phase A's gate-1 already proved byte-identity to the genuine pre-patch).
• Post-Phase-B digest: audit-runs/phase-b-state-equivalence/digest-post-phaseB-cvaroff.json.
• Both runs: check --stable-digest -n 50000000 against the same ISO.
• diff of the two files produces zero output. Byte-identical. PASS.

canary

• Phase B adds three new CONFIG DUMP lines (phase_b_snapshot_dir = "", phase_b_snapshot_and_exit = false, phase_b_dump_section_content = false). All other lines either match Phase A's accepted host-pointer/timing jitter or are unchanged.
• Smoke marker (AUDIT-DEMO-SETUP-BEGIN) still fires.
• PASS by the Phase A gate-1 method.

Gate 2: Snapshot files well-formed

ours

$ ls audit-runs/phase-b-state-equivalence/snap-001/ours/
config.json  cpu_state.json  kernel.json  manifest.json  memory.json  vfs.json

All six files parse as JSON, lead with "schema_version": 1 (or contain it in manifest), and are alphabetically sort-keys-sorted (verified by re-serializing — serde_json::Map defaults to ordered). PASS.

canary

$ ls audit-runs/phase-b-state-equivalence/snap-001/canary/
config.json  cpu_state.json  kernel.json  manifest.json  memory.json  vfs.json

Same six files, same shape. Note: canary's phase_b_snapshot.cc writes JSON via direct fmt::format rather than a JSON map, so keys are emitted in insertion order, not alphabetical order. The diff tool parses to dict before comparing, so this asymmetry has no functional impact (verified empirically — diff_state.py produces identical reports across multiple runs of either engine). It does mean the canary↔ours manifest hashes differ even when the underlying state is semantically identical; the diff tool falls back to full content comparison in that case. PASS with this caveat documented.

Gate 3: Hash-deterministic re-runs (ours)

Two runs of ours with identical args:

$ ./target/release/xenia-rs-phaseB exec --quiet \
    --phase-b-snapshot-dir <dir> --phase-b-snapshot-and-exit <iso>   # run 1
$ mv <dir>/ours <dir>/ours-a
$ ./target/release/xenia-rs-phaseB exec --quiet \
    --phase-b-snapshot-dir <dir> --phase-b-snapshot-and-exit <iso>   # run 2
$ diff -r <dir>/ours <dir>/ours-a && echo BYTE-IDENTICAL
BYTE-IDENTICAL

PASS. Re-running ours with the same args produces hash-identical snapshot files.

The first re-run attempt produced a config.json mismatch because the two runs were given different --phase-b-snapshot-dir values (whose path string is embedded in config.json::cvars.phase_b_snapshot_dir). That field is in the diff tool's SKIP_BY_FILE["config.json"] skip set; the hash difference confirmed the skip rule is well-placed. With identical inputs the snapshots are byte-equal.

Gate 4: Invariants (HARD GATE)

From report.md:

invariant	canary	ours	ok?
xex_entry_point	0x824ab748	0x824ab748	PASS
cpu_state.pc == xex_entry_point	0x824ab748 == 0x824ab748 (canary)	0x824ab748 == 0x824ab748 (ours)	PASS
image_loaded_sha256	a70993b7…	ea8d160e…	FAIL → STOP

The PC + entry-point invariants prove the snapshot point is equivalent across engines — both fired immediately before the first instruction at the same address. This is the principal Phase B equivalence claim.

The image_loaded_sha256 mismatch is the expected STOP condition per the spec. Phase B's contract is to detect and report this; investigation belongs to Phase C/D. The report.md flags it explicitly with re-run guidance.

Gate 5: Diff-tool negative test

$ cp audit-runs/phase-b-state-equivalence/snap-001/ours/kernel.json /tmp/kernel-mut.json
$ sed -i 's/"thread_id": 1/"thread_id": 999/' /tmp/kernel-mut.json
$ mkdir -p /tmp/ours-mut && cp -r audit-runs/phase-b-state-equivalence/snap-001/ours/* /tmp/ours-mut/
$ cp /tmp/kernel-mut.json /tmp/ours-mut/kernel.json
$ python3 tools/diff-state/diff_state.py \
    --canary audit-runs/phase-b-state-equivalence/snap-001/ours \
    --ours /tmp/ours-mut --out /tmp/r.md
$ echo $?
1

Report.md names two divergences:

• kernel.json <manifest> manifest-hash-mismatch — surfaces that /tmp/ours-mut/kernel.json's SHA does not match what /tmp/ours-mut/manifest.json claims.
• kernel.json objects[handle_semantic_id=…].details.thread_id value=canary=1, ours=999 — the actual mutation.

PASS.

Verified 2026-05-13 (Phase A/B verify session). Pre-fix the diff tool trusted the manifest-claimed hashes without verifying them; a tampered file with an intact manifest copy would silently report "identical" (exit 0). The fix in diff_state.py (around diff_directory) re-hashes each file, surfaces a manifest-hash-mismatch σ-structural divergence when the on-disk SHA does not match the manifest, and falls through to a full content diff.

Summary

Gate	Status
1. Cvar-OFF determinism (both engines)	PASS
2. Snapshots well-formed (both engines)	PASS
3. Hash-deterministic re-runs (ours)	PASS
4. Invariants — pc == entry_point	PASS
4. Invariants — image_loaded_sha256	FAIL → STOP (expected: this is what Phase B catalogs)
5. Diff-tool negative test	PASS

Cascade prediction at session close

• A (snapshot tool emits readable state both engines): achieved.
• B (section content hashes match): NOT achieved — image_loaded_sha256 differs. The XEX is loaded into different post-decompression states between the two engines. This is the primary finding that Phase C will investigate, not a Phase B failure.
• C (divergence catalog produced with classification): achieved — 58 divergences across all 5 files, fully classified.
• D (fix lands): N/A — out of scope for Phase B.

Notes on minor implementation choices

• Canary's PPCContext doesn't expose a pc field (the JIT dispatch loop manages PC). At the snapshot point the about-to-execute PC equals the address arg to processor()->Execute(...), which the hook receives as entry_address; we emit that value as cpu_state.pc.
• Memory snapshots emit a fixed named-region list (XEX image, main stack, PCR, TLS) rather than walking the full page table. An earlier blanket-walk approach crashed in Wine because canary's QueryRegionInfo reports COMMIT for some pages whose host-side backing is reserved-not-committed (physical heap mirrors, low system heap). The named-region list is sufficient for the diff tool's cross-engine comparison.
• The xex_header_sha256 field uses different formats in each engine (canary emits a 64-bit UserModule::hash(); ours emits a placeholder zero string). This is a known one-line shim that Phase B intentionally leaves as a divergence to demonstrate the diff tool's δ-content class.