@henols/c64-re-tools 2.1.0-rc.2 → 2.1.1

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;
@@ -153,13 +153,20 @@ export function parseStateItem(text: string): StateItem {
   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";
@@ -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

@@ -6,7 +6,8 @@
 import { formatC64Address, formatSprite, formatVicii, parseC64Address } from "#src/c64.ts";
 import { runProgram } from "#src/host-client/autostart.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, 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 +36,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 +95,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 +118,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 +130,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 +154,20 @@ 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. */
+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);
+}
+
 /** 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 +176,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(run);
   const symbols = namesOf(run.symbols ?? "none");
   const at = (location: string): number => {
     if (location.startsWith("$")) return parseC64Address(location);
@@ -185,7 +245,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) {

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

@@ -5,7 +5,9 @@
 // checklist gives the Markdown list for a human tester.
 
 import { COVERAGE } from "#src/c64.ts";
+import { isRefusal, Refusal } from "#src/errors.ts";
 import { WireFailure } from "#src/host-client/tools.ts";
+import { readPrg } from "#src/host-client/image.ts";
 import { writeReported } from "#src/host-client/transfer.ts";
 import { ViceSessionClient } from "#src/host-client/vice-session.ts";
 import { C64RunSession, PAL_FRAME_CYCLES } from "#src/native/c64run.ts";
@@ -18,7 +20,7 @@ import { play } from "./lib/play.ts";
 import { readRecordFile, record, RECORDING_FILES } from "./lib/recording.ts";
 import { replay } from "./lib/replay.ts";
 import { runFile } from "./lib/runs.ts";
-import { readScenario, runScenario, type Scenario, type ScenarioResult } from "./lib/scenario.ts";
+import { namesOf, readScenario, runScenario, scenarioNames, type Scenario, type ScenarioResult } from "./lib/scenario.ts";
 
 /** The default port of the --play page: next to the Host Runtime's 6464. */
 const DEFAULT_HTTP_PORT = 6465;
