optipack 1.0.0 → 1.0.1

package/src/bench.js

@@ -0,0 +1,231 @@
+/**
+ * `optipack bench` — A/B benchmark of a pack's original vs optimized scripts
+ * under the harness mock.
+ *
+ * Measures, for identical simulated scenarios:
+ *  - host-boundary crossings by kind (the metric optipack exists to reduce:
+ *    location reads, getComponent, getDynamicProperty, getEntities, ...).
+ *    Engine-independent: a crossing is a crossing in V8 or QuickJS.
+ *  - wall-clock time (INDICATIVE ONLY: Node is V8 with a JIT, Minecraft is
+ *    QuickJS without one — use the in-game `/script profiler` workflow in
+ *    BENCHMARKING.md for authoritative numbers).
+ *  - effect-trace equality (a bench between non-equivalent builds is invalid
+ *    and is flagged).
+ *
+ * Determinism: a virtual clock replaces Date during variant execution and
+ * advances a fixed 50ms per tick, so time-gated script logic sees identical
+ * clocks on both sides regardless of how fast each variant actually runs.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { performance } from 'node:perf_hooks';
+
+import { makeRecorder, runVariant, assertSameEffects, pathToUrl, ensureHooks } from './harness/driver.js';
+import { runPack } from './pipeline.js';
+import { normalizeConfig } from './config.js';
+
+const TICK_MS = 50; // 20 TPS
+
+function installVirtualClock() {
+  const RealDate = Date;
+  let now = RealDate.now();
+  class VirtualDate extends RealDate {
+    constructor(...args) {
+      if (args.length === 0) super(now);
+      else super(...args);
+    }
+    static now() {
+      return now;
+    }
+  }
+  globalThis.Date = VirtualDate;
+  return {
+    advance(ms) { now += ms; },
+    restore() { globalThis.Date = RealDate; },
+  };
+}
+
+/**
+ * Run one variant end to end and collect measurements.
+ */
+async function measureVariant(entryAbsPath, variant, scenario, ticks) {
+  const clock = installVirtualClock();
+  const rec = makeRecorder({ reads: scenario.reads, state: scenario.state });
+  globalThis.__opkRecorder = rec;
+  const t = { importMs: 0, ticksMs: 0 };
+  try {
+    const importStart = performance.now();
+    await import(`${pathToUrl(entryAbsPath)}?opkv=${variant}&t=${Date.now()}-${Math.floor(performance.now() * 1000)}`);
+    t.importMs = performance.now() - importStart;
+
+    const steps = scenario.steps || [];
+    const tickStart = performance.now();
+    for (const step of steps) {
+      if (step.op === 'tick') {
+        for (let i = 0; i < step.n; i++) {
+          rec.tick(1);
+          clock.advance(TICK_MS);
+        }
+      } else if (step.op === 'fire') {
+        rec.fire(step.event, step.payload);
+      } else if (step.op === 'fireMany') {
+        for (let i = 0; i < (step.count || 1); i++) rec.fire(step.event, step.payload);
+      } else if (step.op === 'call') {
+        step.fn(rec);
+      }
+    }
+    if (ticks > 0) {
+      for (let i = 0; i < ticks; i++) {
+        rec.tick(1);
+        clock.advance(TICK_MS);
+      }
+    }
+    t.ticksMs = performance.now() - tickStart;
+  } finally {
+    globalThis.__opkRecorder = null;
+    clock.restore();
+  }
+  return {
+    counters: rec.counters,
+    effects: rec.effects,
+    wall: t,
+    totalTicks: rec.tickCounter,
+  };
+}
+
+function compareCounters(a, b) {
+  const keys = [...new Set([...Object.keys(a), ...Object.keys(b)])].sort();
+  return keys.map((k) => {
+    const av = a[k] || 0;
+    const bv = b[k] || 0;
+    const delta = bv - av;
+    const pct = av === 0 ? (bv === 0 ? 0 : 100) : Math.round((delta / av) * 100);
+    return { kind: k, original: av, optimized: bv, delta, pct };
+  });
+}
+
+/**
+ * Full bench: build the optimized pack, measure both variants, report.
+ */
+export async function benchPack(inputDirRaw, options = {}) {
+  const inputDir = path.resolve(inputDirRaw);
+  const {
+    ticks = 200,
+    entry = null,
+    scenario: scenarioPath = null,
+    quiet = false,
+  } = options;
+
+  const configRaw = { ...(options.config || {}) };
+  if (options.level) configRaw.level = options.level;
+  const config = normalizeConfig(configRaw);
+  ensureHooks();
+  const outputDir = fs.mkdtempSync(path.join(os.tmpdir(), 'optipack-bench-'));
+  const report = runPack(inputDir, outputDir, config);
+
+  // Locate the entry: explicit, manifest, or first script with subscribers.
+  let entryRel = entry;
+  if (!entryRel) {
+    const manifestPath = path.join(inputDir, 'manifest.json');
+    if (fs.existsSync(manifestPath)) {
+      try {
+        const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8').replace(/^\uFEFF/, ''));
+        const scriptModule = (manifest.modules || []).find((m) => m.type === 'script');
+        if (scriptModule && scriptModule.entry) entryRel = scriptModule.entry;
+      } catch { /* fall through */ }
+    }
+  }
+  if (!entryRel) {
+    const scripts = report.files.map((f) => f.path);
+    entryRel = scripts[0];
+  }
+  if (!entryRel) throw new Error('bench: pack has no script files');
+  if (!report.files.some((f) => f.path === entryRel)) {
+    throw new Error(`bench: entry "${entryRel}" is not among the pack's script files`);
+  }
+
+  const scenario = scenarioPath
+    ? JSON.parse(fs.readFileSync(scenarioPath, 'utf8').replace(/^\uFEFF/, ''))
+    : { reads: {}, state: {}, steps: [] };
+
+  const entryOriginal = path.join(inputDir, entryRel);
+  const entryOptimized = path.join(outputDir, entryRel);
+
+  // 3 alternating rounds per variant; report the median tick-phase time. A
+  // single round is dominated by V8 JIT warm-up noise (Node is only indicative
+  // anyway — see BENCHMARKING.md for the in-game workflow).
+  const rounds = 3;
+  const run = (v) => measureVariant(v === 'orig' ? entryOriginal : entryOptimized, v, scenario, ticks);
+  const aRuns = [];
+  const bRuns = [];
+  for (let i = 0; i < rounds; i++) {
+    aRuns.push(await run('orig'));
+    bRuns.push(await run('opt'));
+  }
+  const a = aRuns[0];
+  const b = bRuns[0];
+  a.wall.ticksMs = median(aRuns.map((r) => r.wall.ticksMs));
+  b.wall.ticksMs = median(bRuns.map((r) => r.wall.ticksMs));
+
+  let identical = true;
+  try {
+    assertSameEffects(a, b, 'bench');
+  } catch (e) {
+    identical = false;
+    if (!quiet) console.error(`optipack bench: WARNING — effect traces diverge, benchmark is not meaningful:\n${e.message}`);
+  }
+
+  const counters = compareCounters(a.counters, b.counters);
+  const totalCrossings = (v) => Object.values(v).reduce((x, y) => x + y, 0);
+  const result = {
+    pack: inputDir,
+    entry: entryRel,
+    ticks: a.totalTicks,
+    level: config.level,
+    effectsIdentical: identical,
+    boundary: counters,
+    boundaryTotals: { original: totalCrossings(a.counters), optimized: totalCrossings(b.counters) },
+    wall: {
+      original: a.wall,
+      optimized: b.wall,
+      note: 'Node/V8 numbers are indicative only; Minecraft runs QuickJS (no JIT).',
+    },
+    transforms: report.totals.transforms,
+  };
+
+  if (!quiet) printBench(result);
+  return result;
+}
+
+function fmtPct(pct) {
+  const s = pct > 0 ? `+${pct}%` : `${pct}%`;
+  return s;
+}
+
+function median(values) {
+  const sorted = [...values].sort((x, y) => x - y);
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+
+export function printBench(result) {
+  const rows = result.boundary;
+  const width = Math.max(10, ...rows.map((r) => r.kind.length));
+  console.log(`optipack bench — ${result.pack} (entry ${result.entry}, ${result.ticks} ticks, level ${result.level})`);
+  if (!result.effectsIdentical) {
+    console.log('  !! effect traces DIVERGE — the two builds are not behavior-equivalent; treat numbers with suspicion');
+  }
+  console.log(`  ${'boundary crossing'.padEnd(width)}  original  optimized  delta`);
+  for (const r of rows) {
+    console.log(`  ${r.kind.padEnd(width)}  ${String(r.original).padStart(8)}  ${String(r.optimized).padStart(9)}  ${fmtPct(r.pct)}`);
+  }
+  const tot = result.boundaryTotals;
+  const totalPct = tot.original === 0 ? 0 : Math.round(((tot.optimized - tot.original) / tot.original) * 100);
+  console.log(`  ${'TOTAL'.padEnd(width)}  ${String(tot.original).padStart(8)}  ${String(tot.optimized).padStart(9)}  ${fmtPct(totalPct)}`);
+  const w = result.wall;
+  const usPerTick = (v) => (result.ticks > 0 ? Math.round((v.ticksMs / result.ticks) * 1000) : 0);
+  console.log(`  transforms applied: ${result.transforms}`);
+  console.log(`  wall (indicative, Node/V8): original ${w.original.ticksMs.toFixed(1)}ms (${usPerTick(w.original)}µs/tick)` +
+    `, optimized ${w.optimized.ticksMs.toFixed(1)}ms (${usPerTick(w.optimized)}µs/tick)`);
+}

package/src/cli.js

@@ -1,9 +1,10 @@
-/**
+/**
  * optipack CLI.
  *
  *   optipack <inputPackDir> <outputPackDir> [options]
+ *   optipack bench <inputPackDir> [options]
  *
- * Exit codes: 0 success · 1 usage/config error · 2 parse failure · 3 internal error
+ * Exit codes: 0 success · 1 usage/config error · 2 parse failure · 3 internal error
  */
 import fs from 'node:fs';
 import path from 'node:path';
@@ -14,47 +15,31 @@ import { runPack, ParseFailureError, InternalError } from './pipeline.js';
 import { PASS_IDS, PASS_CODES } from './passes/index.js';
 import { unifiedDiff } from './diff.js';
 
-export async function main(argv) {
-  const program = new Command();
-  program
-    .name('optipack')
-    .description('QuickJS-targeted micro-optimizing pre-processor for Minecraft Bedrock behavior-pack scripts')
-    .version('1.0.0')
-    .argument('<inputPackDir>', 'behavior pack directory to read')
-    .argument('<outputPackDir>', 'directory to write the optimized pack into')
-    .option('--level <level>', 'optimization level: safe | balanced | risky')
-    .option('--config <path>', 'config file (default: ./optipack.config.json when present)')
-    .option('--only <ids>', 'comma-separated transform ids to run exclusively')
-    .option('--except <ids>', 'comma-separated transform ids to skip')
-    .option('--dry-run', 'analyze + report, write nothing (prints report to stdout unless --report is given)')
-    .option('--diff', 'print unified diffs per changed file')
-    .option('--report <path>', `report file (default: <outputPackDir>/optipack-report.json)`)
-    .option('--lint <bool>', 'enable/disable the lint pass (true|false)', parseBoolOpt)
-    .exitOverride();
+function parseBoolOpt(v) {
+  if (v === 'true' || v === '' || v === undefined) return true;
+  if (v === 'false') return false;
+  // Signal an invalid value; validated by the caller.
+  return v;
+}
 
-  let opts;
-  const args = [];
+function parseOptInt(v) {
+  const n = Number.parseInt(v, 10);
+  return Number.isFinite(n) && n >= 0 ? n : undefined;
+}
+
+async function runOptimize(inputDir, outputDir, opts) {
   try {
-    program.parse(argv, { from: 'node' });
-    opts = program.opts();
-    args.push(...program.args);
+    const exit = await runOptimizeInner(inputDir, outputDir, opts);
+    process.exitCode = exit;
+    return exit;
   } catch (e) {
-    if (e && e.code === 'commander.version') {
-      console.log(e.message);
-      return 0;
-    }
-    if (e && (e.code === 'commander.help' || e.code === 'commander.helpDisplayed')) {
-      return 0;
-    }
-    if (e && e.code === 'commander.missingArgument') {
-      console.error(`optipack: ${e.message}`);
-      return 1;
-    }
-    console.error(`optipack: ${e && e.message ? e.message : String(e)}`);
-    return 1;
+    process.exitCode = 3;
+    console.error(`optipack: internal error — ${e && e.stack ? e.stack : String(e)}`);
+    return 3;
   }
+}
 
-  const [inputDir, outputDir] = args;
+async function runOptimizeInner(inputDir, outputDir, opts) {
   if (!inputDir || !outputDir) {
     console.error('optipack: both <inputPackDir> and <outputPackDir> are required');
     return 1;
@@ -84,7 +69,6 @@ export async function main(argv) {
     return 1;
   }
 
-  // CLI overrides.
   const cli = {
     level: opts.level,
     only: opts.only,
@@ -122,7 +106,7 @@ export async function main(argv) {
       if (opts.report !== undefined) {
         fs.mkdirSync(path.dirname(reportPath), { recursive: true });
         fs.writeFileSync(reportPath, json);
-        console.log(`optipack: dry run — wrote report to ${reportPath} (no pack files written)`);
+        console.log(`optipack: dry run — wrote report to ${reportPath} (no pack files written)`);
       } else {
         console.log(json);
       }
@@ -144,7 +128,6 @@ export async function main(argv) {
       }
     }
 
-    // Human summary on success (only when not printing the full report).
     if (!dryRun || opts.report !== undefined) {
       const t = report.totals;
       console.log(
@@ -156,25 +139,107 @@ export async function main(argv) {
     return 0;
   } catch (e) {
     if (e instanceof ParseFailureError) {
-      console.error(`optipack: parse failure — ${e.message}`);
+      console.error(`optipack: parse failure — ${e.message}`);
       return 2;
     }
     if (e instanceof InternalError) {
-      console.error(`optipack: internal error — ${e.message}`);
+      console.error(`optipack: internal error — ${e.message}`);
       return 3;
     }
     if (e && e.code === 1) {
       console.error(`optipack: ${e.message}`);
       return 1;
     }
-    console.error(`optipack: internal error — ${e && e.stack ? e.stack : String(e)}`);
+    console.error(`optipack: internal error — ${e && e.stack ? e.stack : String(e)}`);
     return 3;
   }
 }
 
-function parseBoolOpt(v) {
-  if (v === 'true' || v === '' || v === undefined) return true;
-  if (v === 'false') return false;
-  // Signal an invalid value; validated by the caller.
-  return v;
+async function runBench(packDir, opts) {
+  const run = async () => {
+    const { benchPack } = await import('./bench.js');
+    const result = await benchPack(packDir, {
+      ticks: opts.ticks,
+      entry: opts.entry,
+      scenario: opts.scenario,
+      config: opts.config && JSON.parse(fs.readFileSync(opts.config, 'utf8').replace(/^\uFEFF/, '')),
+      level: opts.level,
+    });
+    if (opts.json) {
+      fs.mkdirSync(path.dirname(opts.json), { recursive: true });
+      fs.writeFileSync(opts.json, JSON.stringify(result, null, 2) + '\n');
+      console.log(`optipack bench: JSON written to ${opts.json}`);
+    }
+    return result.effectsIdentical ? 0 : 1;
+  };
+  try {
+    const code = await run();
+    process.exitCode = code;
+    return code;
+  } catch (e) {
+    const code = e instanceof ParseFailureError ? 2
+      : e instanceof InternalError ? 3
+        : 1;
+    console.error(`optipack bench: ${e instanceof ParseFailureError || e instanceof InternalError ? e.message : (e && e.message ? e.message : String(e))}`);
+    process.exitCode = code;
+    return code;
+  }
+}
+
+export async function main(argv) {
+  const program = new Command();
+  program
+    .name('optipack')
+    .description('QuickJS-targeted micro-optimizing pre-processor for Minecraft Bedrock behavior-pack scripts')
+    .version('1.0.0')
+    .exitOverride()
+    .configureOutput({ writeErr: () => {} }); // actions print errors themselves
+
+  program
+    .command('bench')
+    .description('A/B benchmark: original vs optimized scripts under the harness mock (boundary crossings + indicative wall time). See BENCHMARKING.md for the in-game workflow.')
+    .argument('<inputPackDir>', 'behavior pack directory to benchmark')
+    .option('--ticks <n>', 'simulated ticks to run (default 200)', parseOptInt)
+    .option('--entry <path>', 'script entry to load (default: manifest script entry)')
+    .option('--scenario <path>', 'scenario JSON (reads/state/steps) driving events between ticks')
+    .option('--json <path>', 'also write the bench result as JSON to this path')
+    .option('--level <level>', 'optimization level for the optimized build')
+    .option('--config <path>', 'config file for the optimized build')
+    .action(function (packDir, cmdOpts, command) {
+      // --level is declared on both this subcommand and the default command;
+      // Commander absorbs shadowed names into the parent scope, so merge.
+      return runBench(packDir, command.optsWithGlobals());
+    });
+
+  program
+    .argument('<inputPackDir>', 'behavior pack directory to read')
+    .argument('<outputPackDir>', 'directory to write the optimized pack into')
+    .option('--level <level>', 'optimization level: safe | balanced | risky')
+    .option('--config <path>', 'config file (default: ./optipack.config.json when present)')
+    .option('--only <ids>', 'comma-separated transform ids to run exclusively')
+    .option('--except <ids>', 'comma-separated transform ids to skip')
+    .option('--dry-run', 'analyze + report, write nothing (prints report to stdout unless --report is given)')
+    .option('--diff', 'print unified diffs per changed file')
+    .option('--report <path>', 'report file (default: <outputPackDir>/optipack-report.json)')
+    .option('--lint <bool>', 'enable/disable the lint pass (true|false)', parseBoolOpt)
+    .action((inputDir, outputDir) => runOptimize(inputDir, outputDir, program.opts()));
+
+  try {
+    await program.parseAsync(argv, { from: 'node' });
+  } catch (e) {
+    if (e && e.code === 'commander.version') {
+      console.log(e.message);
+      return 0;
+    }
+    if (e && (e.code === 'commander.help' || e.code === 'commander.helpDisplayed')) {
+      return 0;
+    }
+    if (e && (e.code === 'commander.missingArgument' || e.code === 'commander.missingSubcommandArgument')) {
+      console.error(`optipack: ${e.message}`);
+      return 1;
+    }
+    console.error(`optipack: ${e && e.message ? e.message : String(e)}`);
+    return 1;
+  }
+  return process.exitCode ?? 0;
 }

package/{test/harness/setup.js → src/harness/driver.js}

@@ -18,12 +18,15 @@ import os from 'node:os';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 
-if (!globalThis.__opkHooksRegistered) {
-  register(
-    pathToFileURL(path.join(here, '..', 'loader-hooks.mjs')).href,
-    pathToFileURL(path.join(here, 'setup.js')).href
-  );
-  globalThis.__opkHooksRegistered = true;
+/** Register the ESM loader hooks (idempotent). Only needed for variant loading. */
+export function ensureHooks() {
+  if (!globalThis.__opkHooksRegistered) {
+    register(
+      pathToFileURL(path.join(here, 'loader-hooks.mjs')).href,
+      pathToFileURL(path.join(here, 'driver.js')).href
+    );
+    globalThis.__opkHooksRegistered = true;
+  }
 }
 
 export function makeRecorder({ reads = {}, state = {} } = {}) {
@@ -37,6 +40,10 @@ export function makeRecorder({ reads = {}, state = {} } = {}) {
     readIdx: {},
     state,
     tickCounter: 0,
+    counters: {},
+  };
+  r.count = (kind, n = 1) => {
+    r.counters[kind] = (r.counters[kind] || 0) + n;
   };
   r.effect = (call, args) => {
     r.effects.push({ call, args });
@@ -105,7 +112,7 @@ export function makeRecorder({ reads = {}, state = {} } = {}) {
   return r;
 }
 
-/** Recursively replace {__entity: id} markers in a payload with live entities. */
+/** Recursively replace {__entity}/{__dimension}/{__block} markers in a payload with live mock objects. */
 function hydrate(value, rec) {
   if (globalThis.__opkEnsurePlayers) globalThis.__opkEnsurePlayers(rec);
   if (value === null || typeof value !== 'object') return value;
@@ -115,6 +122,14 @@ function hydrate(value, rec) {
     const found = players.find((p) => p.id === value.__entity);
     return found || value;
   }
+  if (typeof value.__dimension === 'string') {
+    if (!globalThis.__opkMakeDimension) throw new Error('hydrate __dimension: server mock not loaded');
+    return globalThis.__opkMakeDimension(value.__dimension);
+  }
+  if (value.__block) {
+    if (!globalThis.__opkMakeBlock) throw new Error('hydrate __block: server mock not loaded');
+    return globalThis.__opkMakeBlock(hydrate(value.__block.location, rec), value.__block.dimension);
+  }
   const out = {};
   for (const k of Object.keys(value)) out[k] = hydrate(value[k], rec);
   return out;
@@ -125,6 +140,7 @@ function hydrate(value, rec) {
  * Steps: {op:'tick', n}, {op:'fire', event, payload}, {op:'call', fn(rec)}
  */
 export async function runVariant(entryUrl, variant, { reads, state, steps = [] }) {
+  ensureHooks();
   const rec = makeRecorder({ reads, state });
   globalThis.__opkRecorder = rec;
   try {
@@ -132,7 +148,9 @@ export async function runVariant(entryUrl, variant, { reads, state, steps = [] }
     for (const step of steps) {
       if (step.op === 'tick') rec.tick(step.n);
       else if (step.op === 'fire') rec.fire(step.event, step.payload);
-      else if (step.op === 'call') step.fn(rec);
+      else if (step.op === 'fireMany') {
+        for (let i = 0; i < (step.count || 1); i++) rec.fire(step.event, step.payload);
+      } else if (step.op === 'call') step.fn(rec);
     }
   } finally {
     globalThis.__opkRecorder = null;
@@ -164,8 +182,8 @@ export function assertSameEffects(a, b, label = '') {
  * the original and optimized file paths.
  */
 export async function buildVariantPack(files, config, testSuffix) {
-  const { normalizeConfig } = await import('../../src/config.js');
-  const { runPack } = await import('../../src/pipeline.js');
+  const { normalizeConfig } = await import('../config.js');
+  const { runPack } = await import('../pipeline.js');
   const inputDir = fs.mkdtempSync(path.join(os.tmpdir(), `optipack-${testSuffix}-in-`));
   const outputDir = fs.mkdtempSync(path.join(os.tmpdir(), `optipack-${testSuffix}-out-`));
   for (const [relPath, content] of Object.entries(files)) {

package/src/harness/loader-hooks.mjs

@@ -0,0 +1,63 @@
+/**
+ * Node module loader hooks for differential testing.
+ *
+ * - `@minecraft/*` runtime modules resolve to harness mocks under
+ *   test/mock/@minecraft/ (single instances; the recorder is passed via
+ *   globalThis.__opkRecorder). @minecraft/server and @minecraft/server-ui
+ *   have functional mocks; the remaining runtime modules have permissive
+ *   stubs generated from their real type definitions.
+ * - Pack files are loaded with a `?opkv=<variant>` query so the original and
+ *   optimized variants get separate ESM cache entries; the query is stripped
+ *   when reading from disk and propagated to relative imports.
+ */
+import path from 'node:path';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+
+const mockDir = path.join(path.dirname(fileURLToPath(import.meta.url)), 'mock', '@minecraft');
+
+// Functional mocks.
+const FUNCTIONAL = new Set(['@minecraft/server', '@minecraft/server-ui']);
+
+// Permissive stubs generated from each module's real index.d.ts.
+const STUBBED = new Set([
+  '@minecraft/common',
+  '@minecraft/debug-utilities',
+  '@minecraft/diagnostics',
+  '@minecraft/server-admin',
+  '@minecraft/server-editor',
+  '@minecraft/server-gametest',
+  '@minecraft/server-graphics',
+  '@minecraft/server-net',
+]);
+
+const MOCK_URLS = new Map([
+  ['@minecraft/server', pathToFileURL(path.join(mockDir, 'server.mjs')).href],
+  ['@minecraft/server-ui', pathToFileURL(path.join(mockDir, 'server-ui.mjs')).href],
+  ...[...STUBBED].map((name) => [
+    name,
+    pathToFileURL(path.join(mockDir, name.replace('@minecraft/', '').replace(/\//g, '-') + '.mjs')).href,
+  ]),
+]);
+
+export async function resolve(specifier, context, nextResolve) {
+  if (MOCK_URLS.has(specifier)) {
+    return { url: MOCK_URLS.get(specifier), shortCircuit: true };
+  }
+  const res = await nextResolve(specifier, context);
+  const parentURL = context.parentURL || '';
+  if (parentURL.includes('opkv=') && res.url.startsWith('file:') && !res.url.includes('opkv=')) {
+    const q = new URL(parentURL).search;
+    return { ...res, url: res.url + q, shortCircuit: true };
+  }
+  return res;
+}
+
+export async function load(url, context, nextLoad) {
+  const u = new URL(url);
+  if (u.protocol === 'file:' && u.search) {
+    const clean = pathToFileURL(fileURLToPath(u)).href;
+    const r = await nextLoad(clean, context);
+    return { format: r.format || 'module', source: r.source, shortCircuit: true };
+  }
+  return nextLoad(url, context);
+}

package/src/harness/mock/@minecraft/common.mjs

@@ -0,0 +1,17 @@
+/**
+ * Permissive stub of @minecraft/common@1.3.0 for the differential harness.
+ * Generated from the module's real index.d.ts (see test/update-mock-stubs.mjs).
+ * Every runtime export is a permissive value: callable, constructable, and
+ * chainable; calls and constructions record harness effects so differential
+ * equivalence holds. NOT a behavioral model of the engine module.
+ */
+import { permissive } from '../permissive.mjs';
+
+export const ArgumentOutOfBoundsError = permissive('common.ArgumentOutOfBoundsError');
+export const ContainerSizeOutOfBoundsError = permissive('common.ContainerSizeOutOfBoundsError');
+export const EngineError = permissive('common.EngineError');
+export const InvalidArgumentError = permissive('common.InvalidArgumentError');
+export const InvalidArgumentErrorType = permissive('common.InvalidArgumentErrorType');
+export const PropertyOutOfBoundsError = permissive('common.PropertyOutOfBoundsError');
+export const RuntimeConditionError = permissive('common.RuntimeConditionError');
+export const UnsupportedFunctionalityError = permissive('common.UnsupportedFunctionalityError');

package/src/harness/mock/@minecraft/debug-utilities.mjs

@@ -0,0 +1,10 @@
+/**
+ * Permissive stub of @minecraft/debug-utilities@1.0.0-beta.1.20.70-preview.20 for the differential harness.
+ * Generated from the module's real index.d.ts (see test/update-mock-stubs.mjs).
+ * Every runtime export is a permissive value: callable, constructable, and
+ * chainable; calls and constructions record harness effects so differential
+ * equivalence holds. NOT a behavioral model of the engine module.
+ */
+import { permissive } from '../permissive.mjs';
+
+export const disableWatchdog = permissive('debug-utilities.disableWatchdog');

package/src/harness/mock/@minecraft/diagnostics.mjs

@@ -0,0 +1,14 @@
+/**
+ * Permissive stub of @minecraft/diagnostics@1.0.0-beta.1.21.70-preview.22 for the differential harness.
+ * Generated from the module's real index.d.ts (see test/update-mock-stubs.mjs).
+ * Every runtime export is a permissive value: callable, constructable, and
+ * chainable; calls and constructions record harness effects so differential
+ * equivalence holds. NOT a behavioral model of the engine module.
+ */
+import { permissive } from '../permissive.mjs';
+
+export const Sentry = permissive('diagnostics.Sentry');
+export const SentryAlreadyInitializedError = permissive('diagnostics.SentryAlreadyInitializedError');
+export const SentryBreadcrumbLevel = permissive('diagnostics.SentryBreadcrumbLevel');
+export const SentryUninitializedError = permissive('diagnostics.SentryUninitializedError');
+export const sentry = permissive('diagnostics.sentry');

package/src/harness/mock/@minecraft/server-admin.mjs

@@ -0,0 +1,14 @@
+/**
+ * Permissive stub of @minecraft/server-admin@1.0.0-beta.11940b24 for the differential harness.
+ * Generated from the module's real index.d.ts (see test/update-mock-stubs.mjs).
+ * Every runtime export is a permissive value: callable, constructable, and
+ * chainable; calls and constructions record harness effects so differential
+ * equivalence holds. NOT a behavioral model of the engine module.
+ */
+import { permissive } from '../permissive.mjs';
+
+export const SecretString = permissive('server-admin.SecretString');
+export const ServerSecrets = permissive('server-admin.ServerSecrets');
+export const ServerVariables = permissive('server-admin.ServerVariables');
+export const secrets = permissive('server-admin.secrets');
+export const variables = permissive('server-admin.variables');