@henols/c64-re-tools 2.0.1 → 2.1.0-rc.2

package/skills/c64-reverse-engineering/SKILL.md

@@ -33,11 +33,12 @@ One repository can hold several programs, with one project folder for each progr
 - From the root of the repository, give `--project <folder>` to each skill script, and `project` to each emulator tool with a path.
 - Write all files in the project folder. Do not write files at the root of the repository.
 - Write each file that you make for your work in `.c64-re-tools/local/` of the project. Git ignores that folder. Examples are results, batches, step files, runs, snapshots and memory dumps.
-- Move a file out of `.c64-re-tools/local/` only when it is the evidence for a finding. Move it before you give it to `--evidence` of c64-knowledge. `--evidence` refuses a file in `.c64-re-tools/local/`.
+- Move a file out of `.c64-re-tools/local/` only when it is the evidence for a finding. Move it before you give it to `--evidence test:<file>` or `--evidence file:<file>` of c64-knowledge. These two refuse a file in `.c64-re-tools/local/`.
+- Do not move a coverage map after `coverage` of c64-knowledge imported it. `--evidence coverage:<map>` names the map by its path at the import. The knowledge keeps the coverage and the SHA-256 of the map, so the evidence stays valid.
 - Put a run that is evidence in `runs/<name>/`, with its run file, its results and the snapshot files that it uses. Change the paths in the run file to the new paths. Then git keeps them, and another person can do the run again.
 - A subagent can have no emulator tools. Give it its experiments as run files of the c64-testing skill. Each run starts its own emulator, so many runs can go at the same time. The emulator of the emulator tools is one machine, for the main session.
-- To name a large program with more agents at the same time, give each agent one range of addresses. Each agent writes a batch with its owner range. Then join the batches with `join` of the c64-knowledge skill, and apply the result one time.
-- Do not write a build script or a merge script. c64-source writes and assembles the loader with `--loader`, and `join` of c64-knowledge joins the batches.
+- To name a large program with more agents at the same time, give each agent one range of addresses. Each agent writes a batch with its owner range. Then join the batches with `knowledge.ts join` of the c64-knowledge skill, and apply the result one time.
+- Do not write a build script or a merge script. `source.ts generate --loader` of c64-source writes and assembles the loader, and `knowledge.ts join` of c64-knowledge joins the batches.
 - Do not write a script that makes a deliverable again, for example a capture, copy or replay script. Commit the deliverable.
 - Write the knowledge only with the c64-knowledge script. Do not write or edit the files in `.c64-re-tools/knowledge/` yourself.
 
@@ -62,7 +63,8 @@ Select the path for the scope:
 | What the program does at run time: values, input, timing, screen | c64-emulator |
 | The routines, code, data and references of the program | c64-static-analysis |
 | The platform meaning of an address or a register | c64-memory-map |
-| Differences between releases of the program | c64-provenance |
+| Differences between releases of the program | c64-provenance `compare` |
+| Leftovers of the development, a crack or a recrack: texts, old copies, unused bytes, dead code | c64-provenance `leftovers` |
 | A routine that another program of the workspace has, for example a music driver | c64-provenance, with the library |
 | Source code from the knowledge | c64-source |
 | Source code to build | c64-assembler |
@@ -78,21 +80,21 @@ Do the stages in this sequence. Go to the next stage only when its exit check is
 
 | Stage | Work | Exit check |
 |---|---|---|
-| 1. Acceptance | Ask the user for the criteria of the rebuild. Offer these: identical source, a verified loader, passed c64-testing scenarios, and a list of the code that no run executed. Also offer documentation of the flows, tables, formats and graphics. | The user gave the criteria. |
+| 1. Acceptance | Ask the user for the criteria of the rebuild. Offer these: identical source, a verified loader, passed c64-testing scenarios, passed replays of the recordings, and a list of the code that no run executed. Also offer documentation of the flows, tables, formats and graphics. | The user gave the criteria. |
 | 2. Get | c64-disk: list the disk. Extract the start file into `original/`. | The start file is in the project. |
 | 3. Start | c64-basic: find the SYS address of the BASIC start. | You have the entry address. |
