Xevious (U): Pass 1 disassembly

The first _wip project to get a real disassembly.  4,165 instructions /
8,444 code bytes (25.8%), 24,324 data bytes, 0 unclassified -- every byte
of the 32 KB PRG is now classified as code or data.

The split needed three stages, all recorded in prg.s's header:

  * nesdis.py --undocumented --auto-seed at base $8000 gave 3,272
    instructions / 6,555 bytes.  The undocumented opcodes matter here: the
    trace stops dead at the first one it cannot decode.
  * Four hand-seeded entries ($C08B, $DC1E, $E0D5, $E134).  Each is a
    branch target from decoded code that sat inside an untraced data run,
    so the tracer never reached it.
  * A merged four-session Mesen Code Data Logger capture (kept as
    xevious_mesen.cdl) promoted 1,902 bytes from data to code and
    demoted 22 the trace had called code.

Two tool bugs fell out and are fixed here:

  * nesdis.py emitted the undocumented single-byte NOPs ($1A/$3A/$5A/
    $7A/$DA/$FA) as `nop`, which ca65 assembles as the *official* $EA --
    the rebuild stopped being byte-identical at $DF82.  The check now
    keys on the opcode byte, not just the addressing mode.  All three
    `make regen` pipelines (MUSCLE, Pyramid, Urban Champion) are
    unaffected and still reproduce prg.s byte for byte.

  * cdl_reclass.py left the original data-block header in place when the
    CDL split that block, so the file ended up with two region headers
    describing overlapping spans (20 of them here).  The header is now
    dropped with the block it describes; the promoted projects that use
    the tool are byte-for-byte unchanged.

The project README has the power-on flow analysis.  The most interesting
find is at $FC45: the reset path compares RAM $0100-$0107 against the
ASCII string "Kei Cros", and the copyright text at $FF1E reads
"MAIN: KEI CROSS.  SOUND: UHOHOY OHNOGI."  The OAM is at $0700, not
$0200 -- the NMI handler does LDA #$07 / STA $4014.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Add explicit `make wip` / `make wipclean` targets for the _wip tier

The root Makefile's all / clean / <MAPPER> targets deliberately name only
the promoted mapper folders, so nothing in them reaches into _wip/.  Give
the pre-promotion tier its own opt-in targets instead of the manual
`for d in _wip/*/*/; do make -C "$d"; done` loop:

  make wip          # build + verify every _wip/<MAPPER>/<Project>/
  make wipclean     # clean the build artifacts in that tier

Both the Makefile and the four documents that describe the tier (README,
TODO, WIP, AGENTS) are updated together, so the tree stays consistent.

The same commit records Xevious (U) reaching Pass 2 in those documents:
all 487 labels named, every branch and call symbolic, zero Label_XXXX and
zero raw $XXXX operands left.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Update the _wip/ tier documentation; fix the make wip target and the mirroring bug

The WIP tier's four documents (WIP.md, README.md, TODO.md, AGENTS.md) had
drifted away from the tree.  Every number in them was re-derived from the
ROMs and the folder layout rather than carried forward.

Counts and structure
  - The tier holds 854 projects across 29 mapper folders, not "856 across
    30".  Xevious (U) and Zanac (U) were promoted on 2026-10-20 and their
    _wip/ folders were left behind as residue -- "git mv" moves only the
    tracked files, so the old folder survived with its build artifacts and a
    stale README.  Both are removed now; the promotion procedure documents
    the step so it does not recur.
  - _wip/MAPPER8/ holds a copy of the already-promoted Mermaids of
    Atlantis (U) and is excluded from every count and table.
  - Pass 0 skeletons: 852 (was 855).  Xevious (U) left the tier, so the
    two projects with a real disassembly are Golf (JU) and Volleyball (U).
  - PRG sizes 2 / 150 / 42 / 522 / 127 / 10 / 1; 226 projects with no CHR;
    38 keep the CPU-address linker layout; 37 are mapper 0.
  - Every inventory row was re-checked against its ROM: PRG/CHR size,
    mirroring, all three vectors, and the battery / four-screen / footer
    notes.  854 of 854 rows now match.

Fixes
  - The root Makefile used $(WIP) but never defined it, so "make wip" and
    "make wipclean" expanded to "for m in /*/" -- they walked the
    filesystem root instead of the tier.  "WIP := _wip" is now defined, and
    "make wip" builds and verifies the whole tier: 855 of 855 passed, 0
    failures.
  - make_skeleton.py masked header byte 6 with 0x03, so the battery bit
    (bit 1) leaked into the mirroring value and 56 battery-backed ROMs'
    READMEs claimed "Four-screen" while their own "Four-screen VRAM" row
    said "no".  The mask is now 0x01 and the 56 READMEs are corrected.
  - Golf (JU)'s README still described the pre-flatten copilot/ folder and
    the old PRG-only compare; it now describes the whole-ROM build.
  - Pyramid (U)'s audit comments are canonical again, so Golf (JU) is the
    only project in the tree still on the pre-canonical spelling.

New in WIP.md
  - Byte 7's lower nybble is non-zero on 58 of the ROMs -- 55 carry the
    literal "DiskDude!" watermark, two "DisNi0330", one "byKH+KEN".  Only
    the upper nybble carries mapper bits, so the noise is harmless.
  - The twelve ROMs that set the four-screen bit, split by whether their
    board actually supports four-screen VRAM.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Promote Volleyball (U) from _wip/NROM/ to NROM/

Volleyball (U) reached Pass 3 before promotion, so this is a promotion of a
finished disassembly rather than a Pass 0 skeleton.

The disassembly
  - 11,395 instructions / 23,926 code bytes (73.0 % of the PRG image),
    8,842 data bytes, 0 unclassified.
  - The split needed the game-state dispatch table at $85E1 declared to the
    tracer (--table 85E1:11) -- without it only 66 % of the image traced --
    plus a Mesen Code Data Logger capture taken while a random-input bot
    played the attract demo, which promoted 1,757 bytes from data to code.
  - Pass 2 named all 1,989 labels: 730 read out of the code by hand, 1,221
    internal branch targets derived mechanically.  Zero Label_XXXX, zero raw
    $XXXX call or branch operands, zero SubC residue.
  - Pass 3 named the zero page, the $0500 ball structure and all 37 data
    blocks.  apply_symbols.py --report: 0 pending substitutions, 0
    multi-alias residue.  align_audit_comments.py: no column drift.
  - cdl_check.py cross-checks the finished prg.s against the capture: 0
    CDL-code bytes not covered by an instruction, 0 CDL-data bytes that
    start one.
  - 29 neutral ZpXX zero-page slots remain, each with its reason recorded
    in locals.inc, as the promotion rules allow.

The promotion
  - git mv "_wip/NROM/Volleyball (U)" "NROM/Volleyball (U)".  Mapper 0, so
    it lands in NROM/.  The whole-ROM build was already in place, so there
    was no build surgery; the project builds byte-identically at its new
    home and the old folder is gone (git mv moves the untracked build
    artifacts too, so no residue was left behind).
  - Root README.md: new inventory row 39 and a per-project detail section,
    plus the WIP-tier counts.  The detail sections for Xevious (U) and
    Zanac (U) were numbered one too high against the inventory rows and
    are now aligned; a leftover editing note in the same place is gone.
  - WIP.md: the Volleyball row leaves the inventory, and the tier is now
    853 projects across 29 mapper folders (36 in _wip/NROM/), 852 of them
    Pass 0 skeletons.  Golf (JU) is the only project left in the tier with
    a real disassembly.
  - TODO.md and AGENTS.md: the same counts, and the promoted tier is now
    40 projects (39 under NROM/).

Verified: make wip builds and verifies the whole tier (854 of 854 passed,
0 failures) and make builds the promoted tier (39 of 39 passed).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Rename NROM/Pyramid (U) to NROM/Pyramid (U) (Sachen)

The promoted inventory row had read "Pyramid (U) (Sachen)" since the
project was promoted on 2026-10-20, but the folder was named "Pyramid (U)" --
so the row pointed at a folder that did not exist.  The folder now matches
the row, and the project's own README title, its ROM file name
("Pyramid (U) (Sachen).nes") and the parenthetical convention the rest of
the promoted tier already uses (Popeye (JU) (PRG 0/1), Raid on Bungeling
Bay (U) [a2], Pac-Man (Tengen) (U)).

What changed inside the project
  - The Makefile's regen target passes --project "Pyramid (U) (Sachen)", so
    the tracer writes the matching header line.  prg.s and locals.inc were
    updated to that header line and nothing else -- the disassembly is
    byte-identical to before.
  - make regen still reproduces prg.s and locals.inc byte for byte.
  - The project's README's build-verification line now names the new folder.

References updated: the root README.md (inventory prose, the row-33 detail
section, the build-status table, and the notable-observations bullet),
TODO.md (the promoted-projects table and the Pyramid notes) and AGENTS.md
(the recently-promoted list and the unlicensed-titles quirk).

Verified: make builds the promoted tier (39 of 39 passed) and the project
rebuilds byte-identically at its new path.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Rebuild Mermaids of Atlantis (U): bank-aware Pass 1, Pass 2/3 names

The promoted project did not build: a Pass 2 rename had been applied
half-way, leaving eight undefined symbols and two jumps that pointed at
the wrong routine, while the root README already claimed the project was
byte identical.  The _wip copy still built, because it held the un-renamed
Pass 1 source.

The disassembly is now derived from the ROM itself, with the Mesen Code
Data Logger as the oracle for the code/data split:

* _tools/banked_dis.py traces every MMC3 bank separately, each with the CPU
  window it is visible at, seeded from a CDL capture so the code a static
  trace cannot reach is disassembled too.  The CDL is the authority: a
  decode the CPU never fetched is dropped, and so is the fall-through
  behind a call whose target never returns (the game's dispatchers have
  their jump table right behind the call).
* One segment per bank (PRG0..PRG7) with its own .org, so the assembler
  knows the CPU address of every label while the linker still writes the
  bytes to the bank's file offset.  A flat segment cannot do both: a call
  would encode the file offset instead of the CPU address.
* Pass 2 names every label - 494 routines, no Label_XXXX and no raw
  $XXXX branch or jump operand left.  Pass 3 applies 13 semantic zero-page
  aliases and writes the routine headers.
* 8,075 bytes of code (12.3% of the 64 KB PRG), up from 200 bytes.

The banking turned out to be unusual and is documented: the fixed bank is
the fourth 8 KB bank (file $6000-$7FFF), not the last one, and the image
carries the reset stub and the vector table twice.  The live NMI vector
is $808F - the frame handler - while the copy at the end of the image
names $8189, which is a BRK in the first half.  The game's text table
lives at CPU $F1D6, which is the fixed window, and that is what settles
the question.

