@henols/c64-re-tools 2.0.0-rc.9 → 2.0.0

package/skills/c64-testing/scripts/run.ts

@@ -1,4 +1,4 @@
-// The c64-testing run script (D45): runs steps in its own emulator, from a
+// The c64-testing run script: runs steps in its own emulator, from a
 // program or a snapshot file, and writes what the steps ask for into a
 // directory: screens, coverage maps, snapshot files, and results.json with
 // the observations. One side, no comparison. Exit status: 0 when every step
@@ -6,20 +6,20 @@
 
 import { parseArgs } from "node:util";
 
-import { formatC64Address, parseC64Address } from "#src/c64.ts";
+import { formatC64Address, formatSprite, formatVicii, parseC64Address } from "#src/c64.ts";
 import { runProgram } from "#src/host-client/autostart.ts";
 import { readCoverage } from "#src/host-client/coverage.ts";
 import { ACTION_STEP_KEYS, ACTION_STEP_KINDS, checkActionStep, isInteger, isObject, runActionStep, type ActionStep } from "#src/host-client/steps.ts";
-import { MAX_MEMORY_READ, WireFailure } from "#src/host-client/tools.ts";
+import { MAX_MEMORY_READ, MAX_TRACE_FRAMES, MAX_TRACE_HITS, MAX_TRACE_POINTS, TRACE_KINDS, WireFailure, type TraceHit, type TraceKind } from "#src/host-client/tools.ts";
 import { readProjectFile, writeProjectFile } from "#src/host-client/transfer.ts";
-import { ViceSessionClient } from "#src/host-client/vice-session.ts";
+import { readMemoryInParts, ViceSessionClient } from "#src/host-client/vice-session.ts";
 import { resolveProjectPath } from "#src/project.ts";
 import { runScript, UsageError } from "#src/script.ts";
-import { loadSymbols } from "./scenario.ts";
+import { loadSymbols } from "./lib/scenario.ts";
 
 const USAGE = `run.ts <run.json> --out <dir>
 
-<run.json> is a run file relative to the project directory: where to start,
+<run.json> is a run file relative to the project folder: where to start,
 optional symbols, and the steps. See references/scenario-format.md, section
 Runs. The files that the steps write, and results.json, go into <dir>. The
 result is one JSON object.`;
@@ -30,7 +30,8 @@ type RunStep =
   | { save: string }
   | { screen: string }
   | { coverage: string }
