romdevtools 0.42.0 → 0.44.0

package/CHANGELOG.md

@@ -4,6 +4,59 @@ All notable changes to `romdevtools`. Dates are release dates.
 (Published as `romdev-mcp` through 0.11.0; renamed to `romdevtools` in 0.13.0 —
 the `romdev-mcp` bin is kept as an alias.)
 
+## 0.44.0 — 2026-06-25
+
+### v0.41.0 feedback (part 2) — RE-session ergonomics
+
+- **`watch({on:'range'})` dedupe + digest.** A range watch over a churny window
+  flooded with per-frame writes (a counter inc'd at one PC → hundreds of
+  near-identical rows). New `dedupe:true` collapses identical `(pc,address,value)`
+  events to one row with an `occurrences` count (parity with `on:'dma'`), and
+  `distinctPCsOnly:true` returns JUST the per-PC digest (`byPC[{pc,count,
+  sampleAddress,sampleValue}]`) and suppresses the raw event list — the
+  token-cheap "which routines touch this range?" answer. (133737 N1)
+- **`catalog({op:'status'}).capabilities` build-toolchain flags.** Added
+  `cc65Build`, `ld65Link`, `da65Disasm` so an agent knows before calling
+  `build`/`disasm` whether the toolchain is present (the analysis subtargets
+  cfg/xrefs/functions/decompile are all da65-backed). (184553 #1, 190223 #1)
+- **`cheats` slot lifecycle.** `apply` now REPLACES an active freeze on the same
+  address instead of stacking a second one that fights for the byte
+  (`replacedSameAddress`), and new `op:'remove'` drops ONE cheat by slot/code
+  without `clear`'s nuke-all. (213831 #3)
+- **`breakpoint` `settleFrames`.** Back-to-back driven runs on the same live host
+  could inherit the prior run's held-button shadow on frame 0 (false-positiving a
+  negative control). `settleFrames:N` releases the pad to neutral and steps N
+  frames before the run so it starts clean. (213831 #1)
+- **`breakpoint({on:'pc'})` miss-note** now names the negative-control case: a
+  `hit:false` may be the DESIRED result (proving input X does NOT reach a branch),
+  not a wrong-address failure. (213831 #2)
+- Confirmed already shipped (0.42.0): hex-string `address`/`offset` params, the
+  base capabilities map. (133737 N2, 002129 #2)
+
+## 0.43.0 — 2026-06-25
+
+### Port engine is now GENERIC (any source → any target), not NES→SNES-only
+
+The recompiler was rebuilt around a small intermediate representation (IR): a
+LIFTER turns a source-CPU disassembly into IR; an EMITTER turns IR into target-CPU
+assembly. Adding a platform PAIR is now one lifter + one emitter, not a bespoke
+recompiler. NES→SNES and the new NES→Genesis run through the *same* pipeline.
+
+- **`disasm({target:'recompile', targetPlatform})`** — `'snes'` is the 1:1
+  emulation-mode port (with the PPU shim/runtime render layers); **`'genesis'` is a
+  real 6502→68000 LOGIC translation** — `lda #$42`→`move.b #$42,d0`,
+  `sta $0010`→`move.b d0,($FF0010).l`, branches/jsr/jmp mapped, the NES address
+  space mapped into Genesis work RAM at `$FF0000` (which IS the Tier-1 RAM-diff
+  oracle's mirror). Verified end-to-end: a real NES homebrew's reset routine
+  translates to m68k (0 residue), builds with vasm68k, and BOOTS in gpgx with the
+  translated logic executing (RAM writes land).
+- The presentation seam (PPU/APU) is stubbed for non-SNES targets — it's a LOGIC
+  port; verify with `frame({op:'compareRam'})` vs the NES original. A render
+  runtime per target is a later layer (NES-PPU-on-SNES is the template).
+- Unsupported targets fail with the supported set. `recompileNesToSnes` now
+  delegates to the generic engine (same image; existing SNES tests unchanged).
+- New: `src/analysis/recompile/` (ir, lift-6502, emit-65816, emit-m68k, index).
+
 ## 0.42.0 — 2026-06-24
 
 ### v0.41.0 feedback batch + the NES→SNES port engine

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "romdevtools",
-  "version": "0.42.0",
+  "version": "0.44.0",
   "description": "Tool server giving coding agents full control of homebrew ROM development AND reverse-engineering/romhacking across 14 retro platforms (NES, SNES, GB, Genesis, Atari, C64, PC Engine, MSX, ...) via WASM toolchains + emulator cores. Use over plain HTTP, as an Agent Skill, or as an MCP server.",
   "type": "module",
   "main": "src/mcp/server.js",

package/src/analysis/recompile/emit-65816.js

@@ -0,0 +1,105 @@
+// IR → 65816 (SNES asar) emitter. The 65816 boots in 6502 EMULATION mode, so a
+// 6502-sourced IR is "near-1:1": reg/branch/jump/call/return nodes re-emit the
+// original mnemonic verbatim, and hwreg (the MMIO seam) becomes a call into the
+// NES-PPU-on-SNES runtime. This emitter reproduces the byte-for-byte body the
+// original monolithic recompile-65816 produced — it's the same output, reached
+// through the generic IR so OTHER source ISAs (whose lifters emit the same IR)
+// could target 65816 too, and so 6502 can target OTHER CPUs via a different emitter.
+//
+// Plain JS ESM + JSDoc.
+
+import { IR } from "./ir.js";
+import { NES_REGISTERS } from "../../platforms/common/registers.js";
+
+/** The native 6502 mnemonic for each IR `reg` node is carried on the node itself
+ *  (node.mnemonic); for 65816 emulation mode we re-emit it unchanged. */
+function emitRegNode(node) {
+  const { mnemonic, operand } = node;
+  return `        ${mnemonic}${operand ? "     " + operand : ""}`;
+}
+
+/** Emit the seam call(s) for one hwreg access — identical to the original
+ *  emitSeamAccess: A holds the value (writes) / receives it (reads); the register
+ *  low byte goes in X so one seam routine handles the whole file. */
+function emitHwReg(node) {
+  const { access, reg, via } = node;
+  const regName = NES_REGISTERS[reg] || `REG_${reg.toString(16)}`;
+  const lowByte = `#$${(reg & 0xff).toString(16).padStart(2, "0")}`;
+  const lines = [`        ; seam: ${via} $${reg.toString(16)} (${regName})`];
+  if (access === "write") {
+    if (via === "sta") {
+      lines.push(`        ldx     ${lowByte}`, `        jsr     NES_PPU_WRITE`);
+    } else { // stx / sty
+      lines.push(`        txa`, `        ldx     ${lowByte}`, `        jsr     NES_PPU_WRITE`);
+    }
+  } else { // read: lda / ldx / ldy / bit
+    lines.push(`        ldx     ${lowByte}`, `        jsr     NES_PPU_READ`);
+    if (via === "bit") lines.push(`        ; (bit set N/V from the read value)`);
+  }
+  return lines;
+}
+
+/**
+ * Emit the 65816 body from an IR program. Returns the body text (functions only;
+ * the LoROM wrapper/seam/vectors are added by the orchestrator via emitMainAsm).
+ * A leading label on a node is emitted as its own `label:` line, matching the
+ * original output exactly so the existing NES→SNES tests stay green.
+ * @param {Array<object>} ir
+ * @returns {string}
+ */
+export function emit65816Body(ir) {
+  const out = [];
+  for (const node of ir) {
+    // node-level label (rides on instruction/branch/etc nodes)
+    if (node.label && node.op !== IR.LABEL) out.push(`${node.label}:`);
+    switch (node.op) {
+      case IR.LABEL:
+        out.push(`${node.name}:`);
+        break;
+      case IR.REG:
+        out.push(emitRegNode(node));
+        break;
+      case IR.BRANCH:
+        // 6502 branch mnemonics ARE valid 65816 — re-emit verbatim. node.raw holds
+        // the original "bne L8016"; recover the mnemonic from it for fidelity.
+        out.push(`        ${branchMnemonic(node)}     ${node.target}`);
+        break;
+      case IR.JUMP:
+        out.push(`        jmp     ${node.target}`);
+        break;
+      case IR.CALL:
+        out.push(`        jsr     ${node.target}`);
+        break;
+      case IR.RET:
+        out.push(node.kind === "interrupt" ? "        rti" : "        rts");
+        break;
+      case IR.HWREG:
+        out.push(...emitHwReg(node));
+        break;
+      case IR.PASSTHROUGH:
+        out.push(node.text);
+        break;
+      case IR.REFUSE:
+        // Visible marker so the asm still SHOWS where logic was dropped (residue
+        // is also reported structurally by the orchestrator).
+        out.push(`        ; UNTRANSLATED: ${(node.raw || "").trim()}  (${node.reason})`);
+        break;
+      default:
+        break;
+    }
+  }
+  return out.join("\n");
+}
+
+/** Recover the 6502 branch mnemonic for an IR branch node from its raw text (the
+ *  cond→mnemonic map is 1:1 for 65816 emulation mode). */
+function branchMnemonic(node) {
+  const m = (node.raw || "").trim().match(/^[a-zA-Z_]\w*:\s*([a-z]{3})|^([a-z]{3})/);
+  if (m) return (m[1] || m[2]);
+  // fall back from the ISA-neutral cond
+  return { eq: "beq", ne: "bne", cc: "bcc", cs: "bcs", mi: "bmi", pl: "bpl", vc: "bvc", vs: "bvs" }[node.cond] || "bne";
+}
+
+/** This emitter's target ISA + a human label (for the registry + diagnostics). */
+export const TARGET_ISA = "65816";
+export const TARGET_PLATFORM = "snes";

package/src/analysis/recompile/emit-m68k.js

@@ -0,0 +1,295 @@
+// IR → m68k (Genesis / Mega Drive, vasm68k syntax) emitter. This is the proof
+// that the recompile engine is GENERIC: a 6502-sourced IR targets the 68000 here
+// through the SAME pipeline that targets the 65816 — no second bespoke recompiler.
+//
+// Unlike NES→SNES (65816 runs 6502 logic 1:1 in emulation mode), NES→Genesis is
+// REAL ISA translation: the 6502's 8-bit register file is modeled on 68000 data
+// registers, and each abstract op becomes the equivalent 68000 instruction. The
+// 6502 address space (zero page + RAM + the parts of $0000-$1FFF a game touches)
+// is mapped to a contiguous block of 68000 work RAM (NES_RAM), so a `sta $05`
+// becomes `move.b d0, (NES_RAM+5).w` — and that block IS the Tier-1 RAM-diff
+// oracle's mirror (run original + port, byte-diff this block per frame).
+//
+// SCOPE (phase 1, logic only): the documented 6502 set that maps mechanically;
+// the PPU/APU seam is STUBBED (writes drop, $2002 read → $80 so vblank loops
+// exit), exactly like the SNES phase-1 path — presentation is a later runtime.
+// Decimal mode, RMW-on-MMIO, and undocumented opcodes are REFUSED upstream by the
+// lifter, so they never reach here.
+//
+// Register model:  6502 A → d0   X → d1   Y → d2   (8-bit, used via .b)
+//                  6502 P (flags) → the 68000 CCR is set by the move/alu itself;
+//                  we do NOT model the full 6502 flag semantics — branches use the
+//                  CCR the prior op left, which is correct for the common
+//                  load→branch / compare→branch idioms (the same pragmatic bound
+//                  the SNES emulation-mode path relies on hardware for).
+//
+// Plain JS ESM + JSDoc.
+
+import { IR } from "./ir.js";
+import { ABSTRACT, COND } from "./ir.js";
+
+/** Base of the mapped 6502 address space inside 68000 work RAM. Genesis work RAM
+ *  is $FF0000-$FFFFFF; we park the 8KB NES-visible space at $FF0000. A 6502
+ *  address N reads/writes (NES_RAM + N). */
+const NES_RAM = 0xff0000;
+
+/** 6502 registers → 68000 data registers. */
+const ACC = "d0", X = "d1", Y = "d2";
+
+/** Translate a 6502 operand to a 68000 source/dest effective address.
+ *  Returns { ea, imm } — `imm` true if it's an immediate (#...). Indexed modes
+ *  (`$addr,x` / `$addr,y`) use the index register as a 68000 address-register
+ *  displacement via a scratch address reg a0. */
+function operandToEa(operand) {
+  if (operand == null) return { ea: null, imm: false };
+  const op = operand.trim();
+  // immediate: #$nn  →  #$nn
+  let m = op.match(/^#\$([0-9A-Fa-f]+)$/);
+  if (m) return { ea: `#$${m[1]}`, imm: true };
+  m = op.match(/^#(\d+)$/);
+  if (m) return { ea: `#${m[1]}`, imm: true };
+  // absolute / zero-page, optionally indexed
+  m = op.match(/^\$([0-9A-Fa-f]+)\s*(?:,\s*([xy]))?$/i);
+  if (m) {
+    const addr = parseInt(m[1], 16);
+    const idx = m[2] ? m[2].toLowerCase() : null;
+    if (!idx) {
+      const abs = NES_RAM + addr;
+      // word-sized absolute EA: (abs).l (work RAM is in the high $FFxxxx range)
+      return { ea: `(${hex(abs)}).l`, imm: false, addr };
+    }
+    // indexed: a0 = NES_RAM + addr + index_reg ; EA = (a0)
+    return { ea: null, imm: false, addr, idx };
+  }
+  // a bare label (branch/jump target handled elsewhere) — pass through as a symbol
+  return { ea: op, imm: false, symbol: true };
+}
+
+const hex = (n) => "$" + (n >>> 0).toString(16).toUpperCase();
+
+/** Emit the indexed-address setup into a0 for `$addr,x|y`, returning the EA "(a0)". */
+function indexedEaLines(addr, idx, out) {
+  const ireg = idx === "x" ? X : Y;
+  out.push(`        move.l  #${hex(NES_RAM + addr)},a0`);
+  out.push(`        move.b  ${ireg},d3`);
+  out.push(`        ext.w   d3`);
+  out.push(`        adda.w  d3,a0`);
+  return "(a0)";
+}
+
+/** Emit one IR `reg` (data/ALU/transfer/flag) node as 68000 instructions. */
+function emitReg(node, out) {
+  const k = node.kind;
+  const { ea, addr, idx } = operandToEa(node.operand);
+  // resolve the source/dest EA, materializing an indexed EA into a0 when needed
+  const realEa = () => (idx != null ? indexedEaLines(addr, idx, out) : ea);
+  switch (k) {
+    case ABSTRACT.LOAD_ACC: out.push(`        move.b  ${realEa()},${ACC}`); return;
+    case ABSTRACT.LOAD_X:   out.push(`        move.b  ${realEa()},${X}`); return;
+    case ABSTRACT.LOAD_Y:   out.push(`        move.b  ${realEa()},${Y}`); return;
+    case ABSTRACT.STORE_ACC: out.push(`        move.b  ${ACC},${realEa()}`); return;
+    case ABSTRACT.STORE_X:   out.push(`        move.b  ${X},${realEa()}`); return;
+    case ABSTRACT.STORE_Y:   out.push(`        move.b  ${Y},${realEa()}`); return;
+    case ABSTRACT.TRANSFER:  emitTransfer(node, out); return;
+    case ABSTRACT.ADD: out.push(`        add.b   ${realEa()},${ACC}`); return;
+    case ABSTRACT.SUB: out.push(`        sub.b   ${realEa()},${ACC}`); return;
+    case ABSTRACT.AND: out.push(`        and.b   ${realEa()},${ACC}`); return;
+    case ABSTRACT.OR:  out.push(`        or.b    ${realEa()},${ACC}`); return;
+    case ABSTRACT.XOR: out.push(`        eor.b   ${ACC},${realEa()}`); return; // 68k eor is reg→ea; approx
+    case ABSTRACT.CMP: out.push(`        cmp.b   ${realEa()},${ACC}`); return;
+    case ABSTRACT.BIT: out.push(`        move.b  ${realEa()},d3`, `        and.b   ${ACC},d3`); return;
+    case ABSTRACT.INC: emitIncDec(node, out, "addq"); return;
+    case ABSTRACT.DEC: emitIncDec(node, out, "subq"); return;
+    case ABSTRACT.SHL: out.push(`        lsl.b   #1,${ACC}`); return;
+    case ABSTRACT.SHR: out.push(`        lsr.b   #1,${ACC}`); return;
+    case ABSTRACT.ROL: out.push(`        roxl.b  #1,${ACC}`); return;
+    case ABSTRACT.ROR: out.push(`        roxr.b  #1,${ACC}`); return;
+    case ABSTRACT.INX: out.push(`        addq.b  #1,${X}`); return;
+    case ABSTRACT.INY: out.push(`        addq.b  #1,${Y}`); return;
+    case ABSTRACT.DEX: out.push(`        subq.b  #1,${X}`); return;
+    case ABSTRACT.DEY: out.push(`        subq.b  #1,${Y}`); return;
+    case ABSTRACT.CPX: out.push(`        cmp.b   ${realEa()},${X}`); return;
+    case ABSTRACT.CPY: out.push(`        cmp.b   ${realEa()},${Y}`); return;
+    case ABSTRACT.PUSH: out.push(`        ; push (${node.mnemonic}) — 6502 stack ops are no-ops in the logic port`); return;
+    case ABSTRACT.PULL: out.push(`        ; pull (${node.mnemonic}) — 6502 stack ops are no-ops in the logic port`); return;
+    case ABSTRACT.SET_FLAG:
+    case ABSTRACT.CLR_FLAG:
+    case ABSTRACT.NOP:
+      out.push(`        nop                     ; ${node.mnemonic} (flag/nop — CCR handled by adjacent ops)`); return;
+    default:
+      out.push(`        ; UNTRANSLATED reg op ${node.mnemonic} (${k})`); return;
+  }
+}
+
+/** 6502 register transfers (tax/tay/txa/tya/tsx/txs) → 68000 reg moves. */
+function emitTransfer(node, out) {
+  const m = node.mnemonic;
+  const map = {
+    tax: `move.b  ${ACC},${X}`, tay: `move.b  ${ACC},${Y}`,
+    txa: `move.b  ${X},${ACC}`, tya: `move.b  ${Y},${ACC}`,
+    tsx: `move.b  #$FF,${X}    ; stack ptr is fixed in the logic port`,
+    txs: `; txs — stack ptr fixed in the logic port`,
+  };
+  out.push(`        ${map[m] || `; ${m} (transfer)`}`);
+}
+
+/** inc/dec on memory (or accumulator) → addq/subq. */
+function emitIncDec(node, out, instr) {
+  const { ea, addr, idx } = operandToEa(node.operand);
+  if (node.operand == null || node.operand === "a") {
+    out.push(`        ${instr}.b  #1,${ACC}`);
+    return;
+  }
+  const e = idx != null ? indexedEaLines(addr, idx, out) : ea;
+  out.push(`        ${instr}.b  #1,${e}`);
+}
+
+/** ISA-neutral branch cond → 68000 branch instruction. The 68000 CCR after a
+ *  move/cmp gives Z (eq/ne) and N (mi/pl); carry/overflow map to C/V. */
+const M68K_BRANCH = {
+  [COND.EQ]: "beq", [COND.NE]: "bne", [COND.CC]: "bcc", [COND.CS]: "bcs",
+  [COND.MI]: "bmi", [COND.PL]: "bpl", [COND.VC]: "bvc", [COND.VS]: "bvs",
+};
+
+/**
+ * Emit the m68k body from an IR program. Returns the asm body (functions only;
+ * the ROM wrapper/vectors/seam are added by emitM68kWrapper / emitM68kSeam).
+ * @param {Array<object>} ir
+ * @returns {string}
+ */
+export function emitm68kBody(ir) {
+  const out = [];
+  for (const node of ir) {
+    if (node.label && node.op !== IR.LABEL) out.push(`${node.label}:`);
+    switch (node.op) {
+      case IR.LABEL: out.push(`${node.name}:`); break;
+      case IR.REG: emitReg(node, out); break;
+      case IR.BRANCH: out.push(`        ${M68K_BRANCH[node.cond] || "bra"}     ${node.target}`); break;
+      case IR.JUMP: out.push(`        jmp     ${node.target}`); break;
+      case IR.CALL: out.push(`        jsr     ${node.target}`); break;
+      case IR.RET: out.push(node.kind === "interrupt" ? "        rte" : "        rts"); break;
+      case IR.HWREG: emitHwReg(node, out); break;
+      case IR.PASSTHROUGH: out.push(node.text); break;
+      case IR.REFUSE: out.push(`        ; UNTRANSLATED: ${(node.raw || "").trim()}  (${node.reason})`); break;
+      default: break;
+    }
+  }
+  return out.join("\n");
+}
+
+/** hwreg (the PPU/APU seam) → a call into the m68k runtime stub. Contract mirrors
+ *  the 65816 path: d0 holds the value (writes) / receives it (reads); d1 carries
+ *  the source register low byte so one routine handles the file. */
+function emitHwReg(node, out) {
+  const { access, reg, via } = node;
+  const lowByte = `#$${(reg & 0xff).toString(16).padStart(2, "0")}`;
+  out.push(`        ; seam: ${via} $${reg.toString(16)}`);
+  if (access === "write") {
+    if (via === "stx") out.push(`        move.b  ${X},${ACC}`);
+    else if (via === "sty") out.push(`        move.b  ${Y},${ACC}`);
+    out.push(`        move.b  ${lowByte},${X}`, `        jsr     NES_PPU_WRITE`);
+  } else {
+    out.push(`        move.b  ${lowByte},${X}`, `        jsr     NES_PPU_READ`);
+  }
+}
+
+/**
+ * The m68k ROM wrapper: 68000 vector table at $000000 (SSP + reset PC), the
+ * minimal SEGA header at $100, the recompiled body at $200, and the seam include.
+ * The body runs straight 68000 (no mode switch) — that's the point: it's a real
+ * translation, not an emulation-mode passthrough.
+ * @param {{body:string, resetLabel:string, withShim?:boolean, withRuntime?:boolean, nmiBody?:string}} a
+ */
+export function emitM68kWrapper(a) {
+  const { body, resetLabel } = a;
+  return [
+    "; NES→Genesis recompiled image (romdev generic emit backend, m68k target).",
+    "; The 6502 logic is TRANSLATED to 68000 (not emulated). NES RAM is mapped to",
+    "; Genesis work RAM at $FF0000 — that block is the Tier-1 RAM-diff oracle mirror.",
+    "",
+    "    org $00000000",
+    "vectors:",
+    "    dc.l   $00FFE000          ; initial SSP",
+    "    dc.l   RESET_ENTRY        ; reset PC",
+    "    rept 62",
+    "    dc.l   RESET_ENTRY        ; exceptions → reset (logic port; no handlers yet)",
+    "    endr",
+    "",
+    "    org $00000100",
+    "    dc.b \"SEGA MEGA DRIVE \"   ; system magic (16)",
+    "    dc.b \"ROMDEV PORT     \"   ; copyright (16, padded)",
+    "    dc.b \"NES-PORT (ROMDEV LOGIC RECOMPILE)               \" ; domestic title (48)",
+    "    dc.b \"NES-PORT (ROMDEV LOGIC RECOMPILE)               \" ; overseas title (48)",
+    "    dc.b \"GM ROMDEV-00  \"     ; serial (14)",
+    "    dc.w $0000                 ; checksum",
+    "    dc.b \"J               \"   ; device support (16)",
+    "    dc.l $00000000             ; ROM start",
+    "    dc.l $003FFFFF             ; ROM end",
+    "    dc.l $00FF0000             ; RAM start",
+    "    dc.l $00FFFFFF             ; RAM end",
+    "    dc.b \"            \"        ; SRAM tag (12)",
+    "    dc.l $00000000             ; SRAM start",
+    "    dc.l $00000000             ; SRAM end",
+    "    dc.b \"            \"        ; modem (12)",
+    "    dc.b \"romdev generic recompile        \" ; notes (32)",
+    "    dc.b \"JUE             \"   ; region (16)",
+    "",
+    "    org $00000200",
+    "RESET_ENTRY:",
+    "    move.w  #$2700,sr          ; mask interrupts during init",
+    "    lea     $00FFE000,sp       ; set the stack",
+    `    jmp     ${resetLabel}`,
+    "",
+    "; ── recompiled 6502 logic, translated to 68000 ──────────────────────",
+    body,
+    "",
+    `    include "nes_seam_md.asm"`,
+    "",
+  ].join("\n");
+}
+
+/** The m68k hardware-seam stub. Writes drop; $2002 (PPUSTATUS) read returns $80
+ *  so 6502 vblank-wait loops (`bit $2002 / bpl`) terminate. Same contract as the
+ *  65816 seam, in 68000 syntax. */
+export function emitM68kSeam() {
+  return [
+    "; ── NES hardware seam (m68k v1 stubs) ───────────────────────────────",
+    "; d0 = value (writes) / receives it (reads); d1 = register low byte.",
+    "NES_PPU_WRITE:",
+    "    rts",
+    "NES_PPU_READ:",
+    "    move.b  #$80,d0            ; vblank set → boot wait-loops exit",
+    "    rts",
+    "NES_APU_WRITE:",
+    "    rts",
+    "NES_OAM_DMA:",
+    "    rts",
+    "",
+  ].join("\n");
+}
+
+/** Callees referenced by jsr/jmp/branch but not defined in this slice → stub them
+ *  (single-routine isolation), in 68000 syntax. */
+export function findUndefinedLabelsM68k(body, equs = []) {
+  const defined = new Set();
+  const equNames = new Set(equs.map((e) => e.split(/\s*=/)[0].trim()));
+  const referenced = new Set();
+  const SEAM = new Set(["NES_PPU_WRITE", "NES_PPU_READ", "NES_APU_WRITE", "NES_OAM_DMA"]);
+  for (const line of body.split("\n")) {
+    const def = line.match(/^(\w+):/);
+    if (def) defined.add(def[1]);
+    const ref = line.match(/^\s+(?:jsr|jmp|b\w\w)\s+([A-Za-z_]\w*)\s*$/);
+    if (ref) referenced.add(ref[1]);
+  }
+  return [...referenced].filter((n) => !defined.has(n) && !equNames.has(n) && !SEAM.has(n));
+}
+
+/** `label: rts` stubs (68000) for undefined callees. */
+export function emitM68kStubs(names) {
+  if (!names.length) return "";
+  return [
+    "; ── unresolved callee stubs (single-routine isolation) ──",
+    ...names.map((n) => `${n}:\n    rts`),
+    "",
+  ].join("\n");
+}

package/src/analysis/recompile/index.js

@@ -0,0 +1,169 @@
+// Generic recompile orchestrator — the source/target-agnostic port engine.
+//
+// recompile(sourceAsm, {source, target}) wires LIFT (source ISA → IR) → EMIT (IR
+// → target ISA) through a registry. Adding a platform PAIR is one lifter + one
+// emitter; the orchestrator, IR, residue handling, callee-stubbing, and the
+// disasm-tool wiring are all shared. NES→SNES and NES→Genesis go through the SAME
+// code path here — the only difference is which emitter the registry hands back.
+//
+// An EMITTER is an object: {
+//   targetPlatform, targetIsa,
+//   emitBody(ir) → string,                       // IR functions → target asm body
+//   emitWrapper({ body, entry, ... }) → string,  // ROM wrapper (vectors, preamble)
+//   emitSeam() → string,                         // the hardware-seam stub include
+//   seamFile,                                    // include filename for the seam
+//   findUndefinedLabels(body, equs) → string[],  // callees to stub (target syntax)
+//   emitStubs(names) → string,                   // `label: ret` stubs (target syntax)
+// }
+// A LIFTER is: lift(sourceAsm) → { ir, equs, instrCount, seamCount, entry }.
+//
+// Plain JS ESM + JSDoc.
+
+import { collectResidue } from "./ir.js";
+import { lift6502 } from "./lift-6502.js";
+import { emit65816Body } from "./emit-65816.js";
+import {
+  emitMainAsm as emit65816Wrapper, emitSeam as emit65816Seam,
+  findUndefinedLabels, emitStubs,
+} from "../recompile-65816.js";
+import {
+  emitm68kBody, emitM68kWrapper, emitM68kSeam, findUndefinedLabelsM68k, emitM68kStubs,
+} from "./emit-m68k.js";
+
+/** source ISA / platform → lifter. (gg/gbc/md aliases map to their base ISA.) */
+const LIFTERS = {
+  nes: lift6502, "6502": lift6502,
+  // future: gb/sms → lift-sm83 / lift-z80; genesis → lift-m68k; etc.
+};
+
+/** target platform → emitter object. */
+const EMITTERS = {
+  snes: {
+    targetPlatform: "snes", targetIsa: "65816",
+    emitBody: emit65816Body,
+    emitWrapper: (a) => emit65816Wrapper(a),
+    emitSeam: emit65816Seam,
+    seamFile: "nes_seam.asm",
+    findUndefinedLabels,
+    emitStubs,
+  },
+  genesis: {
+    targetPlatform: "genesis", targetIsa: "m68k",
+    emitBody: emitm68kBody,
+    emitWrapper: (a) => emitM68kWrapper(a),
+    emitSeam: emitM68kSeam,
+    seamFile: "nes_seam_md.asm",
+    findUndefinedLabels: findUndefinedLabelsM68k,
+    emitStubs: emitM68kStubs,
+  },
+};
+
+/** Resolve a source platform/ISA to its lifter, or throw with the supported set. */
+function resolveLifter(source) {
+  const f = LIFTERS[source];
+  if (!f) throw new Error(`recompile: no lifter for source '${source}'. Supported sources: ${Object.keys(LIFTERS).filter((k) => k.length > 4 || /^[a-z]/.test(k)).join(", ")}.`);
+  return f;
+}
+
+/** Resolve a target platform to its emitter, or throw with the supported set. */
+function resolveEmitter(target) {
+  const e = EMITTERS[target];
+  if (!e) throw new Error(`recompile: no emitter for target '${target}'. Supported targets: ${Object.keys(EMITTERS).join(", ")}.`);
+  return e;
+}
+
+/** The supported (source → target) pairs, for tool docs + capability reporting. */
+export function supportedPairs() {
+  const sources = Object.keys(LIFTERS).filter((k) => !/^\d/.test(k)); // platform names, not bare ISA
+  const targets = Object.keys(EMITTERS);
+  const pairs = [];
+  for (const s of sources) for (const t of targets) if (s !== t) pairs.push(`${s}→${t}`);
+  return pairs;
+}
+
+/**
+ * Recompile a source-CPU disassembly to a target-CPU ROM image source, generically.
+ *
+ * @param {string} sourceAsm   the da65/objdump disassembly of the source routine(s)
+ * @param {Object} opts
+ * @param {string} opts.source         source platform/ISA (e.g. 'nes')
+ * @param {string} opts.target         target platform (e.g. 'snes', 'genesis')
+ * @param {string} [opts.entry]        override the entry label
+ * @param {boolean} [opts.stubUndefined=true]  stub callees undefined in this slice
+ * @param {string} [opts.nmiSourceAsm] source disasm of the NMI handler (2nd body)
+ * @param {boolean} [opts.withShim]    target-specific: include the static PPU shim
+ * @param {boolean} [opts.withRuntime] target-specific: include the per-frame runtime
+ * @returns {{ mainAsm, seamAsm, seamFile, residue, entry, nmiEntry, instrCount,
+ *             seamCount, stubbed, source, target, targetIsa }}
+ */
+export function recompile(sourceAsm, opts = {}) {
+  const source = opts.source || "nes";
+  const target = opts.target || "snes";
+  const lift = resolveLifter(source);
+  const emitter = resolveEmitter(target);
+
+  // 1. LIFT the reset/body to IR.
+  const lifted = lift(sourceAsm);
+  const body = emitter.emitBody(lifted.ir);
+  const residue = collectResidue(lifted.ir);
+
+  // 2. Optionally LIFT a second body (the NMI handler) for the live runtime.
+  let nmiBody = null;
+  let nmiEntry = null;
+  let nmiEqus = [];
+  let nmiResidue = [];
+  let nmiInstr = 0;
+  let nmiSeam = 0;
+  if (opts.withRuntime && opts.nmiSourceAsm) {
+    const nl = lift(opts.nmiSourceAsm);
+    nmiEntry = nl.entry;
+    nmiEqus = nl.equs;
+    nmiInstr = nl.instrCount;
+    nmiSeam = nl.seamCount;
+    nmiResidue = collectResidue(nl.ir);
+    // de-collide the synthetic fall-through entry between the two bodies
+    if (nmiEntry === "RECOMPILE_ENTRY") {
+      // rename in the IR before emit so the label is unique
+      for (const n of nl.ir) { if (n.op === "label" && n.name === "RECOMPILE_ENTRY") n.name = "RECOMPILE_NMI_ENTRY"; if (n.label === "RECOMPILE_ENTRY") n.label = "RECOMPILE_NMI_ENTRY"; }
+      nmiEntry = "RECOMPILE_NMI_ENTRY";
+    }
+    nmiBody = emitter.emitBody(nl.ir);
+  }
+
+  // 3. equs (address aliases) — union, de-duped, emitted once in the reset prefix.
+  const seen = new Set();
+  const allEqus = [...lifted.equs, ...nmiEqus].filter((e) => {
+    const name = e.split(/\s*=/)[0].trim();
+    if (seen.has(name)) return false;
+    seen.add(name);
+    return true;
+  });
+  const fullBody = (allEqus.length ? allEqus.join("\n") + "\n" : "") + body;
+  const entry = opts.entry || lifted.entry || "RECOMPILE_ENTRY";
+
+  // 4. Stub callees undefined across BOTH bodies (isolation), in target syntax.
+  const stubUndefined = opts.stubUndefined !== false;
+  const combined = fullBody + (nmiBody ? "\n" + nmiBody : "");
+  const stubbed = stubUndefined ? emitter.findUndefinedLabels(combined, allEqus) : [];
+  const withStubs = fullBody + (stubbed.length ? "\n" + emitter.emitStubs(stubbed) : "");
+
+  // 5. Wrap into the target ROM image.
+  const mainAsm = emitter.emitWrapper({
+    body: withStubs,
+    resetLabel: entry,
+    withShim: !!opts.withShim,
+    withRuntime: !!opts.withRuntime,
+    nmiBody,
+  });
+  const seamAsm = emitter.emitSeam();
+
+  return {
+    mainAsm, seamAsm, seamFile: emitter.seamFile,
+    residue: [...residue, ...nmiResidue],
+    entry, nmiEntry,
+    instrCount: lifted.instrCount + nmiInstr,
+    seamCount: lifted.seamCount + nmiSeam,
+    stubbed,
+    source, target, targetIsa: emitter.targetIsa,
+  };
+}