@henols/c64-re-tools 2.1.1 → 2.1.3

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

@@ -11,7 +11,7 @@ import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 
 import { Refusal } from "#src/errors.ts";
-import { type AddressRange, COVERAGE, coverageSeedKinds, formatC64Address, textToPetscii } from "#src/c64.ts";
+import { type AddressRange, coverageSeedKinds, formatC64Address, textToPetscii } from "#src/c64.ts";
 import { autostartLoaded, RUN_LIMIT_FRAMES } from "#src/host-client/autostart.ts";
 import { MAX_MEMORY_READ, WireFailure } from "#src/host-client/tools.ts";
 import { writeReported, type Written } from "#src/host-client/transfer.ts";
@@ -26,13 +26,13 @@ import { assemble } from "#src/native/acme.ts";
 import { analyze } from "#src/native/ghidra/analyze.ts";
 import { localToolContext } from "#src/native/local.ts";
 import { GHIDRA_LIMITS, type AssembledSymbol, type Diagnostic } from "#src/native/types.ts";
-import { decode as decodeRegister, describeAddress, platformNamesFor, romUseOf, romUseOfPort, type RomUse } from "#src/platform.ts";
+import { decode as decodeRegister, describeAddress, platformNames, platformNamesFor, romUseOfProgram } from "#src/platform.ts";
 import { resolveProjectPath } from "#src/project.ts";
 import { listed, OPTIONS, runScript, UsageError, type Call } from "#src/script.ts";
 import { knowledgeNames } from "#src/knowledge/names.ts";
 import { COPIER_SOURCE, LOADER_JUMP, loaderLimits, planLoader, rasterLine, loaderState, simulate, stopCause, VIC_DISPLAY_REGISTERS, type EntryState, type LoaderPlan } from "./lib/loader.ts";
-import { OPCODES } from "#src/opcodes.ts";
-import { entriesInData, entryOutsideImage, instructionText, layout, literalOperand, probeForms, render, switchesOf, type Layout, type PatchBlock, type Rendered } from "./lib/source.ts";
+import { instructionWith, OPCODES } from "#src/opcodes.ts";
+import { entriesInData, entryOutsideImage, layout, literalOperand, probeForms, render, switchesOf, type Layout, type PatchBlock, type Rendered } from "./lib/source.ts";
 
 /** At most this many diagnostics or differences of one check. */
 const MAX_DIAGNOSTICS = 20;
@@ -182,7 +182,7 @@ async function probe(laid: Layout): Promise<Set<string>> {
             ? formatC64Address((slot + 2 + (item.bytes[1]! < 0x80 ? item.bytes[1]! : item.bytes[1]! - 0x100)) & 0xffff)
             : literalOperand(item.form.opcode, item.bytes.length === 3 ? item.bytes[1]! | (item.bytes[2]! << 8) : item.bytes[1]!);
       lines.push(`* = ${formatC64Address(slot)}`);
-      lines.push(`        ${instructionText(item.form.opcode, item.form.suffix, operand)}`);
+      lines.push(`        ${instructionWith(item.form.opcode, operand, item.form.suffix)}`);
       lineOf.set(lines.length, item.form.key);
     });
     const built = await assembleFiles([{ name: "probe.asm", text: `${lines.join("\n")}\n` }], "probe.asm");
@@ -491,15 +491,10 @@ async function runLoader(path: string, program: Buffer, plan: LoaderPlan, image:
   }
 }
 