-  | { observe: string; memory?: Array<string | { at: string; size?: number }>; registers?: boolean; vicii?: boolean; sprites?: number[] };
+  | { trace: string; points: Array<{ kind: TraceKind; at: string; end?: string }>; frames: number; maxHits?: number }
+  | { observe: string; memory?: "all" | Array<string | { at: string; size?: number; view?: "cpu" | "ram" }>; registers?: boolean; vicii?: boolean; sprites?: number[] };
 
 interface Run {
   name: string;
@@ -40,7 +41,8 @@ interface Run {
   steps: RunStep[];
 }
 
-const OWN_KINDS = ["snapshot", "save", "screen", "coverage", "observe"] as const;
+const OWN_KINDS = ["snapshot", "save", "screen", "coverage", "observe", "trace"] as const;
+const TRACE_KEYS = ["trace", "points", "frames", "maxHits"];
 const OBSERVE_KEYS = ["observe", "memory", "registers", "vicii", "sprites"];
 /** A name of a file that a step writes: letters, digits, dots, underscores or hyphens. */
 const NAME = /^[A-Za-z0-9._-]{1,64}$/;
@@ -68,10 +70,10 @@ function readRun(path: string): Run {
   (value.steps as unknown[]).forEach((step, index) => {
     const at = `step ${index + 1}`;
     if (!isObject(step)) return fail(`${at} must be an object`);
-    const kinds = "observe" in step ? ["observe"] : Object.keys(step).filter((key) => (ACTION_STEP_KINDS as readonly string[]).includes(key) || (OWN_KINDS as readonly string[]).includes(key));
+    const kinds = "observe" in step ? ["observe"] : "trace" in step ? ["trace"] : Object.keys(step).filter((key) => (ACTION_STEP_KINDS as readonly string[]).includes(key) || (OWN_KINDS as readonly string[]).includes(key));
     if (kinds.length !== 1) return fail(`${at} must have exactly one of ${[...ACTION_STEP_KINDS, ...OWN_KINDS].join(", ")}`);
     const kind = kinds[0]!;
-    const allowed = kind === "observe" ? OBSERVE_KEYS : (ACTION_STEP_KEYS[kind] ?? [kind]);
+    const allowed = kind === "observe" ? OBSERVE_KEYS : kind === "trace" ? TRACE_KEYS : (ACTION_STEP_KEYS[kind] ?? [kind]);
     for (const key of Object.keys(step)) if (!allowed.includes(key)) fail(`${at} has the key ${key}, which a ${kind} step does not have`);
     if ((ACTION_STEP_KINDS as readonly string[]).includes(kind)) return checkActionStep(kind, step, at, fail);
     const name = step[kind];
@@ -80,11 +82,32 @@ function readRun(path: string): Run {
       return;
     }
     if (typeof name !== "string" || !NAME.test(name)) fail(`${at}: ${kind} needs a name of 1 to 64 letters, digits, dots, underscores or hyphens`);
+    if (kind === "trace") {
+      if (labels.has(name as string)) fail(`${at} needs a new name`);
+      labels.add(name as string);
+      const points = step.points;
+      if (!Array.isArray(points) || points.length === 0 || points.length > MAX_TRACE_POINTS) return fail(`${at}: points is a list of 1 to ${MAX_TRACE_POINTS} objects with kind and at`);
+      for (const point of points as unknown[]) {
+        if (!isObject(point) || Object.keys(point).some((key) => !["kind", "at", "end"].includes(key))) return fail(`${at}: a point has kind, at and end, and nothing else`);
+        if (!(TRACE_KINDS as readonly unknown[]).includes(point.kind)) fail(`${at}: a point kind is exec, read or write`);
+        if (typeof point.at !== "string" || (point.end !== undefined && typeof point.end !== "string")) fail(`${at}: a point needs at, and end when it is a range, as names or $ addresses`);
+      }
+      if (!isInteger(step.frames, 1, MAX_TRACE_FRAMES)) fail(`${at}: frames must be a number from 1 to ${MAX_TRACE_FRAMES}`);
+      if (step.maxHits !== undefined && !isInteger(step.maxHits, 1, MAX_TRACE_HITS)) fail(`${at}: maxHits must be a number from 1 to ${MAX_TRACE_HITS}`);
+      return;
+    }
     if (kind !== "observe") return;
     if (labels.has(name as string)) fail(`${at} needs a new observation name`);
     labels.add(name as string);
-    if (step.memory !== undefined && (!Array.isArray(step.memory) || step.memory.some((item) => typeof item !== "string" && !(isObject(item) && typeof item.at === "string" && (item.size === undefined || isInteger(item.size, 1, MAX_MEMORY_READ)))))) {
-      fail(`${at}: memory is a list of names, $ addresses, or objects with at and size`);
+    const memoryItem = (item: unknown) =>
+      typeof item === "string" ||
+      (isObject(item) &&
+        typeof item.at === "string" &&
+        Object.keys(item).every((key) => ["at", "size", "view"].includes(key)) &&
+        (item.size === undefined || isInteger(item.size, 1, 0x10000)) &&
+        (item.view === undefined || item.view === "cpu" || item.view === "ram"));
+    if (step.memory !== undefined && step.memory !== "all" && (!Array.isArray(step.memory) || !step.memory.every(memoryItem))) {
+      fail(`${at}: memory is "all", or a list of names, $ addresses, or objects with at, size (1 to 65536) and view (cpu or ram)`);
     }
     if (step.registers !== undefined && typeof step.registers !== "boolean") fail(`${at}: registers must be true or false`);
     if (step.vicii !== undefined && typeof step.vicii !== "boolean") fail(`${at}: vicii must be true or false`);
@@ -93,6 +116,11 @@ function readRun(path: string): Run {
   return value as unknown as Run;
 }
 
+/** A trace hit with $ addresses, as a person reads it. */
+function showHit(hit: TraceHit) {
+  return { ...hit, pc: formatC64Address(hit.pc), ...(hit.address === undefined ? {} : { address: formatC64Address(hit.address) }) };
+}
+
 async function runFile(path: string, out: string): Promise<{ output: Record<string, unknown>; failed: boolean }> {
   const run = readRun(path);
   const symbols = loadSymbols({ program: "", symbols: run.symbols ?? "none" });
@@ -108,6 +136,7 @@ async function runFile(path: string, out: string): Promise<{ output: Record<stri
     files.push(name);
   };
   const observations: Record<string, unknown> = {};
+  const traces: Record<string, unknown> = {};
   const client = await ViceSessionClient.open({ videoStandard: run.videoStandard ?? "pal" });
   let done = 0;
   let reason: string | undefined;
@@ -135,13 +164,36 @@ async function runFile(path: string, out: string): Promise<{ output: Record<stri
       } else if ("coverage" in step) {
         write(`${step.coverage}.bin`, await readCoverage(client));
         await client.memmap({ action: "clear" });
+      } else if ("trace" in step) {
+        // A trace: every hit of the points while the program runs on, to <name>.json.
+        const points = step.points.map((point) => ({ kind: point.kind, start: at(point.at), end: at(point.end ?? point.at) }));
+        if (points.some((point) => point.end < point.start)) throw new UsageError(`the trace ${step.trace} has a point whose end is before its start`);
+        const traced = await client.trace({ points, frames: step.frames, maxHits: step.maxHits ?? MAX_TRACE_HITS });
+        write(`${step.trace}.json`, Buffer.from(`${JSON.stringify({ points: step.points, frames: traced.frames, end: traced.end, hits: traced.hits.map(showHit) }, null, 1)}\n`));
+        traces[step.trace] = { file: `${step.trace}.json`, hits: traced.hits.length, frames: traced.frames, end: traced.end };
+        if (traced.end !== "frames" && traced.end !== "hits") {
+          reason = `The trace ${step.trace} ended at a ${traced.end} at ${formatC64Address(traced.pc)}.`;
+          break;
+        }
       } else if ("observe" in step) {
         const seen: Record<string, unknown> = {};
-        if (step.memory !== undefined) {
-          const memory: Record<string, string> = {};
+        if (step.memory === "all") {
+          // All 64 KiB of RAM, also under the ROMs and the I/O area, as one file.
+          write(`${step.observe}.bin`, await readMemoryInParts(client, 0x0000, 0x10000, "ram"));
+          seen.memory = { file: `${step.observe}.bin` };
+        } else if (step.memory !== undefined) {
+          const memory: Record<string, string | { file: string }> = {};
           for (const item of step.memory) {
             const spec = typeof item === "string" ? { at: item } : item;
-            memory[spec.at] = (await client.memoryRead({ address: at(spec.at), size: spec.size ?? 1, space: "c64", view: "cpu" })).data;
+            const size = spec.size ?? 1;
+            const bytes = await readMemoryInParts(client, at(spec.at), size, spec.view ?? "cpu");
+            // More than one read gives goes to a file: results.json stays small.
+            if (size <= MAX_MEMORY_READ) memory[spec.at] = bytes.toString("hex");
+            else {
+              const file = `${step.observe}-${spec.at.replace(/^\$/, "")}.bin`;
+              write(file, bytes);
+              memory[spec.at] = { file };
+            }
           }
           seen.memory = memory;
         }
@@ -149,8 +201,8 @@ async function runFile(path: string, out: string): Promise<{ output: Record<stri
           const registers = await client.registersGet("c64");
           seen.registers = { ...registers, pc: formatC64Address(registers.pc) };
         }
-        if (step.vicii === true) seen.vicii = await client.vicii();
-        if (step.sprites !== undefined) seen.sprites = (await client.sprites(step.sprites)).sprites;
+        if (step.vicii === true) seen.vicii = formatVicii(await client.vicii());
+        if (step.sprites !== undefined) seen.sprites = (await client.sprites(step.sprites)).sprites.map(formatSprite);
         observations[step.observe] = seen;
       } else {
         const notReached = await runActionStep(client, step, at);
@@ -162,7 +214,7 @@ async function runFile(path: string, out: string): Promise<{ output: Record<stri
       done++;
     }
     const pc = (await client.registersGet("c64")).pc;
-    const results = { name: run.name, completed: reason === undefined, steps: run.steps.length, done, ...(reason === undefined ? {} : { reason }), pc: formatC64Address(pc), files: [...files], observations };
+    const results = { name: run.name, completed: reason === undefined, steps: run.steps.length, done, ...(reason === undefined ? {} : { reason }), pc: formatC64Address(pc), files: [...files], observations, ...(Object.keys(traces).length === 0 ? {} : { traces }) };
     write("results.json", Buffer.from(`${JSON.stringify(results, null, 2)}\n`));
     return { output: { ...results, files, observations: Object.keys(observations), out }, failed: reason !== undefined };
   } finally {
@@ -171,15 +223,15 @@ async function runFile(path: string, out: string): Promise<{ output: Record<stri
 }
 
 await runScript(
-  async () => {
-    const { values, positionals } = parseArgs({ args: process.argv.slice(2), strict: true, allowPositionals: true, options: { out: { type: "string" }, help: { type: "boolean" } } });
+  async (argv) => {
+    const { values, positionals } = parseArgs({ args: argv, strict: true, allowPositionals: true, options: { out: { type: "string" }, help: { type: "boolean" } } });
     if (values.help) throw new UsageError("");
     if (positionals.length !== 1) throw new UsageError("give one run file");
     if (values.out === undefined) throw new UsageError("run needs --out <dir>");
     try {
       resolveProjectPath(values.out);
     } catch {
-      throw new UsageError(`--out must be a path relative to the project directory that stays inside it, not ${values.out}`);
+      throw new UsageError(`--out must be a path relative to the project folder that stays inside it, not ${values.out}`);
     }
     const { output, failed } = await runFile(positionals[0]!, values.out);
     if (failed) process.exitCode = 1;

package/skills/c64-testing/scripts/test.ts

@@ -8,11 +8,11 @@ import { ViceSessionClient } from "#src/host-client/vice-session.ts";
 import { WireFailure } from "#src/host-client/tools.ts";
 import { resolveProjectPath } from "#src/project.ts";
 import { runScript, UsageError } from "#src/script.ts";
-import { readScenario, runScenario, ScenarioError, type ScenarioResult } from "./scenario.ts";
+import { readScenario, runScenario, ScenarioError, type ScenarioResult } from "./lib/scenario.ts";
 
 const USAGE = `test.ts <scenario.json> [--out <dir>]
 
-<scenario.json> is a scenario file relative to the project directory. See
+<scenario.json> is a scenario file relative to the project folder. See
 references/scenario-format.md. With --out, a FAIL writes both screens, the
 difference image and memory.json with each differing byte into <dir>. The
 result is one JSON object.`;
@@ -27,7 +27,7 @@ async function run(argv: string[]): Promise<ScenarioResult> {
     try {
       resolveProjectPath(values.out);
     } catch {
-      throw new UsageError(`--out must be a path relative to the project directory that stays inside it, not ${values.out}`);
+      throw new UsageError(`--out must be a path relative to the project folder that stays inside it, not ${values.out}`);
     }
   }
   try {
@@ -56,8 +56,8 @@ async function runScenarioFile(path: string, out: string | undefined): Promise<S
 }
 
 await runScript(
-  async () => {
-    const result = await run(process.argv.slice(2));
+  async (argv) => {
+    const result = await run(argv);
     process.exitCode = EXIT[result.result];
     return result;
   },

package/skills/c64-unpacker/SKILL.md

@@ -13,7 +13,7 @@ This skill does not change project knowledge.
 
 ## Inputs
 
-- The program: a PRG file, relative to the project directory.
+- The program: a PRG file, relative to the project folder.
 - For a capture: the address where the unpacked program starts, and the directory for the result.
 
 ## Tools / execution path
@@ -21,9 +21,9 @@ This skill does not change project knowledge.
 ```
 node <skill>/scripts/unpack.ts inspect original/game.prg
 node <skill>/scripts/unpack.ts trace original/game.prg
-node <skill>/scripts/unpack.ts capture original/game.prg --until '$c000' --out unpacked
-node <skill>/scripts/unpack.ts stages original/game.prg --steps input.json
-node <skill>/scripts/unpack.ts loads original/game.d64 --steps parts.json --out parts --drive
+node <skill>/scripts/unpack.ts capture original/game.prg --until '$c000' --out .c64-re-tools/local/capture
+node <skill>/scripts/unpack.ts stages original/game.prg --steps .c64-re-tools/local/input.json
+node <skill>/scripts/unpack.ts loads original/game.d64 --steps .c64-re-tools/local/parts.json --out .c64-re-tools/local/parts --drive
 ```
 
 `inspect` examines the file locally. `trace` and `capture` start their own emulator through the host runtime and start the program. `trace` runs the program and finds the memory that the program wrote and then executed. `capture` stops the program when the CPU gets to the `--until` address. `stages` runs the program and finds each stage: a decruncher, an intro, a copier, and then the program. For each stage it gives the entry, the frames, the written memory (`wrote`) and the entry of the next stage (`next`). In `stages` and `capture`, a `frames` step and a `runUntil` step with only `at` count as run time. `stages` refuses a `runUntil` step with `raster` or `memory`.
@@ -31,8 +31,9 @@ node <skill>/scripts/unpack.ts loads original/game.d64 --steps parts.json --out
 | Option | Meaning |
 |---|---|
 | `--until '$c000'` | The address where the unpacked program starts. The capture stops there after the steps. To capture a later arrival at the address, add a `runUntil` step to an address after the first arrival. |
-| `--out unpacked/game.prg` | Where to write the result, relative to the project directory. |
+| `--out .c64-re-tools/local/capture` | Where to write the result, relative to the project folder. |
 | `--range '$c000' '$cfff'` | Write this range as a PRG. Without it, the script writes all 64 KiB of RAM as a flat file. |
+| `--exclude '$a000-$a9ff'` | `capture` only: remove this range from the segments. You can give it more than once. `image.json` lists the ranges in `excluded`. The entry must not be in the range. |
 | `--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`, `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. |
@@ -49,8 +50,19 @@ A steps file has the steps `write`, `registers`, `joystick`, `type`, `frames` an
 [{ "frames": 50 }, { "type": " " }]
 ```
 
+A `frames` step runs 1 to 30000 frames. A `runUntil` step has `timeoutFrames` from 1 to 30000.
+
 A `type` step puts keys in the keyboard queue of the KERNAL. A program that reads the keyboard hardware does not see them. A step cannot press one specific key of the keyboard matrix. A wait for any key that reads all keyboard columns can end without a key.
 
+### 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/`.
+- 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`.
+
 ## Workflow
 
 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:
@@ -59,7 +71,7 @@ A `type` step puts keys in the keyboard queue of the KERNAL. A program that read
    - `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.
 
    Also read the evidence that the script finds in the file. The script never names a packer from it:
-   - `basicText`: the BASIC lines as text. A packer or a crack often puts its name there.
+   - `basicText`: raw evidence from the BASIC lines, not a listing. A byte that is not a printable character shows as `{$xx}`. A packer or a crack often puts its name there. For a listing, use the c64-basic skill.
    - `strings`: readable text near the start of the code.
    - `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.
@@ -72,13 +84,14 @@ A `type` step puts keys in the keyboard queue of the KERNAL. A program that read
    - Or use `runningRange.start` from `trace`, or `suggestedUntil`. The CPU gets to `suggestedUntil` after the unpacking.
    - Or use the c64-emulator skill: set a breakpoint after the unpack loop, or look at the last JMP of the unpacker.
    - Disassemble the code at the address with the c64-emulator skill. Make sure that it is the start of the program. The start of a program often sets the stack pointer, the interrupts and the vectors.
+   - A program can be relocated and not packed. Then a short copier moves the code and jumps to it. The moved code is the last stage. Make sure that the `entry` of the last stage is not code that the program writes later. An example is a routine that the program makes at run time. Disassemble the entry to make sure.
 4. Run `capture` with that address and a directory in `--out`. Give the same `--steps` as before. The directory gets:
    - `image.bin`: all 64 KiB of RAM at the entry.
    - `image.json`: the entry, the segments, the vectors and the stages. A segment is a block that a stage wrote. A block is not a segment when it holds the entry of a later stage before the program, and no stage wrote over that entry. The block with the capture entry is always a segment. Segments do not overlap. `writtenBy` tells the last stage that wrote into the segment.
    - One PRG for each segment.
    - `entry_state.json`: the registers, `$00` and `$01`, pages 0 to 3, the VIC, SID and CIA registers, and the vectors. `cia` gives the CIA timer latches and interrupt masks. `differsFromReset` lists the bytes that are not as a clean C64 has them at READY. A rebuild must make these bytes the same, because the program can read them.
-5. Make sure that the result is the application: the code at the entry must not be the unpacker again. A segment can be data that a loader left, for example intro graphics. Keep it until other evidence shows that the program does not use it.
-6. Give `image.bin` to the c64-static-analysis skill with its `--flat64k` option, or give it the segment PRGs.
+5. Make sure that the result is the application: the code at the entry must not be the unpacker again. A segment can be data that a loader left, for example intro graphics. Keep it until other evidence shows that the program does not use it. Then capture again with `--exclude` for that range. Thus the source and the loader do not include the range.
+6. Put the capture into the knowledge with `image <out>/image.json` of the c64-knowledge skill. The knowledge keeps the segments, the entry, the entry state and the stages. The other skills read them there. The files in `<out>` are not necessary after that.
 7. Use `--range` only when you know the area of the program. Then the capture writes that one segment.
 
 ## Multi-load programs
@@ -99,7 +112,8 @@ A multi-load program loads more parts from the disk while it runs, for example o
 
 2. Run `loads` with the steps file and a directory in `--out`. Add `--drive` when the program has its own drive code, for example a fast loader.
 3. Each capture writes `<out>/<name>/` with `image.bin`, `image.json`, `entry_state.json` and a PRG for each segment. A segment is a block of RAM from `$0400` that the program changed after the capture before. The first capture also has the program itself.
-4. With `--drive`, `drive8.prg` is the drive RAM at `$0000`-`$07ff`. Analyze it with c64-static-analysis and `--space drive8`, and record its knowledge in space `drive8`.
+4. Put the part that you work on into the knowledge with `image <out>/<name>/image.json` of the c64-knowledge skill.
+5. With `--drive`, `drive8.prg` is the drive RAM at `$0000`-`$07ff`. Put it into the knowledge with `image <out>/<name>/drive8.prg --space drive8`. Then analyze it with c64-static-analysis and `--space drive8`.
 
 VICE records no memory access map for the drive CPU. Thus no tool gives coverage of drive code.
 

package/skills/c64-unpacker/scripts/{evidence.ts → lib/evidence.ts}

@@ -45,7 +45,7 @@ export interface PackingEvidence {
   /** The first SYS line and its address (null when the argument needs run-time values, with the argument), or null when the program has no SYS. */
   basicStart: { line: number; sys: string | null; expression?: string } | null;
   entropy: { blocks: number; highBlocks: number; median: number | null };
-  /** The BASIC lines as text: a packer or a crack often puts its banner there (D43). */
+  /** The BASIC lines as text: a packer or a crack often puts its banner there. */
   basicText: string[];
   /** Runs of readable PETSCII near the start of the code, raw. */
   strings: string[];

package/skills/c64-unpacker/scripts/{loads.ts → lib/loads.ts}

@@ -1,4 +1,4 @@
-// The loads command of c64-unpacker (D53): one capture for each part of a
+// The loads command of c64-unpacker: one capture for each part of a
 // multi-load program. The steps file has action steps and capture steps; a
 // capture writes what the C64 side changed since the previous capture as an
 // image with its entry state, and with --drive the drive RAM as a PRG for
@@ -66,7 +66,7 @@ export function readLoadSteps(path: string): LoadStep[] {
  * Ranges from $0400 that the CPU wrote since the last capture, joined across
  * gaps of up to `join` bytes, each with at least one changed byte. With
  * `writesKnown`, every written byte counts, also one written with the value
- * that was there (zeros over the zeros of VICE's start pattern, F-20).
+ * that was there (zeros over the zeros of VICE's start pattern).
  * Without it, the KERNAL RAM test wrote all of RAM after the map was cleared,
  * and only the changed bytes count.
  */
@@ -102,7 +102,7 @@ export async function loads(program: string, options: { out: string; steps: Load
     let loadedProgram: Buffer | undefined;
     /** False while the map holds the writes of the KERNAL RAM test. */
     let writesKnown = true;
-    /** A known flaw of the host's VICE version that a tape load meets (D56). */
+    /** A known flaw of the host's VICE version that a tape load meets. */
     let emulatorFlaw: string | undefined;
     if (program.toLowerCase().endsWith(".prg")) {
       const { bytes } = readProjectFile(program);
@@ -113,7 +113,7 @@ export async function loads(program: string, options: { out: string; steps: Load
       previous.fill(0, load, Math.min(0x10000, load + bytes.length - 2));
       loadedProgram = bytes;
       await client.memmap({ action: "clear" });
-      // RUN as c64-testing types it: the steps start at the same time as a scenario's (D62).
+      // RUN as c64-testing types it: the steps start at the same time as a scenario's.
       if (!(await typeRun(client))) return { output: { loaded: false, reason: `After RUN, BASIC ran no program line in ${RUN_LIMIT_FRAMES} frames.` }, failed: true };
     } else {
       // A disk, tape or cartridge: VICE loads and starts it. The RAM test of the KERNAL puts back what it writes.

package/skills/c64-unpacker/scripts/{machine.ts → lib/machine.ts}

@@ -1,4 +1,4 @@
-// The machine state that a capture writes (D43): RAM, the CPU port, pages
+// The machine state that a capture writes: RAM, the CPU port, pages
 // 0-3, the chip registers read without side effects, and the vectors. The
 // capture and loads commands of the unpacker share it.
 
@@ -9,12 +9,12 @@ type Registers = Awaited<ReturnType<ViceSessionClient["registersGet"]>>;
 
 const MAX_READ = 4096;
 
-/** The I/O areas of the entry state, read without side effects (D43). */
+/** The I/O areas of the entry state, read without side effects. */
 export const IO_AREAS = { vic: [0xd000, 0x2f], sid: [0xd400, 0x1d], cia1: [0xdc00, 0x10], cia2: [0xdd00, 0x10] } as const;
 /** Frames from a hard reset to the READY prompt, with margin. */
 export const READY_FRAMES = 200;
 
-/** What no register read of a CIA gives (D63). */
+/** What no register read of a CIA gives. */
 export interface CiaHidden {
   latchA: number;
   latchB: number;
@@ -70,7 +70,7 @@ export function entryState(registers: Registers, state: MachineState, vectors: R
     cpuPort: { $00: state.port[0], $01: state.port[1] },
     pages: Object.fromEntries([0, 1, 2, 3].map((page) => [formatC64Address(page << 8), state.pages.subarray(page << 8, (page + 1) << 8).toString("hex")])),
     io: Object.fromEntries(Object.entries(IO_AREAS).map(([name, [address]]) => [name, { from: formatC64Address(address), bytes: state.io[name as keyof typeof IO_AREAS].toString("hex") }])),
-    // The CIA latches and interrupt masks: write-only on the chip, so the I/O bytes do not hold them (D63).
+    // The CIA latches and interrupt masks: write-only on the chip, so the I/O bytes do not hold them.
     cia: state.cia,
     vectors,
     ...(differsFromReset === undefined ? {} : { differsFromReset }),

package/skills/c64-unpacker/scripts/{stages.ts → lib/stages.ts}

@@ -1,11 +1,11 @@
-// The stage rule of the c64-unpacker script (D43, F-17). The memory map keeps
+// The stage rule of the c64-unpacker script. The memory map keeps
 // no order: a written and executed byte can be code that ran first and was
 // written over later, as a decruncher does to its own start code. So a stage
 // starts only where the CPU executes an opcode byte that the current stage
 // wrote before the CPU got there. Code that the stage executed before it wrote
 // it is the stage's own code: it stops the run once, and then a write watch
 // over it arms it again. Written code that the stage calls, and that returns
-// to the stage, is the stage's own code too (D59): a packer hands off by JMP,
+// to the stage, is the stage's own code too: a packer hands off by JMP,
 // RTS or RTI and never runs its own code again.
 
 import { COVERAGE } from "#src/c64.ts";
@@ -71,7 +71,7 @@ export function inRanges(ranges: readonly Range[], address: number): boolean {
 }
 
 /**
- * Where a call returns to the stage (D59): the return address on top of the
+ * Where a call returns to the stage: the return address on top of the
  * stack, when a JSR that the stage executed pushed it. `stack` is page 1.
  * Returns the address of the instruction after that JSR.
  */
@@ -100,10 +100,10 @@ export function executedIn(map: Uint8Array, block: Range): Range[] {
 
 /**
  * The segments of a capture: the blocks that the stages wrote, without loader
- * leftovers, joined into ranges that do not overlap or touch (F-26). A block
+ * leftovers, joined into ranges that do not overlap or touch. A block
  * is a leftover when it holds the entry of an intermediate stage that started
  * after the block's writer, and no write from that stage on replaced the code
- * at that entry (R2-01). Code that a stage ran before a later stage wrote over
+ * at that entry. Code that a stage ran before a later stage wrote over
  * it never drops a block, and the block that holds the capture entry is always
  * a segment. The filter comes before the join: a join first would drop the
  * program with a leftover. `writtenBy` is the last stage that wrote into the
@@ -128,3 +128,15 @@ export function captureSegments(stages: ReadonlyArray<{ entry: number; wrote: re
   }
   return segments;
 }
+
+/** The segments without the bytes of `holes`: a segment that a hole cuts gives its parts, each with the fields of the segment. */
+export function withoutRanges<T extends Range>(segments: readonly T[], holes: readonly Range[]): T[] {
+  let pieces = [...segments];
+  for (const hole of holes) {
+    pieces = pieces.flatMap((piece) => {
+      if (hole.end < piece.start || hole.start > piece.end) return [piece];
+      return [...(hole.start > piece.start ? [{ ...piece, end: hole.start - 1 }] : []), ...(hole.end < piece.end ? [{ ...piece, start: hole.end + 1 }] : [])];
+    });
+  }
+  return pieces;
+}