@henols/c64-re-tools 2.0.0-rc.9 → 2.0.0

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

@@ -1,13 +1,13 @@
-// 6502 idioms that hide code from a disassembler (D44): RTS dispatch tables,
+// 6502 idioms that hide code from a disassembler: RTS dispatch tables,
 // JMP tables and BIT skips are found by their exact instruction patterns and
 // become heuristic findings and entry points; DOP padding and self-modified
-// opcodes are only reported. A self-modified opcode is one that one run wrote
-// and executed, in either order, since a coverage file holds no order (R3-04):
-// a copier's writes in one run and their execution in another do not count (F-16). A table's length is not known statically: entries
+// opcodes are only reported. The CBM80 header of a cartridge bank at $8000
+// gives its two start vectors as entry points. A self-modified opcode is one that one run wrote
+// and executed, in either order, since a coverage file holds no order:
+// a copier's writes in one run and their execution in another do not count. A table's length is not known statically: entries
 // count while each target is a plausible instruction in the program.
 
 import { COVERAGE } from "#src/c64.ts";
-import { joinCoverage } from "#src/host-client/coverage.ts";
 import type { NormalizedFindings } from "#src/knowledge/import.ts";
 import type { ImageByte } from "./coverage.ts";
 
@@ -17,6 +17,8 @@ const LDA_INDEXED = new Set([0xbd, 0xb9]);
 const JAMS = new Set([0x02, 0x12, 0x22, 0x32, 0x42, 0x52, 0x62, 0x72, 0x92, 0xb2, 0xd2, 0xf2]);
 /** Undocumented NOPs with an operand byte (DOP): padding between instructions hides the real ones. */
 const DOPS = new Set([0x04, 0x14, 0x34, 0x44, 0x54, 0x64, 0x74, 0x80, 0x82, 0x89, 0xc2, 0xd4, 0xe2, 0xf4]);
