@henols/c64-re-tools 1.0.0 → 2.0.0-rc.10

package/skills/c64-unpacker/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: c64-unpacker
+description: Use this skill to find out if a packer or a cruncher compressed a C64 program, and to get the unpacked program for analysis. It shows evidence of packing without a guess of the packer name. It runs the program in an emulator until the unpacked code starts, then writes the memory into the project. It also captures each part of a multi-load program and the drive RAM. Do not use it to analyze the unpacked code.
+---
+
+# c64-unpacker
+
+## Purpose
+
+Find out if a packer compressed a C64 program. Get the unpacked program for analysis.
+
+This skill does not change project knowledge.
+
+## Inputs
+
+- The program: a PRG file, relative to the project directory.
+- For a capture: the address where the unpacked program starts, and the directory for the result.
+
+## Tools / execution path
+
+```
+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
+```
+
+`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`.
+
+| 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. |
+| `--range '$c000' '$cfff'` | Write this range as a PRG. Without it, the script writes all 64 KiB of RAM as a flat file. |
+| `--timeout-frames 3000` | How many frames the program can run before the capture stops (default 3000). |
+| `--frames 3000` | `trace` only: how many frames the program runs (default 3000). |
+| `--entry '$c000'` | `trace`, `stages` and `capture`: start the program at this address. Without it, the script types RUN. A file that is not a BASIC program at `$0801` needs it. |
+| `--steps input.json` | Input for the program, right after it starts: a JSON list of steps. Use it when an intro waits for a key or a menu waits for a choice. The scripts start the program as a c64-testing scenario does. Thus the same steps in a scenario get the program to the entry at the same time. |
+| `--drive` | `loads` only: each capture also writes the 2 KiB RAM of the 1541 drive as `drive8.prg`. |
+| `--min-block 64` | `loads` only: the smallest block of changed memory that becomes a segment (default 64). The result counts smaller changes as `smallChanges`. |
+| `--min-stage 64` | `stages` and `capture`: the smallest block of written memory that starts a new stage when the CPU executes it (default 64). |
+
+The capture reads RAM, also the RAM under the ROMs and the I/O area. The script prints one JSON object. The script refuses an option that the command does not use.
+
+A steps file has the steps `write`, `registers`, `joystick`, `type`, `frames` and `runUntil` of the c64-testing skill. Addresses are `$` and four hex digits. For example, wait 50 frames and press the space bar:
+
+```json
+[{ "frames": 50 }, { "type": " " }]
+```
+
+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.
+
+## 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:
+   - `likely`: most of the bytes look compressed. Packed data has this property.
+   - `unlikely`: the bytes look like code and data. A simple cruncher can also give this result.
+   - `unclear`: the file is short, or the blocks do not give clear evidence. Or the code at the SYS address decodes or moves bytes outside the program.
+
+   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.
+   - `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.
+2. Run `trace`. It gives the evidence from the run. Read `packing`:
+   - `likely`: the program wrote code and then executed it. It unpacked, decrypted or moved code. `runningRange` is the written code that runs at the end of the trace. When the trace ends in ROM code, for example in an interrupt, it is the written code that runs next. Its `start` is code that runs after the unpacking. It is not always the entry point of the program. When no written code runs in 50 more frames, the result has no `runningRange` and no `suggestedUntil`.
+   - `unclear`: the program executed a small quantity of code that it wrote. This can be code that changes itself.
+   - `unlikely`: the program executed no code that it wrote. If the program waits for a key or a joystick, it can move code after that input. Then use the c64-emulator skill.
+3. Find the address where the unpacked program starts:
+   - Run `stages`. The `entry` of the last stage is usually the start of the program. A routine that a stage writes and calls is part of that stage when it returns to the stage.
+   - 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.
+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.
+7. Use `--range` only when you know the area of the program. Then the capture writes that one segment.
+
+## Multi-load programs
+
+A multi-load program loads more parts from the disk while it runs, for example one part for each level. Use `loads` to capture each part. The program can be a PRG, or a disk, tape or cartridge image that VICE starts.
+
+1. Write a steps file. Put a `capture` step after each point where a part is in memory, for example:
+
+```json
+[
+  { "runUntil": { "at": "$080d" }, "timeoutFrames": 6000 },
+  { "capture": "main" },
+  { "type": " " },
+  { "runUntil": { "at": "$c000" }, "timeoutFrames": 6000 },
+  { "capture": "level1" }
+]
+```
+
+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`.
+
+VICE records no memory access map for the drive CPU. Thus no tool gives coverage of drive code.
+
+## Knowledge
+
+Automatic write:
+- none.
+
+Do not record the unpacker in the project knowledge, unless the user asks to examine the unpacker.
+
+## Result
+
+The packing evidence, the stages, or the unpacked program with its image, segments and entry state in a directory of the project.
+
+For `loads`: `captures`, with the name, the PC, the segments and the drive file of each capture. `keyWait: true` tells that the CPU was in the KERNAL wait for a key.
+
+The exit status is 0 for a result. The exit status is 1 for `traced: false`, for `captured: false`, for `loaded: false` and for an error. The exit status is 2 for a wrong argument.
+
+## Failure and conflicts
+
+- `traced: false`: the emulator did not load the program into memory in the time limit. The reason gives the load address. Make sure that the file is a PRG that the C64 can load.
+- `captured: false`: the program did not get to the address in the time limit. The reason tells where it stopped. Find a better address with the c64-emulator skill, or give more frames. If it stopped in a key wait, give `--steps` with a key.
+- A step did not reach its target: the reason names the step. Change the step or give it more frames.
+- `loaded: false` and no capture has a segment: the program did not load a part, or it did not start. `keyWait: true` on a capture tells that the C64 waited at READY. or at an INPUT statement. For a tape image, read `emulatorFlaw`. A known VICE flaw can stop a tape load. Tell the user to install the latest VICE.
+- Do not name a packer from weak evidence. The script never names one.
+- Some programs unpack in more than one stage. Run `stages` to find each stage. Capture at the entry of the last stage. Make sure that it is the application and not a second unpacker.
+- `not-found` or `invalid-input`: a path or an argument is wrong. Read the message.
+- `installation-incomplete`, or `machine-unavailable` with a message that the host runtime does not run: stop the task. Give the message to the user and wait for the user. The message gives the remedy. Do not make a replacement for the tool or the host runtime, for example your own disk parser, disassembler or emulator script.
+
+## Handoffs
+
+- Unpacked machine code → c64-static-analysis
+- Find the start address at run time → c64-emulator

