@henols/c64-re-tools 1.1.0 → 2.0.0-rc.11

package/skills/c64-static-analysis/scripts/idioms.ts

@@ -0,0 +1,149 @@
+// 6502 idioms that hide code from a disassembler (D44): RTS dispatch tables,
+// JMP tables and BIT skips are found by their exact instruction patterns and
+// become heuristic findings and entry points; DOP padding and self-modified
+// opcodes are only reported. A self-modified opcode is one that one run wrote
+// and executed, in either order, since a coverage file holds no order (R3-04):
+// a copier's writes in one run and their execution in another do not count (F-16). A table's length is not known statically: entries
+// count while each target is a plausible instruction in the program.
+
+import { COVERAGE } from "#src/c64.ts";
+import { joinCoverage } from "#src/host-client/coverage.ts";
+import type { NormalizedFindings } from "#src/knowledge/import.ts";
+import type { ImageByte } from "./coverage.ts";
+
+const MAX_TABLE = 64;
+const MIN_JUMPS = 3;
+const LDA_INDEXED = new Set([0xbd, 0xb9]);
+const JAMS = new Set([0x02, 0x12, 0x22, 0x32, 0x42, 0x52, 0x62, 0x72, 0x92, 0xb2, 0xd2, 0xf2]);
+/** Undocumented NOPs with an operand byte (DOP): padding between instructions hides the real ones. */
+const DOPS = new Set([0x04, 0x14, 0x34, 0x44, 0x54, 0x64, 0x74, 0x80, 0x82, 0x89, 0xc2, 0xd4, 0xe2, 0xf4]);
+
+export interface Idioms {
+  findings: NormalizedFindings;
+  /** Entry points for the same analysis run: analyzer facts are never seeds. */
+  entryPoints: number[];
+  /** Table ranges for the same run: they are data. */
+  dataRanges: Array<{ start: number; end: number }>;
+  counts: { rtsTables: number; jumpTables: number; bitSkips: number };
+  /** Seen in the coverage, not written: the LLM decides. All of them: the result lists the first ones. */
+  candidates: { dop: number[]; selfModified: number[] };
+}
+
+/** True when an instruction can start at the address: inside the program, and no JAM. */
+function plausible(byteAt: ImageByte, address: number, range: { start: number; end: number }): boolean {
+  const opcode = byteAt(address);
+  return address >= range.start && address <= range.end && opcode !== undefined && !JAMS.has(opcode);
+}
+
+const word = (byteAt: ImageByte, address: number) => {
+  const low = byteAt(address);
+  const high = byteAt(address + 1);
+  return low === undefined || high === undefined ? undefined : low | (high << 8);
+};
+
+/** `runs` are the coverage maps, one for each file. */
+export function findIdioms(byteAt: ImageByte, range: { start: number; end: number }, runs: readonly Uint8Array[] = []): Idioms {
+  const coverage = runs.length === 0 ? undefined : joinCoverage(runs);
+  const regions: NormalizedFindings["regions"] = [];
+  const references: NormalizedFindings["references"] = [];
+  const entryPoints = new Set<number>();
+  const counts = { rtsTables: 0, jumpTables: 0, bitSkips: 0 };
+  const taken = (start: number, end: number) => regions.some((region) => start <= region.end && end >= region.start);
+  const addRegion = (start: number, end: number, type: NormalizedFindings["regions"][number]["type"]) => {
+    if (start < range.start || end > range.end || taken(start, end)) return false;
+    regions.push({ start, end, type });
+    return true;
+  };
+
+  for (let at = range.start; at + 8 <= range.end; at++) {
+    // RTS dispatch: LDA high,X / PHA / LDA low,X / PHA / RTS.
+    if (LDA_INDEXED.has(byteAt(at)!) && byteAt(at + 3) === 0x48 && LDA_INDEXED.has(byteAt(at + 4)!) && byteAt(at + 7) === 0x48 && byteAt(at + 8) === 0x60) {
+      const high = word(byteAt, at + 1)!;
+      const low = word(byteAt, at + 5)!;
+      const interleaved = high === low + 1;
+      const step = interleaved ? 2 : 1;
+      const targets: number[] = [];
+      for (let index = 0; index < MAX_TABLE; index++) {
+        const lowByte = byteAt(low + index * step);
+        const highByte = byteAt(high + index * step);
+        if (lowByte === undefined || highByte === undefined) break;
+        const target = ((highByte << 8) | lowByte) + 1;
+        if (!plausible(byteAt, target, range)) break;
+        targets.push(target);
+      }
+      if (targets.length === 0) continue;
+      const n = targets.length;
+      const written = interleaved
+        ? addRegion(low, low + 2 * n - 1, "rts-addresses")
+        : low + n === high
+          ? addRegion(low, high + n - 1, "rts-addresses-split")
+          : addRegion(low, low + n - 1, "bytes") && addRegion(high, high + n - 1, "bytes");
+      if (!written) continue;
+      counts.rtsTables++;
+      for (const target of targets) {
+        references.push({ from: at + 8, to: target, kind: "jump" });
+        entryPoints.add(target);
+      }
+    }
+  }
+
+  // JMP tables: at least three JMP abs in a row.
+  for (let at = range.start; at + 3 * MIN_JUMPS - 1 <= range.end; at++) {
+    let n = 0;
+    while (at + 3 * n + 2 <= range.end && byteAt(at + 3 * n) === 0x4c) n++;
+    if (n < MIN_JUMPS || !addRegion(at, at + 3 * n - 1, "jumps")) continue;
+    counts.jumpTables++;
+    for (let index = 0; index < n; index++) {
+      entryPoints.add(at + 3 * index);
+      const target = word(byteAt, at + 3 * index + 1)!;
+      if (plausible(byteAt, target, range)) entryPoints.add(target);
+    }
+    at += 3 * n - 1;
+  }
+
+  // BIT skips: BIT abs ($2c) whose operand bytes are an instruction that a JMP, a JSR or the coverage enters.
+  const entered = new Set<number>();
+  for (let at = range.start; at + 2 <= range.end; at++) {
+    if (byteAt(at) === 0x4c || byteAt(at) === 0x20) entered.add(word(byteAt, at + 1)!);
+  }
+  if (coverage !== undefined) for (let address = range.start; address <= range.end; address++) if ((coverage[address]! & COVERAGE.ramExecute) !== 0) entered.add(address);
+  for (let at = range.start; at + 2 <= range.end; at++) {
+    if (byteAt(at) !== 0x2c || !entered.has(at + 1) || !plausible(byteAt, at + 1, range)) continue;
+    if (!addRegion(at + 1, at + 2, "dual-use")) continue;
+    counts.bitSkips++;
+    entryPoints.add(at);
+    entryPoints.add(at + 1);
+    for (let from = range.start; from + 2 <= range.end; from++) {
+      if ((byteAt(from) === 0x4c || byteAt(from) === 0x20) && word(byteAt, from + 1) === at + 1) references.push({ from, to: at + 1, kind: byteAt(from) === 0x20 ? "call" : "jump" });
+    }
+  }
+
+  // Candidates from the coverage: DOP padding that ran, and opcodes that one run wrote and executed.
+  const candidates = { dop: [] as number[], selfModified: [] as number[] };
+  if (coverage !== undefined) {
+    const both = COVERAGE.ramWrite | COVERAGE.ramExecute;
+    for (let address = range.start; address <= range.end; address++) {
+      if ((coverage[address]! & COVERAGE.ramExecute) === 0) continue;
+      if (DOPS.has(byteAt(address)!)) candidates.dop.push(address);
+      if (runs.some((run) => (run[address]! & both) === both)) candidates.selfModified.push(address);
+    }
+  }
+
+  regions.sort((a, b) => a.start - b.start);
+  const dataRanges = regions.filter((region) => region.type !== "jumps" && region.type !== "dual-use").map(({ start, end }) => ({ start, end }));
+  return {
+    findings: {
+      analyzer: "heuristic",
+      coverage: [range],
+      authoritative: { symbols: true, regions: true, references: true },
+      symbols: [],
+      regions,
+      // Each reference once: the importer keys them by from, to and kind.
+      references: [...new Map(references.map((reference) => [`${reference.from}|${reference.to}|${reference.kind}`, reference])).values()],
+    },
+    entryPoints: [...entryPoints].sort((a, b) => a - b),
+    dataRanges,
+    counts,
+    candidates,
+  };
+}

