@henols/vice-mcp 0.1.12 → 0.2.1

package/THIRD-PARTY-NOTICES.md

@@ -75,6 +75,29 @@ package**, so ACME's licence does not attach to anything shipped. ACME never
 appears in `.claude/mcp/vice/package.json`'s `files[]`, `dependencies`, or
 `devDependencies` — it is an apt/CI-installed tool, never an npm package.
 
+## Build/CI tools — not incorporated: regenerator2000
+
+regenerator2000 is invoked as an **external CLI subprocess** (Phase 10's
+`R2000-09` bootstrap and `R2000-06` reassembly proof) against a real,
+locally-installed `regenerator2000` binary. **No regenerator2000 source,
+data table, or output is included in this repository or in either
+published package**, so its licence does not attach to anything shipped.
+
+Its licence is **`MIT OR Apache-2.0`** — dual, at the user's option —
+confirmed from the crate's own crates.io licence field, with both
+`LICENSE-MIT` and `LICENSE-APACHE` shipping in the crate. (Do not read this
+as Apache-2.0 alone: that stale, single-licence claim is what `R2000-03`'s
+own requirement text and `.planning/notes/regenerator2000-integration.md`
+still carried before Phase 10 corrected it here.)
+
+Verified version `0.9.20`, published 2026-07-11 by `ricardoquesada`
+(matching the linked GitHub repository owner), checked 2026-08-20 — so this
+provenance claim is re-checkable against a specific release.
+
+regenerator2000 never appears in `.claude/mcp/vice/package.json`'s
+`files[]`, `dependencies`, or `devDependencies` — it is a `cargo
+install`-provided tool, never an npm package.
+
 ## Explicitly NOT a source: VICE
 
 VICE is GPL-2 and this repository is MIT. **No opcode fact, protocol

package/backend-detect.mts

@@ -196,8 +196,33 @@ export interface BackendCacheRecord {
    * quad; only a live VICE_INFO reply over an established connection can. */
   versionQuad?: string;
   cpuHistoryAvailable?: boolean;
+  /** CR-01 (07-REVIEW.md re-review): the CLIENT-side schema version that
+   * produced `cpuHistoryAvailable`. The version quad answers "is this the
+   * same VICE build?"; it cannot answer "was the code that decided this
+   * capability the code running now?". Without this field a capability
+   * answer derived by a buggy parser was un-invalidatable by any code
+   * change -- only a VICE upgrade could clear it. A record whose value
+   * differs from CAPABILITY_SCHEMA_VERSION (including ABSENT, which is
+   * every record written before this field existed) reads back as `stale`.
+   * Bump CAPABILITY_SCHEMA_VERSION in the same commit as any change to how
+   * a capability is probed or decoded. */
+  capabilitySchema?: number;
 }
 
+/** The client-side capability-decision schema version stamped into every
+ * capability record this module writes (see BackendCacheRecord's own field
+ * comment). BUMP THIS whenever the client's capability probing or the
+ * decoding it depends on changes, so records decided by the older code are
+ * re-probed instead of trusted.
+ *
+ * History:
+ *   1 -- plan 02-08's original probe (implicit; never written to disk).
+ *   2 -- CR-01 fix: decode failures are no longer persisted at all, and the
+ *        CPUHISTORY_GET body layout was corrected (07-12). Every record
+ *        written before this constant existed lacks the field and is
+ *        therefore stale, which is exactly the intent. */
+export const CAPABILITY_SCHEMA_VERSION = 2;
+
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -243,6 +268,7 @@ function readCacheRecord(supervisorDir: string): BackendCacheRecord | null {
   };
   if (typeof parsed.versionQuad === "string") record.versionQuad = parsed.versionQuad;
   if (typeof parsed.cpuHistoryAvailable === "boolean") record.cpuHistoryAvailable = parsed.cpuHistoryAvailable;
+  if (typeof parsed.capabilitySchema === "number") record.capabilitySchema = parsed.capabilitySchema;
   return record;
 }
 
