js-confuser-vm 0.0.9 → 0.1.1

package/dist/transforms/bytecode/dispatcher.js

@@ -0,0 +1,266 @@
+// Routes simple unconditional and conditional jumps through a per-function
+// central dispatcher block so that static analysis cannot read jump targets
+// directly from the bytecode operands.
+//
+// ── How it works ─────────────────────────────────────────────────────────────
+//
+// Each function that contains at least one routable jump gets:
+//
+//   rDisp    — a stable register shared across the whole function.
+//              At every jump site, the per-site encoded target PC is written
+//              here before jumping to the dispatcher block.
+//   rKey     — a stable register written at every jump site with that site's
+//              unique XOR key.  The dispatcher passes it to the decode closure.
+//   rClosure — holds the decode closure, created ONCE at function entry
+//              (hoisted).  All dispatch calls reuse the same closure object.
+//
+// Dispatcher block (appended after the function body, never reached by fall-through):
+//
+//   <dispatcher_N>:
+//     CALL     rDisp, rClosure, 2, rDisp, rKey  // rDisp = decode(rDisp, rKey)
+//     JUMP_REG rDisp                            // indirect jump to recovered PC
+//
+// The decode function is compiled ONCE PER FUNCTION from a Template that
+// embeds a per-function constant (fnSalt).  Every function gets its own
+// distinct decode closure body, so identifying one does not help with others.
+//
+//   function decode(x, k) { return ((x ^ k) + FN_SALT) & 0xFFFF; }
+//
+// Jump site transformations (each site has its own random siteKey):
+//
+//   Original:  JUMP target_label
+//   Becomes:   LOAD_INT rDisp, (target_label_pc - fnSalt) ^ siteKey
+//              LOAD_INT rKey,  siteKey
+//              JUMP     <dispatcher_N>
+//
+//   Original:  JUMP_IF_FALSE cond, target_label
+//   Becomes:   JUMP_IF_TRUE  cond, <skip_N>
+//              LOAD_INT rDisp, (target_label_pc - fnSalt) ^ siteKey
+//              LOAD_INT rKey,  siteKey
+//              JUMP     <dispatcher_N>
+//              <skip_N>:
+//
+//   Original:  JUMP_IF_TRUE cond, target_label
+//   Becomes:   JUMP_IF_FALSE cond, <skip_N>
+//              LOAD_INT rDisp, (target_label_pc - fnSalt) ^ siteKey
+//              LOAD_INT rKey,  siteKey
+//              JUMP     <dispatcher_N>
+//              <skip_N>:
+//
+// ── Encoding scheme ──────────────────────────────────────────────────────────
+// Two-key mixed encoding: XOR (per-site) + SUB/ADD (per-function).
+//
+//   encode(pc, siteKey, fnSalt) = (pc - fnSalt) ^ siteKey
+//   decode(x,  k,       fnSalt) = (x  ^ k)      + fnSalt
+//
+// The siteKey is a random nonzero u16 unique per jump site — stored as a plain
+// integer operand in the bytecode.
+// The fnSalt is a random nonzero u16 unique per function — it is never stored
+// as an operand anywhere; it is compiled as a literal constant inside the
+// function's own decode Template body.
+//
+// Attack resistance:
+//   • Brute-forcing a single jump requires enumerating siteKey × fnSalt
+//     (~4 billion combinations) rather than just siteKey (65 535).
+//   • Assuming pure XOR fails: un-XOR-ing with siteKey yields (pc - fnSalt),
+//     not pc.  Valid-PC heuristics produce wrong answers.
+//   • Each function emits its own decode closure bytecode with a different
+//     fnSalt literal baked in.  There is no shared signature to fingerprint.
+//   • The encode and decode operations differ structurally (SUB vs ADD),
+//     removing the self-inverse property that makes XOR-only schemes obvious.
+//
+// To change the scheme:
+//   1. Change the Template source in processFunctionBlock() to match new decode.
+//   2. Change applyEncoding() to return the matching encode transform.
+//   Only these two places need updating; everything else is scheme-agnostic.
+//
+// ── Pipeline position ─────────────────────────────────────────────────────────
+// Runs BEFORE resolveRegisters (so injected RegisterOperands are picked up by
+// liveness analysis) and BEFORE resolveLabels (so label operands with transforms
+// are resolved as part of the normal label-resolution pass).
+
+import * as b from "../../types.js";
+import { getRandomInt } from "../../utils/random-utils.js";
+import { U16_MAX } from "../../utils/op-utils.js";
+import { Template } from "../../template.js";
+import { ref, buildMaxIdMap, allocReg, extractLabel, forEachFunction } from "../../utils/pass-utils.js";
+// VERY IMPORTANT: All object operands should be unique objects for the entire compilation process.
+// This ensures that other passes that may reference/modify operands (e.g. specializedOpcodes) don't accidentally break behavior by mutating cloned objects.
+
+// VERY IMPORTANT: All "encoded" label operands include a unique "_id" property that survives JSON.stringify.
+// This allows Specialized Opcodes and other passes to correct distinguish them as the "transform" function WILL NOT be preserved
+let _encodedLabelId = 0;
+function encodedLabelOperand(label, siteKey, fnSalt) {
+  return {
+    type: "label",
+    label,
+    _id: _encodedLabelId++,
+    // unique per site — survives JSON.stringify
+    transform: pc => applyEncoding(pc, siteKey, fnSalt)
+  };
+}
+
+// ── Encoding scheme (XOR + SUB/ADD, u16 modular) ────────────────────────────
+// applyEncoding(pc, siteKey, fnSalt): the value stored in rDisp at the jump site.
+// Must be the inverse of the decode function compiled by the Template.
+//   encode: ((pc - fnSalt) & 0xFFFF) ^ siteKey   → always a valid u16
+//   decode: ((x ^ siteKey) + fnSalt) & 0xFFFF    ← compiled into the per-function Template
+// The & 0xFFFF mask keeps both sides in [0, 65535], preventing negative LOAD_INT operands.
+function applyEncoding(pc, siteKey, fnSalt) {
+  return pc - fnSalt & U16_MAX ^ siteKey;
+}
+
+// buildDispatcherBlock: emits the dispatcher label + call + indirect jump.
+// rClosure is already live (created at function entry); this block simply
+// calls the decode closure and jumps to the result.
+function buildDispatcherBlock(compiler, rDisp, rKey, rClosure, dispatcherLabel) {
+  const OP = compiler.OP;
+  return [[null, {
+    type: "defineLabel",
+    label: dispatcherLabel
+  }],
+  // decode(rDisp, rKey) → rDisp.  Args are read before dst is written.
+  [OP.CALL, ref(rDisp),
+  // dst — receives decoded PC
+  ref(rClosure),
+  // the hoisted decode closure
+  2,
+  // argc
+  ref(rDisp),
+  // arg[0] = encoded value
+  ref(rKey) // arg[1] = per-site key
+  ], [OP.JUMP_REG, ref(rDisp)]];
+}
+
+// ── Per-function transformation ───────────────────────────────────────────────
+// Returns the transformed instruction stream and the template bytecode block
+// for the per-function decode closure (to be appended at the end of the output).
+function processFunctionBlock(instrs, fnId, compiler, maxId, labelCounter) {
+  const OP = compiler.OP;
+
+  // Only transform functions that actually contain simple jumps.
+  const hasRoutableJump = instrs.some(instr => {
+    const op = instr[0];
+    return op === OP.JUMP || op === OP.JUMP_IF_FALSE || op === OP.JUMP_IF_TRUE;
+  });
+  if (!hasRoutableJump) return {
+    instrs,
+    tail: []
+  };
+
+  // Per-function salt baked into this function's decode Template.
+  // Never stored as an operand — lives only inside the decode closure body.
+  const fnSalt = getRandomInt(1, U16_MAX);
+
+  // Compile a unique decode closure for this function.
+  const tmpl = new Template(`function decode(x, k) { return ((x ^ k) + ${fnSalt}) & ${U16_MAX}; }`).compile({}, compiler);
+  const decodeDesc = tmpl.functions[0];
+  const dispatcherLabel = labelCounter();
+  const rDisp = allocReg(fnId, maxId); // carries encoded PC to dispatcher
+  const rKey = allocReg(fnId, maxId); // carries per-site key to dispatcher
+  const rClosure = allocReg(fnId, maxId); // holds the hoisted decode closure
+
+  const out = [];
+
+  // ── Hoist: create the decode closure once at function entry ───────────────
+  out.push([OP.MAKE_CLOSURE, ref(rClosure), {
+    type: "label",
+    label: decodeDesc.entryLabel
+  }, decodeDesc.paramCount,
+  // 2 (x, k)
+  b.fnRegCountOperand(decodeDesc._fnIdx),
+  // resolved by resolveRegisters()
+  0,
+  // no upvalues
+  0 // hasRest = false
+  ]);
+
+  // ── Transform each instruction ────────────────────────────────────────────
+  for (const instr of instrs) {
+    const op = instr[0];
+    if (op === OP.JUMP) {
+      // [JUMP, label] → [LOAD_INT rDisp, encoded] + [LOAD_INT rKey, siteKey] + [JUMP dispatcher]
+      const targetLabel = extractLabel(instr[1]);
+      if (targetLabel === null) {
+        out.push(instr);
+        continue;
+      }
+      const siteKey = getRandomInt(1, U16_MAX);
+      out.push([OP.LOAD_INT, ref(rDisp), encodedLabelOperand(targetLabel, siteKey, fnSalt)]);
+      out.push([OP.LOAD_INT, ref(rKey), siteKey]);
+      out.push([OP.JUMP, {
+        type: "label",
+        label: dispatcherLabel
+      }]);
+    } else if (op === OP.JUMP_IF_FALSE) {
+      // Invert to JUMP_IF_TRUE so the false path (jump taken) falls into dispatch.
+      const cond = instr[1];
+      const targetLabel = extractLabel(instr[2]);
+      if (targetLabel === null) {
+        out.push(instr);
+        continue;
+      }
+      const siteKey = getRandomInt(1, U16_MAX);
+      const skipLabel = compiler._makeLabel(targetLabel + "_skip");
+      out.push([OP.JUMP_IF_TRUE, cond, {
+        type: "label",
+        label: skipLabel
+      }]);
+      out.push([OP.LOAD_INT, ref(rDisp), encodedLabelOperand(targetLabel, siteKey, fnSalt)]);
+      out.push([OP.LOAD_INT, ref(rKey), siteKey]);
+      out.push([OP.JUMP, {
+        type: "label",
+        label: dispatcherLabel
+      }]);
+      out.push([null, {
+        type: "defineLabel",
+        label: skipLabel
+      }]);
+    } else if (op === OP.JUMP_IF_TRUE) {
+      // Invert to JUMP_IF_FALSE so the true path (jump taken) falls into dispatch.
+      const cond = instr[1];
+      const targetLabel = extractLabel(instr[2]);
+      if (targetLabel === null) {
+        out.push(instr);
+        continue;
+      }
+      const siteKey = getRandomInt(1, U16_MAX);
+      const skipLabel = compiler._makeLabel(targetLabel + "_skip");
+      out.push([OP.JUMP_IF_FALSE, cond, {
+        type: "label",
+        label: skipLabel
+      }]);
+      out.push([OP.LOAD_INT, ref(rDisp), encodedLabelOperand(targetLabel, siteKey, fnSalt)]);
+      out.push([OP.LOAD_INT, ref(rKey), siteKey]);
+      out.push([OP.JUMP, {
+        type: "label",
+        label: dispatcherLabel
+      }]);
+      out.push([null, {
+        type: "defineLabel",
+        label: skipLabel
+      }]);
+    } else {
+      out.push(instr);
+    }
+  }
+
+  // Dispatcher block appended after the function body.  Never reached by
+  // fall-through; all entries are via the JUMP dispatcher instructions above.
+  out.push(...buildDispatcherBlock(compiler, rDisp, rKey, rClosure, dispatcherLabel));
+  return {
+    instrs: out,
+    tail: tmpl.bytecode
+  };
+}
+
+// ── Pass entry point ──────────────────────────────────────────────────────────
+export function dispatcher(bc, compiler) {
+  const maxId = buildMaxIdMap(bc);
+  // Label factory delegates to the compiler's counter so labels never collide.
+  const labelCounter = () => compiler._makeLabel("dispatcher");
+  // forEachFunction collects each function's tail (decode closure bytecode) and
+  // appends them all after the last function body, so every MAKE_CLOSURE can
+  // reference its entryLabel regardless of where it appears in the bytecode.
+  return forEachFunction(bc, compiler, (fnInstrs, fnId) => processFunctionBlock(fnInstrs, fnId, compiler, maxId, labelCounter));
+}

