@henols/vice-mcp 1.0.0 → 1.1.0

package/THIRD-PARTY-NOTICES.md

@@ -501,9 +501,11 @@ appears in `src/mcp/vice/package.json`'s `files[]`, `dependencies`, or
 VICE is GPL-2 and this repository is MIT. **No opcode fact, protocol
 constant, or line of code in this repository is sourced from VICE's own
 source tree.** The stock backend is built against the binary-monitor
-**protocol** as documented in `docs/phase0-binmon-findings.md`, derived from
-independent probing against a running VICE binary, never from reading VICE's
-own C source.
+**protocol** this project independently reverse-engineered and specified as
+its own normative wire format -- the 11-byte request header, 12-byte
+response header, and confirmed command/response/error code set -- derived
+from independent probing against a running VICE binary, never from reading
+VICE's own C source.
 
 ## Explicitly NOT a source: `fluffy-6502`
 
@@ -530,5 +532,5 @@ have been.
 No new runtime dependency was added by the disassembler (`disasm-opcodes.ts`,
 `disasm-decoder.ts`, `disasm-renderer.ts`, `stock-disassemble.ts` import only
 this package's own sibling modules and Node built-ins). This is a checkable
-claim, not a prose one: `scripts/check-npm-packages.mjs` asserts the packed
+claim, not a prose one: the packed
 tarball's runtime `dependencies` are exactly these two, by key set and count.

package/anno-cli.ts

@@ -131,7 +131,7 @@ import { renderMemoryMap, checkRenderedMemoryMap } from "./anno-memmap-render.ts
 // one. `acme-verify.ts` -- the module that DOES spawn ACME -- is deliberately
 // NOT imported here and must never be: it is test-only (it is absent from
 // `package.json`'s `files[]` on purpose), so a shipped module importing it
-// would drag it into the published closure `check-npm-packages.mjs` walks.
+// would drag it into the published closure.
 import { exportAsmTree } from "./anno-export-asm.ts";
 import type { ExportAsmTreeResult } from "./anno-export-asm.ts";
 // The coverage instrument. It declares its own input shapes

package/anno-store.ts

@@ -50,7 +50,7 @@
 // THIS MODULE MUST BE LISTED IN `package.json`'s `files[]`, and the reason is
 // NOT the reachability reason `prg-image.ts:30-36` gives for itself. This
 // module is not yet reachable from the published entry point's import closure,
-// and `scripts/check-npm-packages.mjs` asserts only one direction -- every
+// and only one direction was ever asserted mechanically -- every
 // REACHABLE module must be listed -- never the converse. The real reason to
 // list it: the shipped-module assertion scans `shippedTsModules()`, which is derived
 // from `files[]`, so an unlisted module makes that assertion VACUOUS. It would

package/backend-detect.mts

@@ -41,6 +41,30 @@
 //     is the exact failure class the 2026-08-01 triple-launch outage came
 //     from (D-03/T-02-25) -- unchanged reasoning from before this plan, only
 //     the mechanism inside resolvedBackend() changed.
+//
+// Phase 60 (LOC-01/LOC-02, PD-01/PD-02/PD-03): resolvedBackend() gains a real
+// VALUE dependency on the tool-location seam (tool-location.mts) for the
+// emulator binary's own resolution -- when neither `viceBin` nor
+// `resolveBinPath` is injected, resolution goes through the seam's
+// `resolveTool("x64sc", ...)` instead of this file's own ordering, so a
+// `.c64-re-tools/tools.json` entry for `x64sc` now changes what this broker
+// actually spawns. `defaultResolveBinPath()` collapses into a thin wrapper
+// over the seam's own exported `resolveOnPath()` -- the first of Phase 59
+// D-02's three independent `$PATH`-walk copies to collapse.
+//
+// This file ships two ways (see the cache-section comment below): unbuilt,
+// imported directly by container-side .ts (vice-proxy.ts's own `import *
+// as backendDetect from "./backend-detect.mts"`), and compiled into
+// resources/ for the host (vice-broker.mts's own `./backend-detect.mjs`
+// value import). A STATIC `import ... from "./tool-location.mjs"` would
+// resolve in only the SECOND form -- that file exists as a real sibling
+// only once both are compiled into resources/, never beside the unbuilt
+// source. Loading it instead through node:module's `createRequire()`
+// (`toolLocationSeam()` below) defers resolution to the call site rather
+// than parse time, so trying the compiled sibling first and falling back to
+// the unbuilt source sibling keeps this ONE seam call working in both
+// shipped forms -- one implementation, no #ifdef-style split, and every
+// existing unbuilt importer of this file needs no change at all.
 import {
   existsSync,
   readFileSync,
@@ -50,7 +74,17 @@ import {
   mkdirSync,
   statSync,
 } from "node:fs";
-import { join, resolve as resolvePath } from "node:path";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+import type { ResolveToolDeps, resolveTool, resolveOnPath } from "./tool-location.mjs";
+
+/** `typeof` the seam's own exported functions -- imported as VALUES above
+ * (under `import type`, so still fully erased at runtime; see this file's
+ * own header for why the REAL call goes through `toolLocationSeam()`
+ * instead) purely so their call signatures can be named as types here. */
+type ResolveToolFn = typeof resolveTool;
+type ResolveOnPathFn = typeof resolveOnPath;
 
 /** The one shape this tree ever launches or speaks to. FORKRM-01 narrowed
  * this from a two-member union ("fork" | "stock") to this single literal --
@@ -201,18 +235,48 @@ export interface BinaryIdentity {
   sizeBytes: number;
 }
 
+/** This module's own directory. Computed once, purely to seed
+ * `toolLocationSeam()`'s two-candidate join below -- mirrors
+ * `tool-location.mts`'s own `HERE` constant and its `readDeclaration()`
+ * "beside `here`, take the first that exists" idiom exactly. */
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/** The tool-location seam's runtime shape, as this file actually calls it --
+ * an interface, not a value import, because the interface itself is
+ * satisfied by `import type` (erased entirely, resolved for TYPES only via
+ * tsc's own NodeNext ".mjs" -> ".mts" mapping) while the REAL call happens
+ * through `toolLocationSeam()` below. */
+interface ToolLocationSeam {
+  resolveTool: ResolveToolFn;
+  resolveOnPath: ResolveOnPathFn;
+}
+
+/** Loads the tool-location seam through `node:module`'s `createRequire()`
+ * rather than a static ESM import -- see this file's own header for why a
+ * static specifier cannot work in both of this file's two shipped forms.
+ * `require()` resolves at THIS call site, not at parse time, so trying the
+ * compiled resources/ sibling first and falling back to the unbuilt source
+ * sibling (the exact two-candidate order `tool-location.mts`'s own
+ * `readDeclaration()` already uses for `prerequisites.json`) lets the SAME
+ * source file resolve correctly whichever way this file itself was loaded.
+ * Never memoised here -- `resolvedBackend()`'s own `memoisedResult` already
+ * ensures this runs at most once in the one production path that reaches
+ * it, and a test process that resets that memo between scenarios must be
+ * free to call this again, cheaply, rather than replay a stale answer. */
+function toolLocationSeam(): ToolLocationSeam {
+  const req = createRequire(import.meta.url);
+  const specifier = existsSync(join(HERE, "tool-location.mjs")) ? "./tool-location.mjs" : "./tool-location.mts";
+  return req(specifier) as ToolLocationSeam;
+}
+
+/** Reduced (Phase 60) to a thin wrapper over the seam's own exported
+ * `resolveOnPath()` -- the first of Phase 59 D-02's three independent
+ * `$PATH`-walk copies to collapse. Kept as a named function (rather than
+ * inlined at its one call site) only because `ResolvedBackendDeps.resolveBinPath`
+ * needs a real default to fall back to when a caller supplies `viceBin` but
+ * not this override (PD-02). */
 function defaultResolveBinPath(bin: string, env: NodeJS.ProcessEnv): string | null {
-  if (bin.includes("/")) {
-    const abs = resolvePath(bin);
-    return existsSync(abs) ? abs : null;
-  }
-  const pathEnv = env.PATH ?? "";
-  for (const dir of pathEnv.split(":")) {
-    if (!dir) continue;
-    const candidate = join(dir, bin);
-    if (existsSync(candidate)) return candidate;
-  }
-  return null;
+  return toolLocationSeam().resolveOnPath(bin, env).path;
 }
 
 function defaultStat(resolvedPath: string): BinaryIdentity | null {
@@ -247,13 +311,27 @@ export interface ResolvedBackendResult {
    * the two it has, instead of a reader having to guess from whether the string
    * happens to contain a slash. */
   binPathResolved: boolean;
+  /** Phase 60 gap closure (LOC-03, PD-13): the tool-location seam's own
+   * `ResolveToolResult.refusal` verbatim, carried through unchanged, when
+   * resolution went through the seam (the PD-01 branch below) AND the seam
+   * refused. `null` in every other case -- including the PD-02
+   * injected-override branch, which never calls the seam at all and so has
+   * no refusal to carry. This is what lets `vice-broker.mts` write a
+   * readable startup line naming which environment-variable override was
+   * refused and why, without itself reading any of the four declared
+   * variable names. */
+  locationRefusal: string | null;
 }
 
 export interface ResolvedBackendDeps {
   env?: NodeJS.ProcessEnv;
-  /** Which binary to detect against -- defaults to VICE_BIN or "x64sc",
-   * matching broker-launch.mts's own spawnAndRecordInstance() default
-   * exactly (one broker, one binary, one verdict). */
+  /** An explicit override that BYPASSES the seam entirely (PD-02) --
+   * defaults to the literal "x64sc" when omitted but `resolveBinPath` below
+   * IS supplied. This no longer "defaults to VICE_BIN or x64sc": when BOTH
+   * this field and `resolveBinPath` are omitted, resolution goes through the
+   * tool-location seam instead (PD-01) and this field plays no part in it.
+   * Every existing caller that injects this field keeps its exact prior
+   * behaviour, byte-for-byte. */
   viceBin?: string;
   /** See this module's own header comment on the cache section above --
    * NEVER defaulted here. Omitted entirely disables the on-disk cache
@@ -262,6 +340,21 @@ export interface ResolvedBackendDeps {
   resolveBinPath?: (bin: string, env: NodeJS.ProcessEnv) => string | null;
   stat?: (resolvedPath: string) => BinaryIdentity | null;
   now?: () => number;
+  /** The directory holding `.c64-re-tools/tools.json` -- passed straight
+   * into the seam's `resolveTool()` call when neither `viceBin` nor
+   * `resolveBinPath` above is supplied (PD-01). Derived from `supervisorDir`
+   * (PD-03) when omitted and a `supervisorDir` IS given -- vice-broker.mts's
+   * own `args.stateDir` IS `.c64-re-tools/supervisor` under this broker's
+   * repo root, so that derivation is exact, not a guess -- otherwise
+   * `process.cwd()`. */
+  toolsDir?: string;
+  /** The project root a relative `tools.json` value resolves against --
+   * same PD-03 derivation rule as `toolsDir` above. */
+  projectRoot?: string;
+  /** Test-only override for the seam call itself -- defaults to
+   * `toolLocationSeam()`'s own lazily-loaded `resolveTool`. Follows the same
+   * injection convention as `resolveBinPath`/`stat`/`now` above. */
+  locate?: ResolveToolFn;
 }
 
 // Memoised answer -- a long-running process (the real broker) resolves once
@@ -309,12 +402,43 @@ export function resolvedBackend(deps: ResolvedBackendDeps = {}): ResolvedBackend
   if (memoisedResult !== null) return memoisedResult;
 
   const env = deps.env ?? process.env;
-  const viceBin = deps.viceBin ?? env.VICE_BIN ?? "x64sc";
-  const resolveBinPath = deps.resolveBinPath ?? defaultResolveBinPath;
   const stat = deps.stat ?? defaultStat;
   const now = deps.now ?? ((): number => Date.now());
 
-  const resolvedPath = resolveBinPath(viceBin, env);
+  let viceBin: string;
+  let resolvedPath: string | null;
+  // Phase 60 gap closure (LOC-03, PD-13): non-null only in the PD-01 branch
+  // below, and only when the seam itself refused. Carried verbatim onto the
+  // returned result's own `locationRefusal` field (see that field's own doc
+  // comment for why); this module reads no environment variable to compose
+  // it, and reads none to name it here either.
+  let locationRefusal: string | null = null;
+
+  if (deps.viceBin !== undefined || deps.resolveBinPath !== undefined) {
+    // PD-02: an explicit override bypasses the seam entirely -- byte-for-byte
+    // the same behaviour every existing injected test case already exercises.
+    viceBin = deps.viceBin ?? "x64sc";
+    const resolveBinPath = deps.resolveBinPath ?? defaultResolveBinPath;
+    resolvedPath = resolveBinPath(viceBin, env);
+  } else {
+    // PD-01: resolvedBackend() gains the tools.json layer internally by
+    // calling the seam; it keeps no ordering of its own. The seam's WHOLE
+    // result is taken here (PD-13), not only its `path`: the display name
+    // handed to binPathFields() below falls back to the seam's own
+    // `envCandidate` -- the value the developer actually wrote -- when the
+    // seam reports one, and to the literal "x64sc" only when it does not
+    // (retiring the hardcoded display name IN-01 logged). `refusal` is
+    // carried onto `locationRefusal` above unchanged.
+    const projectRoot = deps.projectRoot ?? (deps.supervisorDir !== undefined ? dirname(dirname(deps.supervisorDir)) : process.cwd());
+    const toolsDir = deps.toolsDir ?? (deps.supervisorDir !== undefined ? dirname(deps.supervisorDir) : join(process.cwd(), ".c64-re-tools"));
+    const locate: ResolveToolFn = deps.locate ?? toolLocationSeam().resolveTool;
+    const locateDeps: ResolveToolDeps = { toolsDir, projectRoot, env };
+    const locateResult = locate("x64sc", locateDeps);
+    resolvedPath = locateResult.path;
+    viceBin = locateResult.envCandidate ?? "x64sc";
+    locationRefusal = locateResult.refusal;
+  }
+
   const identity = resolvedPath ? stat(resolvedPath) : null;
   const cacheEligible = resolvedPath !== null && identity !== null && typeof deps.supervisorDir === "string";
 
@@ -336,7 +460,7 @@ export function resolvedBackend(deps: ResolvedBackendDeps = {}): ResolvedBackend
     }
   }
 
-  const result: ResolvedBackendResult = { backend: "stock", ...binPathFields(resolvedPath, viceBin) };
+  const result: ResolvedBackendResult = { backend: "stock", ...binPathFields(resolvedPath, viceBin), locationRefusal };
   memoisedResult = result;
   return result;
 }