+/** "CBM80" in PETSCII at $8004: the KERNAL then starts the cartridge through the vectors at $8000 (cold) and $8002 (warm). */
+const CBM80 = [0xc3, 0xc2, 0xcd, 0x38, 0x30];
 
 export interface Idioms {
   findings: NormalizedFindings;
@@ -24,7 +26,7 @@ export interface Idioms {
   entryPoints: number[];
   /** Table ranges for the same run: they are data. */
   dataRanges: Array<{ start: number; end: number }>;
-  counts: { rtsTables: number; jumpTables: number; bitSkips: number };
+  counts: { cartridgeHeaders: number; rtsTables: number; jumpTables: number; bitSkips: number };
   /** Seen in the coverage, not written: the LLM decides. All of them: the result lists the first ones. */
   candidates: { dop: number[]; selfModified: number[] };
 }
@@ -41,13 +43,13 @@ const word = (byteAt: ImageByte, address: number) => {
   return low === undefined || high === undefined ? undefined : low | (high << 8);
 };
 
-/** `runs` are the coverage maps, one for each file. */
-export function findIdioms(byteAt: ImageByte, range: { start: number; end: number }, runs: readonly Uint8Array[] = []): Idioms {
-  const coverage = runs.length === 0 ? undefined : joinCoverage(runs);
+/** `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"] = [];
   const references: NormalizedFindings["references"] = [];
   const entryPoints = new Set<number>();
-  const counts = { rtsTables: 0, jumpTables: 0, bitSkips: 0 };
+  const counts = { cartridgeHeaders: 0, rtsTables: 0, jumpTables: 0, bitSkips: 0 };
   const taken = (start: number, end: number) => regions.some((region) => start <= region.end && end >= region.start);
   const addRegion = (start: number, end: number, type: NormalizedFindings["regions"][number]["type"]) => {
     if (start < range.start || end > range.end || taken(start, end)) return false;
@@ -55,6 +57,14 @@ export function findIdioms(byteAt: ImageByte, range: { start: number; end: numbe
     return true;
   };
 
+  if (range.start <= 0x8000 && range.end >= 0x8008 && CBM80.every((byte, index) => byteAt(0x8004 + index) === byte)) {
+    const vectors = [word(byteAt, 0x8000)!, word(byteAt, 0x8002)!].filter((target) => plausible(byteAt, target, range));
+    if (addRegion(0x8000, 0x8003, "addresses") && addRegion(0x8004, 0x8008, "petscii")) {
+      counts.cartridgeHeaders++;
+      for (const target of vectors) entryPoints.add(target);
+    }
+  }
+
   for (let at = range.start; at + 8 <= range.end; at++) {
     // RTS dispatch: LDA high,X / PHA / LDA low,X / PHA / RTS.
     if (LDA_INDEXED.has(byteAt(at)!) && byteAt(at + 3) === 0x48 && LDA_INDEXED.has(byteAt(at + 4)!) && byteAt(at + 7) === 0x48 && byteAt(at + 8) === 0x60) {
@@ -121,11 +131,10 @@ export function findIdioms(byteAt: ImageByte, range: { start: number; end: numbe
   // Candidates from the coverage: DOP padding that ran, and opcodes that one run wrote and executed.
   const candidates = { dop: [] as number[], selfModified: [] as number[] };
   if (coverage !== undefined) {
-    const both = COVERAGE.ramWrite | COVERAGE.ramExecute;
     for (let address = range.start; address <= range.end; address++) {
       if ((coverage[address]! & COVERAGE.ramExecute) === 0) continue;
       if (DOPS.has(byteAt(address)!)) candidates.dop.push(address);
-      if (runs.some((run) => (run[address]! & both) === both)) candidates.selfModified.push(address);
+      if (covered!.selfModified[address] === 1) candidates.selfModified.push(address);
     }
   }
 

package/skills/c64-static-analysis/scripts/{instructions.ts → lib/instructions.ts}

@@ -1,4 +1,4 @@
-// The structured instruction list (D44): Ghidra's decoded instructions with
+// The structured instruction list: Ghidra's decoded instructions with
 // the addressing mode, the operand in 6502 syntax, the flow target and,
 // with a coverage file, whether the instruction ran.
 

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

@@ -0,0 +1,233 @@
+// Macro candidates: runs of instructions that are a known 6502 idiom,
+// such as a 16-bit increment, and that a macro can write as one line. They
+// are only reported, never written: the LLM applies them as macro uses with
+// c64-knowledge, and c64-source writes a use only when it gives the bytes of
+// the image.
+//
+// The catalogue is fixed, so each candidate has a name and a body that is
+// known to be correct. A search for any repeated sequence was weighed and not
+// chosen: it gives many candidates without a name.
+
+import { instructionLength } from "#src/c64.ts";
+import type { ImageByte } from "./coverage.ts";
+
+/** A macro of the catalogue: its params and its ACME body, which names a param with a dot. */
+export interface MacroIdiom {
+  name: string;
+  params: string[];
+  body: string;
+  comment: string;
+}
+
+export const CATALOGUE: readonly MacroIdiom[] = [
+  { name: "inc16", params: ["dst"], body: ["        inc .dst", "        bne +", "        inc .dst+1", "+"].join("\n"), comment: "Adds 1 to the 16-bit value at dst." },
+  { name: "dec16", params: ["dst"], body: ["        lda .dst", "        bne +", "        dec .dst+1", "+       dec .dst"].join("\n"), comment: "Subtracts 1 from the 16-bit value at dst. It changes A." },
+  {
+    name: "add16_8",
+    params: ["dst", "value"],
+    body: ["        clc", "        lda .dst", "        adc #.value", "        sta .dst", "        bcc +", "        inc .dst+1", "+"].join("\n"),
+    comment: "Adds the 8-bit value to the 16-bit value at dst. It changes A.",
+  },
+  {
+    name: "add16",
+    params: ["dst", "value"],
+    body: ["        clc", "        lda .dst", "        adc #<.value", "        sta .dst", "        lda .dst+1", "        adc #>.value", "        sta .dst+1"].join("\n"),
+    comment: "Adds the 16-bit value to the 16-bit value at dst. It changes A.",
+  },
+  {
+    name: "sub16",
+    params: ["dst", "value"],
+    body: ["        sec", "        lda .dst", "        sbc #<.value", "        sta .dst", "        lda .dst+1", "        sbc #>.value", "        sta .dst+1"].join("\n"),
+    comment: "Subtracts the 16-bit value from the 16-bit value at dst. It changes A.",
+  },
+  {
+    name: "set16",
+    params: ["dst", "value"],
+    body: ["        lda #<.value", "        sta .dst", "        lda #>.value", "        sta .dst+1"].join("\n"),
+    comment: "Puts the 16-bit value at dst. It changes A.",
+  },
+  {
+    name: "mov16",
+    params: ["dst", "src"],
+    body: ["        lda .src", "        sta .dst", "        lda .src+1", "        sta .dst+1"].join("\n"),
+    comment: "Copies the 16-bit value at src to dst. It changes A.",
+  },
+  { name: "wait_line", params: ["line"], body: ["        lda #.line", "-       cmp $d012", "        bne -"].join("\n"), comment: "Waits until the raster line (bits 0-7) is line. It changes A." },
+];
+
+/** A run of instructions that one macro of the catalogue can write, with its args as ACME expressions. */
+export interface MacroCandidate {
+  macro: string;
+  start: number;
+  end: number;
+  args: string[];
+}
+
+/** One instruction: its opcode, its length and its operand value. */
+export interface Instruction {
+  opcode: number;
+  length: number;
+  value: number;
+}
+
+/** An address operand: zero page or absolute, of the same memory in one idiom. */
+interface Operand {
+  value: number;
+  absolute: boolean;
+}
+
+/** Opcodes by mnemonic, zero page first, then absolute. */
+const MEMORY = {
+  lda: [0xa5, 0xad],
+  sta: [0x85, 0x8d],
+  inc: [0xe6, 0xee],
+  dec: [0xc6, 0xce],
+} as const;
+const IMMEDIATE = { lda: 0xa9, adc: 0x69, sbc: 0xe9 } as const;
+const CLC = 0x18;
+const SEC = 0x38;
+const BNE = 0xd0;
+const BCC = 0x90;
+const CMP_ABSOLUTE = 0xcd;
+
+/**
+ * Names the args of a candidate: `address` gives the name of an address in
+ * the knowledge, or undefined. An absolute operand below $0100 keeps four
+ * digits, so ACME writes the absolute form again.
+ */
+export type Namer = (address: number) => string | undefined;
+
+const hex2 = (value: number) => `$${value.toString(16).padStart(2, "0")}`;
+const hex4 = (value: number) => `$${value.toString(16).padStart(4, "0")}`;
+
+function addressArg(operand: Operand, name: Namer): string {
+  const named = name(operand.value);
+  // A name of a zero-page address gives the zero-page form: an absolute operand there keeps its number.
+  if (named !== undefined && (operand.value >= 0x100 || !operand.absolute)) return named;
+  return operand.absolute ? hex4(operand.value) : hex2(operand.value);
+}
+
+/** The memory operand of `instruction` when it is one of the opcodes of the mnemonic. */
+function memory(instruction: Instruction | undefined, mnemonic: keyof typeof MEMORY): Operand | undefined {
+  if (instruction === undefined) return undefined;
+  const index = (MEMORY[mnemonic] as readonly number[]).indexOf(instruction.opcode);
+  return index < 0 ? undefined : { value: instruction.value, absolute: index === 1 };
+}
+
+const same = (a: Operand | undefined, b: Operand | undefined, offset = 0): boolean => a !== undefined && b !== undefined && a.absolute === b.absolute && b.value === a.value + offset;
+const immediate = (instruction: Instruction | undefined, opcode: number) => (instruction?.opcode === opcode ? instruction.value : undefined);
+/** A branch past the next instruction only: its distance is the length of that instruction. */
+const skips = (branch: Instruction | undefined, opcode: number, next: Instruction | undefined) => branch?.opcode === opcode && next !== undefined && branch.value === next.length;
+
+/** Each idiom: how many instructions it takes, and its args when the instructions match. */
+const MATCHERS: Record<string, { count: number; match: (run: Instruction[], name: Namer) => string[] | undefined }> = {
+  inc16: {
+    count: 3,
+    match: ([low, branch, high], name) => {
+      const dst = memory(low, "inc");
+      return same(dst, memory(high, "inc"), 1) && skips(branch, BNE, high) ? [addressArg(dst!, name)] : undefined;
+    },
+  },
+  dec16: {
+    count: 4,
+    match: ([load, branch, high, low], name) => {
+      const dst = memory(load, "lda");
+      return same(dst, memory(low, "dec")) && same(dst, memory(high, "dec"), 1) && skips(branch, BNE, high) ? [addressArg(dst!, name)] : undefined;
+    },
+  },
+  add16_8: {
+    count: 6,
+    match: ([clc, load, add, store, branch, high], name) => {
+      const dst = memory(load, "lda");
+      const value = immediate(add, IMMEDIATE.adc);
+      const ok = clc?.opcode === CLC && value !== undefined && same(dst, memory(store, "sta")) && same(dst, memory(high, "inc"), 1) && skips(branch, BCC, high);
+      return ok ? [addressArg(dst!, name), hex2(value)] : undefined;
+    },
+  },
+  add16: { count: 7, match: (run, name) => wide(run, name, CLC, IMMEDIATE.adc) },
+  sub16: { count: 7, match: (run, name) => wide(run, name, SEC, IMMEDIATE.sbc) },
+  set16: {
+    count: 4,
+    match: ([loadLow, storeLow, loadHigh, storeHigh], name) => {
+      const low = immediate(loadLow, IMMEDIATE.lda);
+      const high = immediate(loadHigh, IMMEDIATE.lda);
+      const dst = memory(storeLow, "sta");
+      if (low === undefined || high === undefined || !same(dst, memory(storeHigh, "sta"), 1)) return undefined;
+      const value = low | (high << 8);
+      return [addressArg(dst!, name), name(value) ?? hex4(value)];
+    },
+  },
+  mov16: {
+    count: 4,
+    match: ([loadLow, storeLow, loadHigh, storeHigh], name) => {
+      const src = memory(loadLow, "lda");
+      const dst = memory(storeLow, "sta");
+      if (!same(src, memory(loadHigh, "lda"), 1) || !same(dst, memory(storeHigh, "sta"), 1)) return undefined;
+      return [addressArg(dst!, name), addressArg(src!, name)];
+    },
+  },
+  wait_line: {
+    count: 3,
+    match: ([load, compare, branch]) => {
+      const line = immediate(load, IMMEDIATE.lda);
+      // BNE back to the CMP: 5 bytes back from the end of the BNE.
+      return line !== undefined && compare?.opcode === CMP_ABSOLUTE && compare.value === 0xd012 && branch?.opcode === BNE && branch.value === 0xfb ? [hex2(line)] : undefined;
+    },
+  },
+};
+
+/** add16 and sub16: the carry, then the low and the high byte, each with an immediate of the 16-bit value. */
+function wide([carry, loadLow, low, storeLow, loadHigh, high, storeHigh]: Instruction[], name: Namer, carryOpcode: number, opcode: number): string[] | undefined {
+  const dst = memory(loadLow, "lda");
+  const lowValue = immediate(low, opcode);
+  const highValue = immediate(high, opcode);
+  const ok =
+    carry?.opcode === carryOpcode && lowValue !== undefined && highValue !== undefined && same(dst, memory(storeLow, "sta")) && same(dst, memory(loadHigh, "lda"), 1) && same(dst, memory(storeHigh, "sta"), 1);
+  return ok ? [addressArg(dst!, name), hex4(lowValue | (highValue << 8))] : undefined;
+}
+
+/** The instruction at `at`, or undefined when a byte of it is outside the range or the image. */
+export function instructionAt(byteAt: ImageByte, at: number, end: number): Instruction | undefined {
+  const opcode = byteAt(at);
+  if (opcode === undefined) return undefined;
+  const length = instructionLength(opcode);
+  if (at + length - 1 > end) return undefined;
+  const bytes = Array.from({ length: length - 1 }, (_, offset) => byteAt(at + 1 + offset));
+  if (bytes.some((byte) => byte === undefined)) return undefined;
+  return { opcode, length, value: length === 1 ? 0 : length === 2 ? bytes[0]! : bytes[0]! | (bytes[1]! << 8) };
+}
+
+/**
+ * Finds the macro candidates in code regions. Each region is read as
+ * instructions from its start; at each instruction the idioms of the
+ * catalogue are tried in order, and a match is a candidate. Candidates do not
+ * overlap: the scan goes on after the end of a match.
+ */
+export function findMacroUses(byteAt: ImageByte, regions: ReadonlyArray<{ start: number; end: number }>, name: Namer): MacroCandidate[] {
+  const candidates: MacroCandidate[] = [];
+  for (const region of [...regions].sort((a, b) => a.start - b.start)) {
+    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;
+    }
+    for (let index = 0; index < run.length; ) {
+      const found = CATALOGUE.flatMap((idiom) => {
+        const matcher = MATCHERS[idiom.name]!;
+        const part = run.slice(index, index + matcher.count);
+        const args = part.length === matcher.count ? matcher.match(part, name) : undefined;
+        return args === undefined ? [] : [{ idiom, count: matcher.count, args }];
+      })[0];
+      if (found === undefined) {
+        index++;
+        continue;
+      }
+      const last = run[index + found.count - 1]!;
+      candidates.push({ macro: found.idiom.name, start: run[index]!.at, end: last.at + last.length - 1, args: found.args });
+      index += found.count;
+    }
+  }
+  return candidates;
+}

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

@@ -0,0 +1,68 @@
+// Platform pitfalls in code regions: code that a C64 runs in another
+// way than it reads. A fixed catalogue, reported as candidates only.
+//
+// raster-bit-8: a read of $D011 gives bit 8 of the current raster line in
+// bit 7. Code that writes the value back without clearing bit 7 sets bit 8 of
+// the raster compare: the next raster interrupt then comes at line 256 or
+// later, or never on a PAL machine past line 311 (the Bruce Lee freeze).
+
+import type { ImageByte } from "./coverage.ts";
+import { instructionAt, type Instruction } from "./macros.ts";
+
+export interface Pitfall {
+  kind: "raster-bit-8";
+  /** The instruction that reads $D011. */
+  at: number;
+  /** The instruction that writes the value back to $D011. */
+  store: number;
+}
+
+const D011 = 0xd011;
+/** LDA, LDX and LDY absolute, and the stores of the same register. */
+const LOADS: Record<number, "a" | "x" | "y"> = { 0xad: "a", 0xae: "x", 0xac: "y" };
+const STORES: Record<number, "a" | "x" | "y"> = { 0x8d: "a", 0x8e: "x", 0x8c: "y" };
+/** INC, DEC, ASL, ROL and ROR absolute: they read the register and write it back. LSR shifts a 0 into bit 7. */
+const READ_MODIFY_WRITE = new Set([0xee, 0xce, 0x0e, 0x2e, 0x6e]);
+/** Instructions after which the next one is not the next in the flow: a jump, a return, a call or a branch. */
+const FLOW = new Set([0x4c, 0x6c, 0x20, 0x60, 0x40, 0x00, 0x10, 0x30, 0x50, 0x70, 0x90, 0xb0, 0xd0, 0xf0]);
+/** Instructions that load A, X or Y with a new value, which ends what the load of $D011 gave. */
+const NEW_VALUE: Record<"a" | "x" | "y", Set<number>> = {
+  a: new Set([0xa9, 0xa5, 0xb5, 0xad, 0xbd, 0xb9, 0xa1, 0xb1, 0x8a, 0x98, 0x68]),
+  x: new Set([0xa2, 0xa6, 0xb6, 0xae, 0xbe, 0xaa, 0xba]),
+  y: new Set([0xa0, 0xa4, 0xb4, 0xac, 0xbc, 0xa8]),
+};
+/** The most instructions between the load and the store. */
+const WINDOW = 8;
+
+/** The raster-bit-8 pitfalls in the code regions, in address order. */
+export function findPitfalls(byteAt: ImageByte, regions: ReadonlyArray<{ start: number; end: number }>): Pitfall[] {
+  const found: Pitfall[] = [];
+  for (const region of [...regions].sort((a, b) => a.start - b.start)) {
+    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;
+    }
+    run.forEach((instruction, index) => {
+      if (instruction.length !== 3 || instruction.value !== D011) return;
+      if (READ_MODIFY_WRITE.has(instruction.opcode)) {
+        found.push({ kind: "raster-bit-8", at: instruction.at, store: instruction.at });
+        return;
+      }
+      const register = LOADS[instruction.opcode];
+      if (register === undefined) return;
+      for (const next of run.slice(index + 1, index + 1 + WINDOW)) {
+        // AND #imm without bit 7 clears raster bit 8: the code knows about it.
+        if (register === "a" && next.opcode === 0x29 && (next.value & 0x80) === 0) return;
+        if (STORES[next.opcode] === register && next.length === 3 && next.value === D011) {
+          found.push({ kind: "raster-bit-8", at: instruction.at, store: next.at });
+          return;
+        }
+        if (FLOW.has(next.opcode) || NEW_VALUE[register].has(next.opcode)) return;
+      }
+    });
+  }
+  return found;
+}

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

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

