@henols/vice-mcp 0.2.2 → 0.2.4

package/anno-join.ts

@@ -0,0 +1,480 @@
+#!/usr/bin/env node
+// anno-join.ts
+//
+// 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.
+//
+// THIS MODULE RECEIVES AN ALREADY-OPEN STORE HANDLE, exactly like
+// `anno-import.ts` -- there is no second store session anywhere in this
+// file. It never names `node:sqlite`, never calls `openStore()`/`closeStore()`
+// itself, and never imports `hostpath.ts`/`containerpath.ts`: the image range
+// it needs arrives as plain numbers (`imageOrigin`, `imageByteLength`) that
+// the caller has already derived from a loaded image, mirroring
+// `dxa-blocks.ts`'s own header posture of reading only already-fetched facts
+// a caller passes in.
+//
+// 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()`. 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`, not merely asserted here in
+// prose.
+//
+// WHAT NOT TO DO:
+//   - Never import anything under `src/skills/`. This function's entire
+//     point is that annotating an address costs one mechanical call, not an
+//     agent turn.
+//   - Never spawn a child process from this module.
+//   - Never carry a bank value forward past a point where two paths
+//     disagree, and never default an unresolved bank state to the power-on
+//     value (T-37-26). A reaching-values set of size other than one, or one
+//     that decodes to more than one region, DECLINES -- see the bank-state
+//     block below.
+//
+// `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`. 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
+// the cross-reference graph the importer already stored via `putXref()`.
+// The set of recovered values reaching a given address is the set of
+// `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 --
+// the decline-on-empty-or-disagreement rule (below) is what turns
+// "nothing reaches this point" into a stated absence rather than a silent
+// default.
+
+import { listXrefs, setComment, setDataType } from "./anno-store.ts";
+import type { AnnoStoreHandle } from "./anno-store.ts";
+import {
+  decodeBankState,
+  isBankConditionalAddress,
+  regionAdmitsEntry,
+  resolveBankedRegion,
+} from "./anno-bank.ts";
+import type { BankedRegion } from "./anno-bank.ts";
+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";
+// 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 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";
+
+/** The axis-qualified provenance marker an annotated bank-conditional
+ * comment carries, ALWAYS before `PROVENANCE_TOKEN_PREFIX`'s own digest
+ * 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: 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 (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".
+ */
+type ReachingValues = { kind: "one"; value: number } | { kind: "several"; values: number[] } | { kind: "unknown" };
+
+/** Builds a forward adjacency map from `xrefs`, ONCE per join run, reused for
+ * every address's own reachability walk below. */
+function buildAdjacency(xrefs: readonly XrefRow[]): Map<number, number[]> {
+  const adjacency = new Map<number, number[]>();
+  for (const xref of xrefs) {
+    const list = adjacency.get(xref.fromAddress);
+    if (list) list.push(xref.toAddress);
+    else adjacency.set(xref.fromAddress, [xref.toAddress]);
+  }
+  return adjacency;
+}
+
+/** Plain forward reachability (DFS, visited-set guarded against cycles):
+ * can `from` reach `target` by following zero or more `adjacency` edges? */
+function canReach(from: number, target: number, adjacency: Map<number, number[]>): boolean {
+  if (from === target) return true;
+  const visited = new Set<number>([from]);
+  const stack = [from];
+  while (stack.length > 0) {
+    const current = stack.pop()!;
+    for (const next of adjacency.get(current) ?? []) {
+      if (next === target) return true;
+      if (!visited.has(next)) {
+        visited.add(next);
+        stack.push(next);
+      }
+    }
+  }
+  return false;
+}
+
+/** 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". */
+function computeReachingValues(
+  targetAddress: number,
+  constWrites: readonly ConstWriteFact[],
+  adjacency: Map<number, number[]>,
+): ReachingValues {
+  const reaching: number[] = [];
+  for (const write of constWrites) {
+    if (canReach(write.storeAddress, targetAddress, adjacency)) reaching.push(write.value);
+  }
+  if (reaching.length === 1) return { kind: "one", value: reaching[0]! };
+  return { kind: "several", values: reaching };
+}
+
+/** Raised when `runMemmapJoin()`'s own inputs cannot support a join at all --
+ * currently only the zero-byte-image refusal below. Follows `anno-import.ts`'s
+ * `AnnoImportError` construction idiom (a bare `Error` subclass, not
+ * `AnnoStoreError`, since this module never touches the store's own
+ * persistence). */
+export class AnnoJoinError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "AnnoJoinError";
+  }
+}
+
+/** What one `runMemmapJoin()` call reports. `addressesConsidered` is always
+ * 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
+ * `contradictedComments`/`reinterpretedSplitTables`. */
+export interface JoinCounts {
+  addressesConsidered: number;
+  annotated: number;
+  skippedInImage: number;
+  skippedNoMapEntry: number;
+  declined: number;
+  commentsChanged: number;
+  graphicsRangesWritten: number;
+  graphicsContradictedComments: number;
+  graphicsReinterpretedSplitTables: number;
+}
+
+/**
+ * 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 -- 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. */
+export interface GraphicsWriteBack {
+  mapIndex: number;
+  rangesWritten: number;
+  contradictedComments: readonly ContradictedComment[];
+  reinterpretedSplitTables: readonly SplitTableReinterpretation[];
+}
+
+/** One address's own outcome. A skip or a decline always carries a non-empty
+ * `reason` naming WHY in the join's own vocabulary; an annotation carries the
+ * `label` it wrote. */
+export interface JoinDecision {
+  address: number;
+  outcome: "annotated" | "skipped-in-image" | "skipped-no-entry" | "declined";
+  reason?: string;
+  label?: string;
+}
+
+export interface RunMemmapJoinArgs {
+  imageOrigin: number;
+  imageByteLength: number;
+  /** 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
+   * complete no-op and every address resolves EXACTLY as before this plan.
+   * An explicit array (even `[]`) activates it for addresses inside
+   * `BANK_CONDITIONAL_RANGES`. */
+  constWrites?: readonly ConstWriteFact[];
+  /** 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
+   * bank-state block above) -- omitting `constWrites` entirely skips the
+   * graphics write-back completely, exactly like the bank-state block. Out
+   * of range for the derived map count refuses BY NAME (`AnnoJoinError`)
+   * rather than silently clamping or picking a default. */
+  graphicsMapIndex?: number;
+}
+
+/**
+ * Joins every DISTINCT `toAddress` `listXrefs()` holds against `memmap.json`,
+ * 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, 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;
+ * everything else is annotated with the selected entry's label via
+ * `setComment()`. Running this twice over an unchanged store re-classifies
+ * every address identically and reports `commentsChanged: 0` on the second
+ * run, because `setComment()` itself reports `changed: false` for a
+ * byte-identical repeat.
+ *
+ * `selectEntry` defaults to the real `selectMemmapEntry` and exists as an
+ * injection point for exactly one reason: it is the seam that makes "never
+ * looked up" checkable at all. Without it, the only available assertion is
+ * on the RESULT, and a result-filtering implementation (compute the
+ * selection, then discard it for an in-image address) would pass that
+ * assertion while still violating the requirement. A test passes a counting
+ * spy in its place and asserts zero calls for an all-in-image store.
+ */
+export function runMemmapJoin(
+  handle: AnnoStoreHandle,
+  args: RunMemmapJoinArgs,
+  entries: readonly MemmapEntry[] = loadMemmap(),
+  selectEntry: (address: number, entries: readonly MemmapEntry[]) => MemmapSelection | undefined = selectMemmapEntry,
+): { counts: JoinCounts; decisions: JoinDecision[]; graphics?: GraphicsWriteBack } {
+  if (args.imageByteLength === 0) {
+    throw new AnnoJoinError(
+      "runMemmapJoin refused: the image's own body length is 0 -- an image with no bytes has no range, and treating " +
+        "it as a zero-width range at its own origin would silently make one address (the origin) read as in-image.",
+    );
+  }
+
+  // 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
+  // be wasted work re-reading and re-hashing the same bytes for nothing).
+  const digest = memmapDigest();
+
+  const xrefs = listXrefs(handle);
+  const targets = [...new Set(xrefs.map((xref) => xref.toAddress))].sort((a, b) => a - b);
+
+  // 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
+  // but simply never consulted -- negligible cost, and keeps the "no
+  // constWrites -> no-op" contract a single conditional rather than two
+  // divergent code paths.
+  const bankAdjacency = buildAdjacency(xrefs);
+
+  // The inclusive image range, computed ONCE from the LoadedImage's own body
+  // 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
+  // extent.
+  const imageStart = args.imageOrigin;
+  const imageEnd = args.imageOrigin + args.imageByteLength - 1;
+
+  const decisions: JoinDecision[] = [];
+  let annotated = 0;
+  let skippedInImage = 0;
+  let skippedNoMapEntry = 0;
+  let declined = 0;
+  let commentsChanged = 0;
+
+  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 this file's own observed-red control.
+    if (address >= imageStart && address <= imageEnd) {
+      skippedInImage += 1;
+      decisions.push({
+        address,
+        outcome: "skipped-in-image",
+        reason:
+          `address $${address.toString(16)} lies inside the loaded image's own range ($${imageStart.toString(16)}-` +
+          `$${imageEnd.toString(16)}) and is therefore a program address, never looked up in memmap.json`,
+      });
+      continue;
+    }
+
+    // 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`.
+    if (args.constWrites !== undefined && isBankConditionalAddress(address)) {
+      const reaching = computeReachingValues(address, args.constWrites, bankAdjacency);
+
+      if (reaching.kind === "unknown") {
+        declined += 1;
+        decisions.push({
+          address,
+          outcome: "declined",
+          reason: `bank state at $${address.toString(16)} could not be determined -- the reaching-values computation could not decide`,
+        });
+        continue;
+      }
+
+      // Resolves ONE region (or refuses) for a single reaching value, applies
+      // it as a candidate constraint BEFORE selection runs (never a
+      // 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 => {
+        const constrained = entries.filter((entry) => regionAdmitsEntry(entry, region));
+        const selection = selectEntry(address, constrained);
+        if (selection === undefined) {
+          skippedNoMapEntry += 1;
+          decisions.push({
+            address,
+            outcome: "skipped-no-entry",
+            reason: `no memmap.json entry admits the resolved ${region} region for $${address.toString(16)}`,
+          });
+          return;
+        }
+        const commentText = `${selection.entry.label} ${BANK_PROVENANCE_PREFIX}${bankNote}] ${PROVENANCE_TOKEN_PREFIX}${digest}`;
+        const write = setComment(handle, { address, commentType: "line", text: commentText });
+        annotated += 1;
+        if (write.changed) commentsChanged += 1;
+        decisions.push({
+          address,
+          outcome: "annotated",
+          label: selection.entry.label,
+          ...(reaching.kind === "several" ? { reason: `reached under differing processor-port values (${bankNote}) that all resolve to the same region (${region})` } : {}),
+        });
+      };
+
+      if (reaching.kind === "one") {
+        const region = resolveBankedRegion(address, decodeBankState(reaching.value));
+        annotateUnderRegion(region as Exclude<BankedRegion, "not_applicable">, `$${reaching.value.toString(16)}`);
+        continue;
+      }
+
+      // reaching.kind === "several"
+      if (reaching.values.length === 0) {
+        declined += 1;
+        decisions.push({
+          address,
+          outcome: "declined",
+          reason: `no recovered processor-port value reaches $${address.toString(16)} -- declining rather than defaulting to the power-on state`,
+        });
+        continue;
+      }
+
+      const uniqueValues = [...new Set(reaching.values)].sort((a, b) => a - b);
+      const regionsByValue = uniqueValues.map((value) => resolveBankedRegion(address, decodeBankState(value)));
+      const uniqueRegions = new Set(regionsByValue);
+      if (uniqueRegions.size > 1) {
+        declined += 1;
+        const named = uniqueValues.map((value, i) => `$${value.toString(16)}(${regionsByValue[i]})`).join(", ");
+        decisions.push({
+          address,
+          outcome: "declined",
+          reason: `$${address.toString(16)} is reached under disagreeing processor-port values: ${named}`,
+        });
+        continue;
+      }
+
+      const region = regionsByValue[0]! as Exclude<BankedRegion, "not_applicable">;
+      const valuesNote = uniqueValues.map((value) => `$${value.toString(16)}`).join(",");
+      annotateUnderRegion(region, valuesNote);
+      continue;
+    }
+
+    const selection = selectEntry(address, entries);
+    if (selection === undefined) {
+      skippedNoMapEntry += 1;
+      decisions.push({
+        address,
+        outcome: "skipped-no-entry",
+        reason: "no memmap.json entry contains this address",
+      });
+      continue;
+    }
+
+    // The full comment text: the selected entry's label, one space, the
+    // provenance prefix, then the full 64-character digest -- always LAST,
+    // 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
+    // a wrong answer that reports success.
+    const commentText = `${selection.entry.label} ${PROVENANCE_TOKEN_PREFIX}${digest}`;
+    const write = setComment(handle, { address, commentType: "line", text: commentText });
+    annotated += 1;
+    if (write.changed) commentsChanged += 1;
+    decisions.push({ address, outcome: "annotated", label: selection.entry.label });
+  }
+
+  // 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
+  // SAME `constWrites !== undefined` condition the bank-state block uses:
+  // omitting `constWrites` entirely is a complete no-op here too, exactly
+  // like the bank-state block above.
+  let graphics: GraphicsWriteBack | undefined;
+  if (args.constWrites !== undefined) {
+    const maps = deriveGraphicsRanges(args.constWrites);
+    const mapIndex = args.graphicsMapIndex ?? 0;
+    const selectedMap: GraphicsMap | undefined = maps[mapIndex];
+    if (selectedMap === undefined) {
+      throw new AnnoJoinError(
+        `runMemmapJoin refused: graphicsMapIndex ${mapIndex} is out of range -- deriveGraphicsRanges() produced ` +
+          `${maps.length} map(s) for this run's own constWrites`,
+      );
+    }
+
+    // Write ONLY the selected map's own ranges -- never every map
+    // deriveGraphicsRanges() returned. Several distinct register-value
+    // 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;
+    const contradictedComments: ContradictedComment[] = [];
+    const reinterpretedSplitTables: SplitTableReinterpretation[] = [];
+    for (const range of selectedMap.ranges) {
+      const write = setDataType(handle, { start: range.start, endInclusive: range.endInclusive, dataType: range.dataType });
+      rangesWritten += 1;
+      // Disclosures a successful range write can carry -- surfaced, never
+      // dropped (must_haves.truths): a comment whose recorded confidence now
+      // contradicts the type this write just assigned, or a split table this
+      // write fragmented.
+      contradictedComments.push(...write.contradictedComments);
+      reinterpretedSplitTables.push(...write.reinterpretedSplitTables);
+    }
+    graphics = { mapIndex, rangesWritten, contradictedComments, reinterpretedSplitTables };
+  }
+
+  const counts: JoinCounts = {
+    addressesConsidered: targets.length,
+    annotated,
+    skippedInImage,
+    skippedNoMapEntry,
+    declined,
+    commentsChanged,
+    graphicsRangesWritten: graphics?.rangesWritten ?? 0,
+    graphicsContradictedComments: graphics?.contradictedComments.length ?? 0,
+    graphicsReinterpretedSplitTables: graphics?.reinterpretedSplitTables.length ?? 0,
+  };
+  return graphics === undefined ? { counts, decisions } : { counts, decisions, graphics };
+}

