romdevtools 0.13.0

package/src/toolchains/common/reassemble.js

@@ -0,0 +1,353 @@
+// Byte-exact disassemble → reassemble using NATIVE tools end to end.
+//
+// `reassembleForPlatform` is the entry point. It disassembles with the native
+// binutils objdump for the CPU and reassembles with the matching native
+// assembler, healing any instruction the assembler rejects to an exact `.byte`:
+//   - 6502/65816 (NES/SNES/Atari/C64/PCE/Lynx) → da65 → ca65/ld65 (reassembleCc65Native)
+//   - m68k (Genesis)                            → objdump → m68k-elf-as/ld/objcopy
+//   - arm (GBA)                                 → objdump → arm-none-eabi-as/ld/objcopy
+//   - z80 (SMS/GG/MSX) + gbz80 (GB/GBC)         → objdump → z80-elf-as + objcopy
+//     (gbz80 objects can't be ld-linked, so as + `.org` + objcopy)
+//
+// objdump and `as` share GNU syntax, so the GNU CPUs need NO instruction
+// translation — objdump's lines feed straight back into `as`. The byte-exact
+// guarantee is the heal loop: assemble, diff vs the original, pin any
+// mismatching/rejected line to a `.byte` of its exact bytes, retry. Always
+// byte-exact; readability = how many lines stayed instructions.
+
+const hex2 = (b) => "$" + (b & 0xFF).toString(16).padStart(2, "0").toUpperCase();
+
+// Label form across disassemblers: `L` + 4..8 hex digits (m68k targets can be
+// 24-bit, e.g. an $E0FF00xx RAM mirror → LE0FF0080).
+const LABEL_RE = /^(L[0-9A-Fa-f]{4,8}):\s*$/;
+const LABEL_REF_RE = /\bL[0-9A-Fa-f]{4,8}\b/g;
+
+/** Parse one disasm line into {label?, code?, bytes?[]}. */
+function parseLine(line) {
+  // Label-only line: `L00023C:`
+  const lm = line.match(LABEL_RE);
+  if (lm) return { label: lm[1] };
+  // Code + trailing `; ADDR BB BB` comment.
+  const cm = line.match(/^\s*(.*?)\s*;\s*([0-9A-Fa-f]{4,8})\s+((?:[0-9A-Fa-f]{2}\s*)+)\s*$/);
+  if (cm) {
+    const bytes = cm[3].trim().split(/\s+/).map((h) => parseInt(h, 16));
+    return { code: cm[1].trim(), addr: parseInt(cm[2], 16), bytes };
+  }
+  // A label on the same line as code: `L00023C:  jmp ...`  (rare)
+  const both = line.match(/^(L[0-9A-Fa-f]{4,8}):\s+(.*?)\s*;\s*([0-9A-Fa-f]{4,8})\s+((?:[0-9A-Fa-f]{2}\s*)+)\s*$/);
+  if (both) {
+    const bytes = both[4].trim().split(/\s+/).map((h) => parseInt(h, 16));
+    return { label: both[1], code: both[2].trim(), addr: parseInt(both[3], 16), bytes };
+  }
+  // Assembler STATE directives that emit no bytes but MUST be preserved for the
+  // reassembly to be correct — chiefly the 65816 width directives `.a8/.a16/
+  // .i8/.i16` (and `.setcpu`), which tell ca65 the accumulator/index size so
+  // `lda #imm` etc. get the right operand width. Dropping them silently
+  // mis-encodes everything after a width switch.
+  const dir = line.match(/^\s*(\.(?:setcpu|a8|a16|i8|i16|smart)\b.*)$/i);
+  if (dir) return { directive: dir[1].trim() };
+  return {}; // comment/blank — skip
+}
+
+/** First differing byte index, or -1 if equal up to min length. */
+function firstDiff(a, b) {
+  const n = Math.min(a.length, b.length);
+  for (let i = 0; i < n; i++) if (a[i] !== b[i]) return i;
+  return a.length === b.length ? -1 : n;
+}
+
+// ── Per-platform orchestrator ───────────────────────────────────────────────
+//
+// Disassemble a chunk of bytes for `platform` at CPU address `startAddress`,
+// then reassemble it BYTE-EXACT in that platform's native assembler. Returns
+// the reassembled source + verification. Picks the native disassembler and
+// assembler per CPU family:
+//   6502/65816 (nes/snes/atari/c64/pce/lynx) → da65 → ca65/ld65
+//   z80 (sms/gg/msx) + sm83 (gb/gbc)          → objdump → z80-elf-as + objcopy
+//   m68k (genesis)                            → objdump → m68k-elf-as/ld/objcopy
+//   arm (gba)                                 → objdump → arm-none-eabi-as/ld/objcopy
+
+const CPU_FAMILY = {
+  nes: "6502", c64: "6502", atari2600: "6502", atari7800: "6502", lynx: "6502",
+  snes: "65816",
+  sms: "z80", gg: "z80", msx: "z80",
+  gb: "sm83", gbc: "sm83",
+  genesis: "m68k", megadrive: "m68k", md: "m68k",
+  gba: "arm",
+  // PC Engine's HuC6280 is a 65C02 superset — the 6502-family da65/ca65 path
+  // reassembles it (da65 also has an explicit --cpu huc6280 mode for decode).
+  pce: "6502",
+};
+
+/**
+ * @param {Object} a
+ * @param {string} a.platform
+ * @param {Uint8Array} a.bytes        the chunk to disassemble (already mapped to CPU space)
+ * @param {number} a.startAddress     CPU address of byte 0
+ * @returns {Promise<{ family:string, source:string, bytes:Uint8Array|null, ok:boolean,
+ *   total:number, dcLines:number, readablePercent:number, note?:string }>}
+ */
+export async function reassembleForPlatform(a) {
+  const { platform, bytes, startAddress } = a;
+  const family = CPU_FAMILY[platform];
+  if (!family) throw new Error(`reassembleForPlatform: no reassembly path for platform '${platform}'`);
+
+  // ── disassemble (NATIVE binutils objdump — no hand-rolled decoders) ──
+  // 6502/65816 use da65 (cc65's real disassembler); everything else uses the
+  // matching binutils objdump. normalizeObjdump emits romdev's house format
+  // (`<insn> ; ADDR bytes`) the heal loop's parseLine consumes.
+  let disasm;
+  if (family === "6502" || family === "65816") {
+    const { runDa65 } = await import("../cc65/da65.js");
+    const r = await runDa65({ bytes, startAddress, cpu: family === "65816" ? "65816" : "6502", options: ["--comments", "4"] });
+    disasm = r.asm;
+    // da65 output is already valid cc65 — heal it in place (cc65 reassembles its
+    // own syntax natively).
+    return reassembleCc65Native(disasm, startAddress, bytes, family);
+  }
+  // ALL non-6502 CPUs: disassemble with native objdump, reassemble with the
+  // matching native binutils `as`/`ld`/`objcopy`. objdump output IS GNU-as
+  // syntax, so there's no translation — keep its lines verbatim and pin only the
+  // instructions `as` rejects (absolute branch/PC-relative forms) to `.byte`.
+  // NO hand-rolled decoders anywhere.
+  const { runObjdump } = await import("../objdump.js");
+  if (family === "m68k") {
+    disasm = (await runObjdump({ bytes, arch: "m68k", startAddress })).asm;
+    const m = await import("../m68k-elf-gcc/gcc.js");
+    return reassembleGnuNative(disasm, startAddress, bytes,
+      { runAs: m.runM68kAs, runLd: m.runM68kLd, runObjcopy: m.runM68kObjcopy, fmtLines: `OUTPUT_FORMAT("elf32-m68k")\nOUTPUT_ARCH(m68k)\n` }, family);
+  }
+  if (family === "arm") {
+    disasm = (await runObjdump({ bytes, arch: "arm", startAddress })).asm;
+    const m = await import("../arm-none-eabi-gcc/gcc.js");
+    return reassembleGnuNative(disasm, startAddress, bytes,
+      { runAs: m.runArmAs, runLd: m.runArmLd, runObjcopy: m.runArmObjcopy }, family);
+  }
+  if (family === "z80" || family === "sm83") {
+    // z80 binutils `as` handles BOTH the Z80 (-march=z80) and the Game Boy CPU
+    // (-march=gbz80) — the same objdump that disassembled them.
+    const arch = family === "sm83" ? "gbz80" : "z80";
+    disasm = (await runObjdump({ bytes, arch, startAddress })).asm;
+    const z = await import("../z80/binutils.js");
+    return reassembleGnuNative(disasm, startAddress, bytes,
+      { runAs: z.runZ80As, runObjcopy: z.runZ80Objcopy, march: arch, noLink: true }, family);
+  }
+  throw new Error(`reassembleForPlatform: no reassembly path for family '${family}'`);
+}
+
+/**
+ * Reassemble a GNU-toolchain CPU (m68k / arm) from native objdump output using
+ * the matching binutils `as`/`ld`/`objcopy`. objdump and as share GNU syntax, so
+ * we keep objdump's instruction lines almost verbatim (only `$hex`→`0x`, our
+ * house normalization) and place a label at each in-range branch target. Heal:
+ * assemble; for any instruction `as` REJECTS (PC-relative/branch forms objdump
+ * prints absolutely), pin that line to a `.byte` of its exact bytes and retry.
+ * Floor = clean all-`.byte` (proven byte-exact). No hand-rolled de/encoding.
+ * @returns same shape as reassembleForPlatform
+ */
+async function reassembleGnuNative(disasm, startAddress, original, tools, family) {
+  // tools: { runAs, runLd, runObjcopy, fmtLines, asArgs? } — the matching
+  // binutils chain for this CPU. asArgs (e.g. for z80's -march=gbz80) ride
+  // through to the assembler call (the z80 wrapper bakes march in itself).
+  const { runAs, runLd, runObjcopy, fmtLines = "" } = tools;
+  const ld = `${fmtLines}ENTRY(_start)\nSECTIONS {\n  .text 0x${startAddress.toString(16)} : {\n    *(.text*) *(.rodata*) *(.data*)\n  }\n  /DISCARD/ : { *(.ARM.attributes) *(.comment) *(.note*) }\n}\n`;
+
+  // Parse objdump's normalized lines into {label?, code?, addr, bytes}.
+  const lines = disasm.split(/\r?\n/).map(parseLine);
+  // Which in-range addresses are branch targets (need a label def)?
+  const addrOf = new Map();
+  for (const p of lines) if (p.addr != null && p.bytes) addrOf.set(p.addr, p);
+  const codeIdx = [];
+  lines.forEach((p, i) => { if (p.code != null && p.bytes) codeIdx.push(i); });
+  const forced = new Set();
+
+  const toGas = (code) => code.replace(/\$([0-9A-Fa-f]+)\b/g, (_, h) => "0x" + h);
+
+  const build = () => {
+    const out = [".section .text", ".global _start"];
+    // No-link (z80/gbz80) path: place the section with `.org` so labels resolve
+    // to real addresses before objcopy (there's no linker to set the origin).
+    if (tools.noLink) out.push(`.org 0x${startAddress.toString(16)}`);
+    out.push("_start:");
+    for (let i = 0; i < lines.length; i++) {
+      const p = lines[i];
+      if (p.label) { out.push(p.label + ":"); continue; }
+      if (p.code != null && p.bytes) {
+        if (forced.has(i)) out.push("\t.byte " + p.bytes.map((b) => "0x" + b.toString(16).padStart(2, "0")).join(","));
+        else out.push("\t" + toGas(p.code));
+      }
+    }
+    return out.join("\n") + "\n";
+  };
+  const assemble = async (src) => {
+    const a = await runAs({ source: src, march: tools.march }).catch(() => ({ object: null, log: "" }));
+    if (!a || !a.object) return { ok: false, log: a?.log || "" };
+    let elf;
+    if (tools.noLink) {
+      // z80/gbz80: `as` resolves all in-file labels (one source file, no cross-
+      // refs), and ld rejects gbz80 objects ("instruction sets incompatible").
+      // Skip ld — objcopy the assembled object straight to binary. Correct
+      // section addresses come from the `.org startAddress` the source carries.
+      elf = a.object;
+    } else {
+      const l = await runLd({ objects: { "main.o": a.object }, linkScript: ld }).catch(() => null);
+      if (!l || !l.elf) return { ok: false, log: l?.log || "" };
+      elf = l.elf;
+    }
+    const o = await runObjcopy({ elf }).catch(() => null);
+    if (!o || !o.binary) return { ok: false, log: "" };
+    let bin = new Uint8Array(o.binary);
+    if (tools.noLink) {
+      // The `.org startAddress` makes objcopy emit `startAddress` leading zero
+      // bytes (the section's offset). Slice to the real region.
+      bin = bin.slice(startAddress, startAddress + original.length);
+    } else if (bin.length > original.length) {
+      bin = bin.slice(0, original.length);
+    }
+    return { ok: true, bytes: bin };
+  };
+
+  const totalCode = codeIdx.length;
+  for (let pass = 0; pass < 80; pass++) {
+    const src = build();
+    const r = await assemble(src);
+    if (r.ok) {
+      if (r.bytes.length === original.length && firstDiff(original, r.bytes) < 0) {
+        return { family, source: src, bytes: r.bytes, ok: true, total: totalCode, dcLines: forced.size,
+          readablePercent: totalCode ? Math.round(100 * (1 - forced.size / totalCode)) : 100 };
+      }
+      // Assembled but bytes differ (and/or length changed). Compare each line's
+      // bytes at its ABSOLUTE offset (p.addr - startAddress), NOT an accumulated
+      // cursor — the linker anchors every line at its real address, so a single
+      // line that `as` re-encoded to a different length doesn't desync the rest
+      // (the cursor-accumulation approach drifted on the first length-changer and
+      // pinned everything after it — the bug that floored literal-heavy ARM).
+      // Pin EVERY mismatching instruction this pass so it converges in a few.
+      let pinnedHere = false;
+      for (let li = 0; li < lines.length; li++) {
+        const p = lines[li];
+        if (!p.bytes || p.code == null || forced.has(li)) continue;
+        const off = p.addr - startAddress;
+        let match = off >= 0 && off + p.bytes.length <= r.bytes.length;
+        if (match) for (let k = 0; k < p.bytes.length; k++) if (r.bytes[off + k] !== p.bytes[k]) { match = false; break; }
+        if (!match) { forced.add(li); pinnedHere = true; }
+      }
+      if (!pinnedHere) {
+        // Bytes all matched at their addresses but totals still differ (length
+        // mismatch with no per-line diff — e.g. a re-encode that shifted later
+        // lines). Pin the next unpinned code line to make progress.
+        const n = codeIdx.find((i) => !forced.has(i));
+        if (n == null) break;
+        forced.add(n);
+      }
+      continue;
+    }
+    // `as` rejected something → pin every code line whose translated text the
+    // error log names. The wrapped source has a 3-line preamble.
+    const srcLines = src.split("\n");
+    let pinned = false;
+    for (const m of (r.log || "").matchAll(/:(\d+):\s*(?:Error|Warning):/g)) {
+      const ln = parseInt(m[1], 10) - 1;
+      const text = (srcLines[ln] || "").trim();
+      for (const i of codeIdx) { if (forced.has(i)) continue; if (("\t" + toGas(lines[i].code)).trim() === text) { forced.add(i); pinned = true; break; } }
+    }
+    if (!pinned) { const n = codeIdx.find((i) => !forced.has(i)); if (n == null) break; forced.add(n); }
+  }
+  // Floor: clean all-`.byte` (proven byte-exact, no labels to perturb layout).
+  const rows = [".section .text", ".global _start", "_start:"];
+  for (let i = 0; i < original.length; i += 16) rows.push("\t.byte " + Array.from(original.slice(i, i + 16)).map((b) => "0x" + b.toString(16).padStart(2, "0")).join(","));
+  const r = await assemble(rows.join("\n") + "\n");
+  const ok = r.ok && r.bytes.length === original.length && firstDiff(original, r.bytes) < 0;
+  return { family, source: rows.join("\n") + "\n", bytes: ok ? r.bytes : null, ok, total: totalCode, dcLines: totalCode,
+    readablePercent: 0, note: ok ? "byte-exact (data-only floor — some instructions didn't round-trip)" : "could not reach byte-exact" };
+}
+
+/**
+ * Reassemble cc65 (6502/65816) families by using da65's output AS-IS — it's
+ * already valid cc65 with its own equate/label structure. We inject `.org`
+ * after `.setcpu` (the proven byte-exact recipe) and heal by replacing any
+ * da65 CODE line that doesn't reassemble to its own bytes with a `.byte` of
+ * those bytes (recovered from the line's `; ADDR BB` comment). Preserves
+ * da65's equates/labels/`.a8`/`.i8` exactly.
+ * @returns same shape as reassembleForPlatform
+ */
+async function reassembleCc65Native(disasm, startAddress, original, family) {
+  const { runCa65, runLd65 } = await import("../cc65/cc65.js");
+  const cpuTag = family === "65816" ? "65816" : "6502";
+  const cfg = `MEMORY{M:start $${startAddress.toString(16)},size $${original.length.toString(16)},type ro,file %O,fill yes,fillval $FF;}\nSEGMENTS{CODE:load M,type ro;}\n`;
+
+  // Split da65 output into lines, tagging code lines with their {addr,bytes}.
+  const lines = disasm.split(/\r?\n/);
+  const meta = lines.map((line) => {
+    const m = line.match(/^\s*(?!L[0-9A-Fa-f]+:|;|\.)(\S.*?)\s*;\s*([0-9A-Fa-f]{4,8})\s+((?:[0-9A-Fa-f]{2}\s*)+)\s*$/);
+    if (m) return { code: true, addr: parseInt(m[2], 16), bytes: m[3].trim().split(/\s+/).map((h) => parseInt(h, 16)) };
+    return { code: false };
+  });
+  const forced = new Set(); // line indices replaced with .byte
+
+  const build = () => {
+    const out = lines.map((line, i) => {
+      if (forced.has(i)) return "\t.byte " + meta[i].bytes.map(hex2).join(",");
+      return line;
+    });
+    // inject `.org` right after `.setcpu`
+    const src = out.join("\n").replace(/(\.setcpu\s+"[^"]+")/, `$1\n\t.org $${startAddress.toString(16).toUpperCase()}`);
+    return src;
+  };
+  const assemble = async (src) => {
+    const ca = await runCa65({ source: src, target: "none" }).catch(() => null);
+    if (!ca || !ca.object) return null;
+    const ld = await runLd65({ objects: { "o.o": ca.object }, target: "none", linkerConfig: cfg }).catch(() => null);
+    return ld && ld.binary ? new Uint8Array(ld.binary) : null;
+  };
+
+  let source = build();
+  const codeLineCount = meta.filter((m) => m.code).length;
+  for (let pass = 0; pass < 80; pass++) {
+    source = build();
+    const out = await assemble(source);
+    if (out && out.length === original.length && firstDiff(original, out) < 0) {
+      return { family, source, bytes: out, ok: true, total: codeLineCount, dcLines: forced.size,
+        readablePercent: codeLineCount ? Math.round(100 * (1 - forced.size / codeLineCount)) : 100 };
+    }
+    if (!out) {
+      // ca65/ld failed — pin the first not-yet-pinned code line and retry.
+      const next = meta.findIndex((m, i) => m.code && !forced.has(i));
+      if (next < 0) break;
+      forced.add(next);
+      continue;
+    }
+    // byte mismatch: pin the code line owning the first diff.
+    const d = firstDiff(original, out);
+    const off = (d < 0 ? Math.min(out.length, original.length) : d) + startAddress;
+    let owner = -1;
+    for (let i = 0; i < meta.length; i++) {
+      if (meta[i].code && meta[i].addr <= off && off < meta[i].addr + meta[i].bytes.length) { owner = i; break; }
+      if (meta[i].code && meta[i].addr <= off) owner = i;
+    }
+    if (owner < 0 || forced.has(owner)) {
+      const next = meta.findIndex((m, i) => m.code && !forced.has(i));
+      if (next < 0) break;
+      forced.add(next);
+    } else {
+      forced.add(owner);
+    }
+  }
+  // Guaranteed floor: a CLEAN all-`.byte` dump of the original bytes (no da65
+  // equates/labels/width-directives to desync). This is byte-exact on every
+  // cc65 target we tested (incl. 65816, where mixing pinned `.byte` with live
+  // instructions can break `.a8`/`.i8` width state — so when the incremental
+  // heal can't converge, we emit pure data). Lower readability, but correct.
+  {
+    const rows = [`\t.setcpu "${cpuTag}"`, `\t.org $${startAddress.toString(16).toUpperCase()}`];
+    for (let i = 0; i < original.length; i += 16) {
+      rows.push("\t.byte " + Array.from(original.slice(i, i + 16)).map(hex2).join(","));
+    }
+    const flat = rows.join("\n") + "\n";
+    const out = await assemble(flat);
+    const ok = !!out && out.length === original.length && firstDiff(original, out) < 0;
+    return { family, source: flat, bytes: out ?? null, ok, total: codeLineCount, dcLines: codeLineCount,
+      readablePercent: 0,
+      note: ok ? "incremental heal did not converge; emitted byte-exact data-only (low readability)" : "could not reach byte-exact even as data" };
+  }
+}

package/src/toolchains/common/sdk-cache.js

@@ -0,0 +1,116 @@
+// sdk-cache.js — "prebuilt seed + opt-in rebuild" for SDK libraries.
+//
+// Compiling a whole SDK (libtonc, SGDK, pvsneslib) from source on every build
+// is slow on the FIRST build of a process (GBA ~42s, Genesis ~18s). But linking
+// a prebuilt black-box .a is the trust problem we removed. The compromise:
+//
+//   - Ship a prebuilt SEED .a derived from the vendored source (fast default).
+//   - Let the caller pass `rebuildSdk:true` to compile the SDK from source
+//     instead (slow once, then disk-cached by source hash).
+//   - The seed is reproducible from the shipped source — nobody is forced to
+//     trust it; they can rebuild and byte-compare.
+//   - If the vendored source no longer matches the seed (the agent edited it)
+//     AND they didn't ask for a rebuild, we still use the fast seed but return
+//     a loud `sdkEditIgnored` warning naming the changed file — so an edit is
+//     never SILENTLY dropped (the trap we eliminated stays eliminated).
+//
+// This module is platform-agnostic: each toolchain passes in how to hash its
+// source, where its seed lives, and how to compile from source.
+
+import { readFile, writeFile, mkdir, stat } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import path from "node:path";
+import os from "node:os";
+
+/** Stable hash of a {name: text|bytes} source map (order-independent). */
+export function hashSources(srcMap) {
+  const h = createHash("sha256");
+  for (const name of Object.keys(srcMap).sort()) {
+    const v = srcMap[name];
+    h.update(name);
+    h.update("\0");
+    h.update(typeof v === "string" ? v : Buffer.from(v));
+    h.update("\0");
+  }
+  return h.digest("hex");
+}
+
+// On-disk cache for rebuilt-from-source archives, so a `rebuildSdk` result is
+// reused across processes/sessions (not just within one). Keyed by source hash.
+function cacheDir() {
+  return path.join(os.tmpdir(), "romdev-sdk-cache");
+}
+async function readDiskCache(key) {
+  try { return new Uint8Array(await readFile(path.join(cacheDir(), key + ".a"))); }
+  catch { return null; }
+}
+async function writeDiskCache(key, bytes) {
+  try {
+    await mkdir(cacheDir(), { recursive: true });
+    await writeFile(path.join(cacheDir(), key + ".a"), bytes);
+  } catch { /* cache is best-effort */ }
+}
+
+/**
+ * Resolve an SDK archive for a build, honoring the seed/rebuild policy.
+ *
+ * @param {Object} a
+ * @param {string} a.name          SDK name (for messages), e.g. "libtonc"
+ * @param {Record<string,string>} a.sources  the vendored SDK source map (for hashing)
+ * @param {string} a.seedPath       absolute path to the prebuilt seed .a
+ * @param {string} a.seedHashPath   absolute path to the seed's source-hash file
+ * @param {boolean} a.rebuild       caller asked to compile from source
+ * @param {() => Promise<{ok:boolean, archive?:Uint8Array, stage?:string, log?:string}>} a.compileFromSource
+ * @returns {Promise<{ok:boolean, archive?:Uint8Array, fromSource:boolean,
+ *   sdkEditIgnored?:{sdk:string, message:string}, stage?:string, log?:string}>}
+ */
+export async function resolveSdkArchive(a) {
+  const srcHash = hashSources(a.sources);
+
+  // Explicit rebuild → compile from source (disk-cached by hash).
+  if (a.rebuild) {
+    // When writeSeed is set (the seed generator), always recompile + persist
+    // the seed; don't short-circuit on the disk cache.
+    if (!a.writeSeed) {
+      const cached = await readDiskCache(srcHash);
+      if (cached) return { ok: true, archive: cached, fromSource: true };
+    }
+    const r = await a.compileFromSource();
+    if (!r.ok) return { ok: false, fromSource: true, stage: r.stage, log: r.log };
+    await writeDiskCache(srcHash, r.archive);
+    if (a.writeSeed && a.seedPath) {
+      await writeFile(a.seedPath, r.archive);
+      await writeFile(a.seedHashPath, srcHash + "\n");
+    }
+    return { ok: true, archive: r.archive, fromSource: true };
+  }
+
+  // Default → use the prebuilt seed.
+  let seed = null;
+  try { seed = new Uint8Array(await readFile(a.seedPath)); } catch { /* no seed */ }
+
+  // Compare the seed's source-hash to the current vendored source.
+  let seedHash = null;
+  try { seedHash = (await readFile(a.seedHashPath, "utf-8")).trim(); } catch { /* no hash */ }
+
+  if (seed) {
+    const edited = seedHash && seedHash !== srcHash;
+    const result = { ok: true, archive: seed, fromSource: false };
+    if (edited) {
+      result.sdkEditIgnored = {
+        sdk: a.name,
+        message:
+          `Your changes to the bundled ${a.name} source were NOT compiled into ` +
+          `this build — it linked the prebuilt ${a.name} cache. To build your ` +
+          `edits, pass rebuildSdk:true.`,
+      };
+    }
+    return result;
+  }
+
+  // No seed shipped (dev / first build before seeding) → compile from source.
+  const r = await a.compileFromSource();
+  if (!r.ok) return { ok: false, fromSource: true, stage: r.stage, log: r.log };
+  await writeDiskCache(srcHash, r.archive);
+  return { ok: true, archive: r.archive, fromSource: true };
+}

package/src/toolchains/common/symbols.js

@@ -0,0 +1,139 @@
+// Generic symbol-file parsers and lookups.
+//
+// Different toolchains emit different formats:
+//   - cc65 → .dbg (line-oriented, see cc65/dbgparse.js — handled separately)
+//   - asar/bass/wla-dx → .sym (WLA format: "<bank>:<addr> <name>" sections)
+//   - cc65 → .lbl (older list label format)
+//
+// This file handles non-dbg formats. Each parser returns the same shape
+// so callers can be format-agnostic.
+
+/**
+ * @typedef {Object} Symbol
+ * @property {string} name
+ * @property {number} address      24-bit linear address (bank << 16 | offset)
+ * @property {number} [bank]       optional bank byte (asar/SNES)
+ * @property {string} [kind]       "label" | "constant" — guessed per format
+ */
+
+/**
+ * Parse a WLA-DX .sym file. asar emits this with --symbols=wla.
+ * Format:
+ *   [labels]
+ *   00:8000 reset
+ *   01:8000 chr_data
+ *
+ *   [definitions]
+ *   ff:0001 some_constant
+ *
+ * Sections are introduced by [section_name] in brackets. Each line is
+ * "<bank>:<offset> <name>". Offsets are hex.
+ * @param {string} text
+ * @returns {Symbol[]}
+ */
+export function parseWlaSym(text) {
+  const out = [];
+  let section = null;
+  // Asar's .sym file has several sections; only [labels] and [definitions]
+  // map names to addresses. [source files], [addr-to-line mapping], etc.
+  // use bank:offset prefixes too but aren't symbol declarations.
+  const NAME_SECTIONS = new Set(["labels", "definitions"]);
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith(";")) continue;
+    const sectionMatch = line.match(/^\[([^\]]+)\]/);
+    if (sectionMatch) {
+      section = sectionMatch[1].toLowerCase();
+      continue;
+    }
+    if (!NAME_SECTIONS.has(section)) continue;
+    const m = line.match(/^([0-9A-Fa-f]+):([0-9A-Fa-f]+)\s+(\S+)/);
+    if (!m) continue;
+    const bank = parseInt(m[1], 16);
+    const offset = parseInt(m[2], 16);
+    if (!Number.isFinite(bank) || !Number.isFinite(offset)) continue;
+    out.push({
+      name: m[3],
+      address: (bank << 16) | offset,
+      bank,
+      kind: section === "definitions" ? "constant" : "label",
+    });
+  }
+  return out;
+}
+
+/**
+ * Parse a cc65-style .lbl file. Simpler format used by older cc65 and
+ * various 6502 tools:
+ *   al 008000 reset
+ *   al 00800a mainloop
+ *
+ * The `al` prefix is "absolute label" (cc65 ld65 emits this with --dbgfile).
+ * @param {string} text
+ * @returns {Symbol[]}
+ */
+export function parseCc65Lbl(text) {
+  const out = [];
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith(";")) continue;
+    const m = line.match(/^al\s+([0-9A-Fa-f]+)\s+(\S+)/);
+    if (!m) continue;
+    const addr = parseInt(m[1], 16);
+    if (!Number.isFinite(addr)) continue;
+    // cc65 leading-dot names like `._main` → strip the dot for ergonomics.
+    const name = m[2].replace(/^\./, "");
+    out.push({ name, address: addr, kind: "label" });
+  }
+  return out;
+}
+
+/**
+ * Auto-detect symbol-file format from filename extension or content
+ * sniffing, then parse and return the unified Symbol[].
+ *
+ * @param {Object} args
+ * @param {string} args.text
+ * @param {string} [args.format] explicit format override: "wla" | "cc65-lbl"
+ * @param {string} [args.path]   filename, used for ext-based detection
+ */
+export function parseSymbols(args) {
+  const { text, format, path } = args;
+  let chosen = format;
+  if (!chosen && path) {
+    const lower = path.toLowerCase();
+    if (lower.endsWith(".sym")) chosen = "wla";
+    else if (lower.endsWith(".lbl")) chosen = "cc65-lbl";
+  }
+  if (!chosen) {
+    // Content sniff. WLA always has a [labels] / [definitions] section
+    // header somewhere near the top.
+    if (/^\s*\[(labels|definitions)\]/im.test(text)) chosen = "wla";
+    else if (/^al\s+[0-9A-Fa-f]+\s/m.test(text)) chosen = "cc65-lbl";
+    else throw new Error("could not detect symbol-file format; pass format=\"wla\" or \"cc65-lbl\"");
+  }
+  switch (chosen) {
+    case "wla":      return parseWlaSym(text);
+    case "cc65-lbl": return parseCc65Lbl(text);
+    default: throw new Error(`unknown symbol format '${chosen}'`);
+  }
+}
+
+/**
+ * Build a fast lookup map for "what's at this address?" — used to
+ * annotate disassembled instructions with labels.
+ * @param {Symbol[]} symbols
+ */
+export function buildSymbolMap(symbols) {
+  const byAddr = new Map();
+  for (const s of symbols) {
+    if (!byAddr.has(s.address)) byAddr.set(s.address, []);
+    byAddr.get(s.address).push(s);
+  }
+  return {
+    /** Look up the symbol(s) exactly at an address. */
+    at: (addr) => byAddr.get(addr) ?? [],
+    /** All symbols, sorted by address (handy for "what's near X"). */
+    list: () => [...symbols].sort((a, b) => a.address - b.address),
+  };
+}