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

package/skills/c64-provenance/scripts/lib/library.ts

@@ -4,10 +4,12 @@
 // its start, so match finds it in another program at another address and
 // suggests its names there as an apply batch. Nothing here writes knowledge.
 
+import { createHash } from "node:crypto";
 import { mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { join, relative, resolve, sep } from "node:path";
 
 import { Refusal } from "#src/errors.ts";
+import { writeRefusal, type Written } from "#src/host-client/transfer.ts";
 import { formatC64Address, instructionLength } from "#src/c64.ts";
 import { evaluate, identifiers, operandText } from "#src/knowledge/expression.ts";
 import type { CommentRow, OperandRow, ReferenceRow, RegionRow, SymbolRow } from "#src/knowledge/read.ts";
@@ -317,16 +319,26 @@ export function readLibrary(folder: string): Routine[] {
     .map((name) => parseRoutine(readFileSync(join(folder, name), "utf8"), name));
 }
 
-/** Writes a routine file into the library: a temporary file, then a rename. Refuses a name that exists unless `replace`. */
-export function saveRoutine(folder: string, routine: Routine, replace: boolean): string {
+/**
+ * Writes a routine file into the library: a temporary file, then a rename.
+ * Refuses a name that exists unless `replace`. Reports the file as a written
+ * file: its path relative to the project folder `root`, its size and its SHA-256.
+ */
+export function saveRoutine(folder: string, routine: Routine, replace: boolean, root = process.cwd()): Written {
   const file = join(folder, `${routine.name}.json`);
+  const out = relative(root, file).split(sep).join("/");
   if (!replace && statSync(file, { throwIfNoEntry: false }) !== undefined) {
     throw new Refusal("conflict", `The library already has the routine ${routine.name}. Give another --name, or give --replace to save over it.`);
   }
+  const bytes = Buffer.from(routineText(routine), "utf8");
   const temporary = `${file}.${process.pid}.tmp`;
-  writeFileSync(temporary, routineText(routine));
-  renameSync(temporary, file);
-  return file;
+  try {
+    writeFileSync(temporary, bytes);
+    renameSync(temporary, file);
+  } catch (error) {
+    throw writeRefusal(error, out, "--library") ?? error;
+  }
+  return { out, bytes: bytes.length, sha256: createHash("sha256").update(bytes).digest("hex") };
 }
 
 /** An image to search: its segments and its bytes inside them. */

package/skills/c64-provenance/scripts/lib/separate.ts

@@ -1,10 +1,11 @@
 // Evidence from one release: for each range of the image, the unpack
 // stage that wrote it and the access class from coverage; for each code
-// region of knowledge, whether call and jump references reach it from the
-// entry; and what the program reads or executes outside the image. Evidence
-// only: nothing here decides what is original.
+// region of knowledge, whether call and jump references or the run on from
+// its last instruction reach it from the entry; and what the program reads
+// or executes outside the image. Evidence only: nothing here decides what is
+// original.
 
-import { type AddressRange, COVERAGE, executedRamCode } from "#src/c64.ts";
+import { type AddressRange, COVERAGE, executedRamCode, instructionLength } from "#src/c64.ts";
 
 export type Access = "executed" | "read" | "written" | "read-written" | "untouched";
 
@@ -49,6 +50,27 @@ export interface Separation {
 
 const SYSTEM_PAGES_END = 0x03ff;
 
+/** BRK, JMP, RTI, RTS, JMP (indirect) and the JAM opcodes: the CPU does not run on to the next instruction after them. */
+const NO_FALL_THROUGH = new Set([0x00, 0x4c, 0x40, 0x60, 0x6c, 0x02, 0x12, 0x22, 0x32, 0x42, 0x52, 0x62, 0x72, 0x92, 0xb2, 0xd2, 0xf2]);
+
+/**
+ * The address after a code region where the CPU runs on, or undefined when
+ * its last instruction does not run on (RTS, RTI, JMP, BRK, JAM). The
+ * instructions follow one another from the start of the region.
+ */
+export function fallThrough(region: AddressRange, memory: Uint8Array): number | undefined {
+  let at = region.start;
+  let last = at;
+  while (at <= region.end) {
+    last = at;
+    at += instructionLength(memory[at]!);
+  }
+  return NO_FALL_THROUGH.has(memory[last]!) || at > 0xffff ? undefined : at;
+}
+
+/** The most instructions outside the code regions that the run on from a region goes through, for example an instruction in a dual-use region. */
+const MAX_RUN_ON = 16;
+
 /** Joins addresses in order into ranges; `gap` is the most bytes between two addresses in one range. */
 function merge(addresses: number[], gap = 0, joins: (from: number, to: number) => boolean = () => true): AddressRange[] {
   const ranges: AddressRange[] = [];
@@ -92,12 +114,29 @@ export function separate(input: SeparationInput): Separation {
     }
   }
 
-  // Reachability: from the region that holds the entry, through call and jump references, to a fixed point.
+  // Reachability: from the region that holds the entry, through call and jump references and the run on
+  // from the last instruction of a region into the next address, to a fixed point.
   const regions = input.codeRegions.filter((region) => input.segments.some((segment) => region.start <= segment.end && segment.start <= region.end));
   const holding = (address: number) => regions.findIndex((region) => address >= region.start && address <= region.end);
   const reached = new Set<number>();
   if (input.entry !== undefined && holding(input.entry) >= 0) reached.add(holding(input.entry));
-  const flows = input.references.filter((reference) => reference.kind === "call" || reference.kind === "jump");
+  // The CPU runs the bytes after the region as instructions: through bytes of no code region (a dual-use
+  // instruction, for example) into the next code region, unless one of them does not run on.
+  const runOn = (from: number): number | undefined => {
+    let at = from;
+    for (let count = 0; count <= MAX_RUN_ON && at <= 0xffff && inImage(at); count++) {
+      if (holding(at) >= 0) return at;
+      if (NO_FALL_THROUGH.has(input.memory[at]!)) return undefined;
+      at += instructionLength(input.memory[at]!);
+    }
+    return undefined;
+  };
+  const runsOn = regions.flatMap((region) => {
+    const next = fallThrough(region, input.memory);
+    const to = next === undefined ? undefined : runOn(next);
+    return to === undefined ? [] : [{ from: region.end, to }];
+  });
+  const flows = [...input.references.filter((reference) => reference.kind === "call" || reference.kind === "jump"), ...runsOn];
   for (let grown = true; grown; ) {
     grown = false;
     for (const flow of flows) {

package/skills/c64-provenance/scripts/provenance.ts

@@ -8,7 +8,7 @@
 // routines that several programs share in a library folder and find them in the
 // program (D71).
 
-import { basename, relative } from "node:path";
+import { basename } from "node:path";
 
 import { type AddressRange, c64AddressOf, formatC64Address } from "#src/c64.ts";
 import { Refusal } from "#src/errors.ts";
@@ -108,6 +108,7 @@ async function compare(call: Call): Promise<unknown> {
   for (const text of call.strings("shift")) {
     const match = /^(\d+):([+-]?\d+)$/.exec(text);
     if (match === null || Number(match[1]) < 1 || Number(match[1]) > positionals.length) throw new UsageError(`--shift must be <release number>:<bytes>, not ${text}`);
+    if (shifts.has(Number(match[1]))) throw new UsageError(`--shift gives release ${match[1]} more than one shift (${shifts.get(Number(match[1]))} and ${match[2]}). Give one --shift for each release`);
     shifts.set(Number(match[1]), Number(match[2]));
   }
   const frames = call.count("frames");
@@ -364,10 +365,10 @@ function routineCommand(call: Call): unknown {
       operands: listOperands(db, range, SEMANTIC_ORIGINS),
       platform: platform(),
     });
-    const file = saveRoutine(libraryFolder(library, { create: true, cwd: projectRoot() }), routine, call.flag("replace"));
+    const written = saveRoutine(libraryFolder(library, { create: true, cwd: projectRoot() }), routine, call.flag("replace"), projectRoot());
     return {
       routine: routine.name,
-      file: relative(projectRoot(), file).split("\\").join("/"),
+      ...written,
       start: formatC64Address(start),
       end: formatC64Address(end),
       length: routine.bytes.length,
@@ -460,7 +461,7 @@ const COMMANDS: CommandSpec[] = [
   },
   {
     name: "separate",
-    summary: "Evidence from the program in the knowledge: the unpack stage that wrote each range, its access in the coverage, whether call and jump references reach each code region from the entry, and what the program reads or executes outside its segments.",
+    summary: "Evidence from the program in the knowledge: the unpack stage that wrote each range, its access in the coverage, whether call and jump references, or the run on from the code before it, reach each code region from the entry, and what the program reads or executes outside its segments.",
     options: { out: { ...OPTIONS.out, value: "<file>", help: "write all ranges to this file" }, "max-listed": OPTIONS["max-listed"] },
     run: separateCommand,
   },

package/skills/c64-source/SKILL.md

@@ -150,6 +150,7 @@ Do not store:
 - `operandsAsNumbers`: the operand expressions that the source has as a number with a side comment, each with its `address`, `expression` and `reason`. An expression becomes a number when no instruction with an operand value is at the address, or when a name has no address. An expression that ACME refuses or does not assemble to the program also becomes a number. Then the script assembles the source again, at most six times.
 - `unusedModules`: modules in the knowledge whose start is in no segment of the program. Often this tells that the program does not hold code that the knowledge describes.
 - `entryOutside`: the entry is in no segment of the program in the knowledge, with a `reason`. The capture does not hold the program.
+- `dataOnly`: the knowledge has no entry, no routine, no code region and no executed address in the space. Thus the source has only data, and Ghidra does not run. A table or a key page in a cartridge bank is an example.
 - `notExecuted`: when the knowledge has coverage, the count of instructions that no run executed, the count of their ranges, and the first ranges. `rest` names the file `not_executed.json` in `--out` when the list is not complete. This file has all of the ranges. Each range has its source `file` and the `routine` before it. `files` counts the ranges in each file.
 - `macroUses`: the count of macro uses that the source has.
 - `macrosAsInstructions`: the macro uses that the source has as instructions, each with its `start`, `end`, `macro` and `reason`.
@@ -171,6 +172,7 @@ Do not store:
 - `patchesNotWritten`: read each `reason`. Move the start or the end of the patch to an instruction, or give the switch another name.
 - `macrosAsInstructions`: read each `reason`. Correct the macro or the args, or remove the use with `unuse`. The source stays identical, so this is not a failure.
 - `entryOutside`: the run fails, but the script still writes and checks the source. With `--loader`, `loader.verified` is `false` with the same `reason`. Capture the program again with c64-unpacker `loads` or `capture`. Make sure that a segment holds the entry. Then put it into the knowledge again with `image`.
+- `dataOnly`: this is not a failure. If the space has code, give `--entry` or classify the code with the c64-knowledge skill. Then generate again.
 - `entriesInData`: an analyzer region of data hides the code at the entry. If the entry is code, record a code region at the entry with the c64-knowledge skill, for example `classify '$0500-$05ff' code`. A region of the user or the LLM replaces the analyzer region. Then generate again.
 - `loader.verified: false` with a `reason`: the script did not make the loader. The script still writes and checks the source. When no copy order or no free pages exist, or the loader needs too many copies, the reason gives the ranges. Capture the program again with fewer segments, or write the loader by hand.
 - `loader.verified: false` with `differences`: the loader ran, and `differences` gives the bytes and registers that are not equal.

package/skills/c64-source/scripts/lib/source.ts

@@ -384,7 +384,7 @@ export function layout(input: SourceInput): Layout {
     }
     const missing = [...new Set(use.args.flatMap((arg) => identifiers(arg)))].filter((name) => !byName.has(name));
     if (missing.length > 0) {
-      fallBack(`No symbol and no platform name is ${missing.join(", ")}.`);
+      fallBack(`${missing.join(", ")} ${missing.length === 1 ? "is" : "are"} not a symbol of the knowledge or a platform name. Name the address with knowledge.ts rename, or give other args with knowledge.ts use.`);
       continue;
     }
     candidates.push({ use, items: run as InstructionItem[] });
@@ -403,7 +403,7 @@ export function layout(input: SourceInput): Layout {
     }
     const missing = identifiers(expression).filter((name) => !byName.has(name));
     if (missing.length > 0) {
-      operandsAsNumbers.push({ address: operand.address, expression, reason: `No symbol and no platform name is ${missing.join(", ")}.` });
+      operandsAsNumbers.push({ address: operand.address, expression, reason: `${missing.join(", ")} ${missing.length === 1 ? "is" : "are"} not a symbol of the knowledge or a platform name. Name the address with knowledge.ts rename, or write the operand again with knowledge.ts operand.` });
       continue;
     }
     // An immediate operand builds the address of a name; any other operand uses the address as the instruction does.

package/skills/c64-source/scripts/source.ts

@@ -40,6 +40,9 @@ const MAX_DIAGNOSTICS = 20;
 const ROUNDS = 6;
 const PROBE_BASE = 0x1000;
 const PROBE_SLOT = 4;
+/** Why a source has no instructions when the knowledge has no code. */
+const DATA_ONLY = "The knowledge has no entry, routine, code region or executed address in this space. Thus the source has only data. For instructions, give --entry, or classify the code with knowledge.ts classify, then generate again.";
+
 /** The copies of a full 64 KiB take about 140 frames. */
 const LOADER_FRAMES = 1500;
 
@@ -99,9 +102,10 @@ function withAnalyzerNames(symbols: SymbolRow[], second: SymbolRow[]): SymbolRow
  * Ghidra's instruction starts and lengths inside the image, seeded from the
  * entry, from knowledge of any origin, and from the coverage: a run's flow
  * starts, also after a JSR, so code that an analyzer does not reach by itself
- * is in the source.
+ * is in the source. A program without a seed has no known code: it is data
+ * only, and Ghidra does not run.
  */
-async function decode(image: ProgramImage, knowledge: ReturnType<typeof readKnowledge>, entries: number[], coverage: Uint8Array | undefined): Promise<Map<number, number>> {
+async function decode(image: ProgramImage, knowledge: ReturnType<typeof readKnowledge>, entries: number[], coverage: Uint8Array | undefined): Promise<{ instructions: Map<number, number>; dataOnly: boolean }> {
   const inImage = (address: number) => image.segments.some((segment) => address >= segment.start && address <= segment.end);
   const seeds = new Set<number>([...(image.entry === undefined ? [] : [image.entry]), ...entries]);
   for (const address of knowledge.routines) seeds.add(address);
@@ -114,8 +118,7 @@ async function decode(image: ProgramImage, knowledge: ReturnType<typeof readKnow
   const entryPoints = [...seeds].filter(inImage).sort((a, b) => a - b);
   if (entryPoints.length === 0) {
     // An entry in no segment is a capture fault: the image is data only, and the result says entryOutside.
-    if (image.entry !== undefined && !inImage(image.entry)) return new Map();
-    throw new UsageError("Ghidra needs an entry point: give --entry, or record a routine or a code region in knowledge with the c64-knowledge skill");
+    return { instructions: new Map(), dataOnly: image.entry === undefined || inImage(image.entry) };
   }
   const dataRanges = knowledge.regions
     .filter((region) => !CODE_REGION_TYPES.includes(region.type) && region.type !== "dual-use")
@@ -138,7 +141,7 @@ async function decode(image: ProgramImage, knowledge: ReturnType<typeof readKnow
     const inside = Array.from({ length: bytes.length }, (_, offset) => instruction.address + offset).every((address, offset) => inImage(address) && image.byteAt(address) === bytes[offset]);
     if (inside) instructions.set(instruction.address, bytes.length);
   }
-  return instructions;
+  return { instructions, dataOnly: false };
 }
 
 /** Assembles files given as text with ACME; the program or the diagnostics. */
@@ -547,7 +550,7 @@ async function generate(call: Call): Promise<{ output: Record<string, unknown>;
   // Read the entry state before the long steps, so a bad state stops the run at once.
   const state = loaderWanted ? loaderState(image.state, "the entry state of the knowledge") : undefined;
   const romUse = romsInUse(image, coverage);
-  const instructions = await decode(image, knowledge, entries, coverage);
+  const { instructions, dataOnly } = await decode(image, knowledge, entries, coverage);
   const laid = layout({
     segments: image.segments,
     byteAt: image.byteAt,
@@ -634,6 +637,7 @@ async function generate(call: Call): Promise<{ output: Record<string, unknown>;
     // The ROM names that the source leaves out, and the evidence.
     ...(space !== DEFAULT_SPACE || (romUse.basic && romUse.kernal) ? {} : { romNamesLeftOut: { roms: [...(romUse.basic ? [] : ["BASIC"]), ...(romUse.kernal ? [] : ["KERNAL"])], ...(romUse.basic || romUse.kernal ? {} : { systemArea: true }), from: romUse.from } }),
     ...(missingEntry === undefined ? {} : { entryOutside: { entry: formatC64Address(image.entry!), reason: missingEntry } }),
+    ...(dataOnly ? { dataOnly: DATA_ONLY } : {}),
     labels: { named: laid.namedLabels, generated: laid.generatedLabels },
     // An --entry in a data region decodes nothing: the result says so, and a code region in the knowledge changes it.
     ...(inData.length === 0

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

@@ -31,7 +31,7 @@ export interface Idioms {
   candidates: { dop: number[]; selfModified: number[] };
 }
 
-/** True when an instruction can start at the address: inside the program, and no JAM. */
+/** True when an instruction can start at the address: inside the range and the program (`byteAt` gives a byte), 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);
@@ -43,7 +43,11 @@ const word = (byteAt: ImageByte, address: number) => {
   return low === undefined || high === undefined ? undefined : low | (high << 8);
 };
 
-/** `covered` is the coverage of the knowledge: the joined map, and the addresses that one run wrote and executed. */
+/**
+ * `byteAt` gives the bytes of the program and undefined outside it, so a
+ * table and its targets stay inside the program. `covered` is the coverage of
+ * the knowledge: the joined map, and the addresses that one run wrote and executed.
+ */
 export function findIdioms(byteAt: ImageByte, range: { start: number; end: number }, covered?: { map: Uint8Array; selfModified: Uint8Array }): Idioms {
   const coverage = covered?.map;
   const regions: NormalizedFindings["regions"] = [];

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

@@ -184,7 +184,8 @@ async function analyze(call: Call): Promise<unknown> {
   // With coverage, a code finding over an executed instruction start replaces the data of the other analyzer.
   const executed = coverage === undefined ? {} : { executed: (address: number) => (coverage[address]! & COVERAGE.ramExecute) !== 0 };
   const loaded = imageKind === "flat64k" ? { start: 0x0000, end: 0xffff } : prgRange(bytes);
-  const idioms = findIdioms(byteAt, { start: loaded.start, end: loaded.end }, covered);
+  // The idioms read only the program: a table that runs past a segment gets no targets from the 0 bytes of the 64 KiB.
+  const idioms = findIdioms(inProgram, { start: loaded.start, end: loaded.end }, covered);
 
   const revision = currentRevision(reader);
   const seeds = seedsFromKnowledge(reader, entries, space);
@@ -281,7 +282,7 @@ async function analyze(call: Call): Promise<unknown> {
       coverage: result.coverage.map((range) => ({ start: formatC64Address(range.start), end: formatC64Address(range.end) })),
       ...imported,
       regions: result.regions.map((region) => ({ start: formatC64Address(region.start), end: formatC64Address(region.end), classification: region.classification })),
-      labels: listed(result.labels, max, (label) => ({ address: formatC64Address(label.address), name: label.name }), "c64-knowledge: knowledge.ts symbols"),
+      labels: listed(result.labels, max, (label) => ({ address: formatC64Address(label.address), name: label.name }), "c64-knowledge: knowledge.ts symbols --analyzer --origin dxa"),
       ...(written === undefined ? {} : { listing: written }),
     };
   }
@@ -311,7 +312,7 @@ async function analyze(call: Call): Promise<unknown> {
     ...(coverage === undefined ? {} : { coverageGaps: listed(gaps, max, formatC64Address, "a larger --max-listed") }),
     coverage: result.coverage.map((range) => ({ start: formatC64Address(range.start), end: formatC64Address(range.end) })),
     ...imported,
-    functions: listed(result.functions, max, (fn) => ({ entry: formatC64Address(fn.entry), name: fn.name }), "c64-knowledge: knowledge.ts symbols --kind routine"),
+    functions: listed(result.functions, max, (fn) => ({ entry: formatC64Address(fn.entry), name: fn.name }), "c64-knowledge: knowledge.ts symbols --analyzer --origin ghidra"),
     decompilations: result.decompilations.map((item) => ({ entry: formatC64Address(item.entry), text: item.text, ...(item.truncated ? { truncated: true } : {}) })),
     ...((result.notDecompiled ?? []).length === 0
       ? {}

package/skills/c64-testing/SKILL.md

@@ -30,6 +30,8 @@ node <skill>/scripts/testing.ts checklist tests/moves-left.json --item 'FIRE sta
 
 `testing.ts checklist` gives a Markdown checklist for a human tester in `text`.
 
+Before the emulator starts, `testing.ts test` examines each file that the scenario names: the program and the symbols of each side, and each snapshot file. A missing file gives `not-found`. A program must be a PRG. The script refuses a disk, tape or cartridge image.
+
 ### 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.
@@ -50,6 +52,8 @@ The run file gives where to start (a program, or a snapshot file), the steps, an
 | `{ "trace": "d011", "points": [{ "kind": "write", "start": "$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 has the `kind` `exec`, `read` or `write`, a `start` and 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. |
 
+Each step that writes a file must have its own file name. The script refuses a run where two steps write the same file, for example `{ "coverage": "x" }` and `{ "observe": "x", "memory": "all" }`, which both write `x.bin`. The script also examines the start program and each snapshot file before the emulator starts.
+
 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. `result` is PASS when all steps ran, and FAIL when a step did not run. `reason` tells why. A long run can need more time than one shell call. Then run it in the background.
@@ -118,7 +122,11 @@ node <skill>/scripts/testing.ts diff .c64-re-tools/local/runs/rooms/results.json
 - Two memory files of a run: the changed ranges. For a file of less than 64 KiB, `--address` 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.
+`registers` gives each changed register and chip value. `cpu.pc` is a `$` address. Each CPU flag is `cpu.flags.<flag>`, for example `cpu.flags.c`, with `true` or `false`.
+
+The script refuses a snapshot that does not restore in its emulator. An example is a PAL snapshot with `--ntsc`. Give `--ntsc` only for snapshots of an NTSC machine.
+
+`--gap N` joins ranges across N equal bytes. `--out` writes all ranges and all changed registers to a project file. The file uses the names of the result.
 
 ### Calling the script
 
@@ -180,6 +188,8 @@ PASS, FAIL or INCONCLUSIVE, the checkpoints and the smallest differences that ex
 ## Failure and conflicts
 
 - `invalid-input`: the scenario file has an error. The message names the step. Change the step and run the test again.
+- `invalid-input` that names the 2.0 form: a step, a memory item or a recording has a form of version 2.0. An example is `"at"` in place of `"address"`. The message gives the form to write. Change the file. Record a recording of version 2.0 again.
+- `not-found` before the run: a file of the scenario or the run file is missing, for example the rebuild program. Build the rebuild, or change the path.
 - 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.

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

@@ -101,6 +101,8 @@ The page sends input only between Start and End. The input of the page goes into
 
 A site is the address of the instruction that reads. The values are hex. `<from>` and `<count>` are decimal.
 
+`testing.ts replay` checks `recording.json` before the replay core starts. A recording of version 2.0 can have events or a comparison in the old form, for example `"at"` in place of `"address"`. The script refuses it with `invalid-input`. The message names the event, the old field and the form to write. Record the session again.
+
 ## Replay
 
 `testing.ts replay` replays a recording folder:

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

@@ -123,3 +123,9 @@ Example: visit two rooms from the same start.
 ## 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.
+
+The script also examines each file before it starts the emulator: the program and the symbols of each side, and each snapshot file. A missing file stops the script with `not-found`. A program that is not a PRG, for example a disk image, stops the script with `invalid-input`.
+
+A step in the form of version 2.0 stops the script with `invalid-input`. The message names the old field and gives the step to write. For example, the script refuses `{ "runUntil": { "at": "main_loop" }, "timeoutFrames": 300 }` and gives `{"runUntil": {"target": {"kind": "address", "address": "main_loop"}, "timeoutFrames": 300}}`. A memory item with `at` gets the same refusal: write `address`.
+
+In a run, two steps must not write the same file name. The script refuses such a run before it starts. Names that differ only in upper and lower case are the same name.

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

@@ -5,6 +5,8 @@
 // run, or two observations of runs (also two of one run), compare as they are.
 
 import { formatC64Address, parseC64Address } from "#src/c64.ts";
+import { Refusal } from "#src/errors.ts";
+import { isObject } from "#src/host-client/steps.ts";
 import { WireFailure } from "#src/host-client/tools.ts";
 import { readProjectFile, writeReported } from "#src/host-client/transfer.ts";
 import { readMemoryInParts, ViceSessionClient } from "#src/host-client/vice-session.ts";
@@ -41,33 +43,80 @@ function observation(path: string): MachineState {
       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 ?? {})) {
+  return { observed, values: cpuValues(seen.registers ?? {}) };
+}
+
+/** The CPU registers as values: each register by its name, the pc from a number or "$xxxx", and each flag as cpu.flags.<flag>. */
+function cpuValues(registers: Record<string, unknown>): Record<string, number | boolean> {
+  const values: Record<string, number | boolean> = {};
+  for (const [register, value] of Object.entries(registers)) {
     if (typeof value === "number") values[`cpu.${register}`] = value;
     else if (typeof value === "string" && value.startsWith("$")) values[`cpu.${register}`] = parseC64Address(value);
+    else if (register === "flags" && isObject(value)) for (const [flag, set] of Object.entries(value)) if (typeof set === "boolean") values[`cpu.flags.${flag}`] = set;
   }
-  return { observed, values };
+  return 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);
+/** The size of the header of a module in a VICE snapshot file: the name (16 bytes), the version (2 bytes) and the size (4 bytes). */
+const MODULE_HEADER = 22;
+const VSF_MAGIC = "VICE Snapshot File\x1a";
+const VSF_VERSION = "VICE Version\x1a";
+
+/**
+ * The 64 KiB of C64 RAM that a VICE snapshot file holds: the C64MEM module,
+ * after the CPU port and the cartridge lines (4 bytes). Undefined when the
+ * file has no such module.
+ */
+export function snapshotRam(file: Uint8Array): Uint8Array | undefined {
+  const bytes = Buffer.from(file);
+  if (bytes.subarray(0, VSF_MAGIC.length).toString("latin1") !== VSF_MAGIC) return undefined;
+  // The magic, the version (2 bytes) and the machine name (16 bytes); a newer VICE adds its own version (8 bytes).
+  let at = VSF_MAGIC.length + 2 + 16;
+  if (bytes.subarray(at, at + VSF_VERSION.length).toString("latin1") === VSF_VERSION) at += VSF_VERSION.length + 8;
+  while (at + MODULE_HEADER <= bytes.length) {
+    const name = bytes.subarray(at, at + 16).toString("latin1").replace(/\0+$/, "");
+    const size = bytes.readUInt32LE(at + 18);
+    if (size < MODULE_HEADER) return undefined;
+    if (name === "C64MEM") return at + MODULE_HEADER + 4 + 0x10000 <= bytes.length ? bytes.subarray(at + MODULE_HEADER + 4, at + MODULE_HEADER + 4 + 0x10000) : undefined;
+    at += size;
+  }
+  return undefined;
+}
+
+/**
+ * The state of a snapshot: restored in the session, then read with the
+ * readers of the runs. The RAM must be the RAM of the file: else the
+ * snapshot did not restore, and the state would be wrong.
+ */
+async function snapshotState(client: ViceSessionClient, path: string, ntsc: boolean): Promise<MachineState> {
+  const file = readProjectFile(path).bytes;
+  const saved = snapshotRam(file);
+  if (saved === undefined) throw new Refusal("invalid-input", `${path} is not a snapshot of a C64: it has no C64 memory. Give a file that c64_snapshot save or a save step of a run wrote.`);
+  const restored = await client.snapshotRestore(file);
   const memory = await readMemoryInParts(client, 0x0000, 0x10000, "ram");
+  // $00 and $01 are the CPU port: the file keeps them apart from the RAM.
+  if (("restored" in restored && !restored.restored) || !memory.subarray(2).equals(Buffer.from(saved.subarray(2)))) {
+    throw new Refusal(
+      "invalid-input",
+      `${path} did not restore: the RAM after the restore is not the RAM of the file. A snapshot restores only in a machine of the video standard that saved it. ${ntsc ? "Leave out --ntsc for a PAL snapshot" : "Give --ntsc for an NTSC snapshot"}, or use the emulator version that saved it.`,
+    );
+  }
   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> = {};
+  const values: Record<string, number | boolean> = {};
   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;
+  Object.assign(values, cpuValues({ ...(await client.registersGet("c64")) }));
   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 }) });
+/** A changed value as a person reads it: the pc as "$xxxx". */
+const showValue = (item: { name: string; a: number | boolean; b: number | boolean }) => (item.name === "cpu.pc" && typeof item.a === "number" && typeof item.b === "number" ? { name: item.name, a: formatC64Address(item.a), b: formatC64Address(item.b) } : item);
 
 /** The differences of two states of one kind: snapshots, memory files or observations of runs. */
 export async function diffFiles(first: string, second: string, options: { gap: number; max: number; ntsc: boolean; at?: number; out?: string }): Promise<Record<string, unknown>> {
@@ -90,8 +139,8 @@ export async function diffFiles(first: string, second: string, options: { gap: n
   } else {
     const client = await ViceSessionClient.open({ videoStandard: options.ntsc ? "ntsc" : "pal" });
     try {
-      a = await snapshotState(client, first);
-      b = await snapshotState(client, second);
+      a = await snapshotState(client, first, options.ntsc);
+      b = await snapshotState(client, second, options.ntsc);
     } finally {
       await client.close();
     }
@@ -101,7 +150,8 @@ export async function diffFiles(first: string, second: string, options: { gap: n
   const part = (item: { changedBytes: number; ranges: ChangedRange[] } | undefined) => (item === undefined ? undefined : { changedBytes: item.changedBytes, ...listed(item.ranges, max, show, rest) });
   let written: ReturnType<typeof writeReported> | undefined;
   if (options.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 ?? [] };
+    // The names of the result: registers holds the changed values.
+    const all = { a: first, b: second, ...(diff.memory === undefined ? {} : { memory: diff.memory.ranges.map(show) }), ...(diff.colorRam === undefined ? {} : { colorRam: diff.colorRam.ranges.map(show) }), registers: (diff.values ?? []).map(showValue), observed: diff.observed ?? [] };
     written = writeReported(options.out, `${JSON.stringify(all, null, 2)}\n`, { what: "--out" });
   }
   return {
@@ -109,7 +159,7 @@ export async function diffFiles(first: string, second: string, options: { gap: n
     b: second,
     ...(diff.memory === undefined ? {} : { memory: part(diff.memory) }),
     ...(diff.colorRam === undefined ? {} : { colorRam: part(diff.colorRam) }),
-    ...(diff.values === undefined ? {} : { registers: listed(diff.values, max, undefined, rest) }),
+    ...(diff.values === undefined ? {} : { registers: listed(diff.values, max, showValue, rest) }),
     ...(diff.observed === undefined ? {} : { observed: listed(diff.observed, max, undefined, rest) }),
     ...(written === undefined ? {} : written),
   };

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

@@ -10,8 +10,8 @@ export interface MachineState {
   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>;
+  /** Named single values: VIC-II, CIA and SID registers and the CPU registers, as "vic.$d011", "cia1.timerA", "cpu.pc", and each CPU flag as "cpu.flags.c". */
+  values?: Record<string, number | boolean>;
   /** The memory items of an observation of a run: the address or name, and its bytes as hex. */
   observed?: Record<string, string>;
 }
@@ -27,7 +27,7 @@ export interface ChangedRange {
 export interface StateDiff {
   memory?: { changedBytes: number; ranges: ChangedRange[] };
   colorRam?: { changedBytes: number; ranges: ChangedRange[] };
-  values?: Array<{ name: string; a: number; b: number }>;
+  values?: Array<{ name: string; a: number | boolean; b: number | boolean }>;
   observed?: Array<{ address: string; a: string; b: string }>;
 }