package/skills/c64-unpacker/scripts/evidence.ts

@@ -0,0 +1,207 @@
+// Local evidence of packing for the c64-unpacker script: where BASIC hands
+// over and how compressed the bytes look. It never names a packer.
+
+import { basicLineText, findHandoffs, formatC64Address, instructionLength, parseTokenized } from "#src/c64.ts";
+
+export class PackingError extends Error {}
+
+/** A 256-byte block above this many bits per byte looks compressed. */
+const HIGH_ENTROPY = 6.9;
+const BLOCK = 256;
+
+function entropy(bytes: Uint8Array): number {
+  const counts = new Array<number>(256).fill(0);
+  for (const byte of bytes) counts[byte]!++;
+  let bits = 0;
+  for (const count of counts) {
+    if (count === 0) continue;
+    const p = count / bytes.length;
+    bits -= p * Math.log2(p);
+  }
+  return bits;
+}
+
+/** A BASIC program at $0801, which RUN starts. */
+export interface BasicStart {
+  /** The first address after the BASIC text. */
+  basicEnd: number;
+  /** The first SYS: its line, and its address when the argument is a constant. */
+  sys?: { line: number; address?: number; expression?: string };
+}
+
+/** The BASIC program of a PRG at $0801 and its first SYS, or undefined when the file is no BASIC program there. */
+export function basicStart(program: Uint8Array): BasicStart | undefined {
+  const tokenized = parseTokenized(program);
+  if ("reason" in tokenized || tokenized.loadAddress !== 0x0801 || tokenized.lines.length === 0) return undefined;
+  const sys = findHandoffs(tokenized.lines).find((handoff) => handoff.kind === "sys");
+  if (sys === undefined) return { basicEnd: tokenized.basicEnd };
+  return { basicEnd: tokenized.basicEnd, sys: "address" in sys ? { line: sys.line, address: sys.address } : { line: sys.line, expression: "expression" in sys ? sys.expression : "" } };
+}
+
+/** The local packing evidence of one PRG. */
+export interface PackingEvidence {
+  loadRange: { start: string; end: string };
+  bytes: number;
+  /** 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). */
+  basicText: string[];
+  /** Runs of readable PETSCII near the start of the code, raw. */
+  strings: string[];
+  /** What the code at the SYS address does in its first bytes. */
+  start: { at: string; jumpsOutside?: string; writesOutside?: string } | null;
+  /** EOR loops that store with an index near the start: decryption or decoding. */
+  decodeLoops: string[];
+  packing: "likely" | "unlikely" | "unclear";
+  evidence: string;
+}
+
+/** How far the start-code signals look from the SYS address. */
+const START_BYTES = 256;
+const MIN_STRING = 8;
+const MAX_STRINGS = 10;
+const EOR_OPCODES = new Set([0x41, 0x45, 0x49, 0x4d, 0x51, 0x55, 0x59, 0x5d]);
+const INDEXED_STORES = new Set([0x81, 0x91, 0x95, 0x99, 0x9d]);
+const BRANCHES = new Set([0x10, 0x30, 0x50, 0x70, 0x90, 0xb0, 0xd0, 0xf0]);
+
+/** Readable PETSCII runs of at least MIN_STRING characters, the first MAX_STRINGS of them. */
+function readableStrings(bytes: Uint8Array): string[] {
+  const found: string[] = [];
+  let run = "";
+  for (const byte of [...bytes, 0]) {
+    if (byte >= 0x20 && byte <= 0x5d) run += String.fromCharCode(byte);
+    else {
+      if (run.trim().length >= MIN_STRING && found.length < MAX_STRINGS) found.push(run.trim().slice(0, 40));
+      run = "";
+    }
+  }
+  return found;
+}
+
+/**
+ * The start-code signals: the first JMP to an address outside the loaded
+ * range, the first indexed store outside it, and EOR loops that store with
+ * an index and branch back.
+ */
+function startSignals(program: Uint8Array, load: number, end: number, sys: number): { start: PackingEvidence["start"]; decodeLoops: string[] } {
+  if (sys < load || sys > end) return { start: null, decodeLoops: [] };
+  const byteAt = (address: number) => (address >= load && address <= end ? program[address - load + 2]! : undefined);
+  const outside = (address: number) => address < load || address > end;
+  const instructions: Array<{ at: number; opcode: number; operand: number; length: number }> = [];
+  for (let at = sys; at <= Math.min(end, sys + START_BYTES - 1); ) {
+    const opcode = byteAt(at)!;
+    const length = instructionLength(opcode);
+    const operand = length === 3 ? (byteAt(at + 1) ?? 0) | ((byteAt(at + 2) ?? 0) << 8) : length === 2 ? (byteAt(at + 1) ?? 0) : 0;
+    instructions.push({ at, opcode, operand, length });
+    at += length;
+  }
+  const jump = instructions.find((instruction) => instruction.opcode === 0x4c && outside(instruction.operand));
+  const store = instructions.find((instruction) => (instruction.opcode === 0x9d || instruction.opcode === 0x99) && outside(instruction.operand));
+  const decodeLoops = instructions
+    .filter((instruction, index) => {
+      if (!EOR_OPCODES.has(instruction.opcode)) return false;
+      const after = instructions.slice(index + 1, index + 9);
+      return after.some((next) => INDEXED_STORES.has(next.opcode)) && after.some((next) => BRANCHES.has(next.opcode) && next.operand >= 0x80);
+    })
+    .map((instruction) => formatC64Address(instruction.at));
+  return {
+    start: { at: formatC64Address(sys), ...(jump === undefined ? {} : { jumpsOutside: formatC64Address(jump.operand) }), ...(store === undefined ? {} : { writesOutside: formatC64Address(store.operand) }) },
+    decodeLoops,
+  };
+}
+
+export function inspect(program: Uint8Array): PackingEvidence {
+  if (program.length < 3) throw new PackingError("the file is too short for a PRG");
+  const load = program[0]! | (program[1]! << 8);
+  const end = load + program.length - 3;
+  const basic = basicStart(program);
+  const stub = basic?.sys;
+  // Without BASIC, all bytes count; with it, only the bytes after the BASIC text.
+  const from = basic === undefined ? 2 : Math.min(program.length, basic.basicEnd - load + 2);
+  const body = program.subarray(from);
+  const blocks: number[] = [];
+  for (let at = 0; at + BLOCK <= body.length; at += BLOCK) blocks.push(entropy(body.subarray(at, at + BLOCK)));
+  const high = blocks.filter((value) => value > HIGH_ENTROPY).length;
+  const share = blocks.length === 0 ? 0 : high / blocks.length;
+  const byEntropy = blocks.length < 2 ? "unclear" : share >= 0.75 ? "likely" : share <= 0.1 ? "unlikely" : "unclear";
+  const tokenized = parseTokenized(program);
+  const basicText = "lines" in tokenized && load === 0x0801 ? tokenized.lines.map(basicLineText) : [];
+  const signals = stub?.address === undefined ? { start: null, decodeLoops: [] } : startSignals(program, load, end, stub.address);
+  const startMoves = signals.start?.jumpsOutside !== undefined || signals.start?.writesOutside !== undefined || signals.decodeLoops.length > 0;
+  // Code that decodes or moves itself is a reason to run it, also when the bytes look plain.
+  const packing = byEntropy === "unlikely" && startMoves ? "unclear" : byEntropy;
+  const sorted = [...blocks].sort((a, b) => a - b);
+  return {
+    loadRange: { start: formatC64Address(load), end: formatC64Address(Math.min(end, 0xffff)) },
+    bytes: program.length - 2,
+    basicStart: stub === undefined ? null : stub.address === undefined ? { line: stub.line, sys: null, expression: stub.expression! } : { line: stub.line, sys: formatC64Address(stub.address) },
+    entropy: {
+      blocks: blocks.length,
+      highBlocks: high,
+      median: sorted.length === 0 ? null : Number(sorted[sorted.length >> 1]!.toFixed(2)),
+    },
+    basicText,
+    strings: readableStrings(body.subarray(0, 1024)),
+    start: signals.start,
+    decodeLoops: signals.decodeLoops,
+    packing,
+    evidence:
+      packing === "likely"
+        ? `${high} of ${blocks.length} blocks of 256 bytes look compressed (above ${HIGH_ENTROPY} bits per byte); code and data are usually below.`
+        : packing === "unlikely"
+          ? `Only ${high} of ${blocks.length} blocks look compressed; the bytes look like code and data. A simple cruncher can look the same: run trace to see if the program writes code and then executes it.`
+          : startMoves && byEntropy === "unlikely"
+            ? "The bytes look like code and data, but the code at the SYS address decodes or moves bytes outside the program. Run trace or stages to see what it writes and runs."
+            : "The entropy does not show clearly if the program is packed. Run it and look at what it writes to memory.",
+  };
+}
+
+/** One range of the emulator's memory map: what the program did with these addresses. */
+export interface AccessRange {
+  start: number;
+  end: number;
+  read: boolean;
+  write: boolean;
+  execute: boolean;
+}
+
+/**
+ * Reads the memory map of $0000-$ffff in address order. One `read` gives a
+ * limited number of ranges, and `next` when more follow: the next read starts there.
+ */
+export async function readMemoryMap(read: (start: number) => Promise<{ ranges: AccessRange[]; next?: number }>): Promise<AccessRange[]> {
+  const ranges: AccessRange[] = [];
+  for (let start: number | undefined = 0; start !== undefined; ) {
+    const found: { ranges: AccessRange[]; next?: number } = await read(start);
+    ranges.push(...found.ranges);
+    if (found.next !== undefined && found.next <= start) throw new Error(`the memory map did not move on from ${start}`);
+    start = found.next;
+  }
+  return ranges;
+}
+
+/** ROM areas: an address here can be written (RAM below) and executed (ROM) without one being the other. */
+export const underRom = (address: number) => (address >= 0xa000 && address <= 0xbfff) || address >= 0xe000;
+
+/**
+ * The memory that the program wrote and then executed, in pieces of code.
+ * `bytes` and `running` count only RAM outside the ROM areas: a write under
+ * a ROM and code that runs in that ROM are not one piece of code.
+ */
+export function writtenThenExecuted(
+  ranges: AccessRange[],
+  pc: number,
+): { written: Array<{ start: number; end: number }>; counted: Array<{ start: number; end: number }>; bytes: number; running?: { start: number; end: number } } {
+  // VICE marks only opcode bytes as executed; a gap of at most two operand bytes stays inside one piece of code.
+  const written: Array<{ start: number; end: number }> = [];
+  for (const range of ranges.filter((candidate) => candidate.write && candidate.execute)) {
+    const last = written.at(-1);
+    if (last !== undefined && range.start - last.end <= 3 && underRom(range.start) === underRom(last.start)) last.end = range.end;
+    else written.push({ start: range.start, end: range.end });
+  }
+  const counted = written.filter((range) => !underRom(range.start));
+  const bytes = counted.reduce((sum, range) => sum + range.end - range.start + 1, 0);
+  const running = counted.find((range) => pc >= range.start && pc <= range.end);
+  return { written, counted, bytes, ...(running === undefined ? {} : { running }) };
+}