@@ -511,11 +537,23 @@ export function resolvedBackend(deps: ResolvedBackendDeps = {}): ResolvedBackend
 export interface CapabilityRecordResult {
   versionQuad?: string;
   cpuHistoryAvailable?: boolean;
-  /** True only when `observedVersionQuad` was given AND differs from the
-   * stored value -- the caller has just seen a DIFFERENT VICE build than
-   * whatever wrote this record (the binary was swapped since the last
-   * capability determination), so the stored answer cannot be trusted and
-   * must be re-determined rather than reused. */
+  /** The client-side schema version stamped on the record that was read
+   * (absent for any record written before CAPABILITY_SCHEMA_VERSION
+   * existed). Surfaced so a caller can log WHY a record was stale. */
+  capabilitySchema?: number;
+  /** True when the caller has just seen a DIFFERENT VICE build than
+   * whatever wrote this record (`observedVersionQuad` was given AND differs
+   * from the stored value -- the binary was swapped since the last
+   * capability determination), OR when the record's `capabilitySchema` is
+   * not the CAPABILITY_SCHEMA_VERSION this client decides capabilities
+   * with. Either way the stored answer cannot be trusted and must be
+   * re-determined rather than reused.
+   *
+   * CR-01 (07-REVIEW.md re-review) added the schema half: keying staleness
+   * on the version quad alone meant a capability answer decided by a buggy
+   * client parser survived every subsequent parser fix, and could only be
+   * cleared by upgrading VICE or hand-deleting a file under
+   * .vice-supervisor/ that nothing tells the user about. */
   stale: boolean;
 }
 
@@ -547,12 +585,20 @@ export function readCapabilityRecord(binPath: string, deps: CapabilityDeps = {})
   if (!existing || existing.resolvedPath !== resolvedPath) return null;
   if (existing.versionQuad === undefined && existing.cpuHistoryAvailable === undefined) return null;
 
-  const stale =
+  const versionMismatch =
     deps.observedVersionQuad !== undefined &&
     existing.versionQuad !== undefined &&
     existing.versionQuad !== deps.observedVersionQuad;
