docs: handoff report for continuing on another machine

Snapshot of repo layout, branch map, gitignore policy for the heavy
local artifacts, and the iterate-2.BC investigation state (next steps
2.BD handle disambiguation -> 2.BE host-driven ISR delivery).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

HANDOFF.md

@@ -0,0 +1,119 @@
+# Handoff — Project Sylpheed RE / xenia-rs
+
+_Generated 2026-06-05 to continue work on another machine._
+
+## TL;DR
+
+Reverse-engineering **Project Sylpheed — Arc of Deception** boot under a Rust
+Xbox 360 emulator (`xenia-rs`), using **Xenia Canary** as the reference
+("canary") oracle. The game boots but **wedges after ~2–6 frames**: a render /
+VSync-event producer stops firing post-boot, so guest threads block forever.
+Investigation is at **iterate 2.BC**; next step is **2.BD (handle
+disambiguation)**, then **2.BE (architecture fix)**.
+
+## Repo / machine layout
+
+Workspace root: `/home/fabi/RE - Project Sylpheed/` (NOT a git repo itself).
+
+| Dir | Git remote | Purpose |
+|-----|-----------|---------|
+| `xenia-rs/` | `git.mc02.dev/fabi/xenia-rs.git` | **Main project** — the Rust emulator + all RE work |
+| `/home/fabi/Xenia-Canary/` | `git.mc02.dev/fabi/Xenia-Canary.git` | Reference Canary build (branch `xenia-rs`) |
+| `xenia-canary/` | `github.com/xenia-canary/xenia-canary` | Upstream canary checkout (incl. `third_party/snappy` submodule) |
+| `xenia-canary/third_party/snappy` | `git.mc02.dev/fabi/Snappy.git` (fork) | snappy + cross-build patch (see below) |
+| `xenia/` | upstream xenia | Reference only |
+| `sylpheed-reborn/` | — | **DEAD — ignore** |
+
+The big game asset (`*.iso`, 7.8 GB) and `*.pe`/`*.xex.json` live at workspace
+root and are **not** in git.
+
+### What is and isn't in git (xenia-rs)
+
+`.gitignore` now excludes the heavy, regenerable local artifacts so the repo
+stays portable:
+
+- **Committed:** all source, plus `audit-runs/**` analysis **notes**
+  (`.md`/`.txt`/small `.json` digests, ~6 MB).
+- **Ignored:** `audit-runs/**` raw traces (`.jsonl`, `.jsonl.gz`, `.gz`, `.csv`,
+  `.stdout`, `.stderr`, `.log` — **~146 GB**), `.claude/` agent worktrees
+  (~66 GB), `*.bin` dumps, `exit-thread-state.json`, `*.bak`.
+
+To regenerate traces on the new machine, re-run the emulator/diff harnesses
+(see `docs/` and the per-iterate `audit-runs/iterate-*/` note files).
+
+## Branch map (xenia-rs, all pushed)
+
+- `master` — golden baseline (`sylpheed_n50m` golden, post-AUDIT-054).
+- `chore/portable-snapshot` — **active line**; HEAD `ef93a4f` carries the
+  dormant parity fixes (`nt_create_event` polarity, MMIO VSync hardcode) +
+  iterate notes.
+- `iterate-2AT-deref`, `iterate-2AU-xaudio`, `iterate-2AZ-vsync` — throwaway
+  probe instrumentation, preserved as-is (inert per findings; do not merge
+  blindly).
+- `worktree-agent-a0848e51cc0d72503` — stale worktree ref (no unique work).
+
+## Where the investigation stands (iterate 2.BC)
+
+The authoritative running log is the persistent memory at
+`~/.claude/projects/-home-fabi-RE---Project-Sylpheed/memory/` (`MEMORY.md`
+index + topic files). Key state:
+
+- **The wedge is a genuine producer bug, independent of cadence mode.** Running
+  the game `--parallel` (wall-clock 60 Hz VSync) also wedges after ~2 frames
+  (iterate 2.BB), so it is **not** a lockstep artifact. Cadence-clock direction
+  is a dead end.
+- **Canary's frame pacing = a host "GPU Frame limiter" thread** (canary tid=2,
+  `graphics_system.cc:146`) that calls `NtSetEvent` ~4660× at 60 Hz and runs
+  the guest VSync ISR **synchronously on the host thread**
+  (`MarkVblank → DispatchInterruptCallback → EmulateCPInterruptDPC →
+  processor_->Execute`), scheduler-independent (iterate 2.BA).
+- **Ours has no host frame-limiter.** It injects the ISR onto a guest *victim*
+  thread (`try_inject_graphics_interrupt`, `crates/xenia-app/src/main.rs`
+  ~3729). Once the guest blocks/idles after boot, ISR delivery stops — ours
+  fires the signal path ~96× early-boot then **stops**.
+- **`opt_callback` signal path IS wired in ours** (iterate 2.BC, falsifies the
+  earlier 2.AT "NULL delegate" claim): `sub_822F2248` body = 3 parts; part C
+  `@0x822F22CC` calls `bl 0x822F13B0` (singleton `0x828f3844`) →
+  `NtSetEvent(ev0)` via `0x824AA2F0`. Runtime: this reaches `NtSetEvent` 96× on
+  **handle 0x108c** then stops. So divergence = **cadence/delivery
+  architecture**, not a missing delegate.
+
+### Open question to resolve FIRST — iterate 2.BD (~0 LOC)
+
+**Handle disambiguation.** `opt_callback` signals **0x108c**, but `tid=1` was
+recorded wedging on **0x10e8**. Are these the same event or different?
+- If `tid=1`'s wait is really 0x108c (0x10e8 a mislabel) → the cadence/delivery
+  fix unwedges tid=1.
+- If 0x10e8 is a separate event → it needs its own producer.
+
+Map who-waits / who-signals for `0x108c / 0x1090 / 0x10e8 / 0x1004` in **both**
+ours and canary before writing any fix. (`0x1004` = tid=12 DPC work-queue wake,
+also dead post-boot.)
+
+### Then iterate 2.BE — architecture fix (~20–60 LOC, MEDIUM)
+
+Replace victim-thread ISR injection with **host-driven synchronous ISR
+delivery** mirroring canary's `EmulateCPInterruptDPC` frame-limiter, so VSync
+keeps firing after the guest blocks. Fix surface:
+`crates/xenia-kernel/src/interrupts.rs` + `crates/xenia-app/src/main.rs`.
+This is why the 2.AZ clock-swap was inert — the gap is *delivery
+architecture*, not the clock.
+
+## Workflow notes
+
+- **The user drives dispatch cadence.** After a research iterate completes,
+  sync memory + report concisely, then **pause for explicit go** — do not
+  auto-dispatch the next sub-agent.
+- Methodology rule earned the hard way (#44/#46): before claiming "X never
+  fires / signal missing", trace the **whole** function body at runtime
+  (`--lr-trace`) and verify the reference engine actually has it non-null —
+  an empty slot is only a bug if canary's is populated.
+
+## Verify the checkout on the new machine
+
+```sh
+cd xenia-rs
+git checkout chore/portable-snapshot
+cargo test          # 300 + 230 + 149 + 11 suites expected green
+# determinism baseline: sylpheed_n50m golden should be bit-identical to master
+```