@henols/c64-re-tools 0.1.4

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

@@ -0,0 +1,243 @@
+// Coverage for the direct .d64 byte parser: the track/sector offset
+// arithmetic, the directory-chain walk (including its loop guard), and the
+// suspicious-entry detector -- against synthetic images built in-test (so the
+// detector is proven to FIRE on a genuine defect, not merely proven silent),
+// plus an optional pass over whatever real .d64 corpus the host project ships.
+// Portable: with no corpus present the real-image checks skip, never fail.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync, readdirSync, existsSync } from "node:fs";
+import { join, basename } from "node:path";
+
+import { sectorsPerTrack, tsToOffset, parseBam, parseDirectory, readImage } from "./d64-parse.mjs";
+import { projectRoot } from "./project-paths.mjs";
+
+
+// ------------------------------------------------------------- tsToOffset
+
+test("tsToOffset(1, 0) is byte 0", () => {
+  assert.equal(tsToOffset(1, 0), 0);
+});
+
+test("tsToOffset(18, 0) is the BAM's offset -- sum of tracks 1-17's 21 sectors each", () => {
+  assert.equal(tsToOffset(18, 0), 17 * 21 * 256);
+});
+
+test("tsToOffset throws for a track below 1", () => {
+  assert.throws(() => tsToOffset(0, 0), /track 0 out of range/);
+});
+
+test("tsToOffset throws for a track above 35", () => {
+  assert.throws(() => tsToOffset(36, 0), /track 36 out of range/);
+});
+
+test("tsToOffset throws for a sector beyond the count for that track's zone", () => {
+  // Track 1 is in the 21-sectors-per-track zone (sectors 0-20).
+  assert.throws(() => tsToOffset(1, 21), /sector 21 out of range/);
+  // Track 30 is in the 18-sectors-per-track zone (sectors 0-17).
+  assert.throws(() => tsToOffset(30, 18), /sector 18 out of range/);
+  // Track 35 is in the 17-sectors-per-track zone (sectors 0-16).
+  assert.throws(() => tsToOffset(35, 17), /sector 17 out of range/);
+});
+
+test("sectorsPerTrack covers all four standard 1541 zones", () => {
+  assert.equal(sectorsPerTrack(1), 21);
+  assert.equal(sectorsPerTrack(17), 21);
+  assert.equal(sectorsPerTrack(18), 19);
+  assert.equal(sectorsPerTrack(24), 19);
+  assert.equal(sectorsPerTrack(25), 18);
+  assert.equal(sectorsPerTrack(30), 18);
+  assert.equal(sectorsPerTrack(31), 17);
+  assert.equal(sectorsPerTrack(35), 17);
+});
+
+// -------------------------------------------------------- synthetic image
+
+/** A blank, well-formed 35-track image: every BAM track marked fully free. */
+function blankImage() {
+  const buf = Buffer.alloc(174848, 0);
+  const bamOff = tsToOffset(18, 0);
+  buf[bamOff] = 18; // first_dir_track
+  buf[bamOff + 1] = 1; // first_dir_sector
+  buf[bamOff + 2] = 0x41; // dos version 'A'
+  for (let t = 1; t <= 35; t++) {
+    const eoff = bamOff + 4 + (t - 1) * 4;
+    buf[eoff] = sectorsPerTrack(t); // fully free
+    buf[eoff + 1] = 0xff;
+    buf[eoff + 2] = 0xff;
+    buf[eoff + 3] = 0xff; // top 3 bits unused for <=21-sector zones, harmless
+  }
+  const nameOff = bamOff + 0x90;
+  const nameBuf = Buffer.alloc(16, 0xa0);
+  Buffer.from("SYNTHETIC", "latin1").copy(nameBuf);
+  nameBuf.copy(buf, nameOff);
+  return buf;
+}
+
+function writeDirEntry(buf, dirTrack, dirSector, index, { typeByte, firstTrack, firstSector, name, blocks }) {
+  const off = tsToOffset(dirTrack, dirSector) + index * 32;
+  buf[off + 2] = typeByte;
+  buf[off + 3] = firstTrack;
+  buf[off + 4] = firstSector;
+  const nameBuf = Buffer.alloc(16, 0xa0);
+  Buffer.from(name, "latin1").copy(nameBuf);
+  nameBuf.copy(buf, off + 5);
+  buf[off + 30] = blocks & 0xff;
+  buf[off + 31] = (blocks >> 8) & 0xff;
+}
+
+function markTrackOccupied(buf, track, usedSectors) {
+  const bamOff = tsToOffset(18, 0);
+  const eoff = bamOff + 4 + (track - 1) * 4;
+  buf[eoff] = sectorsPerTrack(track) - usedSectors;
+}
+
+test("parseDirectory: a genuine defect (0 blocks, first T/S into a BAM-free track) IS flagged suspicious", () => {
+  const buf = blankImage();
+  // Entry 0: a real, valid PRG that actually occupies track 5.
+  markTrackOccupied(buf, 5, 5);
+  writeDirEntry(buf, 18, 1, 0, { typeByte: 0x82, firstTrack: 5, firstSector: 0, name: "REAL FILE", blocks: 5 });
+  // Chain the real file's own 5 sectors so the terminator is well-formed
+  // (not load-bearing for this test, but keeps the fixture honest).
+  for (let s = 0; s < 5; s++) {
+    const off = tsToOffset(5, s);
+    if (s < 4) { buf[off] = 5; buf[off + 1] = s + 1; } else { buf[off] = 0; buf[off + 1] = 0; }
+  }
+  // Entry 1: the faked entry -- claims track 6, which the BAM still reports
+  // entirely free, and a 0 block count.
+  writeDirEntry(buf, 18, 1, 1, { typeByte: 0x82, firstTrack: 6, firstSector: 0, name: "FAKE ENTRY", blocks: 0 });
+
+  const { entries, chain_error } = parseDirectory(buf);
+  assert.equal(chain_error, null);
+  assert.equal(entries.length, 2);
+  const real = entries.find((e) => e.name.startsWith("REAL FILE"));
+  const fake = entries.find((e) => e.name.startsWith("FAKE ENTRY"));
+  assert.equal(real.suspicious, false, "a genuinely-allocated file must not be flagged");
+  assert.equal(fake.suspicious, true, "0 blocks pointing into a BAM-free track must be flagged");
+  assert.ok(fake.suspicious_reasons.some((r) => r.includes("block count is 0")));
+  assert.ok(fake.suspicious_reasons.some((r) => r.includes("entirely free")));
+});
+
+test("parseDirectory: first track/sector outside the image is flagged with its own reason", () => {
+  const buf = blankImage();
+  writeDirEntry(buf, 18, 1, 0, { typeByte: 0x82, firstTrack: 40, firstSector: 0, name: "OUT OF RANGE", blocks: 12 });
+  const { entries } = parseDirectory(buf);
+  assert.equal(entries.length, 1);
+  assert.equal(entries[0].suspicious, true);
+  assert.ok(entries[0].suspicious_reasons[0].includes("outside the image"));
+});
+
+test("parseDirectory: an unused directory slot (blank name, type 0) is not listed as an entry", () => {
+  const buf = blankImage(); // no entries written at all
+  const { entries } = parseDirectory(buf);
+  assert.equal(entries.length, 0);
+});
+
+test("parseDirectory: terminates on a self-referential next-sector pointer without looping", () => {
+  const buf = blankImage();
+  const off = tsToOffset(18, 1);
+  buf[off] = 18; // next track: itself
+  buf[off + 1] = 1; // next sector: itself
+  const { entries, chain_error } = parseDirectory(buf);
+  assert.equal(entries.length, 0);
+  assert.match(chain_error, /revisited 18\/1/);
+});
+
+test("parseDirectory: terminates on a next-sector pointer that cycles back two hops later", () => {
+  const buf = blankImage();
+  const s1 = tsToOffset(18, 1);
+  buf[s1] = 18; buf[s1 + 1] = 2; // 18/1 -> 18/2
+  const s2 = tsToOffset(18, 2);
+  buf[s2] = 18; buf[s2 + 1] = 1; // 18/2 -> 18/1 (cycle)
+  const { chain_error } = parseDirectory(buf);
+  assert.match(chain_error, /revisited 18\/1/);
+});
+
+test("parseBam: reports free-sector counts and derives occupied ranges", () => {
+  const buf = blankImage();
+  markTrackOccupied(buf, 5, 21);
+  markTrackOccupied(buf, 6, 10);
+  const bam = parseBam(buf);
+  assert.equal(bam.disk_name, "SYNTHETIC");
+  assert.deepEqual(bam.occupied_tracks, [5, 6]);
+  assert.deepEqual(bam.occupied_ranges, [{ start: 5, end: 6 }]);
+  const t5 = bam.per_track.find((t) => t.track === 5);
+  assert.equal(t5.free, 0);
+  const t7 = bam.per_track.find((t) => t.track === 7);
+  assert.equal(t7.free, 21, "an untouched track stays fully free");
+});
+
+// ------------------------------------------------------- optional real corpus
+//
+// Everything above runs on synthetic images and passes in any project. What
+// follows exercises the parser against whatever REAL `.d64` images the host
+// project happens to ship, discovered rather than named, and SKIPS when there
+// are none -- so this file never fails just because it was installed somewhere
+// without a disk corpus.
+//
+// These assertions are deliberately properties of the parser, not facts about
+// any particular disk: a specific image's disk name, entry name or block count
+// is that project's evidence and belongs in that project's own records, not
+// hardcoded in a portable test.
+
+const CORPUS = (() => {
+  const dir = process.env.C64RE_DISKS_DIR ?? join(projectRoot(), "disks");
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => f.toLowerCase().endsWith(".d64"))
+    .sort()
+    .map((f) => join(dir, f));
+})();
+
+const noCorpus =
+  CORPUS.length === 0
+    ? "no .d64 images found -- set C64RE_DISKS_DIR to run the real-corpus checks"
+    : false;
+
+test("real corpus: every image is a standard 174848-byte 35-track image", { skip: noCorpus }, () => {
+  for (const path of CORPUS) {
+    const buf = readImage(path);
+    assert.equal(buf.length, 174848, `${basename(path)} is ${buf.length} bytes, not a plain 35-track image`);
+  }
+});
+
+test("real corpus: every image's BAM points at a first directory sector and yields occupied ranges", { skip: noCorpus }, () => {
+  for (const path of CORPUS) {
+    const bam = parseBam(readImage(path));
+    assert.equal(bam.first_dir_track, 18, `${basename(path)}: first dir track should be 18 on a 1541 image`);
+    assert.ok(bam.first_dir_sector >= 0, `${basename(path)}: first dir sector missing`);
+    assert.ok(
+      bam.occupied_ranges.length > 0,
+      `${basename(path)}: no occupied track ranges derived -- a real image should allocate something`,
+    );
+  }
+});
+
+test("real corpus: every directory chain walks to a clean end, with no loop guard tripped", { skip: noCorpus }, () => {
+  for (const path of CORPUS) {
+    const { entries, chain_error } = parseDirectory(readImage(path));
+    assert.equal(chain_error, null, `${basename(path)}: directory chain failed -- ${chain_error}`);
+    assert.ok(entries.length > 0, `${basename(path)}: no directory entries found`);
+  }
+});
+
+test("real corpus: a suspicious entry always names its reasons, and a clean one never does", { skip: noCorpus }, () => {
+  for (const path of CORPUS) {
+    const { entries } = parseDirectory(readImage(path));
+    for (const e of entries) {
+      assert.equal(typeof e.suspicious, "boolean", `${basename(path)}: "${e.name}" has no suspicious flag`);
+      if (e.suspicious) {
+        assert.ok(
+          e.suspicious_reasons.length > 0,
+          `${basename(path)}: "${e.name}" is flagged suspicious with no reason given -- a bare boolean is not a finding`,
+        );
+      } else {
+        assert.deepEqual(
+          e.suspicious_reasons,
+          [],
+          `${basename(path)}: "${e.name}" is not suspicious but carries reasons`,
+        );
+      }
+    }
+  }
+});

