romdevtools 0.42.0 → 0.43.0

package/CHANGELOG.md

@@ -4,6 +4,30 @@ 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.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.43.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,
+  };
+}

package/src/analysis/recompile/ir.js

@@ -0,0 +1,123 @@
+// Generic recompile IR — the spine of the source/target-agnostic port engine.
+//
+// The port engine has two halves: a LIFTER turns one source-CPU instruction into
+// IR node(s); an EMITTER turns IR node(s) into target-CPU assembly. Adding a
+// platform PAIR is then one lifter + one emitter (registered by ISA name), not an
+// N×N matrix of hand-written transpilers. NES→SNES is the first pair; the IR is
+// what lets NES→Genesis (and any other pair whose ISAs have a lifter+emitter)
+// reuse the SAME pipeline instead of a second bespoke recompiler.
+//
+// DESIGN PRINCIPLE: the IR is DELIBERATELY SMALL and HONEST. It models only the
+// instruction classes a mechanical port actually needs, and REFUSES (rather than
+// guesses) anything whose semantics don't carry across ISAs. A refused node is
+// surfaced as residue, never silently mistranslated — the same contract the
+// original 6502→65816 recompiler held. We are NOT building a full optimizing
+// compiler IR (SSA, types, dataflow); we're building a normalized transfer format
+// for "this instruction loads/stores/branches/calls/touches-hardware".
+//
+// IR node shape (a plain object; `op` is the discriminant):
+//   { op:'label',   name }                              — a code label / branch target
+//   { op:'reg',     mnemonic, operand, raw }            — a register/ALU op that maps
+//        1:1 across the source & target's compatible register file. `kind` tags the
+//        abstract operation so an emitter that ISN'T 1:1 can translate it.
+//   { op:'load',    reg, addr, mode }                   — reg ← mem
+//   { op:'store',   reg, addr, mode }                   — mem ← reg
+//   { op:'alu',     fn, reg, operand, mode }            — reg = reg fn operand
+//   { op:'branch',  cond, target }                      — conditional relative branch
+//   { op:'jump',    target }                            — unconditional jump
+//   { op:'call',    target }                            — subroutine call (push return)
+//   { op:'ret',     kind:'sub'|'interrupt' }            — return
+//   { op:'hwreg',   access:'read'|'write', reg, addr, via } — a hardware-MMIO access
+//        (the "seam"): the target can't do the source's MMIO, so this becomes a
+//        call into the target's runtime shim. `reg` is the source register-file
+//        address (e.g. NES $2000); `via` is the CPU register carrying the value.
+//   { op:'passthrough', text, raw }                     — emitter writes `text` as-is
+//        (used by a 1:1 emitter where the source mnemonic IS a valid target mnemonic)
+//   { op:'refuse',  reason, raw }                       — not mechanically translatable;
+//        becomes residue. NEVER emitted as code.
+//
+// Every node may carry `label` (a leading code label) and `addr` (the source CPU
+// address, for diagnostics). Plain JS ESM + JSDoc.
+
+/** The IR op discriminants. */
+export const IR = Object.freeze({
+  LABEL: "label",
+  REG: "reg",
+  LOAD: "load",
+  STORE: "store",
+  ALU: "alu",
+  BRANCH: "branch",
+  JUMP: "jump",
+  CALL: "call",
+  RET: "ret",
+  HWREG: "hwreg",
+  PASSTHROUGH: "passthrough",
+  REFUSE: "refuse",
+});
+
+/**
+ * Abstract operation kinds an emitter can switch on when it ISN'T a 1:1 textual
+ * passthrough (e.g. emitting m68k from 6502, where `lda`→`move.b` and the named
+ * 8-bit accumulator becomes a chosen data register). A lifter tags each `reg`/
+ * `alu`/`load`/`store`/`branch` node with one of these so the emitter never has
+ * to know the SOURCE mnemonic — only the abstract intent.
+ */
+export const ABSTRACT = Object.freeze({
+  // data movement
+  LOAD_ACC: "load_acc", LOAD_X: "load_x", LOAD_Y: "load_y",
+  STORE_ACC: "store_acc", STORE_X: "store_x", STORE_Y: "store_y",
+  TRANSFER: "transfer",
+  PUSH: "push", PULL: "pull",
+  // arithmetic / logic (on the accumulator unless noted)
+  ADD: "add", SUB: "sub", AND: "and", OR: "or", XOR: "xor",
+  INC: "inc", DEC: "dec", SHL: "shl", SHR: "shr", ROL: "rol", ROR: "ror",
+  CMP: "cmp", BIT: "bit",
+  // index reg inc/dec/compare
+  INX: "inx", INY: "iny", DEX: "dex", DEY: "dey",
+  CPX: "cpx", CPY: "cpy",
+  // flags / nop
+  SET_FLAG: "set_flag", CLR_FLAG: "clr_flag", NOP: "nop",
+});
+
+/** Branch conditions (ISA-neutral). A lifter maps its native branches onto these;
+ *  an emitter maps these onto the target's branch instructions. */
+export const COND = Object.freeze({
+  EQ: "eq", NE: "ne", CC: "cc", CS: "cs", // zero/carry
+  MI: "mi", PL: "pl", VC: "vc", VS: "vs", // sign/overflow
+  ALWAYS: "always",
+});
+
+// ── node constructors (keep call sites terse + consistent) ──────────────────
+export const irLabel = (name) => ({ op: IR.LABEL, name });
+export const irPassthrough = (text, raw, label) => ({ op: IR.PASSTHROUGH, text, raw, label });
+export const irRefuse = (reason, raw, label) => ({ op: IR.REFUSE, reason, raw, label });
+export const irReg = (kind, mnemonic, operand, raw, label) => ({ op: IR.REG, kind, mnemonic, operand, raw, label });
+export const irBranch = (cond, target, raw, label) => ({ op: IR.BRANCH, cond, target, raw, label });
+export const irJump = (target, raw, label) => ({ op: IR.JUMP, target, raw, label });
+export const irCall = (target, raw, label) => ({ op: IR.CALL, target, raw, label });
+export const irRet = (kind, raw, label) => ({ op: IR.RET, kind, raw, label });
+export const irHwReg = (access, reg, via, raw, label) => ({ op: IR.HWREG, access, reg, via, raw, label });
+
+/**
+ * Validate an IR program (array of nodes) — a cheap structural check so a buggy
+ * lifter fails loudly here, not deep in an emitter. Returns the array unchanged
+ * or throws. Not a type system; just a guard that every node has a known `op`.
+ * @param {Array<object>} nodes
+ */
+export function validateIR(nodes) {
+  if (!Array.isArray(nodes)) throw new Error("IR program must be an array of nodes");
+  const ops = new Set(Object.values(IR));
+  for (let i = 0; i < nodes.length; i++) {
+    const n = nodes[i];
+    if (!n || typeof n !== "object" || !ops.has(n.op)) {
+      throw new Error(`IR node ${i} has an unknown op: ${JSON.stringify(n)}`);
+    }
+  }
+  return nodes;
+}
+
+/** Collect the residue (refused nodes) from an IR program — what the engine
+ *  could NOT mechanically translate, surfaced to the caller instead of guessed. */
+export function collectResidue(nodes) {
+  return nodes.filter((n) => n.op === IR.REFUSE).map((n) => ({ reason: n.reason, line: (n.raw || "").trim() }));
+}

