# Lunar Pool (U)

ROM: `Lunar Pool (U).nes` (24,592 bytes, iNES). Status: **PASSES 1-3 COMPLETE; PROMOTED TO THE TOP LEVEL 2026-10-18** — 5,300 instructions / **11,077 code bytes (67.6%)** / 5,301 data bytes / the 6 vector bytes as `.word`, byte accounting exact (11,077 + 5,301 + 6 = 16,384), and **BYTE-IDENTICAL for the whole ROM** (header + PRG + CHR) via `cmp reconstructed.nes rom.nes`. Pass 2 named all **705** labels — `Label_<addr>` is gone — and Pass 3 named 33 data structures and finished the zero-page audit (38 semantic aliases, 66 deliberately neutral `ZpXX`, ten former phantom aliases deleted). The ~354 bytes the CDL could not settle stay `.byte` on purpose; they are itemised under *Known remaining gaps*.


## Power-on flow analysis

Derived from the disassembly by `_tools/derive_poweron.py`; the call graph is walked from the reset entry.

**RESET** is at `$E80C` (`Reset`).  The CPU comes here out of reset with the PPU and APU in their power-on state and the zero page and RAM uninitialised.

The reset path calls:

| Address | Routine |
|---------|---------|
| `$CB1D` | `SetPpuCtrlAndMask` |
| `$E817` | `Reset_WaitVblank` (falls through) |
| `$CA3C` | `WritePpuCtrl` |
| `$E81E` | `Reset_WaitVblank2` (falls through) |
| `$CC7B` | `ResetVramQueue` |
| `$CA60` | `SetNtBase2000` |
| `$C3F5` | `ResetGameState` |
| `$E830` | `Reset_ClearShadowTables` (falls through) |
| `$CC7D` | `ResetVramQueue_Loop` (falls through) |
| `$C3BC` | `ClearGameState` |
| `$E848` | `Reset_LoadSpritePalettes` (falls through) |

**NMI** is at `$FF65` (`NmiHandler`).  It is the per-frame handler; what it calls:

| Address | Routine |
|---------|---------|
| `$CB25` | `TriggerOamDma` |
| `$CC8F` | `DrainVramQueue` |
| `$CA52` | `WritePpuCtrlAndResetScroll` |
| `$C003` | `RunObjectFrame` |

**IRQ** is at `$FF64` (`IrqHandler`) - a different address from RESET.

## ROM Facts

| Property | Value |
|----------|-------|
| Mapper | 0 (NROM) — from the iNES header |
| PRG | 16 KB (header claims map at CPU $C000–$FFFF) |
| CHR | 8 KB |
| Mirroring | Vertical |
| Battery-backed flag | clear |
| ROM SHA-256 | `6da37fd34e8f4eb3df34e9f446726a193db77d0e0bba32aa328ef225993fc8a1` |
| PRG SHA-256 | `43a2f54cd48b38fc1e4a33051e019528e9789a774ace773fa7549c33dc9492c9` |

## Interrupt Vectors (taken from PRG $3FFA–$3FFF)

| Vector | Target | Note |
|--------|--------|------|
| NMI | `$FF65` | per-frame heartbeat |
| RESET | `$E80C` | non-$C000 entry — the tracer has to seed it explicitly (`--extra-seed 0xE80C`) |
| IRQ | `$FF64` | a bare `rti` sitting immediately before the NMI handler, so IRQs are effectively ignored |

## Pass Status

