@henols/c64-re-tools 2.0.0-rc.9 → 2.0.1

package/skills/c64-testing/references/scenario-format.md

@@ -23,7 +23,7 @@ A scenario is one JSON object in a project file.
 
 `original` and `rebuild` each have:
 
-- `program`: a PRG file, relative to the project directory.
+- `program`: a PRG file, relative to the project folder.
 - `symbols`: where the names come from:
   - `knowledge`: the project knowledge.
   - A JSON file: the output of the c64-assembler skill, or an object of names and `$` addresses.
@@ -38,7 +38,7 @@ Before the first step of each side, the script does a hard reset. The CPU stops
 | Step | Effect |
 |---|---|
 | `{ "reset": "hard" }` | Reset the C64 (`hard` or `soft`). The CPU stops at the reset vector. |
-| `{ "frames": 150 }` | Run for an exact number of frames, from 1 to 10000. Use it after a reset to start the C64. |
+| `{ "frames": 150 }` | Run for an exact number of frames, from 1 to 30000. A breakpoint or a watchpoint stops it before that. Use it after a reset to start the C64. |
 | `{ "load": true }` | Load the program of the side into memory. The CPU stays stopped. |
 | `{ "autostart": true }` | Load the program of the side, type `RUN` and wait until the program runs. The program must have a BASIC start line. The keys of a later `type` step go to the program. |
 | `{ "write": { "at": "seed", "bytes": [1, 2] } }` | Write bytes into memory: 1 to 4096 numbers from 0 to 255. |
@@ -50,7 +50,7 @@ Before the first step of each side, the script does a hard reset. The CPU stops
 | `{ "runUntil": { "raster": 250 }, "timeoutFrames": 5 }` | Run until the raster beam gets to a line (0 to 311 for PAL, 0 to 262 for NTSC). |
 | `{ "runUntil": { "at": "irq_tick", "raster": 250 }, "timeoutFrames": 600 }` | Run until the CPU gets to an address while the beam is on that line. |
 | `{ "snapshot": "snapshots/start.vsf" }` | Restore a snapshot file. Usually with `side`: the snapshot of one program is not a state of the other. |
-| `{ "normalize": "unpacked/entry_state.json" }` | Write pages 0 to 3 and `$00`/`$01` from an entry state file of the c64-unpacker skill. Then both sides have the same zero page, stack and KERNAL work area. |
+| `{ "normalize": true }` | Write pages 0 to 3 and `$00`/`$01` from the entry state in the knowledge. The entry state comes from a capture of the c64-unpacker skill, which `image` of the c64-knowledge skill put in. Then both sides have the same zero page, stack and KERNAL work area. |
 | `{ "observe": "moved", ... }` | Record a checkpoint. |
 
 The `port` of a joystick is 1 or 2. The `direction` is `center`, `up`, `down`, `left`, `right`, `up-left`, `up-right`, `down-left` or `down-right`.
@@ -67,7 +67,7 @@ An `observe` step has a checkpoint name. A scenario can have each name only one
 
 | Key | What the script compares |
 |---|---|
-| `memory` | A list of names, `$` addresses, or objects with `at`, `size` (1 to 4096, default 1), `tolerance` (0 to 255, default 0) and `exclude`. |
+| `memory` | A list of names, `$` addresses, or objects. An object has `at`, `size` (1 to 65536, default 1), `view` (`cpu` or `ram`, default `cpu`), `tolerance` (0 to 255, default 0) and `exclude`. The view `ram` reads the RAM under the ROMs and the I/O area. |
 | `registers` | A list of register names: `pc`, `a`, `x`, `y`, `sp`, `flags`. |
 | `screen` | The screen of the rebuild against the screen of the original. `maxMismatchRatio` (default 0) is the largest permitted part of different pixels. `mask` is a list of rectangles (`x`, `y`, `width`, `height`) that the comparison does not include. |
 | `vicii` | The VIC-II state: mode, screen address, scroll and colors. |
