romdevtools 0.40.2 → 0.41.0

package/src/cores/capabilities.js

@@ -0,0 +1,218 @@
+// capabilities.js — the platform CAPABILITY CONTRACT.
+//
+// One declarative entry per platform stating, in machine-readable form, what
+// romdev's platform-sensitive tools can do on it. This is the SOURCE OF TRUTH
+// the BUILDING.md `deep`/`shallow` legend used to encode as prose — now data,
+// enforced by test/capability-conformance.test.js (declared MUST exactly match
+// actual tool behavior; mismatch fails CI).
+//
+// Why it exists: the 14 tier-1 platforms are near-uniform, but the next-gen tier
+// (N64/PS1/Dreamcast/PSP/DS) breaks that — 3D rendering, MIPS/SH-4 CPUs, GPU-FBO
+// screenshots, ops that are meaningless on a polygon renderer. A declared
+// contract + a uniform "unsupported" signal lets agents discover what a system
+// can do BEFORE calling, and keeps the matrix honest as platforms diverge.
+//
+// Fields (keep MINIMAL — only what the contract / discovery / conformance use):
+//   cpuFamily       primary CPU family (forward-looking; "6502","z80","sm83",
+//                   "m68k","arm","65816","huc6280" today; "mips","sh4" later)
+//   renderingKind   "tile" | "framebuffer" | "3d" | "none" — how the screen is
+//                   produced. The current 14 are all "tile". Drives whether
+//                   tile/nametable inspection ops even make sense.
+//   introspection   "deep" | "shallow" — the BUILDING.md legend, as data.
+//   ops.*           boolean per platform-sensitive op (see OP_KEYS below).
+//   decompileQuality "excellent"|"good"|"medium"|"rough" (from the RE engine).
+//   cpus            { main, secondary[] } — what getCPUState({op:'read'}) decodes.
+//   audioChips      chip ids audioDebug({op:'inspect'}) decodes ([] = no chip).
+//   memoryRegions   exact region ids memory({op}) accepts beyond the generic set.
+
+/** The platform-sensitive op keys the contract tracks. Universal tools (build's
+ * file plumbing, encodeAudio, catalog, files, ...) are NOT here — they don't
+ * vary by platform. */
+export const OP_KEYS = /** @type {const} */ ([
+  "build",              // buildSource for this platform
+  "run",                // loadMedia + a real core
+  "screenshot",         // frame({op:'screenshot'})
+  "inspectSprites",     // sprites({op:'inspect'})
+  "inspectPalette",     // palette({source:'live'})
+  "inspectBackground",  // background({view:'renderState'/'map'})
+  "renderingContext",   // background({view:'renderState'}) decode
+  "cpuState",           // cpu({op:'read'}) main CPU
+  "audioDebug",         // audioDebug({op:'inspect'})
+  "cart",               // cart({op:'extract'/'wrap'})
+  "disasm",             // disasm({target:'rom'/'project'/'references'})
+  "decompile",          // disasm({target:'decompile'}) — RE engine, all 14
+]);
+
+// Generic regions every running core exposes (libretro RETRO_MEMORY_*).
+const GENERIC_REGIONS = ["system_ram", "save_ram", "video_ram", "rtc"];
+
+/** @typedef {{ cpuFamily:string, renderingKind:"tile"|"framebuffer"|"3d"|"none",
+ *   introspection:"deep"|"shallow", ops:Record<string,boolean>,
+ *   decompileQuality:string, cpus:{main:string, secondary:string[]},
+ *   audioChips:string[], memoryRegions:string[] }} Capability */
+
+const tileDeep = ({ ops: opsOverride = {}, ...rest } = {}) => ({
+  renderingKind: "tile", introspection: "deep",
+  ...rest,
+  ops: {
+    build: true, run: true, screenshot: true,
+    inspectSprites: true, inspectPalette: true, inspectBackground: true,
+    renderingContext: true, cpuState: true, audioDebug: true,
+    cart: true, disasm: true, decompile: true,
+    ...opsOverride,
+  },
+});
+
+/** @type {Record<string, Capability>} */
+export const CAPABILITIES = {
+  nes: {
+    cpuFamily: "6502", decompileQuality: "rough",
+    cpus: { main: "6502", secondary: [] },
+    audioChips: ["nes"],
+    memoryRegions: [...GENERIC_REGIONS, "nes_nametables", "nes_palette", "nes_oam",
+      "nes_chr", "nes_apu_regs", "nes_cpu_regs", "nes_ppu_regs"],
+    ...tileDeep(),
+  },
+  snes: {
+    cpuFamily: "65816", decompileQuality: "medium",
+    cpus: { main: "65816", secondary: ["spc700"] },
+    audioChips: ["dsp"],
+    memoryRegions: [...GENERIC_REGIONS, "snes_oam", "snes_cgram", "snes_aram", "snes_fillram"],
+    ...tileDeep(),
+  },
+  genesis: {
+    cpuFamily: "m68k", decompileQuality: "excellent",
+    cpus: { main: "m68k", secondary: [] }, // z80 not yet decoded
+    audioChips: ["ym2612", "psg"],
+    memoryRegions: [...GENERIC_REGIONS, "genesis_cram", "genesis_vsram", "genesis_vdp_regs",
+      "genesis_z80_ram", "genesis_m68k", "genesis_ym2612", "genesis_psg"],
+    ...tileDeep(),
+  },
+  sms: {
+    cpuFamily: "z80", decompileQuality: "good",
+    cpus: { main: "z80", secondary: [] },
+    audioChips: ["psg"],
+    memoryRegions: [...GENERIC_REGIONS, "sms_vram", "sms_cram", "sms_vdp_regs", "sms_z80_regs"],
+    ...tileDeep(),
+  },
+  gg: {
+    cpuFamily: "z80", decompileQuality: "good",
+    cpus: { main: "z80", secondary: [] },
+    audioChips: ["psg"],
+    memoryRegions: [...GENERIC_REGIONS, "gg_vram", "gg_cram"],
+    ...tileDeep(),
+  },
+  gb: {
+    cpuFamily: "sm83", decompileQuality: "good",
+    cpus: { main: "sm83", secondary: [] },
+    audioChips: ["gb"],
+    memoryRegions: [...GENERIC_REGIONS, "gb_vram", "gb_oam", "gb_io", "gb_hram",
+      "gb_bgpdata", "gb_objpdata", "gb_cpu_regs"],
+    ...tileDeep(),
+  },
+  gbc: {
+    cpuFamily: "sm83", decompileQuality: "good",
+    cpus: { main: "sm83", secondary: [] },
+    audioChips: ["gb"],
+    memoryRegions: [...GENERIC_REGIONS, "gb_vram", "gb_oam", "gb_io", "gb_hram",
+      "gb_bgpdata", "gb_objpdata", "gb_cpu_regs"],
+    ...tileDeep(),
+  },
+  gba: {
+    cpuFamily: "arm", decompileQuality: "excellent",
+    cpus: { main: "arm", secondary: [] },
+    audioChips: ["gba"],
+    memoryRegions: [...GENERIC_REGIONS, "gba_cpu_regs", "gba_io_regs", "gba_palette", "gba_oam"],
+    // GBA: the patched mgba regions give MORE than BUILDING.md's old "shallow"
+    // prose implied — inspectSprites/Palette + renderingContext + cpuState +
+    // audioDebug are all wired (per the tool Supported lists). cart extract/wrap
+    // and inspectBackgroundMap are NOT.
+    renderingKind: "tile", introspection: "shallow",
+    ops: {
+      build: true, run: true, screenshot: true,
+      inspectSprites: true, inspectPalette: true, inspectBackground: false,
+      renderingContext: true, cpuState: true, audioDebug: true,
+      cart: false, disasm: true, decompile: true,
+    },
+  },
+  atari2600: {
+    cpuFamily: "6502", decompileQuality: "rough",
+    cpus: { main: "6502", secondary: [] },
+    audioChips: [], // TIA tone, no dedicated sound chip audioDebug decodes
+    memoryRegions: [...GENERIC_REGIONS, "a26_tia_regs", "a26_cpu_regs"],
+    ...tileDeep({ ops: { audioDebug: false, inspectSprites: true, inspectBackground: false } }),
+  },
+  atari7800: {
+    cpuFamily: "6502", decompileQuality: "rough",
+    cpus: { main: "6502", secondary: [] },
+    audioChips: [], // TIA; no audioDebug decode
+    memoryRegions: [...GENERIC_REGIONS, "a78_cpu_regs"],
+    ...tileDeep({ ops: { audioDebug: false, inspectBackground: false } }),
+  },
+  c64: {
+    cpuFamily: "6502", decompileQuality: "rough",
+    cpus: { main: "6502", secondary: [] },
+    audioChips: ["sid"],
+    memoryRegions: [...GENERIC_REGIONS, "c64_color_ram", "c64_vic_regs", "c64_sid_regs",
+      "c64_cia1_regs", "c64_cia2_regs", "c64_cpu_regs"],
+    // C64 has no inspectBackgroundMap branch (character-mode screen is read via
+    // raw VIC regions, not a snapshotter).
+    ...tileDeep({ ops: { inspectBackground: false } }),
+  },
+  lynx: {
+    cpuFamily: "65c02", decompileQuality: "rough",
+    cpus: { main: "65c02", secondary: [] },
+    audioChips: ["mikey"],
+    memoryRegions: [...GENERIC_REGIONS, "lynx_cpu_regs", "lynx_hw_regs"],
+    // Lynx: sprites return the SCB list head (no fixed OAM) — counts as wired.
+    // shallow per BUILDING.md (generic introspection + sfx/music templates).
+    renderingKind: "tile", introspection: "shallow",
+    ops: {
+      build: true, run: true, screenshot: true,
+      inspectSprites: true, inspectPalette: true, inspectBackground: false,
+      renderingContext: true, cpuState: true, audioDebug: true,
+      cart: false, disasm: true, decompile: true,
+    },
+  },
+  pce: {
+    cpuFamily: "huc6280", decompileQuality: "medium",
+    cpus: { main: "", secondary: [] }, // getCPUState main NOT wired for pce
+    audioChips: ["pce"],
+    memoryRegions: [...GENERIC_REGIONS, "pce_vdc_vram", "pce_vdc_satb", "pce_vdc_regs",
+      "pce_vce_palette", "pce_cpu_regs", "pce_psg_regs"],
+    renderingKind: "tile", introspection: "deep",
+    ops: {
+      build: true, run: true, screenshot: true,
+      inspectSprites: true, inspectPalette: true, inspectBackground: false,
+      renderingContext: true, cpuState: false, audioDebug: true,
+      cart: false, disasm: true, decompile: true,
+    },
+  },
+  msx: {
+    cpuFamily: "z80", decompileQuality: "good",
+    cpus: { main: "", secondary: [] }, // getCPUState main NOT wired for msx
+    audioChips: ["ay8910"],
+    memoryRegions: [...GENERIC_REGIONS, "msx_vram", "msx_vdp_regs", "msx_vdp_status",
+      "msx_palette", "msx_cpu_regs", "msx_psg_regs"],
+    renderingKind: "tile", introspection: "deep",
+    ops: {
+      build: true, run: true, screenshot: true,
+      inspectSprites: true, inspectPalette: true, inspectBackground: false,
+      renderingContext: true, cpuState: false, audioDebug: true,
+      cart: false, disasm: true, decompile: true,
+    },
+  },
+};
+
+/** All platform ids in the contract. */
+export const CONTRACT_PLATFORMS = Object.keys(CAPABILITIES);
+
+/** Does `platform` support `op`? Unknown platform/op → false. */
+export function supports(platform, op) {
+  return Boolean(CAPABILITIES[platform]?.ops?.[op]);
+}
+
+/** The full capability entry for a platform (or null). */
+export function capabilitiesFor(platform) {
+  return CAPABILITIES[platform] ?? null;
+}

