@henols/c64-re-tools 2.1.0 → 2.1.2

package/package.json

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

package/skills/c64-assembler/SKILL.md

@@ -31,9 +31,11 @@ node <skill>/scripts/assembler.ts build src main.a --out build/game.prg
 | `--include lib` | An include directory, relative to the source root. Use it again for more directories. |
 | `--define DEBUG=1` | An assembler symbol: an integer, also as `$` hex, or `true` or `false`. Use it again for more symbols. |
 | `--set-pc '$0801'` | The start address when the source does not set one. |
-| `--compare` | Check the program byte by byte against the program in the knowledge, each segment. Put it in with `image` of the c64-knowledge skill. `--space drive8` or `--space bank0` compares with the program of that space. |
+| `--compare` | Check the program byte by byte against the program in the knowledge, each segment. Put it in with `image` of the c64-knowledge skill. `--space drive8` or `--space bank0` compares with the program of that space. The script refuses `--space` without `--compare`. |
 | `--plain` | Write only the bytes of the program, without the 2-byte load address of a PRG. `loadRange` still tells where the bytes go. |
 | `--all-symbols` | List all symbols. Without it, the list does not include the constants that the source does not use. `unusedConstants` gives their count. |
+| `--max-listed 200` | Show at most 200 symbols in the result. The default is 50. `symbols.count` gives the count of all symbols. |
+| `--out-symbols build/game.json` | Write all symbols to this file as `{"symbols": [...]}`. Give this file to the c64-testing skill as the symbols of the rebuild. |
 
 The script copies the full source root. Put all files that the program includes under it. Version control directories stay out.
 
@@ -46,6 +48,7 @@ The target CPU is the 6510. The output is a C64 PRG, or the bytes only with `--p
 - An address is `$` and 1 to 4 hex digits, for example `'$c000'` or `'$fb'`, or a name. A name is a symbol, else an analyzer name that only one analyzer gives. Quote an address in a shell.
 - A range is `<start>-<end>`, for example `'$c000-$cfff'`. In a JSON file, a range is `start` and `end`.
 - Bytes in a JSON file are hex in a field `data`, for example `"data": "a900"`.
+- The script examines each `--out` path before it starts work. It refuses a path in `.c64-re-tools/knowledge/` and the index of the knowledge, because only c64-knowledge writes them. It refuses a folder where the command writes a file, and a file where the command writes a folder.
 - The result is one JSON object on one line. A file that the script writes shows as `{"out", "bytes", "sha256"}`. A list shows as `{"count", "listed"}`, and `rest` tells where to get the rest of a long list.
 - An error is `{"error": {"code": "...", "message": "..."}}`. The message tells what is wrong and what to do.
 - The exit status is 0 for done or PASS, 1 for FAIL, 2 for an error and 3 for INCONCLUSIVE.
@@ -64,7 +67,7 @@ The target CPU is the 6510. The output is a C64 PRG, or the bytes only with `--p
 
 1. Find the source root and the entry source. The entry source sets its own start address with `* = $0801` or similar.
 2. Run the script.
-3. If `result` is `PASS`, the PRG is at `out`. `loadRange` tells where it loads. `symbols` gives each symbol:
+3. If `result` is `PASS`, the PRG is at `out`. `loadRange` tells where it loads. `symbols` is a list with `count` and `listed`. Each item in `listed` is one symbol:
    - Kind `address` has a value in `loadRange`. It gives the `address`.
    - Kind `constant` has a value outside `loadRange`. It gives the `value` as `$` and four or more hex digits. A label in a `!pseudopc` block can be a constant, because its value is the run address, not the load address.
    - `used` is `false` when the source does not use the symbol.
@@ -92,7 +95,7 @@ A symbol from the rebuilt source can give the address of a routine in the rebuil
 - `FAIL` with `assembled: false`: the source has errors. `diagnostics` gives them.
 - `FAIL` with `assembled: true`: `--compare` found differences. The PRG is at `out`.
 
-With `--compare`, `compare` gives `identical` and `segments`: one check for each segment of the program in the knowledge. The `result` of a check is `identical`, `different` with `firstDifference`, or `not covered` when the build does not hold the segment.
+With `--compare`, `compare` gives `identical` and `segments`: one check for each segment of the program in the knowledge. The `result` of a check is `identical`, `different` with `firstDifference`, or `not covered` when the build does not hold the segment. `firstDifference` gives the `address`, and the byte of the build (`built`) and of the knowledge (`reference`), each as `$` and two hex digits.
 
 ## Failure and conflicts
 
