@henols/c64-re-tools 0.2.2 → 0.2.4

package/skills/c64-ram-capture/SKILL.md

@@ -15,11 +15,11 @@ and name the offending address when it is wrong.
 
 ```bash
 S=src/skills/c64-ram-capture/scripts    # from the repo root
-P=$S/d64-parse.mjs   A=$S/dump-artifacts.mjs
+A=$S/dump-artifacts.mjs
 C=$S/compare.mjs     L=$S/releases.mjs
+T=$S/derive-transients.mjs               V=$S/vsf-slice.mjs
+TD=src/skills/c64-ram-capture/transients # the derived allow-lists live here
 
-node $P directory --image path/to/image.d64      # what's on the disk (--json flags faked entries)
-node $P bam       --image path/to/image.d64      # disk name, DOS type, occupied track ranges
 node $A assemble  --chunks chunks.json           # size + digest, writes nothing
 node $A write-set --release <id> --label <label> \
                   --chunks chunks.json --raw raw.json    # the four committed artifacts
@@ -28,10 +28,16 @@ node $L list                                     # the valid --release ids
 node $C digest  dump.bin                         # sha256 + size, for the capture record
 node $C compare a.bin b.bin                      # classify every difference, exit 1 on FAIL
 node $C floor   a.bin b.bin c.bin                # drift floor across a capture set
+
+node $T derive --release <id> --out $TD/<id>.json a.bin b.bin c.bin
+node $T check  --allow-list $TD/<id>.json a.bin b.bin
+
+node $V slice  run1.vsf --out run1.bin           # flat 64K image from a .vsf snapshot
+node $V digest run1.vsf                          # sha256 + size, writing no file
 ```
 
-All three modules read only committed files and the JSON **you** wrote from your
-own `mcp__plugin_c64-re-tools_vice__*` calls. They contact nothing.
+Every module above reads only committed files and the JSON **you** wrote from
+your own `mcp__plugin_c64-re-tools_vice__*` calls. They contact nothing.
 
 **Prerequisite: a resolvable project root.** `scripts/project-paths.mjs` uses
 `C64RE_PROJECT_ROOT` when it is set, and otherwise walks up from the toolkit's
@@ -51,31 +57,9 @@ variable — the thrown error names both when this fails.
 
 ## Read the disk first
 
-`scripts/d64-parse.mjs` parses `.d64` bytes directly, so it answers what is on the
-disk whether or not the emulator is up:
-
-```bash
-$ node $P directory --image demo.d64
-PRG "DEMO GAME" first=5/0 blocks=5
-
-$ node $P bam --image demo.d64
-disk name: "DEMO DISK"  id: 38  dos type: 2A
-first dir sector: 18/1
-occupied track ranges: 5
-```
-
-Do not eyeball the directory for fakery — `--json` decides it. Every entry carries
-`suspicious` plus `suspicious_reasons`, set when the block count is 0, when the
-first track/sector falls outside the image, or when it points into a track the BAM
-reports as entirely free. That last case is the signature of an entry claiming a
-file never written to disk.
-
-`scripts/d64-parse.test.mjs` proves the detector both **fires** on a synthetic
-faked entry and stays silent on a well-formed one — a guard proven only silent is
-not a guard. It also sweeps whatever real `.d64` corpus the project ships,
-skipping when there is none. A non-null `chain_error` is the separate failure: a
-directory chain that leaves the image or loops, reported instead of hanging.
-**Confidence: HIGH** (synthetic fire-and-silence tests, plus a corpus sweep).
+Disk-image structure — the directory, the block allocation map, a named file's
+sector chain or raw bytes, and directory-fakery detection — is
+`c64-disk-access`'s job now. Read the disk with it before booting anything.
 
 ## Boot a disk
 
@@ -128,6 +112,17 @@ Read state before you resume, and resume exactly once at the end.
 Hold keys down across a gate by releasing them at the trigger checkpoint in
 step 3, never earlier.
 
+**Fill the record's reproducibility key in the same step.**
+`templates/capture-record.template.md`'s Identity table carries three rows that
+are one key, not three facts: `binary sha256`, `argv digest` and `seed`. The
+seed alone is **not** the key — measured, the same seed with a reordered argv
+yielded a 76-byte-different image, so two captures whose argv digests differ are
+different keys and must not be compared as a pair. A record with any of those
+three blank is not a reproducible capture and the void protocol applies. The
+table also carries a `capture route` row (`memory-read` or `snapshot`), and
+**on the snapshot route the `$D000-$DFFF` volatility rule below does not
+apply** — a difference there is a real difference.
+
 `assemble` runs the same assertions and writes nothing, so it is the cheap check
 on a set of chunks before committing them.
 
@@ -164,12 +159,12 @@ only after the provenance diff partitions loader from cracktro from game — see
 
 ## Find an entry point
 