package/skills/c64-testing/SKILL.md

@@ -22,11 +22,11 @@ A PASS proves only the behavior that the scenario does and observes. It does not
 The script starts one emulator through the host runtime. It runs the scenario on the original and then on the rebuild. Before each side, it does a hard reset of the emulator. The CPU then stops at the reset vector.
 
 ```
-node <skill>/scripts/test.ts tests/moves-left.json --out results/moves-left
+node <skill>/scripts/test.ts tests/moves-left.json --out .c64-re-tools/local/results/moves-left
 node <skill>/scripts/checklist.ts tests/moves-left.json --item 'FIRE starts the game.'
 ```
 
-The test script prints one JSON object. The exit status is 0 for PASS, 1 for FAIL, 3 for INCONCLUSIVE and 2 for a bad call. With `--out`, a FAIL writes files into that directory: both screens and the difference image for each screen difference, and `memory.json` with each byte that differs. `files` in the result names them.
+The test script prints one JSON object. The exit status is 0 for PASS, 1 for FAIL, 3 for INCONCLUSIVE and 2 for a bad call. With `--out`, a FAIL writes files into that directory: both screens and the difference image for each screen difference, and `memory.json` with each byte that differs. `files` in the result names them. A PASS writes no files. To keep the screens of a PASS, use a run (below).
 
 The checklist script prints a Markdown checklist for a human tester.
 
