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

package/skills/c64-testing/SKILL.md

@@ -22,23 +22,23 @@ A PASS proves only the behavior that the scenario does and observes. It does not
 The script starts one emulator through the host runtime. It runs the scenario on the original and then on the rebuild. Before each side, it does a hard reset of the emulator. The CPU then stops at the reset vector.
 
 ```
-node <skill>/scripts/test.ts tests/moves-left.json --out .c64-re-tools/local/results/moves-left
-node <skill>/scripts/checklist.ts tests/moves-left.json --item 'FIRE starts the game.'
+node <skill>/scripts/testing.ts test tests/moves-left.json --out .c64-re-tools/local/results/moves-left
+node <skill>/scripts/testing.ts checklist tests/moves-left.json --item 'FIRE starts the game.'
 ```
 
-The test script prints one JSON object. The exit status is 0 for PASS, 1 for FAIL, 3 for INCONCLUSIVE and 2 for a bad call. With `--out`, a FAIL writes files into that directory: both screens and the difference image for each screen difference, and `memory.json` with each byte that differs. `files` in the result names them. A PASS writes no files. To keep the screens of a PASS, use a run (below).
+`testing.ts test` gives `result`: PASS, FAIL or INCONCLUSIVE. With `--out`, a FAIL writes files into that directory: both screens and the difference image for each screen difference, and `memory.json` with each byte that differs. `files` in the result names them. A PASS writes no files. To keep the screens of a PASS, use a run (below).
 
-The checklist script prints a Markdown checklist for a human tester.
+`testing.ts checklist` gives a Markdown checklist for a human tester in `text`.
 
 ### Runs
 
 A run does steps on one program, with no comparison, and keeps the results as files. Use it for many steps. One run replaces many emulator calls, for example a visit to each room of a game.
 
 ```
-node <skill>/scripts/run.ts .c64-re-tools/local/runs/rooms/run.json --out .c64-re-tools/local/runs/rooms
+node <skill>/scripts/testing.ts run .c64-re-tools/local/runs/rooms/run.json --out .c64-re-tools/local/runs/rooms
 ```
 
-The run file gives where to start (a program, or a snapshot file), the steps, and optional symbols. To go on from the live emulator, save its state with `c64_snapshot` action `save` and `out`, and start the run from that file. Besides the steps of a scenario, a run has these steps:
+The run file gives where to start (a program, or a snapshot file), the steps, and optional symbols. To go on from the live emulator, save its state with `c64_snapshot` action `save` and `out`, and start the run from that file. A run has the action steps of a scenario: `write`, `registers`, `joystick`, `type`, `frames` and `runUntil`. It also has these steps:
 
 | Step | Effect |
 |---|---|
@@ -47,47 +47,51 @@ The run file gives where to start (a program, or a snapshot file), the steps, an
 | `{ "screen": "room3" }` | Write the screen to `room3.png`. |
 | `{ "coverage": "room3" }` | Write the coverage map since the start or the last coverage step to `room3.bin`, then clear the map. Add the map to the knowledge with `coverage` of the c64-knowledge skill. |
 | `{ "observe": "room3", "memory": ["$c100"], "registers": true }` | Record memory, registers, `vicii` or `sprites` in `results.json`. |
-| `{ "trace": "d011", "points": [{ "kind": "write", "at": "$d011" }], "frames": 100 }` | Record each hit of the points for 100 frames in `d011.json`: the instruction, its registers and the raster line and cycle. A point is `exec`, `read` or `write`, at an address or a name, with an optional `end`. `maxHits` limits the hits. |
+| `{ "trace": "d011", "points": [{ "kind": "write", "start": "$d011" }], "frames": 100 }` | Record each hit of the points for 100 frames in `d011.json`: the instruction, its registers and the raster line and cycle. A point has the `kind` `exec`, `read` or `write`, a `start` and an optional `end`. `maxHits` limits the hits. |
 | `{ "observe": "all3", "memory": "all" }` | Write all 64 KiB of RAM to `all3.bin`, also the RAM under the ROMs and the I/O area. |
 
 A memory item can have `"view": "ram"`. Then it reads the RAM under the ROMs and the I/O area, for example code at `$e000` under the KERNAL. The default view `cpu` reads as the CPU sees memory. An item larger than 4096 bytes goes into its own `.bin` file, and `results.json` gives the file name.
 
-See [references/scenario-format.md](references/scenario-format.md), section Runs. The script prints one JSON object. The exit status is 0 when all steps ran, 1 when a step did not reach its target, and 2 for a bad call. A long run can need more time than one shell call. Then run it in the background.
+See [references/scenario-format.md](references/scenario-format.md), section Runs. `result` is PASS when all steps ran, and FAIL when a step did not run. `reason` tells why. A long run can need more time than one shell call. Then run it in the background.
 
 ### Recordings
 
 A recording keeps a session of the original program, for example a play through some rooms of a game. A replay gives the same input to a rebuild and compares the game state. Make the recordings early, before you change the program. A recording needs no names. Its coverage also helps the static analysis.
 
-The record and replay scripts run the replay core `c64run` on this machine, not the emulator of the host runtime. The replay core has no disk drive. The program must be a PRG file.
+`testing.ts record` and `testing.ts replay` run the replay core `c64run` on this machine, not the emulator of the host runtime. The replay core has no disk drive. The program must be a PRG file.
 
 Ask the user to play first. Tell the user which parts of the program the recordings must have, for example each room, a fight and a lost life. Make a scripted recording only for a part that the sessions of the user do not have, or when the user cannot play.
 
 ```
-node <skill>/scripts/record.ts tests/record/start.json --out tests/recordings/play1 --play --joystick 1
+node <skill>/scripts/testing.ts record tests/record/start.json --out tests/recordings/play1 --play --joystick 1
 ```
 
 - With `--play`, a person plays the program after the steps of the record file. The steps can start the program, for example a key for an intro.
 - The script writes the address of a page to stderr. Give the address to the user. In a dev container, the port of the page (default 6465) must be forwarded.
-- On the page, the arrow keys, space and a gamepad move the joystick of `--joystick` (default 2). The other keys go to the C64 keyboard.
-- The script runs until the user clicks Stop on the page. Run it in the background. Then it writes the recording folder.
+- The page shows the screen after the steps. The C64 is frozen until the user presses Enter or clicks Start. Tell the user to read the screen first.
+- Give `--joystick` the port that the program reads: port 2 is `$DC00`, and port 1 is `$DC01`. Find the port in the code or in the knowledge. If you do not know the port, use 2. Tell the user that F9 changes the port.
+- The page has the full C64 keyboard and the joystick. F10 changes the arrow keys and space between the joystick and the C64 keys. A gamepad is always the joystick. See the key maps in [references/recording-format.md](references/recording-format.md).
+- RESTORE (Page Up) is not a read. The recording keeps it as an event, and the replay presses it again at the same read.
+- End (F12) stops the C64 and freezes the screen. Then the script writes the recording folder. Run the script in the background.
+- Cancel (F11) stops the session. The script writes no folder and gives `recorded: false` with the reason. Then ask the user what to do. Do not make a scripted recording in its place.
 
-A scripted recording has only steps. See [references/recording-format.md](references/recording-format.md). The steps are `frames`, `joystick`, `type`, `write`, `registers` and `runUntil` with `at` or `memory`.
+A scripted recording has only steps. See [references/recording-format.md](references/recording-format.md). The steps are `frames`, `joystick`, `press`, `type`, `write`, `registers` and `runUntil` with an `address` or `memory` target. `press` pushes keys of the keyboard matrix. `type` puts at most 10 keys into the keyboard queue of the KERNAL.
 
 ```
-node <skill>/scripts/record.ts tests/record/rooms.json --out tests/recordings/rooms
-node <skill>/scripts/replay.ts tests/recordings/rooms --checkpoint main_loop --state room --state lives --pin random_ptr:2 --rebuild build/game.prg --symbols build/game.json
+node <skill>/scripts/testing.ts record tests/record/rooms.json --out tests/recordings/rooms
+node <skill>/scripts/testing.ts replay tests/recordings/rooms --checkpoint main_loop --state room --state lives --pin random_ptr:2 --rebuild build/game.prg --symbols build/game.json
 ```
 
-- The record script writes the recording folder. The exit status is 0 when it recorded the session, 1 when the session did not complete, and 2 for a bad call. `executed` gives the instructions in the coverage map.
-- The replay script first replays the recording on the original. The original must end the session with the recorded state. Then the script replays the recording on the rebuild and compares the state at each checkpoint.
+- `testing.ts record` writes the recording folder. `result` is PASS when it recorded the session, and FAIL when the session did not complete. `executed` gives the instructions in the coverage map.
+- `testing.ts replay` first replays the recording on the original. The original must end the session with the recorded state. Then the script replays the recording on the rebuild and compares the state at each checkpoint.
 - `--checkpoint` gives a routine, and `--state` gives each memory item to compare. Use the names that the knowledge has at the time of the replay. A `$` address is an address of the original. On the rebuild, it moves with the name before it.
-- The replay script gives PASS, FAIL or INCONCLUSIVE, with the exit status 0, 1 or 3. A FAIL gives the first checkpoint that is different and the state items that are different.
-- With `--out`, a FAIL writes the RAM of the two sides at that checkpoint. Compare the two files with `diff.ts`.
-- Without `--rebuild`, the replay script only replays the recording on the original.
+- `result` of the replay is PASS, FAIL or INCONCLUSIVE. A FAIL gives the first checkpoint that is different and the state items that are different.
+- With `--out`, a FAIL writes the RAM of the two sides at that checkpoint. Compare the two files with `testing.ts diff`.
+- Without `--rebuild`, `testing.ts replay` only replays the recording on the original.
 
 A checkpoint is one entry of a routine. Use a routine that the program executes one time in each pass of its game logic, for example the main loop. Do not use an interrupt handler.
 
-The input is the reads of the joystick ports and the keyboard matrix. It is also the reads of the four SID registers that a program can read: the paddles, the noise of voice 3 and its envelope. It is also the reads of `$DE00`-`$DFFF`, where a C64 without a cartridge gives the last byte on the bus. On a replay, the n-th read of each instruction gets the value of the n-th read in the recording. Thus a rebuild with different timing gets the same input and the same SID random numbers. A `write`, `registers` or `runUntil` step is not input. The replay does the step again at the same read of the program.
+The input is the reads of the joystick ports and the keyboard matrix. It is also the reads of the four SID registers that a program can read: the paddles, the noise of voice 3 and its envelope. It is also the reads of `$DE00`-`$DFFF`, where a C64 without a cartridge gives the last byte on the bus. On a replay, the n-th read of each instruction gets the value of the n-th read in the recording. Thus a rebuild with different timing gets the same input and the same SID random numbers. A `press`, `joystick` or `frames` step is input. A `type`, `write`, `registers` or `runUntil` step is not input. The replay does that step again at the same read of the program.
 
 A replay is deterministic. The replay core has no random source and no clock: the same recording gives the same session, to the cycle. Sometimes the recording has no value for a read of an input. Then the read gets a fixed value: `$FF` for the joystick, keyboard and paddle registers, `$00` for the others. `idleReads` in the result counts these reads on the rebuild. On the original, such a read makes the result INCONCLUSIVE.
 
@@ -104,24 +108,36 @@ Commit the recording folder with the scenarios. A recording is not knowledge.
 ### Differences
 
 ```
-node <skill>/scripts/diff.ts .c64-re-tools/local/runs/rooms/before.vsf .c64-re-tools/local/runs/rooms/after.vsf
-node <skill>/scripts/diff.ts .c64-re-tools/local/runs/rooms/results.json:room0 .c64-re-tools/local/runs/rooms/results.json:room3
+node <skill>/scripts/testing.ts diff .c64-re-tools/local/runs/rooms/before.vsf .c64-re-tools/local/runs/rooms/after.vsf
+node <skill>/scripts/testing.ts diff .c64-re-tools/local/runs/rooms/results.json:room0 .c64-re-tools/local/runs/rooms/results.json:room3
 ```
 
-`diff.ts` tells what changed between two states of one kind. Use it in place of your own compare script.
+`testing.ts diff` tells what changed between two states of one kind. Use it in place of your own compare script.
 
 - 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, `--at` gives the address of its first byte.
+- 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.
 
 `--gap N` joins ranges across N equal bytes. `--out` writes all ranges to a project file.
 
+### 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`.
 
@@ -129,9 +145,9 @@ node <skill>/scripts/diff.ts .c64-re-tools/local/runs/rooms/results.json:room0 .
 
 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 `runUntil` 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 `assemble.ts --project <folder> ... > <folder>/build/game.json`.
-5. Run the test script.
+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`.
+5. Run `testing.ts test`.
 6. Read the result:
    - `PASS`: all observations are equal, or the differences are in the allowed tolerance.
    - `FAIL`: `differences` lists each difference with the checkpoint, the item, the original value and the rebuild value.
@@ -171,13 +187,13 @@ PASS, FAIL or INCONCLUSIVE, the checkpoints and the smallest differences that ex
 - A FAIL with only a `screen` difference: add `vicii` or `sprites` to the observation to find which chip state is different.
 - A program that uses random numbers: set the random seed with a `write` step on both sides. If that is not possible, observe only values that do not depend on the random numbers.
 - The two sides start differently, for example the original after a cracked intro. Give the steps that only one side needs a `side`. Then make the memory the same with a `normalize` step. It writes the entry state of the capture in the knowledge.
-- Frame counts drift by one frame between the sides: the sides got to the same address at different raster positions. Do not sync on an IRQ handler. Sync on a value that the IRQ changes, with `runUntil` `memory`, or on an address and a raster line together.
+- Frame counts drift by one frame between the sides: the sides got to the same address at different raster positions. Do not sync on an IRQ handler. Sync on a value that the IRQ changes, with a `runUntil` `memory` target. Or sync on an `address` target with a `raster` condition.
 - INCONCLUSIVE, "does not reproduce": the original does not end the session with the recorded state. Record the session again with this `c64run`.
 - INCONCLUSIVE, "never came to the checkpoint": the original did not execute the checkpoint routine in the session. Give another routine.
 - INCONCLUSIVE, "is not the program of the recording": the program file changed after the recording. Record the session again.
-- A record result with `recorded` false: a step did not reach its target. Change the step.
+- A record result FAIL with `recorded` false: `reason` names the step that did not complete. Examples are a `runUntil` that did not reach its target, and a `type` step with too many keys. Change the step.
 - A record result with `executed` 0: the program never read its input from RAM, so the coverage map is empty. The recording can still replay.
-- A FAIL from a replay: compare the two RAM files of `--out` with `diff.ts`. Then examine the first different state item with the c64-emulator skill.
+- A FAIL from a replay: compare the two RAM files of `--out` with `testing.ts diff`. Then examine the first different state item with the c64-emulator skill.
 - A program that loads more files from a disk: the replay core has no disk drive. Use a test scenario in the emulator.
 - A byte that cannot be the same on both sides, for example a read-only collision register: use `exclude` with the reason. Do not use `exclude` to hide a real difference.
 

package/skills/c64-testing/references/recording-format.md

@@ -2,7 +2,7 @@
 
 ## Record file
 
-A record file (for `record.ts`) is one JSON object in a project file.
+A record file (for `testing.ts record`) is one JSON object in a project file.
 
 ```json
 {
@@ -22,47 +22,76 @@ A record file (for `record.ts`) is one JSON object in a project file.
 - `program`: a PRG file, relative to the project folder.
 - `symbols`: optional. `knowledge` (default), `none`, or a JSON file: the output of the c64-assembler skill, or an object of names and `$` addresses. The steps use these names.
 - `load`: optional. With `false` (default), the program must load at `$0801` with a BASIC start line, and the C64 types `RUN`. With `true`, the program goes into memory and the C64 stays at READY. Then a `registers` step with `pc` starts the program.
-- `checkpoint`, `state` and `pin`: optional. The comparison that a replay uses when the replay gives none. `checkpoint` is the name or `$` address of a routine. Each entry of the routine is a checkpoint. `state` is 1 to 16 memory items that the checkpoints compare. `pin` is the random state in RAM. An item is a name, a `$` address, or `{ "at", "size" }` with a size from 1 to 4096. Give `checkpoint` and `state` together.
+- `checkpoint`, `state` and `pin`: optional. The comparison that a replay uses when the replay gives none. `checkpoint` is the name or `$` address of a routine. Each entry of the routine is a checkpoint. `state` is 1 to 16 memory items that the checkpoints compare. `pin` is the random state in RAM. An item is a name, a `$` address, or `{ "address", "size" }` with a size from 1 to 4096. Give `checkpoint` and `state` together.
 - `inputs`: optional. The I/O addresses (or ranges such as `$de00-$dfff`) whose reads are input. The default is `$dc00` and `$dc01`: the joystick ports and the keyboard matrix. It also has `$d419` to `$d41c` (the paddles, and the noise and envelope of SID voice 3), and `$de00-$dfff` (no device: the last byte on the bus). Add `$d012` or a CIA timer only for a program that reads a seed there and does not wait in a loop on it.
 - `steps`: the steps.
 
 ## Steps
 
-The steps have the form of the steps of a scenario.
+The steps have the form of the steps of a scenario. Two steps behave differently:
+
+- `type` puts at most 10 keys into the keyboard queue of the KERNAL. It is an event: a replay does it again.
+- `press` pushes keys of the keyboard matrix. It is input. A scenario has no `press` step.
+
+A record file has no `raster` target and no `condition`. `write` and `runUntil` have only the space `c64`.
 
 | Step | Effect |
 |---|---|
 | `{ "frames": 300 }` | Run 300 frames (19656 cycles each). |
 | `{ "joystick": { "port": 2, "direction": "left", "fire": true } }` | Set a joystick. It stays in this state until the next joystick step. |
-| `{ "type": "RUN\n" }` | Press each key of the text on the keyboard matrix, for 3 frames, then release it for 3 frames. |
-| `{ "write": { "at": "next_room", "bytes": [1] } }` | Write bytes into RAM. |
+| `{ "press": "RUN\n" }` | Press each key of the text on the keyboard matrix for 3 frames, then release it for 3 frames. |
+| `{ "type": { "mode": "text", "text": "RUN\n" } }` | Put at most 10 keys into the keyboard queue of the KERNAL, after the keys that wait there. |
+| `{ "write": { "address": "next_room", "data": "01" } }` | Write bytes into RAM. |
 | `{ "registers": { "pc": "change_room", "a": 16 } }` | Set registers at the next instruction. `pc` continues the program at that address. |
-| `{ "runUntil": { "at": "main_loop" }, "timeoutFrames": 300 }` | Run until the CPU gets to an address. |
-| `{ "runUntil": { "memory": { "at": "room", "equals": 2 } }, "timeoutFrames": 600 }` | Run until a byte has a value. The script reads the byte at the end of each frame. |
+| `{ "runUntil": { "target": { "kind": "address", "address": "main_loop" }, "timeoutFrames": 300 } }` | Run until the CPU gets to an address. |
+| `{ "runUntil": { "target": { "kind": "memory", "address": "room", "operator": "eq", "value": 2 }, "timeoutFrames": 600 } }` | Run until a byte compares true with `value`. The script reads the byte at the end of each frame. |
 
-The replay core has no `runUntil` with `raster`.
+A `press` step can press A to Z, 0 to 9, space, return (`\n`) and `+-.:@,*;=/!"#$%&'()[]<>?`. It presses a to z as A to Z.
 
-A `type` step can press A to Z, 0 to 9, space, return (`\n`) and `+-.:@,*;=/!"#$%&'()[]<>?`. It types a to z as A to Z.
+The keyboard queue of the KERNAL holds 10 keys. If the keys of a `type` step and the keys that wait in the queue do not fit, the session stops. A program that reads the keyboard hardware does not see the keys of a `type` step. Use `press` for that program.
 
-`joystick`, `type` and `frames` steps are input and time. The recording keeps their effect in the reads, so a replay does not do these steps again.
+`joystick`, `press` and `frames` steps are input and time. The recording keeps their effect in the reads, so a replay does not do these steps again.
 
-`write`, `registers` and `runUntil` steps are events. The recording keeps a point in the program for each event. The point is the next read at the input site with the most reads. That site is not in ROM. A replay does the event at the same read. An event that comes directly after another event runs at once after that event.
+`type`, `write`, `registers` and `runUntil` steps are events. The recording keeps a point in the program for each event. The point is the next read at the input site with the most reads. That site is not in ROM. A replay does the event again at the same read. An event that comes directly after another event runs at once after that event.
 
 ## Play
 
-With `--play`, `record.ts` does the steps, then a person plays. The page on `http://localhost:<port>/` (`--http-port`, default 6465) shows the screen at 50 frames each second. It has no sound.
+With `--play`, `testing.ts record` does the steps, then a person plays. The page on `http://localhost:<port>/` (`--http-port`, default 6465) shows the screen at 50 frames each second. It has no sound.
+
+| Button | Key | Effect |
+|---|---|---|
+| Start | Enter, on the start screen | The C64 runs. Before Start, the page shows the screen after the steps, and the C64 is frozen. The time before Start is not in the recording. |
+| End and save | F12 | The C64 stops at the frame on the page, and the screen stays frozen. The script writes the recording folder. |
+| Cancel | F11 | The session stops before or during the play. The script writes no folder and gives `recorded: false`. |
+| Port | F9 | The joystick goes to the other port. `--joystick` gives the first port (default 2). |
+| Arrows | F10 | The arrow keys and space change between the joystick and the C64 keys. At the start, they are the joystick. |
+| Keys | | The keyboard changes between the symbolic map (the default) and the positional map. |
+
+The buttons are in one row above the screen.
 
 | Page input | C64 input |
 |---|---|
-| Arrow keys, space | The joystick of `--joystick` (default 2): directions and fire. |
-| A gamepad | The same joystick: the left stick or the cross for directions, button 1 or 2 for fire. |
-| A-Z, 0-9, the symbols of a `type` step, Return, Backspace (DEL), Escape (RUN/STOP), F1-F8 | The C64 keyboard. |
+| Arrow keys and space, when they are the joystick | The joystick: directions and fire. |
+| A gamepad | The joystick: the left stick or the cross for directions, button 1 or 2 for fire. |
+| Arrow keys and space, when they are C64 keys | CRSR up, down, left and right, and SPACE. |
+| Escape, Shift+Escape | RUN/STOP, RUN |
+| Page Up | RESTORE |
+| Tab, left Alt | CTRL, C= |
+| Home, Shift+Home | CLR/HOME, CLR |
+| Backspace, Shift+Backspace | INST/DEL, INST |
+| F1-F8 | F1-F8 |
+
+In the symbolic map, a key gives the character on the PC key. a-z give the C64 letters, and A-Z give the letters with SHIFT. The digits and the symbols give the same characters. `£` gives the pound key, `^` gives the up arrow, and the backquote gives the left arrow.
+
+In the positional map, a key gives the C64 key at the same place on the keyboard. Each SHIFT key is a C64 SHIFT key, also alone. The C64 keys `+ - @ * : ; =` are on the PC keys `- = [ ] ; ' \`. Insert gives the pound key, Delete gives the up arrow, and the backquote gives the left arrow. Use the positional map when the program reads SHIFT alone or a key with SHIFT.
+
+Ctrl and Cmd are not C64 keys. They keep their function in the browser.
 
-Stop on the page ends the session, and the script writes the recording folder. The input of the page goes into the reads, as the input of the steps does.
+The page sends input only between Start and End. The input of the page goes into the reads, as the input of the steps does. RESTORE starts an NMI and is not a read. The recording keeps each RESTORE as an event without a step number. The replay presses RESTORE again at the same read of the program.
 
 ## Recording folder
 
-`record.ts` writes these files into the `--out` folder:
+`testing.ts record` writes these files into the `--out` folder:
 
 | File | Content |
 |---|---|
@@ -74,7 +103,7 @@ A site is the address of the instruction that reads. The values are hex. `<from>
 
 ## Replay
 
-`replay.ts` replays a recording folder:
+`testing.ts replay` replays a recording folder:
 
 1. It replays the recording on the original program. The session must end with the recorded cycles and state hash. Else the result is INCONCLUSIVE. It also takes the state at each checkpoint of the original.
 2. With `--rebuild`, it replays the recording on the rebuild. At each checkpoint, the rebuild first gets the pinned values of the original. Then the script compares the state. The cycles can be different.
@@ -89,7 +118,7 @@ The result is one JSON object:
 - `side`: `original` for the check of the original only, `rebuild` with `--rebuild`.
 - `checkpoint`: the routine of the comparison.
 - `checkpoints` and `compared`: the checkpoints of the original, and the checkpoints of the rebuild that were the same.
-- `firstDifference`: on a FAIL, the checkpoint (1 is the first), the cycle on each side, and each state item that is different, as hex.
+- `firstDifference`: on a FAIL, the checkpoint (1 is the first), the cycle on each side, and each state item that is different. An item has `address`, and the `original` and `rebuild` values as hex.
 - `reason`: why the result is FAIL or INCONCLUSIVE.
 - `movedSites`: the number of sites at a different address in the rebuild.
 - `idleReads`: the input reads of the rebuild that the recording had no value for. Such a read is at a site that the recording does not have, or after its end. Each got the fixed value `$FF` (joystick, keyboard, paddles) or `$00`. An input site that the site map did not find shows here.

package/skills/c64-testing/references/scenario-format.md

@@ -11,10 +11,10 @@ A scenario is one JSON object in a project file.
     { "frames": 150 },
     { "load": true },
     { "registers": { "pc": "start" } },
-    { "runUntil": { "at": "main_loop" }, "timeoutFrames": 600 },
+    { "runUntil": { "target": { "kind": "address", "address": "main_loop" }, "timeoutFrames": 600 } },
     { "joystick": { "port": 2, "direction": "left" } },
     { "frames": 10 },
-    { "observe": "moved", "memory": ["player_x", { "at": "$0400", "size": 40 }], "screen": {} }
+    { "observe": "moved", "memory": ["player_x", { "address": "$0400", "size": 40 }], "screen": {} }
   ]
 }
 ```
@@ -41,25 +41,30 @@ Before the first step of each side, the script does a hard reset. The CPU stops
 | `{ "frames": 150 }` | Run for an exact number of frames, from 1 to 30000. A breakpoint or a watchpoint stops it before that. Use it after a reset to start the C64. |
 | `{ "load": true }` | Load the program of the side into memory. The CPU stays stopped. |
 | `{ "autostart": true }` | Load the program of the side, type `RUN` and wait until the program runs. The program must have a BASIC start line. The keys of a later `type` step go to the program. |
-| `{ "write": { "at": "seed", "bytes": [1, 2] } }` | Write bytes into memory: 1 to 4096 numbers from 0 to 255. |
-| `{ "registers": { "pc": "start", "a": 0 } }` | Set registers: `pc`, `a`, `x`, `y` or `sp`. A value is a number or a name. |
-| `{ "joystick": { "port": 2, "direction": "left", "fire": true } }` | Set a joystick. The joystick stays in this state until the next joystick step. |
-| `{ "type": "RUN\n" }` | Type text on the keyboard, at most 1024 keys. The keys go into the keyboard queue of the KERNAL. A program that reads the keyboard hardware does not see them. A step cannot press one specific key of the keyboard matrix. |
-| `{ "runUntil": { "at": "main_loop" }, "timeoutFrames": 600 }` | Run until the CPU gets to an address. |
-| `{ "runUntil": { "memory": { "at": "game_state", "equals": 2 } }, "timeoutFrames": 600 }` | Run until a byte in memory has a value. |
-| `{ "runUntil": { "raster": 250 }, "timeoutFrames": 5 }` | Run until the raster beam gets to a line (0 to 311 for PAL, 0 to 262 for NTSC). |
-| `{ "runUntil": { "at": "irq_tick", "raster": 250 }, "timeoutFrames": 600 }` | Run until the CPU gets to an address while the beam is on that line. |
+| `{ "write": { "address": "seed", "data": "0102" } }` | Write 1 to 4096 bytes into memory. Optional: `space` (`c64` or `drive8`, default `c64`) and `view` (`cpu` or `ram`, default `cpu`). |
+| `{ "registers": { "pc": "start", "a": 0, "flags": { "i": true } } }` | Set registers: `pc`, `a`, `x`, `y`, `sp` and `flags` (`n`, `v`, `b`, `d`, `i`, `z`, `c`). Only `pc` can be a name. |
+| `{ "joystick": { "port": 2, "direction": "left", "fire": true } }` | Set a joystick. `fire` is `false` by default. The joystick stays in this state until the next joystick step. |
+| `{ "type": { "mode": "text", "text": "RUN\n" } }` | Put at most 1024 keys into the keyboard queue of the KERNAL. A program that reads the keyboard hardware does not see them. |
+| `{ "type": { "mode": "petscii", "bytes": [147] } }` | Put PETSCII codes from 1 to 255 into the keyboard queue of the KERNAL. Use it for keys that mode `text` does not have. |
+| `{ "runUntil": { "target": { "kind": "address", "address": "main_loop" }, "timeoutFrames": 600 } }` | Run until the CPU gets to an address. |
+| `{ "runUntil": { "target": { "kind": "memory", "address": "game_state", "operator": "eq", "value": 2 }, "timeoutFrames": 600 } }` | Run until a byte in memory compares true with `value`. `operator` is `eq`, `ne`, `lt`, `lte`, `gt` or `gte`. |
+| `{ "runUntil": { "target": { "kind": "raster", "line": 250 }, "timeoutFrames": 5 } }` | Run until the raster beam gets to a line (0 to 311 for PAL, 0 to 262 for NTSC). Optional: `cycle` from 0 to 64. |
+| `{ "runUntil": { "target": { "kind": "address", "address": "irq_tick", "condition": { "kind": "raster", "line": 250 } }, "timeoutFrames": 600 } }` | Run until the CPU gets to an address while the condition is true. |
 | `{ "snapshot": "snapshots/start.vsf" }` | Restore a snapshot file. Usually with `side`: the snapshot of one program is not a state of the other. |
 | `{ "normalize": true }` | Write pages 0 to 3 and `$00`/`$01` from the entry state in the knowledge. The entry state comes from a capture of the c64-unpacker skill, which `image` of the c64-knowledge skill put in. Then both sides have the same zero page, stack and KERNAL work area. |
 | `{ "observe": "moved", ... }` | Record a checkpoint. |
 
 The `port` of a joystick is 1 or 2. The `direction` is `center`, `up`, `down`, `left`, `right`, `up-left`, `up-right`, `down-left` or `down-right`.
 
-`timeoutFrames` is from 1 to 30000. A `runUntil` that does not get to its target in `timeoutFrames` frames makes the result INCONCLUSIVE.
+A `condition` has the `kind` `register`, `memory` or `raster`. A `register` condition has `register` (`a`, `x`, `y` or `sp`), `operator` and `value`. A `memory` condition has `address`, `operator` and `value`. A `raster` condition has `line` and an optional `cycle`.
+
+`timeoutFrames` is from 1 to 30000, and 3000 by default. A `runUntil` that does not get to its target in `timeoutFrames` frames makes the result INCONCLUSIVE.
+
+A scenario has no `press` step. Only a record file has `press` for keys of the keyboard matrix.
 
 Each step except `observe` can have `"side": "original"` or `"side": "rebuild"`. Then only that side does the step. Use it when only one side needs a step, for example a key for the intro of the original. An `observe` step has no `side`, because it compares both sides.
 
-An address is `$` and four hex digits, or a symbol name. Each side finds a name in its own symbols.
+Each side finds a name in its own symbols.
 
 ## Observations
 
@@ -67,7 +72,7 @@ An `observe` step has a checkpoint name. A scenario can have each name only one
 
 | Key | What the script compares |
 |---|---|
-| `memory` | A list of names, `$` addresses, or objects. An object has `at`, `size` (1 to 65536, default 1), `view` (`cpu` or `ram`, default `cpu`), `tolerance` (0 to 255, default 0) and `exclude`. The view `ram` reads the RAM under the ROMs and the I/O area. |
+| `memory` | A list of names, `$` addresses, or objects. An object has `address`, `size` (1 to 65536, default 1), `view` (`cpu` or `ram`, default `cpu`), `tolerance` (0 to 255, default 0) and `exclude`. The view `ram` reads the RAM under the ROMs and the I/O area. |
 | `registers` | A list of register names: `pc`, `a`, `x`, `y`, `sp`, `flags`. |
 | `screen` | The screen of the rebuild against the screen of the original. `maxMismatchRatio` (default 0) is the largest permitted part of different pixels. `mask` is a list of rectangles (`x`, `y`, `width`, `height`) that the comparison does not include. |
 | `vicii` | The VIC-II state: mode, screen address, scroll and colors. |
@@ -75,13 +80,13 @@ An `observe` step has a checkpoint name. A scenario can have each name only one
 
 A `tolerance` is the largest permitted difference for each byte. A `mask` has at most 64 rectangles. A `mask` must not cover all of the screen: PAL is 384×272 pixels and NTSC is 384×247 pixels. A scenario can observe the screen at most at 64 checkpoints.
 
-`exclude` is a list of bytes in the observed range that the comparison does not include. Each has `at` and a `reason`, for example `{ "at": "$d01e", "reason": "latched sprite collision, not writable" }`. The result lists each excluded byte with its reason.
+`exclude` is a list of bytes in the observed range that the comparison does not include. Each has `address` and a `reason`, for example `{ "address": "$d01e", "reason": "latched sprite collision, not writable" }`. The result lists each excluded byte with its `address` and `reason`.
 
 A `pc` value is an address. Compare `pc` only when both programs have the code at the same address.
 
 ## Runs
 
-A run file (for `run.ts`) has:
+A run file (for `testing.ts run`) has:
 
 - `name`: a short name.
 - `start`: `{ "program": "game.prg" }` to autostart a program with a BASIC start line, `{ "program": "game.prg", "load": true }` to load it with the CPU stopped (set `pc` in a step), or `{ "snapshot": ".c64-re-tools/local/snapshots/room0.vsf" }`.
@@ -89,9 +94,9 @@ A run file (for `run.ts`) has:
 - `videoStandard`: optional, `pal` (default) or `ntsc`.
 - `steps`: the steps `write`, `registers`, `joystick`, `type`, `frames` and `runUntil` of a scenario, and the run steps `snapshot`, `save`, `screen`, `coverage`, `trace` and `observe`.
 
-A `trace` step has a name, `points` (1 to 8), `frames` (1 to 3000) and an optional `maxHits` (at most 20000). A point has `kind` (`exec`, `read` or `write`), `at` and an optional `end`. The step writes `<name>.json` with each hit. `results.json` gives the file, the count of hits, the frames and why the trace ended. A trace that a breakpoint, a watchpoint or a JAM ends also ends the run.
+A `trace` step has a name, `points` (1 to 8), `frames` (1 to 3000) and an optional `maxHits` (at most 20000). A point has `kind` (`exec`, `read` or `write`), `start` and an optional `end`. The step writes `<name>.json` with each hit. `results.json` gives the file, the count of hits, the frames and why the trace ended. A trace that a breakpoint, a watchpoint or a JAM ends also ends the run.
 
-In a run, a memory item has `at`, `size` (1 to 65536) and `view`. An item larger than 4096 bytes goes into the file `<observe>-<at>.bin`. `"memory": "all"` writes all 64 KiB of RAM to `<observe>.bin`.
+In a run, a memory item has `address`, `size` (1 to 65536) and `view`. An item larger than 4096 bytes goes into the file `<observe>-<address>.bin`, without the `$`. `"memory": "all"` writes all 64 KiB of RAM to `<observe>.bin`.
 
 A name in `save`, `screen`, `coverage` and `observe` has 1 to 64 letters, digits, dots, underscores or hyphens. The files go into the `--out` directory, with `results.json`. It has the observations, the files and the steps done. If a `runUntil` step did not reach its target, it also tells why the run stopped.
 
@@ -102,12 +107,12 @@ Example: visit two rooms from the same start.
   "name": "rooms",
   "start": { "snapshot": ".c64-re-tools/local/snapshots/room0.vsf" },
   "steps": [
-    { "write": { "at": "$0350", "bytes": [1] } },
+    { "write": { "address": "$0350", "data": "01" } },
     { "frames": 50 },
     { "screen": "room1" },
     { "coverage": "room1" },
     { "snapshot": ".c64-re-tools/local/snapshots/room0.vsf" },
-    { "write": { "at": "$0350", "bytes": [2] } },
+    { "write": { "address": "$0350", "data": "02" } },
     { "frames": 50 },
     { "screen": "room2" },
     { "coverage": "room2" }

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

@@ -1,37 +1,15 @@
-// The c64-testing diff script: what changed between two machine states.
+// The diff of c64-testing: what changed between two machine states.
 // Two snapshot files are restored one after the other in an own emulator,
 // which reads RAM, colour RAM and the chip and CPU registers with the readers
 // that the runs use: VICE reads its own snapshot format. Two memory files of a
 // run, or two observations of runs (also two of one run), compare as they are.
-// Exit status: 0, or 2 for a bad call.
-
-import { parseArgs } from "node:util";
 
 import { formatC64Address, parseC64Address } from "#src/c64.ts";
 import { WireFailure } from "#src/host-client/tools.ts";
-import { readProjectFile, writeProjectFile } from "#src/host-client/transfer.ts";
+import { readProjectFile, writeReported } from "#src/host-client/transfer.ts";
 import { readMemoryInParts, ViceSessionClient } from "#src/host-client/vice-session.ts";
-import { resolveProjectPath } from "#src/project.ts";
-import { runScript, UsageError } from "#src/script.ts";
-import { diffStates, type ChangedRange, type MachineState } from "./lib/diff.ts";
-
-const USAGE = `diff.ts <a> <b> [--gap N] [--max-listed N] [--ntsc] [--at <address>] [--out <file>]
-
-<a> and <b> are two of one kind, relative to the project folder:
-  snapshot.vsf             the emulator restores each one and reads RAM, colour
-                           RAM, the VIC-II, CIA, SID and CPU registers
-  memory.bin               a memory file of a run (observe with memory "all" or
-                           a size above 4096); --at gives the address of its
-                           first byte when it is shorter than 64 KiB
-  results.json:<name>      the observation <name> of a run; both can be in
-                           one results.json
-
-  --gap N         join changed ranges across at most N equal bytes (default 0)
-  --max-listed N  list at most N ranges of each part (default 64)
-  --ntsc          the snapshots are of an NTSC machine (default PAL)
-  --out <file>    also write all ranges to a project file
-
-The result is one JSON object. Addresses are $ and four hex digits.`;
+import { listed, UsageError } from "#src/script.ts";
+import { diffStates, type ChangedRange, type MachineState } from "./diff.ts";
 
 type Kind = "snapshot" | "memory" | "observation";
 
@@ -91,54 +69,26 @@ async function snapshotState(client: ViceSessionClient, path: string): Promise<M
 
 const show = (range: ChangedRange) => ({ start: formatC64Address(range.start), end: formatC64Address(range.end), ...(range.a === undefined ? {} : { a: range.a, b: range.b }) });
 
-async function run(argv: string[]): Promise<Record<string, unknown>> {
-  const { values, positionals } = parseArgs({
-    args: argv,
-    strict: true,
-    allowPositionals: true,
-    options: { gap: { type: "string" }, "max-listed": { type: "string" }, ntsc: { type: "boolean" }, at: { type: "string" }, out: { type: "string" }, help: { type: "boolean" } },
-  });
-  if (values.help) throw new UsageError("");
-  if (positionals.length !== 2) throw new UsageError("give two states to compare");
-  const [first, second] = positionals as [string, string];
+/** 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);
   if (kindOf(second) !== kind) throw new UsageError("give two states of one kind: two snapshots, two memory files or two observations");
-  const number = (value: string | undefined, fallback: number, what: string) => {
-    if (value === undefined) return fallback;
-    if (!/^\d+$/.test(value)) throw new UsageError(`${what} must be a whole number`);
-    return Number(value);
-  };
-  const gap = number(values.gap, 0, "--gap");
-  const max = number(values["max-listed"], 64, "--max-listed");
-  if (values.out !== undefined) {
-    try {
-      resolveProjectPath(values.out);
-    } catch {
-      throw new UsageError(`--out must be a path relative to the project folder that stays inside it, not ${values.out}`);
-    }
-  }
+  const { gap, max } = options;
   let a: MachineState;
   let b: MachineState;
   if (kind === "observation") {
     a = observation(first);
     b = observation(second);
   } else if (kind === "memory") {
-    let base = 0;
-    if (values.at !== undefined) {
-      try {
-        base = parseC64Address(values.at);
-      } catch {
-        throw new UsageError(`--at must be $ followed by four hex digits, not ${values.at}`);
-      }
-    }
+    const base = options.at ?? 0;
     const read = (path: string) => readProjectFile(path).bytes;
     const [left, right] = [read(first), read(second)];
     if (left.length !== right.length) throw new UsageError(`the memory files have ${left.length} and ${right.length} bytes; give two of one size`);
-    if (base + left.length > 0x10000) throw new UsageError("the memory file goes past $ffff from --at");
+    if (base + left.length > 0x10000) throw new UsageError("the memory file goes past $ffff from --address");
     a = { memory: { base, bytes: left } };
     b = { memory: { base, bytes: right } };
   } else {
-    const client = await ViceSessionClient.open({ videoStandard: values.ntsc ? "ntsc" : "pal" });
+    const client = await ViceSessionClient.open({ videoStandard: options.ntsc ? "ntsc" : "pal" });
     try {
       a = await snapshotState(client, first);
       b = await snapshotState(client, second);
@@ -147,21 +97,20 @@ async function run(argv: string[]): Promise<Record<string, unknown>> {
     }
   }
   const diff = diffStates(a, b, gap);
-  const part = (item: { changedBytes: number; ranges: ChangedRange[] } | undefined) =>
-    item === undefined ? undefined : { changedBytes: item.changedBytes, ranges: item.ranges.length, listed: item.ranges.slice(0, max).map(show) };
-  if (values.out !== undefined) {
+  const rest = options.out ?? "a larger --max-listed, or --out <file>";
+  const part = (item: { changedBytes: number; ranges: ChangedRange[] } | undefined) => (item === undefined ? undefined : { changedBytes: item.changedBytes, ...listed(item.ranges, max, show, rest) });
+  let written: ReturnType<typeof writeReported> | undefined;
+  if (options.out !== undefined) {
     const all = { a: first, b: second, ...(diff.memory === undefined ? {} : { memory: diff.memory.ranges.map(show) }), ...(diff.colorRam === undefined ? {} : { colorRam: diff.colorRam.ranges.map(show) }), values: diff.values ?? [], observed: diff.observed ?? [] };
-    writeProjectFile(values.out, Buffer.from(`${JSON.stringify(all, null, 2)}\n`), { what: "--out" });
+    written = writeReported(options.out, `${JSON.stringify(all, null, 2)}\n`, { what: "--out" });
   }
   return {
     a: first,
     b: second,
     ...(diff.memory === undefined ? {} : { memory: part(diff.memory) }),
     ...(diff.colorRam === undefined ? {} : { colorRam: part(diff.colorRam) }),
-    ...(diff.values === undefined ? {} : { registers: diff.values.slice(0, max) }),
-    ...(diff.observed === undefined ? {} : { observed: diff.observed.slice(0, max) }),
-    ...(values.out === undefined ? {} : { out: values.out }),
+    ...(diff.values === undefined ? {} : { registers: listed(diff.values, max, undefined, rest) }),
+    ...(diff.observed === undefined ? {} : { observed: listed(diff.observed, max, undefined, rest) }),
+    ...(written === undefined ? {} : written),
   };
 }
-
-await runScript(run, { usage: USAGE });

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

@@ -3,6 +3,8 @@
 // from snapshots that VICE restores, from memory files, or from the
 // observations of runs; this file only compares.
 
+import { Refusal } from "#src/errors.ts";
+
 export interface MachineState {
   /** Bytes from `base`: all 64 KiB of RAM, or the bytes of one memory file. */
   memory?: { base: number; bytes: Uint8Array };
@@ -26,7 +28,7 @@ export interface StateDiff {
   memory?: { changedBytes: number; ranges: ChangedRange[] };
   colorRam?: { changedBytes: number; ranges: ChangedRange[] };
   values?: Array<{ name: string; a: number; b: number }>;
-  observed?: Array<{ at: string; a: string; b: string }>;
+  observed?: Array<{ address: string; a: string; b: string }>;
 }
 
 /** Changed ranges of two byte arrays of one length, joined across gaps of at most `gap` equal bytes. */
@@ -52,7 +54,7 @@ export function changedRanges(a: Uint8Array, b: Uint8Array, base: number, gap =
 export function diffStates(a: MachineState, b: MachineState, gap = 0): StateDiff {
   const result: StateDiff = {};
   if (a.memory !== undefined && b.memory !== undefined) {
-    if (a.memory.base !== b.memory.base || a.memory.bytes.length !== b.memory.bytes.length) throw new Error("the two memory parts do not cover the same addresses");
+    if (a.memory.base !== b.memory.base || a.memory.bytes.length !== b.memory.bytes.length) throw new Refusal("operation-failed", "the two memory parts do not cover the same addresses");
     result.memory = changedRanges(a.memory.bytes, b.memory.bytes, a.memory.base, gap);
   }
   if (a.colorRam !== undefined && b.colorRam !== undefined) result.colorRam = changedRanges(a.colorRam, b.colorRam, 0xd800, gap);
@@ -64,7 +66,7 @@ export function diffStates(a: MachineState, b: MachineState, gap = 0): StateDiff
   if (a.observed !== undefined && b.observed !== undefined) {
     result.observed = Object.keys(a.observed)
       .filter((at) => b.observed![at] !== undefined && a.observed![at] !== b.observed![at])
-      .map((at) => ({ at, a: a.observed![at]!, b: b.observed![at]! }));
+      .map((at) => ({ address: at, a: a.observed![at]!, b: b.observed![at]! }));
   }
   return result;
 }