@henols/c64-re-tools 0.2.4 → 1.0.0

package/skills/c64-ram-capture/scripts/compare-cross-binary.mjs

@@ -0,0 +1,525 @@
+#!/usr/bin/env node
+// Cross-binary RAM/chip-state comparison: classify every difference between
+// two captures of DIFFERENT binaries and print a single VERDICT line.
+//
+// Pure logic. This module reads files the agent already produced and does
+// arithmetic over them. It contacts nothing: the mcp__plugin_c64-re-tools_vice__*
+// tools are the only route to the emulator (.claude/CLAUDE.md § Emulator
+// Access), and nothing here opens a connection, reads broker state, or shells
+// out.
+//
+// The narrowed volatile mask below is committed here, in this commit, before
+// any rebuild is compared under it (ROADMAP Phase 50 criterion 1). The mask
+// may be narrowed further later. It must never be widened just to make a
+// rebuild pass -- the same discipline `compare.mjs` and `derive-transients.mjs`
+// already carry for their own masks/allow-lists.
+//
+// This is a SIBLING of `compare.mjs`, not an extension of it. `compare.mjs`'s
+// own rules -- a blanket $D000-$DFFF mask and a one-bit "drift" tolerance --
+// are correct for its own job: two captures of the SAME binary at the same
+// checkpoint. Both rules are wrong for this module's job, which is two
+// captures of DIFFERENT binaries, where a one-bit difference at a masked
+// address (e.g. `lda #$02` -> `lda #$03` ahead of `sta $d020`) is exactly the
+// kind of regression a rebuild must not be allowed to hide. This module does
+// not import from, edit, or re-export `compare.mjs`; its rules stay frozen
+// for its own, still-correct, same-binary job. The three-bucket shape and the
+// classification core are duplicated here DELIBERATELY, not shared, so a
+// future edit to one module's rules cannot silently change the other's.
+//
+// Three rule departures from compare.mjs, each load-bearing:
+//
+//   (a) NO DRIFT BUCKET. Across two different binaries a one-bit difference
+//       is a real difference. `drift` exists to absorb sampling noise between
+//       two runs of the SAME binary; applied across binaries it would absorb
+//       an `lda #$02` to `lda #$03` regression whole. Every non-volatile,
+//       non-allowlisted difference is a divergence here, regardless of bit
+//       count.
+//   (b) NARROWED I/O MASK. `compare.mjs` masks $D000-$DFFF entirely. This
+//       module masks only the addresses and register fields that genuinely
+//       cannot be stable, listed individually below with a reason each.
+//   (c) ROUTE AWARENESS. A capture carries a declared route of "snapshot" or
+//       "memory-read". On the snapshot route the bytes at $D000-$DFFF in the
+//       image are RAM under I/O, not the register read view (SKILL.md,
+//       "Slice the image out of a snapshot instead of transcribing it"); on
+//       the memory-read route they are the register read view. Comparing one
+//       against the other is meaningless, so this module refuses the pair.
+//
+// Departure from compare.mjs's own CLI-dispatch shape: the dispatch tail at
+// the bottom of this file is GUARDED
+// (`if (process.argv[1] === fileURLToPath(import.meta.url))`), unlike
+// compare.mjs's unguarded tail. This module exports IMAGE_VOLATILE and
+// IO_VOLATILE for reuse by this file's own test file and by later Phase 50
+// plans; an unguarded tail would call process.exit() the instant anything
+// imports this module, killing whatever process did the importing.
+// `dump-artifacts.mjs`, the newer script in this same directory, already
+// carries the identical guard for the identical reason.
+
+import { readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { basename, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const IMAGE_BYTES = 65536;
+
+// A hand-bumped version string, printed into every report as
+// `MASK_NARROWED_AT:` so a transcript records which mask produced it. Bump
+// this whenever a mask span in IMAGE_VOLATILE or IO_VOLATILE changes --
+// never silently, and never to make a rebuild pass.
+const MASK_VERSION = "compare-cross-binary-mask-v1";
+
+// ---------------------------------------------------------------- IMAGE_VOLATILE
+
+// Spans of the 64K image that are excluded from the verdict on every route.
+// Carried forward from compare.mjs's own VOLATILE table, same reasons.
+export const IMAGE_VOLATILE = [
+  { lo: 0x0000, hi: 0x0001, reason: "CPU port" },
+  { lo: 0x0100, hi: 0x01ff, reason: "stack page" },
+  { lo: 0x0200, hi: 0x03ff, reason: "KERNAL work area / BASIC input buffer" },
+];
+
+// ------------------------------------------------------------------- IO_VOLATILE
+
+// Register offsets and ranges that stay excluded, each with its own one-line
+// hardware reason. The VIC-II only decodes 6 address bits, so its registers
+// at $D000-$D02E mirror every $40 bytes across the whole $D000-$D3FF window
+// -- entries here for that window are expressed as the CANONICAL address in
+// the first $D000-$D03F block and folded across all sixteen mirrors by
+// (addr & 0x3f) in isIoVolatile()/imageMaskEntryFor() below, so a regression
+// at $D020 is caught at $D020 and at all fifteen of its mirrors.
+//
+// Everything else in $D000-$D3FF -- $D000-$D010, $D013-$D018, $D01A-$D01D
+// and $D020-$D02E -- is deliberately NOT masked. $D015, $D018 and $D020 are
+// the three ROADMAP criterion 1 names inside that carve-out.
+const VIC_MIRRORED_VOLATILE = [
+  {
+    lo: 0xd011,
+    hi: 0xd011,
+    reason: "bit 7 is the raster counter's ninth bit, so the whole byte is masked",
+  },
+  { lo: 0xd012, hi: 0xd012, reason: "the raster counter" },
+  { lo: 0xd019, hi: 0xd019, reason: "the interrupt latch" },
+  { lo: 0xd01e, hi: 0xd01f, reason: "the collision latches, cleared by reading them" },
+];
+
+// Ranges outside the VIC-II mirrored window. These do not mirror the same
+// way -- SID/colour-RAM/CIA/expansion each occupy their own flat span -- so
+// no offset-folding applies; the whole range is excluded.
+const FLAT_VOLATILE = [
+  { lo: 0xd400, hi: 0xd7ff, reason: "SID is write-only in hardware, read-back is unrecoverable" },
+  { lo: 0xd800, hi: 0xdbff, reason: "colour RAM whose high nibble is open bus" },
+  {
+    lo: 0xdc00,
+    hi: 0xdcff,
+    reason: "CIA1 -- timers, time-of-day and interrupt-control registers all move without the program touching them",
+  },
+  {
+    lo: 0xdd00,
+    hi: 0xddff,
+    reason: "CIA2 -- timers, time-of-day and interrupt-control registers all move without the program touching them",
+  },
+  { lo: 0xde00, hi: 0xdfff, reason: "I/O expansion area and reads open bus" },
+];
+
+export const IO_VOLATILE = [...VIC_MIRRORED_VOLATILE, ...FLAT_VOLATILE];
+
+function ioMaskEntryFor(addr) {
+  if (addr >= 0xd000 && addr <= 0xd3ff) {
+    const canonical = 0xd000 + (addr & 0x3f);
+    return VIC_MIRRORED_VOLATILE.find(({ lo, hi }) => canonical >= lo && canonical <= hi) ?? null;
+  }
+  return FLAT_VOLATILE.find(({ lo, hi }) => addr >= lo && addr <= hi) ?? null;
+}
+
+export function isIoVolatile(addr) {
+  return ioMaskEntryFor(addr) !== null;
+}
+
+function imageMaskEntryFor(addr, route) {
+  const base = IMAGE_VOLATILE.find(({ lo, hi }) => addr >= lo && addr <= hi);
+  if (base) return base;
+  if (route === "memory-read" && addr >= 0xd000 && addr <= 0xdfff) {
+    return ioMaskEntryFor(addr);
+  }
+  // snapshot route: $D000-$DFFF in the image is ordinary RAM under I/O, not
+  // the register read view -- not masked at all. See SKILL.md, "Slice the
+  // image out of a snapshot instead of transcribing it".
+  return null;
+}
+
+export function isImageVolatile(addr, route) {
+  return imageMaskEntryFor(addr, route) !== null;
+}
+
+// -------------------------------------------------------------------- format
+
+const hex4 = (n) => "$" + n.toString(16).toUpperCase().padStart(4, "0");
+const hex2 = (n) => "$" + n.toString(16).toUpperCase().padStart(2, "0");
+const bin8 = (n) => "%" + n.toString(2).padStart(8, "0");
+
+function loadImage(path) {
+  const buf = readFileSync(path);
+  if (buf.length !== IMAGE_BYTES) {
+    throw new Error(`${path}: ${buf.length} bytes, expected ${IMAGE_BYTES} — not a full 64K image`);
+  }
+  return buf;
+}
+
+const sha256 = (buf) => createHash("sha256").update(buf).digest("hex");
+
+// ---------------------------------------------------------------------- state
+
+// --state <a.state.json> loads a per-capture sidecar this module defines its
+// own way -- distinct from, but inspired by, `dump-artifacts.mjs`'s
+// chip-state output shape (`registers`/`sprites`/`cpu`), since no committed
+// chip-state sidecar carries $Dxxx register values directly today. The shape
+// this module reads:
+//
+//   {
+//     "route": "snapshot" | "memory-read",
+//     "registers": { "$D011": 27, "53272": 21, "0xD020": 14 }
+//   }
+//
+// `registers` keys may be a "$Dxxx" hex string, a "0xNNNN" hex string, or a
+// bare decimal string -- whatever the caller already has to hand. Every key
+// must parse as an address or the sidecar is refused by name. `registers` is
+// optional: a capture with no chip-state evidence compares on the image
+// alone.
+function loadState(path) {
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+
+function parseAddrKey(k) {
+  if (/^\$[0-9a-fA-F]+$/.test(k)) return parseInt(k.slice(1), 16);
+  if (/^0x[0-9a-fA-F]+$/i.test(k)) return parseInt(k, 16);
+  if (/^\d+$/.test(k)) return parseInt(k, 10);
+  return null;
+}
+
+function normalizeRegisters(stateDoc, path) {
+  const map = new Map();
+  const raw = stateDoc?.registers;
+  if (!raw) return map;
+  for (const [k, v] of Object.entries(raw)) {
+    const addr = parseAddrKey(k);
+    if (addr === null) {
+      throw new Error(`${path}: register key "${k}" is not a parseable address -- refused`);
+    }
+    map.set(addr, v);
+  }
+  return map;
+}
+
+// ----------------------------------------------------------------- allowlist
+
+// --allowlist <path> loads the intentional-difference document. Shape:
+//
+//   {
+//     "checkpoint": "hazard_raster_entry",
+//     "subjects": { "hazard-subject-modified": "<sha256 of the .prg>" },
+//     "entries": [
+//       { "start": 8221, "endInclusive": 8221, "domain": "image", "why": "..." }
+//     ]
+//   }
+//
+// Every entry is validated at load time and refused BY NAME on: a missing or
+// whitespace-only `why`; a `start` above `endInclusive`; a range that
+// intersects a masked span (mask wins -- an allowlist can never re-admit a
+// hardware-volatile address, so a real difference can never be smuggled in
+// under a masked address's cover); and a document `checkpoint` that does not
+// match the checkpoint the two captures themselves declare. This is
+// semantically distinct from the mask tables above -- hardware noise versus a
+// deliberate difference -- and is kept in its own bucket, never folded into
+// IMAGE_VOLATILE/IO_VOLATILE, so ROADMAP criterion 2's distinction stays
+// visible in the record.
+function loadAllowlist(path, { route, checkpointName }) {
+  const doc = JSON.parse(readFileSync(path, "utf8"));
+  const entries = doc.entries ?? [];
+
+  if (checkpointName && doc.checkpoint && doc.checkpoint !== checkpointName) {
+    throw new Error(
+      `${path}: allowlist declares checkpoint "${doc.checkpoint}", captures declare "${checkpointName}" -- refused`,
+    );
+  }
+
+  for (const e of entries) {
+    const rangeLabel =
+      e.start === e.endInclusive ? hex4(e.start) : `${hex4(e.start)}-${hex4(e.endInclusive)}`;
+    if (!e.why || !String(e.why).trim()) {
+      throw new Error(
+        `${path}: allowlist entry ${rangeLabel} has no why -- an allowlist entry without a non-empty why string is refused`,
+      );
+    }
+    if (!(e.start <= e.endInclusive)) {
+      throw new Error(`${path}: allowlist entry ${rangeLabel} has start above endInclusive -- refused`);
+    }
+    const domain = e.domain === "register" ? "register" : "image";
+    for (let addr = e.start; addr <= e.endInclusive; addr++) {
+      const maskEntry = domain === "register" ? ioMaskEntryFor(addr) : imageMaskEntryFor(addr, route);
+      if (maskEntry) {
+        throw new Error(
+          `${path}: allowlist entry ${rangeLabel} (${domain}) overlaps the masked span ` +
+            `${hex4(maskEntry.lo)}-${hex4(maskEntry.hi)} (${maskEntry.reason}) -- overlap between an ` +
+            `allowlist entry and the volatile mask is refused`,
+        );
+      }
+    }
+  }
+
+  return { checkpoint: doc.checkpoint ?? null, subjects: doc.subjects ?? {}, entries };
+}
+
+function findAllowlistEntry(allowlist, addr, domain) {
+  if (!allowlist) return null;
+  for (const e of allowlist.entries) {
+    const eDomain = e.domain === "register" ? "register" : "image";
+    if (eDomain !== domain) continue;
+    if (addr >= e.start && addr <= e.endInclusive) return e;
+  }
+  return null;
+}
+
+// -------------------------------------------------------------- classification
+
+/**
+ * Classify every differing address between two captures -- image bytes plus,
+ * when both sides carry a chip-state sidecar, register values. Precedence is
+ * volatile first, then allowlisted, then divergence -- the same "mask wins
+ * over everything else" precedence compare.mjs already uses for isVolatile,
+ * extended one step further: allowlist wins over bit-count too. There is no
+ * fourth bucket and no bit-count branch: every non-volatile,
+ * non-allowlisted difference is a divergence, one bit or many.
+ */
+export function classify({ imgA, imgB, route, regMapA, regMapB, allowlist }) {
+  const volatile_ = [];
+  const allowlisted = [];
+  const divergence = [];
+
+  for (let addr = 0; addr < IMAGE_BYTES; addr++) {
+    const x = imgA[addr];
+    const y = imgB[addr];
+    if (x === y) continue;
+
+    const rec = { addr, a: x, b: y, domain: "image" };
+    if (isImageVolatile(addr, route)) {
+      volatile_.push(rec);
+      continue;
+    }
+    const aw = findAllowlistEntry(allowlist, addr, "image");
+    if (aw) {
+      allowlisted.push({ ...rec, why: aw.why });
+      continue;
+    }
+    divergence.push(rec);
+  }
+
+  if (regMapA && regMapB && regMapA.size && regMapB.size) {
+    const addrs = new Set([...regMapA.keys(), ...regMapB.keys()]);
+    for (const addr of [...addrs].sort((p, q) => p - q)) {
+      const x = regMapA.get(addr);
+      const y = regMapB.get(addr);
+      // Present on only one side -- not comparable, not counted either way.
+      if (x === undefined || y === undefined) continue;
+      if (x === y) continue;
+
+      const rec = { addr, a: x, b: y, domain: "register" };
+      if (isIoVolatile(addr)) {
+        volatile_.push(rec);
+        continue;
+      }
+      const aw = findAllowlistEntry(allowlist, addr, "register");
+      if (aw) {
+        allowlisted.push({ ...rec, why: aw.why });
+        continue;
+      }
+      divergence.push(rec);
+    }
+  }
+
+  return { volatile: volatile_, allowlisted, divergence, pass: divergence.length === 0 };
+}
+
+// ------------------------------------------------------------------- printing
+
+const fmtDiffRow = (r) =>
+  `  ${hex4(r.addr)}  ${hex2(r.a)} ${bin8(r.a)}  ->  ${hex2(r.b)} ${bin8(r.b)}   [${r.domain}]`;
+
+function printList(title, rows, limit) {
+  console.log(`\n${title}: ${rows.length}`);
+  if (!rows.length) return;
+  // --limit 0 means unlimited, matching the usage text. Anything else caps.
+  const shown = limit ? rows.slice(0, limit) : rows;
+  for (const r of shown) {
+    const why = r.why ? `  -- ${r.why}` : "";
+    console.log(fmtDiffRow(r) + why);
+  }
+  if (shown.length < rows.length) {
+    console.log(`  … ${rows.length - shown.length} more (--limit 0 for all)`);
+  }
+}
+
+// ---------------------------------------------------------------------- cross
+
+function parseCrossArgs(argv) {
+  const positional = [];
+  let statePaths = null;
+  let allowlistPath = null;
+  let noAllowlist = false;
+  let checkpointAssert = null;
+  let routeAssert = null;
+  let limit;
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--state") {
+      statePaths = [argv[++i], argv[++i]];
+    } else if (a === "--allowlist") {
+      allowlistPath = argv[++i];
+    } else if (a === "--no-allowlist") {
+      noAllowlist = true;
+    } else if (a === "--checkpoint") {
+      checkpointAssert = argv[++i];
+    } else if (a === "--route") {
+      routeAssert = argv[++i];
+    } else if (a === "--limit") {
+      const n = Number(argv[++i]);
+      if (!Number.isInteger(n) || n < 0) throw new Error("--limit needs a non-negative integer");
+      limit = n;
+    } else {
+      positional.push(a);
+    }
+  }
+
+  if (positional.length !== 2) throw new Error("cross needs exactly two image paths");
+  return {
+    imagePaths: positional,
+    statePaths,
+    allowlistPath,
+    noAllowlist,
+    checkpointAssert,
+    routeAssert,
+    limit,
+  };
+}
+
+function cmdCross(argv) {
+  const opts = parseCrossArgs(argv);
+  const [pa, pb] = opts.imagePaths;
+  const imgA = loadImage(pa);
+  const imgB = loadImage(pb);
+
+  const stateA = opts.statePaths ? loadState(opts.statePaths[0]) : null;
+  const stateB = opts.statePaths ? loadState(opts.statePaths[1]) : null;
+
+  const routeA = stateA?.route ?? opts.routeAssert ?? "memory-read";
+  const routeB = stateB?.route ?? opts.routeAssert ?? "memory-read";
+  if (routeA !== routeB) {
+    throw new Error(
+      `capture routes differ -- A declares "${routeA}", B declares "${routeB}". Comparing a ` +
+        `snapshot-route capture against a memory-read-route capture is meaningless; refused.`,
+    );
+  }
+  const route = routeA;
+
+  const checkpointA = stateA?.checkpoint_name ?? null;
+  const checkpointB = stateB?.checkpoint_name ?? null;
+  if (checkpointA && checkpointB && checkpointA !== checkpointB) {
+    throw new Error(
+      `logical checkpoints differ -- A resolved "${checkpointA}", B resolved "${checkpointB}". A ` +
+        `comparison whose two captures name different logical checkpoints is refused.`,
+    );
+  }
+  const checkpointName = checkpointA ?? checkpointB ?? null;
+  if (opts.checkpointAssert && checkpointName && opts.checkpointAssert !== checkpointName) {
+    throw new Error(
+      `--checkpoint asserted "${opts.checkpointAssert}", captures declare "${checkpointName}" -- refused`,
+    );
+  }
+
+  const regMapA = stateA ? normalizeRegisters(stateA, opts.statePaths[0]) : null;
+  const regMapB = stateB ? normalizeRegisters(stateB, opts.statePaths[1]) : null;
+
+  const allowlist =
+    opts.allowlistPath && !opts.noAllowlist
+      ? loadAllowlist(opts.allowlistPath, { route, checkpointName })
+      : null;
+
+  const haA = sha256(imgA);
+  const haB = sha256(imgB);
+
+  console.log(`A  ${basename(pa)}  sha256 ${haA}`);
+  console.log(`B  ${basename(pb)}  sha256 ${haB}`);
+  console.log(`MASK_NARROWED_AT: ${MASK_VERSION}`);
+  if (checkpointA) {
+    console.log(`A  checkpoint ${checkpointA} @ ${hex4(stateA.checkpoint_address ?? 0)}`);
+  }
+  if (checkpointB) {
+    console.log(`B  checkpoint ${checkpointB} @ ${hex4(stateB.checkpoint_address ?? 0)}`);
+  }
+
+  const byteIdentical = haA === haB;
+  console.log(`\nBYTE_IDENTICAL: ${byteIdentical ? "yes" : "no"}`);
+  console.log("  (a recorded extra -- the VERDICT line below is the acceptance signal, not this one)");
+
+  // Always classify, even when the images are byte-identical: a chip-state-
+  // only regression must still be caught. Unlike compare.mjs's cmdCompare(),
+  // there is no early return on equal digests here -- see this plan's
+  // assumption_delta_decision, which demotes byte-identity to a recorded
+  // extra and promotes behavioural equivalence (the full classification) to
+  // the actual acceptance criterion.
+  const r = classify({ imgA, imgB, route, regMapA, regMapB, allowlist });
+
+  printList("volatile (excluded from the verdict)", r.volatile, opts.limit);
+  printList("allowlisted (intentional difference, excluded from the verdict)", r.allowlisted, opts.limit);
+  printList("DIVERGENCE — fails the comparison", r.divergence, opts.limit);
+
+  const total = r.volatile.length + r.allowlisted.length + r.divergence.length;
+  console.log(`\ntotal differing addresses (image + register): ${total}`);
+  console.log(`\nVERDICT: ${r.pass ? "PASS" : "FAIL"}`);
+  return r.pass ? 0 : 1;
+}
+
+// -------------------------------------------------------------------- dispatch
+
+const commands = { cross: cmdCross };
+
+function usage() {
+  return `usage: node compare-cross-binary.mjs <command>
+
+  cross <a.bin> <b.bin> [--state <a.state.json> <b.state.json>]
+        [--allowlist <path>] [--no-allowlist] [--checkpoint <name>]
+        [--route <snapshot|memory-read>] [--limit N]
+    classify every difference between two captures of DIFFERENT binaries and
+    print a single VERDICT line.
+
+No drift bucket here: every non-volatile, non-allowlisted difference fails,
+regardless of bit count -- unlike compare.mjs, which is for two captures of
+the SAME binary. Volatile registers (excluded): $D011, $D012, $D019,
+$D01E-$D01F, $D400-$D7FF, $D800-$DBFF, $DC00-$DCFF, $DD00-$DDFF, $DE00-$DFFF
+(mirrored across $D000-$D3FF where applicable). $D015, $D018 and $D020 are
+deliberately NOT masked.
+--limit 0 prints every row. Exit status is 1 on a FAIL verdict, non-zero on
+any refusal (mismatched route, mismatched checkpoint, a malformed allowlist,
+a malformed image).
+
+Captures come from the procedure in c64-ram-capture/SKILL.md, via
+mcp__plugin_c64-re-tools_vice__*. This script contacts nothing.`;
+}
+
+function main() {
+  const [cmd, ...rest] = process.argv.slice(2);
+  if (!cmd || !commands[cmd]) {
+    console.error(usage());
+    process.exit(cmd ? 1 : 0);
+    return;
+  }
+  try {
+    process.exit(commands[cmd](rest));
+  } catch (e) {
+    console.error(`error: ${e.message}`);
+    process.exit(1);
+  }
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main();
+}

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

@@ -1,14 +1,14 @@
 # Capture record — `<release>-<checkpoint>-run<N>`
 
-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
+One record per capture. The reader records every field **in the same step as the
+capture**, before resuming the machine — 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
+slice …`. Stated once here because five rows use the shorthand, and
 `scripts/` resolves from neither cwd by accident.
 
 ## Identity
@@ -16,11 +16,11 @@ slice …`. Stated once here because the shorthand is used in five rows and
 | Field | Value | How obtained |
 |---|---|---|
 | image path | `recovery/<release>/dumps/<name>.bin` | — |
-| size | `65536` bytes | must be exact; anything else is not a full image |
+| 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 |
+| seed | `4242` | the `-seed` value the broker set when it launched the instance — `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 | — |
@@ -57,13 +57,13 @@ 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.
+- [ ] All three reproducibility-key fields — `binary sha256`, `argv digest`, `seed` — hold a value. A blank in any one of them fails this box.
+- [ ] The `capture route` row holds a value, 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.
 
-If any box is unchecked, void the run: rename each artifact to
+If any box stays unchecked, void the run: rename each artifact to
 `<name>.VOID-<UTC timestamp>`, write a sibling note giving the reason and — when a
 drift error was the cause — both epoch values quoted from that error's own text,
 and keep the voided artifacts on disk.
@@ -84,15 +84,15 @@ complete set — more captures of the same checkpoint can only widen 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
+This exclusion is a property of **how you transcribed the image**, 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. |
+| `memory-read` | **Any divergence inside `$D000-$DFFF` is not a divergence.** On this route, `vice_memory_read` reads the range and samples live I/O. The VIC's registers repeat every `$40` across `$D000-$D3FF`, and the SID's registers repeat every `$40` across `$D400-$D7FF`. 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[]`. This array is RAM *under* I/O, 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

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

@@ -17,7 +17,8 @@ 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.
+  verified capture. `derive` refuses fewer than three runs, 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.
@@ -26,8 +27,8 @@ Verbatim, because this is the part that is meant to survive:
   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`.
+  between releases**. `derive` refuses a re-derivation over an existing
+  artifact 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.
@@ -67,7 +68,7 @@ node $S/derive-transients.mjs check --allow-list $T/<id>.json runA.bin runB.bin
 
 `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
+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.
@@ -75,9 +76,9 @@ 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.
+one definition. A test asserts the script's default cap equal to it.
+`--cap` **only ever narrows**. `derive` refuses a value above the committed cap
+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
@@ -103,7 +104,7 @@ measured on this host:
 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.
+better stop, recorded together with the jitter value — 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
@@ -112,7 +113,7 @@ 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
+`normalisePorts()` normalises the 6510 port overlay **in code**, once, 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
@@ -123,7 +124,7 @@ the images, not a rule to add.
 
 `.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
+and this project committed it **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.