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

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.