package/skills/c64-static-analysis/scripts/instructions.ts

@@ -0,0 +1,105 @@
+// The structured instruction list (D44): Ghidra's decoded instructions with
+// the addressing mode, the operand in 6502 syntax, the flow target and,
+// with a coverage file, whether the instruction ran.
+
+import { COVERAGE, formatC64Address } from "#src/c64.ts";
+import type { GhidraInstruction } from "#src/native/types.ts";
+
+export type Mode =
+  | "implied"
+  | "accumulator"
+  | "immediate"
+  | "zeropage"
+  | "zeropage,x"
+  | "zeropage,y"
+  | "absolute"
+  | "absolute,x"
+  | "absolute,y"
+  | "(indirect)"
+  | "(indirect,x)"
+  | "(indirect),y"
+  | "relative";
+
+const BRANCHES = new Set([0x10, 0x30, 0x50, 0x70, 0x90, 0xb0, 0xd0, 0xf0]);
+const JMP_INDIRECT = 0x6c;
+
+/**
+ * The addressing mode from Ghidra's operand text and the instruction length.
+ * Ghidra prints zero page and absolute alike, and JMP (indirect) as an
+ * address, so the length and the opcode decide those.
+ */
+export function modeOf(opcode: number, length: number, operands: string): Mode {
+  const text = operands.toUpperCase();
+  if (text === "") return "implied";
+  if (text === "A") return "accumulator";
+  if (text.startsWith("#")) return "immediate";
+  if (text.startsWith("(") && text.endsWith(",X)")) return "(indirect,x)";
+  if (text.startsWith("(") && text.endsWith("),Y")) return "(indirect),y";
+  if (text.endsWith(",X")) return length === 2 ? "zeropage,x" : "absolute,x";
+  if (text.endsWith(",Y")) return length === 2 ? "zeropage,y" : "absolute,y";
+  if (BRANCHES.has(opcode)) return "relative";
+  if (opcode === JMP_INDIRECT) return "(indirect)";
+  return length === 2 ? "zeropage" : "absolute";
+}
+
+/** The operand in 6502 syntax, from the instruction bytes; empty for implied. */
+export function operandText(mode: Mode, bytes: Uint8Array, target: number | undefined): string {
+  const byte = `$${(bytes[1] ?? 0).toString(16).padStart(2, "0")}`;
+  const word = formatC64Address((bytes[1] ?? 0) | ((bytes[2] ?? 0) << 8));
+  switch (mode) {
+    case "implied":
+      return "";
+    case "accumulator":
+      return "a";
+    case "immediate":
+      return `#${byte}`;
+    case "zeropage":
+      return byte;
+    case "zeropage,x":
+      return `${byte},x`;
+    case "zeropage,y":
+      return `${byte},y`;
+    case "absolute":
+      return word;
+    case "absolute,x":
+      return `${word},x`;
+    case "absolute,y":
+      return `${word},y`;
+    case "(indirect)":
+      return `(${word})`;
+    case "(indirect,x)":
+      return `(${byte},x)`;
+    case "(indirect),y":
+      return `(${byte}),y`;
+    case "relative":
+      return target === undefined ? byte : formatC64Address(target);
+  }
+}
+
+export interface ListedInstruction {
+  address: string;
+  bytes: string;
+  mnemonic: string;
+  mode: Mode;
+  operand: string;
+  target?: string;
+  executed?: boolean;
+}
+
+/** Ghidra's instructions as the list that --instructions writes. */
+export function instructionList(instructions: GhidraInstruction[], coverage?: Uint8Array): ListedInstruction[] {
+  return instructions.map((instruction) => {
+    const bytes = Buffer.from(instruction.bytes, "hex");
+    const mode = modeOf(bytes[0]!, bytes.length, instruction.operands);
+    const [target] = instruction.flows;
+    return {
+      address: formatC64Address(instruction.address),
+      bytes: (instruction.bytes.match(/../g) ?? []).join(" "),
+      mnemonic: instruction.mnemonic,
+      mode,
+      operand: operandText(mode, bytes, target),
+      ...(target === undefined ? {} : { target: formatC64Address(target) }),
+      ...(coverage === undefined ? {} : { executed: (coverage[instruction.address]! & COVERAGE.ramExecute) !== 0 }),
+    };
+  });
+}

