@henols/c64-re-tools 0.2.1 → 0.2.3

package/skills/c64-ram-capture/scripts/mcp-module.mjs

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+// mcp-module.mjs -- the ONE resolution ladder a skill script uses to reach a
+// module that lives in the OTHER package (`@henols/vice-mcp`'s `src/mcp/vice/`
+// tree, as opposed to this file's own `@henols/c64-re-tools` skills tree).
+//
+// ---------------------------------------------------------------------------
+// WHY THIS FILE EXISTS
+// ---------------------------------------------------------------------------
+// Before this file existed, `vsf-slice.mjs`
+// carried its own copy of this exact three-rung ladder (`ladder()` /
+// `resolveTarget()`), and TWO MORE skill scripts (`acme.mjs`,
+// `packer-finding.mjs`) were about to migrate onto the host-tool execution
+// seam and were each going to need the identical lookup to reach
+// `host-tool-client.ts`. Three production consumers were about to carry
+// three copies of one ladder -- so it is extracted here instead, and
+// `vsf-slice.mjs` is rewritten to import it rather than keep its own.
+//
+// The underlying constraint this ladder exists to answer is
+// `vsf-slice.mjs`'s own recorded finding: the MCP server ships as
+// `@henols/vice-mcp`, whose `files[]` lists only `src/mcp/vice/` contents,
+// while `src/skills/**` ships in a DIFFERENT package (`@henols/c64-re-tools`).
+// A plain `import` from a skill script into the MCP tree resolves on NEITHER
+// npm-installer route, so a skill script that needs an MCP-side module must
+// LOCATE it on disk and invoke it as a subprocess (`process.execPath
+// <resolved-path> ...argv`) -- never a static `import`.
+//
+// ---------------------------------------------------------------------------
+// WHAT THIS IS THE ONE AUTHORITATIVE PLACE FOR
+// ---------------------------------------------------------------------------
+//   - the three-rung resolution order (`$VICE_MCP_DIR`, the in-repo relative
+//     path, then `require.resolve()` against the published package) for
+//     locating ANY named file inside `src/mcp/vice/` from a skill's own
+//     `scripts/` directory;
+//   - refusing BY NAME, listing every rung tried, when none resolves
+//     (`refusalMessage()`);
+//   - computing the in-repo hop count from `import.meta.url` rather than a
+//     fixed `".."` count -- `hostpath.ts` and `containerpath.ts` both record
+//     dropping a hard-coded four-level hop when they moved directories once
+//     already, and this project has ALSO shipped a stale hardcoded snapshot
+//     offset before (see `vsf-slice.mjs`'s own header) -- a fixed `".."`
+//     count is a mistake this project keeps making, not a one-off.
+//
+// ---------------------------------------------------------------------------
+// WHAT NOT TO DO
+// ---------------------------------------------------------------------------
+//   - Never carry a second copy of these three rungs, their ordering, or
+//     their refusal text anywhere else in this repository. A future
+//     skill-side consumer of an MCP-side module imports `resolveMcpModule`
+//     from HERE.
+//   - Never let a resolution failure become a local re-implementation of
+//     whatever was being resolved -- refuse by name instead. A silent
+//     fallback that reimplements the target module's own logic is exactly
+//     the divergence this ladder exists to prevent (see `vsf-slice.mjs`'s own
+//     header on the stale-offset incident this project has already had).
+//   - `process.execPath` spawned on a resolved `.ts`/`.mjs` file inside this
+//     project's OWN tree reaches NO external host binary -- it is the
+//     interpreter already running the calling script, pointed at an in-tree
+//     module. This is NOT what the host-tool execution seam (`host-tool.mts`
+//     / `host-tool-client.ts`) exists for, and must never be confused with
+//     it: the seam is for binaries that live on the HOST, outside any
+//     container; this ladder is for locating a file inside this project's own
+//     two npm packages.
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { basename, dirname, join, resolve } from "node:path";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/** The package the MCP-side module ships in, for the npm-installer rung. */
+export const TARGET_PACKAGE = "@henols/vice-mcp";
+
+/**
+ * Walks UP from `startDir` until a directory literally named `name` is
+ * found, returning its absolute path -- or `null` if the filesystem root is
+ * reached first without a match. This is what lets the in-repo hop count be
+ * COMPUTED from `import.meta.url` instead of a fixed `".."` count: whichever
+ * skill's `scripts/` directory this module is imported from, walking up to
+ * the `skills/` ancestor and back down to `mcp/vice/` is the same operation.
+ */
+function findAncestorDir(startDir, name) {
+  let dir = startDir;
+  for (;;) {
+    if (basename(dir) === name) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null; // reached the filesystem root, no match
+    dir = parent;
+  }
+}
+
+// Computed once, at module load: HERE is .../src/skills/<skill>/scripts/, so
+// walking up to the "skills" ancestor and taking ITS parent ("src") gives the
+// root from which "mcp/vice" is a sibling of "skills" -- with no fixed hop
+// count written down anywhere in this file.
+const SKILLS_DIR = findAncestorDir(HERE, "skills");
+const IN_REPO_MCP_VICE_DIR = SKILLS_DIR ? join(dirname(SKILLS_DIR), "mcp", "vice") : null;
+
+/**
+ * The resolution ladder for `fileName`, in order, as `{ rung, path, note }`
+ * records -- returned IN FULL (never short-circuited), so a refusal message
+ * can name every path tried, which is the whole point of refusing rather
+ * than guessing:
+ *
+ *   1. `$VICE_MCP_DIR` -- an explicit override, checked first so a caller can
+ *      always point this ladder at a known-good tree.
+ *   2. The in-repo relative path (see `findAncestorDir()` above). The plugin
+ *      distribution keeps both trees in one checkout, so this is the rung
+ *      that resolves during development and in CI.
+ *   3. `require.resolve()` against the published package, for the
+ *      npm-installer route where the two packages are installed separately.
+ */
+function ladder(fileName) {
+  const rungs = [];
+
+  const override = process.env.VICE_MCP_DIR;
+  rungs.push({
+    rung: "VICE_MCP_DIR",
+    path: override ? join(resolve(override), fileName) : null,
+    note: override ? null : "VICE_MCP_DIR is not set",
+  });
+
+  rungs.push({
+    rung: "in-repo relative path",
+    path: IN_REPO_MCP_VICE_DIR ? join(IN_REPO_MCP_VICE_DIR, fileName) : null,
+    note: IN_REPO_MCP_VICE_DIR ? null : `could not locate an ancestor "skills" directory from ${HERE}`,
+  });
+
+  let resolved = null;
+  let note = null;
+  try {
+    resolved = createRequire(import.meta.url).resolve(`${TARGET_PACKAGE}/${fileName}`);
+  } catch (err) {
+    note = `${TARGET_PACKAGE} is not resolvable from here (${err.code ?? err.message})`;
+  }
+  rungs.push({ rung: `${TARGET_PACKAGE} package`, path: resolved, note });
+
+  return rungs;
+}
+
+/**
+ * Builds the refusal text naming every rung tried plus the instruction to
+ * set `VICE_MCP_DIR` -- the ONE place this message is worded, so callers
+ * that construct their own additional context around it (e.g.
+ * `vsf-slice.mjs`'s own domain-specific rationale) do not restate it.
+ */
+export function refusalMessage(fileName, rungs) {
+  const tried = rungs
+    .map((r) => `  ${r.rung}: ${r.path ?? "(no path)"}${r.note ? ` -- ${r.note}` : ""}`)
+    .join("\n");
+  return (
+    `could not resolve ${fileName}.\n` +
+    `Tried, in order:\n${tried}\n` +
+    `Set VICE_MCP_DIR to the directory holding ${fileName}.`
+  );
+}
+
+/**
+ * Resolves `fileName` (e.g. `"vsf-slice.ts"`, `"host-tool-client.ts"`) against
+ * the three-rung ladder above, with NO per-file special-casing -- every
+ * caller gets the same three rungs in the same order.
+ *
+ * Returns `{ ok: true, rung, path }` for the first rung whose path exists on
+ * disk, or `{ ok: false, rungs, message }` when none resolves -- `rungs`
+ * carries the full attempt list (so a caller can build its own message from
+ * the raw records instead of `refusalMessage()`, if it wants extra context),
+ * and `message` is `refusalMessage(fileName, rungs)` already computed. Never
+ * throws.
+ */
+export function resolveMcpModule(fileName) {
+  const rungs = ladder(fileName);
+  const hit = rungs.find((r) => r.path && existsSync(r.path));
+  if (hit) return { ok: true, rung: hit.rung, path: hit.path };
+  return { ok: false, rungs, message: refusalMessage(fileName, rungs) };
+}