Also: the leftover _wip/MAPPER8 folder is removed, as it is for every
other promotion.

The project builds byte identical:

    Byte-identical ROM verified.

Add CHANGELOG.md: the pass history of every project

A project goes through four milestones - Pass 1 (the code/data split),
Pass 2 (the labels replaced by names), Pass 3 (the semantic naming) and
Promotion (the move into the top-level mapper folder) - and the history
of those milestones was scattered over the commit log, the project
READMEs and the root README.

CHANGELOG.md gathers it: one section per project with a row for each
milestone, the date, and a sentence saying what the milestone produced.
The numbers are the ones the project README and the root README already
carry - instruction count, code coverage, named labels, semantic
zero-page aliases, named data tables - so a reader can see at a glance
which projects are done and which are not.  Golf (JU), the only project
still in _wip/ with a real disassembly, is listed with its open
milestones, and the other 852 _wip/ projects are covered as a tier.

The requirement is now part of the workflow contract: PROMPTS.md gains a
"Pass 3: Changelog entry" section and a ninth checklist item, and
AGENTS.md points at the file.  A milestone and its changelog row go in
the same commit, so the changelog and the source never disagree.

Balloon Fight (JU): repair the audit trail and complete the routine headers

The per-instruction audit trail was stale by two bytes from
ResetInitializationData ($C085) onward.  5,944 of the 6,007 comments named
the wrong CPU address and PRG offset, because the three-byte .byte "HAL"
signature at $C082-$C084 had been counted as one byte when the trail was
first generated - the routine headers and the linker labels were right all
along, so the source and its own headers disagreed with each other.  The
trail was rebuilt from the ca65 -l listing with
_tools/repair_audit_comments.py, and every rewritten comment was re-checked
against prg.bin.  The comments were also moved into the canonical column-35
field: they had sat two spaces after the mnemonic, with no column discipline
at all, unlike every other promoted project.

All 63 routine headers now carry a ; Clobbers: block, so the headers carry
the full template AGENTS.md describes.  The blocks are derived, not written by
hand.  The new _tools/derive_clobbers.py takes the opcode from the audit
comment's byte list, so the addressing mode is exact and a data directive is
never mistaken for an instruction; it resolves the operand through
locals.inc and symbols.inc to name what is written; it follows the real
control flow, so a jsr to another named entry is a call (the callee's
clobbers count) while a branch or a fall-through is not; and it models
register preservation, so NmiHandler reports *no register* - it saves and
restores A, X and Y around the frame - and FlushPpuCommandPreserved reports
only A, because X and Y come back unchanged.

Two tools changed.  derive_clobbers.py is new.  align_audit_comments.py had
an off-by-one: it tested the indented code length against 31 instead of
against 35, so code texts of 28-31 characters were never padded into the
column.

The change is comments only.  The code text of all 8,538 lines is unchanged,
make still prints "Byte-identical ROM verified.", the 6,007 audit comments
still re-check against prg.bin, all 63 routine headers agree with the
instructions they describe, and every label agrees with reconstructed.lbl.
ReflectObjectYVelocity and UpdateSpecialObjectSystem moved out of locals.inc
and became labels in prg.s at their real addresses.

CHANGELOG.md becomes the repository's running log: a Pending list of the
changes to be put in the next commit, a History of the commits already made,
and the per-project milestone index at the end.  The next commit's message is
written from the Pending entries, so the two cannot drift apart.  PROMPTS.md
and AGENTS.md describe the new shape.  WIP.md drops the _wip/MAPPER8/ note:
the folder held a copy of Mermaids of Atlantis (U) that had already been
promoted.

World Class Track Meet (U): Pass 1, the code/data split

Pass 1 is done.  The split is 8,400 instructions / 18,028 code bytes (55.0 %)
of the 32 KB PRG, with 884 routine entries, 55 data blocks and 102 zero-page
aliases.  The PRG is CNROM (mapper 3) and maps whole at $8000-$FFFF, so the
linker moved the PRG segment from a .nes file offset to $8000 and the build
still compares byte identical.

Four dispatch tables had to be seeded by hand.  The event table at $F796 (5
entries) is read at $F780 and jumped to through `jmp ($001F)`.  The three
push-pointer tables - $BFC4 (16 entries), $BFE4 (2) and $E5F2 (7) - push a
handler address and `rts` into it, and the 6502's `rts` adds one to the
address it pops, so each table stores the entry address minus one; the seeds
are the table values plus one.  The tracer runs with --undocumented: the code
uses undocumented NMOS opcodes as ordinary code (ANC $37 at $BFF8, and the
RRA/RLA/SLO and NOP forms elsewhere).  Seeding the tables takes the coverage
from 27.8 % to 55.0 %.

$C0BE-$C0C5 is forced back to data: the IRQ vector $C0C0 points into the
middle of the `jmp $C047` at $C0BE, and the game never executes CLI, so the
vector is dead.  `make pass1` regenerates prg.s and locals.inc from prg.bin
and reproduces the committed prg.s byte for byte.

The project README records the split, the four dispatch tables, the dead IRQ
vector, the wrong CHR size field in the header, and what is still data.  The
milestone index in CHANGELOG.md gains the project; WIP.md, README.md and
AGENTS.md follow the tier counts and the layout.

nesdis.py gains a --mapping-note option, so the header's "PRG mapped at" line
can describe a board that is not NROM - CNROM's whole 32 KB at $8000-$FFFF is
not "mirrored to the upper half".

Replaces runs of $00 and $FF with .res <run>, <byte>

Golf (JU) and World Class Track Meet (U): Pass 2/3 complete, promoted from _wip/

- World Class Track Meet (U) - Pass 2 complete: all 884 Label_<addr>
  definitions replaced (651 semantic routine names + 233 Sub_<addr>), all 731
  raw $XXXX jsr/jmp call operands resolved to symbolic labels, all branch
  targets given role-based names; routinemap.tsv added; make stays
  byte-identical.
- World Class Track Meet (U) - Pass 3 complete: 24 semantic zero-page
  aliases applied via apply_symbols.py (0 residue), 78 neutral ZpXX slots
  documented with reasons in locals.inc, all hardware-register operands use
  symbols.inc names, project README rewritten with Pass 2/Pass 3 sections and
  data-table inventory; promoted out of _wip/CNROM/.
- World Class Track Meet (U) - project README documents the five event-table
  entries at $F796 and marks the olympics mode as not yet proven.
- Golf (JU) - audit comments converted from pre-canonical (; C000: A9 00)
  to the canonical ; CPU:$C000 PRG:0000  A9 00 form at column 35; 4,156
  comments re-aligned, comment/whitespace only, whole-ROM build stays
  byte-identical.
- Golf (JU) - 339 internal branch-target Label_ labels given role-based names
  via _tools/derive_branch_names.py; 0 raw $XXXX branch/jump operands remain.
- Golf (JU) - 275 zero-page operands substituted with locals.inc aliases via
  apply_symbols.py; 0 residue; promoted out of _wip/NROM/.
- Xevious (U) - runs of $FF padding replaced with .res <count>, $FF in prg.s;
  whole-ROM build stays byte-identical.
- Both projects promoted via git mv; leftover _wip/ folders removed; root
  README.md inventory rows added; WIP.md rows removed.

World Class Track Meet (U): apply zero-page symbol substitutions

Run apply_symbols.py to substitute ZpXX zero-page operands with
semantic locals.inc aliases (SlotState, GameMode, etc.) at proven
sites; 0 residue, whole-ROM build stays byte-identical.

Xevious (U): re-split Pass 1 from the Mesen CDL and decode the data tables

- Xevious (U) - Pass 1 re-split from the Mesen CDL (xevious_mesen.cdl) with
  _tools/cdl_reclass.py: 1,158 bytes data->code, 48 code->data, 42 labels
  emitted and 3 branch targets labelled; code 11,321->12,455 bytes
  (34.5%->38.0%), instructions 5,513->6,002. The 45 recovered entry points
  are named Sub_XXXX, so no Label_XXXX remains; six CDL-silent raw call
  operands are documented as residue.
- Xevious (U) - the 4,448-byte block at $A74B-$B8AA is split into six proven
  tables: VramWritePtrTable (15 pointers), VramWriteData, DataStreamPtrTable
  (16), ObjTilePtrTable (99), ObjTileData and DataStreamData. The $D833
  pointer table is corrected to base $D833 (4 entries; the old ObjCodePtrTable
  at $D834 was one byte late). $F957-$FAF5 is split into ObjSpeedTable,
  ObjSpeedTable2, SpriteLayoutPtrTable (19) and SpriteLayoutData;
  $FEE6-$FF1C into PaletteData and OamAttrTable. $F5D8 is decoded as
  TextTileData (font tile indices: PLAYER, GAME OVER, READY, SOLVALOU, LEFT,
  PAUSE); $F53C becomes AttrAddrTable, $F89E HandlerPtrTable and $EF3B
  SpriteLayoutData2. Project README rewritten with the corrected stats, a
  32-entry table inventory and the Pass 1 residue.
- _tools/cdl_reclass.py - preserve the data label(s) between a data-block
  header and its first .byte row when the block stays data; the $DF78 split
  dropped Data_DF78 and the rebuild failed with an undefined symbol.
- _tools/resolve_raw_branches.py - handle negative relative offsets
  (beq *-$0B); the pattern only matched *+$NN and *$NN.

Docs: refresh the tier counts to 41 promoted / 851 _wip, add the WCTM row

- Docs - tier counts refreshed to the post-promotion state across AGENTS.md,
  root README.md, WIP.md, TODO.md and CHANGELOG.md: 41 promoted projects
  (38 under NROM/, plus CNROM/World Class Track Meet (U), UNROM/Zanac (U) and
  MAPPER8/Mermaids of Atlantis (U)) and 851 _wip/ projects, every one of them
  a Pass 0 skeleton. The stale "39/40 promoted", "853 _wip", "Golf (JU) is
  still in _wip/" and "Golf is the last pre-canonical project" statements are
  corrected.
- Root README.md - the promoted inventory gained the missing World Class Track
  Meet (U) row (row 41, mapper 3, 32 KB PRG / 32 KB CHR), and the "All 38 are
  mapper 0 / 16 KB PRG" sentence is replaced with the actual split (36 of the
  41 rows are mapper 0 / 16 KB; Xevious and Volleyball are 32 KB, World Class
  Track Meet is mapper 3, Zanac mapper 2 and Mermaids mapper 8).

NROM/Pyramid (U) (Sachen)/Makefile