@@ -100,6 +103,7 @@ With `--compare`, `compare` gives `identical` and `segments`: one check for each
 - `FAIL` with `assembled: true`: the build is not identical to the program in the knowledge. Read `compare.segments`.
 - `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.
 - `invalid-input`: an option or a path is wrong. Read the message and correct the call.
+- `not-found`: the source root has no main source file with that name, or no folder with files for an `--include`. Give a path relative to the source root.
 
 ## Handoffs
 

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

@@ -1,6 +1,8 @@
 // The c64-assembler script: assembles project source with ACME, which it runs
 // itself, and writes the program into the project.
 
+import { posix } from "node:path";
+
 import { formatC64Address } from "#src/c64.ts";
 import { Refusal } from "#src/errors.ts";
 import { readProjectTree, writeReported } from "#src/host-client/transfer.ts";
@@ -9,8 +11,8 @@ import { knowledgeNames } from "#src/knowledge/names.ts";
 import { requireProgram, type ProgramImage } from "#src/knowledge/program.ts";
 import { assemble } from "#src/native/acme.ts";
 import { localToolContext } from "#src/native/local.ts";
-import type { AcmeParams } from "#src/native/types.ts";
-import { OPTIONS, runScript, UsageError } from "#src/script.ts";
+import type { AcmeParams, AssembledSymbol } from "#src/native/types.ts";
+import { listed as listedItems, OPTIONS, runScript, UsageError } from "#src/script.ts";
 import { compareBuild } from "./lib/compare.ts";
 
 function parseDefine(text: string): [string, number | boolean] {
@@ -23,6 +25,13 @@ function parseDefine(text: string): [string, number | boolean] {
   throw new UsageError(`--define ${match[1]} needs an integer or true/false, not ${value}`);
 }
 
+/** A symbol of the build: an address as $ and four hex digits, a constant as $ and at least four hex digits. */
+function showSymbol(symbol: AssembledSymbol) {
+  return symbol.kind === "address"
+    ? { name: symbol.name, kind: "address", address: formatC64Address(symbol.address), used: symbol.used }
+    : { name: symbol.name, kind: "constant", value: `$${symbol.value.toString(16).padStart(4, "0")}`, used: symbol.used };
+}
+
 await runScript({
   name: "assembler",
   summary: "Assembles project source with ACME and writes the program into the project.",
@@ -36,14 +45,16 @@ await runScript({
         { name: "<entry>", help: "the main source file, relative to the source root" },
       ],
       options: {
-        out: { ...OPTIONS.out, value: "<file.prg>", help: "where to write the program, relative to the project folder", required: true },
+        out: { ...OPTIONS.out, output: "file", value: "<file.prg>", help: "where to write the program, relative to the project folder", required: true },
         include: { kind: "text", value: "<dir>", multiple: true, help: "an include folder, relative to the source root" },
         define: { kind: "text", value: "NAME=VALUE", multiple: true, help: "an assembler symbol: an integer ($hex allowed) or true/false" },
         "set-pc": { kind: "address", value: "<address>", help: "the start address when the source sets none, for example '$0801'" },
         compare: { kind: "flag", help: "check the program byte by byte against the program in the knowledge, each segment" },
-        space: { ...OPTIONS.space, help: "with --compare: the knowledge space of the program: c64 (the default), drive8, or bank0 to bank255" },
+        space: { kind: "space", value: "<space>", help: "with --compare: the knowledge space of the program: c64 (the default), drive8, or bank0 to bank255" },
         plain: { kind: "flag", help: "write the bytes only, without the 2-byte load address of a PRG" },
         "all-symbols": { kind: "flag", help: "list also the constants that the source does not use" },
+        "max-listed": { ...OPTIONS["max-listed"], help: "list at most n symbols (default 50). The count is always given" },
+        "out-symbols": { kind: "path", output: "file", value: "<file.json>", help: "write all symbols to this project file as {\"symbols\": [...]}: the names of the rebuild for c64-testing" },
       },
       notes: "Symbol values are $ and at least four hex digits. Put the program into the knowledge with knowledge.ts image of the c64-knowledge skill before --compare.",
       run: async (call) => {
@@ -51,6 +62,7 @@ await runScript({
         const out = call.string("out")!;
         // Read the program before ACME runs, so a project without it stops at once.
         let program: ProgramImage | undefined;
+        if (call.string("space") !== undefined && !call.flag("compare")) throw new UsageError("--space works only with --compare: it names the knowledge space of the program to compare with");
         if (call.flag("compare")) {
           const db = openForRead();
           try {
@@ -62,6 +74,14 @@ await runScript({
         const setPc = call.address("set-pc");
         const tree = readProjectTree(sourceRoot);
         if (!tree.files.some((file) => file.path === entry)) throw new Refusal("not-found", `${entry} is not a file in ${sourceRoot}. Give the main source file relative to the source root.`);
+        // ACME sees only the files of the source root: an include folder holds some of them. A path out of the root is refused later.
+        for (const folder of call.strings("include")) {
+          const inside = posix.normalize(folder.replaceAll("\\", "/")).replace(/\/+$/, "");
+          if (inside === "." || inside === ".." || inside.startsWith("../") || posix.isAbsolute(inside)) continue;
+          if (!tree.files.some((file) => file.path.startsWith(`${inside}/`))) {
+            throw new Refusal("not-found", `There is no include folder ${folder} with files in the source root ${sourceRoot}. Give --include a folder relative to the source root.`);
+          }
+        }
         const params: AcmeParams = { files: tree.files, entrySource: entry, includeDirs: call.strings("include"), defines: Object.fromEntries(call.strings("define").map(parseDefine)), ...(setPc === undefined ? {} : { setPc }) };
 
         const { result, attachments } = await assemble(params, tree.contents, localToolContext());
@@ -72,7 +92,8 @@ await runScript({
         const compared = program === undefined ? undefined : compareBuild(attachments![0]!, program);
         // An include file of platform names gives many constants that the program does not use.
         const all = call.flag("all-symbols");
-        const listed = result.symbols!.filter((symbol) => all || symbol.kind === "address" || symbol.used);
+        const shown = result.symbols!.filter((symbol) => all || symbol.kind === "address" || symbol.used);
+        const symbolsPath = call.string("out-symbols");
         return {
           // A build that differs from its reference is a failed check.
           result: compared !== undefined && !compared.identical ? "FAIL" : "PASS",
@@ -80,12 +101,9 @@ await runScript({
           ...written,
           ...(plain ? { plain: true } : {}),
           loadRange: { start: formatC64Address(range.start), end: formatC64Address(range.end), bytes: range.bytes },
-          symbols: listed.map((symbol) =>
-            symbol.kind === "address"
-              ? { name: symbol.name, kind: "address", address: formatC64Address(symbol.address), used: symbol.used }
-              : { name: symbol.name, kind: "constant", value: `$${symbol.value.toString(16).padStart(4, "0")}`, used: symbol.used },
-          ),
-          ...(all ? {} : { unusedConstants: result.symbols!.length - listed.length }),
+          symbols: listedItems(shown, call.count("max-listed")!, showSymbol, "a larger --max-listed, or --out-symbols <file.json> for all symbols"),
+          ...(symbolsPath === undefined ? {} : { symbolsFile: writeReported(symbolsPath, `${JSON.stringify({ symbols: shown.map(showSymbol) }, null, 1)}\n`, { what: "--out-symbols" }) }),
+          ...(all ? {} : { unusedConstants: result.symbols!.length - shown.length }),
           diagnostics: result.diagnostics,
           ...(compared === undefined ? {} : { compare: compared }),
         };

package/skills/c64-assembler/scripts/lib/compare.ts

@@ -1,7 +1,7 @@
 // The byte check of a build: the assembled program against the program
 // in the knowledge, segment by segment.
 
-import { formatC64Address, prgRange } from "#src/c64.ts";
+import { formatC64Address, formatC64Byte, prgRange } from "#src/c64.ts";
 
 export interface SegmentCheck {
   start: string;
@@ -10,7 +10,8 @@ export interface SegmentCheck {
   /** Bytes of the segment that the build does not hold. */
   uncovered?: number;
   differences?: number;
-  firstDifference?: { address: string; built: number; reference: number };
+  /** The first address that differs, with its byte in the build and in the knowledge, each as $ and two hex digits. */
+  firstDifference?: { address: string; built: string; reference: string };
 }
 
 /** The program that the build is checked against: its segments and its bytes in them. */
@@ -34,7 +35,7 @@ export function compareBuild(prg: Uint8Array, program: Reference): { identical:
       const referenceByte = program.byteAt(address);
       if (builtByte === referenceByte) continue;
       differences++;
-      first ??= { address: formatC64Address(address), built: builtByte, reference: referenceByte };
+      first ??= { address: formatC64Address(address), built: formatC64Byte(builtByte), reference: formatC64Byte(referenceByte) };
     }
     const uncovered = segment.end - segment.start + 1 - (to - from + 1);
     return {

package/skills/c64-basic/SKILL.md

@@ -30,6 +30,7 @@ node <skill>/scripts/basic.ts list extracted/game.prg
 - An address is `$` and 1 to 4 hex digits, for example `'$c000'` or `'$fb'`, or a name. A name is a symbol, else an analyzer name that only one analyzer gives. Quote an address in a shell.
 - A range is `<start>-<end>`, for example `'$c000-$cfff'`. In a JSON file, a range is `start` and `end`.
 - Bytes in a JSON file are hex in a field `data`, for example `"data": "a900"`.
+- The script examines each `--out` path before it starts work. It refuses a path in `.c64-re-tools/knowledge/` and the index of the knowledge, because only c64-knowledge writes them. It refuses a folder where the command writes a file, and a file where the command writes a folder.
 - The result is one JSON object on one line. A file that the script writes shows as `{"out", "bytes", "sha256"}`. A list shows as `{"count", "listed"}`, and `rest` tells where to get the rest of a long list.
 - An error is `{"error": {"code": "...", "message": "..."}}`. The message tells what is wrong and what to do.
 - The exit status is 0 for done or PASS, 1 for FAIL, 2 for an error and 3 for INCONCLUSIVE.

package/skills/c64-disk/SKILL.md

@@ -47,6 +47,7 @@ File names show the characters that the C64 shows in a directory list. A byte th
 - An address is `$` and 1 to 4 hex digits, for example `'$c000'` or `'$fb'`, or a name. A name is a symbol, else an analyzer name that only one analyzer gives. Quote an address in a shell.
 - A range is `<start>-<end>`, for example `'$c000-$cfff'`. In a JSON file, a range is `start` and `end`.
 - Bytes in a JSON file are hex in a field `data`, for example `"data": "a900"`.
+- The script examines each `--out` path before it starts work. It refuses a path in `.c64-re-tools/knowledge/` and the index of the knowledge, because only c64-knowledge writes them. It refuses a folder where the command writes a file, and a file where the command writes a folder.
 - The result is one JSON object on one line. A file that the script writes shows as `{"out", "bytes", "sha256"}`. A list shows as `{"count", "listed"}`, and `rest` tells where to get the rest of a long list.
 - An error is `{"error": {"code": "...", "message": "..."}}`. The message tells what is wrong and what to do.
 - The exit status is 0 for done or PASS, 1 for FAIL, 2 for an error and 3 for INCONCLUSIVE.
@@ -97,9 +98,9 @@ The directory, the BAM, an entry or a sector chain as JSON.
 ## Failure and conflicts
 
 - `not-found`: the image file is missing, or the image has no file with that name. Read the directory again and compare the names.
-- `media-error`: the image has a defect or is not a disk image. The message tells the problem, for example a sector chain that loops. Tell the user. Do not change the image.
+- `media-error`: the image, the T64 file or the CRT file has a defect, or its content is not of its type. A CRT with a hardware type that the script does not read also gives `media-error`. The message tells the problem, for example a sector chain that loops. Tell the user. Do not change the file.
 - `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.