| Pass | Status | Description |
|------|--------|-------------|
| Pass 0 | Superseded | `prg.s` was a 12-line `.incbin` of the whole PRG — no disassembly at all |
| Pass 1 | **Complete** | Static code/data split, then reclassified against a Mesen Code Data Logger capture (see below). As Pass 1 delivered it: 5,285 instructions / **11,041 bytes emitted as instructions (67.4%)** / 5,343 bytes emitted as data (`.byte`, plus the six vector bytes as `.word`); 11,041 + 5,343 = 16,384 exactly. Labels: 640 `Label_<addr>` plus `Reset`/`NmiHandler`/`IrqHandler`. |
| Pass 2 | **Complete** | NES hardware constants in `symbols.inc`; zero-page aliases in `locals.inc`; and **all 705 labels named — `Label_<addr>` is gone from the file**. 17 dispatch targets that carried no label at all (`UpdateObjects_Render_Sound` `$C05C`, `SetupRound` `$EB60`, `PrintStageNumber` `$E21A`, `SetPpuAddr` `$F989`, …) were given labels and routine headers. Naming rule used: PascalCase for `jsr`/`jmp` targets and logical block heads, `<Block>_<Role>` (`_Loop`, `_Next`, `_Alt`, `_Done`, `_Skip`, `_Return`, `_Store`, …) for targets *inside* a routine; `jsr`/`jmp` operands stay raw numeric — this file's convention, as in `Joypad Test Cartridge (U)` — while branch operands are symbolic. (Earlier revisions claimed 218 entries renamed, 195 of them `SubC<addr>`; no `SubC` label ever existed — `git log -S SubC` finds no commit that added one.) |
| Pass 3 | **Complete** | Zero-page audit: **38 semantic aliases** (object core, VRAM write queue, VRAM read-back, PPU helpers) and **66 neutral `ZpXX`** whose roles are documented as deliberately unproven in `locals.inc`. Data structures: **41 tables/blocks named** across the 44 data blocks of the PRG (see *Pass 3 data-table inventory* below); the blocks that are not named are recorded there as unreferenced data or as unreached code, with their ROM provenance. Vectors are `.word NmiHandler, Reset, IrqHandler`. What is still unnamed is the residue listed under *Known remaining gaps* — it stays `.byte` on purpose. |

## Pass 3 data-table inventory

The tracer leaves **44** data blocks in `prg.s`; each one is listed below.
Every row says what the bytes *are* and which instruction of this dump reads
them, or records that nothing reads them.

The game is FCI's *Lunar Pool* (1985): a two-player beach-volleyball match.
The player serves, the computer returns, and a rally is scored on the
number of touches before the ball lands.

### The named tables and blocks

