@henols/vice-mcp 0.2.3 → 0.2.4

package/anno-graphics.ts

@@ -1,19 +1,19 @@
 #!/usr/bin/env node
 // anno-graphics.ts
 //
-// Phase 37, plan 37-07 (AUTO-06): derives the VIC-II graphics areas -- screen
+// Derives the VIC-II graphics areas -- screen
 // matrix, character set or bitmap, and sprite POINTERS -- from RECOVERED VIC
 // register VALUES, never from cross-references. The chip fetches its
 // character/bitmap/screen data by direct memory access, so a character set
 // may be referenced by NO INSTRUCTION ANYWHERE IN THE PROGRAM -- exactly the
 // case a cross-reference-driven join structurally cannot find. That is
-// AUTO-06's entire reason to exist (`37-RESEARCH.md` SS E: no existing code in
+// This module's entire reason to exist: no existing code in
 // this repository decodes these three registers for this purpose -- the
 // stock-backend modules that name them read LIVE emulator state for a
-// different question).
+// different question.
 //
 // THIS MODULE TAKES PLAIN REGISTER-WRITE VALUES AND RETURNS PLAIN RANGES --
-// AND NOTHING ELSE (D-37-26). It never receives a store handle, never opens
+// AND NOTHING ELSE. It never receives a store handle, never opens
 // or names `node:sqlite`, never imports `anno-store.ts`, `anno-join.ts`, or
 // any module that reads the stored cross-reference graph, and never imports
 // `hostpath.ts`/`containerpath.ts` or the emulator backend
@@ -22,13 +22,13 @@
 // very case this derivation exists to cover -- so its import list is scanned
 // structurally (`anno-graphics.test.ts`) rather than merely reviewed.
 //
-// SPRITE BITMAP LOCATIONS ARE OUT OF SCOPE (D-37-29): this module derives the
+// SPRITE BITMAP LOCATIONS ARE OUT OF SCOPE: this module derives the
 // eight-byte sprite POINTER TABLE range only. The pointer VALUES themselves
 // are program data, usually written at run time, and are not register values
 // a static analysis recovers -- this module must never appear to promise
 // them.
 //
-// A MISSING REGISTER IS A STATED ABSENCE, NEVER A DEFAULT (D-37-28): where a
+// A MISSING REGISTER IS A STATED ABSENCE, NEVER A DEFAULT: where a
 // required register value was never recovered, the ranges that depend on it
 // are omitted from that map and the map names the missing register in
 // `missingRegisters`. Power-on defaults exist and are well known, which is
@@ -37,10 +37,10 @@
 // recovered value, and this phase exists to prevent exactly that class of
 // confident wrong output.
 //
-// SEVERAL COMBINATIONS ARE SEVERAL MAPS, NEVER ONE MERGED MAP (D-37-27): a
+// SEVERAL COMBINATIONS ARE SEVERAL MAPS, NEVER ONE MERGED MAP: a
 // program that reprograms bank, screen or charset per raster split has
 // several valid graphics maps, and a single derived map would be wrong for
-// all but one -- the same path-dependence limit AUTO-05 names for the
+// all but one -- the same path-dependence limit this project's own processor-port derivation names for the
 // processor port. `deriveGraphicsRanges()` returns one map per DISTINCT
 // combination of the three registers' own recovered values: the cross
 // product of each register's own distinct-value set, with a register that
@@ -49,7 +49,7 @@
 // tuple order (missing sorts first), so two runs over the same facts return
 // deeply equal arrays.
 //
-// NO GRAPHICS-SPECIFIC DATA TYPE EXISTS (D-37-30): the store's `DataType`
+// NO GRAPHICS-SPECIFIC DATA TYPE EXISTS: the store's `DataType`
 // vocabulary (`anno-types.ts`) is a frozen twelve with no graphics-specific
 // member, and widening it is a schema decision no plan in this phase makes --
 // widening it would require re-auditing every consumer of that frozen list,
@@ -61,7 +61,7 @@
 // (READ-ONLY, NEVER IMPORTED): this module's bank/screen/charset/bitmap
 // arithmetic was checked by hand against those two files' existing, tested
 // decode of the SAME three registers for the live-emulator backend, and
