@henols/c64-re-tools 2.1.0-rc.1 → 2.1.0

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

@@ -3,18 +3,19 @@
 // Observations name semantic symbols that resolve per side, comparisons are
 // explicit, and the result is PASS, FAIL or INCONCLUSIVE.
 
-import { formatC64Address, formatSprite, formatVicii, parseC64Address } from "#src/c64.ts";
+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_KEYS, checkActionStep, checkLocation, isInteger, isObject, runActionStep, type ActionStep, type Location } from "#src/host-client/steps.ts";
-import { readProjectFile, writeProjectFile } from "#src/host-client/transfer.ts";
+import { ACTION_STEP_KINDS, checkActionStep, checkLocation, isInteger, isObject, runActionStep, type ActionStep, type ActionStepKind, type Location } from "#src/host-client/steps.ts";
+import { applyEntryState, parseEntryState } from "#src/host-client/entry-state.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";
-import { listAnalyzerNames, listSymbols } from "#src/knowledge/read.ts";
+import { nameTable } from "#src/knowledge/names.ts";
+import { DEFAULT_SPACE } from "#src/knowledge/schema.ts";
 import { programImage } from "#src/knowledge/program.ts";
 
-export class ScenarioError extends Error {}
-
 export type Side = "original" | "rebuild";
 export const SIDES: Side[] = ["original", "rebuild"];
 