| Address | Size | Name | Structure | Read by |
|---------|------|------|-----------|---------|
| `$C000-$C002` | 3 | `ResetStub` | the three bytes `4C 0C E8` = `jmp $E80C`; the reset vector points at `$E80C` directly, so this stub is never executed | not referenced by any instruction |
| `$C0C0-$C0E5` | 38 | `ObjectOpcodeHandlerTable` | 19 x 16-bit LE handler addresses, one per object-script opcode (`$80`-`$92`); every target is a `jmp` trampoline into the real handler. The code bases the table one entry early, so entry 0 is dead | `lda $C0C0,y` at `$C0B7` and `lda $C0C1,y` at `$C0B3` (the low and high byte of the selected handler address) |
| `$C3B4-$C3BB` | 8 | `SoundChannelMask` / `SoundChannelDisableMask` (`$C3B8`) | eight bytes: `01 02 04 08` are the APU channel-enable bit masks and `FE FD FB F7` their complements | `lda $C3B4,y` at `$C395` and `lda $C3B8,y` at `$C336` |
| `$C47A-$CA20` | 1447 | `ObjectStatePointerTable` (`$C47A`), `SpawnObjectTable` (`$C522`), `StateTimerTable` (`$C543`), `AnimationPointerTable` (`$C552`), `SpriteAnimationTable` (`$C559`) | the PRG's biggest table, a run of 16-bit little-endian words. `$C47A-$C521` = 84 per-object state pointers, indexed by `(obj_ptr_lo + $0519,x) * 2`; `$C522-$C542` = 16 spawn-record pointers for object ids 1-15 (id 0 is dead); `$C543-$C552` = 16 per-state timer values `1,2,3,4,6,8,12,16,24,32,48,64,96,128,192,0`, indexed by script opcode - `$DF`; `$C552-$C558` = frame-sequence pointers; `$C559-$C56E` = per-sprite animation descriptors used by the draw path | `lda $C522,x` at `$C411`, `lda $C523,x` at `$C40D`, `lda $C543,y` at `$C1D2`, `lda $C552,y` at `$C2D2`, `lda $C553,y` at `$C2D7`, `lda $C559,y` at `$C24C` |
| `$CF40-$CF4A` | 11 | `VsCommandList` | an inline `RunCommandList` script (a byte per command, `$FF` = end) issued when the VS-COMP scene is loaded | not referenced by any instruction (the list is reached through the command-list interpreter) |
| `$D05A-$D05A` | 1 | `DrawCellRunTileTable` | the fourth of the four corner tiles `$3C $69 $C3 $96` that `DrawCellRun` selects by the row bits; the other three bytes lie in the code region at `$D057-$D059` | not referenced by any instruction (the tiles are selected by the row bits) |
| `$D4FA-$D535` | 60 | `LayoutScriptTable` | 30 x 16-bit LE pointers, one per stage, to that stage's layout script | not referenced by any instruction (reached indirectly through the stage index) |
| `$D559-$E01D` | 2757 | `LayoutData` | the per-stage layout records: 2,757 bytes of tile and object data that the layout scripts read | not referenced by any instruction (reached indirectly through `LayoutScriptTable`) |
| `$E862-$E87F` | 30 | `BootSignatureText` (`$E862`), `TitleAttributeRow` (`$E870`) | `$E862-$E86E` = the ASCII string "JEMINI DAZO!!"; `$E86F` = its NUL, which is also the first byte of the 16-byte warm-boot signature the game compares against the RAM copy at `$0440-$044F`; `$E870-$E87E` = the remaining 15 bytes of that signature, which are the title screen's colour codes | `lda $E86F,x` at `$E8FF` (the 16 signature bytes) |
| `$E9A3-$E9C9` | 39 | `TitleColorCycleTable` (`$E9A3`), `StartGameAttributeRow` (`$E9B9`) | `$E9A3-$E9B8` = 22 colour codes cycled into the `$0085-$0087` palette shadow each frame; `$E9B9-$E9C8` = 16 attribute bytes copied to the `$0140-$014F` shadow when a game starts | `lda $E9A3,x` at `$E984`, `$E98F`, `$E99A` and `lda $E9B9,x` at `$E9CC` |
| `$E9FB-$EA0A` | 16 | `TitleCommandList` | an inline `RunCommandList` script for the title screen (a byte per command, `$FF` = end) | not referenced by any instruction (reached through the command-list interpreter) |
| `$EB50-$EB5F` | 16 | `BallJumpHeightTable` | 16 x 8-bit ball heights: the ball rises `09 0A 0B 1B 2B 3B`, pauses for two frames at `30 30`, then falls back `3B 2B 1B 0B 0A 09`; `$FF $FF` ends the table | `lda $EB50,x` at `$EABC` |
| `$EBF1-$EBF7` | 7 | `StageLabelText` | the ASCII string "stage" followed by `;` and a NUL | not referenced by any instruction (the string is reached through the inline-string printer) |
| `$EC05-$EC0B` | 7 | `StartLabelText` | `;` followed by the ASCII string "start" and a NUL | not referenced by any instruction (the string is reached through the inline-string printer) |
| `$EC2A-$EC39` | 16 | `StageAttributeTable` | 16 per-stage attribute bytes copied to the attribute shadow when a stage starts | not referenced by any instruction (copied by index) |
| `$ED3F-$ED4E` | 16 | `SpritePaletteTable` | 4 x 4-byte records `[flag $FF][colour][colour][colour]` - the four sprite palettes, copied to the `$0090-$009F` palette shadow by `Reset_LoadSpritePalettes` | not referenced by any instruction (copied as a block) |
| `$EEE9-$EEEF` | 7 | `BallAppearTiles` | the CHR tile indices of the "ball appears" step animation, indexed by the step counter at `$0340` | `lda $EEE9,x` at `$EEC1` |
| `$EF2A-$EF30` | 7 | `BallSinkTiles` | the CHR tile indices of the "ball sinks" step animation | `lda $EF2A,x` at `$EEF8` |
| `$F098-$F0CD` | 54 | `TileCollisionTable` | 27 x 16-bit LE collision-flag words, one per tile | `lda $F098,x` at `$F093` and `lda $F099,x` at `$F08F` (the low and high byte of the selected word) |
| `$F5F3-$F653` | 97 | `EndingCommandList` | the inline `RunCommandList` script for the ending screen at the head of the block; the rest of the block is the ending code and its inline data | not referenced by any instruction (reached through the command-list interpreter) |
| `$F762-$F779` | 24 | `AimPhaseTable0` (`$F762`), `AimPhaseTable1` (`$F76A`), `AimPhaseTable2` (`$F772`) | three parallel 8-byte colour sequences (`10 00 0C 0E 0E 0C 00 10`, `32 22 12 02 01 02 12 22`, `0A 0B 1B 2B 3B 2B 1B 0B`) shimmered into the `$008B`/`$008F`/`$0092` palette shadow while aiming | `lda $F762,x` at `$EDD5`, `lda $F76A,x` at `$EDDA`, `lda $F772,x` at `$EDDF` |
| `$F78B-$F7A6` | 28 | `StrPlayer1` (`$F78B`), `StrShot` (`$F79B`) | `$F78B-$F78E` = the tail of the Japanese "player" string (`65 72 81` and a NUL); `$F79B-$F7A1` = `$81` then "shot" (`73 68 6F 74`), then `$81` and a NUL. The bytes between them are code | not referenced by any instruction (the strings are reached through the inline-string printer) |
| `$F7F9-$F819` | 33 | `StrPlayer2` (`$F7F9`), `StrGameOver` (`$F80B`) | `$F7F9-$F7FC` = the tail of the Japanese "player" string again; `$F80B-$F816` = "game" (`67 61 6D 65`), `$81`, "over" (`6F 76 65 72`), `$81` and a NUL. The bytes between them are code | not referenced by any instruction (the strings are reached through the inline-string printer) |
| `$F82B-$F84B` | 33 | `StrPlayer3` (`$F82B`), `StrHiScore` (`$F83B`) | `$F82B-$F82E` = the tail of the Japanese "player" string; `$F83B-$F846` = `$81` then "hi`score__" (`68 69 60 73 63 6F 72 65 5F 5F`) and a NUL. The bytes between them are code | not referenced by any instruction (the strings are reached through the inline-string printer) |
| `$FAC9-$FAF8` | 48 | `PaletteColorTable` | 12 rows of 4 colour codes, mapped to PPU palette entries by `MapColorCodeToPalette` | not referenced by any instruction (the rows are indexed by colour) |
| `$FB18-$FB2B` | 20 | `LinearStepValueTable` | 10 x 16-bit big-endian values in an exact arithmetic progression of `$1A1A`: `$000D $1A27 $3441 $4E5B $6875 $828F $9CA9 $B6C3 $D0DD $EAF7` | not referenced by any instruction (the values are picked by index) |
| `$FB90-$FB98` | 9 | `BallSpeedLevelTable` | 9 x 8-bit descending values `0B 0B 0B 0B 0A 0A 09 09 08` | `lda $FB90,x` at `$FB3A` and `$FB56` |
| `$FECE-$FF0D` | 64 | `SineTable` | 64 x 8-bit sine values (0, 6, 12, 18, ... 255), read by `GetSine` | `cmp $FECE,y` at `$E6D9`, `cmp $FECF,y` at `$E6E4`, `lda $FECE,x` at `$FEBE` |
| `$FF90-$FFF8` | 105 | `PaddingFf` | 105 bytes of `$FF` filler between the last table and the vector page | not referenced by any instruction |

