Merge remote-tracking branch 'origin/main' into auto/no-disc-and-menu-captures

docker/decoder/sylph-decoder

@@ -110,6 +110,21 @@ docker_args() {
     # is the most expensive kind of missing mount.
     -v "${SYLPH_DISC:-$PROJECT/sylph_extract}:/disc:ro"
     -e "SYLPHEED_DISC=/disc"
+    # ── the static-analysis corpus ──
+    # The xenia-rs era's disassembly database and the flat VA image. Neither is
+    # reproducible from anything in this repository yet -- the four scripts that
+    # READ sylpheed.db have no producer here -- so they are mounted read-only
+    # from the host as reference material.
+    #
+    # The `.pe` matters most: it is the decompressed image as a flat VA dump
+    # (file offset = VA - 0x82000000), which removes the need to boot the
+    # emulator and scrape /dev/shm to get at it. An earlier belief that this
+    # file was STALE was tested and refuted -- it is current.
+    -v "${SYLPH_XENIA_RS:-$PROJECT/xenia-rs}:/xenia-rs:ro"
+    -v "${SYLPH_PE:-$PROJECT/Project Sylpheed - Arc of Deception (USA, Europe) (En,Ja).pe}:/image/sylpheed.pe:ro"
+    -e "SYLPHEED_DB=/xenia-rs/sylpheed.db"
+    -e "SYLPHEED_PE=/image/sylpheed.pe"
+    -e "SYLPHEED_IMAGE_BASE=0x82000000"
     # The shared exchange: transient files with provenance, outside git history.
     -v "sylpheed-exchange:/exchange"
     -e "PROJECT_DIR=/work"

docs/agents/CONTAINER-NOTES.md

@@ -60,3 +60,46 @@ python3 tools/re-capture/gmem.py find hex:820af844 400
 State what you measured, what you assumed, and what you could not settle. If a
 result is withdrawn, say so and keep the reasoning — that is the corpus's whole
 convention, and the reason its numbers can be trusted.
+
+## The static-analysis corpus — mounted, not reproducible
+
+Two things arrive read-only from the host because **nothing in this repository
+can produce them yet**:
+
+| path | what | env |
+|---|---|---|
+| `/xenia-rs/sylpheed.db` | the disassembly database, 586 MB | `SYLPHEED_DB` |
+| `/image/sylpheed.pe` | the decompressed image, flat VA dump | `SYLPHEED_PE` |
+
+**The `.pe` is a flat VA dump**: file offset = `VA - 0x82000000`
+(`SYLPHEED_IMAGE_BASE`). So reading `0x820A1630` is `seek(0xA1630)` — no XEX
+decrypt, no LZX, and **no booted emulator**. An earlier belief that this file was
+stale was tested and **refuted**; it is current.
+
+Recovering the image by dumping `/dev/shm/xenia_memory_*` also works and
+self-validates, but it needs a running emulator — a poor dependency for
+something the whole static corpus rests on. Use the file.
+
+The database is far richer than the four scripts that read it use:
+
+```
+functions                     25 481   address, name, end_address, frame_size,
+                                       saved_gprs, is_leaf, pdata_validated, has_eh
+classes                          851   name, vtable_address, rtti_present, base_classes_json
+imports                          398   library, ordinal, name, address
+eh_funcinfo / eh_try_blocks    2 588 / 315
+function_pointer_arrays        1 526   + 8 568 entries
+indirect_dispatch_candidates 1 827 297  dispatch_pc, vtable_address, method_address
+```
+
+`instructions.raw` is an **INT, not hex** — a trap this corpus has already paid
+for. Query with `python3 -c 'import duckdb'`; it is not SQLite.
+
+### These mounts are reference material, not a deliverable
+
+They are read-only and they come from outside the repository, which means a
+fresh checkout on another machine has neither. **Reimplementing the producer —
+XEX decrypt + LZX decompress, and the disassembly-to-database step — belongs in
+`crates/sylpheed-formats`.** Until then, every static finding rests on an
+artefact this project cannot rebuild, and that is a real gap in the corpus rather
+than a convenience.