@henols/c64-re-tools 2.1.1 → 2.1.2

package/skills/c64-source/SKILL.md

@@ -47,6 +47,7 @@ When the knowledge has coverage, code that no run executed gets the line `; not
 - 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.

package/skills/c64-source/scripts/lib/source.ts

@@ -13,7 +13,7 @@ import { WireFailure } from "#src/host-client/tools.ts";
 import { identifiers, operandText, replaceIdentifiers, type OperandExpression } from "#src/knowledge/expression.ts";
 import { type CommentPlacement, isAnalyzer, isGeneratedFile, type Origin, type RegionType } from "#src/knowledge/schema.ts";
 import type { Area } from "#src/platform.ts";
-import { hasZeroPageForm, MNEMONICS, MODE_LENGTH, OPCODES, takesAddress, USE_KINDS, useKind, type Mode, type UseKind } from "#src/opcodes.ts";
+import { hasZeroPageForm, instructionWith, labelProblem, MODE_LENGTH, OPCODES, takesAddress, USE_KINDS, useKind, type UseKind } from "#src/opcodes.ts";
 
 export interface SourceInput {
   /** In address order, without overlap. */
@@ -319,7 +319,7 @@ export function layout(input: SourceInput): Layout {
   const outside = new Set<number>();
   // A platform name that knowledge gives to another address, or that reads as an instruction, is not used.
   const knowledgeNames = new Set(input.symbols.map((symbol) => symbol.name));
-  const platform = new Map((input.platform ?? []).filter(({ name }) => !knowledgeNames.has(name) && !MNEMONICS.has(name.toLowerCase())).map(({ address, name }) => [address, name]));
+  const platform = new Map((input.platform ?? []).filter(({ name }) => !knowledgeNames.has(name) && labelProblem(name) === undefined).map(({ address, name }) => [address, name]));
   // An analyzer name (DXA's ld020) gives way to the platform name (EXTCOL); a user or LLM name wins.
   const symbols = new Map(input.symbols.filter((symbol) => !(isAnalyzer(symbol.origin) && platform.has(symbol.address))).map((symbol) => [symbol.address, symbol.name]));
   /** Addresses outside the image without a name of their own, inside a named platform entry of more bytes: the start of that entry. */
@@ -450,7 +450,8 @@ export function layout(input: SourceInput): Layout {
   for (const address of [...wanted, ...outside].sort((a, b) => a - b)) {
     const known = symbols.get(address);
     if (known !== undefined) {
-      if (MNEMONICS.has(known.toLowerCase())) throw new WireFailure("invalid-input", `The symbol ${known} at ${formatC64Address(address)} has the name of an instruction, which ACME cannot read as a label. Rename the symbol with c64-knowledge.`);
+      const problem = labelProblem(known);
+      if (problem !== undefined) throw new WireFailure("invalid-input", `The symbol ${known} at ${formatC64Address(address)}: ${problem} Rename the symbol with c64-knowledge.`);
       names.set(address, known);
       if (inImage(address)) namedLabels++;
       continue;
@@ -574,27 +575,6 @@ export function formOf(layout: Pick<Layout, "inImage" | "byteAt">, item: Instruc
   return { key: `${item.opcode.toString(16).padStart(2, "0")}${suffix}`, opcode: item.opcode, suffix };
 }
 
-/** The instruction text with an operand expression; the expression is a name or a $ number. */
-export function instructionText(opcode: number, suffix: string, expression: string): string {
-  const { mnemonic, mode } = OPCODES[opcode]!;
-  const operand: Record<Mode, string> = {
-    imp: "",
-    imm: `#${expression}`,
-    zp: expression,
-    zpx: `${expression},x`,
-    zpy: `${expression},y`,
-    abs: expression,
-    abx: `${expression},x`,
-    aby: `${expression},y`,
-    ind: `(${expression})`,
-    izx: `(${expression},x)`,
-    izy: `(${expression}),y`,
-    rel: expression,
-  };
-  const text = operand[mode];
-  return text === "" ? `${mnemonic}${suffix}` : `${mnemonic}${suffix} ${text}`;
-}
-
 /** The plain number of an operand: what the probe assembles, and what a comment shows. */
 export function literalOperand(opcode: number, value: number): string {
   const { mode } = OPCODES[opcode]!;
@@ -1046,7 +1026,7 @@ export function render(layout: Layout, asBytes: ReadonlySet<string>, header: str
         const form = formOf(layout, item);
         const { mode } = OPCODES[item.opcode]!;
         const value = mode === "imp" ? 0 : operandValue(item.address, item.opcode, layout.byteAt)!;
-        const literal = instructionText(item.opcode, "", literalOperand(item.opcode, value));
+        const literal = instructionWith(item.opcode, literalOperand(item.opcode, value));
         let written = layout.operands.get(item.address);
         // An expression that is not written stays visible as a side comment.
         const asNumber = (expression: string, reason: string) => {
@@ -1062,13 +1042,11 @@ export function render(layout: Layout, asBytes: ReadonlySet<string>, header: str
           out.push(withSide(`${INDENT}!byte ${bytes.join(",")}`, [literal, ...sides].join(" ")));
           result.asBytes.push({ address: item.address, text: literal });
         } else if (written !== undefined) {
-          // ACME reads an operand in brackets as indirect, so a non-immediate expression does not start with one.
-          const expression = mode !== "imm" && written.startsWith("(") ? `0+${written}` : written;
-          out.push(withSide(`${INDENT}${instructionText(item.opcode, form.suffix, expression)}`, sides.length === 0 ? undefined : sides.join(" ")));
+          out.push(withSide(`${INDENT}${instructionWith(item.opcode, written, form.suffix)}`, sides.length === 0 ? undefined : sides.join(" ")));
           result.expressions.push({ address: item.address, length: item.length, file: piece.file, line: out.length });
         } else {
           const expression = takesAddress(mode) ? (layout.names.get(value) ?? literalOperand(item.opcode, value)) : literalOperand(item.opcode, value);
-          out.push(withSide(`${INDENT}${instructionText(item.opcode, form.suffix, expression)}`, sides.length === 0 ? undefined : sides.join(" ")));
+          out.push(withSide(`${INDENT}${instructionWith(item.opcode, expression, form.suffix)}`, sides.length === 0 ? undefined : sides.join(" ")));
         }
         mapLine(item.address, item.address + item.length - 1);
         result.instructions++;

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

@@ -31,8 +31,8 @@ import { resolveProjectPath } from "#src/project.ts";
 import { listed, OPTIONS, runScript, UsageError, type Call } from "#src/script.ts";
 import { knowledgeNames } from "#src/knowledge/names.ts";
 import { COPIER_SOURCE, LOADER_JUMP, loaderLimits, planLoader, rasterLine, loaderState, simulate, stopCause, VIC_DISPLAY_REGISTERS, type EntryState, type LoaderPlan } from "./lib/loader.ts";
-import { OPCODES } from "#src/opcodes.ts";
-import { entriesInData, entryOutsideImage, instructionText, layout, literalOperand, probeForms, render, switchesOf, type Layout, type PatchBlock, type Rendered } from "./lib/source.ts";
+import { instructionWith, OPCODES } from "#src/opcodes.ts";
+import { entriesInData, entryOutsideImage, layout, literalOperand, probeForms, render, switchesOf, type Layout, type PatchBlock, type Rendered } from "./lib/source.ts";
 
 /** At most this many diagnostics or differences of one check. */
 const MAX_DIAGNOSTICS = 20;
@@ -182,7 +182,7 @@ async function probe(laid: Layout): Promise<Set<string>> {
             ? formatC64Address((slot + 2 + (item.bytes[1]! < 0x80 ? item.bytes[1]! : item.bytes[1]! - 0x100)) & 0xffff)
             : literalOperand(item.form.opcode, item.bytes.length === 3 ? item.bytes[1]! | (item.bytes[2]! << 8) : item.bytes[1]!);
       lines.push(`* = ${formatC64Address(slot)}`);
-      lines.push(`        ${instructionText(item.form.opcode, item.form.suffix, operand)}`);
+      lines.push(`        ${instructionWith(item.form.opcode, operand, item.form.suffix)}`);
       lineOf.set(lines.length, item.form.key);
     });
     const built = await assembleFiles([{ name: "probe.asm", text: `${lines.join("\n")}\n` }], "probe.asm");
@@ -734,7 +734,7 @@ await runScript({
       name: "generate",
       summary: "Writes the source files, source-map.json and not_executed.json, and checks them. result is PASS when every check passes, else FAIL.",
       options: {
-        out: { ...OPTIONS.out, value: "<dir>", help: "the folder for the source files, relative to the project folder", required: true },
+        out: { ...OPTIONS.out, output: "folder", value: "<dir>", help: "the folder for the source files, relative to the project folder", required: true },
         entry: { ...OPTIONS.entry, multiple: true, help: "an entry point for Ghidra" },
         space: { ...OPTIONS.space, help: "the knowledge space of the program: c64 (the default), drive8, or bank0 to bank255. The coverage and --loader are for c64 only" },
         loader: { kind: "flag", help: "also write loader.asm and loader.prg: the loader copies the segments into place, sets the entry state of the knowledge, and jumps to the entry. It is checked in the emulator" },

package/skills/c64-static-analysis/SKILL.md

@@ -61,6 +61,7 @@ The analyzers take at most 1024 entry points. Knowledge routines and `--entry` c
 - 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.
@@ -87,6 +88,7 @@ The analyzers take at most 1024 entry points. Knowledge routines and `--entry` c
    - Ghidra: `functions` gives the number of routines that Ghidra found (`count`) and lists the first routines (`listed`). `decompilations` gives C-like code for the requested routines.
    - If a list is not complete, `rest` gives the c64-knowledge command that lists all of them. For `candidates`, `rest` tells you to give a larger `--max-listed`.
    - `conflicts` lists the places where the analyzer and the current knowledge disagree.
+   - DXA or Ghidra can find data where a run executed an instruction start (`executed`), or where a `user` or `llm` symbol of kind `label` or `routine` is (`knowledge`). Then the script does not write that data region, and the earlier region of the analyzer stays. `conflicts` lists each such place. Executed code and your names have priority over the guess of an analyzer.
    - `idioms` tells what the script found by pattern: RTS dispatch tables (`rtsTables`), JMP tables (`jumpTables`) and BIT skips (`bitSkips`). It also finds the `CBM80` header of a cartridge bank at `$8000` (`cartridgeHeaders`). The two start vectors of the header become entry points. The script writes them as knowledge with the origin `heuristic`, and seeds their targets into the same analysis. `candidates` gives DOP padding (`dop`) and opcodes that the program wrote and executed (`selfModified`). For `selfModified`, the write and the execution must be in one coverage file. A coverage file does not record the order. Thus a candidate can also be code that ran first, and that the program then wrote over. To prevent this, save one coverage file for each part of the program, for example the intro and the game. A loader that copies relocated code is also such a part. Clear the memory map between the parts. Each list has a `count`. The script does not write the candidates. Look at them and decide.
    - `candidates.pointers` gives code that makes an address from immediates. A `vector` or a `zero-page pointer` candidate stores a low byte (`low`) and a high byte (`high`) to a vector or to a zero-page pair that `(zp),y` uses. Its `target` is in the program or has a platform name. A `sprite pointer` candidate stores an immediate (`at`) to a sprite pointer of the screen at $0400 in VIC bank 0. Its `target` (the value × 64) is in a `sprite` region. For each candidate that you confirm, write operand expressions with `operand` of the c64-knowledge skill, for example `operand '<low>' --lo <target name>` and `operand '<high>' --hi <target name>`. Then a rebuild can move the target.
    - `candidates.pitfalls` gives code that a C64 runs in a different way than it reads. `raster-bit-8`: the instruction at `at` reads $D011, and the instruction at `store` writes the value back. A read of $D011 gives bit 8 of the raster line in bit 7. Thus the write can move the raster interrupt to line 256 or later, and on PAL past line 311 the interrupt never comes. Examine each candidate. Where the code must not keep bit 7, add a comment and test the program.

package/skills/c64-static-analysis/scripts/static-analysis.ts

@@ -4,7 +4,7 @@
 // structural findings into .c64-re-tools/knowledge/.
 
 import { COVERAGE, formatC64Address, prgRange } from "#src/c64.ts";
-import { Refusal } from "#src/errors.ts";
+import { isRefusal, Refusal } from "#src/errors.ts";
 import { WireFailure } from "#src/host-client/tools.ts";
 import { writeReported } from "#src/host-client/transfer.ts";
 import { knowledgeNames } from "#src/knowledge/names.ts";
@@ -121,6 +121,15 @@ function withRemedy(reason: string): string {
 
 /** One conflict: what the knowledge has, and what the analyzer found, under the analyzer's name. */
 function showConflict(conflict: ImportConflict, analyzer: Analyzer): Record<string, unknown> {
+  if (conflict.category === "code-evidence") {
+    return {
+      range: { start: formatC64Address(conflict.start), end: formatC64Address(conflict.end) },
+      [analyzer]: conflict.finding,
+      ...(conflict.executed === undefined ? {} : { executed: formatC64Address(conflict.executed) }),
+      ...(conflict.symbol === undefined ? {} : { knowledge: { ...conflict.symbol, address: formatC64Address(conflict.symbol.address) } }),
+      problem: conflict.executed !== undefined ? "a run executed code here: the data finding is not imported" : "the knowledge has a code name here: the data finding is not imported",
+    };
+  }
   if (conflict.category === "symbol") {
     return {
       at: formatC64Address(conflict.address),
@@ -270,7 +279,7 @@ async function analyze(call: Call): Promise<unknown> {
         written = writeReported(listingPath, listing, { what: "--out-listing" });
       } catch (error) {
         const recorded = imported.revision === null ? "The knowledge did not change." : `The knowledge has the findings as revision ${imported.revision}.`;
-        throw new WireFailure("operation-failed", `The script did not write the listing to ${listingPath}: ${(error as Error).message}. ${recorded}`);
+        throw new WireFailure(isRefusal(error) ? error.code : "operation-failed", `The script did not write the listing to ${listingPath}: ${(error as Error).message.replace(/\.$/, "")}. ${recorded}`);
       }
     }
     const found = idiomsResult();
@@ -334,9 +343,9 @@ await runScript({
         decompile: { kind: "address", value: "<address>", multiple: true, help: "ghidra: a routine to decompile, at most 32" },
         space: OPTIONS.space,
         "max-listed": { ...OPTIONS["max-listed"], help: "list at most n labels, functions or candidates (default 50, 0 for none). The counts are always given, and the knowledge has all labels and functions" },
-        "out-listing": { kind: "path", value: "<file>", help: "dxa: write the disassembly listing to this project file" },
-        "out-instructions": { kind: "path", value: "<file>", help: "ghidra: write every instruction (address, bytes, mnemonic, mode, operand, target, executed) to this project file as JSON" },
-        "out-macro-batch": { kind: "path", value: "<file>", help: "write the macro candidates as an apply batch of c64-knowledge (the macros and their uses) to this project file" },
+        "out-listing": { kind: "path", output: "file", value: "<file>", help: "dxa: write the disassembly listing to this project file" },
+        "out-instructions": { kind: "path", output: "file", value: "<file>", help: "ghidra: write every instruction (address, bytes, mnemonic, mode, operand, target, executed) to this project file as JSON" },
+        "out-macro-batch": { kind: "path", output: "file", value: "<file>", help: "write the macro candidates as an apply batch of c64-knowledge (the macros and their uses) to this project file" },
       },
       notes: "The program and the coverage come from the knowledge: put them in with knowledge.ts image and coverage of the c64-knowledge skill. The executed code of the coverage is seeded. Routine symbols in the knowledge are entry points too. Ghidra needs at least one entry point. DXA finds the SYS of a BASIC start by itself.",
       run: analyze,

package/skills/c64-testing/SKILL.md

@@ -120,7 +120,7 @@ node <skill>/scripts/testing.ts diff .c64-re-tools/local/runs/rooms/results.json
 
 - Two snapshot files: the script restores each one in its own emulator. It gives the changed ranges of the RAM and of the colour RAM, and the changed VIC-II, CIA, SID and CPU registers.
 - Two memory files of a run: the changed ranges. For a file of less than 64 KiB, `--address` gives the address of its first byte.
-- Two observations of runs, also of one run: the changed memory items and registers.
+- Two observations of runs, also of one run: the changed memory items and registers. `compared` gives the count of items that both observations have. With `compared: 0`, `reason` tells what each observation has. Then the diff compared nothing, and the observations are not equal.
 
 `registers` gives each changed register and chip value. `cpu.pc` is a `$` address. Each CPU flag is `cpu.flags.<flag>`, for example `cpu.flags.c`, with `true` or `false`.
 
@@ -135,6 +135,7 @@ The script refuses a snapshot that does not restore in its emulator. An example
 - 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.
@@ -154,7 +155,7 @@ The script refuses a snapshot that does not restore in its emulator. An example
 1. Write the scenario file. Start the steps with a frame count, for example `{ "frames": 150 }`. Each side starts at the reset vector, and the C64 needs these frames to start.
 2. Use symbol names, for example `player_x`, not fixed addresses. Each side finds the name in its own symbols. Use a `$` address only when both programs use the same address.
 3. Make each checkpoint a condition, for example a `runUntil` step with an `address` target at a routine. Do not wait for a time.
-4. Save the c64-assembler output of the rebuild to the symbol file, for example `build/game.json` in the project folder. Give `--all-symbols`, so that the file also has the constants that the source does not use. From the folder above the project, write `assembler.ts build --project <folder> ... > <folder>/build/game.json`.
+4. Write the symbol file of the rebuild with `--out-symbols build/game.json` of c64-assembler `build`. Give `--all-symbols`, so that the file also has the constants that the source does not use.
 5. Run `testing.ts test`.
 6. Read the result:
    - `PASS`: all observations are equal, or the differences are in the allowed tolerance.

package/skills/c64-testing/scripts/lib/diff-files.ts

@@ -118,6 +118,18 @@ const show = (range: ChangedRange) => ({ start: formatC64Address(range.start), e
 /** A changed value as a person reads it: the pc as "$xxxx". */
 const showValue = (item: { name: string; a: number | boolean; b: number | boolean }) => (item.name === "cpu.pc" && typeof item.a === "number" && typeof item.b === "number" ? { name: item.name, a: formatC64Address(item.a), b: formatC64Address(item.b) } : item);
 
+/**
+ * How many items two observations have in common, by name: the items that the
+ * diff compared. With none, the reason names what each side has, so that a
+ * count of 0 does not read as "equal".
+ */
+export function comparedItems(what: string, a: readonly string[], b: readonly string[], first: string, second: string): { compared: number; reason?: string } {
+  const compared = a.filter((name) => b.includes(name)).length;
+  if (compared > 0) return { compared };
+  const has = (names: readonly string[]) => (names.length === 0 ? "none" : names.join(", "));
+  return { compared, reason: `No ${what} was compared: the observations have none in common. ${first} has ${has(a)}; ${second} has ${has(b)}.` };
+}
+
 /** The differences of two states of one kind: snapshots, memory files or observations of runs. */
 export async function diffFiles(first: string, second: string, options: { gap: number; max: number; ntsc: boolean; at?: number; out?: string }): Promise<Record<string, unknown>> {
   const kind = kindOf(first);
@@ -159,8 +171,8 @@ export async function diffFiles(first: string, second: string, options: { gap: n
     b: second,
     ...(diff.memory === undefined ? {} : { memory: part(diff.memory) }),
     ...(diff.colorRam === undefined ? {} : { colorRam: part(diff.colorRam) }),
-    ...(diff.values === undefined ? {} : { registers: listed(diff.values, max, showValue, rest) }),
-    ...(diff.observed === undefined ? {} : { observed: listed(diff.observed, max, undefined, rest) }),
+    ...(diff.values === undefined ? {} : { registers: { ...(kind === "observation" ? comparedItems("register", Object.keys(a.values ?? {}), Object.keys(b.values ?? {}), first, second) : {}), ...listed(diff.values, max, showValue, rest) } }),
+    ...(diff.observed === undefined ? {} : { observed: { ...comparedItems("memory item", Object.keys(a.observed ?? {}), Object.keys(b.observed ?? {}), first, second), ...listed(diff.observed, max, undefined, rest) } }),
     ...(written === undefined ? {} : written),
   };
 }

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

@@ -145,11 +145,11 @@ export function joystickMask(direction: Extract<ActionStep, { joystick: unknown
   return direction.split("-").reduce((mask, part) => mask | (bits[part] ?? 0), fire ? 0x10 : 0);
 }
 
-/** A state item of the command line: a name or a $ address, with :size for more than one byte. */
-export function parseStateItem(text: string): StateItem {
+/** A state item of the command line: a name or a $ address, with :size for more than one byte. `option` names the option of the item in a refusal. */
+export function parseStateItem(text: string, option = "--state"): StateItem {
   const match = /^([^:]+)(?::(\d+))?$/.exec(text);
   const size = Number(match?.[2] ?? 1);
-  if (match === null || !isInteger(size, 1, MAX_STATE_BYTES)) throw new Refusal("invalid-input", `--state ${text}: give a name or a $ address, with :size from 1 to ${MAX_STATE_BYTES}`);
+  if (match === null || !isInteger(size, 1, MAX_STATE_BYTES)) throw new Refusal("invalid-input", `${option} ${text}: give a name or a $ address, with :size from 1 to ${MAX_STATE_BYTES}`);
   return { address: match[1]!, size };
 }
 

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

@@ -37,7 +37,7 @@ export async function replay(values: ReplayOptions): Promise<ReplayResult> {
   const folder = values.folder.replace(/\/+$/, "").replace(/\/recording\.json$/, "");
   const recording = readRecording(folder);
   const given: Comparison | undefined =
-    values.checkpoint === undefined ? undefined : { checkpoint: values.checkpoint, state: values.state.map(parseStateItem), ...(values.pin.length === 0 ? {} : { pin: values.pin.map(parseStateItem) }) };
+    values.checkpoint === undefined ? undefined : { checkpoint: values.checkpoint, state: values.state.map((item) => parseStateItem(item, "--state")), ...(values.pin.length === 0 ? {} : { pin: values.pin.map((item) => parseStateItem(item, "--pin")) }) };
   const compare = given ?? recording.compare;
   if (values.rebuild !== undefined && compare === undefined) throw new UsageError("the recording has no checkpoint and state: give --checkpoint and --state");
   const result = (outcome: ReplayResult["result"], side: ReplayResult["side"], fields: Partial<ReplayResult> = {}): ReplayResult => ({

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

@@ -5,8 +5,9 @@
 
 import { formatC64Address, formatSprite, formatVicii, parseC64Address } from "#src/c64.ts";
 import { runProgram } from "#src/host-client/autostart.ts";
+import { isRefusal, Refusal } from "#src/errors.ts";
 import { readCoverage } from "#src/host-client/coverage.ts";
-import { ACTION_STEP_KINDS, checkActionStep, isInteger, isObject, refuseOldStep, renamedField, runActionStep, VICE_STEP_KINDS, type ActionStep, type ActionStepKind } from "#src/host-client/steps.ts";
+import { ACTION_STEP_KINDS, checkActionStep, checkStepNames, isInteger, isObject, refuseOldStep, renamedField, runActionStep, VICE_STEP_KINDS, type ActionStep, type ActionStepKind } from "#src/host-client/steps.ts";
 import { readPrg } from "#src/host-client/image.ts";
 import { MAX_MEMORY_READ, MAX_TRACE_FRAMES, MAX_TRACE_HITS, MAX_TRACE_POINTS, TRACE_KINDS, WireFailure, type TraceHit, type TraceKind } from "#src/host-client/tools.ts";
 import { readProjectFile, writeReported, type Written } from "#src/host-client/transfer.ts";
@@ -161,11 +162,26 @@ function readRun(path: string): Run {
 /** The remedy for a start program that is no PRG. */
 const PROGRAM_REMEDY = "A run starts a PRG. Get the PRG out of the disk, tape or cartridge with disk.ts read (or disk.ts crt) of the c64-disk skill";
 
-/** Checks each file that the run reads before the emulator starts: the start program or snapshot, and each snapshot step. */
-function checkRunFiles(run: Run): void {
-  if ("program" in run.start) readPrg(run.start.program, PROGRAM_REMEDY);
-  else readProjectFile(run.start.snapshot);
-  for (const step of run.steps) if ("snapshot" in step) readProjectFile(step.snapshot);
+/** Checks each file that the run reads before the emulator starts: the start program or snapshot, and each snapshot step. A refusal names the run file and the step. */
+function checkRunFiles(path: string, run: Run): void {
+  const named = (where: string, check: () => unknown) => {
+    try {
+      check();
+    } catch (error) {
+      if (isRefusal(error)) throw new Refusal(error.code, `run ${path}: ${where}: ${error.message}`);
+      throw error;
+    }
+  };
+  if ("program" in run.start) {
+    const { program } = run.start;
+    named("start.program", () => readPrg(program, PROGRAM_REMEDY));
+  } else {
+    const { snapshot } = run.start;
+    named("start.snapshot", () => readProjectFile(snapshot));
+  }
+  run.steps.forEach((step, index) => {
+    if ("snapshot" in step) named(`step ${index + 1}: snapshot`, () => readProjectFile(step.snapshot));
+  });
 }
 
 /** A trace hit with $ addresses, as a person reads it. */
@@ -176,7 +192,7 @@ function showHit(hit: TraceHit) {
 /** Runs the run file and writes its files into `out`. failed: a step did not run. */
 export async function runFile(path: string, out: string): Promise<{ output: Record<string, unknown>; failed: boolean }> {
   const run = readRun(path);
-  checkRunFiles(run);
+  checkRunFiles(path, run);
   const symbols = namesOf(run.symbols ?? "none");
   const at = (location: string): number => {
     if (location.startsWith("$")) return parseC64Address(location);
@@ -184,6 +200,10 @@ export async function runFile(path: string, out: string): Promise<{ output: Reco
     if (address === undefined) throw new UsageError(`the symbols have no ${location}`);
     return address;
   };
+  // The names of the action steps resolve before the emulator starts.
+  run.steps.forEach((step, index) => {
+    if ((ACTION_STEP_KINDS as readonly string[]).some((kind) => kind in step) && !("observe" in step) && !("trace" in step)) checkStepNames([step as ActionStep], at, `run ${path}`, index + 1);
+  });
   const files: string[] = [];
   const written: Written[] = [];
   const write = (name: string, bytes: Uint8Array) => {

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

@@ -123,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 };
@@ -141,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})` },
@@ -158,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) => {
@@ -178,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

@@ -26,7 +26,7 @@ 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 |
 |---|---|
@@ -41,11 +41,11 @@ node <skill>/scripts/unpacker.ts loads original/game.d64 --steps .c64-re-tools/l
 | `--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. 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": " " } }]
@@ -69,6 +69,7 @@ The scripts refuse a step in the form of version 2.0, for example `{ "runUntil":
 - 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.
@@ -107,7 +108,7 @@ The scripts refuse a step in the form of version 2.0, for example `{ "runUntil":
    - 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.
@@ -150,7 +151,9 @@ 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
 

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, VICE_STEP_KINDS, 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. */
@@ -57,7 +56,10 @@ export function readLoadSteps(path: string): LoadStep[] {
     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[];
@@ -97,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. */
@@ -184,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,
@@ -193,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) {