package/anno-memmap-render.ts

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 // anno-memmap-render.ts -- the ONE authoritative place in this repo that
 // renders the human-readable Markdown memory map from this project's own
-// annotation store (D-24) plus a validated run-scoped provenance sidecar
-// (D-27's reconciliation, recorded in 11-10-PLAN.md's objective).
+// annotation store plus a validated run-scoped provenance sidecar, using
+// the reconciliation between those two sources this file implements.
 //
-// WHY THIS MODULE EXISTS (D-24): the store is canonical; the Markdown memory
+// WHY THIS MODULE EXISTS: the store is canonical; the Markdown memory
 // map becomes a rendered VIEW. Criterion 1 says findings must be queryable
 // "instead of re-deriving from Markdown prose" -- that is only true by
 // construction if the prose is GENERATED from the queryable thing. Nothing
@@ -13,7 +13,8 @@
 // `listRanges()`/`listLabels()`/`listComments()` readers, never from a
 // human editing the output file directly.
 //
-// THE D-24/D-27 RECONCILIATION THIS FILE IMPLEMENTS: run-scoped facts (the
+// THE RECONCILIATION THIS FILE IMPLEMENTS, BETWEEN THE STORE AND THE
+// RUN-SCOPED SIDECAR: run-scoped facts (the
 // capture's SHA-256, `$01`, `$DD00`, the derived graphics chain, the video
 // standard, the live vector pair, observed raster positions) are facts about
 // a RUN, not about an address -- the store is address-keyed and has no shape