-| 4. Unpack | c64-unpacker: examine the program. Capture a packed program into `.c64-re-tools/local/`. Then c64-knowledge: put the capture, or the PRG of a program without a packer, into the knowledge with `image`. | `program` of c64-knowledge shows the segments and the entry. |
-| 5. Run | c64-emulator and the run of c64-testing: run each part that the scope names. Write a coverage map for each part into `.c64-re-tools/local/`. Then c64-knowledge: add the maps with `coverage`. | `program` of c64-knowledge lists a coverage map for each part that the scope names. |
-| 6. Analyze | c64-static-analysis. It reads the program and the coverage from the knowledge. | No coverage conflict is open. |
-| 7. Name | c64-provenance: if the workspace has a library, find its routines with `match` and apply the batch. Then c64-knowledge and c64-memory-map: name each routine in the scope and give it a comment. Record the modules. When the scope has hundreds of routines, ask the user which routines to name. The source gives the other routines an `l_xxxx` label. | Each routine that the user selected has a name and a comment. |
-| 8. Generate | c64-source into `src/`. For an unpacked program, add `--loader`. | `check.identical` is true. For an unpacked program, `loader.verified` is true. |
-| 9. Build and test | c64-assembler with `--compare` into `build/`. c64-testing scenarios in `tests/`. | The criteria of stage 1 are true. |
-| 10. Document | When the criteria ask for documentation: c64-docs into `README.md` and `docs/`. | `link.ts --check` of c64-docs gives no problem. |
+| 4. Unpack | c64-unpacker: examine the program with `unpacker.ts inspect`, `trace` and `stages`. Capture a packed program with `unpacker.ts capture` into `.c64-re-tools/local/`. Then c64-knowledge: put the capture, or the PRG of a program without a packer, into the knowledge with `knowledge.ts image`. | `program` of c64-knowledge shows the segments and the entry. |
+| 5. Run | First record: ask the user to play each part that the scope names, with `testing.ts record --play` of c64-testing. Tell the user which parts. Record a part yourself only when the sessions of the user do not have it. Put the recordings in `tests/recordings/`. Then use c64-emulator and `testing.ts run` of c64-testing for the parts that a recording cannot have. Write a coverage map for each part into `.c64-re-tools/local/`. Then c64-knowledge: add the maps and the `coverage.bin` of each recording with `knowledge.ts coverage`. | `program` of c64-knowledge lists a coverage map for each part that the scope names. |
+| 6. Analyze | c64-static-analysis: `static-analysis.ts analyze`. It reads the program and the coverage from the knowledge. | No coverage conflict is open. |
+| 7. Name | c64-provenance: if the workspace has a library, find its routines with `provenance.ts match` and apply the batch. Then c64-knowledge and c64-memory-map: name each routine in the scope and give it a comment. Record the modules. When the scope has hundreds of routines, ask the user which routines to name. The source gives the other routines an `l_xxxx` label. | Each routine that the user selected has a name and a comment. |
+| 8. Generate | c64-source: `source.ts generate --out src`. For an unpacked program, add `--loader`. | `check.identical` is true. For an unpacked program, `loader.verified` is true. |
+| 9. Build and test | c64-assembler: `assembler.ts build` with `--compare` into `build/`. c64-testing: `testing.ts test` with the scenarios in `tests/`. Replay each recording on the rebuild with `testing.ts replay`: give the checkpoint routine, the state and the random state (`--pin`) with the names of stage 7. | The criteria of stage 1 are true. |
+| 10. Document | When the criteria ask for documentation: c64-docs into `README.md` and `docs/`, with `docs.ts generate` and `docs.ts link`. | `docs.ts link --check` of c64-docs gives `result: "PASS"`. |
 | 11. Hand over | Find each file that you made outside `.c64-re-tools/local/` and that is not a deliverable. Move it into `.c64-re-tools/local/`. Then give the answer (below). | Each file that you made outside `.c64-re-tools/local/` is a deliverable. |
 
-In stage 5, if you cannot get to a part of the program, ask the user how to get to it. Do stages 7 and 8 again until the source is clear. Each run of c64-source writes the source again.
+In stage 5, make the recordings before you change the program. A recording needs no names, and its coverage gives the analysis of stage 6 more code. If you cannot get to a part of the program, ask the user how to get to it. Do stages 7 and 8 again until the source is clear. Each run of c64-source writes the source again.
 
-After stage 7, save each routine that other programs can have to the library with c64-provenance `routine`. Examples are a music driver, a decruncher and a loader. Ask the user before you make a library.
+After stage 7, save each routine that other programs can have to the library with `provenance.ts routine` of c64-provenance. Examples are a music driver, a decruncher and a loader. Ask the user before you make a library.
 
 ### Deliverables of a full rebuild
 
@@ -100,6 +102,7 @@ After stage 7, save each routine that other programs can have to the library wit
 - the generated source
 - the built program and the loader
 - the c64-testing scenarios
+- the c64-testing recordings in `tests/recordings/`
 - the documentation in `README.md` and `docs/`, when the criteria ask for it
 - the runs in `runs/` that the knowledge gives as evidence
 - the scripts in `tools/` for the formats of this program, when you wrote them.
@@ -124,7 +127,7 @@ If the project has no layout, use this one. No script checks it. Each script tak
 original/      the disk image or the program as you got it
 src/           the generated source from c64-source
 build/         programs from c64-assembler
-tests/         c64-testing scenarios
+tests/         c64-testing scenarios, and the recordings in tests/recordings/
 runs/          the runs that the knowledge gives as evidence
 docs/          the documentation from c64-docs, with the reference in docs/reference/
 tools/         scripts for the formats of this program only

package/skills/c64-source/SKILL.md

@@ -24,27 +24,40 @@ This skill does not change the knowledge.
 The script runs Ghidra and ACME on this machine. With `--loader`, it also runs the loader in the emulator through the host runtime.
 
 ```
-node <skill>/scripts/generate.ts --out src
-node <skill>/scripts/generate.ts --out src --entry '$080d'
-node <skill>/scripts/generate.ts --out src --loader
+node <skill>/scripts/source.ts generate --out src
+node <skill>/scripts/source.ts generate --out src --entry '$080d'
+node <skill>/scripts/source.ts generate --out src --loader
 ```
 
 | Option | Meaning |
 |---|---|
 | `--out src` | The directory for the source files. The script writes over the files that it generated before. |
 | `--entry '$080d'` | An entry point for Ghidra. Use it again for more entry points. The entry of the program, the routines and the code regions in the knowledge are entry points too. |
