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

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

@@ -0,0 +1,120 @@
+---
+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. |
+| `--max-listed 20` | List at most this number of labels, functions or candidates. The default is 50. Use 0 to list none. |
+| `--instructions analysis/instructions.json` | Ghidra only: write every instruction to this project file as JSON. Each has `address`, `bytes`, `mnemonic`, `mode` and `operand` in 6502 syntax. A branch, jump or call also has its `target`. With `--coverage`, `executed` tells if it ran. |
+| `--space drive8` | The knowledge space of the image: `drive8` for code from the 1541 drive, or `bank0` to `bank255` for a cartridge bank. The default is `c64`. The seeds come from that space, and the findings go into it. |
+| `--coverage coverage/attract.bin` | A coverage file of 64 KiB from `c64_memmap` (action `read` with `out`). Use it again for more runs. The executed code becomes entry points. |
+
+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.
+
+More seeds come from evidence:
+
+- The start of each `code` region and each entry of a `jumps` table from the user or the LLM is an entry point.
+- With `--coverage`, each executed instruction that starts a flow is an entry point. A flow starts after a gap, or after RTS, RTI, JMP or BRK. Then the analyzers find code that only a vector, an RTS table or an interrupt reaches.
+
+The analyzers take at most 1024 entry points. Knowledge routines and `--entry` come first, then code regions and tables, then coverage. `coverageSeeds` gives how many entry points the coverage gave and how many the analysis used.
+
+## 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`. `suppressed` counts the findings that the analysis did not write, because a removal blocks that place.
+   - DXA: `regions` lists the code and data regions. `labels` gives the number of names that DXA found (`count`) and lists the first names (`listed`).
+   - 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.
+   - `idioms` tells what the script found by pattern: RTS dispatch tables (`rtsTables`), JMP tables (`jumpTables`) and BIT skips (`bitSkips`). 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. 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 image 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.
+   - With `--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.
+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, with one exception. With `--coverage`, a code finding replaces a DXA or Ghidra data region or data name where a run executed an instruction start. The revision keeps the coverage files as evidence. Thus run DXA first, then Ghidra with all coverage files.
+
+A `heuristic` region replaces the part of a DXA or Ghidra region where it lies, because an idiom is specific evidence about those bytes. DXA and Ghidra never replace a `heuristic` region. If they find code there, the result shows a conflict. A heuristic table can be too long or too short, because the script cannot know its length. Correct it with the c64-knowledge skill. Your region replaces it, and a removal holds.
+
+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.
+
+A fact that the user or the LLM removes does not come back. The next analysis does not write a fact at that place, and counts it as `suppressed`. To remove a wrong fact, use the c64-knowledge skill.
+
+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.
+- A false reference through a vector: the code jumps through a vector, for example `JMP ($0408)`, and the program writes the vector at run time. The analyzer follows the bytes that the image has there. Do these steps:
+  1. Find the real targets with the c64-emulator skill, or in a coverage file.
+  2. If the vector bytes are also code at another time, classify them as `dual-use`.
+  3. Remove the false reference with `unreference`. It does not come back.
+  4. Add a `jump` reference from the JMP to each real target, and name each target as a routine.
+- `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`, 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.
+- `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,293 @@
+// 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 { createHash } from "node:crypto";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { parseArgs } from "node:util";
+
+import { COVERAGE, formatC64Address, parseC64Address, prgRange } from "#src/c64.ts";
+import { joinCoverage } from "#src/host-client/coverage.ts";
+import { WireFailure } from "#src/host-client/tools.ts";
+import { readProjectFile, writeProjectFile } 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 { GHIDRA_LIMITS } from "#src/native/types.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, listRegions } from "#src/knowledge/read.ts";
+import { DEFAULT_SPACE, SPACE } from "#src/knowledge/schema.ts";
+import { platformNames } from "#src/platform.ts";
+import { resolveProjectPath } from "#src/project.ts";
+import { runScript, UsageError } from "#src/script.ts";
+import { codeEntries, coverageConflicts, coverageEntries, imageReader, readCoverageMaps } from "./coverage.ts";
+import { dxaFindings, ghidraFindings, seedsFromKnowledge } from "./findings.ts";
+import { findIdioms } from "./idioms.ts";
+import { instructionList } from "./instructions.ts";
+import { findPointers, type PointerCandidate } from "./pointers.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
+  --instructions <file>   ghidra: write every instruction (address, bytes, mnemonic,
+                          mode, operand, target, executed) to this project file as JSON
+  --coverage <file>       a coverage map of 64 KiB from c64_memmap (repeatable): its
+                          executed code is seeded, and analyzer data over it is reported
+  --max-listed <n>        list at most n labels, functions or candidates (default 50,
+                          0 for none); the counts are always given, and knowledge has
+                          all labels and functions
+  --space <space>         the knowledge space of the image: c64 (the default), drive8
+                          for 1541 drive code, or bank0 to bank255 for a cartridge bank
+
+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 DEFAULT_MAX_LISTED = 50;
+
+/** The first `max` items, the count, and where to read the rest when the list is cut. */
+function listed<T, U>(items: T[], max: number, show: (item: T) => U, all: string) {
+  return { count: items.length, listed: items.slice(0, max).map(show), ...(items.length > max ? { rest: all } : {}) };
+}
+
+/** A pointer candidate with $ addresses, and the operand writes that would name it (D65). */
+function showPointer(candidate: PointerCandidate) {
+  const hex = formatC64Address;
+  if (candidate.kind === "sprite pointer") {
+    return { kind: candidate.kind, at: hex(candidate.at), to: hex(candidate.to), value: `$${candidate.value.toString(16).padStart(2, "0")}`, target: hex(candidate.target), assumes: "VIC bank 0 and the screen at $0400" };
+  }
+  return { kind: candidate.kind, to: hex(candidate.to), target: hex(candidate.target), low: hex(candidate.low), high: hex(candidate.high) };
+}
+
+/** 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" | "evidence">) {
+  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" },
+      "max-listed": { type: "string" },
+      coverage: { type: "string", multiple: true },
+      instructions: { type: "string" },
+      space: { 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 maxListed = values["max-listed"] ?? String(DEFAULT_MAX_LISTED);
+  if (!/^\d{1,5}$/.test(maxListed)) throw new UsageError(`--max-listed must be a whole number, not ${maxListed}`);
+  const max = Number(maxListed);
+  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");
+  if (analyzer === "dxa" && values.instructions !== undefined) throw new UsageError("--instructions works only with --analyzer ghidra");
+  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 space = values.space ?? DEFAULT_SPACE;
+  if (!SPACE.test(space)) throw new UsageError("--space must be c64, drive8, or bank0 to bank255");
+  // A coverage map is of the C64 CPU: VICE keeps none for the drive (D53).
+  if (space !== DEFAULT_SPACE && values.coverage !== undefined) throw new UsageError("--coverage works only in space c64");
+  const imageKind = values.flat64k ? "flat64k" : "prg";
+  const bytes = readProjectFile(image).bytes;
+  const runs = readCoverageMaps(values.coverage ?? []);
+  const coverage = runs.length === 0 ? undefined : joinCoverage(runs);
+  const byteAt = imageReader(bytes, imageKind);
+  // With coverage, a code finding over an executed instruction start replaces the data of the other analyzer (D58), and the files are the evidence.
+  const executed = coverage === undefined ? {} : { executed: (address: number) => (coverage[address]! & COVERAGE.ramExecute) !== 0 };
+  const coverageEvidence = coverage === undefined ? {} : { evidence: (values.coverage ?? []).map((path) => ({ kind: "coverage" as const, ref: path, sha256: createHash("sha256").update(readProjectFile(path).bytes).digest("hex") })) };
+
+  let loaded: { start: number; end: number };
+  try {
+    loaded = imageKind === "flat64k" ? { start: 0x0000, end: bytes.length - 1 } : prgRange(bytes);
+  } catch (error) {
+    throw new UsageError(`${image}: ${(error as Error).message}`);
+  }
+  const idioms = findIdioms(byteAt, { start: loaded.start, end: loaded.end }, runs);
+
+  const reader = openForRead();
+  const revision = currentRevision(reader);
+  const seeds = seedsFromKnowledge(reader, entries, space);
+  // Knowledge routines and --entry first, then code regions and JMP tables, then idioms, then coverage, up to the seed bound (D44).
+  const fromCoverage = coverage === undefined ? [] : coverageEntries(coverage, byteAt);
+  const ordered = [...new Set([...seeds.entryPoints, ...codeEntries(reader, byteAt, space), ...idioms.entryPoints, ...fromCoverage])];
+  seeds.entryPoints = ordered.slice(0, GHIDRA_LIMITS.entryPoints).sort((a, b) => a - b);
+  // Idiom tables are data for this run too; semantic data ranges come first.
+  seeds.dataRanges = [...seeds.dataRanges, ...idioms.dataRanges.filter((range) => !seeds.dataRanges.some((seed) => range.start <= seed.end && range.end >= seed.start))].slice(0, GHIDRA_LIMITS.dataRanges);
+  const coverageUsed = fromCoverage.filter((entry) => seeds.entryPoints.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 ${image}` }));
+    return {
+      idioms: {
+        ...idioms.counts,
+        revision: imported.revision,
+        changes: { regions: imported.regions, references: imported.references },
+        conflicts: imported.conflicts.map((conflict) => showConflict(conflict, "heuristic")),
+        // Candidates are not knowledge: a larger --max-listed gives more of them.
+        candidates: {
+          dop: listed(idioms.candidates.dop, max, formatC64Address, "a larger --max-listed"),
+          selfModified: listed(idioms.candidates.selfModified, max, formatC64Address, "a larger --max-listed"),
+          pointers: listed(pointers, max, showPointer, "a larger --max-listed"),
+        },
+      },
+    };
+  };
+  /** The coverage part of a result: its seeds, and the analyzer data that it shows to be code. */
+  const coverageResult = () => {
+    if (coverage === undefined) return {};
+    const db = openForRead();
+    const conflicts = coverageConflicts(db, coverage);
+    db?.close();
+    return {
+      coverageSeeds: { entryPoints: fromCoverage.length, used: coverageUsed },
+      coverageConflicts: conflicts.map(({ region, executed }) => ({
+        range: { start: formatC64Address(region.start), end: formatC64Address(region.end) },
+        knowledge: { type: region.type, origin: region.origin },
+        executed,
+        problem: "coverage shows code",
+      })),
+    };
+  };
+  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), space, ...executed }, revision, `DXA analysis of ${image}`, { ...runProvenance(bytes, result.toolVersion), ...coverageEvidence });
+    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}`);
+      }
+    }
+    const found = idiomsResult();
+    return {
+      analyzer: "dxa",
+      ...(space === DEFAULT_SPACE ? {} : { space }),
+      ...found,
+      ...coverageResult(),
+      coverage: result.coverage.map((range) => ({ start: formatC64Address(range.start), end: formatC64Address(range.end) })),
+      ...imported,
+      regions: result.regions.map((region) => ({ start: formatC64Address(region.start), end: formatC64Address(region.end), classification: region.classification })),
+      labels: listed(result.labels, max, (label) => ({ address: formatC64Address(label.address), name: label.name }), "c64-knowledge: knowledge.ts symbols"),
+      ...(listingPath === undefined ? {} : { listing: values.listing }),
+    };
+  }
+
+  const { result } = await analyzeWithGhidra({ imageKind, ...seeds, decompile }, bytes, localToolContext());
+  const imported = record({ ...ghidraFindings(result), space, ...executed }, revision, `Ghidra analysis of ${image}`, { ...runProvenance(bytes, result.toolVersion), ...coverageEvidence });
+  const found = idiomsResult();
+  let instructions: { out: string; count: number } | undefined;
+  if (values.instructions !== undefined) {
+    const list = instructionList(result.instructions, coverage);
+    writeProjectFile(values.instructions, Buffer.from(`${JSON.stringify(list, null, 1)}\n`), { what: "--instructions" });
+    instructions = { out: values.instructions, count: list.length };
+  }
+  return {
+    analyzer: "ghidra",
+    ...(space === DEFAULT_SPACE ? {} : { space }),
+    ...(instructions === undefined ? {} : { instructions }),
+    ...found,
+    ...coverageResult(),
+    coverage: result.coverage.map((range) => ({ start: formatC64Address(range.start), end: formatC64Address(range.end) })),
+    ...imported,
+    functions: listed(result.functions, max, (fn) => ({ entry: formatC64Address(fn.entry), name: fn.name }), "c64-knowledge: knowledge.ts symbols --kind routine"),
+    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/coverage.ts

@@ -0,0 +1,78 @@
+// Runtime evidence for static analysis (D44): coverage files as entry points,
+// user/LLM code regions and JMP tables as entry points, and the check that
+// shows analyzer data over executed code.
+
+import type { DatabaseSync } from "node:sqlite";
+
+import { COVERAGE, instructionLength } from "#src/c64.ts";
+import { FULL_COVERAGE, readCoverageMaps as readMaps } from "#src/host-client/coverage.ts";
+import { listRegions, type RegionRow } from "#src/knowledge/read.ts";
+import { CODE_REGION_TYPES, DEFAULT_SPACE, type Space } from "#src/knowledge/schema.ts";
+import { UsageError } from "#src/script.ts";
+
+const FULL_MAP = FULL_COVERAGE;
+/** Instructions after which the next instruction is not reached by falling through. */
+const FLOW_ENDS = new Set([0x00, 0x40, 0x4c, 0x60, 0x6c]);
+const ANALYZER_ORIGINS = new Set(["dxa", "ghidra", "heuristic"]);
+
+/** Reads coverage files, one map per file (a run). */
+export function readCoverageMaps(paths: string[]): Uint8Array[] {
+  return readMaps(paths, (message) => {
+    throw new UsageError(message);
+  });
+}
+
+/** The byte at an address of the analyzed image, or undefined outside it. */
+export type ImageByte = (address: number) => number | undefined;
+
+export function imageReader(bytes: Uint8Array, kind: "prg" | "flat64k"): ImageByte {
+  if (kind === "flat64k") return (address) => bytes[address];
+  const load = bytes[0]! | (bytes[1]! << 8);
+  return (address) => (address >= load && address - load + 2 < bytes.length ? bytes[address - load + 2] : undefined);
+}
+
+/**
+ * The executed instruction starts in RAM that begin a flow: the first after
+ * a gap, or the first after an instruction that does not fall through. The
+ * analyzers follow the rest of a flow themselves.
+ */
+export function coverageEntries(map: Uint8Array, image: ImageByte): number[] {
+  const entries: number[] = [];
+  let falls: number | undefined;
+  for (let address = 0; address < FULL_MAP; address++) {
+    if ((map[address]! & COVERAGE.ramExecute) === 0) continue;
+    const opcode = image(address);
+    if (opcode === undefined) continue;
+    if (falls !== address) entries.push(address);
+    falls = FLOW_ENDS.has(opcode) ? undefined : address + instructionLength(opcode);
+  }
+  return entries;
+}
+
+/** Entry points from semantic knowledge beyond routines: the start of each code region, and each entry of a JMP table with its target. */
+export function codeEntries(db: DatabaseSync | undefined, image: ImageByte, space: Space = DEFAULT_SPACE): number[] {
+  const entries: number[] = [];
+  for (const region of listRegions(db, undefined, undefined, undefined, space).filter((row) => row.origin === "user" || row.origin === "llm")) {
+    if (region.type === "code") entries.push(region.start);
+    if (region.type !== "jumps") continue;
+    for (let at = region.start; at + 2 <= region.end; at += 3) {
+      entries.push(at);
+      const low = image(at + 1);
+      const high = image(at + 2);
+      if (image(at) === 0x4c && low !== undefined && high !== undefined) entries.push(low | (high << 8));
+    }
+  }
+  return entries;
+}
+
+/** Analyzer data regions that hold executed instruction starts: the coverage shows code there. */
+export function coverageConflicts(db: DatabaseSync | undefined, map: Uint8Array): Array<{ region: RegionRow; executed: number }> {
+  const conflicts: Array<{ region: RegionRow; executed: number }> = [];
+  for (const region of listRegions(db)) {
+    if (!ANALYZER_ORIGINS.has(region.origin) || CODE_REGION_TYPES.includes(region.type) || region.type === "dual-use") continue;
+    let executed = 0;
+    for (let address = region.start; address <= region.end; address++) if ((map[address]! & COVERAGE.ramExecute) !== 0) executed++;
+    if (executed > 0) conflicts.push({ region, executed });
+  }
+  return conflicts;
+}

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

@@ -0,0 +1,75 @@
+// 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 { CODE_REGION_TYPES, DEFAULT_SPACE, type Space } from "#src/knowledge/schema.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[] = [], space: Space = DEFAULT_SPACE): 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);
+  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 (D42).
+      .filter((region) => semantic(region) && !CODE_REGION_TYPES.includes(region.type) && region.type !== "dual-use")
+      .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: [],
+  };
+}