package/src/mcp/tools/disasm.js

@@ -1167,14 +1167,21 @@ export function registerDisasmTools(server, z) {
     "refs carry `prgBank` (NES) / `romBank` (everything else). LIMITATION: direct addressing only " +
     "(indirect/computed jumps are missed).\n" +
     "── RE ENGINE (Rizin + Ghidra, all 14 platforms) ──\n" +
-    "'functions' = Rizin auto-detected function list {address,size,nbbs,cc,callers,callees}; the structural map of " +
-    "an unknown ROM. 'cfg' = basic-block control-flow graph of the function at `address` (nodes + typed edges: " +
+    "'functions' = Rizin auto-detected function list {address,size,nbbs,cc,callers,callees,looksLikeData}; the " +
+    "structural map of an unknown ROM. Sorted REAL CODE FIRST (by nbbs/cc) — don't rank by `size`, which is a lie " +
+    "(rizin folds data tables into giant pseudo-functions). `looksLikeData:true` (and the top-level `dataCount`) flags " +
+    "those data-folds so you don't waste a decompile on a graphics blob. " +
+    "'cfg' = basic-block control-flow graph of the function at `address` (nodes + typed edges: " +
     "jump/branch_true/branch_false). 'xrefs' = every cross-reference TO `address`, following Rizin's analysis graph " +
     "(DEEPER than 'references', which is a flat da65 operand scan — prefer 'xrefs' once you've run a function pass, " +
     "'references' for a quick header-less operand sweep). Typical RE loop: 'functions' to carve → 'cfg'/'xrefs' to " +
     "trace → then the live tools (memory search, write-breakpoints, watch copy) to LABEL what you carved.\n" +
     "'decompile' = Ghidra C-like PSEUDOCODE for the function at `address`, with the decompiler's own WARNINGs and a " +
-    "`qualityNote`. ALTITUDE RULE: decompile is for UNDERSTANDING (and as a port spec when retargeting to a bigger " +
+    "`qualityNote`. Hardware-register MMIO is NAMED in the output (e.g. `PPUMASK = 0x1e;` not `*0x2001 = 0x1e;`) " +
+    "with a `/* hw registers: … */` legend at the top listing each substitution — on platforms with a register map " +
+    "(NES/SNES/Genesis/GB/GBC/SMS/GG/2600/7800/C64). On the 6502 family (NES/2600/7800/C64/Lynx/PCE) a 6502-fold pass also " +
+    "cleans the SLEIGH clutter: width types become C99 stdint (uint1→uint8_t, uint2→uint16_t), redundant nested width " +
+    "casts collapse, and zero-page byte refs are named zp_XX — a `/* 6502 fold: … */` legend notes what was applied. ALTITUDE RULE: decompile is for UNDERSTANDING (and as a port spec when retargeting to a bigger " +
     "machine) — it is NOT the same-platform edit path. To CHANGE a ROM and rebuild it, use target:'project' " +
     "(byte-exact rebuildable asm); read the pseudocode as documentation alongside it. Per-CPU quality (calibrate, " +
     "don't treat low quality as a bug): ARM/GBA + M68K/Genesis = excellent (mostly-C games, real stack frames); " +
@@ -1183,7 +1190,7 @@ export function registerDisasmTools(server, z) {
     "LLM folds it. `address` for all four comes from target:'functions' (a CPU/virtual address; the file-offset " +
     "mapping is handled for you).",
     {
-      target: z.enum(["bytes", "rom", "project", "references", "cfg", "xrefs", "functions", "decompile"]).describe("bytes = raw chunk; rom = mapper-aware ROM; project = full rebuildable disasm; references = flat da65 operand-refs to an address; functions/cfg/xrefs = Rizin RE engine (function list / control-flow graph / deep graph xrefs); decompile = Ghidra C pseudocode. See the tool description for the RE loop + the decompile altitude rule + per-CPU quality (all 14 platforms)."),
+      target: z.enum(["bytes", "rom", "project", "references", "cfg", "xrefs", "functions", "decompile", "resolveJumptable"]).describe("bytes = raw chunk; rom = mapper-aware ROM; project = full rebuildable disasm; references = flat da65 operand-refs to an address; functions/cfg/xrefs = Rizin RE engine (function list / control-flow graph / deep graph xrefs); decompile = Ghidra C pseudocode; resolveJumptable = recover a computed-jump dispatcher's targets (LIVE — redirects to breakpoint({on:'jumptable'}), which runs the emulator and records the real switch arms a static decompiler can't follow). See the tool description for the RE loop + the decompile altitude rule + per-CPU quality (all 14 platforms)."),
       // shared
       path: z.string().optional().describe("target=bytes: raw binary path. target=rom/project/references: ROM file path."),
       base64: z.string().optional().describe("target=bytes: base64 of the bytes (OR `path`)."),
@@ -1227,6 +1234,18 @@ export function registerDisasmTools(server, z) {
         case "xrefs":      return jsonContent(await analyzeXrefs(requireRomPath(args), args.address, args.platform));
         case "functions":  return jsonContent(await analyzeFunctions(requireRomPath(args), args.platform));
         case "decompile":  return jsonContent(await analyzeDecompile(requireRomPath(args), args.address, args.platform));
+        case "resolveJumptable":
+          // A4: jumptable recovery is fundamentally a LIVE operation (it needs a
+          // running emulator to observe the computed targets) — disasm is static
+          // ROM analysis with no session. Redirect to the live op rather than
+          // silently doing nothing.
+          return jsonContent({
+            live: true,
+            redirect: "breakpoint({on:'jumptable'})",
+            address: args.address != null ? "$" + (args.address >>> 0).toString(16).toUpperCase() : null,
+            note: "Computed-jumptable recovery is LIVE, not static: it breaks at the dispatcher in a RUNNING emulator, single-steps through the indirect JMP (table,X)/RTS-trick, and records the targets it actually lands on. Load the ROM (playtest/loadMedia), drive it to the state that runs the dispatcher, then call breakpoint({on:'jumptable', address" +
+              (args.address != null ? `: ${args.address}` : "") + "}). That returns the distinct computed targets; decompile({address: target}) each to read the switch arms. No static-only tool can do this — it needs the live emulator.",
+          });
         default: throw new Error(`disasm: unknown target '${args.target}'`);
       }
     }),

package/src/mcp/tools/platform-tools.js

@@ -6,7 +6,7 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { PNG } from "pngjs";
 import { getHost } from "../state.js";
-import { imageContent, jsonContent } from "../util.js";
+import { imageContent, jsonContent, unsupported } from "../util.js";
 
 // Consolidation: several handlers in this big shared file are extracted as
 // *Core functions that the consolidated domain tools (palette/tiles/background/
@@ -338,7 +338,10 @@ export function registerPlatformTools(server, z, sessionKey) {
         }, png);
       }
 