@@ -0,0 +1,73 @@
+CA65 ?= ca65
+LD65 ?= ld65
+PYTHON ?= python3
+TOOLS  ?= ../../_tools
+
+all: reconstructed.nes verify
+
+prg.o: prg.s symbols.inc locals.inc
+	$(CA65) -g -o $@ $<
+
+header.o: header.s header.bin
+	$(CA65) -g -o $@ $<
+
+chr.o: chr.s chr.bin
+	$(CA65) -g -o $@ $<
+
+reconstructed.nes: header.o prg.o chr.o linker.cfg
+	$(LD65) -C linker.cfg -m reconstructed.map -Ln reconstructed.lbl -o $@ header.o prg.o chr.o
+
+verify: reconstructed.nes rom.nes
+	cmp reconstructed.nes rom.nes
+	@echo "Byte-identical ROM verified."
+
+# Regenerate prg.s and locals.inc from prg.bin, then re-apply the naming.
+# Every --table/--extra-seed flag below is a documented classification
+# decision, not a convenience; see the provenance block at the head of prg.s.
+#
+#   --table 0xC3A6:9,0xCCD5:8  the two queued-event dispatchers, whose
+#                               16-bit vector tables hold the handler
+#                               addresses the engine jumps to
+#   --extra-seed                 the sixteen targets of the four `jmp`
+#                               trampoline tables the tracer cannot see
+#                               ($C01E, $C02A, $C042, $C054), the $C800
+#                               boot mainline, and six further code starts
+#                               found by inspection
+regen: pass1 pass2 pass3
+
+pass1:
+	$(PYTHON) $(TOOLS)/nesdis.py --prg prg.bin --base 0xC000 --project "Pyramid (U) (Sachen)" \
+	    --out prg.s --locals locals.inc --auto-seed \
+	    --table "0xC3A6:9,0xCCD5:8" \
+	    --extra-seed "0xC800,0xC1C9,0xC1D0,0xC1D7,0xC1EF,0xC205,0xC201,0xC225,0xC23A,0xC294,0xC34A,0xC43E,0xC585,0xC5AB,0xC614,0xC662,0xC6A3,0xD79D,0xD7D7,0xD7EB,0xDF89,0xF942,0xFF74"
+	cat zp_aliases.inc >> locals.inc
+
+# Pass 2: the routine and branch-target names, then the zero-page aliases
+# at the sites where their role is proven.
+pass2: pass1
+	$(PYTHON) $(TOOLS)/apply_pass2_map.py . routinemap.tsv --write
+	$(PYTHON) $(TOOLS)/apply_zp_aliases.py . \
+	    --alias ScriptPtrLo=Zp02 --alias ScriptPtrHi=Zp03 --alias CommandListFlag=Zp04 \
+	    --alias VramPosHi=Zp05 --alias VramPosLo=Zp06 --alias FrameCounter=Zp0A \
+	    --alias FrameCounterHi=Zp0B --alias DrawCounter=Zp0C \
+	    --alias SoundTickScriptLo=Zp27 --alias SoundTickScriptHi=Zp28 \
+	    --alias SoundPlayer1ScriptLo=Zp29 --alias SoundPlayer1ScriptHi=Zp2A \
+	    --alias SoundPlayer2ScriptLo=Zp2B --alias SoundPlayer2ScriptHi=Zp2C \
+	    --alias SoundPlayer3ScriptLo=Zp2D --alias SoundPlayer3ScriptHi=Zp2E \
+	    --alias Player1Input=Zp3D --alias Player2Input=Zp3E \
+	    --alias SpriteX=Zp43 --alias SpriteY=Zp44 \
+	    --alias DeltaLo=Zp4D --alias DeltaMid=Zp4E --alias DeltaHi=Zp4F \
+	    --alias DeltaWrapCount=Zp50 \
+	    --at-ind 'ScriptPtrLo@C3A3' --at-ind 'ScriptPtrLo@CCCA' --write
+
+# Pass 3: name the data blocks, apply the hardware register names, and put
+# the audit comments back in their canonical column.
+pass3: pass2
+	$(PYTHON) $(TOOLS)/name_data_region.py . $$(awk -F'\t' '!/^#/ && NF>1 {printf "%s=%s ", $$1, $$2}' data_region_names.tsv) --write
+	$(PYTHON) $(TOOLS)/apply_symbols.py . --write
+	$(PYTHON) $(TOOLS)/align_audit_comments.py . --write
+
+clean:
+	rm -f *.o reconstructed.nes reconstructed_prg.bin reconstructed.map reconstructed.lbl
+
+.PHONY: all verify clean regen pass1 pass2 pass3

NROM/Pyramid (U) (Sachen)/README.md