package/src/analysis/recompile/lift-6502.js

@@ -0,0 +1,176 @@
+// 6502 → IR lifter. Turns one da65 6502 disassembly into the generic recompile
+// IR (ir.js), tagging each instruction with an ABSTRACT op so a non-1:1 target
+// emitter (m68k, z80, …) can translate the INTENT without knowing 6502. The 1:1
+// emitter (65816 emulation mode) ignores the abstract tag and re-emits the
+// mnemonic verbatim — both consume the same IR.
+//
+// This is the existing recompile-65816 classification logic, refactored to emit
+// IR nodes instead of 65816 text. Same documented-opcode set, same seam
+// detection, same refuse rules — but now source-agnostic at the boundary.
+//
+// Plain JS ESM + JSDoc.
+
+import { parseDa65Line } from "../recompile-65816.js";
+import { NES_REGISTERS } from "../../platforms/common/registers.js";
+import {
+  ABSTRACT, COND,
+  irLabel, irReg, irBranch, irJump, irCall, irRet, irHwReg, irRefuse,
+} from "./ir.js";
+
+/** The 151 documented 6502 mnemonics — anything else (an undocumented opcode da65
+ *  rendered, or a data byte caught in the stream) is REFUSED, not guessed. */
+export const DOCUMENTED_6502 = new Set([
+  "adc", "and", "asl", "bcc", "bcs", "beq", "bit", "bmi", "bne", "bpl", "brk",
+  "bvc", "bvs", "clc", "cld", "cli", "clv", "cmp", "cpx", "cpy", "dec", "dex",
+  "dey", "eor", "inc", "inx", "iny", "jmp", "jsr", "lda", "ldx", "ldy", "lsr",
+  "nop", "ora", "pha", "php", "pla", "plp", "rol", "ror", "rti", "rts", "sbc",
+  "sec", "sed", "sei", "sta", "stx", "sty", "tax", "tay", "tsx", "txa", "txs",
+  "tya",
+]);
+
+/** mnemonic → abstract op, so an emitter switches on INTENT not the 6502 name.
+ *  (Branches/jumps/calls/returns/hwreg are handled structurally below, not here.) */
+const ABSTRACT_OF = {
+  lda: ABSTRACT.LOAD_ACC, ldx: ABSTRACT.LOAD_X, ldy: ABSTRACT.LOAD_Y,
+  sta: ABSTRACT.STORE_ACC, stx: ABSTRACT.STORE_X, sty: ABSTRACT.STORE_Y,
+  tax: ABSTRACT.TRANSFER, tay: ABSTRACT.TRANSFER, txa: ABSTRACT.TRANSFER,
+  tya: ABSTRACT.TRANSFER, tsx: ABSTRACT.TRANSFER, txs: ABSTRACT.TRANSFER,
+  pha: ABSTRACT.PUSH, php: ABSTRACT.PUSH, pla: ABSTRACT.PULL, plp: ABSTRACT.PULL,
+  adc: ABSTRACT.ADD, sbc: ABSTRACT.SUB, and: ABSTRACT.AND, ora: ABSTRACT.OR,
+  eor: ABSTRACT.XOR, inc: ABSTRACT.INC, dec: ABSTRACT.DEC, asl: ABSTRACT.SHL,
+  lsr: ABSTRACT.SHR, rol: ABSTRACT.ROL, ror: ABSTRACT.ROR, cmp: ABSTRACT.CMP,
+  bit: ABSTRACT.BIT, inx: ABSTRACT.INX, iny: ABSTRACT.INY, dex: ABSTRACT.DEX,
+  dey: ABSTRACT.DEY, cpx: ABSTRACT.CPX, cpy: ABSTRACT.CPY,
+  clc: ABSTRACT.CLR_FLAG, sec: ABSTRACT.SET_FLAG, cli: ABSTRACT.CLR_FLAG,
+  sei: ABSTRACT.SET_FLAG, clv: ABSTRACT.CLR_FLAG, cld: ABSTRACT.CLR_FLAG,
+  nop: ABSTRACT.NOP,
+};
+
+/** 6502 conditional-branch mnemonic → ISA-neutral condition. */
+const BRANCH_COND = {
+  beq: COND.EQ, bne: COND.NE, bcc: COND.CC, bcs: COND.CS,
+  bmi: COND.MI, bpl: COND.PL, bvc: COND.VC, bvs: COND.VS,
+};
+
+/**
+ * Detect a hardware-register (MMIO) access — the seam. Returns the register's low
+ * address if the operand targets a NES PPU/APU register, else null. Only absolute
+ * operands count; immediates and zero-page never hit the register file.
+ * @param {string|undefined} operand
+ */
+export function seamRegister(operand) {
+  if (!operand) return null;
+  const m = operand.match(/^\$([0-9A-Fa-f]{3,4})(?:\s*,\s*[xy])?$/);
+  if (!m) return null;
+  const addr = parseInt(m[1], 16);
+  if (addr in NES_REGISTERS) return addr;
+  if ((addr >= 0x2000 && addr <= 0x2007) || (addr >= 0x4000 && addr <= 0x4017)) return addr;
+  return null;
+}
+
+/**
+ * Lift one parsed da65 6502 line to an IR node (or null for blank/directive/equ —
+ * those are handled by the orchestrator, which collects equs separately). The
+ * leading label, if any, rides on the returned node so branch targets resolve.
+ * @param {ReturnType<typeof parseDa65Line>} p
+ * @returns {object|null}
+ */
+function liftInstr(p) {
+  const label = p.label;
+  const mnem = p.mnemonic;
+  const operand = p.operand;
+
+  // Refuse the non-mechanical constructs up front (same as the original).
+  if (mnem === "sed") return irRefuse("decimal-mode (sed): BCD edge-flag semantics differ across ISAs", p.raw, label);
+  if (mnem === "jmp" && operand && operand.startsWith("(")) {
+    return irRefuse("indirect jump (jmp (addr)): target is computed — resolve with breakpoint({on:'jumptable'})", p.raw, label);
+  }
+
+  // Hardware seam: any PPU/APU register access becomes an IR hwreg node.
+  const reg = seamRegister(operand);
+  if (reg != null) {
+    const isStore = mnem === "sta" || mnem === "stx" || mnem === "sty";
+    const isLoad = mnem === "lda" || mnem === "ldx" || mnem === "ldy" || mnem === "bit";
+    if (isStore) return irHwReg("write", reg, mnem, p.raw, label);
+    if (isLoad) return irHwReg("read", reg, mnem, p.raw, label);
+    return irRefuse(`hardware-register read-modify-write (${mnem} ${operand}): not in the mechanical set`, p.raw, label);
+  }
+
+  // Control flow → structural IR nodes.
+  if (mnem === "jsr") return irCall(operand, p.raw, label);
+  if (mnem === "jmp") return irJump(operand, p.raw, label);
+  if (mnem === "rts") return irRet("sub", p.raw, label);
+  if (mnem === "rti") return irRet("interrupt", p.raw, label);
+  if (mnem === "brk") return irRefuse("brk: software interrupt needs explicit vector handling in v1", p.raw, label);
+  if (mnem in BRANCH_COND) return irBranch(BRANCH_COND[mnem], operand, p.raw, label);
+
+  // A documented data/ALU/transfer op → a `reg` node tagged with its abstract op.
+  if (mnem in ABSTRACT_OF) {
+    return irReg(ABSTRACT_OF[mnem], mnem, operand, p.raw, label);
+  }
+
+  // Unknown mnemonic = undocumented opcode or a parse miss.
+  return irRefuse(`unrecognized/undocumented opcode '${mnem}' — not a documented 6502 instruction`, p.raw, label);
+}
+
+/**
+ * Lift a block of da65 6502 asm text into an IR program. Returns the IR node list,
+ * the collected equ definitions (address aliases), and a flag for whether the
+ * first instruction was anchored (so the orchestrator can fix the entry label).
+ * @param {string} da65Asm
+ * @returns {{ ir: Array<object>, equs: string[], instrCount: number, seamCount: number, entry: string|null }}
+ */
+export function lift6502(da65Asm) {
+  const lines = da65Asm.split("\n");
+  const ir = [];
+  const equs = [];
+  let instrCount = 0;
+  let seamCount = 0;
+  let entry = null;
+  const ENTRY_LABEL = "RECOMPILE_ENTRY";
+
+  for (const raw of lines) {
+    const p = parseDa65Line(raw);
+    switch (p.kind) {
+      case "blank":
+      case "comment":
+      case "directive":
+        break;
+      case "equ":
+        equs.push(`${p.label} = ${p.operand}`);
+        break;
+      case "label":
+        ir.push(irLabel(p.label));
+        break;
+      case "data":
+        ir.push(irRefuse("data/.byte in code stream (data table or undocumented opcode)", p.raw));
+        break;
+      case "instr": {
+        const node = liftInstr(p);
+        if (!node) break;
+        // Anchor the entry to the FIRST real instruction (lifted node), labeled or
+        // not — da65 only labels branch targets, so a fall-through opener is
+        // unlabeled and would otherwise let the reset skip the routine's setup.
+        if (entry == null && node.op !== "refuse") {
+          if (node.label) {
+            entry = node.label;
+          } else {
+            entry = ENTRY_LABEL;
+            ir.push(irLabel(ENTRY_LABEL));
+          }
+        } else if (entry == null && node.op === "refuse") {
+          // even a refused opener anchors the entry so the vector lands at the top
+          if (node.label) entry = node.label;
+          else { entry = ENTRY_LABEL; ir.push(irLabel(ENTRY_LABEL)); }
+        }
+        if (node.op === "hwreg") seamCount++;
+        if (node.op !== "refuse") instrCount++;
+        ir.push(node);
+        break;
+      }
+      default:
+        break;
+    }
+  }
+  return { ir, equs, instrCount, seamCount, entry };
+}