-/**
- * The ROMs the program uses: from the coverage when the knowledge has
- * it, else from $01 of the entry state, else both.
- */
-function romsInUse(image: ProgramImage, coverage: Uint8Array | undefined): RomUse & { from: "coverage" | "entry state" | "none" } {
-  if (coverage !== undefined) return { ...romUseOf(coverage, COVERAGE.romExecute), from: "coverage" };
-  const port = (image.state?.cpuPort as Record<string, unknown> | undefined)?.$01;
-  if (typeof port === "number") return { ...romUseOfPort(port), from: "entry state" };
-  return { basic: true, kernal: true, from: "none" };
+/** The platform names that `used` leaves out: the names of the ROMs that the program does not use. */
+function leftOutNames(used: ReadonlyArray<{ name: string }>): Set<string> {
+  const kept = new Set(used.map((entry) => entry.name));
+  return new Set(platformNames().flatMap((entry) => (kept.has(entry.name) ? [] : [entry.name])));
 }
 
 /** The first words of every file that the script writes. */
@@ -549,7 +544,8 @@ 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 romUse = romUseOfProgram(coverage, image.state);
+  const platform = platformNamesFor(romUse);
   const { instructions, dataOnly } = await decode(image, knowledge, entries, coverage);
   const laid = layout({
     segments: image.segments,
@@ -567,7 +563,7 @@ async function generate(call: Call): Promise<{ output: Record<string, unknown>;
     macroUses: knowledge.macroUses,
     ...(coverage === undefined ? {} : { coverage }),
     // The platform names are C64 names: drive code and banks get none. A ROM that the program does not use gives none.
-    ...(space === DEFAULT_SPACE ? { platform: platformNamesFor(romUse), describe: describeAddress, decode: decodeRegister } : {}),
+    ...(space === DEFAULT_SPACE ? { platform, platformLeftOut: leftOutNames(platform), describe: describeAddress, decode: decodeRegister } : {}),
   });
   const asBytes = await probe(laid);
   const header = [`Generated by c64-source from knowledge revision ${knowledge.revision}${space === DEFAULT_SPACE ? "" : ` in space ${space}`}.`, "Change names, comments, regions and modules in knowledge, then generate again."];
@@ -734,7 +730,7 @@ await runScript({
       name: "generate",
       summary: "Writes the source files, source-map.json and not_executed.json, and checks them. result is PASS when every check passes, else FAIL.",
       options: {
-        out: { ...OPTIONS.out, value: "<dir>", help: "the folder for the source files, relative to the project folder", required: true },
+        out: { ...OPTIONS.out, output: "folder", value: "<dir>", help: "the folder for the source files, relative to the project folder", required: true },
         entry: { ...OPTIONS.entry, multiple: true, help: "an entry point for Ghidra" },
         space: { ...OPTIONS.space, help: "the knowledge space of the program: c64 (the default), drive8, or bank0 to bank255. The coverage and --loader are for c64 only" },
         loader: { kind: "flag", help: "also write loader.asm and loader.prg: the loader copies the segments into place, sets the entry state of the knowledge, and jumps to the entry. It is checked in the emulator" },

package/skills/c64-static-analysis/SKILL.md

@@ -40,9 +40,10 @@ Both analyzers use the knowledge from the user and the LLM as seeds:
 
 - Each routine is an entry point.
 - Each region that is not code stays data.
+- Each symbol of the kind `data` or `variable` stays data. The region that is not code and that holds the symbol stays data, also a region of an analyzer. Without such a region, the byte of the symbol stays data. A symbol in a code region or at an executed address is not data. When the region holds an entry point or an executed address, only the byte of the symbol stays data.
 - Each name is a label. The listing, Ghidra and the decompiler show that name.
 
-Facts that an analyzer found are not seeds. A new analysis can then correct or remove them.
+Facts that an analyzer found are not seeds alone. A new analysis can then correct or remove them.
 
 More seeds come from evidence:
 
@@ -61,6 +62,7 @@ The analyzers take at most 1024 entry points. Knowledge routines and `--entry` c
 - An address is `$` and 1 to 4 hex digits, for example `'$c000'` or `'$fb'`, or a name. A name is a symbol, else an analyzer name that only one analyzer gives. Quote an address in a shell.
 - A range is `<start>-<end>`, for example `'$c000-$cfff'`. In a JSON file, a range is `start` and `end`.
 - Bytes in a JSON file are hex in a field `data`, for example `"data": "a900"`.
+- The script examines each `--out` path before it starts work. It refuses a path in `.c64-re-tools/knowledge/` and the index of the knowledge, because only c64-knowledge writes them. It refuses a folder where the command writes a file, and a file where the command writes a folder.
 - The result is one JSON object on one line. A file that the script writes shows as `{"out", "bytes", "sha256"}`. A list shows as `{"count", "listed"}`, and `rest` tells where to get the rest of a long list.
 - An error is `{"error": {"code": "...", "message": "..."}}`. The message tells what is wrong and what to do.
 - The exit status is 0 for done or PASS, 1 for FAIL, 2 for an error and 3 for INCONCLUSIVE.
@@ -87,10 +89,11 @@ The analyzers take at most 1024 entry points. Knowledge routines and `--entry` c
    - Ghidra: `functions` gives the number of routines that Ghidra found (`count`) and lists the first routines (`listed`). `decompilations` gives C-like code for the requested routines.
    - If a list is not complete, `rest` gives the c64-knowledge command that lists all of them. For `candidates`, `rest` tells you to give a larger `--max-listed`.
    - `conflicts` lists the places where the analyzer and the current knowledge disagree.
+   - DXA or Ghidra can find data where a run executed an instruction start (`executed`), or where a `user` or `llm` symbol of kind `label` or `routine` is (`knowledge`). Then the script does not write that data region, and the earlier region of the analyzer stays. `conflicts` lists each such place. Executed code and your names have priority over the guess of an analyzer.
    - `idioms` tells what the script found by pattern: RTS dispatch tables (`rtsTables`), JMP tables (`jumpTables`) and BIT skips (`bitSkips`). It also finds the `CBM80` header of a cartridge bank at `$8000` (`cartridgeHeaders`). The two start vectors of the header become entry points. The script writes them as knowledge with the origin `heuristic`, and seeds their targets into the same analysis. `candidates` gives DOP padding (`dop`) and opcodes that the program wrote and executed (`selfModified`). For `selfModified`, the write and the execution must be in one coverage file. A coverage file does not record the order. Thus a candidate can also be code that ran first, and that the program then wrote over. To prevent this, save one coverage file for each part of the program, for example the intro and the game. A loader that copies relocated code is also such a part. Clear the memory map between the parts. Each list has a `count`. The script does not write the candidates. Look at them and decide.
-   - `candidates.pointers` gives code that makes an address from immediates. A `vector` or a `zero-page pointer` candidate stores a low byte (`low`) and a high byte (`high`) to a vector or to a zero-page pair that `(zp),y` uses. Its `target` is in the program or has a platform name. A `sprite pointer` candidate stores an immediate (`at`) to a sprite pointer of the screen at $0400 in VIC bank 0. Its `target` (the value × 64) is in a `sprite` region. For each candidate that you confirm, write operand expressions with `operand` of the c64-knowledge skill, for example `operand '<low>' --lo <target name>` and `operand '<high>' --hi <target name>`. Then a rebuild can move the target.
+   - `candidates.pointers` gives code that makes an address from immediates. The script reads only the instructions of the code regions, from the start of each region. A `vector` or a `zero-page pointer` candidate stores a low byte (`low`) and a high byte (`high`) to a vector or to a zero-page pair. A `(zp),y` instruction of the code uses the zero-page pair. Its `target` is in the program or has a platform name. A `sprite pointer` candidate stores an immediate (`at`) to a sprite pointer of the screen at $0400 in VIC bank 0. Its `target` (the value × 64) is in a `sprite` region. For each candidate that you confirm, write operand expressions with `operand` of the c64-knowledge skill, for example `operand '<low>' --lo <target name>` and `operand '<high>' --hi <target name>`. Then a rebuild can move the target.
    - `candidates.pitfalls` gives code that a C64 runs in a different way than it reads. `raster-bit-8`: the instruction at `at` reads $D011, and the instruction at `store` writes the value back. A read of $D011 gives bit 8 of the raster line in bit 7. Thus the write can move the raster interrupt to line 256 or later, and on PAL past line 311 the interrupt never comes. Examine each candidate. Where the code must not keep bit 7, add a comment and test the program.
-   - `candidates.macros` gives runs of instructions that a macro writes as one line, for example `+inc16 ptr`. The script knows these 6502 idioms: `inc16`, `dec16`, `add16_8`, `add16`, `sub16`, `set16`, `mov16` and `wait_line`. It reads the code regions after the analysis. An arg has the name of a `user` or `llm` symbol or a platform name. Each candidate has `macro`, `start`, `end`, `args` and `text`. `known` counts the uses that the knowledge has. `leftOut` counts the candidates with a label inside, or with a patch or a use over them. The c64-source skill writes such a candidate as instructions. With `--out-macro-batch`, `batch` gives the file, the count of writes (`writes`) and the `apply` command. The batch holds the macros that the knowledge does not have, and the uses. When the knowledge has a macro with the same name and another body, `otherMacros` tells that the batch does not have its uses. The script does not write the candidates. Apply the batch, then generate the source again.
+   - `candidates.macros` gives runs of instructions that a macro writes as one line, for example `+inc16 ptr`. The script knows these 6502 idioms: `inc16`, `dec16`, `add16_8`, `add16`, `sub16`, `set16`, `mov16` and `wait_line`. It reads the code regions after the analysis. An arg has the name of a `user` or `llm` symbol or a platform name. A platform name of a ROM that the program does not use is not an arg, because the c64-source skill does not use it. Each candidate has `macro`, `start`, `end`, `args` and `text`. `known` counts the uses that the knowledge has. `leftOut` counts the candidates with a label inside, or with a patch or a use over them. The c64-source skill writes such a candidate as instructions. With `--out-macro-batch`, `batch` gives the file, the count of writes (`writes`) and the `apply` command. The batch holds the macros that the knowledge does not have, and the uses. When the knowledge has a macro with the same name and another body, `otherMacros` tells that the batch does not have its uses. The script does not write the candidates. Apply the batch, then generate the source again.
    - When the knowledge has coverage, a code finding replaces the DXA or Ghidra data where a run executed an instruction start. `coverageConflicts` lists the analyzer data regions where the coverage still shows executed code. Classify them as code with the c64-knowledge skill, or as `dual-use` when the bytes are also data. For many conflicts, write all classifications in one `apply` batch of the c64-knowledge skill.
 6. Give each important routine a name with the c64-knowledge skill. Then run the analysis again. The analyzers use the new names.
 

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

@@ -4,7 +4,7 @@
 // structural findings into .c64-re-tools/knowledge/.
 
 import { COVERAGE, formatC64Address, prgRange } from "#src/c64.ts";
-import { Refusal } from "#src/errors.ts";
+import { isRefusal, Refusal } from "#src/errors.ts";
 import { WireFailure } from "#src/host-client/tools.ts";
 import { writeReported } from "#src/host-client/transfer.ts";
 import { knowledgeNames } from "#src/knowledge/names.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));
@@ -121,6 +123,15 @@ function withRemedy(reason: string): string {
 
 /** One conflict: what the knowledge has, and what the analyzer found, under the analyzer's name. */
 function showConflict(conflict: ImportConflict, analyzer: Analyzer): Record<string, unknown> {
+  if (conflict.category === "code-evidence") {
+    return {
+      range: { start: formatC64Address(conflict.start), end: formatC64Address(conflict.end) },
+      [analyzer]: conflict.finding,
+      ...(conflict.executed === undefined ? {} : { executed: formatC64Address(conflict.executed) }),
+      ...(conflict.symbol === undefined ? {} : { knowledge: { ...conflict.symbol, address: formatC64Address(conflict.symbol.address) } }),
+      problem: conflict.executed !== undefined ? "a run executed code here: the data finding is not imported" : "the knowledge has a code name here: the data finding is not imported",
+    };
+  }
   if (conflict.category === "symbol") {
     return {
       at: formatC64Address(conflict.address),
@@ -188,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)];
@@ -207,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,
@@ -270,7 +282,7 @@ async function analyze(call: Call): Promise<unknown> {
         written = writeReported(listingPath, listing, { what: "--out-listing" });
       } catch (error) {
         const recorded = imported.revision === null ? "The knowledge did not change." : `The knowledge has the findings as revision ${imported.revision}.`;
-        throw new WireFailure("operation-failed", `The script did not write the listing to ${listingPath}: ${(error as Error).message}. ${recorded}`);
+        throw new WireFailure(isRefusal(error) ? error.code : "operation-failed", `The script did not write the listing to ${listingPath}: ${(error as Error).message.replace(/\.$/, "")}. ${recorded}`);
       }
     }
     const found = idiomsResult();
@@ -334,9 +346,9 @@ await runScript({
         decompile: { kind: "address", value: "<address>", multiple: true, help: "ghidra: a routine to decompile, at most 32" },
         space: OPTIONS.space,
         "max-listed": { ...OPTIONS["max-listed"], help: "list at most n labels, functions or candidates (default 50, 0 for none). The counts are always given, and the knowledge has all labels and functions" },
-        "out-listing": { kind: "path", value: "<file>", help: "dxa: write the disassembly listing to this project file" },
-        "out-instructions": { kind: "path", value: "<file>", help: "ghidra: write every instruction (address, bytes, mnemonic, mode, operand, target, executed) to this project file as JSON" },
-        "out-macro-batch": { kind: "path", value: "<file>", help: "write the macro candidates as an apply batch of c64-knowledge (the macros and their uses) to this project file" },
+        "out-listing": { kind: "path", output: "file", value: "<file>", help: "dxa: write the disassembly listing to this project file" },
+        "out-instructions": { kind: "path", output: "file", value: "<file>", help: "ghidra: write every instruction (address, bytes, mnemonic, mode, operand, target, executed) to this project file as JSON" },
+        "out-macro-batch": { kind: "path", output: "file", value: "<file>", help: "write the macro candidates as an apply batch of c64-knowledge (the macros and their uses) to this project file" },
       },
       notes: "The program and the coverage come from the knowledge: put them in with knowledge.ts image and coverage of the c64-knowledge skill. The executed code of the coverage is seeded. Routine symbols in the knowledge are entry points too. Ghidra needs at least one entry point. DXA finds the SYS of a BASIC start by itself.",
       run: analyze,

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 |
 |---|---|
@@ -120,7 +120,9 @@ node <skill>/scripts/testing.ts diff .c64-re-tools/local/runs/rooms/results.json
 
 - 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, `--address` gives the address of its first byte.
-- Two observations of runs, also of one run: the changed memory items and registers.
+- 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`.
 
@@ -135,6 +137,7 @@ The script refuses a snapshot that does not restore in its emulator. An example
 - An address is `$` and 1 to 4 hex digits, for example `'$c000'` or `'$fb'`, or a name. A name is a symbol, else an analyzer name that only one analyzer gives. Quote an address in a shell.
 - A range is `<start>-<end>`, for example `'$c000-$cfff'`. In a JSON file, a range is `start` and `end`.
 - Bytes in a JSON file are hex in a field `data`, for example `"data": "a900"`.
+- The script examines each `--out` path before it starts work. It refuses a path in `.c64-re-tools/knowledge/` and the index of the knowledge, because only c64-knowledge writes them. It refuses a folder where the command writes a file, and a file where the command writes a folder.
 - The result is one JSON object on one line. A file that the script writes shows as `{"out", "bytes", "sha256"}`. A list shows as `{"count", "listed"}`, and `rest` tells where to get the rest of a long list.
 - An error is `{"error": {"code": "...", "message": "..."}}`. The message tells what is wrong and what to do.
 - The exit status is 0 for done or PASS, 1 for FAIL, 2 for an error and 3 for INCONCLUSIVE.
@@ -154,11 +157,11 @@ The script refuses a snapshot that does not restore in its emulator. An example
 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 a `runUntil` step with an `address` target at a routine. Do not wait for a time.
-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 `assembler.ts build --project <folder> ... > <folder>/build/game.json`.
+4. Write the symbol file of the rebuild with `--out-symbols build/game.json` of c64-assembler `build`. Give `--all-symbols`, so that the file also has the constants that the source does not use.
 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.
@@ -188,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> = {};
@@ -118,10 +133,24 @@ const show = (range: ChangedRange) => ({ start: formatC64Address(range.start), e
 /** 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);
 
+/**
+ * How many items two observations have in common, by name: the items that the
+ * diff compared. With none, the reason names what each side has, so that a
+ * count of 0 does not read as "equal".
+ */
+export function comparedItems(what: string, a: readonly string[], b: readonly string[], first: string, second: string): { compared: number; reason?: string } {
+  const compared = a.filter((name) => b.includes(name)).length;
+  if (compared > 0) return { compared };
+  const has = (names: readonly string[]) => (names.length === 0 ? "none" : names.join(", "));
+  return { compared, reason: `No ${what} was compared: the observations have none in common. ${first} has ${has(a)}; ${second} has ${has(b)}.` };
+}
+
 /** 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>> {
   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;
@@ -137,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);
@@ -159,8 +190,8 @@ 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, showValue, rest) }),
-    ...(diff.observed === undefined ? {} : { observed: listed(diff.observed, max, undefined, rest) }),
+    ...(diff.values === undefined ? {} : { registers: { ...(kind === "observation" ? comparedItems("register", Object.keys(a.values ?? {}), Object.keys(b.values ?? {}), first, second) : {}), ...listed(diff.values, max, showValue, rest) } }),
+    ...(diff.observed === undefined ? {} : { observed: { ...comparedItems("memory item", Object.keys(a.observed ?? {}), Object.keys(b.observed ?? {}), first, second), ...listed(diff.observed, max, undefined, rest) } }),
     ...(written === undefined ? {} : written),
   };
 }