@henols/c64-re-tools 0.1.4

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

@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+// Compare 65536-byte C64 RAM captures and classify every difference.
+//
+// Pure logic. This module reads files the agent already captured 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 classification rules are the ones c64-ram-capture/SKILL.md states, and
+// they live here so they are applied identically every time instead of being
+// re-derived by hand per session:
+//
+//   volatile   $0000-$0001, $0100-$01FF, $0200-$03FF, $D000-$DFFF -- counted,
+//              reported, excluded from the verdict
+//   drift      exactly one bit differs -- listed as a candidate, does not fail
+//   divergence two or more bits differ -- listed, and fails the comparison
+//
+// $D000-$DFFF is this module's one departure from what SKILL.md said when it was
+// written: that range is I/O, not RAM, so it can never be stable. See the VOLATILE
+// table below and .planning/RE-FINDINGS.md (2026-08-04) for the evidence.
+
+import { readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { basename } from "node:path";
+
+const IMAGE_BYTES = 65536;
+
+// Volatile spans, inclusive. A difference inside these is expected on any two
+// captures of the same checkpoint and never fails a comparison.
+const VOLATILE = [
+  [0x0000, 0x0001], // CPU port
+  [0x0100, 0x01ff], // stack page
+  [0x0200, 0x03ff], // KERNAL work area / BASIC input buffer
+  // $D000-$DFFF is I/O, not RAM: the VIC's registers repeat every $40 across
+  // $D000-$D3FF and the SID's across $D400-$D7FF, so reading this range samples
+  // live hardware and two captures can never agree here. Added 2026-08-04 after
+  // every divergence across all six committed gameentry pairings landed either
+  // here ($D344, $D625, $D628) or in RAM under KERNAL ROM -- see
+  // .planning/RE-FINDINGS.md, 2026-08-04. Confidence HIGH: structural.
+  [0xd000, 0xdfff],
+];
+
+// Deliberately NOT volatile: $E000-$FFFF (RAM under KERNAL ROM when HIRAM=0).
+// $FAD8 and $FC51 do differ across captures, but only 2 addresses out of 8192 --
+// far too few for power-on garbage, and unexplained. Blanket-excluding 8 KB on
+// two data points would hide real divergence, so these still fail and the
+// capture record carries the explanation. Confidence MEDIUM, see the same entry.
+
+const isVolatile = (a) => VOLATILE.some(([lo, hi]) => a >= lo && a <= hi);
+
+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");
+
+const popcount = (n) => {
+  let c = 0;
+  while (n) {
+    n &= n - 1;
+    c++;
+  }
+  return c;
+};
+
+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");
+
+/**
+ * Classify every differing address between two images.
+ * Returns { volatile[], drift[], divergence[], pass } — the three lists
+ * SKILL.md requires, plus the verdict.
+ */
+function compare(a, b) {
+  const volatile_ = [];
+  const drift = [];
+  const divergence = [];
+
+  for (let addr = 0; addr < IMAGE_BYTES; addr++) {
+    const x = a[addr];
+    const y = b[addr];
+    if (x === y) continue;
+
+    const bits = popcount(x ^ y);
+    const rec = { addr, a: x, b: y, bits };
+
+    // Volatile wins over bit-count: an address in a volatile span is excluded
+    // from the verdict regardless of how many bits moved.
+    if (isVolatile(addr)) volatile_.push(rec);
+    else if (bits === 1) drift.push(rec);
+    else divergence.push(rec);
+  }
+
+  return { volatile: volatile_, drift, divergence, pass: divergence.length === 0 };
+}
+
+const fmtRow = (r) =>
+  `  ${hex4(r.addr)}  ${hex2(r.a)} ${bin8(r.a)}  ->  ${hex2(r.b)} ${bin8(r.b)}   ${r.bits} bit${r.bits === 1 ? "" : "s"}`;
+
+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) console.log(fmtRow(r));
+  if (shown.length < rows.length) {
+    console.log(`  … ${rows.length - shown.length} more (--limit 0 for all)`);
+  }
+}
+
+function cmdCompare(argv) {
+  const limit = limitFrom(argv);
+  const paths = argv.filter((s) => !s.startsWith("--") && !/^\d+$/.test(s));
+  if (paths.length !== 2) throw new Error("compare needs exactly two image paths");
+
+  const [pa, pb] = paths;
+  const a = loadImage(pa);
+  const b = loadImage(pb);
+
+  const ha = sha256(a);
+  const hb = sha256(b);
+
+  console.log(`A  ${basename(pa)}  sha256 ${ha}`);
+  console.log(`B  ${basename(pb)}  sha256 ${hb}`);
+
+  if (ha === hb) {
+    console.log("\nIDENTICAL — the two images are byte-for-byte equal.");
+    console.log("\nVERDICT: PASS");
+    return 0;
+  }
+
+  const r = compare(a, b);
+
+  printList("volatile (excluded from the verdict)", r.volatile, limit);
+  printList("drift — exactly one bit, reported as candidates", r.drift, limit);
+  printList("DIVERGENCE — two or more bits, fails the comparison", r.divergence, limit);
+
+  const total = r.volatile.length + r.drift.length + r.divergence.length;
+  console.log(`\ntotal differing addresses: ${total} of ${IMAGE_BYTES}`);
+  console.log(`\nVERDICT: ${r.pass ? "PASS" : "FAIL"}`);
+  if (r.pass && r.drift.length) {
+    console.log("Drift candidates present — pass, but record them with the capture.");
+  }
+  return r.pass ? 0 : 1;
+}
+
+/**
+ * Drift floor across N captures of the same checkpoint: every address that
+ * differed in ANY pairing. Reported as a floor, never as a complete set —
+ * more captures can only widen it.
+ */
+function cmdFloor(argv) {
+  const limit = limitFrom(argv);
+  const paths = argv.filter((s) => !s.startsWith("--") && !/^\d+$/.test(s));
+  if (paths.length < 2) throw new Error("floor needs at least two image paths");
+
+  const imgs = paths.map((p) => ({ path: p, buf: loadImage(p) }));
+  for (const i of imgs) console.log(`${basename(i.path)}  sha256 ${sha256(i.buf)}`);
+
+  const floor = new Map(); // addr -> Set of distinct values seen
+  let worstPair = null;
+
+  for (let i = 0; i < imgs.length; i++) {
+    for (let j = i + 1; j < imgs.length; j++) {
+      const r = compare(imgs[i].buf, imgs[j].buf);
+      for (const rec of [...r.volatile, ...r.drift, ...r.divergence]) {
+        if (!floor.has(rec.addr)) floor.set(rec.addr, new Set());
+        floor.get(rec.addr).add(rec.a);
+        floor.get(rec.addr).add(rec.b);
+      }
+      const label = `${basename(imgs[i].path)} vs ${basename(imgs[j].path)}`;
+      console.log(
+        `\n${label}: ${r.volatile.length} volatile, ${r.drift.length} drift, ${r.divergence.length} divergence -> ${r.pass ? "PASS" : "FAIL"}`,
+      );
+      if (!r.pass && (!worstPair || r.divergence.length > worstPair.n)) {
+        worstPair = { label, n: r.divergence.length };
+      }
+    }
+  }
+
+  const addrs = [...floor.keys()].sort((x, y) => x - y);
+  const vol = addrs.filter(isVolatile).length;
+
+  console.log(`\nDRIFT FLOOR: ${addrs.length} addresses (${vol} inside volatile spans)`);
+  const shown = limit === 0 ? addrs : addrs.slice(0, limit || 40);
+  for (const a of shown) {
+    const vals = [...floor.get(a)].sort((p, q) => p - q).map(hex2).join(" / ");
+    console.log(`  ${hex4(a)}${isVolatile(a) ? "  [volatile]" : "            "}  ${vals}`);
+  }
+  if (shown.length < addrs.length) {
+    console.log(`  … ${addrs.length - shown.length} more (--limit 0 for all)`);
+  }
+
+  console.log(
+    "\nThis is a FLOOR, not a complete set — more captures of the same checkpoint can only widen it.",
+  );
+  if (worstPair) {
+    const n = worstPair.n;
+    console.log(`Worst pairing: ${worstPair.label} (${n} divergence${n === 1 ? "" : "s"}).`);
+  }
+  return 0;
+}
+
+/** SHA-256 and size of each image, for recording alongside a capture. */
+function cmdDigest(argv) {
+  const paths = argv.filter((s) => !s.startsWith("--"));
+  if (!paths.length) throw new Error("digest needs at least one image path");
+  for (const p of paths) {
+    const buf = readFileSync(p);
+    const ok = buf.length === IMAGE_BYTES;
+    console.log(
+      `${sha256(buf)}  ${buf.length} bytes${ok ? "" : "  *** NOT 65536 — not a full image ***"}  ${basename(p)}`,
+    );
+  }
+  return 0;
+}
+
+function limitFrom(argv) {
+  const i = argv.indexOf("--limit");
+  if (i < 0) return undefined;
+  const n = Number(argv[i + 1]);
+  if (!Number.isInteger(n) || n < 0) throw new Error("--limit needs a non-negative integer");
+  return n;
+}
+
+const commands = { compare: cmdCompare, floor: cmdFloor, digest: cmdDigest };
+
+const [cmd, ...rest] = process.argv.slice(2);
+if (!cmd || !commands[cmd]) {
+  console.error(`usage: node compare.mjs <command>
+
+  compare <a.bin> <b.bin> [--limit N]   classify every difference, print a verdict
+  floor <a.bin> <b.bin> [...] [--limit N]   drift floor across N captures of one checkpoint
+  digest <image.bin>...                 sha256 + size, for the capture record
+
+Volatile (counted, excluded from the verdict): $0000-$0001, $0100-$01FF, $0200-$03FF, $D000-$DFFF.
+$D000-$DFFF is I/O, not RAM — reading it samples live hardware, so it can never be stable.
+One differing bit is drift and passes; two or more is divergence and fails.
+--limit 0 prints every row. Exit status is 1 on a FAIL verdict.
+
+Images come from the capture procedure in this skill's SKILL.md, via mcp__plugin_c64-re-tools_vice__*.
+This script contacts nothing.`);
+  process.exit(cmd ? 1 : 0);
+}
+
+try {
+  process.exit(commands[cmd](rest));
+} catch (e) {
+  console.error(`error: ${e.message}`);
+  process.exit(1);
+}