@@ -22,15 +23,15 @@ export const SIDES: Side[] = ["original", "rebuild"];
 export type { Location };
 
 export interface MemoryObservation {
-  at: Location;
-  /** Bytes from `at`; 1 when not given, at most 64 KiB. */
+  address: Location;
+  /** Bytes from `address`; 1 when not given, at most 64 KiB. */
   size?: number;
   /** cpu (the default) reads as the CPU sees memory; ram reads the RAM under the ROMs and the I/O area. */
   view?: "cpu" | "ram";
   /** The largest allowed difference per byte; 0 when not given. */
   tolerance?: number;
   /** Bytes in the range that the comparison leaves out, each with the reason. */
-  exclude?: Array<{ at: Location; reason: string }>;
+  exclude?: Array<{ address: Location; reason: string }>;
 }
 
 export interface ScreenPolicy {
@@ -46,7 +47,7 @@ type StepBody =
   | { autostart: true }
   | { snapshot: string }
   | { normalize: true }
-  | ActionStep
+  | Exclude<ActionStep, { press: string }>
   | { observe: string; memory?: Array<Location | MemoryObservation>; registers?: ObservedRegister[]; screen?: ScreenPolicy; vicii?: boolean; sprites?: number[] };
 
 /** A step; with side, only that side does it. An observe step has no side: it compares both. */
@@ -83,16 +84,15 @@ export interface ScenarioResult {
   checkpoints: string[];
   differences: Difference[];
   /** The bytes that the comparison left out, with their reasons. */
-  excluded?: Array<{ checkpoint: string; at: Location; reason: string }>;
+  excluded?: Array<{ checkpoint: string; address: Location; reason: string }>;
   /** The files that a FAIL wrote with --out. */
-  files?: string[];
+  files?: Written[];
 }
 
-const STEP_KINDS = ["reset", "load", "autostart", "snapshot", "normalize", "write", "registers", "joystick", "type", "frames", "runUntil", "observe"];
+const STEP_KINDS = ["reset", "load", "autostart", "snapshot", "normalize", ...ACTION_STEP_KINDS, "observe"];
 
 /** The keys each kind of step can have. */
 const STEP_KEYS: Record<string, readonly string[]> = {
-  ...ACTION_STEP_KEYS,
   observe: ["observe", "memory", "registers", "screen", "vicii", "sprites"],
 };
 
@@ -100,16 +100,17 @@ const STEP_KEYS: Record<string, readonly string[]> = {
 export const OBSERVED_REGISTERS = ["pc", "a", "x", "y", "sp", "flags"] as const;
 type ObservedRegister = (typeof OBSERVED_REGISTERS)[number];
 
-/** Reads and checks a scenario file. Throws ScenarioError naming the first problem. */
+/** Reads and checks a scenario file. Refuses it with the first problem. */
 export function readScenario(path: string): Scenario {
   let value: unknown;
   try {
     value = JSON.parse(readProjectFile(path).bytes.toString("utf8"));
   } catch (error) {
-    throw new ScenarioError(`cannot read the scenario ${path}: ${(error as Error).message}`);
+    if (isRefusal(error)) throw error;
+    throw new Refusal("invalid-input", `cannot read the scenario ${path}: ${(error as Error).message}`);
   }
   const fail = (message: string): never => {
-    throw new ScenarioError(`scenario ${path}: ${message}`);
+    throw new Refusal("invalid-input", `scenario ${path}: ${message}`);
   };
   if (!isObject(value)) return fail("is not a JSON object");
   const scenario = value as unknown as Scenario;
@@ -132,6 +133,11 @@ export function readScenario(path: string): Scenario {
     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`);
+    if ((ACTION_STEP_KINDS as readonly string[]).includes(kind)) {
+      // The step with its defaults filled in, as the shared schema of the action steps gives it.
+      scenario.steps[index] = { ...checkActionStep(kind as ActionStepKind, { [kind]: step[kind] }, at, fail), ...(step.side === undefined ? {} : { side: step.side as Side }) } as Step;
+      return;
+    }
     checkStep(kind, step, at, fail, scenario.videoStandard ?? "pal");
     if (kind === "observe") {
       if (labels.has(step.observe as string)) fail(`${at} needs a new checkpoint name`);
@@ -160,13 +166,6 @@ function checkStep(kind: string, step: Record<string, unknown>, at: string, fail
     case "normalize":
       if (step.normalize !== true) fail(`${at}: normalize is true: it writes the entry state of the knowledge`);
       return;
-    case "write":
-    case "registers":
-    case "joystick":
-    case "type":
-    case "frames":
-    case "runUntil":
-      return checkActionStep(kind, step, at, fail);
     default:
       checkObserve(step, at, fail, videoStandard);
   }
@@ -175,23 +174,23 @@ function checkStep(kind: string, step: Record<string, unknown>, at: string, fail
 function checkObserve(step: Record<string, unknown>, at: string, fail: (message: string) => never, videoStandard: "pal" | "ntsc"): void {
   if (typeof step.observe !== "string" || step.observe === "") fail(`${at} needs a new checkpoint name`);
   if (step.memory !== undefined) {
-    if (!Array.isArray(step.memory) || step.memory.length === 0) fail(`${at}: memory must be a list of names, $ addresses or objects with at`);
+    if (!Array.isArray(step.memory) || step.memory.length === 0) fail(`${at}: memory must be a list of names, $ addresses or objects with address`);
     for (const item of step.memory as unknown[]) {
       if (typeof item === "string") {
         checkLocation(item, `${at}: memory`, fail);
         continue;
       }
-      if (!isObject(item) || Object.keys(item).some((key) => !["at", "size", "view", "tolerance", "exclude"].includes(key))) return fail(`${at}: a memory object has at, size, view, tolerance and exclude, and nothing else`);
+      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`);
       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 at and reason`);
+        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 !== "at" && key !== "reason")) return fail(`${at}: an exclude has at and reason, and nothing else`);
-          checkLocation(excluded.at, `${at}: memory.exclude.at`, fail);
+          if (!isObject(excluded) || Object.keys(excluded).some((key) => key !== "address" && key !== "reason")) return fail(`${at}: an exclude 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`);
         }
       }
-      checkLocation(item.at, `${at}: memory.at`, fail);
+      checkLocation(item.address, `${at}: memory.address`, fail);
       if (item.size !== undefined && !isInteger(item.size, 1, 0x10000)) fail(`${at}: memory.size must be a number from 1 to 65536`);
       if (item.tolerance !== undefined && !isInteger(item.tolerance, 0, 0xff)) fail(`${at}: memory.tolerance must be a number from 0 to 255`);
     }
@@ -233,46 +232,48 @@ function checkObserve(step: Record<string, unknown>, at: string, fail: (message:
   }
 }
 
-/** Name → address for one side. */
-export function loadSymbols(subject: Subject): Map<string, number> {
-  const symbols = new Map<string, number>();
-  if (subject.symbols === "none") return symbols;
-  if (subject.symbols === "knowledge") {
+/**
+ * Name → address from a source of names: none; the knowledge (its symbols and
+ * the analyzer names that only one address has); the c64-assembler output; or
+ * a JSON map of name to $ address. With kinds "code", only the names that move
+ * with the code: labels and routines of the knowledge, and the labels of the
+ * assembler output. With "all", also the data names and the assembler
+ * constants of four hex digits: RAM variables such as "counter = $c100" lie
+ * outside the program, so the assembler reports them as constants.
+ */
+export function namesOf(source: string, kinds: "code" | "all" = "all"): Map<string, number> {
+  if (source === "none") return new Map();
+  if (source === "knowledge") {
     const db = openForRead();
-    for (const symbol of listSymbols(db)) symbols.set(symbol.name, symbol.address);
-    // An analyzer name gives an address too, when no symbol has the name and only one analyzer gives it.
-    const second = new Map<string, number[]>();
-    for (const row of listAnalyzerNames(db)) second.set(row.name, [...(second.get(row.name) ?? []), row.address]);
-    for (const [name, addresses] of second) if (!symbols.has(name) && new Set(addresses).size === 1) symbols.set(name, addresses[0]!);
-    db?.close();
-    return symbols;
+    try {
+      return nameTable(db, DEFAULT_SPACE, kinds === "code" ? ["label", "routine"] : undefined);
+    } finally {
+      db?.close();
+    }
   }
   let value: unknown;
   try {
-    value = JSON.parse(readProjectFile(subject.symbols).bytes.toString("utf8"));
+    value = JSON.parse(readProjectFile(source).bytes.toString("utf8"));
   } catch (error) {
-    throw new ScenarioError(`cannot read the symbols ${subject.symbols}: ${(error as Error).message}`);
+    if (isRefusal(error)) throw error;
+    throw new Refusal("invalid-input", `cannot read the symbols ${source}: ${(error as Error).message}`);
   }
-  // c64-assembler output, or a plain name → "$xxxx" map. A constant in the
-  // assembler output counts too: RAM variables such as "counter = $c100" lie
-  // outside the program, so the assembler reports them as constants.
   const assembled = (value as { symbols?: Array<{ name: string; address?: string; value?: string }> }).symbols;
   const entries: Array<[string, unknown]> = Array.isArray(assembled)
     ? assembled.flatMap((symbol): Array<[string, unknown]> => {
         if (symbol.address !== undefined) return [[symbol.name, symbol.address]];
         // A constant above $ffff has more digits and is no address.
-        if (typeof symbol.value === "string" && /^\$[0-9a-f]{4}$/.test(symbol.value)) return [[symbol.name, symbol.value]];
+        if (kinds === "all" && typeof symbol.value === "string" && /^\$[0-9a-f]{4}$/.test(symbol.value)) return [[symbol.name, symbol.value]];
         return [];
       })
     : Object.entries(value as Record<string, unknown>);
+  const names = new Map<string, number>();
   for (const [name, address] of entries) {
-    try {
-      symbols.set(name, parseC64Address(String(address)));
-    } catch {
-      throw new ScenarioError(`the symbol ${name} in ${subject.symbols} has no $xxxx address`);
-    }
+    const at = typeof address === "string" ? c64AddressOf(address) : undefined;
+    if (at === undefined) throw new Refusal("invalid-input", `the symbol ${name} in ${source} has no $ address`);
+    names.set(name, at);
   }
-  return symbols;
+  return names;
 }
 
 /** A failure that makes the comparison impossible: the result is INCONCLUSIVE. */
@@ -283,7 +284,7 @@ export function resolve(location: Location, symbols: Map<string, number>, side:
     try {
       return parseC64Address(location);
     } catch {
-      throw new ScenarioError(`${location} is not $ followed by four hex digits`);
+      throw new Refusal("invalid-input", `${location} is not $ and 1 to 4 hex digits`);
     }
   }
   const address = symbols.get(location);
@@ -292,7 +293,7 @@ export function resolve(location: Location, symbols: Map<string, number>, side:
 }
 
 interface Observation {
-  memory: Array<{ label: string; address: number; bytes: number[]; tolerance: number; excluded: Array<{ offset: number; at: Location; reason: string }> }>;
+  memory: Array<{ label: string; address: number; bytes: number[]; tolerance: number; excluded: Array<{ offset: number; address: Location; reason: string }> }>;
   registers: Partial<Record<ObservedRegister, unknown>>;
   screen?: { match: boolean; mismatchingPixels: number; comparedPixels: number; mismatchRatio: number; bounds?: unknown };
   vicii?: unknown;
@@ -305,22 +306,14 @@ interface Observation {
 /** Writes pages 0-3 and $00/$01 from the entry state of the knowledge: both sides then start from the same RAM. */
 async function normalize(client: ViceSessionClient): Promise<void> {
   const db = openForRead();
-  let state: { pages?: Record<string, string>; cpuPort?: Record<string, number> } | undefined;
+  let state: unknown;
   try {
-    state = programImage(db)?.state as typeof state;
+    state = programImage(db)?.state;
   } finally {
     db?.close();
   }
-  if (state === undefined) throw new ScenarioError("normalize needs the entry state of a c64-unpacker capture in the knowledge: put the capture in with knowledge.ts image <image.json> of the c64-knowledge skill");
-  const pages = ["$0000", "$0100", "$0200", "$0300"].map((page) => state.pages?.[page]);
-  const port = [state.cpuPort?.$00, state.cpuPort?.$01];
-  if (pages.some((page) => typeof page !== "string" || !/^[0-9a-f]{512}$/.test(page)) || port.some((value) => !isInteger(value, 0, 0xff))) {
-    throw new ScenarioError("the entry state of the knowledge is not the entry state of a c64-unpacker capture: it needs pages $0000 to $0300 and cpuPort $00 and $01");
-  }
-  if ((await client.status()).state === "running") await client.execution({ action: "pause", space: "c64" });
-  // Pages 0 to 3 in RAM from $0002, then the CPU port: the port bits switch what the CPU sees.
-  await client.memoryWrite({ address: 0x0002, data: pages.join("").slice(4), space: "c64", view: "ram" });
-  await client.memoryWrite({ address: 0x0000, data: Buffer.from(port as number[]).toString("hex"), space: "c64", view: "cpu" });
+  if (state === undefined) throw new Refusal("invalid-input", "normalize needs the entry state of a c64-unpacker capture in the knowledge: put the capture in with knowledge.ts image <image.json> of the c64-knowledge skill");
+  await applyEntryState(client, parseEntryState(state, "the entry state of the knowledge"), { registers: false });
 }
 
 /**
@@ -355,16 +348,16 @@ async function runSide(client: ViceSessionClient, scenario: Scenario, side: Side
       checkpoint++;
       const observation: Observation = { memory: [], registers: {} };
       for (const item of step.memory ?? []) {
-        const spec: MemoryObservation = typeof item === "string" ? { at: item } : item;
-        const address = at(spec.at);
+        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.at) - address;
-          if (offset < 0 || offset >= size) throw new ScenarioError(`the exclude ${exclude.at} lies outside the observed ${spec.at} (${size} bytes)`);
-          return { offset, at: exclude.at, reason: exclude.reason };
+          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.at} (${size} bytes)` : spec.at, address, bytes: [...Buffer.from(read.data, "hex")], tolerance: spec.tolerance ?? 0, excluded });
+        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");
@@ -407,7 +400,7 @@ async function runSide(client: ViceSessionClient, scenario: Scenario, side: Side
       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.timeoutFrames} frames (it stopped by ${notReached.stopReason} at ${formatC64Address(notReached.pc)})`);
+        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)})`);
       }
     }
   }