package/skills/c64-static-analysis/scripts/pointers.ts

@@ -0,0 +1,108 @@
+// Pointer candidates (D65): code that builds an address from immediates. The
+// byte of each immediate is the low or high byte of the address, so a rebuild
+// that moves the address needs an operand expression there. They are only
+// reported, never written: the LLM records the expressions with c64-knowledge.
+//
+// The scan reads short straight runs of instructions: LDA/LDX/LDY #imm and
+// STA/STX/STY to zero page or absolute, plus SEI, CLI, CLC, SEC and NOP. Any
+// other instruction ends the run, so no register value is guessed across it.
+
+import { instructionLength } from "#src/c64.ts";
+import type { ImageByte } from "./coverage.ts";
+
+const LOADS: Record<number, "a" | "x" | "y"> = { 0xa9: "a", 0xa2: "x", 0xa0: "y" };
+const STORES: Record<number, "a" | "x" | "y"> = { 0x85: "a", 0x8d: "a", 0x86: "x", 0x8e: "x", 0x84: "y", 0x8c: "y" };
+const NEUTRAL = new Set([0x78, 0x58, 0x18, 0x38, 0xea]);
+/** The instructions of one run: enough for two loads, two stores and a few neutral ones. */
+const MAX_RUN = 8;
+/** The vectors that the KERNAL and the CPU read: IRQ, BRK, NMI, and the hardware vectors. */
+const VECTORS = new Set([0x0314, 0x0316, 0x0318, 0xfffa, 0xfffc, 0xfffe]);
+/** (zp),y: ORA AND EOR ADC STA LDA CMP SBC. */
+const INDIRECT_Y = new Set([0x11, 0x31, 0x51, 0x71, 0x91, 0xb1, 0xd1, 0xf1]);
+/** The sprite pointers of the default screen at $0400 in VIC bank 0. */
+const SPRITE_POINTERS = { start: 0x07f8, end: 0x07ff };
+
+export type PointerCandidate =
+  | {
+      kind: "vector" | "zero-page pointer";
+      /** The vector or zero-page pair that gets the address. */
+      to: number;
+      /** The address that the two immediates make. */
+      target: number;
+      /** The instructions with the low and the high byte as immediate. */
+      low: number;
+      high: number;
+    }
+  | {
+      kind: "sprite pointer";
+      to: number;
+      /** value × 64: the sprite data, in VIC bank 0. */
+      target: number;
+      /** The instruction with the pointer as immediate. */
+      at: number;
+      value: number;
+    };
+
+interface Store {
+  /** The address of the load of the immediate. */
+  load: number;
+  value: number;
+  to: number;
+}
+
+/** The stores of immediates in the straight run that starts at `start`. */
+function storesFrom(byteAt: ImageByte, start: number, range: { start: number; end: number }): Store[] {
+  const last: Partial<Record<"a" | "x" | "y", { load: number; value: number }>> = {};
+  const stores: Store[] = [];
+  let at = start;
+  for (let count = 0; count < MAX_RUN; count++) {
+    const opcode = byteAt(at);
+    if (opcode === undefined) break;
+    const length = instructionLength(opcode);
+    if (at + length - 1 > range.end) break;
+    const operand = length === 2 ? byteAt(at + 1)! : length === 3 ? byteAt(at + 1)! | (byteAt(at + 2)! << 8) : 0;
+    if (LOADS[opcode] !== undefined) last[LOADS[opcode]] = { load: at, value: operand };
+    else if (STORES[opcode] !== undefined) {
+      const loaded = last[STORES[opcode]];
+      if (loaded === undefined) break;
+      stores.push({ ...loaded, to: operand });
+    } else if (!NEUTRAL.has(opcode)) break;
+    at += length;
+  }
+  return stores;
+}
+
+/**
+ * Finds the pointer candidates in the image: an immediate pair stored to a
+ * vector or to a zero-page pair that (zp),y uses, where the pair makes an
+ * address in the image or a platform name; and an immediate stored to a sprite
+ * pointer of the default screen whose sprite data is in a sprite region.
+ */
+export function findPointers(
+  byteAt: ImageByte,
+  range: { start: number; end: number },
+  known: { platform: (address: number) => boolean; sprites: ReadonlyArray<{ start: number; end: number }> },
+): PointerCandidate[] {
+  const indirect = new Set<number>();
+  for (let at = range.start; at < range.end; at++) if (INDIRECT_Y.has(byteAt(at)!)) indirect.add(byteAt(at + 1)!);
+  const inImage = (address: number) => address >= range.start && address <= range.end && byteAt(address) !== undefined;
+  const found = new Map<string, PointerCandidate>();
+  for (let at = range.start; at <= range.end; at++) {
+    if (LOADS[byteAt(at)!] === undefined) continue;
+    const stores = storesFrom(byteAt, at, range);
+    for (const low of stores) {
+      const high = stores.find((store) => store.to === low.to + 1);
+      const target = high === undefined ? undefined : low.value | (high.value << 8);
+      const kind = VECTORS.has(low.to) ? "vector" : low.to < 0xff && indirect.has(low.to) ? "zero-page pointer" : undefined;
+      if (high !== undefined && target !== undefined && kind !== undefined && (inImage(target) || known.platform(target))) {
+        found.set(`${low.load}|${high.load}`, { kind, to: low.to, target, low: low.load, high: high.load });
+      }
+      const sprite = low.value * 64;
+      if (low.to >= SPRITE_POINTERS.start && low.to <= SPRITE_POINTERS.end && known.sprites.some((region) => sprite >= region.start && sprite <= region.end)) {
+        found.set(`${low.load}`, { kind: "sprite pointer", to: low.to, target: sprite, at: low.load, value: low.value });
+      }
+    }
+  }
+  const first = (candidate: PointerCandidate) => (candidate.kind === "sprite pointer" ? candidate.at : Math.min(candidate.low, candidate.high));
+  return [...found.values()].sort((a, b) => first(a) - first(b));
+}