package/skills/c64-unpacker/scripts/loads.ts

@@ -0,0 +1,209 @@
+// The loads command of c64-unpacker (D53): 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
+// knowledge space drive8. No tool guesses where a load ends: the steps decide.
+
+import { COVERAGE, formatC64Address, parseC64Address } from "#src/c64.ts";
+import { autostartLoaded, LOAD_LIMIT_FRAMES, RUN_LIMIT_FRAMES, typeRun } from "#src/host-client/autostart.ts";
+import { readCoverage } from "#src/host-client/coverage.ts";
+import { ACTION_STEP_KEYS, ACTION_STEP_KINDS, checkActionStep, isObject, 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 { ViceSessionClient } from "#src/host-client/vice-session.ts";
+import { UsageError } from "#src/script.ts";
+import { entryState, json, machineState, readRam, vectorsOf } from "./machine.ts";
+
+export type LoadStep = ActionStep | { capture: string };
+
+/** A capture name: letters, digits, dots, underscores or hyphens. */
+const NAME = /^[A-Za-z0-9._-]{1,64}$/;
+/** The drive RAM of a 1541. */
+const DRIVE_RAM = 0x0800;
+/** Pages 0-3 belong to the entry state, not to the segments. */
+const FIRST_SEGMENT_ADDRESS = 0x0400;
+/** The KERNAL LOAD entry in the jump table. */
+const KERNAL_LOAD = 0xffd5;
+/** The KERNAL loop that waits for a key at READY. or at an INPUT statement. */
+const KERNAL_KEY_WAIT = { start: 0xe5cd, end: 0xe5d5 };
+
+/** Reads and checks the steps file of loads: action steps with $ addresses, and capture steps with new names. */
+export function readLoadSteps(path: string): LoadStep[] {
+  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}`);
+  }
+  const fail = (message: string): never => {
+    throw new UsageError(`--steps ${path}: ${message}`);
+  };
+  if (!Array.isArray(value) || value.length === 0) return fail("the steps are a JSON list with at least one step");
+  const names = new Set<string>();
+  value.forEach((step: unknown, index) => {
+    const at = `step ${index + 1}`;
+    if (!isObject(step)) return fail(`${at} must be an object`);
+    if ("capture" in step) {
+      if (Object.keys(step).length !== 1) fail(`${at}: a capture step has only capture`);
+      if (typeof step.capture !== "string" || !NAME.test(step.capture)) fail(`${at}: capture needs a name of 1 to 64 letters, digits, dots, underscores or hyphens`);
+      if (names.has(step.capture as string)) fail(`${at}: the capture name ${step.capture as string} is used before`);
+      names.add(step.capture as string);
+      return;
+    }
+    const kinds = Object.keys(step).filter((key) => (ACTION_STEP_KINDS as readonly string[]).includes(key));
+    if (kinds.length !== 1) return fail(`${at} must have exactly one of ${[...ACTION_STEP_KINDS, "capture"].join(", ")}`);
+    const kind = kinds[0]!;
+    const allowed = 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`);
+    checkActionStep(kind, step, at, fail, false);
+  });
+  if (names.size === 0) fail("the steps have no capture step");
+  return value as 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).
+ * Without it, the KERNAL RAM test wrote all of RAM after the map was cleared,
+ * and only the changed bytes count.
+ */
+export function changedBlocks(before: Uint8Array, after: Uint8Array, map: Uint8Array, join: number, writesKnown: boolean): Array<{ start: number; end: number; bytes: number }> {
+  const blocks: Array<{ start: number; end: number; bytes: number; changed: boolean }> = [];
+  for (let address = FIRST_SEGMENT_ADDRESS; address < 0x10000; address++) {
+    const changed = before[address] !== after[address];
+    if ((map[address]! & COVERAGE.ramWrite) === 0 || (!writesKnown && !changed)) continue;
+    const last = blocks.at(-1);
+    if (last !== undefined && address - last.end <= join) {
+      last.end = address;
+      last.bytes++;
+      last.changed ||= changed;
+    } else blocks.push({ start: address, end: address, bytes: 1, changed });
+  }
+  return blocks.filter((block) => block.changed).map(({ start, end, bytes }) => ({ start, end, bytes }));
+}
+
+const hex4 = (value: number) => value.toString(16).padStart(4, "0");
+
+/**
+ * Runs the program and its steps. Each capture step writes <out>/<name>/:
+ * image.bin, image.json, entry_state.json, a PRG for each segment, and with
+ * `drive` the drive RAM as drive8.prg. Blocks below `minBlock` bytes are
+ * counted, not written: a game changes its variables all the time.
+ */
+export async function loads(program: string, options: { out: string; steps: LoadStep[]; drive: boolean; minBlock: number }): Promise<{ output: Record<string, unknown>; failed: boolean }> {
+  const client = await ViceSessionClient.open({ videoStandard: "pal" });
+  try {
+    await client.reset({ mode: "hard", run: false });
+    let previous: Buffer;
+    /** A PRG that autostart put into memory without the CPU: its bytes count as written in the first capture. */
+    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). */
+    let emulatorFlaw: string | undefined;
+    if (program.toLowerCase().endsWith(".prg")) {
+      const { bytes } = readProjectFile(program);
+      if (!(await autostartLoaded(client, program, bytes))) return { output: { loaded: false, reason: `The program was not in memory after ${LOAD_LIMIT_FRAMES} frames.` }, failed: true };
+      // The RAM before RUN, without the program, so the first capture holds the program too.
+      previous = await readRam(client, 0x0000, 0x10000);
+      const load = bytes[0]! | (bytes[1]! << 8);
+      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).
+      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.
+      previous = await readRam(client, 0x0000, 0x10000);
+      await client.memmap({ action: "clear" });
+      ({ emulatorFlaw } = await client.autostart({ path: program, index: 0, run: true }));
+      writesKnown = false;
+      if (!program.toLowerCase().endsWith(".crt")) {
+        // The map starts again where the KERNAL LOAD starts, after the RAM test: then it holds only what the program wrote.
+        const load = await client.runUntil({ target: { kind: "address", address: KERNAL_LOAD, space: "c64" }, timeoutFrames: LOAD_LIMIT_FRAMES });
+        if (load.reached) {
+          await client.memmap({ action: "clear" });
+          writesKnown = true;
+        }
+      }
+    }
+
+    const captures: Array<Record<string, unknown>> = [];
+    for (const [index, step] of options.steps.entries()) {
+      if (!("capture" in step)) {
+        const notReached = await runActionStep(client, step, parseC64Address);
+        if (notReached !== undefined && "runUntil" in step) {
+          const reason = `Step ${index + 1} did not reach its target in ${step.timeoutFrames} frames. It stopped by ${notReached.stopReason} at ${formatC64Address(notReached.pc)}.`;
+          return { output: { loaded: false, reason, captures }, failed: true };
+        }
+        continue;
+      }
+      if ((await client.status()).state === "running") await client.execution({ action: "pause", space: "c64" });
+      const registers = await client.registersGet("c64");
+      const memory = await readRam(client, 0x0000, 0x10000);
+      const map = await readCoverage(client);
+      if (loadedProgram !== undefined) {
+        // The PRG itself is part of the first capture.
+        const load = loadedProgram[0]! | (loadedProgram[1]! << 8);
+        for (let address = load; address < Math.min(0x10000, load + loadedProgram.length - 2); address++) map[address]! |= COVERAGE.ramWrite;
+        loadedProgram = undefined;
+      }
+      const blocks = changedBlocks(previous, memory, map, 16, writesKnown);
+      const segments = blocks.filter((block) => block.end - block.start + 1 >= options.minBlock);
+      const small = blocks.filter((block) => !segments.includes(block)).reduce((sum, block) => sum + block.bytes, 0);
+      const state = await machineState(client);
+      const vectors = vectorsOf(state, memory);
+      const directory = `${options.out}/${step.capture}`;
+      const write = (name: string, bytes: Uint8Array) => writeProjectFile(`${directory}/${name}`, bytes, { what: "--out" });
+      write("image.bin", memory);
+      const files = segments.map((segment) => {
+        const name = `segment-${hex4(segment.start)}-${hex4(segment.end)}.prg`;
+        write(name, Buffer.concat([Buffer.from([segment.start & 0xff, segment.start >> 8]), memory.subarray(segment.start, segment.end + 1)]));
+        return name;
+      });
+      let drive: Record<string, unknown> | undefined;
+      if (options.drive) {
+        const ram = Buffer.from((await client.memoryRead({ address: 0x0000, size: DRIVE_RAM, space: "drive8", view: "cpu" })).data, "hex");
+        write("drive8.prg", Buffer.concat([Buffer.from([0x00, 0x00]), ram]));
+        drive = { file: "drive8.prg", pc: formatC64Address((await client.registersGet("drive8")).pc), space: "drive8" };
+      }
+      const showRange = (range: { start: number; end: number }) => ({ start: formatC64Address(range.start), end: formatC64Address(range.end) });
+      write(
+        "image.json",
+        json({
+          capture: step.capture,
+          entry: formatC64Address(registers.pc),
+          segments: segments.map((segment, at) => ({ ...showRange(segment), file: files[at] })),
+          vectors,
+          image: "image.bin",
+          ...(drive === undefined ? {} : { drive }),
+        }),
+      );
+      write("entry_state.json", json(entryState(registers, state, vectors)));
+      const keyWait = registers.pc >= KERNAL_KEY_WAIT.start && registers.pc <= KERNAL_KEY_WAIT.end;
+      captures.push({
+        capture: step.capture,
+        out: directory,
+        pc: formatC64Address(registers.pc),
+        ...(keyWait ? { keyWait: true } : {}),
+        segments: segments.map(showRange),
+        ...(small === 0 ? {} : { smallChanges: small }),
+        ...(drive === undefined ? {} : { drive: drive.file }),
+      });
+      previous = memory;
+      await client.memmap({ action: "clear" });
+      writesKnown = true;
+    }
+    if (captures.length > 0 && captures.every((capture) => (capture.segments as unknown[]).length === 0)) {
+      const waits = captures.some((capture) => capture.keyWait === true) ? " The C64 waited for a key at READY. or at an INPUT statement, so the load ended or did not start." : "";
+      const reason = `No capture has a segment: the program changed no block of RAM from ${formatC64Address(FIRST_SEGMENT_ADDRESS)} on.${waits}`;
+      return { output: { loaded: false, reason, captures, ...(emulatorFlaw === undefined ? {} : { emulatorFlaw }) }, failed: true };
+    }
+    return { output: { loaded: true, captures }, failed: false };
+  } finally {
+    await client.close();
+  }
+}