### The blocks that are not tables

| Address | Size | Name | Structure | Read by |
|---------|------|------|-----------|---------|
| `$C0F2-$C12A` | 57 | - | a run of `jmp` trampolines (`4C 8F C0`, `4C 5C C0`, ...) - **code**, reached only indirectly through `ObjectOpcodeHandlerTable` at `$C0C0`. The tracer never reached it because it is entered through the pointer table | reached indirectly through `ObjectOpcodeHandlerTable` at `$C0C0` |
| `$C14A-$C18C` | 67 | - | another run of `jmp` trampolines - code, reached only indirectly through `ObjectOpcodeHandlerTable` | reached indirectly through `ObjectOpcodeHandlerTable` at `$C0C0` |
| `$CA9E-$CAA2` | 5 | - | unreferenced; decodes as a run of instructions (`lda $F0`, `and #$01`, `rts`) - code the tracer could not reach, not data | not referenced by any instruction |
| `$CAC9-$CAF6` | 46 | - | unreferenced; decodes as 23 consecutive instructions - code the tracer could not reach, not data | not referenced by any instruction |
| `$CB3E-$CB44` | 7 | - | unreferenced; decodes as a run of instructions (`ldx #$FA`, `jmp $CB45`) - code the tracer could not reach, not data | not referenced by any instruction |
| `$CB55-$CB59` | 5 | - | unreferenced; decodes as a run of instructions (`ldx #$F8`, `jmp $CB61`) - code the tracer could not reach, not data | not referenced by any instruction |
| `$CD38-$CD3B` | 4 | - | unreferenced; decodes as a run of instructions (`lda $0180`, `rts`) - code the tracer could not reach, not data | not referenced by any instruction |
| `$D05A-$D05A` | 1 | `DrawCellRunTileTable` | see the named-table section above | not referenced by any instruction |
| `$E281-$E285` | 5 | - | unreferenced; decodes as a run of instructions (`pla`, `tay`, `pla`, `tax`, `rts`) - code the tracer could not reach, not data | not referenced by any instruction |
| `$E8E6-$E8F5` | 16 | - | unreferenced; four groups of four small values (`03 03 1B 03`, `03 03 05 1C`, `09 01 07 0D`, `18 0D 02 FF`) whose meaning was not established from this dump | not referenced by any instruction |
| `$F0F2-$F101` | 16 | - | unreferenced; decodes as a run of instructions - code the tracer could not reach, not data | not referenced by any instruction |
| `$F15B-$F160` | 6 | - | unreferenced; decodes as a run of instructions - code the tracer could not reach, not data | not referenced by any instruction |
| `$F187-$F192` | 12 | - | unreferenced; decodes as a run of instructions - code the tracer could not reach, not data | not referenced by any instruction |
| `$F2D8-$F2DA` | 3 | - | unreferenced; decodes as a run of instructions - code the tracer could not reach, not data | not referenced by any instruction |
| `$F7CB-$F7E7` | 29 | - | unreferenced; a mixture of code and inline string bytes for the Japanese "game over" caption, which the tracer could not split | not referenced by any instruction |
| `$F866-$F866` | 1 | - | a single byte `$F7` sitting between two instructions | not referenced by any instruction |
| `$FFF9-$FFFF` | 7 | - | the IRQ stub (`rti` at `$FFF9`) followed by the three vectors: NMI = `$C02C`, RESET = `$C000`, IRQ = `$FFF9` | the CPU reads the vectors from the vector page |