package/build.ts

@@ -11,6 +11,7 @@
 // under bare `node`, exactly like vice-broker.mts.
 import { execFileSync } from "node:child_process";
 import {
+  copyFileSync,
   existsSync,
   mkdirSync,
   mkdtempSync,
@@ -50,8 +51,30 @@ export const HOST_BOUND_ARTIFACTS: string[] = [
   "backend-detect.mjs",
   "host-tool.mjs",
   "ghidra-project.mjs",
+  "tool-location.mjs",
 ];
 
+/** A plain data file that travels WITH the compiled artifacts above, never
+ * compiled by `tsc` and never asserted against `HOST_BOUND_ARTIFACTS`'s own
+ * emitted-file-set check (that check is `.mjs`-only, per
+ * `emittedMjsFilesUnder()` below). Found missing by Plan 60-05's own
+ * required full-suite baseline diff: `tool-location.mts`'s
+ * `readDeclaration()` locates `prerequisites.json` "beside `here`" or one
+ * directory up from wherever the compiled module actually runs. That
+ * candidate pair only ever resolved correctly while the compiled artifact
+ * ran IN PLACE inside `src/mcp/vice/resources/` (one directory up lands on
+ * `src/mcp/vice/prerequisites.json`) -- once `vice-broker.mts` started
+ * resolving `x64sc` through the seam at STARTUP (Plan 60-01), a real
+ * deployment into a consuming project's `.c64-re-tools/bin/` (where
+ * neither candidate exists) made the broker throw before it ever wrote
+ * `broker.json`. Copying it into `resources/` here, alongside every
+ * compiled artifact, makes `install-resources.ts`'s own generic recursive
+ * walk of `resources/` deploy it automatically -- no separate deploy-side
+ * code needed -- and gives `readDeclaration()`'s FIRST candidate ("beside
+ * `here`") a real file at every location the compiled module ever runs
+ * from, deployed or not. */
+export const HOST_BOUND_DATA_FILES: string[] = ["prerequisites.json"];
+
 /** The generated-file banner (01.6-RESEARCH.md §F), a function of the
  * source's relative path. Prepended to every emitted file by build() below --
  * this is the ONLY place that produces this text, so a sync test built
@@ -230,6 +253,24 @@ export function build({ outDir = "resources" }: BuildOptions = {}): void {
       }
     }
 
+    // HOST_BOUND_DATA_FILES: a plain copy, never compiled by tsc and never
+    // part of the emitted-file-set assertion above (that check is
+    // `.mjs`-only). Staged and renamed the SAME atomic way as every
+    // compiled artifact -- never exposed at an `outDir` path half-written --
+    // so it must be moved into place BEFORE the leftover check below, or its
+    // own staged copy would itself register as an unexplained leftover.
+    for (const rel of HOST_BOUND_DATA_FILES) {
+      const staged = join(stagingDir, rel);
+      copyFileSync(join(HERE, rel), staged);
+      const to = join(outDirAbs, rel);
+      try {
+        renameSync(staged, to);
+      } catch (e) {
+        const detail = (e as NodeJS.ErrnoException).code === "EXDEV" ? " (EXDEV: staging dir and outDir are on different filesystems -- outDir must be reachable via a same-filesystem sibling)" : "";
+        throw new Error(`build: failed to move staged data file into place: ${staged} -> ${to}${detail}`, { cause: e });
+      }
+    }
+
     // tsc emits exactly HOST_BOUND_ARTIFACTS today (verified). A leftover
     // here means the compiler started emitting something this list does not
     // describe -- fail loudly rather than silently drop a file that used to
@@ -263,7 +304,7 @@ if (process.argv[1] && resolvePath(process.argv[1]) === fileURLToPath(import.met
   try {
     build(opts);
     const outDirAbs = resolveOutDirAbs(opts.outDir ?? "resources");
-    process.stderr.write(`build: wrote ${HOST_BOUND_ARTIFACTS.length} artifact(s) to ${outDirAbs}\n`);
+    process.stderr.write(`build: wrote ${HOST_BOUND_ARTIFACTS.length} artifact(s) and ${HOST_BOUND_DATA_FILES.length} data file(s) to ${outDirAbs}\n`);
   } catch (e) {
     process.stderr.write(`build: FAILED -- ${(e as Error).message}\n`);
     process.exitCode = 1;

package/evid-ingest.ts

@@ -92,9 +92,13 @@ export interface IngestRunIdentity {
 }
 
 /** `runIdentityFrom()`'s answer: the bare `(imageSha256, argvDigest, seed)`
- * triple the `no-change` run-identity decision selected (plan 43-01,
- * `docs/phase43-instrumentation-perturbation-ab.md`) -- no `runClass`
- * discriminator field exists on this type. */
+ * triple the `no-change` run-identity decision selected -- measured by an
+ * A/B capture comparison that ran the identical anchor-counted AUTOSTART
+ * sequence with and without runtime evidence dialed over the text channel
+ * and found the two byte-for-byte equivalent at both tested anchor depths,
+ * so recording evidence does not perturb the capture and the run identity
+ * needs no extra discriminator -- no `runClass` discriminator field exists
+ * on this type. */
 export interface RunIdentity {
   readonly imageSha256: string;
   readonly argvDigest: string;

package/host-tool-client.ts

@@ -40,9 +40,13 @@
 // this new family off that five-member list entirely, by construction.
 //
 // Do not write the tokens `binPath`, `viceBin`, `VICE_BIN` or `x64sc`
-// anywhere in this file -- it ships (package.json `files[]`) and is scanned
-// by spawn-seam.test.ts, which would misclassify a bare identifier match as
-// an emulator spawn site.
+// anywhere in this file -- it ships (package.json `files[]`). This is kept
+// deliberately, by CONVENTION, not by a mechanical guard: the test that once
+// scanned for those four tokens (its own file) was deleted in commit
+// `276c15c9` and is not revived here. What IS mechanically enforced, over
+// the four tool-location environment-variable names this project reads, is
+// the closed consumer set `tool-location-consumers.test.ts` (plan 60-05)
+// asserts.
 import { readFileSync } from "node:fs";
 import { spawn } from "node:child_process";
 import { connect } from "node:net";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henols/vice-mcp",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "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": {
@@ -65,6 +65,7 @@
     "anno-symbols.ts",
     "anno-regbits-gen.ts",
     "anno-regbits.json",
+    "prerequisites.json",
     "anno-enum-gen.ts",
     "anno-acme-ident.ts",
     "anno-confidence.ts",
@@ -133,6 +134,7 @@
     "test:manual": "node test-gate.mjs --manual",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "build": "node build.ts",
+    "generate:readme": "node prereq-readme-gen.ts --write",
     "smoke": "node smoke.mjs"
   },
   "dependencies": {