@henols/c64-re-tools 1.1.0 → 2.0.0-rc.3

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

@@ -0,0 +1,83 @@
+// The c64-provenance script: compares two or more releases byte by byte at
+// their addresses and reports where they differ and which releases agree.
+
+import { parseArgs } from "node:util";
+
+import { formatC64Address, parseC64Address } from "#src/c64.ts";
+import { readProjectFile } from "#src/host-client/transfer.ts";
+import { runScript, UsageError } from "#src/script.ts";
+import { compareReleases, suggestShift, type Release } from "./compare.ts";
+
+const USAGE = `provenance.ts <release.prg> <release.prg> [<release.prg> ...] [options]
+
+  --shift <n>:<bytes>   move release n (1 = the first) by a number of bytes, for example 2:-256
+  --from <address>      compare from this address
+  --to <address>        compare up to this address
+
+Each release is a PRG file relative to the project directory, placed at its
+load address. The result is one JSON object.`;
+
+function address(text: string, option: string): number {
+  try {
+    return parseC64Address(text);
+  } catch {
+    throw new UsageError(`${option} must be $ followed by four hex digits, not ${text}`);
+  }
+}
+
+const hexBytes = (bytes: number[]) => Buffer.from(bytes).toString("hex").replace(/(..)(?!$)/g, "$1 ");
+
+function run(argv: string[]): unknown {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    strict: true,
+    allowPositionals: true,
+    options: { shift: { type: "string", multiple: true }, from: { type: "string" }, to: { type: "string" }, help: { type: "boolean" } },
+  });
+  if (values.help) throw new UsageError("");
+  if (positionals.length < 2) throw new UsageError("give two or more releases");
+  const shifts = new Map<number, number>();
+  for (const text of values.shift ?? []) {
+    const match = /^(\d+):([+-]?\d+)$/.exec(text);
+    if (match === null || Number(match[1]) < 1 || Number(match[1]) > positionals.length) throw new UsageError(`--shift must be <release number>:<bytes>, not ${text}`);
+    shifts.set(Number(match[1]), Number(match[2]));
+  }
+  const releases: Release[] = positionals.map((path, index) => {
+    const { bytes } = readProjectFile(path);
+    if (bytes.length < 3) throw new UsageError(`${path} is too short for a PRG`);
+    const start = bytes.readUInt16LE(0) + (shifts.get(index + 1) ?? 0);
+    if (start < 0 || start + bytes.length - 3 > 0xffff) throw new UsageError(`the shift moves ${path} outside $0000-$ffff`);
+    return { name: path, start, bytes: bytes.subarray(2) };
+  });
+  const comparison = compareReleases(releases, {
+    ...(values.from === undefined ? {} : { from: address(values.from, "--from") }),
+    ...(values.to === undefined ? {} : { to: address(values.to, "--to") }),
+  });
+  const compared = comparison.identicalBytes + comparison.differingBytes;
+  const identicalShare = compared === 0 ? 0 : comparison.identicalBytes / compared;
+  // A poor match at the load addresses can mean that the releases are placed differently.
+  const suggestions =
+    identicalShare < 0.5
+      ? releases.slice(1).flatMap((release, index) => {
+          const best = suggestShift(releases[0]!, release);
+          return best === undefined || best.shift === 0 ? [] : [{ release: index + 2, shift: best.shift, matchingSequences: best.matches }];
+        })
+      : [];
+  return {
+    releases: releases.map((release) => ({ name: release.name, start: formatC64Address(release.start), end: formatC64Address(release.start + release.bytes.length - 1) })),
+    common: comparison.common === null ? null : { start: formatC64Address(comparison.common.start), end: formatC64Address(comparison.common.end) },
+    identicalBytes: comparison.identicalBytes,
+    differingBytes: comparison.differingBytes,
+    identicalShare: Number(identicalShare.toFixed(3)),
+    differences: comparison.differences.map((difference) => ({
+      start: formatC64Address(difference.start),
+      end: formatC64Address(difference.end),
+      values: Object.fromEntries(Object.entries(difference.values).map(([name, bytes]) => [name, hexBytes(bytes.slice(0, 32)) + (bytes.length > 32 ? " ..." : "")])),
+      groups: difference.groups,
+    })),
+    ...(comparison.moreDifferences ? { moreDifferences: true } : {}),
+    ...(suggestions.length > 0 ? { suggestedShifts: suggestions } : {}),
+  };
+}
+
+await runScript(() => run(process.argv.slice(2)), { usage: USAGE });

