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

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

@@ -0,0 +1,105 @@
+// The replay of c64-testing: replays a recording in the replay core
+// (c64run). First on the original program, which must end with the recorded
+// state hash. Then, with --rebuild, on the rebuild: it compares the state at
+// each checkpoint with the original's. --checkpoint and --state choose the
+// comparison, else the record file gave it.
+
+import { createHash } from "node:crypto";
+
+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";
+import { Workspace } from "#src/native/staging.ts";
+import { UsageError } from "#src/script.ts";
+import { firstDifference, parseStateItem, pinLines, readRecording, replaySide, siteMap, type Comparison, type ReplayResult, type ReplaySubject } from "./recording.ts";
+import { namesOf } from "./scenario.ts";
+
+const MAX_STATE_ITEMS = 16;
+
+export interface ReplayOptions {
+  folder: string;
+  checkpoint?: string;
+  state: string[];
+  pin: string[];
+  rebuild?: string;
+  symbols?: string;
+  out?: string;
+}
+
+/** Replays the recording on the original, and with `rebuild` on the rebuild: PASS, FAIL or INCONCLUSIVE. */
+export async function replay(values: ReplayOptions): Promise<ReplayResult> {
+  if (values.symbols !== undefined && values.rebuild === undefined) throw new UsageError("--symbols is for the rebuild: give --rebuild too");
+  if ((values.checkpoint === undefined) !== (values.state.length === 0)) throw new UsageError("give --checkpoint and --state together");
+  if (values.state.length + values.pin.length > MAX_STATE_ITEMS) throw new UsageError(`give at most ${MAX_STATE_ITEMS} --state and --pin items`);
+  if (values.pin.length > 0 && values.checkpoint === undefined) throw new UsageError("--pin needs --checkpoint and --state");
+  const folder = values.folder.replace(/\/+$/, "").replace(/\/recording\.json$/, "");
+  const recording = readRecording(folder);
+  const given: Comparison | undefined =
+    values.checkpoint === undefined ? undefined : { checkpoint: values.checkpoint, state: values.state.map(parseStateItem), ...(values.pin.length === 0 ? {} : { pin: values.pin.map(parseStateItem) }) };
+  const compare = given ?? recording.compare;
+  if (values.rebuild !== undefined && compare === undefined) throw new UsageError("the recording has no checkpoint and state: give --checkpoint and --state");
+  const result = (outcome: ReplayResult["result"], side: ReplayResult["side"], fields: Partial<ReplayResult> = {}): ReplayResult => ({
+    result: outcome,
+    recording: folder,
+    side,
+    ...(compare === undefined ? {} : { checkpoint: compare.checkpoint }),
+    checkpoints: 0,
+    compared: 0,
+    ...fields,
+  });
+  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` });
+
+  const context = localToolContext();
+  const core = await C64RunSession.open(context);
+  const workspace = Workspace.create(context.supervisor, "c64-re-tools-replay-");
+  try {
+    // A recording made without names takes the names that the knowledge has now.
+    const originalSymbols = recording.symbols === "none" ? "knowledge" : recording.symbols;
+    const original: ReplaySubject = { side: "original", program: recording.program, symbols: originalSymbols };
+    const side = (subject: ReplaySubject, options: Parameters<typeof replaySide>[5]) => replaySide(core, recording, folder, subject, workspace, options);
+    // The self-check: the original ends the session with the recorded state, to the cycle.
+    const self = await side(original, { ...(compare === undefined ? {} : { compare }) });
+    if (self.problem !== undefined) return result("INCONCLUSIVE", "original", { reason: `the recording does not reproduce on the original: ${self.problem}` });
+    if (self.unknown > 0 || self.misses > 0) {
+      return result("INCONCLUSIVE", "original", { reason: `the recording does not reproduce on the original: ${self.unknown + self.misses} input reads had no recorded value; record the session again with this c64run` });
+    }
+    if (self.end.tick !== recording.ticks || self.end.hash !== recording.hash) {
+      return result("INCONCLUSIVE", "original", { reason: "the recording does not reproduce on the original: the state at its end is different; record the session again with this c64run" });
+    }
+    const expected = self.samples;
+    if (compare !== undefined && expected.length === 0) return result("INCONCLUSIVE", "original", { reason: `the original never came to the checkpoint ${compare.checkpoint} in the session` });
+    if (values.rebuild === undefined) return result("PASS", "original", { checkpoints: expected.length });
+
+    const rebuild: ReplaySubject = { side: "rebuild", program: values.rebuild, symbols: values.symbols ?? originalSymbols };
+    let movedSites: number;
+    try {
+      movedSites = siteMap(recording.sites, namesOf(originalSymbols, "code"), namesOf(rebuild.symbols, "code")).length;
+    } catch (error) {
+      throw new UsageError(`--symbols ${rebuild.symbols}: ${(error as Error).message}`);
+    }
+    const pins = pinLines(expected, compare!.state);
+    const replayed = await side(rebuild, { compare: compare!, stop: expected.length, pins });
+    const difference = firstDifference(expected, replayed.samples, compare!.state);
+    // A read that the recording has no value for gets the idle value: it is in the result, never silent.
+    const base = { checkpoints: expected.length, movedSites, ...(replayed.unknown > 0 ? { idleReads: replayed.unknown } : {}) };
+    if (difference === undefined && replayed.samples.length >= expected.length) return result("PASS", "rebuild", { ...base, compared: expected.length });
+    const reason =
+      difference !== undefined
+        ? `the state differs at checkpoint ${difference.checkpoint} of ${expected.length}${replayed.unknown > 0 ? `; the rebuild read input ${replayed.unknown} times at sites that the recording does not have` : ""}`
+        : `the rebuild came to ${replayed.samples.length} of ${expected.length} checkpoints${replayed.problem === undefined ? "" : `: ${replayed.problem}`}`;
+    const failed = result("FAIL", "rebuild", { ...base, compared: (difference?.checkpoint ?? replayed.samples.length + 1) - 1, reason, ...(difference === undefined ? {} : { firstDifference: difference }) });
+    if (values.out !== undefined && difference !== undefined) {
+      const files: Written[] = [];
+      for (const subject of [original, rebuild]) {
+        const dumped = await side(subject, { compare: compare!, dump: difference.checkpoint, ...(subject.side === "rebuild" ? { pins } : {}) });
+        files.push(writeReported(`${values.out}/${subject.side}-${difference.checkpoint}.bin`, dumped.ram!, { what: "--out" }));
+      }
+      failed.files = files;
+    }
+    return failed;
+  } finally {
+    await core.close();
+    workspace.remove();
+  }
+}

package/skills/c64-testing/scripts/{run.ts → lib/runs.ts}

@@ -1,28 +1,17 @@
-// The c64-testing run script: runs steps in its own emulator, from a
-// program or a snapshot file, and writes what the steps ask for into a
-// directory: screens, coverage maps, snapshot files, and results.json with
-// the observations. One side, no comparison. Exit status: 0 when every step
-// ran, 1 when a step did not, 2 for a bad call.
-
-import { parseArgs } from "node:util";
+// The runs of c64-testing: steps in their own emulator, from a program or a
+// snapshot file, and what the steps ask for written into a folder: screens,
+// coverage maps, snapshot files, and results.json with the observations. One
+// side, no comparison.
 
 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_KEYS, ACTION_STEP_KINDS, checkActionStep, isInteger, isObject, runActionStep, type ActionStep } from "#src/host-client/steps.ts";
+import { ACTION_STEP_KINDS, checkActionStep, isInteger, isObject, runActionStep, type ActionStep, type ActionStepKind } from "#src/host-client/steps.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, writeProjectFile } from "#src/host-client/transfer.ts";
+import { readProjectFile, writeReported, type Written } from "#src/host-client/transfer.ts";
 import { readMemoryInParts, ViceSessionClient } from "#src/host-client/vice-session.ts";
-import { resolveProjectPath } from "#src/project.ts";
-import { runScript, UsageError } from "#src/script.ts";
-import { loadSymbols } from "./lib/scenario.ts";
-
-const USAGE = `run.ts <run.json> --out <dir>
-
-<run.json> is a run file relative to the project folder: where to start,
-optional symbols, and the steps. See references/scenario-format.md, section
-Runs. The files that the steps write, and results.json, go into <dir>. The
-result is one JSON object.`;
+import { UsageError } from "#src/script.ts";
+import { namesOf } from "./scenario.ts";
 
 type RunStep =
   | ActionStep
@@ -30,8 +19,8 @@ type RunStep =
   | { save: string }
   | { screen: string }
   | { coverage: string }
-  | { trace: string; points: Array<{ kind: TraceKind; at: string; end?: string }>; frames: number; maxHits?: number }
-  | { observe: string; memory?: "all" | Array<string | { at: string; size?: number; view?: "cpu" | "ram" }>; registers?: boolean; vicii?: boolean; sprites?: number[] };
+  | { trace: string; points: Array<{ kind: TraceKind; start: string; end?: string }>; frames: number; maxHits?: number }
+  | { observe: string; memory?: "all" | Array<string | { address: string; size?: number; view?: "cpu" | "ram" }>; registers?: boolean; vicii?: boolean; sprites?: number[] };
 
 interface Run {
   name: string;
@@ -73,9 +62,13 @@ function readRun(path: string): Run {
     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(", ")}`);
     const kind = kinds[0]!;
