@henols/c64-re-tools 2.1.0 → 2.1.2

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

@@ -5,7 +5,9 @@
 // checklist gives the Markdown list for a human tester.
 
 import { COVERAGE } from "#src/c64.ts";
+import { isRefusal, Refusal } from "#src/errors.ts";
 import { WireFailure } from "#src/host-client/tools.ts";
+import { readPrg } from "#src/host-client/image.ts";
 import { writeReported } from "#src/host-client/transfer.ts";
 import { ViceSessionClient } from "#src/host-client/vice-session.ts";
 import { C64RunSession, PAL_FRAME_CYCLES } from "#src/native/c64run.ts";
@@ -18,7 +20,7 @@ import { play } from "./lib/play.ts";
 import { readRecordFile, record, RECORDING_FILES } from "./lib/recording.ts";
 import { replay } from "./lib/replay.ts";
 import { runFile } from "./lib/runs.ts";
-import { readScenario, runScenario, type Scenario, type ScenarioResult } from "./lib/scenario.ts";
+import { namesOf, readScenario, runScenario, scenarioNames, type Scenario, type ScenarioResult } from "./lib/scenario.ts";
 
 /** The default port of the --play page: next to the Host Runtime's 6464. */
 const DEFAULT_HTTP_PORT = 6465;