@@ -24,8 +25,8 @@
 // `<placeholder>` for one.
 //
 // WHY THE LAYOUT IS EMBEDDED IN TYPESCRIPT RATHER THAN READ FROM A TEMPLATE
-// FILE AT RUNTIME (the second decision this plan records): Phase 10's D-06
-// established that `.claude/mcp/vice/*.ts` exists as files on disk only
+// FILE AT RUNTIME (the second decision this plan records): an earlier
+// finding established that `.claude/mcp/vice/*.ts` exists as files on disk only
 // under the Claude Code plugin route -- both npm-installer routes launch via
 // `npx`. A renderer that resolved a template path into the skills tree at
 // runtime would silently fail to resolve for an npm-installed user. The
@@ -41,7 +42,7 @@
 //   - drift detection (`checkRenderedMemoryMap()`) -- the one place a
 //     rendered file on disk is compared against what the store (plus the
 //     sidecar) would produce right now;
-//   - Markdown-cell escaping (`escapeMarkdownCell()`, WR-04, closed) --
+//   - Markdown-cell escaping (`escapeMarkdownCell()`) --
 //     every store-derived text interpolation in the generated document
 //     (comment evidence, symbol names) is escaped through this one
 //     function, never a second ad hoc `.replace()` at a call site.
@@ -50,7 +51,7 @@
 //   - Never hand-edit the rendered output. The banner exists precisely so a
 //     human editor is caught by `checkRenderedMemoryMap()` -- see the
 //     `render_digest` comment below for exactly what it covers.
