@henols/c64-re-tools 1.0.0 → 2.0.0-rc.2

package/skills/c64-program-recon/references/control-flow.md

@@ -1,180 +0,0 @@
-# Control flow: entry point → vectors → IRQ source → main loop → structure
-
-Graded 2026-08-01, **MEDIUM**, doc-derived, except where a line says otherwise. This project
-checked the vector-table step against its own captures on 2026-08-04 — see the bottom of this file.
-
-## 1. Entry point — three routes, and post-depack is a different question
-
-| Situation | Where the entry point is |
-|---|---|
-| BASIC stub at `$0801` | A tokenized `SYS <addr>` line. The address is plain PETSCII digits in the stub, so it reads straight out of the load image with no interpretation. |
-| Autostart / non-BASIC | The `.prg` load address (first two bytes), the RESET vector at `$FFFC/$FFFD`, or a cartridge CBM80 signature at `$8000`. |
-| **Post-depack — this project's case** | Wherever the PC sits when the decrunch checkpoint fires. A different question with a different answer. |
-
-For a depacked image there is no BASIC stub to find. Do not spend time looking for one.
-`c64-ram-capture` § Find an entry point gives the live procedure: step in batches until PC and
-SP settle into a repeating range across three consecutive batches.
-
-## 2. Vectors — sweep every block, and `$01` decides which are live
-
-Six pairs is not "all vectors". `node derive.mjs vectors <image.bin>` sweeps all six blocks below.
-It prints the IRQ/BRK/NMI and hardware blocks by default and takes `--all` for the rest.
-
-| Block | Range | Why it matters |
-|---|---|---|
-| BASIC indirects | `$0300-$030B` | IERROR, IMAIN, ICRNCH, IQPLOP, IGONE, IEVAL — a program returning to a modified BASIC prompt hooks these |
-| KERNAL IRQ/BRK/NMI | `$0314-$0319` | CINV `$EA31`, CBINV `$FE66`, NMINV `$FE47`. The per-frame handler, and the pair music players retarget |
-| KERNAL I/O indirects | `$031A-$0333` | OPEN…SAVE. **`$0328` STOP and `$0330`/`$0332` LOAD/SAVE are where a cracker hooks** |
-| Autostart / cartridge | `$8000` cold, `$8002` warm, `$8004` `CBM80` | The standard survive-a-reset trick. Without the signature the KERNAL ignores both words |
-| BASIC ROM entry | `$A000/$A002` | Only meaningful with BASIC banked in — check `$01` LORAM first |
-| Hardware vectors | `$FFFA-$FFFF` | NMI, RESET, IRQ/BRK. Live when the KERNAL is banked out |
-
-**The hardware pairs are only live when the ROMs are banked out via `$01`.** The deciding bit is
-HIRAM, `$01` bit 1 (observed 2026-08-02). HIRAM = 1 ⇒ KERNAL ROM is in and `$0314/$0315` is
-live. HIRAM = 0 ⇒ RAM at `$E000-$FFFF` and `$FFFE/$FFFF` is live.
-
-Why LOAD and STOP earn their own callout on this project: both releases use custom raw-sector
-loaders that bypass the KERNAL, so a diverted `$0330` is a provenance signal, and a diverted
-`$0328` is anti-tamper. Neither was being looked for before 2026-08-04.
-
-The second tell is the handler's own first instruction: the KERNAL's register-save preamble means
-the KERNAL path is in use. A jump straight into game code means it is not.
-
-### A non-default value in a dormant block is not a hook
-
-**A garbage-looking `$0314` is not a bug when HIRAM = 0.** With the KERNAL banked out, nothing
-maintains the RAM vectors and they hold whatever was last there — usually the KERNAL's own
-boot-time values, partly overwritten. `derive.mjs` labels each such block `DORMANT` and reports
-its non-default bytes as *residue*, never as a divert, because reading a hook into residue is the
-fastest way to a confidently-wrong structural claim.
-
-A residue byte that **differs between two releases** is still worth something — but it is a
-provenance question, not a structural one. Take it to `c64-provenance-diff`.
-
-### A target in a ROM window is unresolved until you read it twice
-
-A vector target in `$A000-$BFFF`, `$D000-$DFFF` or `$E000-$FFFF` is *either* ROM *or* the RAM
-underneath, decided by `$01` at the moment the vector is taken. `derive.mjs` marks these
-`bank-ambiguous` and stops there, because a static image cannot settle it.
-
-Live, it is one extra call: read the target with `mcp__plugin_c64-re-tools_vice__vice_memory_read`'s default bank,
-then again with `bank: "ram"`, and compare (`vice_memory_banks` lists what is available). Agreeing
-with stock ROM bytes ⇒ the vector genuinely lands in ROM and the KERNAL path is in use. Differing
-⇒ **the program has its own code hidden under ROM**, which is a large structural finding and is
-otherwise not looked for at all. Record the stock bytes you compared against, so the check is
-reproducible.
-
-This supersedes the weaker "check `$01` and read the handler's preamble" tell, which silently
-reads whichever bank happens to be mapped.
-
-### What the widened sweep found here — 2026-08-04
-
-Run over all six committed captures of one title (two releases, runs 1-3 each):
-
-| Vector | release-a | release-b | Reading |
-|---|---|---|---|
-| `$FFFE/$FFFF` IRQ | `$1103` | `$1103` | Known. Matches the live-established handler chain |
-| `$FFFA/$FFFB` NMI | `$1116` | `$1116` | **New.** The game installs its own NMI handler under KERNAL ROM |
-| `$FFFC/$FFFD` RESET | `$1116` | `$1116` | **New.** RESET funnels to the *same* address as NMI |
-| `$0328/$0329` ISTOP | `$F6FC` | `$F6ED` (stock) | **New, and a divergence.** Residue — the block is dormant |
-| `$8004` `CBM80` | absent | absent | Nothing catches a reset via the cartridge route |
-
-NMI and RESET sharing one entry is the shape of an anti-tamper trap: RESTORE and reset are the two
-ways a user perturbs a running game, and both land in the same place. `$1116` is therefore the
-address to checkpoint when the emulator is next available. Testing the RESTORE half of that
-experiment is not currently possible: **`vice_keyboard_restore` is permanently unavailable.** The
-RESTORE key pulses the NMI line directly and is not part of the keyboard matrix, so `KEYBOARD_FEED`
-(which only injects PETSCII text into the buffer) cannot produce it. Calling the tool returns an
-error naming the reason, rather than pulsing RESTORE. No client-side substitute exists — see
-`docs/stock-hard-losses.md`. The reset half of the experiment remains testable: arm the checkpoint,
-call `vice_machine_reset` soft and hard, and record where the PC actually lands.
-
-**Evidence:** derived mechanically from six three-run-verified captures. Every value stays
-identical across all three runs of its release, so none of it is drift.
-**Confidence:** HIGH for the values and for the cross-release divergence. The *interpretation* of
-`$1116` as anti-tamper is **LOW** — unexercised, and the perturbation experiment above is exactly
-what would settle it.
-
-## 3. IRQ source — two enable masks close the question
-
-- **Raster IRQ** — `$D012` (raster compare), `$D011` bit 7 (raster bit 8), `$D01A` (IRQ enable
-  mask), `$D019` (latch, which the handler must acknowledge). **A handler that writes a new
-  `$D012` on its way out is a split raster chain**, and each such write is one more IRQ position
-  to enumerate.
-- **CIA timer IRQ** — `$DC0D` (CIA#1, drives IRQ) and `$DD0D` (CIA#2, drives NMI), with
-  `$DC04-$DC07` / `$DD04-$DD07` for the periods.
-
-A game that never touches `$DC0D` is on a raster IRQ. One that programs `$DC04-$DC07` and enables
-timer A has its own timebase. Read the two enable registers before reading any handler code.
-
-## 4. Main loop — decide the shape before hunting
-
-- **Real main loop** — an unconditional backward branch or `JMP` to a nearby earlier address that
-  never returns, usually preceded by a frame-sync wait: polling `$D012` for a fixed raster line, or
-  spinning on a flag the IRQ handler sets.
-- **IRQ-does-everything** — the main loop is a two-instruction spin and all logic hangs off the
-  raster IRQ. Common enough that assuming the first shape wastes the search.
-
-**The honest test is live, not static.** The address that repeats exactly once per frame in an
-execution trace is the main loop, whatever the listing suggests.
-
-## 5. Four structural features a linear disassembler gets wrong
-
-- **Jump tables and dispatch** — `JMP ($xxxx)` and `JSR` into an indexed table. This is where game
-  state machines live, and exactly what a linear decoder mis-decodes.
-- **Self-modifying code** — writes into `$0800-$CFFF` from code that also executes there. Common
-  for animation frame pointers.
-- **Zero page** — the game's hot variables. The highest-frequency ZP addresses in a trace are the
-  state worth naming first.
-- **Code/data separation** — the project's standing rule (`.claude/CLAUDE.md` § Stack Patterns): a
-  range never hit as an instruction stream across full gameplay coverage is data, regardless of
-  what the tracer guessed. The provenance diff between the two cracked releases is the second check
-  on the same question.
-
-## Finding the state machine
-
-Most games have one even when it is not explicit. Two shapes:
-
-```asm
-    LDA GameState        ; indexed dispatch — the common shape, and the one
-    ASL                  ; a linear disassembler turns into nonsense
-    TAX
-    LDA StateTable,X
-    STA JumpVector+1
-    LDA StateTable+1,X
-    STA JumpVector+2
-JumpVector:
-    JMP $FFFF            ; operand is patched at runtime
-```
-
-```asm
-    LDA GameState        ; compare chain — easier to read, easier to find
-    CMP #STATE_TITLE
-    BEQ TitleState
-```
-
-Finding the state variable gives a high-level map of the whole program. A practical route: pause
-at a title screen and again in gameplay, diff the two captures, and look for a single byte that
-differs in zero page or low RAM. `vice_memory_compare` narrows this. `c64-ram-capture` § Compare
-two captures gives the volatility rules that stop you chasing drift.
-
-`vice_memory_compare` serves only `mode: 'ranges'`, which captures the two states at different
-points in time and compares two live ranges. It refuses `mode: 'snapshot'` with an explanatory
-message. There is no memory-only snapshot producer at all.
-
-## Verified against this project — 2026-08-04
-
-Running `derive.mjs vectors` cold on both releases' `*-gameentry-run1.bin` returns `$01` = `$40`
-(LORAM 0, HIRAM 0, CHAREN 0 — KERNAL and BASIC banked out), so the live pair is `$FFFE/$FFFF`,
-holding **`$1103`**, while `$0314/$0315` holds `$0101` — nothing meaningful, exactly as the
-dormant-block rule predicts.
-
-`$1103` is the same IRQ-handler entry that phase-01 live work independently established, with the
-raster-split chain `$1103 → $1574 → $152C` (observed 2026-08-02, on a checkpoint trap). The
-method reproduces a known-good result from a static image with no emulator running. The widened
-sweep's own results, including two facts this table never surfaced, are in §2 above.
-
-**Evidence:** derived mechanically from three-run-verified captures, cross-checked against a live
-finding recorded independently.
-**Confidence:** HIGH for the vector-table step, the HIRAM rule, and the dormant-block rule. The
-remaining steps in this file stay MEDIUM until exercised the same way.

package/skills/c64-program-recon/references/graphics.md

@@ -1,79 +0,0 @@
-# VIC-II: locating every displayed byte
-
-Graded 2026-08-01, **MEDIUM**, doc-derived.
-
-**Graphics data is computed, not searched.** Every pointer the VIC follows derives from two
-registers plus a bank. Read the bank, read `$D018`, read the mode bits, read `$D015` and the
-sprite pointer block, and you have located every byte of graphics on screen. Searching memory for
-something the hardware will tell you the address of is the single largest time sink in graphics RE.
-
-`node derive.mjs vic` and `node derive.mjs sprites` do the arithmetic. For what any individual bit
-*means*, use `c64-memory-mapping` — it carries the full `$D018` and `$DD00` value tables, and this
-file deliberately does not restate them.
-
-## The order, and why it is this order
-
-1. **`$DD00` bits 0-1 — the VIC bank. Read this first, every time.** The bits are **inverted**
-   (`%11` → bank 0 at `$0000`, `%00` → bank 3 at `$C000`). Every other pointer is relative to this
-   base, so getting it wrong corrupts the whole chain **silently, with no error to signal it**.
-   This is the most common source of a wrong answer in C64 graphics RE.
-2. **`$D018` — two pointers in one byte.** Bits 4-7 = VM (screen RAM = bank + VM × `$0400`).
-   Bits 1-3 = CB (charset = bank + CB × `$0800`). In bitmap mode only bit 3 matters: which 8K half
-   of the bank the bitmap occupies, and the video matrix then holds colour pairs rather than
-   character codes.
-3. **The mode bits** — `$D011` bit 6 (ECM), `$D011` bit 5 (BMM), `$D016` bit 4 (MCM). These decide
-   what the bytes *mean*. Decoding a multicolor sprite as hires produces garbage twice as wide as
-   it should be. ECM combined with BMM or MCM is invalid and blanks the screen — if you compute
-   that, you probably caught the registers mid-update inside a raster split, so re-read.
-4. **`$D015` — the sprite enable mask. Start here, not at the sprite data.** A disabled sprite's
-   other registers are stale and decoding them yields noise.
-5. **Sprite pointers at video matrix + `$03F8`**, 8 bytes. Each pointer × 64 = the sprite's data
-   address *within the current bank*. 63 bytes used of the 64 allocated.
-
-## The hazard that costs an hour
-
-**The character ROM shadow.** The VIC sees character ROM at `$1000-$1FFF` (bank 0) and
-`$9000-$9FFF` (bank 2) **regardless of the `$01` banking the CPU sees**. If CB resolves into
-either window, the game is using ROM characters and there is no charset in RAM to extract.
-`derive.mjs vic` flags this explicitly. Check it before dumping anything.
-
-## Colour is not banked
-
-Colour RAM is fixed at `$D800-$DBFF` and does **not** move with the VIC bank. Only the low nybble
-of each byte exists. `$D020` is the border, `$D021-$D024` backgrounds 0-3 (2 and 3 used only in
-ECM). Looking for colour data at a bank-relative address finds something else entirely.
-
-## Two watch targets that find the two highest-value routines
-
-`vice_watch_add` finds **writers**, and that is its real leverage in RE — it is under-used relative
-to reading memory.
-
-| Watch | Finds |
-|---|---|
-| `$D018` | The screen-setup routine. In a room- or level-based game this is usually the room loader — one of the highest-value routines to locate early. |
-| video matrix + `$03F8` | The animation driver. Rewriting sprite pointers frame to frame is exactly what it does. |
-
-## Reading collision registers changes the game
-
-`$D01E` (sprite-sprite) and `$D01F` (sprite-background) **clear when read**. Reading them while the
-game runs steals the collision the game was about to act on — the worst class of observation bug,
-because it discredits the capture without announcing itself. Prefer `vice_vicii_get_state`.
-
-Whether the VICE monitor's own read is side-effect-free is **unverified** — treat it as
-check-don't-assume, not as a settled fact.
-
-Many games do software collision anyway: look for coordinate subtraction, comparisons against
-width and height, tile lookups, mask tables and bounding-box arithmetic before concluding the
-hardware registers are what the game uses.
-
-## Sprite decoding
-
-`vice_sprite_get` / `vice_sprite_inspect` do the pointer arithmetic and the multicolor bit-pair
-unpacking. Check what they return once against a hand-resolved pointer — `derive.mjs sprites`
-gives you that hand resolution — then trust them.
-
-On stock, `vice_vicii_get_state`'s `$D018` pointers come back **bank-relative**.
-`vice_sprite_get` resolves the absolute `screenBase` and per-sprite `dataAddress` for you.
-`vice_sprite_inspect`'s ASCII grid is the sprite's native 24x21 (hi-res) or 12x21 (multicolour)
-**data block** — it is **not** scaled by the `$D017`/`$D01D` expansion bits, so a sprite shown
-double-size on screen still renders at its native resolution in the grid.

package/skills/c64-program-recon/references/observation-hazards.md

@@ -1,143 +0,0 @@
-# Hazards: how observing a running C64 gives you the wrong answer
-
-The entries here are graded higher than the method files, because most were established live on
-this project at real cost. A wrong answer from a register table is cheap. A wrong answer from a
-machine that changed *because you looked at it* discredits a whole session without announcing
-itself.
-
-Log a new hazard in your own project notes at the moment you hit one — the cost of rediscovering
-one is a whole discredited session.
-
-## 1. Agent think-time runs the emulator at full speed
-
-**Evidence: live, 01-04 attempt 5. Confidence: HIGH (measured, then reproduced with a control).**
-
-Between one screenshot and the next — a handful of memory/register reads, **zero input sent** —
-a game ran through an interstitial to `GAME OVER`. `vice_cycles_stopwatch` read **258,504,308**
-cycles since the previous action: roughly **262 seconds of emulated PAL time**, all of it real
-unattended execution while the agent composed tool calls.
-
-This invalidated a previously recorded gameplay-hazard conclusion. A "counter that depletes per
-input event" was really a counter depleting during the agent's own reasoning latency, and the
-earlier finding had no way to rule that out because it never paused either.
-
-**The discipline:** call `vice_execution_pause` immediately after every observation that is not
-immediately followed by a deliberate scripted input. Resume only for the bounded duration of that
-input. **Never leave the machine running across a reasoning step.**
-
-Two confirmations from the same session: a pause takes effect only once actually processed (the
-counter climbed another ~20M cycles before settling), but once landed it holds solidly — two
-consecutive stopwatch reads returned an identical value. And with the discipline held from the
-first frame, a room previously judged impassable across six attempts was crossed on the next try.
-
-## 2. An armed stopping checkpoint can look exactly like a dead emulator
-
-**Evidence: cross-read of three recorded incidents, 3/3 correlation. Confidence: MEDIUM — the
-mechanism is consistent with every symptom and testable in minutes, but has not been reproduced.**
-
-The common factor across three "silent stall" incidents was not an address. It was: **a stopping
-exec checkpoint was armed, and execution was resumed.**
-
-The signature is complete and self-consistent — the cycle bracket reads exactly `0`, `vice_ping`
-answers `execution: "running"` because VICE's flag flips before the trap fires, and
-`vice_registers_get` returns a byte-identical PC every time **because the machine genuinely never
-moved.** The strongest single tell: in one incident `vice_checkpoint_list` reported the checkpoint
-at `hit_count: 0` after multiple resume/poll cycles, on an IRQ-driven screen where its address
-*must* execute every frame.
-
-**`mcp__plugin_c64-re-tools_vice__vice_diagnose` now performs this check for you** (2026-08-04): it enumerates armed
-checkpoints, reads the PC, resolves the live IRQ handler through `$01`, and returns a
-`checkpoint_trap` verdict — with **no resume and no stopwatch call**, which matters because
-`vice_execution_run` is this project's leading crash suspect. Call it before anything else. The
-triage decision tree around it is `vice-wedge-triage`.
-
-**Know the two shapes it matches, because a trap outside them reads as a wedge.** It fires when an
-enabled stopping exec checkpoint sits *exactly* at the current PC, or at the resolved handler
-entry with `hit_count` exactly `0`. This hazard's own evidence describes the PC as pinned "at or
-just past" the checkpoint — *just past* is not *exactly at*. A checkpoint armed mid-handler rather
-than at its entry, with a non-zero hit count, matches neither shape, falls through to the cycle
-bracket, and comes back `wedged`. **The response to `wedged` is recycle, and recycling a healthy
-instance is the exact loss both the tool and this hazard exist to prevent.** So when a `wedged`
-verdict arrives with any checkpoint still armed, do the two reads by hand before recycling:
-`vice_checkpoint_list`, then resolve the live handler (`$0314/$0315`, or `$FFFE/$FFFF` when `$01`
-has the ROMs banked out). Observed 2026-08-04, and still open.
-
-**Counter-evidence, and why this is MEDIUM:** in one incident, deleting the checkpoint did *not*
-unfreeze the machine, and neither did a soft reset, a hard reset, nor a single step. A checkpoint
-trap may be the *onset* without being the whole story. Do not assume delete-and-resume recovers it.
-`vice_diagnose`'s own `checkpoint_trap` report states this too, and cites the same incident.
-
-**This is not a reason to stop arming checkpoints on IRQ handlers** — that is core technique. It
-is a reason to enumerate what you armed *first* whenever the machine looks frozen, before
-concluding the emulator died.
-
-## 3. Registers that clear when you read them
-
-`$D01E`, `$D01F` (VIC collisions) and `$DC0D`, `$DD0D` (CIA interrupt flags) clear on read.
-Reading one while the game runs steals the event the game was about to service.
-
-Prefer the whole-chip reads — `vice_vicii_get_state`, `vice_cia_get_state`, `vice_sid_get_state`
-— over raw register reads. Whether the VICE monitor's own read path is side-effect-free is
-**unverified**: treat it as check-don't-assume rather than taking it on faith.
-
-`vice_vicii_get_state`/`vice_cia_get_state` reads are `sidefx: false` with
-no argument able to override it — **VERIFIED**, asserted on the wire body by a regression test.
-Whether the emulator's own `MEM_GET` read path actually honours that flag for
-`$D01E`/`$D01F`/`$DC0D`/`$DD0D` — i.e. whether it truly cannot clear them — is **ASSUMED**, with
-no probe recorded in this repo. Treat it as unverified, not as a proven guarantee.
-`vice_sid_get_state` read-back is **permanently unavailable**: SID `$D400-$D418` is write-only
-in hardware and the binary monitor has no SID command, so there is no route to recover it.
-Writes to those addresses still work fine. See `docs/stock-hard-losses.md`. Also: an internal
-field the register map cannot expose is marked `{ available: false, reason }` in the answer, never
-a bare `0` — do not record a `0` from one of these fields as a measurement. Check `available`
-first. A chip-state or sprite answer also **names the memory view it read** (`bank`, or
-`registerBank`/`dataBank`), read through the emulator's own `io`/`ram` banks, so it stays valid
-even while the program has I/O banked out ($01 driving the RAM/ROM/I-O switch). An answer with
-**no** bank field — an older transcript — is suspect whenever `$01` may not
-have been `$37`: those bytes may be the RAM underneath the I/O area, not registers.
-
-## 4. The keyboard buffer is not how games read keys
-
-**Evidence: live. Confidence: HIGH. Cost: an afternoon.**
-
-Games and cracks poll the `$DC00`/`$DC01` matrix directly, bypassing the KERNAL buffer, so
-`vice_keyboard_type` is invisible to them. Use `vice_keyboard_matrix`, and hold a key across a
-gate by releasing it at the trigger checkpoint, never earlier.
-
-**`vice_keyboard_matrix` is permanently unavailable.** The binary monitor's `KEYBOARD_FEED` (0x72)
-only injects PETSCII text into the KERNAL keyboard buffer. The emulator recomputes CIA port B from
-its own keyboard array on every read, so there is no wire command that can drive the raw matrix —
-this is unrecoverable, not merely unbuilt. 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 instead. Either way, buffer injection is
-invisible to a program polling `$DC00`/`$DC01` itself, so a matrix-polling gate must be driven by
-the joystick or not at all.
-
-## 5. Most state reads pause the emulator and do not resume it
-
-Read all state first, poll with `vice_ping` (the non-pausing poll), and resume **exactly once** at
-the end. `vice_ping`'s `execution` field is **not** a liveness signal — see hazard 2 for why it
-reports `running` on a machine that is not moving. The only trustworthy liveness test is a cycle
-bracket.
-
-## 6. The machine can be replaced under you
-
-A crash-and-respawn mid-session means the run is void — `c64-ram-capture` § Void a run gives the
-procedure. A successful retry after an auto-restart may be talking to a blank machine.
-
-**You do not poll for this, and no exposed tool reads the epoch.** The proxy compares it before and
-*after* every forwarded call and raises a loud error naming both values, then re-baselines so the
-session stays usable. The two recorded incidents surfaced exactly that way and self-healed on the
-next call. Where an epoch value is needed for a record, it comes from that error text or from
-`vice_diagnose`'s `restarted` report — there is no `vice_epoch_get`.
-
-What is still yours to do: **treat every post-drift read as a fresh machine, never as a resume
-point.** Reboot from `vice_disk_attach`. Two crashes in ~20 minutes of continuous live work is a
-real measured rate, so plan a live session to tolerate re-deriving a boot sequence more than once.
-
-## 7. Full-64K byte-identity is impossible in principle
-
-Never-written RAM drifts continuously, so two captures of the same checkpoint will not match
-across all 64K. The recovery procedure is deterministic **for the program image**, not for 64K.
-`c64-ram-capture` § Compare two captures carries the volatility regions and the drift
-discriminator. Use them rather than treating any difference as a divergence.

package/skills/c64-program-recon/references/reconstruction.md

@@ -1,133 +0,0 @@
-# Turning findings into ACME source
-
-Do not wait until everything is understood. Stand up a buildable tree early, include the
-unidentified bulk as binary, and replace regions with real source as they are confirmed. The tree
-stays assemblable at every commit, so a regression has a small blast radius.
-
-`acme-build` covers assembling. This file covers the shape of the source and what makes a
-reconstruction right.
-
-## Start with binary inclusion
-
-```asm
-* = $4000
-!binary "unknown_4000_5fff.bin"
-```
-
-Then replace piece by piece, keeping the addresses fixed:
-
-```asm
-* = $4200
-
-UpdatePlayer:
-    ; reconstructed code
-```
-
-A layout that keeps this workable:
-
-```
-src/
-  main.a          zeropage.a      irq.a
-  input.a         player.a        enemies.a
-  collision.a     graphics.a      music.a
-  data/
-    sprites.a     levels.a        text.a
-```
-
-## Behavioural equivalence is this project's definition of correctness
-
-**Correctness here means scripted replay plus comparison at checkpoints — nothing else**
-(`.claude/CLAUDE.md` § Constraints). A reconstruction is right when driving it through the
-checkpoint set produces the same observable behaviour as the original. **Anything not observable
-at a checkpoint is not verified** — the constraint's own conclusion, and the reason checkpoint
-design is part of the reconstruction work rather than something to bolt on afterwards.
-
-**That bar is what buys you the freedom to rename routines, reorganise files, replace constants
-with symbols and add macros**. **But** reorganising shifts addresses, which breaks self-modifying code and
-timing-sensitive raster routines. Replay through the checkpoint set after EACH reorganisation, not
-at the end of several: one shifted address per failing replay is a short diagnosis, ten is a
-bisect.
-
-A full 64K RAM capture is not a comparison surface: never-written RAM drifts continuously, so
-full-64K identity is impossible in principle (`observation-hazards.md` § 7).
-
-## Self-modifying code needs explicit labels
-
-A static disassembler sees `LDA $FFFF,X` and cannot know the operand is written at runtime:
-
-```asm
-    LDA SourceAddress
-    STA CopyLoop+1
-    LDA SourceAddress+1
-    STA CopyLoop+2
-CopyLoop:
-    LDA $FFFF,X
-    STA $0400,X
-```
-
-Name the patched location so the intent survives:
-
-```asm
-CopySource = CopyLoop + 1
-```
-
-Look for writes to the byte after an opcode, the two bytes after a `JMP`/`JSR`, branch operands
-and immediate constants — `STA Routine+1`, `STX Routine+2`, `INC Routine+1`.
-
-## Label vocabulary: name from evidence, promote on confirmation
-
-Provisional names that carry their own uncertainty beat confident names that turn out wrong:
-
-| Prefix | Means |
-|---|---|
-| `ZP_` | unknown zero-page variable |
-| `State_` | state variable |
-| `Flag_` | boolean or bit field |
-| `Counter_` | counter |
-| `Ptr_` | pointer |
-| `Table_` | lookup table |
-| `IRQ_` | interrupt routine |
-| `Maybe_` | plausible but unconfirmed |
-| `Unknown_` | no reliable interpretation yet |
-
-`Routine_43A2` → `Maybe_UpdatePlayer` → `UpdatePlayerPosition`, promoted only when behaviour is
-confirmed. Avoid `AmazingCollisionRoutine`-style names entirely. They encode a guess as a fact.
-
-Record the confidence next to the thing, in the same grammar the project uses everywhere else:
-
-```asm
-; Confirmed: decremented once per frame while the player is invulnerable.
-; Evidence: live, watch on $D015 during damage. Confidence: HIGH.
-PlayerInvulnerabilityTimer:
-    !byte 0
-```
-
-## Data tables a linear disassembler destroys
-
-The split low/high address table is the classic:
-
-```asm
-AddressLo:  !byte <Room0, <Room1, <Room2
-AddressHi:  !byte >Room0, >Room1, >Room2
-```
-
-Without recognising the pair, a disassembler shows meaningless instructions. Other data tells:
-referenced through indexed loads, repeated byte patterns, valid PETSCII or screen codes,
-sprite-sized 64-byte blocks, values matching VIC-II coordinates.
-
-Code tells: reachable through `JSR`/`JMP`/branches/vectors, **executes during tracing**, plausible
-control flow. The project's standing rule settles ties — a range never hit as an instruction
-stream across full gameplay coverage is data, whatever the tracer guessed.
-
-## Labels round-trip through VICE
-
-ACME's `--vicelabels` output is the `al C:xxxx .Name` format `vice_symbols_load` /
-`vice_symbols_lookup` consume, so labels flow source → build → debugger without translation.
-`acme-build` emits the `.vs` file on every build. Load it after each one and your checkpoints carry
-real names.
-
-**The other direction — exporting the annotation store into that same format — is withdrawn as of
-2026-08-29, and no phase currently owns its return** (an earlier forecast naming a numbered phase
-for it is superseded: that phase covered the ACME export oracle only). So a name discovered live
-goes into the store with `anno_set_label_name` first (the store is the merge point) and reaches the
-emulator only through a `.lbl` you produce yourself.

package/skills/c64-program-recon/references/sound-and-input.md

@@ -1,74 +0,0 @@
-# SID and CIA: music, effects, the RNG, input, timing
-
-Graded 2026-08-01, **MEDIUM**, doc-derived, except where marked. Per-register bit detail lives in
-`c64-memory-mapping`. This file carries the idioms and the order.
-
-## SID — separating the player from the game logic
-
-Voice 1 at `$D400`, voice 2 at `$D407`, voice 3 at `$D40E`, seven bytes each: frequency lo/hi,
-pulse width lo/hi, control (gate bit 0, then sync/ring/test and the waveform bits), attack/decay,
-sustain/release. Then `$D415`-`$D418` for filter and volume. Write-only but for the last four:
-`$D419`/`$D41A` paddles, `$D41B` voice 3 oscillator, `$D41C` voice 3 envelope.
-
-**Watch `$D404` to land directly on the play routine.** Voice 1's control register gates on every
-note, so a write watch there hits the player without reading the IRQ handler line by line.
-Separating the two entry points follows immediately:
-
-> `init` is called **once** from the main code. `play` is called **once per frame** from the IRQ.
-
-Pulling the music driver out early removes a large amount of apparent complexity from everything
-else — it is often the single biggest block of code that has nothing to do with gameplay.
-
-### Two idioms worth recognising on sight
-
-- **`$D41B` read is the random number generator, not audio.** Reading voice 3's oscillator is *the*
-  C64 RNG idiom. Code reading `$D41B` is almost never doing sound — it is enemy AI, spawn
-  placement, or a title-screen effect. Filing it as sound code sends the AI hunt in the wrong
-  direction. Corollary: `$D418` bit 7 (voice 3 disconnect) is often set **precisely because** voice
-  3 is the RNG rather than a voice.
-- **`$D418` hammered alone at high frequency is 4-bit sample playback**, not music. It is a
-  separate subsystem from the player and usually runs off a **fast CIA timer** rather than the
-  frame IRQ — so finding it also explains a CIA timer you could not otherwise account for.
-
-## CIA — two chips, identical layouts, different jobs
-
-Confusing them is a frequent early error.
-
-| | CIA#1 `$DC00` — keyboard, joysticks, **IRQ** | CIA#2 `$DD00` — VIC bank, serial, user port, **NMI** |
-|---|---|---|
-| Port A | `$DC00` keyboard **column** select. Joystick port 2 | `$DD00` VIC bank (bits 0-1, inverted). Serial ATN/CLK/DATA |
-| Port B | `$DC01` keyboard **row** read. Joystick port 1 | `$DD01` user port / RS-232 |
-| Timers | `$DC04-$DC07`, control at `$DC0E`/`$DC0F` | `$DD04-$DD07`, `$DD0E`/`$DD0F` — these drive **NMI** |
-| Interrupt | `$DC0D` | `$DD0D`, same bit layout |
-
-**The timebase question closes in one read.** A game that never touches `$DC0D` is on a raster IRQ.
-One that programs `$DC04-$DC07` and enables timer A runs its own timebase.
-
-## Three CIA hazards
-
-- **`$DD00` is dual-purpose.** The same register carries the VIC bank *and* the serial bus lines,
-  so a write during disk access also moves the VIC's view of memory unless the code masks
-  carefully. **Check the mask** before concluding a `$DD00` write is a bank switch — loader code
-  writing `$DD00` is usually talking to the drive.
-- **`$DC0D`/`$DD0D` clear the interrupt flags on read**, the same shape as `$D01E`/`$D01F`. Reading
-  one steals an interrupt the game was about to service. Prefer `vice_cia_get_state`. The VICE
-  monitor's exact behaviour here is **unverified** — check, don't assume. On stock,
-  `vice_cia_get_state` reports the **read** side of `$xx0D` as `interruptStatus` and marks the
-  write-side enable mask `unavailable` — the two share one address with different meanings, so a
-  reader looking for "which interrupts are enabled" is not silently handed the flags that have
-  fired.
-- **Direct `$DC00`/`$DC01` polling is the norm, and it defeats `vice_keyboard_type`.**
-  **Evidence: live, established on this project during recovery work. Confidence: HIGH. Cost: an
-  afternoon.** Games and cracks bypass the KERNAL keyboard buffer and read the matrix directly.
-  Assume it until shown otherwise. **`vice_keyboard_matrix` is permanently unavailable** — the
-  binary monitor's `KEYBOARD_FEED` only injects PETSCII buffer text 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.
-
-## Finding input handling from the observable side
-
-Watch reads of `$DC00`/`$DC01` to find the input routine, then trace forward to what it stores.
-The joystick bits are active-low: bit 4 is fire, bits 0-3 up/down/left/right. A routine that reads
-`$DC01`, masks one bit and branches is the input decoder. The variable it writes is the one to
-name first.