package/skills/c64-reverse-engineering/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: c64-reverse-engineering
+description: Use this skill to reverse engineer a C64 program or a part of it. The work goes from an unknown disk or file to documented understanding or a rebuilt program. It decides what to learn next and which specialist skill does that work. Use it for questions such as "what does this game do", "find the main loop", "understand $2100" or "rebuild this program".
+---
+
+# c64-reverse-engineering
+
+## Purpose
+
+Coordinate the reverse engineering of a C64 program. Decide the next unknown to examine and the specialist skill that examines it.
+
+This skill does not do the specialist work itself.
+
+## Inputs
+
+- The subject: a disk image or a program file in the project, or a program that runs in the emulator.
+- The scope: the question or the target. Examples:
+  - identify the main loop
+  - understand the routine at `$2100`
+  - find the IRQ handler
+  - reconstruct the input system
+  - reverse engineer and rebuild the whole program
+- The current project knowledge.
+
+## Tools / execution path
+
+This skill uses the other skills. It does not use the host runtime or the emulator directly.
+
+## Workflow
+
+1. Write down the scope. Stop when the scope is complete.
+2. Read the current knowledge for the subject with the c64-knowledge skill. Do not examine again what the knowledge already explains.
+3. Find the next unknown or blocker, and use the specialist for it:
+
+| Unknown | Skill |
+|---|---|
+| The files on a disk image, or a file to extract | c64-disk |
+| A BASIC program, and where it starts machine code | c64-basic |
+| A program that can be packed or crunched | c64-unpacker |
+| What the program does at run time: values, input, timing, screen | c64-emulator |
+| The routines, code, data and references of the program | c64-static-analysis |
+| The platform meaning of an address or a register | c64-memory-map |
+| Differences between releases of the program | c64-provenance |
+| Source code to build | c64-assembler |
+| Proof that a rebuild behaves as the original | c64-testing |
+
+4. Interpret the result. Keep observed facts apart from your conclusions.
+5. Record each conclusion that the evidence supports with the c64-knowledge skill: names of routines and variables, data classifications, comments.
+6. Go back to step 3 until the scope is complete.
+7. For a rebuild scope: write the source, build it with the c64-assembler skill, and test it against the original with the c64-testing skill.
+
+A typical order for an unknown program:
+
+1. c64-disk: list the disk and extract the start file.
+2. c64-basic: find the SYS address of the BASIC start.
+3. c64-unpacker: find out if a packer compressed the program. Unpack it if necessary.
+4. c64-emulator: run the program and observe it.
+5. c64-static-analysis: find the routines, regions and references.
+6. c64-knowledge and c64-memory-map: name the important routines and variables.
+7. c64-static-analysis again: Ghidra now uses the names.
+8. c64-assembler and c64-testing: rebuild and test when the scope asks for it.
+
+## Knowledge
+
+Read:
+- the knowledge for the addresses, ranges and routines in the scope
+- the history of a conclusion that is surprising or that a person disputes.
+
+Automatic write:
+- none directly.
+
+Record durable conclusions with the c64-knowledge skill. Do not store:
+- the state of the current investigation
+- a name only because a routine needs a temporary name
+- guesses.
+
+## Result
+
+A clear answer for the scope, with the durable conclusions in the project knowledge. For a rebuild scope, also a rebuilt program that passes its tests.
+
+## Failure and conflicts
+
+- If the evidence does not support a conclusion, keep the unknown and get more evidence. Do not make up a meaning.
+- Before you replace current knowledge from the user or the LLM, read its history and the evidence for it.
+- A conflict from the static analysis: find the correct answer at run time with the c64-emulator skill.
+- A test that is INCONCLUSIVE does not show a defect. Find why the test could not compare.
+
+## Handoffs
+
+All specialist skills in the table above.

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