-| `--analyzer-names` | Name an address that has no symbol and no platform name with its analyzer name, for example `FUN_17e2`. The order is heuristic, Ghidra, then DXA. Without it, the source makes its own names, for example `l17e2`. |
+| `--analyzer-names` | Name an address that has no symbol and no platform name with its analyzer name, for example `FUN_17e2`. The order is heuristic, Ghidra, then DXA. Without it, the source makes its own names, for example `l_17e2`. |
 | `--space drive8` | Generate the source of drive code or a cartridge bank from the knowledge of that space. The coverage, `--loader` and the platform names are only for `c64`. |
 | `--loader` | Also write `loader.asm` and `loader.prg`. This needs a capture in the knowledge, with its entry and its entry state. |
+| `--max-listed 20` | List at most this number of items in each list. The default is 50. The counts are always in the result. |
 
 When the knowledge has coverage, code that no run executed gets the line `; not executed` with its range. `notExecuted` lists it. The executed code is also a seed for Ghidra. Thus the source has the code after a JSR to a routine that Ghidra thinks does not return.
 
+### Calling the script
+
+- Call a script as `node <skill>/scripts/<script>.ts <command> [subjects] [options]`. The command comes first.
+- `<script>.ts --help` lists the commands. `<script>.ts <command> --help` gives the subjects and the options of one command. The help is JSON: `{"text": "..."}`.
+- 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 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.
+
 ### Project folder
 
 - Paths are relative to the project folder. The project folder is the nearest folder at or above the working directory that holds `.c64-re-tools/`.
 - If the working directory is not in a project and has projects below it, the script refuses and lists them. Then give `--project <folder>` to each script.
 - Write each file that you make for your work in `.c64-re-tools/local/` of the project. Git ignores that folder. Examples are results, batches, step files, runs, snapshots and memory dumps.
-- Move a file out of `.c64-re-tools/local/` only when it is the evidence for a finding. Move it before you give it to `--evidence` of c64-knowledge. `--evidence` refuses a file in `.c64-re-tools/local/`.
+- Move a file out of `.c64-re-tools/local/` only when it is the evidence for a finding. Move it before you give it to `--evidence test:<file>` or `--evidence file:<file>` of c64-knowledge. These two refuse a file in `.c64-re-tools/local/`.
+- Do not move a coverage map after `coverage` of c64-knowledge imported it. `--evidence coverage:<map>` names the map by its path at the import. The knowledge keeps the coverage and the SHA-256 of the map, so the evidence stays valid.
 - Put a run that is evidence in `runs/<name>/`, with its run file, its results and the snapshot files that it uses. Change the paths in the run file to the new paths. Then git keeps them, and another person can do the run again.
 - A shell redirect (`>`) is relative to the working directory, not to the project folder. From the folder above the project, write `<folder>/.c64-re-tools/local/result.json`.
 