package/skills/c64-ram-capture/scripts/project-paths.mjs

@@ -6,7 +6,7 @@
 //
 //   1. The project root is found by walking UP for a `.git` marker. Counting
 //      hops from `import.meta.url` breaks the moment the toolkit is installed
-//      somewhere other than `.claude/skills/<skill>/scripts/`, and it breaks
+//      somewhere other than `src/skills/<skill>/scripts/`, and it breaks
 //      silently -- paths resolve to a plausible wrong place rather than erroring.
 //   2. Every data location is overridable by environment variable, so a project
 //      that does not use this repo's `recovery/` + `disks/` layout can point the

package/skills/c64-ram-capture/scripts/releases.mjs

@@ -44,7 +44,7 @@ export function release(id) {
 }
 
 /**
- * The registry's own N-readiness documentation (01-03-PLAN.md's Task 2):
+ * The registry's own N-readiness documentation:
  * a top-level `schema_notes` string, sibling to `schema_version` and
  * `releases`, stating the mechanical claim that adding a release is one
  * `releases[]` entry plus one invocation of `tools/recover.mjs`. Kept as a

package/skills/c64-ram-capture/scripts/vsf-slice.mjs

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+// Slice a flat 64K RAM image out of a VICE `.vsf` snapshot, with no
+// transcription step anywhere.
+//
+// A WRAPPER, DELIBERATELY EMPTY OF LAYOUT KNOWLEDGE. Not one snapshot byte
+// offset, module name or body length appears in this file. Every such fact
+// lives in `src/mcp/vice/vsf-slice.ts`, which this script resolves and
+// invokes. If you came here looking for the layout, you are in the wrong
+// file, and that is the design.
+//
+// WHY IT INVOKES THE OTHER PACKAGE'S MODULE INSTEAD OF CARRYING A COPY.
+// THE CONSTRAINT, MEASURED rather than assumed: the MCP server ships as
+// `@henols/vice-mcp`, whose `files[]` lists only `src/mcp/vice/` contents,
+// while `src/skills/**` ships in the other package (`@henols/c64-re-tools`).
+// A plain `import` from a skill script into the MCP tree resolves on neither
+// npm-installer route, and `scripts/check-npm-packages.mjs`'s transitive
+// closure walk over `files[]` would fail the pack the moment a reachable
+// module sat outside the listed set.
+//
+// That leaves two answers, and this file takes the second:
+//
+//   (a) a self-contained skill-side script carrying its own copy of the
+//       layout -- the retired skill-side/MCP-side disk-image-reader pair's
+//       own precedent (two independent copies of the sector-chain walk,
+//       both deleted once the c1541 host-tool seam took over their one job).
+//   (b) a CLI entry point on the MCP-side module, which the skill invokes.
+//
+// (b), because the two cases are not alike. That retired pair's own
+// duplicate was of a STABLE, PUBLISHED disk format that has not changed in
+// forty years. The
+// `.vsf` layout is version-sensitive: a second magic block moved the first
+// module offset, the memory module's body length differs between two module
+// minors that are both in the wild, and this project already had ONE stale
+// copy of those numbers -- a prototype carrying a first-module offset that
+// predates that second magic block, which survived only through a
+// byte-by-byte rescan fallback that can lock onto a false module name inside
+// 64 KB of RAM data. The real values, and their derivations, are in
+// `vsf-slice.ts` where they belong. A second copy of the one
+// authoritative reading of a version-sensitive format is precisely the
+// divergence hazard the single-seam convention exists to remove. Recorded
+// here as a decision so the next reader sees a choice rather than an
+// oversight.
+//
+// IT SPAWNS `node` ON AN IN-TREE MODULE, AND NOTHING ELSE. `process.execPath`
+// is the interpreter already running this script, and the target is a
+// JavaScript/TypeScript file inside one of this project's own two packages.
+// No external host binary is reached, so the host-tool execution seam is not
+// involved here and must not be pre-empted -- that seam is for binaries that
+// live on the host outside any container, which this is not.
+//
+// WHAT NOT TO DO:
+//   - Never add a fallback that slices the snapshot here. If no rung of the
+//     resolution ladder resolves, this script exits non-zero naming every
+//     path it tried. A local re-implementation would turn a resolution
+//     failure into a WRONG IMAGE, which is the one outcome the whole slicing
+//     route exists to avoid.
+//   - Never rewrite, prefix or summarise the target module's stderr. It is
+//     inherited straight through, so a refusal reaches you in the words of
+//     the code that refused.
+//   - Never copy a snapshot byte offset, a module body length or a module
+//     name into this file, not even in a comment as documentation, and not
+//     even into the usage text. The next person to update the layout will
+//     update `vsf-slice.ts` and will not know to look here. Its colocated
+//     test asserts the absence mechanically, so this is a red gate rather
+//     than a promise. (The `$D000-$DFFF` range in the usage below is a C64
+//     address range and a fact about the memory-read route, not a snapshot
+//     layout constant.)
+import { spawnSync } from "node:child_process";
+
+// The resolution ladder used to live HERE,
+// as this file's own `ladder()`/`resolveTarget()` pair. It is now extracted
+// to `mcp-module.mjs` (`resolveMcpModule()`/`refusalMessage()`), because two
+// MORE skill scripts (`acme.mjs`, `packer-finding.mjs`) needed the identical
+// lookup to reach the host-tool execution seam's `host-tool-client.ts`, and
+// three copies of one ladder is exactly the divergence hazard this file's own
+// header (below) already warns about for the `.vsf` layout itself. Import
+// the ladder rather than re-adding a copy here.
+import { resolveMcpModule, refusalMessage, TARGET_PACKAGE } from "./mcp-module.mjs";
+
+/** The MCP-side module's file name, in one place. */
+const TARGET_FILE = "vsf-slice.ts";
+
+/** Forwards argv to the MCP-side entry point with stdio inherited, so its
+ * stdout and stderr reach the caller unmodified and its exit status is this
+ * script's exit status. */
+function forward(argv) {
+  const resolved = resolveMcpModule(TARGET_FILE);
+
+  if (!resolved.ok) {
+    console.error(
+      `vsf-slice.mjs: ${refusalMessage(TARGET_FILE, resolved.rungs)}\n` +
+        `${TARGET_FILE} is where the .vsf layout lives. Refusing rather than slicing the snapshot ` +
+        `here: a second copy of a version-sensitive byte layout is how a wrong image gets produced ` +
+        `with no error.`,
+    );
+    return 1;
+  }
+
+  const run = spawnSync(process.execPath, [resolved.path, ...argv], { stdio: "inherit" });
+  if (run.error) {
+    console.error(`vsf-slice.mjs: could not run ${resolved.path}: ${run.error.message}`);
+    return 1;
+  }
+  if (run.signal) {
+    console.error(`vsf-slice.mjs: ${resolved.path} was killed by ${run.signal}`);
+    return 1;
+  }
+  return run.status ?? 1;
+}
+
+// Both verbs forward identically. The table exists so an unknown verb is
+// answered here, with this script's usage, rather than by a subprocess whose
+// own usage names a file the caller did not run.
+//
+// Prototype-less, via Object.create(null). A plain object
+// literal inherits Object.prototype, so `commands["constructor"]` and
+// `commands["toString"]` are truthy FUNCTIONS: an unknown verb that happens to
+// be a prototype member passed the known-verb test and was then CALLED, so the
+// documented usage was never printed and the failure surfaced as a confusing
+// message from process.exit() about its argument type instead. Same idiom this
+// file already uses for its flag bag, applied one level up.
+const commands = Object.assign(Object.create(null), { slice: forward, digest: forward });
+
+const [cmd, ...rest] = process.argv.slice(2);
+if (!cmd || !commands[cmd]) {
+  console.error(`usage: node vsf-slice.mjs <command>
+
+  slice <snapshot.vsf> --out <image.bin> [--json]   write the flat 64K image
+  digest <snapshot.vsf>                             sha256 of the sliced image, writing no file
+
+Produces a flat 64K image by slicing the snapshot's memory module body. There
+is no transcription step on this route, so the \`$D000-$DFFF\` volatility rule
+that governs the memory-read route does NOT apply to an image produced this
+way: the snapshot array is RAM under I/O, not the register read view.
+
+The layout lives in ${TARGET_FILE} on the MCP side; this script resolves it via
+VICE_MCP_DIR, the in-repo path, or ${TARGET_PACKAGE}, and refuses by name when
+no rung resolves. A malformed snapshot is refused, never truncated.`);
+  process.exit(cmd ? 1 : 0);
+}
+
+try {
+  process.exit(commands[cmd]([cmd, ...rest]));
+} catch (e) {
+  console.error(`error: ${e.message}`);
+  process.exit(1);
+}