@@ -35,31 +35,60 @@ The checklist script prints a Markdown checklist for a human tester.
 A run does steps on one program, with no comparison, and keeps the results as files. Use it for many steps. One run replaces many emulator calls, for example a visit to each room of a game.
 
 ```
-node <skill>/scripts/run.ts runs/rooms.json --out runs/rooms
+node <skill>/scripts/run.ts .c64-re-tools/local/runs/rooms/run.json --out .c64-re-tools/local/runs/rooms
 ```
 
 The run file gives where to start (a program, or a snapshot file), the steps, and optional symbols. To go on from the live emulator, save its state with `c64_snapshot` action `save` and `out`, and start the run from that file. Besides the steps of a scenario, a run has these steps:
 
 | Step | Effect |
 |---|---|
-| `{ "snapshot": "snapshots/room0.vsf" }` | Restore a snapshot file. |
+| `{ "snapshot": ".c64-re-tools/local/snapshots/room0.vsf" }` | Restore a snapshot file. |
 | `{ "save": "room3" }` | Write the state now to `room3.vsf` in the output directory. |
 | `{ "screen": "room3" }` | Write the screen to `room3.png`. |
-| `{ "coverage": "room3" }` | Write the coverage map since the start or the last coverage step to `room3.bin`, then clear the map. |
+| `{ "coverage": "room3" }` | Write the coverage map since the start or the last coverage step to `room3.bin`, then clear the map. Add the map to the knowledge with `coverage` of the c64-knowledge skill. |
 | `{ "observe": "room3", "memory": ["$c100"], "registers": true }` | Record memory, registers, `vicii` or `sprites` in `results.json`. |