@@ -52,11 +65,11 @@ When the knowledge has coverage, code that no run executed gets the line `; not
 
 1. Put the program into the knowledge with `image` of the c64-knowledge skill. For a packed program, capture it first with the c64-unpacker skill. For a program without a packer, use the PRG.
 2. Run the script.
-3. Read `check`. `identical: true` tells that the source assembles to the program byte by byte.
+3. Read `result` and `check`. `check.identical: true` tells that the source assembles to the program byte by byte.
 4. Read the source. A label `l_xxxx` is an address that has no name in the knowledge.
 5. Record names, comments, regions and modules with the c64-knowledge skill. Use `apply` for many changes.
 6. Run the script again. Do steps 4 to 6 again until the source is clear.
-7. Build the program with the c64-assembler skill: `--source-root src --entry main.asm`.
+7. Build the program with the c64-assembler skill: `assembler.ts build src main.asm --out <file.prg>`.
 8. For an unpacked program, run the script with `--loader` at the end. Test `loader.prg` against the original with the c64-testing skill.
 
 ## The source
@@ -104,15 +117,15 @@ The script writes a macro use only when the use gives the bytes of the program.
 1. `10 SYS 2061` starts it.
 2. It stops the interrupts and makes all RAM visible. Then it moves its copier to two free pages. Thus a copier at $a000 or higher is not read from the BASIC ROM.
 3. It copies each segment and the pages $0002-$03ff of the entry state into place. The script selects an order in which no copy writes over the packed bytes of a copy that has not run yet.
-4. It sets the display registers of the VIC-II and the VIC bank from `io` in the entry state. Then it waits for the raster line of the entry.
+4. It sets the screen registers of the VIC-II and the VIC bank from `io` in the entry state. Then it waits for the raster line of the entry.
 5. It sets the CIA timers, their latches and the interrupt masks from `io` and `cia` in the entry state. A running timer gets the value that counts down to the timer value of the entry at the entry.
 6. It sets $00/$01, the stack pointer, A, X, Y and the flags, and jumps to the entry.
 
-The copy table, the copier and the jump to the entry use labels, not numbers. `loader_from_xxxx` and `loader_end_xxxx` are around each packed segment, and `loader_to_xxxx` is its first address in place. The jump goes to the label of the entry. Thus a segment can change its length, and the loader still copies it and jumps to the entry that moved. The display values, the raster line and the CIA values stay numbers. They are the entry state, not addresses of the program.
+The copy table, the copier and the jump to the entry use labels, not numbers. `loader_from_xxxx` and `loader_end_xxxx` are around each packed segment, and `loader_to_xxxx` is its first address in place. The jump goes to the label of the entry. Thus a segment can change its length, and the loader still copies it and jumps to the entry that moved. The screen values, the raster line and the CIA values stay numbers. They are the entry state, not addresses of the program.
 
 The flags go through the free stack byte below the stack pointer (`stackByte`). The loader changes this byte. The loader does not set the SID, the time of day of the CIAs, the CIA interrupt flags or the interrupt registers of the VIC-II. `loader.limits` names each CIA value that the loader cannot set as it was at the entry. A program that reads the SID voice 3 for random numbers can still differ in a scenario. A raster sync does not change a timer or the SID. Then observe after the program sets up its own random numbers. To sync the original and the rebuild in a test, see the sync rules of the c64-testing skill.
 
-The script simulates the copies first. Then it runs `loader.prg` in the emulator to its jump to the entry. It compares the memory, $00/$01, the registers, the display registers of the VIC-II, the VIC bank and the raster line with the entry state there. It also compares the CIA timers, latches and interrupt masks. `loader.verified: true` tells that all of them are equal. An interrupt can run right at the entry, as in the original program.
+The script simulates the copies first. Then it runs `loader.prg` in the emulator to its jump to the entry. It compares the memory, $00/$01, the registers, the screen registers of the VIC-II, the VIC bank and the raster line with the entry state there. It also compares the CIA timers, latches and interrupt masks. `loader.verified: true` tells that all of them are equal. An interrupt can run right at the entry, as in the original program.
 
 ## Knowledge
 
@@ -127,9 +140,8 @@ Do not store:
 
 ## Result
 
-One JSON object:
-
-- `files`: the files in the output directory.
+- `result`: `PASS` when every check passes, else `FAIL`.
+- `files`: the files that the script wrote in `--out`, each with `out`, `bytes` and `sha256`. `sourceMap` names `source-map.json`.
 - `instructions`, `dataBytes` and `undecodedBytes`.
 - `labels`: `named` labels from the knowledge and `generated` labels `l_xxxx`.
 - `entriesInData`: each `--entry` in a data region of the knowledge, with the `region` and its `origin`. Ghidra does not decode an entry in a data region.
@@ -138,7 +150,7 @@ One JSON object:
 - `operandsAsNumbers`: the operand expressions that the source has as a number with a side comment, each with its `address`, `expression` and `reason`. An expression becomes a number when no instruction with an operand value is at the address, or when a name has no address. An expression that ACME refuses or does not assemble to the program also becomes a number. Then the script assembles the source again, at most six times.
 - `unusedModules`: modules in the knowledge whose start is in no segment of the program. Often this tells that the program does not hold code that the knowledge describes.
 - `entryOutside`: the entry is in no segment of the program in the knowledge, with a `reason`. The capture does not hold the program.
-- `notExecuted`: when the knowledge has coverage, the count of instructions that no run executed, the count of their ranges, and the first ranges. `all` names the file `not_executed.json` in `--out`. It has all of the ranges. Each range has its source `file` and the `routine` before it. `files` counts the ranges in each file.
+- `notExecuted`: when the knowledge has coverage, the count of instructions that no run executed, the count of their ranges, and the first ranges. `rest` names the file `not_executed.json` in `--out` when the list is not complete. This file has all of the ranges. Each range has its source `file` and the `routine` before it. `files` counts the ranges in each file.
 - `macroUses`: the count of macro uses that the source has.
 - `macrosAsInstructions`: the macro uses that the source has as instructions, each with its `start`, `end`, `macro` and `reason`.
 - `patchesNotWritten`: the patches that the source does not have, each with its range, `switch` and `reason`.
@@ -146,7 +158,7 @@ One JSON object:
 - `switches`: the build of each switch. Each item has the `define` for the c64-assembler skill, the patches and the `result` of the build with the switch on. `fits` tells that the build is good, and `changedBytes` counts the changed bytes. `overflow` tells that the code of a patch is longer than its range. `changes outside` gives the first byte outside the ranges that changed. `does not assemble` gives the diagnostics of ACME. `insideNames` lists the labels inside a patch. Code that writes to one of these labels changes the patch when the switch is on.
 - `loader`: the program, the copies in their order, the copier page, `stackByte`, `verified` and `differences`. `limits` lists the CIA values that the loader cannot set. An entry state from an old capture has no CIA values. Then `limits` tells you to capture the program again. When the script cannot make the loader, `loader` has `verified: false` and a `reason`. The loader includes the source. Thus a source that does not assemble to the program also stops the loader.
 
-The exit status is 0 when the source is identical and the emulator check of the loader passes. The exit status is 1 for a failed check, for an entry in no segment, and for an error. A patch that the source does not have, or a switch that does not fit, also gives 1. The exit status is 2 for a wrong argument.
+`result` is `PASS` when the source is identical and the emulator check of the loader passes. `result` is `FAIL` for a failed check and for an entry in no segment. A patch that the source does not have, or a switch that does not fit, also gives `FAIL`. `asBytes`, `notExecuted`, `operandsAsNumbers`, `macrosAsInstructions` and `patchesNotWritten` are lists of at most `--max-listed` items.
 
 ## Failure and conflicts
 
@@ -159,7 +171,7 @@ The exit status is 0 when the source is identical and the emulator check of the
 - `patchesNotWritten`: read each `reason`. Move the start or the end of the patch to an instruction, or give the switch another name.
 - `macrosAsInstructions`: read each `reason`. Correct the macro or the args, or remove the use with `unuse`. The source stays identical, so this is not a failure.
 - `entryOutside`: the run fails, but the script still writes and checks the source. With `--loader`, `loader.verified` is `false` with the same `reason`. Capture the program again with c64-unpacker `loads` or `capture`. Make sure that a segment holds the entry. Then put it into the knowledge again with `image`.
-- `entriesInData`: an analyzer region of data hides the code at the entry. If the entry is code, record a code region at the entry with the c64-knowledge skill, for example `classify '$0500' '$05ff' code`. A region of the user or the LLM replaces the analyzer region. Then generate again.
+- `entriesInData`: an analyzer region of data hides the code at the entry. If the entry is code, record a code region at the entry with the c64-knowledge skill, for example `classify '$0500-$05ff' code`. A region of the user or the LLM replaces the analyzer region. Then generate again.
 - `loader.verified: false` with a `reason`: the script did not make the loader. The script still writes and checks the source. When no copy order or no free pages exist, or the loader needs too many copies, the reason gives the ranges. Capture the program again with fewer segments, or write the loader by hand.
 - `loader.verified: false` with `differences`: the loader ran, and `differences` gives the bytes and registers that are not equal.
 - `loader.verified: false` with `stop`: the loader did not get to its copier or to its jump. `stop` gives the address where it stopped and `port`, the value of $01. `history` gives the last 16 instructions. `cause` gives the first byte of the copier that is not equal to its byte in the loader file. If the copier ran, `cause` can also give the first byte that a copy did not write correctly.

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

@@ -7,9 +7,10 @@
 // overwrites the packed bytes of a copy that has not run yet. The plan is
 // simulated here before the emulator runs it.
 
-import { formatC64Address } from "#src/c64.ts";
+import { type AddressRange, formatC64Address, formatC64Byte } from "#src/c64.ts";
+import { Refusal } from "#src/errors.ts";
+import { parseEntryState } from "#src/host-client/entry-state.ts";
 import { WireFailure } from "#src/host-client/tools.ts";
-import type { Range } from "./source.ts";
 
 export interface EntryState {
   pc: number;
@@ -59,51 +60,27 @@ export function rasterLine(registers: Uint8Array): number {
   return ((registers[0x11]! & 0x80) << 1) | registers[0x12]!;
 }
 
-const FLAG_BITS: Record<string, number> = { n: 0x80, v: 0x40, b: 0x10, d: 0x08, i: 0x04, z: 0x02, c: 0x01 };
+const FLAG_BITS = { n: 0x80, v: 0x40, d: 0x08, i: 0x04, z: 0x02, c: 0x01 } as const;
 
-/** Reads entry_state.json of the c64-unpacker skill. */
-export function readEntryState(text: string, path: string): EntryState {
+/**
+ * The entry state that the loader recreates: the shared entry state of the
+ * c64-unpacker capture, with the flags as PLP reads them, the VIC-II and the CIAs.
+ */
+export function loaderState(value: unknown, where: string): EntryState {
+  const state = parseEntryState(value, where);
   const fail = (what: string): never => {
-    throw new WireFailure("invalid-input", `${path} is not an entry_state.json of the c64-unpacker skill: ${what}.`);
+    throw new Refusal("invalid-input", `${where} is not an entry state of a c64-unpacker capture: ${what}. Capture the program again with c64-unpacker capture or loads.`);
   };
-  let value: Record<string, any>;
-  try {
-    value = JSON.parse(text) as Record<string, any>;
-  } catch (error) {
-    return fail((error as Error).message);
-  }
-  const registers = value.registers;
-  const byte = (item: unknown, what: string) => (Number.isInteger(item) && (item as number) >= 0 && (item as number) <= 0xff ? (item as number) : fail(`${what} is not a byte`));
-  if (typeof registers !== "object" || registers === null) return fail("it has no registers");
-  const pc = typeof registers.pc === "string" && /^\$[0-9a-f]{4}$/i.test(registers.pc) ? Number.parseInt(registers.pc.slice(1), 16) : fail("registers.pc is not a $ address");
-  if (typeof registers.flags !== "object" || registers.flags === null) fail("registers.flags is missing");
   let flags = 0x20;
-  for (const [name, bit] of Object.entries(FLAG_BITS)) if (registers.flags[name] === true) flags |= bit;
-  const pages = new Uint8Array(0x400);
-  for (let page = 0; page < 4; page++) {
-    const hex = value.pages?.[formatC64Address(page << 8)];
-    if (typeof hex !== "string" || !/^[0-9a-f]{512}$/i.test(hex)) fail(`pages.${formatC64Address(page << 8)} is not 256 bytes of hex`);
-    pages.set(Buffer.from(hex as string, "hex"), page << 8);
-  }
-  return {
-    pc,
-    a: byte(registers.a, "registers.a"),
-    x: byte(registers.x, "registers.x"),
-    y: byte(registers.y, "registers.y"),
-    sp: byte(registers.sp, "registers.sp"),
-    flags,
-    port: [byte(value.cpuPort?.$00, "cpuPort.$00"), byte(value.cpuPort?.$01, "cpuPort.$01")],
-    pages,
-    ...readVic(value.io, fail),
-    ...readCia(value, fail),
-  };
+  for (const [name, bit] of Object.entries(FLAG_BITS)) if (state.flags[name as keyof typeof FLAG_BITS]) flags |= bit;
+  return { pc: state.pc, a: state.a, x: state.x, y: state.y, sp: state.sp, flags, port: state.port, pages: state.pages, ...readVic(state.raw.io as Record<string, any> | undefined, fail), ...readCia(state.raw, fail) };
 }
 
 export interface Copy {
   /** What the copy writes: a segment or a part of pages 0-3. */
   what: string;
-  target: Range;
-  source: Range;
+  target: AddressRange;
+  source: AddressRange;
   /** True when the copy runs from the last byte down: its target is above an overlapping source. */
   backward: boolean;
 }
@@ -111,7 +88,7 @@ export interface Copy {
 /** What the loader holds, in its order: a segment or a part of pages 0-3, packed at an address of the loader. */
 export interface PackedBlock {
   what: string;
-  range: Range;
+  range: AddressRange;
   packedAt: number;
   bytes: (address: number) => number;
 }
@@ -161,13 +138,11 @@ export const MAX_COPIES = Math.min(Math.floor((256 - 2) / COPY_ENTRY), Math.floo
 const LOAD_LIMIT = 0xcfff;
 const COPIER_PAGES = [...Array.from({ length: 15 }, (_, index) => 0xc000 + index * 0x100), ...Array.from({ length: 0x9b }, (_, index) => 0x9e00 - index * 0x100)];
 
-const hex2 = (value: number) => `$${value.toString(16).padStart(2, "0")}`;
-const hex4 = formatC64Address;
-const overlaps = (a: Range, b: Range) => a.start <= b.end && b.start <= a.end;
-const show = (range: Range) => `${hex4(range.start)}-${hex4(range.end)}`;
+const overlaps = (a: AddressRange, b: AddressRange) => a.start <= b.end && b.start <= a.end;
+const show = (range: AddressRange) => `${formatC64Address(range.start)}-${formatC64Address(range.end)}`;
 
 /** Parts of `range` that no range in `holes` covers. */
-function subtract(range: Range, holes: Range[]): Range[] {
+function subtract(range: AddressRange, holes: AddressRange[]): AddressRange[] {
   let pieces = [range];
   for (const hole of holes) {
     pieces = pieces.flatMap((piece) => {
@@ -217,13 +192,13 @@ export function stopCause(ram: Uint8Array, plan: LoaderPlan, copierSource: numbe
     const got = ram[plan.copier + offset]!;
     const wanted = fileByte(copierSource + offset);
     if (got === wanted) continue;
-    const rom = underRom(copierSource + offset) ? `; ${hex4(copierSource + offset)} is under a ROM, so the move read the ROM` : "";
-    return `The copier at ${hex4(plan.copier + offset)} holds ${hex2(got)}, not ${hex2(wanted)} from ${hex4(copierSource + offset)} of the loader file${rom}.`;
+    const rom = underRom(copierSource + offset) ? `; ${formatC64Address(copierSource + offset)} is under a ROM, so the move read the ROM` : "";
+    return `The copier at ${formatC64Address(plan.copier + offset)} holds ${formatC64Byte(got)}, not ${formatC64Byte(wanted)} from ${formatC64Address(copierSource + offset)} of the loader file${rom}.`;
   }
   if (!copied) return undefined;
   for (const copy of plan.copies) {
     for (let address = copy.target.start; address <= copy.target.end; address++) {
-      if (ram[address] !== expected(address)) return `The copy of ${copy.what} wrote ${hex2(ram[address]!)} at ${hex4(address)}, not ${hex2(expected(address))}.`;
+      if (ram[address] !== expected(address)) return `The copy of ${copy.what} wrote ${formatC64Byte(ram[address]!)} at ${formatC64Address(address)}, not ${formatC64Byte(expected(address))}.`;
     }
   }
   return undefined;
@@ -304,8 +279,8 @@ interface Op {
  */
 export function ciaSection(state: EntryState): { ops: Op[]; plan: CiaPlan } | undefined {
   if (state.cia === undefined) return undefined;
-  const lda = (value: number): Op => ({ text: `lda #${hex2(value)}`, bytes: 2, cycles: 2 });
-  const sta = (address: number): Op => ({ text: `sta ${hex4(address)}`, bytes: 3, cycles: 4 });
+  const lda = (value: number): Op => ({ text: `lda #${formatC64Byte(value)}`, bytes: 2, cycles: 2 });
+  const sta = (address: number): Op => ({ text: `sta ${formatC64Address(address)}`, bytes: 3, cycles: 4 });
   const limits: string[] = [];
   const timers: CiaTimerPlan[] = [];
   const disable: Op[] = [];
