@henols/c64-re-tools 2.1.1 → 2.1.3

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

@@ -145,11 +145,11 @@ export function joystickMask(direction: Extract<ActionStep, { joystick: unknown
   return direction.split("-").reduce((mask, part) => mask | (bits[part] ?? 0), fire ? 0x10 : 0);
 }
 
-/** A state item of the command line: a name or a $ address, with :size for more than one byte. */
-export function parseStateItem(text: string): StateItem {
+/** A state item of the command line: a name or a $ address, with :size for more than one byte. `option` names the option of the item in a refusal. */
+export function parseStateItem(text: string, option = "--state"): StateItem {
   const match = /^([^:]+)(?::(\d+))?$/.exec(text);
   const size = Number(match?.[2] ?? 1);
-  if (match === null || !isInteger(size, 1, MAX_STATE_BYTES)) throw new Refusal("invalid-input", `--state ${text}: give a name or a $ address, with :size from 1 to ${MAX_STATE_BYTES}`);
+  if (match === null || !isInteger(size, 1, MAX_STATE_BYTES)) throw new Refusal("invalid-input", `${option} ${text}: give a name or a $ address, with :size from 1 to ${MAX_STATE_BYTES}`);
   return { address: match[1]!, size };
 }
 

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

@@ -37,7 +37,7 @@ export async function replay(values: ReplayOptions): Promise<ReplayResult> {
   const folder = values.folder.replace(/\/+$/, "").replace(/\/recording\.json$/, "");
   const recording = readRecording(folder);
   const given: Comparison | undefined =
-    values.checkpoint === undefined ? undefined : { checkpoint: values.checkpoint, state: values.state.map(parseStateItem), ...(values.pin.length === 0 ? {} : { pin: values.pin.map(parseStateItem) }) };
+    values.checkpoint === undefined ? undefined : { checkpoint: values.checkpoint, state: values.state.map((item) => parseStateItem(item, "--state")), ...(values.pin.length === 0 ? {} : { pin: values.pin.map((item) => parseStateItem(item, "--pin")) }) };
   const compare = given ?? recording.compare;
   if (values.rebuild !== undefined && compare === undefined) throw new UsageError("the recording has no checkpoint and state: give --checkpoint and --state");
   const result = (outcome: ReplayResult["result"], side: ReplayResult["side"], fields: Partial<ReplayResult> = {}): ReplayResult => ({

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

@@ -5,12 +5,14 @@
 
 import { formatC64Address, formatSprite, formatVicii, parseC64Address } from "#src/c64.ts";
 import { runProgram } from "#src/host-client/autostart.ts";
+import { isRefusal, Refusal } from "#src/errors.ts";
 import { readCoverage } from "#src/host-client/coverage.ts";
-import { ACTION_STEP_KINDS, checkActionStep, isInteger, isObject, refuseOldStep, renamedField, runActionStep, VICE_STEP_KINDS, type ActionStep, type ActionStepKind } from "#src/host-client/steps.ts";
+import { ACTION_STEP_KINDS, checkActionStep, checkStepNames, isInteger, isObject, refuseOldStep, renamedField, runActionStep, VICE_STEP_KINDS, type ActionStep, type ActionStepKind } from "#src/host-client/steps.ts";
 import { readPrg } from "#src/host-client/image.ts";
 import { MAX_MEMORY_READ, MAX_TRACE_FRAMES, MAX_TRACE_HITS, MAX_TRACE_POINTS, TRACE_KINDS, WireFailure, type TraceHit, type TraceKind } from "#src/host-client/tools.ts";
 import { readProjectFile, writeReported, type Written } from "#src/host-client/transfer.ts";
 import { readMemoryInParts, ViceSessionClient } from "#src/host-client/vice-session.ts";
+import { checkSnapshotFile } from "#src/media.ts";
 import { UsageError } from "#src/script.ts";
 import { namesOf } from "./scenario.ts";
 
@@ -161,11 +163,26 @@ function readRun(path: string): Run {
 /** The remedy for a start program that is no PRG. */
 const PROGRAM_REMEDY = "A run starts a PRG. Get the PRG out of the disk, tape or cartridge with disk.ts read (or disk.ts crt) of the c64-disk skill";
 
-/** Checks each file that the run reads before the emulator starts: the start program or snapshot, and each snapshot step. */
-function checkRunFiles(run: Run): void {
-  if ("program" in run.start) readPrg(run.start.program, PROGRAM_REMEDY);
-  else readProjectFile(run.start.snapshot);
-  for (const step of run.steps) if ("snapshot" in step) readProjectFile(step.snapshot);
+/** Checks each file that the run reads before the emulator starts: the start program, and the start snapshot and each snapshot step, which must be VICE snapshot files. A refusal names the run file and the step. */
+function checkRunFiles(path: string, run: Run): void {
+  const named = (where: string, check: () => unknown) => {
+    try {
+      check();
+    } catch (error) {
+      if (isRefusal(error)) throw new Refusal(error.code, `run ${path}: ${where}: ${error.message}`);
+      throw error;
+    }
+  };
+  if ("program" in run.start) {
+    const { program } = run.start;
+    named("start.program", () => readPrg(program, PROGRAM_REMEDY));
+  } else {
+    const { snapshot } = run.start;
+    named("start.snapshot", () => checkSnapshotFile(snapshot, readProjectFile(snapshot).bytes));
+  }
+  run.steps.forEach((step, index) => {
+    if ("snapshot" in step) named(`step ${index + 1}: snapshot`, () => checkSnapshotFile(step.snapshot, readProjectFile(step.snapshot).bytes));
+  });
 }
 
 /** A trace hit with $ addresses, as a person reads it. */
@@ -176,14 +193,33 @@ function showHit(hit: TraceHit) {
 /** Runs the run file and writes its files into `out`. failed: a step did not run. */
 export async function runFile(path: string, out: string): Promise<{ output: Record<string, unknown>; failed: boolean }> {
   const run = readRun(path);
-  checkRunFiles(run);
+  checkRunFiles(path, run);
   const symbols = namesOf(run.symbols ?? "none");
   const at = (location: string): number => {
     if (location.startsWith("$")) return parseC64Address(location);
     const address = symbols.get(location);
-    if (address === undefined) throw new UsageError(`the symbols have no ${location}`);
-    return address;
+    if (address !== undefined) return address;
+    if (run.symbols === undefined || run.symbols === "none") {
+      throw new UsageError(`${location} is a name, and the run file has no symbols. A run file has no symbols unless it gives "symbols": "knowledge" for the names of the knowledge, or "symbols": "<file>" for a JSON file of names. Give one of them, or a $ address`);
+    }
+    throw new UsageError(`the symbols ${run.symbols} have no ${location}`);
   };
+  // Every name of the steps resolves before the emulator starts. A refusal names the step.
+  run.steps.forEach((step, index) => {
+    if ("trace" in step || "observe" in step) {
+      const names = "trace" in step ? step.points.flatMap((point) => [point.start, ...(point.end === undefined ? [] : [point.end])]) : step.memory === undefined || step.memory === "all" ? [] : step.memory.map((item) => (typeof item === "string" ? item : item.address));
+      for (const name of names) {
+        try {
+          at(name);
+        } catch (error) {
+          if (isRefusal(error)) throw new Refusal("invalid-input", `run ${path}: step ${index + 1}: ${error.message}`);
+          throw error;
+        }
+      }
+    } else if ((ACTION_STEP_KINDS as readonly string[]).some((kind) => kind in step)) {
+      checkStepNames([step as ActionStep], at, `run ${path}`, index + 1);
+    }
+  });
   const files: string[] = [];
   const written: Written[] = [];
   const write = (name: string, bytes: Uint8Array) => {

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,14 +123,17 @@ 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, 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,
   },
   {
     name: "run",
     summary: "Runs the steps of a run file in its own emulator and writes what they ask for into --out: screens, coverage maps, snapshot files, traces, and results.json with the observations. result is FAIL when a step did not run.",
     subjects: [{ name: "<run.json>", help: "a run file, relative to the project folder. See references/scenario-format.md, section Runs" }],
-    options: { out: { ...OPTIONS.out, value: "<dir>", required: true, help: "the folder for the files of the steps and results.json" } },
+    options: { out: { ...OPTIONS.out, output: "folder", value: "<dir>", required: true, help: "the folder for the files of the steps and results.json" } },
     run: async (call) => {
       const { output, failed } = await runFile(call.subject(0), call.string("out")!);
       return { result: failed ? "FAIL" : "PASS", ...output };
@@ -141,7 +144,7 @@ const COMMANDS: CommandSpec[] = [
     summary: "Plays the steps of a record file on the original in the replay core (c64run), and writes the session as a recording folder: recording.json, reads.txt and coverage.bin. result is FAIL when the session did not complete.",
     subjects: [{ name: "<record.json>", help: "a record file, relative to the project folder. See references/recording-format.md" }],
     options: {
-      out: { ...OPTIONS.out, value: "<dir>", required: true, help: "the recording folder, for example tests/recordings/<name>" },
+      out: { ...OPTIONS.out, output: "folder", value: "<dir>", required: true, help: "the recording folder, for example tests/recordings/<name>" },
       play: { kind: "flag", help: "a person plays after the steps: the script prints the address of a page on stderr. The page shows the start screen frozen until Start (Enter). End (F12) saves the recording, Cancel (F11) ends without one" },
       joystick: { kind: "count", value: "<1|2>", min: 1, max: 2, help: "with --play: the joystick port that the program reads, at the start (default 2). F9 on the page changes it" },
       "http-port": { kind: "count", value: "<n>", min: 0, max: 65535, help: `with --play: the port of the page (default ${DEFAULT_HTTP_PORT})` },
@@ -158,7 +161,7 @@ const COMMANDS: CommandSpec[] = [
       pin: { kind: "text", value: "<item>", multiple: true, help: `random state in RAM, in the form of --state: at each checkpoint the rebuild gets the original's values there` },
       rebuild: { kind: "path", value: "<prg>", help: "the rebuild to compare with the original" },
       symbols: { ...OPTIONS.symbols, help: "the names of the rebuild: the c64-assembler output (default: the symbols of the recording)" },
-      out: { ...OPTIONS.out, value: "<dir>", help: "with a FAIL, write the RAM of both sides at the first different checkpoint into this folder" },
+      out: { ...OPTIONS.out, output: "folder", value: "<dir>", help: "with a FAIL, write the RAM of both sides at the first different checkpoint into this folder" },
     },
     notes: "A recording without names takes the names of the knowledge for the original. A $ address is an address of the original: on the rebuild it moves with the name before it.",
     run: (call) => {
@@ -178,7 +181,7 @@ const COMMANDS: CommandSpec[] = [
       "max-listed": OPTIONS["max-listed"],
       ntsc: { kind: "flag", help: "the snapshots are of an NTSC machine (default PAL)" },
       address: { kind: "address", value: "<address>", help: "the address of the first byte of a memory file that is shorter than 64 KiB" },
-      out: { ...OPTIONS.out, value: "<file>", help: "also write all ranges to this file" },
+      out: { ...OPTIONS.out, output: "file", value: "<file>", help: "also write all ranges to this file" },
     },
     run: (call) => {
       const [address, out] = [call.address("address"), call.string("out")];

package/skills/c64-unpacker/SKILL.md

@@ -26,7 +26,7 @@ node <skill>/scripts/unpacker.ts capture original/game.prg --until '$c000' --out
 node <skill>/scripts/unpacker.ts loads original/game.d64 --steps .c64-re-tools/local/parts.json --out .c64-re-tools/local/parts --drive
 ```
 
-`inspect` examines the file locally. `trace`, `stages`, `capture` and `loads` start their own emulator through the host runtime and start the program. `trace` runs the program and finds the memory that the program wrote and then executed. `stages` runs the program and finds each stage: a decruncher, an intro, a copier, and then the program. For each stage it gives the entry, the frames, the written memory (`wrote`) and the entry of the next stage (`next`). `capture` stops the program when the CPU gets to the `--until` address. In `stages` and `capture`, a `frames` step and a `runUntil` step to an address without a condition count as run time. `stages` refuses a different `runUntil` step.
+`inspect` examines the file locally. `trace`, `stages`, `capture` and `loads` start their own emulator through the host runtime and start the program. `trace` runs the program and finds the memory that the program wrote and then executed. `stages` runs the program and finds each stage: a decruncher, an intro, a copier, and then the program. For each stage it gives the entry, the frames, the written memory (`wrote`) and the entry of the next stage (`next`). `wrote` lists each block that the stage wrote, also a small block. `capture` stops the program when the CPU gets to the `--until` address. In `stages` and `capture`, a `frames` step and a `runUntil` step to an address without a condition count as run time. `stages` refuses a different `runUntil` step.
 
 | Option | Meaning |
 |---|---|
@@ -41,11 +41,11 @@ node <skill>/scripts/unpacker.ts loads original/game.d64 --steps .c64-re-tools/l
 | `--max-listed 50` | `trace` only: the most ranges that `writtenThenExecuted` lists (default 50). |
 | `--drive` | `loads` only: each capture also writes the 2 KiB RAM of the 1541 drive as `drive8.prg`. |
 | `--min-block 64` | `loads` only: the smallest block of changed memory that becomes a segment (default 64). The result counts smaller changes as `smallChanges`. |
-| `--min-stage 64` | `stages` and `capture`: the smallest block of written memory that starts a new stage when the CPU executes it (default 64). |
+| `--min-stage 64` | `stages` and `capture`: the smallest block of written memory that starts a new stage when the CPU executes it (default 64). It does not change `wrote` or the segments. |
 
 The capture reads RAM, also the RAM under the ROMs and the I/O area. The script refuses an option that the command does not use. It refuses a wrong `--range` or `--exclude` before the emulator starts.
 
-A steps file is a JSON list of steps. Each step has the input of the MCP tool of the same action. An address in a step can be a name. For example, wait 50 frames and type a space:
+A steps file is a JSON list of steps. Each step has the input of the MCP tool of the same action. An address in a step can be a name. The script refuses an unknown name before the emulator starts. The message gives the file and the step. For example, wait 50 frames and type a space:
 
 ```json
 [{ "frames": 50 }, { "type": { "mode": "text", "text": " " } }]
@@ -69,6 +69,7 @@ The scripts refuse a step in the form of version 2.0, for example `{ "runUntil":
 - An address is `$` and 1 to 4 hex digits, for example `'$c000'` or `'$fb'`, or a name. A name is a symbol, else an analyzer name that only one analyzer gives. Quote an address in a shell.
 - A range is `<start>-<end>`, for example `'$c000-$cfff'`. In a JSON file, a range is `start` and `end`.
 - Bytes in a JSON file are hex in a field `data`, for example `"data": "a900"`.
+- The script examines each `--out` path before it starts work. It refuses a path in `.c64-re-tools/knowledge/` and the index of the knowledge, because only c64-knowledge writes them. It refuses a folder where the command writes a file, and a file where the command writes a folder.
 - The result is one JSON object on one line. A file that the script writes shows as `{"out", "bytes", "sha256"}`. A list shows as `{"count", "listed"}`, and `rest` tells where to get the rest of a long list.
 - An error is `{"error": {"code": "...", "message": "..."}}`. The message tells what is wrong and what to do.
 - The exit status is 0 for done or PASS, 1 for FAIL, 2 for an error and 3 for INCONCLUSIVE.
@@ -107,8 +108,8 @@ The scripts refuse a step in the form of version 2.0, for example `{ "runUntil":
    - A program can be relocated and not packed. Then a short copier moves the code and jumps to it. The moved code is the last stage. Make sure that the `entry` of the last stage is not code that the program writes later. An example is a routine that the program makes at run time. Disassemble the entry to make sure.
 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. 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. 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.
+   - `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. 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.
@@ -131,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`.
 
@@ -150,7 +151,9 @@ The packing evidence, the stages, or the unpacked program with its image, segmen
 
 `trace`, `stages`, `capture` and `loads` give `result: "PASS"` or `result: "FAIL"`. A FAIL has `reason`. `capture` gives the written files in `files`, each as `{out, bytes, sha256}`.
 
-For `loads`: `captures`, with the name, the PC, the segments, the files and the drive file of each capture. `keyWait: true` tells that the CPU was in the KERNAL wait for a key.
+`capture` gives `differsFromReset`: the count of bytes that are not as a clean C64 has them at READY.
+
+For `loads`: `captures`, with the name, the PC, the segments, `differsFromReset`, the files and the drive file of each capture. Each `entry_state.json` of `loads` has `differsFromReset` as the one of `capture` has. `keyWait: true` tells that the CPU was in the KERNAL wait for a key.
 
 ## Failure and conflicts
 

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

@@ -7,13 +7,14 @@
 import { COVERAGE, formatC64Address } from "#src/c64.ts";
 import { autostartLoaded, LOAD_LIMIT_FRAMES, RUN_LIMIT_FRAMES, typeRun } from "#src/host-client/autostart.ts";
 import { readCoverage } from "#src/host-client/coverage.ts";
-import { ACTION_STEP_KINDS, checkActionStep, isObject, runActionStep, VICE_STEP_KINDS, type ActionStep, type ActionStepKind } from "#src/host-client/steps.ts";
+import { ACTION_STEP_KINDS, checkActionStep, checkStepNames, isObject, runActionStep, VICE_STEP_KINDS, type ActionStep, type ActionStepKind } from "#src/host-client/steps.ts";
 import { knowledgeAt } from "#src/knowledge/names.ts";
 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 { entryState, json, machineState, readRam, vectorsOf } from "./machine.ts";
+import { entryStateFile, json, machineState, readRam, readyState, removeStaleFiles, vectorsOf } from "./machine.ts";
+import { FIRST_SEGMENT_ADDRESS } from "./stages.ts";
 
 
 export type LoadStep = ActionStep | { capture: string };
@@ -22,8 +23,6 @@ export type LoadStep = ActionStep | { capture: string };
 const NAME = /^[A-Za-z0-9._-]{1,64}$/;
 /** The drive RAM of a 1541. */
 const DRIVE_RAM = 0x0800;
-/** Pages 0-3 belong to the entry state, not to the segments. */
-const FIRST_SEGMENT_ADDRESS = 0x0400;
 /** The KERNAL LOAD entry in the jump table. */
 const KERNAL_LOAD = 0xffd5;
 /** The KERNAL loop that waits for a key at READY. or at an INPUT statement. */
@@ -57,7 +56,10 @@ export function readLoadSteps(path: string): LoadStep[] {
     if (kinds.length > 1) return fail(`${at} has ${kinds.length} step kinds: ${kinds.join(", ")}. Give each one its own step`);
     if (kinds.length !== 1) return fail(`${at} must have exactly one of ${[...VICE_STEP_KINDS, "capture"].join(", ")}`);
     // The step with its defaults filled in, as the shared schema of the action steps gives it.
-    (value as unknown[])[index] = checkActionStep(kinds[0] as ActionStepKind, step, at, fail);
+    const checked = checkActionStep(kinds[0] as ActionStepKind, step, at, fail);
+    // Its names resolve now: an unknown name stops the call before the emulator starts.
+    checkStepNames([checked], knowledgeAt(), `--steps ${path}`, index + 1);
+    (value as unknown[])[index] = checked;
   });
   if (names.size === 0) fail("the steps have no capture step");
   return value as LoadStep[];
@@ -97,6 +99,8 @@ const hex4 = (value: number) => value.toString(16).padStart(4, "0");
 export async function loads(program: string, options: { out: string; steps: LoadStep[]; drive: boolean; minBlock: number }): Promise<{ output: Record<string, unknown>; failed: boolean }> {
   const client = await ViceSessionClient.open({ videoStandard: "pal" });
   try {
+    // A clean machine at the READY prompt shows what the program changed at each capture. The run goes on after a capture, so it is read first.
+    const clean = await readyState(client);
     await client.reset({ mode: "hard", run: false });
     let previous: Buffer;
     /** A PRG that autostart put into memory without the CPU: its bytes count as written in the first capture. */
@@ -184,15 +188,20 @@ export async function loads(program: string, options: { out: string; steps: Load
           ...(drive === undefined ? {} : { drive }),
         }),
       );
-      write("entry_state.json", json(entryState(registers, state, vectors)));
+      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),
+        differsFromReset: entry.differsFromReset,
         ...(small === 0 ? {} : { smallChanges: small }),
         ...(drive === undefined ? {} : { drive: drive.file }),
       });