-      throw new Error(`inspectPalette not yet wired for platform '${p}'. Supported: nes, snes, genesis, sms, gg, gb, gbc, atari2600, atari7800, c64, gba, lynx, pce, msx.`);
+      unsupported(p, "inspectPalette", {
+        reason: "no palette decoder for this platform",
+        alternative: "platform({op:'capabilities'}) to see what's wired",
+      });
   };
 
   // getCPUState → cpu({op:'read'}) (router in watch-memory.js). Live-binding core.
@@ -347,7 +350,10 @@ export function registerPlatformTools(server, z, sessionKey) {
       const p = resolvePlatform(host, platform);
       const state = getCPUState(host, p, cpu);
       if (!state) {
-        throw new Error(`getCPUState: no decoder for platform '${p}' cpu '${cpu}'. Main CPU is wired for nes, snes, genesis, sms, gg, gb, gbc, atari2600, atari7800, c64, lynx, gba. Secondary CPUs: snes 'spc700' (genesis 'z80' not yet decoded).`);
+        unsupported(p, "cpuState", {
+          reason: `no ${cpu === "main" ? "main" : `'${cpu}'`}-CPU decoder for this platform`,
+          alternative: "platform({op:'capabilities'}) shows each platform's decoded CPUs (main + secondary); memory({op:'read'}) the raw CPU-register region otherwise",
+        });
       }
       return jsonContent({ platform: p, cpu, ...state });
   };