-    const allowed = kind === "observe" ? OBSERVE_KEYS : kind === "trace" ? TRACE_KEYS : (ACTION_STEP_KEYS[kind] ?? [kind]);
+    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)) return checkActionStep(kind, step, at, fail);
+    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.
+      (value.steps as unknown[])[index] = checkActionStep(kind as ActionStepKind, step, at, fail);
+      return;
+    }
     const name = step[kind];
     if (kind === "snapshot") {
       if (typeof name !== "string" || name === "") fail(`${at}: snapshot needs a project file`);
@@ -86,11 +79,11 @@ function readRun(path: string): Run {
       if (labels.has(name as string)) fail(`${at} needs a new name`);
       labels.add(name as string);
       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 at`);
+      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", "at", "end"].includes(key))) return fail(`${at}: a point has kind, at and end, and nothing else`);
+        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 (!(TRACE_KINDS as readonly unknown[]).includes(point.kind)) fail(`${at}: a point kind is exec, read or write`);
-        if (typeof point.at !== "string" || (point.end !== undefined && typeof point.end !== "string")) fail(`${at}: a point needs at, and end when it is a range, as names or $ addresses`);
+        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`);
       }
       if (!isInteger(step.frames, 1, MAX_TRACE_FRAMES)) fail(`${at}: frames must be a number from 1 to ${MAX_TRACE_FRAMES}`);
       if (step.maxHits !== undefined && !isInteger(step.maxHits, 1, MAX_TRACE_HITS)) fail(`${at}: maxHits must be a number from 1 to ${MAX_TRACE_HITS}`);