@@ -84,10 +84,14 @@ A `pc` value is an address. Compare `pc` only when both programs have the code a
 A run file (for `run.ts`) has:
 
 - `name`: a short name.
-- `start`: `{ "program": "game.prg" }` to autostart a program with a BASIC start line, `{ "program": "game.prg", "load": true }` to load it with the CPU stopped (set `pc` in a step), or `{ "snapshot": "snapshots/room0.vsf" }`.
+- `start`: `{ "program": "game.prg" }` to autostart a program with a BASIC start line, `{ "program": "game.prg", "load": true }` to load it with the CPU stopped (set `pc` in a step), or `{ "snapshot": ".c64-re-tools/local/snapshots/room0.vsf" }`.
 - `symbols`: optional, `knowledge`, `none` (default), or a JSON file as for a subject.
 - `videoStandard`: optional, `pal` (default) or `ntsc`.
-- `steps`: the steps `write`, `registers`, `joystick`, `type`, `frames` and `runUntil` of a scenario, and the run steps `snapshot`, `save`, `screen`, `coverage` and `observe`.
+- `steps`: the steps `write`, `registers`, `joystick`, `type`, `frames` and `runUntil` of a scenario, and the run steps `snapshot`, `save`, `screen`, `coverage`, `trace` and `observe`.
+
+A `trace` step has a name, `points` (1 to 8), `frames` (1 to 3000) and an optional `maxHits` (at most 20000). A point has `kind` (`exec`, `read` or `write`), `at` and an optional `end`. The step writes `<name>.json` with each hit. `results.json` gives the file, the count of hits, the frames and why the trace ended. A trace that a breakpoint, a watchpoint or a JAM ends also ends the run.
+
+In a run, a memory item has `at`, `size` (1 to 65536) and `view`. An item larger than 4096 bytes goes into the file `<observe>-<at>.bin`. `"memory": "all"` writes all 64 KiB of RAM to `<observe>.bin`.
 
 A name in `save`, `screen`, `coverage` and `observe` has 1 to 64 letters, digits, dots, underscores or hyphens. The files go into the `--out` directory, with `results.json`. It has the observations, the files and the steps done. If a `runUntil` step did not reach its target, it also tells why the run stopped.
 
@@ -96,13 +100,13 @@ Example: visit two rooms from the same start.
 ```json
 {
   "name": "rooms",
-  "start": { "snapshot": "snapshots/room0.vsf" },
+  "start": { "snapshot": ".c64-re-tools/local/snapshots/room0.vsf" },
   "steps": [
     { "write": { "at": "$0350", "bytes": [1] } },
     { "frames": 50 },
     { "screen": "room1" },
     { "coverage": "room1" },
-    { "snapshot": "snapshots/room0.vsf" },
+    { "snapshot": ".c64-re-tools/local/snapshots/room0.vsf" },
     { "write": { "at": "$0350", "bytes": [2] } },
     { "frames": 50 },
     { "screen": "room2" },

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

@@ -5,7 +5,7 @@
 import { parseArgs } from "node:util";
 
 import { runScript, UsageError } from "#src/script.ts";
-import { readScenario, ScenarioError, type Scenario } from "./scenario.ts";
+import { readScenario, ScenarioError, type Scenario } from "./lib/scenario.ts";
 
 const USAGE = `checklist.ts <scenario.json> [<scenario.json> ...] [--item <text> ...]
 
