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

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

@@ -11,14 +11,14 @@
 import { createHash } from "node:crypto";
 import { readFileSync, writeFileSync } from "node:fs";
 
+import { isRefusal, Refusal } from "#src/errors.ts";
 import { formatC64Address, parseC64Address } from "#src/c64.ts";
-import { checkActionStep, isInteger, isObject, type ActionStep, type Location } from "#src/host-client/steps.ts";
-import { readProjectFile } from "#src/host-client/transfer.ts";
-import { openForRead } from "#src/knowledge/database.ts";
-import { listSymbols } from "#src/knowledge/read.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 { 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";
-import { loadSymbols, ScenarioError, type Outcome } from "./scenario.ts";
+import { namesOf, type Outcome } from "./scenario.ts";
 
 export const RECORDING_FORMAT = 1;
 /**
@@ -34,9 +34,7 @@ export const DEFAULT_INPUTS = ["$dc00", "$dc01", "$d419", "$d41a", "$d41b", "$d4
 export function inputsArgument(inputs: string[]): string {
   return inputs.map((input) => input.replace(/\$/g, "")).join(",");
 }
-/** Frames from power-on to READY, before the program goes into memory. */
-export const BOOT_FRAMES = 150;
-/** Frames that a typed key is held, and then released. */
+/** Frames that a pressed key is held, and then released. */
 const KEY_FRAMES = 3;
 const MAX_STATE_ITEMS = 16;
 const MAX_STATE_BYTES = 4096;
@@ -44,7 +42,7 @@ const MAX_STATE_BYTES = 4096;
 const REBUILD_TIME_FACTOR = 2;
 
 export interface StateItem {
-  at: Location;
+  address: Location;
   size: number;
 }
 
@@ -73,10 +71,16 @@ export interface Comparison {
   pin?: StateItem[];
 }
 