@@ -694,7 +700,10 @@ export function registerPlatformTools(server, z, sessionKey) {
         });
       }
 
-      throw new Error(`inspectSprites not yet wired for platform '${p}'. Supported: nes, snes, genesis, sms, gg, gb, gbc, atari2600, atari7800, c64, gba, pce, msx. (Lynx returns the SCB list head — it has no fixed OAM.)`);
+      unsupported(p, "inspectSprites", {
+        reason: "no sprite decoder for this platform",
+        alternative: "memory({op:'read'}) the raw OAM/sprite-attribute region, or platform({op:'capabilities'}) to see what's wired",
+      });
   };
 
   // inspectBackgroundMap lives in the `background` tool (rendering-context.js)
@@ -803,7 +812,10 @@ export function registerPlatformTools(server, z, sessionKey) {
         });
         return emitImage(r.png, `SNES BG map composite (${r.width}×${r.height}, ${r.mapWidth}×${r.mapHeight} tiles, ${r.bpp}bpp, tilemap@0x${tilemapBaseByte.toString(16)}, tiles@0x${tileBaseByte.toString(16)}). ${r.note}`);
       }
-      throw new Error(`inspectBackgroundMap not yet implemented for platform '${p}'`);
+      unsupported(p, "inspectBackground", {
+        reason: "no background-map snapshotter for this platform",
+        alternative: "background({view:'renderState'}) for the register-level context, or memory({op:'read'}) the raw VRAM/nametable region",
+      });
   };
 
   // convertImageToTiles → encodeArt({stage:'tiles'}) (router in sprite-pipeline.js).

package/src/mcp/tools/platforms.js

@@ -2,6 +2,7 @@ import { CORES, listAvailableCores, resolveCore } from "../../cores/registry.js"
 import { TOOLCHAINS } from "../../toolchains/registry.js";
 import { getLanguageOptions } from "../../toolchains/index.js";
 import { jsonContent, safeTool } from "../util.js";
