@henols/c64-re-tools 2.1.0-rc.1 → 2.1.0

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

@@ -6,69 +6,20 @@
 // writes the memory into the project. "loads" captures each part of a
 // multi-load program. No native unpack tool is used.
 
-import { parseArgs } from "node:util";
-
-import { COVERAGE, EXECUTE, formatC64Address, parseC64Address, READ, WRITE } from "#src/c64.ts";
+import { type AddressRange, COVERAGE, EXECUTE, formatC64Address, READ, WRITE } from "#src/c64.ts";
 import { autostartLoaded, LOAD_LIMIT_FRAMES, RUN_LIMIT_FRAMES, typeRun } from "#src/host-client/autostart.ts";
 import { readCoverage, writtenBlocks } from "#src/host-client/coverage.ts";
-import { checkActionSteps, runActionStep, type ActionStep } from "#src/host-client/steps.ts";
+import { resetToReady } from "#src/host-client/entry-state.ts";
+import { readActionSteps, runActionStep, type ActionStep } from "#src/host-client/steps.ts";
 import { WireFailure } from "#src/host-client/tools.ts";
-import { readProjectFile, writeProjectFile } from "#src/host-client/transfer.ts";
+import { readProjectFile, writeReported, type Written } from "#src/host-client/transfer.ts";
 import { ViceSessionClient } from "#src/host-client/vice-session.ts";
-import { resolveProjectPath } from "#src/project.ts";
-import { runScript, UsageError } from "#src/script.ts";
-import { basicStart, inspect, PackingError, readMemoryMap, underRom, writtenThenExecuted } from "./lib/evidence.ts";
+import { knowledgeAt, knowledgeNames } from "#src/knowledge/names.ts";
+import { OPTIONS, runScript, UsageError, type Call, type CommandSpec, type OptionSpec } from "#src/script.ts";
+import { basicStart, inspect, readMemoryMap, underRom, writtenThenExecuted } from "./lib/evidence.ts";
 import { loads, readLoadSteps } from "./lib/loads.ts";
-import { callReturn, captureSegments, executedIn, inRanges, mergeMaps, stageCandidates, stagePoints, withoutRanges, type Range } from "./lib/stages.ts";
-import { entryState, IO_AREAS, json, machineState, readRam, READY_FRAMES, vectorsOf } from "./lib/machine.ts";
-
-const USAGE = `unpack.ts inspect <program.prg>
-unpack.ts trace <program.prg> [--frames <n>] [--entry <address>] [--steps <file>]
-unpack.ts capture <program.prg> --until <address> --out <dir> [--range <start> <end>] [--exclude <start>-<end>]... [--timeout-frames <n>] [--entry <address>] [--steps <file>] [--min-stage <bytes>]
-unpack.ts stages <program.prg> [--frames <n>] [--entry <address>] [--steps <file>] [--min-stage <bytes>]
-unpack.ts loads <program> --steps <file> --out <dir> [--drive] [--min-block <bytes>]
-
-inspect   packing evidence: the BASIC start and the entropy of the bytes
-trace     run the program for <n> frames (default 3000) and report the memory
-          that it wrote and then executed; --entry starts it there instead of RUN
-capture   run the program until the CPU gets to <address> after the steps, and write into the
-          directory --out: image.bin (64 KiB of RAM), image.json (the entry,
-          the segments that the stages wrote, the vectors, the stages), a PRG
-          for each segment, and entry_state.json (registers, $00/$01, pages
-          0-3, VIC, SID and CIA registers, vectors, and what differs from a
-          clean reset). --range gives one segment in place of the found ones.
-          --exclude (more than once) leaves a range out of the segments, for
-          example bytes that a crack left and the program never reads.
-          --entry starts it there instead of RUN.
-
-stages    run the program for <n> frames (default 3000) and report each stage:
-          where it starts, the memory it wrote, and where the next one starts.
-          A stage starts when the CPU executes a block of at least
-          --min-stage bytes (default 64) that the stage before wrote.
-
-loads     run a multi-load program (a PRG, or a disk, tape or cartridge image)
-          with the steps file; each capture step {"capture": "<name>"} writes
-          <dir>/<name>/ with image.bin, image.json, entry_state.json and a PRG
-          for each block of at least --min-block bytes (default 64) that the C64
-          side changed since the previous capture. --drive also writes the 2 KiB
-          drive RAM as drive8.prg, for knowledge space drive8.
-
---steps <file>  a JSON list of input steps that run right after the program
-          starts: write, registers, joystick, type, frames and runUntil, as in
-          c64-testing scenarios, with $ addresses only. Use it to press a key
-          in an intro or to get through a menu. stages and capture track the
-          stages in frames steps and in runUntil steps with at alone.
-
-Addresses are $ and four hex digits. The result is one JSON object.`;
-
-
-function address(text: string, option: string): number {
-  try {
-    return parseC64Address(text);
-  } catch {
-    throw new UsageError(`${option} must be $ followed by four hex digits, not ${text}`);
-  }
-}
+import { callReturn, captureSegments, executedIn, inRanges, mergeMaps, stageCandidates, stagePoints, withoutRanges } from "./lib/stages.ts";
+import { entryState, IO_AREAS, json, machineState, readRam, vectorsOf } from "./lib/machine.ts";
 
 /** Written-then-executed bytes from this many on are unpacking, decrypting or relocating, not self-changing code. */
 const UNPACKED_BYTES = 256;
