romdevtools 0.42.0 → 0.44.0

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/cheats.js

@@ -204,18 +204,38 @@ export async function cheatsApplyCore({ code, desc, path: romPath, index, enable
       const { code: codeToApply, appliedAs, reencodedFrom } = resolveCheatCodeForApply(rawCode, plat);
 
       const unencodable = appliedAs === "rom-unencodable";
-      const slot = index != null ? index : host.listActiveCheats().length;
+      // Slot selection: an explicit `index` wins. Otherwise, if an active cheat
+      // already targets the SAME address, REUSE its slot — applying `005C:03` over
+      // an active `005C:02` should REPLACE the freeze, not stack a second one that
+      // fights for the same byte (v0.41.0 feedback 213831 #3). Only append a new
+      // slot when nothing targets this address yet.
+      const newAddr = cheatAddress(codeToApply);
+      let replacedSlot = null;
+      let slot;
+      if (index != null) {
+        slot = index;
+      } else if (newAddr != null) {
+        const existing = host.listActiveCheats().find((c) => cheatAddress(c.code) === newAddr);
+        if (existing) { slot = existing.index; replacedSlot = existing.index; }
+        else slot = host.listActiveCheats().length;
+      } else {
+        slot = host.listActiveCheats().length;
+      }
       // Still install it (the raw poke may be what the user wants), but warn.
       host.setCheat(slot, codeToApply, enabled);
       return {
         applied: enabled,
         slot,
+        ...(replacedSlot != null ? { replacedSameAddress: true } : {}),
         code: codeToApply,
         appliedAs,
         ...(reencodedFrom ? { reencodedFrom } : {}),
         ...(resolvedDesc ? { desc: resolvedDesc } : {}),
         active: host.listActiveCheats(),
-        note: (reencodedFrom
+        note: (replacedSlot != null
+          ? `REPLACED the active cheat on the same address (slot ${replacedSlot}) — applying a new freeze on an address that already had one swaps it rather than stacking two that fight over the byte. To remove a single freeze without clearing the rest, use cheats({op:'remove', code|slot}). `
+          : "") +
+          (reencodedFrom
           ? `Raw code ${reencodedFrom} names a ROM address — re-encoded to the native ROM-patch device (${codeToApply}) so the core installs a read-intercept (a raw ADDR:VAL on a ROM address is treated as a RAM poke and would silently no-op). `
           : unencodable
           ? `WARNING: this raw code names a ROM address but couldn't be re-encoded to a ROM-patch code (a ROM patch needs a COMPARE byte — pass ADDR:VAL:COMPARE). As applied it's a RAM poke and will likely NO-OP on this read-only ROM address. Read the current byte and supply it as the compare, or use makeCheat. `
@@ -226,6 +246,53 @@ export async function cheatsApplyCore({ code, desc, path: romPath, index, enable
       };
 }
 
+/** The CPU/RAM address a cheat code targets, or null if undecodable. Used to
+ *  detect same-address freezes (replace, not stack) + for op:'remove' by code. */
+function cheatAddress(code) {
+  if (typeof code !== "string") return null;
+  // raw ADDR:VAL[:COMPARE] — the address is the first field.
+  if (code.includes(":")) {
+    const a = parseInt(code.split(":")[0], 16);
+    return Number.isNaN(a) ? null : (a & 0xffff);
+  }
+  // a device code (Game Genie / PAR / GameShark) — decode it platform-agnostically.
+  try {
+    const d = decodeCode(code, null);
+    return d && d.address != null ? (d.address & 0xffff) : null;
+  } catch { return null; }
+}
+
+/** op:'remove' — disable ONE active cheat (by slot index or by code/address),
+ *  leaving the rest in place. The single-slot complement to op:'clear' (nuke-all).
+ *  v0.41.0 feedback 213831 #3. */
+export async function cheatsRemoveCore({ slot, code }, sessionKey) {
+      const host = getHost(sessionKey);
+      if (!host.listActiveCheats) return { removed: false, reason: "no cheat interface on this core", active: [] };
+      const active = host.listActiveCheats();
+      let target = null;
+      if (slot != null) {
+        target = active.find((c) => c.index === slot);
+      } else if (code != null) {
+        // match by exact code OR by the address the code targets (so a user can
+        // remove '005C:02' by passing '005C:03', '$5C', or the device code).
+        const addr = cheatAddress(code);
+        target = active.find((c) => c.code === code) || (addr != null ? active.find((c) => cheatAddress(c.code) === addr) : null);
+      } else {
+        throw new Error("cheats({op:'remove'}): provide `slot` (index) or `code` (the cheat to remove).");
+      }
+      if (!target) {
+        return { removed: false, reason: `no active cheat matching ${slot != null ? `slot ${slot}` : `code '${code}'`}`, active };
+      }
+      host.setCheat(target.index, target.code, false); // disable that slot only
+      return {
+        removed: true,
+        slot: target.index,
+        code: target.code,
+        active: host.listActiveCheats(),
+        note: "Disabled that one cheat (volatile); the rest stay active. Use op:'clear' to remove ALL, op:'apply' to add/swap.",
+      };
+}
+
 /** op:'clear' — remove ALL active cheats (volatile core-side reset). */
 export async function cheatsClearCore(_args, sessionKey) {
       const host = getHost(sessionKey);
@@ -319,7 +386,7 @@ export function registerCheatTools(server, z, sessionKey) {
     "round-trip `verified`. RAM cheat = address+value; ROM/code cheat = also `compare` (the byte currently there — " +
     "read it first).",
     {
-      op: z.enum(["lookup", "search", "apply", "clear", "make"]).describe("lookup THIS game's DB cheats; search the DB by game name; apply a cheat live; clear all cheats; make a new code."),
+      op: z.enum(["lookup", "search", "apply", "remove", "clear", "make"]).describe("lookup THIS game's DB cheats; search the DB by game name; apply a cheat live (replaces an active cheat on the SAME address); remove ONE active cheat (by slot/code); clear ALL cheats; make a new code."),
       // lookup
       path: z.string().optional().describe("op=lookup/apply(+desc): absolute ROM path. lookup sniffs platform+name from it."),
       filter: z.string().optional().describe("op=lookup: case-insensitive substring filter on cheat descriptions."),
@@ -330,8 +397,9 @@ export function registerCheatTools(server, z, sessionKey) {
       // apply
       code: z.string().optional().describe("op=apply: raw cheat code (ADDR:VAL or a Game Genie code). Provide code OR desc."),
       desc: z.string().optional().describe("op=apply: description of a matched cheat (requires `path`). First substring match is applied."),
-      index: z.number().int().min(0).optional().describe("op=apply: cheat slot (default: next free slot). Reuse a slot to replace it."),
+      index: z.number().int().min(0).optional().describe("op=apply: cheat slot (default: reuse the slot of an active cheat on the same address, else next free). Reuse a slot to replace it."),
       enabled: z.boolean().default(true).describe("op=apply: false disables the slot instead of enabling."),
+      slot: z.number().int().min(0).optional().describe("op=remove: the active-cheat slot to disable (from apply's `slot` / active[].index). Provide slot OR code."),
       // make / search / lookup share `platform`
       platform: z.enum([...MAKE_CHEAT_PLATFORMS]).optional().describe("op=lookup: override platform detection. op=search: OPTIONAL — omit to search ALL platforms (each match returns its own `platform`); pass one only to scope the search. op=make: REQUIRED — the target platform (all 14 tier-1)."),
       address: z.number().int().min(0).optional().describe("op=make: address to cheat (RAM addr, or the ROM addr to patch)."),
@@ -345,6 +413,7 @@ export function registerCheatTools(server, z, sessionKey) {
         case "lookup": return jsonContent(await cheatsLookupCore(args));
         case "search": return jsonContent(await cheatsSearchCore(args));
         case "apply":  return attachObserverFrame(jsonContent(await cheatsApplyCore(args, sessionKey)), getHost(sessionKey), "cheat applied");
+        case "remove": return jsonContent(await cheatsRemoveCore(args, sessionKey));
         case "clear":  return jsonContent(await cheatsClearCore(args, sessionKey));
         case "make":   return jsonContent(await cheatsMakeCore(args));
         default: throw new Error(`cheats: unknown op '${args.op}'`);