-
-  return { versionQuad: existing.versionQuad, cpuHistoryAvailable: existing.cpuHistoryAvailable, stale };
+  // CR-01: a record decided by a different client-side capability schema is
+  // as untrustworthy as one decided against a different binary. Absent
+  // counts as a mismatch -- that is every record written before the field
+  // existed, i.e. every record a possibly-broken parser could have written.
+  const schemaMismatch = existing.capabilitySchema !== CAPABILITY_SCHEMA_VERSION;
+  const stale = versionMismatch || schemaMismatch;
+
+  const result: CapabilityRecordResult = { versionQuad: existing.versionQuad, cpuHistoryAvailable: existing.cpuHistoryAvailable, stale };
+  if (existing.capabilitySchema !== undefined) result.capabilitySchema = existing.capabilitySchema;
+  return result;
 }
 
 /** Attaches `{ versionQuad, cpuHistoryAvailable }` to the EXISTING backend
@@ -591,5 +637,9 @@ export function writeCapabilityRecord(
     probedAt: existing.probedAt,
     versionQuad: capability.versionQuad,
     cpuHistoryAvailable: capability.cpuHistoryAvailable,
+    // CR-01: stamp WHICH client decided this, so a later parser change
+    // invalidates it. Never accept this from the caller -- it describes this
+    // module's own code, not anything the caller observed.
+    capabilitySchema: CAPABILITY_SCHEMA_VERSION,
   });
 }

package/capability-registry.ts

@@ -0,0 +1,388 @@
+// capability-registry.ts
+//
+// WHY THIS FILE EXISTS (BACK-05): today, a tool name the ACTIVE backend does
+// not advertise falls straight through vice-proxy.ts's CallToolRequestSchema
+// override to its generic `Unknown tool: ${name}` fallback -- the exact same
+// message a genuine typo gets. That is indistinguishable and unhelpful: a
+// caller cannot tell "you misspelled this" from "this tool exists, but only
+// on the other backend, for this specific reason." This module is the ONE
+// authoritative place holding that per-backend capability data -- names,
+// reason categories, reason text, and which backend actually provides each
+// one -- so a future call site (the runtime refusal wired in plan 08-02, the
+// generated support table in plan 08-03, the skill-text lint in plan 08-04)
+// reads exactly one source rather than re-deriving or hand-copying it.
+//
+// WHAT NOT TO DO: do not hand-maintain a second copy of this data anywhere
+// else in the repo (D-E; see CLAUDE.md's "re-deriving a cross-cutting seam
+// locally" anti-pattern). If a consumer needs this data in a different
+// shape, import CAPABILITY_REGISTRY and reshape it there -- never re-type
+// the 26 entries or their reasons from memory.
+//
+// SECURITY POSTURE: this module is a READ-ONLY MESSAGE-TEXT LOOKUP and is
+// NEVER an authorization boundary. DENY_LIST (vice.ts) remains the only
+// refusal in this tree that is a security control; that check runs first, at
+// every call site, and this module never overrides or duplicates it. Every
+// string held here is already public: it names only information already
+// published in docs/stock-vice-parity.md and this public repository -- no
+// credential, no secret, no host, no port, no path, and no tool name that is
+// not already present in one of the two shipped manifests
+// (tools-manifest.json, tools-manifest.stock.json).
+//
+// This is the exact shape vice.ts's DENY_LIST / denyListRefusalMessage()
+// already established: one exported readonly array, one exported
+// message-rendering function, keyed by hazard/reason shape rather than one
+// wording reused for every entry -- because telling a caller the wrong
+// reason shape for what is otherwise the same permanent refusal invites a
+// pointless retry (that function's own doc comment makes the identical
+// point).
+//
+// EXCLUDED, DELIBERATELY (see docs/stock-vice-parity.md and
+// 08-RESEARCH.md's "Capability Delta Registry"):
+//   - "vice_diagnose" and "vice_recycle" are NOT capability gaps: they are
+//     synthetic, proxy-local tools registered on BOTH backends by
+//     vice-proxy.ts's buildBackendAwareTool()/resolveAdvertisedToolDefinition()
+//     synthetic-registration call sites, never listed in either raw manifest
+//     JSON file. A naive set-difference over the two manifests misclassifies
+//     them as a divergence; they are not one, and including them here would
+//     be a factual error, not merely an omission.
+//   - "initialize", "notifications_initialized", "tools_call", "tools_list"
+//     are already refused by vice.ts's DENY_LIST, which runs strictly BEFORE
+//     any capability-registry lookup and owns a different hazard shape
+//     entirely (confused-deputy bypass, not a missing capability). They must
+//     keep being owned there, not duplicated here.
+//
+// This module imports nothing at runtime -- the only import is a type-only
+// import of ViceBackend, which is erased by Node's type-stripping -- so it
+// has no transport, no filesystem, and no process dependency of its own.
+import type { ViceBackend } from "./backend-detect.mts";
+
+/**
+ * Three reason categories, matching the distinctions the project's own docs
+ * already draw (docs/stock-vice-parity.md SS A/B):
+ *   - "hardware": no 1:1 opcode can ever exist because of a hardware or
+ *     firmware property (a write-only register, per-read recomputation, no
+ *     monitor command for a physical line). Permanent; nothing to build.
+ *   - "descoped": theoretically buildable client-side (an opcode or
+ *     equivalent already exists) but cut from v0.2.0 scope because no
+ *     shipped skill calls it.
+ *   - "stock-only-gain": the reverse direction -- stock has a native opcode
+ *     the fork's custom HTTP API never exposed an equivalent RPC for.
+ */
+export type CapabilityCategory = "hardware" | "descoped" | "stock-only-gain";
+
+/**
+ * One row of capability data. `providedBy` names the backend that DOES have
+ * the capability (never the backend refusing it). `reason` is one sentence
+ * of user-facing prose ending in a full stop -- no planning identifier
+ * (BACK-05, SKILL-01, DERIV-*, SHOT-*, GAIN-*, "Phase N") belongs in this
+ * field; those are internal routing annotations, not something a caller
+ * calling a tool by name should ever see. `alternative`, when present, names
+ * a concrete route that exists on the OTHER backend today -- omit it rather
+ * than inventing one where none exists.
+ */
+export interface CapabilityEntry {
+  name: string;
+  category: CapabilityCategory;
+  providedBy: ViceBackend;
+  reason: string;
+  alternative?: string;
+}
+
+const KEYBOARD_ALTERNATIVE =
+  "vice_keyboard_type / vice_keyboard_petscii inject text through the KERNAL keyboard buffer, " +
+  "and vice_joystick_set covers most in-game input -- but a program polling $DC00/$DC01 directly " +
+  "will not see buffer injection.";
+
+/**
+ * The 26-entry capability delta: every tool one backend advertises that the
+ * other genuinely does not, after excluding registration artifacts
+ * (vice_diagnose/vice_recycle) and DENY_LIST's own four meta-tools -- see
+ * the header comment above and 08-RESEARCH.md's "Capability Delta Registry"
+ * for the full accounting this array is derived from.
+ */
+export const CAPABILITY_REGISTRY: readonly CapabilityEntry[] = [
+  // --- hardware (6), providedBy: fork -------------------------------------
+  {
+    name: "vice_sid_get_state",
+    category: "hardware",
+    providedBy: "fork",
+    reason:
+      "SID's $D400-$D418 registers are write-only in hardware, and the binary monitor exposes " +
+      "no SID read command.",
+  },
+  {
+    name: "vice_keyboard_matrix",
+    category: "hardware",
+    providedBy: "fork",
+    reason:
+      "The binary monitor's KEYBOARD_FEED (0x72) only injects PETSCII buffer text; the emulator " +
+      "recomputes CIA port B from its own keyboard array on every read, so there is no wire " +
+      "command that can drive the raw matrix.",
+    alternative: KEYBOARD_ALTERNATIVE,
+  },
+  {
+    name: "vice_keyboard_restore",
+    category: "hardware",
+    providedBy: "fork",
+    reason:
+      "RESTORE pulses the NMI line directly; it is not part of the keyboard matrix, and " +
+      "KEYBOARD_FEED has no way to produce it.",
+    alternative: KEYBOARD_ALTERNATIVE,
+  },
+  {
+    name: "vice_keyboard_chord",
+    category: "hardware",
+    providedBy: "fork",
+    reason:
+      "KEYBOARD_FEED injects a whole string at a time; it has no primitive for holding multiple " +
+      "keys down together for a span of frames.",
+    alternative: KEYBOARD_ALTERNATIVE,
+  },
+  {
+    name: "vice_keyboard_key_press",
+    category: "hardware",
+    providedBy: "fork",
+    reason:
+      "KEYBOARD_FEED has no hold/release primitive -- it injects a complete string, not an " +
+      "individual key-down event.",
+    alternative: KEYBOARD_ALTERNATIVE,
+  },
+  {
+    name: "vice_keyboard_key_release",
+    category: "hardware",
+    providedBy: "fork",
+    reason:
+      "KEYBOARD_FEED has no hold/release primitive -- it injects a complete string, not an " +
+      "individual key-up event.",
+    alternative: KEYBOARD_ALTERNATIVE,
+  },
+
+  // --- descoped (18), providedBy: fork -------------------------------------
+  {
+    name: "vice_disk_detach",
+    category: "descoped",
+    providedBy: "fork",
+    reason:
+      "No detach opcode exists on the stock binary monitor; attaching a different disk image " +
+      "covers the same workflow.",
+  },
+  {
+    name: "vice_disk_read_sector",
+    category: "descoped",
+    providedBy: "fork",
+    reason:
+      "Reading a sector would require parsing the .d64 file client-side rather than calling a " +
+      "live-drive opcode, and no shipped skill calls it.",
+  },
+  {
+    name: "vice_display_screenshot",
+    category: "descoped",
+    providedBy: "fork",
+    reason:
+      "The client-side PNG encoder for the INDEXED8 framebuffer DISPLAY_GET returns was descoped " +
+      "because no shipped skill calls it.",
+  },
+  {
+    name: "vice_display_get_dimensions",
+    category: "descoped",
+    providedBy: "fork",
+    reason: "Descoped alongside vice_display_screenshot -- no shipped skill calls it.",
+  },
+  {
+    name: "vice_backtrace",
+    category: "descoped",
+    providedBy: "fork",
+    reason: "No shipped skill calls it.",
+  },
+  {
+    name: "vice_checkpoint_group_add",
+    category: "descoped",
+    providedBy: "fork",
+    reason: "No shipped skill calls any checkpoint-group tool.",
+  },
+  {
+    name: "vice_checkpoint_group_create",
+    category: "descoped",
+    providedBy: "fork",
+    reason: "No shipped skill calls any checkpoint-group tool.",
+  },
+  {
+    name: "vice_checkpoint_group_list",
+    category: "descoped",
+    providedBy: "fork",
+    reason: "No shipped skill calls any checkpoint-group tool.",
+  },
+  {
+    name: "vice_checkpoint_group_toggle",
+    category: "descoped",
+    providedBy: "fork",
+    reason: "No shipped skill calls any checkpoint-group tool.",
+  },
+  {
+    name: "vice_checkpoint_set_ignore_count",
+    category: "descoped",
+    providedBy: "fork",
+    reason:
+      "No native wire ignore-count exists; the only implementation would require resuming the " +
+      "machine on every ignored hit, which the no-unrequested-resume policy forbids. " +
+      "CHECKPOINT_INFO's reply still reports an existing ignore count read-only.",
+  },
+  {
+    name: "vice_cia_set_state",
+    category: "descoped",
+    providedBy: "fork",
+    reason:
+      "The write half of a tool whose read half already ships on stock; no shipped skill calls " +
+      "the write half.",
+  },
+  {
+    name: "vice_vicii_set_state",
+    category: "descoped",
+    providedBy: "fork",
+    reason:
+      "The write half of a tool whose read half already ships on stock; no shipped skill calls " +
+      "the write half.",
+  },
+  {
+    name: "vice_sprite_set",
+    category: "descoped",
+    providedBy: "fork",
+    reason:
+      "The write half of a tool whose read half already ships on stock; no shipped skill calls " +
+      "the write half.",
+  },
+  {
+    name: "vice_memory_fill",
+    category: "descoped",
+    providedBy: "fork",
+    reason: "No shipped skill calls it.",
+  },
+  {
+    name: "vice_sid_set_state",
+    category: "descoped",
+    providedBy: "fork",
+    reason:
+      "SID writes work fine over MEM_SET at $D400-$D418 -- this is not a hardware loss, only " +
+      "reads are write-only in hardware. It is simply not implemented because no shipped skill " +
+      "calls it.",
+  },
+  {
+    name: "vice_machine_config_get",
+    category: "descoped",
+    providedBy: "fork",
+    reason:
+      "Full resource get/set access was descoped; the fork's tool is a hand-curated whitelist " +
+      "subset that never shipped on stock.",
+  },
+  {
+    name: "vice_machine_config_set",
+    category: "descoped",
+    providedBy: "fork",
+    reason:
+      "Full resource get/set access was descoped; the fork's tool is a hand-curated whitelist " +
+      "subset that never shipped on stock.",
+  },
+  {
+    name: "vice_joystick_tap",
+    category: "descoped",
+    providedBy: "fork",
+    reason:
+      "Requires running the machine for a measured hold-then-release interval, which depends on " +
+      "timing infrastructure; not yet built, and no shipped skill calls it.",
+  },
+
+  // --- stock-only-gain (2), providedBy: stock ------------------------------
+  {
+    name: "vice_execution_until_return",
+    category: "stock-only-gain",
+    providedBy: "stock",
+    reason: "The fork's custom HTTP API has no equivalent RPC; this is the native EXECUTE_UNTIL_RETURN opcode.",
+  },
+  {
+    name: "vice_registers_available",
+    category: "stock-only-gain",
+    providedBy: "stock",
+    reason: "The fork has no equivalent enumeration call; this is the native REGISTERS_AVAILABLE opcode.",
+  },
+];
+
+/**
+ * Plain name-keyed lookup over CAPABILITY_REGISTRY. `name` is untrusted
+ * `request.params.name` from the wire: it is used ONLY as an equality
+ * comparison value below. Never interpolate it into a path, a command, or
+ * anything executed.
+ */
+export function capabilityEntryFor(name: string): CapabilityEntry | undefined {
+  return CAPABILITY_REGISTRY.find((entry) => entry.name === name);
+}
+
+/**
+ * Renders the BACK-05 refusal for `name` on `activeBackend`, or `undefined`
+ * when there is nothing to refuse -- mirroring denyListRefusalMessage()'s
+ * keyed-by-hazard-shape contract (vice.ts).
+ *
+ * Returns `undefined` when:
+ *   - no registry entry exists for `name` (a genuinely unknown tool name --
+ *     a typo -- must still fall through to the generic "Unknown tool"
+ *     message at the call site, not this function's wording); or
+ *   - `entry.providedBy === activeBackend` (defensive: the active backend
+ *     already advertises this tool, so a miss here is a genuine
+ *     unknown-tool case, not a capability gap, and must not be
+ *     misclassified as one).
+ *
+ * Otherwise renders one of three wordings, selected by `entry.category`:
+ *   - "hardware": names the tool, states it is unrecoverable on
+ *     `activeBackend`, gives `entry.reason`, then names `entry.providedBy`
+ *     with the actionable `Set VICE_BACKEND=...`, then `entry.alternative`
+ *     when present. No "wait for a later phase" framing -- none is coming
+ *     for a hardware loss, but a stock route may still exist and must be
+ *     named here, since this is where the caller actually reads it.
+ *   - "descoped": names the tool, states it is not implemented on
+ *     `activeBackend`, gives `entry.reason`, then `entry.providedBy` and
+ *     `Set VICE_BACKEND=...`, then `entry.alternative` when present. The
+ *     literal token "unrecoverable" must NEVER appear in this wording: a
+ *     reader told "not supported" for both a hardware loss and a merely
+ *     unbuilt tool cannot tell which one is worth filing an issue about.
+ *   - "stock-only-gain": names the tool, states it is not implemented on the
+ *     fork backend specifically, gives `entry.reason`, then
+ *     `Set VICE_BACKEND=stock`.
+ */
+export function capabilityRefusalMessage(
+  name: string,
+  activeBackend: ViceBackend,
+): string | undefined {
+  const entry = capabilityEntryFor(name);
+  if (!entry) return undefined;
+  if (entry.providedBy === activeBackend) return undefined;
+
+  // `alternative` is rendered in EVERY branch that has one. It used to be
+  // read only inside the "descoped" branch, which made the field dead at
+  // runtime: all five entries that carry an alternative are category
+  // "hardware", and no "descoped" entry has one. The generated support
+  // table, the skill playbooks and README all printed the stock route while
+  // the runtime refusal -- the one surface BACK-05 exists for -- dropped it.
+  // Do not re-scope this back into a single branch.
+  const alt = entry.alternative ? ` ${entry.alternative}` : "";
+
+  if (entry.category === "hardware") {
+    return (
+      `${entry.name} is unrecoverable on the ${activeBackend} backend: ${entry.reason} ` +
+      `Use the ${entry.providedBy} backend instead (Set VICE_BACKEND=${entry.providedBy}).${alt}`
+    );
+  }
+
+  if (entry.category === "descoped") {
+    return (
+      `${entry.name} is not implemented on the ${activeBackend} backend: ${entry.reason} ` +
+      `Use the ${entry.providedBy} backend instead (Set VICE_BACKEND=${entry.providedBy}).${alt}`
+    );
+  }
+
+  // category === "stock-only-gain": only reachable with activeBackend ===
+  // "fork" and entry.providedBy === "stock", since the same-backend guard
+  // above already excluded the activeBackend === "stock" case.
+  return (
+    `${entry.name} is not implemented on the fork backend: ${entry.reason} ` +
+    `Use the stock backend instead (Set VICE_BACKEND=stock).${alt}`
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henols/vice-mcp",
-  "version": "0.1.12",
+  "version": "0.2.1",
   "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": {
@@ -13,6 +13,7 @@
     "vice-sync.ts",
     "vice-probe.ts",
     "vice-broker-client.ts",
+    "version.ts",
     "stock-protocol.ts",
     "stock-connect.ts",
     "containerpath.ts",
@@ -24,6 +25,7 @@
     "build.ts",
     "container-guard.mts",
     "backend-detect.mts",
+    "capability-registry.ts",
     "stock-dispatch.ts",
     "stock-derived.ts",
     "stock-handler.ts",
@@ -42,6 +44,29 @@
     "disasm-opcodes.ts",
     "disasm-decoder.ts",
     "disasm-renderer.ts",
+    "stock-memory-search.ts",
+    "stock-symbols.ts",
+    "stock-vicii.ts",
+    "stock-cia.ts",
+    "stock-sprites.ts",
+    "stock-timing.ts",
+    "stock-run-until.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",
     "resources",
     "tools-manifest.json",
     "tools-manifest.stock.json",

package/r2000-acme-ident.ts

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+// r2000-acme-ident.ts -- the ONE authoritative place in this repo for the
+// ACME identifier policy (T-11-ENUM-NAME / T-11-NAME-INJECT): what makes a
+// string a legal ACME symbol/label name, and the single check function that
+// decides it.
+//
+// WHY THIS MODULE EXISTS: this policy started life inside r2000-enum-gen.ts,
+// consumed only by its own `createOrUpdateEnum()`/`sanitizeVariantMap()`.
+// T-11-NAME-INJECT widened the finding to a SECOND entry route --
+// `r2000_set_label_name` (both outer and batch-inner) in r2000-tools.ts, and
+// `importLabels()` in r2000-symbols.ts -- and `r2000-enum-gen.ts` statically
+// imports `runR2000Tool` FROM `r2000-tools.ts`, so `r2000-tools.ts` cannot
+// import the policy back from `r2000-enum-gen.ts` without forming a module
+// cycle. This module has no import from anywhere else in this repo, so
+// every one of those consumers (and any future one) can import it directly.
+//
+// WHAT THIS IS THE ONE AUTHORITATIVE PLACE FOR: `MAX_ACME_IDENTIFIER_LENGTH`,
+// `ACME_IDENT_RE`, `ACME_RESERVED_MNEMONICS` and `assertLegalAcmeIdentifier()`
+// -- the complete, only definition of "legal ACME identifier" in this repo.
+// `r2000-enum-gen.ts` re-exports `assertLegalAcmeIdentifier` /
+// `MAX_ACME_IDENTIFIER_LENGTH` from here so its own existing consumers and
+// tests keep their current import path; it does not hold a second copy.
+//
+// WHAT NOT TO DO, named concretely:
+//   - Never add a second identifier regex anywhere in this repo. The
+//     `r2000-regbits-gen.ts` / `r2000-regbits.test.ts` copies of
+//     `ACME_IDENT_RE` predate this module and are out of this plan's scope
+//     (260821-a86) to consolidate -- but no NEW copy should be added; import
+//     this module's `assertLegalAcmeIdentifier()` instead.
+//   - Never sanitize, quote, or auto-correct an illegal identifier here or
+//     in any caller. This function's contract is REJECT, per
+//     T-11-REGBITS-PROSE and T-11-ENUM-NAME precedent: a malformed name is a
+//     bug to surface, never silently rewritten into something else -- the
+//     caller-visible name must never diverge from what actually gets
+//     exported into ACME source.
+//   - Never import anything from this repo into this module. It must stay
+//     importable by both `r2000-tools.ts` and `r2000-enum-gen.ts` (which
+//     imports `runR2000Tool` FROM `r2000-tools.ts`) without a cycle.
+export const MAX_ACME_IDENTIFIER_LENGTH = 200;
+
+const ACME_IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/**
+ * The 6502/6510 instruction mnemonics -- the ONLY category of reserved word
+ * actually measured to collide with a bare identifier in real ACME 0.97.
+ * Verified live on this host: `LDA = $05` is REJECTED ("No value given." /
+ * "Garbage data at end of statement" -- ACME parses `LDA` positionally as
+ * the opcode, not as an assignable symbol), while `A = $05` is ACCEPTED
+ * (register-letter shorthand is not reserved as a bare symbol name). This
+ * list is therefore a measured, not a guessed, reservation.
+ */
+const ACME_RESERVED_MNEMONICS: ReadonlySet<string> = new Set([
+  "ADC", "AND", "ASL", "BCC", "BCS", "BEQ", "BIT", "BMI", "BNE", "BPL", "BRK", "BVC",
+  "BVS", "CLC", "CLD", "CLI", "CLV", "CMP", "CPX", "CPY", "DEC", "DEX", "DEY", "EOR",
+  "INC", "INX", "INY", "JMP", "JSR", "LDA", "LDX", "LDY", "LSR", "NOP", "ORA", "PHA",
+  "PHP", "PLA", "PLP", "ROL", "ROR", "RTI", "RTS", "SBC", "SEC", "SED", "SEI", "STA",
+  "STX", "STY", "TAX", "TAY", "TSX", "TXA", "TXS", "TYA",
+]);
+
+/**
+ * Refuses `id` (naming it as `what` in the thrown message) unless it is a
+ * legal ACME identifier: matches `^[A-Za-z_][A-Za-z0-9_]*$`, is no longer
+ * than `MAX_ACME_IDENTIFIER_LENGTH`, and does not collide (case-
+ * insensitively) with a reserved 6502/6510 mnemonic (see
+ * `ACME_RESERVED_MNEMONICS`'s own header comment for how that specific list
+ * was measured, not assumed).
+ *
+ * T-11-ENUM-NAME (the highest-value threat in this phase): regenerator2000
+ * validates only the ENUM name server-side
+ * (`app_state.rs:443`, `validate_new_enum_name`) and performs ZERO
+ * validation on variant names -- they flow straight into
+ * `format!("{}_{}", enum_name, variant)` at export time
+ * (`formatter_acme.rs:367-369`). This function is called on BOTH the enum
+ * name and every variant name, and is called BEFORE any
+ * `r2000_create_project_enum`/`r2000_update_project_enum` call reaches
+ * `runR2000Tool()` -- proven zero-spawn in `r2000-enum-gen.test.ts`.
+ */
+export function assertLegalAcmeIdentifier(id: string, what: string): void {
+  if (id.length === 0) {
+    throw new Error(`${what}: identifier must not be empty`);
+  }
+  if (id.length > MAX_ACME_IDENTIFIER_LENGTH) {
+    throw new Error(
+      `${what}: identifier "${id.slice(0, 40)}..." is ${id.length} characters, exceeding the ` +
+        `${MAX_ACME_IDENTIFIER_LENGTH}-character ceiling`,
+    );
+  }
+  if (!ACME_IDENT_RE.test(id)) {
+    throw new Error(`${what}: "${JSON.stringify(id)}" is not a legal ACME identifier -- must match ${ACME_IDENT_RE}`);
+  }
+  if (ACME_RESERVED_MNEMONICS.has(id.toUpperCase())) {
+    throw new Error(
+      `${what}: "${id}" collides with the reserved 6502/6510 mnemonic ${id.toUpperCase()} (verified rejected ` +
+        `by real ACME 0.97 -- see this module's ACME_RESERVED_MNEMONICS header comment)`,
+    );
+  }
+}