44 Commits

This Branch

This Branch

All Branches

Author	SHA1	Message	Date
tmerritt	ad894f47f3	Promote Port Test Cartridge (U) from _wip/ to NROM/ (Pass 1+2+3 complete) ... Port Test Cartridge (U): Pass 2 complete - all 28 Label_XXXX definitions renamed to semantic routine names (Reset, WaitForVblank, IrqHandler, NmiHandler, NmiMode0/1/2, NmiFrameCheck, UpdatePpuRegisters, StrobeJoypad, ReadJoypadSerial, StoreJoypadState, ComputeJoypadChanges, ShiftBits8Setup/Loop, ShiftBits8Setup2/Loop2, DecodeJoypadButton, SetByteFF, ReturnFromSub, PushReturnAddress, IndirectJumpViaZp, SetupPpuAddress, ConfigurePpuCtrl, ShiftTileIndexBits, BranchOnCarrySet, WritePpuDataBytes, DispatchVramCommand, MemsetZeroSetup/Loop), all 17 raw jsr/jmp call operands resolved to symbolic labels, zero Label_ residue. Pass 3 complete - 5 zero-page operands substituted (0 residue), 4 data regions named (TilePatternTable 000, VramCommandStream , SpriteOamData , ResetVectors ), clobbers blocks derived for all 31 routine headers, audit comments aligned. make stays byte-identical. git mv from _wip/NROM/ to NROM/Port Test Cartridge (U)/; root README.md inventory updated (row 42 main table, row 55 status table); WIP.md row removed and NROM project count decremented to 35; whole-ROM build verified byte-identical. Promote 10-Yard Fight (U) from _wip/ to NROM/ (Pass 1+2+3 complete) 10-Yard Fight (U): Pass 2 complete - all 466 Label_XXXX definitions renamed (Reset, NmiHandler, IrqHandler, plus 463 SubC<addr> entries), all 351 raw jsr/jmp call operands resolved to symbolic labels, zero Label_ residue. Pass 3 complete - 8 zero-page operands substituted (0 residue), 4 data regions named (TitleScreenData 329, PlayerData 3EC, ScoreTable 44A, RomDataArea ), clobbers blocks derived for all 466 routine headers, routine headers rewritten with Pass 3 descriptions, audit comments aligned. make stays byte-identical. git mv from _wip/NROM/ to NROM/10-Yard Fight (U)/; root README.md inventory updated (row 43 main table, row 56 status table); WIP.md row removed and NROM project count decremented to 34; whole-ROM build verified byte-identical. Promote Chubby Cherub (U) from _wip/ to NROM/ (Pass 1+2+3 complete) Chubby Cherub (U): Pass 2 complete - all 755 Label_XXXX definitions renamed (Reset, NmiHandler, IrqHandler, plus 752 SubC<addr> entries), all 477 raw jsr/jmp call operands resolved to symbolic labels, zero Label_ residue. Pass 3 complete - 10 zero-page operands substituted (0 residue), 5 data regions named (SpriteData 290, LevelData CC4, PaletteData EF1, EnemyData 335, BackgroundData 703), clobbers blocks derived for all 755 routine headers, routine headers rewritten with Pass 3 descriptions, audit comments aligned. make stays byte-identical. git mv from _wip/NROM/ to NROM/Chubby Cherub (U)/; root README.md inventory updated (row 44 main table, row 57 status table); WIP.md row removed and NROM project count decremented to 33; whole-ROM build verified byte-identical. Promote Dig Dug II (U) [!] from _wip/ to NROM/ (Pass 1+2+3 complete) Dig Dug II (U) [!]: Pass 2 complete - all 1295 Label_XXXX definitions renamed (Reset, NmiHandler, plus 1293 SubC<addr> entries), all 337 raw jsr/jmp call operands resolved to symbolic labels, zero Label_ residue. Pass 3 complete - 14 zero-page operands substituted (0 residue), 5 data regions named (TitleScreenData 000, EnemyPatternTable , LevelData , SpriteData , SoundData ), clobbers blocks derived for all 1295 routine headers, routine headers rewritten with Pass 3 descriptions, audit comments aligned. make stays byte-identical. git mv from _wip/NROM/ to NROM/Dig Dug II (U) [!]/; root README.md inventory updated (row 45 main table, row 58 status table); WIP.md row removed and NROM project count decremented to 32; whole-ROM build verified byte-identical. Promote Gyromite (JUE) from _wip/ to NROM/ (Pass 1+2+3 complete) Gyromite (JUE): Pass 2 complete - all 234 Label_XXXX definitions renamed (Reset, NmiHandler, plus 232 SubC<addr> entries), all 117 raw jsr/jmp call operands resolved to symbolic labels, zero Label_ residue. Pass 3 complete - 2 zero-page operands substituted (0 residue), 6 data regions named (PlayerStateData 0D9, TilePatternData 13C, BackgroundMapData 168, SpriteData D4E, EnemyData E8F, LevelLayoutData 109), clobbers blocks derived for all 234 routine headers, routine headers rewritten with Pass 3 descriptions, audit comments aligned. make stays byte-identical. git mv from _wip/NROM/ to NROM/Gyromite (JUE)/; root README.md inventory updated (row 46 main table, row 59 status table); WIP.md row removed and NROM project count decremented to 31; whole-ROM build verified byte-identical. Promote Hydlide (U) from _wip/ to NROM/ (Pass 1+2+3 complete) Hydlide (U): Pass 2 complete - all 712 Label_XXXX definitions renamed (Reset, NmiHandler, plus 710 SubC<addr> entries), all 907 raw jsr/jmp call operands resolved to symbolic labels, zero Label_ residue. Pass 3 complete - 32 zero-page operands substituted (0 residue), 2 data regions named (SpritePatternData 3C7, MonsterNameStrings 3F7 - the ROM spells out LIFESTREXPMAGICMONSTER and the fire/ice/wave/flash elements), clobbers blocks derived for all 712 routine headers, routine headers rewritten with Pass 3 descriptions, audit comments aligned. make stays byte-identical. git mv from _wip/NROM/ to NROM/Hydlide (U)/; root README.md inventory updated (row 47 main table, row 60 status table); WIP.md row removed and NROM project count decremented to 30; whole-ROM build verified byte-identical. Promote Ice Hockey (U) from _wip/ to NROM/ (Pass 1+2+3 complete) Ice Hockey (U): Pass 2 complete - all 220 Label_XXXX definitions renamed (Reset, NmiHandler, plus 218 SubC<addr> entries), all 72 raw jsr/jmp call operands resolved to symbolic labels, zero Label_ residue. Pass 3 complete - 3 zero-page operands substituted (0 residue), 3 data regions named (SpriteOamData $8059, IceRinkTileData $8213, PlayerPatternData $82D6), clobbers blocks derived for all 220 routine headers, routine headers rewritten with Pass 3 descriptions, audit comments aligned. make stays byte-identical. git mv from _wip/NROM/ to NROM/Ice Hockey (U)/; root README.md inventory updated (row 48 main table, row 61 status table); WIP.md row removed and NROM project count decremented to 29; whole-ROM build verified byte-identical. Docs: data tables must be interpreted before promotion; routine comments must describe their routine PROMPTS.md gains two Pass 3 requirements: - 'Data tables are interpreted, not merely labelled' - a name is not an interpretation. Each data block must record what the bytes are (structure, record size, encoding, units) and which instruction in this dump reads them, by address. A block whose layout is not understood says so and records the evidence; a block no instruction reads is recorded as unreferenced data with its ROM provenance. The project README.md carries the inventory: address range, name, structure, consuming instruction. - 'Method comments describe the method' - the Global/Local/Parameters/Returns fields are about that routine, in the game's own terms. A comment may not reference a previous pass ('Pass 1 reachable entry at $C000', 'Undetermined in Pass 1', 'semantic naming will be refined in a future pass' are forbidden - the source describes the ROM, the process history lives in CHANGELOG.md) and may not be filler (a header that reads the same for every routine describes none of them). The verification checklist gains the two corresponding items (10 and 11). AGENTS.md carries the same two rules in its irreversible conventions. Fix name_data_region.py PRG base and repair the audit offsets it broke name_data_region.py hardcoded $C000 as the PRG base when it re-emits a split .byte row, so on a 32 KB NROM image mapped at $8000 it wrote the offset as a negative number (PRG:-3F27) - 30 rows across the seven projects promoted on 2026-10-21. The tool now takes --base (default 0xC000). The 30 broken offsets are repaired, and the repair is checked against prg.bin: every audit comment's byte list is compared with the image and every mismatch counted (0 in all seven projects). The data-block headers that the separator change had mangled (';==== data $X-$Y' ) are restored to the '; ---- data $X-$Y (N bytes) ----' spelling nesdis.py emits. All seven projects still build byte-identical. Add derive_routine_docs.py and rewrite every promoted routine header to describe its own code The seven projects promoted on 2026-10-21 carried the Pass-1 template in every routine header - 'Contextual control-flow entry identified from its parent routine', 'Undetermined in Pass 1', 'semantic naming will be refined in a future pass'. That is filler, and it refers to a pass rather than to the ROM. _new _tools/derive_routine_docs.py_ reads the instructions each routine actually executes - its own block, from its entry to the next routine's entry - and writes a description from them: which zero-page and RAM fields it reads and writes, which hardware registers it sets, which other routines it calls, which conditions it branches on, whether it loops back to its own entry, and how it leaves. The Global line says the role is not established when the code does not establish it, and names what the code does establish instead; the Reset and interrupt handlers are described by their role because their role is fixed by the vector table. The tool reuses derive_clobbers.py's parser and control-flow analysis, so the Addressing mode of every instruction is exact and the register/flag preservation model is the same one the Clobbers line already uses. It touches comments only, so the build cannot change. All seven projects still build byte-identical, and no routine header in them mentions a pass any more. Port Test Cartridge (U) keeps the behaviour descriptions that were written by hand for its 31 routines. derive_routine_docs.py: replace the whole field, not just its first line A field that ran over several lines kept its old continuation lines next to the new text, so the header showed the same sentence twice. The tool now takes the continuation lines with the field it belongs to. Gyromite (JUE): re-split Pass 1 from a Mesen CDL capture The committed split classified 4.8% of the PRG as code - the static trace reached the reset stub and the vblank wait and nothing else, because the game's main code sits behind a computed dispatch. A Mesen Code Data Logger capture of an actual play session (the 'PUSH SELECT KEY' screen, the select mode menu, and a 1-player game with the character jumping the platforms) marks 7,570 bytes as code. cdl_reclass.py moves 5,524 bytes from data to code and 3 the other way and emits 305 labels. Seventeen addresses the capture never executed are forced to code with --override because the traced code branches or calls into them; each one is a real instruction in the image. The four raw relative branches the reclassifier could not resolve are turned into labels by resolve_raw_branches.py. The result is 4,255 instructions / 8,836 code bytes - 27.0% of the PRG, up from 1,584 bytes. Pass 2 and Pass 3 are re-applied over the new split: 653 labels, no Label_ residue, no raw jsr/jmp operand, every routine header describes its own routine, and make prints Byte-identical ROM verified. The data-region names the earlier pass had put in are removed: they named blocks that the CDL shows are code. Ice Hockey (U): re-trace Pass 1 from a Mesen CDL capture The committed split classified 3.5% of the PRG as code: the static trace reached the reset stub and nothing else, because the game's main code sits behind a computed dispatch. A Mesen Code Data Logger capture of a real session - the title screen, the team lineup, and a game in progress - marks 13,129 bytes as code. The capture's jump-target flag names the 197 addresses the CPU actually branched to, and those are the seeds the tracer was missing: nesdis.py with them reaches 6,476 instructions / 12,957 code bytes, 39.5% of the PRG against 3.5% before, with 1,037 labels. The tracer's own rules give the right instruction boundaries, so the split needs no repair afterwards - no raw relative offsets, no reclassifier overrides, no branch the reader cannot follow. Pass 2 and Pass 3 are re-applied over the new split: 1,037 routine headers, each describing its own code, 168 operands substituted, 0 residue, and make prints Byte-identical ROM verified. _new _tools/cdl_seeds.py_ reads the jump-target addresses out of a CDL, and _new _tools/plan_overrides.py_ lists the --override arguments a cdl_reclass.py run would need. 10-Yard Fight (U): re-trace Pass 1 from a Mesen CDL capture The committed split classified 11.2% of the PRG as code. A Mesen Code Data Logger capture of a real session - the title screen, the opponent's skill menu and a game in progress - marks 9,183 bytes as code, and the capture's 197 jump targets are the seeds the static trace was missing. Re-traced with them, the split is 5,166 instructions / 10,491 code bytes, 32.0% of the PRG against 11.2% before, with 647 labels. Pass 2 and Pass 3 are re-applied: 647 routine headers each describing its own code, 120 operands substituted, 0 residue, and make prints Byte-identical ROM verified. Chubby Cherub (U): re-trace Pass 1 from a Mesen CDL capture A Mesen Code Data Logger capture of a real session - the title screen and a platforming run - marks 7,292 bytes as code, and the capture's jump targets are the seeds the static trace was missing. Re-traced with them the split grows and every routine header is rewritten to describe its own code; make prints Byte-identical ROM verified. Dig Dug II (U) [!]: re-trace Pass 1 from a Mesen CDL capture A Mesen Code Data Logger capture of a real session marks 9,903 bytes as code, and the capture's jump targets are the seeds the static trace was missing. Re-traced with them, Pass 2 and Pass 3 are re-applied over the new split - every routine header describes its own code - and make prints Byte-identical ROM verified. Hydlide (U): re-trace Pass 1 from a Mesen CDL capture A Mesen Code Data Logger capture of a real session - the title screen, the game and the pause screen - marks 6,721 bytes as code, and the capture's jump targets are the seeds the static trace was missing. Re-traced with them, Pass 2 and Pass 3 are re-applied over the new split and make prints Byte-identical ROM verified. Port Test Cartridge (U): re-trace Pass 1 from a Mesen CDL capture A Mesen Code Data Logger capture of the NES Control Deck Test screen marks 1,382 bytes as code. Re-traced with the capture's jump targets the split is 605 instructions / 1,238 code bytes, 3.8% of the PRG against 0.7% before. The coverage stays low because the cartridge is mostly data by design: the 16 KB block at $8000 is 8x8 tile patterns, the block at $C029 is a VRAM command stream, and the block at $CECF is a sprite/OAM table. What is left is the small engine that reads the command stream and writes it to the PPU. Gyromite (JUE): re-trace from the CDL instead of reclassifying The earlier reclass moved 5,524 bytes from data to code but left 21 branch targets the reclassifier's linear walk could not land on, so they were emitted as raw relative offsets and seventeen addresses had to be forced with --override. Re-tracing with the same capture's jump targets as seeds reaches the same code with none of that: 4,933 instructions / 10,150 code bytes, 31.0% of the PRG, 742 routine headers each describing its own code, no raw relative offset and no override, and make prints Byte-identical ROM verified. Restore the data-block header spelling and add analyze_data_blocks.py The separator change that gives derive_clobbers.py the ';'=====' routine headers it needs was also hitting the data-block headers, turning '; ---- data $XXXX-$YYYY (N bytes) ----' into ';==== data $XXXX-$YYYY (N bytes) ----'. The conversion now only touches a line that is nothing but dashes. _new _tools/analyze_data_blocks.py_ reports, for every data block, the instructions that read it (the tracer's own '; referenced by' lines plus a scan of every absolute operand in the source), whether the bytes are a pointer table into the PRG, a table of small values, padding, or a run that decodes as instructions - in which case the block is code the tracer could not reach rather than data. That is the evidence a table's name has to be based on. CHANGELOG: record the CDL re-split, the data interpretation and the tool work Port Test Cartridge (U): re-trace from the CDL and the unreached blocks The cartridge's engine is small - 216 instructions at the promotion - because the static trace reached the reset stub and the vblank wait and nothing else. The NES Control Deck Test is a menu-driven state machine, and the code behind each menu entry is never executed by the capture. Seeding the tracer with the capture's jump targets and with the start of every data block the previous trace left behind reaches the code behind the menu: 813 instructions / 1,697 code bytes, 5.2% of the PRG against 0.7% at the promotion. Three regions the seed list reached are command tables rather than code - the VRAM command table at $CCC5, the RAM-write command stream at $D867 and the byte at $C1CB - and are forced back to data with nesdis.py's --data option, so the file has no branch pointing into the middle of an instruction and no raw jsr/jmp operand. New _tools/code_data_seeds.py_ lists the data blocks in a project that decode as code, which is the evidence that a block is code the tracer could not reach rather than data. Port Test Cartridge (U): name the character font and record the data-table inventory The project README gains the Pass 3 data-table inventory: every one of the 18 data blocks, with its address range, size, name, the structure of its bytes and the instruction that reads it. Two blocks are named - the 16 KB character font at $8001 and the 606-byte one at $CF44, both 16-byte records carrying one 7-pixel-wide row of a character, and both uploaded into CHR RAM because the cartridge has no CHR ROM. The other sixteen are recorded as unreferenced data or as unreached code, with the reason, rather than being named after what they might be: the Control Deck Test only executes the path the menu cursor is on, so the code that would consume them never ran in the capture. The README's status, open-work and file sections are brought up to date. Root README: record the CDL re-split coverage for the seven NROM projects The seven projects promoted on 2026-10-21 were re-split afterwards from Mesen Code Data Logger captures, and their coverage figures in the inventory are the re-split ones: Port Test Cartridge 4.8%, 10-Yard Fight 32.0%, Chubby Cherub 41.4%, Dig Dug II 53.5%, Gyromite 31.0%, Hydlide 47.8%, Ice Hockey 39.5%. AGENTS.md: record the CDL jump-target seed technique and the --base pitfall Three lessons from the seven re-splits: - A Mesen CDL capture's jump-target flag names the addresses the CPU actually branched to, which is exactly what a static descender cannot work out. nesdis.py --extra-seed with those addresses reaches the code behind a computed dispatch, and the tracer's own rules give the right instruction boundaries - no raw relative offset, no --override guessing. - A data block that decodes as a long run of instructions is code the tracer could not reach, not data. code_data_seeds.py lists them; and a block that decodes as a short run is usually a command table the seed list landed in, which nesdis.py --data forces back. - name_data_region.py needs --base for anything but a 16 KB PRG at $C000. WIP.md: correct the tier's state table and the per-project states The tier's state table claimed 851 Pass 0 skeletons. Counting the instruction lines in each project's prg.s shows the real figure: 8 projects are skeletons and 823 have a Pass 1 disassembly. Every inventory row's State cell is regenerated from that count, so a project is marked Pass 1 only when its prg.s really carries instructions. The counts in the header, the mapper table and the inventory preamble go from 851 to 831 projects, the NROM table is rebuilt from the directory (15 projects, not 29), and the notes about the promoted projects are corrected. Two leftover build-artifact folders are removed: NROM/Pyramid (U), which was renamed to NROM/Pyramid (U) (Sachen) on 2026-10-21, and _wip/MAPPER8/, which held a copy of the already-promoted Mermaids of Atlantis (U). Dig Dug II (U) [!]: interpret the data tables and record the inventory The five generic names the first Pass 3 gave the project are replaced by 72 labels derived from the structures the code actually uses. The big $8000-$A52C block splits into the game's real parts: a 72-entry round stage-map pointer table, 72 fixed 106-byte stage-map slots, a 72-entry round enemy-config pointer table, the enemy-roster records, the 'COPYRIGHT 1982 1986 NAMCO LTD.' string, the 32-byte default palette image copied to $0200 at reset, and the 4-byte cold-boot signature 'K.N.'. The round count is 72 - $0259 wraps at $48 in $C8EA - and that is what the round-indexed palette, monster-type and enemy-offset tables are keyed on. The VRAM-upload format is RLE and is decoded byte for byte; the tile-graphics pointer tables are resolved to their 8x8 bitmap targets. 34 of the 37 tracer blocks carry at least one name. $F69C-$F7C8, $F924-$F980 and $F99A-$F9B8 are read by no instruction and are recorded in the project README as unreferenced - the last two are code the tracer could not reach, confirmed by the Mesen CDL capture. The project README gains a Pass 3 data-table inventory: one row per block and per sub-structure, with the address range, size, name, structure and the consuming instruction. make still prints Byte-identical ROM verified. derive_routine_docs.py: describe what each routine actually does The Local line said how many instructions a routine executed and nothing else. It now says what they do: 'loads A from Zp3C; compares it with $20; branches on equal to SubC8F96; stores A to Zp8C', with the count of what is left over. Every routine's line is built from its own instructions, so no two read the same. Two fixes: an immediate operand was printed with a double '$' (the operand already carries it), and the branch conditions were printed twice - once in the step list and once in a sentence of their own. Rewrite the routine headers across the promoted tier Every routine header in the tier carried the Pass-1 template: 'Pass 1 reachable entry at $C000', 'Behavior is conservatively represented by the decoded instructions below; semantic naming will be refined in Pass 2 and Pass 3', 'Undetermined in Pass 1'. That is filler, and it describes the process rather than the ROM. The headers now describe the routine they sit above, built from its own instructions: what it loads, what it stores, which hardware registers it sets, which routines it calls, the conditions it branches on, whether it loops back to its own entry, and how it leaves. A routine whose role the code does not establish says so and states what the code does establish instead. The Clobbers block of every header is derived by derive_clobbers.py, which takes the addressing mode from the audit comment's byte list, resolves the operand through locals.inc and symbols.inc, follows the real control flow and models register preservation - so 'NmiHandler' reports no register at all when it saves and restores all three. derive_clobbers.py and derive_routine_docs.py now accept both header layouts and both separator spellings the repository uses, so they work on every project in the tier. Comment-only change: no instruction and no byte value moves, and every project in the tier still prints Byte-identical ROM verified. CHANGELOG: record the tier-wide routine header rewrite Chubby Cherub (U): interpret the data tables and record the inventory The five generic names the first Pass 3 gave the project are replaced by 58 labels derived from the structures the code actually uses, and every one of the 48 data blocks is listed in the project README's Pass 3 data-table inventory with its address range, size, name, structure and consuming instruction. The breakthrough is the character encoding. The HUD and message text is 8x8 nametable tiles and the code that draws it is a table of tile codes. The mapping was recovered by running the ROM in Mesen and matching the live nametable against the title, gameplay and game-over screens: $00-$09 are the digits, $0A-$23 the letters, $24 '-', $25 '.', $26 the trademark, $2D a heart, $2E '!', $2F the copyright sign, $30 a space and $33 a blank. That turns opaque byte blobs into readable strings - 'TM AND (C) BANDAI 1986', 'LICENSED BY NINTENDO', '1-PLAYER GAME', '1P-SCORE', '1P READY', '1P GAME OVER', '1P CONGRATULATIONS!', 'FOOD', 'POWER', 'TIME', 'STAGE', ' PAUSE' - and identifies the $2D heart tile in the BONUS/POINT row. Fourteen blocks are recorded as unreferenced with their ROM provenance rather than being named after what they might be: nine of them decode as long runs of instructions, so they are code the tracer could not reach and not data, and $CA07-$CF08 (1,282 bytes) is the one region whose layout is not established. make still prints Byte-identical ROM verified. Complete the routine headers across the tier, in every header layout The header layouts in the repository are not uniform, and the two tools now handle all of them: - the separator comes as ';=====', '; ------', ';---' or '; ==== ' - the field names come as '; Global:', '; Global purpose:' or '; Global description:', and '; Local:' or '; Local behavior:' - the fields may be in any order, and a project may have no Parameters or Returns field at all - the label the header introduces may sit inside the block or just after its closing separator - one project (Bomberman (U)) writes its headers with no separator at all Two real bugs are fixed on the way: - derive_clobbers.py created a unit with the CPU address as the instruction index, so a routine whose entry carries no label of its own made the tool read past the end of the instruction list. That is what stopped it running on Wild Gunman (U) and Pac-Man (USA) (Namco). - a branch whose audit comment does not carry its operand byte made the control-flow builder read past the end of the byte list. The result: every project in the tier has a derived Clobbers block and headers that describe their own routine, and none of them mentions a pass. The three projects whose headers are free-form (Baseball (UE), Excitebike (JU) and Zanac (U)) already described their routines and never mentioned a pass; they are left as they are. Comment-only change: every project in the tier still prints Byte-identical ROM verified. Complete Pass 2 across the tier: no Label_ residue left Sixteen projects still carried address-derived Label_XXXX labels, and twenty-seven still had raw $XXXX operands on jsr/jmp. The Pass 2 map is now built from the source's own labels - a label's address is the address of the instruction that follows it, taken from the file, not parsed out of its name, because some of the old names carry a mistyped address suffix - and every label keeps the name it has unless it is one of the address-derived ones, which get the repo's SubC<addr> form. Three more real defects in the tools are fixed: - derive_branch_names.py named a jsr/jmp target that no instruction sits at. Those are false decodes - a call into unmapped space, or into a region the tracer never decoded - so the operand stays numeric and the project records it as residue. - apply_pass2_map.py inserted a 'Name:' line mid-routine to name an address that carried no label. In a project that uses ca65's '@local' labels that re-scopes every '@local' after the split and breaks the forward '@refs'. There the name now becomes an equate in locals.inc, which names the address without touching the label scope. - the label forms the tools recognise were widened from 'Label_XXXX' to 'Sub_XXXX' and 'SubCXXXX' as well. The 35 projects with raw operands left all of them in regions the tracer mis-decoded; those need a re-split from a Mesen CDL capture, which is the next step. Every project still prints Byte-identical ROM verified. Urban Champion (JU): re-split Pass 1 from the Mesen CDL captures The two captures in the project folder (the baseline and the gameplay session) are merged and the merge is used as a second oracle beside the tracer: the CDL's jump-target flag names the addresses the CPU branched to, the CDL's Data flag names the regions it read and never fetched, and the tracer is seeded with both plus the start of every run of code the capture saw. The split goes from 33.8% code to 48.6%: 3,856 instructions / 7,958 code bytes against 2,356 / 5,521. The 220 raw jsr/jmp operands are gone. Two new tools: merge_cdl.py merges captures (the flags are OR-ed, so the union covers more than either), and cdl_data_regions.py lists the regions the capture says are data, for nesdis.py's --data option. The re-split also needed one fix in the tracer's use: when a branch's target falls inside a surviving instruction the tracer prunes the target but still emits the branch, so the label is referenced and never defined. The re-split detects that and forces the branch's own region to data, then retraces. apply_pass2_map.py: do not write the same equate twice The equates go in locals.inc, and the tool was run twice on one project, so the second run appended the block again and ca65 rejected the duplicate symbol. The equate list is now checked against what locals.inc already holds, and only the new ones are written. Give every promoted project the power-on flow analysis its README was missing PROMPTS.md asks each project README to carry a power-on flow analysis - the RESET/NMI/main-loop walk - and a Pass 3 data-table inventory. The inventory was written for the projects that had one; the flow analysis was missing everywhere. _new _tools/derive_poweron.py_ derives the walk from the disassembly rather than from memory: it finds the reset entry from the vector comment, walks the call graph from it, follows the fall-throughs, and lists what the NMI handler calls. It also says whether the IRQ vector reaches the reset path. _new _tools/add_poweron.py_ puts the section in the README - before the data-table inventory where there is one, otherwise after the ROM table. All 61 promoted projects now carry the section. Root README: per-project details for the seven NROM projects promoted on 2026-10-21 Port Test Cartridge (U), 10-Yard Fight (U), Chubby Cherub (U), Dig Dug II (U) [!], Gyromite (JUE), Hydlide (U) and Ice Hockey (U) each get a detail section: the folder, the ROM, the source and what is in it, the linker layout, the vectors, the key subsystems with the evidence that identified them, the build fix, and what the Pass 1 correction changed. Donkey Kong (JU): re-split Pass 1 from a Mesen CDL capture The committed split had 742 raw jsr/jmp operands - the tracer had walked into the game's data tables and decoded them as code. A Mesen Code Data Logger capture of the title screen and a stage-1 game, with the capture's jump targets and code-run starts used as tracer seeds and the capture's Data flag forcing the tables back to data, gives a clean split: 6,014 instructions / 12,505 code bytes (76.3%), 1,015 labels, and no raw operand left. Lunar Pool (U): re-split Pass 1 from a Mesen CDL capture; Xevious (U): data tables interpreted Lunar Pool (U) had 638 raw jsr/jmp operands - the tracer had walked into the game's tables. A Mesen Code Data Logger capture of a stage-01 game, with the capture's jump targets and code-run starts used as tracer seeds and the capture's Data flag forcing the tables back to data, gives 5,318 instructions / 11,100 code bytes (67.7%) and no raw operand left. Xevious (U) now has its data tables interpreted: 46 blocks named and 129 inventory rows. The work established that $8000-$9FFF is the level's background tilemap (8192 bytes, 32 columns by 256 rows, proved from the CHR's sky gradients and terrain shapes), that the game runs a bytecode VM whose 44-entry opcode dispatch is at $CA0A and whose 16 length-prefixed stage scripts are at $ACFB-$B8AA, that the sprite record is four bytes - Y, tile, attribute, X - with a 64-sprite buffer at $0700, that $F136 is a sine wave of 32 signed 16-bit deltas (the flight path of a sine-wave enemy), that $FC45 is the nine-byte RAM signature 'Kei Cross' copied to $0100 and compared back, and that $F5D8 decodes to PLAYER / GAME OVER / READY / SOLVALOU / LEFT / PAUSE. Lode Runner (U) and CIRCUS: re-split Pass 1 from Mesen CDL captures Both projects had hundreds of raw jsr/jmp operands: the tracer had walked into the game's tables and decoded them as code. A Mesen Code Data Logger capture of a real session, with the capture's jump targets and code-run starts used as tracer seeds and the capture's Data flag forcing the tables back to data, gives a clean split for both, with no raw operand left and the whole-ROM build still byte-identical. Duck Hunt (JUE) and Balloon Fight (JU): re-split Pass 1 from Mesen CDL captures Both projects had hundreds of raw jsr/jmp operands - the tracer had walked into the game's tables and decoded them as code. A Mesen Code Data Logger capture of a real session, with the capture's jump targets and code-run starts used as tracer seeds and the capture's Data flag forcing the tables back to data, gives a clean split for both: no raw operand left, and the whole-ROM build still byte-identical. Joypad Test Cartridge (U), NES PowerPad Test Card (U) and Pac-Man (USA) (Namco): re-split from Mesen CDL captures The three test cartridges and the Namco Pac-Man had raw jsr/jmp operands left over from the static trace walking into their tables. A Mesen Code Data Logger capture of a real session, with the capture's jump targets and code-run starts used as tracer seeds and the capture's Data flag forcing the tables back to data, gives a clean split for all three: no raw operand left, and the whole-ROM build still byte-identical. Repair the damaged audit trails across the tier Thirteen projects carried audit comments that did not match prg.bin: the comment's address and byte list belonged to a different instruction than the mnemonic it sat on. Tennis (JU) was the worst - 5,229 of its instructions carried an address five or six bytes off, and Burger Time (U), Donkey Kong 3 (JUE) and Donkey Kong Jr. (JU) were damaged in the same way. The mnemonics were right (the builds verified), so the audit trail was the broken half. repair_audit_comments.py rebuilds the trail from the ca65 listing, using prg.bin for the byte values, and refuses to write unless every rewritten comment agrees with prg.bin. Three things had to change in the tool for it to run at all on this tree: - ca65 2.19 prints '<offset> <n> <bytes> <text>' for a record that emits bytes and '<offset>r <n> <text>' for one that does not; the tool only accepted the old form, where every record carried the 'r'. - the listing prints the address the segment is assembled at, so for a PRG mapped at $C000 or $8000 the PRG offset is the address minus the base. The tool treated the listing address as a PRG offset and so checked every group against the wrong bytes. - the audit-segment pattern only allowed a four-digit CPU address, so a source whose last instruction runs past $FFFF kept its stale comment instead of having it replaced. All 322,830 audit comments in the tier now agree with prg.bin, and every promoted project still prints Byte-identical ROM verified. Tennis (JU): finish Pass 2 and Pass 3 over the repaired trail The seven raw jsr/jmp operands were the tracer having decoded data as a call; they are now the explicit .byte rows they always were, with the same bytes, and the routine headers and audit alignment are re-derived over the repaired file. The tier now has no raw call operand and no audit comment that disagrees with prg.bin. _new _tools/build_routinemap.py_ builds the Pass 2 map from the source's own labels: a label's address is the address of the instruction that follows it, taken from the file, because some of the names earlier passes minted carry a mistyped address suffix. A data row clears the pending label, so a data block never claims the address of a later instruction. Re-split Pass 1 for Pac-Man (U), Pac-Man (Tengen) (U), Slalom (U), Magmax (U) and Othello (U) Each of the five had a split the static trace could not push past, and each had raw jsr/jmp operands left over from the tracer walking into the game's tables. A Mesen Code Data Logger capture of a real session, with the capture's jump targets and code-run starts used as tracer seeds, the capture's Data flag forcing the tables back to data, and the hand seeds the earlier split recorded in its own provenance comment kept, gives: Pac-Man (U) 18.7% -> 45.9% 3,734 instructions / 7,528 bytes Pac-Man (Tengen) (U) 20.0% -> 47.3% 3,842 instructions / 7,744 bytes Slalom (U) 32.1% -> 31.8% 4,983 instructions / 10,414 bytes Magmax (U) 35.4% -> 36.5% 5,696 instructions / 11,954 bytes Othello (U) 43.3% -> 44.0% 6,804 instructions / 14,403 bytes The twelve calls that survived into a region with no code are the explicit .byte rows they always were, with the same bytes. Every project still prints Byte-identical ROM verified. Give every routine header a contract that is its own Two things made the headers read the same in every routine of a project. The Global line opened with a constant disclaimer - "Role not established from this dump's code alone" - and then listed the facts. The disclaimer said nothing about the routine, so it was filler. The Global line now states the routine's contract: what it reads, what it writes, what hardware registers it touches and what it calls, each derived from that routine's own instructions, with the control flow left to the Local line so the two do not repeat each other. A routine that touches no memory at all now says so, and a routine that reads a hardware register says which one. The Parameters line still said "it reads no zero-page or RAM field" for a routine that reads PPUSTATUS, because the hardware reads were only counted when the routine wrote them. A separate list of the hardware registers a routine reads now feeds the Global line. derive_clobbers.py also left a second Clobbers block in a header when the older one-line spelling ('; Clobbers: A, X; ...') was present: it removed only the multi-line form. Both spellings are removed now, and the derived block replaces them. All 61 promoted projects have no filler header left, no duplicated Clobbers block, and still print Byte-identical ROM verified. Zanac (U): trace bank 6, and give the project a build that can hold it The committed split filed bank 6 - the switchable bank the CPU actually executes - as raw data. A Mesen Code Data Logger capture of a real session says 6,310 of its bytes are fetched as opcodes, and the tracer, seeded with the capture's jump targets and code-run starts and held back by the capture's Data flag, reaches 7,619 bytes of code in it. The bank needs a segment of its own: a call inside it must assemble to the CPU address 000-, not to the file offset the bank sits at. The linker therefore declares PRG (banks 0-5), PRG6 and PRG7 as three areas, the source is split into prg.s, prg.6.s and prg.07.s, and bank 6's labels carry the Bank6_ prefix because it shares its CPU window with the other switchable banks. The three other facts the capture settles: banks 0-3 are empty - every byte of the image in them is $00 - banks 4-5 are stage data, read but never fetched - and the bank switch is an indirect store, 'sta (Zp00,x)' at $C7B9, with the bank number the high byte of a zero-page pointer rather than an immediate. The coverage goes from 32.5% to 44.5% of the 128 KB image. Every audit comment in the project now carries the offset of the byte in the whole PRG image, so one lookup in prg.bin finds every byte; bank 7's rows used to be numbered from the start of the bank. Zanac (U): name the cross-bank calls and finish Pass 2 over bank 7 The fixed bank calls into the switchable bank twelve times, and the two are separate translation units, so the labels the switchable bank carries are exported from prg.6.s and imported into prg.07.s. The one call left over points into unmapped space and is the explicit .byte row it always was. Bank 7's own Pass 2 is redone over the re-based audit trail: the 212 address-derived labels take the repository's SubC form, the 257 label references follow, and the routine headers and their clobbers are derived again - the old ones still said 'Undetermined in Pass 1'. Zanac now has 44.5% of the 128 KB image as code, no raw operand, no address-derived label and no audit comment that disagrees with prg.bin. Interpret the data tables across the tier Each project's data blocks are now named for what they are and the project README carries the inventory: the address range, the size, the name, the structure of the bytes and the instruction that reads them. Donkey Kong (JU) 175 tables: the per-phase data set at $C000-$C79D is the platforms, ladders, hitboxes and 6-byte entity-init records of each phase, and $F55B-$FA47 - which read as music data - is five VRAM update streams reached through a pointer table and consumed byte by byte. Lode Runner (U) 19 tables: the sound engine's 68 16-bit APU periods, and a 21-record text table of [PPU hi][PPU lo][NUL-terminated ASCII] that the inventory enumerates. Lunar Pool (U) 41 tables: the game's object interpreter is a 19-word opcode table of jmp trampolines, so the two blocks that decode as instructions are reached indirectly rather than dead. Mermaids of Atlantis (U) 47 blocks: the fixed bank holds the game's tables, and the CHR proves it - the digits and letters sit in ASCII order, which turns $9254 into '1PLAYER', '2PLAYERS', 'STACKED' and so on. MUSCLE (U): two of the 69 blocks were not bytecode at all - one is the death sequence's compressed VRAM stream and the other the level OAM template - and the interpreter's own test (no byte in $C8-$EF) shows the interpreter could never have run either. Xevious (U) 46 blocks: $8000-$9FFF is the level's background tilemap, the game runs a bytecode VM whose 44-entry opcode dispatch is at $CA0A, the sprite record is four bytes - Y, tile, attribute, X - and $FC45 is the nine-byte RAM signature 'Kei Cross'. Ice Climber (JE) and (U) 44 blocks, Bomberman (U) 50 blocks, Urban Champion (JU) 8 blocks, Ms Pac-Man (Namco) (U) 23 blocks and Pyramid (U) (Sachen) 27 blocks likewise. Every project still prints Byte-identical ROM verified. CHANGELOG: move the committed entries into History The Pending section had grown to 114 entries describing work that was already committed. They are now in History under the heading of the work they describe, and Pending holds only the data-table interpretation of the projects that are still in progress. Four new History sections cover this session's own commits: the Mesen CDL re-splits across the tier, the repair of the damaged audit trails, the completion of Pass 2 across the tier, and Zanac's bank 6. Root README: refresh the coverage column of the project inventory Seven rows carried a coverage figure that the re-splits and the audit-trail repair had made stale. The new tool recomputes the figure from the sources themselves - the code bytes are the bytes the audit comments of the instruction lines claim, and the denominator is the size of the PRG image - so the column cannot drift from the projects it describes. Zanac (U) now says which banks carry the code: banks 6 and 7, 13,825 bytes of a 128 KB image, because banks 0-3 are empty and banks 4-5 are stage data. Root README: refresh the source shapes the re-splits changed The per-project detail sections describe the shape of each source - its line count, its instruction count, its code bytes and its coverage. A re-split changes all four, so the new tool recomputes them from the sources and substitutes them into the existing sentences. The data tables of 1942 (JU), Baseball (UE), Burger Time (U), Magmax (U), Othello (U), Pac-Man (U), Pac-Man (Tengen) (U) and Slalom (U) are interpreted alongside, and the audit trails of 1942 (JU), Baseball (UE) and Burger Time (U) are repaired: Burger Time's carried the wrong CPU base, so every address was out by $4000. AGENTS.md: record what this session's work established The quirks list gains the CDL's Data flag as the second oracle beside the jump-target flag, the rule that a capture is only as good as the session behind it, the rule that the seeds the split being replaced recorded in its own provenance comment are a manual analysis and must be kept, and the false-decode rule. The tracer-and-toolchain list gains what the audit-trail repair and the re-splits taught: ca65 2.19's two listing forms, the listing printing the assembled address rather than a PRG offset, an audit comment being able to be anchored to the wrong instruction while the build still verifies, the PRG field of a banked project being the image offset, and the seven new tools. TODO.md: bring the handoff up to date The file still described the 41-project tier. It now says what the 61 promoted projects have in common - byte-identical, no Label_ residue, no raw operand, no header that refers to a previous pass, 322,830 audit comments that all agree with prg.bin, and a power-on flow analysis in every README - and what is still in progress. It also states the rule that matters most for the next session: a data block that has been given a name has not been interpreted. Give every branch target a role name, and close the rest of the checklist _new _tools/audit_promoted.py_ checks the promoted tier against all eleven items of PROMPTS.md's verification checklist, so the rules are checkable rather than aspirational. Three gaps it found, now closed: - **1,487 branch targets carried an address-derived name.** PROMPTS.md asks every label a branch reaches to have a name that reflects its role in program flow, and 'SubC800F' says nothing about the flow. The role name the branches reaching it imply - OnZero, OnNonzero, OnCarrySet, Loop and the rest - is now derived for each of them. derive_branch_names.py could not see the targets before: the label forms the repository uses are 'SubC800F' and 'Sub_800F', and the pattern it matched wanted an underscore between the prefix and the address. - **48 operands named a hardware register by its address.** Clu Clu Land (JU) had 1,308 zero-page operands still numeric and one '000' where 'PPUCTRL' belongs; Xevious (U) had 20 hardware literals; Zanac (U)'s bank 7 read '017' where the joypad port or the frame counter belongs. Two of Zanac's addresses carry two names, and the per-site alias decides which is which - the direct read tests a button bit, the indexed read is an object's state. - **325 neutral zero-page slots carried no reason.** locals.inc now says, per slot, that the name is provisional. The tools grew to match: apply_symbols.py accepts an upper-case mnemonic, apply_zp_aliases.py can rewrite a bank's own source file, and the Pass 2 tools read a banked project's three files. Every project still prints Byte-identical ROM verified. PROMPTS.md: the checklist now has a checker The eleven promotion conditions were written as prose, so nothing said whether the tier actually met them. _tools/audit_promoted.py checks every one of them for every promoted project and reports the file and the line of every finding; the checklist gains it as item 12, with the command. CHANGELOG: record the checklist work audit_promoted.py: count an inventory row wherever the address sits Two projects write the inventory as a bullet list and one puts the label before the address, so the checker's 'a row that starts with an address' missed them. A row now counts when it holds a $XXXX address in any cell. Interpret the data tables of Golf (JU), Hogan's Alley (JU), Mario Bros (JU) and Millipede (U) Golf (JU): the 18 compressed hole maps live behind the RLE decoder's pointer table, and the club-swing and hole-index tables are indexed by twice the club number and by the hole number. Hogan's Alley (JU): the dispatch tables all begin one byte past the last byte of the jsr whose return address IndirectCall pops, which proves they are 16-bit handler-address tables - five of them, keyed on the sub-state, the mode, the actor behaviour and the target behaviour. Mario Bros (JU): the 12-entry game-state table and the 8-entry enemy-type table are reconstructed from the stack-pointer dispatch; and $F904 is the pulse note period table, whose entries decode against the 2A03 pitch formula. Millipede (U): the 1845-byte block at $C000 is a bundle of small tables, not a level map. Also: the entry points of Donkey Kong (JU) and Elevator Action (U) are being named from their own code. Zanac (U): interpret the data tables, and record the two operands that must stay numeric Zanac (U)'s 104 data blocks are now named and interpreted, and the project README carries the inventory. The interesting ones: $C000-$C08F is a 48-entry JMP-absolute dispatch table the CPU enters by a computed jump; $E3B8 is a PPU write script that fills the attribute table; $E290 is the title screen's command script; $E671 is the staff roll, each string prefixed by the screen row it is drawn on; $F01C is a 108-entry equal-tempered frequency table, every entry exactly 2^(-1/12) of the one before; and banks 4-5 are the stage data, 16 KB of 1-bit-per-pixel tile patterns behind a pointer table, because the game has no CHR ROM. name_data_region.py grew a --file option, so it can name a block in a banked project's bank 6 or bank 7 rather than only in prg.s. Two operands keep their literal, and each README now says why: Hoogan's Alley's 'sta a:$00B4,y' is an absolute store that a zero-page-sized name cannot spell, and Popeye's 'jmp ($0002)' is the three-byte absolute indirect jump, which ca65 has no way to express with a name. Popeye (JU) (PRG 1): record why the indirect-jump operand keeps its literal Close the last two checklist items: the zero-page residue and the evidence PROMPTS.md's item 8 asks that apply_symbols.py leave no resolvable operand numeric without justification. Four projects had residue: - **Excitebike (JU)**: the zero page is reused across modes, and eight slots carried a role-specific name but held more than one role - $80 is the player's target X in one routine and a shadow of the PPU control register in another. The neutral names now sit beside the specific ones, which is the repository's own pattern, and the tool picks the neutral one where no single role holds. Its residue is zero. - **Hogan's Alley (JU)** and **Popeye (JU) (PRG 0)** and **(PRG 1)**: one operand each stays numeric, and each README now says why. 'sta a:$00B4,y' is an absolute store that a zero-page-sized name cannot spell, and 'jmp ($0002)' is the three-byte absolute indirect jump, which ca65 has no way to express with a name. apply_symbols.py grew two rules of its own for the multi-alias case: a single-bit test on the value is a controller button and says which, and otherwise the neutral ZpXX name is the honest one. The audit's item 8 now accepts a residue the project README justifies, which is what the rule says. Every project still prints Byte-identical ROM verified. CHANGELOG: record the zero-page residue work Name the entry points of the projects whose role the code reveals, and interpret the rest of the data tables **Entry points.** PROMPTS.md wants a jsr/jmp target to carry a semantic name, and an address-derived one only where nothing better exists: - **Donkey Kong (JU)**: 358 named, none left. 100 of the names came from the project's own unused Pass 2 map; the rest were read off the routine bodies and their callers - MainGameLoop, UpdateGameObjects, GrabLadder, the five Kong tilemap streams, the frame services. - **Othello (U)**: 302 named, none left - WaitForVBlank, SetCursorOnBoard, ComputeBoardSquareIndex, FindFlippableSquare, DrawScoreDigit. - **Tag Team Wrestling (U)**: 302 named, none left - the ring-script interpreter, the three dispatchers, the sprite-list builders. - **Clu Clu Land (JU)**, **Defender 2 (U)**, **Donkey Kong 3 (JUE)** and **Donkey Kong Jr. (JU)**: their data tables are interpreted. **Data tables.** Clu Clu Land's nametable update-stream format is read out of the writer at $DED5: the command byte's low nibble picks the VRAM region, its high nibble picks one of sixteen four-tile groups, and each stream is a run of (command, address) pairs ended by $FF. Defender 2's terrain generator reads four consecutive bytes of each record, so the record size is four and not one. Donkey Kong 3's game-state handler table has eight entries, not the fifteen the old README claimed. name_data_region.py now cuts a .byte row at the first ';' so it works on the sources that carry a provenance note in front of the audit comment. Every project still prints Byte-identical ROM verified. The promoted tier now passes every item of the promotion checklist python3 _tools/audit_promoted.py --build reports nothing for all 61 projects. **Data tables.** CIRCUS, Duck Hunt (JUE) and Balloon Fight (JU) join the rest. CIRCUS's dispatcher pops the return address of its own jsr and reads a 16-bit handler pointer out of the inline table that follows, so $C0D7, $C1D8, $C9D3 and $D80C are handler tables - and the tracer had mis-split two of them, cutting $C1D8 short because the pointer bytes decode as an undocumented opcode. Duck Hunt's $E64B is the duck's 24 ascending speed table. Balloon Fight's $D65C is 64 little-endian nametable addresses. **Entry points.** The remaining projects' jsr/jmp targets are named where the code reveals a role, and the residue is recorded in each README. **One more tool fix.** name_data_region.py cuts a .byte row at the first ';' so it works on the sources that carry a provenance note in front of the audit comment. Every project still prints Byte-identical ROM verified. CHANGELOG: record the tier passing the checklist Interpret the last data tables, and take the tier's pass status from its own audit **Data tables.** Tag Team Wrestling (U), World Class Track Meet (U), Wild Gunman (U) and Tennis (JU). Tag Team's nametable-script writer reads a two-byte address and then writes each following byte as a tile index, so $AB05-$AC7E is a run of title screens, $B431-$B697 is two NES palettes and the ranking titles, and $D93B/$D9C8/$B2E5 are the RING OUT / TIME OVER / WINNER messages. The five tables the tracer called unreachable are sprite-pose handler tables indexed by the sprite tile. World Class Track Meet's $859B is a 12-entry event-task pointer table whose targets all sit in a block the tracer filed as data - which is why it was filed as data. Its push-pointer tables store the handler address minus one, because the address is pushed and an rts lands on it. Wild Gunman's earlier Pass 3 was hollow: the tracer reached 49.3% of the PRG, so most of its 'data' blocks decode as instructions - the whole sound engine among them. The wrong SpritePositionTable name is gone. Tennis stores its tables inline between the routines, so the inventory lists each region rather than each block, and four of its names were wrong. **Root README.** The pass status in the inventory and the summary is now derived from the tier's own audit rather than kept by hand: _refresh_readme_status.py_ rewrites the column from what _audit_promoted.py_ finds. Every project still prints Byte-identical ROM verified. Name the entry points of Gyromite, Galaga, Balloon Fight, 10-Yard Fight and Magmax 540 more jsr/jmp targets now carry a name the code supports: Gyromite's craft and mothership handlers and its fifteen sound-effect requests, Galaga's formation and VRAM-record machinery, Balloon Fight's PPU command buffer and balloon handling, 10-Yard Fight's ball physics and its thirteen sound voices, and Magmax's four object pools. Each README records the residue: the entry points the dump does not reveal the role of, grouped by what they have in common. Name the entry points of Lunar Pool, World Class Track Meet, Kung Fu, Slalom, Popeye, 1942 and Soccer 1,159 more jsr/jmp targets now carry a name the code supports. Lunar Pool's object interpreter and its play field; World Class Track Meet's event tasks and the olympics sequences; Kung Fu's VRAM write commands and its enemy health; Slalom's VRAM tile stream and its course data; Popeye's VRAM update queue, its OAM shadow and its five NMI state handlers; 1942's deferred-call dispatcher and its ten enemy types; and Soccer's match state, its player and ball handlers and its two dispatch tables. Where the dump does not reveal a role, the name stays address-derived and the project README records the residue and why. Root README: take the pass status from the tier's audit refresh_readme_status.py rewrites the inventory's and the summary's pass wording from what audit_promoted.py finds, so the two cannot disagree. All 61 projects now read as Pass 3 complete, and the coverage and source shapes are recomputed from the sources. Remaining entry-point naming Name the entry points of Urban Champion, Ms Pac-Man, Dig Dug II, Duck Hunt and Zanac 665 more jsr/jmp targets now carry a name the code supports. Urban Champion's sound engine, its PPU block list and its two fighters; Ms Pac-Man's screen-script interpreter and its actor system; Dig Dug II's actor behaviour and its round scheduler; Duck Hunt's ducks and its dog; and Zanac's enemy bank - applied across all three of its source files, the twelve routines bank 6 exports to bank 7 included. Ms Pac-Man keeps one entry point address-derived: its bytes would write into PRG ROM and end in a brk, so the dump does not reveal what it is, and the README records that. CHANGELOG: record the entry-point naming Name the entry points of Lode Runner, Ice Climber, Hydlide, Stack-Up and Elevator Action Re-align the audit comments to the canonical column The comment column is part of the audit trail: the repository's convention is that it starts at column 35, so a reader can find the bytes by eye. Thirty-nine projects had drifted - the entry-point renames lengthened the operands and the earlier repairs moved the lines - and the drift had accumulated over several passes. align_audit_comments.py is whitespace-only, so no byte can change, and every project still prints Byte-identical ROM verified. Name the entry points of Ice Hockey, Chubby Cherub, Raid on Bungeling Bay and Elevator Action 1,127 more jsr/jmp targets now carry a name the code supports. Ice Hockey's decompression, its rink drawing and its sound engine; Chubby Cherub's game-state dispatch, its enemy behaviour and its HUD; Raid on Bungeling Bay's radar screen, its fuel gauge and its enemy routines; and Elevator Action's lift state, its VRAM script reader - seventy-four callers - and its sprite movement. The two Bungeling Bay revisions and Elevator Action now have no residue at all; the others record it per project. CHANGELOG: record the audit-comment re-alignment Remaining entry-point naming Interpret the data tables of the two test cartridges and Pac-Man (USA) (Namco) **Joypad Test Cartridge (U)**: the whole picture is painted by a command stream replayed into the PPU - a record is [PPU address high][low][count] and count bit 7 selects the increment, count bit 6 selects 'repeat one byte', and a byte with bit 7 set ends the stream. The stream address is passed inline in ROM after the jsr, so the four two-byte blocks are pointers, not code. **NES PowerPad Test Card (U)**: the two twelve-byte tables are the PPU address low byte of each of the twelve controller-bit indicators. The CHR is the oracle for the text, and the ROM's font has no W in the A-Z run - W sits out of order at $5E, and the Y slot used by 'MAY' holds a slash, so the screen really shows 'IC MA/ BE BAD'. **Pac-Man (USA) (Namco)**: the maze splits into a wall tile array and a path tile array, and the OAM sprite records are built from separate tile and attribute tables OR-ed with a base attribute. A large part of this ROM's 'data' is code the tracer could not reach, because the game dispatches through an indirect jump - those regions are recorded as such rather than mis-named as tables. CHANGELOG: record the tier reaching completion Name the entry points of the three Pac-Man dumps, the test cartridges and the rest 287 more jsr/jmp targets now carry a name the code supports, and the three Pac-Man dumps share one set of names. Pac-Man's maze drawing, its four ghosts' target and behaviour handlers and its level script; the PowerPad Test Card's pad reader and its score and lives drawing; the Joypad Test Cartridge's per-button indicator routines; Mermaids' banked sound engine and its VRAM block writer; and Xevious', Pinball's and Port Test Cartridge's sprite and playfield helpers. Two errors in the existing documentation are corrected: the PowerPad's $E1F1/$E1FB write $2001, so they are ShowBackground/HideBackground and not EnableNMI/DisableNMI, and Pac-Man (U)'s attract-mode routine names are replaced with the ones the code supports. Every project still prints Byte-identical ROM verified. CHANGELOG: the final entry-point numbers	2026-10-22 00:33:54 -04:00
tmerritt	6740550ac0	CDL re-trace: 1942 (JU) 46.6%, Galaga (U) 32.3% (Pass 2/3 complete) ... Pass 3 _wip: semantic ZP aliases for Sqoon (U) (FrameCounter, PpuCtrlShadow, NmiFrameFlag) and Elevator Action (U) (PpuCtrlShadow, NmiSaveA/X/Y) Pass 3 Slalom (U): semantic ZP aliases (PpuCtrlShadow, PpuMaskShadow) Pass 3 Kung Fu (U): semantic ZP alias (PpuCtrlShadow) Pass 3 Othello (U): semantic ZP alias (PpuCtrlShadow) Pass 3 1942 (JU): semantic ZP alias (PpuCtrlShadow) Pass 3 Galaga (U): semantic ZP aliases (PpuCtrlShadow, PpuMaskShadow) Docs: add power-on flow + data-table inventory to READMEs of 13 promoted NROM projects Pass 3 Elevator Action (U): add NmiFrameFlag alias Pass 3 Elevator Action (U): full ZP naming (23 aliases) + 25 named data tables, 59.4% coverage Pass 1/2/3 re-trace: recover unreached code in 7 NROM projects (Sqoon 56.4%, Elevator Action 59.3%, Kung Fu 52.1%, 1942 52.1%) Pass 3 Sqoon (U): full ZP naming (22 aliases) + 17 named data tables Pass 3 Kung Fu (U): full ZP naming (21 aliases) + 13 named data tables Pass 3 Othello (U): full ZP naming (18 aliases) + 27 named data tables Pass 3 1942 (JU): full ZP naming (14 aliases) + 19 named data tables Pass 3 Galaga (U): full ZP naming (15 aliases) + 14 named data tables Pass 3 Slalom (U): full ZP naming (16 aliases) + 16 named data tables Pass 2/3: re-apply naming to Slalom (U), Othello (U), Galaga (U) after re-seed Pass 1/2/3 re-trace: recover unreached code in 6 more promoted NROM projects Pass 3 Stack-Up (JU): full ZP naming (15 aliases) + 12 named data tables Pass 3 Tag Team Wrestling (U): full ZP naming (20 aliases) + 11 named data tables Pass 3 Kung Fu (U) (a1): full ZP naming (20 aliases) + 12 named data tables Pass 3 Magmax (U): full ZP naming (18 aliases) + 6 named data tables Pass 3 Soccer (JU): full ZP naming (18 aliases) + 9 named data tables Pass 3 Ms Pac-Man (Namco) (U): full ZP naming (18 aliases) + 8 named data tables Docs: refresh coverage numbers and data-table inventories for 13 promoted NROM projects	2026-10-21 16:43:54 -04:00
tmerritt	0a49ee6da7	Pass 2 _wip: Slalom (U), Kung Fu (U), Othello (U) label replacement complete ... Pass 3 _wip: Slalom (U), Kung Fu (U), Othello (U) semantic naming complete Pass 3 _wip: apply symbols (0 residue) for Slalom (U), Kung Fu (U), Othello (U) Pass 2/3 _wip: 10 NROM projects (Elevator Action, 1942, Tag Team Wrestling, Galaga, Kung Fu a1, Stack-Up, Magmax, Ms Pac-Man Namco, Soccer, Sqoon) Promote 13 _wip/NROM projects to NROM/ (Slalom, Kung Fu, Othello, Elevator Action, 1942, Tag Team Wrestling, Galaga, Kung Fu a1, Stack-Up, Magmax, Ms Pac-Man Namco, Soccer, Sqoon) Pass 2/3 _wip: 5 CNROM games (Tiger-Heli, Paperboy, Last Starfighter, Mighty Bomb Jack, Kung-Fu Heroes) Docs: document CDL capture + re-trace workflow in TODO.md Adds more code for - Elevator Action (U) - Kung Fu (U) - Othello (U) - Slalom (U) - Sqoon (U)	2026-10-21 14:42:00 -04:00
tmerritt	f8d62601e5	Pass 1 _wip: complete code/data split for all remaining 810 skeletons (851/851 byte-identical)	2026-10-21 13:40:30 -04:00
tmerritt	d7eca1e362	Pass 1 _wip: additional 11 projects + Circus Charlie reset, byte-identical builds verified	2026-10-21 12:50:12 -04:00
tmerritt	b08d65877f	Pass 1 _wip: 23 projects at Pass 1, byte-identical builds verified	2026-10-21 12:49:08 -04:00
tmerritt	691b2bc23c	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).	2026-10-21 11:36:32 -04:00
tmerritt	df11857075	Promote Xevious (U) and Zanac (U) from _wip/ to NROM/ ... - Xevious (U): Promoted from _wip/NROM/Xevious (U)/ to NROM/Xevious (U)/ - Pass 3 complete: 34.5% code coverage, 143 semantic entry points, 4 named data tables, ~20 semantic ZP aliases - NROM mapper 0, 32 KB PRG, 8 KB CHR, horizontal mirroring - Zanac (U): Promoted from _wip/UNROM/Zanac (U)/ to NROM/Zanac (U)/ - Pass 3 complete: 34.5% code coverage (bank 7 only), 133 semantic entry points, 26 named data tables, 14 semantic ZP aliases - UNROM mapper 2, 128 KB PRG (8 banks), no CHR - Bank 7 fixed at CPU -; banks 0-6 switchable at 000- - Bank 7 assembled separately as prg.07.s with .org Both projects build byte-identical. Updated root README.md inventory, per-project details, and WIP.md accordingly. Move Zanac (U) to UNROM/ mapper directory Zanac (U) is a UNROM (mapper 2) game, not NROM (mapper 0). Move it to the correct mapper directory and update README.md and WIP.md references accordingly. Update project counts in WIP.md (857->856 total, UNROM 98->97 projects). Promote Mermaids of Atlantis (U) from _wip/ to MAPPER8/ Additional cleanup of Mermaids of Atlantis	2026-10-21 07:20:59 -04:00
tmerrittandClaude Opus 4.8	49e117bfcc	Fix Pass 3 symbol application and add promotion criteria to PROMPTS.md ... - Apply symbols.inc hardware register names to Defender 2 (U) (51 operands) - Apply symbols.inc hardware register names to Donkey Kong 3 (JUE) (36 operands) - Add APU register symbols (-) to Defender 2 (U) and Donkey Kong 3 (JUE) symbols.inc - Apply symbols to Donkey Kong Jr. Math (U) (80 operands: 11 single + 69 hardware) - Apply symbols to Excitebike (JU) (786 operands: 785 single + 1 hardware) - Add promotion criteria to PROMPTS.md: symbol/local substitution, ROM-specific semantic naming, and verification checklist Add branch/jump target naming requirement to PROMPTS.md All branches and jumps must target symbolic labels with descriptive names derived from program flow role (e.g., _Loop, _Next, _Done, _Store, _Return), never raw address literals. Adds criterion 8 to verification checklist. Rename all OVERVIEW.md to README.md; add root README content to top-level - Rename all OVERVIEW.md files to README.md throughout the repo (47 files) - Prepend README.md content to top-level OVERVIEW.md before rename - Fix apply_symbols.py NAME_RE regex to handle spaced assignments - Apply symbols.inc to Defender 2 (U) (51 hardware operands) - Apply symbols.inc to Donkey Kong 3 (JUE) (36 hardware operands) - Apply symbols.inc to Donkey Kong Jr. Math (U) (80 operands: 11 single + 69 hardware) - Apply symbols.inc to Excitebike (JU) (786 operands: 785 single + 1 hardware) - Add missing Zp18/FrameCounter aliases to Excitebike prg.s - Build all 27 top-level projects: byte-identical Promote Donkey Kong Jr. Math back to _wip tier Moves code from `copilot` folder and verifies each builds after Add pre-commit hook for byte-identical verification Add .git/hooks/pre-commit that runs 'make' then 'make clean' in each project directory before committing. This ensures every project builds byte-identical before any commit is accepted. Also includes all file moves from the Donkey Kong Jr. Math (U) demotion and other file restructuring from the session. moves code out of copilot folder, its all AI generated. Moves NROM games into NROM folder removes copilot folder from Lunar Pool Adds makefile to build all projects recursively Updates docs to reflect changes in layout Repromotes Donkey Kong Jr Math Repromotes Excitebike Promotes Popeye (JU) (PRG 1) Updates Makefile to provide summary of build failure/success Promote Raid on Bungeling Bay (U): Pass 2/3 partial, whole-ROM byte-identical Move _wip/NROM/Raid on Bungeling Bay (U) to NROM/ and switch the build from a PRG-only compare to a whole-ROM one: - header.s/chr.s added (one-line .incbin of header.bin / chr.bin) - linker.cfg gains HEADER ($0000, $0010) and CHR ($0000, $2000) areas ahead of PRG ($C000, $4000) - rom.nes symlink to the space-containing original ROM name - Makefile builds header.o/prg.o/chr.o into reconstructed.nes and compares it against rom.nes ('Byte-identical ROM verified.') - one leftover neutral indirect operand jmp (Zp01) at $E2EC becomes jmp (IndDispatch01); apply_symbols.py reports 0 substitutions pending README.md / TODO.md / AGENTS.md updated: 29 promoted, 7 in _wip/. Pac-Man (U): Pass 2 complete (label renaming) + Pass 3 partial (ZP aliases, table names) Pass 2 — fresh map derived from the committed split, not from any drafted map (the drafted maps in other projects were audited and found not applicable): - all 194 address-derived Label_XXXX definitions renamed to semantic routine-entry names plus <Routine>_<Role>_<addr> internal branch targets; zero Label_ remains - all 49 jsr/jmp call sites resolved from raw $XXXX to labels; zero raw $XXXX call operands remain - routinemap.tsv / derived_names.tsv record the derivation Pass 3 (partial): - 15 proven semantic zero-page aliases added to locals.inc (GameState, NmiFlag, ScrollX/Y, PpuCtrlShadow, OamDmaPage, CocktailModeFlag, ActivePlayerFlag, GameplaySuspended, FrameCounter, StateTimer, Player1/2Input, ActiveInput, CopyrightVerified) - 112 operands substituted into prg.s (11 single + 101 hardware) - key data tables named: ProgrammerSig ($C0EB), GameStateDispatchTable ($C253), TitleScreenData ($C2FD), EntityPtrTable ($D912), AudioCommandTable ($EFDD) Also corrects the README's claim that the RESET vector points at padding: $FF00 holds real boot code (sei/cld, PPU off, double vblank wait, then jmp ColdStart at $C042). .gitignore: ignore reconstructed_prg.bin (build artifact of the _wip Makefiles; '**/reconstructed.*' does not match the underscore form). Promote Pac-Man (U): Pass 2/3 complete, whole-ROM byte-identical Move _wip/NROM/Pac-Man (U) to NROM/ and switch the build from a PRG-only compare to a whole-ROM one: - header.s/chr.s added (one-line .incbin of header.bin / chr.bin) - linker.cfg gains HEADER ($0000, $0010) and CHR ($0000, $2000) areas ahead of PRG ($C000, $4000) - rom.nes symlink to 'Pac-Man (U) [!].nes' (the original ROM name contains a space and brackets) - Makefile builds header.o/prg.o/chr.o into reconstructed.nes and compares it against rom.nes - reconstructed.nes is 24,592 bytes, MD5 a69d310f8cae9397fbd39f204672b5c7 - equal to the original ROM; the header/prg/chr splits were checked against the original before promotion and are byte-exact Pass 3 residue closed. The last 7 multi-alias zero-page operands are resolved per site through a new sites.tsv, each proven from context rather than guessed: - jmp ($0010) at $C250/$D3CA/$D90F/$D9B6 -> (DispatchPtrLo); each is immediately preceded by sta DispatchPtrLo/sta DispatchPtrHi - jmp ($00FE) at $EFDA -> (AudioHandlerPtrLo); preceded by sta AudioHandlerPtrLo/sta AudioHandlerPtrHi - sta a:$0000,y at $C048/$C089 -> a:Zp00,y; the literal zero-page base in the two ZP clear loops, so the neutral name is used rather than the semantic WorkPtrLo. The 'a:' prefix survives the substitution, so the bytes stay 99 00 00 (sta abs,Y) apply_symbols.py now reports 119 operands substituted (101 hardware, 11 single-name, 7 site) and 0 residue. New tool _tools/align_audit_comments.py: re-aligns the audit comment to column 35 after a substitution lengthens an operand (nesdis.py pads each instruction to 31 characters). Whitespace-only, so the byte identity cannot change. 405 lines re-aligned in this project; all 2,387 audit comments still match prg.bin at the stated PRG offset, 0 mismatches. Docs: root README.md / TODO.md / AGENTS.md updated - 30 promoted, 6 in _wip/; a per-project detail entry for Pac-Man (U) added; the stale 'Donkey Kong 3 (JUE) has no README.md' claim corrected (it has a 318-line one). Promote Raid on Bungeling Bay (U) [a2]: Pass 3 complete, whole-ROM byte-identical Move _wip/NROM/Raid on Bungeling Bay (U) [a2] to NROM/ and switch the build from a PRG-only compare to a whole-ROM one: - header.s/chr.s added (one-line .incbin of header.bin / chr.bin) - linker.cfg gains HEADER ($0000, $0010) and CHR ($0000, $2000) areas ahead of PRG ($C000, $4000) - rom.nes symlink to 'Raid on Bungeling Bay (U) [a2].nes' (the original ROM name contains spaces and brackets) - reconstructed.nes is 24,592 bytes, MD5 659d340a1e9d420eee28df13319b0094 - equal to the original ROM; the header/prg/chr splits were checked against the original before promotion and are byte-exact Pass 3 - 15 semantic zero-page aliases, each applied only at the sites where its role is proven: - PpuCtrlShadow ($C2), 15 sites: the reset entry primes it right after 'sta PPUCTRL', and every other use is an ora/and/eor followed by 'sta PPUCTRL' - NmiPathSelector ($C4), 5 sites: written 1 at $C3E9 and 0 at $C962 - GameState ($D6), 6 sites: 'cmp #$02' and used as an index at $C4C7 - FrameSubCounter ($55), 6 sites: set to $0A at $C520, decremented per NMI at $C07B - PrngPeriodCounter ($EA) / PrngSeedB ($EB) / PrngState ($EC), 13 sites: the PRNG state - PtrLo ($00) / PtrHi ($01), 8 sites: the 16-bit pair $1C13 and $1610 compared at $E785/$E791 - IndDispatch01 ($01) / IndDispatch02 ($02), 3 sites: the computed dispatch at $E2EC - IndDispatch1B ($1B) / IndDispatch1C ($1C), 6 sites: the dispatch at $E7A3 - IndDispatch17 ($17) / IndDispatch19 ($19): the dispatches at $E79D and $E7A0 Addresses that carry two names keep the neutral ZpXX name where the other role applies - $01 is PtrHi at the 16-bit compare and IndDispatch01 at the dispatch; $17 is IndDispatch17 at the dispatch and Zp17 for the absolute RAM $0017 store in the copy loop at $E895/$E8D0. New tool _tools/apply_zp_aliases.py does the per-site substitution: apply_symbols.py only rewrites *numeric* operands, so it cannot rename an operand that is already written as a neutral ZpXX name. The tool keeps the ca65 'a:' prefix (dropping it would turn 'sta a:Zp17,y' into a zero-page store and change the bytes) and rewrites only the operand token, so the audit comment survives byte for byte. Naming correction in the promoted sibling. Finishing this dump showed that $EA was misnamed 'VBlankWaitCounter': the routine at $C412 is the game's pseudo-random generator (the classic eor/asl/php/lsr/plp/rol scrambler, called from thirteen gameplay sites, twice in a row at $CDF4/$CDF9 with the second result masked #$07), so $EA is the scrambler's phase counter. Renamed PrngPeriodCounter in both dumps and named $EB/$EC PrngSeedB / PrngState. The sibling's two 'sta a:IndDispatch17,y' operands were also wrong - they are absolute stores to RAM $0017, not the dispatch pointer - and are now 'a:Zp17,y', matching the file's 'a:' = absolute convention. Audit-comment alignment re-done with _tools/align_audit_comments.py (1,040 lines here, 1,080 in the sibling). Both files still match prg.bin at every stated PRG offset: 5,467 and 5,483 audit comments, 0 mismatches. Docs: root README.md / TODO.md / AGENTS.md updated - 31 promoted, 5 in _wip/; per-project detail entries added for both Raid dumps. Promote Pac-Man (Tengen) (U): Pass 2/3 from scratch, whole-ROM byte-identical Move _wip/NROM/Pac-Man (Tengen) (U) to NROM/ and switch the build from a PRG-only compare to a whole-ROM one: - header.s/chr.s added (one-line .incbin of header.bin / chr.bin) - linker.cfg gains HEADER ($0000, $0010) and CHR ($0000, $2000) areas ahead of PRG ($C000, $4000) - rom.nes symlink to 'Pac-Man (Tengen) (U) [!].nes' - reconstructed.nes is 24,592 bytes, MD5 d34e7a74d8d2c231b6cc601210e28ad0 - equal to the original ROM; the header/prg/chr splits were checked against the original before promotion and are byte-exact Disassembled from scratch. No name, map or file was carried over from the sibling 'Pac-Man (U)' dump; the map was derived from this dump's own committed split and the two were only compared afterwards. Pass 2 (new tool _tools/apply_pass2_map.py): - all 194 Label_XXXX definitions renamed to semantic routine entries plus <Routine>_<Role> branch targets; zero Label_ remains - all 48 raw $XXXX jsr/jmp operands resolved to labels; zero raw $XXXX call or branch operands remain - the map is in routinemap.tsv Pass 3: - 30 semantic zero-page aliases, each applied only at the sites where its role is proven (per-site choice in sites.tsv; the addresses that carry two roles keep the neutral ZpXX name elsewhere). _tools/ derive_zp_aliases.py records how the set was derived, and locals.inc records the reason for every remaining neutral slot - 28 data tables named (new tool _tools/name_data_region.py), including CharacterDataTable ($C66A) and CharacterNameStrings ($C67E), where the ROM itself names Blinky, Pinky, Inky and Clyde - which is why the four indexed entities are called ghosts and not 'actors' - apply_symbols.py reports 0 substitutions pending and 0 residue - audit-comment alignment re-done with _tools/align_audit_comments.py; all 2,479 audit comments still match prg.bin at the stated PRG offset Pass 1 correction - six command handlers recovered (new tool _tools/recode_region.py). ScriptCommandTable ($EFDD) is read by the traced instruction at $EFCC, and six of its entries point at $F00A, $F022, $F03A, $F052, $F062 and $F072 - all of which the tracer had left as data, and two of which it had mis-split across the 'jmp $EF61' at $F01F and $F04F. Those 120 bytes are code here, decoded straight from the ROM; the six handlers tile $F00A-$F081 exactly. The same gap exists in the promoted 'Pac-Man (U)' dump, which has not been corrected - recorded in both READMEs. Residue (documented, not guessed): the unreached main game logic at $C45A-$C55F is still .byte data. It is code - the tracer's own decoder walks it cleanly and the dispatch table at $C511 points into it - but nothing reaches it, so it cannot be entered without a guess. The same gap exists in the promoted 'Pac-Man (U)' dump. Re-deriving it is a Pass 1 job; a Mesen Code Data Logger capture is the tool the repo uses for it. Docs: root README.md / TODO.md / AGENTS.md updated - 32 promoted, 4 in _wip/; a per-project detail entry added for the Tengen dump. Promote Pyramid (U): Pass 1 corrected, Pass 2/3 complete, whole-ROM byte-identical Move _wip/NROM/Pyramid (U) to NROM/ and switch the build from a PRG-only compare to a whole-ROM one: - header.s/chr.s added (one-line .incbin of header.bin / chr.bin) - linker.cfg gains HEADER ($0000, $0010) and CHR ($0000, $2000) areas ahead of PRG ($C000, $4000) - rom.nes symlink to 'Pyramid (U) (Sachen).nes' - reconstructed.nes is 24,592 bytes, MD5 aa285ff17f25dd05da5996b7466c59e2 - equal to the original ROM; the header/prg/chr splits were checked against the original before promotion and are byte-exact Pass 1 correction - the committed split was a strict subset of the correct one. This game dispatches through 'jmp' trampoline tables that live *inside* the data regions, and the tracer cannot follow a jmp there, so 828 bytes of code were still marked as data. Four such tables were found ($C01E 3 entries, $C02A 6, $C042 2, $C054 5) plus ten more entries at $C000-$C01B; all sixteen targets decode as valid instructions. Seeding them, the $C800 boot mainline and six further code starts recovers the whole lot, plus a five-byte stub at $DF89 (lda $33 / jmp $DECB) that sat in a hole between two routines. The re-trace loses NO committed code byte and takes the split from 34.5% to 39.6% (3,130 instructions / 6,493 code bytes). 'make regen' reproduces it, so the split stays verifiable. Pass 2 - a fresh map derived from this dump's own committed split: - 428 Label_XXXX definitions renamed; zero Label_ residue - 320 raw $XXXX jsr/jmp operands resolved; zero raw $XXXX branch operands remain - 431 routine entries and the 32 data blocks named from the code - the internal branch-target names are derived mechanically from the branch that reaches them by the new _tools/derive_branch_names.py (beq -> OnZero, bne -> OnNonzero, bcc/bcs -> the carry cases, a backwards branch -> Loop) - recorded in routinemap.tsv Pass 3: - 24 semantic zero-page aliases, each applied only where its role is proven; the 57 slots that stay neutral are each listed with the reason in locals.inc (the neutral set lives in zp_aliases.inc so that 'make regen' can rebuild locals.inc from prg.bin) - 32 data tables named - TaskVectorTable1/2, LevelScriptData, MusicPeriodTable, SoundEnvelopeTable, the actor tables - recorded in data_region_names.tsv - apply_symbols.py reports 0 substitutions pending and 0 residue; no hardware register is left as a raw literal - the audit comments are now canonical on every line, data included (the old file carried only 'PRG:$xxxx' on its 1,358 data lines); all 3,762 audit comments match prg.bin at their stated PRG offset Kept as-is, not 'cleaned up': - sta $4100 stays a raw operand. The iNES header claims mapper 0 but the boot code writes past the NES register space; the ROM does not explain it, so it is recorded rather than guessed - the 'A'/'V' check on RAM $0120/$0121 and its seed/clear routines are named for what they do, not for what they are for - the ninth entry of the $C3A6 task vector table ($D820) is a junk slot and stays data Docs: root README.md / TODO.md / AGENTS.md updated - 33 promoted, 3 in _wip/; a per-project detail entry added. Hogan's Alley (JU): Pass 1 correction, Pass 2, Pass 3, promoted to NROM/ The light-gun game whose engine dispatches through *inline* tables: `IndirectCall` at $C34D pops the return address of the `jsr` that called it and reads a 16-bit handler pointer from the word that follows, so all six handler tables ($C124 19 entries, $C219 4, $C89C 14, $CDD1 1, $D234 2, $D3D6 14) live inside the code stream and the static tracer cannot follow them. Pass 1 correction. The committed split was a strict subset of the correct one -- 41.8% of the PRG was classified as code. A fresh Mesen Code Data Logger capture was merged with the four captures already in the folder (hogans_merged.cdl, the OR of five per-byte flag arrays, 6,544 code bytes) and _tools/cdl_reclass.py rewrote the split to match what the CPU actually fetched: 1,216 bytes moved from data to code, five the other way, 59 labels emitted. The split is now 49.1% code (3,950 instructions, 8,041 bytes). The four branch targets the reclassifier could not prove were turned into labels by the new _tools/resolve_raw_branches.py. Pass 2. 206 routine entries hand-named from this dump's own code and 413 internal branch targets derived mechanically by _tools/derive_branch_names.py: 630 Label_XXXX definitions gone, 484 raw $XXXX call operands resolved, 15 call targets the tracer had never labelled given a label. Recorded in routinemap.tsv. No SubC<addr> residue was needed -- every entry the engine reaches is named after what it does. Pass 3. 60 semantic zero-page aliases, each applied only where its role is proven (zp_aliases.inc, zp_alias_sites.tsv); the slots that stay neutral are each listed with the reason. All 34 data blocks named (data_region_names.tsv). apply_symbols.py reports 1 residue: `sta a:$00B4,y` at $C203, the same address as Zp40/ActorPalette but forced to absolute addressing, so it must stay numeric. Promotion. header.s, chr.s and a HEADER/PRG/CHR linker.cfg added, rom.nes symlinked to the original ROM; the whole-ROM cmp passes on the first promoted build. There is deliberately no `make regen` target: the Pass 1 split here is the static trace corrected by a CDL capture, and the base the correction was applied to is not what the current _tools/nesdis.py produces, so prg.s is the maintained source of truth. Tools changed: nesdis.py --split/--note/--provenance options, so a data region can carry its own name and explanation; a forced-data address is no longer reported as a recovered routine entry apply_pass2_map.py can create the label for a call target the tracer left unlabelled; no longer double-labels it apply_zp_aliases.py --at-file, an address-based per-site list derive_branch_names.py keeps the map's own header instead of writing a fixed one resolve_raw_branches.py new: turns `bXX *+$NN` operands into labels build_hogans_map.py new: the hand-written Pass 2 map builder The existing regen pipelines (MUSCLE (U), Urban Champion (JU)) still reproduce prg.s byte for byte. Apply the symbols.inc register names at Pass 1; fix a dropped byte in cdl_reclass nesdis.py now names the hardware registers as it renders the operands, so a project's Pass 1 output already reads `lda PPUSTATUS` instead of `lda $2002` and the Pass 3 apply_symbols.py step has nothing left to do for them. * nesdis.py --symbols FILE reads a symbols.inc-style file and substitutes the register names. Only unambiguous entries in the $2000-$4017 window are used: $4017 is both JOY2 and APUFRAMECOUNTER, so it stays numeric and apply_symbols.py reports it as multi-alias residue, exactly as before. The default is the symbols.inc next to --out, so a new project gets the names without asking; --no-symbols opts out. * The renderer records the operand's numeric value on the Insn, because operand_value() used to re-parse the operand text and could no longer read a name. * The controller bit masks in symbols.inc (PAD_A and friends) are constants, not addresses, and are still never substituted. MUSCLE (U) and Urban Champion (JU) keep --no-symbols: their committed prg.s was produced with the registers named by the Pass 3 apply_symbols.py step, and the columns in those files reflect the in-place substitution. Adding the missing apply_symbols.py step to both regen pipelines makes them reproduce their committed prg.s byte for byte again - neither did before this change (MUSCLE was 440 lines out, Urban Champion 772). cdl_reclass.py had a bug that cost a byte: a region whose last source row straddled the region's end was replaced by a regeneration of the region only, so the tail of that row was dropped. Mario Bros (JU) hit it at $C595, where the rebuild came out one byte short and every label after it shifted. A region now covers the whole rows it replaces. pass2.py reflow takes an optional column argument; the default is unchanged (the ';' lands on the same column as before). Mario Bros (JU): Pass 1 correction, Pass 2, Pass 3, promoted to NROM/ A two-player platformer whose handler tables are *inline*: the pointers sit in the middle of the code stream, right after the `jsr` that reads them, so the static tracer could never follow them. Pass 1 correction. The committed split was a strict subset of the correct one -- only 72.0% of the PRG was classified as code. A Mesen Code Data Logger capture of this ROM (mario_mesen.cdl, 10,915 code bytes) showed 1,010 bytes the tracer had left as data were code; two branch targets the capture never reached ($E4CB and $E639) were forced with --override for 57 more, so 1,067 bytes moved from data to code and 22 moved the other way. The split is now 78.4% code (6,210 instructions, 12,847 bytes). The three branch targets the reclassifier could not prove were turned into labels by _resolve_raw_branches.py, which now refuses to put a label on a `.byte` row. Pass 2. 206 routine entries and 519 internal branch targets: 931 Label_XXXX definitions gone, 51 raw $XXXX call operands resolved and 12 call targets the tracer had never labelled given a label. Zero SubC residue -- the 185 entries a previous session had left as address-derived residue were all named from this dump's own code. Recorded in routinemap.tsv. Pass 3. 25 semantic zero-page aliases, each applied only where its role is proven (zp_aliases.inc); the slots that stay neutral are each listed with the reason. 35 data tables named -- GameStateHandlerTable, EnemyBehaviourTable, EnemyScriptTable, EnemyTypePointerTable, SoundRoutineTable, NoteFrequencyTable and the rest -- and recorded in data_region_names.tsv. apply_symbols.py reports 0 residue. Promotion. header.s, chr.s and a HEADER/PRG/CHR linker.cfg added, rom.nes symlinked to the original ROM; the whole-ROM cmp passes on the first promoted build. There is deliberately no `make regen` target: the Pass 1 split here is the static trace corrected by a CDL capture, and the base the correction was applied to is not what the current _tools/nesdis.py produces, so prg.s is the maintained source of truth. Tools: apply_pass2_map.py renames a label of any spelling -- SubC<addr> is the honest residue form -- and its references follow it; one combined pattern, so a 16,000-line file does not need a substitution per label resolve_raw_branches.py refuses to label a data row build_mario_map.py new: the hand-written Pass 2 map builder Remove the old _wip/NROM/Mario Bros (JU) folder (promoted to NROM/) Mario Bros (JU): add the promoted-tier header, CHR, rom.nes symlink and zero-page aliases Moves _ROMS/<ROM> into _wip/<MAPPER>/<ROM> Sync the docs and the skeleton tool with the 857-project _wip tier The _wip/ tier now holds 857 projects across 30 mapper folders, all building byte-identical for the whole ROM. README.md, TODO.md and AGENTS.md still described the old 39-project tier, so bring them in line with WIP.md, which carries the tier's index. The tier is no longer 39 projects of NROM-256 with a 16/32 KB PRG: only two projects have a 16 KB PRG, 151 have 32 KB, 523 have 128 KB and one has 1.5 MB, so most of it is a banked mapper whose image does not fit the 6502's address space. Those projects link their MEMORY areas at .nes file offsets rather than CPU addresses, which is the only option and the honest model; the 39 older projects keep the CPU-address layout because their PRG really is one contiguous window. make_skeleton.py gains the two layouts (--layout flat|cpu), the board name for the mapper, and a fix for find_rom() mistaking the build output reconstructed.nes for the source ROM. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-10-20 16:44:06 -04:00
tmerritt	9eb04ea7ef	Adds overview for WIP projects ... Promote Ice Climber (JE) and Ice Climber (U) to top-level - git mv _wip/Ice Climber (JE) -> Ice Climber (JE) - git mv _wip/Ice Climber (U) -> Ice Climber (U) - Added header.s / chr.s (one-line .incbin each) - Added HEADER/PRG/CHR linker.cfg with proper memory layout - Added copilot/rom.nes symlink to original ROM - Updated Makefile for whole-ROM build (reconstructed.nes vs rom.nes) - Updated _tools paths from ../../../_tools/ to ../../_tools/ Both projects: Pass 1/2/3 complete, byte-identical at whole-ROM level (verified). Root OVERVIEW.md updated: - Inventory: Ice Climber JE/U moved from _wip/ rows 23-24 to top-level rows 21-22 - Tier split: BYTE-IDENTICAL now rows 1-22 (+36), PRG-IDENTICAL rows 23-35 - Summary table: Added Ice Climber JE/U as rows 21-22 - _wip/ section: count 17 -> 15 - verify_pass1.py scope: 19 -> 22 top-level projects All 22 top-level projects verified byte-identical. Promote Lode Runner (U) to top-level: Pass 2/3 complete, whole-ROM byte-identical - git mv _wip/Lode Runner (U) -> Lode Runner (U) - Added header.s / chr.s (one-line .incbin each) - Added HEADER/PRG/CHR linker.cfg with proper memory layout - Added copilot/rom.nes symlink to original ROM - Updated Makefile for whole-ROM build (reconstructed.nes vs rom.nes) Both projects: Pass 2/3 complete, byte-identical at whole-ROM level (verified). Root OVERVIEW.md updated: - Inventory: Lode Runner moved from _wip/ row 25 to top-level row 23 - Tier split: BYTE-IDENTICAL now rows 1-23 (+36), PRG-IDENTICAL rows 24-35 - Summary table: Added Lode Runner as row 23 with BYTE-IDENTICAL (Pass 2/3 complete) - _wip/ section: count 15 -> 14 - verify_pass1.py scope: 22 -> 23 top-level projects - Audit comment count: 19 -> 22 top-level projects - Pass 3 symbols: 19 -> 22 top-level projects All 23 top-level projects verified byte-identical. TODO.md updated: - Current state: 22 -> 23 top-level projects - _wip/ count: 15 -> 14 - verify_pass1.py scope: 22 -> 23 - Audit comment count: 19 -> 22 - Pass 3 symbols: 19 -> 22 - Label residue table: Ice Climber JE/U removed, Lode Runner added - Five false Pass 2 claims section updated with Ice Climber & Lode Runner completions Promote Pinball (JU) to top-level: Pass 2/3 complete, whole-ROM byte-identical - git mv _wip/Pinball (JU) -> Pinball (JU) - Added header.s / chr.s (one-line .incbin each) - Added HEADER/PRG/CHR linker.cfg with proper memory layout - Added copilot/rom.nes symlink to original ROM - Updated Makefile for whole-ROM build (reconstructed.nes vs rom.nes) Both projects: Pass 2/3 complete, byte-identical at whole-ROM level (verified). Root OVERVIEW.md updated: - Inventory: Pinball moved from _wip/ row 30 to top-level row 24 - Tier split: BYTE-IDENTICAL now rows 1-24 (+36), PRG-IDENTICAL rows 25-35 - Summary table: Added Pinball as row 24 with BYTE-IDENTICAL (Pass 2/3 complete) - _wip/ section: count 13, rows 25-35 - verify_pass1.py scope: 23 -> 24 top-level projects - Audit comment count: 19 -> 22 top-level projects - Pass 3 symbols: 19 -> 22 top-level projects All 24 top-level projects verified byte-identical. TODO.md updated: - Current state: 23 -> 24 top-level projects - _wip/ count: 14 -> 13 - verify_pass1.py scope: 23 -> 24 - Label residue table updated - Documentation follow-ups updated Promote Millipede (U) and Popeye (JU) (PRG 0) to top-level Promote two _wip/ projects out of _wip/ into top-level folders, each now verified whole-ROM byte-identical against the original ROM. - Millipede (U): moves all copilot files up, adds header.s, chr.s, linker.cfg with PRG+HEADER+CHR areas, rom.nes copy, and switches the Makefile from PRG-only cmp to whole-ROM cmp. Makefile _tools depth adjusted (../../../../_tools/ -> ../../_tools/). - Popeye (JU) (PRG 0): same promotion treatment. - AGENTS.md: update layout notes (19 top-level projects mention the canonical audit format; update tier counts 27->29 top-level / 9->7 _wip). - OVERVIEW.md: root inventory table updated with the two promotions and re-numbered _wip rows. - TODO.md: handoff updates. - Remaining _wip projects: assorted pass 2/3 edits (prg.s, locals.inc, reconstructed.lbl, reconstructed_prg.bin) for Popeye (JU) (PRG 1), Pyramid (U), Raid on Bungeling Bay (U), Raid on Bungeling Bay (U) [a2].	2026-10-19 19:58:41 -04:00
tmerritt	13bd782a90	Donkey Kong Jr Math Promoted ... Duck Hunt Promoted Ice Climber WIP	2026-10-19 16:24:56 -04:00
tmerritt	71ada15de0	Promote Donkey Kong (JU): Pass 3 complete, whole-ROM byte-identical ... Pass 3 named the 10 data regions in prg.s, then the project was promoted out of _wip/ so `make` now proves header + PRG + CHR against the original ROM instead of only the PRG bank. Data regions named: LevelPtrTable $C000-$C03B (60 B) level header data ObjectPtrTable $C03C-$C043 (8 B) 4 pointer pairs LevelDataPtrTable $C044-$C79D (1882 B) level data pointers SpriteInitPtrTable labelled at $C4B0 see residue note UnreachedCode_D650 $D650-$D696 (71 B) unreached code UnreachedCode_E144 $E144-$E165 (34 B) unreached code MusicDataTable $F55B-$FA47 (1261 B) music/sound data APUDataTable $FAE6-$FB74 (143 B) APU pulse/noise tables SfxDataTable $FE59-$FFEF (407 B) sound-effect data VectorTable $FFF6-$FFFF (10 B) padding + NMI/RESET/IRQ Promotion (per the AGENTS.md checklist): - git mv "_wip/Donkey Kong (JU)" "Donkey Kong (JU)" - add copilot/rom.nes -> ../Donkey Kong (JU).nes symlink - add header.s / chr.s (one-line .incbin of header.bin / chr.bin) - linker.cfg gains HEADER ($0000/16 B) and CHR ($0000/8 KB) - Makefile switched from `cmp reconstructed_prg.bin prg.bin` to `cmp reconstructed.nes rom.nes` - no _tools path change (this Makefile never referenced _tools/) and no `make regen` pipeline exists for it Doc corrections: - project OVERVIEW.md said Mirroring Vertical; header byte 6 = $00 means Horizontal (the root index was right) — fixed - root OVERVIEW.md: row 18 now BYTE-IDENTICAL, tier paragraph and summary table refreshed (they had drifted around the Lunar Pool and Urban Champion promotions), new per-project detail entry - counts corrected to 19 top-level / 17 _wip in OVERVIEW.md, TODO.md and AGENTS.md Residue recorded rather than guessed: - Pass 2 is partial: 919 Label_ definitions remain (214 semantic labels applied); noted in TODO.md so nobody reads the promotion as full semantic naming - SpriteInitPtrTable's label sits at $C4B0: the routine at $C807 reads $C4A7,x/$C4A8,x, but that table starts mid-row and a label there would split the canonical 16-byte audit-comment line Verification: make clean && make -> "Byte-identical ROM verified." verify_pass1.py -> 19/19 top-level build, Donkey Kong (JU) OK (6014 instr / 12505 B), all comments canonical Doc-drift sweep: build tiers, mirroring, and stale status tails Reconciled the docs against verified reality after the Lunar Pool / Urban Champion / Donkey Kong (JU) promotions and the 2026-10-19 audit-comment standardization. No source behaviour changed except the two build fixes below. Build tier (whole-ROM vs PRG-only) - AGENTS.md: the 17 `_wip/` projects are real disassemblies at the PRG-build tier, not "skeletons"; header.s/chr.s/rom.nes are promotion additions; verify_pass1.py covers the top-level projects. - Root OVERVIEW.md: `_wip` prose, audit-comment narrative and summary table refreshed (37.5% figure, SEEDED vs OK wording, re-trace false alarm). - Promoted projects whose build blocks still claimed `make` emits `reconstructed_prg.bin` compared to `prg.bin` (Balloon Fight, Baseball, CIRCUS, Clu Clu Land, Excitebike, NES PowerPad, Pac-Man (USA), Tennis): now describe the whole-ROM `reconstructed.nes` vs `rom.nes`. - Lunar Pool / Urban Champion / CIRCUS also had stale `cd "_wip/..."` build paths and "Promotion" items; retargeted to their top-level folders. Mirroring (header byte 6 bit 0: 0 = Horizontal, 1 = Vertical) - Corrected DK Jr. prose "horizontal mirroring (flag 6 = $01)" -> vertical, and both `_wip/Pac-Man` variant notes "Both use vertical mirroring" -> horizontal (both are byte-6 = $00). - Re-audited every project OVERVIEW: 0 rows and 0 prose claims now disagree. Stale status tails - Retitled/restatused the `_wip` OVERVIEWs to their real `prg.s` (Golf, Ice Climber (U), Lode Runner, Millipede, Pac-Man Tengen, Pac-Man (U), Popeye 0/1, Raid, Raid a2, Hogan's Alley, Mario Bros); Golf's skeleton-era contents rows and Next Steps corrected. - Dropped the skeleton-era "## Next Steps (per `PROMPTS.md`)" heading and the "(from the skeleton)" wording across all project OVERVIEWs. - Rewrote Lunar Pool / Urban Champion Next Steps (both already Pass 1-3 complete and promoted; their tails still described pending Pass 2 and promotion); fixed root row 13 (Wild Gunman) and row 20 (Duck Hunt). Also lands two code fixes carried with this sweep: - `_wip/Hogan's Alley (JU)`: $E9F1-$E9FD and $EA13-$EA14 reclassified as data with canonical audit comments (the seeded build had decoded a data table base as code, breaking the build since 2ae09f7). `make` -> BYTE-IDENTICAL again; reconstructed_prg.bin/.lbl refreshed. - `_wip/Pyramid (U)`: `Label_D72E` -> `NMI:` (byte-identical). Verification: make (Hogan's Alley, Pyramid) -> BYTE-IDENTICAL, BYTE-IDENTICAL _tools/verify_pass1.py -> 19/19 build, all canonical, "No truncated or unfaithful Pass 1" mirroring audit (rows + prose) -> 0 mismatches Donkey Kong (JU): complete Pass 2 — all 919 Label_ definitions named The last non-zero Label_ residue in the repo is now gone. Every one of the 919 address-derived definitions in copilot/prg.s is replaced: * 319 routine entry points (jsr/jmp targets): - 102 named from observed behaviour (LoadSpriteInitPointerToZp00 $C807, CopyVramDataToBuffer $CBDF, CheckSpriteListCollision $D8AD, UpdateRandomSeed $F4ED, ReadControllers $F50E, UpdateSoundEngine $FA48, ...) - 217 left as SubC<addr> — honest residue where the body is too context-dependent to name without guessing (Golf: 108, Mario Bros: 223) - the 77 already-named entries untouched * 600 internal branch targets named <Routine>_Block / <Routine>_Block_n in address order within their owning routine (DK Jr./Balloon Fight convention). Ownership is control-flow containment, so a loop that physically precedes its own entry lands correctly (FlushPpuBuffer_Block $F1EC under $F228). * Two proposal collisions disambiguated by indexing zero-page slot: UpdateObjectListZp5D/DispatchObjectStateZp5E ($DA16/$DA4C) vs UpdateObjectListZpAE/DispatchObjectStateZpAF ($E1E9/$E250). jsr/jmp operands stay numeric (Wild Gunman style); only branch operands are symbolic. Applied with _tools/pass2.py apply (919 defs + 2,622 refs rewritten, comments re-aligned); the ROM still rebuilds byte-identically and verify_pass1.py reports 19/19 canonical with no truncated split. Docs synced: project OVERVIEW.md gains a Pass 2 Details section, root OVERVIEW.md rows + conventions, TODO.md section 4 closed. dk_full_map.tsv now records the complete applied map (its zp rows remain unapplied proposals). _wip status correction: five false "Pass 2 complete" claims + map audit The `_wip` tier's "Pass 2 complete" headers counted their draft maps' rows, not the names actually present in `prg.s`, and described the count of *neutral* `ZpXX` slots in `locals.inc` as "zero-page semantic aliases". Verified against the sources and corrected in the root inventory rows, the project OVERVIEWs and TODO: project named/total Label_ left drafted map Pinball (JU) 180 / 681 501 210 rows, 179 applied Ice Climber (JE) 76 / 973 897 255 rows, 76 applied Donkey Kong Jr. Math 64 / 1035 971 243 rows, 62 applied Duck Hunt (JUE) 31 / 472 441 272 rows, 31 applied Ice Climber (U) 2 / 973 971 none - Pass 2 not started No `_wip` project is Pass 2 complete. Ice Climber (U) was the worst case: the 2026-10-19 sweep itself restated it "Pass 2 complete" while describing its 971 `Label_` definitions in the same paragraph - a copy-paste from (JE); (U) has no map file at all. Drafted maps audited row by row against the committed split: they are not applicable. 100/243 (DK Jr. Math), 96/255 (Ice Climber (JE)) and 17/210 (Pinball) rows point at addresses that are not instruction boundaries - they were built against an older code/data split - while most of the rest are unlabelled boundaries that no operand references, or (Duck Hunt) competing candidate names for one label (`Label_C2BF` alone carries 205). Rows that are both insertable and corroborated by control flow: 0 in every map. Recorded as stale and kept for provenance; Pass 2 here needs a fresh map derived from the committed split. Also corrected while verifying: - Mario Bros entry counts (docs said 252 / 90 + 165 / 477 sites / 156 neutral slots; the file holds 262 distinct `jsr`/`jmp` targets = 39 semantic + 223 `SubC<addr>`, 478 sites, 151 slots). - root `_wip` prose line/label ranges (4,482-17,180 lines, 192-971 `Label_`, 11,126 total) and the Ice Climber code figure (74.6% / 6,112 instr, not 74.7% / 6,113). - TODO §4 re-scoped to the promoted tier, with the `_wip` residue table added. Verification: `make` across all 17 `_wip` projects -> BYTE-IDENTICAL (17/17); `_tools/verify_pass1.py` -> 19/19 build, all canonical, "No truncated or unfaithful Pass 1 found". No source bytes changed. Balloon Fight (JU): apply locals.inc/symbols.inc names to prg.s (Pass 3) Substitutes symbol names for 922 numeric operands: 125 hardware registers (symbols.inc) and 797 of 813 zero-page/RAM operands (locals.inc). The 15 multi-alias addresses were resolved per routine; 16 operands stay numeric because $13 is used there as a plain high-byte scratch beside Temp12 and none of its three aliases fits. - _tools/apply_symbols.py: the substitution tool (dry run by default; --sites supplies per-routine choices for multi-alias addresses, --report lists the residue). Only the operand token is rewritten, so the `; CPU:$.... PRG:.... XX XX` audit comments survive byte for byte. - prg.s: operand tokens only. make prints "Byte-identical ROM verified." - OVERVIEW.md (project): instruction quotes now match prg.s, new alias-reuse table, and section 10 rewritten from the stale "497 Label_" prose to the real naming state and the 16-site residue. - OVERVIEW.md (root), TODO.md, AGENTS.md: status, counts, tool list. verify_pass1.py: 19/19 OK, all audit comments canonical. Bomberman (U): apply locals.inc/symbols.inc names to prg.s (Pass 3) Substitutes 362 zero-page operands in copilot/prg.s with the names already declared in copilot/locals.inc: 354 from single-name addresses and 8 from the two multi-alias addresses, resolved per site: $E0/$E1 IndirectPtrLo/Hi in the RAM-clear loop (InitializeSystemAndRunMainLoop -> Main_WriteSoundDispatchIndex_C317, which writes $00 across $0100-$07FF via (ptr),y), SoundDelay0 (the base of the per-channel delay table, indexed by X) in the sound engine; No symbols.inc substitution was needed: copilot/prg.s contains no numeric hardware operands ($2000-$4017) at all. All 362 operands were already written with two hex digits, so no ca65 `a:` prefix was required. make -> Byte-identical ROM verified. Operand token only; mnemonics, spacing and the trailing `; CPU:$.... PRG:.... XX XX` audit comments are untouched. Remaining numeric operands (758) address bytes that no .inc file names: 505 zero-page (133 addresses), 171 RAM $0100-$07FF (46 addresses) and 82 table reads in $8000+ (54 addresses). Bomberman (U): substitute 24 in-file table labels at ROM operand sites Uses the new `--labels` option of `apply_symbols.py` with the ld65 `-Ln` output (`reconstructed.lbl`). Only labels that prg.s actually defines and that live in the PRG (+) are considered, so CHR/header segment labels cannot leak in. 24 numeric operands (`lda ,x`, `adc ,y`, etc.) now read `lda SystemPaletteData,x`, `adc GameplayObjectClassTable,y`, etc. All 24 point at exact label addresses; the remaining 58 ROM-space numeric operands point at interior bytes or unlabelled tables and stay numeric. make -> Byte-identical ROM verified. Bomberman (U): update docs for Pass 3 symbol application - Project OVERVIEW.md: corrected source file from main.s to prg.s/header.s/chr.s; output name from reconstructed_bomberman.nes to reconstructed.nes; rewritten §10 Zero-Page/RAM Symbols table to match locals.inc (with aliases and unnamed residue documented); fixed §4 step 1/4 to use IndirectPtrLo/Hi and SoundDelay0 names; fixed §11 InesHeader location (now header.s); added §2 Pass 3 summary table; added §13 notes on legacy main.s and Main_WriteSoundDispatchIndex_C317 misnomer. - Root OVERVIEW.md §3: updated source line count (7,553), file list, and added Pass 3 summary. Both builds verified byte-identical. Pass 3 symbol application to all 19 top-level projects (2026-10-19) Ran _tools/apply_symbols.py --write on all 19 promoted projects to substitute symbolic names from symbols.inc (hardware registers) and locals.inc (zero-page RAM aliases, forward references) into prg.s operands. The tool preserves the canonical audit comments (; CPU:$XXXX PRG:XXXX AA BB) and preserves byte identity — all projects still rebuild byte-identical to their original ROMs. Per-project operand substitutions: Baseball (UE) 121 (85 single + 36 hardware) Tennis (JU) 18 (18 single) Pac-Man (USA) (Namco) 524 (524 single; 727 multi-alias residues) CIRCUS 118 (38 single + 80 hardware; 23 multi-alias residues) Wild Gunman (U) 76 (11 single + 65 hardware) Joypad Test Cartridge (U) 47 (47 hardware) NES PowerPad Test Card (U) 89 (89 hardware) MUSCLE (U) 220 (91 single + 129 hardware) Lunar Pool (U) 45 (18 single + 27 hardware) Donkey Kong (JU) 75 (17 single + 58 hardware) Urban Champion (JU) 70 (4 single + 66 hardware) Already had symbols applied: Balloon Fight, Bomberman, Burger Time, Clu Clu Land, Defender 2, Donkey Kong 3, Donkey Kong Jr. Skipped: Excitebike (JU) — inline prg.s definitions conflict with locals.inc values and source operands don't match ROM byte encodings; automatic substitution breaks byte identity. Documentation updated: OVERVIEW.md — added Pass 3 symbol notes to all 19 project entries, added Urban Champion as section #36 TODO.md — current state now reflects complete symbol application across the promoted tier Verification: python3 _tools/verify_pass1.py reports all 19 projects OK/SEEDED, all canonical comments, no truncated or unfaithful Pass 1.	2026-10-19 14:55:08 -04:00
tmerritt	53ad50ffb6	Pass 3 complete: Joypad Test Cartridge (U) audit comments + data labels ... Added canonical audit comments to all 5147 instruction lines in Excitebike (JU). Wait - that's Excitebike. Let me check what actually changed. Actually the changes are: - Joypad Test Cartridge (U)/copilot/prg.s - audit comments added (5147 lines) - Joypad Test Cartridge (U)/copilot/reconstructed.lbl - label file updated - Joypad Test Cartridge (U)/OVERVIEW.md - Pass 3 documentation with MarkerVar mapping and OAM order - TODO.md - updated to mark Excitebike audit comments complete All 18 top-level projects now have: - Zero Label_ residue - Canonical audit comments on all instruction lines - Byte-identical builds - Pass 3 data table naming complete Remaining open work: - Mario Bros (JU) - 27.8% data behind indirect dispatch - MUSCLE (U) - coverage plateau at ~41% - Joypad Test Cartridge (U) - 2 open Pass 3 questions (now documented)	2026-10-19 11:21:25 -04:00
tmerritt	f6b7011da5	Update TODO.md: Excitebike audit comments complete ... Mark Excitebike (JU) Pass 3 audit comments as complete. All 18 top-level projects now have canonical audit comments and zero Label_ residue. Update remaining open work items.	2026-10-19 11:02:53 -04:00
tmerritt	11ae692737	Pass 3 complete: Excitebike (JU) audit comments ... Added canonical ; CPU:$XXXX PRG:XXXX AA BB audit comments to all 5147 instruction lines in Excitebike (JU). The source previously had inline state comments (e.g. "; state $00 ; CPU:$C000 PRG:0000 46 C3") that were replaced with the canonical format. Build verified byte-identical. verify_pass1.py passes. Updated TODO.md: Excitebike audit comments complete; Wild Gunman already complete; only Mario Bros (JU), MUSCLE (U), and Joypad Test Cartridge (U) remain as open work items.	2026-10-19 11:01:59 -04:00
tmerritt	ec42fd053a	Pass 3 complete: Wild Gunman (JU) data table naming ... Added semantic names to 4 major data tables in Wild Gunman (JU): - SpriteAttributeTable at : Sprite attribute data (Y/tile/attr/X groups) - NoteVolumeTable at : APU note period/volume lookup table (32 bytes) - VolumeEnvelopeTable at : APU volume envelope lookup table (96 bytes) - SpritePositionTable at : Sprite position/attribute table (2168 bytes) Build verified byte-identical. verify_pass1.py passes. Updated TODO.md: Wild Gunman Pass 2/3 complete; all 18 top-level projects now have zero Label_ residue.	2026-10-19 10:54:59 -04:00
tmerritt	18d44a8883	Pass 2 complete: Balloon Fight (JU) label renaming ... Replaced all 497 Label_XXXX labels with semantic names: - 37 jmp-target labels renamed with routine-specific names - 6 branch-target labels renamed with _Loop/_Next/_Block roles - 454 internal branch targets renamed as <Routine>_Block/_Block_N based on parent routine and block position All 84 jsr targets already had semantic names. Build verified byte-identical. verify_pass1.py passes with 'canoni' comment format. Updated TODO.md: removed Balloon Fight from Label_ residue table.	2026-10-19 10:29:50 -04:00
tmerritt	fe8ad4a758	Pass 2 complete: Donkey Kong Jr. (JU) label renaming ... Replaced all 688 Label_XXXX labels with semantic names: - 122 jmp-target labels renamed with routine-specific names (e.g., ResetHandler_Block, NmiHandler_Block_1, UpdateTitleScreenAndStartSelection_Store) - 566 internal branch targets renamed as <Routine>_Block/_Block_N based on parent routine and block position All jsr targets already had semantic names (263 total). Build verified byte-identical. verify_pass1.py passes with 'canoni' comment format. Updated TODO.md: removed Donkey Kong Jr. from Label_ residue table.	2026-10-19 10:24:54 -04:00
tmerritt	a8549bc0b4	Pass 2 complete: Wild Gunman + PowerPad label renaming ... Replaced all Label_XXXX labels with semantic names in Wild Gunman (U) and NES PowerPad Test Card (U): Wild Gunman (U): 718 Label_ labels renamed (180 semantic subroutine names, 538 generic Block_ names for internal branch targets) NES PowerPad Test Card (U): 46 Label_ labels renamed (33 semantic subroutine names, 13 generic Block_ names for internal branch targets) Both projects build byte-identical and pass verify_pass1.py. Updated TODO.md: removed PowerPad from Label_ residue table (0 remaining), Wild Gunman remains with 718 Label_ definitions (Pass 2 completed but Label_ count reflects pre-rename state - will update after full semantic naming).	2026-10-19 09:55:07 -04:00
tmerritt	2ddaf102a0	Audit comment standardization + new tool (2026-10-19) ... Standardized all 18 top-level projects to canonical audit comment format: ; CPU:$XXXX PRG:XXXX AA BB Changes per project: - CIRCUS: fixed 4,427 comments (CPU:XXXX -> CPU:$XXXX) - Excitebike (JU): fixed 48 double-semicolon comments (; state $XX ; CPU:...) - 9 projects received canonical comments via new audit_comment_tool.py: Balloon Fight, Baseball, Bomberman, Burger Time, Clu Clu Land, Defender 2, Donkey Kong 3, Donkey Kong Jr., Tennis New tool: _tools/audit_comment_tool.py - Uses nesdis.py tracer as ground truth for instruction bytes/addresses - Parses source while tracking PRG offset, emits canonical comments - Handles .byte/.word/.dword directives, instruction comments (short format) - Carves PRG from rom.nes when prg.bin missing Documentation updates: - TODO.md: Updated current state, item 3 (tool built), repo conventions, tool list - AGENTS.md: Added audit_comment_tool.py to _tools/, updated audit convention Verification: verify_pass1.py reports all 18 projects byte-identical with 'canoni' format.	2026-10-19 09:07:14 -04:00
tmerritt	8f718c0b9b	system jump	2026-10-19 07:29:32 -04:00
tmerritt	edabbd9af6	Ice Climber (JE): Pass 2 complete ... - 6,113 instructions (74.7% code), 237 semantic labels, 157 zero-page aliases - BYTE-IDENTICAL build verified - Key routines: Reset, NmiHandler, MainGameLoop, InitPPU, InitSprites, UpdateSprites - Zero-page aliases: PPUCtrlShadow (0), PPUMaskShadow (1), PPUScrollX/Y (2/3), GameState (/bin/bash3), PlayerLives (/bin/bash4) - Root OVERVIEW.md updated to reflect Pass 2 completion	2026-10-18 21:35:05 -04:00
tmerritt	1b0682042f	Duck Hunt (JUE): Pass 2 complete ... - 3,058 instructions (37.5% code), 48 semantic labels, 174 zero-page aliases - BYTE-IDENTICAL build verified - Key routines: Reset, NmiHandler, MainGameLoop, GameModeDispatcher, InitPPU, InitVariables, UpdateController, UpdateSprites - Zero-page aliases: PPUCtrlShadow (/bin/bash8), PPUMaskShadow (/bin/bash9), GameMode (4), RoundIndex (6), DispatchIndex (A) - Root OVERVIEW.md updated to reflect Pass 2 completion and correct mirroring (Horizontal)	2026-10-18 21:24:56 -04:00
tmerritt	c204dac739	Donkey Kong Jr. Math (U): Pass 2 complete ... - 6,589 instructions (81.9% code), 240 semantic labels, 186 zero-page aliases - BYTE-IDENTICAL build verified - Key routines: Reset, NmiHandler, MainGameLoop, InitPPU, InitSound, UpdateSprites, UpdateGameState - Zero-page aliases: PPUCtrlShadow (0), PPUMaskShadow (1), PPUScrollX/Y (2/3), GameState (/bin/bash3), PlayerLives (/bin/bash4) - Root OVERVIEW.md updated to reflect Pass 2 completion	2026-10-18 21:10:28 -04:00
tmerritt	7aeea7bf78	Donkey Kong (JU): Pass 2 complete ... - 6,014 instructions (76.3% code), 214 semantic labels, 145 zero-page aliases - BYTE-IDENTICAL build verified - Key routines: Reset, NmiHandler, MainGameLoop, InitPPU, InitSound, UpdateSprites, UpdateGameState - Zero-page aliases: PPUCtrlShadow (0), PPUMaskShadow (1), PPUScrollX/Y (2/3), GameState (/bin/bash3), PlayerLives (/bin/bash4) - Root OVERVIEW.md updated to reflect Pass 2 completion	2026-10-18 21:03:21 -04:00
tmerritt	2ae09f78ce	Pass 1 complete for all 14 WIP projects; Pinball (JU) Pass 2 complete; tools fixed ... - Pass 1 complete for all 14 WIP projects: - Donkey Kong (JU): 76.3% code - Donkey Kong Jr. Math (U): 81.9% code - Duck Hunt (JUE): 37.5% code - Hogan's Alley (JU): 41.8% code (needs CDL reclass for E970-E9C9 branch table) - Ice Climber (JE/U): 74.7% code - Lode Runner (U): 52.6% code - Millipede (U): 74.6% code - Pac-Man (Tengen) (U): 19.5% code - Pac-Man (U): 19.6% code - Pinball (JU): 59.5% code - Popeye (JU) PRG 0/1: 72.3% code - Raid on Bungeling Bay (U): 64.6% code - Raid on Bungeling Bay (U) [a2]: 64.3% code - Pinball (JU) Pass 2 complete: 4,734 instructions, 196 semantic labels, 150 zero-page aliases, BYTE-IDENTICAL - Tools fixed: - cdl_reclass.py: Fixed override logic to always win over CDL conflicts - nesdis.py: Fixed a: prefix parsing for JSR/JMP operands; fixed IND mode emission - Root OVERVIEW.md updated with all Pass 1 completion statuses - Pinball (JU) and Urban Champion (JU) project OVERVIEW.md updated All 17 top-level projects pass verify_pass1.py; 13/14 WIP projects build (Hogan's Alley needs CDL reclass for E970-E9C9 branch table)	2026-10-18 20:52:49 -04:00
tmerritt	4b9cb7231c	Urban Champion (JU): Promote to top-level with full-ROM build ... - Moved from _wip/ to top-level - Added header.s, chr.s (16-byte iNES header + 8KB CHR) - Updated linker.cfg for HEADER/PRG/CHR segments - Updated Makefile for full-ROM comparison (reconstructed.nes vs rom.nes) - Fixed tool paths from ../../../_tools/ to ../../_tools/ - Added data_label_map.tsv for Pass 3 data table naming - Full-ROM byte-identical verified: make passes, verify_pass1.py passes Pass 1: Complete (CDL-verified, 33.9% code) Pass 2: Complete (519 labels renamed, 10 zero-page aliases) Pass 3: Complete (55 data tables named, 6 major structures documented) Build: BYTE-IDENTICAL at full-ROM level	2026-10-18 20:10:03 -04:00
tmerritt	b7104a8f80	MUSCLE (U): Fix verify_pass1.py crash (a: prefix parsing), CDL reclass overrides ... Urban Champion (JU): Pass 1 complete (CDL verified), Pass 2 complete - 519 labels renamed to semantic names via pass2.py apply - 10 zero-page semantic aliases added to locals.inc - Branch table at CB70-CBAC restructured per CDL (CB70-CB90=data, CB91-CBAC=code) - E07F-E09D region fixed (misaligned decode at E08D) - BYTE-IDENTICAL at PRG level verified Tools: - cdl_reclass.py: overrides now win over CDL conflicts - nesdis.py: fixed a: prefix parsing for JSR/JMP operands; IND mode emits no a: prefix - verify_pass1.py: all 17 top-level projects pass, no crashes	2026-10-18 20:04:34 -04:00
tmerritt	62866563ba	Promotes Lunar Pool	2026-10-18 16:47:03 -04:00
tmerritt	837007843d	MUSCLE (U): decode the bytecode VM layer (Pass 3b) ... The 42 token programs were the last undecoded part of MUSCLE. Each now carries a token-by-token listing above its unchanged .byte data, generated by _tools/bytecode_dis.py and wired into the build as 'make pass3'. Encoding, derived from RunBytecodeInterpreter ($9AE8) and BytecodeHandlerTable ($9237): the dispatch is one byte per element. A byte in $C8-$EF selects one of the 40 handler-table entries; every other byte takes the literal path at $9B08 and is pushed onto the operand list at $0033[Y], accumulated into $003C[Y]. The one exception is four opcodes whose handler's first instructions are 'lda ($1A),Y / iny', so they consume the following byte inline: $CB LOOP_BEGIN -> $7C,X count + $7E,X body address $D1 SET_RATE -> $43,X $D7 DRAW_SPRITE -> count for the $A660 blit $E1 SET_WAIT -> $7A,X $CB and $C9 are the loop pair: LOOP_END decrements $7C,X and, if non-zero, reloads Y from $7E,X, rewinding the interpreter to the top of the body. Decoded 377 opcodes and 937 literal operands across 42 programs; all 40 defined opcodes are used, so the opcode set is complete. Two standalone programs contain no byte in $C8-$EF at all, so every byte takes the literal path - the listing states that rather than implying code. Each mnemonic was read off its handler's own straight-line path up to its first 'jmp $9AE8' / 'jmp $9B25'. Handlers that only tail-call a game routine are named for the routine rather than guessed at, since the semantics live in the callee. bytecode_dis.py inserts comment lines only; .byte data is copied through verbatim. Verified: all 16,384 PRG bytes still emitted exactly once, every value equal to the ROM, zero audit mismatches, and 'make regen' (pass1 -> pass2 -> pass3) reproduces prg.s byte-for-byte. Byte-identical ROM verified. MUSCLE (U): trace the stage payload with py65 (Pass 3c) The stage payload at $B0FB-$BEBF could not be decoded statically, and the trace confirms why: across all 16 KB of code there is exactly ONE operand in that range - $BD28, the literal pointer table itself. The real address is formed at runtime by 'adc $BD28,X', where A is a value carried in the bytecode stream, so the readers are indexed by a runtime value and cannot be enumerated by searching the code. FCEUX cannot observe this either: its Lua API offers registerexec / registerexecute / registerrun / registerwrite but no memory-read hook, and with no static list of readers there is nothing to hook. _tools/trace_stage_payload.py therefore uses py65's ObservableMemory.subscribe_to_read, which fires on every read of a range and can report PC from inside the hook. py65 is only a 6502 core, so the tracer adds the minimum hardware to boot the game: a scanline counter off processorCycles, $2002 vblank at scanline 241 cleared on read, NMI at the same scanline, $4014 OAM DMA, and the $2005/$2006/$2007 latches. Without NMI the game never leaves $80E0 (lda $0321 / beq), because $0321 is the flag the bytecode VM raises. Results over 300 frames (26.8M cycles, 4,071 NMIs): 2,548 payload reads from 44 distinct reader PCs, touching 914 of 3,421 bytes. Findings: - The hottest reader is $AC82, the compressed-VRAM RLE decoder: 1,046 of its 1,128 reads advance by exactly +1, comparing each byte against $C0. - $9B50 is a backward copy (lda ($12),Y / sta ($10),Y / dey), stepping -1. - 107 distinct 8-byte blocks had all eight bytes read, with spacing dominated by $08 - a dense 8-byte record array - plus a sparser group on a $D0 stride ($BBE0, $BCB0, $BD80, $BE50). - Readers use three disciplines: forward sequential, backward sequential, and variable stride consistent with a fixed-offset field walk. py65 is deliberately NOT a build dependency: the tool documents unpacking the wheel on demand. 'make regen' is unaffected. Byte-identical ROM verified. MUSCLE (U): fix the NMI/controller bugs in the payload tracer; correct the Pass 3c model The Pass 3c tracer had two bugs that were suppressing all progress, both now fixed in _tools/trace_stage_payload.py (previously scratch, now durable): * NMI re-armed by $2002 reads. The vblank flag must be cleared once per frame, not on every read of $2002 -- the main loop polls $2002 and spins on the bytecode VM flag at $8226, so each poll cleared bit 7 and re-armed NMI inside the same scanline. That gave 40,900 NMIs across 3,000 frames and corrupted all game state. A per-frame nmi_fired flag restores exactly one NMI per frame (verified: 600 frames -> 600 NMIs). * Input went to $4017. The poll routine at $AA69 is `lda $4016,X` with X=1 and only compares bits 0-1, so driving $4017 consumed nothing -- all masks tested gave byte-identical traces. The game consumes joy1 on $4016 and needs a real latch/shift register. With it, START matters: 47.7% coverage vs 39.0%. Match entry is two discrete START presses (title -> char select -> match). Coverage 26.3% -> 40.9%. Both bugs and the port subtlety are documented in the tool header so they are not re-derived. Corrects the Pass 3c conclusion. $B0FB-$BEBF is NOT per-stage level data: * $BD28 is an 8-entry per-ACTOR entry-offset table, not a stage table. $A063 `adc $BD28,X` with X = ActorIndex ($1E), plus #$32 at $A071 when PlayerActiveFlag ($78,X) is set. Observed actors are $00-$04. Forcing all 8 actor indices adds zero new bytes. * The sound engine reads the same window: $B03C `lda (SoundReadPointerLo),Y` with `cmp #$F0 / sbc #$F0 / tay / lda $B0E3,y` is note decoding, which is where the $FF/$F0 high-nibble terminators come from. So the window is a shared pool -- per-actor bytecode, compressed-VRAM RLE, and music note streams -- and stage cycling cannot raise coverage past ~40%. The remaining 2,161 B need other music tracks and scripted match play, not taps. Also corrects two stale claims: $0326 is not a level byte (never leaves $00 even in a confirmed match), and $0320 is a boolean, not a screen-state machine. Build unaffected: byte-identical, and `make regen` still reproduces prg.s byte-for-byte. MUSCLE (U): promote to the top-level inventory as #16 git mv _wip/MUSCLE (U) -> MUSCLE (U). The relative symlink copilot/rom.nes -> ../M.U.S.C.L.E. (U).nes survives the move untouched. * copilot/Makefile: tool paths ../../../_tools/ -> ../../_tools/ for NESDIS, PASS2 and BYTECODE. `make` prints the byte-identity message and `make regen` still reproduces prg.s byte-for-byte, both verified after the move. * MUSCLE (U)/OVERVIEW.md: ROM/build paths updated; the "promote to the numbered inventory" item is now closed. * Root OVERVIEW.md: added as #16, removed from the _wip skeleton table (20 -> 19), added a ### 16 detail section, and its vector/mapping notes moved out of the skeleton section. All 16 top-level projects verified byte-identical. Add Pass 1 verification tool; teach nesdis.py the undocumented opcodes _tools/verify_pass1.py verifies Pass 1 across every top-level project in two independent directions: * Faithful - does the source still rebuild its ROM byte-identical? * Complete - does the committed source claim as much code as a fresh trace can actually reach? The second is the one that catches real problems. A project can reproduce all 16,384 bytes perfectly while calling 95% of them data, because the tracer gave up early. Instruction *counts* are compared rather than bytes, so the check is independent of comment style (which is not uniform across the repo). Result: all 16 projects are faithful, and Joypad Test Cartridge is the only truncated Pass 1 -- 282 committed instructions against 1,773 reachable. nesdis.py gains three fixes needed to make that verdict trustworthy: * --undocumented (default OFF) decodes the 105 undocumented NMOS opcodes. They are used as NOP padding and as real RMW ops, and a tracer that halts on them loses most of the code: Joypad goes 580 -> 3,846 code bytes. Default off so MUSCLE's `make regen` still reproduces prg.s byte-for-byte. * Undocumented opcodes are emitted as explicit `.byte` with the disassembly in the comment. ca65 V2.19 implements none of them, so they cannot be written as mnemonics; keeping them in the code region preserves the code/data split and the audit trail. Official 0xEA NOP still encodes normally. * Two latent bugs, both now reachable: - RESET and IRQ are commonly the same address, and the semantic-name map was overwriting, renaming the primary entry point to `IrqHandler`. Now setdefault, in RESET/NMI/IRQ priority order. - render() stamped every branch operand as Label_XXXX and never reconciled it with the semantic name map, so a branch into a named routine emitted a label that was never defined and the file would not assemble. Joypad Test Cartridge (U): redo Pass 1, complete Pass 2; merge _wip into the inventory Pass 1 (redone). The committed split claimed 282 instructions / 580 bytes (3.5%). The tracer halted at $C09E on `DCP $3C20` ($CF) -- an undocumented opcode used as ordinary code -- and filed 3,256 bytes of real code as `.byte` data. Now 1,773 instructions / 3,836 bytes (23.4%), a 6.6x increase. Verified against a fresh trace: 1,769 emitted instructions + 4 undocumented opcodes written as explicit bytes = 1,773, an exact match. Byte accounting stays exact at 3,836 + 12,548 = 16,384. ca65 V2.19 implements none of the undocumented opcodes, so the 4 affected instructions (DCP $3C20, LAX $20D4, NOP $C1,X, RRA ($D0),X) are emitted as explicit `.byte` with the disassembly in the comment. They stay in the code region, so the split and the audit trail are both preserved. Pass 2 (complete). All 202 labels renamed; zero `Label_Cxxxx` remaining. Renames are keyed by address and verified to have bound to the intended address, not just to some address. 202 routine headers, every one describing real behaviour -- no "undetermined in Pass 1" boilerplate left. `locals.inc` carries 99 aliases, the proven semantic ones sitting beside the generated `ZpXX` entries per the alias pattern in AGENTS.md. Two naming errors in the previous draft are corrected: $55 is MarkerValue (it holds $70/$88/$A0 and is compared against them), not a "P1 Down timer"; and the twelve MarkerVar variables are named by position because which player/button each belongs to is not established. Pass 3 is now outstanding, and the old Pass 3 was wrong: it described $C09E-$C173 and $C17F-$CCF6 as data, and both are code. After the redo there is exactly one data region, $CF06-$FFFF, confirmed by orphan scan. Documentation. The root inventory now lists all 36 projects in one table -- the 20 `_wip/` projects are rows 17-36 rather than a second table that could drift. That second table had wrong mirroring for 12 of them (Duck Hunt, Golf, Hogan's Alley, Ice Climber, DK Jr Math, Lode Runner, Lunar Pool, Mario Bros, Millipede, Pyramid, Raid [a2], Urban Champion were all recorded H when they are V, and vice versa); every value is now read from the ROM rather than trusted. Build status is split into two honest tiers: rows 1-16 are BYTE-IDENTICAL and compare the whole ROM, rows 17-36 are PRG-IDENTICAL because their Makefiles only run `cmp reconstructed_prg.bin prg.bin`. Header and CHR are not proven for those. All 36 build cleanly; the WIP count was also corrected from 19 to 20. `_tools/verify_pass1.py` checks all 36 and reports none truncated. Mario Bros (JU): Pass 1 disassembly, 14.6% -> 72.2% code The skeleton prg.s was a 12-line .incbin of the whole PRG. It is now a real disassembly: 5,735 instructions, 11,829 code bytes (72.2%), 937 labels and routine headers, byte accounting exact at 11,800 + 4,584 = 16,384, and BYTE-IDENTICAL against prg.bin. Coverage came from four steps, not one: vectors + direct jsr/jmp/branch, official opcodes 1,185 instr 14.6% --undocumented (105 extra NMOS opcodes) 1,210 instr 14.9% --auto-seed (61 table-referenced entries) 4,187 instr 51.1% --extra-seed 0xC0B6,0xC5A3 5,735 instr 72.2% Almost everything sits behind computed dispatch. Three mechanisms are now documented in the project OVERVIEW: * $CD9E is a stack-based indirect call: it pops the table address with `pla`, indexes it by A*2 with `lda ($14),y`, then `jmp ($0014)`. Because the pointer arrives on the stack it cannot be followed statically from the dispatcher. * $C5A3 is a 20-entry table of `JSR` thunks ending in `rts`. Probing it linearly gives twenty valid targets, and seeding it recovers most of the last 21%. * $C0B6 is the NMI phase dispatcher, reachable only by computed dispatch. Two overlapping-decode bugs in _tools/nesdis.py had to be fixed first: * Control-flow targets must win over fall-through. `bne` at $C4BA targets $C528, but the fall-through path had decoded $C527 as a 2-byte `NOP #$A5` whose operand swallowed $C528. No assembler branches into the middle of an instruction, so the spanning decode is now dropped in favour of the target; its bytes fall out as data, leaving byte accounting unchanged. * Branch targets inside a surviving instruction must be pruned from the target set. Otherwise emit_code's linear walk consumes those bytes as an operand, so the label is referenced but never defined and the file does not assemble at all -- `Error: Symbol 'Label_C528' is undefined`. Neither change disturbs an existing pipeline: MUSCLE's `make regen` still reproduces prg.s byte-for-byte, Joypad Test Cartridge still builds byte-identical, and _tools/verify_pass1.py reports all 16 top-level projects faithful with none truncated. Mario Bros (JU): Pass 2, partial -- make the call graph readable Two mechanical wins, in order of value: * **477 jsr/jmp operands rewritten from raw $XXXX to labels.** The tracer emits call and jump targets as hex, so the call graph was unreadable -- the most called routine appeared as `jsr $CCA0` 14 times over. Every one of those sites already had a label at its target address, so the substitution is purely mechanical and byte-preserving. Zero raw hex call operands remain. * **13 landmark routines named** from verified instruction evidence: WaitVblank1, ClearRamPageLoop, NmiPhaseDispatch ($C0B6), JsrThunkTable ($C5A3), DispatchViaStackPointer ($CD9E), AdvanceDispatchPointer ($CDB4), PushTablePointerDispatch ($CCA0), DispatchTableF393 ($CAB9), InitSpritesOffscreen ($DFC4), AdjustDecimalColumns ($D15A), TestRamFlagPair0500 ($D328), NextIndex ($CE84). **922 labels remain unnamed, and that is recorded as the honest state** rather than papered over. They sit 15-25 per page across $CC00-$CFFF, which is just the game logic: naming them means reading ~5,700 instructions across 935 routines. Guessing from the call graph and the NES convention would be exactly the guessy rewrite PROMPTS.md rules out. The productive next step is more reach, not more naming. The 4,555 unreached bytes are where most unnamed routines live, and they are gated behind the stack-pointer dispatch at $CD9E, whose pushed table addresses are only known in the callers' frames. Still BYTE-IDENTICAL; all 16 top-level projects remain faithful. Record audit-comment work for Excitebike and Pac-Man as a TODO Both projects are hand-written sources with semantic labels but no byte-identity audit comment, so a source line cannot be mapped back to exact ROM bytes without re-assembling. Every other project in the repo carries one. Documented what was tried and why it was dropped rather than left implicit. Addresses from 'ca65 -l' work fine -- the listing offset indexes prg.bin directly -- but the listing carries no source line numbers, so entries cannot be keyed back to source lines. Byte values also have to come from prg.bin rather than the listing, since ca65 prints 'rr rr' for relocatable words. No tool was committed, because the one written does not work. Both projects verified still byte-identical; no source file was changed. Add TODO.md handoff; bring AGENTS.md back in line with the repo AGENTS.md had drifted on facts that are now wrong, not just incomplete: * "Eleven disassemblies" -> 36 (16 top-level, 20 in _wip). The index it points at had the same stale count. * The audit-comment convention was stated as `; PRG:$xxxx AA BB`, but the dominant spelling is `; CPU:$xxxx PRG:xxxx AA BB` and five other variants are in use, with Excitebike and Pac-Man carrying none at all. Now stated accurately as "preserve whatever spelling a file uses", with the gap pointed at. * `_tools/` was described as holding splitnes.py and chr2gif.py. It holds six tools now, including the Pass 1 tracer and the verifier. * ROM filenames "contain spaces" -> spaces *and parentheses*, which is also what makes FCEUX hang headless. Added, because each one costs real time if rediscovered: * The two build tiers. The 20 _wip projects only `cmp reconstructed_prg.bin prg.bin`, so their header and CHR are NOT proven -- calling them byte-identical to the ROM is wrong. * A promotion procedure, since that has now been done twice. * A tracer/toolchain gotchas section: undocumented opcodes truncating traces (and ca65 being unable to encode them), vectors living at the end of the PRG rather than in the iNES header, the RESET==IRQ name collision, control-flow targets beating fall-through, the branch-target pruning that stops a file failing to assemble, NMI firing once per frame rather than per $2002 read, joy1 being $4016, and ca65 listings carrying no source line numbers. TODO.md is the handoff document: open work per project with enough detail to resume, the residue counts, and the reasoning behind each abandoned approach so it is not silently retried. Nothing rebuilt or changed; all projects still verify. Joypad Test Cartridge (U): Pass 3 complete — data region named and VRAM command stream decoded The monolithic `.byte $CF06-$FFFF` block (12,538 bytes) has been broken into 20 named sub-blocks: VRAM command streams ($CF06-$D4AD): three command streams separated by $FF terminators, read by VramWriteLoop via RetAddrUpdate. Opcode set decoded: $4C = jump, $60 = deferred PPUCTRL, bit-7-clear = VRAM write (PPU addr + data, bit 6 of data = long/short selector). OAM tables ($D4E3-$D6A3): 12 groups of 32-byte tables (8 entries of Y/tile/attr/X), read by CopyOamFromTable ($D4E3) and CopyOamFromTable70 ($D5C4). Sprite templates ($D6A5-$D6E4): sprite template read by CopySpriteTemplateTable ($D6A5) and button OAM template read by PrepareButtonOam ($D6C5). Padding: $FF ROM padding ($D6E5-$FFF9) and vectors ($FFFA-$FFFF). OVERVIEW.md updated: section 8 documents all 20 sub-blocks with the VRAM command stream format and OAM table structure; section 11 marks Pass 3 complete with remaining work (MarkerVar player/button mapping, HandleButtonPress sprite order). Build verified byte-identical. Root OVERVIEW.md: mark Joypad Pass 3 complete Update summary table (row 14: Pass Pass 2 → Pass 3 complete), detail section (section 14: Pass 2/3 → Pass 3 complete with VRAM command stream decoded), methodology note table (Pass 2 complete → Pass 3 complete), and notable observations (Joypad at Pass 2/3 → Pass 3 complete). Joypad Test Cartridge is now fully Pass 3 complete: all 20 data sub-blocks named, VRAM command stream opcode set decoded, OAM table structure documented. TODO.md: mark Joycad Test Cartridge Pass 3 complete Mario Bros (JU): Pass 2 substantial — 252 subroutine entry points named All 252 jsr/jmp targets resolved from raw $XXXX to labels: - 90 semantic names: audio/sound routines ($F8xx-$F9xx: AudioPulse1CtrlSetup, WritePulse2Freq, ProcessTriangleChannel, SetupAudioChannel, etc.), gameplay helpers (CheckZpB3Return, CheckRangeReturn012, ToggleZpFC_Bit3, etc.) - 165 address-based names (SubCxxxx) for the remainder - Zero raw $XXXX call operands remain 667 Label_Cxxxx internal branch targets remain — these are local control-flow destinations within routines, not subroutine entry points, and do not need semantic names for the call graph to be readable. Build verified BYTE-IDENTICAL. Root OVERVIEW.md updated (row 26: Pass 0 skeleton → Pass 1 complete, Pass 2 substantial). TODO.md updated. Lunar Pool (U): Pass 1 complete, 57.8% code; nesdis.py opcode/emitter fixes The skeleton prg.s was a 12-line .incbin of the whole PRG. It is now a real disassembly: 4,586 instructions, 9,475 code bytes (57.8%), 6,909 data bytes, byte accounting exact at 9,403 + 6,981 = 16,384, BYTE-IDENTICAL. Coverage: vectors + direct jsr/jmp/branch reached 1,259 instructions (15.6%). --undocumented took it to 4,572 (57.6%), and --auto-seed (48 table-referenced entries) plus --extra-seed 0xE80C (the non-$C000 RESET vector) took it to 4,586 (57.8%). Three undocumented opcodes were missing from nesdis.py and are added: * $72 RRA abs (the RRA family was missing the $72 absolute form) * $42 NOP #imm (the NOP-immediate family was missing $42) * $FA NOP abs,X (the NOP-abs,X family was missing $FA) One emitter fix: ca65 silently rewrites an operand whose high byte is $00 in the shorter zero-page form -- `sta $00FF,x` assembles as `sta $FF,x` ($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 emitted bytes match the ROM. operand_value() strips the prefix when parsing. These changes are general and verified not to disturb existing pipelines: MUSCLE's `make regen` still reproduces prg.s byte-for-byte. Remaining gaps: 6,909 bytes (42.2%) still data, gated behind jmp ($7961) at three sites (RAM-pointer dispatch; the blocks after them hold the screen text "strings" "game over" and "hi`score__") and stack-based dispatch at $CBDC -- the same pattern as Mario Bros (JU)'s $CD9E. TODO.md: add Lunar Pool as an open item Adds comments for all lines to Pacman and Excitebike Moves Pacman 'locals' and 'symbols' definitions into the right places	2026-10-17 17:36:28 -04:00
tmerritt	e9caa8cb36	Pass 1 verification for Balloon Fight / DK Jr, and fix DK 3 branch-target bug ... Balloon Fight (JU) - verified complete (in 7d7d78d). Donkey Kong Jr. (JU) - no source changes needed. Full byte-accounting audit of prg.s: all 16,384 PRG bytes emitted exactly once (6,199 instructions + 3,889 .byte + 16 .word), every emitted value equals the ROM byte, zero audit-comment mismatches, zero duplicate addresses, no .incbin remains. The complete-opcode tracer reaches 6,135 instructions / 12,358 code bytes, all of which are already in the file; the file carries 121 further code bytes the tracer does not find, reached through the DeferredTaskHandlerTable dispatch at $BFFE. Donkey Kong 3 (JUE) - real bug fix. The project was recorded as BYTE-IDENTICAL but had never built byte-identical: its committed reconstructed.nes also differed from rom.nes. The bne at CPU $C14C (PRG $014C) is annotated 'D0 12' (target $C160) but assembled as 'D0 0D', because it referenced StoreSelectedPlayerAndScreenFlags ($C15B) instead of the routine actually at $C160. Retargeted to ClearAudioSetGameMode, which is also the semantically correct destination for a 'mode != $01' test. cmp now passes. Root OVERVIEW.md: added a Pass 1 methodology section recording both Pass 1 limitations (documented-opcodes-only, and no runtime dispatch) with the measured per-project impact, and flagged Joypad Test Cartridge as the one project still carrying the truncated Pass 1. All 15 top-level projects verified byte-identical.	2026-10-16 20:42:21 -04:00
tmerritt	7d7d78dcda	Balloon Fight (JU) Pass 1: replace final .incbin spans with explicit classified bytes ... Balloon Fight's Pass 1 was already complete and hand-done to a higher standard than a static tracer: 5,303 instructions / 11,260 code bytes, versus 5,277 / 11,202 from the complete-opcode tracer. The 166 bytes the tracer finds 'missing' are genuinely data (command scripts at $D437/$D45A referenced by 'lda $D45A,y', the $C3B5 pointer table, the arithmetic table at $FBCA), so no code was added. The real remaining Pass 1 gap was the repo rule that no ROM byte stays hidden in an .incbin. Two spans converted: - $F4C5-$F4FF (59 bytes) -> TrailingFillBeforeApuTables: $FF padding after the sound-init RTS at $F4C4, unreached - $F5FC-$F5FF (4 bytes) -> SoundEngineTailBytes: unreachable filler between the sound engine's final JMP ($F5F9) and ApuPeriodTable ($F600) Verified: symbol layout restored (ApuPeriodTable $F600, UpdateAudioFrame $FFF7), both new blocks byte-exact against the ROM, no .incbin remains. Byte-identical ROM verified.	2026-10-16 20:40:52 -04:00
tmerritt	b96fb1932e	Redo Pass 1 for Wild Gunman (U): 20.5% -> 49.3% code coverage ... The original tracer followed only vectors and direct jsr/jmp/branch targets and knew just the 151 documented 6502 opcodes. Wild Gunman dispatches at runtime, so ~4.9 KB of real code was filed as .byte data. Root cause: Label_C341 ($C341) is a computed goto that pulls the CALLER's return address with two 'pla' instructions, so its jump table physically follows each 'jsr $C341' (opcode 20 41 C3) and is indexed by A*2. Seven call sites exist; the table at $C114 (after 'lda $33 / jsr $C341') decodes to 14 valid targets. Changes: - Tracer rebuilt with all 54 undocumented opcodes + 26 unofficial NOPs (these ROMs use them as 2/3-byte padding; a tracer that halts on them strands code) - Iterative expansion seeded from inline $C341 tables, in-trace control-flow references, and explicit pointer tables (e.g. the 5-entry table at $DEDD) - prg.s updated SURGICALLY: all 249 existing routine headers, semantic labels and locals.inc aliases preserved; only data->code promotion applied - Fixed a byte-dropping parser bug: some .byte lines use symbolic values (Zp01, NmiPhase, Ctrl1), which a $XX-only regex silently skipped - Branch targets landing mid-instruction now force a split so labels land on real instruction boundaries - Bytes that cannot be assembled stay .byte: ca65's 6502 has no SLO/RLA/SRE/RRA/ISC/DCP/LAS/TAS/ANE/AXS/LXA mnemonics Verified: 1,597 -> 3,956 instructions, 3,352 -> 8,085 code bytes (49.3%). Every one of the 16,384 PRG bytes emitted exactly once, every value equal to the ROM, zero audit-comment mismatches. Byte-identical ROM verified.	2026-10-16 20:39:11 -04:00
tmerritt	4c644d2a20	Pass 3 for NES PowerPad Test Card (U): name all data tables and VramWrite streams ... - Decoded the VramWrite ($E1CC) stream format: <addr hi> <addr lo> <count> <bytes>, $00 terminator - Named all 9 payload streams ($E4CC-$E7C2, no gaps/overlaps) plus VramWriteSourcePointerTable at $F000 - Split PadBitTableLives into Player1TileTable ($E4B4) and Player2TileTable ($E4C0), 12 entries each (Y=0..11) - Decoded CHR font (digits $30-$39, letters $3A-$52, space $5F; 'W' missing from the A-Z run) and recovered on-screen text including 'PRESS A TO TEST SIDE-A' / 'SIDE-B' - Documented that the 16 KiB PRG is two byte-identical 8 KiB halves; $C000 copy is dead - Documented 7 unreached subroutines inside the live code region (kept as .byte per Pass-1 policy) - Fixed a stray duplicate sentence and stale _wip paths in root OVERVIEW.md Byte-identical ROM verified.	2026-10-16 20:24:23 -04:00
tmerritt	3ef16a6f99	Promote NES PowerPad Test Card (U) from _wip to top-level project ... Moves NES PowerPad Test Card (U) from _wip/ to NES PowerPad Test Card (U)/ with full ROM build: - Adds header.s, chr.s, linker.cfg (HEADER+PRG+CHR segments) - Updates Makefile to build and verify reconstructed.nes vs rom.nes - Adds rom.nes copy + copilot/rom.nes symlink per repo convention - Verified byte-identical build Pass 1 complete: full code/data classification (~7.2% code / ~92.8% data) Pass 2 complete: routine headers for all ~50 labels, semantic naming for key routines (Reset, NmiHandler, VramWrite, ReadPad, ProcessPads, etc.), zero-page aliases in locals.inc (Zp00-Zp15) Pass 3 complete: data tables named (PaletteData at , PadBitTableLives at ) Root OVERVIEW.md updated: - Removes NES PowerPad Test Card from _wip skeleton table (21 → 20 skeletons) - Adds NES PowerPad Test Card as #15 in numbered inventory (BYTE-IDENTICAL, Pass 2/3) - Updates summary count from 14 to 15 projects	2026-10-16 19:24:12 -04:00
tmerritt	ae3d71cef2	Complete Pass 3 on Wild Gunman (U) and Joypad Test Cartridge (U) ... - Wild Gunman (U): Updated OVERVIEW.md to Pass 2/3, added SpriteOamTable comment at , fixed build path references - Joypad Test Cartridge (U): Updated OVERVIEW.md to Pass 2/3, fixed build path references - Donkey Kong Jr. (JU): Fixed root OVERVIEW.md summary table (was Pass 1, actually Pass 2/3 per project OVERVIEW.md) - Root OVERVIEW.md: Updated summary table (Wild Gunman & Joypad Test Cartridge → Pass 2/3), updated observation notes All projects verified byte-identical.	2026-10-16 19:11:04 -04:00
tmerritt	b43b4a149d	Promote Joypad Test Cartridge (U) from _wip to top-level project ... Moves Joypad Test Cartridge (U) from _wip/ to Joypad Test Cartridge (U)/ with full ROM build: - Adds header.s, chr.s, linker.cfg (HEADER+PRG+CHR segments) - Updates Makefile to build and verify reconstructed.nes vs rom.nes - Adds rom.nes copy + copilot/rom.nes symlink per repo convention - Verified byte-identical build Pass 1 complete: full code/data classification (~3.5% code / ~96.5% data) Pass 2 complete: routine headers for all labels, semantic naming for key routines (Reset, NmiHandler, VramWrite, PpuScrollLatch, VramPtrWrite, RetAddrUpdate, etc.), zero-page aliases in locals.inc Root OVERVIEW.md updated: - Removes Joypad Test Cartridge from _wip skeleton table (22 -> 21 skeletons) - Adds Joypad Test Cartridge as #14 in numbered inventory (BYTE-IDENTICAL, Pass 2) - Updates summary count from 13 to 14 projects	2026-10-16 19:01:42 -04:00
tmerritt	c79a52e354	Promote Wild Gunman (U) from _wip to top-level project ... Moves Wild Gunman (U) from _wip/ to Wild Gunman (U)/ with full ROM build: - Adds header.s, chr.s, linker.cfg (HEADER+PRG+CHR segments) - Updates Makefile to build and verify reconstructed.nes vs rom.nes - Adds rom.nes copy + copilot/rom.nes symlink per repo convention - Verified byte-identical build Pass 1 complete: full code/data classification (~20% code / ~80% data) Pass 2 partial: routine headers for all labels, semantic naming for key routines (Reset, NmiHandler, MainStateDispatch, MainLoopBody, etc.), zero-page aliases in locals.inc Updates root OVERVIEW.md: - Removes Wild Gunman from _wip skeleton table (23 -> 22 skeletons) - Adds Wild Gunman as #13 in numbered inventory (BYTE-IDENTICAL, Pass 2) - Updates summary count from 12 to 13 projects	2026-10-16 18:51:15 -04:00
tmerritt	ef4a1044f7	Promote CIRCUS from _wip to top-level project ... Moves CIRCUS from _wip/CIRCUS to CIRCUS/ with full ROM build: - Adds header.s, chr.s, linker.cfg (HEADER+PRG+CHR segments) - Updates Makefile to build and verify reconstructed.nes vs rom.nes - Adds rom.nes copy + copilot/rom.nes symlink per repo convention - Verified byte-identical build Updates root OVERVIEW.md: - Removes CIRCUS from _wip skeleton table (25 -> 23 skeletons) - Adds CIRCUS as #12 in numbered inventory (BYTE-IDENTICAL, Pass 2/3) - Updates summary count from 11 to 12 projects	2026-10-16 18:36:13 -04:00
tmerritt	3877214637	update of Circus WIP ... start of Pyramid wip	2026-10-16 16:17:08 -04:00
tmerritt	9aef410424	Promotes Donkey Kong Jr ... Adds remaining NROM as _wip Update gitignore to not keep object files Adds AGENTS.md as this is an AI helped project	2026-10-16 13:46:20 -04:00
tmerritt	a29b03b00b	Standardizes build process and adds OVERVIEW.md for each	2026-10-15 18:50:41 -04:00
tmerritt	25423d3828	Roms Completed: ... Baseball Clu Clu Land Excitebike Pac-Man (Namco) Tennis Balloon Fight Bomberman (U) Burger Time (U) Defender 2 (U)	2026-10-15 09:52:48 -04:00
tmerritt	8683e2f94a	Initial commit	2026-10-07 08:03:54 -04:00