@@ -0,0 +1,206 @@
+# Pyramid (U) (Sachen) — Game Flow from Power-On
+
+This document describes the execution flow of the disassembled **Pyramid (U) (Sachen)** PRG bank (16 KB, mapped at CPU **$C000–$FFFF**), starting from power-on. It is based entirely on `prg.s` in the repository. The rebuild is verified **byte-identical to the original ROM** — `make` compares the whole `reconstructed.nes` against `rom.nes`.
+
+**This is an unlicensed Sachen release.** The iNES header claims mapper 0, but the boot code writes to `$4100` — past the end of the NES register space. On the real cartridge those pokes are a mapper-unlock/protection sequence. That mismatch is recorded, not explained.
+
+---
+
+## 1. Reset Vector — CPU $FFFC → $FF00
+
+| Vector | Address | Handler |
+|--------|---------|---------|
+| NMI | $D72E | `NmiHandler` |
+| RESET | $FF00 | `Reset` — the boot chain, at the very end of the PRG |
+| IRQ | $FF00 | `Reset` — the same address; `sei` is never undone, so the IRQ never fires |
+
+**`Reset`** ($FF00) is the cold-start chain, and it is unusual in that the whole thing lives in the vector page:
+
+```
+Reset ($FF00):
+    ldx #$FF / txs / sei / cld
+    lda #$00 / sta PPUCTRL / sta PPUMASK
+    lda #$30 / jsr BootPokeMapperUnlock
+    jsr BootCheckStackBytes
+    bcc Reset_Loop                  ; the check failed - take the other sequence
+    lda #$10 / jsr BootPokeMapperUnlock
+    lda #$30 / jsr BootPokeMapperUnlock
+    jsr BootUnlockDelay / jsr BootUnlockDelay
+    lda #$10 / jsr BootPokeMapperUnlock
+    jmp BootChainEntry
+
+Reset_Loop ($FF2F):                 ; the alternate poke sequence
+    lda #$20 / jsr BootPokeMapperUnlock
+    lda #$30 / jsr BootPokeMapperUnlock
+    lda #$20 / jsr BootPokeMapperUnlock
+    ...
+```
+
+The two sequences differ in the values poked: `$30 $10 $30` on the carry-set path, `$20 $30 $20` on the carry-clear path.
+
+### The mapper unlock
+
+**`BootPokeMapperUnlock`** ($FF49) is one instruction plus a delay:
+
+```
+BootPokeMapperUnlock:
+    sta $4100            ; the unlock poke
+BootUnlockDelay:
+    ldy #$04
+BootUnlockDelay_Loop:
+    ldx #$CE
+BootUnlockDelay_Inner:
+    dex / bne BootUnlockDelay_Inner
+    dey / bne BootUnlockDelay_Loop
+    rts
+```
+
+The delay is the protection: the console latches `$4100` and the ROM waits for the mapper to settle.
+
+### The "AV" check
+
+**`BootCheckStackBytes`** ($FF57) compares two RAM bytes against the letters **A** and **V**:
+
+```
+BootCheckStackBytes:
+    lda #$41 / cmp $0120 / bne BootCheckStackBytes_Fail
+    lda #$56 / cmp $0121 / bne BootCheckStackBytes_Fail
+    sec / rts
+BootCheckStackBytes_Fail:
+    clc / rts
+```
+
+`Carry` set means the check passed and the first poke sequence runs; `Carry` clear means the alternate sequence runs. **`BootSeedStackBytes`** ($FF69) writes `$41`/`$56` into `$0120`/`$0121` itself, so the check is satisfied on the next pass. **`ClearCheckerBytes`** ($FF74) writes `$00` into both again.
+
+### The real entry
+
+**`BootChainEntry`** ($FF3E) is the hand-off into the game:
+
+```
+BootChainEntry:
+    lda #$30 / jsr BootPokeMapperUnlock
+    jsr BootSeedStackBytes        ; seed the "AV" checker bytes for next time
+    jmp BootColdStart             ; the real init, at $C800
+```
+
+**`BootColdStart`** ($C800) is the game's own entry: it sets up the stack, waits for two vblank phases, clears RAM, resets the sound engine and initialises the PPU.
+
+---
+
+## 2. The dispatch architecture
+
+The game dispatches through **two levels** of indirection.
+
+### The task table — `jmp` trampolines
+
+The entry points live in a table of `jmp` instructions rather than of addresses. Four such tables sit inside the data regions:
+
+| Table | Address | Entries | Task |
+|-------|---------|---------|------|
+| `TaskDispatchTable1` | $C01E | 3 | $C1C9, $C1D0, $C1D7 |
+| `TaskDispatchTable2` | $C02A | 6 | $C1EF, $C205, $C201, $C225, $C23A, $C294 |
+| `TaskDispatchTable3` | $C042 | 2 | $C34A, $C43E |
+| `TaskDispatchTable4` | $C054 | 5 | $C585, $C5AB, $C614, $C662, $C6A3 |
+
+and the first ten entries of the table are code of their own, at $C000–$C01B (`Task_PlayVramScript`, `Task_CopyBlockToCommandBuffer`, `Task_UploadPalette1`, …). The tracer cannot see any of this: a `jmp` inside a data region is just four bytes to it, so **all sixteen targets had to be seeded by hand**.
+
+### The queued-event dispatchers
+
+Two dispatchers jump through the zero page with `jmp (ScriptPtrLo)`:
+
+| Dispatcher | Site | Vector table | Entries |
+|------------|------|--------------|---------|
+| 1 | `DispatchTask1` ($C392) | `TaskVectorTable1` ($C3A6) | 9 entries — the ninth, $D820, is a **junk slot** and stays data |
+| 2 | `DispatchTask2` ($CCB8) | `TaskVectorTable2` ($CCD5) | 8 entries, preceded by the 8-byte `TaskIndexTable2` at $CCCD |
+
+Both build the pointer with the same idiom — read a 16-bit entry from the table into $02/$03, then `jmp ($0002)` — and both terminate the static trace.
+
+---
+
+## 3. The VRAM command list
+
+The engine never writes the PPU directly. It assembles a **byte stream** in the buffer at $0700 and flushes it:
+
+- `$FE` — the next two bytes are a VRAM address
+- `$FD` — end of list
+- anything else — a byte for $2007
+
+`PlayVramScript` ($C063) walks a script and builds that list; `FlushVramCommandList` ($C127) plays it back. `FinishCommandList` ($C11B) writes the `$FD` marker and waits for `CommandListFlag` to clear.
+
+---
+
+## 4. The NMI handler
+
+`NmiHandler` ($D72E) is the per-frame entry: it advances the frame counter, runs `ActorUpdate` ($D50A) and `SoundTick` ($DF80), then restores the registers. Two byte counters at $D75C/$D75D accumulate the frame total, and `DrawNumber` ($D79D) turns that into the score digits on the PPU.
+
+---
+
+## 5. Pass 3 Data-Table Inventory
+
+| Address | Name | Size | What it holds |
+|---------|------|------|---------------|
+| $C01E | `TaskDispatchTable1` | 9 | three `jmp` trampolines |
+| $C02A | `TaskDispatchTable2` | 18 | six `jmp` trampolines |
+| $C042 | `TaskDispatchTable3` | 6 | two `jmp` trampolines |
+| $C054 | `TaskDispatchTable4` | 15 | five `jmp` trampolines |
+| $C3A6 | `TaskVectorTable1` | 16 | the first dispatcher's eight handler addresses |
+| $C52A | `PaletteIndexTable` | 12 | the palette slot indices |
+| $C605 | `SoundDeltaTable` | 15 | the 16-bit deltas the sound engine adds and subtracts |
+| $C6E7 | `ZeroPadding` | 281 | zero fill up to the level data |
+| $C95A | `SpriteTileTable` | 77 | the tile indices of the sprite sheet |
+| $CAAA | `ActorAttributeTable` | 73 | four-byte actor attribute records |
+| $CBC1 | `ActorSizeTable` | 27 | the actor size and speed classes |
+| $CCCD | `TaskIndexTable2` | 8 | the second dispatcher's per-slot index |
+| $CCD5 | `TaskVectorTable2` | 16 | the second dispatcher's eight handler addresses |
+| $CD97 | `ActorParameterTable` | 13 | per-actor behaviour parameters |
+| $D021 | `BrightnessRampTable` | 9 | the brightness ramp `$0F $14 $28 $3C $50 $64` |
+| $D0C5 | `ActorTypeTable` | 14 | the actor type codes |
+| $D1AA | `ActorOffsetTable` | 8 | the per-actor table offsets |
+| $D2AB | `ActorSpriteTable` | 20 | the sprite indices per actor |
+| $D320 | `LevelLayoutTable` | 129 | the per-level byte table |
+| $D467 | `ActorBehaviourTable` | 15 | the actor behaviour records |
+| $D4EE | `ActorInitialStateTable` | 28 | the actors' initial state |
+| $D556 | `ActorSpeedTable` | 21 | the actor speed steps |
+| $D5D5 | `ActorSpriteOffsetTable` | 93 | the per-actor sprite offsets |
+| $D69C | `ValueRampTable` | 16 | the value ramp |
+| $D72D | `ActorFlagByte` | 1 | a single flag byte |
+| $D7F3 | `LevelScriptData` | 1,703 | the packed level script |
+| $DEBB | `SoundSampleTable` | 16 | the sound sample descriptors |
+| $DF30 | `MusicPeriodTable` | 80 | the 16-bit note periods |
+| $E276 | `SoundEnvelopeTable` | 2,808 | the instrument and envelope ramps |
+| $EDBF | `SoundSamplePool` | 2,770 | the sample and instrument pool |
+| $F95D | `ZeroPadding2` | 1,443 | zero fill up to the vector page |
+| $FF7D | `VectorPagePadding` | 131 | zero fill up to the vectors |
+
+---
+
+## 6. Naming and Residue
+
+**Pass 1** — 8,253 lines. 3,130 instruction lines covering 6,493 code bytes (**39.6%**), 632 data lines covering 9,891 bytes, 3,762 canonical audit comments. The byte accounting is exact: 16,384 bytes, no duplicates, nothing missing.
+
+**Pass 1 correction (2026-10-20).** The committed split was a strict subset of the correct one: **828 bytes** of code were still marked as data, because the tracer cannot follow a `jmp` that sits inside a data region. Re-tracing with the sixteen `jmp`-table targets, the `$C800` boot mainline and six further code starts seeded by hand recovers them, and a five-byte stub at $DF89 (`lda $33 / jmp SoundPlayEffect`) that sits in a hole between two routines. The re-trace loses **no** committed code byte.
+
+**Pass 2 complete** — 463 label definitions, **zero `Label_` residue**: 431 routine entries and the 32 data blocks, named from this dump's own code. **No raw `$XXXX` operand** remains on any `jsr`, `jmp` or branch. The map is in `routinemap.tsv`; the internal branch-target names are derived mechanically from the branch that reaches them by `_tools/derive_branch_names.py`.
+
+**Pass 3** — 24 semantic zero-page aliases, each applied only where its role is proven (`locals.inc`, `zp_aliases.inc`). 57 slots keep their neutral `ZpXX` name, and **every one of them is listed with the reason** in `locals.inc`. `apply_symbols.py` reports **0 substitutions pending and 0 residue**; no hardware register is left as a raw literal.
+
+**Residue (recorded, not guessed):**
+- The zero page is reused heavily — 410 references still carry a neutral name. The largest group is `$45`–`$49` (105, 69, 33, 22 and 11 references), which are the general-purpose scratch of the shift and arithmetic helpers; one name would not describe their other uses.
+- 482 absolute operands point at RAM ($0700, $0200, $0400, $0436, …). Those are data addresses, not hardware registers, and stay numeric.
+- `sta $4100` at $FF49 stays a raw operand. It is outside the `$2000-$4017` range that `PROMPTS.md` asks to be symbolic, and no `symbols.inc` name would describe a mapper unlock.
+
+---
+
+## 7. Promotion to `NROM/` (2026-10-20)
+
+Moved out of `_wip/NROM/` with `git mv`; the build now compares the **whole ROM**, not just the PRG:
+
+- `header.s` / `chr.s` added (one-line `.incbin`s of `header.bin` / `chr.bin`)
+- `linker.cfg` gained the `HEADER` ($0000, $0010) and `CHR` ($0000, $2000) areas ahead of `PRG` ($C000, $4000)
+- `rom.nes` — symlink to `Pyramid (U) (Sachen).nes`
+- `Makefile` builds `header.o` / `prg.o` / `chr.o` into `reconstructed.nes` and compares it against `rom.nes`
+- `make regen` reproduces `prg.s` and `locals.inc` from `prg.bin` and re-applies the naming, so the split stays reproducible
+
+`reconstructed.nes` is 24,592 bytes, MD5 `aa285ff1…6c59e2` — equal to the original ROM. The `header.bin` / `prg.bin` / `chr.bin` splits were checked against the original before promotion: they are the ROM's first 16 bytes, its next 16,384 bytes and its last 8,192 bytes, exactly.
+
+Build verification: `make` in `NROM/Pyramid (U) (Sachen)/` produces `reconstructed.nes`, compared against `rom.nes` (**whole-ROM byte-identical**).

NROM/Pyramid (U) (Sachen)/chr.s

@@ -0,0 +1,2 @@
+.segment "CHR"
+    .incbin "chr.bin"

NROM/Pyramid (U) (Sachen)/data_region_names.tsv

@@ -0,0 +1,34 @@
+# Pyramid (U) — Pass 3 data-block names.
+# Format: <CPU address><TAB><name>.  Applied by _tools/name_data_region.py.
+C01E	TaskDispatchTable1
+C02A	TaskDispatchTable2
+C042	TaskDispatchTable3
+C054	TaskDispatchTable4
+C3A6	TaskVectorTable1
+C52A	PaletteIndexTable
+C605	SoundDeltaTable
+C6E7	ZeroPadding
+C95A	SpriteTileTable
+CAAA	ActorAttributeTable
+CBC1	ActorSizeTable
+CCCD	TaskIndexTable2
+CCD5	TaskVectorTable2
+CD97	ActorParameterTable
+D021	BrightnessRampTable
+D0C5	ActorTypeTable
+D1AA	ActorOffsetTable
+D2AB	ActorSpriteTable
+D320	LevelLayoutTable
+D467	ActorBehaviourTable
+D4EE	ActorInitialStateTable
+D556	ActorSpeedTable
+D5D5	ActorSpriteOffsetTable
+D69C	ValueRampTable
+D72D	ActorFlagByte
+D7F3	LevelScriptData
+DEBB	SoundSampleTable
+DF30	MusicPeriodTable
+E276	SoundEnvelopeTable
+EDBF	SoundSamplePool
+F95D	ZeroPadding2
+FF7D	VectorPagePadding

NROM/Pyramid (U) (Sachen)/header.s

@@ -0,0 +1,2 @@
+.segment "HEADER"
+    .incbin "header.bin"

NROM/Pyramid (U) (Sachen)/linker.cfg

@@ -0,0 +1,10 @@
+MEMORY {
+  HEADER: start = $0000, size = $0010, file = %O, fill = yes;
+  PRG:    start = $C000, size = $4000, file = %O, fill = yes;
+  CHR:    start = $0000, size = $2000, file = %O, fill = yes;
+}
+SEGMENTS {
+  HEADER: load = HEADER, type = ro;
+  PRG:    load = PRG,    type = ro;
+  CHR:    load = CHR,    type = ro;
+}

NROM/Pyramid (U) (Sachen)/locals.inc

