@henols/c64-re-tools 2.0.0-rc.2 → 2.0.0-rc.21

package/skills/c64-static-analysis/scripts/lib/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

@@ -1,6 +1,6 @@
 ---
 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. Do not use it to find the cause of a difference.
+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
@@ -22,24 +22,73 @@ A PASS proves only the behavior that the scenario does and observes. It does not
 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
+node <skill>/scripts/test.ts tests/moves-left.json --out .c64-re-tools/local/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.
+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. A PASS writes no files. To keep the screens of a PASS, use a run (below).
 
 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 .c64-re-tools/local/runs/rooms/run.json --out .c64-re-tools/local/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": ".c64-re-tools/local/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. Add the map to the knowledge with `coverage` of the c64-knowledge skill. |
+| `{ "observe": "room3", "memory": ["$c100"], "registers": true }` | Record memory, registers, `vicii` or `sprites` in `results.json`. |
+| `{ "trace": "d011", "points": [{ "kind": "write", "at": "$d011" }], "frames": 100 }` | Record each hit of the points for 100 frames in `d011.json`: the instruction, its registers and the raster line and cycle. A point is `exec`, `read` or `write`, at an address or a name, with an optional `end`. `maxHits` limits the hits. |
+| `{ "observe": "all3", "memory": "all" }` | Write all 64 KiB of RAM to `all3.bin`, also the RAM under the ROMs and the I/O area. |
+
+A memory item can have `"view": "ram"`. Then it reads the RAM under the ROMs and the I/O area, for example code at `$e000` under the KERNAL. The default view `cpu` reads as the CPU sees memory. An item larger than 4096 bytes goes into its own `.bin` file, and `results.json` gives the file name.
+
+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.
+
+### Differences
+
+```
+node <skill>/scripts/diff.ts .c64-re-tools/local/runs/rooms/before.vsf .c64-re-tools/local/runs/rooms/after.vsf
+node <skill>/scripts/diff.ts .c64-re-tools/local/runs/rooms/results.json:room0 .c64-re-tools/local/runs/rooms/results.json:room3
+```
+
+`diff.ts` tells what changed between two states of one kind. Use it in place of your own compare script.
+
+- Two snapshot files: the script restores each one in its own emulator. It gives the changed ranges of the RAM and of the colour RAM, and the changed VIC-II, CIA, SID and CPU registers.
+- Two memory files of a run: the changed ranges. For a file of less than 64 KiB, `--at` gives the address of its first byte.
+- Two observations of runs, also of one run: the changed memory items and registers.
+
+`--gap N` joins ranges across N equal bytes. `--out` writes all ranges to a project file.
+
+### Project folder
+
+- Paths are relative to the project folder. The project folder is the nearest folder at or above the working directory that holds `.c64-re-tools/`.
+- If the working directory is not in a project and has projects below it, the script refuses and lists them. Then give `--project <folder>` to each script.
+- Write each file that you make for your work in `.c64-re-tools/local/` of the project. Git ignores that folder. Examples are results, batches, step files, runs, snapshots and memory dumps.
+- Move a file out of `.c64-re-tools/local/` only when it is the evidence for a finding. Move it before you give it to `--evidence` of c64-knowledge. `--evidence` refuses a file in `.c64-re-tools/local/`.
+- Put a run that is evidence in `runs/<name>/`, with its run file, its results and the snapshot files that it uses. Change the paths in the run file to the new paths. Then git keeps them, and another person can do the run again.
+- A shell redirect (`>`) is relative to the working directory, not to the project folder. From the folder above the project, write `<folder>/.c64-re-tools/local/result.json`.
+
 ## 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`.
+4. Save the c64-assembler output of the rebuild to the symbol file, for example `build/game.json` in the project folder. Give `--all-symbols`, so that the file also has the constants that the source does not use. From the folder above the project, write `assemble.ts --project <folder> ... > <folder>/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.
+   - Each value has one form. The pc and each address are `$xxxx`. Memory is lowercase hex. Other register values and chip values are decimal numbers.
    - `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.
 
@@ -66,8 +115,12 @@ PASS, FAIL or INCONCLUSIVE, the checkpoints and the smallest differences that ex
 - 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. It writes the entry state of the capture in the knowledge.
+- 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.
 

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,21 +38,27 @@ 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 and start the program of the side as VICE autostart does. |
+| `{ "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. |
+| `{ "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": 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`.
 
 `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
@@ -61,16 +67,54 @@ 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) and `tolerance` (0 to 255, default 0). |
+| `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. |
 | `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 scenario can observe the screen at most at 64 checkpoints.
+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": ".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`, `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.
+
+Example: visit two rooms from the same start.
+
+```json
+{
+  "name": "rooms",
+  "start": { "snapshot": ".c64-re-tools/local/snapshots/room0.vsf" },
+  "steps": [
+    { "write": { "at": "$0350", "bytes": [1] } },
+    { "frames": 50 },
+    { "screen": "room1" },
+    { "coverage": "room1" },
+    { "snapshot": ".c64-re-tools/local/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

@@ -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 (D77): 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 (D77): 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;
+}