@@ -76,26 +27,12 @@ const MAX_ADVANCE = 10_000;
 /** The most ranges one memory map read gives. */
 const MAX_RANGES = 1000;
 
-/** Reads and checks a steps file: action steps with $ addresses only. */
-function readSteps(path: string): ActionStep[] {
-  let value: unknown;
-  try {
-    value = JSON.parse(readProjectFile(path).bytes.toString("utf8"));
-  } catch (error) {
-    if (error instanceof WireFailure) throw error;
-    throw new UsageError(`--steps ${path} is not JSON: ${(error as Error).message}`);
-  }
-  return checkActionSteps(value, (message) => {
-    throw new UsageError(`--steps ${path}: ${message}`);
-  });
-}
-
 /** Runs the steps; the reason when a runUntil step did not reach its target. */
 async function runSteps(client: ViceSessionClient, steps: ActionStep[]): Promise<string | undefined> {
   for (const [index, step] of steps.entries()) {
-    const notReached = await runActionStep(client, step, parseC64Address);
+    const notReached = await runActionStep(client, step, knowledgeAt());
     if (notReached !== undefined && "runUntil" in step) {
-      return `Step ${index + 1} did not reach its target in ${step.timeoutFrames} frames. It stopped by ${notReached.stopReason} at ${formatC64Address(notReached.pc)}.`;
+      return `Step ${index + 1} did not reach its target in ${step.runUntil.timeoutFrames} frames. It stopped by ${notReached.stopReason} at ${formatC64Address(notReached.pc)}.`;
     }
   }
   return undefined;
@@ -240,9 +177,11 @@ interface Followed {
   failed?: string;
 }
 
-/** A runUntil step to an address alone: a breakpoint stops it, so the stages are tracked while it runs. */
-function trackedRunUntil(step: ActionStep): step is { runUntil: { at: string }; timeoutFrames: number } {
-  return "runUntil" in step && "at" in step.runUntil && !("raster" in step.runUntil);
+type RunUntilStep = Extract<ActionStep, { runUntil: unknown }>;
+
+/** A runUntil step to an address with no condition: a breakpoint stops it, so the stages are tracked while it runs. */
+function trackedRunUntil(step: ActionStep): step is RunUntilStep & { runUntil: { target: { kind: "address" } } } {
+  return "runUntil" in step && step.runUntil.target.kind === "address" && step.runUntil.target.condition === undefined;
 }
 
 /**
@@ -281,7 +220,7 @@ async function follow(
   let stopAt: number | undefined;
   const atTarget = (pc: number) => stopAt !== undefined && pc === stopAt;
   // The current stage: its memory map since it started, chunk by chunk, its own code, and the written code it calls.
-  let stage = { map: new Uint8Array(0x10000), own: new Set<number>(), called: [] as Range[] };
+  let stage = { map: new Uint8Array(0x10000), own: new Set<number>(), called: [] as AddressRange[] };
   const startStage = async (next: number, last: Uint8Array) => {
     mergeMaps(stage.map, last);
     found.push({ entry, firstFrame, frames: total - firstFrame, wrote: writtenBlocks(stage.map, options.minStage), next });
@@ -296,9 +235,9 @@ async function follow(
    * blocks, and stops at the first opcode that the stage wrote and the CPU
    * then executes. Own code stops the run once; a write watch arms it again.
    */
-  const rerun = async (candidates: Range[], frames: number): Promise<{ used: number; map: Uint8Array; next?: number; atTarget: boolean }> => {
+  const rerun = async (candidates: AddressRange[], frames: number): Promise<{ used: number; map: Uint8Array; next?: number; atTarget: boolean }> => {
     const points = new Map<string, { kind: "exec" | "watch"; id: number }>();
-    const arm = async (wanted: { exec: Range[]; watch: Range[] }) => {
+    const arm = async (wanted: { exec: AddressRange[]; watch: AddressRange[] }) => {
       const keys = new Set([...wanted.exec.map((range) => `exec:${range.start}:${range.end}`), ...wanted.watch.map((range) => `watch:${range.start}:${range.end}`)]);
       for (const [key, point] of points) {
         if (keys.has(key)) continue;
@@ -337,7 +276,7 @@ async function follow(
         return undefined;
       } finally {
         await client.breakpoint({ action: "remove", id: point.id });
-        await client.snapshot({ action: "discard", name: CALL_SNAPSHOT });
+        await client.snapshot({ action: "remove", name: CALL_SNAPSHOT });
       }
     };
     let left = frames;
@@ -448,17 +387,17 @@ async function follow(
   for (const [index, step] of options.steps.entries()) {
     if ("frames" in step) await track(step.frames);
     else if (trackedRunUntil(step)) {
-      if (!(await trackTo(parseC64Address(step.runUntil.at), step.timeoutFrames))) {
+      if (!(await trackTo(knowledgeAt()(step.runUntil.target.address), step.runUntil.timeoutFrames))) {
         const { pc } = await client.registersGet("c64");
-        return { stages: found, frames: total, reached: false, failed: `Step ${index + 1} did not reach its target in ${step.timeoutFrames} frames. It is at ${formatC64Address(pc)}.` };
+        return { stages: found, frames: total, reached: false, failed: `Step ${index + 1} did not reach its target in ${step.runUntil.timeoutFrames} frames. It is at ${formatC64Address(pc)}.` };
       }
-    } else await runActionStep(client, step, parseC64Address);
+    } else await runActionStep(client, step, knowledgeAt());
   }
   const left = Math.max(0, options.frames - total);
   let reached = false;
   if (options.until === undefined) await track(left);
   else reached = await trackTo(options.until, left);
-  await client.snapshot({ action: "discard", name: STAGE_SNAPSHOT }).catch(() => undefined);
+  await client.snapshot({ action: "remove", name: STAGE_SNAPSHOT }).catch(() => undefined);
   mergeMaps(stage.map, await readCoverage(client));
   found.push({ entry, firstFrame, frames: total - firstFrame, wrote: writtenBlocks(stage.map, options.minStage) });
   return { stages: found, frames: total, reached };
@@ -494,10 +433,9 @@ async function stages(program: string, options: { frames: number; entry?: number
   }
 }
 
-
 async function capture(
   program: string,
-  options: { until: number; out: string; range?: [number, number]; exclude: Array<{ start: number; end: number }>; timeoutFrames: number; entry?: number; steps: ActionStep[]; minStage: number },
+  options: { until: number; out: string; range?: AddressRange; exclude: AddressRange[]; timeoutFrames: number; entry?: number; steps: ActionStep[]; minStage: number },
 ): Promise<{ output: Record<string, unknown>; failed: boolean }> {
   const client = await ViceSessionClient.open({ videoStandard: "pal" });
   try {
@@ -514,14 +452,15 @@ async function capture(
     const memory = await readRam(client, 0x0000, 0x10000);
     const state = await machineState(client);
     // The segments: what the stages wrote, without loader leftovers, with no overlap.
-    const found = options.range !== undefined ? [{ start: options.range[0], end: options.range[1] }] : captureSegments(followed.stages, registers.pc);
+    const found = options.range !== undefined ? [options.range] : captureSegments(followed.stages, registers.pc);
     const inside = options.exclude.find((range) => registers.pc >= range.start && registers.pc <= range.end);
     if (inside !== undefined) {
       return { output: { captured: false, reason: `The entry ${formatC64Address(registers.pc)} is in --exclude ${formatC64Address(inside.start)}-${formatC64Address(inside.end)}. A segment must hold the entry.` }, failed: true };
     }
     const segments = withoutRanges(found, options.exclude);
     const file = (path: string) => `${options.out}/${path}`;
-    const write = (path: string, bytes: Uint8Array) => writeProjectFile(file(path), bytes, { what: "--out" });
+    const written: Written[] = [];
+    const write = (path: string, bytes: Uint8Array) => written.push(writeReported(file(path), bytes, { what: "--out" }));
     write("image.bin", memory);
     const files = segments.map((segment) => {
       const name = `segment-${segment.start.toString(16).padStart(4, "0")}-${segment.end.toString(16).padStart(4, "0")}.prg`;
@@ -547,8 +486,7 @@ async function capture(
       ),
     );
     // A clean machine at the READY prompt shows what the loader and the stages changed.
-    await client.reset({ mode: "hard", run: true });
-    await client.execution({ action: "advance-frames", count: READY_FRAMES, space: "c64" });
+    await resetToReady(client);
     const clean = await machineState(client);
     const differs: Array<{ address: string; entry: number; reset: number }> = [];
     const compare = (base: number, entry: Buffer, reset: Buffer) => entry.forEach((value, offset) => value !== reset[offset] && differs.push({ address: formatC64Address(base + offset), entry: value, reset: reset[offset]! }));
@@ -561,7 +499,7 @@ async function capture(
         captured: true,
         pc: formatC64Address(registers.pc),
         out: options.out,
-        files: ["image.json", "image.bin", "entry_state.json", ...files],
+        files: written,
         segments: segments.map(showRange),
         ...(options.exclude.length === 0 ? {} : { excluded: options.exclude.map(showRange) }),
         stages: followed.stages.length,
@@ -574,127 +512,87 @@ async function capture(
   }
 }
 
-/** The options that each command takes; any other option is refused, not ignored. */
-const OPTIONS_OF: Record<string, string[]> = {
-  inspect: [],
-  trace: ["frames", "entry", "steps"],
-  stages: ["frames", "entry", "steps", "min-stage"],
-  capture: ["until", "out", "range", "exclude", "timeout-frames", "entry", "steps", "min-stage"],
-  loads: ["steps", "out", "drive", "min-block"],
+const PROGRAM = { name: "<program>", help: "a PRG file, relative to the project folder" };
+const FRAMES: OptionSpec = { ...OPTIONS.frames, max: 30_000, default: 3000, help: "run the program for n frames (default 3000)" };
+const ENTRY: OptionSpec = { ...OPTIONS.entry, help: "start the program here in place of RUN" };
+const STEPS: OptionSpec = { ...OPTIONS.steps, help: "action steps (JSON) that run right after the program starts, for example to press a key in an intro or to get through a menu" };
+const MIN_STAGE: OptionSpec = { kind: "count", value: "<bytes>", min: 1, max: 0x10000, default: 64, help: "a stage starts when the CPU executes a block of at least this many bytes that the stage before wrote (default 64)" };
+
+/** The result of a command: PASS, or FAIL with the reason. */
+const outcome = ({ output, failed }: { output: unknown; failed: boolean }) => ({ result: failed ? "FAIL" : "PASS", ...(output as Record<string, unknown>) });
+const entryOf = (call: Call) => {
+  const entry = call.address("entry");
+  return entry === undefined ? {} : { entry };
+};
+const stepsOf = (call: Call) => {
+  const path = call.string("steps");
+  return path === undefined ? [] : readActionSteps(path, "--steps");
 };
 
-async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }> {
-  const { values, positionals } = parseArgs({
-    args: argv,
-    strict: true,
-    allowPositionals: true,
+const COMMANDS: CommandSpec[] = [
+  {
+    name: "inspect",
+    summary: "Packing evidence: the BASIC start and the entropy of the bytes.",
+    subjects: [PROGRAM],
+    run: (call) => inspect(readProjectFile(call.subject(0)).bytes),
+  },
+  {
+    name: "trace",
+    summary: "Runs the program and reports the memory that it wrote and then executed.",
+    subjects: [PROGRAM],
+    options: { frames: FRAMES, entry: ENTRY, steps: STEPS },
+    run: async (call) => outcome(await trace(call.subject(0), { frames: call.count("frames")!, steps: stepsOf(call), ...entryOf(call) })),
+  },
+  {
+    name: "stages",
+    summary: "Runs the program and reports each stage: where it starts, the memory it wrote, and where the next one starts.",
+    subjects: [PROGRAM],
+    options: { frames: FRAMES, entry: ENTRY, steps: STEPS, "min-stage": MIN_STAGE },
+    notes: "stages tracks the stages in frames steps and in runUntil steps to an address target without a condition.",
+    run: async (call) => {
+      const steps = stepsOf(call);
+      // A runUntil step to a raster line or a memory value cannot be tracked in chunks of frames; capture takes it.
+      if (steps.some((step) => "runUntil" in step && !trackedRunUntil(step))) throw new UsageError("stages takes a runUntil step only with an address target without a condition. Use frames steps, or capture");
+      return outcome(await stages(call.subject(0), { frames: call.count("frames")!, steps, minStage: call.count("min-stage")!, ...entryOf(call) }));
+    },
+  },
+  {
+    name: "capture",
+    summary: "Runs the program until the CPU gets to --until after the steps, and writes into --out: image.bin (64 KiB of RAM), image.json (the entry, the segments that the stages wrote, the vectors, the stages), a PRG for each segment, and entry_state.json.",
+    subjects: [PROGRAM],
     options: {
-      until: { type: "string" },
-      out: { type: "string" },
-      range: { type: "string" },
-      exclude: { type: "string", multiple: true },
-      "timeout-frames": { type: "string" },
-      frames: { type: "string" },
-      entry: { type: "string" },
-      steps: { type: "string" },
-      "min-stage": { type: "string" },
-      "min-block": { type: "string" },
-      drive: { type: "boolean" },
-      help: { type: "boolean" },
+      until: { kind: "address", value: "<address>", required: true, help: "the unpacked entry point" },
+      out: { ...OPTIONS.out, value: "<dir>", required: true, help: "the folder for the capture, relative to the project folder" },
+      range: { ...OPTIONS.range, help: "one segment in place of the found ones" },
+      exclude: { kind: "range", value: "<start>-<end>", multiple: true, help: "a range to leave out of the segments, for example bytes that a crack left and the program never reads" },
+      "timeout-frames": { ...OPTIONS["timeout-frames"], max: 30_000, default: 3000, help: "stop the wait for --until after n frames (default 3000)" },
+      entry: ENTRY,
+      steps: STEPS,
+      "min-stage": MIN_STAGE,
     },
-  });
-  if (values.help) throw new UsageError("");
-  const [command, program, ...rest] = positionals;
-  if (program === undefined) throw new UsageError("give a command and a program");
-  const allowed = OPTIONS_OF[command ?? ""];
-  if (allowed === undefined) throw new UsageError(`unknown command ${command}`);
-  for (const option of Object.keys(values)) {
-    if (option !== "help" && !allowed.includes(option)) throw new UsageError(`${command} does not take --${option}`);
-  }
-  if (command === "inspect") {
-    if (rest.length > 0) throw new UsageError("inspect takes one program");
-    const { bytes } = readProjectFile(program);
-    try {
-      return { output: inspect(bytes), failed: false };
-    } catch (error) {
-      if (error instanceof PackingError) throw new UsageError(error.message);
-      throw error;
-    }
-  }
-  if (command === "trace") {
-    if (rest.length > 0) throw new UsageError("trace takes one program");
-    const frames = values.frames === undefined ? 3000 : Number(values.frames);
-    if (!Number.isInteger(frames) || frames < 1 || frames > 30_000) throw new UsageError("--frames must be from 1 to 30000");
-    const steps = values.steps === undefined ? [] : readSteps(values.steps);
-    return trace(program, { frames, steps, ...(values.entry === undefined ? {} : { entry: address(values.entry, "--entry") }) });
-  }
-  if (command === "stages") {
-    if (rest.length > 0) throw new UsageError("stages takes one program");
-    const frames = values.frames === undefined ? 3000 : Number(values.frames);
-    if (!Number.isInteger(frames) || frames < 1 || frames > 30_000) throw new UsageError("--frames must be from 1 to 30000");
-    const minStage = values["min-stage"] === undefined ? 64 : Number(values["min-stage"]);
-    if (!Number.isInteger(minStage) || minStage < 1 || minStage > 0x10000) throw new UsageError("--min-stage must be from 1 to 65536");
-    const steps = values.steps === undefined ? [] : readSteps(values.steps);
-    // A runUntil step to a raster line or a memory value cannot be tracked in chunks of frames; capture takes it.
-    if (steps.some((step) => "runUntil" in step && !trackedRunUntil(step))) throw new UsageError("stages takes a runUntil step only with at alone; use frames steps or runUntil at");
-    return stages(program, { frames, steps, minStage, ...(values.entry === undefined ? {} : { entry: address(values.entry, "--entry") }) });
-  }
-  if (command === "loads") {
-    if (rest.length > 0) throw new UsageError("loads takes one program");
-    if (values.steps === undefined || values.out === undefined) throw new UsageError("loads needs --steps and --out");
-    try {
-      resolveProjectPath(values.out);
-    } catch {
-      throw new UsageError(`--out must be a path relative to the project folder that stays inside it, not ${values.out}`);
-    }
-    const minBlock = values["min-block"] === undefined ? 64 : Number(values["min-block"]);
-    if (!Number.isInteger(minBlock) || minBlock < 1 || minBlock > 0x10000) throw new UsageError("--min-block must be from 1 to 65536");
-    return loads(program, { out: values.out, steps: readLoadSteps(values.steps), drive: values.drive === true, minBlock });
-  }
-  if (values.until === undefined || values.out === undefined) throw new UsageError("capture needs --until and --out");
-  // --range takes two values: the end is the next positional argument.
-  let range: [number, number] | undefined;
-  if (values.range !== undefined) {
-    if (rest.length !== 1) throw new UsageError("--range takes a start and an end address");
-    range = [address(values.range, "--range"), address(rest[0]!, "--range")];
-    if (range[1] < range[0]) throw new UsageError("the --range end must not be before its start");
-  } else if (rest.length > 0) {
-    throw new UsageError("too many arguments");
-  }
-  const exclude = (values.exclude ?? []).map((value) => {
-    const parts = value.split("-");
-    if (parts.length !== 2) throw new UsageError(`--exclude takes <start>-<end>, not ${value}`);
-    const range = { start: address(parts[0]!, "--exclude"), end: address(parts[1]!, "--exclude") };
-    if (range.end < range.start) throw new UsageError(`the --exclude end must not be before its start: ${value}`);
-    return range;
-  });
-  try {
-    resolveProjectPath(values.out);
-  } catch {
-    throw new UsageError(`--out must be a path relative to the project folder that stays inside it, not ${values.out}`);
-  }
-  const timeoutFrames = values["timeout-frames"] === undefined ? 3000 : Number(values["timeout-frames"]);
-  if (!Number.isInteger(timeoutFrames) || timeoutFrames < 1 || timeoutFrames > 30_000) throw new UsageError("--timeout-frames must be from 1 to 30000");
-  const steps = values.steps === undefined ? [] : readSteps(values.steps);
-  const minStage = values["min-stage"] === undefined ? 64 : Number(values["min-stage"]);
-  if (!Number.isInteger(minStage) || minStage < 1 || minStage > 0x10000) throw new UsageError("--min-stage must be from 1 to 65536");
-  return capture(program, {
-    until: address(values.until, "--until"),
-    out: values.out,
-    ...(range === undefined ? {} : { range }),
-    exclude,
-    timeoutFrames,
-    steps,
-    minStage,
-    ...(values.entry === undefined ? {} : { entry: address(values.entry, "--entry") }),
-  });
-}
-
-await runScript(
-  async (argv) => {
-    const { output, failed } = await run(argv);
-    if (failed) process.exitCode = 1;
-    return output;
+    notes: "entry_state.json has the registers, $00/$01, pages 0-3, the VIC, SID and CIA registers, the vectors, and what differs from a clean reset.",
+    run: async (call) => {
+      const range = call.range("range");
+      return outcome(await capture(call.subject(0), { until: call.address("until")!, out: call.string("out")!, ...(range === undefined ? {} : { range }), exclude: call.ranges("exclude"), timeoutFrames: call.count("timeout-frames")!, steps: stepsOf(call), minStage: call.count("min-stage")!, ...entryOf(call) }));
+    },
+  },
+  {
+    name: "loads",
+    summary: "Runs a multi-load program with the steps file. Each capture step {\"capture\": \"<name>\"} writes <dir>/<name>/ with image.bin, image.json, entry_state.json and a PRG for each block that the C64 side changed since the previous capture.",
+    subjects: [{ name: "<program>", help: "a PRG, or a disk, tape or cartridge image, relative to the project folder" }],
+    options: {
+      steps: { ...STEPS, required: true, help: "action steps and capture steps (JSON)" },
+      out: { ...OPTIONS.out, value: "<dir>", required: true, help: "the folder for the captures, relative to the project folder" },
+      drive: { kind: "flag", help: "also write the 2 KiB drive RAM as drive8.prg, for knowledge space drive8" },
+      "min-block": { kind: "count", value: "<bytes>", min: 1, max: 0x10000, default: 64, help: "write a changed block of at least this many bytes (default 64)" },
+    },
+    run: async (call) => outcome(await loads(call.subject(0), { out: call.string("out")!, steps: readLoadSteps(call.string("steps")!), drive: call.flag("drive"), minBlock: call.count("min-block")! })),
   },
-  { usage: USAGE },
-);
+];
+
+await runScript({
+  name: "unpacker",
+  summary: "Packing evidence of a program, and captures of the program after it unpacked itself. It never names a packer and runs no native unpack tool.",
+  names: knowledgeNames,
+  commands: COMMANDS,
+});

package/src/c64.ts

@@ -1,25 +1,40 @@
-const ADDRESS_PATTERN = /^\$([0-9a-fA-F]{4})$/;
+import { Refusal } from "./errors.ts";
 
-/** Returns the value when it is a C64 address (0-$ffff). Throws RangeError otherwise. */
+/** A C64 address as text: $ and 1 to 4 hex digits, either case. */
+const ADDRESS_PATTERN = /^\$([0-9a-fA-F]{1,4})$/;
+
+/** The address that the text gives ($ and 1 to 4 hex digits), or undefined. */
+export function c64AddressOf(text: string): number | undefined {
+  const match = ADDRESS_PATTERN.exec(text);
+  return match === null ? undefined : Number.parseInt(match[1]!, 16);
+}
+
+/** Returns the value when it is a C64 address (0-$ffff). Refuses it otherwise. */
 function checkAddress(value: number): number {
-  if (!Number.isInteger(value) || value < 0 || value > 0xffff) {
-    throw new RangeError(`C64 address out of range: ${value}`);
-  }
+  if (!Number.isInteger(value) || value < 0 || value > 0xffff) throw new Refusal("invalid-input", `${value} is not a C64 address: an address is from $0000 to $ffff.`);
   return value;
 }
 
-export function parseC64Address(value: string): number {
-  const match = ADDRESS_PATTERN.exec(value);
-  if (match === null) {
-    throw new TypeError(`Invalid C64 address: ${value}`);
-  }
-  return checkAddress(Number.parseInt(match[1]!, 16));
+/** The address of $ and 1 to 4 hex digits. Refuses other text. */
+export function parseC64Address(text: string): number {
+  const value = c64AddressOf(text);
+  if (value === undefined) throw new Refusal("invalid-input", `${JSON.stringify(text)} is not a C64 address: give $ and 1 to 4 hex digits, for example $c000 or $fb.`);
+  return value;
 }
 
 export function formatC64Address(value: number): string {
   return `$${checkAddress(value).toString(16).padStart(4, "0")}`;
 }
 
+/** An inclusive span of C64 addresses. */
+export interface AddressRange {
+  start: number;
+  end: number;
+}
+
+/** The knowledge spaces: the C64, the 1541 drive in unit 8, and cartridge banks 0 to 255. */
+export const SPACE_PATTERN = /^(c64|drive8|bank(0|[1-9][0-9]?|1[0-9]{2}|2[0-4][0-9]|25[0-5]))$/;
+
 /** VIC-II state with its addresses as $xxxx; the other values stay numbers. */
 export function formatVicii<T extends { screenAddress: number; graphicsAddress: number }>(state: T): Omit<T, "screenAddress" | "graphicsAddress"> & { screenAddress: string; graphicsAddress: string } {
   return { ...state, screenAddress: formatC64Address(state.screenAddress), graphicsAddress: formatC64Address(state.graphicsAddress) };
@@ -30,20 +45,20 @@ export function formatSprite<T extends { dataAddress: number }>(sprite: T): Omit
   return { ...sprite, dataAddress: formatC64Address(sprite.dataAddress) };
 }
 
-/** A byte as $xx. Throws RangeError outside 0-255. */
+/** A byte as $xx. Refuses a value outside 0-255. */
 export function formatC64Byte(value: number): string {
-  if (!Number.isInteger(value) || value < 0 || value > 0xff) throw new RangeError(`C64 byte out of range: ${value}`);
+  if (!Number.isInteger(value) || value < 0 || value > 0xff) throw new Refusal("invalid-input", `${value} is not a byte: a byte is from 0 to 255.`);
   return `$${value.toString(16).padStart(2, "0")}`;
 }
 
 /**
  * The memory a PRG loads into: the 2-byte load address, then the body.
- * Throws RangeError for a file shorter than 3 bytes or one that runs past $ffff.
+ * Refuses a file shorter than 3 bytes or one that runs past $ffff.
  */
 export function prgRange(prg: Uint8Array): { start: number; end: number; body: Uint8Array } {
-  if (prg.length < 3) throw new RangeError("A PRG has a 2-byte load address and at least one byte.");
+  if (prg.length < 3) throw new Refusal("invalid-input", "A PRG has a 2-byte load address and at least one byte.");
   const start = prg[0]! | (prg[1]! << 8);
-  if (start + prg.length - 2 > 0x10000) throw new RangeError("The PRG runs past $ffff.");
+  if (start + prg.length - 2 > 0x10000) throw new Refusal("invalid-input", "The PRG runs past $ffff.");
   return { start, end: start + prg.length - 3, body: prg.subarray(2) };
 }
 
@@ -86,7 +101,7 @@ export function d018Offsets(d018: number): { screen: number; characters: number;
  * Converts text to the PETSCII bytes the C64 keyboard types after a reset
  * (upper case/graphics mode). Letters of either case type the unshifted key,
  * which shows as an upper-case letter. "\n" and "\r\n" type RETURN.
- * Throws RangeError naming the first character that has no key.
+ * Refuses the text with the first character that has no key.
  */
 export function textToPetscii(text: string): Uint8Array {
   const bytes: number[] = [];
@@ -100,7 +115,7 @@ export function textToPetscii(text: string): Uint8Array {
     else if (character === "£") bytes.push(0x5c);
     else if (character === "↑" || character === "^") bytes.push(0x5e);
     else if (character === "←") bytes.push(0x5f);
-    else throw new RangeError(`There is no C64 key for ${JSON.stringify(character)}`);
+    else throw new Refusal("invalid-input", `There is no C64 key for ${JSON.stringify(character)}`);
   }
   return Uint8Array.from(bytes);
 }
@@ -125,7 +140,7 @@ export function petsciiNameToText(bytes: Uint8Array): string {
 
 /**
  * The reverse of petsciiNameToText. Letters of either case are the unshifted
- * letters ($41-$5a). Throws RangeError for text that is no name.
+ * letters ($41-$5a). Refuses text that is no name.
  */
 export function textToPetsciiName(text: string): Uint8Array {
   const bytes: number[] = [];
@@ -144,7 +159,7 @@ export function textToPetsciiName(text: string): Uint8Array {
     else if (character === "↑") bytes.push(0x5e);
     else if (character === "←") bytes.push(0x5f);
     else if (code >= 0x20 && code <= 0x5d) bytes.push(code);
-    else throw new RangeError(`${JSON.stringify(character)} is not a name character. Write other bytes as {$xx}.`);
+    else throw new Refusal("invalid-input", `${JSON.stringify(character)} is not a name character. Write other bytes as {$xx}.`);
     index++;
   }
   return Uint8Array.from(bytes);

package/src/cli/main.ts

@@ -10,7 +10,7 @@ import { parseArgs } from "node:util";
 import { oldNodeRefusal, PACKAGE } from "../package.ts";
 import { localToolContext } from "../native/local.ts";
 import { localToolStatus } from "../native/status.ts";
-import { WireFailure } from "../protocol/messages.ts";
+import { isRefusal } from "../errors.ts";
 import { startTrace } from "../trace.ts";
 import { runApSdk } from "./ap-sdk.ts";
 import { installedItems, parseTargets, tidyAfterUninstall, undoWindsurfProjectMcp, windsurfBefore, withoutWindsurfMcp, type Scope } from "./cleanup.ts";
@@ -124,7 +124,7 @@ try {
   if ((error as NodeJS.ErrnoException).code?.startsWith("ERR_PARSE_ARGS")) {
     console.error(`${(error as Error).message}\n\n${HELP}`);
     process.exitCode = 2;
-  } else if (error instanceof WireFailure) {
+  } else if (isRefusal(error)) {
     // A refusal by name, for example AP SDK that did not finish in time.
     console.error(error.message);
     process.exitCode = 1;

package/src/errors.ts

@@ -0,0 +1,38 @@
+// The one list of error codes and the one refusal class. Every part of the
+// repository may import this file: the scripts, the MCP server, the host and
+// the knowledge all report a failure as a code from this list and a message.
+
+export const ERROR_CODES = [
+  "invalid-input",
+  "machine-running",
+  "machine-unavailable",
+  "machine-state-lost",
+  "not-found",
+  "media-error",
+  "limit-exceeded",
+  "unsupported-in-space",
+  "installation-incomplete",
+  "operation-failed",
+  "conflict",
+  "stale-revision",
+  "invalid-database",
+  "unsupported-schema",
+] as const;
+export type ErrorCode = (typeof ERROR_CODES)[number];
+
+/** A refused operation: a stable code and a message that tells what is wrong and what to do. */
+export class Refusal extends Error {
+  override name = "Refusal";
+  readonly code: ErrorCode;
+
+  constructor(code: ErrorCode, message: string) {
+    super(message);
+    this.code = code;
+  }
+}
+
+/** True for an Error with a code from ERROR_CODES: a refusal, whatever its class. */
+export function isRefusal(error: unknown): error is Error & { code: ErrorCode } {
+  const code = (error as { code?: unknown } | undefined)?.code;
+  return error instanceof Error && typeof code === "string" && (ERROR_CODES as readonly string[]).includes(code);
+}

package/src/graphics.ts

@@ -5,6 +5,8 @@
 
 import { crc32, deflateSync } from "node:zlib";
 
+import { Refusal } from "./errors.ts";
+
 export interface IndexedFrame {
   width: number;
   height: number;
@@ -26,7 +28,7 @@ function chunk(type: string, data: Uint8Array): Buffer {
 /** Encodes an indexed frame as an 8-bit palette PNG. */
 export function encodePng(frame: IndexedFrame, palette: ReadonlyArray<Rgb>): Buffer {
   for (const index of frame.pixels) {
-    if (index >= palette.length) throw new Error(`pixel colour ${index} is not in the ${palette.length}-colour palette`);
+    if (index >= palette.length) throw new Refusal("operation-failed", `pixel colour ${index} is not in the ${palette.length}-colour palette`);
   }
   const header = Buffer.alloc(13);
   header.writeUInt32BE(frame.width, 0);