romdevtools 0.13.0

package/src/mcp/tools/cheats.js

@@ -0,0 +1,343 @@
+import path from "node:path";
+import { readFile } from "node:fs/promises";
+import { getHost } from "../state.js";
+import { jsonContent, safeTool } from "../util.js";
+import { lookupCheats, searchCheatGames } from "../../cheats/lookup.js";
+import { encodeForDevice, nativeDevicesFor, decodeCode } from "../../cheats/gamegenie.js";
+
+// Per-platform cheat address space (for makeCheat validation). A Game Genie
+// letter code can only address these ranges; out-of-range → raw ADDR:VAL only.
+const GG_ADDR_RANGE = {
+  nes: [0x8000, 0xFFFF],      // PRG space (mapped ROM)
+  gb: [0x0002, 0x7FFF],       // ROM
+  gbc: [0x0002, 0x7FFF],
+  genesis: [0x000000, 0xFFFFFF],
+  megadrive: [0x000000, 0xFFFFFF],
+  md: [0x000000, 0xFFFFFF],
+  snes: [0x008000, 0xFFFFFF], // mapped ROM ($xx:8000-$xx:FFFF); the Game Genie
+                              // ROM device patches here. (Pro Action Replay is
+                              // a RAM poke — for a ROM patch we pick GG below.)
+};
+
+// The native ROM-PATCH device per platform (installs a read-intercept), as
+// opposed to the RAM-poke device. Used when a raw ROM-range code must be
+// re-encoded so it actually takes effect. SMS/GG are intentionally absent:
+// Action Replay is a RAM device and SMS/GG cheats are RAM addresses, so a raw
+// SMS/GG code is already a correct RAM poke — nothing to re-encode.
+const ROM_PATCH_DEVICE = {
+  nes: "game-genie",
+  genesis: "game-genie", megadrive: "game-genie", md: "game-genie",
+  gb: "game-genie", gbc: "game-genie",
+  snes: "game-genie",   // NOT pro-action-replay (that's the RAM device)
+};
+
+/**
+ * Resolve a user-supplied cheat code into the string to hand the core, fixing
+ * the raw-ROM-cheat footgun: a raw `ADDR:VAL[:COMPARE]` on a ROM address is
+ * decoded by the core as a per-frame RAM poke (silently no-ops on read-only
+ * ROM), so we re-encode it to the platform's ROM-patch device (a read-
+ * intercept). Native-device codes (no `:`) pass through unchanged. Shared by
+ * applyCheat and loadMedia({cheats}).
+ * @param {string} rawCode
+ * @param {string|null} platform
+ * @returns {{ code: string, appliedAs: "ram"|"rom"|"raw"|"rom-unencodable", reencodedFrom: string|null }}
+ */
+export function resolveCheatCodeForApply(rawCode, platform) {
+  let code = rawCode, appliedAs = "raw", reencodedFrom = null;
+  const isRawForm = typeof rawCode === "string" && rawCode.includes(":");
+  if (isRawForm && platform) {
+    const decoded = decodeCode(rawCode, platform);
+    const range = GG_ADDR_RANGE[platform];
+    const inRom = decoded && range && decoded.address >= range[0] && decoded.address <= range[1];
+    if (inRom) {
+      const dev = ROM_PATCH_DEVICE[platform];
+      const enc = dev ? encodeForDevice(decoded, platform, dev) : null;
+      if (enc && enc.code) { code = enc.code; appliedAs = "rom"; reencodedFrom = rawCode; }
+      else appliedAs = "rom-unencodable";
+    } else if (decoded) {
+      appliedAs = "ram";
+    }
+  }
+  return { code, appliedAs, reencodedFrom };
+}
+
+// Platforms that have a bundled cheat INDEX (a DB to look up with gameCheats).
+// These are exactly the platforms the romdev_game_codes package ships an index for
+// (the romdev platforms the community cheats tree actually covers). All tier-1
+// cores expose retro_cheat_set, so applyCheat/makeCheat work everywhere (see
+// MAKE_CHEAT_PLATFORMS) — this set is specifically about a shipped DB to look
+// up. C64 is intentionally absent: the libretro-database cheats tree has no
+// "Commodore - 64" folder (zero source cheats), so there is nothing to index —
+// makeCheat still works on C64 via raw ADDR:VAL codes. (Source of truth for the
+// list is romdev_game_codes' listPlatforms(); kept inline here to avoid a load at
+// module init.)
+const SUPPORTED = new Set([
+  "nes", "gb", "gbc", "snes", "genesis", "sms", "gg",
+  "atari2600", "atari7800", "lynx", "gba", "pce", "msx",
+]);
+
+// Platforms makeCheat can CREATE a code for. Every tier-1 core decodes raw
+// ADDR:VAL via retro_cheat_set, so this is all 14 — even C64 (no DB index) and
+// gba/lynx/pce/msx (DB is apply-only / raw-poke). Native-device encoding (Game
+// Genie / PAR / GameShark / Action Replay) is added per platform by
+// nativeDevicesFor(); the rest get a verified raw code.
+const MAKE_CHEAT_PLATFORMS = [
+  "nes", "gb", "gbc", "snes", "genesis", "sms", "gg",
+  "atari2600", "atari7800", "lynx", "gba", "c64", "pce", "msx",
+];
+
+// gameCheats indexes whose codes are predominantly ENCRYPTED at the source
+// (Code Breaker / GameShark v3 on GBA), so we ship the raw code for apply but
+// CANNOT descramble it to a labeled address — the entry is apply-only, not a
+// labeled RE map. Surfaced in the gameCheats `note` so the agent doesn't expect
+// addresses it won't get.
+const APPLY_ONLY_INDEX = new Set(["gba"]);
+
+// ── *Core functions: one per cheat operation. The `cheats` tool routes to them.
+//    Stateful ops take sessionKey so getHost(sessionKey) resolves the live host.
+
+/** op:'lookup' — read-only DB lookup of a ROM's known cheats. */
+export async function cheatsLookupCore({ path: romPath, platform, filter, kind = "all" }) {
+      const mod = await import("../../rom-id/identifier.js");
+      const id = await mod.identifyFile(romPath).catch(() => null);
+      const plat = platform ?? id?.platform;
+      if (!plat || !SUPPORTED.has(plat)) {
+        return {
+          matched: false, confidence: "none", platform: plat ?? "unknown",
+          note: `No bundled cheat index for platform '${plat ?? "unknown"}'. Supported: ${[...SUPPORTED].join(", ")}.`,
+        };
+      }
+      const bytes = await readFile(romPath).catch(() => null);
+      const fileName = path.basename(romPath);
+      const res = await lookupCheats({
+        platform: plat,
+        romName: id?.title || undefined,
+        fileName,
+        bytes: bytes ? new Uint8Array(bytes) : undefined,
+      });
+      if (res.matched && res.entries) {
+        let entries = res.entries;
+        if (kind !== "all") {
+          entries = entries.filter((e) => (e.parts || []).some((p) => p && p.kind === kind));
+        }
+        if (filter) {
+          const f = filter.toLowerCase();
+          entries = entries.filter((e) => (e.desc || "").toLowerCase().includes(f));
+        }
+        // Pretty-print addresses/values as hex for the agent.
+        const pretty = entries.map((e) => ({
+          desc: e.desc,
+          code: e.code,
+          // `device` tells the agent WHICH cheat device each code is for —
+          // game-genie / pro-action-replay / gameshark / action-replay / raw —
+          // so it's never assumed to be "Game Genie".
+          parts: (e.parts || []).map((p) => {
+            if (!p) return null;
+            if (p.address == null) return { device: p.device, kind: p.kind, decoded: false };
+            return {
+              device: p.device,
+              address: "$" + p.address.toString(16).toUpperCase(),
+              value: "0x" + p.value.toString(16).toUpperCase().padStart(2, "0"),
+              ...(p.compare != null ? { compare: "0x" + p.compare.toString(16).toUpperCase().padStart(2, "0") } : {}),
+              kind: p.kind,
+            };
+          }),
+        }));
+        return {
+          ...res,
+          entryCount: pretty.length,
+          totalInGame: res.entries.length,
+          entries: pretty,
+          ...(APPLY_ONLY_INDEX.has(plat) ? {
+            mapNote: `${plat.toUpperCase()} source cheats are encrypted (Code Breaker / GameShark), so the addresses are NOT descrambled — these entries are APPLY-ONLY: the labeled \`code\` works with applyCheat (the core decodes it live), but \`parts\` carry no usable address, so this is not a labeled-address RE map the way NES/GB/etc. indexes are.`,
+          } : {}),
+        };
+      }
+      return res;
+}
+
+/** op:'search' — fuzzy game-name search in the cheat DB. */
+export async function cheatsSearchCore({ platform, query, limit }) {
+      return await searchCheatGames({ platform, query, limit });
+}
+
+/** op:'apply' — enable a cheat live (non-destructive, volatile core state). */
+export async function cheatsApplyCore({ code, desc, path: romPath, index, enabled = true }, sessionKey) {
+      const host = getHost(sessionKey);
+      if (!host.cheatsSupported || !host.cheatsSupported()) {
+        throw new Error("The loaded core does not expose the cheat interface. (Older core build — rebuild with cheat exports.)");
+      }
+      let rawCode = code;
+      let resolvedDesc;
+      if (!rawCode && desc) {
+        if (!romPath) throw new Error("applyCheat: `desc` requires `path` to look the cheat up.");
+        const mod = await import("../../rom-id/identifier.js");
+        const id = await mod.identifyFile(romPath).catch(() => null);
+        const bytes = await readFile(romPath).catch(() => null);
+        const res = await lookupCheats({
+          platform: id?.platform, romName: id?.title || undefined,
+          fileName: path.basename(romPath), bytes: bytes ? new Uint8Array(bytes) : undefined,
+        });
+        if (!res.matched) throw new Error(`applyCheat: no DB match for that ROM, so cannot resolve desc='${desc}'. Pass a raw \`code\` instead.`);
+        const f = desc.toLowerCase();
+        const entry = res.entries.find((e) => (e.desc || "").toLowerCase().includes(f));
+        if (!entry) throw new Error(`applyCheat: no cheat matching desc='${desc}' in '${res.game}'.`);
+        rawCode = entry.code;
+        resolvedDesc = entry.desc;
+      }
+      if (!rawCode) throw new Error("applyCheat: provide `code` (raw) or `desc` (+`path`).");
+
+      // Resolve the raw-ROM-cheat footgun (raw ADDR:VAL on a ROM address is a
+      // RAM poke that silently no-ops — re-encode it to a ROM-patch device). See
+      // resolveCheatCodeForApply. Shared with loadMedia({cheats}).
+      const plat = host.getStatus?.().platform ?? null;
+      const { code: codeToApply, appliedAs, reencodedFrom } = resolveCheatCodeForApply(rawCode, plat);
+
+      const unencodable = appliedAs === "rom-unencodable";
+      const slot = index != null ? index : 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,
+        code: codeToApply,
+        appliedAs,
+        ...(reencodedFrom ? { reencodedFrom } : {}),
+        ...(resolvedDesc ? { desc: resolvedDesc } : {}),
+        active: host.listActiveCheats(),
+        note: (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. `
+          : "") +
+          "Applied in volatile core state — the ROM file is untouched; reset / loadState / clearCheats removes it. " +
+          "Screenshot to see the effect (and to verify the cheat's address label is correct). " +
+          "`appliedAs` tells you how it went in: 'ram' poke, 'rom' read-intercept, 'raw' core-decoded code, or 'rom-unencodable' (a ROM address that couldn't be made into a working ROM patch).",
+      };
+}
+
+/** op:'clear' — remove ALL active cheats (volatile core-side reset). */
+export async function cheatsClearCore(_args, sessionKey) {
+      const host = getHost(sessionKey);
+      if (host.clearCheats) host.clearCheats();
+      return { cleared: true, active: host.listActiveCheats ? host.listActiveCheats() : [] };
+}
+
+/** op:'make' — CREATE a new cheat code from an address + value. */
+export async function cheatsMakeCore({ platform, address, value, values, compare, device }) {
+      const range = GG_ADDR_RANGE[platform];
+      const devices = device ? [device] : nativeDevicesFor(platform);
+
+      // Build the code set for ONE value (factored out so a `values[]` batch
+      // reuses it without a per-value round-trip).
+      const buildFor = (v) => {
+        const parts = { address, value: v, ...(compare != null ? { compare } : {}) };
+        const verify = (code) => {
+          const back = decodeCode(code, platform);
+          return !!back && back.address === address && back.value === v && (compare == null || back.compare === compare);
+        };
+        const codes = [];
+        let rangeNote;
+        for (const dev of devices) {
+          if (dev === "raw") continue; // raw always added below
+          if (dev === "game-genie" && range && (address < range[0] || address > range[1])) {
+            rangeNote = `address $${address.toString(16).toUpperCase()} is outside this platform's Game Genie range ($${range[0].toString(16).toUpperCase()}-$${range[1].toString(16).toUpperCase()}); use the raw or another device code.`;
+            continue;
+          }
+          const r = encodeForDevice(parts, platform, dev);
+          if (r && r.code && verify(r.code)) codes.push({ device: r.device, code: r.code, verified: true });
+        }
+        const raw = encodeForDevice(parts, platform, "raw").code;
+        return {
+          value: "0x" + v.toString(16).toUpperCase().padStart(2, "0"),
+          codes, raw, ...(rangeNote ? { rangeNote } : {}),
+        };
+      };
+
+      const common = {
+        platform,
+        address: "$" + address.toString(16).toUpperCase(),
+        ...(compare != null ? { compare: "0x" + compare.toString(16).toUpperCase().padStart(2, "0") } : {}),
+        kind: compare != null ? "code" : "ram",
+      };
+
+      // Batch form: one entry per value.
+      if (values && values.length) {
+        const variants = values.map(buildFor);
+        return {
+          ...common,
+          variants,
+          note: (compare != null ? "ROM/code patches" : "RAM cheats") + " for " + platform + " at " + common.address +
+            " across " + values.length + " values. Each variant carries device codes + raw. Apply any with cheats({op:'apply', code}).",
+        };
+      }
+
+      // Single-value form (back-compat).
+      if (value == null) throw new Error("makeCheat: provide `value` (single) or `values` (batch).");
+      const built = buildFor(value);
+      const primary = built.codes[0]?.code || built.raw;
+      return {
+        ...common,
+        value: built.value,
+        codes: built.codes,
+        raw: built.raw,
+        ...(built.rangeNote ? { rangeNote: built.rangeNote } : {}),
+        note: (compare != null ? "ROM/code patch" : "RAM cheat") + " for " + platform + ". " +
+          "Devices: " + (built.codes.length ? built.codes.map((c) => `${c.device} ${c.code}`).join(", ") + ", " : "") + "raw " + built.raw + ". " +
+          "Apply to confirm: cheats({op:'apply', code: \"" + primary + "\" }). Non-destructive — no ROM file is touched.",
+      };
+}
+
+export function registerCheatTools(server, z, sessionKey) {
+  server.tool(
+    "cheats",
+    "Cheat lookup / search / apply / create for the loaded ROM. `op`: " +
+    "'lookup' (THIS game's known cheats from the bundled DB — returns labeled RAM addresses + Game Genie/ROM code " +
+    "sites, so it answers 'which byte holds X?' for free); " +
+    "'search' (fuzzy-find a game by NAME when you don't have the exact No-Intro title — returns game names + cheat " +
+    "counts, then lookup the chosen one); " +
+    "'apply' (enable a cheat on the LOADED game — pass a raw `code` or a `desc` from lookup); " +
+    "'clear' (remove all active cheats); 'make' (CREATE a shareable code from an address+value). " +
+    "TRUST: lookup matches by NAME/fuzzy similarity, NOT a verified CRC — a PROBABLE match. Labels are usually " +
+    "right, but a different region/revision can use different addresses — VERIFY before patching: apply + observe, " +
+    "or check the address in live memory with memory/watch. " +
+    "apply is NON-DESTRUCTIVE (volatile core state; reset / loadState / clear removes it, the ROM file is never " +
+    "touched), so it doubles as the verifier — apply a label, screenshot, confirm. " +
+    "make emits the platform's NATIVE device code (not always 'Game Genie': NES/Genesis=Game Genie; SNES=Pro " +
+    "Action Replay+GG; GB/GBC=Game Genie(ROM)+GameShark(RAM); SMS/GG=Action Replay) plus the raw ADDR:VAL, all " +
+    "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."),
+      // 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."),
+      kind: z.enum(["ram", "code", "all"]).default("all").describe("op=lookup: RAM-variable cheats, ROM/code cheats, or all (default)."),
+      // search
+      query: z.string().optional().describe("op=search: free-text game name — any form; tags/region/punctuation ignored."),
+      limit: z.number().int().min(1).max(50).default(12).describe("op=search: max results (default 12)."),
+      // 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."),
+      enabled: z.boolean().default(true).describe("op=apply: false disables the slot instead of enabling."),
+      // make / search / lookup share `platform`
+      platform: z.enum([...MAKE_CHEAT_PLATFORMS]).optional().describe("op=lookup: override platform detection. op=search/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)."),
+      value: z.number().int().min(0).max(255).optional().describe("op=make: replacement byte (0-255). Provide value OR values."),
+      values: z.array(z.number().int().min(0).max(255)).min(1).max(64).optional().describe("op=make: batch — a code per value at the same address. Returns variants[]."),
+      compare: z.number().int().min(0).max(255).optional().describe("op=make: ROM cheats only — the byte CURRENTLY at `address` (read it first). Selects the device's ROM-patch form."),
+      device: z.enum(["game-genie", "pro-action-replay", "gameshark", "action-replay", "raw"]).optional().describe("op=make: force a specific device's encoding. Default: the platform's native device(s)."),
+    },
+    safeTool(async (args) => {
+      switch (args.op) {
+        case "lookup": return jsonContent(await cheatsLookupCore(args));
+        case "search": return jsonContent(await cheatsSearchCore(args));
+        case "apply":  return jsonContent(await cheatsApplyCore(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}'`);
+      }
+    }),
+  );
+}

