@henols/c64-re-tools 2.0.0-rc.4 → 2.0.0-rc.5

package/README.md

@@ -19,7 +19,7 @@ The design is in [`docs/redesign/`](docs/redesign/README.md), and
 
 ## Install
 
-You need Node.js 24 or newer, and VICE 3.9 or later (`x64sc`, `c1541`, `petcat`) with its ROM files. ACME, DXA and Ghidra are needed only for the skills that use them: [docs/install-tools.md](docs/install-tools.md) has the steps for each system.
+You need Node.js 24 or newer, and VICE 3.9 or later (`x64sc`, `c1541`, `petcat`) with its ROM files; use the latest VICE release. `status` and the host name the known flaws of an older VICE. ACME, DXA and Ghidra are needed only for the skills that use them: [docs/install-tools.md](docs/install-tools.md) has the steps for each system.
 
 Start the Host Runtime and leave it running:
 
@@ -50,6 +50,8 @@ The agent runs in the container, VICE and the Host Runtime on the host. In `.dev
 "runArgs": ["--add-host=host.docker.internal:host-gateway"]
 ```
 
+Until 2.0.0 is released, the `latest` URL has no Feature. Use the prerelease: `https://github.com/henols/c64-re-tools/releases/download/v2.0.0-rc.4/devcontainer-feature-c64-re-tools.tgz` with `{ "target": "claude", "channel": "next" }`.
+
 The Feature installs ACME, dxa, Java 21 and Ghidra, puts the toolkit into the project when the container is created, and updates it at each start. `target` is a harness or a comma list. `channel` is `latest` (default) or `next`. Debian and Ubuntu images only. `runArgs` is for Docker on Linux. Start the Host Runtime on the host as above.
 
 ### Settings

package/distribution/package.ts

@@ -2,22 +2,7 @@
 // only reads package.json, so a caller that needs the declaration does not
 // build the plugin.
 
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
-
-/**
- * The npm dist-tag that a version is published under: a prerelease
- * (2.0.0-rc.1) goes to "next", a release to "latest".
- */
-export function channelOf(version: string): "latest" | "next" {
-  return version.includes("-") ? "next" : "latest";
-}
-
-/** The name, version and dist-tag of this npm package, from its package.json. */
-export const PACKAGE = (() => {
-  const metadata = JSON.parse(readFileSync(join(import.meta.dirname, "..", "package.json"), "utf8")) as { name: string; version: string };
-  return { name: metadata.name, version: metadata.version, tag: channelOf(metadata.version) };
-})();
+import { PACKAGE } from "../src/package.ts";
 
 /**
  * The agent starts the MCP server through npx with the newest version of the

package/distribution/plugin.ts

@@ -13,7 +13,8 @@ import { dirname, join, relative, resolve, sep } from "node:path";
 
 import { definePlugin, defineSkill, type Skill } from "@jalco/ap-sdk";
 
-import { MCP_SERVER, PACKAGE } from "./package.ts";
+import { PACKAGE } from "../src/package.ts";
+import { MCP_SERVER } from "./package.ts";
 
 const root = resolve(import.meta.dirname, "..");
 const SOURCE = join(root, "src");
@@ -27,9 +28,10 @@ const SPECIFIER = /(?:\bfrom\s*|\bimport\s*\(?\s*|\bnew URL\(\s*)(["'])((?:\.\.?
 
 /**
  * The package.json of an installed skill: ES modules, #src/* resolved inside
- * the skill, and the version of c64-re-tools that the copy comes from.
+ * the skill, and the name and version of c64-re-tools that the copy comes
+ * from, which src/package.ts reads.
  */