### Notes

- The blocks that "decode as N consecutive instructions" are code, not
  data. The tracer never reached them, so they are still emitted as `.byte`
  rows, but their contents are instructions; they are left unnamed on
  purpose.
- The two blocks at `$C0F2-$C12A` and `$C14A-$C18C` are also code, but they
  are not dead: `ObjectOpcodeHandlerTable` points straight at them. They
  are listed as "reached indirectly" rather than as unreferenced data.
- `LayoutScriptTable` and `LayoutData` hold the stage layouts. No decoded
  instruction names an address inside either block - the stage index selects
  the entry and the script then walks the layout data - so the two blocks are
  reached indirectly and their internal record structure is recorded here
  rather than claimed.

The Pass 1 split came from a static trace only, and a static trace cannot see code that
is reached through computed dispatch, nor can it tell inline string data from an
instruction that happens to decode from the same bytes. Both errors were present.

Ground truth came from the emulator: Mesen's Code Data Logger marks every byte the CPU
**fetched as an opcode** (Code) and every byte it **read as data** (Data). Playing the
ROM through title → 1P → game over → VS COMP marked 10,028 PRG bytes Code (61.2%) and
1,534 Data; that is the classification oracle for every byte it observed. Where the CDL
is silent the previous classification is kept, never guessed.

| | code bytes | data bytes |
|---|---|---|
| As originally emitted by Pass 1 | 9,403 | 6,981 |
| After the CDL reclassification | **11,041** | **5,343** |

1,738 bytes that Pass 1 had emitted as `.byte` are executed code and are now
instructions; 100 bytes it had emitted as instructions are read as data and are now
`.byte`.

The result reconciles with the CDL exactly, with no disagreement in either direction:

| emitted as | CDL says Code | CDL says Data | CDL never saw it |
|---|---:|---:|---:|
| instructions | 10,028 | **0** | 1,013 |
| data (`.byte`/`.word`) | **0** | 1,534 | 3,809 |

Every byte the CDL observed is therefore classified the way the CPU used it. The 1,013
instruction bytes the CDL never saw are Pass 1 static code plus the two inference steps
below; the 3,809 unseen data bytes are the residue — 45 of them carry an undocumented
opcode's disassembly in the audit comment (Pass 1 read them as code statically, but the
CDL never watched the session fetch them, and ca65 V2.19 cannot encode those opcodes
anyway, so they stay `.byte` with the disassembly recorded).

As an independent structural check, all 1,183 control-flow targets in the file — 633
`jsr`/`jmp` operands and 550 branch targets — land exactly on an instruction boundary;
none points into an operand or a `.byte` run.