package/src/mcp/tools/classify-region.js

@@ -0,0 +1,107 @@
+// classifyRegion — cheap heuristic for "what kind of data is at this offset?"
+//
+// The trap this kills: a long RE session confidently identified a "stat table"
+// at an offset because values 82/79/68 matched the stats it wanted — but those
+// bytes were the ASCII string "ROD" (from "FROM DOWNTOWN"). A weaker agent will
+// 100% ship a broken patch off a coincidence like that. classifyRegion looks at
+// the bytes and says "this looks like ASCII text / code / a pointer table / tile
+// data / unknown" with the metrics behind the call, so the agent stops before
+// trusting a coincidental table.
+
+/** Printable ASCII (incl. space) ratio of a byte buffer. */
+function printableRatio(bytes) {
+  if (!bytes.length) return 0;
+  let p = 0;
+  for (const b of bytes) if (b === 0x20 || b === 0x09 || b === 0x0a || b === 0x0d || (b >= 0x21 && b <= 0x7e)) p++;
+  return p / bytes.length;
+}
+
+/** Longest run of consecutive printable-ASCII bytes (length). */
+function longestPrintableRun(bytes) {
+  let best = 0, cur = 0;
+  for (const b of bytes) {
+    if (b === 0x20 || (b >= 0x21 && b <= 0x7e)) { cur++; if (cur > best) best = cur; }
+    else cur = 0;
+  }
+  return best;
+}
+
+/** Shannon entropy (bits/byte, 0..8) — low = repetitive/structured, high = packed/compressed. */
+function entropy(bytes) {
+  if (!bytes.length) return 0;
+  const counts = new Uint32Array(256);
+  for (const b of bytes) counts[b]++;
+  let h = 0;
+  for (const c of counts) if (c) { const p = c / bytes.length; h -= p * Math.log2(p); }
+  return h;
+}
+
+/** Fraction of zero bytes — high in sparse tables / padding / tile data. */
+function zeroRatio(bytes) {
+  if (!bytes.length) return 0;
+  let z = 0;
+  for (const b of bytes) if (b === 0) z++;
+  return z / bytes.length;
+}
+
+/**
+ * Heuristically classify a byte buffer.
+ * @param {Uint8Array} bytes
+ * @param {object} [opts]
+ * @param {boolean} [opts.bigEndian] platform endianness (for pointer-table guess)
+ * @returns {{ looksLike: string, printableRatio:number, entropy:number, zeroRatio:number, longestAsciiRun:number, asciiPreview:string|null, confidence:string, note:string }}
+ */
+export function classifyBytes(bytes, opts = {}) {
+  const pr = printableRatio(bytes);
+  const ent = entropy(bytes);
+  const zr = zeroRatio(bytes);
+  const run = longestPrintableRun(bytes);
+
+  // ASCII text: mostly printable AND a meaningful run (so a table that happens to
+  // have some printable bytes scattered doesn't read as text — it's the RUN that
+  // distinguishes "ROD" inside real text from coincidental printable values).
+  let looksLike = "unknown";
+  let confidence = "low";
+  let note = "";
+  if (pr >= 0.85 && run >= 4) {
+    looksLike = "ascii-text";
+    confidence = pr >= 0.95 && run >= 6 ? "high" : "medium";
+    note = "Mostly printable ASCII with a real run — likely a text string. A 'data table' overlapping this is probably a coincidence (values matching ASCII codes). Check for terminators / a font map before treating bytes here as a stat/pointer table.";
+  } else if (ent >= 6.5) {
+    looksLike = "high-entropy"; // compressed / encrypted / packed graphics
+    confidence = "medium";
+    note = "High entropy — likely compressed data, packed graphics, or encrypted. Not a plain table; don't read it as flat values.";
+  } else if (zr >= 0.5 && ent <= 3.5) {
+    looksLike = "sparse-or-tiledata"; // lots of zeros, low entropy
+    confidence = "low";
+    note = "Sparse / low-entropy (many zeros) — could be tile/bitmap data, a sparse table, or padding. Inspect as tiles (getTile/inspectPatternTiles) if it's graphics.";
+  } else if (ent <= 4.5 && pr < 0.5) {
+    looksLike = "structured-data"; // tables, code, binary records
+    confidence = "low";
+    note = "Low-entropy non-text bytes — plausibly a table, structured records, or code. If you think it's a table, verify the stride/record size; if code, disassemble.";
+  } else {
+    looksLike = "unknown";
+    note = "No strong signal. Could be a table, mixed data, or code — verify before trusting it as a flat value table.";
+  }
+
+  const asciiPreview = (looksLike === "ascii-text" || pr >= 0.6)
+    ? Array.from(bytes.slice(0, 48), (b) => (b >= 0x20 && b <= 0x7e ? String.fromCharCode(b) : ".")).join("")
+    : null;
+
+  return {
+    looksLike,
+    printableRatio: Math.round(pr * 100) / 100,
+    entropy: Math.round(ent * 100) / 100,
+    zeroRatio: Math.round(zr * 100) / 100,
+    longestAsciiRun: run,
+    asciiPreview,
+    confidence,
+    note,
+  };
+}
+
+/** True if a buffer is "probably ASCII text" — the cheap guard tools use to warn
+ *  that a candidate offset overlaps a string region. */
+export function overlapsAsciiText(bytes) {
+  return printableRatio(bytes) >= 0.85 && longestPrintableRun(bytes) >= 4;
+}