@@ -363,7 +338,7 @@ export function ciaSection(state: EntryState): { ops: Op[]; plan: CiaPlan } | un
       if (mask !== 0) masks.push(lda(0x80 | mask), sta(base + 0x0d));
       touched = true;
     }
-    if (touched) acks.push({ text: `lda ${hex4(base + 0x0d)}`, bytes: 3, cycles: 4 });
+    if (touched) acks.push({ text: `lda ${formatC64Address(base + 0x0d)}`, bytes: 3, cycles: 4 });
     const flags = chip.registers[0x0d]! & 0x1f;
     if (flags !== 0) limits.push(`CIA ${id} has the interrupt flags $${flags.toString(16).padStart(2, "0")} at the entry: only an event sets a flag, so the loader cannot.`);
   });
@@ -386,7 +361,7 @@ export function ciaSection(state: EntryState): { ops: Op[]; plan: CiaPlan } | un
 
 export interface LoaderInput {
   /** The segments with the files that hold them, in address order. */
-  segments: Array<Range & { files: string[] }>;
+  segments: Array<AddressRange & { files: string[] }>;
   byteAt: (address: number) => number;
   state: EntryState;
   entry: number;
@@ -407,7 +382,7 @@ export const COPIER_SOURCE = "loader_copier_src";
 export function planLoader(input: LoaderInput): LoaderPlan {
   const { state } = input;
   // What the copies write: each segment without $00/$01, which the loader sets last, and pages $0002-$03ff where no segment is.
-  const blocks: Array<{ what: string; range: Range; files?: string[]; pseudo: number; bytes: (address: number) => number }> = [];
+  const blocks: Array<{ what: string; range: AddressRange; files?: string[]; pseudo: number; bytes: (address: number) => number }> = [];
   for (const segment of input.segments) blocks.push({ what: `segment ${show(segment)}`, range: segment, files: segment.files, pseudo: segment.start, bytes: input.byteAt });
   for (const part of subtract({ start: 0x0002, end: 0x03ff }, input.segments)) {
     blocks.push({ what: `entry state ${show(part)}`, range: part, pseudo: part.start, bytes: (address) => state.pages[address]! });
@@ -437,7 +412,7 @@ export function planLoader(input: LoaderInput): LoaderPlan {
   const copierImage = at;
   const copierSize = COPIER_CODE_SIZE + (state.vic === undefined ? 0 : VIC_SIZE) + ciaSize + COPY_ENTRY * plain.length + 2;
   const end = copierImage + copierSize - 1;
-  if (end > LOAD_LIMIT) throw new WireFailure("invalid-input", `The loader would end at ${hex4(end)}, after ${hex4(LOAD_LIMIT)}: loading it would write the I/O area. The image is too large for one loader file.`);
+  if (end > LOAD_LIMIT) throw new WireFailure("invalid-input", `The loader would end at ${formatC64Address(end)}, after ${formatC64Address(LOAD_LIMIT)}: loading it would write the I/O area. The image is too large for one loader file.`);
 
   const order = copyOrder(plain);
   if (order === undefined) {
@@ -457,8 +432,8 @@ export function planLoader(input: LoaderInput): LoaderPlan {
   const copyBlocks = order.map((index) => blockOf[index]!);
 
   const stackByte = 0x0100 + state.sp;
-  const lines: string[] = [...input.header.map((line) => `; ${line}`), "", "!cpu 6510", '!source "constants.asm"', ...(input.macros ? ['!source "macros.asm"'] : []), "", `* = ${hex4(LOAD)}`];
-  lines.push(`        !byte $0b,$08,$0a,$00,$9e,${[...String(STUB)].map((digit) => hex2(digit.charCodeAt(0))).join(",")},$00,$00,$00 ; 10 SYS ${STUB}`);
+  const lines: string[] = [...input.header.map((line) => `; ${line}`), "", "!cpu 6510", '!source "constants.asm"', ...(input.macros ? ['!source "macros.asm"'] : []), "", `* = ${formatC64Address(LOAD)}`];
+  lines.push(`        !byte $0b,$08,$0a,$00,$9e,${[...String(STUB)].map((digit) => formatC64Byte(digit.charCodeAt(0))).join(",")},$00,$00,$00 ; 10 SYS ${STUB}`);
   lines.push(
     "!zone loader_stub {",
     "        sei",
@@ -467,22 +442,22 @@ export function planLoader(input: LoaderInput): LoaderPlan {
     "        sta $01",
     "        ldx #0",
     `-       lda ${COPIER_SOURCE},x`,
-    `        sta ${hex4(copier)},x`,
+    `        sta ${formatC64Address(copier)},x`,
     `        lda ${COPIER_SOURCE}+$100,x`,
-    `        sta ${hex4(copier + 0x100)},x`,
+    `        sta ${formatC64Address(copier + 0x100)},x`,
     "        inx",
     "        bne -",
-    `        jmp ${hex4(copier)}`,
+    `        jmp ${formatC64Address(copier)}`,
     "}",
   );
   // The labels around each block give the copy table its numbers, so a block can change its length.
   for (const block of blocks) {
-    lines.push("", `; ${block.what}`, blockLabel(block.range.start, "from"), `!pseudopc ${hex4(block.pseudo)} {`, blockLabel(block.range.start, "to"));
+    lines.push("", `; ${block.what}`, blockLabel(block.range.start, "from"), `!pseudopc ${formatC64Address(block.pseudo)} {`, blockLabel(block.range.start, "to"));
     if (block.files !== undefined) for (const file of block.files) lines.push(`!source "${file}"`);
     else {
       for (let address = block.range.start; address <= block.range.end; address += 16) {
         const last = Math.min(block.range.end, address + 15);
-        lines.push(`        !byte ${Array.from({ length: last - address + 1 }, (_, offset) => hex2(block.bytes(address + offset))).join(",")}`);
+        lines.push(`        !byte ${Array.from({ length: last - address + 1 }, (_, offset) => formatC64Byte(block.bytes(address + offset))).join(",")}`);
       }
     }
     lines.push("}", blockLabel(block.range.start, "end"));
@@ -490,9 +465,9 @@ export function planLoader(input: LoaderInput): LoaderPlan {
   const [port0, port1] = state.port;
   lines.push(
     "",
-    `; The copier runs at ${hex4(copier)}. The flags pass through ${hex4(stackByte)}, the free stack byte below the stack pointer.`,
+    `; The copier runs at ${formatC64Address(copier)}. The flags pass through ${formatC64Address(stackByte)}, the free stack byte below the stack pointer.`,
     COPIER_SOURCE,
-    `!pseudopc ${hex4(copier)} {`,
+    `!pseudopc ${formatC64Address(copier)} {`,
     "!zone loader_copier {",
     "        lda #$34",
     "        sta $01",
@@ -550,28 +525,28 @@ export function planLoader(input: LoaderInput): LoaderPlan {
     // The CIA part runs after the raster wait: the wait ends its whole lines earlier, so the entry comes in its line.
     ...vicLines(state, Math.floor((cia?.ops.reduce((sum, op) => sum + op.cycles, 0) ?? 0) / LINE_CYCLES)),
     ...(cia === undefined ? [] : cia.ops.map((op) => `        ${op.text}`)),
-    `        lda #${hex2(port0)}`,
+    `        lda #${formatC64Byte(port0)}`,
     "        sta $00",
-    `        lda #${hex2(port1)}`,
+    `        lda #${formatC64Byte(port1)}`,
     "        sta $01",
-    `        ldx #${hex2((state.sp - 1) & 0xff)}`,
+    `        ldx #${formatC64Byte((state.sp - 1) & 0xff)}`,
     "        txs",
-    `        lda #${hex2(state.flags)}`,
-    `        sta ${hex4(stackByte)}`,
-    `        lda #${hex2(state.a)}`,
-    `        ldx #${hex2(state.x)}`,
-    `        ldy #${hex2(state.y)}`,
+    `        lda #${formatC64Byte(state.flags)}`,
+    `        sta ${formatC64Address(stackByte)}`,
+    `        lda #${formatC64Byte(state.a)}`,
+    `        ldx #${formatC64Byte(state.x)}`,
+    `        ldy #${formatC64Byte(state.y)}`,
     "        plp",
     // A global label: the check of the loader stops here, before an interrupt can run.
-    `${LOADER_JUMP} jmp ${input.entryName ?? hex4(input.entry)}`,
+    `${LOADER_JUMP} jmp ${input.entryName ?? formatC64Address(input.entry)}`,
     ".count  !word 0",
     ".index  !byte 0",
     ".back   !byte 0",
     ...(state.vic === undefined
       ? []
       : [
-          `.vicreg !byte ${VIC_DISPLAY_REGISTERS.map((item) => hex2(item.register)).join(",")}`,
-          `.vicval !byte ${VIC_DISPLAY_REGISTERS.map((item) => hex2(state.vic!.registers[item.register]!)).join(",")}`,
+          `.vicreg !byte ${VIC_DISPLAY_REGISTERS.map((item) => formatC64Byte(item.register)).join(",")}`,
+          `.vicval !byte ${VIC_DISPLAY_REGISTERS.map((item) => formatC64Byte(state.vic!.registers[item.register]!)).join(",")}`,
         ]),
     ".table",
   );
@@ -609,7 +584,7 @@ function vicLines(state: EntryState, earlier: number): string[] {
   return [
     "        lda #$35",
     "        sta $01",
-    `        ldx #${hex2(VIC_DISPLAY_REGISTERS.length - 1)}`,
+    `        ldx #${formatC64Byte(VIC_DISPLAY_REGISTERS.length - 1)}`,
     ".vic    ldy .vicreg,x",
     "        lda .vicval,x",
     "        sta $d000,y",
@@ -617,14 +592,14 @@ function vicLines(state: EntryState, earlier: number): string[] {
     "        bpl .vic",
     "        lda $dd00",
     "        and #$fc",
-    `        ora #${hex2(state.vic.bank)}`,
+    `        ora #${formatC64Byte(state.vic.bank)}`,
     "        sta $dd00",
     `.raster lda $d012`,
-    `        cmp #${hex2(line & 0xff)}`,
+    `        cmp #${formatC64Byte(line & 0xff)}`,
     "        bne .raster",
     "        lda $d011",
     "        and #$80",
-    `        cmp #${hex2((line >> 1) & 0x80)}`,
+    `        cmp #${formatC64Byte((line >> 1) & 0x80)}`,
     "        bne .raster",
   ];
 }