@henols/c64-re-tools 1.1.0 → 2.0.0-rc.2

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

@@ -1,581 +0,0 @@
-#!/usr/bin/env node
-// The on-demand-load detector's pure logic (01-04 Task 1). Every function
-// here takes already-fetched data as an argument or reads a committed file
-// -- nothing in this module contacts the emulator, ever. The single
-// permitted route to the emulator is the executing agent's own
-// `mcp__plugin_c64-re-tools_vice__*` tool calls (see .claude/CLAUDE.md "Emulator Access");
-// arming, resuming, polling, disassembling and reading memory all happen in
-// the agent's own turn, and the observations land in a committed hit-log
-// JSON (`recovery/<release>/dumps/<release>-loading-hits.json`) that this
-// module reads back. The import-purity guard test in
-// tools/watch-loads.test.mjs is the mechanical statement of that boundary:
-// every import specifier in this file resolves to a `node:` built-in or a
-// sibling file inside tools/, so this module cannot acquire an outside
-// dependency without the guard failing.
-import { readFileSync, writeFileSync, existsSync } from "node:fs";
-import { createHash } from "node:crypto";
-import { fileURLToPath } from "node:url";
-import { dirname, join, resolve, relative } from "node:path";
-
-import { loadRegistry, release as getReleaseEntry, upsertRelease } from "./releases.mjs";
-import { projectRoot, dataRoot } from "./project-paths.mjs";
-
-const HERE = dirname(fileURLToPath(import.meta.url));
-const REPO_ROOT = projectRoot();
-const RECOVERY_DIR = dataRoot();
-
-const die = (m) => { console.error(`error: ${m}`); process.exit(1); };
-
-function rel(p) {
-  return relative(REPO_ROOT, p);
-}
-
-// ------------------------------------------------------------ address math
-
-/** Parse `"$08B1"`, `"0x8b1"`, a decimal string, or a number into an integer. */
-export function addrNum(a) {
-  if (typeof a === "number") return a;
-  if (typeof a === "string") {
-    const s = a.trim();
-    if (s.startsWith("$")) return parseInt(s.slice(1), 16);
-    if (/^0x/i.test(s)) return parseInt(s, 16);
-    const n = Number(s);
-    if (Number.isNaN(n)) throw new Error(`addrNum: cannot parse address from "${a}"`);
-    return n;
-  }
-  throw new Error(`addrNum: cannot parse address from ${JSON.stringify(a)}`);
-}
-
-/** Format an integer as a canonical `$XXXX` 4-hex-digit address string. */
-export function hex4(n) {
-  return "$" + (n & 0xffff).toString(16).toUpperCase().padStart(4, "0");
-}
-
-// -------------------------------------------------------------- hit-log I/O
-
-function hitLogPath(releaseId) {
-  return join(RECOVERY_DIR, releaseId, "dumps", `${releaseId}-loading-hits.json`);
-}
-
-/** Read and JSON.parse a release's committed boundary hit-log artifact. */
-export function readHitLog(releaseId) {
-  const p = hitLogPath(releaseId);
-  if (!existsSync(p)) {
-    throw new Error(`readHitLog: no hit log at ${rel(p)} for release "${releaseId}"`);
-  }
-  return JSON.parse(readFileSync(p, "utf8"));
-}
-
-/**
- * Structural validation of a hit-log's boundary-artifact shape: every
- * `armed` entry must carry the `checkpoint_num` the arming call returned,
- * and `teardown.checkpoints_remaining` must be present -- both are the
- * "the delete call's own word is never the proof" invariant made mechanical.
- */
-export function validateHitLog(log) {
-  const errors = [];
-  for (const a of log.armed ?? []) {
-    if (a.checkpoint_num === undefined || a.checkpoint_num === null) {
-      errors.push(`armed sentinel "${a.name}" is missing checkpoint_num`);
-    }
-  }
-  if (!log.teardown || log.teardown.checkpoints_remaining === undefined || log.teardown.checkpoints_remaining === null) {
-    errors.push("teardown.checkpoints_remaining is not recorded");
-  }
-  return { ok: errors.length === 0, errors };
-}
-
-// --------------------------------------------------------------- WATCH_SET
-
-function loadManifestForRelease(rel) {
-  const dump = (rel.dumps ?? []).find((d) => d.label === "run1");
-  if (!dump || !dump.range_manifest) {
-    throw new Error(`WATCH_SET: release "${rel.id}" has no run1 dump with a range_manifest recorded`);
-  }
-  const manifestPath = join(REPO_ROOT, dump.range_manifest);
-  return JSON.parse(readFileSync(manifestPath, "utf8"));
-}
-
-/**
- * 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). `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
- * raw-sector loader toggles directly -- the primary on-demand-load sentinel
- * precisely because such a loader leaves no KERNAL vector activity to watch
- * instead.
- */
-export function WATCH_SET(releaseId, { registry, manifest } = {}) {
-  const reg = registry ?? loadRegistry();
-  const rel = reg.releases.find((r) => r.id === releaseId);
-  if (!rel) {
-    throw new Error(`WATCH_SET: unknown release "${releaseId}" -- known releases: ${reg.releases.map((r) => r.id).join(", ")}`);
-  }
-  const loaderRanges = rel.loader_ranges ?? [];
-  if (loaderRanges.length === 0) {
-    throw new Error(
-      `WATCH_SET: release "${releaseId}" has no loader_ranges recorded -- derive and record loader_ranges ` +
-        `(earn them live against a disassembly, per plan Task 2 step 1) before resolving a watch set; a set ` +
-        `with no re-entry sentinel in it is not a two-tier set`
-    );
-  }
-  const map = manifest ?? loadManifestForRelease(rel);
-  const neverPopulated = (map.ranges ?? []).filter((r) => r.kind === "unused");
-
-  const sentinels = [];
-  for (const lr of loaderRanges) {
-    const start = addrNum(lr.start);
-    const end = addrNum(lr.end);
-    sentinels.push({
-      name: `loader:${hex4(start)}-${hex4(end)}`,
-      kind: "loader-reentry",
-      tier: "stopping",
-      type: "exec",
-      start,
-      end,
-      reason: lr.note ?? "loader-reentry range: must never fire again after the dump point",
-      evidence: lr.evidence ?? "",
-    });
-  }
-  for (const nr of neverPopulated) {
-    const start = addrNum(nr.start);
-    const end = addrNum(nr.end);
-    sentinels.push({
-      name: `unused:${hex4(start)}-${hex4(end)}`,
-      kind: "never-populated",
-      tier: "counting",
-      type: "write",
-      start,
-      end,
-      reason: nr.note ?? "never-populated range in the run1 capture -- any write during gameplay is a candidate",
-      evidence: nr.note ?? "",
-    });
-  }
-  sentinels.push({
-    name: "reg:$DD00",
-    kind: "register",
-    tier: "counting",
-    type: "write",
-    start: 0xdd00,
-    end: 0xdd00,
-    reason:
-      "CIA2 port A -- VIC-II bank-select bits (0-1) plus the bit-banged serial-bus lines (ATN/CLOCK/DATA, bits 3-5) " +
-      "a KERNAL-bypassing raw-sector loader toggles directly; the primary on-demand-load sentinel because such a " +
-      "loader leaves no KERNAL vector activity to watch instead",
-    evidence:
-      "c64-memory-mapping skill memmap: $DD00 bits 0-1 select the VIC bank (00=bank3 $C000-$FFFF ... 11=bank0 " +
-      "$0000-$3FFF); bits 3-5 are the serial bus ATN OUT/CLOCK OUT/DATA OUT lines",
-  });
-  return sentinels;
-}
-
-// ----------------------------------------------------------- attributeAddress
-
-/**
- * Resolve `addr` to exactly one sentinel's name. Validates the *whole*
- * sentinel set for overlap/duplication on every call -- a configuration
- * error is a property of the set, not of the one address being queried, so
- * it must be caught regardless of which address happens to be asked about.
- * Abutting ranges (one range's `end` immediately followed by the next
- * range's `start`) are never flagged: they are adjacent, not overlapping.
- */
-export function attributeAddress(addr, sentinels) {
-  const a = addrNum(addr);
-  for (let i = 0; i < sentinels.length; i++) {
-    for (let j = i + 1; j < sentinels.length; j++) {
-      const s1 = sentinels[i];
-      const s2 = sentinels[j];
-      const s1s = addrNum(s1.start);
-      const s1e = addrNum(s1.end);
-      const s2s = addrNum(s2.start);
-      const s2e = addrNum(s2.end);
-      if (s1s <= s2e && s2s <= s1e) {
-        throw new Error(
-          `attributeAddress: overlapping or duplicate sentinel ranges "${s1.name}" (${hex4(s1s)}-${hex4(s1e)}) and ` +
-            `"${s2.name}" (${hex4(s2s)}-${hex4(s2e)}) -- refusing to resolve a winner by precedence`
-        );
-      }
-    }
-  }
-  const matches = sentinels.filter((s) => a >= addrNum(s.start) && a <= addrNum(s.end));
-  if (matches.length === 0) {
-    return { matched: false, name: null, address: a };
-  }
-  return { matched: true, name: matches[0].name, address: a };
-}
-
-// ----------------------------------------------------------------- reportHits
-
-/**
- * Total order over a hit log: cycle ascending, then address ascending, then
- * sentinel name ascending -- so two hits sharing both cycle and address
- * still have one defined position, and re-reporting an unchanged log is
- * byte-identical. Accepts either a bare array of hit records or the whole
- * boundary-artifact object (reading its `.hits` field); an absent/empty
- * `hits` array reports as an empty result rather than throwing.
- */
-export function reportHits(hitLog) {
-  const hits = Array.isArray(hitLog) ? hitLog : hitLog?.hits ?? [];
-  return [...hits].sort((a, b) => {
-    const ca = a.cycle ?? 0;
-    const cb = b.cycle ?? 0;
-    if (ca !== cb) return ca - cb;
-    const aa = addrNum(a.address);
-    const ab = addrNum(b.address);
-    if (aa !== ab) return aa - ab;
-    return String(a.sentinel ?? "").localeCompare(String(b.sentinel ?? ""));
-  });
-}
-
-// ------------------------------------------------------------------ idleGate
-
-/**
- * The mechanical half of the idle check. Passes only when every
- * `stopping`-tier sentinel recorded exactly zero hits AND the recorded
- * `cycles_advanced` is greater than zero -- a machine that did not execute
- * proves nothing, whatever the hit counts say. Otherwise names the
- * violating sentinels with their counts.
- */
-export function idleGate(calibration) {
-  const cyclesAdvanced = calibration?.cycles_advanced;
-  const sentinels = calibration?.sentinels ?? [];
-  const violations = sentinels
-    .filter((s) => s.tier === "stopping" && s.hits !== 0)
-    .map((s) => ({ name: s.name, hits: s.hits }));
-  const cyclesOk = typeof cyclesAdvanced === "number" && cyclesAdvanced > 0;
-  const reasons = [];
-  if (!cyclesOk) {
-    reasons.push(`cycles_advanced (${cyclesAdvanced}) is not greater than zero -- a machine that did not execute proves nothing`);
-  }
-  if (violations.length > 0) {
-    reasons.push(
-      `stopping-tier sentinel(s) recorded non-zero idle hits: ${violations.map((v) => `${v.name}=${v.hits}`).join(", ")}`
-    );
-  }
-  return { ok: cyclesOk && violations.length === 0, cycles_advanced: cyclesAdvanced, violations, reasons };
-}
-
-// ---------------------------------------------------------------- classifyHit
-
-/**
- * Returns `unattributed` unless the hit record carries a non-empty program
- * counter, backtrace and disassembly -- only then does it return the
- * recorded classification (`gameplay-write` or `load-candidate`). An
- * unattributed hit is reported as exactly that, never as a bare count.
- */
-export function classifyHit(hit) {
-  const hasPc = hit?.pc !== undefined && hit?.pc !== null && hit?.pc !== "";
-  const hasBacktrace = Array.isArray(hit?.backtrace) ? hit.backtrace.length > 0 : !!hit?.backtrace;
-  const hasDisassembly = !!hit?.disassembly;
-  if (!hasPc || !hasBacktrace || !hasDisassembly) return "unattributed";
-  if (hit.classification === "gameplay-write" || hit.classification === "load-candidate") {
-    return hit.classification;
-  }
-  return "unattributed";
-}
-
-// ------------------------------------------------------------ screenSignature
-
-/**
- * Hash the 1000 bytes of screen matrix the agent read (hex string in,
- * digest out) together with the sprite-enable register value. Screenshots
- * 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
- * to decode-then-hash instead.
- */
-export function screenSignature(screenMatrixHex, spriteEnable) {
-  const buf = Buffer.from(screenMatrixHex, "hex");
-  if (buf.length !== 1000) {
-    throw new Error(`screenSignature: expected 1000 bytes of screen matrix hex, got ${buf.length} bytes`);
-  }
-  const digest = createHash("sha256").update(buf).digest("hex");
-  return { digest, sprite_enable: spriteEnable ?? null };
-}
-
-// --------------------------------------------------------------- recordWatchSet
-
-/** Persist a resolved sentinel set into the registry under `watch_set`. */
-export function recordWatchSet(releaseId, watchSet) {
-  return upsertRelease(releaseId, (r) => ({ ...r, watch_set: watchSet }));
-}
-
-// ----------------------------------------------------------------- renderLoading
-
-function escapeCell(text) {
-  return String(text ?? "").replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
-}
-
-function fmtRange(s) {
-  return `${hex4(addrNum(s.start))}-${hex4(addrNum(s.end))}`;
-}
-
-function renderReleaseSection(id, log) {
-  const hits = reportHits(log);
-  const count = hits.length;
-  let s = `## Release: ${id}\n\n`;
-
-  s += `**Load-event count:**\n\n${count}\n\n`;
-
-  if (log.run_status === "blocked") {
-    if (count === 0) {
-      s += `> **⚠ THIS IS NOT AN EVIDENCED ZERO.** The count above is \`0\` only because no live ` +
-        `emulator work reached completion for this release this run -- it is a bare absence of ` +
-        `attempted measurement, not a null result earned by an idle calibration on a machine proven ` +
-        `to have executed. ${log.run_status_note ?? ""}\n\n`;
-    } else {
-      s += `> **⚠ THIS IS A PARTIAL RESULT, NOT A COMPLETED COVERAGE CLAIM.** The count above (\`${count}\`) ` +
-        `reflects genuinely attributed hits from the portion of the play-through that did complete before this ` +
-        `run was blocked -- it is not evidence that no further load events exist beyond what was reached. ` +
-        `${log.run_status_note ?? ""}\n\n`;
-    }
-  }
-
-  s += `**Route:** the executing agent's own \`mcp__plugin_c64-re-tools_vice__*\` tool calls -- machine ${log.machine ?? "unknown"}, ` +
-    `video standard ${log.video_standard ?? "unknown"}, VICE server version ${log.vice_version ?? "unknown"}.\n\n`;
-
-  s += `### Armed set\n\n`;
-  s += "| Sentinel | Kind | Tier | Type | Range | Reason | Evidence | Idle hits |\n";
-  s += "|---|---|---|---|---|---|---|---|\n";
-  for (const a of log.armed ?? []) {
-    s += `| ${a.name} | ${a.kind} | ${a.tier} | ${a.type} | ${fmtRange(a)} | ${escapeCell(a.reason)} | ${escapeCell(a.evidence)} | ${a.idle_hits ?? ""} |\n`;
-  }
-  s += "\n";
-
-  s += `### Idle calibration\n\n`;
-  const cal = log.idle_calibration ?? {};
-  s += `Cycles advanced during the no-input idle window: **${cal.cycles_advanced ?? "unrecorded"}**.\n\n`;
-  s += "| Sentinel | Tier | Range | Idle hits |\n|---|---|---|---|\n";
-  for (const sn of cal.sentinels ?? []) {
-    s += `| ${sn.name} | ${sn.tier} | ${sn.start !== undefined ? fmtRange(sn) : ""} | ${sn.hits} |\n`;
-  }
-  s += "\n";
-
-  s += `### Counting-tier probe\n\n`;
-  const probe = log.counting_tier_probe ?? {};
-  s += `Observed hit count: ${probe.hit_count ?? "unrecorded"}. Execution stopped during the probe: ${probe.execution_stopped ?? "unrecorded"}.\n\n`;
-  if (probe.fallback_taken) {
-    s += `**Fallback taken:** the counting tier could not count without stopping. ${probe.fallback_note ?? ""}\n\n`;
-  }
-
-  s += `### Coverage reached\n\n`;
-  s += "| Milestone | Reached | Screen signature | Cycles advanced | Retries | Screenshot |\n|---|---|---|---|---|---|\n";
-  for (const m of log.milestones ?? []) {
-    s += `| ${m.name} | ${m.reached ? "yes" : "no"} | ${m.screen_signature ?? ""} | ${m.cycles_advanced ?? ""} | ${m.retries ?? 0} | ${m.screenshot ?? ""} |\n`;
-  }
-  s += "\n";
-
-  s += `### States not reached\n\n`;
-  const notReachedMilestones = (log.milestones ?? []).filter((m) => !m.reached);
-  const scopeBoundary = log.scope_not_attempted ?? [];
-  if (notReachedMilestones.length === 0 && scopeBoundary.length === 0) {
-    s += "(nothing recorded as not reached -- if this looks wrong, the record is incomplete, not the coverage)\n\n";
-  } else {
-    for (const m of notReachedMilestones) {
-      s += `- **${m.name}**: not reached. ${m.not_reached_reason ?? ""}\n`;
-    }
-    for (const item of scopeBoundary) {
-      s += `- ${item}\n`;
-    }
-    s += "\n";
-  }
-
-  s += `### Attributed hits\n\n`;
-  if (hits.length === 0) {
-    s += "(no hits recorded above the idle floor)\n\n";
-  } else {
-    s += "| Cycle | Address | Sentinel | Tier | Classification | Evidence |\n|---|---|---|---|---|---|\n";
-    for (const h of hits) {
-      const cls = h.classification ?? classifyHit(h);
-      s += `| ${h.cycle} | ${h.address} | ${h.sentinel} | ${h.tier ?? ""} | ${cls} | ${escapeCell(h.disassembly ?? "")} |\n`;
-    }
-    s += "\n";
-  }
-
-  const loadCandidates = hits.filter((h) => (h.classification ?? classifyHit(h)) === "load-candidate");
-  s += `### Supplementary dumps\n\n`;
-  if (loadCandidates.length === 0) {
-    s += "None -- no hit was classified `load-candidate` for this release.\n\n";
-  } else {
-    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 ` +
-        `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 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 += "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`;
-  const teardown = log.teardown ?? {};
-  s += `Checkpoints remaining after teardown, from an explicit \`mcp__plugin_c64-re-tools_vice__vice_checkpoint_list\` enumeration: ` +
-    `**${teardown.checkpoints_remaining ?? "unrecorded"}** (enumerated at ${teardown.enumerated_at ?? "unrecorded"}).\n\n`;
-
-  if ((log.identity_changes ?? []).length > 0) {
-    s += `### Identity changes\n\n`;
-    for (const c of log.identity_changes) {
-      s += `- ${JSON.stringify(c)}\n`;
-    }
-    s += "\n";
-  }
-
-  return s;
-}
-
-/**
- * Render `recovery/LOADING.md` from a list of `{ id, log }` entries, each
- * `log` being one release's validated boundary hit-log artifact. Pure
- * 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";
-  out +=
-    "This document is the absence-as-evidence record: per release, the armed set with its justification, the " +
-    "idle calibration result, the coverage reached with a mechanical arrival proof per milestone, the states not " +
-    "reached, the attributed hits, and the teardown enumeration. Every measurement below was fetched by the " +
-    "executing agent's own `mcp__plugin_c64-re-tools_vice__*` tool calls; `.claude/skills/c64-ram-capture/scripts/watch-loads.mjs` and `.claude/skills/c64-ram-capture/scripts/dump-artifacts.mjs` hold " +
-    "only the pure logic that resolves, attributes, orders and renders it -- neither module contacted the " +
-    "emulator.\n\n";
-  for (const { id, log } of entries) {
-    out += renderReleaseSection(id, log);
-  }
-  return out;
-}
-
-// -------------------------------------------------------------------- CLI
-
-function optValue(rest, name) {
-  const i = rest.indexOf(`--${name}`);
-  return i === -1 ? undefined : rest[i + 1];
-}
-
-const VERBS = {
-  resolve(rest) {
-    const releaseId = optValue(rest, "release");
-    if (!releaseId) die("usage: resolve --release <id> [--json]");
-    const watchSet = WATCH_SET(releaseId);
-    recordWatchSet(releaseId, watchSet);
-    const result = { release: releaseId, count: watchSet.length, watch_set: watchSet };
-    if (rest.includes("--json")) {
-      console.log(JSON.stringify(result, null, 2));
-    } else {
-      console.log(`${releaseId}: resolved ${watchSet.length} sentinel(s)`);
-      for (const s of watchSet) console.log(`  ${s.name} tier=${s.tier} type=${s.type} ${fmtRange(s)}`);
-    }
-  },
-
-  attribute(rest) {
-    const releaseId = optValue(rest, "release");
-    const addrArg = optValue(rest, "addr");
-    if (!releaseId || !addrArg) die("usage: attribute --release <id> --addr <address> [--json]");
-    const relEntry = getReleaseEntry(releaseId);
-    const sentinels = relEntry.watch_set && relEntry.watch_set.length ? relEntry.watch_set : WATCH_SET(releaseId);
-    const result = attributeAddress(addrArg, sentinels);
-    if (rest.includes("--json")) {
-      console.log(JSON.stringify(result, null, 2));
-    } else {
-      console.log(result.matched ? `${addrArg} -> ${result.name}` : `${addrArg} -> unmatched`);
-    }
-  },
-
-  report(rest) {
-    const releaseId = optValue(rest, "release");
-    if (!releaseId) die("usage: report --release <id> [--json]");
-    const log = readHitLog(releaseId);
-    const hits = reportHits(log);
-    const result = { release: releaseId, count: hits.length, hits };
-    if (rest.includes("--json")) {
-      console.log(JSON.stringify(result, null, 2));
-    } else {
-      console.log(`${releaseId}: ${hits.length} hit(s)`);
-      for (const h of hits) {
-        console.log(`  cycle=${h.cycle} addr=${h.address} sentinel=${h.sentinel} classification=${h.classification ?? classifyHit(h)}`);
-      }
-    }
-  },
-
-  "check-idle"(rest) {
-    const releaseId = optValue(rest, "release");
-    if (!releaseId) die("usage: check-idle --release <id> [--json]");
-    const log = readHitLog(releaseId);
-    if (!log.idle_calibration) die(`check-idle: release "${releaseId}" hit log has no idle_calibration recorded`);
-    const gate = idleGate(log.idle_calibration);
-    const result = { release: releaseId, ...gate, sentinels: log.idle_calibration.sentinels ?? [] };
-    if (rest.includes("--json")) {
-      console.log(JSON.stringify(result, null, 2));
-    } else {
-      console.log(`${releaseId}: cycles_advanced=${gate.cycles_advanced} ok=${gate.ok}`);
-      for (const s of result.sentinels) console.log(`  ${s.name}: tier=${s.tier} ${s.start !== undefined ? fmtRange(s) : ""} hits=${s.hits}`);
-      if (!gate.ok) for (const r of gate.reasons) console.error(`  - ${r}`);
-    }
-    process.exitCode = gate.ok ? 0 : 1;
-  },
-
-  signature(rest) {
-    const hex = optValue(rest, "hex");
-    const spriteEnable = optValue(rest, "sprite-enable");
-    if (!hex) die("usage: signature --hex <1000-byte-hex> [--sprite-enable <n>] [--json]");
-    const result = screenSignature(hex, spriteEnable !== undefined ? Number(spriteEnable) : null);
-    if (rest.includes("--json")) {
-      console.log(JSON.stringify(result, null, 2));
-    } else {
-      console.log(`${result.digest} sprite_enable=${result.sprite_enable}`);
-    }
-  },
-
-  render(rest) {
-    const reg = loadRegistry();
-    const only = optValue(rest, "release");
-    const releaseIds = only ? [only] : reg.releases.map((r) => r.id);
-    const entries = [];
-    for (const id of releaseIds) {
-      const p = hitLogPath(id);
-      if (!existsSync(p)) continue;
-      entries.push({ id, log: JSON.parse(readFileSync(p, "utf8")) });
-    }
-    const markdown = renderLoading(entries);
-    const outPath = join(RECOVERY_DIR, "LOADING.md");
-    writeFileSync(outPath, markdown);
-    const result = { path: rel(outPath), releases: entries.map((e) => e.id) };
-    if (rest.includes("--json")) {
-      console.log(JSON.stringify(result, null, 2));
-    } else {
-      console.log(`wrote ${rel(outPath)} for releases: ${result.releases.join(", ")}`);
-    }
-  },
-};
-
-if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
-  const [cmd, ...rest] = process.argv.slice(2);
-  if (!cmd || !VERBS[cmd]) {
-    console.log(`usage: node ${fileURLToPath(import.meta.url)} <resolve|attribute|report|check-idle|signature|render> [--release <id>] [--json]`);
-    process.exitCode = cmd ? 1 : 0;
-  } else {
-    VERBS[cmd](rest);
-  }
-}

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

@@ -1,99 +0,0 @@
-# Capture record — `<release>-<checkpoint>-run<N>`
-
-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 five rows use the shorthand, and
-`scripts/` resolves from neither cwd by accident.
-
-## Identity
-
-| Field | Value | How obtained |
-|---|---|---|
-| 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 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 | — |
-| 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.
-
-| Field | Value | Source |
-|---|---|---|
-| `$01` (processor port) | `$__` `%________` | `vice_memory_read` — decides which vectors are live |
-| video standard | PAL \| NTSC | `vice_vicii_get_state` |
-| registers (PC, A, X, Y, SP, flags) | | `vice_registers_get` |
-| epoch-drift errors during the capture | `none` | the proxy raises these itself, before and after every forwarded call — no tool reads the epoch on demand |
-| checkpoints armed at exit | `0` | `vice_checkpoint_list` — accept only this enumeration as proof |
-
-## Verdict
-
-- [ ] Size is exactly 65536 bytes.
-- [ ] 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 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.
-
-## Comparison against sibling runs
-
-`node scripts/compare.mjs compare <a>.bin <b>.bin` for each pairing, and
-`node scripts/compare.mjs floor <a>.bin <b>.bin <c>.bin` across the set.
-
-| Pairing | volatile | drift (1 bit) | divergence (2+ bits) | verdict |
-|---|---|---|---|---|
-| run1 vs run2 | | | | |
-| run1 vs run3 | | | | |
-| run2 vs run3 | | | | |
-
-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.
-
-### `$D000-$DFFF`: the rule depends on the `capture route` row
-
-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, `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
-reading which route produced the image.