+| `{ "trace": "d011", "points": [{ "kind": "write", "at": "$d011" }], "frames": 100 }` | Record each hit of the points for 100 frames in `d011.json`: the instruction, its registers and the raster line and cycle. A point is `exec`, `read` or `write`, at an address or a name, with an optional `end`. `maxHits` limits the hits. |
+| `{ "observe": "all3", "memory": "all" }` | Write all 64 KiB of RAM to `all3.bin`, also the RAM under the ROMs and the I/O area. |
+
+A memory item can have `"view": "ram"`. Then it reads the RAM under the ROMs and the I/O area, for example code at `$e000` under the KERNAL. The default view `cpu` reads as the CPU sees memory. An item larger than 4096 bytes goes into its own `.bin` file, and `results.json` gives the file name.
 
 See [references/scenario-format.md](references/scenario-format.md), section Runs. The script prints one JSON object. The exit status is 0 when all steps ran, 1 when a step did not reach its target, and 2 for a bad call. A long run can need more time than one shell call. Then run it in the background.
 
+### Differences
+
+```
+node <skill>/scripts/diff.ts .c64-re-tools/local/runs/rooms/before.vsf .c64-re-tools/local/runs/rooms/after.vsf
+node <skill>/scripts/diff.ts .c64-re-tools/local/runs/rooms/results.json:room0 .c64-re-tools/local/runs/rooms/results.json:room3
+```
+
+`diff.ts` tells what changed between two states of one kind. Use it in place of your own compare script.
+
+- Two snapshot files: the script restores each one in its own emulator. It gives the changed ranges of the RAM and of the colour RAM, and the changed VIC-II, CIA, SID and CPU registers.
+- Two memory files of a run: the changed ranges. For a file of less than 64 KiB, `--at` gives the address of its first byte.
+- Two observations of runs, also of one run: the changed memory items and registers.
+
+`--gap N` joins ranges across N equal bytes. `--out` writes all ranges to a project file.
+
+### Project folder
+
+- Paths are relative to the project folder. The project folder is the nearest folder at or above the working directory that holds `.c64-re-tools/`.
+- If the working directory is not in a project and has projects below it, the script refuses and lists them. Then give `--project <folder>` to each script.
+- Write each file that you make for your work in `.c64-re-tools/local/` of the project. Git ignores that folder. Examples are results, batches, step files, runs, snapshots and memory dumps.
+- Move a file out of `.c64-re-tools/local/` only when it is the evidence for a finding. Move it before you give it to `--evidence` of c64-knowledge. `--evidence` refuses a file in `.c64-re-tools/local/`.
+- Put a run that is evidence in `runs/<name>/`, with its run file, its results and the snapshot files that it uses. Change the paths in the run file to the new paths. Then git keeps them, and another person can do the run again.
+- A shell redirect (`>`) is relative to the working directory, not to the project folder. From the folder above the project, write `<folder>/.c64-re-tools/local/result.json`.
+
 ## Workflow
 
 1. Write the scenario file. Start the steps with a frame count, for example `{ "frames": 150 }`. Each side starts at the reset vector, and the C64 needs these frames to start.
 2. Use symbol names, for example `player_x`, not fixed addresses. Each side finds the name in its own symbols. Use a `$` address only when both programs use the same address.
 3. Make each checkpoint a condition, for example `runUntil` at a routine. Do not wait for a time.
