@henols/c64-re-tools 2.0.1 → 2.1.0-rc.2

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

@@ -3,7 +3,7 @@
 // the bytes from coverage files, and the references in and out. Nothing here
 // reads files: knowledge.ts gives the lookups.
 
-import { COVERAGE } from "#src/c64.ts";
+import { COVERAGE, formatC64Address, formatC64Byte } from "#src/c64.ts";
 import { MODE_LENGTH, OPCODES, type Mode } from "#src/opcodes.ts";
 
 export interface ListingSource {
@@ -41,8 +41,6 @@ export interface ListingLine {
 }
 
 const CODE = new Set(["code", "jumps"]);
-const hex2 = (value: number) => `$${value.toString(16).padStart(2, "0")}`;
-const hex4 = (value: number) => `$${value.toString(16).padStart(4, "0")}`;
 const DATA_PER_LINE = 8;
 
 /** The access class of bytes from the coverage: x, r and w as they occur, or - for none. */
@@ -57,12 +55,12 @@ function accessOf(coverage: Uint8Array | undefined, start: number, length: numbe
 /** The operand of an instruction in ACME syntax, with the name of its target where one exists. */
 function operandOf(mode: Mode, address: number, low: number, high: number, nameOf: ListingSource["nameOf"]): string {
   const word = low | (high << 8);
-  const named = (target: number, digits: 2 | 4) => nameOf(target) ?? (digits === 2 ? hex2(target) : hex4(target));
+  const named = (target: number, digits: 2 | 4) => nameOf(target) ?? (digits === 2 ? formatC64Byte(target) : formatC64Address(target));
   switch (mode) {
     case "imp":
       return "";
     case "imm":
-      return `#${hex2(low)}`;
+      return `#${formatC64Byte(low)}`;
     case "zp":
       return named(low, 2);
     case "zpx":
@@ -138,7 +136,7 @@ export function listing(source: ListingSource, start: number, end: number): List
       values.push(source.byteAt(at)!);
       at++;
     }
-    if (address >= start) lines.push(line(address, values.length, `!byte ${values.map(hex2).join(",")}`));
+    if (address >= start) lines.push(line(address, values.length, `!byte ${values.map(formatC64Byte).join(",")}`));
     address = at;
   }
   return lines;
@@ -149,7 +147,7 @@ export function listingText(lines: readonly ListingLine[]): string {
   const out: string[] = [];
   for (const item of lines) {
     for (const comment of item.lineComments ?? []) out.push(`                         ; ${comment}`);
-    const head = `${hex4(item.address)}  ${item.bytes.padEnd(9)} ${(item.access ?? "").padEnd(3)}`;
+    const head = `${formatC64Address(item.address)}  ${item.bytes.padEnd(9)} ${(item.access ?? "").padEnd(3)}`;
     const body = (item.label === undefined ? "" : `${item.label} `).padEnd(20) + item.text;
     const notes = [
       ...(item.comment === undefined ? [] : [item.comment]),

package/skills/c64-memory-map/SKILL.md

@@ -21,10 +21,10 @@ This skill does not read the emulator and does not change project knowledge.
 The script looks up local reference data. It does not use the host runtime.
 
 ```
-node <skill>/scripts/memmap.ts at '$d020' '$0314' '$ffd2'
-node <skill>/scripts/memmap.ts decode '$d018' '$15' --bank '$97'
-node <skill>/scripts/memmap.ts list vic
-node <skill>/scripts/memmap.ts export --out src/hw.asm
+node <skill>/scripts/memory-map.ts at '$d020' '$0314' '$ffd2'
+node <skill>/scripts/memory-map.ts decode '$d018' '$15' --bank '$97'
+node <skill>/scripts/memory-map.ts list vic
+node <skill>/scripts/memory-map.ts export --out src/hw.asm
 ```
 
 | Command | Result |
@@ -34,16 +34,26 @@ node <skill>/scripts/memmap.ts export --out src/hw.asm
 | `list <vic\|sid\|cia1\|cia2\|kernal\|system>` | All entries of that group. |
 | `export --out <file>` | Writes all platform names to a project file as an ACME include: one line for each name, with its meaning as a comment. A zero-page name is `NAME = $xx`. Other names are `NAME = $xxxx`. |
 
-Write an address or a value as `$` and hex digits, as a decimal number, or as `%` and binary digits. Put a `$` value in single quotes in a shell.
+Write a value for `decode` and `--bank` as `$` and hex digits, as a decimal number, or as `%` and binary digits. Put a `$` value in single quotes in a shell.
 
-The script prints one JSON object.
+### Calling the script
+
+- Call a script as `node <skill>/scripts/<script>.ts <command> [subjects] [options]`. The command comes first.
+- `<script>.ts --help` lists the commands. `<script>.ts <command> --help` gives the subjects and the options of one command. The help is JSON: `{"text": "..."}`.
+- 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 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.
 
 ### Project folder
 
 - Paths are relative to the project folder. The project folder is the nearest folder at or above the working directory that holds `.c64-re-tools/`.
 - If the working directory is not in a project and has projects below it, the script refuses and lists them. Then give `--project <folder>` to each script.
 - Write each file that you make for your work in `.c64-re-tools/local/` of the project. Git ignores that folder. Examples are results, batches, step files, runs, snapshots and memory dumps.
-- Move a file out of `.c64-re-tools/local/` only when it is the evidence for a finding. Move it before you give it to `--evidence` of c64-knowledge. `--evidence` refuses a file in `.c64-re-tools/local/`.
+- Move a file out of `.c64-re-tools/local/` only when it is the evidence for a finding. Move it before you give it to `--evidence test:<file>` or `--evidence file:<file>` of c64-knowledge. These two refuse a file in `.c64-re-tools/local/`.
+- Do not move a coverage map after `coverage` of c64-knowledge imported it. `--evidence coverage:<map>` names the map by its path at the import. The knowledge keeps the coverage and the SHA-256 of the map, so the evidence stays valid.
 - Put a run that is evidence in `runs/<name>/`, with its run file, its results and the snapshot files that it uses. Change the paths in the run file to the new paths. Then git keeps them, and another person can do the run again.
 - A shell redirect (`>`) is relative to the working directory, not to the project folder. From the folder above the project, write `<folder>/.c64-re-tools/local/result.json`.
 
@@ -71,9 +81,7 @@ A conclusion about the application can be project knowledge. For example: "the p
 
 ## Result
 
-The platform meaning of each address, or the decoded meaning of a register value. For `export`: the file, the count of names and the bytes.
-
-The exit status is 0 for a result. The exit status is 2 for a wrong argument.
+The platform meaning of each address, or the decoded meaning of a register value. For `export`: the count of names in `names`, and the file as `{out, bytes, sha256}`.
 
 ## Failure and conflicts
 

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

@@ -0,0 +1,81 @@
+// The c64-memory-map script: the platform meaning of C64 addresses and of
+// values in platform registers. Local lookup only; nothing is stored. export
+// writes the platform names to a project file as an ACME include.
+
+import { formatC64Address, formatC64Byte } from "#src/c64.ts";
+import { writeReported } from "#src/host-client/transfer.ts";
+import { knowledgeNames } from "#src/knowledge/names.ts";
+import { decode, IO, lookup, platformNames, ROM, SYSTEM, type Entry } from "#src/platform.ts";
+import { OPTIONS, runScript, UsageError } from "#src/script.ts";
+
+const show = (entry: Entry) => ({ start: formatC64Address(entry.start), ...(entry.end !== entry.start ? { end: formatC64Address(entry.end) } : {}), name: entry.name, meaning: entry.meaning });
+
+const LISTS: Record<string, () => Entry[]> = {
+  vic: () => IO[0]!.registers,
+  sid: () => IO[1]!.registers,
+  cia1: () => IO[2]!.registers,
+  cia2: () => IO[3]!.registers,
+  kernal: () => ROM,
+  system: () => SYSTEM,
+};
+
+await runScript({
+  name: "memory-map",
+  summary: "The platform meaning of C64 addresses and of values in platform registers.",
+  names: knowledgeNames,
+  commands: [
+    {
+      name: "at",
+      summary: "The platform meaning of each address: its name, area and meaning.",
+      subjects: [{ name: "<address>", help: "an address or a name of the knowledge", list: true }],
+      run: (call) => ({
+        addresses: call.subjects.map((text) => {
+          const found = lookup(call.parseAddress(text, "<address>"));
+          // The chip registers, color RAM and the cartridge I/O areas show only while $01 maps I/O in.
+          const io = found.address >= 0xd000 && found.address <= 0xdfff;
+          return {
+            ...found,
+            address: formatC64Address(found.address),
+            ...(found.mirrorOf === undefined ? {} : { mirrorOf: formatC64Address(found.mirrorOf) }),
+            ...(found.entryStart === undefined ? {} : { entryStart: formatC64Address(found.entryStart) }),
+            ...(io ? { visible: "when $01 shows I/O at $D000 (the default)" } : {}),
+          };
+        }),
+      }),
+    },
+    {
+      name: "decode",
+      summary: "The meaning of a value in a platform register.",
+      subjects: [
+        { name: "<register>", help: "the register: $0001, $d011, $d016, $d018, $d010, $d015-$d01f, $dc0d, $dd00 or $dd0d" },
+        { name: "<value>", help: "the value of the register: $ and hex, decimal, or % and binary, 0 to 255" },
+      ],
+      options: { bank: { kind: "number", value: "<value>", help: "the value of $dd00, for the VIC-II bank of a $d018 value", max: 0xff } },
+      run: (call) => {
+        const register = call.parseAddress(call.subject(0), "<register>");
+        const value = call.parseNumber(call.subject(1), "<value>", 0, 0xff);
+        return { register: formatC64Address(register), value: formatC64Byte(value), name: lookup(register).name, ...decode(register, value, call.count("bank")) };
+      },
+    },
+    {
+      name: "list",
+      summary: "The registers of a chip, the KERNAL jump table, or the system areas.",
+      subjects: [{ name: "<list>", help: `one of ${Object.keys(LISTS).join(", ")}` }],
+      run: (call) => {
+        const list = LISTS[call.subject(0)];
+        if (list === undefined) throw new UsageError(`<list> must be one of ${Object.keys(LISTS).join(", ")}, not ${call.subject(0)}`);
+        return { entries: list().map(show) };
+      },
+    },
+    {
+      name: "export",
+      summary: "Writes the platform names as an ACME include: NAME = $xxxx.",
+      options: { out: { ...OPTIONS.out, value: "<file>", help: "the include file, relative to the project folder", required: true } },
+      run: (call) => {
+        const names = platformNames();
+        const lines = ["; C64 platform names from the c64-memory-map skill, for ACME.", ...names.map((item) => `${item.name} = ${item.address < 0x100 ? formatC64Byte(item.address) : formatC64Address(item.address)}`.padEnd(24) + `; ${item.meaning}`)];
+        return { names: names.length, ...writeReported(call.string("out")!, `${lines.join("\n")}\n`, { what: "--out" }) };
+      },
+    },
+  ],
+});

package/skills/c64-provenance/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: c64-provenance
-description: Use this skill to compare two or more releases of a C64 program, for example cracked versions from different groups. It finds the bytes where the releases differ and shows which releases agree there. It can run each release and tell how the program uses each difference. It also gives evidence for each range of the program in the knowledge. The evidence is the unpack stage, the access, and the code that the entry does not reach. Use the result to separate the content of the application from changes that a release added. It also keeps a library of routines that several programs share. It finds them in the program of the knowledge and writes their names as a batch for c64-knowledge. Do not use it to analyze the code.
+description: Use this skill to compare two or more releases of a C64 program, for example cracked versions from different groups. It finds the bytes where the releases differ and shows which releases agree there. It can run each release and tell how the program uses each difference. It also gives evidence for each range of the program in the knowledge. The evidence is the unpack stage, the access, and the code that the entry does not reach. It also finds leftovers in one program: texts, assembler source, BASIC lines, fills, unused bytes, copies and dead code. It finds text of other computers, for example Apple II source. Leftovers tell about the development, the cracks and the recracks. Use the result to separate the content of the application from changes that a release added. It also keeps a library of routines that several programs share. It finds them in the program of the knowledge and writes their names as a batch for c64-knowledge. Do not use it to analyze the code.
 ---
 
 # c64-provenance
@@ -9,13 +9,15 @@ description: Use this skill to compare two or more releases of a C64 program, fo
 
 Compare releases of a C64 program. Find the bytes where they differ and which releases agree. Use this to find which bytes are probably the original application and which are changes of one release.
 
+Find the leftovers in one program. A leftover is a part of the program that the program does not need. Examples are a crack text, an old copy of a routine and a piece of assembler source.
+
 Keep a library of routines that several programs share, for example a music driver or a decruncher. Find the routines of the library in a program, and get their names for that program.
 
 This skill does not change project knowledge.
 
 ## Inputs
 
-- Two or more releases, relative to the project folder. A release is a PRG file or an `image.json` from c64-unpacker capture. Extract releases from disk images with the c64-disk skill. Unpack packed releases with the c64-unpacker skill first.
+- Two or more releases, relative to the project folder. A release is `knowledge` (the program in the knowledge), a PRG file, or an `image.json` from c64-unpacker capture with its `entry_state.json` beside it. Extract releases from disk images with the c64-disk skill. Unpack packed releases with the c64-unpacker skill first.
 - Optional: an address range to compare.
 - Optional: a shift for a release that loads at a different address.
 - Optional: a number of frames to run each release, and a steps file.
@@ -24,35 +26,47 @@ This skill does not change project knowledge.
 
 ## Tools / execution path
 
-The script compares the files locally. Only `--run` uses the host runtime: each release runs in its own emulator.
+The script compares the releases locally. Only `--frames` uses the host runtime: each release runs in its own emulator.
 
 ```
-node <skill>/scripts/provenance.ts releases/a.prg releases/b.prg releases/c.prg
-node <skill>/scripts/provenance.ts releases/a.prg releases/b.prg --shift 2:-256 --from '$0900' --to '$09ff'
-node <skill>/scripts/provenance.ts releases/a.prg .c64-re-tools/local/b/image.json --run 600 --steps .c64-re-tools/local/start-game.json
+node <skill>/scripts/provenance.ts compare releases/a.prg releases/b.prg releases/c.prg
+node <skill>/scripts/provenance.ts compare releases/a.prg releases/b.prg --shift 2:-256 --range '$0900-$09ff'
+node <skill>/scripts/provenance.ts compare knowledge .c64-re-tools/local/b/image.json --frames 600 --steps .c64-re-tools/local/start-game.json
 node <skill>/scripts/provenance.ts separate --out .c64-re-tools/local/separate.json
+node <skill>/scripts/provenance.ts leftovers --out .c64-re-tools/local/leftovers.json
 ```
 
 | Option | Meaning |
 |---|---|
 | `--shift 2:-256` | Move release 2 (the first release is 1) by -256 bytes. Use it again for more releases. |
-| `--from '$0900'` | Compare from this address. |
-| `--to '$09ff'` | Compare up to this address. |
-| `--run 600` | Run each release for this many frames, and give each listed difference its runtime evidence. |
-| `--steps steps/start-game.json` | With `--run`: the action steps of the c64-unpacker steps file to run before the frames, for example a key to start the game. |
+| `--range '$0900-$09ff'` | Compare only the addresses in this range. |
+| `--frames 600` | Run each release for this many frames, and give each listed difference its runtime evidence. |
+| `--steps .c64-re-tools/local/start-game.json` | With `--frames`: a JSON list of action steps to run before the frames, for example a key to start the game. The steps are the steps of a c64-unpacker steps file. |
 
-The script puts each PRG at its load address. An image has bytes only in its segments. The script compares the addresses where all releases have bytes. It prints one JSON object.
+The script puts each PRG at its load address. An image has bytes only in its segments. The script compares the addresses where all releases have bytes.
 
 With `--shift`, the addresses of `segments`, `common` and `differences` are the release addresses plus the `shift` of the release. The `start` and `end` of `runtime` are the addresses in the release itself, without the shift.
 
-With `--run`, a PRG starts with autostart and RUN. An image starts from its bytes: the script writes the segments and the entry state from `entry_state.json` into the emulator, and starts at the entry. Watchpoints on each difference stop the run at its first access.
+With `--frames`, a PRG starts with autostart and RUN. An image starts from its bytes: the script writes the segments and the entry state from `entry_state.json` into the emulator, and starts at the entry. Watchpoints on each difference stop the run at its first access.
+
+### Calling the script
+
+- Call a script as `node <skill>/scripts/<script>.ts <command> [subjects] [options]`. The command comes first.
+- `<script>.ts --help` lists the commands. `<script>.ts <command> --help` gives the subjects and the options of one command. The help is JSON: `{"text": "..."}`.
+- 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 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.
 
 ### Project folder
 
 - Paths are relative to the project folder. The project folder is the nearest folder at or above the working directory that holds `.c64-re-tools/`.
 - If the working directory is not in a project and has projects below it, the script refuses and lists them. Then give `--project <folder>` to each script.
 - Write each file that you make for your work in `.c64-re-tools/local/` of the project. Git ignores that folder. Examples are results, batches, step files, runs, snapshots and memory dumps.
-- Move a file out of `.c64-re-tools/local/` only when it is the evidence for a finding. Move it before you give it to `--evidence` of c64-knowledge. `--evidence` refuses a file in `.c64-re-tools/local/`.
+- Move a file out of `.c64-re-tools/local/` only when it is the evidence for a finding. Move it before you give it to `--evidence test:<file>` or `--evidence file:<file>` of c64-knowledge. These two refuse a file in `.c64-re-tools/local/`.
+- Do not move a coverage map after `coverage` of c64-knowledge imported it. `--evidence coverage:<map>` names the map by its path at the import. The knowledge keeps the coverage and the SHA-256 of the map, so the evidence stays valid.
 - Put a run that is evidence in `runs/<name>/`, with its run file, its results and the snapshot files that it uses. Change the paths in the run file to the new paths. Then git keeps them, and another person can do the run again.
 - A shell redirect (`>`) is relative to the working directory, not to the project folder. From the folder above the project, write `<folder>/.c64-re-tools/local/result.json`.
 
@@ -63,7 +77,7 @@ With `--run`, a PRG starts with autostart and RUN. An image starts from its byte
 
    `suggestedShifts` has at most 3 shifts for each release. The shift with the most `matchingSequences` is first. Data that did not move and code that moved give different shifts. Try each shift. `current: true` marks the shift of this run.
 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:
+4. To know how the program uses the differences, run the script again with `--frames` 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`. 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.
@@ -85,24 +99,66 @@ Use `separate` when you have only one release. It reads the program, its stages
 - `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 program 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. A `generated` range can have gaps of two bytes or less: these are operand bytes.
 
-Each list has `count` and `listed`. `listed` has the first ranges, at most `--max-listed`. `--out` writes all of them. Run more coverage runs for parts that are `untouched`, and add them with `coverage` of the c64-knowledge skill, before you decide.
+Each list has `count` and `listed`. `listed` has the first ranges, at most `--max-listed` (default 50). `--out` writes all of them and the result shows the file as `{out, bytes, sha256}`. Run more coverage runs for parts that are `untouched`, and add them with `coverage` of the c64-knowledge skill, before you decide.
+
+## Leftovers
+
+Use `leftovers` to find what the program holds in addition to its working code. It reads the program, its stages, the coverage and the code regions from the knowledge, as `separate` does. It gives evidence, not a decision. Each list has `count` and `listed`, as in `separate`. `--out` writes all findings.
+
+| List | What it holds |
+|---|---|
+| `text` | Text, and lines of assembler source. `encoding` is `petscii`, `screen`, `ascii` or `high-bit`. `reversed: true` marks screen codes with bit 7 set. `source: true` marks lines of assembler source. A line end in `text` is a new line. `mnemonics` counts 6502 instructions in the text. |
+| `basic` | Two or more BASIC lines away from the BASIC start. `linkedAt` is the address where BASIC linked the lines. It can be another address than the address of the bytes now. |
+| `fill` | One byte that repeats, at least 16 times, or a pattern of two to four bytes that repeats, at least 32 bytes in total. `pattern` is the repeated bytes. |
+| `residue` | Bytes that no run touched and that are no text, BASIC, fill or code region. `bytes` shows the first 16 bytes. |
+| `copies` | Bytes that are the same as earlier bytes of the program, at least 32 bytes. `copyOf` is the address of the earlier bytes. |
+| `deadCode` | Code regions of the knowledge that no call or jump reaches from the entry, and that no run executed. |
+
+Text from another computer can show the tools of the developer:
+
+- `ascii` is text in ASCII, with small letters. A cross assembler on another computer can leave it.
+- `high-bit` is text with bit 7 set. The Apple II keeps text in this form, with `$8d` at the end of a line. Apple II assembler source, for example from Merlin, has `DFB` lines and `*` comments. A C64 text in shifted letters with `$a0` spaces is also `high-bit`.
+- Data of another computer, for example a table of Atari key codes, is not text. The script does not find it. Examine `residue` and the data that no code reads, and use your knowledge of the other computers.
+
+Each finding has `stages`: the unpack stages that wrote its bytes. Each finding also has `access`: the accesses of its bytes in the coverage. A stage before the last stage is a depacker, an intro or a loader.
+
+| Option | Meaning |
+|---|---|
+| `--min-text 6` | The minimum number of characters in a text. The default is 8. A short text, for example a group name, can need 6. |
+
+Do these steps:
+
+1. Unpack the program with `stages` or `capture` of the c64-unpacker skill. Put the capture into the knowledge.
+2. Add the coverage of runs that use many parts of the program. Without coverage, `residue` is empty and no finding has `access`. `noCoverage` tells this.
+3. Run c64-static-analysis. Without code regions, `deadCode` is empty, and `residue` can include code.
+4. Run `leftovers`. When you have two or more releases, also compare them.
+5. Read `text` first: names, dates, greetings and credits. Then read `copies`, `residue`, `basic` and `deadCode`.
+6. Examine each important finding with the c64-emulator skill or the c64-static-analysis skill.
+7. Record each confirmed finding with the c64-knowledge skill. Classify a confirmed PETSCII text as a `petscii` region, and a screen code text as a `screen` region. Classify other text as `bytes`. Write a comment that tells what the leftover is.
+
+Read the findings with care:
+
+- A text is a run of bytes that looks like text. Some runs are data, for example a character map. A text can include one byte before it or after it that is not part of the text.
+- A copy is not always a leftover. A program can copy its code to another address before it runs the code.
+- A text in an early stage is often a crack intro. A text that no run read can be an old text of an earlier release.
+- Keep the fact apart from the conclusion. "Text at $4770" is a fact. "A recrack by group X" is a conclusion.
 
 ## Library of routines
 
 A library is a folder of routine files. Each file holds one routine: its bytes and its knowledge. Keep one library beside the project folders, for example `library/` at the root of the workspace. A library is not a project folder. Commit it with the projects.
 
-`--library` is relative to the working directory, as `--project`. All other paths are relative to the project folder.
+`--library` is relative to the project folder, as all other paths. For example, `../library` is the folder `library/` beside the project.
 
 ```
-node <skill>/scripts/provenance.ts routine --module '$1000' --library library --project game-a
-node <skill>/scripts/provenance.ts routine --start '$1000' --end '$1026' --name play --library library --project game-a
-node <skill>/scripts/provenance.ts match --library library --out .c64-re-tools/local/match.json --project game-b
+node <skill>/scripts/provenance.ts routine '$1000' --library ../library --project game-a
+node <skill>/scripts/provenance.ts routine '$1000-$1026' --name play --library ../library --project game-a
+node <skill>/scripts/provenance.ts match --library ../library --out .c64-re-tools/local/match.json --project game-b
 ```
 
 To save a routine:
 
 1. Put the program into the knowledge, and name the routine there first. The file keeps the user and LLM names, comments, regions, references and operand expressions in the range. It also keeps the code regions of each origin.
-2. Run `routine` with the start of a module (`--module`), or with `--start` and `--end`. A module ends at the next module or at the end of its segment.
+2. Run `routine` with the start address of a module, or with a range `<start>-<end>`. A module ends at the next module or at the end of its segment.
    - `--name` is the name of the routine and of its file. When you do not give it, the script uses the user or LLM name at the start.
    - `--title` is the title of the routine. When you do not give it, the script uses the module title.
    - A routine has at least 16 bytes. Its last instruction must end in the range.
@@ -114,7 +170,7 @@ To find the routines in a program:
    - The opcodes and the other bytes must be equal.
    - An address into the routine must point into the routine at its new address. `shift` is the address in the program minus the address in the library.
    - An operand that addresses something outside the routine can be different. `differing` lists each one with its value in the library and in the program. Examine them. For example, the program can use other variables or another SID voice.
-2. Give `--out` to get a batch for `knowledge.ts apply`. The batch has the names, regions, comments, references and operand expressions of each routine at its addresses in the program. `match` does not change the knowledge.
+2. Give `--out` to get a batch for `knowledge.ts apply`. `batch` shows the file as `{out, bytes, sha256}`. The batch has the names, regions, comments, references and operand expressions of each routine at its addresses in the program. `match` does not change the knowledge.
 3. Read `batch.leftOut` before you apply the batch. The script leaves out a write in these conditions:
    - The program has a user or LLM row at that place.
    - The program uses the name at another address.
@@ -128,17 +184,17 @@ To find the routines in a program:
 Automatic write:
 - none.
 
-Record a confirmed conclusion as a normal comment, region or symbol with the c64-knowledge skill. Do not record the full comparison.
+Record a confirmed conclusion as a normal comment, region or symbol with the c64-knowledge skill. Do not record the full comparison or the full list of leftovers.
 
 `match --out` writes a batch file and does not change the knowledge. Apply the batch with the c64-knowledge skill.
 
 ## Result
 
-The differing ranges with the bytes of each release and the groups that agree, and the share of identical bytes. `common` gives the ranges where all releases have bytes. `releases` gives the segments and the `shift` of each release. With `--run`, each difference also has `runtime`, and `run` tells if each release started, or why not.
+The differing ranges with the bytes of each release and the groups that agree, and the share of identical bytes. `common` gives the ranges where all releases have bytes. `releases` gives the segments and the `shift` of each release. With `--frames`, each difference also has `runtime`, and `run` tells if each release started, or why not.
 
-The runtime evidence is evidence only. The script does not decide which bytes are original.
+For `leftovers`: the lists of findings, with `entry` and the number of `stages`. `noEntry`, `noStages` and `noCoverage` tell which knowledge is missing.
 
-The exit status is 0 for a result. The exit status is 1 for an error. The exit status is 2 for a wrong argument.
+The runtime evidence and the leftovers are evidence only. The script does not decide which bytes are original.
 
 ## Failure and conflicts
 
@@ -147,7 +203,7 @@ The exit status is 0 for a result. The exit status is 1 for an error. The exit s
 - `common` is empty: the releases do not cover the same addresses. Use `--shift`, or compare a range that all releases cover.
 - `run.releases` shows `started: false`: a PRG without a BASIC start, or an image without `entry_state.json`. The reason tells which. The other releases still give evidence.
 - `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 emulator script.
-- `moreDifferences: true`: the script shows only the first differences. Use `--from` and `--to` to see the others.
+- `moreDifferences: true`: the script shows only the first differences. Use `--range` to see the others.
 - `not-found`: the project has no file at that path.
 - `not-found` from `match`: the library folder does not exist, or it has no routine files. Save a routine with `routine` first.
 - `conflict` from `routine`: the library has a routine with that name. Give another `--name`, or give `--replace` to save over it.

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

@@ -5,15 +5,12 @@
 // releases differ and which releases agree there. It never decides which
 // bytes are original: that needs evidence beyond one comparison.
 
-export interface Range {
-  start: number;
-  end: number;
-}
+import { type AddressRange, formatC64Address } from "#src/c64.ts";
 
 export interface Release {
   name: string;
   /** Where the release has bytes, after the shift, in address order. */
-  segments: Range[];
+  segments: AddressRange[];
   /** The byte at an address inside a segment. */
   byteAt: (address: number) => number;
 }
@@ -29,7 +26,7 @@ export interface DifferingRange {
 
 export interface Comparison {
   /** The addresses where every release has bytes. */
-  common: Range[];
+  common: AddressRange[];
   identicalBytes: number;
   differingBytes: number;
   differences: DifferingRange[];
@@ -43,8 +40,8 @@ const JOIN_GAP = 4;
 export const covers = (release: Release, address: number) => release.segments.some((segment) => address >= segment.start && address <= segment.end);
 
 /** The ranges where every release has bytes, inside from..to. */
-export function commonRanges(releases: Release[], from = 0x0000, to = 0xffff): Range[] {
-  const ranges: Range[] = [];
+export function commonRanges(releases: Release[], from = 0x0000, to = 0xffff): AddressRange[] {
+  const ranges: AddressRange[] = [];
   for (let address = from; address <= to; address++) {
     if (!releases.every((release) => covers(release, address))) continue;
     const last = ranges.at(-1);
@@ -67,7 +64,7 @@ export function compareReleases(releases: Release[], options: { from?: number; t
   }
   // A joined range stays inside one common range, so every release has all of its bytes.
   const inSameCommon = (a: number, b: number) => common.some((range) => a >= range.start && b <= range.end);
-  const ranges: Range[] = [];
+  const ranges: AddressRange[] = [];
   for (const address of differing) {
     const last = ranges.at(-1);
     if (last !== undefined && address - last.end <= JOIN_GAP && inSameCommon(last.start, address)) last.end = address;
@@ -137,9 +134,8 @@ export type ShiftSuggestion = { release: number; shift: number; matchingSequence
  */
 export function shiftSuggestion(releases: Release[], applied: number[], index: number, found: { shift: number; matches: number }): ShiftSuggestion {
   const outside = (release: Release, by: number) => release.segments.find((segment) => segment.start + by < 0 || segment.end + by > 0xffff);
-  const hex = (value: number) => `$${value.toString(16).padStart(4, "0")}`;
-  const why = (number: number, by: number, segment: Range) =>
-    `release ${number} moved by ${by} puts ${hex(segment.start)}-${hex(segment.end)} ${segment.start + by < 0 ? "below $0000" : "past $ffff"}`;
+  const why = (number: number, by: number, segment: AddressRange) =>
+    `release ${number} moved by ${by} puts ${formatC64Address(segment.start)}-${formatC64Address(segment.end)} ${segment.start + by < 0 ? "below $0000" : "past $ffff"}`;
   const own = outside(releases[index]!, found.shift);
   if (own === undefined) return { release: index + 1, shift: applied[index]! + found.shift, matchingSequences: found.matches };
   const reasons = [why(index + 1, found.shift, own)];