@henols/c64-re-tools 2.1.2 → 2.1.3

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

@@ -15,19 +15,34 @@ const semantic = (row: { origin: string }) => isSemantic(row.origin);
 /**
  * Seeds from current semantic knowledge: routines from the user or
  * the LLM are entry points, their non-code regions are data, and their names
- * are labels. Analyzer facts are never seeds: fed back, an analyzer's own
- * earlier guess would force the same answer again, and a re-analysis could
- * not retire it.
+ * are labels. Analyzer facts are never seeds alone: fed back, an analyzer's
+ * own earlier guess would force the same answer again, and a re-analysis
+ * could not retire it. A data or variable symbol of the user or the LLM is a
+ * decision that its address is data: the non-code region that holds it is
+ * data, also a region of an analyzer, else the byte of the symbol. Where a
+ * code region holds the symbol (a variable in the operand of self-modifying
+ * code) or the address executed, the symbol gives no data. A region with an
+ * executed address or an entry point in it gives only the byte of the symbol.
  */
-export function seedsFromKnowledge(db: DatabaseSync | undefined, extraEntryPoints: number[] = [], space: Space = DEFAULT_SPACE): Seeds {
+export function seedsFromKnowledge(db: DatabaseSync | undefined, extraEntryPoints: number[] = [], space: Space = DEFAULT_SPACE, executed: (address: number) => boolean = () => false): Seeds {
   const symbols = listSymbols(db, undefined, undefined, undefined, space).filter(semantic);
   const entryPoints = [...new Set([...extraEntryPoints, ...symbols.filter((symbol) => symbol.kind === "routine").map((symbol) => symbol.address)])].sort((a, b) => a - b);
+  const regions = listRegions(db, undefined, undefined, undefined, space);
+  // A JMP table is code and dual-use bytes are both: neither is a data range.
+  const isData = (region: { type: string }) => !CODE_REGION_TYPES.includes(region.type as never) && region.type !== "dual-use";
+  const dataRanges = regions.filter((region) => semantic(region) && isData(region)).map((region) => ({ start: region.start, end: region.end }));
+  const covered = (range: { start: number; end: number }) => dataRanges.some((seed) => seed.start <= range.end && range.start <= seed.end);
+  const holdsCode = (range: { start: number; end: number }) => entryPoints.some((entry) => entry >= range.start && entry <= range.end) || Array.from({ length: range.end - range.start + 1 }, (_, offset) => range.start + offset).some(executed);
+  for (const symbol of symbols.filter((row) => row.kind === "data" || row.kind === "variable").sort((a, b) => a.address - b.address)) {
+    const own = { start: symbol.address, end: symbol.address };
+    const region = regions.find((row) => row.start <= symbol.address && symbol.address <= row.end);
+    if ((region !== undefined && !isData(region)) || holdsCode(own) || covered(own)) continue;
+    const range = region !== undefined && !holdsCode(region) ? { start: region.start, end: region.end } : own;
+    dataRanges.push(range);
+  }
   return {
     entryPoints,
-    dataRanges: listRegions(db, undefined, undefined, undefined, space)
-      // A JMP table is code and dual-use bytes are both: neither is a data range.
-      .filter((region) => semantic(region) && !CODE_REGION_TYPES.includes(region.type) && region.type !== "dual-use")
-      .map((region) => ({ start: region.start, end: region.end })),
+    dataRanges: dataRanges.sort((a, b) => a.start - b.start),
     labels: symbols.map((symbol) => ({ address: symbol.address, name: symbol.name })),
   };
 }

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

@@ -3,12 +3,14 @@
 // 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.
+// The scan reads the instructions of the code regions, decoded from the start
+// of each region: bytes of data are never read as an instruction. It reads
+// short straight runs: 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";
+import { instructionAt, type Instruction } from "./macros.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" };
@@ -50,46 +52,57 @@ interface Store {
   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[] {
+/** The stores of immediates in the straight run of decoded instructions that starts at `start`. */
+function storesFrom(run: ReadonlyArray<Instruction & { at: number }>, start: 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 };
+  for (const { opcode, value, at } of run.slice(start, start + MAX_RUN)) {
+    if (LOADS[opcode] !== undefined) last[LOADS[opcode]] = { load: at, value };
     else if (STORES[opcode] !== undefined) {
       const loaded = last[STORES[opcode]];
       if (loaded === undefined) break;
-      stores.push({ ...loaded, to: operand });
+      stores.push({ ...loaded, to: value });
     } else if (!NEUTRAL.has(opcode)) break;
-    at += length;
   }
   return stores;
 }
 
+/** The instructions of each code region, decoded from its start, up to a byte that is no instruction. */
+function decoded(byteAt: ImageByte, code: ReadonlyArray<{ start: number; end: number }>): Array<Array<Instruction & { at: number }>> {
+  return [...code]
+    .sort((a, b) => a.start - b.start)
+    .map((region) => {
+      const run: Array<Instruction & { at: number }> = [];
+      for (let at = region.start; at <= region.end; ) {
+        const instruction = instructionAt(byteAt, at, region.end);
+        if (instruction === undefined) break;
+        run.push({ ...instruction, at });
+        at += instruction.length;
+      }
+      return run;
+    });
+}
+
 /**
- * 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.
+ * Finds the pointer candidates in the code regions of the image: an immediate
+ * pair stored to a vector or to a zero-page pair that a (zp),y instruction of
+ * the code 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 },
+  code: ReadonlyArray<{ 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 runs = decoded(byteAt, code);
+  const indirect = new Set(runs.flatMap((run) => run.filter((instruction) => INDIRECT_Y.has(instruction.opcode)).map((instruction) => instruction.value)));
   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 [run, index] of runs.flatMap((run) => run.map((_, index) => [run, index] as const))) {
+    if (LOADS[run[index]!.opcode] === undefined) continue;
+    const stores = storesFrom(run, index);
     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);

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

@@ -17,7 +17,7 @@ import { analyzedBytes, programCoverage, requireProgram } from "#src/knowledge/p
 import { importFindings, runProvenance, type ImportConflict, type ImportContext, type ImportResult, type NormalizedFindings } from "#src/knowledge/import.ts";
 import { currentRevision, listMacros, listMacroUses, listPatches, listReferences, listRegions, listSymbols } from "#src/knowledge/read.ts";
 import { DEFAULT_SPACE, SEMANTIC_ORIGINS, type Analyzer } from "#src/knowledge/schema.ts";
-import { platformNames } from "#src/platform.ts";
+import { platformNames, platformNamesFor, romUseOfProgram, type RomUse } from "#src/platform.ts";
 import { listed, OPTIONS, runScript, UsageError, type Call } from "#src/script.ts";
 import { codeEntries, coverageConflicts, coverageEntries, coverageSeedKinds, executedStarts, imageReader, romOnlyRanges, type ImageByte } from "./lib/coverage.ts";
 import { dxaFindings, ghidraFindings, seedsFromKnowledge } from "./lib/findings.ts";
@@ -52,17 +52,19 @@ function showMacro(candidate: MacroCandidate) {
 
 /**
  * The macro candidates in the current code regions of every origin,
- * with the names of the knowledge in their args. A candidate is left out when
+ * with the names of the knowledge in their args, else the platform names of
+ * the ROMs that the program uses, as c64-source names them. A candidate is left out when
  * a name or a reference target is inside it, or a patch or a use overlaps it:
  * c64-source would write its instructions. The same use in the knowledge is
  * known. With `batchPath`, the candidates go to an apply batch with the
  * macros they need; a macro of the catalogue that the knowledge has with
  * another body leaves its candidates out of the batch.
  */
-function macroCandidates(space: string, byteAt: ImageByte, batchPath: string | undefined) {
+function macroCandidates(space: string, byteAt: ImageByte, batchPath: string | undefined, romUse: RomUse) {
   const db = openForRead();
   try {
-    const platform = space === DEFAULT_SPACE ? new Map(platformNames().map((entry) => [entry.address, entry.name])) : new Map<number, string>();
+    // The platform names that c64-source uses: a name of a ROM that the program does not use is no arg.
+    const platform = space === DEFAULT_SPACE ? new Map(platformNamesFor(romUse).map((entry) => [entry.address, entry.name])) : new Map<number, string>();
     const semantic = new Map(listSymbols(db, undefined, undefined, [...SEMANTIC_ORIGINS], space).map((symbol) => [symbol.address, symbol.name]));
     const code = listRegions(db, undefined, "code", undefined, space);
     const found = findMacroUses(byteAt, code, (address) => semantic.get(address) ?? platform.get(address));
@@ -197,7 +199,7 @@ async function analyze(call: Call): Promise<unknown> {
   const idioms = findIdioms(inProgram, { start: loaded.start, end: loaded.end }, covered);
 
   const revision = currentRevision(reader);
-  const seeds = seedsFromKnowledge(reader, entries, space);
+  const seeds = seedsFromKnowledge(reader, entries, space, executed.executed);
   // Knowledge routines and --entry first, then code regions and JMP tables, then idioms, then coverage, up to the seed bound.
   const fromCoverage = coverage === undefined ? [] : coverageEntries(coverage, inProgram);
   const known = [...seeds.entryPoints, ...codeEntries(reader, byteAt, space)];
@@ -216,20 +218,21 @@ async function analyze(call: Call): Promise<unknown> {
   const coverageUsed = fromCoverage.filter((entry) => seeds.entryPoints.includes(entry) || codeStarts.includes(entry)).length;
   // Platform names are C64 names: drive code and banks get none.
   const platform = space === DEFAULT_SPACE ? platformNames() : [];
-  const pointers = findPointers(byteAt, { start: loaded.start, end: loaded.end }, {
-    platform: (address) => platform.some((entry) => address >= entry.address && address <= entry.end),
-    sprites: listRegions(reader, undefined, "sprite", undefined, space),
-  });
   reader?.close();
   /** Imports the idioms as their own revision, after the analyzer's, and gives their part of the result. */
   const idiomsResult = () => {
     const imported = withWrite((db) => importFindings(db, { ...idioms.findings, space }, { description: "Idioms in the program" }));
     // The macro candidates read the code regions after both imports.
-    const macros = macroCandidates(space, byteAt, batchPath);
-    // Platform pitfalls are C64 facts: drive code and banks get none.
-    const pitfallDb = openForRead();
-    const pitfalls = space === DEFAULT_SPACE ? findPitfalls(byteAt, listRegions(pitfallDb, undefined, "code", undefined, space)) : [];
-    pitfallDb?.close();
+    const macros = macroCandidates(space, byteAt, batchPath, romUseOfProgram(coverage, program.state));
+    // Platform pitfalls are C64 facts: drive code and banks get none. Pitfalls and pointers read the code regions after both imports.
+    const codeDb = openForRead();
+    const code = listRegions(codeDb, undefined, "code", undefined, space);
+    const pitfalls = space === DEFAULT_SPACE ? findPitfalls(byteAt, code) : [];
+    const pointers = findPointers(byteAt, { start: loaded.start, end: loaded.end }, code, {
+      platform: (address) => platform.some((entry) => address >= entry.address && address <= entry.end),
+      sprites: listRegions(codeDb, undefined, "sprite", undefined, space),
+    });
+    codeDb?.close();
     return {
       idioms: {
         ...idioms.counts,

package/skills/c64-testing/SKILL.md

@@ -26,7 +26,7 @@ node <skill>/scripts/testing.ts test tests/moves-left.json --out .c64-re-tools/l
 node <skill>/scripts/testing.ts checklist tests/moves-left.json --item 'FIRE starts the game.'
 ```
 
-`testing.ts test` gives `result`: PASS, FAIL or INCONCLUSIVE. 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).
+`testing.ts test` gives `result`: PASS, FAIL or INCONCLUSIVE. With `--out`, a FAIL writes files into that directory: both screens and the difference image for each screen difference, and `memory.json`. `memory.json` has all bytes of each memory item that differs, and 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).
 
 `testing.ts checklist` gives a Markdown checklist for a human tester in `text`.
 
@@ -40,7 +40,7 @@ A run does steps on one program, with no comparison, and keeps the results as fi
 node <skill>/scripts/testing.ts run .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. A run has the action steps of a scenario: `write`, `registers`, `joystick`, `type`, `frames` and `runUntil`. It also has these steps:
+The run file gives where to start (a program, or a snapshot file), the steps, and optional symbols. A run file has no names unless it gives `"symbols": "knowledge"` or a JSON file of names. To go on from the live emulator, save its state with `c64_snapshot` action `save` and `out`, and start the run from that file. A run has the action steps of a scenario: `write`, `registers`, `joystick`, `type`, `frames` and `runUntil`. It also has these steps:
 
 | Step | Effect |
 |---|---|
@@ -122,6 +122,8 @@ 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. `compared` gives the count of items that both observations have. With `compared: 0`, `reason` tells what each observation has. Then the diff compared nothing, and the observations are not equal.
 
+For two snapshot files, `$00` and `$01` are the CPU port of the snapshot: the direction register and the data register. They are not the RAM under the port. `--ntsc` is only for snapshot files, and `--address` is only for memory files. The script refuses these options for the other kinds.
+
 `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.
@@ -159,7 +161,7 @@ The script refuses a snapshot that does not restore in its emulator. An example
 5. Run `testing.ts test`.
 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.
+   - `FAIL`: `differences` lists each difference with the checkpoint and the item. A memory item gives `bytes`: the count of the bytes that differ, and the first of these bytes. Each byte has the address, the original value and the rebuild value. `--max-listed` sets how many bytes it lists (default 50). `memory.json` in `--out` has all of them. Another item gives 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.
@@ -189,6 +191,7 @@ 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.
+- INCONCLUSIVE, `step N (kind): ...`: the step failed on one side. `reason` names the step and why.
 - `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.

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

@@ -47,7 +47,7 @@ Before the first step of each side, the script does a hard reset. The CPU stops
 | `{ "type": { "mode": "text", "text": "RUN\n" } }` | Put at most 1024 keys into the keyboard queue of the KERNAL. A program that reads the keyboard hardware does not see them. |
 | `{ "type": { "mode": "petscii", "bytes": [147] } }` | Put PETSCII codes from 1 to 255 into the keyboard queue of the KERNAL. Use it for keys that mode `text` does not have. |
 | `{ "runUntil": { "target": { "kind": "address", "address": "main_loop" }, "timeoutFrames": 600 } }` | Run until the CPU gets to an address. |
-| `{ "runUntil": { "target": { "kind": "memory", "address": "game_state", "operator": "eq", "value": 2 }, "timeoutFrames": 600 } }` | Run until a byte in memory compares true with `value`. `operator` is `eq`, `ne`, `lt`, `lte`, `gt` or `gte`. |
+| `{ "runUntil": { "target": { "kind": "memory", "address": "game_state", "operator": "eq", "value": 2 }, "timeoutFrames": 600 } }` | Run until a write to the byte makes the comparison with `value` true. `operator` is `eq`, `ne`, `lt`, `lte`, `gt` or `gte`. The run does not stop for a byte that is already true at the start. It also does not stop for a register that the hardware changes, for example `$d012`. For a raster line, use a `raster` target. |
 | `{ "runUntil": { "target": { "kind": "raster", "line": 250 }, "timeoutFrames": 5 } }` | Run until the raster beam gets to a line (0 to 311 for PAL, 0 to 262 for NTSC). Optional: `cycle` from 0 to 64. |
 | `{ "runUntil": { "target": { "kind": "address", "address": "irq_tick", "condition": { "kind": "raster", "line": 250 } }, "timeoutFrames": 600 } }` | Run until the CPU gets to an address while the condition is true. |
 | `{ "snapshot": "snapshots/start.vsf" }` | Restore a snapshot file. Usually with `side`: the snapshot of one program is not a state of the other. |
@@ -90,7 +90,7 @@ A run file (for `testing.ts run`) 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.
+- `symbols`: optional, `knowledge`, `none` (default), or a JSON file as for a subject. Without `symbols`, a run has no names: give `"symbols": "knowledge"` to use the names of the knowledge.
 - `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`.
 
@@ -124,7 +124,9 @@ Example: visit two rooms from the same start.
 
 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`.
+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 snapshot file that does not start with the signature of a VICE snapshot file also stops the script with `invalid-input`. The message names the step and the file.
+
+A run also examines each name of its steps before it starts the emulator. An unknown name stops the run with `invalid-input`, and the message names the step. In a scenario, a side that does not have a name gives INCONCLUSIVE, and `reason` names the step.
 
 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`.
 

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

@@ -10,6 +10,7 @@ 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";
+import { checkSnapshotFile, hasSignature, VSF_SIGNATURE } from "#src/media.ts";
 import { listed, UsageError } from "#src/script.ts";
 import { diffStates, type ChangedRange, type MachineState } from "./diff.ts";
 
@@ -59,30 +60,40 @@ function cpuValues(registers: Record<string, unknown>): Record<string, number |
 
 /** 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.
+ * The data of the C64MEM module of a VICE snapshot file: the data and the
+ * direction register of the CPU port, the cartridge lines (2 bytes), then
+ * the 64 KiB of RAM. Undefined when the file has no such module.
  */
-export function snapshotRam(file: Uint8Array): Uint8Array | undefined {
+function c64Memory(file: Uint8Array): Buffer | undefined {
   const bytes = Buffer.from(file);
-  if (bytes.subarray(0, VSF_MAGIC.length).toString("latin1") !== VSF_MAGIC) return undefined;
+  if (!hasSignature("vsf", bytes)) 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;
+  let at = VSF_SIGNATURE.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;
+    if (name === "C64MEM") return at + MODULE_HEADER + 4 + 0x10000 <= bytes.length ? bytes.subarray(at + MODULE_HEADER, at + MODULE_HEADER + 4 + 0x10000) : undefined;
     at += size;
   }
   return undefined;
 }
 
+/** The 64 KiB of C64 RAM that a VICE snapshot file holds, also the RAM under the CPU port at $00/$01. Undefined when the file has no C64MEM module. */
+export function snapshotRam(file: Uint8Array): Uint8Array | undefined {
+  return c64Memory(file)?.subarray(4);
+}
+
+/** The CPU port of a VICE snapshot file: the direction register ($00) and the data register ($01). Undefined when the file has no C64MEM module. */
+export function snapshotCpuPort(file: Uint8Array): { direction: number; data: number } | undefined {
+  const memory = c64Memory(file);
+  return memory === undefined ? undefined : { data: memory[0]!, direction: memory[1]! };
+}
+
 /**
  * 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
@@ -101,6 +112,10 @@ async function snapshotState(client: ViceSessionClient, path: string, ntsc: bool
       `${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.`,
     );
   }
+  // $00 and $01 are the CPU port of the file, not the RAM under it: a program reads and writes the port there.
+  const port = snapshotCpuPort(file)!;
+  memory[0] = port.direction;
+  memory[1] = port.data;
   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 | boolean> = {};
@@ -134,6 +149,8 @@ export function comparedItems(what: string, a: readonly string[], b: readonly st
 export async function diffFiles(first: string, second: string, options: { gap: number; max: number; ntsc: boolean; at?: number; out?: string }): Promise<Record<string, unknown>> {
   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");
+  if (options.at !== undefined && kind !== "memory") throw new UsageError(`--address is only for two memory files (.bin). ${kind === "snapshot" ? "A snapshot file holds all 64 KiB" : "An observation gives the address of each item"}: leave out --address`);
+  if (options.ntsc && kind !== "snapshot") throw new UsageError(`--ntsc is only for two snapshot files (.vsf), which restore in an emulator. ${kind === "memory" ? "Memory files" : "Observations"} compare as they are: leave out --ntsc`);
   const { gap, max } = options;
   let a: MachineState;
   let b: MachineState;
@@ -149,6 +166,8 @@ export async function diffFiles(first: string, second: string, options: { gap: n
     a = { memory: { base, bytes: left } };
     b = { memory: { base, bytes: right } };
   } else {
+    // Both files are snapshot files before the emulator starts.
+    for (const path of [first, second]) checkSnapshotFile(path, readProjectFile(path).bytes);
     const client = await ViceSessionClient.open({ videoStandard: options.ntsc ? "ntsc" : "pal" });
     try {
       a = await snapshotState(client, first, options.ntsc);

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

@@ -12,6 +12,7 @@ import { readPrg } from "#src/host-client/image.ts";
 import { MAX_MEMORY_READ, MAX_TRACE_FRAMES, MAX_TRACE_HITS, MAX_TRACE_POINTS, TRACE_KINDS, WireFailure, type TraceHit, type TraceKind } from "#src/host-client/tools.ts";
 import { readProjectFile, writeReported, type Written } from "#src/host-client/transfer.ts";
 import { readMemoryInParts, ViceSessionClient } from "#src/host-client/vice-session.ts";
+import { checkSnapshotFile } from "#src/media.ts";
 import { UsageError } from "#src/script.ts";
 import { namesOf } from "./scenario.ts";
 
@@ -162,7 +163,7 @@ function readRun(path: string): Run {
 /** The remedy for a start program that is no PRG. */
 const PROGRAM_REMEDY = "A run starts a PRG. Get the PRG out of the disk, tape or cartridge with disk.ts read (or disk.ts crt) of the c64-disk skill";
 
-/** Checks each file that the run reads before the emulator starts: the start program or snapshot, and each snapshot step. A refusal names the run file and the step. */
+/** Checks each file that the run reads before the emulator starts: the start program, and the start snapshot and each snapshot step, which must be VICE snapshot files. A refusal names the run file and the step. */
 function checkRunFiles(path: string, run: Run): void {
   const named = (where: string, check: () => unknown) => {
     try {
@@ -177,10 +178,10 @@ function checkRunFiles(path: string, run: Run): void {
     named("start.program", () => readPrg(program, PROGRAM_REMEDY));
   } else {
     const { snapshot } = run.start;
-    named("start.snapshot", () => readProjectFile(snapshot));
+    named("start.snapshot", () => checkSnapshotFile(snapshot, readProjectFile(snapshot).bytes));
   }
   run.steps.forEach((step, index) => {
-    if ("snapshot" in step) named(`step ${index + 1}: snapshot`, () => readProjectFile(step.snapshot));
+    if ("snapshot" in step) named(`step ${index + 1}: snapshot`, () => checkSnapshotFile(step.snapshot, readProjectFile(step.snapshot).bytes));
   });
 }
 
@@ -197,12 +198,27 @@ export async function runFile(path: string, out: string): Promise<{ output: Reco
   const at = (location: string): number => {
     if (location.startsWith("$")) return parseC64Address(location);
     const address = symbols.get(location);
-    if (address === undefined) throw new UsageError(`the symbols have no ${location}`);
-    return address;
+    if (address !== undefined) return address;
+    if (run.symbols === undefined || run.symbols === "none") {
+      throw new UsageError(`${location} is a name, and the run file has no symbols. A run file has no symbols unless it gives "symbols": "knowledge" for the names of the knowledge, or "symbols": "<file>" for a JSON file of names. Give one of them, or a $ address`);
+    }
+    throw new UsageError(`the symbols ${run.symbols} have no ${location}`);
   };
-  // The names of the action steps resolve before the emulator starts.
+  // Every name of the steps resolves before the emulator starts. A refusal names the step.
   run.steps.forEach((step, index) => {
-    if ((ACTION_STEP_KINDS as readonly string[]).some((kind) => kind in step) && !("observe" in step) && !("trace" in step)) checkStepNames([step as ActionStep], at, `run ${path}`, index + 1);
+    if ("trace" in step || "observe" in step) {
+      const names = "trace" in step ? step.points.flatMap((point) => [point.start, ...(point.end === undefined ? [] : [point.end])]) : step.memory === undefined || step.memory === "all" ? [] : step.memory.map((item) => (typeof item === "string" ? item : item.address));
+      for (const name of names) {
+        try {
+          at(name);
+        } catch (error) {
+          if (isRefusal(error)) throw new Refusal("invalid-input", `run ${path}: step ${index + 1}: ${error.message}`);
+          throw error;
+        }
+      }
+    } else if ((ACTION_STEP_KINDS as readonly string[]).some((kind) => kind in step)) {
+      checkStepNames([step as ActionStep], at, `run ${path}`, index + 1);
+    }
   });
   const files: string[] = [];
   const written: Written[] = [];