package/skills/c64-testing/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: c64-testing
+description: Use this skill to test if a rebuilt or changed C64 program behaves as the original. It runs one scenario on the original and then on the rebuild in an emulator. It compares memory, registers, chip state and the screen with explicit rules, and gives PASS, FAIL or INCONCLUSIVE. It also makes a checklist for a human playtest. Use its run command to explore a program with many steps, for example to visit each room or level. A run keeps screens, coverage maps and snapshots as files. Do not use it to find the cause of a difference.
+---
+
+# c64-testing
+
+## Purpose
+
+Test if a rebuild or a changed program behaves as the original in a scenario. Give one result: PASS, FAIL or INCONCLUSIVE.
+
+A PASS proves only the behavior that the scenario does and observes. It does not prove that the two programs are equal in all behavior.
+
+## Inputs
+
+- The original program and the rebuild: PRG files in the project.
+- The symbols of each side. For the original, the project knowledge. For the rebuild, the JSON output of the c64-assembler skill in a file.
+- A scenario file: the steps, the checkpoints and the observations. See [references/scenario-format.md](references/scenario-format.md).
+
+## Tools / execution path
+
+The script starts one emulator through the host runtime. It runs the scenario on the original and then on the rebuild. Before each side, it does a hard reset of the emulator. The CPU then stops at the reset vector.
+
+```
+node <skill>/scripts/test.ts tests/moves-left.json --out results/moves-left
+node <skill>/scripts/checklist.ts tests/moves-left.json --item 'FIRE starts the game.'
+```
+
+The test script prints one JSON object. The exit status is 0 for PASS, 1 for FAIL, 3 for INCONCLUSIVE and 2 for a bad call. With `--out`, a FAIL writes files into that directory: both screens and the difference image for each screen difference, and `memory.json` with each byte that differs. `files` in the result names them.
+
+The checklist script prints a Markdown checklist for a human tester.
+
+### Runs
+
+A run does steps on one program, with no comparison, and keeps the results as files. Use it for many steps. One run replaces many emulator calls, for example a visit to each room of a game.
+
+```
+node <skill>/scripts/run.ts runs/rooms.json --out runs/rooms
+```
+
+The run file gives where to start (a program, or a snapshot file), the steps, and optional symbols. To go on from the live emulator, save its state with `c64_snapshot` action `save` and `out`, and start the run from that file. Besides the steps of a scenario, a run has these steps:
+
+| Step | Effect |
+|---|---|
+| `{ "snapshot": "snapshots/room0.vsf" }` | Restore a snapshot file. |
+| `{ "save": "room3" }` | Write the state now to `room3.vsf` in the output directory. |
+| `{ "screen": "room3" }` | Write the screen to `room3.png`. |
+| `{ "coverage": "room3" }` | Write the coverage map since the start or the last coverage step to `room3.bin`, then clear the map. |
+| `{ "observe": "room3", "memory": ["$c100"], "registers": true }` | Record memory, registers, `vicii` or `sprites` in `results.json`. |
+
+See [references/scenario-format.md](references/scenario-format.md), section Runs. The script prints one JSON object. The exit status is 0 when all steps ran, 1 when a step did not reach its target, and 2 for a bad call. A long run can need more time than one shell call. Then run it in the background.
+
+## Workflow
+
+1. Write the scenario file. Start the steps with a frame count, for example `{ "frames": 150 }`. Each side starts at the reset vector, and the C64 needs these frames to start.
+2. Use symbol names, for example `player_x`, not fixed addresses. Each side finds the name in its own symbols. Use a `$` address only when both programs use the same address.
+3. Make each checkpoint a condition, for example `runUntil` at a routine. Do not wait for a time.
+4. Save the c64-assembler output of the rebuild to the symbol file: `assemble.ts ... > build/game.json`.
+5. Run the test script.
+6. Read the result:
+   - `PASS`: all observations are equal, or the differences are in the allowed tolerance.
+   - `FAIL`: `differences` lists each difference with the checkpoint, the item, the original value and the rebuild value.
+   - `INCONCLUSIVE`: `reason` tells why the script could not compare. This is not a failure of the program.
+7. For a FAIL, examine the first difference with the c64-emulator skill.
+
+## Knowledge
+
+Read:
+- the symbols of the original from the project knowledge.
+
+Automatic write:
+- none.
+
+Do not store:
+- test results
+- screenshots
+- playtest results.
+
+## Result
+
+PASS, FAIL or INCONCLUSIVE, the checkpoints and the smallest differences that explain a FAIL.
+
+## Failure and conflicts
+
+- `invalid-input`: the scenario file has an error. The message names the step. Change the step and run the test again.
+- INCONCLUSIVE, "did not reach the checkpoint": one side did not reach the checkpoint in the frame limit. Find the reason with the c64-emulator skill. Do not report a FAIL.
+- INCONCLUSIVE, "has no symbol": one side has no symbol with that name. Add the name to the knowledge or to the rebuild source.
+- INCONCLUSIVE, "no emulator" or "could not run": the host runtime or the emulator failed. Tell the user the message.
+- `installation-incomplete`, or `machine-unavailable` with a message that the host runtime does not run: stop the task. Give the message to the user and wait for the user. The message gives the remedy. Do not make a replacement for the tool or the host runtime, for example your own disk parser, disassembler or emulator script.
+- A FAIL with only a `screen` difference: add `vicii` or `sprites` to the observation to find which chip state is different.
+- A program that uses random numbers: set the random seed with a `write` step on both sides. If that is not possible, observe only values that do not depend on the random numbers.
+- The two sides start differently, for example the original after a cracked intro. Give the steps that only one side needs a `side`. Then make the memory the same with a `normalize` step from the entry state of the c64-unpacker skill.
+- Frame counts drift by one frame between the sides: the sides got to the same address at different raster positions. Do not sync on an IRQ handler. Sync on a value that the IRQ changes, with `runUntil` `memory`, or on an address and a raster line together.
+- A byte that cannot be the same on both sides, for example a read-only collision register: use `exclude` with the reason. Do not use `exclude` to hide a real difference.
+
+Do not add a mask or a tolerance only to make a test pass. A tolerance must have a reason in the behavior of the program.
+
+## Handoffs
+
+- Find the cause of a difference → c64-emulator
+- Find the code that causes it → c64-static-analysis
+- Rebuild after a correction → c64-assembler
+- Record a confirmed conclusion → c64-knowledge

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