package/dist/transforms/bytecode/macroOpcodes.js

@@ -1,6 +1,6 @@
-import { SOURCE_NODE_SYM } from "../../compiler.js";
+import { OP_ORIGINAL, SOURCE_NODE_SYM } from "../../compiler.js";
 import { nextFreeSlot } from "../../utils/op-utils.js";
-import { ok } from "node:assert";
+import { ok } from "assert";
 
 // Opcodes that must not appear in a non-terminal position inside a macro window.
 // Jump ops: modifying frame._pc mid-execution causes the macro handler to
@@ -54,7 +54,7 @@ export function macroOpcodes(bc, compiler) {
       if (JUMP_OPS.has(op)) return false;
       if (nonTerminalExcluded.find(name => opName.includes(name))) return false;
     }
-    return OP_NAME[op] !== undefined;
+    return OP_NAME[op] !== undefined && OP_ORIGINAL[opName] !== undefined;
   }
 
   // ── Step 1: count window frequencies ──────────────────────────────────────

package/dist/transforms/bytecode/resolveConstants.js

@@ -0,0 +1,100 @@
+import { SOURCE_NODE_SYM } from "../../compiler.js";
+import { getRandomInt } from "../../utils/random-utils.js";
+import { U16_MAX } from "../../utils/op-utils.js";
+
+// Encrypt a string with a position-dependent XOR key (u16) then base64-encode.
+//
+// Each char code is XOR'd with ((key + i) & 0xFFFF), producing a u16 value.
+// The u16 values are packed as little-endian byte pairs (matching decodeBytecode),
+// then base64-encoded so the stored constant is always safe ASCII — no raw Unicode
+// surrogates, control chars, or quote chars that would break JS string literals.
+function concealString(s, key) {
+  const bytes = new Uint8Array(s.length * 2);
+  for (let i = 0; i < s.length; i++) {
+    const code = s.charCodeAt(i) ^ key + i & 0xffff;
+    bytes[i * 2] = code & 0xff;
+    bytes[i * 2 + 1] = code >> 8 & 0xff;
+  }
+  return Buffer.from(bytes).toString("base64");
+}
+
+// Resolve all {type:"constant", value} (index) and {type:"constant", value, key: true} (key) operands
+//
+// constPoolIndex — index into the constants array (as before).
+// concealKey     — XOR key used to conceal this constant.
+//                  0 means no concealment (concealConstants is off, or the
+//                  value type is not concealable: null, undefined, bool, float…).
+//
+// The constants array stores the CONCEALED value when key != 0.
+// The runtime's _readConstant(idx, key) reverses the concealment on the fly.
+//
+// Both slots are u16; all existing operand serialization handles them identically.
+export function resolveConstants(bc, compiler) {
+  const constants = [];
+  const constantsMap = new Map(); // original value → pool index
+  const keyMap = new Map(); // pool index → conceal key
+
+  function intern(operand) {
+    const value = operand.value;
+    let idx = constantsMap.get(value);
+    let key = 0;
+    if (typeof idx !== "number") {
+      idx = constants.length;
+      constantsMap.set(value, idx);
+      if (compiler.options.concealConstants && typeof value === "string") {
+        // Strings: position-dependent XOR. Key must be >= 1.
+        key = getRandomInt(1, U16_MAX);
+        constants.push(concealString(value, key));
+      } else if (compiler.options.concealConstants && typeof value === "number" && Number.isInteger(value)) {
+        // Integers: simple XOR. Result is still a valid JS integer.
+        key = getRandomInt(1, U16_MAX);
+        constants.push(value ^ key);
+      } else {
+        // Not concealable (null, undefined, boolean, float, RegExp…) or option off.
+        key = 0;
+        constants.push(value);
+      }
+      keyMap.set(idx, key);
+    } else {
+      // Reuse existing pool entry — same key that was assigned on first intern.
+      key = keyMap.get(idx);
+    }
+    const idxOperand = {
+      type: "number",
+      resolvedValue: idx
+    };
+    const keyOperand = {
+      type: "number",
+      resolvedValue: key
+    };
+
+    // key is a plain u16 number — no wrapping needed.
+    return [idxOperand, keyOperand];
+  }
+  const resolved = [];
+  for (const instr of bc) {
+    const [op, ...operands] = instr;
+    const hasConstant = operands.some(o => o !== undefined && o !== null && typeof o === "object" && o.type === "constant");
+    if (hasConstant) {
+      // 1-to-2 expansion: each {type:"constant"} becomes [constIdx, concealKey].
+      const newOperands = operands.map(operand => {
+        if (operand?.type === "constant") {
+          const [idxOperand, key] = intern(operand);
+          const newOperand = operand?.key ? key : idxOperand;
+          return Object.assign(operand, newOperand);
+        } else {
+          return operand;
+        }
+      });
+      const newInstr = [op, ...newOperands];
+      newInstr[SOURCE_NODE_SYM] = instr[SOURCE_NODE_SYM];
+      resolved.push(newInstr);
+    } else {
+      resolved.push(instr);
+    }
+  }
+  return {
+    bytecode: resolved,
+    constants
+  };
+}