@@ -102,12 +95,12 @@ function readRun(path: string): Run {
     const memoryItem = (item: unknown) =>
       typeof item === "string" ||
       (isObject(item) &&
-        typeof item.at === "string" &&
-        Object.keys(item).every((key) => ["at", "size", "view"].includes(key)) &&
+        typeof item.address === "string" &&
+        Object.keys(item).every((key) => ["address", "size", "view"].includes(key)) &&
         (item.size === undefined || isInteger(item.size, 1, 0x10000)) &&
         (item.view === undefined || item.view === "cpu" || item.view === "ram"));
     if (step.memory !== undefined && step.memory !== "all" && (!Array.isArray(step.memory) || !step.memory.every(memoryItem))) {
-      fail(`${at}: memory is "all", or a list of names, $ addresses, or objects with at, size (1 to 65536) and view (cpu or ram)`);
+      fail(`${at}: memory is "all", or a list of names, $ addresses, or objects with address, size (1 to 65536) and view (cpu or ram)`);
     }
     if (step.registers !== undefined && typeof step.registers !== "boolean") fail(`${at}: registers must be true or false`);
     if (step.vicii !== undefined && typeof step.vicii !== "boolean") fail(`${at}: vicii must be true or false`);
@@ -121,9 +114,10 @@ function showHit(hit: TraceHit) {
   return { ...hit, pc: formatC64Address(hit.pc), ...(hit.address === undefined ? {} : { address: formatC64Address(hit.address) }) };
 }
 
-async function runFile(path: string, out: string): Promise<{ output: Record<string, unknown>; failed: boolean }> {
+/** 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);
-  const symbols = loadSymbols({ program: "", symbols: run.symbols ?? "none" });
+  const symbols = namesOf(run.symbols ?? "none");
   const at = (location: string): number => {
     if (location.startsWith("$")) return parseC64Address(location);
     const address = symbols.get(location);
@@ -131,8 +125,9 @@ async function runFile(path: string, out: string): Promise<{ output: Record<stri
     return address;
   };
   const files: string[] = [];
+  const written: Written[] = [];
   const write = (name: string, bytes: Uint8Array) => {
-    writeProjectFile(`${out}/${name}`, bytes, { what: "--out" });
+    written.push(writeReported(`${out}/${name}`, bytes, { what: "--out" }));
     files.push(name);
   };
   const observations: Record<string, unknown> = {};
@@ -158,7 +153,7 @@ async function runFile(path: string, out: string): Promise<{ output: Record<stri
       } else if ("save" in step) {
         await client.snapshot({ action: "save", name: "run-save" });
         write(`${step.save}.vsf`, await client.snapshotExport("run-save"));
-        await client.snapshot({ action: "discard", name: "run-save" });
+        await client.snapshot({ action: "remove", name: "run-save" });
       } else if ("screen" in step) {
         write(`${step.screen}.png`, Buffer.from((await client.screenCapture()).png, "base64"));
       } else if ("coverage" in step) {
@@ -166,7 +161,7 @@ async function runFile(path: string, out: string): Promise<{ output: Record<stri
         await client.memmap({ action: "clear" });
       } else if ("trace" in step) {
         // A trace: every hit of the points while the program runs on, to <name>.json.
-        const points = step.points.map((point) => ({ kind: point.kind, start: at(point.at), end: at(point.end ?? point.at) }));
+        const points = step.points.map((point) => ({ kind: point.kind, start: at(point.start), end: at(point.end ?? point.start) }));
         if (points.some((point) => point.end < point.start)) throw new UsageError(`the trace ${step.trace} has a point whose end is before its start`);
         const traced = await client.trace({ points, frames: step.frames, maxHits: step.maxHits ?? MAX_TRACE_HITS });
         write(`${step.trace}.json`, Buffer.from(`${JSON.stringify({ points: step.points, frames: traced.frames, end: traced.end, hits: traced.hits.map(showHit) }, null, 1)}\n`));
@@ -184,15 +179,15 @@ async function runFile(path: string, out: string): Promise<{ output: Record<stri
         } else if (step.memory !== undefined) {
           const memory: Record<string, string | { file: string }> = {};
           for (const item of step.memory) {
-            const spec = typeof item === "string" ? { at: item } : item;
+            const spec = typeof item === "string" ? { address: item } : item;
             const size = spec.size ?? 1;
-            const bytes = await readMemoryInParts(client, at(spec.at), size, spec.view ?? "cpu");
+            const bytes = await readMemoryInParts(client, at(spec.address), size, spec.view ?? "cpu");
             // More than one read gives goes to a file: results.json stays small.
-            if (size <= MAX_MEMORY_READ) memory[spec.at] = bytes.toString("hex");
+            if (size <= MAX_MEMORY_READ) memory[spec.address] = bytes.toString("hex");
             else {
-              const file = `${step.observe}-${spec.at.replace(/^\$/, "")}.bin`;
+              const file = `${step.observe}-${spec.address.replace(/^\$/, "")}.bin`;
               write(file, bytes);
-              memory[spec.at] = { file };
+              memory[spec.address] = { file };
             }
           }
           seen.memory = memory;
@@ -207,7 +202,7 @@ async function runFile(path: string, out: string): Promise<{ output: Record<stri
       } else {
         const notReached = await runActionStep(client, step, at);
         if (notReached !== undefined && "runUntil" in step) {
-          reason = `Step ${done + 1} did not reach its target in ${step.timeoutFrames} frames. It stopped by ${notReached.stopReason} at ${formatC64Address(notReached.pc)}.`;
+          reason = `Step ${done + 1} did not reach its target in ${step.runUntil.timeoutFrames} frames. It stopped by ${notReached.stopReason} at ${formatC64Address(notReached.pc)}.`;
           break;
         }
       }
@@ -216,26 +211,8 @@ async function runFile(path: string, out: string): Promise<{ output: Record<stri
     const pc = (await client.registersGet("c64")).pc;
     const results = { name: run.name, completed: reason === undefined, steps: run.steps.length, done, ...(reason === undefined ? {} : { reason }), pc: formatC64Address(pc), files: [...files], observations, ...(Object.keys(traces).length === 0 ? {} : { traces }) };
     write("results.json", Buffer.from(`${JSON.stringify(results, null, 2)}\n`));
-    return { output: { ...results, files, observations: Object.keys(observations), out }, failed: reason !== undefined };
+    return { output: { ...results, files: written, observations: Object.keys(observations), out }, failed: reason !== undefined };
   } finally {
     await client.close();
   }
 }
-
-await runScript(
-  async (argv) => {
-    const { values, positionals } = parseArgs({ args: argv, strict: true, allowPositionals: true, options: { out: { type: "string" }, help: { type: "boolean" } } });
-    if (values.help) throw new UsageError("");
-    if (positionals.length !== 1) throw new UsageError("give one run file");
-    if (values.out === undefined) throw new UsageError("run needs --out <dir>");
-    try {
-      resolveProjectPath(values.out);
-    } catch {
-      throw new UsageError(`--out must be a path relative to the project folder that stays inside it, not ${values.out}`);
-    }
-    const { output, failed } = await runFile(positionals[0]!, values.out);
-    if (failed) process.exitCode = 1;
-    return output;
-  },
-  { usage: USAGE },
-);

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",