@@ -0,0 +1,173 @@
+; Pyramid (U) (Sachen) application-specific RAM aliases - Pass 1
+; Generated from every direct zero-page operand in reachable code:
+; ref counts are reads/writes, `where` lists the referencing addresses.
+; ZpXX names indicate storage with a role not yet unique enough for a behavioral name;
+; Pass 2 replaces them with names derived from observed usage.
+
+Zp00                    = $00 ; 9 refs; reads=3 writes=6; used at $C0BF, C1A2, C401, C815, +5 more
+Zp01                    = $01 ; 11 refs; reads=4 writes=7; used at $C0B3, C1EF, C843, C883, +7 more
+Zp02                    = $02 ; 46 refs; reads=32 writes=14; used at $C063, C069, C070, C090, +41 more
+Zp03                    = $03 ; 19 refs; reads=7 writes=12; used at $C065, C0BB, C0DD, C0FD, +14 more
+Zp04                    = $04 ; 6 refs; reads=4 writes=2; used at $C120, C122, C127, C15D, +1 more
+Zp05                    = $05 ; 8 refs; reads=1 writes=7; used at $C06B, C1AF, C31D, CA43, +4 more
+Zp06                    = $06 ; 11 refs; reads=3 writes=8; used at $C072, C198, C1A8, C324, +6 more
+Zp07                    = $07 ; 8 refs; reads=1 writes=7; used at $C84A, C8F4, C9D8, CA0B, +4 more
+Zp08                    = $08 ; 12 refs; reads=7 writes=5; used at $C87C, C8B8, C8BA, C8BC, +4 more
+Zp09                    = $09 ; 1 refs; reads=1 writes=0; used at $D768
+Zp0A                    = $0A ; 9 refs; reads=5 writes=4; used at $C1C2, C1C4, C909, CBED, +4 more
+Zp0B                    = $0B ; 5 refs; reads=2 writes=3; used at $C90B, C925, CBEF, D791
+Zp0C                    = $0C ; 4 refs; reads=1 writes=3; used at $C33B, D1EE, D1FF, D210
+Zp0D                    = $0D ; 6 refs; reads=5 writes=1; used at $C1C9, C2A6, C2D2, C449, +1 more
+Zp0E                    = $0E ; 4 refs; reads=3 writes=1; used at $C1CD, C483, C48B
+Zp0F                    = $0F ; 5 refs; reads=3 writes=2; used at $DFFB, DFFF, E002, E004, +1 more
+Zp11                    = $11 ; 1 refs; reads=0 writes=1; used at $E02D
+Zp12                    = $12 ; 2 refs; reads=1 writes=1; used at $E02F, E036
+Zp13                    = $13 ; 7 refs; reads=4 writes=3; used at $E087, E08C, E0A0, E0A4, +3 more
+Zp15                    = $15 ; 1 refs; reads=0 writes=1; used at $E0D2
+Zp16                    = $16 ; 2 refs; reads=1 writes=1; used at $E0D4, E0DB
+Zp17                    = $17 ; 7 refs; reads=4 writes=3; used at $E12C, E131, E145, E149, +3 more
+Zp19                    = $19 ; 1 refs; reads=0 writes=1; used at $E177
+Zp1A                    = $1A ; 2 refs; reads=1 writes=1; used at $E179, E180
+Zp1B                    = $1B ; 3 refs; reads=2 writes=1; used at $E1C2, E1C7, E24F
+Zp1F                    = $1F ; 3 refs; reads=1 writes=2; used at $DF9C, E049, E205
+Zp20                    = $20 ; 3 refs; reads=1 writes=2; used at $E059, E0EE, E220
+Zp21                    = $21 ; 3 refs; reads=1 writes=2; used at $E0FE, E193, E230
+Zp22                    = $22 ; 3 refs; reads=1 writes=2; used at $E1A3, E1F9, E249
+Zp23                    = $23 ; 6 refs; reads=2 writes=4; used at $DF01, DF14, DF92, DF96, +1 more
+Zp24                    = $24 ; 4 refs; reads=2 writes=2; used at $E04F, E053, E0E7
+Zp25                    = $25 ; 4 refs; reads=2 writes=2; used at $E0F4, E0F8, E18C
+Zp26                    = $26 ; 4 refs; reads=2 writes=2; used at $E199, E19D, E1E2
+Zp27                    = $27 ; 6 refs; reads=4 writes=2; used at $DED8, DFA3, DFCF, E03D, +1 more
+Zp28                    = $28 ; 3 refs; reads=1 writes=2; used at $DEDD, E25E
+Zp29                    = $29 ; 8 refs; reads=5 writes=3; used at $DEE2, E060, E085, E089, +3 more
+Zp2A                    = $2A ; 5 refs; reads=2 writes=3; used at $DEE7, E090, E094, E265
+Zp2B                    = $2B ; 8 refs; reads=5 writes=3; used at $DEEC, E105, E12A, E12E, +3 more
+Zp2C                    = $2C ; 5 refs; reads=2 writes=3; used at $DEF1, E135, E139, E26C
+Zp2D                    = $2D ; 8 refs; reads=5 writes=3; used at $DEF6, E1AA, E1C0, E1C4, +3 more
+Zp2E                    = $2E ; 5 refs; reads=2 writes=3; used at $DEFB, E1CB, E1CF, E273
+Zp2F                    = $2F ; 4 refs; reads=1 writes=3; used at $DF05, DF16, DF8E, DFBB
+Zp30                    = $30 ; 2 refs; reads=1 writes=1; used at $E04B, E078
+Zp31                    = $31 ; 2 refs; reads=1 writes=1; used at $E0F0, E11D
+Zp32                    = $32 ; 2 refs; reads=1 writes=1; used at $E195, E1B2
+Zp33                    = $33 ; 15 refs; reads=8 writes=7; used at $CA1D, CDF4, CDF9, CE06, +11 more
+Zp34                    = $34 ; 5 refs; reads=4 writes=1; used at $DFD1, DFD8, E040, E0E5, +1 more
+Zp3D                    = $3D ; 2 refs; reads=1 writes=1; used at $C171
+Zp3E                    = $3E ; 2 refs; reads=1 writes=1; used at $C17D
+Zp3F                    = $3F ; 5 refs; reads=3 writes=2; used at $C301, C303, C314, D72F, +1 more
+Zp40                    = $40 ; 4 refs; reads=2 writes=2; used at $C305, C307, D735, D737
+Zp41                    = $41 ; 4 refs; reads=2 writes=2; used at $C309, C30B, D73B, D73D
+Zp42                    = $42 ; 3 refs; reads=2 writes=1; used at $C30D, C30F, C312
+Zp43                    = $43 ; 1 refs; reads=1 writes=0; used at $C234
+Zp44                    = $44 ; 1 refs; reads=1 writes=0; used at $C225
+Zp45                    = $45 ; 105 refs; reads=53 writes=52; used at $C09E, C0A8, C23A, C241, +86 more
+Zp46                    = $46 ; 69 refs; reads=36 writes=33; used at $C23D, C24C, C271, C27C, +56 more
+Zp47                    = $47 ; 33 refs; reads=18 writes=15; used at $C34A, C364, C4C8, C4CE, +26 more
+Zp48                    = $48 ; 22 refs; reads=13 writes=9; used at $C440, C467, C47B, C4A1, +17 more
+Zp49                    = $49 ; 11 refs; reads=7 writes=4; used at $C43E, C44B, C462, C485, +6 more
+Zp4D                    = $4D ; 19 refs; reads=10 writes=9; used at $C5AB, C5C0, C5C6, C5E3, +12 more
+Zp4E                    = $4E ; 18 refs; reads=9 writes=9; used at $C5AE, C5C8, C5CE, C5EB, +11 more
+Zp4F                    = $4F ; 16 refs; reads=8 writes=8; used at $C5B1, C5D0, C5D8, C5FC, +9 more
+Zp50                    = $50 ; 5 refs; reads=2 writes=3; used at $C5B8, C5DA, C5F9, C64B
+Zp55                    = $55 ; 1 refs; reads=1 writes=0; used at $C61A
+Zp80                    = $80 ; 1 refs; reads=1 writes=0; used at $D7D7
+ZpAC                    = $AC ; 1 refs; reads=1 writes=0; used at $D7DB
+ZpD0                    = $D0 ; 5 refs; reads=2 writes=3; used at $CF51, CF82, CF90, D1BB, +1 more
+ZpD1                    = $D1 ; 2 refs; reads=1 writes=1; used at $CF80, CF92
+ZpD2                    = $D2 ; 3 refs; reads=1 writes=2; used at $D1D2, D1E7
+ZpD4                    = $D4 ; 2 refs; reads=1 writes=1; used at $CF60, CF69
+ZpD5                    = $D5 ; 5 refs; reads=2 writes=3; used at $C831, F89A, F8D5, F8DA
+ZpD6                    = $D6 ; 5 refs; reads=2 writes=3; used at $C833, F8EF, F939, F93E
+ZpD7                    = $D7 ; 2 refs; reads=1 writes=1; used at $C82B, F8A2
+ZpD8                    = $D8 ; 4 refs; reads=2 writes=2; used at $C82F, F8B0, F8B2
+ZpD9                    = $D9 ; 3 refs; reads=2 writes=1; used at $F8FE, F917, F91C
+ZpDA                    = $DA ; 4 refs; reads=3 writes=1; used at $F8F9, F920, F922
+ZpDB                    = $DB ; 3 refs; reads=2 writes=1; used at $F8A5, F8A7, F8C8
+ZpDC                    = $DC ; 3 refs; reads=2 writes=1; used at $F8AB, F8CF
+ZpDD                    = $DD ; 3 refs; reads=2 writes=1; used at $F90C, F90E, F92C
+ZpDE                    = $DE ; 3 refs; reads=2 writes=1; used at $F912, F933
+; ---------------------------------------------------------------------------
+; Semantic zero-page aliases (Pass 3)
+;
+; Every alias below was read out of this dump's own code.  The neutral ZpXX
+; name stays on the same line so the file keeps both readings.
+;
+; $02/$03   the 16-bit pointer to the command script: every routine that
+;            reads the script uses (Zp02),y, and AdvanceScriptPointer at
+;            $C1D0 increments the pair
+; $04       the command-list sync flag: set by FinishCommandList, waited
+;            on by FinishCommandList_Wait, tested by FlushVramCommandList
+; $05/$06   the VRAM write position: BuildVramAddress at $C198 folds
+;            $06 into the low byte and $05 into the high byte of a
+;            $2000-based address
+; $0A/$0B   the 16-bit frame counter: incremented once per NMI at $D791
+;            and used by AddToCounter as the value to wait for
+; $0C       the counter the three draw routines clear before they run
+; $27/$28   the pointer to the sound tick script
+; $29/$2A   the pointer to the first sound player's script
+; $2B/$2C   the pointer to the second sound player's script
+; $2D/$2E   the pointer to the third sound player's script
+; $3D/$3E   the JOY1/JOY2 shift registers, filled by ReadControllers
+; $43/$44   the sprite X and Y, written into OAM bytes 3 and 0
+; $4D/$4E/$4F  the 24-bit delta the sound engine adds and subtracts
+; $50       the per-voice wrap counter of the delta subtraction
+; ---------------------------------------------------------------------------
+ScriptPtrLo            = $02 ; semantic alias for Zp02 (the 16-bit command-script pointer)
+ScriptPtrHi            = $03 ; semantic alias for Zp03 (the high byte of that pointer)
+CommandListFlag        = $04 ; semantic alias for Zp04 (the command-list sync flag)
+VramPosHi              = $05 ; semantic alias for Zp05 (the high bits of the VRAM write position)
+VramPosLo              = $06 ; semantic alias for Zp06 (the low bits of the VRAM write position)
+FrameCounter           = $0A ; semantic alias for Zp0A (the 16-bit frame counter)
+FrameCounterHi         = $0B ; semantic alias for Zp0B (the high byte of the frame counter)
+DrawCounter            = $0C ; semantic alias for Zp0C (the counter the draw routines clear)
+SoundTickScriptLo      = $27 ; semantic alias for Zp27 (the sound tick script pointer)
+SoundTickScriptHi      = $28 ; semantic alias for Zp28 (the high byte of that pointer)
+SoundPlayer1ScriptLo   = $29 ; semantic alias for Zp29 (the first sound player's script pointer)
+SoundPlayer1ScriptHi   = $2A ; semantic alias for Zp2A (the high byte of that pointer)
+SoundPlayer2ScriptLo   = $2B ; semantic alias for Zp2B (the second sound player's script pointer)
+SoundPlayer2ScriptHi   = $2C ; semantic alias for Zp2C (the high byte of that pointer)
+SoundPlayer3ScriptLo   = $2D ; semantic alias for Zp2D (the third sound player's script pointer)
+SoundPlayer3ScriptHi   = $2E ; semantic alias for Zp2E (the high byte of that pointer)
+Player1Input           = $3D ; semantic alias for Zp3D (the JOY1 shift register)
+Player2Input           = $3E ; semantic alias for Zp3E (the JOY2 shift register)
+SpriteX                = $43 ; semantic alias for Zp43 (the sprite X, OAM byte 3)
+SpriteY                = $44 ; semantic alias for Zp44 (the sprite Y, OAM byte 0)
+DeltaLo                = $4D ; semantic alias for Zp4D (the 24-bit sound delta)
+DeltaMid               = $4E ; semantic alias for Zp4E (the middle byte of the delta)
+DeltaHi                = $4F ; semantic alias for Zp4F (the high byte of the delta)
+DeltaWrapCount         = $50 ; semantic alias for Zp50 (the per-voice wrap counter)
+
+; ---------------------------------------------------------------------------
+; Slots that stay neutral, and why
+;
+; The aliases above are the ones whose role the ROM proves.  Every slot
+; below is listed with the reason it keeps its neutral ZpXX name: the role
+; is either only visible inside one routine, or the address is reused for
+; two different things, so a single name would be a guess.
+;
+; $00/$01   the two halves of a $20xx VRAM address in the boot and palette
+;           code, reused as plain scratch elsewhere
+; $07/$08   the boot region's frame and state counters
+; $09       one read, in a comparison that never leads anywhere
+; $0D/$0E   a 16-bit counter in one routine and a RAM pointer in another
+; $0F       a byte the sound player passes around
+; $11/$12   the envelope bytes of the sound tick
+; $13/$14   the envelope bytes of the first sound player
+; $15/$16   the envelope bytes of the second sound player
+; $17/$18   the envelope bytes of the third sound player
+; $19/$1A   the target bytes of the first sound player
+; $1B/$1C   the target bytes of the second and third sound players
+; $1F       a flag the sound player clears when it starts
+; $20/$21/$22  the "finished" flag of each of the three sound players
+; $23-$26   the four voices' envelope bytes, indexed by X
+; $2F-$32   the four voices' flag bytes, indexed by X
+; $33       the sound effect id and the "a voice is playing" flag
+; $34       a counter
+; $3F-$42   the 24-bit product accumulator of Multiply16
+; $45/$46   the general-purpose scratch of the shift and arithmetic helpers
+; $47       the carry byte of those helpers
+; $48/$49   the second and third operand slots of the delta helpers
+; $55       one read, as the seed of a delta
+; $80       the base of the indexed sound table
+; $AC       one comparison against a table byte
+; $D0-$DE   the sound engine's per-voice working bytes
+; ---------------------------------------------------------------------------

NROM/Pyramid (U) (Sachen)/rom.nes

@@ -0,0 +1 @@
+Pyramid (U) (Sachen).nes

NROM/Pyramid (U) (Sachen)/routinemap.tsv

@@ -0,0 +1,459 @@
+# Pyramid (U) (Sachen) — Pass 2 name map
+#
+# Derived from this dump's own committed split.  Every name below was read
+# out of the code; nothing is generic where the ROM gives a better basis.
+#
+# Format:  <CPU address><TAB><name>
+#
+# The routine entries (the task table, the engine routines and the boot
+# chain) are named by hand; the internal branch targets are derived from the
+# branch that reaches them by _tools/derive_branch_names.py:
+#   beq -> OnZero      bne -> OnNonzero
+#   bcc -> OnCarryClear  bcs -> OnCarrySet
+#   bmi -> OnNegative    bpl -> OnNonnegative
+#   bvc -> OnOverflowClear  bvs -> OnOverflowSet
+#   a backwards branch (the target is below the branch) -> Loop
+#
+# The game dispatches through `jmp` trampoline tables that live inside the
+# data regions ($C000-$C01B and the data blocks at $C01E, $C02A, $C042 and
+# $C054).  Those table entries are the game's *task* entries and are named
+# Task_<name>; the routines they jump to carry the plain name.
+#
+# Two vocabularies are used for the zero-page and RAM state:
+#   * $02/$03    the 16-bit script pointer
+#   * $00/$01    the high/low bytes of a VRAM address
+#   * $04        the command-list sync flag
+#   * $05/$06    the VRAM write position
+#   * $0700/$0701  the VRAM command buffer (16-bit pointer)
+
+C000	Task_PlayVramScript
+C003	Task_CopyBlockToCommandBuffer
+C006	Task_UploadPalette1
+C009	Task_UploadPalette2
+C00C	Task_FinishCommandList
+C00F	Task_StrobeControllers
+C012	Task_EmitVramAddressMarker
+C015	Task_DrawSpriteAtPosition
+C018	Task_ClearOamShadow
+C01B	Task_AddToCounter
+C027	Task_FlushVramCommandList
+C03C	Task_Multiply16
+C03F	Task_BuildVramCommandList
+C048	Task_ShiftRight8
+C04B	Task_ShiftLeft8
+C04E	Task_SetPalette16
+C051	Task_SetPaletteBlock16
+C063	PlayVramScript
+C090	PlayVramScript_CopyRun
+C0A0	PlayVramScript_WriteData
+C0A8	PlayVramScript_StoreCount
+C0AD	PlayVramScript_NextCommand
+C0B3	PlayVramScript_End
+C0B9	CopyBlockToCommandBuffer
+C0CD	CopyBlockToCommandBuffer_Loop
+C0DB	UploadPalette1
+C0ED	UploadPalette1_Loop
+C0FB	UploadPalette2
+C10D	UploadPalette2_Loop
+C11B	FinishCommandList
+C122	FinishCommandList_Wait
+C127	FlushVramCommandList
+C139	FlushVramCommandList_Loop
+C155	FlushVramCommandList_WriteData
+C15B	FlushVramCommandList_End
+C160	StrobeControllers
+C16A	ReadControllers
+C188	DrawSpriteAtPosition
+C192	EmitVramAddressMarker
+C198	BuildVramAddress
+C1B6	ClearOamShadow
+C1BA	ClearOamShadow_Loop
+C1C1	AddToCounter
+C1C4	AddToCounter_Wait
+C1C9	IncrementCounter16
+C1CF	IncrementCounter16_End
+C1D0	AdvanceScriptPointer
+C1D6	AdvanceScriptPointer_Loop
+C1D7	ConvertNibbleToBcd
+C1E2	ConvertNibbleToBcd_Digit
+C1EA	ConvertNibbleToBcd_Store
+C1EF	SetPpuCtrl
+C1F6	WaitForVblankClear
+C1FB	WaitForVblankSet
+C201	SetPpuCtrlAndMask
+C205	SetPpuCtrlAndMask_Alt
+C207	SetPpuCtrlAndMask_Store
+C225	StoreOamEntry
+C23A	DrawTwoDigitNumber
+C256	DrawTwoDigitNumber_Loop
+C25F	DrawTwoDigitNumber_High
+C277	EmitDigit
+C28A	EmitDigit_SetFlag
+C28F	EmitDigit_Store
+C294	AddDeltaToPosition
+C2A0	AddDeltaToPosition_Loop
+C2B6	AddDeltaToPosition_Carry
+C2BE	AddDeltaToPosition_Store
+C2E2	AddDeltaToPosition_Carry2
+C2EA	AddDeltaToPosition_Store2
+C2F9	AddDeltaToPosition_End
+C300	Multiply16
+C317	BuildVramCommandList
+C31B	BuildVramCommandList_SetAddress
+C32C	BuildVramCommandList_Data
+C341	BuildVramCommandList_Store
+C347	BuildVramCommandList_End
+C34A	CopyBlockToCommandBufferTail
+C354	CopyBlockToCommandBufferTail_Loop
+C35F	SetPaletteBlock
+C36D	SetPaletteBlock_Loop
+C384	ScanForButtonPress
+C386	ScanForButtonPress_Loop
+C392	DispatchTask1
+C3B6	MoveSpriteRight
+C3C7	MoveSpriteLeft
+C3D8	ComputeOamSlotAddress
+C3E3	MoveSpriteDown
+C3E7	MoveSpriteUp
+C3EB	MoveSpriteLeft2
+C3EF	MoveSpriteRight2
+C3F0	ClampSpriteToGrid
+C3FA	ClampSpriteToGrid_Redraw
+C3FD	Task_ReturnStub
+C3FE	BuildVramPositionWrite
+C43E	Subtract16
+C460	Subtract16_Loop
+C477	Subtract16_Loop2
+C47A	Subtract16_Loop3
+C49A	Subtract16_Loop4
+C4B1	Subtract16_Loop5
+C4B4	Subtract16_Loop6
+C4B8	ShiftRight8
+C4C0	ShiftRight8_OnNonzero
+C4C7	ShiftRight8_Loop
+C4D1	ShiftLeft8
+C4D9	ShiftLeft8_OnNonzero
+C4E4	ShiftLeft8_Loop
+C4EB	SetPalette16
+C4FD	SetPalette16_Loop
+C50A	SetPalette16_Entry
+C536	SetPaletteBlock16
+C548	SetPaletteBlock16_Loop
+C56D	SetPaletteBlock16_Entry
+C585	WriteDigitString
+C58F	WriteDigitString_Loop
+C59D	WriteDigitString_Loop_Loop
+C5A1	WriteDigitString_Loop_Loop2
+C5AB	AddDelta24
+C5B8	AddDelta24_Copy
+C5C0	AddDelta24_Loop
+C5E1	AddDelta24_Borrow
+C614	AddDelta24B
+C620	AddDelta24B_Save
+C662	SetPaletteEntry
+C676	SetPaletteEntry_OnCarryClear
+C683	SetPaletteEntry_OnCarryClear2
+C6A3	SetPaletteEntry2
+C6BA	SetPaletteEntry2_OnNonnegative
+C6DB	SetPaletteEntry2_OnCarryClear
+C800	BootColdStart
+C805	BootWaitForVblank
+C80A	BootWaitForVblank2
+C815	BootClearRam
+C835	BootInitState
+C897	BootFirstFrame
+C8A4	BootDecCounters
+C8B8	BootDecTimer
+C8D0	BootCopySpriteData
+C8F2	BootUploadPalette
+C90D	BootCopyTableToBuffer
+C932	BootCopyTableStart
+C934	BootCopyTableLoop
+C9A7	BootInitLevel
+CA1D	BootCheckController
+CA32	BootFrameCounter
+CA41	BootDrawSprite
+CA61	BootSetFlag
+CA68	BootSelectTable
+CA80	BootCopyTable
+CA97	BootSetPaletteBlock
+CAF3	BootInitPpu
+CB68	ActorGridClear
+CB6C	ActorGridClear_Loop
+CB82	ActorGridLookup
+CB99	ActorGridRead
+CBAD	ActorGridStart
+CBDC	ActorGridClamp
+CBE5	ActorGridInit
+CBF9	ActorGridFill
+CC11	TaskScheduler
+CC3D	TaskScheduler_Tick
+CC56	TaskScheduler_Count
+CC5C	TaskScheduler_Step
+CC71	TaskScheduler_Scan
+CC73	TaskScheduler_ScanLoop
+CC8B	TaskScheduler_Button
+CC90	TaskScheduler_Next
+CCA5	TaskScheduler_Restart
+CCA8	TaskScheduler_Accept
+CCB1	DispatchTask2
+CCB8	DispatchTask2_Build
+CCE5	TaskScheduler_Return
+CCEE	TaskScheduler_Select
+CD07	TaskScheduler_Compare
+CD18	TaskScheduler_Compare_Loop
+CD23	TaskScheduler_Compare_Loop2
+CD24	TaskScheduler_Return2
+CD27	TaskScheduler_Check
+CD43	TaskScheduler_Check2
+CD72	TaskScheduler_Return3
+CD75	TaskScheduler_SetPointer
+CD80	TaskScheduler_Wait
+CD85	TaskScheduler_Wait2
+CD8A	TaskScheduler_Wait3
+CDA4	TaskScheduler_Finish
+CDAC	TaskScheduler_Advance
+CDBD	TaskScheduler_Return4
+CDC0	TaskScheduler_Start
+CDDC	TaskScheduler_Place
+CE14	TaskScheduler_CursorNext
+CE17	TaskScheduler_Return5
+CE1A	TaskScheduler_Move
+CE22	TaskScheduler_MoveStep
+CE32	TaskScheduler_Return6
+CE35	TaskScheduler_Turn
+CE54	TaskScheduler_TurnStep
+CE5B	TaskScheduler_Return7
+CE5E	TaskScheduler_Move2
+CE66	TaskScheduler_Move2Step
+CE78	TaskScheduler_Return8
+CE7B	TaskScheduler_Turn2
+CE96	TaskScheduler_Turn2Step
+CE9D	TaskScheduler_Return9
+CEA0	ActorPositionLookup
+CEA8	ActorPositionLookup_Entry
+CED3	TaskScheduler_Return10
+CED6	ActorGridRebuild
+CEE0	ActorGridRebuild_Row
+CEEB	ActorGridRebuild_Cell
+CEF6	ActorGridRebuild_Next
+CF02	ActorGridRebuild_NextRow
+CF0E	ActorGridRebuild_Column
+CF10	ActorGridRebuild_ColumnStart
+CF14	ActorGridRebuild_Slot
+CF29	ActorGridRebuild_Copy
+CF35	ActorGridRebuild_SlotEnd
+CF55	ActorGridRebuild_Column2
+CF67	ActorGridRebuild_Column2Loop
+CF74	ActorGridRebuild_Copy2
+CF90	ActorGridRebuild_Copy2End
+CF98	ActorGridRebuild_Column2End
+CFC4	ActorGridRebuild_End
+CFC7	ActorGridNext
+CFFA	ActorGridNext_Reset
+CFFF	ActorGridNext_Start
+D020	ActorGridNext_Start_Loop
+D02A	ActorSearch
+D036	ActorSearch_Row
+D03D	ActorSearch_Slot
+D04A	ActorSearch_Match
+D074	ActorSearch_Check
+D085	ActorSearch_NotFound
+D087	ActorSearch_Restore
+D0A0	ActorSearch_Restore2
+D0AC	ActorSearch_Restore3
+D0AD	ActorSearch_Empty
+D0B6	ActorSearch_Restore4
+D0B8	ActorSearch_Next
+D0C3	ActorSearch_Done
+D0D3	ActorPositionTest
+D0DF	ActorPositionTest_Loop
+D0F5	ActorPositionTest_Loop_Loop
+D0F8	ActorPositionTest_Step
+D105	ActorPositionTest_End
+D10D	ActorPositionTest_Match
+D134	ActorPositionTest_Blocked
+D13C	ActorPositionTest_Taken
+D146	ActorPositionTest_Compare
+D15B	ActorPositionTest_Blocked2
+D15E	ActorPositionTest_Compare2
+D16A	ActorPositionTest_Compare3
+D185	ActorPositionTest_Next
+D190	ActorPositionTest_Done
+D193	RandomByte
+D1B2	DrawActorRow
+D1BB	DrawActorRow_Setup
+D1D7	DrawActorRow_Copy
+D1EC	DrawScore
+D1FD	DrawLifeCount
+D20E	DrawLevelNumber
+D21C	DrawTileRow
+D227	DrawTileRow_Loop
+D237	DrawTileRow_Digit
+D23A	DrawTileRow_Store
+D248	DecimalSplit
+D24A	DecimalSplit_Hundreds
+D253	DecimalSplit_Tens
+D257	DecimalSplit_Units
+D260	DecimalSplit_Done
+D265	DrawActorSprite
+D27F	DrawActorSprite_Setup
+D2A0	OamShadowClear
+D2A4	OamShadowClear_Loop
+D2BF	ActorGridOffset
+D2ED	ActorGridOffset_Copy
+D3A1	RandomWithinRange
+D3B5	RandomWithinRange_Out
+D3B7	ActorSpriteSetup
+D3BB	ActorSpriteSetup_Offset
+D41D	ActorSpriteSetup_State
+D424	ActorSpriteSetup_Pos
+D42E	ActorSpriteSetup_Next
+D43E	ActorSpriteSetup_Draw
+D45A	OamShadowClear2
+D45E	OamShadowClear2_Loop
+D476	OamShadowClear3
+D47F	OamShadowClear3_Loop
+D488	ActorSpriteSetup_Offset2
+D4B7	OamShadowClear4
+D4BB	OamShadowClear4_Loop
+D4C5	ActorInitFromTable
+D50A	ActorUpdate
+D510	ActorUpdate_Loop
+D512	ActorUpdate_Slot
+D520	ActorUpdate_Timer
+D530	ActorUpdate_Move
+D54A	ActorUpdate_Next
+D555	ActorUpdate_Done
+D56B	ActorUpdate_Anim
+D57A	ActorUpdate_AnimIndex
+D59A	ActorUpdate_Sprite
+D5AD	ActorUpdate_SpritePos
+D5CA	ActorUpdate_NextSprite
+D632	ActorSpawn
+D63B	ActorSpawn_Setup
+D655	ActorSpawn_Start
+D66D	ActorSpawn_Copy
+D679	ActorSpawn_CopyLoop
+D6AC	ActorGridShift
+D6B2	ActorGridShift_Row
+D6BB	ActorGridShift_Scan
+D6C9	ActorGridShift_Next
+D6D6	ActorGridShift_Dst
+D6E7	ActorGridShift_Copy
+D6F6	ActorGridShift_Copy_Loop
+D6FD	ActorGridShift_Copy2
+D720	ActorGridShift_End
+D72C	ActorGridShift_Done
+D72E	NmiHandler
+D78A	NmiHandler_Body
+D793	NmiHandler_Epilogue
+D79D	NmiHandler_Number
+D79F	NmiHandler_NumberLoop
+D7A8	NmiHandler_NumberDigit
+D7B6	WriteSoundRegister
+D7C5	WriteSoundRegister_Loop
+D7D7	SoundTableEntry
+D7E3	IrqHandler
+D7EB	ColdStartAlternate
+DE9A	SoundInit
+DEA9	SoundInit_Copy
+DECB	SoundPlayEffect
+DEFF	SoundClearVoices
+DF0E	SoundStopAll
+DF14	SoundStopAll_Loop
+DF29	SoundClearVoices_Loop
+DF80	SoundTick
+DF89	PlaySoundEffectFromSlot
+DF8E	SoundTick_Voice
+DF9A	SoundTick_Next
+DFA1	SoundTick_Command
+DFAC	SoundTick_Command2
+DFB5	SoundTick_Command3
+DFBF	SoundTick_Command4
+DFD5	SoundTick_Sample
+DFF4	SoundTick_Volume
+E00C	SoundTick_Volume2
+E017	SoundTick_VolumeLoop
+E029	SoundTick_Envelope
+E04B	SoundPlayer
+E057	SoundPlayer_Reset
+E05E	SoundPlayer_Command
+E069	SoundPlayer_Command2
+E072	SoundPlayer_Command3
+E07C	SoundPlayer_Command4
+E099	SoundPlayer_Volume
+E0B1	SoundPlayer_Volume2
+E0BC	SoundPlayer_VolumeLoop
+E0CE	SoundPlayer_Envelope
+E0F0	SoundPlayer2
+E0FC	SoundPlayer2_Reset
+E103	SoundPlayer2_Command
+E10E	SoundPlayer2_Command2
+E117	SoundPlayer2_Command3
+E121	SoundPlayer2_Command4
+E13E	SoundPlayer2_Volume
+E156	SoundPlayer2_Volume2
+E161	SoundPlayer2_VolumeLoop
+E173	SoundPlayer2_Envelope
+E195	SoundPlayer3
+E1A1	SoundPlayer3_Reset
+E1A8	SoundPlayer3_Command
+E1B7	SoundPlayer3_Command2
+E1D4	SoundPlayer3_Sample
+E1E9	SoundPlayer3_Envelope
+E1FB	SoundPlayer3_Write
+E20B	SoundPlayer3_WriteLoop
+E215	SoundPlayer3_Voice
+E220	SoundPlayer3_VoiceLoop
+E226	SoundPlayer3_VoiceLoop_OnCarryClear
+E230	SoundPlayer3_Voice2
+E236	SoundPlayer3_Voice2Loop
+E240	SoundPlayer3_Decay
+E249	SoundPlayer3_Decay2
+E24F	SoundPlayer3_Decay2Loop
+E259	SoundPlayer3_Done
+E25A	SoundVoiceIndexAdvance
+E260	SoundVoiceIndexAdvance_End
+E261	SoundVoiceIndexAdvance2
+E267	SoundVoiceIndexAdvance2_End
+E268	SoundVoiceIndexAdvance3
+E26E	SoundVoiceIndexAdvance3_End
+E26F	SoundVoiceIndexAdvance4
+E275	SoundVoiceIndexAdvance4_End
+ED6E	SampleTableLookup
+EDB7	SampleTableLookup_OnNonzero
+F891	SampleTableRead
+F894	SampleTableRead2
+F897	SampleTableRead3
+F89A	SampleTableNext
+F8A2	SampleTableNext_OnNonzero
+F8AD	SampleTableNext_Loop
+F8B2	SampleTableNext_Loop2
+F8BC	SampleTableNext_Loop3
+F8C0	SampleTableNext_Loop4
+F8C4	SampleTableNext_OnZero
+F8C5	SampleTableNext_Loop5
+F8D8	SampleTableNext_Loop6
+F8DD	SampleTableNext_OnNegative
+F8EF	SampleTableEnd
+F908	SampleTableEnd_OnNonzero
+F914	SampleTableEnd_Loop
+F922	SampleTableEnd_Loop2
+F929	SampleTableEnd_Loop3
+F93C	SampleTableEnd_Loop4
+F941	SampleTableCopy
+F942	SampleDecode
+F951	SampleTableCopy2
+F959	SampleTableCopy2_Loop
+FF00	Reset
+FF2F	Reset_Loop
+FF3E	BootChainEntry
+FF49	BootPokeMapperUnlock
+FF4C	BootUnlockDelay
+FF4E	BootUnlockDelay_OnNonzero
+FF50	BootUnlockDelay_OnNonzero2
+FF57	BootCheckStackBytes
+FF67	BootCheckStackBytes_Fail
+FF69	BootSeedStackBytes
+FF74	ClearCheckerBytes

NROM/Pyramid (U) (Sachen)/symbols.inc

@@ -0,0 +1,108 @@
+; =============================================================================
+; Nintendo Entertainment System hardware symbols
+; =============================================================================
+
+; -----------------------------------------------------------------------------
+; PPU registers
+; -----------------------------------------------------------------------------
+
+PPUCTRL             = $2000
+PPUMASK             = $2001
+PPUSTATUS           = $2002
+OAMADDR             = $2003
+OAMDATA             = $2004
+PPUSCROLL           = $2005
+PPUADDR             = $2006
+PPUDATA             = $2007
+
+OAMDMA              = $4014
+
+; -----------------------------------------------------------------------------
+; Controller ports
+;
+; $4016:
+;   Write: controller strobe
+;   Read:  controller port 1
+;
+; $4017:
+;   Read:  controller port 2
+;   Write: APU frame counter
+; -----------------------------------------------------------------------------
+
+JOY1                = $4016
+JOY2                = $4017
+
+; -----------------------------------------------------------------------------
+; APU pulse channel 1
+; -----------------------------------------------------------------------------
+
+APUPULSE1CTRL       = $4000
+APUPULSE1SWEEP      = $4001
+APUPULSE1TIMERLO    = $4002
+APUPULSE1TIMERHI    = $4003
+
+; -----------------------------------------------------------------------------
+; APU pulse channel 2
+; -----------------------------------------------------------------------------
+
+APUPULSE2CTRL       = $4004
+APUPULSE2SWEEP      = $4005
+APUPULSE2TIMERLO    = $4006
+APUPULSE2TIMERHI    = $4007
+
+; -----------------------------------------------------------------------------
+; APU triangle channel
+; -----------------------------------------------------------------------------
+
+APUTRIANGLECTRL     = $4008
+APUTRIANGLETIMERLO  = $400A
+APUTRIANGLETIMERHI  = $400B
+
+; -----------------------------------------------------------------------------
+; APU noise channel
+; -----------------------------------------------------------------------------
+
+APUNOISECTRL        = $400C
+APUNOISEPERIOD      = $400E
+APUNOISELENGTH      = $400F
+
+; -----------------------------------------------------------------------------
+; APU DMC channel
+; -----------------------------------------------------------------------------
+
+APUDMCCTRL          = $4010
+APUDMCDIRECT        = $4011
+APUDMCADDR          = $4012
+APUDMCLENGTH        = $4013
+
+; -----------------------------------------------------------------------------
+; APU status and frame counter
+;
+; $4015:
+;   Write: enable or disable the five APU channels
+;   Read:  channel and interrupt status
+;
+; $4017:
+;   Write: APU frame-counter mode and IRQ inhibit
+;   Read:  controller port 2
+; -----------------------------------------------------------------------------
+
+APUSTATUS           = $4015
+APUFRAMECOUNTER     = $4017
+
+; -----------------------------------------------------------------------------
+; Controller masks
+; -----------------------------------------------------------------------------
+
+PAD_RIGHT           = $01
+PAD_LEFT            = $02
+PAD_DOWN            = $04
+PAD_UP              = $08
+PAD_START           = $10
+PAD_SELECT          = $20
+PAD_B               = $40
+PAD_A               = $80
+
+PAD_HORIZONTAL      = PAD_LEFT | PAD_RIGHT
+PAD_VERTICAL        = PAD_UP | PAD_DOWN
+PAD_DPAD            = PAD_HORIZONTAL | PAD_VERTICAL

NROM/Pyramid (U) (Sachen)/zp_aliases.inc

@@ -0,0 +1,86 @@
+; ---------------------------------------------------------------------------
+; Semantic zero-page aliases (Pass 3)
+;
+; Every alias below was read out of this dump's own code.  The neutral ZpXX
+; name stays on the same line so the file keeps both readings.
+;
+; $02/$03   the 16-bit pointer to the command script: every routine that
+;            reads the script uses (Zp02),y, and AdvanceScriptPointer at
+;            $C1D0 increments the pair
+; $04       the command-list sync flag: set by FinishCommandList, waited
+;            on by FinishCommandList_Wait, tested by FlushVramCommandList
+; $05/$06   the VRAM write position: BuildVramAddress at $C198 folds
+;            $06 into the low byte and $05 into the high byte of a
+;            $2000-based address
+; $0A/$0B   the 16-bit frame counter: incremented once per NMI at $D791
+;            and used by AddToCounter as the value to wait for
+; $0C       the counter the three draw routines clear before they run
+; $27/$28   the pointer to the sound tick script
+; $29/$2A   the pointer to the first sound player's script
+; $2B/$2C   the pointer to the second sound player's script
+; $2D/$2E   the pointer to the third sound player's script
+; $3D/$3E   the JOY1/JOY2 shift registers, filled by ReadControllers
+; $43/$44   the sprite X and Y, written into OAM bytes 3 and 0
+; $4D/$4E/$4F  the 24-bit delta the sound engine adds and subtracts
+; $50       the per-voice wrap counter of the delta subtraction
+; ---------------------------------------------------------------------------
+ScriptPtrLo            = $02 ; semantic alias for Zp02 (the 16-bit command-script pointer)
+ScriptPtrHi            = $03 ; semantic alias for Zp03 (the high byte of that pointer)
+CommandListFlag        = $04 ; semantic alias for Zp04 (the command-list sync flag)
+VramPosHi              = $05 ; semantic alias for Zp05 (the high bits of the VRAM write position)
+VramPosLo              = $06 ; semantic alias for Zp06 (the low bits of the VRAM write position)
+FrameCounter           = $0A ; semantic alias for Zp0A (the 16-bit frame counter)
+FrameCounterHi         = $0B ; semantic alias for Zp0B (the high byte of the frame counter)
+DrawCounter            = $0C ; semantic alias for Zp0C (the counter the draw routines clear)
+SoundTickScriptLo      = $27 ; semantic alias for Zp27 (the sound tick script pointer)
+SoundTickScriptHi      = $28 ; semantic alias for Zp28 (the high byte of that pointer)
+SoundPlayer1ScriptLo   = $29 ; semantic alias for Zp29 (the first sound player's script pointer)
+SoundPlayer1ScriptHi   = $2A ; semantic alias for Zp2A (the high byte of that pointer)
+SoundPlayer2ScriptLo   = $2B ; semantic alias for Zp2B (the second sound player's script pointer)
+SoundPlayer2ScriptHi   = $2C ; semantic alias for Zp2C (the high byte of that pointer)
+SoundPlayer3ScriptLo   = $2D ; semantic alias for Zp2D (the third sound player's script pointer)
+SoundPlayer3ScriptHi   = $2E ; semantic alias for Zp2E (the high byte of that pointer)
+Player1Input           = $3D ; semantic alias for Zp3D (the JOY1 shift register)
+Player2Input           = $3E ; semantic alias for Zp3E (the JOY2 shift register)
+SpriteX                = $43 ; semantic alias for Zp43 (the sprite X, OAM byte 3)
+SpriteY                = $44 ; semantic alias for Zp44 (the sprite Y, OAM byte 0)
+DeltaLo                = $4D ; semantic alias for Zp4D (the 24-bit sound delta)
+DeltaMid               = $4E ; semantic alias for Zp4E (the middle byte of the delta)
+DeltaHi                = $4F ; semantic alias for Zp4F (the high byte of the delta)
+DeltaWrapCount         = $50 ; semantic alias for Zp50 (the per-voice wrap counter)
+
+; ---------------------------------------------------------------------------
+; Slots that stay neutral, and why
+;
+; The aliases above are the ones whose role the ROM proves.  Every slot
+; below is listed with the reason it keeps its neutral ZpXX name: the role
+; is either only visible inside one routine, or the address is reused for
+; two different things, so a single name would be a guess.
+;
+; $00/$01   the two halves of a $20xx VRAM address in the boot and palette
+;           code, reused as plain scratch elsewhere
+; $07/$08   the boot region's frame and state counters
+; $09       one read, in a comparison that never leads anywhere
+; $0D/$0E   a 16-bit counter in one routine and a RAM pointer in another
+; $0F       a byte the sound player passes around
+; $11/$12   the envelope bytes of the sound tick
+; $13/$14   the envelope bytes of the first sound player
+; $15/$16   the envelope bytes of the second sound player
+; $17/$18   the envelope bytes of the third sound player
+; $19/$1A   the target bytes of the first sound player
+; $1B/$1C   the target bytes of the second and third sound players
+; $1F       a flag the sound player clears when it starts
+; $20/$21/$22  the "finished" flag of each of the three sound players
+; $23-$26   the four voices' envelope bytes, indexed by X
+; $2F-$32   the four voices' flag bytes, indexed by X
+; $33       the sound effect id and the "a voice is playing" flag
+; $34       a counter
+; $3F-$42   the 24-bit product accumulator of Multiply16
+; $45/$46   the general-purpose scratch of the shift and arithmetic helpers
+; $47       the carry byte of those helpers
+; $48/$49   the second and third operand slots of the delta helpers
+; $55       one read, as the seed of a delta
+; $80       the base of the indexed sound table
+; $AC       one comparison against a table byte
+; $D0-$DE   the sound engine's per-voice working bytes
+; ---------------------------------------------------------------------------