@@ -44,8 +44,8 @@ function run(argv: string[]): string {
 }
 
 await runScript(
-  () => {
-    process.stdout.write(run(process.argv.slice(2)));
+  (argv) => {
+    process.stdout.write(run(argv));
   },
   { usage: USAGE },
 );

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

@@ -0,0 +1,167 @@
+// The c64-testing diff script: what changed between two machine states.
+// Two snapshot files are restored one after the other in an own emulator,
+// which reads RAM, colour RAM and the chip and CPU registers with the readers
+// that the runs use: VICE reads its own snapshot format. Two memory files of a
+// run, or two observations of runs (also two of one run), compare as they are.
+// Exit status: 0, or 2 for a bad call.
+
+import { parseArgs } from "node:util";
+
+import { formatC64Address, parseC64Address } from "#src/c64.ts";
+import { WireFailure } from "#src/host-client/tools.ts";
+import { readProjectFile, writeProjectFile } 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 { diffStates, type ChangedRange, type MachineState } from "./lib/diff.ts";
+
+const USAGE = `diff.ts <a> <b> [--gap N] [--max-listed N] [--ntsc] [--at <address>] [--out <file>]
+
+<a> and <b> are two of one kind, relative to the project folder:
+  snapshot.vsf             the emulator restores each one and reads RAM, colour
+                           RAM, the VIC-II, CIA, SID and CPU registers
+  memory.bin               a memory file of a run (observe with memory "all" or
+                           a size above 4096); --at gives the address of its
+                           first byte when it is shorter than 64 KiB
+  results.json:<name>      the observation <name> of a run; both can be in
+                           one results.json
+
+  --gap N         join changed ranges across at most N equal bytes (default 0)
+  --max-listed N  list at most N ranges of each part (default 64)
+  --ntsc          the snapshots are of an NTSC machine (default PAL)
+  --out <file>    also write all ranges to a project file
+
+The result is one JSON object. Addresses are $ and four hex digits.`;
+
+type Kind = "snapshot" | "memory" | "observation";
+
+function kindOf(path: string): Kind {
+  if (/\.vsf$/i.test(path)) return "snapshot";
+  if (/\.json:[^:]+$/.test(path)) return "observation";
+  if (/\.bin$/i.test(path)) return "memory";
+  throw new UsageError(`${path} is no .vsf, .bin or results.json:<observation>`);
+}
+
+/** The state of one observation of a results.json: its memory items and its registers. */
+function observation(path: string): MachineState {
+  const [file, name] = [path.slice(0, path.lastIndexOf(":")), path.slice(path.lastIndexOf(":") + 1)];
+  let results: { observations?: Record<string, { memory?: Record<string, unknown>; registers?: Record<string, unknown> }> };
+  try {
+    results = JSON.parse(readProjectFile(file).bytes.toString("utf8")) as typeof results;
+  } catch (error) {
+    if (error instanceof WireFailure) throw error;
+    throw new UsageError(`${file} is not JSON: ${(error as Error).message}`);
+  }
+  const seen = results.observations?.[name];
+  if (seen === undefined) throw new UsageError(`${file} has no observation ${name}; it has ${Object.keys(results.observations ?? {}).join(", ") || "none"}`);
+  const observed: Record<string, string> = {};
+  for (const [at, value] of Object.entries(seen.memory ?? {})) {
+    // A memory item in a file of its own: compare its bytes.
+    if (typeof value === "string") observed[at] = value;
+    else if (typeof value === "object" && value !== null && typeof (value as { file?: unknown }).file === "string") {
+      const folder = file.includes("/") ? file.slice(0, file.lastIndexOf("/") + 1) : "";
+      observed[at] = readProjectFile(`${folder}${(value as { file: string }).file}`).bytes.toString("hex");
+    }
+  }
+  const values: Record<string, number> = {};
+  for (const [register, value] of Object.entries(seen.registers ?? {})) {
+    if (typeof value === "number") values[`cpu.${register}`] = value;
+    else if (typeof value === "string" && value.startsWith("$")) values[`cpu.${register}`] = parseC64Address(value);
+  }
+  return { observed, values };
+}
+
+/** The state of a snapshot: restored in the session, then read with the readers of the runs. */
+async function snapshotState(client: ViceSessionClient, path: string): Promise<MachineState> {
+  await client.snapshotRestore(readProjectFile(path).bytes);
+  const memory = await readMemoryInParts(client, 0x0000, 0x10000, "ram");
+  const colorRam = Buffer.from((await client.ioRead(0xd800, 0x400)).data, "hex").map((value) => value & 0x0f);
+  const vic = Buffer.from((await client.ioRead(0xd000, 0x2f)).data, "hex");
+  const values: Record<string, number> = {};
+  vic.forEach((value, index) => (values[`vic.${formatC64Address(0xd000 + index)}`] = value));
+  for (const chip of (await client.cia("both")).chips) {
+    for (const field of ["portA", "portB", "ddrA", "ddrB", "timerA", "timerB", "latchA", "latchB", "controlA", "controlB", "interruptMask"] as const) values[`cia${chip.id}.${field}`] = chip[field];
+  }
+  const sid = await client.sid();
+  for (const voice of sid.voices) for (const [field, value] of Object.entries(voice)) if (field !== "index" && typeof value === "number") values[`sid.voice${voice.index}.${field}`] = value;
+  const registers = await client.registersGet("c64");
+  for (const [field, value] of Object.entries(registers)) if (typeof value === "number") values[`cpu.${field}`] = value;
+  return { memory: { base: 0, bytes: memory }, colorRam, values };
+}
+
+const show = (range: ChangedRange) => ({ start: formatC64Address(range.start), end: formatC64Address(range.end), ...(range.a === undefined ? {} : { a: range.a, b: range.b }) });
+
+async function run(argv: string[]): Promise<Record<string, unknown>> {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    strict: true,
+    allowPositionals: true,
+    options: { gap: { type: "string" }, "max-listed": { type: "string" }, ntsc: { type: "boolean" }, at: { type: "string" }, out: { type: "string" }, help: { type: "boolean" } },
+  });
+  if (values.help) throw new UsageError("");
+  if (positionals.length !== 2) throw new UsageError("give two states to compare");
+  const [first, second] = positionals as [string, string];
+  const kind = kindOf(first);
+  if (kindOf(second) !== kind) throw new UsageError("give two states of one kind: two snapshots, two memory files or two observations");
+  const number = (value: string | undefined, fallback: number, what: string) => {
+    if (value === undefined) return fallback;
+    if (!/^\d+$/.test(value)) throw new UsageError(`${what} must be a whole number`);
+    return Number(value);
+  };
+  const gap = number(values.gap, 0, "--gap");
+  const max = number(values["max-listed"], 64, "--max-listed");
+  if (values.out !== undefined) {
+    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}`);
+    }
+  }
+  let a: MachineState;
+  let b: MachineState;
+  if (kind === "observation") {
+    a = observation(first);
+    b = observation(second);
+  } else if (kind === "memory") {
+    let base = 0;
+    if (values.at !== undefined) {
+      try {
+        base = parseC64Address(values.at);
+      } catch {
+        throw new UsageError(`--at must be $ followed by four hex digits, not ${values.at}`);
+      }
+    }
+    const read = (path: string) => readProjectFile(path).bytes;
+    const [left, right] = [read(first), read(second)];
+    if (left.length !== right.length) throw new UsageError(`the memory files have ${left.length} and ${right.length} bytes; give two of one size`);
+    if (base + left.length > 0x10000) throw new UsageError("the memory file goes past $ffff from --at");
+    a = { memory: { base, bytes: left } };
+    b = { memory: { base, bytes: right } };
+  } else {
+    const client = await ViceSessionClient.open({ videoStandard: values.ntsc ? "ntsc" : "pal" });
+    try {
+      a = await snapshotState(client, first);
+      b = await snapshotState(client, second);
+    } finally {
+      await client.close();
+    }
+  }
+  const diff = diffStates(a, b, gap);
+  const part = (item: { changedBytes: number; ranges: ChangedRange[] } | undefined) =>
+    item === undefined ? undefined : { changedBytes: item.changedBytes, ranges: item.ranges.length, listed: item.ranges.slice(0, max).map(show) };
+  if (values.out !== undefined) {
+    const all = { a: first, b: second, ...(diff.memory === undefined ? {} : { memory: diff.memory.ranges.map(show) }), ...(diff.colorRam === undefined ? {} : { colorRam: diff.colorRam.ranges.map(show) }), values: diff.values ?? [], observed: diff.observed ?? [] };
+    writeProjectFile(values.out, Buffer.from(`${JSON.stringify(all, null, 2)}\n`), { what: "--out" });
+  }
+  return {
+    a: first,
+    b: second,
+    ...(diff.memory === undefined ? {} : { memory: part(diff.memory) }),
+    ...(diff.colorRam === undefined ? {} : { colorRam: part(diff.colorRam) }),
+    ...(diff.values === undefined ? {} : { registers: diff.values.slice(0, max) }),
+    ...(diff.observed === undefined ? {} : { observed: diff.observed.slice(0, max) }),
+    ...(values.out === undefined ? {} : { out: values.out }),
+  };
+}
+
+await runScript(run, { usage: USAGE });

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

@@ -0,0 +1,70 @@
+// The differences between two machine states: changed ranges of RAM and
+// colour RAM, and changed chip registers and CPU registers. The states come
+// from snapshots that VICE restores, from memory files, or from the
+// observations of runs; this file only compares.
+
+export interface MachineState {
+  /** Bytes from `base`: all 64 KiB of RAM, or the bytes of one memory file. */
+  memory?: { base: number; bytes: Uint8Array };
+  /** Colour RAM $D800-$DBFF, the low 4 bits of each byte. */
+  colorRam?: Uint8Array;
+  /** Named single values: VIC-II, CIA and SID registers and the CPU registers, as "vic.$d011", "cia1.timerA", "cpu.pc". */
+  values?: Record<string, number>;
+  /** The memory items of an observation of a run: the address or name, and its bytes as hex. */
+  observed?: Record<string, string>;
+}
+
+export interface ChangedRange {
+  start: number;
+  end: number;
+  /** The bytes of both states, as hex, when the range has at most 16 bytes. */
+  a?: string;
+  b?: string;
+}
+
+export interface StateDiff {
+  memory?: { changedBytes: number; ranges: ChangedRange[] };
+  colorRam?: { changedBytes: number; ranges: ChangedRange[] };
+  values?: Array<{ name: string; a: number; b: number }>;
+  observed?: Array<{ at: string; a: string; b: string }>;
+}
+
+/** Changed ranges of two byte arrays of one length, joined across gaps of at most `gap` equal bytes. */
+export function changedRanges(a: Uint8Array, b: Uint8Array, base: number, gap = 0): { changedBytes: number; ranges: ChangedRange[] } {
+  const ranges: ChangedRange[] = [];
+  let changedBytes = 0;
+  for (let offset = 0; offset < a.length; offset++) {
+    if (a[offset] === b[offset]) continue;
+    changedBytes++;
+    const last = ranges.at(-1);
+    if (last !== undefined && base + offset - last.end - 1 <= gap) last.end = base + offset;
+    else ranges.push({ start: base + offset, end: base + offset });
+  }
+  for (const range of ranges) {
+    if (range.end - range.start + 1 > 16) continue;
+    range.a = Buffer.from(a.subarray(range.start - base, range.end - base + 1)).toString("hex");
+    range.b = Buffer.from(b.subarray(range.start - base, range.end - base + 1)).toString("hex");
+  }
+  return { changedBytes, ranges };
+}
+
+/** What differs between two states, for each part that both have. */
+export function diffStates(a: MachineState, b: MachineState, gap = 0): StateDiff {
+  const result: StateDiff = {};
+  if (a.memory !== undefined && b.memory !== undefined) {
+    if (a.memory.base !== b.memory.base || a.memory.bytes.length !== b.memory.bytes.length) throw new Error("the two memory parts do not cover the same addresses");
+    result.memory = changedRanges(a.memory.bytes, b.memory.bytes, a.memory.base, gap);
+  }
+  if (a.colorRam !== undefined && b.colorRam !== undefined) result.colorRam = changedRanges(a.colorRam, b.colorRam, 0xd800, gap);
+  if (a.values !== undefined && b.values !== undefined) {
+    result.values = Object.keys(a.values)
+      .filter((name) => b.values![name] !== undefined && a.values![name] !== b.values![name])
+      .map((name) => ({ name, a: a.values![name]!, b: b.values![name]! }));
+  }
+  if (a.observed !== undefined && b.observed !== undefined) {
+    result.observed = Object.keys(a.observed)
+      .filter((at) => b.observed![at] !== undefined && a.observed![at] !== b.observed![at])
+      .map((at) => ({ at, a: a.observed![at]!, b: b.observed![at]! }));
+  }
+  return result;
+}

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

@@ -3,14 +3,15 @@
 // Observations name semantic symbols that resolve per side, comparisons are
 // explicit, and the result is PASS, FAIL or INCONCLUSIVE.
 
-import { formatC64Address, parseC64Address } from "#src/c64.ts";
-import { MAX_BASELINES, MAX_MASK_RECTANGLES, MAX_MEMORY_READ, maskCoversFrame, WireFailure } from "#src/host-client/tools.ts";
+import { 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 type { ViceSessionClient } from "#src/host-client/vice-session.ts";
+import { readMemoryInParts, type ViceSessionClient } from "#src/host-client/vice-session.ts";
 import { openForRead } from "#src/knowledge/database.ts";
-import { listSymbols } from "#src/knowledge/read.ts";
+import { listAnalyzerNames, listSymbols } from "#src/knowledge/read.ts";
+import { programImage } from "#src/knowledge/program.ts";
 
 export class ScenarioError extends Error {}
 
@@ -22,11 +23,13 @@ export type { Location };
 
 export interface MemoryObservation {
   at: Location;
-  /** Bytes from `at`; 1 when not given. */
+  /** Bytes from `at`; 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 (D46). */
+  /** Bytes in the range that the comparison leaves out, each with the reason. */
   exclude?: Array<{ at: Location; reason: string }>;
 }
 
@@ -42,16 +45,16 @@ type StepBody =
   | { load: true }
   | { autostart: true }
   | { snapshot: string }
-  | { normalize: string }
+  | { normalize: true }
   | ActionStep
   | { observe: string; memory?: Array<Location | MemoryObservation>; registers?: ObservedRegister[]; screen?: ScreenPolicy; vicii?: boolean; sprites?: number[] };
 
-/** A step; with side, only that side does it (D46). An observe step has no side: it compares both. */
+/** A step; with side, only that side does it. An observe step has no side: it compares both. */
 export type Step = StepBody & { side?: Side };
 
 export interface Subject {
   program: string;
-  /** "knowledge" for knowledge.db, a project JSON file (c64-assembler output or a name → "$xxxx" map), or "none". */
+  /** "knowledge" for the project knowledge, a project JSON file (c64-assembler output or a name → "$xxxx" map), or "none". */
   symbols: string;
 }
 
@@ -79,7 +82,7 @@ export interface ScenarioResult {
   reason?: string;
   checkpoints: string[];
   differences: Difference[];
-  /** The bytes that the comparison left out, with their reasons (D46). */
+  /** The bytes that the comparison left out, with their reasons. */
   excluded?: Array<{ checkpoint: string; at: Location; reason: string }>;
   /** The files that a FAIL wrote with --out. */
   files?: string[];
@@ -155,7 +158,7 @@ function checkStep(kind: string, step: Record<string, unknown>, at: string, fail
       if (typeof step.snapshot !== "string" || step.snapshot === "") fail(`${at}: snapshot needs a .vsf file in the project`);
       return;
     case "normalize":
-      if (typeof step.normalize !== "string" || step.normalize === "") fail(`${at}: normalize needs an entry state file in the project`);
+      if (step.normalize !== true) fail(`${at}: normalize is true: it writes the entry state of the knowledge`);
       return;
     case "write":
     case "registers":
@@ -178,7 +181,8 @@ function checkObserve(step: Record<string, unknown>, at: string, fail: (message:
         checkLocation(item, `${at}: memory`, fail);
         continue;
       }
-      if (!isObject(item) || Object.keys(item).some((key) => !["at", "size", "tolerance", "exclude"].includes(key))) return fail(`${at}: a memory object has at, size, tolerance and exclude, and nothing else`);
+      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 (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`);
         for (const excluded of item.exclude as unknown[]) {
@@ -188,7 +192,7 @@ function checkObserve(step: Record<string, unknown>, at: string, fail: (message:
         }
       }
       checkLocation(item.at, `${at}: memory.at`, fail);
-      if (item.size !== undefined && !isInteger(item.size, 1, MAX_MEMORY_READ)) fail(`${at}: memory.size must be a number from 1 to ${MAX_MEMORY_READ}`);
+      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`);
     }
   }
@@ -216,7 +220,7 @@ function checkObserve(step: Record<string, unknown>, at: string, fail: (message:
           isInteger(rectangle.height, 1, 4096);
         if (!ok) fail(`${at}: a screen.mask rectangle needs whole numbers x and y from 0, and width and height from 1`);
       }
-      // The emulator refuses such a compare too, but only after the original side ran (b2/03).
+      // The emulator refuses such a compare too, but only after the original side ran.
       if (maskCoversFrame(screen.mask as Array<{ x: number; y: number; width: number; height: number }>, videoStandard)) fail(`${at}: screen.mask covers the whole screen, so nothing is compared`);
     }
   }
@@ -236,6 +240,10 @@ export function loadSymbols(subject: Subject): Map<string, number> {
   if (subject.symbols === "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;
   }
@@ -248,11 +256,12 @@ export function loadSymbols(subject: Subject): Map<string, number> {
   // 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?: number }> }).symbols;
+  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]];
-        if (Number.isInteger(symbol.value) && symbol.value! >= 0 && symbol.value! <= 0xffff) return [[symbol.name, formatC64Address(symbol.value!)]];
+        // 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]];
         return [];
       })
     : Object.entries(value as Record<string, unknown>);
@@ -288,24 +297,25 @@ interface Observation {
   screen?: { match: boolean; mismatchingPixels: number; comparedPixels: number; mismatchRatio: number; bounds?: unknown };
   vicii?: unknown;
   sprites?: unknown;
-  /** PNG images for the files of a FAIL (D46): the side's screen, and on the rebuild the difference image. */
+  /** PNG images for the files of a FAIL: the side's screen, and on the rebuild the difference image. */
   png?: string;
   diffPng?: string;
 }
 
-/** Writes pages 0-3 and $00/$01 from an entry state file (D43, D46): both sides then start from the same RAM. */
-async function normalize(client: ViceSessionClient, path: string): Promise<void> {
-  let state: { pages?: Record<string, string>; cpuPort?: Record<string, number> };
+/** 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;
   try {
-    state = JSON.parse(readProjectFile(path).bytes.toString("utf8")) as typeof state;
-  } catch (error) {
-    if (error instanceof WireFailure) throw error;
-    throw new ScenarioError(`${path} is not an entry state file: ${(error as Error).message}`);
+    state = programImage(db)?.state as typeof 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(`${path} is not an entry state file: it needs pages $0000 to $0300 and cpuPort $00 and $01`);
+    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.
@@ -348,7 +358,7 @@ async function runSide(client: ViceSessionClient, scenario: Scenario, side: Side
         const spec: MemoryObservation = typeof item === "string" ? { at: item } : item;
         const address = at(spec.at);
         const size = spec.size ?? 1;
-        const read = await client.memoryRead({ address, size, space: "c64", view: "cpu" });
+        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)`);
@@ -358,14 +368,14 @@ async function runSide(client: ViceSessionClient, scenario: Scenario, side: Side
       }
       if (step.registers !== undefined) {
         const registers = await client.registersGet("c64");
-        for (const name of step.registers) observation.registers[name] = registers[name];
+        for (const name of step.registers) observation.registers[name] = name === "pc" ? formatC64Address(registers.pc) : registers[name];
       }
       if (step.vicii) {
         // The raster line changes from one moment to the next; the comparison leaves it out.
         const { rasterLine: _rasterLine, ...state } = await client.vicii();
-        observation.vicii = state;
+        observation.vicii = formatVicii(state);
       }