package/skills/c64-ram-capture/scripts/dump-artifacts.mjs

@@ -0,0 +1,317 @@
+#!/usr/bin/env node
+// The artifact renderer (01-04 Task 1, Part B). This module exists because
+// of a structural fact worth stating up front: the executing agent can
+// write text, not binary, so the only shape a committable 65536-byte image
+// can take under the one permitted route to the emulator is *the agent
+// serialises what it fetched via mcp__plugin_c64-re-tools_vice__* tool calls, and a pure
+// function renders it*. Every function below takes already-fetched data as
+// an argument -- nothing here contacts the emulator.
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve, relative } from "node:path";
+
+import { releaseDir } from "./releases.mjs";
+import { projectRoot } from "./project-paths.mjs";
+import { addrNum, hex4 } from "./watch-loads.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = projectRoot();
+
+const die = (m) => { console.error(`error: ${m}`); process.exit(1); };
+
+function rel(p) {
+  return relative(REPO_ROOT, p);
+}
+
+// ---------------------------------------------------------------- assembleImage
+
+/**
+ * Assemble the ordered `{ address, hex }` chunk records the agent wrote
+ * after its `mcp__plugin_c64-re-tools_vice__vice_memory_read` calls into a 65536-byte buffer.
+ * Asserts contiguity from $0000 with no gap and no overlap and a total of
+ * exactly 65536 bytes, naming the offending address in every failure.
+ */
+export function assembleImage(chunks) {
+  const sorted = [...chunks].sort((a, b) => addrNum(a.address) - addrNum(b.address));
+  const bufs = [];
+  let expected = 0;
+  for (const c of sorted) {
+    const addr = addrNum(c.address);
+    const buf = Buffer.from(c.hex, "hex");
+    if (addr > expected) {
+      throw new Error(`assembleImage: gap before address ${hex4(expected)} -- next chunk starts at ${hex4(addr)}`);
+    }
+    if (addr < expected) {
+      throw new Error(`assembleImage: overlap at address ${hex4(addr)} -- a previous chunk already covered up to ${hex4(expected - 1)}`);
+    }
+    bufs.push(buf);
+    expected += buf.length;
+  }
+  const total = Buffer.concat(bufs);
+  if (total.length !== 65536) {
+    throw new Error(`assembleImage: assembled ${total.length} bytes ending at ${hex4(expected)}, expected exactly 65536`);
+  }
+  return total;
+}
+
+/** SHA-256 of a buffer, hex-encoded. `node:crypto` only -- no package added (D-18). */
+export function sha256Buffer(buf) {
+  return createHash("sha256").update(buf).digest("hex");
+}
+
+// ----------------------------------------------------------------- vicBank
+
+/**
+ * VIC-II bank number (0-3) from CIA2 port A ($DD00)'s low two bits. The
+ * stored value is the INVERSE of the bank number (c64-memory-mapping skill
+ * memmap: raw value %00 = "Bank #3" $C000-$FFFF ... %11 = "Bank #0"
+ * $0000-$3FFF), so bank = 3 - (raw & 3). Verified against
+ * a committed chip-state sidecar's own recorded
+ * dd00_raw=193 (0xC1, low bits %01) -> vic_bank=2, which this formula
+ * reproduces exactly.
+ */
+export function vicBank(dd00Raw) {
+  return 3 - (dd00Raw & 3);
+}
+
+// --------------------------------------------------------------- screenBase
+
+/**
+ * Screen memory base address, derived from $D018's bits 4-7 (screen pointer,
+ * in 1024-byte units relative to the VIC bank) added to the VIC bank's own
+ * base (bank * 16384). Verified against the same committed sidecar:
+ * dd00_raw=193, d018_raw=49 (0x31) -> screen_base=35840, reproduced exactly.
+ */
+export function screenBase(d018Raw, dd00Raw) {
+  const bank = vicBank(dd00Raw);
+  const bankBase = bank * 16384;
+  const screenOffset = ((d018Raw >> 4) & 0xf) * 1024;
+  return bankBase + screenOffset;
+}
+
+/** Character memory base: $D018 bits 1-3, in 2048-byte units relative to the VIC bank. */
+function charsetBase(d018Raw, dd00Raw) {
+  const bank = vicBank(dd00Raw);
+  const bankBase = bank * 16384;
+  const charsetOffset = ((d018Raw >> 1) & 0x7) * 2048;
+  return bankBase + charsetOffset;
+}
+
+// -------------------------------------------------------------- buildChipState
+
+/**
+ * Build the D-04 chip-state sidecar in the exact shape the committed
+ * primary sidecars already use (same top-level keys, same `derived` field
+ * set), from the register/state readings the agent recorded. `raw` carries
+ * whatever the agent fetched via vice_registers_get / vice_sprite_get /
+ * vice_memory_read, keyed to match: `registers`, `sprites`, `cpu` pass
+ * through verbatim; `dd00_raw`, `d018_raw`, `port01_raw` and
+ * `sprite_pointers` (the bytes read from the sprite-pointer table at
+ * screen_base+$3F8..$3FF) feed the derivation.
+ */
+export function buildChipState(raw) {
+  const dd00 = raw.dd00_raw;
+  const d018 = raw.d018_raw;
+  const bank = vicBank(dd00);
+  const bankBase = bank * 16384;
+  const screenBaseAddr = screenBase(d018, dd00);
+  const charsetBaseAddr = charsetBase(d018, dd00);
+  const port01raw = raw.port01_raw;
+  const spritePointers = raw.sprite_pointers ?? [];
+  const spriteDataAddresses = spritePointers.map((p) => bankBase + p * 64);
+
+  return {
+    schema_version: 1,
+    release: raw.release,
+    label: raw.label,
+    snapshot_name: raw.snapshot_name ?? null,
+    registers: raw.registers,
+    sprites: raw.sprites,
+    cpu: raw.cpu,
+    derived: {
+      port01: {
+        raw: port01raw,
+        loram: !!(port01raw & 1),
+        hiram: !!(port01raw & 2),
+        charen: !!(port01raw & 4),
+      },
+      dd00_raw: dd00,
+      dd00_direct_read: raw.dd00_direct_read ?? dd00,
+      vic_bank: bank,
+      d018_raw: d018,
+      screen_base: screenBaseAddr,
+      charset_base: charsetBaseAddr,
+      sprite_pointers: spritePointers,
+      sprite_data_addresses: spriteDataAddresses,
+    },
+    captured_at: raw.captured_at ?? new Date().toISOString(),
+  };
+}
+
+// ---------------------------------------------------------- buildRangeManifest
+
+const IO_START = 0xd000;
+const IO_END = 0xdfff;
+
+function powerOnRunLength(image, start) {
+  const b = image[start];
+  if (b !== 0x00 && b !== 0xff) return 0;
+  let end = start;
+  while (end < image.length && image[end] === b) end++;
+  return end - start;
+}
+
+/**
+ * Emit the D-02 range manifest in the committed shape: ranges whose union
+ * covers $0000-$FFFF with no gap and no overlap, a contiguous power-on-
+ * pattern run of at least 16 bytes marked kind `unused`, the I/O window
+ * ($D000-$DFFF) marked `io`, everything else `unclassified`, and
+ * `classification_state` set to the same transient `ranges-only` state the
+ * committed primary manifests carry.
+ */
+export function buildRangeManifest(image, meta = {}) {
+  if (image.length !== 65536) {
+    throw new Error(`buildRangeManifest: image must be exactly 65536 bytes, got ${image.length}`);
+  }
+  const ranges = [];
+  let i = 0;
+  while (i < 65536) {
+    if (i >= IO_START && i <= IO_END) {
+      ranges.push({ start: i, end: IO_END, kind: "io", source: "capture", note: "VIC-II/SID/CIA/color-RAM I/O window" });
+      i = IO_END + 1;
+      continue;
+    }
+    const runLen = powerOnRunLength(image, i);
+    if (runLen >= 16) {
+      const end = i + runLen - 1;
+      ranges.push({ start: i, end, kind: "unused", source: "capture", note: "contiguous $00/$FF power-on-pattern run of at least 16 bytes" });
+      i = end + 1;
+      continue;
+    }
+    let j = i;
+    while (j < 65536 && !(j >= IO_START && j <= IO_END) && powerOnRunLength(image, j) < 16) {
+      j++;
+    }
+    ranges.push({ start: i, end: j - 1, kind: "unclassified", source: "capture", note: "awaiting the loader/cracktro/game three-bucket partition" });
+    i = j;
+  }
+  return {
+    schema_version: 1,
+    release: meta.release,
+    label: meta.label,
+    snapshot_name: meta.snapshot_name ?? null,
+    image_bytes: image.length,
+    offset_equals_address: true,
+    classification_state: "ranges-only",
+    ranges,
+    note: meta.note ?? "",
+    generated_at: meta.generated_at ?? new Date().toISOString(),
+  };
+}
+
+// -------------------------------------------------------------- writeDumpSet
+
+/**
+ * Render and write the four-file dump set from a committed chunk file's
+ * contents plus the chip-state raw readings. Returns the written paths and
+ * the image digest, so a caller can register a `dumps[]` entry.
+ */
+export function writeDumpSet({ releaseId, label, chunks, chipStateRaw, meta = {}, captureExtra = {} }) {
+  const image = assembleImage(chunks);
+  const digest = sha256Buffer(image);
+  const dumpsDir = join(releaseDir(releaseId), "dumps");
+  mkdirSync(dumpsDir, { recursive: true });
+
+  const binPath = join(dumpsDir, `${releaseId}-${label}.bin`);
+  writeFileSync(binPath, image);
+
+  const stateOut = buildChipState({ ...chipStateRaw, release: releaseId, label });
+  const statePath = join(dumpsDir, `${releaseId}-${label}.state.json`);
+  writeFileSync(statePath, JSON.stringify(stateOut, null, 2) + "\n");
+
+  const manifestOut = buildRangeManifest(image, { release: releaseId, label, ...meta });
+  const mapPath = join(dumpsDir, `${releaseId}-${label}.map.json`);
+  writeFileSync(mapPath, JSON.stringify(manifestOut, null, 2) + "\n");
+
+  const captureOut = {
+    release: releaseId,
+    label,
+    sha256: digest,
+    bytes: image.length,
+    ...captureExtra,
+  };
+  const capturePath = join(dumpsDir, `${releaseId}-${label}.capture.json`);
+  writeFileSync(capturePath, JSON.stringify(captureOut, null, 2) + "\n");
+
+  return {
+    bin: rel(binPath),
+    state: rel(statePath),
+    map: rel(mapPath),
+    capture: rel(capturePath),
+    sha256: digest,
+  };
+}
+
+// -------------------------------------------------------------------- CLI
+
+function optValue(rest, name) {
+  const i = rest.indexOf(`--${name}`);
+  return i === -1 ? undefined : rest[i + 1];
+}
+
+function readJsonArg(rest, name) {
+  const p = optValue(rest, name);
+  if (!p) return undefined;
+  return JSON.parse(readFileSync(resolve(p), "utf8"));
+}
+
+const VERBS = {
+  assemble(rest) {
+    const chunks = readJsonArg(rest, "chunks");
+    if (!chunks) die("usage: assemble --chunks <chunks.json> [--json]");
+    const image = assembleImage(chunks);
+    const digest = sha256Buffer(image);
+    const result = { bytes: image.length, sha256: digest };
+    console.log(rest.includes("--json") ? JSON.stringify(result, null, 2) : `${result.bytes} bytes, sha256 ${result.sha256}`);
+  },
+
+  "chip-state"(rest) {
+    const raw = readJsonArg(rest, "raw");
+    if (!raw) die("usage: chip-state --raw <raw.json> [--json]");
+    const result = buildChipState(raw);
+    console.log(JSON.stringify(result, null, 2));
+  },
+
+  manifest(rest) {
+    const chunks = readJsonArg(rest, "chunks");
+    const metaArg = readJsonArg(rest, "meta") ?? {};
+    if (!chunks) die("usage: manifest --chunks <chunks.json> [--meta <meta.json>] [--json]");
+    const image = assembleImage(chunks);
+    const result = buildRangeManifest(image, metaArg);
+    console.log(JSON.stringify(result, null, 2));
+  },
+
+  "write-set"(rest) {
+    const releaseId = optValue(rest, "release");
+    const label = optValue(rest, "label");
+    const chunks = readJsonArg(rest, "chunks");
+    const chipStateRaw = readJsonArg(rest, "raw");
+    const metaArg = readJsonArg(rest, "meta") ?? {};
+    if (!releaseId || !label || !chunks || !chipStateRaw) {
+      die("usage: write-set --release <id> --label <label> --chunks <chunks.json> --raw <raw.json> [--meta <meta.json>] [--json]");
+    }
+    const result = writeDumpSet({ releaseId, label, chunks, chipStateRaw, meta: metaArg });
+    console.log(JSON.stringify(result, null, 2));
+  },
+};
+
+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)} <assemble|chip-state|manifest|write-set> [--json]`);
+    process.exitCode = cmd ? 1 : 0;
+  } else {
+    VERBS[cmd](rest);
+  }
+}

package/skills/c64-ram-capture/scripts/dump-artifacts.test.mjs

@@ -0,0 +1,133 @@
+// Coverage for the artifact renderer (01-04 Task 1, Part B): chunk
+// contiguity and the 65536-byte assertion, the gap and overlap refusals,
+// the VIC-bank/screen-base/charset-base derivations against the committed
+// sidecars' own recorded values, and the power-on-pattern run detection
+// that produces `unused` ranges. Runs entirely with no emulator present.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
+
+import { assembleImage, sha256Buffer, buildChipState, vicBank, screenBase, buildRangeManifest } from "./dump-artifacts.mjs";
+import { allDumpArtifacts, skipUnless } from "./test-corpus.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(HERE, "..", "..", "..", "..");  // scripts -> skill -> skills -> .claude -> repo root
+
+function chunkOf(address, byte, length) {
+  // `byte` is a 2-hex-char octet (e.g. "00"); repeating it `length` times
+  // yields `length` bytes of hex.
+  return { address, hex: byte.repeat(length) };
+}
+
+test("assembleImage returns a 65536-byte buffer from ordered contiguous chunk records", () => {
+  const chunks = [chunkOf(0, "00", 32768), chunkOf(32768, "ff", 32768)];
+  const image = assembleImage(chunks);
+  assert.equal(image.length, 65536);
+  assert.equal(image[0], 0x00);
+  assert.equal(image[32768], 0xff);
+});
+
+test("assembleImage accepts chunks out of order and still assembles correctly", () => {
+  const chunks = [chunkOf(32768, "ff", 32768), chunkOf(0, "00", 32768)];
+  const image = assembleImage(chunks);
+  assert.equal(image.length, 65536);
+});
+
+test("assembleImage throws naming the address for a one-byte gap", () => {
+  const chunks = [chunkOf(0, "00", 32768), chunkOf(32769, "ff", 32767)];
+  assert.throws(() => assembleImage(chunks), /gap before address \$8000/);
+});
+
+test("assembleImage throws naming the address for a one-byte overlap", () => {
+  const chunks = [chunkOf(0, "00", 32769), chunkOf(32768, "ff", 32768)];
+  assert.throws(() => assembleImage(chunks), /overlap at address \$8000/);
+});
+
+test("assembleImage throws when the total is not exactly 65536 bytes", () => {
+  const chunks = [chunkOf(0, "00", 100)];
+  assert.throws(() => assembleImage(chunks), /expected exactly 65536/);
+});
+
+test("sha256Buffer hashes with node:crypto and is deterministic", () => {
+  const buf = Buffer.from("hello", "utf8");
+  const a = sha256Buffer(buf);
+  const b = sha256Buffer(buf);
+  assert.equal(a, b);
+  assert.equal(a.length, 64);
+});
+
+test("vicBank derives the bank from the two low bits of $DD00, inverted per the memmap table", () => {
+  assert.equal(vicBank(0b00), 3);
+  assert.equal(vicBank(0b01), 2);
+  assert.equal(vicBank(0b10), 1);
+  assert.equal(vicBank(0b11), 0);
+  assert.equal(vicBank(193), 2); // real committed dd00_raw
+});
+
+test("screenBase derives the screen pointer from $D018 bits 4-7 relative to the VIC bank base", () => {
+  assert.equal(screenBase(49, 193), 35840); // real committed values
+});
+
+// Corpus-driven: re-derive vic_bank / screen_base / charset_base from EVERY
+// committed chip-state sidecar the registry names, and require each to match what
+// that sidecar recorded. Running it over every release is what proves the formula
+// is generic rather than tuned to one machine state -- and with no corpus it
+// skips instead of failing.
+const CHIP_STATES = allDumpArtifacts("chip_state");
+
+test("buildChipState reproduces every committed sidecar's recorded vic_bank, screen_base and charset_base",
+  { skip: skipUnless(CHIP_STATES, "committed chip-state sidecars") }, () => {
+  for (const { release, label, path } of CHIP_STATES) {
+    const committed = JSON.parse(readFileSync(path, "utf8"));
+    if (!committed.derived) continue;
+    const raw = {
+      dd00_raw: committed.derived.dd00_raw,
+      d018_raw: committed.derived.d018_raw,
+      port01_raw: committed.derived.port01.raw,
+      sprite_pointers: committed.derived.sprite_pointers,
+    };
+    const result = buildChipState(raw);
+    const where = `${release}/${label}`;
+    assert.equal(result.derived.vic_bank, committed.derived.vic_bank, `${where}: vic_bank`);
+    assert.equal(result.derived.screen_base, committed.derived.screen_base, `${where}: screen_base`);
+    assert.equal(result.derived.charset_base, committed.derived.charset_base, `${where}: charset_base`);
+  }
+});
+
+test("buildRangeManifest marks a contiguous power-on-pattern run of at least 16 bytes as kind unused", () => {
+  const image = Buffer.alloc(65536, 0xaa);
+  // A genuine 20-byte run of $00 in the middle, well clear of the I/O window.
+  image.fill(0x00, 4096, 4116);
+  const manifest = buildRangeManifest(image, { release: "fake", label: "run1" });
+  const hit = manifest.ranges.find((r) => r.start === 4096);
+  assert.ok(hit, "expected a range starting at the pattern run");
+  assert.equal(hit.kind, "unused");
+  assert.equal(hit.end, 4115);
+});
+
+test("buildRangeManifest marks the I/O window $D000-$DFFF as kind io and sets classification_state to ranges-only", () => {
+  const image = Buffer.alloc(65536, 0xaa);
+  const manifest = buildRangeManifest(image, { release: "fake", label: "run1" });
+  assert.equal(manifest.classification_state, "ranges-only");
+  const io = manifest.ranges.find((r) => r.start === 0xd000);
+  assert.ok(io);
+  assert.equal(io.kind, "io");
+  assert.equal(io.end, 0xdfff);
+});
+
+test("buildRangeManifest throws when the image is not exactly 65536 bytes", () => {
+  assert.throws(() => buildRangeManifest(Buffer.alloc(100), {}), /exactly 65536 bytes/);
+});
+
+test("buildRangeManifest's ranges union covers $0000-$FFFF with no gap and no overlap on a synthetic image", () => {
+  const image = Buffer.alloc(65536, 0x11);
+  const manifest = buildRangeManifest(image, { release: "fake", label: "run1" });
+  let expected = 0;
+  for (const r of manifest.ranges) {
+    assert.equal(r.start, expected);
+    expected = r.end + 1;
+  }
+  assert.equal(expected, 65536);
+});