mirror of
https://github.com/Druthulu/BFM-decomp
synced 2026-10-03 00:05:11 -04:00
Drew T
0c29c9e16b
- decomp-architect/corpus/record/: the how-to (13), decision-log, accelerators, retrospective, story, wave-playbook, effort-map, gen3-standards, gen3-handoff, DIGEST and every PhaseEnd (34) verbatim behind an authored front page (what each is, how to read it, what is NOT there — the phase logs, R19 — and that the mining pass is their distillation); tool_census: RECORD_SOURCES + record_dest + the third corpus in plan/write/check (358 copies + 28 pointers, --check OK); kit_lint exempts corpus/record; SETUP Step 6 gains 2c docs/inherited-record.md (+ the verify line; expected-manifest +1); ops-setup/README/tree/methodology/ wiki page/Home/Tools page/README bullet/SETUP row: "two dictionaries" → three - tools/kit_coverage.py (+ config/kit_coverage_map.tsv): derives R1..R83 from DIGEST §3 (asserted contiguous) and the 58 accelerator entries (headings + numbered items), asserts each is cited by a provenance line of the registry seed / the kernels or dispositioned (G / DK / FOLDED:G / ENV / PA / SEED: / KIT: / RECORD / COOKBOOK / NOT-PORTABLE; unknown ids refused); first run: 26 uncited rules + 21 uncited entries → DK-66 (a ledger's tie-break, a checker's widening and a blanket commit are part of the instrument — R70/R80/R52), DK-67 (the ignore file's directory-form wall — S91 (1)), DK-68 (a summarised signal is a claim, not ground truth — R14/R66) in a new kernels section 8 (the museum is 9; "In all" 68) + 41 dispositions (15 PA, 3 ENV, folds into G6/G18/G38/G66/DK-12/19/20/22/25/26/31/35/44/45/46/57/61, 1 KIT template, 1 COOKBOOK); now 0 UNCOVERED on both populations; wired into tools-health after tool_census --check; SETUP row + dictionary row - verify: tool_census --check OK; kit_coverage OK (rules 57 cited + 26 dispositioned / 83; accelerators 41 + 15 / 58); kit_lint OK; doc_links --strict OK; wiki_render --selftest 32 pages / 0 unlisted
69 lines
5.0 KiB
Markdown
69 lines
5.0 KiB
Markdown
<!-- decomp-architect: the rows appended to docs/ops-setup.md at Step 8, inside a marked section. The generation-time
|
|
placeholders are written as literal TODO(phase-N) lines when their phase has not happened yet, so the leftover
|
|
placeholder audit stays clean; the phase that produces the value replaces the TODO. -->
|
|
|
|
## Decomp environment (decomp-architect, Phase 0.5 — installed {{INSTALL_DATE}})
|
|
|
|
### Version pins (decomp)
|
|
|
|
| Component | Version | Notes / why pinned |
|
|
|---|---|---|
|
|
| The pinned toolchain triple (compiler → assembler shim → binutils, with flags) | {{TOOLCHAIN_TRIPLE}} | TODO(phase-4): pinned by fingerprint evidence down the candidate ladder; the assembler's compatibility version is always passed explicitly — a shim's default is not "latest" |
|
|
| Candidate compiler family (from the SDK evidence) | {{COMPILER_FAMILY}} | the candidate set the pin phase runs down; never a sibling project's triple |
|
|
| The splitter / disassembler and its config | TODO(phase-3) | version pinned in the bootstrap script |
|
|
| The disassembler database and its agent server | TODO(phase-2) | the static oracle; the database is tracked as a TEXT export with a rebuild script |
|
|
| The emulator and its scripting bridge | TODO(phase-2) | the runtime oracle |
|
|
|
|
### The game and the medium
|
|
|
|
- **Title / platform / serial:** {{GAME_TITLE}} · {{PLATFORM}} · {{GAME_SERIAL}}
|
|
- **The main executable on the medium:** `{{TARGET_BINARY}}` (its hash is the first per-binary contract, Phase 3)
|
|
- **Container layout:** {{CONTAINER_LAYOUT}}
|
|
- **SDK / compiler-era evidence:** {{SDK_EVIDENCE}}
|
|
- **The dump (machine-local, never committed):** `{{DUMP_PATH}}` — copied once onto a fast local filesystem under `disks/`
|
|
(ignored); the extractor reads it, nothing builds against it.
|
|
|
|
### Build / extract / verify (decomp)
|
|
|
|
```
|
|
# extract the medium and verify against the committed manifest
|
|
{{EXTRACT_CMD}}
|
|
# the clean fleet verification — every binary from clean → extract → build, exit code read
|
|
{{FLEET_CHECK_CMD}}
|
|
```
|
|
|
|
- **The gate:** a binary is green only when its hash check inside `make build` passes; a match is verified from a CLEAN
|
|
rebuild, never incremental; the executable is gated only by a clean rebuild; a build is verified by its exit code.
|
|
|
|
### The oracles (decomp)
|
|
|
|
- **Disassembler MCP:** {{DISASSEMBLER_MCP}} — verify with one cheap call before any reverse-engineering task; after a
|
|
restart or a program switch, pause and ask the developer to reconnect the client.
|
|
- **Emulator bridge:** {{EMULATOR_BRIDGE}} — a live-memory finding is verified only with three or more consistent datapoints
|
|
or a controlled before/after diff.
|
|
|
|
### Git posture (decomp)
|
|
|
|
- **Visibility at day one:** {{PUBLIC_OR_PRIVATE}} — the ROM firewall applies either way (`config/firewall.txt`,
|
|
`tools/audit_public.py`, the CI workflow). If ever private, a later flip is gated on the host's object store, never on
|
|
a clean tree.
|
|
- Never `git clean -x` in this tree (the game-derived data is ignored-but-present); the backup of the reverse-engineering
|
|
work is the text export + the checksum files + a private archive repository, not the ignored directories.
|
|
|
|
### Tooling inventory (decomp)
|
|
|
|
| Tool | Location | Purpose |
|
|
|---|---|---|
|
|
| `tools/audit_public.py` | `tools/` | the ROM audit (purge paths, the derived hash set, the size cap, the pasted-disassembly check); the first-push gate and the CI job; its sources are `config/firewall.txt` |
|
|
| `make format` | `Makefile` | clang-format over `src/` with the tracked `.clang-format` (the community style) |
|
|
| TODO(phase-1): the extractor, the manifest | `tools/` | — |
|
|
|
|
### The three dictionaries (the kit master copy — consulted, never copied into this repository)
|
|
|
|
| Corpus | Where | How to use it |
|
|
|---|---|---|
|
|
| The tool dictionary — the source project's tools, verbatim, by ladder phase, keyed by the need each answers | `<kit master copy>/decomp-architect/corpus/tools/INDEX.md` (installed summary: `docs/tools-manifest.md`) | before designing or debugging a tool, grep the index by the need; the matching file is the jumping-off point, its Adapt column the list of what differs here |
|
|
| The inherited knowledge base — the cookbook, its symptom index and the codegen map, verbatim | `<kit master copy>/decomp-architect/corpus/cookbook/` (installed front page: `docs/knowledge-corpus.md`) | same compiler family: look the symptom up, apply, re-prove on your bytes; another compiler: read the same pass in your compiler's source and find your own lever |
|
|
| The inherited record — the source project's distilled records (the how-to, the decision log, the accelerators, the retrospective, the story, the playbook, the effort doctrine, the readability charter) and every phase-end, verbatim | `<kit master copy>/decomp-architect/corpus/record/` (installed front page: `docs/inherited-record.md`) | when a rule or kernel cites a source, open it here; the digest first, a phase-end on demand, the how-to in order |
|
|
| Kit master copy location | TODO(phase-0.5): the absolute path where `decomp-architect/` is kept after the package folder is deleted from this repository | — |
|