@henols/c64-re-tools 2.1.0 → 2.1.2

package/skills/c64-testing/scripts/lib/diff-files.ts

@@ -5,6 +5,8 @@
 // run, or two observations of runs (also two of one run), compare as they are.
 
 import { formatC64Address, parseC64Address } from "#src/c64.ts";
+import { Refusal } from "#src/errors.ts";
+import { isObject } from "#src/host-client/steps.ts";
 import { WireFailure } from "#src/host-client/tools.ts";
 import { readProjectFile, writeReported } from "#src/host-client/transfer.ts";
 import { readMemoryInParts, ViceSessionClient } from "#src/host-client/vice-session.ts";
@@ -41,33 +43,92 @@ function observation(path: string): MachineState {
       observed[at] = readProjectFile(`${folder}${(value as { file: string }).file}`).bytes.toString("hex");
     }
   }
-  const values: Record<string, number> = {};
-  for (const [register, value] of Object.entries(seen.registers ?? {})) {
+  return { observed, values: cpuValues(seen.registers ?? {}) };
+}
+
+/** The CPU registers as values: each register by its name, the pc from a number or "$xxxx", and each flag as cpu.flags.<flag>. */
+function cpuValues(registers: Record<string, unknown>): Record<string, number | boolean> {
+  const values: Record<string, number | boolean> = {};
+  for (const [register, value] of Object.entries(registers)) {
     if (typeof value === "number") values[`cpu.${register}`] = value;
     else if (typeof value === "string" && value.startsWith("$")) values[`cpu.${register}`] = parseC64Address(value);
+    else if (register === "flags" && isObject(value)) for (const [flag, set] of Object.entries(value)) if (typeof set === "boolean") values[`cpu.flags.${flag}`] = set;
   }
-  return { observed, values };
+  return values;
 }
 