-      if (step.sprites !== undefined) observation.sprites = (await client.sprites(step.sprites)).sprites;
+      if (step.sprites !== undefined) observation.sprites = (await client.sprites(step.sprites)).sprites.map(formatSprite);
       if (step.screen !== undefined) {
         const baseline = baselineName(checkpoint, step.observe);
         if (side === "original") {
@@ -392,7 +402,7 @@ async function runSide(client: ViceSessionClient, scenario: Scenario, side: Side
     } else if ("snapshot" in step) {
       await client.snapshotRestore(readProjectFile(step.snapshot).bytes);
     } else if ("normalize" in step) {
-      await normalize(client, step.normalize);
+      await normalize(client);
     } else {
       const { side: _side, ...action } = step;
       const notReached = await runActionStep(client, action as ActionStep, at);
@@ -413,7 +423,7 @@ export function compare(original: Map<string, Observation>, rebuild: Map<string,
       const other = right.memory[index]!;
       const skipped = new Set(item.excluded.map((excluded) => excluded.offset));
       if (item.bytes.some((byte, at) => !skipped.has(at) && Math.abs(byte - other.bytes[at]!) > item.tolerance)) {
-        const show = (bytes: number[]) => (bytes.length === 1 ? bytes[0] : Buffer.from(bytes).toString("hex"));
+        const show = (bytes: number[]) => Buffer.from(bytes).toString("hex");
         differences.push({ checkpoint, what: `memory ${item.label}`, original: show(item.bytes), rebuild: show(other.bytes) });
       }
     });
@@ -430,7 +440,7 @@ export function compare(original: Map<string, Observation>, rebuild: Map<string,
 }
 
 /**
- * Writes the files of a FAIL into `out` (D46): for a screen difference both
+ * 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[] {
@@ -439,7 +449,8 @@ function writeFailFiles(out: string, original: Map<string, Observation>, rebuild
     writeProjectFile(`${out}/${name}`, bytes, { what: "--out" });
     files.push(name);
   };
-  const memory: Array<{ checkpoint: string; what: string; bytes: Array<{ address: string; original: number; rebuild: number }> }> = [];
+  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");
   for (const difference of differences) {
     const left = original.get(difference.checkpoint)!;
     const right = rebuild.get(difference.checkpoint)!;
@@ -454,7 +465,7 @@ function writeFailFiles(out: string, original: Map<string, Observation>, rebuild
       const item = left.memory[index]!;
       const other = right.memory[index]!;
       const skipped = new Set(item.excluded.map((excluded) => excluded.offset));
-      const bytes = item.bytes.flatMap((byte, offset) => (!skipped.has(offset) && Math.abs(byte - other.bytes[offset]!) > item.tolerance ? [{ address: formatC64Address(item.address + offset), original: byte, rebuild: other.bytes[offset]! }] : []));
+      const bytes = item.bytes.flatMap((byte, offset) => (!skipped.has(offset) && Math.abs(byte - other.bytes[offset]!) > item.tolerance ? [{ address: formatC64Address(item.address + offset), original: hex(byte), rebuild: hex(other.bytes[offset]!) }] : []));
       memory.push({ checkpoint: difference.checkpoint, what: difference.what, bytes });
     }
   }