-//   - Never read the layout from the skills tree at runtime (Phase 10 D-06).
+//   - Never read the layout from the skills tree at runtime (see the module header for why).
 //     This module's own non-vacuity test asserts a zero-count grep for the
 //     recon skill's template filename -- if you are tempted to add a
 //     `readFileSync()` call reaching into `.claude/skills/`, don't; the
@@ -101,14 +102,14 @@ function errMsg(err: unknown): string {
  * offset at which parsing stopped, as ` (at byte offset N)`, or `""` when the
  * runtime did not name one.
  *
- * WHY THIS IS A DIGIT EXTRACTOR AND NOT A MESSAGE PASS-THROUGH (CR-03). V8's
+ * WHY THIS IS A DIGIT EXTRACTOR AND NOT A MESSAGE PASS-THROUGH. V8's
  * JSON `SyntaxError` embeds a SNIPPET OF THE INPUT in its own message --
  * `Unexpected token 'Q', "QQZZORACLE"... is not valid JSON` -- so any code
  * that forwards `err.message` from a JSON parse over caller-supplied bytes is
  * a content-disclosure oracle. The capture group here is `(\d+)` and nothing
  * else, so no byte of the parsed file can reach the returned string however
  * the runtime words its message. Widening this regex to capture anything but
- * digits reopens CR-03.
+ * digits reopens the same content-disclosure risk.
  *
  * Returns `""` rather than guessing when no position is present (`Unexpected
  * end of JSON input` carries none) -- an absent offset is reported by absence,
@@ -280,9 +281,9 @@ export function parseProvenanceHeader(json: unknown): ProvenanceHeader {
  * distinguishable from drift under the same one.
  *
  * Version 2 (260821-a86) escaped Markdown table cells via
- * `escapeMarkdownCell()` -- WR-04, an output-shape change.
+ * `escapeMarkdownCell()`, an output-shape change.
  *
- * Version 3 (D-17) is an INPUT change: `computeRenderDigest()` canonicalises
+ * Version 3 is an INPUT change: `computeRenderDigest()` canonicalises
  * this store's own `RangeRow`/`LabelRow`/`CommentRow` instead of the three
  * wire shapes recorded above, so the same underlying annotations hash
  * differently either side of it. Leaving the version at "2" across that
@@ -298,7 +299,7 @@ export const RENDERER_VERSION = "3";
  * other leg), because comment `evidence` legitimately contains `|` and
  * embedded newlines (`anno_set_comment`'s own schema documents multi-line
  * support) -- refusing here would refuse valid data, not an attack. Closes
- * WR-04 / T-11-NAME-INJECT's render leg: an unescaped `|` or newline in
+ * this control's own render leg of T-11-NAME-INJECT: an unescaped `|` or newline in
  * store text used to be able to inject an extra table cell or split a row
  * across lines in the generated Markdown. A plain string or an empty string
  * is returned unchanged. */
@@ -348,7 +349,7 @@ export interface RenderMemoryMapOptions {
    *  reaching an equally real `readFileSync`, carried nothing -- so a reader
    *  comparing the two would reasonably conclude the difference was
    *  deliberate. It was not: the CLI read this argument raw, making it an
-   *  arbitrary-file read oracle (`29-REVIEW.md` CR-03). An absent comment
+   *  arbitrary-file read oracle. An absent comment
    *  beside a present one is a claim, and this one was false. */
   provenancePath: string;
   /** The workspace root both confinement checks are taken against. REQUIRED
@@ -396,7 +397,7 @@ export async function renderMemoryMap(opts: RenderMemoryMapOptions): Promise<Ren
   try {
     sidecarJson = JSON.parse(sidecarBytes);
   } catch (err) {
-    // NEVER INTERPOLATE THE UNDERLYING PARSE ERROR HERE (CR-03). Node's
+    // NEVER INTERPOLATE THE UNDERLYING PARSE ERROR HERE. Node's
     // SyntaxError quotes a snippet of the input it choked on -- e.g.
     // `Unexpected token 'Q', "QQZZORACLE"... is not valid JSON` -- so passing
     // it through turns a read refusal into a CONTENT-DISCLOSURE ORACLE. That
@@ -410,7 +411,7 @@ export async function renderMemoryMap(opts: RenderMemoryMapOptions): Promise<Ren
     // where parsing stopped and not about what the file contains.
     throw new Error(
       `renderMemoryMap: provenance sidecar at "${provenancePath}" is not valid JSON${jsonParsePosition(err)}. ` +
-        "The underlying parser message is deliberately NOT included -- it quotes the file's own bytes (CR-03).",
+        "The underlying parser message is deliberately NOT included -- it quotes the file's own bytes.",
     );
   }
   const provenance = parseProvenanceHeader(sidecarJson);
@@ -460,7 +461,7 @@ export async function renderMemoryMap(opts: RenderMemoryMapOptions): Promise<Ren
   // load-bearing detail rather than a formatting preference: every byte below
   // is re-rendered and compared BYTE FOR BYTE by `checkRenderedMemoryMap()`,
   // so an absolute path here would make the drift verdict a function of where
-  // the checkout sits (CR-01). `workspaceRelativePath()` is the one definition
+  // the checkout sits. `workspaceRelativePath()` is the one definition
   // of that spelling; it computes a location and refuses one that escapes the
   // root. It is NOT a confinement check -- this module still performs no
   // confinement of its own, exactly as `RenderMemoryMapOptions` documents.
@@ -587,13 +588,13 @@ export interface CheckRenderedMemoryMapOptions {
   /** See `RenderMemoryMapOptions.provenancePath` -- same argument, one layer
    *  up. The CALLER (`anno-cli.ts`'s `cmdRenderMemmap()`) confines it through
    *  `storePathWithinWorkspace()`; this module performs no confinement of its
-   *  own (CR-03). */
+   *  own. */
   provenancePath: string;
   /** The rendered file to compare against, read RAW by `readFileSync` below.
    *  The CALLER confines it through `storePathWithinWorkspace()` -- the SAME
    *  resolution that produces the write path on the non-`--check` branch, so
    *  the drift check and the write are one confined value rather than two
-   *  rules. This module performs no confinement of its own (CR-02). */
+   *  rules. This module performs no confinement of its own. */
   renderedPath: string;
   /** See `RenderMemoryMapOptions.workspaceRoot`. */
   workspaceRoot: string;
@@ -626,8 +627,8 @@ export type CheckRenderedMemoryMapResult =
  *     the workspace root;
  *   - a renderer change (output shape, or a `RENDERER_VERSION` bump).
  *
- * AND THE NEGATIVE, which is the defect this list was corrected for (CR-01,
- * `29-VERIFICATION.md` gap 1): relocating the checkout -- the same tree at a
+ * AND THE NEGATIVE, which is the defect this list was corrected for: relocating
+ * the checkout -- the same tree at a
  * different absolute path -- does NOT drift. The banner records
  * workspace-relative locations, so no compared byte is a function of where the
  * checkout sits. Before that fix this returned `drifted` for a byte-identical