@@ -0,0 +1,116 @@
+# Scenario format
+
+A scenario is one JSON object in a project file.
+
+```json
+{
+  "name": "player moves left",
+  "original": { "program": "original/game.prg", "symbols": "knowledge" },
+  "rebuild": { "program": "build/game.prg", "symbols": "build/game.json" },
+  "steps": [
+    { "frames": 150 },
+    { "load": true },
+    { "registers": { "pc": "start" } },
+    { "runUntil": { "at": "main_loop" }, "timeoutFrames": 600 },
+    { "joystick": { "port": 2, "direction": "left" } },
+    { "frames": 10 },
+    { "observe": "moved", "memory": ["player_x", { "at": "$0400", "size": 40 }], "screen": {} }
+  ]
+}
+```
+
+## Subjects
+
+`original` and `rebuild` each have:
+
+- `program`: a PRG file, relative to the project directory.
+- `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.
+  - `none`: no names.
+
+Optional: `videoStandard`, `pal` (default) or `ntsc`.
+
+## Steps
+
+Before the first step of each side, the script does a hard reset. The CPU stops at the reset vector. Then the script does the steps in sequence. Each step has one of these keys:
+
+| 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. |
+| `{ "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. |
+| `{ "registers": { "pc": "start", "a": 0 } }` | Set registers: `pc`, `a`, `x`, `y` or `sp`. A value is a number or a name. |
+| `{ "joystick": { "port": 2, "direction": "left", "fire": true } }` | Set a joystick. The joystick stays in this state until the next joystick step. |
+| `{ "type": "RUN\n" }` | Type text on the keyboard, at most 1024 keys. The keys go into the keyboard queue of the KERNAL. A program that reads the keyboard hardware does not see them. A step cannot press one specific key of the keyboard matrix. |
+| `{ "runUntil": { "at": "main_loop" }, "timeoutFrames": 600 }` | Run until the CPU gets to an address. |
+| `{ "runUntil": { "memory": { "at": "game_state", "equals": 2 } }, "timeoutFrames": 600 }` | Run until a byte in memory has a value. |
+| `{ "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. |
+| `{ "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`.
+
+`timeoutFrames` is from 1 to 30000. A `runUntil` that does not get to its target in `timeoutFrames` frames makes the result INCONCLUSIVE.
+
+Each step except `observe` can have `"side": "original"` or `"side": "rebuild"`. Then only that side does the step. Use it when only one side needs a step, for example a key for the intro of the original. An `observe` step has no `side`, because it compares both sides.
+
+An address is `$` and four hex digits, or a symbol name. Each side finds a name in its own symbols.
+
+## Observations
+
+An `observe` step has a checkpoint name. A scenario can have each name only one time. The step can have these keys:
+
+| 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`. |
+| `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. |
+| `sprites` | A list of sprite numbers from 0 to 7. The script compares their position, color and flags. |
+
+A `tolerance` is the largest permitted difference for each byte. A `mask` has at most 64 rectangles. A `mask` must not cover all of the screen: PAL is 384×272 pixels and NTSC is 384×247 pixels. A scenario can observe the screen at most at 64 checkpoints.
+
+`exclude` is a list of bytes in the observed range that the comparison does not include. Each has `at` and a `reason`, for example `{ "at": "$d01e", "reason": "latched sprite collision, not writable" }`. The result lists each excluded byte with its reason.
+
+A `pc` value is an address. Compare `pc` only when both programs have the code at the same address.
+
+## Runs
+
+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" }`.
+- `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`.
+
+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.
+
+Example: visit two rooms from the same start.
+
+```json
+{
+  "name": "rooms",
+  "start": { "snapshot": "snapshots/room0.vsf" },
+  "steps": [
+    { "write": { "at": "$0350", "bytes": [1] } },
+    { "frames": 50 },
+    { "screen": "room1" },
+    { "coverage": "room1" },
+    { "snapshot": "snapshots/room0.vsf" },
+    { "write": { "at": "$0350", "bytes": [2] } },
+    { "frames": 50 },
+    { "screen": "room2" },
+    { "coverage": "room2" }
+  ]
+}
+```
+
+## Checks
+
+The script checks the scenario before it starts the emulator. A step with an unknown key or a wrong value stops the script with `invalid-input`. The message names the step.

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

@@ -0,0 +1,51 @@
+// The c64-testing playtest checklist: a Markdown list for a human tester,
+// made from the scenarios' checkpoints and the behavior that automated
+// scenarios cannot check. Nothing is stored.
+
+import { parseArgs } from "node:util";
+
+import { runScript, UsageError } from "#src/script.ts";
+import { readScenario, ScenarioError, type Scenario } from "./scenario.ts";
+
+const USAGE = `checklist.ts <scenario.json> [<scenario.json> ...] [--item <text> ...]
+
+Prints a Markdown checklist. --item adds an application-specific line.`;
+
+/** Behavior that only a person can judge. */
+const ALWAYS = [
+  "The controls respond as fast as in the original.",
+  "The animation is smooth and has no glitches.",
+  "The music and the sound effects sound the same as in the original.",
+  "The game flow and the level changes work from start to end.",
+  "Nothing unexpected happens outside the tested scenarios.",
+];
+
+function run(argv: string[]): string {
+  const { values, positionals } = parseArgs({ args: argv, strict: true, allowPositionals: true, options: { item: { type: "string", multiple: true }, help: { type: "boolean" } } });
+  if (values.help) throw new UsageError("");
+  if (positionals.length === 0) throw new UsageError("give at least one scenario file");
+  const lines = ["# Playtest checklist", ""];
+  for (const path of positionals) {
+    let scenario: Scenario;
+    try {
+      scenario = readScenario(path);
+    } catch (error) {
+      if (error instanceof ScenarioError) throw new UsageError(error.message);
+      throw error;
+    }
+    lines.push(`## ${scenario.name}`, "");
+    for (const step of scenario.steps) if ("observe" in step) lines.push(`- [ ] At "${step.observe}", the rebuild looks and behaves as the original.`);
+    lines.push("");
+  }
+  lines.push("## Application", "");
+  for (const item of values.item ?? []) lines.push(`- [ ] ${item}`);
+  for (const item of ALWAYS) lines.push(`- [ ] ${item}`);
+  return `${lines.join("\n")}\n`;
+}
+
+await runScript(
+  () => {
+    process.stdout.write(run(process.argv.slice(2)));
+  },
+  { usage: USAGE },
+);