+import { CAPABILITIES, CONTRACT_PLATFORMS, capabilitiesFor } from "../../cores/capabilities.js";
 import { listToolchainsCore, installToolchainCore } from "./toolchain.js";
 import { listPlatformDocsCore, getPlatformDocCore } from "./platform-docs.js";
 
@@ -99,11 +100,17 @@ export function resolvePlatformCore({ platform }) {
 export function registerPlatformTools(server, z) {
   server.tool(
     "platform",
-    "Platform/toolchain/docs discovery — what romdev can run and how. `op`: 'list' | 'resolve' | 'toolchains' | " +
-    "'docs' | 'doc'.\n" +
+    "Platform/toolchain/docs discovery — what romdev can run and how. `op`: 'list' | 'capabilities' | 'resolve' | " +
+    "'toolchains' | 'docs' | 'doc'.\n" +
     "'list': every platform with its emulator core, toolchain(s), available languages (+ documented default), and " +
     "platform-specific quirks. Call this FIRST to discover what's possible + check a non-default language is " +
     "available before asking build for it.\n" +
+    "'capabilities': the CAPABILITY CONTRACT — which platform-sensitive ops a platform supports (inspectSprites/" +
+    "Palette/Background, cpuState, audioDebug, renderingContext, cart, disasm, decompile), plus its cpuFamily, " +
+    "renderingKind (tile/framebuffer/3d), introspection depth, CPUs, audio chips, and memory regions. Pass `platform` " +
+    "for one, omit it for the whole matrix. Check this BEFORE calling a platform-sensitive tool to avoid an " +
+    "'unsupported' error — every tool that can't do an op on a platform returns {unsupported:true, platform, op, " +
+    "reason, alternative}.\n" +
     "'resolve': resolved core paths for a platform (debugging aid).\n" +
     "'toolchains': the bundled homebrew toolchains (all Tier-1 = bundled WASM, no install). Pass `id` to confirm a " +
     "specific toolchain's install status (a no-op in v1 — everything's bundled).\n" +
@@ -111,7 +118,7 @@ export function registerPlatformTools(server, z) {
     "troubleshooting / upstream_sources; `platform:'romhacking'` + `name:'playbook'` for the RE decision tree). " +
     "Read MENTAL_MODEL before writing code, and the romhacking playbook before a hack.",
     {
-      op: z.enum(["list", "resolve", "toolchains", "docs", "doc"]).describe("list=platforms; resolve=core paths; toolchains; docs=a platform's doc names; doc=read one doc."),
+      op: z.enum(["list", "capabilities", "resolve", "toolchains", "docs", "doc"]).describe("list=platforms; capabilities=per-platform op support matrix; resolve=core paths; toolchains; docs=a platform's doc names; doc=read one doc."),
       platform: z.string().optional().describe("op=resolve/docs/doc: platform id (e.g. nes, gb, genesis; 'romhacking' for the RE playbook)."),
       id: z.string().optional().describe("op=toolchains: a specific toolchain's install status (e.g. 'cc65')."),
       name: z.string().optional().describe("op=doc: which doc — mental_model | troubleshooting | upstream_sources | playbook."),
@@ -119,6 +126,14 @@ export function registerPlatformTools(server, z) {
     safeTool(async (args) => {
       switch (args.op) {
         case "list":    return jsonContent(listPlatformsCore());
+        case "capabilities": {
+          if (args.platform) {
+            const cap = capabilitiesFor(args.platform);
+            if (!cap) throw new Error(`platform({op:'capabilities'}): unknown platform '${args.platform}'. Known: ${CONTRACT_PLATFORMS.join(", ")}.`);
+            return jsonContent({ platform: args.platform, ...cap });
+          }
+          return jsonContent({ platforms: CONTRACT_PLATFORMS, capabilities: CAPABILITIES });
+        }
         case "resolve": {
           if (!args.platform) throw new Error("platform({op:'resolve'}): `platform` is required.");
           return jsonContent(resolvePlatformCore(args));

package/src/mcp/tools/rendering-context.js

@@ -9,7 +9,7 @@
 
 import { readFileSync } from "node:fs";
 import { getHost } from "../state.js";
-import { jsonContent, safeTool } from "../util.js";
+import { jsonContent, safeTool, unsupported } from "../util.js";
 import { inspectBackgroundMapCore } from "./platform-tools.js";
 import { whichTilesAreRenderedCore } from "./which-tiles.js";
 
@@ -530,9 +530,10 @@ export async function getRenderingContextCore({ platform, area = "all", sessionK
     case "pce":   return pceContext(host, area);
     case "msx":   return msxContext(host, area);
     default:
-      throw new Error(
-        `getRenderingContext: unknown platform '${p}'. Supported: nes, snes, genesis, gb, gbc, sms, gg, atari2600, atari7800, c64, gba, lynx, pce, msx.`
-      );
+      unsupported(p, "renderingContext", {
+        reason: "no rendering-context decoder for this platform",
+        alternative: "platform({op:'capabilities'}) to see what's wired",
+      });
   }
 }
 

package/src/mcp/tools/watch-memory.js

@@ -793,6 +793,138 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
       }), host);
   }
 
+  // A4: Computed-jumptable recovery via the LIVE emulator. Static analysis follows
+  // direct addressing only, so a `JMP (table,X)` / RTS-trick dispatcher collapses
+  // to "Could not recover jumptable" — and those dispatchers (game-state machines,
+  // script/event VMs, battle engines) are the routines you most want to read. We
+  // resolve them dynamically: break at the dispatcher, single-step THROUGH the
+  // indirect transfer, and record the PC it actually lands on. Run across many
+  // frames/inputs to accumulate the distinct target set — the real switch arms.
+  //
+  // No standalone tool (IDA/Ghidra/Binary Ninja) can do this: they have no live
+  // emulator to observe the computed target. The observed set can be fed back as
+  // analysis hints (Rizin ahi/aho) so `decompile`/`cfg` recover the switch.
+  async function bpResolveJumptable({ address, maxFrames = 1200, maxTargets = 64, stepLimit = 48, jumpThreshold = 5, pressDuring, fromState, fromStatePath }) {
+      const host = getHost(sessionKey);
+      if (!host.pcBreakSupported || !host.pcBreakSupported()) {
+        return jsonContent({
+          ok: false, notSupported: true, address: "$" + address.toString(16).toUpperCase(),
+          note: "This core build has no PC breakpoint / single-step (shipped on all 14 platforms as of 0.5.0 — update the core package if you see this).",
+        });
+      }
+      const restored = await maybeRestoreState(host, fromState, fromStatePath);
+      const presses = (pressDuring ?? []).slice().sort((a, b) => a.frame - b.frame);
+      const pressDriver = makePressDriver(host, presses);
+
+      // We separate COMPUTED targets from FIXED trampolines by what VARIES. As we
+      // single-step out of the dispatcher, normal flow is sequential (next PC =
+      // prev + 1..4 on a 6502, wider on ARM); a computed JMP (table,X) / RTS-trick
+      // makes the PC LEAP (delta > jumpThreshold or backward). But a real dispatch
+      // path contains FIXED leaps too — cc65 lowers an indirect call to
+      // JSR<callax>; JMP(ptr), so the trampoline addresses leap identically on
+      // every hit. The handler ARM is the leap destination that DIFFERS hit-to-
+      // hit. So: per hit, collect the set of leap destinations; across all hits,
+      // a destination seen on EVERY hit is a fixed trampoline (drop it), and one
+      // seen on only SOME hits is a real computed arm (keep it). leapSeen counts
+      // how many hits each destination appeared in; perHitLeaps holds the firstFrame
+      // + a sample fromPC for the keepers.
+      const leapSeen = new Map();   // destPC -> hitCount
+      const leapMeta = new Map();   // destPC -> { firstFrame, fromPC }
+      let dispatcherHits = 0, framesRun = 0;
+
+      try {
+        for (let i = 0; i < maxFrames && leapMeta.size < maxTargets * 4; i++) {
+          pressDriver.applyForFrame(i);
+          host.setPCBreak(address, true, false);
+          host.stepFrames(1);
+          framesRun++;
+          let st = host.getPCBreak(false);
+          if (!st.hit) { host.setPCBreak(0, false, false); continue; }
+
+          const fromPC = st.lastPC ?? address;
+          host.getPCBreak(true); // clear the hit so the next arm is clean
+          // Walk forward; collect the destination of EVERY control-flow leap in
+          // this hit (deduped within the hit), plus the PC it leapt FROM.
+          const seenThisHit = new Set();
+          let prev = fromPC, prevLeapFrom = fromPC;
+          for (let s = 0; s < stepLimit; s++) {
+            const step = host.stepInstruction(); // { pc } AFTER one instr
+            const pc = step.pc;
+            if (pc == null) break;
+            const delta = pc - prev;
+            if (delta < 0 || delta > jumpThreshold) {
+              if (!seenThisHit.has(pc)) {
+                seenThisHit.add(pc);
+                if (!leapMeta.has(pc)) leapMeta.set(pc, { firstFrame: framesRun, fromPC: prevLeapFrom });
+              }
+              prevLeapFrom = prev;
+            }
+            prev = pc;
+          }
+          for (const pc of seenThisHit) leapSeen.set(pc, (leapSeen.get(pc) ?? 0) + 1);
+          dispatcherHits++;
+        }
+      } finally {
+        pressDriver.finish();
+        host.setPCBreak(0, false, false); // disarm
+        if (host.getRegSnapshot) host.getRegSnapshot(true); // consume any stale snapshot
+      }
+
+      const hx = (v) => "$" + (v >>> 0).toString(16).toUpperCase();
+      // Classify each leap destination. A COMPUTED arm VARIES across hits — it was
+      // reached on some hits but not all (leapSeen < dispatcherHits). A FIXED
+      // trampoline (cc65 callax, the post-handler return path) leaps identically
+      // EVERY hit (leapSeen == dispatcherHits). Keep the variers as targets.
+      const allLeaps = [...leapMeta.entries()].map(([pc, m]) => ({
+        pc, hits: leapSeen.get(pc) ?? 0, firstFrame: m.firstFrame, fromPC: m.fromPC,
+      }));
+      let arms = allLeaps.filter((l) => l.hits < dispatcherHits);
+      // Fallback: if NOTHING varied (the dispatcher only ever took one path under
+      // this input — a single observed arm), report the non-trampoline leaps as
+      // candidate targets rather than nothing. With only one hit, everything has
+      // hits==1==dispatcherHits, so report all leaps as candidates.
+      let singleArm = false;
+      if (!arms.length && allLeaps.length) { arms = allLeaps; singleArm = true; }
+
+      const sorted = arms
+        .slice(0, maxTargets)
+        .map((l) => ({ target: hx(l.pc), targetRaw: l.pc, hits: l.hits, firstFrame: l.firstFrame, fromPC: hx(l.fromPC) }))
+        .sort((a, b) => b.hits - a.hits || a.targetRaw - b.targetRaw);
+
+      if (!sorted.length) {
+        const drove = presses.length > 0;
+        return attachObserverFrame(jsonContent({
+          ok: true, resolved: false,
+          address: hx(address), framesRun, dispatcherHits,
+          ...(restored ? { restoredFrom: restored } : {}),
+          ...(presses.length ? { pressesScheduled: presses.length, pressesApplied: pressDriver.applied() } : {}),
+          note: dispatcherHits === 0
+            ? (drove
+              ? "The dispatcher at this address never executed within maxFrames EVEN WITH the scheduled input — likely the WRONG address (a different routine dispatches), or not an instruction boundary. Confirm with breakpoint({on:'pc'}) that the PC reaches it at all."
+              : "The dispatcher never executed — drive the game to the state that runs it (pressDuring / fromState), or increase maxFrames. Confirm reachability with breakpoint({on:'pc'}).")
+            : "The dispatcher executed but no control-flow LEAP was observed in the next " + stepLimit + " instructions — so this address isn't (or isn't reaching) a computed jump. Confirm it's the indirect-jump instruction, or raise stepLimit if the dispatch does heavy setup first.",
+        }), host);
+      }
+
+      return attachObserverFrame(jsonContent({
+        ok: true, resolved: true,
+        address: hx(address),
+        targets: sorted,
+        distinctTargets: sorted.length,
+        dispatcherHits, framesRun,
+        ...(singleArm ? { singleArmObserved: true } : {}),
+        ...(arms.length > maxTargets ? { truncated: true, truncatedAt: maxTargets } : {}),
+        ...(restored ? { restoredFrom: restored } : {}),
+        ...(presses.length ? { pressesScheduled: presses.length, pressesApplied: pressDriver.applied() } : {}),
+        note: (singleArm
+            ? "Only ONE dispatch path ran under this input, so targets are the candidate leap destinations (couldn't separate the computed arm from fixed trampolines without a second arm to compare). Drive MORE game states (pressDuring / fromState) so the dispatcher takes different arms — then the varying one is isolated as the real target. "
+            : "targets are the COMPUTED jump destinations that VARIED across dispatches — the real switch arms a static decompiler can't see (fixed trampolines were filtered out). ") +
+          "Each is a routine the dispatcher branches to; decompile({address: target}) / disasm({target:'rom', startAddress: target}) to read them. " +
+          "hits = how many dispatches took that arm under this input; drive more states to surface rarer arms. " +
+          "This is the live-emulator advantage: no static-only tool can recover these.",
+      }), host);
+  }
+
   async function bpRunUntilRead({ address, maxFrames = 600, pressDuring }) {
       const host = getHost(sessionKey);
       if (!host.readWatchSupported || !host.readWatchSupported()) {
@@ -862,11 +994,12 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
     "use it, NOT a follow-up cpu({op:'read'}). On some cores (notably NES/fceumm) the core drains the cycle budget on hit but the frame still finishes, " +
     "so a live cpu read afterward returns END-OF-FRAME registers, not the break instant. `registersAtHit` sidesteps that. The break PC is reported as `pc`/`pcRaw`; " +
     "the RAM side effects are also reliable via memory({op:'read'}). frame({op:'stepInstruction'}) to single-step from the break. (on:'read'/'write' finish the frame.)\n" +
+    "• on:'jumptable' — **RESOLVE a computed-jump dispatcher the static decompiler can't follow.** Game-state machines, script/event VMs, and battle engines dispatch through `JMP (table,X)` / RTS-trick tables; `decompile`/`cfg` collapse them to `(*_IRQ)()` + 'Could not recover jumptable'. Break at the dispatcher `address`, single-step THROUGH the indirect transfer, and record the PC it lands on — repeated across frames/inputs to accumulate the DISTINCT target set (the real switch arms), ranked by hit count. Drive more game states (pressDuring / fromState) to surface rarer arms. Returns `{targets:[{target,hits,fromPC}], distinctTargets}`. **No static-only tool (IDA/Ghidra/Binary Ninja) can do this — it needs a live emulator in the loop, which is romdev's edge.** Feed the targets to decompile({address:target}) to read each arm.\n" +
     "All supported on every CPU core. **Every hit carries `registersAtHit` — the FULL register file frozen by the core AT the hit instant, on ALL 14 platforms and all three `on` kinds.** Use it instead of a follow-up cpu({op:'read'}): the live registers keep moving after a hit (per-scanline CPU scheduling / frame completion), so a post-hit read drifts — chasing pointer registers read that way burned a real session for hours. The hit `pc` is the EXECUTING instruction's first byte (mid-instruction hooks no longer report the operand-advanced PC). Out-of-date core packages return notSupported.\n" +
     "MENU-SCREEN INPUT TRICK: if a pressDuring schedule never registers (some menu screens poll input in a way scheduled taps miss), HOLD the button instead: input({op:'set', buttons:{...}}) BEFORE this call and OMIT pressDuring — the run inherits the held state, the menu sees the edge, and the breakpoint catches the event.",
     {
-      on: z.enum(["write", "read", "pc"])
-        .describe("write=break on a write to address (precision:exact=true writer PC / sampled=frame PC, a lie under IRQ); read=break on a read (exact PC, who consumes it); pc=break when PC reaches address — the hit returns `registersAtHit` (the break-instant register file, all 14 platforms) + the break PC; use registersAtHit, not a follow-up cpu read (end-of-frame state)."),
+      on: z.enum(["write", "read", "pc", "jumptable"])
+        .describe("write=break on a write to address (precision:exact=true writer PC / sampled=frame PC, a lie under IRQ); read=break on a read (exact PC, who consumes it); pc=break when PC reaches address — the hit returns `registersAtHit` (the break-instant register file, all 14 platforms) + the break PC; jumptable=RESOLVE a computed-jump dispatcher (JMP (tbl,X) / RTS-trick) by breaking at `address`, single-stepping THROUGH the indirect transfer, and recording every COMPUTED target PC live across frames/inputs — the switch arms a static decompiler reports as 'Could not recover jumptable'. (use registersAtHit, not a follow-up cpu read.)"),
       precision: z.enum(["exact", "sampled"]).default("exact")
         .describe("on:'write' ONLY. exact=core watchpoint, the real writing instruction PC even under interrupts (uses `address`). sampled=cheap frame-boundary PC (uses region/offset/length) — NOT the writer under IRQ. Ignored for on:read/pc (always exact)."),
       address: z.number().int().min(0).optional().describe("on:'write' exact / on:'read' / on:'pc' — CPU address to break on (write target, read target, or instruction boundary). Required for those."),
@@ -893,6 +1026,11 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
         length: z.number().int().min(1).max(256).default(1).describe("bytes to read"),
         label: z.string().optional().describe("human name for this read (else 'region+offset')"),
       })).optional().describe("on:'pc' — read these memory regions AT the hit and return them inline as `capturedMemory` (collapses break→read-RAM into ONE call, the token win). Pair with `registersAtHit` to get the routine's register + RAM state in a single round trip (e.g. capture the ZP pointer bytes a decoder just wrote). NOTE: registersAtHit is the true break instant (core snapshot); these RAM reads are taken after the hit frame finishes, so on run-to-frame-end cores (fceumm) they're the routine's RAM side effects for that frame — stable + reliable, which is exactly what RE needs."),
+      maxTargets: z.number().int().min(1).max(1024).default(64).describe("on:'jumptable' — stop once this many DISTINCT computed targets have been observed (the run also ends at maxFrames). Sets `truncated:true` if reached."),
+      stepLimit: z.number().int().min(1).max(256).default(48).describe("on:'jumptable' — instructions to single-step after each dispatcher hit while collecting control-flow leaps. Must be deep enough to REACH the handler: a compiler-lowered indirect call (cc65 JSR<callax>; JMP(ptr)) runs the table load + trampoline + the indirect jump before the handler is entered — ~30 instructions here, so the default is 48. Too low and you only capture the fixed trampolines (the real arms never appear); raise it if a dispatch does heavy setup before the indirect jump."),
+      jumpThreshold: z.number().int().min(1).max(64).default(5).describe("on:'jumptable' — a single-step whose PC delta exceeds this many bytes (or goes backward) counts as a control-flow LEAP (a taken jump/branch/call), vs sequential instruction flow. 5 suits 6502/Z80/SM83 (max ~3-byte instructions); raise for wider ISAs (ARM/m68k) so multi-byte sequential instructions aren't misread as leaps."),
+      fromState: z.number().int().min(0).optional().describe("on:'jumptable'/'pc' (via the trace path) — restore this in-memory savestate SLOT before running, so the dispatcher is resolved from a known, repeatable moment (e.g. inside the battle/menu the dispatcher drives). Mutually exclusive with fromStatePath."),
+      fromStatePath: z.string().optional().describe("on:'jumptable' — restore this savestate FILE before running (the disk equivalent of fromState). Mutually exclusive with fromState."),
     },
     safeTool(async (args) => {
       switch (args.on) {
@@ -912,6 +1050,10 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
           if (args.address == null) throw new Error("breakpoint({on:'pc'}): `address` is required.");
           return await bpRunUntilPC(args);
         }
+        case "jumptable": {
+          if (args.address == null) throw new Error("breakpoint({on:'jumptable'}): `address` is required (the computed-jump dispatcher).");
+          return await bpResolveJumptable(args);
+        }
         default: throw new Error(`breakpoint: unknown on '${args.on}'`);
       }
     }),

package/src/mcp/util.js

@@ -62,12 +62,49 @@ export function imageContent(pngBase64) {
 
 /** Wrap an Error as a tool error result. */
 export function errorContent(err) {
+  // UnsupportedError carries the structured capability-contract fields so an
+  // agent can branch on `unsupported: true` instead of string-matching the
+  // message. We surface BOTH a clean sentence and the structured fields.
+  if (err && err.name === "UnsupportedError") {
+    const text = err.message + (err.alternative ? ` (try: ${err.alternative})` : "");
+    return {
+      isError: true,
+      unsupported: true,
+      platform: err.platform,
+      op: err.op,
+      reason: err.reason ?? null,
+      alternative: err.alternative ?? null,
+      content: [{ type: "text", text }],
+    };
+  }
   return {
     isError: true,
     content: [{ type: "text", text: String(err?.message ?? err) }],
   };
 }
 
+/**
+ * The single, uniform "this platform doesn't support this op" signal. Throws a
+ * typed UnsupportedError that safeTool → errorContent formats consistently
+ * (and that programmatic callers / the conformance test can catch + inspect).
+ * Replaces the ad-hoc "not supported"/"not yet wired" throws.
+ *
+ * @param {string} platform
+ * @param {string} op        a capability op key (see cores/capabilities.js OP_KEYS)
+ * @param {{reason?:string, alternative?:string}} [opts]
+ * @returns {never}
+ */
+export function unsupported(platform, op, { reason, alternative } = {}) {
+  const base = `'${op}' is not supported on platform '${platform}'`;
+  const err = new Error(reason ? `${base}: ${reason}` : base + ".");
+  err.name = "UnsupportedError";
+  err.platform = platform;
+  err.op = op;
+  err.reason = reason ?? null;
+  err.alternative = alternative ?? null;
+  throw err;
+}
+
 /**
  * Wrap a tool implementation so any thrown error becomes a structured tool
  * error rather than a transport-layer exception.