@@ -443,11 +436,10 @@ 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.
  */
-function writeFailFiles(out: string, original: Map<string, Observation>, rebuild: Map<string, Observation>, differences: Difference[]): string[] {
-  const files: string[] = [];
+function writeFailFiles(out: string, original: Map<string, Observation>, rebuild: Map<string, Observation>, differences: Difference[]): Written[] {
+  const files: Written[] = [];
   const write = (name: string, bytes: Uint8Array) => {
-    writeProjectFile(`${out}/${name}`, bytes, { what: "--out" });
-    files.push(name);
+    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");
@@ -479,7 +471,7 @@ export async function runScenario(client: ViceSessionClient, scenario: Scenario,
   const observed = new Map<Side, Map<string, Observation>>();
   for (const side of SIDES) {
     try {
-      observed.set(side, await runSide(client, scenario, side, loadSymbols(scenario[side]), options.out !== undefined));
+      observed.set(side, await runSide(client, scenario, side, namesOf(scenario[side].symbols), options.out !== undefined));
     } catch (error) {
       if (error instanceof Inconclusive) return { result: "INCONCLUSIVE", scenario: scenario.name, reason: error.message, checkpoints, differences: [] };
       if (error instanceof WireFailure) {
@@ -491,7 +483,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 excluded = [...original].flatMap(([checkpoint, observation]) => observation.memory.flatMap((item) => item.excluded.map((excluded) => ({ checkpoint, at: excluded.at, reason: excluded.reason }))));
+  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 {
     result: differences.length === 0 ? "PASS" : "FAIL",

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

@@ -0,0 +1,189 @@
+// The c64-testing script. test runs a scenario on the original and the
+// rebuild in one emulator; run runs steps on one side and writes what they
+// ask for; record and replay play a session in the replay core (c64run) and
+// compare the rebuild with it; diff shows what changed between two states;
+// checklist gives the Markdown list for a human tester.
+
+import { COVERAGE } from "#src/c64.ts";
+import { WireFailure } from "#src/host-client/tools.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";
+import { localToolContext } from "#src/native/local.ts";
+import { Workspace } from "#src/native/staging.ts";
+import { knowledgeNames } from "#src/knowledge/names.ts";
+import { OPTIONS, runScript, UsageError, type Call, type CommandSpec } from "#src/script.ts";
+import { diffFiles } from "./lib/diff-files.ts";
+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";
+
+/** The default port of the --play page: next to the Host Runtime's 6464. */
+const DEFAULT_HTTP_PORT = 6465;
+
+/** Behavior that only a person can judge. */
+const ALWAYS = [
+  "The controls respond as fast as in the original.",
+  "The animation is smooth and has no glitches.",
+  "The music and the sound effects sound the same as in the original.",
+  "The game flow and the level changes work from start to end.",
+  "Nothing unexpected happens outside the tested scenarios.",
+];
+
+async function test(call: Call): Promise<ScenarioResult> {
+  const scenario = readScenario(call.subject(0));
+  const out = call.string("out");
+  let client: ViceSessionClient;
+  try {
+    client = await ViceSessionClient.open({ videoStandard: scenario.videoStandard ?? "pal" });
+  } catch (error) {
+    if (!(error instanceof WireFailure)) throw error;
+    return { result: "INCONCLUSIVE", scenario: scenario.name, reason: `no emulator: ${error.message}`, checkpoints: [], differences: [] };
+  }
+  try {
+    return await runScenario(client, scenario, out === undefined ? {} : { out });
+  } finally {
+    await client.close();
+  }
+}
+
+async function recordCommand(call: Call): Promise<Record<string, unknown>> {
+  const playing = call.flag("play");
+  if (!playing && (call.count("joystick") !== undefined || call.count("http-port") !== undefined)) throw new UsageError("--joystick and --http-port are for --play");
+  const joystick = (call.count("joystick") ?? 2) as 1 | 2;
+  const httpPort = call.count("http-port") ?? DEFAULT_HTTP_PORT;
+  const out = call.string("out")!;
+  const file = readRecordFile(call.subject(0));
+  const context = localToolContext();
+  const core = await C64RunSession.open(context);
+  const workspace = Workspace.create(context.supervisor, "c64-re-tools-record-");
+  try {
+    const person = playing
+      ? (session: C64RunSession, restore: () => Promise<string | undefined>) => {
+          const ready = (url: string) =>
+            process.stderr.write("Open " + url + ". The start screen is frozen. Enter or Start begins the play, F12 or End saves the recording, F11 or Cancel ends without one. F9 changes the joystick port.\n");
+          return play(session, { httpPort, joystick, ready, restore });
+        }
+      : undefined;
+    const outcome = await record(core, file, workspace, person);
+    const summary = {
+      name: file.name,
+      frames: Math.round(outcome.recording.ticks / PAL_FRAME_CYCLES),
+      inputSites: outcome.recording.sites.length,
+      events: outcome.recording.events.length,
+      // The instructions in the coverage map: 0 when the program never read its input from RAM.
+      executed: outcome.coverage.reduce((count, byte) => count + ((byte & COVERAGE.ramExecute) === 0 ? 0 : 1), 0),
+    };
+    if (outcome.reason !== undefined) return { result: "FAIL", recorded: false, reason: outcome.reason, ...summary };
+    const files = [
+      writeReported(`${out}/${RECORDING_FILES.recording}`, `${JSON.stringify(outcome.recording, null, 2)}\n`, { what: "--out" }),
+      writeReported(`${out}/${RECORDING_FILES.reads}`, outcome.reads, { what: "--out" }),
+      writeReported(`${out}/${RECORDING_FILES.coverage}`, outcome.coverage, { what: "--out" }),
+    ];
+    return { result: "PASS", recorded: true, out, ...summary, files };
+  } finally {
+    await core.close();
+    workspace.remove();
+  }
+}
+
+function checklist(call: Call): { text: string } {
+  const lines = ["# Playtest checklist", ""];
+  for (const path of call.subjects) {
+    const scenario: Scenario = readScenario(path);
+    lines.push(`## ${scenario.name}`, "");
+    for (const step of scenario.steps) if ("observe" in step) lines.push(`- [ ] At "${step.observe}", the rebuild looks and behaves as the original.`);
+    lines.push("");
+  }
+  lines.push("## Application", "");
+  for (const item of call.strings("item")) lines.push(`- [ ] ${item}`);
+  for (const item of ALWAYS) lines.push(`- [ ] ${item}`);
+  return { text: `${lines.join("\n")}\n` };
+}
+
+const STATE_ITEM = "a name or a $ address, with :size for more than one byte, for example room:2";
+
+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" } },
+    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" } },
+    run: async (call) => {
+      const { output, failed } = await runFile(call.subject(0), call.string("out")!);
+      return { result: failed ? "FAIL" : "PASS", ...output };
+    },
+  },
+  {
+    name: "record",
+    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>" },
+      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})` },
+    },
+    run: recordCommand,
+  },
+  {
+    name: "replay",
+    summary: "Replays a recording on the original, which must end with the recorded state, and with --rebuild on the rebuild, which must have the state of the original at each checkpoint. result is PASS, FAIL or INCONCLUSIVE.",
+    subjects: [{ name: "<recording>", help: "a folder that record wrote, relative to the project folder" }],
+    options: {
+      checkpoint: { kind: "text", value: "<routine>", help: "the name or $ address of a routine: each entry is a checkpoint. Without it, the comparison of the record file" },
+      state: { kind: "text", value: "<item>", multiple: true, help: `the state to compare at each checkpoint: ${STATE_ITEM}` },
+      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" },
+    },
+    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) => {
+      const [checkpoint, rebuild, symbols, out] = [call.string("checkpoint"), call.string("rebuild"), call.string("symbols"), call.string("out")];
+      return replay({ folder: call.subject(0), state: call.strings("state"), pin: call.strings("pin"), ...(checkpoint === undefined ? {} : { checkpoint }), ...(rebuild === undefined ? {} : { rebuild }), ...(symbols === undefined ? {} : { symbols }), ...(out === undefined ? {} : { out }) });
+    },
+  },
+  {
+    name: "diff",
+    summary: "What changed between two machine states of one kind: two snapshot files (snapshot.vsf), two memory files of runs (memory.bin), or two observations of runs (results.json:<name>).",
+    subjects: [
+      { name: "<a>", help: "the first state, relative to the project folder" },
+      { name: "<b>", help: "the second state" },
+    ],
+    options: {
+      gap: { kind: "count", value: "<n>", min: 0, max: 0xffff, default: 0, help: "join changed ranges across at most n equal bytes (default 0)" },
+      "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" },
+    },
+    run: (call) => {
+      const [address, out] = [call.address("address"), call.string("out")];
+      return diffFiles(call.subject(0), call.subject(1), { gap: call.count("gap")!, max: call.count("max-listed")!, ntsc: call.flag("ntsc"), ...(address === undefined ? {} : { at: address }), ...(out === undefined ? {} : { out }) });
+    },
+  },
+  {
+    name: "checklist",
+    summary: "The playtest checklist for a human tester as Markdown in text: the checkpoints of the scenarios, and the behavior that automated scenarios cannot check.",
+    subjects: [{ name: "<scenario.json>", help: "a scenario file", list: true }],
+    options: { item: { kind: "text", value: "<text>", multiple: true, help: "an application-specific line" } },
+    run: checklist,
+  },
+];
+
+await runScript({
+  name: "testing",
+  summary: "Tests a rebuild against the original: scenarios in VICE, runs, recorded play sessions in the replay core, state differences, and a checklist for a human tester.",
+  names: knowledgeNames,
+  commands: COMMANDS,
+});