package/src/analysis/recompile-65816.js

@@ -22,6 +22,7 @@
 // Plain JS ESM + JSDoc. See internal-romdev/PORTING_MENTAL_MODELS.md Part 4.
 
 import { NES_REGISTERS } from "../platforms/common/registers.js";
+import { recompile } from "./recompile/index.js";
 
 /**
  * The 151 documented 6502 mnemonics. Anything da65 emits outside this set — or
@@ -375,73 +376,21 @@ export function sliceFirstRoutine(da65Asm) {
  *             seamCount: number, stubbed: string[] }}
  */
 export function recompileNesToSnes(da65Asm, opts = {}) {
-  const { body, equs, residue, instrCount, seamCount, entry: bodyEntry } = translateBody(da65Asm);
-
-  // Optionally translate the NES NMI handler as a second body (phase-2 runtime).
-  let nmiBody = null;
-  let nmiEntry = null;
-  let nmiEqus = [];
-  let nmiResidue = [];
-  let nmiInstr = 0;
-  let nmiSeam = 0;
-  if (opts.withRuntime && opts.nmiDa65Asm) {
-    const t = translateBody(opts.nmiDa65Asm);
-    nmiBody = t.body;
-    nmiEntry = t.entry;
-    nmiEqus = t.equs;
-    nmiResidue = t.residue;
-    nmiInstr = t.instrCount;
-    nmiSeam = t.seamCount;
-    // The two bodies may both define an entry named RECOMPILE_ENTRY (the synthetic
-    // fall-through label). Rename the NMI's so they don't collide in one image.
-    if (nmiEntry === "RECOMPILE_ENTRY") {
-      nmiBody = nmiBody.replace(/\bRECOMPILE_ENTRY\b/g, "RECOMPILE_NMI_ENTRY");
-      nmiEntry = "RECOMPILE_NMI_ENTRY";
-    }
-  }
-
-  // Equs (zero-page/external address aliases like `L001E = $001E`) are shared
-  // between the two bodies — emit the UNION once, de-duplicated, in the reset
-  // body's prefix; the NMI body carries none (a duplicate `=` is an asar error).
-  const seenEqu = new Set();
-  const allEqus = [...equs, ...nmiEqus].filter((e) => {
-    const name = e.split(/\s*=/)[0].trim();
-    if (seenEqu.has(name)) return false;
-    seenEqu.add(name);
-    return true;
-  });
-  const fullBody = (allEqus.length ? allEqus.join("\n") + "\n" : "") + body;
-  const fullNmiBody = nmiBody; // equs already hoisted above
-  // entry: caller override > the first-instruction label translateBody fixed >
-  // first label in the body (legacy fallback) > a synthetic name. bodyEntry is
-  // the correct one — it anchors the reset vector to the routine's OPENING
-  // instruction, not a later branch target.
-  const entry = opts.entry || bodyEntry || entryLabel(fullBody) || "RECOMPILE_ENTRY";
-
-  // Stub callees undefined across BOTH bodies (so a routine the reset calls that
-  // happens to be defined inside the NMI body — or vice versa — is not stubbed).
-  const stubUndefined = opts.stubUndefined !== false;
-  const combined = fullBody + (fullNmiBody ? "\n" + fullNmiBody : "");
-  const stubbed = stubUndefined ? findUndefinedLabels(combined, allEqus) : [];
-  const stubsAsm = stubbed.length ? "\n" + emitStubs(stubbed) : "";
-  const withStubs = fullBody + stubsAsm;
-
-  const mainAsm = emitMainAsm({
-    body: withStubs,
-    resetLabel: entry,
-    withShim: !!opts.withShim,
-    withRuntime: !!opts.withRuntime,
-    nmiBody: fullNmiBody,
+  // Delegate to the GENERIC engine (lift 6502 → IR → emit 65816). This is now a
+  // thin source/target-pinned wrapper kept for back-compat with the disasm tool +
+  // existing tests; the actual translation lives in analysis/recompile/. The
+  // generic path produces the same image (the 65816 emitter reproduces this
+  // module's emitMainAsm/emitSeam output) — see analysis/recompile/index.js.
+  // `nmiDa65Asm` is the old arg name; the generic engine calls it `nmiSourceAsm`.
+  return recompile(da65Asm, {
+    source: "nes",
+    target: "snes",
+    entry: opts.entry,
+    stubUndefined: opts.stubUndefined,
+    withShim: opts.withShim,
+    withRuntime: opts.withRuntime,
+    nmiSourceAsm: opts.nmiDa65Asm,
   });
-  const seamAsm = emitSeam();
-  return {
-    mainAsm, seamAsm,
-    residue: [...residue, ...nmiResidue],
-    entry, nmiEntry,
-    instrCount: instrCount + nmiInstr,
-    seamCount: seamCount + nmiSeam,
-    stubbed,
-  };
 }
 
 /**

package/src/mcp/tools/disasm.js

@@ -1227,12 +1227,19 @@ async function pointerTableCore(args) {
 }
 
 async function recompileCore(args) {
-  const { platform, targetPlatform } = args;
+  const { platform } = args;
+  const targetPlatform = args.targetPlatform || "snes";
   if (platform && platform !== "nes") {
-    throw new Error(`disasm({target:'recompile'}): only NES source is supported in phase 1 (got '${platform}').`);
+    throw new Error(`disasm({target:'recompile'}): only NES source is supported today (got '${platform}'). The engine is generic (lift→IR→emit); other source lifters land as they're built.`);
   }
-  if (targetPlatform && targetPlatform !== "snes") {
-    throw new Error(`disasm({target:'recompile'}): only SNES target is supported in phase 1 (got '${targetPlatform}').`);
+  // The generic engine targets any platform with a registered emitter. SNES is the
+  // 1:1 emulation-mode path (with the PPU shim/runtime render layers); Genesis is a
+  // real 6502→68000 LOGIC translation (presentation seam stubbed — verify with the
+  // RAM-diff oracle, frame({op:'compareRam'})).
+  const { supportedPairs } = await import("../../analysis/recompile/index.js");
+  const validTargets = new Set(supportedPairs().filter((p) => p.startsWith("nes→")).map((p) => p.split("→")[1]));
+  if (!validTargets.has(targetPlatform)) {
+    throw new Error(`disasm({target:'recompile'}): no emitter for target '${targetPlatform}'. Supported NES→ targets: ${[...validTargets].join(", ")}.`);
   }
   const romPath = requireRomPath(args);
   const rom = new Uint8Array(await readFile(romPath));
@@ -1289,8 +1296,12 @@ async function recompileCore(args) {
   // The phase-2 runtime (withRuntime) implies the shim (it needs the BG + tiles
   // the shim uploads); enabling it turns the static port into a LIVE one (sprites
   // animate each vblank, the game's NMI runs). withShim alone is the static path.
-  const wantRuntime = args.withRuntime === true;
-  const wantShim = args.withShim === true || wantRuntime;
+  // The PPU shim/runtime are NES-PPU-on-SNES render layers — SNES target only. A
+  // Genesis (or other) target is a LOGIC port (presentation seam stubbed); verify
+  // it with the RAM-diff oracle, not a rendered screen.
+  const snesTarget = targetPlatform === "snes";
+  const wantRuntime = snesTarget && args.withRuntime === true;
+  const wantShim = snesTarget && (args.withShim === true || wantRuntime);
   let shimAsm = null;
   let shimInfo = null;
   if (wantShim) {
@@ -1328,11 +1339,14 @@ async function recompileCore(args) {
     }
   }
 
-  const { mainAsm, seamAsm, residue, entry, nmiEntry, instrCount, seamCount, stubbed } =
-    recompileNesToSnes(da65Asm, {
+  const { recompile } = await import("../../analysis/recompile/index.js");
+  const { mainAsm, seamAsm, seamFile, residue, entry, nmiEntry, instrCount, seamCount, stubbed, targetIsa } =
+    recompile(da65Asm, {
+      source: "nes",
+      target: targetPlatform,
       withShim: !!shimAsm,
       withRuntime: !!runtimeAsm,
-      nmiDa65Asm,
+      nmiSourceAsm: nmiDa65Asm,
     });
 
   const runtimeOn = !!runtimeAsm;
@@ -1348,7 +1362,7 @@ async function recompileCore(args) {
       await writeFile(rtPath, runtimeAsm);
       written.runtimeAsm = rtPath;
     } else {
-      const seamPath = nodePath.join(args.outputDir, "nes_seam.asm");
+      const seamPath = nodePath.join(args.outputDir, seamFile);
       await writeFile(seamPath, seamAsm);
       written.seamAsm = seamPath;
     }
@@ -1362,30 +1376,36 @@ async function recompileCore(args) {
   const shimDrawn = !!shimAsm;
   return jsonContent({
     ok: true,
-    source: "nes", target: "snes",
+    source: "nes", target: targetPlatform, targetIsa,
     resetVector: "$" + resetVec.toString(16).toUpperCase().padStart(4, "0"),
     entry,
     ...(runtimeOn ? { nmiEntry, nmi: nmiInfo } : {}),
     instrCount, seamCount,
     stubbedCallees: stubbed,
     residue,
-    shim: shimDrawn
-      ? { applied: true, phase: runtimeOn ? "live-background" : "static-boot-picture", tiles: shimInfo.tileCount, note: "Emitted the NES-PPU-on-SNES shim (converted tiles/nametable/palette → VRAM/CGRAM, BG1 on). It draws the original ROM's boot screen background." }
-      : { applied: false, reason: shimInfo?.error || "withShim not set (default off)", note: "No PPU shim — the port runs the logic but renders blank. Pass withShim:true (static) or withRuntime:true (live) to draw the original ROM's picture on SNES." },
-    runtime: runtimeOn
-      ? { applied: true, phase: "live-sprites", gameNmi: nmiInfo?.gameNmi || null, note: "PHASE 2: the per-frame runtime is wired — each vblank it flushes the game's shadow OAM to SNES sprites and runs the game's NMI handler, so sprites ANIMATE (not a static screenshot). Background is from the shim; live nametable streaming is phase 3. Build all emitted files together with build({platform:'snes'})." }
-      : { applied: false, note: "Static port (no per-frame runtime). Pass withRuntime:true to animate sprites + run the game's NMI each vblank." },
+    ...(snesTarget ? {
+      shim: shimDrawn
+        ? { applied: true, phase: runtimeOn ? "live-background" : "static-boot-picture", tiles: shimInfo.tileCount, note: "Emitted the NES-PPU-on-SNES shim (converted tiles/nametable/palette → VRAM/CGRAM, BG1 on). It draws the original ROM's boot screen background." }
+        : { applied: false, reason: shimInfo?.error || "withShim not set (default off)", note: "No PPU shim — the port runs the logic but renders blank. Pass withShim:true (static) or withRuntime:true (live) to draw the original ROM's picture on SNES." },
+      runtime: runtimeOn
+        ? { applied: true, phase: "live-sprites", gameNmi: nmiInfo?.gameNmi || null, note: "PHASE 2: the per-frame runtime is wired — each vblank it flushes the game's shadow OAM to SNES sprites and runs the game's NMI handler, so sprites ANIMATE (not a static screenshot). Background is from the shim; live nametable streaming is phase 3. Build all emitted files together with build({platform:'snes'})." }
+        : { applied: false, note: "Static port (no per-frame runtime). Pass withRuntime:true to animate sprites + run the game's NMI each vblank." },
+    } : {
+      port: { kind: "logic-recompile", targetIsa, note: `LOGIC port: the NES 6502 was TRANSLATED to ${targetIsa} (not emulated) — game logic runs, the PPU/APU presentation seam is STUBBED. Build with the platform's toolchain, then VERIFY with the RAM-diff oracle: load the original NES ROM and this port side by side and frame({op:'compareRam'}) the work-RAM mirror. Presentation (a ${targetPlatform} render runtime) is a separate layer.` },
+    }),
     note:
-      `Recompiled the NES reset${runtimeOn ? " + NMI" : ""} routine(s) to 65816 (asar). ${instrCount} instrs, ${seamCount} PPU/APU seam calls, ` +
+      `Recompiled the NES reset${runtimeOn ? " + NMI" : ""} routine(s) to ${targetIsa}. ${instrCount} instrs, ${seamCount} PPU/APU seam calls, ` +
       `${stubbed.length} callee(s) stubbed (isolation), ${residue.length} residue line(s). ` +
-      (runtimeOn
-        ? "PHASE 2: the 6502 logic runs in emulation mode; the runtime flushes sprites + runs the game NMI every vblank, and the shim draws the BG — so the port is LIVE (sprites move). "
-        : shimDrawn
-          ? `The 6502 logic runs in 65816 EMULATION mode; the shim draws the converted static boot picture (${shimInfo.tileCount} tiles). `
-          : "The 6502 logic runs in 65816 EMULATION mode; the hardware seam is STUBBED so the port renders blank. ") +
+      (snesTarget
+        ? (runtimeOn
+          ? "PHASE 2: the 6502 logic runs in emulation mode; the runtime flushes sprites + runs the game NMI every vblank, and the shim draws the BG — so the port is LIVE (sprites move). "
+          : shimDrawn
+            ? `The 6502 logic runs in 65816 EMULATION mode; the shim draws the converted static boot picture (${shimInfo.tileCount} tiles). `
+            : "The 6502 logic runs in 65816 EMULATION mode; the hardware seam is STUBBED so the port renders blank. ")
+        : `The 6502 logic is TRANSLATED to ${targetIsa} (real ISA translation, not emulation); the PPU/APU seam is STUBBED so it's a LOGIC port — verify with frame({op:'compareRam'}) vs the NES original. `) +
       (written
-        ? `Wrote ${Object.values(written).join(" + ")}. Build all of them together with build({platform:'snes'}); then loadMedia + frame({op:'sideBySide'}) vs the NES original.`
-        : `Pass outputDir to write the .asm files to disk for build({platform:'snes'}).`),
+        ? `Wrote ${Object.values(written).join(" + ")}. Build with the ${targetPlatform} toolchain; then loadMedia + frame({op:'compareRam'}) vs the NES original.`
+        : `Pass outputDir to write the .asm files to disk for build({platform:'${targetPlatform}'}).`),
     ...(written ? { written } : { mainAsm, ...(runtimeOn ? { runtimeAsm } : { seamAsm }), ...(shimAsm ? { shimAsm } : {}) }),
   });
 }
@@ -1495,7 +1515,7 @@ export function registerDisasmTools(server, z) {
       annotateFileOffsets: z.boolean().default(true).describe("target=rom: append `; @0xNNNN` file offset to every line (for romPatch)."),
       // project
       outputDir: z.string().optional().describe("target=project: directory to write the project into (one .asm per region). target=recompile: directory to write main.asm + nes_seam.asm for build({platform:'snes'})."),
-      targetPlatform: z.string().optional().describe("target=recompile: the platform to emit (phase 1: only 'snes'). The source platform is `platform` (phase 1: only 'nes')."),
+      targetPlatform: z.string().optional().describe("target=recompile: the platform to EMIT (default 'snes'). The engine is generic (lift source→IR→emit target): 'snes' = 1:1 emulation-mode port with the PPU render layers (withShim/withRuntime); 'genesis' = real 6502→68000 LOGIC translation (presentation stubbed, verify with frame({op:'compareRam'})). Source `platform` is 'nes' today; more source lifters land as built."),
       withShim: z.boolean().default(false).describe("target=recompile: phase-1 STATIC render (default off). Emit the NES-PPU-on-SNES shim — boots the original ROM, converts its tiles/nametable/palette to SNES VRAM/CGRAM data + a 65816 upload routine that draws the original's STATIC boot screen on SNES (verified on snes9x). Draws the first screen only; sprites don't animate. For a LIVE port use withRuntime instead."),
       withRuntime: z.boolean().default(false).describe("target=recompile: phase-2 LIVE render (default off). Implies withShim (BG) and adds the per-frame runtime: each vblank it flushes the game's shadow OAM to SNES sprites and runs the game's own NMI handler, so SPRITES ANIMATE and the game's per-frame logic runs — the port plays, not just boots to a screenshot. Background is static from the shim; live nametable/scroll streaming is phase 3. Verified on snes9x."),
       // references / cfg / xrefs