package/skills/c64-unpacker/scripts/machine.ts

@@ -0,0 +1,80 @@
+// The machine state that a capture writes (D43): 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.
+
+import { formatC64Address } from "#src/c64.ts";
+import type { ViceSessionClient } from "#src/host-client/vice-session.ts";
+
+type Registers = Awaited<ReturnType<ViceSessionClient["registersGet"]>>;
+
+const MAX_READ = 4096;
+
+/** The I/O areas of the entry state, read without side effects (D43). */
+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). */
+export interface CiaHidden {
+  latchA: number;
+  latchB: number;
+  interruptMask: number;
+}
+
+export interface MachineState {
+  port: Buffer;
+  pages: Buffer;
+  io: Record<keyof typeof IO_AREAS, Buffer>;
+  /** The timer latches and the interrupt mask of each CIA. */
+  cia: { cia1: CiaHidden; cia2: CiaHidden };
+  romVectors: Buffer;
+}
+
+/** Reads `size` bytes from `address` in the RAM view, in parts. */
+export async function readRam(client: ViceSessionClient, address: number, size: number): Promise<Buffer> {
+  const parts: Buffer[] = [];
+  for (let at = address; at < address + size; at += MAX_READ) {
+    parts.push(Buffer.from((await client.memoryRead({ address: at, size: Math.min(MAX_READ, address + size - at), space: "c64", view: "ram" })).data, "hex"));
+  }
+  return Buffer.concat(parts);
+}
+
+/** The state the program finds at its entry: what a rebuild's loader must recreate. */
+export async function machineState(client: ViceSessionClient): Promise<MachineState> {
+  const port = Buffer.from((await client.memoryRead({ address: 0x0000, size: 2, space: "c64", view: "cpu" })).data, "hex");
+  const pages = await readRam(client, 0x0000, 0x400);
+  const io = {} as Record<keyof typeof IO_AREAS, Buffer>;
+  for (const [name, [address, size]] of Object.entries(IO_AREAS)) io[name as keyof typeof IO_AREAS] = Buffer.from((await client.ioRead(address, size)).data, "hex");
+  const [cia1, cia2] = (await client.cia("both")).chips.map(({ latchA, latchB, interruptMask }) => ({ latchA, latchB, interruptMask }));
+  const romVectors = Buffer.from((await client.memoryRead({ address: 0xfffa, size: 6, space: "c64", view: "cpu" })).data, "hex");
+  return { port, pages, io, cia: { cia1: cia1!, cia2: cia2! }, romVectors };
+}
+
+const word = (bytes: Buffer, offset: number) => formatC64Address(bytes[offset]! | (bytes[offset + 1]! << 8));
+
+/** The KERNAL vectors in page 3, the hardware vectors in RAM, and the ROM's own. */
+export function vectorsOf(state: MachineState, memory: Buffer) {
+  return {
+    irq: word(state.pages, 0x314),
+    brk: word(state.pages, 0x316),
+    nmi: word(state.pages, 0x318),
+    ram: { nmi: word(memory, 0xfffa), reset: word(memory, 0xfffc), irq: word(memory, 0xfffe) },
+    rom: { nmi: word(state.romVectors, 0), reset: word(state.romVectors, 2), irq: word(state.romVectors, 4) },
+  };
+}
+
+/** The content of entry_state.json; `differsFromReset` only when the caller compared with a clean reset. */
+export function entryState(registers: Registers, state: MachineState, vectors: ReturnType<typeof vectorsOf>, differsFromReset?: Array<{ address: string; entry: number; reset: number }>) {
+  return {
+    registers: { pc: formatC64Address(registers.pc), a: registers.a, x: registers.x, y: registers.y, sp: registers.sp, flags: registers.flags },
+    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).
+    cia: state.cia,
+    vectors,
+    ...(differsFromReset === undefined ? {} : { differsFromReset }),
+  };
+}
+
+export const json = (value: unknown) => Buffer.from(`${JSON.stringify(value, null, 2)}\n`);