@@ -35,6 +37,8 @@ const ALWAYS = [
 async function test(call: Call): Promise<ScenarioResult> {
   const scenario = readScenario(call.subject(0));
   const out = call.string("out");
+  // Every file of the scenario is checked before the emulator starts.
+  const names = scenarioNames(scenario);
   let client: ViceSessionClient;
   try {
     client = await ViceSessionClient.open({ videoStandard: scenario.videoStandard ?? "pal" });
@@ -43,7 +47,7 @@ async function test(call: Call): Promise<ScenarioResult> {
     return { result: "INCONCLUSIVE", scenario: scenario.name, reason: `no emulator: ${error.message}`, checkpoints: [], differences: [] };
   }
   try {
-    return await runScenario(client, scenario, out === undefined ? {} : { out });
+    return await runScenario(client, scenario, { names, ...(out === undefined ? {} : { out }) });
   } finally {
     await client.close();
   }
@@ -56,6 +60,15 @@ async function recordCommand(call: Call): Promise<Record<string, unknown>> {
   const httpPort = call.count("http-port") ?? DEFAULT_HTTP_PORT;
   const out = call.string("out")!;
   const file = readRecordFile(call.subject(0));
+  // The program and the symbols are checked before the replay core starts.
+  for (const [field, check] of [["program", () => readPrg(file.program)], ["symbols", () => namesOf(file.symbols)]] as const) {
+    try {
+      check();
+    } catch (error) {
+      if (isRefusal(error)) throw new Refusal(error.code, `record file ${call.subject(0)}: ${field}: ${error.message}`);
+      throw error;
+    }
+  }
   const context = localToolContext();
   const core = await C64RunSession.open(context);
   const workspace = Workspace.create(context.supervisor, "c64-re-tools-record-");
@@ -110,14 +123,14 @@ const COMMANDS: CommandSpec[] = [
     name: "test",
     summary: "Runs a scenario on the original and then on the rebuild in one emulator. result is PASS, FAIL with the differences, or INCONCLUSIVE with the reason.",
     subjects: [{ name: "<scenario.json>", help: "a scenario file, relative to the project folder. See references/scenario-format.md" }],
-    options: { out: { ...OPTIONS.out, value: "<dir>", help: "with a FAIL, write both screens, the difference image and memory.json with each differing byte into this folder" } },
+    options: { out: { ...OPTIONS.out, output: "folder", value: "<dir>", help: "with a FAIL, write both screens, the difference image and memory.json with each differing byte into this folder" } },
     run: test,
   },
   {
     name: "run",
     summary: "Runs the steps of a run file in its own emulator and writes what they ask for into --out: screens, coverage maps, snapshot files, traces, and results.json with the observations. result is FAIL when a step did not run.",
     subjects: [{ name: "<run.json>", help: "a run file, relative to the project folder. See references/scenario-format.md, section Runs" }],
-    options: { out: { ...OPTIONS.out, value: "<dir>", required: true, help: "the folder for the files of the steps and results.json" } },
+    options: { out: { ...OPTIONS.out, output: "folder", value: "<dir>", required: true, help: "the folder for the files of the steps and results.json" } },
     run: async (call) => {
       const { output, failed } = await runFile(call.subject(0), call.string("out")!);
       return { result: failed ? "FAIL" : "PASS", ...output };
@@ -128,7 +141,7 @@ const COMMANDS: CommandSpec[] = [
     summary: "Plays the steps of a record file on the original in the replay core (c64run), and writes the session as a recording folder: recording.json, reads.txt and coverage.bin. result is FAIL when the session did not complete.",
     subjects: [{ name: "<record.json>", help: "a record file, relative to the project folder. See references/recording-format.md" }],
     options: {
-      out: { ...OPTIONS.out, value: "<dir>", required: true, help: "the recording folder, for example tests/recordings/<name>" },
+      out: { ...OPTIONS.out, output: "folder", value: "<dir>", required: true, help: "the recording folder, for example tests/recordings/<name>" },
       play: { kind: "flag", help: "a person plays after the steps: the script prints the address of a page on stderr. The page shows the start screen frozen until Start (Enter). End (F12) saves the recording, Cancel (F11) ends without one" },
       joystick: { kind: "count", value: "<1|2>", min: 1, max: 2, help: "with --play: the joystick port that the program reads, at the start (default 2). F9 on the page changes it" },
       "http-port": { kind: "count", value: "<n>", min: 0, max: 65535, help: `with --play: the port of the page (default ${DEFAULT_HTTP_PORT})` },
@@ -145,7 +158,7 @@ const COMMANDS: CommandSpec[] = [
       pin: { kind: "text", value: "<item>", multiple: true, help: `random state in RAM, in the form of --state: at each checkpoint the rebuild gets the original's values there` },
       rebuild: { kind: "path", value: "<prg>", help: "the rebuild to compare with the original" },
       symbols: { ...OPTIONS.symbols, help: "the names of the rebuild: the c64-assembler output (default: the symbols of the recording)" },
-      out: { ...OPTIONS.out, value: "<dir>", help: "with a FAIL, write the RAM of both sides at the first different checkpoint into this folder" },
+      out: { ...OPTIONS.out, output: "folder", value: "<dir>", help: "with a FAIL, write the RAM of both sides at the first different checkpoint into this folder" },
     },
     notes: "A recording without names takes the names of the knowledge for the original. A $ address is an address of the original: on the rebuild it moves with the name before it.",
     run: (call) => {
@@ -165,7 +178,7 @@ const COMMANDS: CommandSpec[] = [
       "max-listed": OPTIONS["max-listed"],
       ntsc: { kind: "flag", help: "the snapshots are of an NTSC machine (default PAL)" },
       address: { kind: "address", value: "<address>", help: "the address of the first byte of a memory file that is shorter than 64 KiB" },
-      out: { ...OPTIONS.out, value: "<file>", help: "also write all ranges to this file" },
+      out: { ...OPTIONS.out, output: "file", value: "<file>", help: "also write all ranges to this file" },
     },
     run: (call) => {
       const [address, out] = [call.address("address"), call.string("out")];

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 folder.
+- The program: a PRG file, relative to the project folder. `inspect`, `trace`, `stages` and `capture` refuse a disk, tape or cartridge image. For such an image, use `loads`, or get the PRG with `disk.ts read` of the c64-disk skill.
 - For a capture: the address where the unpacked program starts, and the directory for the result.
 
 ## Tools / execution path
@@ -26,25 +26,26 @@ node <skill>/scripts/unpacker.ts capture original/game.prg --until '$c000' --out
 node <skill>/scripts/unpacker.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`, `stages`, `capture` and `loads` 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. `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`). `capture` stops the program when the CPU gets to the `--until` address. In `stages` and `capture`, a `frames` step and a `runUntil` step to an address without a condition count as run time. `stages` refuses a different `runUntil` step.
+`inspect` examines the file locally. `trace`, `stages`, `capture` and `loads` 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. `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`). `wrote` lists each block that the stage wrote, also a small block. `capture` stops the program when the CPU gets to the `--until` address. In `stages` and `capture`, a `frames` step and a `runUntil` step to an address without a condition count as run time. `stages` refuses a different `runUntil` step.
 
 | Option | Meaning |
 |---|---|
 | `--until '$c000'` | `capture`: 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 .c64-re-tools/local/capture` | `capture` and `loads`: the folder for the result, relative to the project folder. |
-| `--range '$c000-$cfff'` | `capture` only: write this range as the one segment. Without it, the segments are the blocks that the stages wrote. |
-| `--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. |
+| `--range '$c000-$cfff'` | `capture` only: write this range as the one segment. Without it, the segments are the blocks that the stages wrote. The range must hold the `--until` address. |
+| `--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 range must not hold the `--until` address. |
 | `--timeout-frames 3000` | `capture` only: how many frames the program can run before the capture stops (default 3000). |
 | `--frames 3000` | `trace` and `stages`: 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. |
+| `--max-listed 50` | `trace` only: the most ranges that `writtenThenExecuted` lists (default 50). |
 | `--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). |
+| `--min-stage 64` | `stages` and `capture`: the smallest block of written memory that starts a new stage when the CPU executes it (default 64). It does not change `wrote` or the segments. |
 
-The capture reads RAM, also the RAM under the ROMs and the I/O area. The script refuses an option that the command does not use.
+The capture reads RAM, also the RAM under the ROMs and the I/O area. The script refuses an option that the command does not use. It refuses a wrong `--range` or `--exclude` before the emulator starts.
 
-A steps file is a JSON list of steps. Each step has the input of the MCP tool of the same action. An address in a step can be a name. For example, wait 50 frames and type a space:
+A steps file is a JSON list of steps. Each step has the input of the MCP tool of the same action. An address in a step can be a name. The script refuses an unknown name before the emulator starts. The message gives the file and the step. For example, wait 50 frames and type a space:
 
 ```json
 [{ "frames": 50 }, { "type": { "mode": "text", "text": " " } }]
@@ -59,6 +60,8 @@ A steps file is a JSON list of steps. Each step has the input of the MCP tool of
 
 A program that reads the keyboard matrix does not see the keys of a `type` step. These scripts refuse a `press` step. A wait for any key that reads all keyboard columns can end without a key.
 
+The scripts refuse a step in the form of version 2.0, for example `{ "runUntil": { "at": "main_loop" }, "timeoutFrames": 300 }`. The message names the old field and gives the step to write.
+
 ### Calling the script
 
 - Call a script as `node <skill>/scripts/<script>.ts <command> [subjects] [options]`. The command comes first.
@@ -66,6 +69,7 @@ A program that reads the keyboard matrix does not see the keys of a `type` step.
 - An address is `$` and 1 to 4 hex digits, for example `'$c000'` or `'$fb'`, or a name. A name is a symbol, else an analyzer name that only one analyzer gives. Quote an address in a shell.
 - A range is `<start>-<end>`, for example `'$c000-$cfff'`. In a JSON file, a range is `start` and `end`.
 - Bytes in a JSON file are hex in a field `data`, for example `"data": "a900"`.
+- The script examines each `--out` path before it starts work. It refuses a path in `.c64-re-tools/knowledge/` and the index of the knowledge, because only c64-knowledge writes them. It refuses a folder where the command writes a file, and a file where the command writes a folder.
 - The result is one JSON object on one line. A file that the script writes shows as `{"out", "bytes", "sha256"}`. A list shows as `{"count", "listed"}`, and `rest` tells where to get the rest of a long list.
 - An error is `{"error": {"code": "...", "message": "..."}}`. The message tells what is wrong and what to do.
 - The exit status is 0 for done or PASS, 1 for FAIL, 2 for an error and 3 for INCONCLUSIVE.
@@ -92,7 +96,7 @@ A program that reads the keyboard matrix does not see the keys of a `type` step.
    - `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`:
+2. Run `trace`. It gives the evidence from the run. `writtenThenExecuted` lists the ranges that the program wrote and then executed. 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.
@@ -104,7 +108,7 @@ A program that reads the keyboard matrix does not see the keys of a `type` step.
    - 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.
+   - `image.json`: the entry, the segments, the vectors and the stages. A segment is a block that a stage wrote, also a small block. 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. A block that a stage before the program wrote in such a block is also not a segment, for example a variable of a loader. A block that is fully in pages 0 to 3 is not a segment, because `entry_state.json` holds these pages. 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. Then capture again with `--exclude` for that range. Thus the source and the loader do not include the range.
@@ -147,11 +151,14 @@ The packing evidence, the stages, or the unpacked program with its image, segmen
 
 `trace`, `stages`, `capture` and `loads` give `result: "PASS"` or `result: "FAIL"`. A FAIL has `reason`. `capture` gives the written files in `files`, each as `{out, bytes, sha256}`.
 
-For `loads`: `captures`, with the name, the PC, the segments, the files and the drive file of each capture. `keyWait: true` tells that the CPU was in the KERNAL wait for a key.
+`capture` gives `differsFromReset`: the count of bytes that are not as a clean C64 has them at READY.
+
+For `loads`: `captures`, with the name, the PC, the segments, `differsFromReset`, the files and the drive file of each capture. Each `entry_state.json` of `loads` has `differsFromReset` as the one of `capture` has. `keyWait: true` tells that the CPU was in the KERNAL wait for a key.
 
 ## Failure and conflicts
 
 - `traced: false` or `followed: 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.
+- `traced: false` or `followed: false` with `stopReason`: the CPU stopped before the frames ran, for example at a JAM instruction. `pc` gives the address. Make sure that `--entry` is the start of the code that the file holds at that time, and that the steps are correct.
 - `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 `type` step.
 - 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.

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

@@ -1,7 +1,7 @@
 // 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";
+import { basicLineText, findHandoffs, formatC64Address, instructionLength, parseTokenized, prgRange } from "#src/c64.ts";
 import { Refusal } from "#src/errors.ts";
 
 /** A 256-byte block above this many bits per byte looks compressed. */
@@ -111,9 +111,8 @@ function startSignals(program: Uint8Array, load: number, end: number, sys: numbe
 }
 
 export function inspect(program: Uint8Array): PackingEvidence {
-  if (program.length < 3) throw new Refusal("invalid-input", "the file is too short for a PRG");
-  const load = program[0]! | (program[1]! << 8);
-  const end = load + program.length - 3;
+  // A PRG ends at $ffff or before: a longer file (a disk image) is refused.
+  const { start: load, end } = prgRange(program);
   const basic = basicStart(program);
   const stub = basic?.sys;
   // Without BASIC, all bytes count; with it, only the bytes after the BASIC text.
@@ -132,7 +131,7 @@ export function inspect(program: Uint8Array): PackingEvidence {
   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)) },
+    loadRange: { start: formatC64Address(load), end: formatC64Address(end) },
     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: {

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

@@ -7,13 +7,14 @@
 import { COVERAGE, formatC64Address } 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_KINDS, checkActionStep, isObject, runActionStep, type ActionStep, type ActionStepKind } from "#src/host-client/steps.ts";
+import { ACTION_STEP_KINDS, checkActionStep, checkStepNames, isObject, runActionStep, VICE_STEP_KINDS, type ActionStep, type ActionStepKind } from "#src/host-client/steps.ts";
 import { knowledgeAt } from "#src/knowledge/names.ts";
 import { WireFailure } from "#src/host-client/tools.ts";
 import { readProjectFile, writeReported, type Written } 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";
+import { entryStateFile, json, machineState, readRam, readyState, vectorsOf } from "./machine.ts";
+import { FIRST_SEGMENT_ADDRESS } from "./stages.ts";
 
 
 export type LoadStep = ActionStep | { capture: string };
@@ -22,8 +23,6 @@ export type LoadStep = ActionStep | { capture: string };
 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. */
@@ -54,9 +53,13 @@ export function readLoadSteps(path: string): LoadStep[] {
       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(", ")}`);
+    if (kinds.length > 1) return fail(`${at} has ${kinds.length} step kinds: ${kinds.join(", ")}. Give each one its own step`);
+    if (kinds.length !== 1) return fail(`${at} must have exactly one of ${[...VICE_STEP_KINDS, "capture"].join(", ")}`);
     // The step with its defaults filled in, as the shared schema of the action steps gives it.
-    (value as unknown[])[index] = checkActionStep(kinds[0] as ActionStepKind, step, at, fail);
+    const checked = checkActionStep(kinds[0] as ActionStepKind, step, at, fail);
+    // Its names resolve now: an unknown name stops the call before the emulator starts.
+    checkStepNames([checked], knowledgeAt(), `--steps ${path}`, index + 1);
+    (value as unknown[])[index] = checked;
   });
   if (names.size === 0) fail("the steps have no capture step");
   return value as LoadStep[];
@@ -96,6 +99,8 @@ const hex4 = (value: number) => value.toString(16).padStart(4, "0");
 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 {
+    // A clean machine at the READY prompt shows what the program changed at each capture. The run goes on after a capture, so it is read first.
+    const clean = await readyState(client);
     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. */
@@ -183,7 +188,8 @@ export async function loads(program: string, options: { out: string; steps: Load
           ...(drive === undefined ? {} : { drive }),
         }),
       );
-      write("entry_state.json", json(entryState(registers, state, vectors)));
+      const entry = entryStateFile(registers, state, vectors, clean);
+      write("entry_state.json", entry.bytes);
       const keyWait = registers.pc >= KERNAL_KEY_WAIT.start && registers.pc <= KERNAL_KEY_WAIT.end;
       captures.push({
         capture: step.capture,
@@ -192,6 +198,7 @@ export async function loads(program: string, options: { out: string; steps: Load
         pc: formatC64Address(registers.pc),
         ...(keyWait ? { keyWait: true } : {}),
         segments: segments.map(showRange),
+        differsFromReset: entry.differsFromReset,
         ...(small === 0 ? {} : { smallChanges: small }),
         ...(drive === undefined ? {} : { drive: drive.file }),
       });

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

@@ -3,6 +3,7 @@
 // capture and loads commands of the unpacker share it.
 
 import { formatC64Address } from "#src/c64.ts";
+import { resetToReady } from "#src/host-client/entry-state.ts";
 import type { ViceSessionClient } from "#src/host-client/vice-session.ts";
 
 type Registers = Awaited<ReturnType<ViceSessionClient["registersGet"]>>;
@@ -61,8 +62,34 @@ export function vectorsOf(state: MachineState, memory: Buffer) {
   };
 }
 
-/** 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 }>) {
+/** The state of a clean machine at the READY prompt after a hard reset: what differsFromReset compares with. It resets the machine. */
+export async function readyState(client: ViceSessionClient): Promise<MachineState> {
+  await resetToReady(client);
+  return machineState(client);
+}
+
+/** The bytes that differ from a clean machine: the CPU port, pages 0-3 from $0002, and the I/O areas. */
+export function differsFrom(state: MachineState, clean: MachineState): Array<{ address: string; entry: number; reset: number }> {
+  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]! }));
+  compare(0x0000, state.port, clean.port);
+  compare(0x0002, state.pages.subarray(2), clean.pages.subarray(2));
+  for (const [name, [address]] of Object.entries(IO_AREAS)) compare(address, state.io[name as keyof typeof IO_AREAS], clean.io[name as keyof typeof IO_AREAS]);
+  return differs;
+}
+
+/**
+ * entry_state.json, the one writer of capture and loads: the state at the
+ * entry, and what differs from `clean` (readyState). Gives the file and the
+ * count of differing bytes.
+ */
+export function entryStateFile(registers: Registers, state: MachineState, vectors: ReturnType<typeof vectorsOf>, clean: MachineState): { bytes: Buffer; differsFromReset: number } {
+  const differs = differsFrom(state, clean);
+  return { bytes: json(entryState(registers, state, vectors, differs)), differsFromReset: differs.length };
+}
+
+/** The content of entry_state.json. */
+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] },
@@ -71,7 +98,7 @@ export function entryState(registers: Registers, state: MachineState, vectors: R
     // 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 }),
+    differsFromReset,
   };
 }
 

package/skills/c64-unpacker/scripts/lib/stages.ts

@@ -93,25 +93,33 @@ export function executedIn(map: Uint8Array, block: AddressRange): AddressRange[]
   return ranges;
 }
 
+/** Pages 0-3 ($0000-$03ff) are in entry_state.json: a written block that is all in them is no segment. */
+export const FIRST_SEGMENT_ADDRESS = 0x0400;
+
 /**
  * The segments of a capture: the blocks that the stages wrote, without loader
- * leftovers, joined into ranges that do not overlap or touch. A block
+ * leftovers and without blocks that are all in pages 0-3 (the entry state
+ * holds them), 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. 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
- * range.
+ * a segment. A block that an intermediate stage wrote inside a leftover, for
+ * example a variable of the loader, is a leftover too. 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 range.
  */
 export function captureSegments(stages: ReadonlyArray<{ entry: number; wrote: readonly AddressRange[] }>, entry: number): Array<AddressRange & { writtenBy: number }> {
   const last = stages.length - 1;
   const replaced = (from: number, address: number) => stages.slice(from).some((stage) => inRanges(stage.wrote, address));
   const leftover = (block: AddressRange, writer: number) =>
     !contains(block, entry) && stages.some((stage, index) => index > writer && index < last && contains(block, stage.entry) && !replaced(index, stage.entry));
-  const blocks = stages
-    .flatMap((stage, index) => stage.wrote.map((range) => ({ start: range.start, end: range.end, writtenBy: index })))
-    .filter((block) => !leftover(block, block.writtenBy))
+  const written = stages.flatMap((stage, index) => stage.wrote.map((range) => ({ start: range.start, end: range.end, writtenBy: index })));
+  const leftovers = written.filter((block) => leftover(block, block.writtenBy));
+  const inLeftover = (block: AddressRange & { writtenBy: number }) =>
+    block.writtenBy < last && !contains(block, entry) && leftovers.some((left) => block.start >= left.start && block.end <= left.end);
+  const blocks = written
+    .filter((block) => !leftover(block, block.writtenBy) && !inLeftover(block) && (block.end >= FIRST_SEGMENT_ADDRESS || contains(block, entry)))
     .sort((a, b) => a.start - b.start);
   const segments: Array<AddressRange & { writtenBy: number }> = [];
   for (const block of blocks) {