@henols/vice-mcp 0.2.1 → 0.2.3

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.1",
+  "version": "0.2.3",
   "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,30 +58,48 @@
     "stock-sprites.ts",
     "stock-timing.ts",
     "stock-run-until.ts",
+    "stock-reproducible-run.ts",
     "stock-diagnose.ts",
     "stock-recycle.ts",
-    "r2000-launch.ts",
-    "r2000-project.ts",
-    "r2000-d64.ts",
-    "r2000-cli.ts",
-    "r2000-verify.ts",
-    "r2000-mcp-client.ts",
-    "r2000-tools.ts",
-    "r2000-symbols.ts",
-    "r2000-regbits-gen.ts",
-    "r2000-regbits.json",
-    "r2000-enum-gen.ts",
-    "r2000-acme-ident.ts",
-    "r2000-confidence.ts",
-    "r2000-memmap-render.ts",
+    "anno-cli.ts",
+    "anno-symbols.ts",
+    "anno-regbits-gen.ts",
+    "anno-regbits.json",
+    "anno-enum-gen.ts",
+    "anno-acme-ident.ts",
+    "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"
   ],
   "engines": {
-    "node": ">=22.18.0"
+    "node": ">=24.0.0"
   },
   "publishConfig": {
     "access": "public"
@@ -87,7 +112,7 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/henols/c64-re-tools.git",
-    "directory": ".claude/mcp/vice"
+    "directory": "src/mcp/vice"
   },
   "homepage": "https://github.com/henols/c64-re-tools#readme",
   "bugs": {

package/prg-image.ts

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+// prg-image.ts -- the ONE authoritative place in this repo holding pure C64
+// image byte-layout knowledge: how a `.prg` splits into a load address plus a
+// body, what load address a flat 64K RAM capture has, and how to invert a
+// gzip-then-base64 payload back into bytes. These are facts about C64 file
+// formats and about one payload encoding -- they depend on no external
+// analyser, no emulator, and no annotation store, so they belong in a module
+// none of those can take with them when it goes away.
+//
+// This module performs NO filesystem and NO network I/O: every function takes
+// bytes (or a base64 string) and returns values. Callers obtain and persist
+// the bytes themselves. That is the same claim `anno-project.ts` makes about
+// itself, and it must remain true of both files now that the split has
+// happened -- a structural test in `prg-image.test.ts` asserts it from this
+// module's own source rather than trusting this paragraph.
+//
+// WHY THIS FILE EXISTS SEPARATELY: these three functions used to live in
+// `anno-project.ts`, the module that builds a `.regen2000proj` file for the
+// the external analyser analyser. They were never about that analyser. One of them
+// is imported statically by the byte-coverage census (`anno-coverage.ts`), a
+// capability that must keep working independently of whether this repo still
+// drives that analyser at all -- so a census whose only route to a payload
+// decoder ran through analyser glue was one deletion away from breaking with
+// no announcement (SEAM-02). Extracting them under a name that carries no
+// analyser prefix removes that coupling outright instead of recording it as a
+// hazard to remember later. There is deliberately NO re-export left behind in
+// `anno-project.ts`: a compatibility shim would leave the coupling fully
+// intact while looking finished.
+//
+// THIS MODULE MUST BE LISTED IN `package.json`'s `files[]`. It is reachable
+// from the published entry point's import closure, and the STATIC route is
+// named here first because it is the stronger reachability claim: `anno-
+// tools.ts` -- the curated `anno_*` MCP tool surface -- imports `parsePrg` and
+// `flatImageOrigin` from here with a plain top-level import, and `vice-proxy.ts`
+// imports `anno-tools.ts` statically. `anno-coverage.ts` (the byte-coverage
+// 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.
+//
+// CORRECTED 2026-08-30 (WR-07, plan 29-16). This paragraph previously named
+// `anno-cli.ts` as importing `parsePrg` and `flatImageOrigin` and rested the
+// whole reachability claim on the DYNAMIC import that reaches that file. That
+// was doubly wrong: `anno-cli.ts` imported neither symbol (it imported
+// `decodeRawData` only), and it now imports nothing from here at all -- its
+// image decode delegates to `anno-coverage.ts`'s `loadProjectImage()`. A
+// stated reason for shipping a file has to be true or it is worse than absent.
+//
+// WHAT NOT TO DO:
+//   - Never give any function here a filesystem PATH parameter. They take byte
+//     arrays and a base64 string, which is precisely what keeps path traversal
+//     out of this module's threat surface entirely. Path resolution belongs to
+//     the CLI. For the same reason this module imports nothing from either of
+//     this repo's two host/container path-translation seams; that absence is
+//     asserted structurally by `hostpath-consumers.test.ts`, not merely stated
+//     here.
+//   - Never relax, reword or reorder either input refusal below. The concrete
+//     incident: a 4096-byte flat `.raw` capture fell through to the `.prg`
+//     parser, whose first two bytes become the load address, so a truncated
+//     capture silently "bootstrapped" with an origin read backwards out of its
+//     own payload bytes and exited zero -- every downstream address wrong, no
+//     diagnostic. The refusal message texts are a user-visible contract: both
+//     `anno-tools.ts`'s `loadImage()` and `anno-coverage.ts`'s
+//     `loadProjectImage()` prefix them with the caller's own image path, and
+//     tests on both routes match on their wording, so a reworded message
+//     breaks a test for a reason that looks unrelated. (Attribution corrected
+//     2026-08-30, WR-07: this line named `anno-cli.ts`, which prefixed them
+//     through a `bootstrap` verb deleted by D-14 on 2026-08-29.)
+//   - Never add the dispatch ORDER discipline here. Which check runs first for
+//     a given input extension belongs to the two loaders that own it --
+//     `anno-tools.ts`'s `loadImage()` for the MCP tool surface and
+//     `anno-coverage.ts`'s `loadProjectImage()` for the coverage verb. Both
+//     dispatch `.raw`/`.bin` by extension BEFORE any length check, so that
+//     `flatImageOrigin`'s named refusal is always reachable for those two
+//     extensions. Neither function below may start inferring what kind of
+//     image it was handed.
+
+import { gunzipSync } from "node:zlib";
+
+/**
+ * Parses a `.prg` file: a little-endian 2-byte load address followed by the
+ * payload bytes. This is the C64 program-file convention every C64 loader
+ * (and this project's own `acme-build` output) already follows.
+ */
+export function parsePrg(bytes: Uint8Array): { origin: number; body: Uint8Array } {
+  if (bytes.length < 3) {
+    throw new Error(
+      `parsePrg: input is ${bytes.length} byte(s) -- a .prg needs at least 3 bytes (2-byte load address plus at least 1 payload byte)`,
+    );
+  }
+  const origin = bytes[0]! | (bytes[1]! << 8);
+  const body = bytes.subarray(2);
+  return { origin, body };
+}
+
+/**
+ * Returns the load address (`0`) for a flat 64K RAM capture, and throws for
+ * anything else. Flat 64K is in scope because `ANNO-06` names it directly
+ * and it is exactly the shape `c64-ram-capture` already produces (D-03) --
+ * this function does not attempt to support any other flat-image size.
+ */
+export function flatImageOrigin(bytes: Uint8Array): number {
+  if (bytes.length !== 65536) {
+    throw new Error(
+      `flatImageOrigin: input is ${bytes.length} byte(s) -- a flat 64K capture must be exactly 65536 bytes`,
+    );
+  }
+  return 0;
+}
+
+/**
+ * The inverse of a gzip-then-base64 payload encoding: base64-decode, then
+ * gunzip. Exported so tests can prove the payload round-trips exactly,
+ * rather than asserting against an opaque blob.
+ */
+export function decodeRawData(base64: string): Uint8Array {
+  return gunzipSync(Buffer.from(base64, "base64"));
+}