-1. Press past any "hit any key" gate with `mcp__plugin_c64-re-tools_vice__vice_keyboard_matrix`.
-   **This call requires the fork backend** — the binary monitor's `KEYBOARD_FEED` only injects
-   PETSCII text into the KERNAL buffer and cannot drive the raw matrix. On stock, use
-   `vice_keyboard_type` / `vice_keyboard_petscii` when the gate reads the KERNAL buffer, or
-   `vice_joystick_set` when it polls the matrix directly; buffer injection stays invisible to a
-   program polling `$DC00`/`$DC01` itself.
+1. Press past any "hit any key" gate. **`vice_keyboard_matrix` is permanently unavailable** — the
+   binary monitor's `KEYBOARD_FEED` only injects PETSCII text into the KERNAL buffer and cannot
+   drive the raw matrix; see `docs/stock-hard-losses.md`. Use `vice_keyboard_type` /
+   `vice_keyboard_petscii` when the gate reads the KERNAL buffer, or `vice_joystick_set` when it
+   polls the matrix directly; buffer injection stays invisible to a program polling
+   `$DC00`/`$DC01` itself.
 2. Step forward in batches with `mcp__plugin_c64-re-tools_vice__vice_execution_step`, reading
    `mcp__plugin_c64-re-tools_vice__vice_registers_get` after each batch.
 3. Stop when the program counter and the stack pointer both settle into a
@@ -256,8 +251,8 @@ were guaranteed. Region first, bit-count second.
 `$E000-$FFFF` (RAM under KERNAL ROM when HIRAM = 0) is deliberately **not**
 excluded. `$FAD8` and `$FC51` do differ across captures, but only two addresses
 out of 8192 — too few for power-on garbage, and unexplained. They still fail, and
-what writes them is an open question. Evidence and grading:
-`.planning/RE-FINDINGS.md`, 2026-08-04.
+what writes them is an open question. Observed 2026-08-04; graded MEDIUM,
+structural, not reproduced against a second release.
 
 **Establish a drift floor** with `floor` across every capture of one checkpoint.
 It reports each address that differed in any pairing, with the distinct values
@@ -271,6 +266,76 @@ Capture the power-on image as the very first action against a fresh machine, the
 idle-capture twice more and run `floor` over the set. State the result as a
 floor, not a complete set — more captures can only widen it.
 
+## Derive a per-release transient allow-list
+
+`scripts/derive-transients.mjs` is the named, repeatable derivation. **The
+method is what carries forward between releases; no address set ever does.** Two
+verbs:
+
+```bash
+node $T derive --release <id> --out $TD/<id>.json run1.bin run2.bin run3.bin
+node $T check  --allow-list $TD/<id>.json runA.bin runB.bin
+```
+
+`derive` takes **N ≥ 3** runs of the same release under the same protocol at the
+same stop and writes the **union of addresses differing across every pairwise
+comparison** — one entry per address, carrying which pairings it differed in,
+the distinct bytes seen, and an empty attribution line for you to fill. Fewer
+than three images is refused naming the count and the minimum; an image that is
+not exactly 65536 bytes is refused naming the path and the length. It prints
+`TRANSIENT_COUNT: <n>` at column 0, so a measurement gets transcribed rather
+than paraphrased.
+
+**Over the cap of 64 addresses the derivation is VOID:** non-zero exit, **no
+artifact written**, and the message says what the overflow means — the stop is
+not frame-exact. That is a fact to record, not a threshold to raise. `--cap`
+only ever *narrows*; a value above 64 is refused by name, and the union is never
+truncated to fit, because a truncated list makes every later comparison pass on
+bytes nobody vetted. Overflow is a **measured** outcome: 0 differing addresses
+at a frame-exact `READY` stop, 66 at a frame-anchored autostarted stop at
+jitter 4000 ms, 300 at a wall-clock autostarted stop on a real release, 1242 at
+a wall-clock `READY` stop with the determinism block applied.
+
+Re-deriving over an existing artifact is **refused without `--force`**, with the
+no-inheritance rule in the message: an inherited list cannot be distinguished
+afterwards from an honestly derived one.
+
+`check` re-checks one pair against an already-committed derivation without
+re-deriving it, printing `CHECK_VERDICT: equivalent | not-equivalent` and exiting
+1 when not equivalent. Note what it does **not** carry: no address range is a
+volatile span, and there is no bit-count tolerance at any address — a one-bit
+difference outside the list fails. Those two rules belong to `compare.mjs` and
+are deliberately not inherited. `src/skills/c64-ram-capture/transients/README.md`
+holds the artifact shape, the committed method and the cap's reasoning.
+
+## Slice the image out of a snapshot instead of transcribing it
+
+`scripts/vsf-slice.mjs` produces the flat 64K image by slicing a VICE `.vsf`
+snapshot's memory module body. Two verbs:
+
+```bash
+node $V slice  run1.vsf --out run1.bin   # writes exactly 65536 bytes
+node $V digest run1.vsf                 # sha256 + size, writing no file
+```
+
+Add `--json` to either for the same summary as one JSON object — it carries the
+snapshot's memory-module minor, the observed body length, and the three CPU port
+read-back values.
+
+**The one thing that matters operationally: this route has no transcription
+step, so the `$D000-$DFFF` volatility rule above does *not* apply to an image
+produced this way.** That rule exists because `vice_memory_read` samples live
+I/O. The snapshot array is RAM *under* I/O, not the register read view, so those
+4096 addresses are ordinary RAM in a sliced image and a difference there is a
+real difference. Do not carry the exclusion across from the memory-read route.
+
+A malformed snapshot is **refused**, by name, naming the offending value and the
+valid range — it is never truncated into a plausible short image. The `.vsf`
+byte layout lives in exactly one place, `vsf-slice.ts` on the MCP side; this
+script resolves it via `VICE_MCP_DIR`, the in-repo path, or the
+`@henols/vice-mcp` package, and refuses naming every path it tried when no rung
+resolves rather than falling back to a second copy of the layout.
+
 ## Feeding the memory map's provenance sidecar
 
 `c64-program-recon`'s generated memory map (`vice-mcp anno render-memmap`) takes a small provenance