-4. Save the c64-assembler output of the rebuild to the symbol file: `assemble.ts ... > build/game.json`.
+4. Save the c64-assembler output of the rebuild to the symbol file, for example `build/game.json` in the project folder. Give `--all-symbols`, so that the file also has the constants that the source does not use. From the folder above the project, write `assemble.ts --project <folder> ... > <folder>/build/game.json`.
 5. Run the test script.
 6. Read the result:
    - `PASS`: all observations are equal, or the differences are in the allowed tolerance.
    - `FAIL`: `differences` lists each difference with the checkpoint, the item, the original value and the rebuild value.
+   - Each value has one form. The pc and each address are `$xxxx`. Memory is lowercase hex. Other register values and chip values are decimal numbers.
    - `INCONCLUSIVE`: `reason` tells why the script could not compare. This is not a failure of the program.
 7. For a FAIL, examine the first difference with the c64-emulator skill.
 
@@ -89,7 +118,7 @@ PASS, FAIL or INCONCLUSIVE, the checkpoints and the smallest differences that ex
 - `installation-incomplete`, or `machine-unavailable` with a message that the host runtime does not run: stop the task. Give the message to the user and wait for the user. The message gives the remedy. Do not make a replacement for the tool or the host runtime, for example your own disk parser, disassembler or emulator script.
 - A FAIL with only a `screen` difference: add `vicii` or `sprites` to the observation to find which chip state is different.
 - A program that uses random numbers: set the random seed with a `write` step on both sides. If that is not possible, observe only values that do not depend on the random numbers.
-- The two sides start differently, for example the original after a cracked intro. Give the steps that only one side needs a `side`. Then make the memory the same with a `normalize` step from the entry state of the c64-unpacker skill.
+- The two sides start differently, for example the original after a cracked intro. Give the steps that only one side needs a `side`. Then make the memory the same with a `normalize` step. It writes the entry state of the capture in the knowledge.
 - Frame counts drift by one frame between the sides: the sides got to the same address at different raster positions. Do not sync on an IRQ handler. Sync on a value that the IRQ changes, with `runUntil` `memory`, or on an address and a raster line together.
 - A byte that cannot be the same on both sides, for example a read-only collision register: use `exclude` with the reason. Do not use `exclude` to hide a real difference.