The rewrite is reproducible with `_tools/cdl_reclass.py` (dry run by default). Capture a
CDL from the Mesen MCP with
`mesen_cdl_file(action:'save', memoryType:'NesPrgRom', filepath:'lunar.cdl')` — the
capture is cumulative, so it does not reset — then:

```bash
python3 _tools/cdl_reclass.py --dir "copilot" --cdl lunar.cdl \
  --override 0xC0C0-0xC0E5:D \
  --override 0xF81A-0xF825:C --override 0xF826-0xF82E:D --override 0xF82F-0xF83A:C \
  --override 0xF83B-0xF846:D --override 0xF847-0xF84B:C --override 0xF84C-0xF857:C \
  --override 0xF858-0xF861:D --override 0xF862-0xF866:C
```

Its output differs from this `prg.s` only in this provenance header, the `.word` vector
split, and three `jsr Label_CAA3` → `jsr $CAA3` operand spellings (this file spells
`jsr`/`jmp` operands as raw addresses and branch operands as `Label_<addr>`). Always run
`make` afterwards.

Two inference steps were needed beyond the CDL because the capture never reached the
hi-score screen. They are marked as inference, not ground truth:

* `$C0C0–$C0E5` is a 19-entry little-endian 16-bit pointer table (read as
  `lda $C0C0,y` / `lda $C0C1,y`). Pass 1 had decoded it as a `cmp (ZpXX,x)` chain; the
  CDL only observed the few entries the current game state walked. Code resumes at
  `$C0E6` (`tax`), which is a real branch target from `$C101`.
* `$F81A` (hi-score) and `$F84C` ("perfect") are text routines. They are never reached
  in normal play until a hi-score is beaten, so the CDL is silent; their inline-string
  structure is inferred from the CDL-confirmed twins `$F77A` and `$F7E8`.

### The inline-string dispatcher (this is not a jump gate)

`$CBDC` (and its variant `$CBC9`, which also clears the PPU destination first) is a
**print-inline-string-and-return-after-it** helper:

```
$CBDC  pla / sta ptr_lo        ; pop the caller's return address = the string address
$CBDF  pla / sta ptr_hi
$CBE2  jsr $CB5A               ; prepare the PPU destination
$CBE5  ldy #$00
$CBE7  lda (ptr_lo),y          ; next character
$CBE9  beq $CBF4               ; $00 terminates
$CBEB  jsr $CC29               ; emit it (advances ptr_lo/hi)
$CBEE  jsr $CB5A
$CBF1  jmp $CBE5
$CBF4  lda ptr_hi / pha        ; push the address of the byte after the $00 ...
$CBF7  lda ptr_lo / pha
$CBFA  rts                     ; ... and rts to it
```

So every `jsr $CBDC` in the image is immediately followed by a `$00`-terminated string
that begins with the control byte `$81` (`$81` also acts as the word separator), and
execution resumes after the terminator:

| site | bytes | text |
|------|-------|------|
| `$F786` | `$81player$81$00` | player |
| `$F79B` | `$81shot$81$00` | shot |
| `$F7F4` | `$81player$81$00` | player |
| `$F809` | `$81game$81over$81$00` | game over |
| `$F826` | `$81player$81$00` | player |
| `$F83B` | ``$81hi`score__$00`` | hi`score__ |
| `$F858` | `$81perfect_$00` | perfect_ |

**Earlier revisions of this document claimed a `jmp ($7961)` RAM-pointer dispatch at
`$F788`/`$F7F6`/`$F828`. That was a flat-tracer phantom.** The bytes after `jsr $CBDC`
are the strings above; the decoder happened to start an instruction two bytes into
`player`, reading `$6C $61 $79` as `jmp ($7961)` — the operand is the middle of the word
"player". Nothing in the ROM ever writes `$7961`/`$7962`, and `$6000–$7FFF` is unmapped
on NROM, so such a jump could not work. The three sites are gone from the classification;
no instruction in the corrected file is an indirect `jmp`.

The genuine computed dispatch that remains is small and resolved. `$CBE5` re-reads its
string pointer through `ptr_lo`/`ptr_hi` and re-enters its loop with it — plain code.
`$F193` does the reverse: it pushes `Zp17`/`Zp16` and `rts`es, so a caller sets that pair
and the `rts` transfers control to it; the pattern is named in `locals.inc` and every
target is inside CDL-covered code.

### Code the CDL proved but Pass 1 missed (largest runs)

