@henols/c64-re-tools 2.1.2 → 2.1.3

package/skills/c64-testing/scripts/lib/scenario.ts

@@ -12,10 +12,12 @@ import { applyEntryState, parseEntryState } from "#src/host-client/entry-state.t
 import { readPrg } from "#src/host-client/image.ts";
 import { readProjectFile, writeReported, type Written } from "#src/host-client/transfer.ts";
 import { readMemoryInParts, type ViceSessionClient } from "#src/host-client/vice-session.ts";
+import { checkSnapshotFile } from "#src/media.ts";
 import { openForRead } from "#src/knowledge/database.ts";
 import { nameTable } from "#src/knowledge/names.ts";
 import { DEFAULT_SPACE } from "#src/knowledge/schema.ts";
 import { programImage } from "#src/knowledge/program.ts";
+import { listed } from "#src/script.ts";
 
 export type Side = "original" | "rebuild";
 export const SIDES: Side[] = ["original", "rebuild"];
@@ -70,11 +72,24 @@ export interface Scenario {
 
 export type Outcome = "PASS" | "FAIL" | "INCONCLUSIVE";
 
+/** A byte of a memory item that differs: its address, and its value on each side as two hex digits. */
+export interface DifferingByte {
+  address: string;
+  original: string;
+  rebuild: string;
+}
+
+/**
+ * A difference at a checkpoint. A memory item gives the bytes that differ
+ * (at most --max-listed of them, and their count); every other item gives
+ * its value on each side.
+ */
 export interface Difference {
   checkpoint: string;
   what: string;
-  original: unknown;
-  rebuild: unknown;
+  original?: unknown;
+  rebuild?: unknown;
+  bytes?: { count: number; listed: DifferingByte[]; rest?: string };
 }
 
 export interface ScenarioResult {
@@ -290,8 +305,9 @@ const PROGRAM_REMEDY = "A scenario program is a PRG. Get the PRG out of the disk
 /**
  * Checks each file that the scenario names before an emulator starts: the
  * program and the symbols of each side, and each snapshot file. A missing
- * file is not-found; a program that is no PRG and a symbols file with no
- * names are invalid-input. Gives the names of each side.
+ * file is not-found; a program that is no PRG, a symbols file with no names
+ * and a snapshot step whose file is no VICE snapshot file are invalid-input.
+ * A refusal names the field or the step. Gives the names of each side.
  */
 export function scenarioNames(scenario: Scenario): Map<Side, Map<string, number>> {
   const names = new Map<Side, Map<string, number>>();
@@ -307,7 +323,9 @@ export function scenarioNames(scenario: Scenario): Map<Side, Map<string, number>
     named(`${side}.program`, () => readPrg(scenario[side].program, PROGRAM_REMEDY));
     names.set(side, named(`${side}.symbols`, () => namesOf(scenario[side].symbols)));
   }
-  for (const step of scenario.steps) if ("snapshot" in step) readProjectFile(step.snapshot);
+  scenario.steps.forEach((step, index) => {
+    if ("snapshot" in step) named(`step ${index + 1}: snapshot`, () => checkSnapshotFile(step.snapshot, readProjectFile(step.snapshot).bytes));
+  });
   return names;
 }
 
@@ -368,7 +386,6 @@ async function startProgram(client: ViceSessionClient, program: string, side: Si
 }
 
 async function runSide(client: ViceSessionClient, scenario: Scenario, side: Side, symbols: Map<string, number>, files: boolean): Promise<Map<string, Observation>> {
-  const subject = scenario[side];
   const observations = new Map<string, Observation>();
   const at = (location: Location) => resolve(location, symbols, side);
   // Each side starts from a hard reset, stopped at the reset vector, with the control ports released.
@@ -376,84 +393,117 @@ async function runSide(client: ViceSessionClient, scenario: Scenario, side: Side
   await client.joystick({ port: 1, direction: "center", fire: false });
   await client.joystick({ port: 2, direction: "center", fire: false });
   let checkpoint = 0;
-  for (const step of scenario.steps) {
+  for (const [index, step] of scenario.steps.entries()) {
     if (step.side !== undefined && step.side !== side) continue;
-    // Observe first: an observe step may also carry "registers" or "memory".
-    if ("observe" in step) {
-      checkpoint++;
-      const observation: Observation = { memory: [], registers: {} };
-      for (const item of step.memory ?? []) {
-        const spec: MemoryObservation = typeof item === "string" ? { address: item } : item;
-        const address = at(spec.address);
-        const size = spec.size ?? 1;
-        const read = { data: (await readMemoryInParts(client, address, size, spec.view ?? "cpu")).toString("hex") };
-        const excluded = (spec.exclude ?? []).map((exclude) => {
-          const offset = at(exclude.address) - address;
-          if (offset < 0 || offset >= size) throw new Refusal("invalid-input", `the exclude ${exclude.address} lies outside the observed ${spec.address} (${size} bytes)`);
-          return { offset, address: exclude.address, reason: exclude.reason };
-        });
-        observation.memory.push({ label: size > 1 ? `${spec.address} (${size} bytes)` : spec.address, address, bytes: [...Buffer.from(read.data, "hex")], tolerance: spec.tolerance ?? 0, excluded });
-      }
-      if (step.registers !== undefined) {
-        const registers = await client.registersGet("c64");
-        for (const name of step.registers) observation.registers[name] = name === "pc" ? formatC64Address(registers.pc) : registers[name];
-      }
-      if (step.vicii) {
-        // The raster line changes from one moment to the next; the comparison leaves it out.
-        const { rasterLine: _rasterLine, ...state } = await client.vicii();
-        observation.vicii = formatVicii(state);
-      }
-      if (step.sprites !== undefined) observation.sprites = (await client.sprites(step.sprites)).sprites.map(formatSprite);
-      if (step.screen !== undefined) {
-        const baseline = baselineName(checkpoint, step.observe);
-        if (side === "original") {
-          const shot = await client.screenCapture(baseline);
-          if (files) observation.png = shot.png;
-        } else {
-          const compared = await client.screenCompare({ baseline, maxMismatchRatio: step.screen.maxMismatchRatio ?? 0, mask: step.screen.mask ?? [], includeDiff: files });
-          observation.screen = { match: compared.match, mismatchingPixels: compared.mismatchingPixels, comparedPixels: compared.comparedPixels, mismatchRatio: compared.mismatchRatio, ...(compared.bounds === undefined ? {} : { bounds: compared.bounds }) };
-          if (files) {
-            observation.png = (await client.screenCapture()).png;
-            if (compared.diffPng !== undefined) observation.diffPng = compared.diffPng;
-          }
-          await client.screenDiscard(baseline);
+    try {
+      checkpoint = await runStep(client, scenario, side, step, at, checkpoint, files, observations);
+    } catch (error) {
+      // The step in the reason or the message: the scenario file has many steps.
+      const where = `step ${index + 1} (${stepKindOf(step)})`;
+      if (error instanceof Inconclusive) throw new Inconclusive(`${where}: ${error.message}`);
+      if (error instanceof WireFailure) throw new WireFailure(error.code, `${where}: ${error.message}`);
+      if (error instanceof Refusal) throw new Refusal(error.code, `${where}: ${error.message}`);
+      throw error;
+    }
+  }
+  return observations;
+}
+
+/** The kind of a checked step: its one key from the step kinds. */
+const stepKindOf = (step: Step) => Object.keys(step).find((key) => STEP_KINDS.includes(key)) ?? "step";
+
+/** Runs one step of one side. Gives the number of the last checkpoint. */
+async function runStep(client: ViceSessionClient, scenario: Scenario, side: Side, step: Step, at: (location: Location) => number, last: number, files: boolean, observations: Map<string, Observation>): Promise<number> {
+  const subject = scenario[side];
+  let checkpoint = last;
+  // Observe first: an observe step may also carry "registers" or "memory".
+  if ("observe" in step) {
+    checkpoint++;
+    const observation: Observation = { memory: [], registers: {} };
+    for (const item of step.memory ?? []) {
+      const spec: MemoryObservation = typeof item === "string" ? { address: item } : item;
+      const address = at(spec.address);
+      const size = spec.size ?? 1;
+      const read = { data: (await readMemoryInParts(client, address, size, spec.view ?? "cpu")).toString("hex") };
+      const excluded = (spec.exclude ?? []).map((exclude) => {
+        const offset = at(exclude.address) - address;
+        if (offset < 0 || offset >= size) throw new Refusal("invalid-input", `the exclude ${exclude.address} lies outside the observed ${spec.address} (${size} bytes)`);
+        return { offset, address: exclude.address, reason: exclude.reason };
+      });
+      observation.memory.push({ label: size > 1 ? `${spec.address} (${size} bytes)` : spec.address, address, bytes: [...Buffer.from(read.data, "hex")], tolerance: spec.tolerance ?? 0, excluded });
+    }
+    if (step.registers !== undefined) {
+      const registers = await client.registersGet("c64");
+      for (const name of step.registers) observation.registers[name] = name === "pc" ? formatC64Address(registers.pc) : registers[name];
+    }
+    if (step.vicii) {
+      // The raster line changes from one moment to the next; the comparison leaves it out.
+      const { rasterLine: _rasterLine, ...state } = await client.vicii();
+      observation.vicii = formatVicii(state);
+    }
+    if (step.sprites !== undefined) observation.sprites = (await client.sprites(step.sprites)).sprites.map(formatSprite);
+    if (step.screen !== undefined) {
+      const baseline = baselineName(checkpoint, step.observe);
+      if (side === "original") {
+        const shot = await client.screenCapture(baseline);
+        if (files) observation.png = shot.png;
+      } else {
+        const compared = await client.screenCompare({ baseline, maxMismatchRatio: step.screen.maxMismatchRatio ?? 0, mask: step.screen.mask ?? [], includeDiff: files });
+        observation.screen = { match: compared.match, mismatchingPixels: compared.mismatchingPixels, comparedPixels: compared.comparedPixels, mismatchRatio: compared.mismatchRatio, ...(compared.bounds === undefined ? {} : { bounds: compared.bounds }) };
+        if (files) {
+          observation.png = (await client.screenCapture()).png;
+          if (compared.diffPng !== undefined) observation.diffPng = compared.diffPng;
         }
-      }
-      observations.set(step.observe, observation);
-    } else if ("reset" in step) {
-      // Stopped at the reset vector, so frame counts from here are exact.
-      await client.reset({ mode: step.reset, run: false });
-    } else if ("load" in step) {
-      await client.programLoad({ path: subject.program });
-    } else if ("autostart" in step) {
-      await startProgram(client, subject.program, side);
-    } else if ("snapshot" in step) {
-      await client.snapshotRestore(readProjectFile(step.snapshot).bytes);
-    } else if ("normalize" in step) {
-      await normalize(client);
-    } else {
-      const { side: _side, ...action } = step;
-      const notReached = await runActionStep(client, action as ActionStep, at);
-      if (notReached !== undefined && "runUntil" in step) {
-        throw new Inconclusive(`the ${side} side did not reach the checkpoint before ${step.runUntil.timeoutFrames} frames (it stopped by ${notReached.stopReason} at ${formatC64Address(notReached.pc)})`);
+        await client.screenDiscard(baseline);
       }
     }
+    observations.set(step.observe, observation);
+  } else if ("reset" in step) {
+    // Stopped at the reset vector, so frame counts from here are exact.
+    await client.reset({ mode: step.reset, run: false });
+  } else if ("load" in step) {
+    await client.programLoad({ path: subject.program });
+  } else if ("autostart" in step) {
+    await startProgram(client, subject.program, side);
+  } else if ("snapshot" in step) {
+    await client.snapshotRestore(readProjectFile(step.snapshot).bytes);
+  } else if ("normalize" in step) {
+    await normalize(client);
+  } else {
+    const { side: _side, ...action } = step;
+    const notReached = await runActionStep(client, action as ActionStep, at);
+    if (notReached !== undefined && "runUntil" in step) {
+      throw new Inconclusive(`the ${side} side did not reach the checkpoint before ${step.runUntil.timeoutFrames} frames (it stopped by ${notReached.stopReason} at ${formatC64Address(notReached.pc)})`);
+    }
   }
-  return observations;
+  return checkpoint;
 }
 
-/** The differences between the two sides' observations at each checkpoint, under the scenario's rules. */
-export function compare(original: Map<string, Observation>, rebuild: Map<string, Observation>): Difference[] {
+type MemoryItem = Observation["memory"][number];
+
+/** The bytes of a memory item that differ by more than its tolerance, without the excluded bytes. */
+function differingBytes(item: MemoryItem, other: MemoryItem): DifferingByte[] {
+  const hex = (byte: number) => byte.toString(16).padStart(2, "0");
+  const skipped = new Set(item.excluded.map((excluded) => excluded.offset));
+  return item.bytes.flatMap((byte, offset) => (!skipped.has(offset) && Math.abs(byte - other.bytes[offset]!) > item.tolerance ? [{ address: formatC64Address(item.address + offset), original: hex(byte), rebuild: hex(other.bytes[offset]!) }] : []));
+}
+
+/** The most differing bytes of one memory item that a result lists when no --max-listed is given. */
+export const DEFAULT_LISTED_BYTES = 50;
+
+/**
+ * The differences between the two sides' observations at each checkpoint,
+ * under the scenario's rules. A memory item lists at most `max` differing
+ * bytes; `rest` tells where the others are.
+ */
+export function compare(original: Map<string, Observation>, rebuild: Map<string, Observation>, options: { max?: number; rest?: string } = {}): Difference[] {
   const differences: Difference[] = [];
+  const max = options.max ?? DEFAULT_LISTED_BYTES;
   for (const [checkpoint, left] of original) {
     const right = rebuild.get(checkpoint)!;
     left.memory.forEach((item, index) => {
-      const other = right.memory[index]!;
-      const skipped = new Set(item.excluded.map((excluded) => excluded.offset));
-      if (item.bytes.some((byte, at) => !skipped.has(at) && Math.abs(byte - other.bytes[at]!) > item.tolerance)) {
-        const show = (bytes: number[]) => Buffer.from(bytes).toString("hex");
-        differences.push({ checkpoint, what: `memory ${item.label}`, original: show(item.bytes), rebuild: show(other.bytes) });
-      }
+      const bytes = differingBytes(item, right.memory[index]!);
+      if (bytes.length > 0) differences.push({ checkpoint, what: `memory ${item.label}`, bytes: listed(bytes, max, undefined, options.rest) });
     });
     for (const [name, value] of Object.entries(left.registers)) {
       const other = right.registers[name as ObservedRegister];
@@ -469,15 +519,15 @@ export function compare(original: Map<string, Observation>, rebuild: Map<string,
 
 /**
  * Writes the files of a FAIL into `out`: for a screen difference both
- * screens and the difference image, and memory.json with each differing byte.
+ * screens and the difference image, and memory.json with each differing
+ * memory item: all its bytes on each side, and each byte that differs.
  */
 function writeFailFiles(out: string, original: Map<string, Observation>, rebuild: Map<string, Observation>, differences: Difference[]): Written[] {
   const files: Written[] = [];
   const write = (name: string, bytes: Uint8Array) => {
     files.push(writeReported(`${out}/${name}`, bytes, { what: "--out" }));
   };
-  const memory: Array<{ checkpoint: string; what: string; bytes: Array<{ address: string; original: string; rebuild: string }> }> = [];
-  const hex = (byte: number) => byte.toString(16).padStart(2, "0");
+  const memory: Array<{ checkpoint: string; what: string; address: string; original: string; rebuild: string; bytes: DifferingByte[] }> = [];
   for (const difference of differences) {
     const left = original.get(difference.checkpoint)!;
     const right = rebuild.get(difference.checkpoint)!;
@@ -491,9 +541,8 @@ function writeFailFiles(out: string, original: Map<string, Observation>, rebuild
       const index = left.memory.findIndex((item) => `memory ${item.label}` === difference.what);
       const item = left.memory[index]!;
       const other = right.memory[index]!;
-      const skipped = new Set(item.excluded.map((excluded) => excluded.offset));
-      const bytes = item.bytes.flatMap((byte, offset) => (!skipped.has(offset) && Math.abs(byte - other.bytes[offset]!) > item.tolerance ? [{ address: formatC64Address(item.address + offset), original: hex(byte), rebuild: hex(other.bytes[offset]!) }] : []));
-      memory.push({ checkpoint: difference.checkpoint, what: difference.what, bytes });
+      const show = (bytes: number[]) => Buffer.from(bytes).toString("hex");
+      memory.push({ checkpoint: difference.checkpoint, what: difference.what, address: formatC64Address(item.address), original: show(item.bytes), rebuild: show(other.bytes), bytes: differingBytes(item, other) });
     }
   }
   if (memory.length > 0) write("memory.json", Buffer.from(`${JSON.stringify(memory, null, 2)}\n`));
@@ -501,7 +550,7 @@ function writeFailFiles(out: string, original: Map<string, Observation>, rebuild
 }
 
 /** Runs the scenario on the original, then on the rebuild, in one VICE session. With out, a FAIL leaves files there. */
-export async function runScenario(client: ViceSessionClient, scenario: Scenario, options: { out?: string; names?: Map<Side, Map<string, number>> } = {}): Promise<ScenarioResult> {
+export async function runScenario(client: ViceSessionClient, scenario: Scenario, options: { out?: string; names?: Map<Side, Map<string, number>>; max?: number } = {}): Promise<ScenarioResult> {
   const checkpoints = scenario.steps.flatMap((step) => ("observe" in step ? [step.observe] : []));
   const observed = new Map<Side, Map<string, Observation>>();
   // The names of both sides before either side runs: a bad symbols file is an error, not a result.
@@ -519,7 +568,7 @@ export async function runScenario(client: ViceSessionClient, scenario: Scenario,
   }
   const original = observed.get("original")!;
   const rebuild = observed.get("rebuild")!;
-  const differences = compare(original, rebuild);
+  const differences = compare(original, rebuild, { ...(options.max === undefined ? {} : { max: options.max }), rest: options.out === undefined ? "a larger --max-listed, or --out <dir> for memory.json with every byte" : `${options.out}/memory.json` });
   const excluded = [...original].flatMap(([checkpoint, observation]) => observation.memory.flatMap((item) => item.excluded.map((excluded) => ({ checkpoint, address: excluded.address, reason: excluded.reason }))));
   const files = differences.length > 0 && options.out !== undefined ? writeFailFiles(options.out, original, rebuild, differences) : [];
   return {

package/skills/c64-testing/scripts/testing.ts

@@ -47,7 +47,7 @@ async function test(call: Call): Promise<ScenarioResult> {
     return { result: "INCONCLUSIVE", scenario: scenario.name, reason: `no emulator: ${error.message}`, checkpoints: [], differences: [] };
   }
   try {
-    return await runScenario(client, scenario, { names, ...(out === undefined ? {} : { out }) });
+    return await runScenario(client, scenario, { names, max: call.count("max-listed")!, ...(out === undefined ? {} : { out }) });
   } finally {
     await client.close();
   }
@@ -123,7 +123,10 @@ const COMMANDS: CommandSpec[] = [
     name: "test",
     summary: "Runs a scenario on the original and then on the rebuild in one emulator. result is PASS, FAIL with the differences, or INCONCLUSIVE with the reason.",
     subjects: [{ name: "<scenario.json>", help: "a scenario file, relative to the project folder. See references/scenario-format.md" }],
-    options: { out: { ...OPTIONS.out, output: "folder", value: "<dir>", help: "with a FAIL, write both screens, the difference image and memory.json with each differing byte into this folder" } },
+    options: {
+      out: { ...OPTIONS.out, output: "folder", value: "<dir>", help: "with a FAIL, write both screens, the difference image and memory.json into this folder: each differing memory item with all its bytes, and each byte that differs" },
+      "max-listed": { ...OPTIONS["max-listed"], help: "list at most n differing bytes of each memory item (default 50). The count is always given" },
+    },
     run: test,
   },
   {

package/skills/c64-unpacker/SKILL.md

@@ -109,7 +109,7 @@ The scripts refuse a step in the form of version 2.0, for example `{ "runUntil":
 4. Run `capture` with that address and a directory in `--out`. Give the same `--steps` as before. The directory gets:
    - `image.bin`: all 64 KiB of RAM at the entry.
    - `image.json`: the entry, the segments, the vectors and the stages. A segment is a block that a stage wrote, also a small block. A block is not a segment when it holds the entry of a later stage before the program, and no stage wrote over that entry. A block that a stage before the program wrote in such a block is also not a segment, for example a variable of a loader. A block that is fully in pages 0 to 3 is not a segment, because `entry_state.json` holds these pages. The block with the capture entry is always a segment. Segments do not overlap. `writtenBy` tells the last stage that wrote into the segment.
-   - One PRG for each segment.
+   - One PRG for each segment. A capture into a directory that has a capture removes the segment PRGs that the new `image.json` does not list. `removed` in the result names them. The capture keeps all other files.
    - `entry_state.json`: the registers, `$00` and `$01`, pages 0 to 3, the VIC, SID and CIA registers, and the vectors. `cia` gives the CIA timer latches and interrupt masks. `differsFromReset` lists the bytes that are not as a clean C64 has them at READY. A rebuild must make these bytes the same, because the program can read them.
 5. Make sure that the result is the application: the code at the entry must not be the unpacker again. A segment can be data that a loader left, for example intro graphics. Keep it until other evidence shows that the program does not use it. Then capture again with `--exclude` for that range. Thus the source and the loader do not include the range.
 6. Put the capture into the knowledge with `image <out>/image.json` of the c64-knowledge skill. The knowledge keeps the segments, the entry, the entry state and the stages. The other skills read them there. The files in `<out>` are not necessary after that.
@@ -132,7 +132,7 @@ A multi-load program loads more parts from the disk while it runs, for example o
 ```
 
 2. Run `loads` with the steps file and a directory in `--out`. Add `--drive` when the program has its own drive code, for example a fast loader.
-3. Each capture writes `<out>/<name>/` with `image.bin`, `image.json`, `entry_state.json` and a PRG for each segment. A segment is a block of RAM from `$0400` that the program changed after the capture before. The first capture also has the program itself.
+3. Each capture writes `<out>/<name>/` with `image.bin`, `image.json`, `entry_state.json` and a PRG for each segment. It removes the segment PRGs and the `drive8.prg` of an earlier capture that the new `image.json` does not list. A segment is a block of RAM from `$0400` that the program changed after the capture before. The first capture also has the program itself.
 4. Put the part that you work on into the knowledge with `image <out>/<name>/image.json` of the c64-knowledge skill.
 5. With `--drive`, `drive8.prg` is the drive RAM at `$0000`-`$07ff`. Put it into the knowledge with `image <out>/<name>/drive8.prg --space drive8`. Then analyze it with c64-static-analysis and `--space drive8`.
 

package/skills/c64-unpacker/scripts/lib/loads.ts

@@ -13,7 +13,7 @@ import { WireFailure } from "#src/host-client/tools.ts";
 import { readProjectFile, writeReported, type Written } from "#src/host-client/transfer.ts";
 import { ViceSessionClient } from "#src/host-client/vice-session.ts";
 import { UsageError } from "#src/script.ts";
-import { entryStateFile, json, machineState, readRam, readyState, vectorsOf } from "./machine.ts";
+import { entryStateFile, json, machineState, readRam, readyState, removeStaleFiles, vectorsOf } from "./machine.ts";
 import { FIRST_SEGMENT_ADDRESS } from "./stages.ts";
 
 
@@ -190,11 +190,14 @@ export async function loads(program: string, options: { out: string; steps: Load
       );
       const entry = entryStateFile(registers, state, vectors, clean);
       write("entry_state.json", entry.bytes);
+      // A capture again into the folder: the files of the earlier capture that image.json no longer lists go.
+      const removed = removeStaleFiles(directory, [...files, ...(drive === undefined ? [] : ["drive8.prg"])]);
       const keyWait = registers.pc >= KERNAL_KEY_WAIT.start && registers.pc <= KERNAL_KEY_WAIT.end;
       captures.push({
         capture: step.capture,
         out: directory,
         files: written,
+        ...(removed.length === 0 ? {} : { removed }),
         pc: formatC64Address(registers.pc),
         ...(keyWait ? { keyWait: true } : {}),
         segments: segments.map(showRange),

package/skills/c64-unpacker/scripts/lib/machine.ts

@@ -2,9 +2,14 @@
 // 0-3, the chip registers read without side effects, and the vectors. The
 // capture and loads commands of the unpacker share it.
 
+import { readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+
 import { formatC64Address } from "#src/c64.ts";
 import { resetToReady } from "#src/host-client/entry-state.ts";
+import { writeRefusal } from "#src/host-client/transfer.ts";
 import type { ViceSessionClient } from "#src/host-client/vice-session.ts";
+import { projectRoot, resolveProjectPath } from "#src/project.ts";
 
 type Registers = Awaited<ReturnType<ViceSessionClient["registersGet"]>>;
 
@@ -102,4 +107,30 @@ function entryState(registers: Registers, state: MachineState, vectors: ReturnTy
   };
 }
 
+/** The names of the files that a capture writes for its content: a PRG for each segment, and the drive RAM. */
+const CAPTURE_FILE = /^(?:segment-[0-9a-f]{4}-[0-9a-f]{4}\.prg|drive8\.prg)$/;
+
+/**
+ * Removes from the capture folder `folder` (a project path) each file that an
+ * earlier capture wrote and this capture did not: a segment PRG of another
+ * range, or the drive RAM. image.json lists only the files of this capture.
+ * Every other file stays. Gives the removed files as project paths.
+ */
+export function removeStaleFiles(folder: string, written: readonly string[]): string[] {
+  const path = resolveProjectPath(folder, projectRoot());
+  const removed: string[] = [];
+  for (const entry of readdirSync(path, { withFileTypes: true })) {
+    // A symbolic link is not a file of a capture: it stays.
+    if (!entry.isFile() || !CAPTURE_FILE.test(entry.name) || written.includes(entry.name)) continue;
+    const file = `${folder}/${entry.name}`;
+    try {
+      rmSync(join(path, entry.name));
+    } catch (error) {
+      throw writeRefusal(error, file, "--out") ?? error;
+    }
+    removed.push(file);
+  }
+  return removed.sort();
+}
+
 export const json = (value: unknown) => Buffer.from(`${JSON.stringify(value, null, 2)}\n`);

package/skills/c64-unpacker/scripts/unpacker.ts

@@ -19,7 +19,7 @@ import { listed, OPTIONS, runScript, UsageError, type Call, type CommandSpec, ty
 import { basicStart, inspect, readMemoryMap, underRom, writtenThenExecuted } from "./lib/evidence.ts";
 import { loads, readLoadSteps } from "./lib/loads.ts";
 import { callReturn, captureSegments, executedIn, inRanges, mergeMaps, stageCandidates, stagePoints, withoutRanges } from "./lib/stages.ts";
-import { entryStateFile, machineState, readRam, readyState, vectorsOf } from "./lib/machine.ts";
+import { entryStateFile, machineState, readRam, readyState, removeStaleFiles, vectorsOf } from "./lib/machine.ts";
 
 /** Written-then-executed bytes from this many on are unpacking, decrypting or relocating, not self-changing code. */
 const UNPACKED_BYTES = 256;
@@ -537,12 +537,15 @@ async function capture(
     // A clean machine at the READY prompt shows what the loader and the stages changed.
     const entry = entryStateFile(registers, state, vectors, await readyState(client));
     write("entry_state.json", entry.bytes);
+    // A capture again into the folder: the segment PRGs of the earlier capture that image.json no longer lists go.
+    const removed = removeStaleFiles(options.out, files);
     return {
       output: {
         captured: true,
         pc: formatC64Address(registers.pc),
         out: options.out,
         files: written,
+        ...(removed.length === 0 ? {} : { removed }),
         segments: segments.map(showRange),
         ...(options.exclude.length === 0 ? {} : { excluded: options.exclude.map(showRange) }),
         stages: followed.stages.length,