package/skills/c64-ram-capture/scripts/watch-loads.mjs

@@ -100,7 +100,7 @@ function loadManifestForRelease(rel) {
  * Resolve the two-tier sentinel set for one release from registry data and
  * that release's run1 range manifest -- never hardcoded. `stopping` tier is
  * one sentinel per `loader_ranges` entry (the loader-reentry sentinels that
- * must never fire again after the dump point per D-10). `counting` tier is
+ * must never fire again after the dump point). `counting` tier is
  * one sentinel per never-populated range in the run1 manifest, plus one
  * register sentinel on CIA2 port A ($DD00), which carries both the VIC
  * bank-select bits and the bit-banged serial-bus lines a KERNAL-bypassing
@@ -136,7 +136,7 @@ export function WATCH_SET(releaseId, { registry, manifest } = {}) {
       type: "exec",
       start,
       end,
-      reason: lr.note ?? "loader-reentry range: must never fire again after the dump point (D-10)",
+      reason: lr.note ?? "loader-reentry range: must never fire again after the dump point",
       evidence: lr.evidence ?? "",
     });
   }
@@ -285,7 +285,7 @@ export function classifyHit(hit) {
  * are human-audit artifacts and are never hashed here or anywhere else in
  * this project: an encoder can emit different bytes for pixel-identical
  * images, and this project deliberately installs no image-decoding library
- * (D-18) to decode-then-hash instead.
+ * to decode-then-hash instead.
  */
 export function screenSignature(screenMatrixHex, spriteEnable) {
   const buf = Buffer.from(screenMatrixHex, "hex");
@@ -403,24 +403,24 @@ function renderReleaseSection(id, log) {
     for (const h of loadCandidates) {
       s += `- Hit at ${h.address} (cycle ${h.cycle}): supplementary dump \`${h.supplementary_dump ?? "unrecorded"}\`, ` +
         `registry ref \`${h.load_event_ref ?? "unrecorded"}\`. Reproducibility bar: a single capture, decided in ` +
-        `this plan because the claim is about an observed moment rather than a stable state -- if D-13 resolves to ` +
-        `absorbing loaded content into the canonical image, this region must be re-captured at the primary dumps' ` +
-        `three-run bar before Phase 4 treats it as a round-trip diff target.\n`;
+        `the claim is about an observed moment rather than a stable state -- if loaded content is later ` +
+        `absorbed into the canonical image, this region must be re-captured at the primary dumps' ` +
+        `three-run bar before it can be treated as a round-trip diff target.\n`;
     }
     s += "\n";
   }
 
-  s += `### Hand-off to plan 02-02\n\n`;
-  s += "The registry's `watch_set` entries for this release are the re-armable specification: plan 02-02's own " +
-    "executing agent re-arms the same set by issuing the same `mcp__plugin_c64-re-tools_vice__vice_checkpoint_add` calls during Phase " +
-    "2's exhaustive all-chambers trace, and interprets what it observes with this module's pure `attributeAddress`, " +
-    "`reportHits` and `classifyHit` functions. This is a hand-off of data and procedure, not an executable -- plan " +
-    "02-02's own plan text should describe agent-performed arming with acceptance criteria over a committed record " +
+  s += `### Hand-off to the exhaustive trace\n\n`;
+  s += "The registry's `watch_set` entries for this release are the re-armable specification: whoever runs the " +
+    "exhaustive all-chambers trace re-arms the same set by issuing the same `mcp__plugin_c64-re-tools_vice__vice_checkpoint_add` " +
+    "calls, and interprets what it observes with this module's pure `attributeAddress`, " +
+    "`reportHits` and `classifyHit` functions. This is a hand-off of data and procedure, not an executable -- describe " +
+    "agent-performed arming with acceptance criteria over a committed record " +
     "rather than over an exit code. A late hit there reopens this document.\n\n";
 
   s += `### Input sequence notes\n\n`;
   s += (log.input_notes ?? "(no input notes recorded)") + "\n\n";
-  s += "Per D-12 this is plain notes, not a `verify/scripts/` artifact -- VERIFY-01 in Phase 3 owns the real " +
+  s += "This is plain notes, not a `verify/scripts/` artifact -- the replay tooling owns the real " +
     "input-script format; these notes are a seed for it, not a pre-empting specification.\n\n";
 
   s += `### Teardown proof\n\n`;
@@ -445,6 +445,12 @@ function renderReleaseSection(id, log) {
  * string templating over already-fetched data -- nothing here reads a file
  * or contacts anything; the CLI `render` verb below is what reads the
  * hit-log files and writes the result.
+ *
+ * The two script paths named in the output below are deliberately the
+ * consumer's installed location, not this repository's source tree -- this
+ * string is written into a `recovery/LOADING.md` a consumer keeps. A blanket
+ * path sweep rewrote them to the source tree once already; pinned
+ * by the test below plus the class-level registry in skill-consumer-paths.test.ts.
  */
 export function renderLoading(entries) {
   let out = "# `recovery/LOADING.md` -- the on-demand-load detection record\n\n";

package/skills/c64-ram-capture/templates/capture-record.template.md

@@ -4,6 +4,13 @@ One record per capture. Every field is recorded **in the same step as the
 capture**, before the machine is resumed — a value read later describes a
 different machine.
 
+Every `node scripts/…` command cited below is relative to **this skill's own
+directory** (`src/skills/c64-ram-capture/`), not to the repository root. From
+the repo root, use the `$S`-derived variables `SKILL.md`'s quick-reference
+block defines — `node $V slice …` rather than `node scripts/vsf-slice.mjs
+slice …`. Stated once here because the shorthand is used in five rows and
+`scripts/` resolves from neither cwd by accident.
+
 ## Identity
 
 | Field | Value | How obtained |
@@ -11,10 +18,30 @@ different machine.
 | image path | `recovery/<release>/dumps/<name>.bin` | — |
 | size | `65536` bytes | must be exact; anything else is not a full image |
 | sha256 | `<64 hex chars>` | `node scripts/compare.mjs digest <name>.bin` |
+| binary sha256 | `<64 hex chars>` | `sha256sum <release>.d64` (or `.prg`), or `node scripts/compare.mjs digest <release>.d64`. This identifies the release by its **bytes**, never by its filename |
+| argv digest | `<64 hex chars>` | `argvDigest()` in `src/mcp/vice/capture-predicate.ts` — sha256 over the **exact spawn argv array joined by a single NUL byte**. **Order-sensitive by construction**, which is the whole reason it is a field of its own. It refuses an empty argv array rather than digesting the empty string, so a blank here is a blank and never a plausible-looking digest |
+| seed | `4242` | the `-seed` value the instance was launched with — `STOCK_DETERMINISM_SEED` in `src/mcp/vice/broker-launch.mts`. Cite the constant, not a loose number |
+| capture route | `memory-read` \| `snapshot` | `memory-read` = the sixteen `vice_memory_read` calls, transcribed. `snapshot` = `node scripts/vsf-slice.mjs slice <run>.vsf --out <run>.bin`. **This row decides which volatility rule applies to this record** — see the closing note |
 | checkpoint / trigger address | `$____` | the address armed for this capture |
 | release | the registry id this capture belongs to | — |
 | run | `<N>` of `<total>` | three runs is this project's minimum for a verified capture |
 
+### The reproducibility key is the triple, not the seed
+
+**`(binary sha256, argv digest, seed)`.** All three rows, together. Two captures
+share a reproducibility key only when all three fields are exactly equal.
+
+**MEASURED: the same seed with a reordered argv yielded a 76-byte-different
+image.** So the seed alone is not the key, and a record keyed on it claims a
+reproducibility it does not have. Two captures whose argv digests differ are
+**different keys and must not be compared as a pair**, even at the same seed —
+including when the difference is a single reordered element, because the digest
+is order-sensitive and a reordered argv is a different launch.
+
+**A record with any of the three fields blank is not a reproducible capture.**
+The void protocol below applies to it: it is not a capture with a gap in its
+paperwork, it is a capture whose identity cannot be established.
+
 ## Machine state at the capture instant
 
 Read these *before* resuming, in the same paused window as the memory reads.
@@ -30,6 +57,8 @@ Read these *before* resuming, in the same paused window as the memory reads.
 ## Verdict
 
 - [ ] Size is exactly 65536 bytes.
+- [ ] All three reproducibility-key fields — `binary sha256`, `argv digest`, `seed` — are filled. A blank in any one of them fails this box.
+- [ ] The `capture route` row is filled, so a reader knows which volatility rule this record is under.
 - [ ] No epoch-drift error appeared at any point during the capture.
 - [ ] `vice_checkpoint_list` reported zero checkpoints before resuming.
 - [ ] Machine resumed exactly once, at the end.
@@ -53,7 +82,18 @@ and keep the voided artifacts on disk.
 Record the drift floor address count, and state it as a floor rather than a
 complete set — more captures of the same checkpoint can only widen it.
 
-**Any divergence inside `$D000-$DFFF` is not a divergence.** That range is
-register images, not RAM: reading it samples live hardware, so it can never be
-stable across two captures. Classify it as volatile and say so in the record
-rather than voiding a good capture over it.
+### `$D000-$DFFF`: the rule depends on the `capture route` row
+
+This exclusion is a property of **how the image was transcribed**, not of the
+C64. Read the `capture route` row and apply the matching half. Getting this
+backwards costs a good capture in one direction and hides 4096 addresses of real
+divergence in the other.
+
+| `capture route` | Rule for `$D000-$DFFF` |
+|---|---|
+| `memory-read` | **Any divergence inside `$D000-$DFFF` is not a divergence.** On this route the range is read through `vice_memory_read`, which samples live I/O: the VIC's registers repeat every `$40` across `$D000-$D3FF` and the SID's across `$D400-$D7FF`, so two reads can never agree there. Classify it as volatile, say so in the record, and do not void a good capture over it. |
+| `snapshot` | **The exclusion does not apply, and a divergence there is a real divergence.** A `.vsf`-sliced image is the `C64MEM` array — `mem_ram[]`, which is RAM *under* I/O and not the register read view — so those 4096 addresses are ordinary RAM in a sliced image. There is no transcription step on this route to sample anything. Do not carry the memory-read exclusion across. |
+
+Both halves are live: records taken on the memory-read route still exist and
+still need the first row. What is not permitted is applying either half without
+reading which route produced the image.

package/skills/c64-ram-capture/transients/README.md

@@ -0,0 +1,136 @@
+# Per-release transient allow-lists
+
+One committed JSON artifact per release, written by
+`../scripts/derive-transients.mjs derive`. Nothing in this directory is
+inherited, hand-edited or carried across releases.
+
+**What carries forward is the method below and the script that implements it.
+Never an address set.** A real release's transients are its own frame counters,
+RNG state, sprite positions and music-player pointers. An allow-list borrowed
+from another release cannot be distinguished afterwards from one honestly
+derived, so a contaminated ledger has no cheap repair — it has to be re-derived
+from fresh captures.
+
+## The committed derivation method
+
+Verbatim, because this is the part that is meant to survive:
+
+- **N >= 3 runs** of the **same release** under the **same protocol** at the
+  **same stop**. Three runs is already this project's documented minimum for a
+  verified capture. Fewer is refused, naming the count and the minimum.
+- The allow-list is the **union of addresses differing across the pairwise
+  comparisons** — every pairing, which is N(N-1)/2 for N images, not just the
+  adjacent ones.
+- Each entry records **the address**, **which run pairs it differed in**, the
+  distinct byte values seen, and **a one-line attribution where known** (left
+  empty otherwise, so an unattributed transient is visibly unattributed rather
+  than absent).
+- It is **re-derived per release**, and **no address set is ever inherited
+  between releases**. Re-deriving over an existing artifact is refused without
+  an explicit `--force`.
+- The list is **enumerated** — one entry per address, never a range, a span, a
+  page or a region. `parseAllowList()` in
+  `src/mcp/vice/capture-predicate.ts` refuses range-shaped keys by name.
+- There is **no bit-count tolerance** at any address. A one-bit difference
+  outside the list fails.
+
+```bash
+S=src/skills/c64-ram-capture/scripts      # from the repo root
+T=src/skills/c64-ram-capture/transients
+
+node $S/derive-transients.mjs derive --release <id> \
+  --out $T/<id>.json run1.bin run2.bin run3.bin
+
+node $S/derive-transients.mjs check --allow-list $T/<id>.json runA.bin runB.bin
+```
+
+## The artifact shape
+
+```json
+{
+  "schema_version": "1.0",
+  "release": "<the registry id the runs came from>",
+  "derived_from": ["run1.bin", "run2.bin", "run3.bin"],
+  "pair_count": 3,
+  "cap": 64,
+  "method": "union of addresses differing across every pairwise comparison ...",
+  "entries": [
+    {
+      "address": 164,
+      "pairs": ["run1.bin vs run2.bin", "run2.bin vs run3.bin"],
+      "values": ["$11", "$22"],
+      "attribution": ""
+    }
+  ]
+}
+```
+
+`entries` is ascending by address, so the artifact is diffable and an entry's
+position never depends on which pairing happened to observe it first. `address`
+is an integer; `values` are the distinct bytes seen at it, in hex, across every
+pairing it differed in. This is exactly the shape `parseAllowList()` accepts —
+there is no translation step between the derivation and the predicate, and the
+derivation's colocated test asserts the round-trip rather than assuming it.
+
+## The cap is 64, and exceeding it VOIDS the derivation
+
+`TRANSIENT_ALLOW_LIST_CAP = 64` in `src/mcp/vice/capture-predicate.ts` is the
+one definition; the script's default cap is asserted equal to it by test.
+`--cap` **only ever narrows** — a value above the committed cap is refused by
+name.
+
+**Over the cap is not "the list is a bit long".** It means **the stop is not
+frame-exact**, and that is a fact the gate must hear rather than a threshold to
+move. So the script exits non-zero, writes **no artifact at all** — not a
+partial one and not a truncated one — and says so. A list truncated to fit the
+cap would make every later comparison pass on bytes nobody vetted, which is the
+one failure this rule exists to remove. Raising the cap after seeing a
+derivation overflow converts a measurement into an excuse.
+
+### What the cap actually distinguishes — four measured reference points
+
+The cap does not separate "a few transients" from "a lot of transients". It
+separates **a frame-exact stop** from **a stop that is not**. The numbers, all
+measured on this host:
+
+| Differing addresses | The stop that produced it | Verdict under the cap |
+|---|---|---|
+| **0** | frame-exact stop at the KERNAL `READY` prompt | derivation writes |
+| **66** | autostarted stop, frame anchor, pre-protocol jitter 4000 ms (48 for the reported jitter-0/2500 pair) | **VOID** — 2 over |
+| **300** | wall-clock autostarted stop on a real cracked release | **VOID** — 4.7× the cap |
+| **1242** | wall-clock `READY`-prompt stop with the determinism block fully applied | **VOID** — 19× the cap |
+
+Read the second row carefully: **overflow is an observed outcome, not a
+hypothetical.** A frame-anchored autostarted stop has already been measured
+over the cap at one jitter and under it at another. The answer to that is a
+better stop, recorded with the jitter it was taken at — not a bigger cap.
+
+The 1242 row is also the reason the seed is not the whole story: that stop had
+the determinism block applied and still differed at 1242 bytes, because it was
+wall-clock-anchored. The residual is what the reset protocol and the frame
+anchor close, not what the seed does.
+
+## `$0000` / `$0001` do not belong in a derived list by hand
+
+The 6510 port overlay is normalised **in code**, once, by `normalisePorts()` on
+the snapshot route. Spending two of the cap's 64 slots on those two addresses
+would hide a real difference behind a known one. They can legitimately appear in
+a derivation taken from un-normalised images — `derive` compares the bytes it is
+given — so if you see them in an artifact, that is what it is telling you about
+the images, not a rule to add.
+
+## What this directory refuses, and why now
+
+`.gitignore` here refuses every image byte form — flat captures, disk and tape
+images, cartridges, `.vsf` snapshots, and the archives an image arrives inside —
+and it was committed **before the first derivation existed**. A directory that
+starts refusing images after the first capture lands has already had one
+commit's worth of opportunity to leak one. JSON is deliberately not refused:
+the derived allow-lists are the artifacts this directory is for.
+
+**If you are reading this from an installed copy of the skill, that `.gitignore`
+did not come with it.** npm excludes a nested `.gitignore` from a published
+tarball, so the installed `transients/` directory has this README and nothing
+else. Add the same refusals to your own project's ignore rules before you take
+the first capture — the whole point of the timing is that it happens before,
+not after.