-/** A step that is not input: it runs at the same point of the program on each replay. */
+/** RESTORE: it starts an NMI and is no read, so the recording keeps it as an event. */
+export interface RestoreAction {
+  restore: true;
+}
+
+/** A step that is not input, or a RESTORE of the play: it runs at the same point of the program on each replay. */
 export interface RecordedEvent {
-  step: number;
-  action: ActionStep;
+  /** The step of the record file; none for a RESTORE of the play. */
+  step?: number;
+  action: ActionStep | RestoreAction;
   /**
    * The point: the n-th read at the busiest program site, or a tick when no
    * program site has read yet. An event that follows another event directly
@@ -111,13 +115,16 @@ export interface Recording {
 
 export const RECORDING_FILES = { recording: "recording.json", reads: "reads.txt", coverage: "coverage.bin" } as const;
 
-const STEP_KINDS = ["write", "registers", "joystick", "type", "frames", "runUntil"];
-/** Steps that are input or time: a replay does not do them again. */
-const INPUT_KINDS = new Set(["joystick", "type", "frames"]);
+/** Steps that are input or time: the replay gives the program the reads that they caused, and does not do them again. */
+const INPUT_KINDS = new Set(["joystick", "press", "frames"]);
+/** The KERNAL keyboard queue: $0277, its length in $c6, at most 10 keys. */
+const QUEUE = 0x0277;
+const QUEUE_LENGTH = 0x00c6;
+const QUEUE_SIZE = 10;
 
 const hex = (address: number) => address.toString(16).padStart(4, "0");
 
-/** The keys of the replay core for the characters that a type step can have. */
+/** The keys of the replay core for the characters that a press step can have. */
 const KEY_CODES = new Map<string, number>([
   ...[..."ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 +-.:@,*;=/!\"#$%&'()[]<>?"].map((character) => [character, character.charCodeAt(0)] as [string, number]),
   ["\n", 0x0d],
@@ -127,7 +134,7 @@ const KEY_CODES = new Map<string, number>([
 export function keyCodes(text: string): number[] {
   return [...text.replace(/\r\n?/g, "\n")].map((character) => {
     const code = KEY_CODES.get(character.toUpperCase());
-    if (code === undefined) throw new ScenarioError(`type cannot press ${JSON.stringify(character)} on the keyboard of the replay core`);
+    if (code === undefined) throw new Refusal("invalid-input", `press cannot press ${JSON.stringify(character)} on the keyboard of the replay core`);
     return code;
   });
 }
@@ -142,18 +149,18 @@ export function joystickMask(direction: Extract<ActionStep, { joystick: unknown
 export function parseStateItem(text: string): StateItem {
   const match = /^([^:]+)(?::(\d+))?$/.exec(text);
   const size = Number(match?.[2] ?? 1);
-  if (match === null || !isInteger(size, 1, MAX_STATE_BYTES)) throw new ScenarioError(`--state ${text}: give a name or a $ address, with :size from 1 to ${MAX_STATE_BYTES}`);
-  return { at: match[1]!, size };
+  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}`);
+  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`);
   return (value as unknown[]).map((item, index) => {
-    const spec = typeof item === "string" ? { at: item } : item;
-    if (!isObject(spec) || typeof spec.at !== "string" || Object.keys(spec).some((key) => key !== "at" && key !== "size")) fail(`state item ${index + 1} must be a name, a $ address, or { at, size }`);
+    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 }`);
     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}`);
-    return { at: (spec as { at: string }).at, size: size as number };
+    return { address: (spec as { address: string }).address, size: size as number };
   });
 }
 
@@ -166,15 +173,16 @@ function checkInputs(value: unknown, fail: (message: string) => never): string[]
   return (value as string[]).map((input) => input.toLowerCase());
 }
 
-/** Reads and checks a record file. Throws ScenarioError naming the first problem. */
+/** Reads and checks a record file. Refuses it with the first problem. */
 export function readRecordFile(path: string): RecordFile {
   const fail = (message: string): never => {
-    throw new ScenarioError(`record file ${path}: ${message}`);
+    throw new Refusal("invalid-input", `record file ${path}: ${message}`);
   };
   let value: unknown;
   try {
     value = JSON.parse(readProjectFile(path).bytes.toString("utf8"));
   } catch (error) {
+    if (isRefusal(error)) throw error;
     return fail((error as Error).message);
   }
   if (!isObject(value)) return fail("it must be a JSON object");
@@ -191,16 +199,11 @@ export function readRecordFile(path: string): RecordFile {
   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");
-  (value.steps as unknown[]).forEach((step, index) => {
+  const steps = (value.steps as unknown[]).map((raw, index) => {
     const at = `step ${index + 1}`;
-    if (!isObject(step)) return fail(`${at} must be an object`);
-    const kinds = Object.keys(step).filter((key) => STEP_KINDS.includes(key));
-    if (kinds.length !== 1) return fail(`${at} must have exactly one of ${STEP_KINDS.join(", ")}`);
-    const kind = kinds[0]!;
-    for (const key of Object.keys(step)) if (key !== kind && !(kind === "runUntil" && key === "timeoutFrames")) fail(`${at} has the key ${key}, which a ${kind} step does not have`);
-    checkActionStep(kind, step, at, fail);
-    if (kind === "runUntil" && "raster" in (step.runUntil as object)) fail(`${at}: the replay core has no runUntil raster; use at or memory`);
-    if (kind === "type") keyCodes(step.type as string);
+    const step = checkActionStep(stepKind(raw, ACTION_STEP_KINDS, at, fail), raw as Record<string, unknown>, at, fail, { press: true });
+    checkCoreStep(step, at, fail);
+    return step;
   });
   return {
     name: value.name as string,
@@ -209,10 +212,26 @@ export function readRecordFile(path: string): RecordFile {
     load: value.load === true,
     ...(compare === undefined ? {} : { compare }),
     inputs,
-    steps: value.steps as ActionStep[],
+    steps,
   };
 }
 
+/** 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 ("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`);
+  }
+  if ("runUntil" in step) {
+    const { target } = step.runUntil;
+    if (target.kind === "raster") fail(`${at}: the replay core has no raster target; use an address or a memory target`);
+    else if (target.space !== "c64") fail(`${at}: the replay core has the C64 alone, not ${target.space}`);
+    else if (target.kind === "address" && target.condition !== undefined) fail(`${at}: the replay core has no condition at an address target`);
+  }
+}
+
 /** Reads and checks recording.json of a recording folder. */
 export function readRecording(folder: string): Recording {
   const path = `${folder}/${RECORDING_FILES.recording}`;
@@ -220,12 +239,13 @@ export function readRecording(folder: string): Recording {
   try {
     value = JSON.parse(readProjectFile(path).bytes.toString("utf8"));
   } catch (error) {
-    throw new ScenarioError(`recording ${path}: ${(error as Error).message}`);
+    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 ScenarioError(`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 ScenarioError(`recording ${path}: ${key} is missing`);
-  for (const key of ["inputs", "events", "sites"]) if (!Array.isArray(value[key])) throw new ScenarioError(`recording ${path}: ${key} is missing`);
-  if (!isInteger(value.ticks, 1, Number.MAX_SAFE_INTEGER)) throw new ScenarioError(`recording ${path}: ticks is missing`);
+  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`);
   return value as unknown as Recording;
 }
 
@@ -243,40 +263,12 @@ function sideAddresses(symbols: Map<string, number>, side: string, move: { code:
   const resolve = (location: Location, kind: "code" | "data") => {
     if (location.startsWith("$")) return move[kind](parseC64Address(location));
     const address = symbols.get(location);
-    if (address === undefined) throw new ScenarioError(`the ${side} side has no symbol ${location}`);
+    if (address === undefined) throw new Refusal("invalid-input", `the ${side} side has no symbol ${location}`);
     return address;
   };
   return { code: (location) => resolve(location, "code"), data: (location) => resolve(location, "data") };
 }
 
-/**
- * The symbols of a symbol source that move with the program: with "code",
- * knowledge labels and routines, else all knowledge symbols; the address
- * symbols of c64-assembler output; or every entry of a name → address map.
- * Constants do not move with the code, so they are left out.
- */
-export function codeLabels(symbols: string, kind: "code" | "all" = "code"): Map<string, number> {
-  if (symbols === "none") return new Map();
-  if (symbols === "knowledge") {
-    const db = openForRead();
-    try {
-      return new Map(
-        listSymbols(db)
-          .filter((row) => kind === "all" || row.kind === "label" || row.kind === "routine")
-          .map((row) => [row.name, row.address]),
-      );
-    } finally {
-      db?.close();
-    }
-  }
-  const value = JSON.parse(readProjectFile(symbols).bytes.toString("utf8")) as unknown;
-  const assembled = (value as { symbols?: Array<{ name: string; kind?: string; address?: string }> }).symbols;
-  if (Array.isArray(assembled)) {
-    return new Map(assembled.filter((symbol) => symbol.address !== undefined).map((symbol) => [symbol.name, parseC64Address(symbol.address!)]));
-  }
-  return new Map(Object.entries(value as Record<string, string>).map(([name, address]) => [name, parseC64Address(address)]));
-}
-
 /** The furthest a site can be from the label before it and still move with that label. */
 const MAX_LABEL_DISTANCE = 4096;
 
@@ -311,11 +303,11 @@ export function siteMap(sites: RecordedSite[], from: Map<string, number>, to: Ma
 
 /** Power-on and READY, then the program in memory as a LOAD leaves it, and RUN in the keyboard queue. */
 async function startProgram(core: C64RunSession, prg: Uint8Array, load: boolean): Promise<CoreStatus> {
-  if (prg.length < 3) throw new ScenarioError("the program is not a PRG file");
-  await core.status(`run ${BOOT_FRAMES * PAL_FRAME_CYCLES}`);
+  if (prg.length < 3) throw new Refusal("invalid-input", "the program is not a PRG file");
+  await core.status(`run ${READY_FRAMES * PAL_FRAME_CYCLES}`);
   const start = prg[0]! | (prg[1]! << 8);
   const end = start + prg.length - 2;
-  if (!load && start !== 0x0801) throw new ScenarioError(`the program loads at ${formatC64Address(start)}, not at $0801 with a BASIC start line: give load true and a registers step that starts it`);
+  if (!load && start !== 0x0801) throw new Refusal("invalid-input", `the program loads at ${formatC64Address(start)}, not at $0801 with a BASIC start line: give load true and a registers step that starts it`);
   await core.write(start, prg.subarray(2));
   // The pointers that LOAD sets: the end of the program and of the variables.
   for (const pointer of [0x2d, 0x2f, 0x31, 0xae]) await core.write(pointer, Uint8Array.of(end & 0xff, end >> 8));
@@ -354,39 +346,63 @@ async function runToKey(core: C64RunSession, key: RecordedEvent["key"], until: n
 }
 
 /** Does a step that is not input. Gives a reason when a runUntil does not reach its target. */
-async function doAction(core: C64RunSession, step: ActionStep, at: SideAddresses): Promise<string | undefined> {
-  if ("write" in step) {
-    await core.write(at.data(step.write.at), Uint8Array.from(step.write.bytes));
+/** The status flags in the order of the P register, bit 7 to bit 0; bit 5 is always 1. */
+const FLAG_BITS: Record<string, number> = { n: 0x80, v: 0x40, b: 0x10, d: 0x08, i: 0x04, z: 0x02, c: 0x01 };
+
+/** A memory comparison of a memory target. */
+const COMPARE: Record<string, (value: number, wanted: number) => boolean> = {
+  eq: (value, wanted) => value === wanted,
+  ne: (value, wanted) => value !== wanted,
+  lt: (value, wanted) => value < wanted,
+  lte: (value, wanted) => value <= wanted,
+  gt: (value, wanted) => value > wanted,
+  gte: (value, wanted) => value >= wanted,
+};
+
+async function doAction(core: C64RunSession, step: ActionStep | RestoreAction, at: SideAddresses): Promise<string | undefined> {
+  if ("restore" in step) {
+    // The NMI line is low while RESTORE is down: hold it as a press step holds a key.
+    const tick = (await core.status("status")).tick;
+    await core.command("key ff down");
+    await core.status("run " + (tick + KEY_FRAMES * PAL_FRAME_CYCLES));
+    await core.command("key ff up");
+  } else if ("write" in step) {
+    await core.write(at.data(step.write.address), Buffer.from(step.write.data, "hex"));
+  } else if ("type" in step) {
+    // The KERNAL keyboard queue: the keys after the keys that wait there now.
+    const keys = keyboardBytes(step.type) as Uint8Array;
+    const waiting = (await core.peek(QUEUE_LENGTH, 1))[0]!;
+    if (waiting + keys.length > QUEUE_SIZE) return `the KERNAL keyboard queue holds ${waiting} keys, and ${keys.length} more do not fit in its ${QUEUE_SIZE}`;
+    await core.write(QUEUE + waiting, keys);
+    await core.write(QUEUE_LENGTH, Uint8Array.of(waiting + keys.length));
   } else if ("registers" in step) {
     const now = await core.status("run-sync");
-    const value = (name: "a" | "x" | "y" | "sp", current: number) => {
-      const given = step.registers[name];
-      return given === undefined ? current : typeof given === "number" ? given : at.data(given);
-    };
-    const values = [value("a", now.a), value("x", now.x), value("y", now.y), value("sp", now.s), now.p].map((n) => n.toString(16));
+    const { pc, flags } = step.registers;
+    let p = now.p;
+    for (const [name, set] of Object.entries(flags ?? {})) if (set !== undefined) p = set ? p | FLAG_BITS[name]! : p & ~FLAG_BITS[name]!;
+    const values = [step.registers.a ?? now.a, step.registers.x ?? now.x, step.registers.y ?? now.y, step.registers.sp ?? now.s, p].map((n) => n.toString(16));
     await core.status(`regs ${values.join(" ")}`);
-    const pc = step.registers.pc;
-    if (pc !== undefined) await core.status(`goto ${hex(typeof pc === "number" ? pc : at.code(pc))}`);
+    if (pc !== undefined) await core.status(`goto ${hex(at.code(pc))}`);
   } else if ("runUntil" in step) {
+    const { target, timeoutFrames } = step.runUntil;
     const start = (await core.status("status")).tick;
-    const until = start + step.timeoutFrames * PAL_FRAME_CYCLES;
-    if ("memory" in step.runUntil) {
-      const { at: where, equals } = step.runUntil.memory;
+    const until = start + timeoutFrames * PAL_FRAME_CYCLES;
+    if (target.kind === "memory") {
       for (let tick = start; ; tick += PAL_FRAME_CYCLES) {
-        if ((await core.peek(at.data(where), 1))[0] === equals) return undefined;
-        if (tick >= until) return `${where} did not become ${equals} within ${step.timeoutFrames} frames`;
+        if (COMPARE[target.operator]!((await core.peek(at.data(target.address), 1))[0]!, target.value)) return undefined;
+        if (tick >= until) return `${target.address} did not become ${target.operator} ${target.value} within ${timeoutFrames} frames`;
         await core.status(`run ${tick + PAL_FRAME_CYCLES}`);
       }
     }
-    const target = (step.runUntil as { at: Location }).at;
-    const reached = await core.status(`run-pc ${hex(at.code(target))} ${until}`);
-    if (reached.word !== "reached") return `the program did not reach ${target} within ${step.timeoutFrames} frames`;
+    if (target.kind !== "address") return "the replay core has no raster target";
+    const reached = await core.status(`run-pc ${hex(at.code(target.address))} ${until}`);
+    if (reached.word !== "reached") return `the program did not reach ${target.address} within ${timeoutFrames} frames`;
   }
   return undefined;
 }
 
 function rangesArgument(state: StateItem[], at: SideAddresses): string {
-  return state.map((item) => `${hex(at.data(item.at))}:${item.size}`).join(",");
+  return state.map((item) => `${hex(at.data(item.address))}:${item.size}`).join(",");
 }
 
 export interface RecordOutcome {
@@ -397,15 +413,24 @@ export interface RecordOutcome {
   reason?: string;
 }
 
-/** Plays the steps of a record file in the replay core and records the session. */
-export async function record(core: C64RunSession, file: RecordFile, workspace: Workspace, input?: (core: C64RunSession) => Promise<void>): Promise<RecordOutcome> {
+/**
+ * Plays the steps of a record file in the replay core and records the session.
+ * `input` runs after the steps, with `restore` for a RESTORE press of the play;
+ * a reason that it gives means no recording.
+ */
+export async function record(
+  core: C64RunSession,
+  file: RecordFile,
+  workspace: Workspace,
+  input?: (core: C64RunSession, restore: () => Promise<string | undefined>) => Promise<string | undefined>,
+): Promise<RecordOutcome> {
   const prg = readProjectFile(file.program).bytes;
   const same = (address: number) => address;
-  const at = sideAddresses(loadSymbols({ program: file.program, symbols: file.symbols }), "original", { code: same, data: same });
+  const at = sideAddresses(namesOf(file.symbols), "original", { code: same, data: same });
   // A checkpoint and state of the record file must resolve now, so that a replay can use them.
   if (file.compare !== undefined) {
     at.code(file.compare.checkpoint);
-    for (const item of file.compare.state) at.data(item.at);
+    for (const item of file.compare.state) at.data(item.address);
   }
   const reads = workspace.path(RECORDING_FILES.reads);
   const coverage = workspace.path(RECORDING_FILES.coverage);
@@ -420,36 +445,37 @@ export async function record(core: C64RunSession, file: RecordFile, workspace: W
   const masks = [0, 0];
   let reason: string | undefined;
   let afterEvent = false;
+  // An event runs after the next read at the busiest program site, here and on each
+  // replay. An event right after another event runs where that one ended.
+  const runEvent = async (action: ActionStep | RestoreAction, step?: number): Promise<string | undefined> => {
+    const tick = (await core.status("status")).tick;
+    const busiest = afterEvent ? undefined : busiestSite(await core.command("sites"));
+    const key: RecordedEvent["key"] = afterEvent
+      ? { previous: true }
+      : busiest === undefined
+        ? { tick: tick + 1 }
+        : { site: formatC64Address(busiest.site), addr: formatC64Address(busiest.addr), count: busiest.count + 1 };
+    if ((await runToKey(core, key, tick + 600 * PAL_FRAME_CYCLES, new Map())) !== "reached") return "the program did not read its input again within 600 frames";
+    events.push({ ...(step === undefined ? {} : { step }), action, key });
+    return doAction(core, action, at);
+  };
   for (const [index, step] of file.steps.entries()) {
     let tick = (await core.status("status")).tick;
-    const event = !INPUT_KINDS.has(Object.keys(step).find((key) => STEP_KINDS.includes(key))!);
+    const event = !INPUT_KINDS.has(Object.keys(step)[0]!);
     if ("frames" in step) {
       await core.status(`run ${tick + step.frames * PAL_FRAME_CYCLES}`);
     } else if ("joystick" in step) {
       masks[step.joystick.port - 1] = joystickMask(step.joystick.direction, step.joystick.fire ?? false);
       await core.command(`joy ${masks[0]!.toString(16)} ${masks[1]!.toString(16)}`);
-    } else if ("type" in step) {
-      for (const code of keyCodes(step.type)) {
+    } else if ("press" in step) {
+      for (const code of keyCodes(step.press)) {
         await core.command(`key ${code.toString(16)} down`);
         await core.status(`run ${(tick += KEY_FRAMES * PAL_FRAME_CYCLES)}`);
         await core.command(`key ${code.toString(16)} up`);
         await core.status(`run ${(tick += KEY_FRAMES * PAL_FRAME_CYCLES)}`);
       }
     } else {
-      // Not input: it runs after the next read at the busiest program site, here and on each
-      // replay. An event right after another event runs where that one ended.
-      const busiest = afterEvent ? undefined : busiestSite(await core.command("sites"));
-      const key: RecordedEvent["key"] = afterEvent
-        ? { previous: true }
-        : busiest === undefined
-          ? { tick: tick + 1 }
-          : { site: formatC64Address(busiest.site), addr: formatC64Address(busiest.addr), count: busiest.count + 1 };
-      if ((await runToKey(core, key, tick + 600 * PAL_FRAME_CYCLES, new Map())) !== "reached") {
-        reason = `step ${index + 1}: the program did not read its input again within 600 frames`;
-        break;
-      }
-      events.push({ step: index + 1, action: step, key });
-      reason = await doAction(core, step, at);
+      reason = await runEvent(step, index + 1);
       if (reason !== undefined) {
         reason = `step ${index + 1}: ${reason}`;
         break;
@@ -457,7 +483,13 @@ export async function record(core: C64RunSession, file: RecordFile, workspace: W
     }
     afterEvent = event;
   }
-  if (input !== undefined && reason === undefined) await input(core);
+  // The play runs frames before each RESTORE: a RESTORE never runs where an event of the steps ended.
+  const restore = async () => {
+    afterEvent = false;
+    const failed = await runEvent({ restore: true });
+    return failed === undefined ? undefined : "RESTORE: " + failed;
+  };
+  if (input !== undefined && reason === undefined) reason = await input(core, restore);
   const end = await core.status("status");
   const sites = (await core.command("sites")).split(" ").slice(2).map((entry): RecordedSite => {
     const [where, reads, kind] = entry.split(":");
@@ -526,9 +558,9 @@ export async function replaySide(
   const same = (address: number) => address;
   const move = original
     ? { code: same, data: same }
-    : { code: mover(codeLabels(names), codeLabels(subject.symbols)), data: mover(codeLabels(names, "all"), codeLabels(subject.symbols, "all")) };
-  const at = sideAddresses(loadSymbols({ program: subject.program, symbols: subject.symbols }), subject.side, move);
-  const moved = original ? [] : siteMap(recording.sites, codeLabels(names), codeLabels(subject.symbols));
+    : { code: mover(namesOf(names, "code"), namesOf(subject.symbols, "code")), data: mover(namesOf(names), namesOf(subject.symbols)) };
+  const at = sideAddresses(namesOf(subject.symbols), subject.side, move);
+  const moved = original ? [] : siteMap(recording.sites, namesOf(names, "code"), namesOf(subject.symbols, "code"));
   const map = new Map(moved);
   const reads = workspace.path(`${subject.side}-${RECORDING_FILES.reads}`);
   writeFileSync(reads, readProjectFile(`${folder}/${RECORDING_FILES.reads}`).bytes);
@@ -555,15 +587,16 @@ export async function replaySide(
   const limit = original ? recording.ticks : recording.ticks * REBUILD_TIME_FACTOR;
   let problem: string | undefined;
   for (const event of recording.events) {
+    const what = event.step === undefined ? "the RESTORE of the play" : "step " + event.step;
     const point = await runToKey(core, event.key, limit, map);
     if (point === "halted") break;
     if (point === "not-reached") {
-      problem = `the program did not come to the point of step ${event.step}`;
+      problem = "the program did not come to the point of " + what;
       break;
     }
     problem = await doAction(core, event.action, at);
     if (problem !== undefined) {
-      problem = `step ${event.step}: ${problem}`;
+      problem = what + ": " + problem;
       break;
     }
   }
@@ -585,7 +618,7 @@ export interface CheckpointDifference {
   /** 1 = the first checkpoint. */
   checkpoint: number;
   tick: { original: number; rebuild: number };
-  items: Array<{ at: Location; original: string; rebuild: string }>;
+  items: Array<{ address: Location; original: string; rebuild: string }>;
 }
 
 /** The pinned values of each sample line: the fields after the state items. */
@@ -604,7 +637,7 @@ export function firstDifference(expected: string[], got: string[], state: StateI
     const a = allA.slice(0, state.length);
     const b = allB.slice(0, state.length);
     if (a.join(" ") === b.join(" ")) continue;
-    const items = state.flatMap((item, at) => (a[at] === b[at] ? [] : [{ at: item.at, original: a[at] ?? "", rebuild: b[at] ?? "" }]));
+    const items = state.flatMap((item, at) => (a[at] === b[at] ? [] : [{ address: item.address, original: a[at] ?? "", rebuild: b[at] ?? "" }]));
     return { checkpoint: index + 1, tick: { original: Number(tickA), rebuild: Number(tickB) }, items };
   }
   return undefined;
@@ -625,5 +658,5 @@ export interface ReplayResult {
   movedSites?: number;
   /** Input reads of the rebuild that the recording had no value for: they got the idle value. */
   idleReads?: number;
-  files?: string[];
+  files?: Written[];
 }