package/src/mcp/tools/diff-cluster.js

@@ -0,0 +1,32 @@
+// clusterChanges — turn a flat list of changed byte offsets into a context-safe
+// summary: adjacent changes merge into ranges, and evenly-spaced ranges report
+// their stride. The trap this kills: a 20-frame gameplay diff churns thousands
+// of bytes and a raw {offset,before,after} dump blows the token budget. The
+// summary says "4 change-islands at stride 0x80 — likely a player-struct array"
+// in a few rows instead, which is also the more USEFUL answer (the stride is the
+// record size of an entity array — exactly what an RE session is hunting for).
+
+/**
+ * Group changed absolute offsets into clusters and detect a uniform stride.
+ * @param {number[]} absOffsets changed offsets (ABSOLUTE, ascending), e.g. baseOffset + i
+ * @param {object} [opts]
+ * @param {number} [opts.gap=4] merge two changes into one cluster if within this many bytes
+ * @returns {{ clusters: {startDec:number,endDec:number,bytes:number}[], stride: number|null }}
+ */
+export function clusterChanges(absOffsets, opts = {}) {
+  const gap = opts.gap ?? 4;
+  const clusters = [];
+  for (const abs of absOffsets) {
+    const last = clusters[clusters.length - 1];
+    if (last && abs - last.endDec <= gap) { last.endDec = abs; last.bytes++; }
+    else clusters.push({ startDec: abs, endDec: abs, bytes: 1 });
+  }
+  // Stride: clusters' start offsets evenly spaced ⇒ struct/entity array.
+  let stride = null;
+  if (clusters.length >= 3) {
+    const deltas = [];
+    for (let i = 1; i < clusters.length; i++) deltas.push(clusters[i].startDec - clusters[i - 1].startDec);
+    if (deltas.every((d) => d === deltas[0]) && deltas[0] > 0) stride = deltas[0];
+  }
+  return { clusters, stride };
+}