KB: document the #60 census/re-export aftermath across the context system

- CLAUDE.md front + project-overview: census/re-export DONE (93.5% coverage,
  41KB dark), polish list refreshed; the citation-policy warning rides the
  front matter so it is unmissable.
- locomotion §CROUCH addendum: the re-export CONFIRMS the hand transcription
  field-for-field, documents that Ghidra renders members as int-ARRAY indices
  ([0xfe] == byte 0x3f8 -- why offset-string greps of the export miss them),
  and records the AIRBORNE AUTO-RISE branch the raw pass missed (+ its fix).
- decomp-reference §7: citation policy (@ADDR, never part/LINE -- old
  citations resolve only against archive_2025export/), the array-index
  gotcha, and the full re-export toolchain (ghidra_reexport.sh incl. the 8.3
  short-path requirement, gapcensus, gapdiff).
- open-questions: the leads the re-export produced -- @0x4c0904 is the MASTER
  BTPlayer Performance (team-by-name resolve + EndMission post + score
  heartbeat; our @0x4c083c attribution needs a re-check) and the ~9KB
  l4splr|btmssn cluster that stayed dark THROUGH the fill (no call/data
  reference reaches it -- jump-table entry suspected).
- glossary: dark-region.
Section ordering fixed (addenda above Key Relationships); checkctx CLEAN.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Joe DiPrima
2026-08-06 11:18:48 -05:00
co-authored by Claude Fable 5
parent 51dff6bd5a
commit bf39b81b9d
6 changed files with 71 additions and 9 deletions
+16 -1
View File
@@ -685,7 +685,22 @@ Respawn SIM path: `DropZoneReply` `FUN_004bffd0` → `Mech::Reset` @0x4009fb74;
---
## 7. Tools
- `tools/gapcensus.py` — the #60 dark-region census: index/export coverage, function-start discovery, TU attribution, repo-citation flags → `reference/decomp/GAP_CENSUS.md` + `gap_census.tsv`. Consult BEFORE any "absent from the export" claim (gotcha §20).
- **CITATION POLICY (since the 2026-08-06 re-export): cite `@ADDR`, never `part_0NN.c:LINE`.**
Addresses are stable across exports; shard membership and line numbers are NOT. Pre-08-06
part/line citations resolve only against `reference/decomp/archive_2025export/`.
-**Ghidra renders member access as int-ARRAY indices** (`param_1[0xfe]` == byte offset 0x3f8,
`[0x1e7]` == 0x79c): grepping the export for an offset STRING misses every such site. Divide
by 4 (or grep both forms) — this is a live instance of gotcha §20.
- `tools/gapcensus.py [dir]` — the #60 dark-region census: index/export coverage, function-start
discovery, TU attribution, repo-citation flags → `<dir>/GAP_CENSUS.md` + `gap_census.tsv`.
Consult BEFORE any "absent from the export" claim (gotcha §20).
- `tools/ghidra_reexport.sh [reprocess]` — headless re-export: Ghidra 12.1.2 + JDK 21 (installed
in `%LOCALAPPDATA%\bt411-tools` beside DXSDK/cmake) run `reference/ghidra_scripts/ExportGaps.java`
(ExportAll's output contract + the dark-region gap fill). ⚠ the runner MUST use 8.3 SHORT paths
(`JOELAP~1`, `BT411-~1`): Ghidra's launcher .bat expands `%JAVA_HOME%` UNQUOTED and the user
profile has a space. `reprocess` re-runs the script on the saved project (skips re-analysis).
- `tools/gapdiff.py [old] [new]` — score two censused exports (coverage/dark deltas, which
previously-dark addresses the KB already cites, celebrity check).
- `tools/disas2.py <VA> [len]` — capstone disassembly of BTL4OPT.EXE at a VA (recovers x87 math
Ghidra drops; folds known call targets + float constants). THE tool for any `FUN_` the