-/** The state of a snapshot: restored in the session, then read with the readers of the runs. */
-async function snapshotState(client: ViceSessionClient, path: string): Promise<MachineState> {
-  await client.snapshotRestore(readProjectFile(path).bytes);
+/** The size of the header of a module in a VICE snapshot file: the name (16 bytes), the version (2 bytes) and the size (4 bytes). */
+const MODULE_HEADER = 22;
+const VSF_MAGIC = "VICE Snapshot File\x1a";
+const VSF_VERSION = "VICE Version\x1a";
+
+/**
+ * The 64 KiB of C64 RAM that a VICE snapshot file holds: the C64MEM module,
+ * after the CPU port and the cartridge lines (4 bytes). Undefined when the
+ * file has no such module.
+ */
+export function snapshotRam(file: Uint8Array): Uint8Array | undefined {
+  const bytes = Buffer.from(file);
+  if (bytes.subarray(0, VSF_MAGIC.length).toString("latin1") !== VSF_MAGIC) return undefined;
+  // The magic, the version (2 bytes) and the machine name (16 bytes); a newer VICE adds its own version (8 bytes).
+  let at = VSF_MAGIC.length + 2 + 16;
+  if (bytes.subarray(at, at + VSF_VERSION.length).toString("latin1") === VSF_VERSION) at += VSF_VERSION.length + 8;
+  while (at + MODULE_HEADER <= bytes.length) {
+    const name = bytes.subarray(at, at + 16).toString("latin1").replace(/\0+$/, "");
+    const size = bytes.readUInt32LE(at + 18);
+    if (size < MODULE_HEADER) return undefined;
+    if (name === "C64MEM") return at + MODULE_HEADER + 4 + 0x10000 <= bytes.length ? bytes.subarray(at + MODULE_HEADER + 4, at + MODULE_HEADER + 4 + 0x10000) : undefined;
+    at += size;
+  }
+  return undefined;
+}
+
+/**
+ * The state of a snapshot: restored in the session, then read with the
+ * readers of the runs. The RAM must be the RAM of the file: else the
+ * snapshot did not restore, and the state would be wrong.
+ */
+async function snapshotState(client: ViceSessionClient, path: string, ntsc: boolean): Promise<MachineState> {
+  const file = readProjectFile(path).bytes;
+  const saved = snapshotRam(file);
+  if (saved === undefined) throw new Refusal("invalid-input", `${path} is not a snapshot of a C64: it has no C64 memory. Give a file that c64_snapshot save or a save step of a run wrote.`);
+  const restored = await client.snapshotRestore(file);
   const memory = await readMemoryInParts(client, 0x0000, 0x10000, "ram");
+  // $00 and $01 are the CPU port: the file keeps them apart from the RAM.
+  if (("restored" in restored && !restored.restored) || !memory.subarray(2).equals(Buffer.from(saved.subarray(2)))) {
+    throw new Refusal(
+      "invalid-input",
+      `${path} did not restore: the RAM after the restore is not the RAM of the file. A snapshot restores only in a machine of the video standard that saved it. ${ntsc ? "Leave out --ntsc for a PAL snapshot" : "Give --ntsc for an NTSC snapshot"}, or use the emulator version that saved it.`,
+    );
+  }
   const colorRam = Buffer.from((await client.ioRead(0xd800, 0x400)).data, "hex").map((value) => value & 0x0f);
   const vic = Buffer.from((await client.ioRead(0xd000, 0x2f)).data, "hex");
-  const values: Record<string, number> = {};
+  const values: Record<string, number | boolean> = {};
   vic.forEach((value, index) => (values[`vic.${formatC64Address(0xd000 + index)}`] = value));
   for (const chip of (await client.cia("both")).chips) {
     for (const field of ["portA", "portB", "ddrA", "ddrB", "timerA", "timerB", "latchA", "latchB", "controlA", "controlB", "interruptMask"] as const) values[`cia${chip.id}.${field}`] = chip[field];
   }
   const sid = await client.sid();
   for (const voice of sid.voices) for (const [field, value] of Object.entries(voice)) if (field !== "index" && typeof value === "number") values[`sid.voice${voice.index}.${field}`] = value;
-  const registers = await client.registersGet("c64");
-  for (const [field, value] of Object.entries(registers)) if (typeof value === "number") values[`cpu.${field}`] = value;
+  Object.assign(values, cpuValues({ ...(await client.registersGet("c64")) }));
   return { memory: { base: 0, bytes: memory }, colorRam, values };
 }
 
 const show = (range: ChangedRange) => ({ start: formatC64Address(range.start), end: formatC64Address(range.end), ...(range.a === undefined ? {} : { a: range.a, b: range.b }) });
+/** A changed value as a person reads it: the pc as "$xxxx". */
+const showValue = (item: { name: string; a: number | boolean; b: number | boolean }) => (item.name === "cpu.pc" && typeof item.a === "number" && typeof item.b === "number" ? { name: item.name, a: formatC64Address(item.a), b: formatC64Address(item.b) } : item);
+
+/**
+ * How many items two observations have in common, by name: the items that the
+ * diff compared. With none, the reason names what each side has, so that a
+ * count of 0 does not read as "equal".
+ */
+export function comparedItems(what: string, a: readonly string[], b: readonly string[], first: string, second: string): { compared: number; reason?: string } {
+  const compared = a.filter((name) => b.includes(name)).length;
+  if (compared > 0) return { compared };
+  const has = (names: readonly string[]) => (names.length === 0 ? "none" : names.join(", "));
+  return { compared, reason: `No ${what} was compared: the observations have none in common. ${first} has ${has(a)}; ${second} has ${has(b)}.` };
+}
 
 /** The differences of two states of one kind: snapshots, memory files or observations of runs. */
 export async function diffFiles(first: string, second: string, options: { gap: number; max: number; ntsc: boolean; at?: number; out?: string }): Promise<Record<string, unknown>> {
@@ -90,8 +151,8 @@ export async function diffFiles(first: string, second: string, options: { gap: n
   } else {
     const client = await ViceSessionClient.open({ videoStandard: options.ntsc ? "ntsc" : "pal" });
     try {
-      a = await snapshotState(client, first);
-      b = await snapshotState(client, second);
+      a = await snapshotState(client, first, options.ntsc);
+      b = await snapshotState(client, second, options.ntsc);
     } finally {
       await client.close();
     }
@@ -101,7 +162,8 @@ export async function diffFiles(first: string, second: string, options: { gap: n
   const part = (item: { changedBytes: number; ranges: ChangedRange[] } | undefined) => (item === undefined ? undefined : { changedBytes: item.changedBytes, ...listed(item.ranges, max, show, rest) });
   let written: ReturnType<typeof writeReported> | undefined;
   if (options.out !== undefined) {
-    const all = { a: first, b: second, ...(diff.memory === undefined ? {} : { memory: diff.memory.ranges.map(show) }), ...(diff.colorRam === undefined ? {} : { colorRam: diff.colorRam.ranges.map(show) }), values: diff.values ?? [], observed: diff.observed ?? [] };
+    // The names of the result: registers holds the changed values.
+    const all = { a: first, b: second, ...(diff.memory === undefined ? {} : { memory: diff.memory.ranges.map(show) }), ...(diff.colorRam === undefined ? {} : { colorRam: diff.colorRam.ranges.map(show) }), registers: (diff.values ?? []).map(showValue), observed: diff.observed ?? [] };
     written = writeReported(options.out, `${JSON.stringify(all, null, 2)}\n`, { what: "--out" });
   }
   return {
@@ -109,8 +171,8 @@ export async function diffFiles(first: string, second: string, options: { gap: n
     b: second,
     ...(diff.memory === undefined ? {} : { memory: part(diff.memory) }),
     ...(diff.colorRam === undefined ? {} : { colorRam: part(diff.colorRam) }),
-    ...(diff.values === undefined ? {} : { registers: listed(diff.values, max, undefined, rest) }),
-    ...(diff.observed === undefined ? {} : { observed: listed(diff.observed, max, undefined, rest) }),
+    ...(diff.values === undefined ? {} : { registers: { ...(kind === "observation" ? comparedItems("register", Object.keys(a.values ?? {}), Object.keys(b.values ?? {}), first, second) : {}), ...listed(diff.values, max, showValue, rest) } }),
+    ...(diff.observed === undefined ? {} : { observed: { ...comparedItems("memory item", Object.keys(a.observed ?? {}), Object.keys(b.observed ?? {}), first, second), ...listed(diff.observed, max, undefined, rest) } }),
     ...(written === undefined ? {} : written),
   };
 }

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

@@ -10,8 +10,8 @@ export interface MachineState {
   memory?: { base: number; bytes: Uint8Array };
   /** Colour RAM $D800-$DBFF, the low 4 bits of each byte. */
   colorRam?: Uint8Array;
-  /** Named single values: VIC-II, CIA and SID registers and the CPU registers, as "vic.$d011", "cia1.timerA", "cpu.pc". */
-  values?: Record<string, number>;
+  /** Named single values: VIC-II, CIA and SID registers and the CPU registers, as "vic.$d011", "cia1.timerA", "cpu.pc", and each CPU flag as "cpu.flags.c". */
+  values?: Record<string, number | boolean>;
   /** The memory items of an observation of a run: the address or name, and its bytes as hex. */
   observed?: Record<string, string>;
 }
@@ -27,7 +27,7 @@ export interface ChangedRange {
 export interface StateDiff {
   memory?: { changedBytes: number; ranges: ChangedRange[] };
   colorRam?: { changedBytes: number; ranges: ChangedRange[] };
-  values?: Array<{ name: string; a: number; b: number }>;
+  values?: Array<{ name: string; a: number | boolean; b: number | boolean }>;
   observed?: Array<{ address: string; a: string; b: string }>;
 }
 

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

@@ -14,7 +14,7 @@ import { readFileSync, writeFileSync } from "node:fs";
 import { isRefusal, Refusal } from "#src/errors.ts";
 import { formatC64Address, parseC64Address } from "#src/c64.ts";
 import { READY_FRAMES } from "#src/host-client/entry-state.ts";
-import { ACTION_STEP_KINDS, checkActionStep, isInteger, isObject, keyboardBytes, stepKind, type ActionStep, type Location } from "#src/host-client/steps.ts";
+import { ACTION_STEP_KINDS, checkActionStep, isInteger, isObject, keyboardBytes, renamedField, stepKind, type ActionStep, type Location } from "#src/host-client/steps.ts";
 import { readProjectFile, type Written } from "#src/host-client/transfer.ts";
 import { PAL_FRAME_CYCLES, type C64RunSession, type CoreStatus } from "#src/native/c64run.ts";
 import type { Workspace } from "#src/native/staging.ts";
@@ -46,7 +46,7 @@ export interface StateItem {
   size: number;
 }
 
-/** The input of record.ts. */
+/** The input of testing.ts record. */
 export interface RecordFile {
   name: string;
   program: string;
@@ -145,21 +145,28 @@ 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 };
 }
 
-export function checkState(value: unknown, fail: (message: string) => never): StateItem[] {
-  if (!Array.isArray(value) || value.length === 0 || value.length > MAX_STATE_ITEMS) fail(`state must be a list of 1 to ${MAX_STATE_ITEMS} memory items`);
+/** Checks the memory items of state or pin (`what`): names, $ addresses, or { address, size }. */
+export function checkState(value: unknown, fail: (message: string) => never, what = "state"): StateItem[] {
+  if (!Array.isArray(value) || value.length === 0 || value.length > MAX_STATE_ITEMS) fail(`${what} must be a list of 1 to ${MAX_STATE_ITEMS} memory items`);
   return (value as unknown[]).map((item, index) => {
     const spec = typeof item === "string" ? { address: item } : item;
-    if (!isObject(spec) || typeof spec.address !== "string" || Object.keys(spec).some((key) => key !== "address" && key !== "size")) fail(`state item ${index + 1} must be a name, a $ address, or { address, size }`);
+    if (isObject(spec)) {
+      for (const key of Object.keys(spec)) {
+        const renamed = renamedField(key, ["address", "size"]);
+        if (key !== "address" && key !== "size") fail(`${what} item ${index + 1} has the field ${key}. ${renamed ?? "A memory item has address and size, and nothing else"}`);
+      }
+    }
+    if (!isObject(spec) || typeof spec.address !== "string") fail(`${what} item ${index + 1} must be a name, a $ address, or { address, size }`);
     const size = (spec as { size?: unknown }).size ?? 1;
-    if (!isInteger(size, 1, MAX_STATE_BYTES)) fail(`state item ${index + 1}: size must be from 1 to ${MAX_STATE_BYTES}`);
+    if (!isInteger(size, 1, MAX_STATE_BYTES)) fail(`${what} item ${index + 1}: size must be from 1 to ${MAX_STATE_BYTES}`);
     return { address: (spec as { address: string }).address, size: size as number };
   });
 }
@@ -195,7 +202,7 @@ export function readRecordFile(path: string): RecordFile {
   if ((value.checkpoint === undefined) !== (value.state === undefined)) fail("give checkpoint and state together, or neither: a replay can give them");
   if (value.checkpoint !== undefined && (typeof value.checkpoint !== "string" || value.checkpoint === "")) fail("checkpoint must be the name or $ address of a routine");
   if (value.pin !== undefined && value.checkpoint === undefined) fail("pin needs checkpoint and state");
-  const pin = value.pin === undefined ? undefined : checkState(value.pin, fail);
+  const pin = value.pin === undefined ? undefined : checkState(value.pin, fail, "pin");
   const compare = value.checkpoint === undefined ? undefined : { checkpoint: value.checkpoint as string, state: checkState(value.state, fail), ...(pin === undefined ? {} : { pin }) };
   const inputs = checkInputs(value.inputs, fail);
   if (!Array.isArray(value.steps) || value.steps.length === 0) fail("steps must be a list with at least one step");
@@ -219,7 +226,14 @@ export function readRecordFile(path: string): RecordFile {
 /** What the replay core cannot do of a step that is right for VICE: it has the C64 alone, no raster wait and no conditions. */
 function checkCoreStep(step: ActionStep, at: string, fail: (message: string) => never): void {
   if ("write" in step && step.write.space !== "c64") fail(`${at}: the replay core has the C64 alone, not ${step.write.space}`);
-  if ("press" in step) keyCodes(step.press);
+  if ("press" in step) {
+    try {
+      keyCodes(step.press);
+    } catch (error) {
+      if (isRefusal(error)) fail(`${at}: ${error.message}`);
+      throw error;
+    }
+  }
   if ("type" in step) {
     const keys = keyboardBytes(step.type);
     if (typeof keys !== "string" && keys.length > QUEUE_SIZE) fail(`${at}: the KERNAL keyboard queue holds ${QUEUE_SIZE} keys; give more type steps, or press for keys of the keyboard matrix`);
@@ -242,10 +256,31 @@ export function readRecording(folder: string): Recording {
     if (isRefusal(error)) throw error;
     throw new Refusal("invalid-input", `recording ${path}: ${(error as Error).message}`);
   }
-  if (!isObject(value) || value.format !== RECORDING_FORMAT) throw new Refusal("invalid-input", `recording ${path}: it is not a recording of format ${RECORDING_FORMAT}`);
-  for (const key of ["name", "program", "sha256", "symbols", "hash"]) if (typeof value[key] !== "string") throw new Refusal("invalid-input", `recording ${path}: ${key} is missing`);
-  for (const key of ["inputs", "events", "sites"]) if (!Array.isArray(value[key])) throw new Refusal("invalid-input", `recording ${path}: ${key} is missing`);
-  if (!isInteger(value.ticks, 1, Number.MAX_SAFE_INTEGER)) throw new Refusal("invalid-input", `recording ${path}: ticks is missing`);
+  const fail = (message: string): never => {
+    throw new Refusal("invalid-input", `recording ${path}: ${message}`);
+  };
+  if (!isObject(value) || value.format !== RECORDING_FORMAT) return fail(`it is not a recording of format ${RECORDING_FORMAT}`);
+  for (const key of ["name", "program", "sha256", "symbols", "hash"]) if (typeof value[key] !== "string") fail(`${key} is missing`);
+  for (const key of ["inputs", "events", "sites"]) if (!Array.isArray(value[key])) fail(`${key} is missing`);
+  if (!isInteger(value.ticks, 1, Number.MAX_SAFE_INTEGER)) fail("ticks is missing");
+  // A recording of an older version can have the step forms of the 2.0 files: refused with the form to write, never replayed wrong.
+  const remedy = "Record the session again with record, or write the 2.1 form in recording.json";
+  if (value.compare !== undefined) {
+    const compare = isObject(value.compare) ? value.compare : fail("compare must be an object with checkpoint, state and pin");
+    const where = (message: string): never => fail(`compare: ${message}. ${remedy}`);
+    if (typeof compare.checkpoint !== "string" || compare.checkpoint === "") where("checkpoint must be the name or $ address of a routine");
+    checkState(compare.state, where);
+    if (compare.pin !== undefined) checkState(compare.pin, where, "pin");
+  }
+  (value.events as unknown[]).forEach((event, index) => {
+    const at = `event ${index + 1}`;
+    const where = (message: string): never => fail(`${message}. ${remedy}`);
+    if (!isObject(event) || !isObject(event.action) || !isObject(event.key)) return where(`${at} must be an object with action and key`);
+    const named = typeof event.step === "number" ? `${at} (step ${event.step})` : at;
+    if (event.action.restore === true && Object.keys(event.action).length === 1) return;
+    // The action with the defaults filled in, as the record file gave it.
+    event.action = checkActionStep(stepKind(event.action, ACTION_STEP_KINDS, named, where), event.action, named, where, { press: true });
+  });
   return value as unknown as Recording;
 }
 

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

@@ -6,6 +6,8 @@
 
 import { createHash } from "node:crypto";
 
+import { isRefusal, Refusal } from "#src/errors.ts";
+import { readPrg } from "#src/host-client/image.ts";
 import { readProjectFile, writeReported, type Written } from "#src/host-client/transfer.ts";
 import { C64RunSession } from "#src/native/c64run.ts";
 import { localToolContext } from "#src/native/local.ts";
@@ -35,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 => ({
@@ -47,6 +49,15 @@ export async function replay(values: ReplayOptions): Promise<ReplayResult> {
     compared: 0,
     ...fields,
   });
+  // The files of the rebuild are checked before the replay core starts.
+  for (const [option, check] of [["--rebuild", () => values.rebuild !== undefined && readPrg(values.rebuild)], ["--symbols", () => values.symbols !== undefined && namesOf(values.symbols)]] as const) {
+    try {
+      check();
+    } catch (error) {
+      if (isRefusal(error)) throw new Refusal(error.code, `${option}: ${error.message}`);
+      throw error;
+    }
+  }
   const sha256 = createHash("sha256").update(readProjectFile(recording.program).bytes).digest("hex");
   if (sha256 !== recording.sha256) return result("INCONCLUSIVE", "original", { reason: `${recording.program} is not the program of the recording (its SHA-256 changed); record the session again` });
 

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

@@ -5,8 +5,10 @@
 
 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, runActionStep, 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";
@@ -35,6 +37,40 @@ const TRACE_KEYS = ["trace", "points", "frames", "maxHits"];
 const OBSERVE_KEYS = ["observe", "memory", "registers", "vicii", "sprites"];
 /** A name of a file that a step writes: letters, digits, dots, underscores or hyphens. */
 const NAME = /^[A-Za-z0-9._-]{1,64}$/;
+/** The file of the observations, which every run writes. */
+const RESULTS = "results.json";
+
+/** The file name of an observed memory item that goes into its own file: more than one read gives. */
+const memoryFile = (observe: string, address: string) => `${observe}-${address.replace(/^\$/, "")}.bin`;
+
+/**
+ * The files that each step of a run writes into --out, by step. Two steps
+ * that write one name (also in another case: some file systems do not tell
+ * them apart) are refused: the second would overwrite the first.
+ */
+function checkFileNames(steps: RunStep[], fail: (message: string) => never): void {
+  const writers = new Map<string, string>([[RESULTS, `the run itself (${RESULTS})`]]);
+  steps.forEach((step, index) => {
+    const named: [string, string[]] =
+      "save" in step
+        ? ["save", [`${step.save}.vsf`]]
+        : "screen" in step
+          ? ["screen", [`${step.screen}.png`]]
+          : "coverage" in step
+            ? ["coverage", [`${step.coverage}.bin`]]
+            : "trace" in step
+              ? ["trace", [`${step.trace}.json`]]
+              : "observe" in step
+                ? ["observe", step.memory === "all" ? [`${step.observe}.bin`] : (step.memory ?? []).flatMap((item) => (typeof item !== "string" && (item.size ?? 1) > MAX_MEMORY_READ ? [memoryFile(step.observe, item.address)] : []))]
+                : ["", []];
+    const [kind, files] = named;
+    for (const file of files) {
+      const other = writers.get(file.toLowerCase());
+      if (other !== undefined) fail(`step ${index + 1} (${kind}) writes ${file}, and ${other} writes that file too. Give one of them another name`);
+      writers.set(file.toLowerCase(), `step ${index + 1} (${kind})`);
+    }
+  });
+}
 
 function readRun(path: string): Run {
   let value: unknown;
@@ -60,8 +96,10 @@ function readRun(path: string): Run {
     const at = `step ${index + 1}`;
     if (!isObject(step)) return fail(`${at} must be an object`);
     const kinds = "observe" in step ? ["observe"] : "trace" in step ? ["trace"] : Object.keys(step).filter((key) => (ACTION_STEP_KINDS as readonly string[]).includes(key) || (OWN_KINDS as readonly string[]).includes(key));
-    if (kinds.length !== 1) return fail(`${at} must have exactly one of ${[...ACTION_STEP_KINDS, ...OWN_KINDS].join(", ")}`);
+    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, ...OWN_KINDS].join(", ")}`);
     const kind = kinds[0]!;
+    refuseOldStep(kind, step, at, fail);
     const allowed = kind === "observe" ? OBSERVE_KEYS : kind === "trace" ? TRACE_KEYS : [kind];
     for (const key of Object.keys(step)) if (!allowed.includes(key)) fail(`${at} has the key ${key}, which a ${kind} step does not have`);
     if ((ACTION_STEP_KINDS as readonly string[]).includes(kind)) {
@@ -81,7 +119,8 @@ function readRun(path: string): Run {
       const points = step.points;
       if (!Array.isArray(points) || points.length === 0 || points.length > MAX_TRACE_POINTS) return fail(`${at}: points is a list of 1 to ${MAX_TRACE_POINTS} objects with kind and start`);
       for (const point of points as unknown[]) {
-        if (!isObject(point) || Object.keys(point).some((key) => !["kind", "start", "end"].includes(key))) return fail(`${at}: a point has kind, start and end, and nothing else`);
+        if (!isObject(point)) return fail(`${at}: a point is an object with kind, start and end`);
+        for (const key of Object.keys(point)) if (!["kind", "start", "end"].includes(key)) fail(`${at}: a point has the field ${key}. ${renamedField(key, ["kind", "start", "end"]) ?? "A point has kind, start and end, and nothing else"}`);
         if (!(TRACE_KINDS as readonly unknown[]).includes(point.kind)) fail(`${at}: a point kind is exec, read or write`);
         if (typeof point.start !== "string" || (point.end !== undefined && typeof point.end !== "string")) fail(`${at}: a point needs start, and end when it is a range, as names or $ addresses`);
       }
@@ -92,6 +131,16 @@ function readRun(path: string): Run {
     if (kind !== "observe") return;
     if (labels.has(name as string)) fail(`${at} needs a new observation name`);
     labels.add(name as string);
+    const itemFields = ["address", "size", "view"];
+    if (Array.isArray(step.memory)) {
+      for (const item of step.memory as unknown[]) {
+        if (!isObject(item)) continue;
+        for (const key of Object.keys(item)) {
+          const renamed = renamedField(key, itemFields);
+          if (renamed !== undefined && !itemFields.includes(key)) fail(`${at}: a memory object has the field ${key}. ${renamed}`);
+        }
+      }
+    }
     const memoryItem = (item: unknown) =>
       typeof item === "string" ||
       (isObject(item) &&
@@ -106,9 +155,35 @@ function readRun(path: string): Run {
     if (step.vicii !== undefined && typeof step.vicii !== "boolean") fail(`${at}: vicii must be true or false`);
     if (step.sprites !== undefined && (!Array.isArray(step.sprites) || !step.sprites.every((sprite) => isInteger(sprite, 0, 7)))) fail(`${at}: sprites is a list of numbers from 0 to 7`);
   });
+  checkFileNames(value.steps as RunStep[], fail);
   return value as unknown as 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. 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", () => readProjectFile(snapshot));
+  }
+  run.steps.forEach((step, index) => {
+    if ("snapshot" in step) named(`step ${index + 1}: snapshot`, () => readProjectFile(step.snapshot));
+  });
+}
+
 /** A trace hit with $ addresses, as a person reads it. */
 function showHit(hit: TraceHit) {
   return { ...hit, pc: formatC64Address(hit.pc), ...(hit.address === undefined ? {} : { address: formatC64Address(hit.address) }) };
@@ -117,6 +192,7 @@ 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(path, run);
   const symbols = namesOf(run.symbols ?? "none");
   const at = (location: string): number => {
     if (location.startsWith("$")) return parseC64Address(location);
@@ -124,6 +200,10 @@ export async function runFile(path: string, out: string): Promise<{ output: Reco
     if (address === undefined) throw new UsageError(`the symbols have no ${location}`);
     return address;
   };
+  // The names of the action steps resolve before the emulator starts.
+  run.steps.forEach((step, index) => {
+    if ((ACTION_STEP_KINDS as readonly string[]).some((kind) => kind in step) && !("observe" in step) && !("trace" in step)) checkStepNames([step as ActionStep], at, `run ${path}`, index + 1);
+  });
   const files: string[] = [];
   const written: Written[] = [];
   const write = (name: string, bytes: Uint8Array) => {
@@ -185,7 +265,7 @@ export async function runFile(path: string, out: string): Promise<{ output: Reco
             // More than one read gives goes to a file: results.json stays small.
             if (size <= MAX_MEMORY_READ) memory[spec.address] = bytes.toString("hex");
             else {
-              const file = `${step.observe}-${spec.address.replace(/^\$/, "")}.bin`;
+              const file = memoryFile(step.observe, spec.address);
               write(file, bytes);
               memory[spec.address] = { file };
             }

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

@@ -7,8 +7,9 @@ import { isRefusal, Refusal } from "#src/errors.ts";
 import { c64AddressOf, formatC64Address, formatSprite, formatVicii, parseC64Address } from "#src/c64.ts";
 import { MAX_BASELINES, MAX_MASK_RECTANGLES, maskCoversFrame, WireFailure } from "#src/host-client/tools.ts";
 import { LOAD_LIMIT_FRAMES, RUN_LIMIT_FRAMES, runProgram } from "#src/host-client/autostart.ts";
-import { ACTION_STEP_KINDS, checkActionStep, checkLocation, isInteger, isObject, runActionStep, type ActionStep, type ActionStepKind, type Location } from "#src/host-client/steps.ts";
+import { ACTION_STEP_KINDS, checkActionStep, checkLocation, isInteger, isObject, refuseOldStep, renamedField, runActionStep, VICE_STEP_KINDS, type ActionStep, type ActionStepKind, type Location } from "#src/host-client/steps.ts";
 import { applyEntryState, parseEntryState } from "#src/host-client/entry-state.ts";
+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 { openForRead } from "#src/knowledge/database.ts";
@@ -90,6 +91,8 @@ export interface ScenarioResult {
 }
 
 const STEP_KINDS = ["reset", "load", "autostart", "snapshot", "normalize", ...ACTION_STEP_KINDS, "observe"];
+/** The step kinds that a scenario runs: press is for the replay core only. */
+const SHOWN_KINDS = ["reset", "load", "autostart", "snapshot", "normalize", ...VICE_STEP_KINDS, "observe"];
 
 /** The keys each kind of step can have. */
 const STEP_KEYS: Record<string, readonly string[]> = {
@@ -128,8 +131,10 @@ export function readScenario(path: string): Scenario {
     if (!isObject(step)) return fail(`${at} must be an object`);
     // An observe step names what it observes with "memory" and "registers" too.
     const kinds = "observe" in step ? ["observe"] : Object.keys(step).filter((key) => STEP_KINDS.includes(key));
-    if (kinds.length !== 1) return fail(`${at} must have exactly one of ${STEP_KINDS.join(", ")}`);
+    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 ${SHOWN_KINDS.join(", ")}`);
     const kind = kinds[0]!;
+    refuseOldStep(kind, step, at, fail);
     const allowed = [...(STEP_KEYS[kind] ?? [kind]), ...(kind === "observe" ? [] : ["side"])];
     for (const key of Object.keys(step)) if (!allowed.includes(key)) fail(`${at} has the key ${key}, which a ${kind} step does not have`);
     if (step.side !== undefined && !(SIDES as unknown[]).includes(step.side)) fail(`${at}: side must be original or rebuild`);
@@ -180,12 +185,15 @@ function checkObserve(step: Record<string, unknown>, at: string, fail: (message:
         checkLocation(item, `${at}: memory`, fail);
         continue;
       }
-      if (!isObject(item) || Object.keys(item).some((key) => !["address", "size", "view", "tolerance", "exclude"].includes(key))) return fail(`${at}: a memory object has address, size, view, tolerance and exclude, and nothing else`);
+      const itemFields = ["address", "size", "view", "tolerance", "exclude"];
+      if (!isObject(item)) return fail(`${at}: memory must be a list of names, $ addresses or objects with address`);
+      for (const key of Object.keys(item)) if (!itemFields.includes(key)) fail(`${at}: a memory object has the field ${key}. ${renamedField(key, itemFields) ?? `It has ${itemFields.join(", ")}, and nothing else`}`);
       if (item.view !== undefined && item.view !== "cpu" && item.view !== "ram") fail(`${at}: memory.view must be cpu or ram`);
       if (item.exclude !== undefined) {
         if (!Array.isArray(item.exclude) || item.exclude.length === 0) fail(`${at}: memory.exclude must be a list of objects with address and reason`);
         for (const excluded of item.exclude as unknown[]) {
-          if (!isObject(excluded) || Object.keys(excluded).some((key) => key !== "address" && key !== "reason")) return fail(`${at}: an exclude has address and reason, and nothing else`);
+          if (!isObject(excluded)) return fail(`${at}: memory.exclude must be a list of objects with address and reason`);
+          for (const key of Object.keys(excluded)) if (key !== "address" && key !== "reason") fail(`${at}: an exclude has the field ${key}. ${renamedField(key, ["address", "reason"]) ?? "It has address and reason, and nothing else"}`);
           checkLocation(excluded.address, `${at}: memory.exclude.address`, fail);
           if (typeof excluded.reason !== "string" || excluded.reason.trim() === "") fail(`${at}: an exclude needs a reason: why this byte may differ`);
         }
@@ -276,6 +284,33 @@ export function namesOf(source: string, kinds: "code" | "all" = "all"): Map<stri
   return names;
 }
 
+/** The remedy for a scenario program that is no PRG. */
+const PROGRAM_REMEDY = "A scenario program is 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 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.
+ */
+export function scenarioNames(scenario: Scenario): Map<Side, Map<string, number>> {
+  const names = new Map<Side, Map<string, number>>();
+  const named = <T>(field: string, read: () => T): T => {
+    try {
+      return read();
+    } catch (error) {
+      if (isRefusal(error)) throw new Refusal(error.code, `${field}: ${error.message}`);
+      throw error;
+    }
+  };
+  for (const side of SIDES) {
+    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);
+  return names;
+}
+
 /** A failure that makes the comparison impossible: the result is INCONCLUSIVE. */
 class Inconclusive extends Error {}
 
@@ -466,12 +501,14 @@ 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 } = {}): Promise<ScenarioResult> {
+export async function runScenario(client: ViceSessionClient, scenario: Scenario, options: { out?: string; names?: Map<Side, Map<string, 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.
+  const names = options.names ?? new Map(SIDES.map((side) => [side, namesOf(scenario[side].symbols)]));
   for (const side of SIDES) {
     try {
-      observed.set(side, await runSide(client, scenario, side, namesOf(scenario[side].symbols), options.out !== undefined));
+      observed.set(side, await runSide(client, scenario, side, names.get(side)!, options.out !== undefined));
     } catch (error) {
       if (error instanceof Inconclusive) return { result: "INCONCLUSIVE", scenario: scenario.name, reason: error.message, checkpoints, differences: [] };
       if (error instanceof WireFailure) {