| Range | Bytes | What it is |
|-------|------:|-----------|
| `$EA00–$EBAF` | 432 | VS-COMP / select-screen logic (`$EB16` is still unreached and stays data) |
| `$EBF3–$ED4E` | 348 | menu/round state machine |
| `$CE35–$CF9A` | 358 | collision/entity maths |
| `$D4FA–$E01D` | 2,852 | `$D4FA` 30-entry pointer table (`$D4FA–$D535`), the 35-byte code helper at `$D536–$D558`, then variable-length records from `$D559` |
| `$F897–$F98F` | 249 | high-score / attract handling |
| `$C0F2–$C18C` | 155 | object update chain (branches back to `$C0E6`) |
| `$D325–$D391`, `$D2A0–$D2D3`, `$D1BB–$D209` | 240 | further record/table walkers |

### Tracer fixes required during Pass 1

Three undocumented opcodes were missing from `_tools/nesdis.py` and were added, with the
`--undocumented` switch (default off, so existing `make regen` pipelines stay byte-stable):

* `$72` — `RRA abs` (the `RRA` family had `$63`/`$67`/`$6F`/`$73`/`$77`/`$7B`/`$7F` but not `$72`).
* `$42` — `NOP #imm` (the family had `$80`/`$82`/`$89`/`$C2`/`$E2` but not `$42`).
* `$FA` — `NOP abs,X` (the family had `$1C`/`$3C`/`$5C`/`$7C`/`$DC`/`$FC` but not `$FA`).

One emitter fix: ca65 silently rewrites an operand whose high byte is `$00` into the
shorter zero-page form (`sta $00FF,x` becomes `sta $FF,x`, emitting `$95` instead of
`$9D`). `render()` now emits the `a:` prefix for ABS/ABSX/ABSY/IND operands with a high
byte of `$00`, forcing the absolute form so the bytes match the ROM. `operand_value()`
strips the prefix when parsing.

## Entry points that are still named after their address

**48 of the 233 address-derived entry points are still named `SubC<addr>`.** The
other 185 now carry a name taken from what the ROM shows them doing, and their
`; Global:` lines were rewritten to say so. The residue is grouped below by
*why* the dump does not reveal a better name.

| Address | Name | Why the dump does not reveal a better name |
|---------|------|------------------------------------------|
| `$CD20A` | `SubCD20A` | a three-instruction stub that seeds the VRAM pointer for the attribute table; it is only ever reached from the neighbouring attribute code, and nothing in the dump says which picture it belongs to |
| `$E0BA`, `$E0E3`, `$E0E7`, `$E118`, `$E147`, `$E162` | `SubCE0BA` … `SubCE162` | the diagonal-movement pair for the two sides of the rally. The code moves a 16-bit position by a decoded fixed-point step, but the dump never says in words which of the two is the ball and which is the aiming cursor |
| `$E1AC`, `$E1F2` | `SubCE1AC`, `SubCE1F2` | print the score-panel marker tile (`$68` = `h` for one player, `$6E` = `n` for the other) and the six digits that follow it. The dump gives the glyph indices but not the Japanese word the glyph stands for |
| `$E202`, `$E20D`, `$E215`, `$E21A`, `$E225`, `$E22D`, `$E24F`, `$E25C`, `$E286`, `$E2A2`, `$E2C8` | `SubCE202` … `SubCE2C8` | eleven stubs that each print one label tile at one fixed screen position. The tile indices (`$62`, `$87`, `$C3`, `$C4`, `$7D`, `$7E`) are visible, but the game's font is a Japanese one and the dump carries no character table, so a name would have to guess at the word |
| `$E31D`, `$E322`, `$E34A`, `$E370` | `SubCE31D` … `SubCE370` | the serve state machine. It reads two RAM flags and a frame counter, and the game never names what the flags mean |
| `$E3BF`, `$E3FB`, `$E40E`, `$E415`, `$E43B`, `$E582`, `$E586`, `$E60B`, `$E67A` | `SubCE3BF` … `SubCE67A` | the field-index and hit-test arithmetic. The dump shows the 16-bit and 8-bit coordinate maths, but not which player each side of the comparison is |
| `$E71D`, `$E76D`, `$E7B1`, `$E7B5` | `SubCE71D` … `SubCE7B5` | three setters of one byte that is then compared against a per-slot threshold; the dump shows the comparison but not what the byte counts |
| `$EA0B`, `$EB06`, `$EC0C`, `$EC3A` | `SubCEA0B` … `SubCEC3A` | three screen set-ups and one index reset. Each draws a different panel, and the dump's own strings do not name those panels |
| `$EE3A` | `SubCEE3A` | a two-instruction stub that stores a constant into a flag byte; it is the tail of the routine above it |
| `$F017` | `SubCF017` | a one-instruction stub inside the ball-state routine; it is the tail of the block above it |
| `$F0CE` | `SubCF0CE` | a candidate entry in the ball-collision table at `$F098`. The bytes here decode as `TXS`/`SBC ($A5),Y`/`SED`, which no sensible routine would start with, so the tracer's split of this region is probably one byte out. The dump does not settle what the routine is |
| `$F225`, `$F238` | `SubCF225`, `SubCF238` | two tests of the ball's state byte against `$22`; the dump does not say which state `$22` is |
| `$F413` | `SubCF413` | counts a round timer down and then loads the round statistics; the dump does not name the timer |
| `$F56C` | `SubCF56C` | a two-call stub that picks between two of the field routines; the dump does not say what the branch tests |

