xenia-rs/audit-runs/iterate-2M-exit-state-dump/writer-report.md

Iterate 2.M — Always-on structured exit-state dump (writer report)

Date: 2026-05-28. LOC delta: engine +143 (xenia-app main.rs +128, xenia-kernel event_log.rs +15). Tests: xenia-kernel 227/227 PASS + xenia-app 5/5 + 2 ignored + 1 ignored = ZERO regressions. Cascade: N/A — diagnostic, not investigation (tripstone #40).

Headline

STRUCTURED-EXIT-DUMP-LANDED. Every exec invocation now emits <phase-A-trace-dir>/exit-thread-state.json at exit time, regardless of --quiet. The dump contains every alive thread (tid, hw_id, idx, pc, lr, sp, priority, affinity, suspend_count, state) plus a wedge_map cross-referencing every blocked-forever wait into {waiter_tid, waiter_pc, handle, handle_type, signaler_tid_if_known, human summary}. Closes reading-error #42 — Phase-A JSONL is now never the sole source of exit-time ground truth.

Mode

Engine code change in xenia-rs/crates/:

• xenia-kernel/src/event_log.rs:7-22, 48-53, 79-89 — record the Phase-A trace path passed to init() so the dump can derive a sibling path; expose pub fn output_path() -> Option<&'static Path>. ~15 LOC net.
• xenia-app/src/main.rs:4460-4583 — new fn write_thread_state_dump( kernel: &KernelState) that builds JSON via serde_json from kernel.scheduler.slots[*].runqueue[*] + kernel.objects[h] and writes to <phase-A-dir>/exit-thread-state.json (CWD fallback when Phase-A is disabled). Always-on (no quiet gate). ~110 LOC body + 13 LOC docstring.
• xenia-app/src/main.rs:2161-2164, 4525-4527 — wire the call into both post-run paths (headless cmd_exec_inner and run_with_ui), immediately after dump_thread_diagnostic. Existing plain-text diagnostic untouched.

Verification gate

Same invocation as 2.J/2.K with no extra flags:

XENIA_CACHE_WIPE=1 timeout 600 ./target/release/xenia-rs exec \
  -n 50000000 --quiet \
  --phase-a-event-log audit-runs/iterate-2M-exit-state-dump/ours-cold.jsonl \
  "<iso>"

Run completed EXIT=0. Stderr emitted (under --quiet):

exit-thread-state: wrote 13 thread(s), 10 wedge entr(ies) to \
  audit-runs/iterate-2M-exit-state-dump/exit-thread-state.json

Gate criteria — all PASS

criterion	result
Dump emitted at <output-dir>/exit-thread-state.json without extra flags	PASS
Contains all 13 alive threads (matches 2.K's plain-text dump count)	PASS
5 blocked tids at PC 0x824ac578 present and tagged state=Blocked	PASS (tid 1, 13, 4, 5, 3)
Wedge map cross-references handle → type → signaler_tid_if_known	PASS (10 entries, all blocked-forever waits)
tid=1 → Thread(id=13) circular wait surfaced	PASS (summary: "tid=1 → Thread(id=13)")
tid=8 → Semaphore(0/2^31-1) AUDIT-069 work-sem visible	PASS (summary: "tid=8 → Semaphore(0/2147483647)")
tid=13 → Event(sig=false) signaler-unknown surfaced	PASS (signaler_tid_if_known: null)
Existing === Final State === / === Thread diagnostics === / -- Handle waiter lists -- blocks preserved under non-quiet	PASS (3 grep hits in non-quiet stdout)
Structured dump ALSO emits under non-quiet (idempotent w.r.t. quiet flag)	PASS

Bit-for-bit match against 2.K's exit-diag-full.log

Each of the 8 blocked tids in 2.K's plain-text dump appears in 2.M's wedge_map/alive_threads with identical handle ids, identical handle types, identical PC/LR/SP values, identical waiter membership. Spot-check:

2.K plain-text line	2.M JSON
tid=1 ... handles: [4808] ... pc=0x824ac578	{"tid":1, "handle":"0x000012c8", "pc":"0x824ac578"} (4808=0x12c8)
tid=13 ... handles: [4816] ... pc=0x824ac578	{"tid":13, "handle":"0x000012d0", "pc":"0x824ac578"} (4816=0x12d0)
tid=8 ... handles: [4332, 4312]	[{"handle":"0x000010ec"},{"handle":"0x000010d8"}] (4332=0x10ec, 4312=0x10d8)
tid=4 ... handles: [4136]	{"tid":4, "handle":"0x00001028"} (4136=0x1028)
tid=5 ... handles: [4836]	{"tid":5, "handle":"0x000012e4"} (4836=0x12e4)
tid=3 ... handles: [4128]	{"tid":3, "handle":"0x00001020"} (4128=0x1020)
tid=8 ... 0x10d8 Semaphore(0/2147483647)	{"type":"Semaphore","count":0,"max":2147483647}
0x12c8 Thread(id=13, exit=None)	{"type":"Thread","thread_id":13,"exited":false}

Existing-mechanism

fn dump_thread_diagnostic (main.rs:3933-4453) produces the plain-text === Thread diagnostics === + -- Handle waiter lists -- block when !quiet. 2.K's exit-diag-full.log was a manual non-quiet re-run. 2.M extends by adding a sibling structured emitter that is always on; the existing plain-text path is unchanged (still off under --quiet, still emits identically under non-quiet).

Relationship: the plain-text dump remains the human-readable walk-the-log artifact; the new JSON is the machine-readable harness input. They produce the same content from the same KernelState snapshot; choosing JSON for the new sibling matches Phase-A JSONL's schema-versioned input style and is jq-friendly.

Test results

• cargo build --release -p xenia-app — OK, 1 pre-existing unrelated warning (phase_b_snapshot.rs::walk_committed_regions dead_code).
• cargo test --release -p xenia-kernel -p xenia-app — 235 passed, 0 failed (227 lib + 5 + 2 ignored + 1 ignored + 0 doc).

Use cases

• Next iterate can jq '.wedge_map[] | select(.waiter_pc == "0x824ac578")' to get the wedge tid set in one line.
• Cross-engine diff: pair canary's analogous exit-state JSON (TBD) with ours's via tools/diff-events-style diff to identify missing-thread (canary tids 15/27/28 = sub_825070F0 family) and missing-signaler (Event handles with waiters_tid≠[] and no producer in ours's trace).
• No more 2.J-class misreadings: a Phase-A trace ending with kernel.return success at the matched-prefix tail will be immediately contradicted by exit-thread-state.json showing those same tids parked indefinitely. The reading-error #42 surface is closed at the output level.

Tripstone audit

• #28 (cross-engine tid stability): JSON keys tids by raw integer, which is acceptable for ours-only intra-run reads. For cross-engine diffs against canary, downstream tooling must continue to key on (entry_pc, ctx_ptr) — that's a 2.M+1 concern, not a 2.M one. The dump preserves enough columns (hw_id, idx, pc, lr, sp, affinity_mask) for the consumer to do its own re-keying.
• #39 (progression class): 2.M is methodology not progression. No cascade A/B/C/D claim made. Headline does NOT claim VdSwap/draw movement.
• #40 (single-keystone framing): not applicable — diagnostic, not single-cause investigation.
• #42 (Phase-A blind to blocked-forever waits): CLOSED at the output level by this iterate. Future investigations now have an always-on machine-readable wedge snapshot.

Confidence

• HIGH that the dump emits on every exec run with no extra flags (verified empirically under --quiet AND non-quiet).
• HIGH that content matches 2.K's plain-text dump bit-for-bit (every handle id, every PC, every waiter list line cross-checked).
• HIGH that existing diagnostic mechanism is unbroken (plain-text still emits 3 sections under non-quiet, JSON also emits).
• HIGH that ZERO test regressions (235/235 pass).

Artifacts

Under xenia-rs/audit-runs/iterate-2M-exit-state-dump/:

• ours-cold.jsonl (Phase-A trace, 121,569 events, ~28MB, bit-equal to 2.J/2.K)
• ours-cold.stdout.log (empty — quiet mode preserved)
• ours-cold.stderr.log (single line: dump emission notice)
• exit-thread-state.json (the new artifact, 9651 bytes, 13 threads + 10 wedge entries)
• ours-cold-nonquiet.stdout.log / .stderr.log (regression check: existing plain-text diagnostic preserved)
• writer-report.md (this file)

Patch:

• xenia-rs/crates/xenia-kernel/src/event_log.rs (path tracker + accessor)
• xenia-rs/crates/xenia-app/src/main.rs (dump function + 2 call sites)

Next iterate enabler

exit-thread-state.json is now a stable input for:

1. Canary parity: add the analogous emitter to canary's exit path so cross-engine wedge-map diffs become trivial.
2. Per-handle signaler hunt: for each wedge handle_type=Event, signaler_tid_if_known=null, walk Phase-A trace for canary's handle-equivalent (semantic_id) signal source — directly identifies which canary thread/path is missing in ours.
3. Regression alarm: a CI step can refuse to merge if len(wedge_map) > N for the boot-replay scenario, preventing silent re-wedges.