@@ -35,6 +37,8 @@ const ALWAYS = [
 async function test(call: Call): Promise<ScenarioResult> {
   const scenario = readScenario(call.subject(0));
   const out = call.string("out");
+  // Every file of the scenario is checked before the emulator starts.
+  const names = scenarioNames(scenario);
   let client: ViceSessionClient;
   try {
     client = await ViceSessionClient.open({ videoStandard: scenario.videoStandard ?? "pal" });
@@ -43,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, out === undefined ? {} : { out });
+    return await runScenario(client, scenario, { names, ...(out === undefined ? {} : { out }) });
   } finally {
     await client.close();
   }
@@ -56,6 +60,15 @@ async function recordCommand(call: Call): Promise<Record<string, unknown>> {
   const httpPort = call.count("http-port") ?? DEFAULT_HTTP_PORT;
   const out = call.string("out")!;
   const file = readRecordFile(call.subject(0));
+  // The program and the symbols are checked before the replay core starts.
+  for (const [field, check] of [["program", () => readPrg(file.program)], ["symbols", () => namesOf(file.symbols)]] as const) {
+    try {
+      check();
+    } catch (error) {
+      if (isRefusal(error)) throw new Refusal(error.code, `record file ${call.subject(0)}: ${field}: ${error.message}`);
+      throw error;
+    }
+  }
   const context = localToolContext();
   const core = await C64RunSession.open(context);
   const workspace = Workspace.create(context.supervisor, "c64-re-tools-record-");

package/skills/c64-unpacker/SKILL.md

@@ -13,7 +13,7 @@ This skill does not change project knowledge.
 
 ## Inputs
 
-- The program: a PRG file, relative to the project folder.
+- The program: a PRG file, relative to the project folder. `inspect`, `trace`, `stages` and `capture` refuse a disk, tape or cartridge image. For such an image, use `loads`, or get the PRG with `disk.ts read` of the c64-disk skill.
 - For a capture: the address where the unpacked program starts, and the directory for the result.
 
 ## Tools / execution path
@@ -32,17 +32,18 @@ node <skill>/scripts/unpacker.ts loads original/game.d64 --steps .c64-re-tools/l
 |---|---|
 | `--until '$c000'` | `capture`: the address where the unpacked program starts. The capture stops there after the steps. To capture a later arrival at the address, add a `runUntil` step to an address after the first arrival. |
 | `--out .c64-re-tools/local/capture` | `capture` and `loads`: the folder for the result, relative to the project folder. |
-| `--range '$c000-$cfff'` | `capture` only: write this range as the one segment. Without it, the segments are the blocks that the stages wrote. |
-| `--exclude '$a000-$a9ff'` | `capture` only: remove this range from the segments. You can give it more than once. `image.json` lists the ranges in `excluded`. The entry must not be in the range. |
+| `--range '$c000-$cfff'` | `capture` only: write this range as the one segment. Without it, the segments are the blocks that the stages wrote. The range must hold the `--until` address. |
+| `--exclude '$a000-$a9ff'` | `capture` only: remove this range from the segments. You can give it more than once. `image.json` lists the ranges in `excluded`. The range must not hold the `--until` address. |
 | `--timeout-frames 3000` | `capture` only: how many frames the program can run before the capture stops (default 3000). |
 | `--frames 3000` | `trace` and `stages`: how many frames the program runs (default 3000). |
 | `--entry '$c000'` | `trace`, `stages` and `capture`: start the program at this address. Without it, the script types RUN. A file that is not a BASIC program at `$0801` needs it. |
 | `--steps input.json` | Input for the program, right after it starts: a JSON list of steps. Use it when an intro waits for a key or a menu waits for a choice. |
+| `--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). |
 
-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.
+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:
 
@@ -59,6 +60,8 @@ A steps file is a JSON list of steps. Each step has the input of the MCP tool of
 
 A program that reads the keyboard matrix does not see the keys of a `type` step. These scripts refuse a `press` step. A wait for any key that reads all keyboard columns can end without a key.
 
+The scripts refuse a step in the form of version 2.0, for example `{ "runUntil": { "at": "main_loop" }, "timeoutFrames": 300 }`. The message names the old field and gives the step to write.
+
 ### Calling the script
 
 - Call a script as `node <skill>/scripts/<script>.ts <command> [subjects] [options]`. The command comes first.
@@ -92,7 +95,7 @@ A program that reads the keyboard matrix does not see the keys of a `type` step.
    - `strings`: readable text near the start of the code.
    - `start`: the code at the SYS address. `jumpsOutside` and `writesOutside` give an address outside the loaded program, where the code jumps or writes.
    - `decodeLoops`: EOR instructions in loops that store with an index. This is usually decryption or decoding.
-2. Run `trace`. It gives the evidence from the run. Read `packing`:
+2. Run `trace`. It gives the evidence from the run. `writtenThenExecuted` lists the ranges that the program wrote and then executed. Read `packing`:
    - `likely`: the program wrote code and then executed it. It unpacked, decrypted or moved code. `runningRange` is the written code that runs at the end of the trace. When the trace ends in ROM code, for example in an interrupt, it is the written code that runs next. Its `start` is code that runs after the unpacking. It is not always the entry point of the program. When no written code runs in 50 more frames, the result has no `runningRange` and no `suggestedUntil`.
    - `unclear`: the program executed a small quantity of code that it wrote. This can be code that changes itself.
    - `unlikely`: the program executed no code that it wrote. If the program waits for a key or a joystick, it can move code after that input. Then use the c64-emulator skill.
@@ -152,6 +155,7 @@ For `loads`: `captures`, with the name, the PC, the segments, the files and the
 ## Failure and conflicts
 
 - `traced: false` or `followed: false`: the emulator did not load the program into memory in the time limit. The reason gives the load address. Make sure that the file is a PRG that the C64 can load.
+- `traced: false` or `followed: false` with `stopReason`: the CPU stopped before the frames ran, for example at a JAM instruction. `pc` gives the address. Make sure that `--entry` is the start of the code that the file holds at that time, and that the steps are correct.
 - `captured: false`: the program did not get to the address in the time limit. The reason tells where it stopped. Find a better address with the c64-emulator skill, or give more frames. If it stopped in a key wait, give `--steps` with a `type` step.
 - A step did not reach its target: the reason names the step. Change the step or give it more frames.
 - `loaded: false` and no capture has a segment: the program did not load a part, or it did not start. `keyWait: true` on a capture tells that the C64 waited at READY. or at an INPUT statement. For a tape image, read `emulatorFlaw`. A known VICE flaw can stop a tape load. Tell the user to install the latest VICE.

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

@@ -1,7 +1,7 @@
 // Local evidence of packing for the c64-unpacker script: where BASIC hands
 // over and how compressed the bytes look. It never names a packer.
 
-import { basicLineText, findHandoffs, formatC64Address, instructionLength, parseTokenized } from "#src/c64.ts";
+import { basicLineText, findHandoffs, formatC64Address, instructionLength, parseTokenized, prgRange } from "#src/c64.ts";
 import { Refusal } from "#src/errors.ts";
 
 /** A 256-byte block above this many bits per byte looks compressed. */
@@ -111,9 +111,8 @@ function startSignals(program: Uint8Array, load: number, end: number, sys: numbe
 }
 
 export function inspect(program: Uint8Array): PackingEvidence {
-  if (program.length < 3) throw new Refusal("invalid-input", "the file is too short for a PRG");
-  const load = program[0]! | (program[1]! << 8);
-  const end = load + program.length - 3;
+  // A PRG ends at $ffff or before: a longer file (a disk image) is refused.
+  const { start: load, end } = prgRange(program);
   const basic = basicStart(program);
   const stub = basic?.sys;
   // Without BASIC, all bytes count; with it, only the bytes after the BASIC text.
@@ -132,7 +131,7 @@ export function inspect(program: Uint8Array): PackingEvidence {
   const packing = byEntropy === "unlikely" && startMoves ? "unclear" : byEntropy;
   const sorted = [...blocks].sort((a, b) => a - b);
   return {
-    loadRange: { start: formatC64Address(load), end: formatC64Address(Math.min(end, 0xffff)) },
+    loadRange: { start: formatC64Address(load), end: formatC64Address(end) },
     bytes: program.length - 2,
     basicStart: stub === undefined ? null : stub.address === undefined ? { line: stub.line, sys: null, expression: stub.expression! } : { line: stub.line, sys: formatC64Address(stub.address) },
     entropy: {

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

@@ -7,7 +7,7 @@
 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, type ActionStep, type ActionStepKind } from "#src/host-client/steps.ts";
+import { ACTION_STEP_KINDS, checkActionStep, 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";
@@ -54,7 +54,8 @@ export function readLoadSteps(path: string): LoadStep[] {
       return;
     }
     const kinds = Object.keys(step).filter((key) => (ACTION_STEP_KINDS as readonly string[]).includes(key));
-    if (kinds.length !== 1) return fail(`${at} must have exactly one of ${[...ACTION_STEP_KINDS, "capture"].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, "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);
   });