Two of these are **not** really entry points at all: `$EE3A` and `$F017` are the
tails of the routine above them and carry a `SubC` name only because Pass 2 gave
every label in the file a name.

## Known remaining gaps

* The static tracer reported two overlaps (`$C3BB` — resolved with `--data 0xC3BB:1` —
  and `$F0EF`) and three rejected mis-aligned stubs. The residue that remains is the
  CDL's: 5,343 bytes (32.6%) are still emitted as data (`.byte`, plus the six vector
  bytes as `.word`).
* Unreached in the CDL session, therefore still unclassified: the hi-score entry screen
  (`$F81A`+ / `$F84C`+ are inferred by symmetry, above), the 2-player-only branches, and
  `$EB16` (a poll loop behind `beq` at `$EB11`, emitted as a raw `beq *+$05`).
* `locals.inc` carries 104 aliases: **38 semantic** (see the Pass 3 notes at the foot of
  the file) and 66 neutral `ZpXX`. Ten further aliases were deleted by the
  reclassification: they were phantoms — `$49`/`$84`/`$8A`/`$AA`/`$C0` came from the
  mis-decoded `$C0C0` table, and `$3B`/`$65`/`$67`/`$72`/`$81` were ASCII characters of
  the inline strings read as operands.

## Project folder contents

| File | Purpose |
|------|---------|
| `Lunar Pool (U).nes` | original ROM image (reference) |
| `rom.nes` | space-free symlink to the ROM, used by the `cmp` |
| `prg.bin` / `header.bin` / `chr.bin` | split image, produced by `_tools/splitnes.py` |
| `header.s` / `chr.s` | one-line `.incbin` of `header.bin` / `chr.bin` |
| `prg.s` | disassembly: 5,285 instructions with per-instruction address/byte audit comments, unclassified bytes kept as `.byte`/`.word`, and 41 named data tables |
| `symbols.inc` | shared NES hardware constants (PPU/APU/controller) |
| `locals.inc` | project-local zero-page aliases — 38 semantic, 66 neutral `ZpXX`; Pass 3 evidence notes at the foot of the file |
| `linker.cfg` | PRG at $C000, 16 KB, `fill = yes` |
| `Makefile` | links `reconstructed.nes` and `cmp`s it against `rom.nes` (whole ROM) |
| `reconstructed.nes` | build output from the last verified build |
| `lunarpool_gameplay.cdl` | Mesen Code Data Logger capture used for the Pass 1 reclassification |

This project is promoted: the project folder links `header.s` + `prg.s` + `chr.s` and `make`
compares the whole `reconstructed.nes` against `rom.nes`, so header, PRG and CHR are all
proven. `header.bin`/`chr.bin` remain as the `.incbin` sources for those two stubs.

## Build

```bash
cd "NROM/Lunar Pool (U)"
make        # → cmp reconstructed.nes rom.nes → "Byte-identical ROM verified."
```

## Next Steps

Passes 1-3 are complete and the project is promoted to the top level (row 17); see
*Pass Status* above. The data tables are interpreted and recorded in
*Pass 3 data-table inventory*. The remaining residue is the ~354 bytes the CDL could not
settle, kept `.byte` on purpose and itemised under *Known remaining gaps*; the largest
single item is the 16-byte block at `$E8E6-$E8F5`, whose meaning was not established from
this dump. No pass work is pending.