package/skills/c64-ram-capture/scripts/d64-parse.mjs

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+// Direct byte-level .d64 parser -- the permanent, sanctioned replacement for
+// the forbidden vice_disk_list tool (T-01-03). Never calls any vice_* tool
+// or touches the emulator at all: this is pure Node over the disk-image
+// bytes, which is why it works whether or not VICE happens to be up.
+//
+// Standard 35-track 1541 layout: BAM at track 18 sector 0, directory chain
+// from track 18 sector 1, four sector-count zones (21/19/18/17 sectors per
+// track). Plain 174848-byte, 35-track, no-error-info images are assumed
+// are plain 174848-byte, 35-track, no-error-info images -- no extended
+// (40-track) or error-byte variants to handle.
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { resolve } from "node:path";
+
+const die = (m) => { console.error(`error: ${m}`); process.exit(1); };
+
+export function readImage(path) {
+  return readFileSync(path);
+}
+
+/** The four sector-count zones of a standard 35-track 1541 image. */
+export function sectorsPerTrack(track) {
+  if (!Number.isInteger(track) || track < 1 || track > 35) {
+    throw new Error(`sectorsPerTrack: track ${track} out of range 1-35`);
+  }
+  if (track <= 17) return 21;
+  if (track <= 24) return 19;
+  if (track <= 30) return 18;
+  return 17;
+}
+
+/** Byte offset of the start of {track, sector} in a flat 35-track image. */
+export function tsToOffset(track, sector) {
+  if (!Number.isInteger(track) || track < 1 || track > 35) {
+    throw new Error(`tsToOffset: track ${track} out of range 1-35`);
+  }
+  const spt = sectorsPerTrack(track);
+  if (!Number.isInteger(sector) || sector < 0 || sector >= spt) {
+    throw new Error(`tsToOffset: sector ${sector} out of range for track ${track} (0-${spt - 1}, this track has ${spt} sectors)`);
+  }
+  let offset = 0;
+  for (let t = 1; t < track; t++) offset += sectorsPerTrack(t) * 256;
+  return offset + sector * 256;
+}
+
+function isInImage(track, sector) {
+  if (!Number.isInteger(track) || track < 1 || track > 35) return false;
+  if (!Number.isInteger(sector) || sector < 0) return false;
+  return sector < sectorsPerTrack(track);
+}
+
+/**
+ * Directory/disk-name bytes are PETSCII, padded with $A0. Every byte this
+ * project's two disks actually use in a name (A-Z, digits, space, parens)
+ * sits at the same code point in PETSCII as in ASCII/Latin-1, so only the
+ * $A0 padding needs stripping -- there is no general PETSCII<->ASCII table
+ * here, on purpose, since one is not needed for what these disks contain.
+ */
+function petsciiName(bytes) {
+  let end = bytes.length;
+  while (end > 0 && bytes[end - 1] === 0xa0) end--;
+  return Buffer.from(bytes.subarray(0, end)).toString("latin1");
+}
+
+const FILE_TYPES = { 0: "DEL", 1: "SEQ", 2: "PRG", 3: "USR", 4: "REL" };
+
+/** Read track 18 sector 0: disk name/id, DOS type, and per-track free counts. */
+export function parseBam(buffer) {
+  const off = tsToOffset(18, 0);
+  const bam = buffer.subarray(off, off + 256);
+
+  const perTrack = [];
+  for (let t = 1; t <= 35; t++) {
+    const eoff = 4 + (t - 1) * 4;
+    perTrack.push({
+      track: t,
+      free: bam[eoff],
+      sectors_per_track: sectorsPerTrack(t),
+      bitmap: [bam[eoff + 1], bam[eoff + 2], bam[eoff + 3]],
+    });
+  }
+
+  const occupiedTracks = perTrack.filter((t) => t.free < t.sectors_per_track).map((t) => t.track);
+  const occupiedRanges = [];
+  for (const t of occupiedTracks) {
+    const last = occupiedRanges[occupiedRanges.length - 1];
+    if (last && last.end === t - 1) last.end = t;
+    else occupiedRanges.push({ start: t, end: t });
+  }
+
+  return {
+    first_dir_track: bam[0],
+    first_dir_sector: bam[1],
+    dos_version: bam[2],
+    disk_name: petsciiName(bam.subarray(0x90, 0x90 + 16)),
+    disk_id: Buffer.from(bam.subarray(0xa2, 0xa2 + 2)).toString("latin1"),
+    dos_type: Buffer.from(bam.subarray(0xa5, 0xa5 + 2)).toString("latin1"),
+    per_track: perTrack,
+    occupied_tracks: occupiedTracks,
+    occupied_ranges: occupiedRanges,
+  };
+}
+
+function isTrackFullyFree(bam, track) {
+  const entry = bam.per_track.find((t) => t.track === track);
+  return !!entry && entry.free === entry.sectors_per_track;
+}
+
+/**
+ * Walk the directory chain from track 18 sector 1 (by default). Guards
+ * against a malicious or corrupt next-sector pointer with a visited set: a
+ * sector, once processed, can never be re-entered, so even a
+ * self-referential or cyclic pointer stops the walk (reported in
+ * `chain_error`) rather than looping forever.
+ *
+ * Each entry is flagged `suspicious` -- with the specific reason(s) named,
+ * never a bare boolean -- when its block count is 0, when its first
+ * track/sector falls outside the image, or when its first track/sector
+ * points into a track the BAM reports as entirely free (0 sectors
+ * allocated): exactly the signature of a faked directory entry that claims
+ * a file that was never actually written to disk.
+ */
+export function parseDirectory(buffer, { startTrack = 18, startSector = 1 } = {}) {
+  const bam = parseBam(buffer);
+  const entries = [];
+  const visited = new Set();
+  let track = startTrack;
+  let sector = startSector;
+  let chainError = null;
+
+  for (;;) {
+    const key = `${track}/${sector}`;
+    if (visited.has(key)) {
+      chainError = `directory chain revisited ${key} -- stopped to avoid an infinite loop (self-referential or cyclic next-sector pointer)`;
+      break;
+    }
+    visited.add(key);
+    if (!isInImage(track, sector)) {
+      chainError = `directory chain pointer ${key} is outside the image -- stopped`;
+      break;
+    }
+
+    const off = tsToOffset(track, sector);
+    const sec = buffer.subarray(off, off + 256);
+    const nextTrack = sec[0];
+    const nextSector = sec[1];
+
+    for (let i = 0; i < 8; i++) {
+      const e = sec.subarray(i * 32, i * 32 + 32);
+      const typeByte = e[2];
+      const firstTrack = e[3];
+      const firstSector = e[4];
+      const nameBytes = e.subarray(5, 21);
+      const blocks = e[30] | (e[31] << 8);
+
+      // An all-zero type byte with a blank/padded name is an unused slot,
+      // not a file -- never listed as an entry.
+      const isEmptySlot =
+        typeByte === 0 && firstTrack === 0 && firstSector === 0 &&
+        [...nameBytes].every((b) => b === 0xa0 || b === 0x00);
+      if (isEmptySlot) continue;
+
+      const reasons = [];
+      if (blocks === 0) reasons.push("block count is 0");
+      if (!isInImage(firstTrack, firstSector)) {
+        reasons.push(`first track/sector ${firstTrack}/${firstSector} is outside the image`);
+      } else if (isTrackFullyFree(bam, firstTrack)) {
+        reasons.push(`first track ${firstTrack} is reported entirely free by the BAM (0 sectors allocated) -- the file cannot really start there`);
+      }
+
+      entries.push({
+        dir_track: track,
+        dir_sector: sector,
+        entry_index: i,
+        type: FILE_TYPES[typeByte & 0x0f] ?? `unknown(0x${(typeByte & 0x0f).toString(16)})`,
+        closed: !!(typeByte & 0x80),
+        locked: !!(typeByte & 0x40),
+        name: petsciiName(nameBytes),
+        first_track: firstTrack,
+        first_sector: firstSector,
+        blocks,
+        suspicious: reasons.length > 0,
+        suspicious_reasons: reasons,
+      });
+    }
+
+    if (nextTrack === 0) break; // end of chain, by DOS convention
+    track = nextTrack;
+    sector = nextSector;
+  }
+
+  return { entries, chain_error: chainError };
+}
+
+// -------------------------------------------------------------------- CLI
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const [cmd, ...rest] = process.argv.slice(2);
+  const opt = (name, fallback) => {
+    const i = rest.indexOf(`--${name}`);
+    return i === -1 ? fallback : rest[i + 1];
+  };
+  const jsonFlag = rest.includes("--json");
+
+  function run() {
+    if (cmd !== "directory" && cmd !== "bam") {
+      console.log(`usage: node ${fileURLToPath(import.meta.url)} <directory|bam> --image <path.d64> [--json]`);
+      process.exitCode = cmd ? 1 : 0;
+      return;
+    }
+    const imagePath = opt("image");
+    if (!imagePath) die(`usage: ${cmd} --image <path.d64> [--json]`);
+    const buffer = readImage(resolve(imagePath));
+
+    if (cmd === "directory") {
+      const result = parseDirectory(buffer);
+      if (jsonFlag) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        for (const e of result.entries) {
+          const flag = e.suspicious ? ` SUSPICIOUS: ${e.suspicious_reasons.join("; ")}` : "";
+          console.log(`${e.type} "${e.name}" first=${e.first_track}/${e.first_sector} blocks=${e.blocks}${flag}`);
+        }
+        if (result.chain_error) console.log(`chain error: ${result.chain_error}`);
+      }
+      return;
+    }
+
+    const bam = parseBam(buffer);
+    if (jsonFlag) {
+      console.log(JSON.stringify(bam, null, 2));
+    } else {
+      console.log(`disk name: "${bam.disk_name}"  id: ${bam.disk_id}  dos type: ${bam.dos_type}`);
+      console.log(`first dir sector: ${bam.first_dir_track}/${bam.first_dir_sector}`);
+      console.log(
+        `occupied track ranges: ${bam.occupied_ranges.map((r) => (r.start === r.end ? `${r.start}` : `${r.start}-${r.end}`)).join(", ")}`
+      );
+    }
+  }
+
+  run();
+}