@henols/vice-mcp 0.2.2 → 0.2.4

package/memmap-lookup.ts

@@ -0,0 +1,285 @@
+#!/usr/bin/env node
+// memmap-lookup.ts
+//
+// Phase 37, plan 37-01 (IMP-01/AUTO-01's shared foundation): the ONE loader
+// for `c64-memory-mapping`'s own `memmap.json`, its content digest, and
+// narrowest-containing-range selection over its 959 entries.
+//
+// THIS MODULE MUST NEVER IMPORT `hostpath.ts` OR `containerpath.ts` -- every
+// path here is repo-relative and derived from this module's own location, the
+// same posture `anno-regbits-gen.ts` and `dxa-blocks.ts` take for themselves.
+// It also NEVER NAMES `node:sqlite` and NEVER OPENS THE ANNOTATION STORE:
+// `anno-store.ts` is the one module `anno-seam.test.ts` allows to name that
+// dependency, and this module answers a pure question about a static JSON
+// file that has nothing to do with the store's own persistence.
+//
+// D-37-03: `anno-regbits-gen.ts:62` already computes the SAME `HERE`-relative
+// five-hop path to `memmap.json` and `anno-regbits-gen.ts:377` already
+// computes its sha256 digest, for a different purpose (bit-name generation).
+// This module COPIES that formula rather than importing the generator --
+// `anno-regbits-gen.ts`'s own header declares itself "the sole read of
+// c64-memory-mapping's own memmap.json ... for this purpose", and widening
+// that consumer set is a separate decision this plan does not make.
+//
+// WHAT THIS IS THE ONE AUTHORITATIVE PLACE FOR: loading and caching
+// `memmap.json`'s 959 entries, computing the file's own sha256 provenance
+// digest, and the NARROWEST-CONTAINING-RANGE selection rule an address
+// resolves through. `anno-join.ts` calls this module; nothing else needs to.
+//
+// WHAT NOT TO DO:
+//   - Never re-derive `MEMMAP_PATH` from a different relative offset. This
+//     formula has already broken once when the skills tree moved (plan
+//     16-01's own deviation note) -- one HERE-relative constant, copied
+//     verbatim in shape from `anno-regbits-gen.ts:62`.
+//   - Never mutate the cached entries array. `loadMemmap()` returns the same
+//     frozen array on every call after the first; a caller that needs a
+//     filtered view copies it.
+//   - Never derive "is this range bank-conditional" from `memmap.json`'s own
+//     fields. `BANK_CONDITIONAL_RANGES` below is HAND-MAINTAINED on purpose
+//     (37-RESEARCH.md Pitfall 2) -- the schema carries no structured
+//     bank-condition field, only free prose inside `desc`.
+
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/** The `HERE`-relative path to `c64-memory-mapping`'s `memmap.json`, using the
+ * SAME five-hop formula `anno-regbits-gen.ts:62` uses. Copied, not imported
+ * (D-37-03). */
+export const MEMMAP_PATH = join(HERE, "..", "..", "..", "src", "skills", "c64-memory-mapping", "memmap.json");
+
+/** One entry as `memmap.json` holds it. MEASURED at plan time: 959 entries,
+ * `start`/`end` are INCLUSIVE integers with no length field, and `sym` is
+ * present on 219 of them. */
+export interface MemmapEntry {
+  start: number;
+  end: number;
+  label: string;
+  section: string;
+  desc: string;
+  src: string;
+  sym?: string;
+}
+
+interface MemmapDocument {
+  sources: unknown[];
+  entries: MemmapEntry[];
+}
+
+/** Module-level cache, exactly as `anno-enum-gen.ts`'s `loadRegBits()` caches
+ * its own generated table -- `memmap.json` is read and parsed once per
+ * process, never per call. */
+let cachedEntries: readonly MemmapEntry[] | undefined;
+
+/** Reads and parses `memmap.json`, caching the parsed array. Refuses BY NAME
+ * if the top-level shape is not `{sources, entries}` or if `entries` is
+ * empty -- a malformed or truncated memmap.json must not read as "a memmap
+ * with nothing in it". */
+export function loadMemmap(): readonly MemmapEntry[] {
+  if (cachedEntries !== undefined) return cachedEntries;
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(MEMMAP_PATH, "utf8"));
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    throw new Error(`memmap-lookup: ${MEMMAP_PATH} could not be read/parsed as JSON (${reason}).`);
+  }
+
+  const doc = parsed as Partial<MemmapDocument> | null;
+  if (doc === null || typeof doc !== "object" || !Array.isArray(doc.sources) || !Array.isArray(doc.entries)) {
+    throw new Error(
+      `memmap-lookup: ${MEMMAP_PATH} is not a { sources, entries } document -- refusing to guess a shape for a ` +
+        "malformed memmap.json.",
+    );
+  }
+  if (doc.entries.length === 0) {
+    throw new Error(
+      `memmap-lookup: ${MEMMAP_PATH}'s "entries" array is empty -- "a memmap with nothing in it" and "a memmap ` +
+        'that failed to load" must not read the same, so this refuses rather than returning an empty selector.',
+    );
+  }
+
+  cachedEntries = Object.freeze(doc.entries.slice());
+  return cachedEntries;
+}
+
+/** The sha256 hex digest of `memmap.json`'s RAW BYTES -- the provenance value
+ * `AUTO-08` (a later plan) appends to derived comment text. MEASURED at plan
+ * time: this equals the same value `anno-regbits.json`'s committed banner
+ * carries (`_generated.memmapSha256`), and the test that pins this asserts
+ * that RELATION rather than a hard-coded literal, because the map is a living
+ * file. */
+export function memmapDigest(): string {
+  return createHash("sha256").update(readFileSync(MEMMAP_PATH)).digest("hex");
+}
+
+/**
+ * D-37-13: the fixed, machine-parseable prefix `anno-join.ts` appends
+ * `memmapDigest()`'s full 64-character lowercase hex digest to, on every
+ * derived comment (`AUTO-08`). Chosen to be unlikely to collide with
+ * ordinary comment prose and to sit LAST in the comment text (no closing
+ * delimiter follows it), so a regex can find it without knowing the
+ * preceding label's own shape: `new RegExp(PROVENANCE_TOKEN_PREFIX_ESCAPED +
+ * "[0-9a-f]{64}$")`. Exported from here, not `anno-join.ts`, because the
+ * digest and the prefix that names it belong to the same module as
+ * `memmapDigest()` itself.
+ */
+export const PROVENANCE_TOKEN_PREFIX = "[memmap-sha256:";
+
+/** WHICH of the three steps decided a selection, or `unique` when only one
+ * entry contained the address at all. `AUTO-02` names two steps
+ * (narrowest-range-wins, then the `sym` tie-break); D-37-10 adds a third,
+ * because the phase's own headline `$D020` example is NOT resolved by the
+ * first two -- MEASURED at plan time, its two 1-byte contenders both lack a
+ * `sym`. Reported rather than left for a caller to infer, so a test (and
+ * plan 37-04's controls) can assert WHICH rule decided, not merely what it
+ * decided. */
+export type MemmapTieBreak = "unique" | "width" | "symbol" | "order";
+
+/** What `selectMemmapEntry()` returns for a unique or a resolved-tie hit.
+ * `contenderCount` is the number of containing entries the scan considered,
+ * so a caller can tell a unique hit from a resolved tie without re-running
+ * the scan itself. */
+export interface MemmapSelection {
+  entry: MemmapEntry;
+  width: number;
+  contenderCount: number;
+  tieBrokenBy: MemmapTieBreak;
+}
+
+/** Inclusive width of one entry: `end - start`. Named once so every step
+ * below computes it identically. */
+function inclusiveWidth(entry: MemmapEntry): number {
+  return entry.end - entry.start;
+}
+
+/**
+ * STEP ONE, WIDTH -- the whole of narrowest-range-wins. Prefers the smallest
+ * `end - start`; returns every entry tied at that minimum, since a single
+ * winner here is `unique`ly correct only when nothing else shares its width.
+ * Kept as its own named function (not folded into a single comparator) so
+ * plan 37-04's control -- "switch selection to first-match" -- is a single,
+ * small, textual replacement of exactly this step, per this plan's own
+ * `<read_first>` instruction.
+ */
+function narrowestWidthSurvivors(containing: readonly MemmapEntry[]): MemmapEntry[] {
+  let minWidth = Infinity;
+  for (const entry of containing) {
+    const width = inclusiveWidth(entry);
+    if (width < minWidth) minWidth = width;
+  }
+  return containing.filter((entry) => inclusiveWidth(entry) === minWidth);
+}
+
+/**
+ * STEP TWO, SYMBOL -- `AUTO-02`'s own tie-break. Among step one's survivors,
+ * prefers an entry carrying a non-empty `sym` over one that does not.
+ * D-37-11's `$0000` fixture (three equal-width contenders, exactly one
+ * carrying `sym: "D6510"`) is this step's own fixture. Returns every
+ * `sym`-carrying survivor when at least one exists, else returns every
+ * survivor unchanged (this step decided nothing -- step three must run).
+ */
+function symbolSurvivors(survivors: readonly MemmapEntry[]): MemmapEntry[] {
+  const withSym = survivors.filter((entry) => typeof entry.sym === "string" && entry.sym.length > 0);
+  return withSym.length > 0 ? withSym : survivors.slice();
+}
+
+/**
+ * STEP THREE, ORDER -- D-37-10. Among step two's survivors, the entry
+ * appearing FIRST in `memmap.json`'s own `entries` array wins. Stated
+ * explicitly, rather than left to whatever order a scan happened to
+ * produce, because the phase's own headline `$D020` example needs it: two
+ * 1-byte contenders there are tied on width AND neither carries a `sym`, so
+ * without this named third rule the selection would be an unstated,
+ * scan-order accident that a later refactor could change silently. No
+ * `sort()` is used here -- a single linear scan over `entries` (the same
+ * order the caller supplied) finds the first survivor, which is cheaper and
+ * keeps this step's own mutation (plan 37-05's "reverse the tie-break")
+ * a one-line replacement rather than a sort-comparator edit.
+ */
+function orderWinner(survivors: readonly MemmapEntry[], entries: readonly MemmapEntry[]): MemmapEntry {
+  for (const entry of entries) {
+    if (survivors.includes(entry)) return entry;
+  }
+  // Unreachable: `survivors` is always drawn from `entries` by reference, so
+  // the scan above always finds one before falling through.
+  return survivors[0]!;
+}
+
+/**
+ * The THREE-DEEP selection order (D-37-10): narrowest-containing-range,
+ * then the `sym` tie-break (`AUTO-02`), then -- because those two do not
+ * resolve every real tie in the committed `memmap.json` -- the stated
+ * residual rule of "first in `entries` order". Collects every entry whose
+ * inclusive `[start, end]` contains `address`; returns `undefined` if none
+ * does. `tieBrokenBy` names WHICH step decided, so a caller (and plan
+ * 37-04's controls) can tell width-decided from symbol-decided from
+ * order-decided, not merely infer it from the winning entry's own shape.
+ */
+export function selectMemmapEntry(address: number, entries: readonly MemmapEntry[] = loadMemmap()): MemmapSelection | undefined {
+  const containing: MemmapEntry[] = [];
+  for (const entry of entries) {
+    if (address < entry.start || address > entry.end) continue;
+    containing.push(entry);
+  }
+  const contenderCount = containing.length;
+  if (contenderCount === 0) return undefined;
+  if (contenderCount === 1) {
+    const entry = containing[0]!;
+    return { entry, width: inclusiveWidth(entry), contenderCount, tieBrokenBy: "unique" };
+  }
+
+  const widthSurvivors = narrowestWidthSurvivors(containing);
+  if (widthSurvivors.length === 1) {
+    const entry = widthSurvivors[0]!;
+    return { entry, width: inclusiveWidth(entry), contenderCount, tieBrokenBy: "width" };
+  }
+
+  const symSurvivors = symbolSurvivors(widthSurvivors);
+  if (symSurvivors.length === 1) {
+    const entry = symSurvivors[0]!;
+    return { entry, width: inclusiveWidth(entry), contenderCount, tieBrokenBy: "symbol" };
+  }
+
+  const entry = orderWinner(symSurvivors, entries);
+  return { entry, width: inclusiveWidth(entry), contenderCount, tieBrokenBy: "order" };
+}
+
+/** One hand-maintained bank-conditional range: its meaning depends on the
+ * processor port's bits #0-#2 at `$0001`. */
+export interface BankConditionalRange {
+  start: number;
+  end: number;
+  why: string;
+}
+
+/**
+ * The three inclusive ranges whose interpretation depends on the processor
+ * port, HAND-MAINTAINED rather than derived from `memmap.json` (37-RESEARCH.md
+ * Pitfall 2): only 6 of 959 entries even mention the condition in free-text
+ * `desc`, and there is no structured bank-condition field to scan instead.
+ * Nothing in THIS module branches on this list -- a later plan's bank-decode
+ * logic does. Landed here so the list has one home rather than being
+ * reinvented per caller.
+ */
+export const BANK_CONDITIONAL_RANGES: readonly BankConditionalRange[] = Object.freeze([
+  {
+    start: 0xa000,
+    end: 0xbfff,
+    why: "BASIC ROM when banked in, otherwise RAM (bits #0-#2 of $0001 select between them).",
+  },
+  {
+    start: 0xd000,
+    end: 0xdfff,
+    why: "I/O area, Character ROM, or RAM depending on $0001 bits #0-#2 -- the canonical three-way case.",
+  },
+  {
+    start: 0xe000,
+    end: 0xffff,
+    why: "KERNAL ROM when banked in, otherwise RAM (bits #0-#2 of $0001 select between them).",
+  },
+]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henols/vice-mcp",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "VICE emulator MCP server for C64 reverse-engineering: a stdio MCP server that proxies vice tools to a host VICE MCP server.",
   "type": "module",
   "bin": {
@@ -9,23 +9,24 @@
   "main": "vice-proxy.ts",
   "files": [
     "vice-proxy.ts",
-    "vice.ts",
-    "vice-sync.ts",
-    "vice-probe.ts",
+    "vice-errors.ts",
     "vice-broker-client.ts",
+    "host-tool-client.ts",
     "version.ts",
     "stock-protocol.ts",
     "stock-connect.ts",
+    "text-protocol.ts",
+    "text-connect.ts",
+    "text-tools.ts",
+    "channel-lock.ts",
     "containerpath.ts",
     "hostpath.ts",
     "repo-root.ts",
     "install-resources.ts",
     "incident-record.ts",
-    "refresh-manifest.ts",
     "build.ts",
     "container-guard.mts",
     "backend-detect.mts",
-    "capability-registry.ts",
     "stock-dispatch.ts",
     "stock-derived.ts",
     "stock-handler.ts",
@@ -44,6 +45,12 @@
     "disasm-opcodes.ts",
     "disasm-decoder.ts",
     "disasm-renderer.ts",
+    "textmon-memmap.ts",
+    "textmon-cpuhistory.ts",
+    "textmon-backtrace.ts",
+    "textmon-profile.ts",
+    "textmon-registers.ts",
+    "text-capability-probe.ts",
     "stock-memory-search.ts",
     "stock-symbols.ts",
     "stock-vicii.ts",
@@ -51,9 +58,9 @@
     "stock-sprites.ts",
     "stock-timing.ts",
     "stock-run-until.ts",
+    "stock-reproducible-run.ts",
     "stock-diagnose.ts",
     "stock-recycle.ts",
-    "anno-d64.ts",
     "anno-cli.ts",
     "anno-symbols.ts",
     "anno-regbits-gen.ts",
@@ -63,18 +70,30 @@
     "anno-confidence.ts",
     "anno-memmap-render.ts",
     "anno-export-asm.ts",
+    "anno-provenance-ledger.ts",
     "anno-coverage.ts",
     "block-class.ts",
+    "anno-hazard-report.ts",
+    "evid-reconcile.ts",
+    "evid-ingest.ts",
     "prg-image.ts",
+    "vsf-slice.ts",
+    "capture-predicate.ts",
+    "stop-oracle.ts",
     "anno-types.ts",
     "anno-index.ts",
     "anno-store.ts",
+    "anno-store-export.ts",
     "anno-tools.ts",
     "anno-derive.ts",
     "anno-details.ts",
     "anno-register.ts",
+    "anno-import.ts",
+    "anno-join.ts",
+    "anno-bank.ts",
+    "anno-graphics.ts",
+    "memmap-lookup.ts",
     "resources",
-    "tools-manifest.json",
     "tools-manifest.stock.json",
     "README.md",
     "THIRD-PARTY-NOTICES.md"

package/prg-image.ts

@@ -36,8 +36,7 @@
 // census) imports `decodeRawData`, `parsePrg` and `flatImageOrigin` for the
 // same three facts on the CLI's route. `scripts/check-npm-packages.mjs` walks
 // that closure over `files[]` and fails the pack the moment a reachable module
-// sits outside the listed set, exactly as `anno-d64.ts`'s own header records
-// for the same reason.
+// sits outside the listed set.
 //
 // CORRECTED 2026-08-30 (WR-07, plan 29-16). This paragraph previously named
 // `anno-cli.ts` as importing `parsePrg` and `flatImageOrigin` and rested the

package/repo-root.ts

@@ -182,11 +182,95 @@ export function repoRoot({ from = HERE, env = process.env, exists = existsSync }
   return resolve(from, "..", "..", "..");
 }
 
+/** The ONE definition of the tool-written root every writer in this codebase
+ * ultimately derives its location from (D-33, 2026-09-08 clean-break
+ * consolidation): `join(repoRoot(...), ".c64-re-tools")`.
+ *
+ * CORRECTED 2026-09-08 (gap `G-40-1`; see
+ * .planning/notes/ghidra-dot-path-check-semantics.md): this comment used to
+ * claim (a) that the Ghidra runs directory was among the writers resolving
+ * through THIS function, and (b) that the literal string below had exactly
+ * one non-comment occurrence in the codebase. Both were false when written,
+ * and neither was ever measured before being written down. The corrected
+ * picture:
+ *
+ *   - FIVE files call `toolsDir()`/`supervisorDir()` directly, across FOUR
+ *     distinct subdirectories: incident-record.ts (`incidents`),
+ *     stock-paths.ts (`snapshots`), vice-proxy.ts (`bin`, reading back the
+ *     deployed launcher path), and vice.ts + vice-broker-client.ts, both via
+ *     `supervisorDir()` (`supervisor`, the broker state directory -- one
+ *     writer, two readers).
+ *   - FOUR files cannot import this container-side module at all, so each
+ *     joins `".c64-re-tools"` with its own trailing segment(s) directly,
+ *     matching this function's shape by CONVENTION, never by shared code:
+ *     install-resources.ts's `installTargetDir()` (`bin` -- module-cycle
+ *     avoidance, since THIS file's own bottom-of-module call invokes it),
+ *     vice-broker.mts's `parseArgs()` state-dir fallback (`supervisor` --
+ *     host-bound, compiled separately by build.ts), host-tool.mts's
+ *     `oracle.run` scratch directory (`runs/oracle` -- host-bound), and
+ *     ghidra-project.mts's `ghidraRunsRoot()`/`ghidraRunsRealRoot()`
+ *     (`runs/ghidra` -- host-bound, reached through a symlinked alias
+ *     handle, see below). Every one of these four must keep its literal
+ *     equal to `join(toolsDir(...), <same segments>)`, by convention, or the
+ *     two halves of this codebase silently disagree on where the root is.
+ *
+ * The Ghidra runs root is emphatically NOT, and never was, one of the five
+ * files that call this function directly -- it is host-bound
+ * (ghidra-project.mts) and cannot import this file at all.
+ *
+ * The literal string ".c64-re-tools" therefore has exactly 6 non-comment
+ * occurrences in this codebase, across 5 files. repo-root.test.ts's census
+ * gate reads BOTH the count and this file list straight out of this
+ * sentence and the bullet list below -- never duplicated by hand a second
+ * time in the test -- and compares both against the real tree, with a
+ * planted-violation control proving the comparison predicate actually
+ * fires. That is the mechanism that stops this specific claim going false
+ * again (threat `T-40-10-02`):
+ *   - repo-root.ts -- this definition, the line below (1)
+ *   - install-resources.ts -- `installTargetDir()`'s `bin` join (1)
+ *   - vice-broker.mts -- `parseArgs()`'s state-dir fallback, BOTH branches
+ *     of one ternary on the same line (2)
+ *   - ghidra-project.mts -- `GHIDRA_RUNS_HANDLE_TARGET`, the alias handle's
+ *     relative symlink target (1)
+ *   - host-tool.mts -- `oracle.run`'s scratch-directory join (1)
+ *
+ * The Ghidra alias handle: a non-dotted sibling of this root
+ * (`<repoRoot>/c64-re-tools`, no leading dot), a symlink whose RELATIVE
+ * target is this root's own directory name, minted host-side by the broker
+ * at startup (vice-broker.mts) and re-asserted, idempotently, as a
+ * precondition by ghidra-project.mts's `ensureGhidraRunsHandle()` on every
+ * resolve -- refused BY NAME, never repaired, when something unexpected
+ * already sits at the handle path. It exists because Ghidra's own
+ * project-location refusal binds the ABSOLUTIZED path argument it is
+ * handed (`ProjectLocator` calls `java.io.File.getAbsolutePath()`, never
+ * `getCanonicalPath()` -- MEASURED from the class's own bytecode -- so it
+ * absolutizes a relative argument but does not resolve a symlink), so a
+ * tool that refuses a dot-prefixed segment in the path it is HANDED can
+ * still be pointed, indirectly, at bytes that live physically inside this
+ * one root. The superseded method that produced the original overstated
+ * claim was running this project's OWN dot-segment-refusal check
+ * (`hasDotPrefixedSegment()`) against a synthetic string -- which observes
+ * this project, never Ghidra. See
+ * .planning/notes/ghidra-dot-path-check-semantics.md for the full live
+ * measurement against real Ghidra 12.1.3.
+ *
+ * This is a clean break, not a migration: no code path falls back to any of
+ * the five previous locations when the new one is absent, and there is no
+ * opt-back-in environment variable. A pre-existing tree at one of the old
+ * locations is simply left on disk, unread, for the user to delete by hand.
+ * `VICE_POOL_DIR` / `VICE_EPOCH_FILE` / `VICE_SUPERVISOR_DIR` /
+ * `VICE_INCIDENTS_DIR` are unaffected by this move -- they still override
+ * their respective resolved default, exactly as before; only the DEFAULT
+ * moved. */
+export function toolsDir(opts: RepoRootOptions = {}): string {
+  return join(repoRoot(opts), ".c64-re-tools");
+}
+
 /** The one shared directory name every module in this skill reads/writes
- * host-synchronised state through -- `join(repoRoot(...), ".vice-supervisor")`,
- * so the literal directory name also has exactly one definition. */
+ * host-synchronised state through -- `join(toolsDir(...), "supervisor")`,
+ * a subdirectory of the single tool-written root `toolsDir()` owns. */
 export function supervisorDir(opts: RepoRootOptions = {}): string {
-  return join(repoRoot(opts), ".vice-supervisor");
+  return join(toolsDir(opts), "supervisor");
 }
 
 // Fires once per process, on whatever entry point happens to import THIS