package/dist/transforms/bytecode/resolveLabels.js

@@ -31,11 +31,13 @@ export function resolveLabels(bc, compiler) {
     const operand = instr[1];
     if (op === null && operand !== null && typeof operand === "object" && operand.type === "defineLabel") {
       labelToPc.set(operand.label, realPc);
-    } else {
-      // Each instruction occupies 1 slot for the opcode + 1 per operand.
-      // IMPORTANT: 'placeholder' operands are not counted
-      realPc += instr.filter(x => x?.placeholder !== true).length;
+      continue;
     }
+    if (op === null) continue; // "null" opcodes are never emitted
+
+    // Each instruction occupies 1 slot for the opcode + 1 per operand.
+    // IMPORTANT: 'placeholder' operands are not counted
+    realPc += instr.filter(x => x?.placeholder !== true).length;
   }
 
   // Pass 2 – build the resolved instruction list.
@@ -44,31 +46,32 @@ export function resolveLabels(bc, compiler) {
   for (const instr of bc) {
     const [op, ...operands] = instr;
 
-    // Strip defineLabel pseudo-ops.
-    if (op === null && typeof operands[0] === "object" && operands[0]?.type === "defineLabel") {
-      continue;
-    }
-
-    // Replace label-ref operands with their resolved flat PC (any position).
+    // Replace label-ref and encodedLabel operands with resolved flat PCs.
+    // encodedLabel applies an encoding to the PC before emission so that raw
+    // jump targets are hidden; the dispatcher block reverses it at runtime.
+    // To change the encoding scheme, update both here and in jumpDispatcher.ts.
     const newOperands = operands.map(operand => {
-      if (operand !== undefined && operand !== null && typeof operand === "object" && operand.type === "label") {
+      if (operand === undefined || operand === null || typeof operand !== "object") return operand;
+      const type = operand.type;
+      if (type === "label") {
         const pc = labelToPc.get(operand.label);
         if (pc === undefined) throw new Error(`Undefined label: ${operand.label}`);
+        let resolvedValue = pc + (operand.offset ?? 0);
+        if (operand.transform) {
+          resolvedValue = operand.transform(resolvedValue);
+        }
         const newOperand = {
           type: "number",
-          resolvedValue: pc + (operand.offset ?? 0)
+          resolvedValue: resolvedValue
         };
-
-        // Mutate original object so that references are also updated
-        if (typeof operand === "object" && operand !== null) {
-          return Object.assign(operand, newOperand);
-        }
-        return newOperand;
+        return Object.assign(operand, newOperand);
       }
       return operand;
     });
     const newInstr = [op, ...newOperands];
     newInstr[SOURCE_NODE_SYM] = instr[SOURCE_NODE_SYM];
+
+    // Pseudo-op "defineLabel"s are kept within this bytecode as the Serializer is responsible for dropping it, and its useful information for comment generation
     resolved.push(newInstr);
   }
 

package/dist/transforms/bytecode/resolveRegisters.js

@@ -0,0 +1,216 @@
+// resolveRegisters
+// Converts virtual RegisterOperand objects into concrete slot indices and sets
+// each FnDescriptor's regCount.
+//
+// Two-tier slot assignment:
+//
+//   "local::" pool  (params, `arguments`, hoisted vars, upvalue-captured vars)
+//   ─────────────────────────────────────────────────────────────────────────
+//   Sorted by virtual-id, slots assigned sequentially with NO reuse.
+//   This is required because:
+//     • The runtime writes args[i] to regs[base + i] at call time, so params
+//       MUST occupy slots 0..paramCount-1 in virtual-id order.
+//     • Open upvalues hold an absolute slot index and read regs[base+slot] for
+//       the lifetime of the outer frame — reusing a captured slot corrupts reads.
+//
+//   All other pools  (e.g. "temp::", "canary::", pass-introduced pools)
+//   ─────────────────────────────────────────────────────────────────────────
+//   Linear-scan with a free list: registers are sorted by firstUse, and any
+//   slot whose previous occupant's lastUse < current register's firstUse is
+//   recycled. An explicit [null, freeRegOperand(reg)] pseudo-instruction clamps
+//   lastUse early, enabling reuse before the natural end of the live range.
+//
+//   Pools are processed in priority order: "local::" always first (slots
+//   0..N), then remaining pools alphabetically. This keeps temp slots above
+//   the reserved param/local region.
+//
+//   regCount = max concrete slot used across all pools + 1.
+//
+// Run AFTER all IR-level passes but BEFORE resolveLabels / resolveConstants.
+
+export function resolveRegisters(bc, compiler) {
+  function registerPoolKey(op) {
+    // Pinned registers must never share a slot with anything else.
+    // Passes set this on registers whose live range crosses a CFF back-edge
+    // that the linear-scan liveness analysis cannot see.
+    if (op.pinned) return "local::";
+    return `${op.kind ?? "local"}::${op.scopeId ?? ""}`;
+  }
+
+  // ── Pass 1: collect live ranges ───────────────────────────────────────────
+  // For each (fnId, virtId) record the first and last instruction index where
+  // the register appears as a real operand.  A freeReg marker clamps lastUse.
+
+  // fnId -> virtId -> RegInfo
+  const fnRegInfo = new Map();
+  for (let i = 0; i < bc.length; i++) {
+    const instr = bc[i];
+    for (let j = 1; j < instr.length; j++) {
+      const op = instr[j];
+      if (!op || typeof op !== "object") continue;
+      if (op.type === "register") {
+        const {
+          fnId,
+          id
+        } = op;
+        const poolKey = registerPoolKey(op);
+        let fnMap = fnRegInfo.get(fnId);
+        if (!fnMap) {
+          fnMap = new Map();
+          fnRegInfo.set(fnId, fnMap);
+        }
+        const existing = fnMap.get(id);
+        if (!existing) {
+          fnMap.set(id, {
+            firstUse: i,
+            lastUse: i,
+            poolKey,
+            freed: false
+          });
+        } else if (!existing.freed) {
+          // Only extend lastUse if no explicit freeReg has clamped it yet.
+          existing.lastUse = i;
+        }
+      } else if (op.type === "freeReg") {
+        // Explicit end-of-life marker: clamp lastUse and prevent extension.
+        const {
+          fnId,
+          id
+        } = op;
+        const fnMap = fnRegInfo.get(fnId);
+        if (fnMap) {
+          const info = fnMap.get(id);
+          if (info && !info.freed) {
+            info.lastUse = i;
+            info.freed = true;
+          }
+        }
+      }
+    }
+  }
+
+  // ── Pass 2: slot assignment per function ──────────────────────────────────
+  // fnId -> virtId -> concrete slot
+  const fnSlotMaps = new Map();
+
+  // Pool ordering: "local::" always first; all other keys sorted alphabetically.
+  function poolSortKey(key) {
+    return key === "local::" ? [0, ""] : [1, key];
+  }
+  for (const [fnId, regMap] of fnRegInfo) {
+    // Group by pool key.
+    const pools = new Map();
+    for (const [id, info] of regMap) {
+      let pool = pools.get(info.poolKey);
+      if (!pool) {
+        pool = [];
+        pools.set(info.poolKey, pool);
+      }
+      pool.push({
+        id,
+        firstUse: info.firstUse,
+        lastUse: info.lastUse
+      });
+    }
+    const sortedPoolKeys = Array.from(pools.keys()).sort((a, b) => {
+      const [pa, sa] = poolSortKey(a);
+      const [pb, sb] = poolSortKey(b);
+      if (pa !== pb) return pa - pb;
+      return sa < sb ? -1 : sa > sb ? 1 : 0;
+    });
+    const slotMap = new Map(); // virtId -> slot
+    fnSlotMaps.set(fnId, slotMap);
+
+    // nextSlot is the high-water mark: the next fresh slot to allocate.
+    // It is shared across all pools so each pool's slots start above the
+    // previous pool's maximum slot.
+    let nextSlot = 0;
+    for (const poolKey of sortedPoolKeys) {
+      const regs = pools.get(poolKey);
+      if (poolKey === "local::") {
+        // ── Local pool: virtual-id order, no reuse ────────────────────────
+        // Params must be at the lowest slots (written by the runtime at call
+        // time); upvalue captures must keep their slot for the frame's lifetime.
+        regs.sort((a, b) => a.id - b.id);
+        for (const reg of regs) {
+          slotMap.set(reg.id, nextSlot++);
+        }
+      } else {
+        // ── Non-local pool: firstUse order, linear-scan reuse ─────────────
+        regs.sort((a, b) => a.firstUse - b.firstUse);
+
+        // freeList entries: { slot, freeAt } where freeAt = lastUse of current
+        // occupant.  A slot becomes available when freeAt < next reg's firstUse.
+        const freeList = [];
+        for (const reg of regs) {
+          // Find the lowest-numbered slot whose last occupant has ended.
+          let bestSlot = -1;
+          let bestIdx = -1;
+          for (let k = 0; k < freeList.length; k++) {
+            if (freeList[k].freeAt < reg.firstUse) {
+              if (bestSlot === -1 || freeList[k].slot < bestSlot) {
+                bestSlot = freeList[k].slot;
+                bestIdx = k;
+              }
+            }
+          }
+          let assignedSlot;
+          if (bestIdx !== -1) {
+            assignedSlot = bestSlot;
+            freeList.splice(bestIdx, 1);
+          } else {
+            assignedSlot = nextSlot++;
+          }
+          slotMap.set(reg.id, assignedSlot);
+          freeList.push({
+            slot: assignedSlot,
+            freeAt: reg.lastUse
+          });
+        }
+        // nextSlot already reflects the high-water mark; reused slots are
+        // always < nextSlot by construction.
+      }
+    }
+  }
+
+  // ── Pass 3: patch register operands ──────────────────────────────────────
+  for (const instr of bc) {
+    for (let i = 1; i < instr.length; i++) {
+      const op = instr[i];
+      if (!op || typeof op !== "object") continue;
+      if (op.type === "register") {
+        op.resolvedValue = fnSlotMaps.get(op.fnId)?.get(op.id);
+      }
+    }
+  }
+
+  // ── Pass 4: set regCount on each FnDescriptor ─────────────────────────────
+  // regCount = max concrete slot used + 1  (not sum of virtual-register counts).
+  for (const desc of compiler.fnDescriptors) {
+    const fnId = desc._fnIdx;
+    const slotMap = fnSlotMaps.get(fnId);
+    let regCount = 0;
+    if (slotMap) {
+      for (const slot of slotMap.values()) {
+        if (slot + 1 > regCount) regCount = slot + 1;
+      }
+    }
+    desc.regCount = regCount;
+  }
+  compiler.mainRegCount = compiler.mainFn?.regCount ?? 0;
+
+  // ── Pass 5: patch fnRegCount operands ────────────────────────────────────
+  for (const instr of bc) {
+    for (let i = 1; i < instr.length; i++) {
+      const op = instr[i];
+      if (!op || typeof op !== "object") continue;
+      if (op.type === "fnRegCount") {
+        const desc = compiler.fnDescriptors[op.fnId];
+        op.resolvedValue = desc?.regCount ?? 0;
+      }
+    }
+  }
+  return {
+    bytecode: bc
+  };
+}