@@ -288,6 +353,7 @@ This one owns the image and its identity. It does not restate what the others ca
 
 | Need | Go to |
 |---|---|
+| A disk image's directory, BAM, sector chains, or directory-fakery detection | `c64-disk-access` |
 | Which address to read next, and what the answer rules out | `c64-program-recon` |
 | Every way a live read gives a wrong answer | `c64-program-recon` — `references/observation-hazards.md`. **Read before driving.** |
 | What a specific address or bit means | `c64-memory-mapping` — `node … lookup '$D018'` |
@@ -326,15 +392,17 @@ split: the workflow fits in one file, which is the right call when it does.
 | Path | Covers |
 |---|---|
 | `scripts/compare.mjs` | Difference classification and the drift floor. Pure logic over captures you already have — `node $C` with no arguments prints the rules. |
-| `templates/capture-record.template.md` | The per-capture record: identity, machine state read in the same paused window, the void checklist, and the per-pairing comparison table. |
-| `scripts/d64-parse.mjs` | `.d64` directory, BAM, and `--json` fakery detection. Fixture-tested against both real images by `scripts/d64-parse.test.mjs`. |
+| `scripts/vsf-slice.mjs` | `slice` / `digest` — the flat 64K image sliced out of a `.vsf` snapshot with no transcription step. The layout lives in `vsf-slice.ts` on the MCP side; this wrapper resolves it and refuses by name when it cannot. Covered by `scripts/vsf-slice.test.mjs`. |
+| `scripts/derive-transients.mjs` | `derive` / `check` — the per-release transient allow-list, derived from N ≥ 3 runs as the pairwise union, under a committed cap of 64 that **voids** rather than warns. Covered by `scripts/derive-transients.test.mjs`. |
+| `transients/README.md` | The committed derivation method, the artifact shape, the cap's reasoning with its four measured reference points, and the rule that no address set is inherited between releases. Its `.gitignore` refuses every image byte form. |
+| `templates/capture-record.template.md` | The per-capture record: identity including the three-row reproducibility key and the `capture route` row, machine state read in the same paused window, the void checklist, and the per-pairing comparison table. |
 | `scripts/dump-artifacts.mjs` | `assemble` / `chip-state` / `manifest` / `write-set` — the guarded byte work, and the source of every `assembleImage:` message in the table below. |
 | `RELEASES.json.example` | A copyable release-registry shape — see `## Release registry shape` above. |
 
-Findings that make RE faster go in `.planning/RE-FINDINGS.md` **at the moment you
-find them**, graded with `Evidence:` and `Confidence:`. Promote by re-logging with
-the new evidence, never by editing a grade in place. File-changing work enters
-through a GSD command (`/gsd-quick`).
+Record findings that make RE faster in your own project notes **at the moment you
+find them**, graded with `Evidence:` and `Confidence:`. Promote a finding by
+re-logging it with the new evidence, never by editing an old grade in place — the
+grade is only worth anything if it says what was actually known when it was written.
 
 ## Troubleshooting
 

package/skills/c64-ram-capture/scripts/compare.mjs

@@ -17,7 +17,7 @@
 //
 // $D000-$DFFF is this module's one departure from what SKILL.md said when it was
 // written: that range is I/O, not RAM, so it can never be stable. See the VOLATILE
-// table below and .planning/RE-FINDINGS.md (2026-08-04) for the evidence.
+// table below for the evidence (observed 2026-08-04).
 
 import { readFileSync } from "node:fs";
 import { createHash } from "node:crypto";
@@ -36,7 +36,7 @@ const VOLATILE = [
   // live hardware and two captures can never agree here. Added 2026-08-04 after
   // every divergence across all six committed gameentry pairings landed either
   // here ($D344, $D625, $D628) or in RAM under KERNAL ROM -- see
-  // .planning/RE-FINDINGS.md, 2026-08-04. Confidence HIGH: structural.
+  // Observed 2026-08-04. Confidence HIGH: structural.
   [0xd000, 0xdfff],
 ];