-// found to agree exactly -- see the plan 37-07 SUMMARY for the comparison.
+// found to agree exactly.
 // This module REIMPLEMENTS that arithmetic rather than importing it, because
 // importing either file would reach the emulator backend's own transport
 // seam, which this module must never touch.
@@ -126,7 +126,7 @@ export const SPRITE_POINTER_OFFSET = 0x3f8;
 const SPRITE_POINTER_SIZE = 8;
 
 /** The existing, byte-shaped `DataType` every range this module emits
- * carries (D-37-30). */
+ * carries. */
 const GRAPHICS_DATA_TYPE: DataType = "byte";
 
 /** One recovered register write, in the same shape `ConstWriteFact` in
@@ -212,7 +212,7 @@ function distinctValuesFor(facts: readonly GraphicsConstWriteFact[], targetAddre
 }
 
 /** One combination of the three registers' own recovered values --
- * `undefined` names a register with zero recovered facts (D-37-28). */
+ * `undefined` names a register with zero recovered facts. */
 interface RegisterCombo {
   bankSelect: number | undefined;
   memoryControl: number | undefined;
@@ -220,7 +220,7 @@ interface RegisterCombo {
 }
 
 /** Ascending, with `undefined` (missing) sorting first -- a stated,
- * deterministic order over the tuple (D-37-27), not "whatever `Set`
+ * deterministic order over the tuple, not "whatever `Set`
  * iteration happened to produce". */
 function compareSlot(a: number | undefined, b: number | undefined): number {
   const av = a ?? -1;
@@ -304,13 +304,13 @@ function buildGraphicsMap(combo: RegisterCombo): GraphicsMap {
 
 /**
  * Derives the graphics areas -- screen matrix, character set or bitmap, and
- * sprite pointers -- from recovered VIC register values ALONE (D-37-26).
+ * sprite pointers -- from recovered VIC register values ALONE.
  * Returns one `GraphicsMap` per distinct combination of the three registers'
- * own recovered values (D-37-27), in ascending tuple order, so two calls
+ * own recovered values, in ascending tuple order, so two calls
  * with the same `facts` return deeply equal arrays. A register with zero
  * recovered facts contributes a single "missing" combination slot rather
  * than an axis; every range depending on it is omitted from every map, and
- * the map names it in `missingRegisters` (D-37-28). `facts` carrying values
+ * the map names it in `missingRegisters`. `facts` carrying values
  * for addresses other than the three this module watches (e.g. the
  * processor port, $0001) are ignored -- this module only ever reads writes
  * to `BANK_SELECT_ADDRESS`/`MEMORY_CONTROL_ADDRESS`/`CONTROL_REGISTER_1_ADDRESS`.

package/anno-hazard-report.ts

@@ -233,8 +233,8 @@ export interface HazardLimit {
 }
 
 /**
- * The two limits this plan's slice seeds. Plan 48-03 and plan 48-05 add the
- * remaining entries; this array only ever grows.
+ * The two limits seeded here; later work adds the
+ * remaining entries -- this array only ever grows.
  */
 export const HAZARD_LIMITS: readonly HazardLimit[] = Object.freeze([
   {

package/anno-import.ts

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 // anno-import.ts
 //
-// Phase 37, plan 37-01 (IMP-01, IMP-02): the container-side parser and
-// importer for `GhidraStructExport.java`'s `## `-delimited transfer file.
+// The container-side parser and importer for `GhidraStructExport.java`'s
+// `## `-delimited transfer file.
 //
 // THIS MODULE RECEIVES AN ALREADY-OPEN STORE HANDLE. It never opens or closes
 // a store itself -- there is no second store session anywhere in this file.
@@ -18,9 +18,9 @@
 // WHAT THIS IS THE ONE AUTHORITATIVE PLACE FOR: parsing the export's fixed
 // `## `-delimited section format, mapping Ghidra's `Reference.getReferenceType()`
 // vocabulary onto the store's frozen four-member `XrefAccessKind`
-// (`GHIDRA_REFTYPE_TO_ACCESS_KIND`, D-37-05), and the digest-then-delete
+// (`GHIDRA_REFTYPE_TO_ACCESS_KIND`), and the digest-then-delete
 // discipline that makes the transfer file transient evidence rather than a
-// second on-disk model (IMP-02).
+// second on-disk model.
 //
 // WHAT NOT TO DO:
 //   - Never write a row before the WHOLE document has parsed successfully.
@@ -37,7 +37,7 @@
 //     member of `XREF_ACCESS_KINDS`. It is dropped and COUNTED in
 //     `kindsSeenNotImported`, never silently absorbed and never refused --
 //     refusing on an ordinary `JSR`/`JMP` reference would make the importer
-//     unusable against a real corpus binary (D-37-05).
+//     unusable against a real corpus binary.
 
 import { createHash } from "node:crypto";
 // Namespace import, deliberately: a later acceptance gate greps this file for
@@ -95,11 +95,11 @@ export interface GhidraExportDocument {
  * hand-written test fixture using either convention keeps working.
  *
  * Discovered as a LIVE, previously-untested defect in the REFERENCES import
- * path (plan 37-01): every prior test used a hand-written, `$`-prefixed
+ * path: every prior test used a hand-written, `$`-prefixed
  * transfer file, never a token shaped exactly as Ghidra itself renders one
  * -- `importGhidraExport()` would refuse EVERY real captured export outright.
  * Fixed here, in the SAME function `## CONST_WRITES`'s own tokens (which are
- * ALSO bare hex, D-37-06) need the identical treatment for.
+ * ALSO bare hex) need the identical treatment for.
  */
 function parseGhidraAddressToken(token: string, what: string): number {
   if (token.startsWith("$") || /^0[xX]/.test(token)) {
@@ -245,7 +245,7 @@ export function parseGhidraExport(text: string): GhidraExportDocument {
   };
   checkTrailerCount("REFERENCES", "REFERENCE_COUNT");
   checkTrailerCount("CLASSIFICATION", "CLASSIFICATION_LINES");
-  // Plan 37-02: the SAME generic trailer-count check, extended to
+  // The SAME generic trailer-count check, extended to
   // `## CONST_WRITES` / `## CONST_WRITES_COUNT`. Note what this generic
   // grammar already does with the exporter's own `## CONST_WRITES_NONE`
   // marker line: because every `## `-prefixed line with no following space
@@ -262,7 +262,7 @@ export function parseGhidraExport(text: string): GhidraExportDocument {
 }
 
 /**
- * D-37-05's frozen mapping from Ghidra's `Reference.getReferenceType()`
+ * The frozen mapping from Ghidra's `Reference.getReferenceType()`
  * vocabulary onto the store's four-member `XrefAccessKind`. A token absent
  * from this table is dropped and COUNTED (`kindsSeenNotImported`), never
  * refused and never guessed -- a real corpus binary carries ordinary jump and
@@ -277,7 +277,7 @@ export const GHIDRA_REFTYPE_TO_ACCESS_KIND: Readonly<Record<string, XrefAccessKi
   COMPUTED_CALL: "COMPUTED_JUMP",
 });
 
-/** D-37-06's watched-address set, mirroring the Java constant
+/** The watched-address set, mirroring the Java constant
  * `CONST_WRITE_WATCHED_ADDRESSES` in `GhidraStructExport.java` byte-for-byte
  * -- the two MUST be kept in step. `parseConstWrites()` below does NOT
  * filter its own output against this list: a `## CONST_WRITES` line for an
@@ -299,8 +299,8 @@ export interface ConstWriteFact {
 
 /**
  * Turns the `## CONST_WRITES` section `parseGhidraExport()` already parsed
- * into `(storeAddress, targetAddress, value)` facts (Phase 37 plan 37-02,
- * `AUTO-04`/`AUTO-05`). `parseGhidraExport()` has ALREADY refused, before
+ * into `(storeAddress, targetAddress, value)` facts. `parseGhidraExport()`
+ * has ALREADY refused, before
  * this function is ever called, if a declared `## CONST_WRITES_COUNT`
  * trailer disagrees with the section's own parsed body-line count -- the
  * SAME generic check `## REFERENCE_COUNT`/`## CLASSIFICATION_LINES` already
@@ -357,10 +357,10 @@ export interface ImportCounts {
    * still reported as a success with this reason attached, never as a
    * failure after a durable write. */
   transferDeleteError?: string;
-  /** CR-01 fix: the `## CONST_WRITES` section's own facts, parsed by
+  /** The `## CONST_WRITES` section's own facts, parsed by
    * `parseConstWrites()` BEFORE the transfer file is deleted below -- the
    * ONE artifact carrying them. `importGhidraExport()` never persists these
-   * facts in the store (the reserved `bank` column stays null, IMP-01/D-37-25);
+   * facts in the store (the reserved `bank` column stays null);
    * they ride on THIS return value instead, so a caller can hand the SAME
    * array straight to `anno_join_memmap`'s own `const_writes` argument in a
    * following call, closing the loop `anno-tools.ts`'s `dispatchJoinMemmap()`
@@ -429,7 +429,7 @@ export function importGhidraExport(handle: AnnoStoreHandle, args: ImportGhidraEx
 
   const doc = parseGhidraExport(contents.toString("utf8"));
   const referenceLines = doc.sections.get("REFERENCES") ?? [];
-  // CR-01/WR-02 fix: parsed here, from the SAME document, before the
+  // Parsed here, from the SAME document, before the
   // transfer file is deleted below -- `parseConstWrites()` was previously
   // exercised only by test code (`anno-join.test.ts`/`ghidra-live.test.ts`),
   // never by this, the only production entry point that reads a transfer

package/anno-index.ts

@@ -3,7 +3,7 @@
 //
 // The ONE place that answers "which annotated range owns this address" --
 // a pure, narrowest-range-wins paint index over the whole 64K address space,
-// rebuilt from rows and never maintained incrementally (STORE-03).
+// rebuilt from rows and never maintained incrementally.
 //
 // ---------------------------------------------------------------------------
 // WHY THIS FILE EXISTS
@@ -37,14 +37,14 @@
 //      an argument is the only shape that can be tested for it.
 //   2. NEVER cache this index on disk. A cached index is a second truth that
 //      can disagree with the range table -- exactly the failure the
-//      derived-from-bytes coverage census (`COV-01`) exists to make impossible.
+//      derived-from-bytes coverage census exists to make impossible.
 //      Rebuild it; see the measurement above.
-//   3. NEVER add an adjacency, coalescing or merge pass. `STORE-02` stores
-//      ranges AS ranges and never merges them, so there is no splitter
-//      primitive here to introduce. Merging is the named blocker behind
-//      `DECOMP-01` and `BUILD-02` and the predicted over-merge bias behind
-//      `COV-01`; all three are designed out by construction here, not
-//      documented as hazards to remember.
+//   3. NEVER add an adjacency, coalescing or merge pass. This project's own
+//      store stores ranges AS ranges and never merges them, so there is no
+//      splitter primitive here to introduce. Merging is a named blocker for
+//      decomposition-to-closure work and the predicted over-merge bias
+//      behind the coverage census; all three are designed out by
+//      construction here, not documented as hazards to remember.
 //   4. NEVER maintain the index incrementally. An incremental update has to
 //      know what the row it is removing was covering UNDERNEATH, which the
 //      index cannot say -- a painted cell records the winner, not the losers.

package/anno-join.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // anno-join.ts
 //
-// Phase 37, plan 37-01 (AUTO-01): the mechanical join between stored
+// The mechanical join between stored
 // cross-references and `memmap.json`, with no agent call, no queue walk and
 // no skill invocation anywhere in the loop.
 //
@@ -17,9 +17,9 @@
 // WHAT THIS IS THE ONE AUTHORITATIVE PLACE FOR: reading `listXrefs()`'s
 // distinct target addresses, classifying each one (inside the loaded image,
 // no `memmap.json` entry, or annotated) and writing the resulting comment
-// through `setComment()`. `AUTO-01`'s own criterion -- no agent, no queue
+// through `setComment()`. This module's own criterion -- no agent, no queue
 // walk, no skill invocation -- is checked STRUCTURALLY over this module's own
-// source in `anno-join.test.ts` (plan 37 task 3), not merely asserted here in
+// source in `anno-join.test.ts`, not merely asserted here in
 // prose.
 //
 // WHAT NOT TO DO:
@@ -33,14 +33,14 @@
 //     that decodes to more than one region, DECLINES -- see the bank-state
 //     block below.
 //
-// Phase 37, plan 37-06 (AUTO-04/AUTO-05): `runMemmapJoin()` gains an
+// `runMemmapJoin()` gains an
 // OPTIONAL `constWrites` argument. When `undefined` (every pre-37-06 call
 // site, and every existing test in this file), the bank-state machinery
 // below is a complete no-op and every address resolves EXACTLY as it did
 // before this plan -- the candidate-constraint argument must not change any
 // unconstrained selection's answer. Only when a caller explicitly supplies
 // an array (even an empty one) does the reaching-values/decline logic
-// activate for addresses inside `BANK_CONDITIONAL_RANGES`. D-37-24: the
+// activate for addresses inside `BANK_CONDITIONAL_RANGES`. The
 // reaching-values computation is deliberately conservative -- it is NOT a
 // dataflow analysis. It uses only what the export gives: the recovered
 // constant stores to the processor port (each with its own address), and
@@ -49,7 +49,7 @@
 // `constWrites` whose OWN store address can reach that address, walked
 // forward over that same graph. Where the graph does not connect a store to
 // the address at all, that value is simply not in the reaching set --
-// D-37-23's decline-on-empty-or-disagreement rule (below) is what turns
+// the decline-on-empty-or-disagreement rule (below) is what turns
 // "nothing reaches this point" into a stated absence rather than a silent
 // default.
 
@@ -66,30 +66,29 @@ import type { ConstWriteFact } from "./anno-import.ts";
 import type { ContradictedComment, SplitTableReinterpretation, XrefRow } from "./anno-types.ts";
 import { loadMemmap, memmapDigest, PROVENANCE_TOKEN_PREFIX, selectMemmapEntry } from "./memmap-lookup.ts";
 import type { MemmapEntry, MemmapSelection } from "./memmap-lookup.ts";
-// Phase 37, plan 37-08 (AUTO-07): the graphics write-back. deriveGraphicsRanges()
+// The graphics write-back. deriveGraphicsRanges()
 // is structurally typed against ConstWriteFact -- GraphicsConstWriteFact's own
 // shape is identical ({storeAddress, targetAddress, value}) -- so THIS module's
-// own constWrites argument, already threaded for D-37-24's bank-state block, is
-// handed straight through with no translation layer (37-07-SUMMARY.md's own
-// "Next Phase Readiness" note names this directly).
+// own constWrites argument, already threaded for the bank-state block, is
+// handed straight through with no translation layer.
 import { deriveGraphicsRanges } from "./anno-graphics.ts";
 import type { GraphicsMap } from "./anno-graphics.ts";
 
-/** D-37-25: the axis-qualified provenance marker an annotated bank-conditional
+/** The axis-qualified provenance marker an annotated bank-conditional
  * comment carries, ALWAYS before `PROVENANCE_TOKEN_PREFIX`'s own digest
- * token (which stays last -- D-37-13). Names the axis ("processor-port")
+ * token (which stays last). Names the axis ("processor-port")
  * explicitly, so a later phase adding the VIC banking axis is additive
  * rather than ambiguous about which axis a given token names. */
 const BANK_PROVENANCE_PREFIX = "[processor-port:";
 
 /**
- * The reaching-values computation's own result shape (D-37-24): exactly one
+ * The reaching-values computation's own result shape: exactly one
  * recovered value reaches the address; several do (an array -- length 0
  * means none reach at all, length 2+ means genuine disagreement-or-agreement
  * to resolve); or the computation cannot decide at all. Nothing in this
  * project's current data model (a plain directed graph of already-resolved
  * `XrefRow`s) can currently produce `"unknown"` -- there is no signal here
- * for a dropped or unresolved reference (D-37-24's own stated limit) -- but
+ * for a dropped or unresolved reference (a stated limit of this computation) -- but
  * the shape is kept complete for a future importer that DOES emit such a
  * signal, rather than silently folding that case into "empty".
  */
@@ -126,7 +125,7 @@ function canReach(from: number, target: number, adjacency: Map<number, number[]>
   return false;
 }
 
-/** D-37-24: the set of recovered processor-port values whose OWN store
+/** The set of recovered processor-port values whose OWN store
  * address can reach `targetAddress`, over `adjacency`. Never a dataflow
  * analysis -- purely "does the stored cross-reference graph connect this
  * store to this address". */
@@ -156,8 +155,8 @@ export class AnnoJoinError extends Error {
 }
 
 /** What one `runMemmapJoin()` call reports. `addressesConsidered` is always
- * the sum of the next four fields. The three `graphics*` fields (plan 37-08,
- * AUTO-07) are always present and `0` when `constWrites` is omitted or when
+ * the sum of the next four fields. The three `graphics*` fields are always
+ * present and `0` when `constWrites` is omitted or when
  * the selected map derives zero ranges -- never absent, so a caller reads
  * them unconditionally instead of guarding on them, mirroring
  * `SetDataTypeResult`'s own "always present, often empty" convention for
@@ -175,14 +174,14 @@ export interface JoinCounts {
 }
 
 /**
- * What the graphics write-back (plan 37-08, AUTO-07) reports, in full --
+ * What the graphics write-back reports, in full --
  * `JoinCounts`'s own `graphics*` fields are the COUNTS of these same
  * `contradictedComments`/`reinterpretedSplitTables` arrays; this record
  * carries the disclosures themselves so neither is dropped (must_haves.truths:
  * "the join's returned counts include the contradicted-comment and
  * fragmented-split-table disclosures the range write reported; neither is
  * dropped"). `mapIndex` records WHICH of `deriveGraphicsRanges()`'s several
- * maps was written -- D-37-27's own rule (several valid combinations are
+ * maps was written -- this project's own rule (several valid combinations are
  * several maps, never one merged map) means writing more than one would
  * write mutually-contradicting ranges into the SAME store, so exactly one is
  * ever written and this field is the record of which. */
@@ -206,7 +205,7 @@ export interface JoinDecision {
 export interface RunMemmapJoinArgs {
   imageOrigin: number;
   imageByteLength: number;
-  /** D-37-24/AUTO-04/AUTO-05: the recovered `$01` const-write facts this run
+  /** The recovered `$01` const-write facts this run
    * has evidence for, typically `parseConstWrites()`'s own output over one
    * imported export. `undefined` (every pre-37-06 call site) means "this run
    * carries no bank-state evidence at all" -- the bank-state machinery is a
@@ -214,7 +213,7 @@ export interface RunMemmapJoinArgs {
    * An explicit array (even `[]`) activates it for addresses inside
    * `BANK_CONDITIONAL_RANGES`. */
   constWrites?: readonly ConstWriteFact[];
-  /** Plan 37-08 (AUTO-07, D-37-27): which of `deriveGraphicsRanges()`'s
+  /** Which of `deriveGraphicsRanges()`'s
    * several maps to write back, when `constWrites` derives more than one
    * distinct register-value combination. Defaults to `0`. Consulted ONLY
    * when `constWrites` is supplied AT ALL (the SAME gate that activates the
@@ -230,8 +229,9 @@ export interface RunMemmapJoinArgs {
  * in ascending address order. An address inside the caller's own loaded
  * image range is a program address, not a hardware/memory-map feature, and
  * is skipped WITHOUT a `memmap.json` lookup -- the membership test runs
- * BEFORE `selectEntry()` is called at all (D-37-12), so the guard is a
- * control-flow fact rather than a result-filtering one: `AUTO-03` says an
+ * BEFORE `selectEntry()` is called at all, so the guard is a
+ * control-flow fact rather than a result-filtering one: this file's own
+ * contract says an
  * in-image address is "never looked up in memmap.json", a claim about what
  * runs, not merely about what the caller sees back. An address with no
  * containing `memmap.json` entry is skipped for that reason instead;
@@ -262,7 +262,7 @@ export function runMemmapJoin(
     );
   }
 
-  // D-37-13: computed ONCE per join run and reused for every annotated row,
+  // Computed ONCE per join run and reused for every annotated row,
   // never recomputed per row -- two comments written in the same run are
   // therefore GUARANTEED to carry byte-identical tokens, not merely likely
   // to (the file cannot change mid-run, but a per-row recompute would still
@@ -272,7 +272,7 @@ export function runMemmapJoin(
   const xrefs = listXrefs(handle);
   const targets = [...new Set(xrefs.map((xref) => xref.toAddress))].sort((a, b) => a - b);
 
-  // D-37-24: built ONCE per run, over the SAME xref graph the unconstrained
+  // Built ONCE per run, over the SAME xref graph the unconstrained
   // path already reads via `listXrefs()` above -- reused for every address's
   // own reachability walk below. `undefined` `args.constWrites` means the
   // bank-state block is never entered at all, so this adjacency map is built
@@ -282,7 +282,7 @@ export function runMemmapJoin(
   const bankAdjacency = buildAdjacency(xrefs);
 
   // The inclusive image range, computed ONCE from the LoadedImage's own body
-  // bytes (D-37-12) -- never from `totalBytes` (the file's own byte count,
+  // bytes -- never from `totalBytes` (the file's own byte count,
   // which on the .prg route includes the two-byte load-address header and
   // would shift this whole range by two bytes) and never a caller-supplied
   // number pair that could silently widen or narrow the program's own
@@ -300,7 +300,7 @@ export function runMemmapJoin(
   for (const address of targets) {
     // THE GUARD: one early-return, before selectEntry() is ever called. A
     // single textual deletion of this block removes it cleanly -- that
-    // deletion is plan 37-05's own observed-red control (row 4).
+    // deletion is this file's own observed-red control.
     if (address >= imageStart && address <= imageEnd) {
       skippedInImage += 1;
       decisions.push({
@@ -313,13 +313,13 @@ export function runMemmapJoin(
       continue;
     }
 
-    // THE BANK-STATE BLOCK (D-37-22/D-37-23/D-37-24, AUTO-04/AUTO-05). Only
+    // THE BANK-STATE BLOCK. Only
     // entered when the caller supplied `constWrites` AT ALL (`undefined`
     // skips this whole block, falling through to the unconstrained path
     // below exactly as pre-37-06) AND the address is inside one of the
     // three bank-conditional ranges -- outside them, bank state is
     // irrelevant and the candidate set stays unconstrained regardless of
-    // `constWrites` (D-37-22).
+    // `constWrites`.
     if (args.constWrites !== undefined && isBankConditionalAddress(address)) {
       const reaching = computeReachingValues(address, args.constWrites, bankAdjacency);
 
@@ -335,7 +335,7 @@ export function runMemmapJoin(
 
       // Resolves ONE region (or refuses) for a single reaching value, applies
       // it as a candidate constraint BEFORE selection runs (never a
-      // post-filter -- D-37-22), and pushes the matching decision. Shared by
+      // post-filter), and pushes the matching decision. Shared by
       // both the single-value and the several-values-same-region branches
       // below, so the annotate path is written exactly once.
       const annotateUnderRegion = (region: Exclude<BankedRegion, "not_applicable">, bankNote: string): void => {
@@ -412,7 +412,7 @@ export function runMemmapJoin(
 
     // The full comment text: the selected entry's label, one space, the
     // provenance prefix, then the full 64-character digest -- always LAST,
-    // never truncated (D-37-13). setComment() -> assertCommentText() refuses
+    // never truncated. setComment() -> assertCommentText() refuses
     // (never truncates) a text that overflows MAX_COMMENT_BYTES; that
     // refusal is left to propagate here rather than being pre-checked and
     // silently worked around, because a truncated provenance token would be
@@ -424,7 +424,7 @@ export function runMemmapJoin(
     decisions.push({ address, outcome: "annotated", label: selection.entry.label });
   }
 
-  // THE GRAPHICS WRITE-BACK (D-37-32/D-37-33, AUTO-07). Runs AFTER the main
+  // THE GRAPHICS WRITE-BACK. Runs AFTER the main
   // per-address loop above, as its own step -- graphics ranges are derived
   // from register VALUES, never from the cross-reference targets the loop
   // above walks, so there is no reason to interleave the two. Gated on the
@@ -443,10 +443,10 @@ export function runMemmapJoin(
       );
     }
 
-    // D-37-27: write ONLY the selected map's own ranges -- never every map
+    // Write ONLY the selected map's own ranges -- never every map
     // deriveGraphicsRanges() returned. Several distinct register-value
-    // combinations describe MUTUALLY CONTRADICTING layouts (D-37-27's own
-    // reason several maps exist at all); writing more than one into the
+    // combinations describe MUTUALLY CONTRADICTING layouts (the reason
+    // several maps exist at all); writing more than one into the
     // same store would write ranges that disagree with each other by
     // construction.
     let rangesWritten = 0;