@@ -0,0 +1,96 @@
+---
+name: c64-static-analysis
+description: Use this skill to find the structure of a C64 program without running it. DXA gives a fast first pass of code and data regions and a disassembly listing. Ghidra gives a deeper pass with routines, regions, references and decompiled code. The skill records the structure in the project knowledge and reports conflicts with the current knowledge. Do not use it for runtime questions or to name routines.
+---
+
+# c64-static-analysis
+
+## Purpose
+
+Find the static structure of a C64 program. Record the structure in the project knowledge. Report conflicts with current knowledge.
+
+## Inputs
+
+- The program: a PRG file, relative to the project directory. Or 64 KiB of memory from `$0000`, for example a memory dump.
+- Entry points: addresses where code starts, for example the SYS address from the c64-basic skill. Routine symbols in the knowledge are entry points too. Ghidra needs at least one. DXA finds the SYS of a BASIC start by itself.
+- Optional: routines to decompile (Ghidra), or a file for the listing (DXA).
+
+## Tools / execution path
+
+The script reads the current knowledge and runs DXA or Ghidra on this machine. The host runtime is not necessary. The script records the result in `.c64-re-tools/knowledge.db`.
+
+```
+node <skill>/scripts/analyze.ts extracted/game.prg --analyzer dxa --listing analysis/game.lst
+node <skill>/scripts/analyze.ts extracted/game.prg --entry '$080d' --decompile '$080d'
+```
+
+| Option | Meaning |
+|---|---|
+| `--analyzer dxa` | Use DXA: a fast first pass. Without this option, the script uses Ghidra. |
+| `--entry '$080d'` | An address where code starts. Use it again for more addresses. |
+| `--listing analysis/game.lst` | DXA only: write the disassembly listing to this project file. |
+| `--decompile '$0818'` | Ghidra only: decompile the routine at this address. Use it again for more routines, at most 32. |
+| `--flat64k` | The file is 64 KiB of memory from `$0000`, not a PRG. |
+
+The script prints one JSON object. Addresses are `$` and four hex digits.
+
+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 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.
+
+## Workflow
+
+1. Read the knowledge for the program with the c64-knowledge skill.
+2. Run a first pass with `--analyzer dxa`. For a BASIC loader, DXA finds the SYS address. Read the listing for a quick view of the code.
+3. Find the important routines. Give them names with the c64-knowledge skill.
+4. Run a deeper pass with Ghidra. Give the entry points with `--entry`. Ask for decompiled code of the routines that you must understand.
+5. Read the result:
+   - `changes` counts the symbols, regions and references that the analysis `added`, `changed`, `retired` or kept `unchanged`.
+   - DXA: `regions` lists the code and data regions, and `labels` lists the addresses that DXA named.
+   - Ghidra: `functions` lists the routines that Ghidra found, and `decompilations` gives C-like code for the requested routines.
+   - `conflicts` lists the places where the analyzer and the current knowledge disagree.
+6. Give each important routine a name with the c64-knowledge skill. Then run the analysis again. The analyzers use the new names.
+
+The script records only structure: generated names, code and data regions, and references from Ghidra. The listing and the decompiled code are only for the current task. The script does not record them in the knowledge.
+
+## Knowledge
+
+Automatic write:
+- code and data regions
+- names that DXA generated (labels) and routine entry points with names that Ghidra generated
+- references from Ghidra: call, jump, read and write.
+
+The script never replaces a name or a region from the user or the LLM. A name that an analyzer only shows back stays with its owner. DXA and Ghidra do not replace the facts of each other.
+
+A new analysis replaces the earlier facts of the same analyzer in the analyzed range. The history keeps the earlier facts. DXA labels stay until a person or the LLM removes them, because DXA names only the addresses that it sees used.
+
+Do not store:
+- the listing or decompiled code
+- the function list as comments.
+
+## Result
+
+The changes to the knowledge and the conflicts. For DXA, also the regions, the labels and the path of the listing. For Ghidra, also the routines and the decompiled code.
+
+The exit status is 0 for a result, also with conflicts. The exit status is 1 for an error. The exit status is 2 for a wrong argument.
+
+## Failure and conflicts
+
+- A conflict: the analyzer finds code where the knowledge has data, or data where the knowledge has code. The knowledge stays unchanged. Find the correct answer with the c64-emulator skill, then correct the knowledge with the c64-knowledge skill.
+- A conflict with the problem "another address has this name": the knowledge has the generated name at a different address. The knowledge stays unchanged.
+- `invalid-input` with a message about an entry point: no entry point is inside the program for Ghidra. Give one with `--entry`.
+- `stale-revision`: the knowledge changed during the analysis. The script recorded nothing. Run the analysis again.
+- `operation-failed` with a message about an incomplete result or listing: the analyzer did not give a complete result. The script recorded nothing. Tell the user.
+- `installation-incomplete`: DXA or Ghidra is not installed on this machine. Tell the user the message.
+- `notDecompiled`: Ghidra did not decompile these routines. Each entry has the reason. If the reason says that the decompiler did not start, tell the user the remedy in the reason. On macOS, Ghidra has no native decompiler until the user builds it: `./gradlew buildNatives` in the `support/gradle` directory of Ghidra.
+
+## Handoffs
+
+- Runtime behavior → c64-emulator
+- Names and classifications → c64-knowledge
+- The meaning of a C64 hardware address → c64-memory-map
+- Source code for a rebuild → c64-assembler

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