-export const SKILL_PACKAGE = `${JSON.stringify({ type: "module", version: PACKAGE.version, imports: { "#src/*": "./src/*" } }, null, 2)}\n`;
+export const SKILL_PACKAGE = `${JSON.stringify({ name: PACKAGE.name, type: "module", version: PACKAGE.version, imports: { "#src/*": "./src/*" } }, null, 2)}\n`;
 
 /** The scripts that a SKILL.md runs, by file name. */
 export function scriptsOf(skillMarkdown: string): string[] {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henols/c64-re-tools",
-  "version": "2.0.0-rc.4",
+  "version": "2.0.0-rc.5",
   "description": "Agent-friendly Commodore 64 engineering toolkit for reverse engineering, debugging, development and testing.",
   "license": "MIT",
   "author": "Henrik Olsson",

package/skills/c64-basic/SKILL.md

@@ -30,9 +30,9 @@ The script prints one JSON object. Addresses are `$` and four hex digits.
 1. Run the script on the program.
 2. Read `listing`. Each line starts with its BASIC line number. Keywords show in lower case. Control characters in strings show in braces, for example `{clr}`.
 3. Read `handoffs`. Each handoff has a `kind` (`sys` or `usr`) and the BASIC `line`.
-   - A `sys` handoff with an `address`: BASIC calls the machine code at that address.
-   - A handoff with `computed: true`: the address comes from a calculation at run time. Use the c64-emulator skill to find the address.
-4. Compare the address with `loadRange` and `basicEnd`. From `basicEnd` to the end of `loadRange`, the file holds bytes that are not BASIC. Usually this is the machine code that the handoff calls.
+   - A `sys` handoff with an `address`: BASIC calls the machine code at that address. The script calculates a SYS argument with numbers, π, `+`, `-`, `*`, `/` and brackets. For example, `SYS π*656` calls `$080c`.
+   - A handoff with `computed: true`: the address comes from a calculation at run time, for example with `PEEK`. A `sys` handoff gives its argument in `expression`. Use the c64-emulator skill to find the address.
+4. Compare the address with `loadRange` and `basicEnd`. From `basicEnd` to the end of `loadRange`, the file holds bytes that are not BASIC. Usually this is the machine code that the handoff calls. Some programs have no end marker (two zero bytes) after the last line. The machine code starts directly after the last line. Then `basicEnd` is the first byte of that machine code.
 
 The address ranges are for a load to the load address of the file. A load without `,1` puts a BASIC program at `$0801`. Most loaders have `$0801` as their load address.
 

package/skills/c64-emulator/SKILL.md

@@ -70,7 +70,7 @@ Step, next and until-return work only in space `c64`. The emulator cannot stop t
 
 `c64_keyboard` puts keys in the keyboard queue of the KERNAL. A program that reads the keyboard hardware directly does not see them. Many games do this. The emulator has no command that presses one key of the keyboard matrix. For such a program:
 
-- A wait for any key that reads all keyboard columns at one time can end without a key. Joystick port 1 uses the same lines as the keyboard.
+- VICE 3.10 and older have a known flaw: bits 5-7 of `$DC00` and `$DC01` are always 0. Then `emulatorFlaw` in the result of `c64_keyboard` and `c64_joystick` gives the flaw. With this flaw, a wait for any key that reads all keyboard columns at one time ends without a key. A wait for one specific key, or a compare of the full byte of a joystick port, never ends. Tell the user about the flaw. The next VICE release and the VICE nightly builds do not have it. Joystick port 1 uses the same lines as the keyboard.
 - For one specific key, for example F1 or RUN/STOP, open the window and ask the user to press the key.
 - Do not change the program to make it accept a key.
 
@@ -114,7 +114,7 @@ If you cannot get the machine into the necessary state, say which state you coul
 
 - `machine-state-lost` and the message says that the VICE window closed: the window closed before `c64_window` action `close`. The emulator has no window again. The machine state is the same as at the time when the window opened. The breakpoints and the watchpoints stay. Do not use results from the window time. Read the machine state again, then continue.
 - `machine-unavailable` and the message says that the VICE window closed: the session starts the emulator again. Wait a few seconds. Then do the operation again.
-- `machine-state-lost` with a different message: the emulator stopped and its state is gone. Do not continue with results from before. Tell the user to restart the MCP server.
+- `machine-state-lost` with a different message: the connection to the host runtime was lost, and the machine state is gone. Do not continue with results from before. The next call starts a new machine when the host runtime runs. Load the program again, and set the breakpoints and the watchpoints again. If the next call gives `machine-unavailable` with a message that the host runtime does not run, obey the rule for that message.
 - `machine-unavailable` and the message names a pause or a dialog in the emulator window: this occurs only while the window is open. Do not send more operations. Tell the user to resume the emulator (Pause, Alt+P) or to close the dialog in the VICE window. Then do the operation again. The machine state does not change.
 - `machine-running`: stop the CPU first, then try again.
 - `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. Do not try to repair the installation.

package/skills/c64-knowledge/SKILL.md

@@ -76,7 +76,7 @@ Region types:
 Read:
 
 1. Use `at` for the addresses in the question before other work.
-2. Use `history` when the current knowledge is surprising or disputed.
+2. Use `history` when the current knowledge is surprising or disputed. Each row gives the `reason` and the `evidence` of the revision that wrote it.
 
 Write:
 
@@ -97,11 +97,25 @@ For more than a few writes, put them in one JSON file and use `apply`. The file
 ]
 ```
 
-The ops are `rename`, `remove-symbol`, `classify`, `unclassify`, `comment`, `uncomment`, `reference`, `unreference`, `module` and `unmodule`. All writes become one revision. If the knowledge refuses one write, the script writes nothing, and the error names the write.
+The ops and their fields:
+
+| op | Fields |
+|---|---|
+| `rename` | `address`, `name`, `kind` (optional) |
+| `remove-symbol` | `address` |
+| `classify` | `start`, `end`, `type`, `element` (optional) |
+| `unclassify` | `start`, `end` |
+| `comment` | `address`, `placement` (`line` or `side`), `text` |
+| `uncomment` | `address`, `placement` |
+| `reference`, `unreference` | `from`, `to`, `kind` |
+| `module` | `start`, `file`, `title` (optional) |
+| `unmodule` | `start` |
+
+A `line` comment is a line of its own above the address. A `side` comment is at the end of the line of the address. All writes become one revision. If the knowledge refuses one write, the script writes nothing, and the error names the write.
 
 ## Modules
 
-A module tells the c64-source skill where a file of the generated source starts. The file runs to the next module or to the end of its segment. Each address has one module, and each file name has one module. A file name has letters, digits, underscores or hyphens, and ends in `.asm`. The title becomes the first line of the file. Modules have a history, and `revert` restores them.
+A module tells the c64-source skill where a file of the generated source starts. The file runs to the next module or to the end of its segment. Each address has one module, and each file name has one module. A file name has letters, digits, underscores or hyphens, and ends in `.asm`. The title becomes the first line of the file. A `module` write without a title keeps the title that the module has. Modules have a history, and `revert` restores them.
 
 ## Removals
 

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

@@ -9,7 +9,7 @@ import { parseArgs } from "node:util";
 import { formatC64Address, parseC64Address } from "#src/c64.ts";
 import { readProjectFile, writeProjectFile } from "#src/host-client/transfer.ts";
 import { KnowledgeError, openForRead, withWrite } from "#src/knowledge/database.ts";
-import { historyAt, historyNamed, revision, revisions, type HistoryEntry } from "#src/knowledge/history.ts";
+import { historyAt, historyNamed, revision, revisionNote, revisions, type HistoryEntry } from "#src/knowledge/history.ts";
 import {
   at,
   currentRevision,
@@ -281,7 +281,10 @@ function run(argv: string[]): unknown {
         case "spaces":
           return { spaces: listSpaces(db) };
         case "history":
-          return { history: (values.name === undefined ? historyAt(db, address(args[0]), space) : historyNamed(db, values.name, space)).map(historyEntry) };
+          // Each row with the reason and the evidence of the revision that wrote it (F-26).
+          return {
+            history: (values.name === undefined ? historyAt(db, address(args[0]), space) : historyNamed(db, values.name, space)).map((entry) => ({ ...historyEntry(entry), ...revisionNote(db, entry.from) })),
+          };
         case "revisions": {
           const options: { limit?: number; before?: number } = {};
           if (values.limit !== undefined) options.limit = integer(values.limit, "--limit");

package/skills/c64-memory-map/scripts/memmap.ts

@@ -79,7 +79,7 @@ function run(argv: string[]): unknown {
     case "export": {
       if (rest.length !== 0 || values.out === undefined) throw new UsageError("export takes --out <file> and nothing else");
       const names = platformNames();
-      const lines = ["; C64 platform names from the c64-memory-map skill, for ACME.", ...names.map((item) => `${item.name} = ${hex(item.address)}`.padEnd(24) + `; ${item.meaning}`)];
+      const lines = ["; C64 platform names from the c64-memory-map skill, for ACME.", ...names.map((item) => `${item.name} = ${hex(item.address, item.address < 0x100 ? 2 : 4)}`.padEnd(24) + `; ${item.meaning}`)];
       const bytes = Buffer.from(`${lines.join("\n")}\n`, "utf8");
       writeProjectFile(values.out, bytes, { what: "--out" });
       return { out: values.out, names: names.length, bytes: bytes.length };

package/skills/c64-provenance/SKILL.md

@@ -48,10 +48,11 @@ With `--run`, a PRG starts with autostart and RUN. An image starts from its byte
 2. Read `identicalShare`. If it is low and `suggestedShifts` is present, the releases are at different addresses. Run the script again with `--shift`.
 3. Read `differences`. Each one has an address range, the bytes of each release, and `groups`: the releases that have the same bytes there.
 4. To know how the program uses the differences, run the script again with `--run` and the frames that get the program to the part you examine. Read `runtime` of each difference:
-   - `first`: the first access in that release: `read`, `write`, `execute` or `none`. An instruction that reads and then writes the same byte, for example INC, counts as `read`.
+   - `first`: the first access in that release: `read`, `write`, `execute` or `none`. An instruction that reads and then writes the same byte, for example INC, counts as `read`. The operand bytes of an executed instruction count as `execute`, for example the value of `LDA #$03`.
    - `changed`: `true` when the bytes at the end of the run are not the bytes of the release.
    - A range that each release writes before it reads is probably runtime state, not a difference of the releases.
    - A range with `none` in each release is not used in this run. Run more frames or other steps before you decide.
+   - `run.skipped`: the releases have no differences, so no release ran.
 5. Examine each important difference:
    - Disassemble the bytes of each release with the c64-emulator skill, or analyze them with the c64-static-analysis skill.
    - Find what the change does, for example a trainer, a removed copy protection, or a changed text.
@@ -62,7 +63,7 @@ With `--run`, a PRG starts with autostart and RUN. An image starts from its byte
 
 Use `separate` when you have only one release. It gives evidence, not a decision:
 
-- `ranges`: the image in ranges with the same stage and access. `stage` is the last unpack stage that wrote the range. In `image.json`, the last stage is the program. An earlier stage is a depacker, an intro or a loader.
+- `ranges`: the image in ranges with the same stage and access. `stage` is the last unpack stage that wrote the range. In `image.json`, the last stage is the program. An earlier stage is a depacker, an intro or a loader. Only an image from c64-unpacker `capture` has stages. For an image from `loads`, `noStages` tells this.
 - `access`: from the joined `--coverage` files: `executed`, `read`, `written`, `read-written` or `untouched`. `untouched` bytes did not take part in the runs.
 - `codeRegions.unreachable`: code regions of the knowledge that no chain of call and jump references reaches from the entry. Run c64-static-analysis first, so that the knowledge has the code regions and the references.
 - `outside`: RAM outside the image that the program `read` or `executed` but did not write, and code it `generated`. A loader or an earlier stage put the bytes that the program did not write.

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

@@ -252,7 +252,9 @@ async function run(argv: string[]): Promise<unknown> {
     })),
     ...(comparison.moreDifferences ? { moreDifferences: true } : {}),
     ...(suggestions.length > 0 ? { suggestedShifts: suggestions } : {}),
-    ...(frames === undefined ? {} : { run: { frames, steps: steps.length, releases: runs } }),
+    ...(frames === undefined
+      ? {}
+      : { run: { frames, steps: steps.length, releases: runs, ...(comparison.differences.length === 0 ? { skipped: "The releases have no differences, so no release ran." } : {}) } }),
   };
 }
 
@@ -293,7 +295,7 @@ function separateCommand(path: string, coveragePaths: string[], out: string | un
     release: path,
     ...(loaded.entry === undefined ? {} : { entry: formatC64Address(loaded.entry) }),
     ...(lastStage === undefined
-      ? {}
+      ? { noStages: "image.json has no stage log. Only a capture of c64-unpacker writes one. A capture of loads holds one part of a program and has none." }
       : {
           stages: lastStage + 1,
           bytesByStage: Object.fromEntries([...[...Array(lastStage + 1).keys()].map((stage): [string, number] => [String(stage), bytes((range) => range.stage === stage)]), ["none", bytes((range) => range.stage === undefined)]]),

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

@@ -4,7 +4,7 @@
 // Watchpoints and range breakpoints stop the run at an access; the coverage
 // map then tells which range and which access it was.
 
-import { COVERAGE, formatC64Address } from "#src/c64.ts";
+import { COVERAGE, formatC64Address, instructionLength } from "#src/c64.ts";
 import { runProgram } from "#src/host-client/autostart.ts";
 import { readCoverage } from "#src/host-client/coverage.ts";
 import { runActionStep, type ActionStep } from "#src/host-client/steps.ts";
@@ -108,7 +108,12 @@ export async function watchRelease(
   }
   await client.memmap({ action: "clear" });
 
-  /** After a stop: the ranges that the coverage shows accessed get their first access, and lose their points. */
+  /**
+   * After a stop: the ranges that the coverage shows accessed get their first
+   * access, and lose their points. VICE marks only the opcode byte of an
+   * executed instruction, so an instruction that starts up to two bytes before
+   * a range, or in it, executes its operand bytes too (F-27).
+   */
   const settle = async (): Promise<boolean> => {
     const map = await readCoverage(client);
     let found = false;
@@ -116,6 +121,13 @@ export async function watchRelease(
       const range = ranges[index]!;
       let flags = 0;
       for (let address = range.start; address <= range.end; address++) flags |= map[address]!;
+      const from = Math.max(0, range.start - 2);
+      if ((flags & EXECUTE) === 0 && map.subarray(from, range.start).some((byte) => (byte & COVERAGE.ramExecute) !== 0)) {
+        const code = Buffer.from((await client.memoryRead({ address: from, size: range.start - from, space: "c64", view: "ram" })).data, "hex");
+        for (let address = from; address < range.start; address++) {
+          if ((map[address]! & COVERAGE.ramExecute) !== 0 && address + instructionLength(code[address - from]!) - 1 >= range.start) flags |= COVERAGE.ramExecute;
+        }
+      }
       if (accessOf(flags) === "none") continue;
       first[index] = accessOf(flags);
       for (const point of ids) {

package/skills/c64-source/SKILL.md

@@ -74,7 +74,7 @@ Do not edit the generated files. The next run writes over them.
 
 The flags go through the free stack byte below the stack pointer (`stackByte`). The loader changes this byte. The loader does not set the VIC, SID and CIA registers. They stay as the KERNAL set them.
 
-The script simulates the copies first. Then it runs `loader.prg` in the emulator to the entry. It compares the memory, $00/$01 and the registers with the entry state. `loader.verified: true` tells that all of them are equal.
+The script simulates the copies first. Then it runs `loader.prg` in the emulator to its jump to the entry. It compares the memory, $00/$01 and the registers with the entry state there. `loader.verified: true` tells that all of them are equal. An interrupt can run right at the entry, as in the original program.
 
 ## Knowledge
 
@@ -98,7 +98,7 @@ One JSON object:
 - `unusedModules`: modules that start outside the image.
 - `notExecuted`: with `--coverage`, the count of instructions that no run executed, and their ranges. Put these ranges in the report.
 - `check`: `identical`, and the result for each segment. A different segment gives its first different address.
-- `loader`: the program, the copies in their order, the copier page, `stackByte`, `verified` and `differences`.
+- `loader`: the program, the copies in their order, the copier page, `stackByte`, `verified` and `differences`. When the script cannot make the loader, `loader` has `verified: false` and a `reason`. The loader includes the source. Thus a source that does not assemble to the image also stops the loader.
 
 The exit status is 0 when the source is identical and the emulator check of the loader passes. The exit status is 1 for a failed check and for an error. The exit status is 2 for a wrong argument.
 
@@ -107,8 +107,8 @@ The exit status is 0 when the source is identical and the emulator check of the
 - `check.diagnostics`: ACME did not assemble the source. A name in the knowledge can be wrong for ACME. Read the diagnostics and change the name with c64-knowledge.
 - `check.identical: false`: the script has a defect. Give the result to the user.
 - `invalid-input` that names a symbol or a module: change that symbol or module in the knowledge.
-- `invalid-input` for the loader: no copy order or no free pages exist. The message gives the ranges. Capture the image again with fewer segments, or write the loader by hand.
-- `loader.verified: false`: `differences` gives the bytes and registers that are not equal.
+- `loader.verified: false` with a `reason`: the script did not make the loader. The script still writes and checks the source. When no copy order or no free pages exist, or the loader needs too many copies, the reason gives the ranges. Capture the image again with fewer segments, or write the loader by hand.
+- `loader.verified: false` with `differences`: the loader ran, and `differences` gives the bytes and registers that are not equal.
 - `installation-incomplete`, or 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 disassembler or emulator script.
 
 ## Handoffs

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

@@ -5,7 +5,8 @@
 // checks it in the emulator. Exit status: 0 when every check passes, 1 when
 // one fails, 2 for a bad call.
 
-import { posix } from "node:path";
+import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { join, posix } from "node:path";
 import { parseArgs } from "node:util";
 
 import { formatC64Address, parseC64Address, prgRange, textToPetscii } from "#src/c64.ts";
@@ -20,11 +21,11 @@ import { CODE_REGION_TYPES, DEFAULT_SPACE, SPACE, type Space } from "#src/knowle
 import { assemble } from "#src/native/acme.ts";
 import { analyze } from "#src/native/ghidra/analyze.ts";
 import { localToolContext } from "#src/native/local.ts";
-import { GHIDRA_LIMITS, type Diagnostic } from "#src/native/types.ts";
+import { GHIDRA_LIMITS, type AssembledSymbol, type Diagnostic } from "#src/native/types.ts";
 import { platformNames } from "#src/platform.ts";
 import { resolveProjectPath } from "#src/project.ts";
 import { runScript, UsageError } from "#src/script.ts";
-import { planLoader, readEntryState, simulate, type EntryState, type LoaderPlan } from "./loader.ts";
+import { LOADER_JUMP, planLoader, readEntryState, simulate, type EntryState, type LoaderPlan } from "./loader.ts";
 import { OPCODES } from "./opcodes.ts";
 import { instructionText, layout, literalOperand, probeForms, render, type Layout, type Range } from "./source.ts";
 
@@ -148,7 +149,7 @@ async function decode(image: Image, knowledge: ReturnType<typeof readKnowledge>,
 }
 
 /** Assembles files given as text with ACME; the program or the diagnostics. */
-async function assembleFiles(files: Array<{ name: string; text: string }>, entry: string): Promise<{ program?: Buffer; start?: number; diagnostics: Diagnostic[] }> {
+async function assembleFiles(files: Array<{ name: string; text: string }>, entry: string): Promise<{ program?: Buffer; start?: number; symbols?: AssembledSymbol[]; diagnostics: Diagnostic[] }> {
   const contents = files.map((file) => Buffer.from(file.text, "utf8"));
   const { result, attachments } = await assemble(
     { files: files.map((file, index) => ({ path: file.name, size: contents[index]!.length })), entrySource: entry, includeDirs: [], defines: {} },
@@ -156,7 +157,7 @@ async function assembleFiles(files: Array<{ name: string; text: string }>, entry
     localToolContext(),
   );
   if (!result.assembled) return { diagnostics: result.diagnostics };
-  return { program: attachments![0]!, start: result.loadRange!.start, diagnostics: result.diagnostics };
+  return { program: attachments![0]!, start: result.loadRange!.start, ...(result.symbols === undefined ? {} : { symbols: result.symbols }), diagnostics: result.diagnostics };
 }
 
 /**
@@ -238,7 +239,13 @@ async function readRam(client: ViceSessionClient, start: number, size: number):
 }
 
 /** Runs the loader in the emulator to the entry and compares memory, $00/$01 and the registers with the entry state. */
-async function runLoader(path: string, program: Buffer, plan: LoaderPlan, image: Image, state: EntryState): Promise<{ verified: boolean; differences: string[] }> {
+/**
+ * Runs the loader in the emulator to its jump to the entry and compares the
+ * machine with the entry state there. At the jump, every byte and register is
+ * set and no interrupt has run since the PLP: the 6502 takes one only after
+ * the JMP, as the original program can take one right at its entry (F-32).
+ */
+async function runLoader(path: string, program: Buffer, plan: LoaderPlan, image: Image, state: EntryState, jump: number): Promise<{ verified: boolean; differences: string[] }> {
   const client = await ViceSessionClient.open({ videoStandard: "pal" });
   try {
     await client.reset({ mode: "hard", run: false });
@@ -246,9 +253,12 @@ async function runLoader(path: string, program: Buffer, plan: LoaderPlan, image:
     await client.keyboard(textToPetscii("RUN\n"));
     const copier = await client.runUntil({ target: { kind: "address", address: plan.copier, space: "c64" }, timeoutFrames: RUN_LIMIT_FRAMES });
     if (!copier.reached) return { verified: false, differences: [`The loader did not get to its copier at ${formatC64Address(plan.copier)}; it stopped at ${formatC64Address(copier.pc)}.`] };
-    const entry = await client.runUntil({ target: { kind: "address", address: state.pc, space: "c64" }, timeoutFrames: LOADER_FRAMES });
-    if (!entry.reached) return { verified: false, differences: [`The loader did not get to the entry ${formatC64Address(state.pc)}; it stopped at ${formatC64Address(entry.pc)}.`] };
+    const atJump = await client.runUntil({ target: { kind: "address", address: jump, space: "c64" }, timeoutFrames: LOADER_FRAMES });
+    if (!atJump.reached) return { verified: false, differences: [`The loader did not get to its jump to the entry at ${formatC64Address(jump)}; it stopped at ${formatC64Address(atJump.pc)}.`] };
     const memory = await readRam(client, 0x0000, 0x10000);
+    if (memory[jump] !== 0x4c || (memory[jump + 1]! | (memory[jump + 2]! << 8)) !== state.pc) {
+      return { verified: false, differences: [`The instruction at ${formatC64Address(jump)} is not JMP ${formatC64Address(state.pc)}.`] };
+    }
     const port = Buffer.from((await client.memoryRead({ address: 0x0000, size: 2, space: "c64", view: "cpu" })).data, "hex");
     const registers = await client.registersGet("c64");
     const differences: string[] = [];
@@ -272,6 +282,22 @@ async function runLoader(path: string, program: Buffer, plan: LoaderPlan, image:
   }
 }
 
+/** The first words of every file that the script writes. */
+const GENERATED_MARK = "; Generated by c64-source";
+
+/** Removes the .asm files of an earlier run that this run does not write, and an earlier loader.prg; other files stay. */
+function removeOldFiles(out: string, keep: ReadonlySet<string>): void {
+  const directory = resolveProjectPath(out);
+  if (!existsSync(directory)) return;
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    if (!entry.isFile()) continue;
+    const name = entry.name;
+    const path = join(directory, name);
+    if (name === "loader.prg") rmSync(path, { force: true });
+    else if (name.endsWith(".asm") && !keep.has(name) && readFileSync(path, "utf8").startsWith(GENERATED_MARK)) rmSync(path, { force: true });
+  }
+}
+
 async function run(argv: string[]): Promise<{ output: Record<string, unknown>; failed: boolean }> {
   const { values, positionals } = parseArgs({
     args: argv,
@@ -325,11 +351,21 @@ async function run(argv: string[]): Promise<{ output: Record<string, unknown>; f
   const rendered = render(laid, asBytes, header);
   const files = [...rendered.files];
   let loader: LoaderPlan | undefined;
+  // A loader that cannot be planned does not stop the source: the source is written and checked, and the result says why.
+  let loaderRefused: string | undefined;
   if (state !== undefined) {
     const segments = image.segments.map((segment) => ({ ...segment, files: laid.pieces.filter((piece) => piece.start >= segment.start && piece.start <= segment.end).map((piece) => piece.file) }));
-    loader = planLoader({ segments, byteAt: image.byteAt, state, entry: image.entry!, header: [`Loader generated by c64-source from ${image.path}.`, "It copies the segments into place, sets the entry state and jumps to the entry."] });
-    files.push({ name: "loader.asm", text: loader.text });
+    try {
+      loader = planLoader({ segments, byteAt: image.byteAt, state, entry: image.entry!, header: [`Loader generated by c64-source from ${image.path}.`, "It copies the segments into place, sets the entry state and jumps to the entry."] });
+      files.push({ name: "loader.asm", text: loader.text });
+    } catch (error) {
+      if (!(error instanceof WireFailure)) throw error;
+      loaderRefused = error.message;
+    }
   }
+  // Every generated file starts with the mark, so a later run knows its own files and removes the ones it does not write again (F-25).
+  for (const [index, file] of files.entries()) if (!file.text.startsWith(GENERATED_MARK)) files[index] = { ...file, text: `${GENERATED_MARK}. Do not edit: change the knowledge and generate again.\n${file.text}` };
+  removeOldFiles(values.out, new Set(files.map((file) => file.name)));
   for (const file of files) writeProjectFile(`${values.out}/${file.name}`, Buffer.from(file.text, "utf8"), { what: "--out" });
 
   const output: Record<string, unknown> = {
@@ -354,16 +390,20 @@ async function run(argv: string[]): Promise<{ output: Record<string, unknown>; f
         }),
     ...(laid.unusedModules.length === 0 ? {} : { unusedModules: laid.unusedModules.map((module) => ({ start: formatC64Address(module.start), file: module.file })) }),
   };
+  // The loader includes the source, so it is built only from a source that is identical to the image.
+  const notBuilt = (reason: string) => (state === undefined ? {} : { loader: { verified: false, reason: loaderRefused ?? reason } });
   const built = await assembleFiles(files, "main.asm");
   if (built.program === undefined) {
-    return { output: { ...output, check: { identical: false, diagnostics: built.diagnostics.slice(0, MAX_LISTED) } }, failed: true };
+    return { output: { ...output, check: { identical: false, diagnostics: built.diagnostics.slice(0, MAX_LISTED) }, ...notBuilt("The source does not assemble, and the loader includes it.") }, failed: true };
   }
   const checked = check(built.program, built.start!, image);
   output.check = checked;
-  if (!checked.identical || loader === undefined || state === undefined) return { output, failed: !checked.identical };
+  if (!checked.identical) return { output: { ...output, ...notBuilt("The source does not assemble to the image, and the loader includes it.") }, failed: true };
+  if (loaderRefused !== undefined) return { output: { ...output, loader: { verified: false, reason: loaderRefused } }, failed: true };
+  if (loader === undefined || state === undefined) return { output, failed: false };
 
   const loaderBuilt = await assembleFiles(files, "loader.asm");
-  if (loaderBuilt.program === undefined) return { output: { ...output, loader: { verified: false, diagnostics: loaderBuilt.diagnostics.slice(0, MAX_LISTED) } }, failed: true };
+  if (loaderBuilt.program === undefined) return { output: { ...output, loader: { verified: false, reason: "loader.asm does not assemble.", diagnostics: loaderBuilt.diagnostics.slice(0, MAX_LISTED) } }, failed: true };
   const program = loaderBuilt.program;
   // The simulation: the loader in memory as it loads, then every copy in its order, byte by byte.
   const memory = new Int16Array(0x10000).fill(-1);
@@ -376,12 +416,15 @@ async function run(argv: string[]): Promise<{ output: Record<string, unknown>; f
   if (loaderBuilt.start !== 0x0801 || loaderBuilt.start + program.length - 3 !== loader.end || wrongPacking !== undefined) {
     throw new WireFailure("operation-failed", `The assembled loader does not have the planned layout${wrongPacking === undefined ? "" : ` (${wrongPacking.what})`}. This is a defect of the c64-source script.`);
   }
+  const jumpSymbol = loaderBuilt.symbols?.find((symbol) => symbol.name === LOADER_JUMP);
+  if (jumpSymbol === undefined) throw new WireFailure("operation-failed", `The assembled loader has no ${LOADER_JUMP} label. This is a defect of the c64-source script.`);
+  const jump = jumpSymbol.kind === "address" ? jumpSymbol.address : jumpSymbol.value;
   const wrong = simulate(memory, loader.copies, expected);
   if (wrong !== undefined) throw new WireFailure("operation-failed", `The simulated loader writes a wrong byte at ${formatC64Address(wrong)}. This is a defect of the c64-source script.`);
   const loaderPath = `${values.out}/loader.prg`;
   writeProjectFile(loaderPath, program, { what: "--out" });
   (output.files as string[]).push("loader.prg");
-  const ran = await runLoader(loaderPath, program, loader, image, state);
+  const ran = await runLoader(loaderPath, program, loader, image, state, jump);
   output.loader = {
     program: loaderPath,
     copies: loader.copies.map((copy) => ({ what: copy.what, to: `${formatC64Address(copy.target.start)}-${formatC64Address(copy.target.end)}` })),

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

@@ -88,6 +88,9 @@ export interface LoaderPlan {
   text: string;
 }
 
+/** The label of the loader's jump to the entry, in ACME's symbol list. */
+export const LOADER_JUMP = "c64_source_loader_jump";
+
 const LOAD = 0x0801;
 const STUB = 0x080d;
 /** sei, ldx, the 2-page move loop and jmp. */
@@ -295,7 +298,8 @@ export function planLoader(input: LoaderInput): LoaderPlan {
     `        ldx #${hex2(state.x)}`,
     `        ldy #${hex2(state.y)}`,
     "        plp",
-    `        jmp ${hex4(input.entry)}`,
+    // A global label: the check of the loader stops here, before an interrupt can run (F-32).
+    `${LOADER_JUMP} jmp ${hex4(input.entry)}`,
     ".count  !word 0",
     ".index  !byte 0",
     ".back   !byte 0",

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

@@ -93,6 +93,8 @@ export interface Layout {
 
 const hex2 = (value: number) => `$${value.toString(16).padStart(2, "0")}`;
 const hex4 = (value: number) => formatC64Address(value);
+/** ACME reads leading zeros as a 16-bit value, so a zero-page name gets two digits. */
+const constantValue = (address: number) => (address < 0x100 ? hex2(address) : hex4(address));
 const signed = (byte: number) => (byte < 0x80 ? byte : byte - 0x100);
 
 function operandValue(address: number, opcode: number, byteAt: (address: number) => number): number | undefined {
@@ -545,7 +547,7 @@ export function render(layout: Layout, asBytes: ReadonlySet<string>, header: str
     result.files.push({ name: piece.file, text: `${out.join("\n")}\n` });
   }
 
-  const constants = ["; Names outside the image.", ...layout.constants.map((address) => `${layout.names.get(address)} = ${hex4(address)}`)];
+  const constants = ["; Names outside the image.", ...layout.constants.map((address) => `${layout.names.get(address)} = ${constantValue(address)}`)];
   result.files.push({ name: "constants.asm", text: `${constants.join("\n")}\n` });
   const main = [...header.map((line) => `; ${line}`), "", "!cpu 6510", '!source "constants.asm"'];
   for (const piece of layout.pieces) {

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

@@ -66,7 +66,7 @@ The analyzers take at most 1024 entry points. Knowledge routines and `--entry` c
    - If a list is not complete, `rest` gives the c64-knowledge command that lists all of them.
    - `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 and opcodes that the program wrote and then executed. The script does not write those. Look at them and decide.
-   - With `--coverage`, `coverageConflicts` lists the analyzer data regions where the coverage shows executed code. Classify them as code with the c64-knowledge skill, or as `dual-use` when the bytes are also data.
+   - 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.
@@ -78,7 +78,7 @@ Automatic write:
 - 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.
+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.
 

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

@@ -3,11 +3,12 @@
 // 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 { formatC64Address, parseC64Address, prgRange } from "#src/c64.ts";
+import { COVERAGE, formatC64Address, parseC64Address, prgRange } from "#src/c64.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";
@@ -93,7 +94,7 @@ function showConflict(conflict: ImportConflict, analyzer: Analyzer): Record<stri
  * 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">) {
+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 }));
@@ -159,6 +160,9 @@ async function run(argv: string[]): Promise<unknown> {
   const bytes = readProjectFile(image).bytes;
   const coverage = readCoverageFiles(values.coverage ?? []);
   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 {
@@ -212,7 +216,7 @@ async function run(argv: string[]): Promise<unknown> {
     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 }, revision, `DXA analysis of ${image}`, runProvenance(bytes, result.toolVersion));
+    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 });
@@ -237,7 +241,7 @@ async function run(argv: string[]): Promise<unknown> {
   }
 
   const { result } = await analyzeWithGhidra({ imageKind, ...seeds, decompile }, bytes, localToolContext());
-  const imported = record({ ...ghidraFindings(result), space }, revision, `Ghidra analysis of ${image}`, runProvenance(bytes, result.toolVersion));
+  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) {

package/skills/c64-unpacker/SKILL.md

@@ -35,13 +35,13 @@ node <skill>/scripts/unpack.ts loads original/game.d64 --steps parts.json --out
 | `--range '$c000' '$cfff'` | Write this range as a PRG. Without it, the script writes all 64 KiB of RAM as a flat file. |
 | `--timeout-frames 3000` | How many frames the program can run before the capture stops (default 3000). |
 | `--frames 3000` | `trace` only: how many frames the program runs (default 3000). |
-| `--entry '$c000'` | `trace` only: start the program at this address. Without it, `trace` types RUN. A program without a BASIC start line needs it. |
+| `--entry '$c000'` | `trace`, `stages` and `capture`: start the program at this address. Without it, the script types RUN. A file that is not a BASIC program at `$0801` needs it. |
 | `--steps input.json` | Input for the program, right after it starts: a JSON list of steps. Use it when an intro waits for a key or a menu waits for a choice. |
 | `--drive` | `loads` only: each capture also writes the 2 KiB RAM of the 1541 drive as `drive8.prg`. |
 | `--min-block 64` | `loads` only: the smallest block of changed memory that becomes a segment (default 64). The result counts smaller changes as `smallChanges`. |
-| `--min-stage 64` | `stages` only: the smallest block of written memory that starts a new stage when the CPU executes it (default 64). |
+| `--min-stage 64` | `stages` and `capture`: the smallest block of written memory that starts a new stage when the CPU executes it (default 64). |
 
-The capture reads RAM, also the RAM under the ROMs and the I/O area. The script prints one JSON object.
+The capture reads RAM, also the RAM under the ROMs and the I/O area. The script prints one JSON object. The script refuses an option that the command does not use.
 
 A steps file has the steps `write`, `registers`, `joystick`, `type`, `frames` and `runUntil` of the c64-testing skill. Addresses are `$` and four hex digits. For example, wait 50 frames and press the space bar:
 
@@ -53,7 +53,7 @@ A `type` step puts keys in the keyboard queue of the KERNAL. A program that read
 
 ## Workflow
 
-1. Run `inspect`. Read `basicStart` and `packing`:
+1. Run `inspect`. Read `basicStart` and `packing`. `basicStart` gives the first SYS line and its address. When the SYS argument needs values at run time, `sys` is null and `expression` gives the argument. Then `trace`, `stages` and `capture` stop at the first instruction after the BASIC text:
    - `likely`: most of the bytes look compressed. Packed data has this property.
    - `unlikely`: the bytes look like code and data. A simple cruncher can also give this result.
    - `unclear`: the file is short, or the blocks do not give clear evidence. Or the code at the SYS address decodes or moves bytes outside the program.
@@ -64,7 +64,7 @@ A `type` step puts keys in the keyboard queue of the KERNAL. A program that read
    - `start`: the code at the SYS address. `jumpsOutside` and `writesOutside` give an address outside the loaded program, where the code jumps or writes.
    - `decodeLoops`: EOR instructions in loops that store with an index. This is usually decryption or decoding.
 2. Run `trace`. It gives the evidence from the run. Read `packing`:
-   - `likely`: the program wrote code and then executed it. It unpacked, decrypted or moved code. `runningRange` is the code that runs now. Its `start` is usually the entry point of the unpacked program.
+   - `likely`: the program wrote code and then executed it. It unpacked, decrypted or moved code. `runningRange` is the written code that runs at the end of the trace. When the trace ends in ROM code, for example in an interrupt, it is the written code that runs next. Its `start` is usually the entry point of the unpacked program. When no written code runs in 50 more frames, the result has no `runningRange` and no `suggestedUntil`.
    - `unclear`: the program executed a small quantity of code that it wrote. This can be code that changes itself.
    - `unlikely`: the program executed no code that it wrote. If the program waits for a key or a joystick, it can move code after that input. Then use the c64-emulator skill.
 3. Find the address where the unpacked program starts: