relaxnative 0.1.2 → 0.1.4

package/dist/chunk-2KRTGQYD.js

@@ -0,0 +1,898 @@
+import {
+  alloc,
+  compileWithCache,
+  detectCompilers,
+  detectLanguage,
+  loadNative,
+  loadNativeWithBindings,
+  parseNativeSource
+} from "./chunk-UGGUZN4H.js";
+import {
+  loadFfi
+} from "./chunk-LLZ4I4OR.js";
+
+// src/registry/registryPaths.ts
+import { join, resolve } from "path";
+function getProjectRoot(cwd = process.cwd()) {
+  return cwd;
+}
+function getRegistryRoot(projectRoot = getProjectRoot()) {
+  return join(projectRoot, "native", "registry");
+}
+function getInstalledPackageDir(pkg, projectRoot = getProjectRoot()) {
+  return join(getRegistryRoot(projectRoot), pkg);
+}
+function resolveRegistryImport(specifier, projectRoot = getProjectRoot()) {
+  const prefix = "relaxnative/";
+  if (!specifier.startsWith(prefix)) return null;
+  const pkg = specifier.slice(prefix.length);
+  return resolve(getInstalledPackageDir(pkg, projectRoot));
+}
+
+// src/registry/relaxJson.ts
+import { readFileSync } from "fs";
+import { join as join2 } from "path";
+
+// src/registry/trust.ts
+function normalizeTrustLevel(value) {
+  if (value === "local" || value === "community" || value === "verified") return value;
+  return "community";
+}
+function trustPolicy(level) {
+  if (level === "verified") {
+    return {
+      requireConfirm: false,
+      warnOnInstall: false,
+      defaultIsolation: "process",
+      defaultExecutionMode: "sync",
+      allowPermissions: true
+    };
+  }
+  if (level === "local") {
+    return {
+      requireConfirm: false,
+      warnOnInstall: false,
+      defaultIsolation: "process",
+      defaultExecutionMode: "sync",
+      allowPermissions: true
+    };
+  }
+  return {
+    requireConfirm: true,
+    warnOnInstall: true,
+    defaultIsolation: "process",
+    defaultExecutionMode: "async",
+    allowPermissions: false
+  };
+}
+
+// src/registry/relaxJson.ts
+function readRelaxJson(pkgDir) {
+  const jsonPath = join2(pkgDir, "relax.json");
+  const raw = readFileSync(jsonPath, "utf8");
+  const parsed = JSON.parse(raw);
+  if (!parsed?.name || !parsed?.version || !Array.isArray(parsed?.exports)) {
+    throw new Error(`Invalid relax.json at ${jsonPath}`);
+  }
+  parsed.trust = normalizeTrustLevel(parsed.trust);
+  if (parsed.trust === "verified") {
+    const sig = parsed.registrySignature;
+    if (!sig || sig.alg !== "sha256" || typeof sig.digest !== "string" || sig.digest.length < 32) {
+      parsed.registrySignature = sig;
+    }
+  }
+  return parsed;
+}
+
+// src/registry/installer.ts
+import {
+  mkdirSync,
+  readFileSync as readFileSync4,
+  rmSync,
+  writeFileSync,
+  existsSync as existsSync2,
+  readdirSync
+} from "fs";
+import { join as join4 } from "path";
+import { createInterface } from "readline";
+
+// src/registry/staticScan.ts
+import { readFileSync as readFileSync2 } from "fs";
+function staticScanNativeSource(sourcePath) {
+  const src = readFileSync2(sourcePath, "utf8");
+  const lines = src.split(/\r?\n/);
+  const rules = [
+    {
+      rule: "process-spawn",
+      re: /\b(system|popen|fork|execv|execve|execvp|execvpe|execl|execlp|CreateProcessW|WinExec)\b/,
+      message: "Potential process execution API found"
+    },
+    {
+      rule: "raw-syscall",
+      re: /\b(syscall|__syscall)\b/,
+      message: "Raw syscall usage found"
+    },
+    {
+      rule: "file-io",
+      re: /\b(fopen|open|CreateFileW|unlink|remove|rename)\b/,
+      message: "Potential filesystem API found"
+    },
+    {
+      rule: "network",
+      re: /\b(socket|connect|bind|listen|accept|recv|send|getaddrinfo)\b/,
+      message: "Potential network API found"
+    },
+    {
+      rule: "w-x-memory",
+      re: /\b(mprotect|VirtualProtect|PROT_EXEC|PAGE_EXECUTE_READWRITE)\b/,
+      message: "Writable/executable memory pattern found"
+    },
+    {
+      rule: "dynamic-loader",
+      re: /\b(dlopen|LoadLibraryA|LoadLibraryW)\b/,
+      message: "Dynamic loader API found"
+    }
+  ];
+  const findings = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    for (const r of rules) {
+      if (r.re.test(line)) {
+        findings.push({ rule: r.rule, message: r.message, line: i + 1 });
+      }
+    }
+  }
+  return findings;
+}
+
+// src/registry/signature.ts
+import { createHash, timingSafeEqual } from "crypto";
+import { readFileSync as readFileSync3, existsSync } from "fs";
+import { join as join3 } from "path";
+function sha256RelaxJsonWithoutSignatureHex(jsonPath) {
+  try {
+    const raw = readFileSync3(jsonPath, "utf8");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object") return { ok: false, reason: "Invalid JSON" };
+    if ("registrySignature" in parsed) delete parsed.registrySignature;
+    const canonical = JSON.stringify(parsed, null, 2);
+    const digest = createHash("sha256").update(canonical, "utf8").digest("hex");
+    return { ok: true, digest };
+  } catch (e) {
+    return { ok: false, reason: e?.message ?? "Failed to hash relax.json" };
+  }
+}
+function verifyRegistrySignature(pkgDir, sig) {
+  if (!sig) return { ok: false, reason: "Missing registrySignature" };
+  if (sig.alg !== "sha256") return { ok: false, reason: `Unsupported signature alg: ${sig.alg}` };
+  const jsonPath = join3(pkgDir, "relax.json");
+  if (!existsSync(jsonPath)) return { ok: false, reason: "Missing relax.json" };
+  const digestRes = sha256RelaxJsonWithoutSignatureHex(jsonPath);
+  if (!digestRes.ok) return { ok: false, reason: digestRes.reason };
+  const digest = digestRes.digest;
+  try {
+    const a = Buffer.from(digest, "hex");
+    const b = Buffer.from(sig.digest, "hex");
+    if (a.length !== b.length) return { ok: false, reason: "Digest length mismatch" };
+    if (!timingSafeEqual(a, b)) return { ok: false, reason: "Digest mismatch" };
+    return { ok: true };
+  } catch {
+    return { ok: false, reason: "Invalid digest encoding" };
+  }
+}
+
+// src/registry/installer.ts
+function trustStatePath(registryRoot) {
+  return join4(registryRoot, ".trust.json");
+}
+function readTrustState(registryRoot) {
+  const p = trustStatePath(registryRoot);
+  try {
+    if (!existsSync2(p)) return { trusted: {} };
+    const raw = readFileSync4(p, "utf8");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || typeof parsed.trusted !== "object") return { trusted: {} };
+    return parsed;
+  } catch {
+    return { trusted: {} };
+  }
+}
+function writeTrustState(registryRoot, state) {
+  const p = trustStatePath(registryRoot);
+  writeFileSync(p, JSON.stringify(state, null, 2) + "\n");
+}
+function isInteractive() {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+async function promptYesNo(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return await new Promise((resolve2) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      const a = String(answer ?? "").trim().toLowerCase();
+      resolve2(a === "y" || a === "yes");
+    });
+  });
+}
+function formatPermissions(perms) {
+  if (!perms) return [];
+  const lines = [];
+  const fsRead = perms.fs?.read?.length ? perms.fs.read.join(", ") : null;
+  const fsWrite = perms.fs?.write?.length ? perms.fs.write.join(", ") : null;
+  if (fsRead) lines.push(`- fs.read: ${fsRead}`);
+  if (fsWrite) lines.push(`- fs.write: ${fsWrite}`);
+  if (perms.network?.outbound === true) lines.push("- network.outbound: true");
+  if (perms.process?.spawn === true) lines.push("- process.spawn: true");
+  return lines;
+}
+function installPackage(pkgSpecifier, projectRoot = process.cwd()) {
+  const warnings = [];
+  const registryRoot = getRegistryRoot(projectRoot);
+  mkdirSync(registryRoot, { recursive: true });
+  const isFile = pkgSpecifier.startsWith("file:");
+  if (!isFile) {
+    throw new Error(
+      `Only file: installs are supported right now (deterministic, offline). Got: ${pkgSpecifier}`
+    );
+  }
+  const srcDir = pkgSpecifier.slice("file:".length);
+  const manifest = readRelaxJson(srcDir);
+  const trust = normalizeTrustLevel(manifest.trust);
+  const policy = trustPolicy(trust);
+  if (trust === "verified") {
+    const sig = verifyRegistrySignature(srcDir, manifest.registrySignature);
+    if (!sig.ok) {
+      throw new Error(`Refusing verified package: signature check failed (${sig.reason})`);
+    }
+  }
+  const destDir = getInstalledPackageDir(manifest.name, projectRoot);
+  rmSync(destDir, { recursive: true, force: true });
+  mkdirSync(destDir, { recursive: true });
+  writeFileSync(join4(destDir, "relax.json"), readFileSync4(join4(srcDir, "relax.json")));
+  for (const exp of manifest.exports) {
+    const srcPath = join4(srcDir, exp.source);
+    const dstPath = join4(destDir, exp.source);
+    mkdirSync(join4(dstPath, ".."), { recursive: true });
+    if (!existsSync2(srcPath)) {
+      throw new Error(`Missing export source: ${srcPath}`);
+    }
+    const findings = staticScanNativeSource(srcPath);
+    for (const f of findings) {
+      warnings.push(`${exp.source}:${f.line ?? "?"} ${f.rule}: ${f.message}`);
+    }
+    writeFileSync(dstPath, readFileSync4(srcPath));
+  }
+  return { pkg: manifest.name, dir: destDir, warnings, trust };
+}
+async function installPackageEnforcingTrust(pkgSpecifier, projectRoot = process.cwd(), options) {
+  const registryRoot = getRegistryRoot(projectRoot);
+  mkdirSync(registryRoot, { recursive: true });
+  if (!pkgSpecifier.startsWith("file:")) {
+    throw new Error(
+      `Only file: installs are supported right now (deterministic, offline). Got: ${pkgSpecifier}`
+    );
+  }
+  const srcDir = pkgSpecifier.slice("file:".length);
+  const manifest = readRelaxJson(srcDir);
+  const trust = normalizeTrustLevel(manifest.trust);
+  const policy = trustPolicy(trust);
+  const state = readTrustState(registryRoot);
+  const key = `${manifest.name}@${manifest.version}`;
+  const known = state.trusted[key];
+  const permissionLines = formatPermissions(manifest.permissions);
+  const hasElevatedPerms = permissionLines.length > 0;
+  if (trust === "verified") {
+    const sig = verifyRegistrySignature(srcDir, manifest.registrySignature);
+    if (!sig.ok) {
+      throw new Error(`Refusing verified package: signature check failed (${sig.reason})`);
+    }
+  }
+  if (policy.requireConfirm && !known) {
+    const lines = [];
+    lines.push(`Installing community package ${manifest.name}@${manifest.version}`);
+    lines.push(`Trust: ${trust}`);
+    if (hasElevatedPerms) {
+      lines.push("Requested permissions:");
+      lines.push(...permissionLines);
+    } else {
+      lines.push("Requested permissions: (none)");
+    }
+    lines.push("This will compile and run native code on your machine.");
+    if (options?.yes) {
+      throw new Error("Community package install requires confirmation (re-run without --yes or mark as trusted).");
+    }
+    if (!isInteractive()) {
+      throw new Error("Community package install requires an interactive terminal.");
+    }
+    console.warn(lines.join("\n"));
+    const ok = await promptYesNo("Proceed? (y/N) ");
+    if (!ok) {
+      throw new Error("Aborted");
+    }
+    state.trusted[key] = { trust, at: Date.now() };
+    writeTrustState(registryRoot, state);
+  }
+  if (!policy.allowPermissions && hasElevatedPerms) {
+    throw new Error(
+      `Refusing community package with declared permissions. Move to 'local' trust or get it verified.`
+    );
+  }
+  const res = installPackage(pkgSpecifier, projectRoot);
+  if (!state.trusted[key]) {
+    state.trusted[key] = { trust, at: Date.now() };
+    writeTrustState(registryRoot, state);
+  }
+  if (policy.warnOnInstall && res.warnings.length) {
+    console.warn(`
+Static scan warnings (${res.warnings.length}):`);
+  }
+  return res;
+}
+function removePackage(pkg, projectRoot = process.cwd()) {
+  const destDir = getInstalledPackageDir(pkg, projectRoot);
+  rmSync(destDir, { recursive: true, force: true });
+}
+function listPackages(projectRoot = process.cwd()) {
+  const root = getRegistryRoot(projectRoot);
+  if (!existsSync2(root)) return [];
+  return readdirSync(root, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name).sort();
+}
+function updateIndex(projectRoot = process.cwd()) {
+  const root = getRegistryRoot(projectRoot);
+  if (!existsSync2(root)) return;
+  const pkgs = listPackages(projectRoot);
+  writeFileSync(join4(root, ".index"), pkgs.join("\n") + (pkgs.length ? "\n" : ""));
+}
+
+// src/nativeTestHarness.ts
+import { readdirSync as readdirSync2, existsSync as existsSync3, readFileSync as readFileSync5 } from "fs";
+import { extname, join as join5 } from "path";
+var NATIVE_EXTS = /* @__PURE__ */ new Set([".c", ".cpp", ".cc", ".cxx", ".rs"]);
+function isNativeFile(p) {
+  return NATIVE_EXTS.has(extname(p));
+}
+function discoverNativeTestFiles(rootDir) {
+  const out = [];
+  function walk(dir) {
+    for (const ent of readdirSync2(dir, { withFileTypes: true })) {
+      const p = join5(dir, ent.name);
+      if (ent.isDirectory()) walk(p);
+      else if (ent.isFile() && isNativeFile(p)) out.push(p);
+    }
+  }
+  if (!existsSync3(rootDir)) return [];
+  walk(rootDir);
+  out.sort((a, b) => {
+    const at = /_test\./.test(a) ? 0 : 1;
+    const bt = /_test\./.test(b) ? 0 : 1;
+    return at - bt || a.localeCompare(b);
+  });
+  return out;
+}
+function discoverNativeTestsFromFile(sourcePath) {
+  const src = readFileSync5(sourcePath, "utf8");
+  const lines = src.split(/\r?\n/);
+  const out = [];
+  const re = /^(?:\s*)(const\s+char\s*\*|int)\s+(test_[A-Za-z0-9_]+)\s*\(/;
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(re);
+    if (!m) continue;
+    const ret = m[1];
+    const name = m[2];
+    const kind = /^int\b/.test(ret) ? "int" : "cstring";
+    out.push({ name, sourcePath, line: i + 1, kind });
+  }
+  if (out.length) return out;
+  const language = detectLanguage(sourcePath);
+  const bindings = parseNativeSource(sourcePath, language);
+  const tests = [];
+  for (const [name, fn] of Object.entries(bindings.functions ?? {})) {
+    if (!name.startsWith("test_")) continue;
+    const ret = fn.returns;
+    const kind = ret === "int" || ret === "uint" || ret === "long" || ret === "size_t" ? "int" : "cstring";
+    tests.push({
+      name,
+      sourcePath,
+      line: fn.sourceLine,
+      kind
+    });
+  }
+  return tests;
+}
+function discoverNativeTests(rootDir) {
+  const files = discoverNativeTestFiles(rootDir);
+  const all = [];
+  for (const f of files) {
+    all.push(...discoverNativeTestsFromFile(f));
+  }
+  return all;
+}
+function formatLocation(sourcePath, line) {
+  if (!line) return sourcePath;
+  return `${sourcePath}:${line}`;
+}
+function formatNativeTestResults(results) {
+  const lines = [];
+  for (const r of results) {
+    if (r.ok) {
+      lines.push(`\u2713 ${r.name}`);
+    } else {
+      const loc = formatLocation(r.sourcePath, r.line);
+      const msg = r.message ? ` (${r.message})` : "";
+      lines.push(`\u2717 ${r.name}${msg}`);
+      lines.push(`  at ${loc}`);
+    }
+  }
+  const passed = results.filter((r) => r.ok).length;
+  const failed = results.length - passed;
+  lines.push("");
+  lines.push(`${passed} passed, ${failed} failed`);
+  return lines.join("\n");
+}
+async function runNativeTests(rootDir, opts) {
+  const isolation = opts?.isolation ?? "in-process";
+  const tests = discoverNativeTests(rootDir);
+  if (!tests.length) {
+    return { results: [], exitCode: 0 };
+  }
+  const { c, rust, platform } = detectCompilers();
+  const byFile = /* @__PURE__ */ new Map();
+  for (const t of tests) {
+    const arr = byFile.get(t.sourcePath) ?? [];
+    arr.push(t);
+    byFile.set(t.sourcePath, arr);
+  }
+  const results = [];
+  for (const [sourcePath, cases] of byFile) {
+    const language = detectLanguage(sourcePath);
+    const compiler = language === "rust" ? rust : c;
+    if (!compiler) throw new Error(`No compiler for ${language}`);
+    const compileRes = compileWithCache(compiler, platform, {
+      sourcePath,
+      outDir: ".cache/native"
+    });
+    let api;
+    if (isolation === "in-process") {
+      const bindings = parseNativeSource(sourcePath, language);
+      api = loadFfi(compileRes.outputPath, bindings);
+    } else {
+      const synth = {
+        functions: Object.fromEntries(
+          cases.map((tc) => [
+            tc.name,
+            {
+              name: tc.name,
+              // Note: mapType supports "char*" (and "cstring" used to), but
+              // some environments/version combos reject "cstring" when sent
+              // across worker/process boundaries. Use a stable alias.
+              returns: tc.kind === "int" ? "int" : "char*",
+              args: [],
+              mode: "sync",
+              cost: "low"
+            }
+          ])
+        )
+      };
+      const { mod } = await loadNativeWithBindings(sourcePath, {
+        isolation,
+        mutateBindings(bindings) {
+          bindings.functions = synth.functions;
+        }
+      });
+      api = mod;
+    }
+    for (const tc of cases) {
+      const fn = api[tc.name];
+      if (typeof fn !== "function") {
+        results.push({
+          name: tc.name,
+          ok: false,
+          message: `Function not found: ${tc.name}`,
+          sourcePath: tc.sourcePath,
+          line: tc.line,
+          durationMs: 0
+        });
+        continue;
+      }
+      const start = process.hrtime.bigint();
+      let ok = false;
+      let message;
+      try {
+        const out = fn();
+        const awaited = out instanceof Promise ? await out : out;
+        if (tc.kind === "int") {
+          ok = Number(awaited) === 0;
+          if (!ok) message = `returned ${String(awaited)}`;
+        } else {
+          ok = awaited == null || String(awaited).length === 0;
+          if (!ok) message = String(awaited);
+        }
+      } catch (err) {
+        ok = false;
+        message = err?.message ?? String(err);
+      }
+      const end = process.hrtime.bigint();
+      const durationMs = Number(end - start) / 1e6;
+      results.push({
+        name: tc.name,
+        ok,
+        message,
+        sourcePath: tc.sourcePath,
+        line: tc.line,
+        durationMs
+      });
+    }
+  }
+  const failed = results.some((r) => !r.ok);
+  return { results, exitCode: failed ? 1 : 0 };
+}
+function getSourceLine(sourcePath, line) {
+  if (!line) return null;
+  try {
+    const src = readFileSync5(sourcePath, "utf8");
+    const lines = src.split(/\r?\n/);
+    return lines[line - 1] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+// src/benchmark.ts
+function isTraceEnabled() {
+  return process.env.RELAXNATIVE_TRACE === "1";
+}
+function trace(...args) {
+  if (!isTraceEnabled()) return;
+  console.log("[relaxnative:trace]", ...args);
+}
+function nowNs() {
+  return process.hrtime.bigint();
+}
+function nsToMs(ns) {
+  return Number(ns) / 1e6;
+}
+function assertSafeRun(iterations) {
+  if (iterations > 2e6) {
+    throw new Error(
+      `Refusing to run benchmark with iterations=${iterations} (cap=2,000,000). Pass a smaller value.`
+    );
+  }
+}
+async function benchmarkJsFunction(name, fn, opts) {
+  const iterations = opts?.iterations ?? 1e5;
+  const warmup = opts?.warmup ?? Math.min(1e4, Math.max(100, Math.floor(iterations * 0.05)));
+  assertSafeRun(iterations);
+  const args = Array.isArray(opts?.args) ? opts.args : fn.length === 0 ? [] : [1, 2];
+  for (let i = 0; i < warmup; i++) {
+    const out = fn(...args);
+    if (out instanceof Promise) await out;
+  }
+  const latencies = [];
+  const startAll = nowNs();
+  for (let i = 0; i < iterations; i++) {
+    const t0 = nowNs();
+    const out = fn(...args);
+    if (out instanceof Promise) await out;
+    const t1 = nowNs();
+    latencies.push(nsToMs(t1 - t0));
+  }
+  const endAll = nowNs();
+  const totalMs = nsToMs(endAll - startAll);
+  let min = Infinity;
+  let max = -Infinity;
+  let sum = 0;
+  for (const l of latencies) {
+    if (l < min) min = l;
+    if (l > max) max = l;
+    sum += l;
+  }
+  const avg = sum / latencies.length;
+  const callsPerSec = iterations / (totalMs / 1e3);
+  return {
+    name,
+    iterations,
+    warmup,
+    callsPerSec,
+    avgLatencyMs: avg,
+    minLatencyMs: min,
+    maxLatencyMs: max
+  };
+}
+function pickArgs(fnName, jsArity, callerArgs) {
+  if (Array.isArray(callerArgs)) return callerArgs;
+  return jsArity === 0 ? [] : [1, 2];
+}
+function mapArgsForNative(fnName, args, opts) {
+  const keepAlive = [];
+  if (fnName === "sum_u8") {
+    const buf = args[0];
+    const n = args[1];
+    if (buf && typeof n === "number" && ArrayBuffer.isView(buf)) {
+      const nb = alloc(buf.byteLength);
+      nb.write(new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength));
+      keepAlive.push(nb);
+      return { args: [nb, n], keepAlive };
+    }
+  }
+  if (fnName === "dot_f64") {
+    const a = args[0];
+    const b = args[1];
+    const n = args[2];
+    if (a && b && typeof n === "number" && ArrayBuffer.isView(a) && ArrayBuffer.isView(b)) {
+      const na = alloc(a.byteLength);
+      na.write(new Uint8Array(a.buffer, a.byteOffset, a.byteLength));
+      const nb = alloc(b.byteLength);
+      nb.write(new Uint8Array(b.buffer, b.byteOffset, b.byteLength));
+      keepAlive.push(na, nb);
+      return { args: [na.f64(0, n), nb.f64(0, n), n], keepAlive };
+    }
+  }
+  if (fnName === "saxpy_f64") {
+    const a = args[0];
+    const x = args[1];
+    const y = args[2];
+    const n = args[3];
+    if (typeof a === "number" && x && y && typeof n === "number" && ArrayBuffer.isView(x) && ArrayBuffer.isView(y)) {
+      const nx = alloc(x.byteLength);
+      nx.write(new Uint8Array(x.buffer, x.byteOffset, x.byteLength));
+      const ny = alloc(y.byteLength);
+      ny.write(new Uint8Array(y.buffer, y.byteOffset, y.byteLength));
+      keepAlive.push(nx, ny);
+      return { args: [a, nx.address, ny.address, n], keepAlive };
+    }
+  }
+  if (fnName === "matmul_f32") {
+    const A = args[0];
+    const B = args[1];
+    const C = args[2];
+    const M = args[3];
+    const K = args[4];
+    const N = args[5];
+    if (A && B && C && typeof M === "number" && typeof K === "number" && typeof N === "number" && ArrayBuffer.isView(A) && ArrayBuffer.isView(B) && ArrayBuffer.isView(C)) {
+      const nA = alloc(A.byteLength);
+      nA.write(new Uint8Array(A.buffer, A.byteOffset, A.byteLength));
+      const nB = alloc(B.byteLength);
+      nB.write(new Uint8Array(B.buffer, B.byteOffset, B.byteLength));
+      const nC = alloc(C.byteLength);
+      nC.write(new Uint8Array(C.buffer, C.byteOffset, C.byteLength));
+      keepAlive.push(nA, nB, nC);
+      return {
+        args: [
+          nA.f32(0, M * K),
+          nB.f32(0, K * N),
+          nC.f32(0, M * N),
+          M,
+          K,
+          N
+        ],
+        keepAlive
+      };
+    }
+  }
+  if (fnName === "xor_u8") {
+    const a = args[0];
+    const b = args[1];
+    const out = args[2];
+    const n = args[3];
+    if (a && b && out && typeof n === "number" && ArrayBuffer.isView(a) && ArrayBuffer.isView(b) && ArrayBuffer.isView(out)) {
+      if (opts?.isolation === "worker") {
+        return { args: [a, b, out, n], keepAlive };
+      }
+      const na = alloc(a.byteLength);
+      na.write(new Uint8Array(a.buffer, a.byteOffset, a.byteLength));
+      const nb = alloc(b.byteLength);
+      nb.write(new Uint8Array(b.buffer, b.byteOffset, b.byteLength));
+      const no = alloc(out.byteLength);
+      keepAlive.push(na, nb, no);
+      return { args: [na.address, nb.address, no.address, n], keepAlive };
+    }
+  }
+  if (fnName === "crc32_u8") {
+    const buf = args[0];
+    const n = args[1];
+    if (buf && typeof n === "number" && ArrayBuffer.isView(buf)) {
+      if (opts?.isolation === "worker") {
+        return { args: [buf, n], keepAlive };
+      }
+      const nb = alloc(buf.byteLength);
+      nb.write(new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength));
+      keepAlive.push(nb);
+      return { args: [nb.address, n], keepAlive };
+    }
+  }
+  if (fnName === "histogram_u8") {
+    const buf = args[0];
+    const n = args[1];
+    const out = args[2];
+    if (buf && out && typeof n === "number" && ArrayBuffer.isView(buf) && ArrayBuffer.isView(out)) {
+      if (opts?.isolation === "worker") {
+        return { args: [buf, n, out], keepAlive };
+      }
+      const nb = alloc(buf.byteLength);
+      nb.write(new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength));
+      const no = alloc(out.byteLength);
+      keepAlive.push(nb, no);
+      return { args: [nb.address, n, no.address], keepAlive };
+    }
+  }
+  return { args, keepAlive };
+}
+async function benchmarkNativeFunction(nativePath, fnName, opts) {
+  const iterations = opts?.iterations ?? 1e5;
+  const warmup = opts?.warmup ?? Math.min(1e4, Math.max(100, Math.floor(iterations * 0.05)));
+  const mode = opts?.mode ?? "sync";
+  assertSafeRun(iterations);
+  const pointerHeavy = /* @__PURE__ */ new Set([
+    "sum_u8",
+    "dot_f64",
+    "saxpy_f64",
+    "matmul_f32",
+    "xor_u8",
+    "crc32_u8",
+    "histogram_u8"
+  ]);
+  const isolation = mode === "worker" ? "worker" : pointerHeavy.has(fnName) ? "worker" : "in-process";
+  trace("benchmark loadNative: begin", { nativePath, fnName, isolation });
+  const mod = await loadNative(nativePath, { isolation });
+  trace("benchmark loadNative: done", { nativePath, fnName });
+  const fn = mod?.[fnName];
+  if (typeof fn !== "function") {
+    throw new Error(`Function not found: ${fnName}`);
+  }
+  const isMaybeAsync = isolation === "worker";
+  const { args, keepAlive } = mapArgsForNative(
+    fnName,
+    pickArgs(fnName, fn.length, opts?.args),
+    { isolation }
+  );
+  trace("benchmark args ready", {
+    fnName,
+    argc: args.length,
+    argTypes: args.map(
+      (a) => a == null ? "null" : ArrayBuffer.isView(a) ? a.constructor?.name : typeof a
+    ),
+    keepAlive: keepAlive.length
+  });
+  trace("benchmark warmup: begin", { fnName, warmup });
+  for (let i = 0; i < warmup; i++) {
+    const out = fn(...args);
+    if (isMaybeAsync || out instanceof Promise) await out;
+  }
+  trace("benchmark warmup: done", { fnName });
+  const latencies = [];
+  const startAll = nowNs();
+  trace("benchmark loop: begin", { fnName, iterations });
+  for (let i = 0; i < iterations; i++) {
+    const t0 = nowNs();
+    const out = fn(...args);
+    if (isMaybeAsync || out instanceof Promise) await out;
+    const t1 = nowNs();
+    latencies.push(nsToMs(t1 - t0));
+    if (isTraceEnabled() && (i === 0 || i === 1e4 || i === 1e5 || i === iterations - 1)) {
+      trace("benchmark progress", { fnName, i: i + 1 });
+    }
+  }
+  trace("benchmark loop: done", { fnName });
+  void keepAlive;
+  const endAll = nowNs();
+  const totalMs = nsToMs(endAll - startAll);
+  let min = Infinity;
+  let max = -Infinity;
+  let sum = 0;
+  for (const l of latencies) {
+    if (l < min) min = l;
+    if (l > max) max = l;
+    sum += l;
+  }
+  const avg = sum / latencies.length;
+  const callsPerSec = iterations / (totalMs / 1e3);
+  return {
+    fnName,
+    mode,
+    iterations,
+    warmup,
+    callsPerSec,
+    avgLatencyMs: avg,
+    minLatencyMs: min,
+    maxLatencyMs: max
+  };
+}
+async function benchmarkCompareSyncVsWorker(nativePath, fnName, opts) {
+  const sync = await benchmarkNativeFunction(nativePath, fnName, {
+    ...opts,
+    mode: "sync"
+  });
+  const worker = await benchmarkNativeFunction(nativePath, fnName, {
+    ...opts,
+    mode: "worker"
+  });
+  return { sync, worker };
+}
+async function benchmarkCompareTraditionalVsRelaxnative(nativePath, fnName, opts) {
+  const baseline = opts?.baseline ?? (() => {
+    throw new Error(
+      `Missing JS baseline for fn=${fnName}. Provide opts.baseline (a JS function) and opts.args (a JSON-serializable args array) to compare.`
+    );
+  })();
+  const baselineName = opts?.baselineName ?? "traditional-js";
+  const traditional = await benchmarkJsFunction(baselineName, baseline, {
+    iterations: opts?.iterations,
+    warmup: opts?.warmup,
+    args: pickArgs(fnName, baseline.length, opts?.args)
+  });
+  const relaxnative = await benchmarkCompareSyncVsWorker(nativePath, fnName, opts);
+  return { traditional, relaxnative };
+}
+function formatBenchmarkResult(r) {
+  const f = (n) => Number.isFinite(n) ? n.toFixed(3) : String(n);
+  return [
+    `${r.fnName} (${r.mode})`,
+    `  iterations: ${r.iterations} (warmup ${r.warmup})`,
+    `  calls/sec:   ${f(r.callsPerSec)}`,
+    `  avg ms:      ${f(r.avgLatencyMs)}`,
+    `  min ms:      ${f(r.minLatencyMs)}`,
+    `  max ms:      ${f(r.maxLatencyMs)}`
+  ].join("\n");
+}
+function formatBenchmarkCompare(res) {
+  return [formatBenchmarkResult(res.sync), "", formatBenchmarkResult(res.worker)].join("\n");
+}
+function formatBenchmarkTraditionalCompare(res) {
+  const f = (n) => Number.isFinite(n) ? n.toFixed(3) : String(n);
+  const t = res.traditional;
+  const speedup = (relax) => {
+    if (!Number.isFinite(relax) || !Number.isFinite(t.callsPerSec) || t.callsPerSec <= 0) return "n/a";
+    const s = relax / t.callsPerSec;
+    return s.toFixed(2) + "x";
+  };
+  const traditionalBlock = [
+    `${t.name} (baseline)`,
+    `  iterations: ${t.iterations} (warmup ${t.warmup})`,
+    `  calls/sec:   ${f(t.callsPerSec)}`,
+    `  avg ms:      ${f(t.avgLatencyMs)}`,
+    `  min ms:      ${f(t.minLatencyMs)}`,
+    `  max ms:      ${f(t.maxLatencyMs)}`
+  ].join("\n");
+  const summary = [
+    "Speedup vs baseline (higher is better)",
+    `  sync:   ${speedup(res.relaxnative.sync.callsPerSec)}`,
+    `  worker: ${speedup(res.relaxnative.worker.callsPerSec)}`
+  ].join("\n");
+  return [
+    traditionalBlock,
+    "",
+    summary,
+    "",
+    formatBenchmarkResult(res.relaxnative.sync),
+    "",
+    formatBenchmarkResult(res.relaxnative.worker)
+  ].join("\n");
+}
+
+export {
+  getProjectRoot,
+  getRegistryRoot,
+  getInstalledPackageDir,
+  resolveRegistryImport,
+  normalizeTrustLevel,
+  trustPolicy,
+  readRelaxJson,
+  installPackage,
+  installPackageEnforcingTrust,
+  removePackage,
+  listPackages,
+  updateIndex,
+  discoverNativeTestFiles,
+  discoverNativeTestsFromFile,
+  discoverNativeTests,
+  formatNativeTestResults,
+  runNativeTests,
+  getSourceLine,
+  benchmarkJsFunction,
+  benchmarkNativeFunction,
+  benchmarkCompareSyncVsWorker,
+  benchmarkCompareTraditionalVsRelaxnative,
+  formatBenchmarkResult,
+  formatBenchmarkCompare,
+  formatBenchmarkTraditionalCompare
+};