@@ -0,0 +1,175 @@
+// The c64-static-analysis script: analyzes a project program with DXA (fast
+// first pass) or Ghidra (deeper), which it runs itself, seeded from
+// current knowledge, and imports the structural findings into
+// .c64-re-tools/knowledge.db.
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { parseArgs } from "node:util";
+
+import { formatC64Address, parseC64Address } from "#src/c64.ts";
+import { WireFailure } from "#src/host-client/tools.ts";
+import { readProjectFile } from "#src/host-client/transfer.ts";
+import { analyze as analyzeWithDxa } from "#src/native/dxa.ts";
+import { analyze as analyzeWithGhidra } from "#src/native/ghidra/analyze.ts";
+import { localToolContext } from "#src/native/local.ts";
+import { KnowledgeError, openForRead, withWrite } from "#src/knowledge/database.ts";
+import { importFindings, runProvenance, type Analyzer, type ImportConflict, type ImportContext, type ImportResult, type NormalizedFindings } from "#src/knowledge/import.ts";
+import { currentRevision } from "#src/knowledge/read.ts";
+import { resolveProjectPath } from "#src/project.ts";
+import { runScript, UsageError } from "#src/script.ts";
+import { dxaFindings, ghidraFindings, seedsFromKnowledge } from "./findings.ts";
+
+const USAGE = `analyze.ts <image> [options]
+
+  <image>                 a PRG file, relative to the project directory
+  --analyzer <name>       dxa (fast first pass) or ghidra (deeper, the default)
+  --flat64k               the image is 64 KiB of memory from $0000, not a PRG
+  --entry <address>       an entry point, for example '$080d' (repeatable)
+  --decompile <address>   ghidra: a routine to decompile, at most 32 (repeatable)
+  --listing <file>        dxa: write the disassembly listing to this project file
+
+Routine symbols in knowledge are entry points too. Ghidra needs at least one
+entry point; dxa finds the SYS of a BASIC start by itself. The result is one
+JSON object. Addresses are $ and four hex digits.`;
+
+const MAX_LISTED_FUNCTIONS = 200;
+
+/** A decompiler that did not start gets the remedy: Ghidra ships no native decompiler for macOS. */
+function withRemedy(reason: string): string {
+  return reason.startsWith("the Ghidra decompiler did not start")
+    ? `${reason} On macOS, build the native decompiler once: in <Ghidra>/support/gradle run ./gradlew buildNatives.`
+    : reason;
+}
+
+function addresses(values: string[] | undefined, option: string): number[] {
+  return (values ?? []).map((value) => {
+    try {
+      return parseC64Address(value);
+    } catch {
+      throw new UsageError(`${option} must be $ followed by four hex digits, not ${value}`);
+    }
+  });
+}
+
+/** 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 === "symbol") {
+    return {
+      at: formatC64Address(conflict.address),
+      knowledge: { name: conflict.current.name, kind: conflict.current.kind, origin: conflict.current.origin, at: formatC64Address(conflict.current.address) },
+      [analyzer]: conflict.finding,
+      problem: conflict.reason === "kind" ? "code and data disagree" : "another address has this name",
+    };
+  }
+  return {
+    range: { start: formatC64Address(conflict.start), end: formatC64Address(conflict.end) },
+    knowledge: conflict.current,
+    [analyzer]: conflict.finding,
+    problem: "code and data disagree",
+  };
+}
+
+/**
+ * Imports one analyzer's findings as one revision, refused when knowledge
+ * changed since the seeds were read. A refused import creates no knowledge.db.
+ * The revision records the image hash and the analyzer version.
+ */
+function record(findings: NormalizedFindings, revision: number, description: string, provenance: Pick<ImportContext, "inputHash" | "toolVersion">) {
+  let imported: ImportResult;
+  try {
+    imported = withWrite((db) => importFindings(db, findings, { expectedRevision: revision, description, ...provenance }));
+  } catch (error) {
+    if (error instanceof KnowledgeError && error.code === "stale-revision") {
+      throw new KnowledgeError("stale-revision", "The knowledge changed during the analysis. Nothing was imported. Run the analysis again.");
+    }
+    throw error;
+  }
+  return {
+    revision: imported.revision,
+    changes: { symbols: imported.symbols, regions: imported.regions, references: imported.references },
+    conflicts: imported.conflicts.map((conflict) => showConflict(conflict, findings.analyzer)),
+  };
+}
+
+async function run(argv: string[]): Promise<unknown> {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    strict: true,
+    allowPositionals: true,
+    options: {
+      analyzer: { type: "string" },
+      flat64k: { type: "boolean" },
+      entry: { type: "string", multiple: true },
+      decompile: { type: "string", multiple: true },
+      listing: { type: "string" },
+      help: { type: "boolean" },
+    },
+  });
+  if (values.help) throw new UsageError("");
+  if (positionals.length !== 1) throw new UsageError("give one image");
+  const image = positionals[0]!;
+  const entries = addresses(values.entry, "--entry");
+  const decompile = addresses(values.decompile, "--decompile");
+  if (decompile.length > 32) throw new UsageError("--decompile takes at most 32 routines");
+  const analyzer = values.analyzer ?? "ghidra";
+  if (analyzer !== "dxa" && analyzer !== "ghidra") throw new UsageError(`--analyzer must be dxa or ghidra, not ${analyzer}`);
+  if (analyzer === "dxa" && decompile.length > 0) throw new UsageError("--decompile works only with --analyzer ghidra");
+  if (analyzer === "ghidra" && values.listing !== undefined) throw new UsageError("--listing works only with --analyzer dxa");
+  let listingPath: string | undefined;
+  if (values.listing !== undefined) {
+    try {
+      listingPath = resolveProjectPath(values.listing);
+    } catch {
+      throw new UsageError(`--listing must be a path relative to the project directory that stays inside it, not ${values.listing}`);
+    }
+  }
+
+  const reader = openForRead();
+  const revision = currentRevision(reader);
+  const seeds = seedsFromKnowledge(reader, entries);
+  reader?.close();
+
+  const imageKind = values.flat64k ? "flat64k" : "prg";
+  const bytes = readProjectFile(image).bytes;
+  if (analyzer === "dxa") {
+    const { result, attachments } = await analyzeWithDxa({ imageKind, ...seeds }, bytes, localToolContext());
+    const listing = attachments[0]!.toString("utf8");
+    // The listing is written only after the import: a refused import leaves no new file.
+    const imported = record(dxaFindings(result), revision, `DXA analysis of ${image}`, runProvenance(bytes, result.toolVersion));
+    if (listingPath !== undefined) {
+      try {
+        mkdirSync(dirname(listingPath), { recursive: true });
+        writeFileSync(listingPath, 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 ${values.listing}: ${(error as Error).message}. ${recorded}`);
+      }
+    }
+    return {
+      analyzer: "dxa",
+      coverage: result.coverage.map((range) => ({ start: formatC64Address(range.start), end: formatC64Address(range.end) })),
+      ...imported,
+      regions: result.regions.map((region) => ({ start: formatC64Address(region.start), end: formatC64Address(region.end), classification: region.classification })),
+      labels: result.labels.slice(0, MAX_LISTED_FUNCTIONS).map((label) => ({ address: formatC64Address(label.address), name: label.name })),
+      ...(result.labels.length > MAX_LISTED_FUNCTIONS ? { moreLabels: result.labels.length - MAX_LISTED_FUNCTIONS } : {}),
+      ...(listingPath === undefined ? {} : { listing: values.listing }),
+    };
+  }
+
+  const { result } = await analyzeWithGhidra({ imageKind, ...seeds, decompile }, bytes, localToolContext());
+  const imported = record(ghidraFindings(result), revision, `Ghidra analysis of ${image}`, runProvenance(bytes, result.toolVersion));
+  return {
+    analyzer: "ghidra",
+    coverage: result.coverage.map((range) => ({ start: formatC64Address(range.start), end: formatC64Address(range.end) })),
+    ...imported,
+    functions: result.functions.slice(0, MAX_LISTED_FUNCTIONS).map((fn) => ({ entry: formatC64Address(fn.entry), name: fn.name })),
+    ...(result.functions.length > MAX_LISTED_FUNCTIONS ? { moreFunctions: result.functions.length - MAX_LISTED_FUNCTIONS } : {}),
+    decompilations: result.decompilations.map((item) => ({ entry: formatC64Address(item.entry), text: item.text, ...(item.truncated ? { truncated: true } : {}) })),
+    ...((result.notDecompiled ?? []).length === 0
+      ? {}
+      : { notDecompiled: result.notDecompiled!.map((item) => ({ entry: formatC64Address(item.entry), reason: withRemedy(item.reason) })) }),
+  };
+}
+
+await runScript(() => run(process.argv.slice(2)), { usage: USAGE, refusals: [KnowledgeError] });

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

@@ -0,0 +1,73 @@
+// Knowledge seeds for an analyzer, and the mapping of a Ghidra result to the
+// common normalized findings.
+
+import type { DatabaseSync } from "node:sqlite";
+
+import type { NormalizedFindings } from "#src/knowledge/import.ts";
+import { listRegions, listSymbols } from "#src/knowledge/read.ts";
+import type { DxaResult, GhidraParams, GhidraResult } from "#src/native/types.ts";
+
+export type Seeds = Pick<GhidraParams, "entryPoints" | "dataRanges" | "labels">;
+
+const semantic = (row: { origin: string }) => row.origin === "user" || row.origin === "llm";
+
+/**
+ * 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.
+ */
+export function seedsFromKnowledge(db: DatabaseSync | undefined, extraEntryPoints: number[] = []): Seeds {
+  const symbols = listSymbols(db).filter(semantic);
+  const entryPoints = [...new Set([...extraEntryPoints, ...symbols.filter((symbol) => symbol.kind === "routine").map((symbol) => symbol.address)])].sort((a, b) => a - b);
+  return {
+    entryPoints,
+    dataRanges: listRegions(db)
+      .filter((region) => semantic(region) && region.type !== "code")
+      .map((region) => ({ start: region.start, end: region.end })),
+    labels: symbols.map((symbol) => ({ address: symbol.address, name: symbol.name })),
+  };
+}
+
+/**
+ * Ghidra's result as normalized findings. A function named by an echoed seed
+ * stays in the snapshot: its address holds the seed's semantic symbol, which
+ * the importer never replaces, so the name keeps its owner,
+ * and a code/data disagreement with that symbol is still reported.
+ */
+export function ghidraFindings(result: GhidraResult): NormalizedFindings {
+  // Ghidra can give one generated name to two functions, for example
+  // thunk_FUN_e434 to two thunks of one routine. A name
+  // must have one address, so a repeated name that is not a seed gets its address.
+  const uses = new Map<string, number>();
+  for (const fn of result.functions) uses.set(fn.name, (uses.get(fn.name) ?? 0) + 1);
+  const nameOf = (fn: GhidraResult["functions"][number]) =>
+    fn.nameSource !== "seed" && uses.get(fn.name)! > 1 ? `${fn.name}_${fn.entry.toString(16).padStart(4, "0")}` : fn.name;
+  return {
+    analyzer: "ghidra",
+    coverage: result.coverage,
+    authoritative: { symbols: result.completeness.functions, regions: result.completeness.regions, references: result.completeness.references },
+    symbols: result.functions.map((fn) => ({ address: fn.entry, name: nameOf(fn), kind: "routine" as const })),
+    regions: result.regions.map((region) => ({ start: region.start, end: region.end, type: region.classification === "code" ? ("code" as const) : ("bytes" as const) })),
+    references: result.references.map((reference) => ({ from: reference.from, to: reference.to, kind: reference.type })),
+  };
+}
+
+/**
+ * DXA's result as normalized findings. A label in one of DXA's data
+ * regions becomes a symbol of kind data, any other label one of kind label.
+ * DXA names only referenced addresses, so labels are not authoritative, while
+ * its regions cover every byte and are.
+ */
+export function dxaFindings(result: DxaResult): NormalizedFindings {
+  const inData = (address: number) => result.regions.some((region) => region.classification === "data" && region.start <= address && address <= region.end);
+  return {
+    analyzer: "dxa",
+    coverage: result.coverage,
+    authoritative: { symbols: result.completeness.labels, regions: result.completeness.regions, references: false },
+    symbols: result.labels.map((label) => ({ address: label.address, name: label.name, kind: inData(label.address) ? ("data" as const) : ("label" as const) })),
+    regions: result.regions.map((region) => ({ start: region.start, end: region.end, type: region.classification === "code" ? ("code" as const) : ("bytes" as const) })),
+    references: [],
+  };
+}

package/skills/c64-testing/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: c64-testing
+description: Use this skill to test if a rebuilt or changed C64 program behaves as the original. It runs one scenario on the original and then on the rebuild in an emulator. It compares memory, registers, chip state and the screen with explicit rules, and gives PASS, FAIL or INCONCLUSIVE. It also makes a checklist for a human playtest. Do not use it to find the cause of a difference.
+---
+
+# c64-testing
+
+## Purpose
+
+Test if a rebuild or a changed program behaves as the original in a scenario. Give one result: PASS, FAIL or INCONCLUSIVE.
+
+A PASS proves only the behavior that the scenario does and observes. It does not prove that the two programs are equal in all behavior.
+
+## Inputs
+
+- The original program and the rebuild: PRG files in the project.
+- The symbols of each side. For the original, the project knowledge. For the rebuild, the JSON output of the c64-assembler skill in a file.
+- A scenario file: the steps, the checkpoints and the observations. See [references/scenario-format.md](references/scenario-format.md).
+
+## Tools / execution path
+
+The script starts one emulator through the host runtime. It runs the scenario on the original and then on the rebuild. Before each side, it does a hard reset of the emulator. The CPU then stops at the reset vector.
+
+```
+node <skill>/scripts/test.ts tests/moves-left.json
+node <skill>/scripts/checklist.ts tests/moves-left.json --item 'FIRE starts the game.'
+```
+
+The test script prints one JSON object. The exit status is 0 for PASS, 1 for FAIL, 3 for INCONCLUSIVE and 2 for a bad call.
+
+The checklist script prints a Markdown checklist for a human tester.
+
+## 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`.
+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.
+   - `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.
+
+## Knowledge
+
+Read:
+- the symbols of the original from the project knowledge.
+
+Automatic write:
+- none.
+
+Do not store:
+- test results
+- screenshots
+- playtest results.
+
+## Result
+
+PASS, FAIL or INCONCLUSIVE, the checkpoints and the smallest differences that explain a FAIL.
+
+## 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, "did not reach the checkpoint": one side did not reach the checkpoint in the frame limit. Find the reason with the c64-emulator skill. Do not report a FAIL.
+- INCONCLUSIVE, "has no symbol": one side has no symbol with that name. Add the name to the knowledge or to the rebuild source.
+- INCONCLUSIVE, "no emulator" or "could not run": the host runtime or the emulator failed. Tell the user the message.
+- 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.
+
+Do not add a mask or a tolerance only to make a test pass. A tolerance must have a reason in the behavior of the program.
+
+## Handoffs
+
+- Find the cause of a difference → c64-emulator
+- Find the code that causes it → c64-static-analysis
+- Rebuild after a correction → c64-assembler
+- Record a confirmed conclusion → c64-knowledge