From e1e10561b10ce734da752a240205ab54d16a31fd Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 12 Apr 2026 20:53:36 +0000
Subject: [PATCH] docs: scrub remaining stale AST-codegen references
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fallout from removing the `--use-ast` flag and the AST codegen.
Four references in `docs/future-work.md` and one in `plan.md` were
still implying a parallel AST code path existed:

- `future-work.md` "--debug CLI flag wired" entry — said the flag
  threads through `CodeGen::with_debug` (the old AST codegen's
  builder). Updated to `IrCodeGen::with_debug`.
- `future-work.md` IR debug.log/assert entry — had a parenthetical
  "(same behavior as AST codegen)" that no longer makes sense
  without an AST codegen to compare against. Dropped.
- `future-work.md` inline assembly entry — said "Both IR and AST
  codegen splice parsed instructions directly into the output
  stream." There's only the IR codegen now. Updated.
- `future-work.md` `on scanline(N)` entry — described scanline
  handling as "codegen (MMC3 IRQ vector wiring) is still TODO."
  That wiring has been in place for a while: the IR codegen
  emits `__irq_user` + `__ir_mmc3_reload` with per-state
  dispatch, and `examples/scanline_split.ne` and
  `examples/mmc3_per_state_split.ne` both exercise it in the
  jsnes smoke test. Rewrote the entry to match reality.
- `plan.md` M2 "Compiler phases built" list — had "Codegen from
  IR (replacing direct AST codegen)." The present-tense
  parenthetical read as if AST codegen still existed; stripped
  it. M1's "direct AST → 6502, skip IR for this milestone" line
  is left as a historical milestone scope description.

One intentional mention remains: `future-work.md` "Recently
completed" bullet explicitly notes the AST-based path and the
`--use-ast` flag were removed. That's the correct tombstone.

https://claude.ai/code/session_014Z5y3Q9krLcAxYpZQJhZ5V
---
 docs/future-work.md | 19 +++++++++++--------
 plan.md             |  2 +-
 2 files changed, 12 insertions(+), 9 deletions(-)

diff --git a/docs/future-work.md b/docs/future-work.md
index 8c12444..46af9c2 100644
--- a/docs/future-work.md
+++ b/docs/future-work.md
@@ -314,7 +314,7 @@ These items were documented as future work but have since been implemented:
 - **debug.log / debug.assert** — parses into `Statement::DebugLog` /
   `Statement::DebugAssert`, codegen emits runtime writes to $4800 when
   `--debug` is set, stripped in release mode
-- **--debug CLI flag wired** — threads through `CodeGen::with_debug`
+- **--debug CLI flag wired** — threads through `IrCodeGen::with_debug`
 - **IR-based codegen** — `src/codegen/ir_codegen.rs` walks `IrProgram` and
   emits 6502 for every IR op: load/store, arithmetic, comparisons, arrays,
   calls, draws, input (P1 and P2), scroll, debug.log/assert, state
@@ -330,8 +330,8 @@ These items were documented as future work but have since been implemented:
 - **IR scroll support** — `scroll(x, y)` lowers to `IrOp::Scroll(x, y)`
   which emits two PPU $2005 writes in IR codegen
 - **IR debug.log / debug.assert** — new `IrOp::DebugLog(temps)` and
-  `IrOp::DebugAssert(cond)` variants, emitted as $4800 writes in debug
-  mode and stripped in release (same behavior as AST codegen)
+  `IrOp::DebugAssert(cond)` variants, emitted as $4800 writes in
+  debug mode and stripped in release
 - **Asset pipeline @binary / @chr loading** — `resolve_sprites()` reads
   raw binary files and converts PNGs via `png_to_chr()`. Missing files
   are silently skipped (documentation-friendly)
@@ -354,15 +354,18 @@ These items were documented as future work but have since been implemented:
   allocator stops at `$0800`; overflow emits E0301 at the declaration
 - **E0505 multiple start declarations** — parser rejects a second
   `start X` token
-- **`on scanline(N)` parsing** — `state { on scanline(240) { ... } }`
+- **`on scanline(N)` handlers** — `state { on scanline(240) { ... } }`
   parses and populates `StateDecl::on_scanline`; analyzer emits E0203
-  if the game isn't using MMC3. Codegen (MMC3 IRQ vector wiring) is
-  still TODO
+  if the game isn't using MMC3. The IR codegen now emits the full
+  MMC3 IRQ vector glue: per-state dispatch in `__irq_user` and a
+  `__ir_mmc3_reload` helper that picks the right `$C000` latch value
+  based on `current_state`. See `examples/scanline_split.ne` and
+  `examples/mmc3_per_state_split.ne`.
 - **Inline assembly** — `asm { ... }` blocks. The lexer captures the
   body as a raw `AsmBody` token; `src/asm/inline_parser.rs` provides a
   minimal 6502 mnemonic parser that handles every addressing mode the
-  codegen emits. Both IR and AST codegen splice parsed instructions
-  directly into the output stream
+  codegen emits. The IR codegen splices parsed instructions directly
+  into the output stream
 - **Enum types** — `enum Name { V1, V2, ... }` declares u8 constants
   with values equal to declaration order. Variant names are flattened
   into the global symbol table
diff --git a/plan.md b/plan.md
index a8ca22a..3d2cc65 100644
--- a/plan.md
+++ b/plan.md
@@ -932,7 +932,7 @@ start Main
 - Full analyzer (call graph, depth limits, recursion detection, state validation)
 - IR lowering
 - Basic optimizer (constant folding, dead code)
-- Codegen from IR (replacing direct AST codegen)
+- Codegen from IR
 - Memory map report
 - Call graph report