-- `invalid-input`: an argument or a path is wrong. Read the message and correct the call.
+- `invalid-input`: an argument or a path is wrong. A file with an extension that the command does not take is also wrong. The message gives each type that the command takes. Read the message and correct the call.
 
 A file that is not `closed` was not written fully. Its data can be incomplete.
 

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

@@ -4,7 +4,7 @@
 
 import { formatC64Address } from "#src/c64.ts";
 import { isRefusal, Refusal } from "#src/errors.ts";
-import { inspectDisk } from "#src/host-client/tools.ts";
+import { DISK_IMAGE_TYPES, inspectDisk } from "#src/host-client/tools.ts";
 import { readProjectFile, writeReported } from "#src/host-client/transfer.ts";
 import { OPTIONS, runScript, type Call, type SubjectSpec } from "#src/script.ts";
 import { parseCrt, parseT64, tapeFile } from "./lib/containers.ts";
@@ -13,14 +13,30 @@ const IMAGE: SubjectSpec = { name: "<image>", help: "a .d64, .d71, .d81 or .g64
 const NAME: SubjectSpec = { name: "<name>", help: "the file name as the directory shows it. Write a byte that has no character as {$xx}, for example {$c1}" };
 
 type Kind = "disk" | "t64" | "crt";
-const kindOf = (image: string): Kind => (image.toLowerCase().endsWith(".t64") ? "t64" : image.toLowerCase().endsWith(".crt") ? "crt" : "disk");
+/** The kind of a file by its extension; undefined for a file that no command takes. */
+function kindOf(image: string): Kind | undefined {
+  const extension = image.toLowerCase().split(".").at(-1) ?? "";
+  if (extension === "t64" || extension === "crt") return extension;
+  return (DISK_IMAGE_TYPES as readonly string[]).includes(extension) ? "disk" : undefined;
+}
+
+const KIND_TEXT: Record<Kind, string> = { disk: "a .d64, .d71, .d81 or .g64 disk image", t64: "a .t64 tape file", crt: "a .crt cartridge file" };
+
+/** The kind of the image of a command; refuses a file of a kind that the command does not take, and names every kind that it takes. */
+function kindFor(command: string, image: string, takes: readonly Kind[]): Kind {
+  const kind = kindOf(image);
+  if (kind !== undefined && takes.includes(kind)) return kind;
+  const kinds = takes.map((item) => KIND_TEXT[item]);
+  const list = kinds.length === 1 ? kinds[0]! : `${kinds.slice(0, -1).join(", ")} or ${kinds.at(-1)}`;
+  throw new Refusal("invalid-input", `${image} is not a file that ${command} takes. Give ${list}.`);
+}
 
 /** Runs `body` and names the file in a refusal of its content. */
 function about<T>(image: string, body: () => T): T {
   try {
     return body();
   } catch (error) {
-    if (isRefusal(error) && error.code === "invalid-input") throw new Refusal(error.code, `${image}: ${error.message}`);
+    if (isRefusal(error) && error.code === "media-error") throw new Refusal(error.code, `${image}: ${error.message}`);
     throw error;
   }
 }
@@ -55,9 +71,7 @@ function cartridge(image: string) {
 }
 
 /** A command that takes only a disk image. */
-const diskOnly = (call: Call, action: string) => {
-  if (kindOf(call.subject(0)) !== "disk") throw new Refusal("invalid-input", `${action} needs a .d64, .d71, .d81 or .g64 disk image, not ${call.subject(0)}`);
-};
+const diskOnly = (call: Call, action: string) => kindFor(action, call.subject(0), ["disk"]);
 
 await runScript({
   name: "disk",
@@ -69,7 +83,7 @@ await runScript({
       subjects: [{ ...IMAGE, help: "a disk image, a .t64 tape file or a .crt cartridge file, relative to the project folder" }],
       run: async (call) => {
         const image = call.subject(0);
-        const kind = kindOf(image);
+        const kind = kindFor("directory", image, ["disk", "t64", "crt"]);
         if (kind === "t64") return tapeDirectory(image);
         if (kind === "crt") {
           const { header, chips } = cartridge(image);
@@ -109,12 +123,12 @@ await runScript({
       name: "read",
       summary: "Writes the bytes of one file into the project. It also reads a .t64 tape file.",
       subjects: [{ ...IMAGE, help: "a disk image or a .t64 tape file, relative to the project folder" }, NAME],
-      options: { out: { ...OPTIONS.out, value: "<file>", help: "the file to write, relative to the project folder", required: true } },
+      options: { out: { ...OPTIONS.out, output: "file", value: "<file>", help: "the file to write, relative to the project folder", required: true } },
       run: async (call) => {
         const [image, name] = [call.subject(0), call.subject(1)];
         const out = call.string("out")!;
-        const kind = kindOf(image);
-        if (kind === "crt") throw new Refusal("invalid-input", `read takes a disk image or a .t64 tape file. Give crt for ${image}`);
+        if (kindOf(image) === "crt") throw new Refusal("invalid-input", `read takes a disk image or a .t64 tape file. Use the command crt for the cartridge file ${image}.`);
+        const kind = kindFor("read", image, ["disk", "t64"]);
         if (kind === "t64") {
           const { bytes } = readProjectFile(image);
           const tape = about(image, () => parseT64(bytes));
@@ -131,10 +145,10 @@ await runScript({
       name: "crt",
       summary: "Writes each CHIP packet of a cartridge as a PRG, and crt.json with the header and the packets.",
       subjects: [{ name: "<file.crt>", help: "a .crt cartridge file, relative to the project folder" }],
-      options: { out: { ...OPTIONS.out, value: "<dir>", help: "the folder for the files, relative to the project folder", required: true } },
+      options: { out: { ...OPTIONS.out, output: "folder", value: "<dir>", help: "the folder for the files, relative to the project folder", required: true } },
       run: (call) => {
         const image = call.subject(0);
-        if (kindOf(image) !== "crt") throw new Refusal("invalid-input", `crt needs a .crt file, not ${image}`);
+        kindFor("crt", image, ["crt"]);
         const out = call.string("out")!;
         const { crt, header, chips } = cartridge(image);
         const files = crt.chips.map((chip, index) => writeReported(`${out}/${chips[index]!.file}`, Buffer.concat([Buffer.from([chip.address & 0xff, chip.address >> 8]), chip.data]), { what: "--out" }));

package/skills/c64-disk/scripts/lib/containers.ts

@@ -5,6 +5,7 @@
 
 import { formatC64Address, petsciiNameToText } from "#src/c64.ts";
 import { Refusal } from "#src/errors.ts";
+import { hasSignature } from "#src/media.ts";
 
 /** The CRT hardware types this toolkit reads, by type number. */
 export const CRT_TYPES: Record<number, string> = { 0: "normal", 5: "Ocean", 19: "Magic Desk", 32: "EasyFlash" };
@@ -30,36 +31,34 @@ export interface Crt {
   chips: CrtChip[];
 }
 
-const SIGNATURE = "C64 CARTRIDGE   ";
-
 export function parseCrt(bytes: Uint8Array): Crt {
   const buffer = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
-  if (buffer.length < 0x40 || buffer.toString("latin1", 0, 16) !== SIGNATURE) throw new Refusal("invalid-input", "the file is not a CRT: it does not start with C64 CARTRIDGE");
+  if (buffer.length < 0x40 || !hasSignature("crt", buffer)) throw new Refusal("media-error", "the file is not a CRT: it does not start with C64 CARTRIDGE");
   const headerLength = buffer.readUInt32BE(0x10);
   const type = buffer.readUInt16BE(0x16);
   const exrom = buffer[0x18]!;
   const game = buffer[0x19]!;
   const typeName = CRT_TYPES[type];
   if (typeName === undefined) {
-    throw new Refusal("invalid-input", `the CRT has hardware type ${type}; this toolkit reads types ${Object.entries(CRT_TYPES).map(([number, name]) => `${number} (${name})`).join(", ")}`);
+    throw new Refusal("media-error", `the CRT has hardware type ${type}; this toolkit reads types ${Object.entries(CRT_TYPES).map(([number, name]) => `${number} (${name})`).join(", ")}`);
   }
   const name = buffer.toString("latin1", 0x20, 0x40).replace(/\0+$/, "");
   const chips: CrtChip[] = [];
   let offset = Math.max(headerLength, 0x40);
   while (offset + 0x10 <= buffer.length) {
-    if (buffer.toString("latin1", offset, offset + 4) !== "CHIP") throw new Refusal("invalid-input", `the CRT has no CHIP packet at offset ${offset}`);
+    if (buffer.toString("latin1", offset, offset + 4) !== "CHIP") throw new Refusal("media-error", `the CRT has no CHIP packet at offset ${offset}`);
     const packetLength = buffer.readUInt32BE(offset + 4);
     const chipType = buffer.readUInt16BE(offset + 8);
     const bank = buffer.readUInt16BE(offset + 10);
     const address = buffer.readUInt16BE(offset + 12);
     const size = buffer.readUInt16BE(offset + 14);
-    if (packetLength < 0x10 || offset + packetLength > buffer.length) throw new Refusal("invalid-input", `the CHIP packet at offset ${offset} runs past the end of the file`);
-    if (bank > 255) throw new Refusal("invalid-input", `the CHIP packet at offset ${offset} has bank ${bank}; banks go up to 255`);
-    if (size > packetLength - 0x10 || address + size > 0x10000) throw new Refusal("invalid-input", `the CHIP packet at offset ${offset} has a wrong size ${size} at ${formatC64Address(address)}`);
+    if (packetLength < 0x10 || offset + packetLength > buffer.length) throw new Refusal("media-error", `the CHIP packet at offset ${offset} runs past the end of the file`);
+    if (bank > 255) throw new Refusal("media-error", `the CHIP packet at offset ${offset} has bank ${bank}; banks go up to 255`);
+    if (size > packetLength - 0x10 || address + size > 0x10000) throw new Refusal("media-error", `the CHIP packet at offset ${offset} has a wrong size ${size} at ${formatC64Address(address)}`);
     if (size > 0) chips.push({ bank, address, size, chipType, data: buffer.subarray(offset + 0x10, offset + 0x10 + size) });
     offset += packetLength;
   }
-  if (chips.length === 0) throw new Refusal("invalid-input", "the CRT has no CHIP packet with data");
+  if (chips.length === 0) throw new Refusal("media-error", "the CRT has no CHIP packet with data");
   const crt: Crt = { name, type, typeName, exrom, game, chips };
   if (type === 0) crt.mode = exrom === 0 && game === 1 ? "8k" : exrom === 0 && game === 0 ? "16k" : "ultimax";
   return crt;
@@ -85,7 +84,7 @@ export interface Tape {
 
 export function parseT64(bytes: Uint8Array): Tape {
   const buffer = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
-  if (buffer.length < 0x40 || !buffer.toString("latin1", 0, 32).startsWith("C64")) throw new Refusal("invalid-input", "the file is not a T64: it does not start with C64");
+  if (buffer.length < 0x40 || !hasSignature("t64", buffer)) throw new Refusal("media-error", "the file is not a T64: it does not start with C64");
   const maxEntries = buffer.readUInt16LE(0x22);
   const name = buffer.toString("latin1", 0x28, 0x40).replace(/[\0 ]+$/, "");
   const raw: Array<Omit<TapeEntry, "bytes" | "end"> & { end: number }> = [];
@@ -107,7 +106,7 @@ export function parseT64(bytes: Uint8Array): Tape {
   // Many T64 files have a wrong end address: the next file or the end of the file bounds each one.
   const offsets = [...raw.map((entry) => entry.offset), buffer.length].sort((a, b) => a - b);
   const entries = raw.map((entry): TapeEntry => {
-    if (entry.offset >= buffer.length) throw new Refusal("invalid-input", `the T64 entry ${entry.name} starts past the end of the file`);
+    if (entry.offset >= buffer.length) throw new Refusal("media-error", `the T64 entry ${entry.name} starts past the end of the file`);
     const available = offsets.find((offset) => offset > entry.offset)! - entry.offset;
     const stated = entry.end - entry.start;
     const bytes = stated > 0 && stated <= available ? stated : Math.min(available, 0x10000 - entry.start);

package/skills/c64-docs/SKILL.md

@@ -49,6 +49,7 @@ node <skill>/scripts/docs.ts link README.md docs --source src --check
 - An address is `$` and 1 to 4 hex digits, for example `'$c000'` or `'$fb'`, or a name. A name is a symbol, else an analyzer name that only one analyzer gives. Quote an address in a shell.
 - A range is `<start>-<end>`, for example `'$c000-$cfff'`. In a JSON file, a range is `start` and `end`.
 - Bytes in a JSON file are hex in a field `data`, for example `"data": "a900"`.
+- The script examines each `--out` path before it starts work. It refuses a path in `.c64-re-tools/knowledge/` and the index of the knowledge, because only c64-knowledge writes them. It refuses a folder where the command writes a file, and a file where the command writes a folder.
 - The result is one JSON object on one line. A file that the script writes shows as `{"out", "bytes", "sha256"}`. A list shows as `{"count", "listed"}`, and `rest` tells where to get the rest of a long list.
 - An error is `{"error": {"code": "...", "message": "..."}}`. The message tells what is wrong and what to do.
 - The exit status is 0 for done or PASS, 1 for FAIL, 2 for an error and 3 for INCONCLUSIVE.
@@ -144,7 +145,7 @@ Do not store:
 - `invalid-input` that names an old revision: the knowledge changed after the source. Generate the source again, then run `docs.ts generate`.
 - `invalid-input` that names a page in the reference directory: the page is not a page of `docs.ts generate`. Move the page out of the directory. Do not give `--out` a directory with pages that you wrote.
 - `unknown-name`: the page uses a name that is not in the knowledge. Record the name with c64-knowledge, or correct the page.
-- `wrong-address`: the address after the name is not the address of the name, and it is not a place inside it. The message gives the routine that holds the address. Correct the name or the address. For a value, write `` `scroll_moves` = `$10` ``.
+- `wrong-address`: the address after the name is not the address of the name, and it is not a place inside it. The message gives the routine that holds the address. Correct the name or the address. For a value, write `` `scroll_moves` = `$10` ``. The script does not link such a mention until it is correct.
 - `missing-file`, `missing-anchor` or `missing-line`: a link goes to nothing. Correct the link. An image of an asset must exist in the project.
 - `stale-reference`: the source or the reference is older than the knowledge. Do steps 2 and 3 of the workflow again.
 - `conflict`: the knowledge has conflicts from a git merge. Run `knowledge.ts merge` of c64-knowledge.

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

@@ -297,7 +297,7 @@ await runScript({
       summary: "Writes the reference pages: a page for each module, and pages for the names, the variables, the tables, the memory map and the graphics.",
       subjects: [{ name: "<source-dir>", help: SOURCE.help }],
       options: {
-        out: { ...OPTIONS.out, value: "<dir>", help: "the folder for the reference pages, relative to the project folder, for example docs/reference. generate writes only there and refuses a page in it that it did not write", required: true },
+        out: { ...OPTIONS.out, output: "folder", value: "<dir>", help: "the folder for the reference pages, relative to the project folder, for example docs/reference. generate writes only there and refuses a page in it that it did not write", required: true },
         "max-listed": OPTIONS["max-listed"],
       },
       notes: "When the knowledge has the program of the source (knowledge.ts image of the c64-knowledge skill), the reference decodes the tables and shows the graphics.",

package/skills/c64-docs/scripts/lib/links.ts

@@ -2,8 +2,8 @@
 // its line in the source; the address after it links to the entry of the name
 // in the reference, or, for an address inside the routine or the data of the
 // name ("draw_room $0AAF", a place in draw_room), to the line of that address. A link that points into the source or the reference is
-// managed: link.ts writes it again when a line moves. Other links stay as the
-// person wrote them; link.ts only checks that their targets exist.
+// managed: docs.ts link writes it again when a line moves. Other links stay as the
+// person wrote them; docs.ts link only checks that their targets exist.
 
 import { posix } from "node:path";
 
@@ -24,7 +24,7 @@ export interface LinkContext {
   lineOf: (address: number) => string | undefined;
   /** The name of the routine or data that holds an address, for a message. */
   placeOf: (address: number) => string | undefined;
-  /** True for a project path that link.ts manages: a file of the source or a page of the reference. */
+  /** True for a project path that docs.ts link manages: a file of the source or a page of the reference. */
   managed: (path: string) => boolean;
 }
 
@@ -102,6 +102,8 @@ export function linkPage(text: string, context: LinkContext): { text: string; ch
         const expected = `$${(address + delta).toString(16).toUpperCase().padStart(4, "0")}`;
         const holder = context.placeOf(given!);
         report("wrong-address", `\`${name}${offset ?? ""}\` is ${expected} in the knowledge, and the page gives ${addressText}${holder === undefined || holder === name ? "" : `, a place in \`${holder}\``}. Correct the name or the address.${digits!.length <= 2 ? ` For a value, write \`${name}\` = \`${addressText}\`.` : ""}`);
+        // A mention with a problem gets no link: the text stays as the person wrote it until it is correct.
+        return whole;
       }
       const shownName = `${TICK}${name}${offset ?? ""}${TICK}`;
       const code = context.codeOf(name);

package/skills/c64-docs/scripts/lib/reference.ts

@@ -12,7 +12,7 @@ import type { CommentRow, ModuleRow, ReferenceRow, RegionRow, SymbolRow } from "
 import type { RegionType } from "#src/knowledge/schema.ts";
 import type { SourceMap } from "./source-map.ts";
 
-/** The first line of every generated page. A page without it is a page of a person, and generate.ts never writes over it. */
+/** The first line of every generated page. A page without it is a page of a person, and docs.ts generate never writes over it. */
 export const GENERATED_MARK = "<!-- Generated by c64-docs";
 
 export interface ReferenceInput {
@@ -183,7 +183,7 @@ export function buildReference(input: ReferenceInput): { files: ReferenceFile[];
   }
   const titleOf = (file: string) => input.modules.find((module) => module.file === file)?.title;
 
-  const header = `${GENERATED_MARK} from knowledge revision ${input.revision} and ${map.pathOf("source-map.json")}. Do not edit: change the knowledge, generate the source again, then run generate.ts. -->`;
+  const header = `${GENERATED_MARK} from knowledge revision ${input.revision} and ${map.pathOf("source-map.json")}. Do not edit: change the knowledge, generate the source again, then run docs.ts generate. -->`;
   const files: ReferenceFile[] = [];
   const write = (path: string, lines: string[]) => files.push({ path, bytes: Buffer.from(`${[header, ...lines].join("\n").replace(/\n{3,}/g, "\n\n")}\n`, "utf8") });
 

package/skills/c64-emulator/SKILL.md

@@ -57,6 +57,7 @@ For a large result, give `out` with a path in the project. `c64_memory_read`, `c
 
 - Only the first byte of an instruction gets execute. Thus `read` without `out` gives a new range at each instruction of code. For code, use `summary`, or `read` with `out`.
 - A read on a byte right after executed code, or at a return address, can be a dummy read of the 6502. The CPU reads such a byte but does not use it.
+- VICE has a known flaw: it uses only one bit of `$01` to find RAM or ROM. At `$A000-$BFFF` it gives `rom` when bit 0 is set, also when bit 1 is clear and the CPU used the RAM there. Many games set `$01` to `$35`. Then code that runs at `$A000-$BFFF` shows as ROM. `emulatorFlaw` in the result tells when this can occur. Every access at `$D000-$DFFF` shows as I/O.
 
 `c64_profile` gives the routines that used the most cycles since the session started, the last `clear` or the last `c64_window`. Use action `clear` before the part of the program that you want to measure. The profiler gives the cycles to the routine that a JSR called last. Code that the CPU enters with JMP or a branch counts for that routine. After `c64_window` or a snapshot restore, the profiler of VICE keeps the routines that ran before the restore. Then `c64_profile` can give the cycles of the program to such a routine, for example `$fd50`. Do not trust the routine addresses of `c64_profile` after a restore.
 
@@ -80,7 +81,7 @@ Write operations need a stopped CPU. Stop the CPU with `c64_execution` action `p
 
 A cartridge from `c64_autostart` stays in the C64 through every reset, as on a real C64. `c64_status` gives `cartridge: true` while the C64 has it, and `cartridge: false` when it does not. `c64_autostart` of a file that is not a cartridge removes the cartridge first. `c64_autostart` also sets both joysticks to the center first. `joysticksCentred` gives the ports that it changed.
 
-Step, next and until-return work only in space `c64`. The emulator cannot stop the disk drive CPU after one instruction. To find when the drive executes an address, use `c64_run_until` with an address target in space `drive8`, or a breakpoint in space `drive8`. The drive can execute a few more instructions before it stops. The computer completes its current instruction. The `pc` in the result is the drive address where it stopped.
+Step, next and until-return work only in space `c64`. The emulator cannot stop the disk drive CPU after one instruction. To find when the drive executes an address, use `c64_run_until` with an address target in space `drive8`, or a breakpoint in space `drive8`. The drive can execute a few more instructions before it stops. The computer completes its current instruction. The `pc` in the result is the drive address where it stopped. `space` in the result is `drive8`. A breakpoint or a watchpoint in space `drive8` that stops `advance-frames` gives the same `pc` and `space`. `c64_status` also gives them. A memory target or a memory condition tests only space `c64`.
 
 `c64_keyboard` puts keys in the keyboard queue of the KERNAL. A program that reads the keyboard matrix directly does not see them. Many games do this. No MCP tool presses a key of the keyboard matrix. For such a program:
 
@@ -137,7 +138,13 @@ An error is `{"error": {"code": "...", "message": "..."}}`. The message tells wh
 - `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.
 - `c64_run_until` with `stopReason` `timeout`: the target did not occur in the frame limit. This is evidence too. Report it.
-- `c64_run_until` with `stopReason` `jam`: the CPU executed a JAM opcode and stopped. Report the address.
+- `stopReason` `jam`: the CPU executed a JAM opcode and stopped. Report the address. The CPU stays stopped, as on a real C64. Each run gives `jam` again. Step, next, until-return and resume refuse with `operation-failed`. Only `c64_reset`, a snapshot restore or `c64_autostart` starts the CPU again.
+- After a JAM, VICE records no CPU history until the next reset. If the CPU ran again after a snapshot restore, `c64_cpu_history` refuses with `operation-failed`. `c64_run_until` then gives `historyMissing` in place of `history`. Use `c64_reset`, or use `c64_trace`.
+- `invalid-input`: the message names the field and the rule. Change the call to obey the rule.
+- `not-found`: a file, a snapshot, a baseline or a point that the call names does not exist.
+- `unsupported-in-space`: the action works only in space `c64`.
+- `limit-exceeded`: the call goes past a limit of the session, for example the number of snapshots. The message names the limit.
+- `operation-failed`: the emulator did not do the operation. The message tells why.
 
 If the runtime evidence does not agree with the current knowledge, do not change the knowledge. Report the conflict and hand it to c64-knowledge.
 

package/skills/c64-knowledge/SKILL.md

@@ -27,7 +27,7 @@ One of these:
 node <skill>/scripts/knowledge.ts <command> [subjects] [options]
 ```
 
-A symbol is the name of an address from the user or the LLM. An analyzer name is a second name from DXA, Ghidra or an idiom, for example `FUN_17e2`. Each analyzer keeps its own name at an address. `at`, `search` and `export` show the analyzer names. The generated source uses only the symbols, unless c64-source gets `--analyzer-names`. To use an analyzer name in the source, `rename` the address with it.
+A symbol is the name of an address from the user or the LLM. An analyzer name is a second name from DXA, Ghidra or an idiom, for example `FUN_17e2`. Each analyzer keeps its own name at an address. `at`, `search` and `export` show the analyzer names. The generated source uses only the symbols, unless c64-source gets `--analyzer-names`. To use an analyzer name in the source, `rename` the address with it. A symbol name is a label for ACME: a letter or underscore, then letters, digits or underscores. The knowledge refuses the name of a 6502 instruction, for example `lda`, in upper or lower case.
 
 | Need | Command |
 |---|---|
@@ -42,6 +42,7 @@ A symbol is the name of an address from the user or the LLM. An analyzer name is
 | What the knowledge holds of the program | `program` |
 | The code of a range with names, comments, access and references | `listing '$0400-$04ff'` |
 | Name the symbol at an address | `rename '$2100' update_player --kind routine` |
+| The rows that one revision added and closed, also memory, entry and coverage rows | `revision 20261015T2145` |
 | Remove a symbol | `remove-symbol '$2100'` |
 | Classify memory | `classify '$3000-$303f' sprite` |
 | Classify a table of records | `classify '$3000-$303b' bytes --element 6` |
@@ -62,12 +63,12 @@ A symbol is the name of an address from the user or the LLM. An analyzer name is
 | Files of generated source | `modules` |
 | The address spaces that hold knowledge | `spaces` |
 | History | `history '$2100'`, `history --name update_player`, `history --macro inc16`, `revisions`, `revision 20261015T2145` |
-| Go back to an earlier state | `revert 20261015T2145` |
+| Go back to an earlier state | `revert 20261015T2145` for all spaces, or `revert 20261015T2145 --space bank3` for one space |
 | Decide the conflicts after a git merge | `merge --reason 'merge of two computers'` |
 
 A revision has an id such as `20261015T214501.123-k3f9qz`. The id starts with the date and time. A command takes the full id, or a start of the id that only one revision has. The revision `0` is the knowledge before the first revision.
 
-Every command takes `--space`: `c64` (the default), `drive8` for code in the 1541 drive, or `bank0` to `bank255` for cartridge banks. Drive code and banks use the same addresses as the C64, so each space has its own knowledge. A name is unique inside one space. In a batch, a write can name its own `space`.
+Every command takes `--space`: `c64` (the default), `drive8` for code in the 1541 drive, or `bank0` to `bank255` for cartridge banks. `revert` is different: without `--space`, it reverts all spaces. With `--space`, it reverts only that space. Drive code and banks use the same addresses as the C64, so each space has its own knowledge. A name is unique inside one space. In a batch, a write can name its own `space`.
 
 Symbol kinds are `label`, `routine`, `variable`, `data` and `vector`. Reference kinds are `call`, `jump`, `read`, `write`, `reference` and `pointer`. Only an operand expression writes a `pointer` reference.
 
@@ -94,6 +95,7 @@ Region types:
 - An address is `$` and 1 to 4 hex digits, for example `'$c000'` or `'$fb'`, or a name. A name is a symbol, else an analyzer name that only one analyzer gives. Quote an address in a shell.
 - A range is `<start>-<end>`, for example `'$c000-$cfff'`. In a JSON file, a range is `start` and `end`.
 - Bytes in a JSON file are hex in a field `data`, for example `"data": "a900"`.
+- The script examines each `--out` path before it starts work. It refuses a path in `.c64-re-tools/knowledge/` and the index of the knowledge, because only c64-knowledge writes them. It refuses a folder where the command writes a file, and a file where the command writes a folder.
 - The result is one JSON object on one line. A file that the script writes shows as `{"out", "bytes", "sha256"}`. A list shows as `{"count", "listed"}`, and `rest` tells where to get the rest of a long list.
 - An error is `{"error": {"code": "...", "message": "..."}}`. The message tells what is wrong and what to do.
 - The exit status is 0 for done or PASS, 1 for FAIL, 2 for an error and 3 for INCONCLUSIVE.
@@ -139,6 +141,7 @@ The knowledge holds the program, so a project needs no image or coverage files.
 - `image` writes only the bytes that changed. The same image again writes nothing. A new image replaces the program of the space. The history keeps the old bytes.
 - `coverage` joins the maps. It keeps each address that a run executed, read or wrote. It also keeps each address that one run wrote and executed: self-modified code. `coverage` puts each map into the space of `--space`. You can add the same map to each space. A map that the space has is not added again.
 - The capture and the maps are not necessary after the import. Keep them in `.c64-re-tools/local/`.
+- A `revert` also gives back the coverage maps of that revision. A `revert` to a revision before an import removes the map and its ranges. Then you can import the map again, and `--evidence coverage:<map>` refuses it until you do.
 
 For more than a few writes, use `apply -` and give the writes on standard input as one JSON list. Each write has `op` and the arguments of the command with the same name, for example:
 
@@ -171,7 +174,7 @@ The ops and their fields:
 | `unmacro` | `name` |
 | `use` | `start`, `end`, `macro`, `args` (a list or a comma list) |
 
-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. The script checks an `operand`, `patch` or `use` write against the program of the knowledge in the space of `--space`. All writes become one revision. If the knowledge refuses one write, the script writes nothing, and the error names the write.
+Each write can also have `space`. 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. The script checks an `operand`, `patch` or `use` write against the program of the knowledge in the space of `--space`. All writes become one revision. If the knowledge refuses one write, the script writes nothing, and the error names the write.
 
 The c64-provenance skill writes a batch with `match --out`. The batch holds the names of library routines at their addresses in this program. Read the `batch.leftOut` of its result first. Then apply the batch with the command in its `apply`.
 
@@ -213,6 +216,7 @@ Give one selector:
 | `--value <symbol>` | The symbol plus the offset | `lda bar_colours-1,x` |
 | `--expr <text>` | ACME expression text with names and numbers | `lda #(sprite_bank + 5*64) / 64` |
 
+- The address is the start of an instruction in a code region. The script decodes the instructions from the start of the region, as `listing` does. It refuses an address in no code region and an operand byte of an instruction. Classify the code first.
 - `--offset` adds a whole number to the symbol. Write a negative offset as `--offset=-1`.
 - A name is a symbol of the knowledge or a platform name of the c64-memory-map skill.
 - `--expr` takes `$`, `%` and decimal numbers, names, brackets, the operators `+ - * / % << >> >>> & | XOR`, and `<`, `>`, `-` and `!` before an operand.
@@ -277,7 +281,7 @@ The script records the origin `llm`. Use `--by user` only when the user decides
 
 ## Result
 
-For a read: the current or historical knowledge in compact JSON.
+For a read: the current or historical knowledge in compact JSON. Each list of a list command has `count` and `listed`. `--max-listed` limits `listed`. The default is 50. When the list is longer, `rest` tells how to get the other items. For `revisions`, give `--before` with the oldest revision in `listed`.
 
 For a write: the new revision and the current value after the write. If the write replaces a symbol, a region or an operand expression of a different origin, `previous` gives that row as it was before the write. For example, an `llm` write over a `user` name gives `previous`. Read `previous` and tell the user about the change. For `apply`, `replaced` lists each write that replaced a row. Each item has the number of the write, its `op` and its `previous`.