relaxnative 0.1.4 → 0.1.6

package/dist/chunk-5OGJZMKW.js

@@ -0,0 +1,847 @@
+import {
+  formatBindingSignature,
+  logDebug,
+  traceDebug,
+  traceInfo,
+  wrapFunctions
+} from "./chunk-HBO7F7P4.js";
+import {
+  InvalidFreeError,
+  MemoryError,
+  NativeBuffer,
+  NativePointer,
+  NullPointerError,
+  UseAfterFreeError,
+  loadFfi
+} from "./chunk-GKVUUIR2.js";
+import {
+  __export
+} from "./chunk-MLKGABMK.js";
+
+// src/compiler/detectPlatform.ts
+function detectPlatform() {
+  const platform = process.platform;
+  const arch = process.arch;
+  return {
+    platform,
+    arch,
+    isWindows: platform === "win32",
+    isMac: platform === "darwin",
+    isLinux: platform === "linux"
+  };
+}
+
+// src/compiler/detectCCompiler.ts
+import { execFileSync } from "child_process";
+
+// src/utils/which.ts
+import { accessSync, constants } from "fs";
+import { delimiter } from "path";
+function which(cmd) {
+  const paths = process.env.PATH?.split(delimiter) ?? [];
+  for (const p of paths) {
+    const full = `${p}/${cmd}`;
+    try {
+      accessSync(full, constants.X_OK);
+      return full;
+    } catch {
+    }
+  }
+  return null;
+}
+
+// src/compiler/detectCCompiler.ts
+function getVersion(path) {
+  try {
+    return execFileSync(path, ["--version"], { encoding: "utf8" }).split("\n")[0].trim();
+  } catch {
+    return "unknown";
+  }
+}
+function detectCCompiler() {
+  const candidates = [
+    process.env.CC,
+    "clang",
+    "gcc",
+    "cc",
+    "cl"
+  ].filter(Boolean);
+  for (const name of candidates) {
+    const resolved = name.includes("/") ? name : which(name);
+    if (!resolved) continue;
+    const version = getVersion(resolved);
+    return {
+      kind: "c",
+      path: resolved,
+      version,
+      vendor: resolved.includes("clang") ? "clang" : resolved.includes("gcc") ? "gcc" : resolved.includes("cl") ? "msvc" : "unknown"
+    };
+  }
+  throw new Error("No C compiler found (gcc/clang/cl)");
+}
+
+// src/compiler/detectRustCompiler.ts
+import { execFileSync as execFileSync2 } from "child_process";
+function detectRustCompiler() {
+  const rustc = process.env.RUSTC ?? which("rustc");
+  if (!rustc) return null;
+  const version = execFileSync2(rustc, ["--version"], {
+    encoding: "utf8"
+  }).trim();
+  return {
+    kind: "rust",
+    path: rustc,
+    version,
+    vendor: "rust"
+  };
+}
+
+// src/compiler/sanityCheck.ts
+import { execFileSync as execFileSync3 } from "child_process";
+import { writeFileSync, mkdtempSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+function sanityCheckC(compiler) {
+  const dir = mkdtempSync(join(tmpdir(), "relaxnative-"));
+  const source = join(dir, "test.c");
+  const output = join(dir, "test");
+  writeFileSync(source, "int main(){return 0;}");
+  try {
+    execFileSync3(
+      compiler.path,
+      compiler.vendor === "msvc" ? [source] : [source, "-o", output],
+      { stdio: "ignore" }
+    );
+  } catch (err) {
+    throw new Error(
+      `C compiler failed sanity check: ${compiler.path}`
+    );
+  }
+}
+
+// src/compiler/detect.ts
+function detectCompilers() {
+  const platform = detectPlatform();
+  const c = detectCCompiler();
+  sanityCheckC(c);
+  const rust = detectRustCompiler();
+  return {
+    platform,
+    c,
+    rust
+  };
+}
+
+// src/cache/cachePaths.ts
+import { homedir } from "os";
+import { join as join2 } from "path";
+function homeDir() {
+  return process.env.HOME ?? homedir();
+}
+function getCacheRoot() {
+  return join2(homeDir(), ".relaxnative", "cache");
+}
+function getCacheEntry(hash) {
+  return join2(getCacheRoot(), hash);
+}
+
+// src/compiler/compileNative.ts
+import { execFileSync as execFileSync4 } from "child_process";
+import { mkdirSync } from "fs";
+
+// src/compiler/buildCommand.ts
+import { basename } from "path";
+
+// src/compiler/detectLanguage.ts
+function detectLanguage(filePath) {
+  if (filePath.endsWith(".c")) return "c";
+  if (filePath.endsWith(".cpp") || filePath.endsWith(".cc") || filePath.endsWith(".cxx"))
+    return "cpp";
+  if (filePath.endsWith(".rs")) return "rust";
+  throw new Error(`Unsupported native file: ${filePath}`);
+}
+
+// src/compiler/outputNaming.ts
+function getSharedLibName(baseName, platform) {
+  if (platform.isWindows) return `${baseName}.dll`;
+  if (platform.isMac) return `lib${baseName}.dylib`;
+  return `lib${baseName}.so`;
+}
+
+// src/compiler/buildCommand.ts
+function buildCompileCommand(compiler, platform, request) {
+  const language = detectLanguage(request.sourcePath);
+  const baseName = basename(request.sourcePath).split(".")[0];
+  const outputName = getSharedLibName(baseName, platform);
+  const outputPath = `${request.outDir}/${outputName}`;
+  const userFlags = request.flags ?? [];
+  const sources = [request.sourcePath, ...request.sources ?? []];
+  const includePaths = request.includePaths ?? [];
+  const libraryPaths = request.libraryPaths ?? [];
+  const libraries = request.libraries ?? [];
+  const includeFlags = compiler.vendor === "msvc" ? includePaths.map((p) => `/I${p}`) : includePaths.flatMap((p) => ["-I", p]);
+  const libPathFlags = compiler.vendor === "msvc" ? libraryPaths.map((p) => `/LIBPATH:${p}`) : libraryPaths.flatMap((p) => ["-L", p]);
+  const libFlags = compiler.vendor === "msvc" ? libraries.map((l) => `${l}.lib`) : libraries.flatMap((l) => ["-l", l]);
+  const flags = [...includeFlags, ...libPathFlags, ...libFlags, ...userFlags];
+  let command = [];
+  if (language === "c" || language === "cpp") {
+    if (compiler.vendor === "msvc") {
+      command = [
+        ...sources,
+        "/LD",
+        `/Fe:${outputPath}`,
+        ...flags
+      ];
+    } else {
+      command = [
+        ...sources,
+        "-shared",
+        "-fPIC",
+        "-o",
+        outputPath,
+        ...flags
+      ];
+    }
+  }
+  if (language === "rust") {
+    command = [
+      request.sourcePath,
+      "--crate-type",
+      "cdylib",
+      "-O",
+      "-o",
+      outputPath,
+      ...flags
+    ];
+  }
+  return {
+    language,
+    outputPath,
+    command
+  };
+}
+
+// src/compiler/compileNative.ts
+function parseDiagnostics(text) {
+  const out = [];
+  const lines = String(text ?? "").split(/\r?\n/);
+  const ccRe = /^(.*?):(\d+):(\d+):\s*(warning|error|note):\s*(.*)$/;
+  for (const l of lines) {
+    const m = l.match(ccRe);
+    if (m) {
+      out.push({
+        file: m[1],
+        line: Number(m[2]),
+        col: Number(m[3]),
+        severity: m[4],
+        message: m[5],
+        raw: l
+      });
+      continue;
+    }
+    const m2 = l.match(/^\s*-->\s*(.*?):(\d+):(\d+)\s*$/);
+    if (m2) {
+      const prev = out[out.length - 1];
+      if (prev && !prev.file) {
+        prev.file = m2[1];
+        prev.line = Number(m2[2]);
+        prev.col = Number(m2[3]);
+        prev.raw += `
+${l}`;
+      } else {
+        out.push({ severity: "error", file: m2[1], line: Number(m2[2]), col: Number(m2[3]), message: "", raw: l });
+      }
+      continue;
+    }
+    const m3 = l.match(/^(error|warning|note)(?:\[[^\]]+\])?:\s*(.*)$/);
+    if (m3) {
+      out.push({ severity: m3[1], message: m3[2], raw: l });
+      continue;
+    }
+  }
+  return out;
+}
+function formatDiagnostics(diags) {
+  if (!diags.length) return "";
+  const lines = [];
+  for (const d of diags) {
+    const loc = d.file && d.line != null ? `${d.file}:${d.line}:${d.col ?? 0}` : d.file ?? "";
+    const head = loc ? `${loc} - ${d.severity}` : d.severity;
+    const msg = d.message ? `: ${d.message}` : "";
+    lines.push(`${head}${msg}`);
+  }
+  return lines.join("\n");
+}
+function compileNative(compiler, platform, request) {
+  mkdirSync(request.outDir, { recursive: true });
+  const result = buildCompileCommand(compiler, platform, request);
+  try {
+    logDebug("compile", { compiler: compiler.path, cmd: result.command, sourcePath: request.sourcePath });
+    execFileSync4(compiler.path, result.command, {
+      stdio: "inherit"
+    });
+  } catch (err) {
+    try {
+      const out = execFileSync4(compiler.path, result.command, {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"]
+      });
+      logDebug("compile recovered on retry", { sourcePath: request.sourcePath, outLen: out?.length ?? 0 });
+    } catch (err2) {
+      const stdout = String(err2?.stdout ?? "");
+      const stderr = String(err2?.stderr ?? "");
+      const diags = parseDiagnostics([stderr, stdout].filter(Boolean).join("\n"));
+      const formatted = formatDiagnostics(diags);
+      const details = formatted ? `
+
+${formatted}` : stderr || stdout ? `
+
+${(stderr || stdout).trim()}` : "";
+      throw new Error(`Native compilation failed for ${request.sourcePath}${details}`);
+    }
+    throw new Error(`Native compilation failed for ${request.sourcePath}`);
+  }
+  return result;
+}
+
+// src/compiler/compileWithCache.ts
+import { mkdirSync as mkdirSync3 } from "fs";
+
+// src/cache/hash.ts
+import { readFileSync } from "fs";
+import crypto from "crypto";
+function computeHash(input) {
+  const source = readFileSync(input.sourcePath, "utf8");
+  const hash = crypto.createHash("sha256");
+  hash.update(source);
+  hash.update(input.compiler.path);
+  hash.update(input.compiler.version);
+  hash.update(input.flags.join(" "));
+  hash.update(input.platform);
+  return hash.digest("hex");
+}
+
+// src/cache/cacheManager.ts
+import { existsSync, mkdirSync as mkdirSync2, writeFileSync as writeFileSync2, readFileSync as readFileSync2 } from "fs";
+import { join as join3 } from "path";
+function cacheExists(hash) {
+  return existsSync(getCacheEntry(hash));
+}
+function loadCacheEntry(hash) {
+  const metaPath = join3(getCacheEntry(hash), "meta.json");
+  const raw = readFileSync2(metaPath, "utf8");
+  const entry = JSON.parse(raw);
+  try {
+    const next = {
+      ...entry,
+      lastAccessAt: Date.now()
+    };
+    writeFileSync2(metaPath, JSON.stringify(next, null, 2));
+    return next;
+  } catch {
+    return entry;
+  }
+}
+function saveCacheEntry(entry) {
+  const dir = getCacheEntry(entry.hash);
+  mkdirSync2(dir, { recursive: true });
+  writeFileSync2(
+    join3(dir, "meta.json"),
+    JSON.stringify(entry, null, 2)
+  );
+}
+
+// src/compiler/compileWithCache.ts
+function compileWithCache(compiler, platform, request) {
+  const flags = request.flags ?? [];
+  const hash = computeHash({
+    sourcePath: request.sourcePath,
+    compiler,
+    flags,
+    platform: `${platform.platform}-${platform.arch}`
+  });
+  if (cacheExists(hash)) {
+    logDebug("cache hit", { hash, sourcePath: request.sourcePath });
+    const entry = loadCacheEntry(hash);
+    return {
+      language: compiler.kind === "rust" ? "rust" : "c",
+      outputPath: entry.outputPath,
+      command: []
+    };
+  }
+  logDebug("cache miss", { hash, sourcePath: request.sourcePath });
+  const cacheDir = getCacheEntry(hash);
+  mkdirSync3(cacheDir, { recursive: true });
+  const result = compileNative(compiler, platform, {
+    ...request,
+    outDir: cacheDir
+  });
+  saveCacheEntry({
+    hash,
+    sourcePath: request.sourcePath,
+    outputPath: result.outputPath,
+    compilerPath: compiler.path,
+    compilerVersion: compiler.version,
+    flags,
+    platform: `${platform.platform}-${platform.arch}`,
+    createdAt: Date.now(),
+    lastAccessAt: Date.now()
+  });
+  return result;
+}
+
+// src/dev/hotReload.ts
+import { watch } from "fs";
+import { dirname } from "path";
+
+// src/parser/index.ts
+import { readFileSync as readFileSync3 } from "fs";
+
+// src/parser/loadParser.ts
+import Parser from "tree-sitter";
+import C from "tree-sitter-c";
+import CPP from "tree-sitter-cpp";
+import Rust from "tree-sitter-rust";
+function createParser(lang) {
+  const parser = new Parser();
+  if (lang === "c") parser.setLanguage(C);
+  if (lang === "cpp") parser.setLanguage(CPP);
+  if (lang === "rust") parser.setLanguage(Rust);
+  return parser;
+}
+
+// src/parser/parseC.ts
+function parseCFunctions(tree) {
+  const functions = [];
+  const varargs = [];
+  function visit(node) {
+    if (node.type === "function_definition") {
+      const declarator = node.childForFieldName("declarator");
+      const typeNode = node.childForFieldName("type");
+      if (!declarator || !typeNode) return;
+      const nameNode = declarator.childForFieldName("declarator");
+      const name = nameNode?.text ?? declarator.text?.split("(")[0]?.trim();
+      if (!name) return;
+      const paramsNode = declarator.childForFieldName("parameters");
+      const hasVarargs = (paramsNode?.children ?? []).some(
+        (c) => c?.type === "variadic_parameter" || c?.type === "..." || c?.text === "..."
+      );
+      if (hasVarargs) {
+        varargs.push({ name, line: node.startPosition.row + 1 });
+        return;
+      }
+      const params = paramsNode?.children?.filter((c) => c.type === "parameter_declaration").map((p) => ({
+        name: p.childForFieldName("declarator")?.text ?? "arg",
+        type: mapCType(
+          // For pointer params, tree-sitter C often stores `*` in the declarator,
+          // not in the `type` field. Combine both so we can detect pointers.
+          `${p.childForFieldName("type")?.text ?? ""}${p.childForFieldName("declarator")?.text ?? ""}`
+        )
+      })) ?? [];
+      functions.push({
+        name,
+        returnType: mapCType(typeNode.text),
+        params,
+        sourceLine: node.startPosition.row + 1
+      });
+    }
+    for (const child of node.children ?? []) visit(child);
+  }
+  visit(tree.rootNode);
+  if (varargs.length) {
+    const msg = varargs.map((v) => `- ${v.name} (line ${v.line})`).join("\n");
+    throw new Error(
+      `Unsupported native API: variadic functions (varargs, ",") are not supported.
+
+Relaxnative can't safely infer varargs ABI/calling conventions from source.
+Please write a fixed-signature wrapper function in C/C++ and export that instead.
+
+Found varargs functions:
+${msg}`
+    );
+  }
+  return functions;
+}
+function mapCType(type) {
+  if (!type) return "unknown";
+  const t = type.replace(/\s+/g, " ").trim();
+  if (/\bconst\s+char\s*\*/.test(t)) return "cstring";
+  if (/\bchar\b/.test(t) && t.includes("*")) return "buffer";
+  if (/\b(u?int8_t|unsigned\s+char|uint8_t)\b/.test(t) && t.includes("*")) return "buffer";
+  if (t.includes("*")) {
+    if (t.includes("**")) {
+      if (/\bdouble\b/.test(t)) return "pointer<pointer<double>>";
+      if (/\bfloat\b/.test(t)) return "pointer<pointer<float>>";
+      if (/\buint8_t\b/.test(t)) return "pointer<pointer<uint8_t>>";
+      if (/\bint8_t\b/.test(t)) return "pointer<pointer<int8_t>>";
+      if (/\buint16_t\b/.test(t)) return "pointer<pointer<uint16_t>>";
+      if (/\bint16_t\b/.test(t)) return "pointer<pointer<int16_t>>";
+      if (/\buint32_t\b/.test(t)) return "pointer<pointer<uint32_t>>";
+      if (/\bint32_t\b/.test(t)) return "pointer<pointer<int32_t>>";
+      if (/\buint64_t\b/.test(t)) return "pointer<pointer<uint64_t>>";
+      if (/\bint64_t\b/.test(t)) return "pointer<pointer<int64_t>>";
+      if (/\bunsigned\s+int\b/.test(t)) return "pointer<pointer<uint>>";
+      if (/\bint\b/.test(t)) return "pointer<pointer<int>>";
+      if (/\blong\b/.test(t)) return "pointer<pointer<long>>";
+      if (/\bchar\b/.test(t)) return "pointer<pointer<char>>";
+      return "pointer<pointer<void>>";
+    }
+    if (/\bdouble\b/.test(t)) return "pointer<double>";
+    if (/\bfloat\b/.test(t)) return "pointer<float>";
+    if (/\buint8_t\b/.test(t)) return "pointer<uint8_t>";
+    if (/\bint8_t\b/.test(t)) return "pointer<int8_t>";
+    if (/\buint16_t\b/.test(t)) return "pointer<uint16_t>";
+    if (/\bint16_t\b/.test(t)) return "pointer<int16_t>";
+    if (/\buint32_t\b/.test(t)) return "pointer<uint32_t>";
+    if (/\bint32_t\b/.test(t)) return "pointer<int32_t>";
+    if (/\buint64_t\b/.test(t)) return "pointer<uint64_t>";
+    if (/\bint64_t\b/.test(t)) return "pointer<int64_t>";
+    if (/\bint\b/.test(t)) return "pointer<int>";
+  }
+  if (/\buint8_t\b/.test(t)) return "uint8_t";
+  if (/\bint8_t\b/.test(t)) return "int8_t";
+  if (/\buint16_t\b/.test(t)) return "uint16_t";
+  if (/\bint16_t\b/.test(t)) return "int16_t";
+  if (/\buint32_t\b/.test(t)) return "uint32_t";
+  if (/\bint32_t\b/.test(t)) return "int32_t";
+  if (/\buint64_t\b/.test(t)) return "uint64_t";
+  if (/\bint64_t\b/.test(t)) return "int64_t";
+  if (/\bunsigned\s+int\b/.test(t)) return "uint";
+  if (/\bsize_t\b/.test(t)) return "size_t";
+  if (t.includes("int")) return "int";
+  if (t.includes("long")) return "long";
+  if (t.includes("float")) return "float";
+  if (t.includes("double")) return "double";
+  if (t.includes("char") && t.includes("*")) return "buffer";
+  if (t.includes("*")) return "pointer";
+  if (t.includes("void")) return "void";
+  return "unknown";
+}
+
+// src/parser/parseRust.ts
+function parseRustFunctions(tree) {
+  const functions = [];
+  function visit(node) {
+    if (node.type === "function_item" && node.text.includes("pub extern")) {
+      const nameNode = node.childForFieldName("name");
+      const paramsNode = node.childForFieldName("parameters");
+      const returnNode = node.childForFieldName("return_type");
+      const params = paramsNode?.children?.filter((c) => c.type === "parameter").map((p) => ({
+        name: p.childForFieldName("pattern")?.text ?? "arg",
+        type: mapRustType(p.childForFieldName("type")?.text)
+      })) ?? [];
+      functions.push({
+        name: nameNode?.text ?? "unknown",
+        returnType: mapRustType(returnNode?.text),
+        params,
+        sourceLine: node.startPosition.row + 1
+      });
+    }
+    for (const child of node.children ?? []) visit(child);
+  }
+  visit(tree.rootNode);
+  return functions;
+}
+function mapRustType(type) {
+  if (!type) return "void";
+  const t = type.replace(/\s+/g, " ").trim();
+  if (/\bi32\b/.test(t)) return "int";
+  if (/\bi64\b/.test(t)) return "long";
+  if (/\bu32\b/.test(t)) return "uint32_t";
+  if (/\bu64\b/.test(t)) return "uint64_t";
+  if (/\bf32\b/.test(t)) return "float";
+  if (/\bf64\b/.test(t)) return "double";
+  if (/\*const\s+i8\b/.test(t) || /\*mut\s+i8\b/.test(t)) return "char*";
+  if (t.includes("*")) {
+    if (/\*const\s+f64\b/.test(t) || /\*mut\s+f64\b/.test(t)) return "pointer<double>";
+    if (/\*const\s+f32\b/.test(t) || /\*mut\s+f32\b/.test(t)) return "pointer<float>";
+    if (/\*const\s+i32\b/.test(t) || /\*mut\s+i32\b/.test(t)) return "pointer<int>";
+    if (/\*const\s+u32\b/.test(t) || /\*mut\s+u32\b/.test(t)) return "pointer<uint32_t>";
+    if (/\*const\s+u8\b/.test(t) || /\*mut\s+u8\b/.test(t)) return "pointer<uint8_t>";
+    if (/\*const\s+i8\b/.test(t) || /\*mut\s+i8\b/.test(t)) return "pointer<int8_t>";
+    return "pointer";
+  }
+  return "unknown";
+}
+
+// src/parser/validateFunctions.ts
+function validateFunctions(funcs) {
+  return funcs.filter((fn) => {
+    if (fn.returnType === "unknown") return false;
+    if (fn.params.some((p) => p.type === "unknown")) return false;
+    return true;
+  });
+}
+
+// src/parser/generateBindings.ts
+function generateBindings(functions) {
+  const entries = functions.map((f) => [
+    f.name,
+    {
+      name: f.name,
+      returns: f.returnType,
+      args: f.params.map((p) => p.type),
+      // optional execution hints
+      mode: f.annotations?.mode,
+      cost: f.annotations?.cost
+    }
+  ]);
+  return {
+    functions: Object.fromEntries(entries)
+  };
+}
+
+// src/parser/index.ts
+function parseAnnotationsForFunctions(source, funcs) {
+  const lines = source.split(/\r?\n/);
+  for (const fn of funcs) {
+    if (!fn.sourceLine) continue;
+    const idx = Math.max(0, fn.sourceLine - 1);
+    const start = Math.max(0, idx - 3);
+    const window = lines.slice(start, idx).join("\n");
+    const mode = /@async\b/.test(window) ? "async" : /@sync\b/.test(window) ? "sync" : void 0;
+    const costMatch = window.match(/@cost\s+(low|medium|high)\b/);
+    const cost = costMatch?.[1] ?? void 0;
+    if (mode || cost) {
+      fn.annotations = { ...fn.annotations ?? {}, mode, cost };
+    }
+  }
+  return funcs;
+}
+function parseNativeSource(filePath, lang) {
+  const source = readFileSync3(filePath, "utf8");
+  const parser = createParser(lang);
+  const tree = parser.parse(source);
+  const rawFunctions = lang === "rust" ? parseRustFunctions(tree) : parseCFunctions(tree);
+  const annotated = parseAnnotationsForFunctions(source, rawFunctions);
+  const validFunctions = validateFunctions(annotated);
+  return generateBindings(validFunctions);
+}
+
+// src/dev/hotReload.ts
+function log(msg) {
+  console.log(msg);
+}
+function fingerprintBindings(bindings) {
+  const entries = Object.entries(bindings?.functions ?? {}).map(([k, v]) => {
+    return `${k}:${v.returns}(${(v.args ?? []).join(",")})`;
+  });
+  entries.sort();
+  return entries.join("|");
+}
+async function loadNativeDevHot(sourcePath, opts) {
+  const enabled = process.env.RELAXNATIVE_DEV === "1";
+  if (!enabled) {
+    throw new Error("Hot reload is only available when RELAXNATIVE_DEV=1");
+  }
+  const { c, rust, platform } = detectCompilers();
+  const isolation = opts?.isolation ?? "worker";
+  let current = null;
+  const buildOnce = () => {
+    const language = detectLanguage(sourcePath);
+    const compiler = language === "rust" ? rust : c;
+    if (!compiler) throw new Error(`No compiler for ${language}`);
+    const t0 = process.hrtime.bigint();
+    const compileRes = compileWithCache(compiler, platform, {
+      sourcePath,
+      outDir: ".cache/native"
+    });
+    const bindings = parseNativeSource(sourcePath, language);
+    const api = loadFfi(compileRes.outputPath, bindings);
+    const mod = wrapFunctions(api, compileRes.outputPath, bindings, { isolation });
+    const abi = fingerprintBindings(bindings);
+    const t1 = process.hrtime.bigint();
+    const durationMs = Number(t1 - t0) / 1e6;
+    return { libPath: compileRes.outputPath, bindings, abi, api, mod, durationMs };
+  };
+  const first = buildOnce();
+  current = { ...first, mod: first.mod };
+  const stable = new Proxy(
+    {},
+    {
+      get(_t, prop) {
+        if (prop === "__isHotReloadProxy") return true;
+        if (prop === "then") return void 0;
+        const target = current?.mod;
+        if (!target) return void 0;
+        return target[prop];
+      },
+      ownKeys() {
+        return Reflect.ownKeys(current?.mod ?? {});
+      },
+      getOwnPropertyDescriptor(_t, prop) {
+        return Object.getOwnPropertyDescriptor(current?.mod ?? {}, prop);
+      }
+    }
+  );
+  const watcher = watch(dirname(sourcePath), { persistent: false }, (event, filename) => {
+    if (!filename) return;
+    if (!String(filename).endsWith(sourcePath.split("/").pop() ?? "")) return;
+    try {
+      const next = buildOnce();
+      if (current && next.abi !== current.abi) {
+        log(`[relaxnative] ABI change detected in ${sourcePath}; reload requires restart`);
+        return;
+      }
+      current = { ...next, mod: next.mod };
+      const ms = next.durationMs;
+      log(`[relaxnative] Recompiled ${sourcePath} (${ms.toFixed(0)}ms)`);
+      opts?.onReload?.({ sourcePath, durationMs: ms });
+    } catch (err) {
+      log(`[relaxnative] Hot reload failed for ${sourcePath}: ${err?.message ?? String(err)}`);
+    }
+  });
+  return {
+    mod: stable,
+    close() {
+      watcher.close();
+    }
+  };
+}
+
+// src/loader.ts
+async function buildNative(sourcePath, options) {
+  traceInfo("loadNative.build.begin", { sourcePath });
+  const { c, rust, platform } = detectCompilers();
+  const language = detectLanguage(sourcePath);
+  const compiler = language === "rust" ? rust : c;
+  if (!compiler) {
+    traceDebug("loadNative.build.noCompiler", { sourcePath, language });
+    throw new Error(`No compiler for ${language}`);
+  }
+  const compileResult = compileWithCache(compiler, platform, {
+    sourcePath,
+    outDir: ".cache/native",
+    ...options?.build ?? {}
+  });
+  traceDebug("loadNative.build.compiled", {
+    sourcePath,
+    language,
+    outputPath: compileResult.outputPath
+  });
+  const bindings = parseNativeSource(sourcePath, language);
+  const funcs = Object.values(bindings?.functions ?? {});
+  traceDebug("loadNative.bindings", {
+    sourcePath,
+    functionCount: funcs.length,
+    functions: funcs.map((b) => ({
+      name: b?.name,
+      mode: b?.mode,
+      cost: b?.cost,
+      signature: formatBindingSignature(b)
+    }))
+  });
+  const config = options?.config;
+  if (config?.functionMode) {
+    for (const [name, mode] of Object.entries(config.functionMode)) {
+      if (bindings.functions?.[name]) {
+        bindings.functions[name] = {
+          ...bindings.functions[name],
+          mode
+        };
+      }
+    }
+  }
+  if (config?.defaultMode) {
+    for (const [name, binding] of Object.entries(bindings.functions ?? {})) {
+      if (!binding.mode) {
+        bindings.functions[name] = { ...binding, mode: config.defaultMode };
+      }
+    }
+  }
+  globalThis.__bindings = bindings;
+  const api = loadFfi(compileResult.outputPath, bindings);
+  traceInfo("loadNative.build.done", {
+    sourcePath,
+    libPath: compileResult.outputPath,
+    exports: Object.keys(api ?? {})
+  });
+  return { libPath: compileResult.outputPath, bindings, api };
+}
+async function loadNative(sourcePath, options) {
+  traceInfo("loadNative.begin", { sourcePath, isolation: options?.isolation ?? "worker" });
+  if (process.env.RELAXNATIVE_DEV === "1") {
+    if (options?.config) {
+      throw new Error("RELAXNATIVE_DEV=1: loadNative() does not support config overrides yet");
+    }
+    const handle = await loadNativeDevHot(sourcePath, { isolation: options?.isolation });
+    return handle.mod;
+  }
+  const { libPath, bindings, api } = await buildNative(sourcePath, options);
+  const isolation = options?.isolation ?? "worker";
+  const mod = wrapFunctions(api, libPath, bindings, { isolation });
+  traceInfo("loadNative.done", { sourcePath, isolation, functions: Object.keys(bindings?.functions ?? {}) });
+  return mod;
+}
+async function loadNativeWithBindings(sourcePath, options) {
+  const { libPath, bindings, api } = await buildNative(sourcePath, options);
+  if (options?.mutateBindings) {
+    options.mutateBindings(bindings);
+  }
+  const isolation = options?.isolation ?? "worker";
+  const mod = wrapFunctions(api, libPath, bindings, { isolation });
+  return { mod, bindings };
+}
+
+// src/memory/nativeMemory.ts
+import koffi from "koffi";
+function allocRaw(size) {
+  if (!Number.isInteger(size) || size <= 0) {
+    throw new TypeError(`native.alloc(size): size must be a positive integer, got ${size}`);
+  }
+  const handle = koffi.alloc("char", size);
+  const ab = koffi.view(handle, size);
+  const view = new Uint8Array(ab);
+  return { handle, view };
+}
+function freeRaw(ptr) {
+  koffi.free(ptr);
+}
+
+// src/memory/index.ts
+var memory_exports = {};
+__export(memory_exports, {
+  InvalidFreeError: () => InvalidFreeError,
+  MemoryError: () => MemoryError,
+  NativeBuffer: () => NativeBuffer,
+  NativePointer: () => NativePointer,
+  NullPointerError: () => NullPointerError,
+  UseAfterFreeError: () => UseAfterFreeError,
+  alloc: () => alloc,
+  allocRaw: () => allocRaw,
+  free: () => free,
+  freeRaw: () => freeRaw
+});
+function alloc(size, opts) {
+  const allocation = allocRaw(size);
+  return new NativeBuffer(allocation, { ownership: "js", autoFree: opts?.autoFree });
+}
+function free(ptr) {
+  if (NativeBuffer.isNativeBuffer(ptr)) {
+    ptr.free();
+    return;
+  }
+  if (NativePointer.isNativePointer(ptr)) {
+    throw new InvalidFreeError(
+      `native.free(ptr): cannot free a raw NativePointer (unknown allocator). Use a NativeBuffer allocated by native.alloc().`
+    );
+  }
+  throw new TypeError("native.free(ptr): expected NativeBuffer or NativePointer");
+}
+
+export {
+  detectCompilers,
+  getCacheRoot,
+  detectLanguage,
+  compileNative,
+  compileWithCache,
+  parseNativeSource,
+  loadNativeDevHot,
+  loadNative,
+  loadNativeWithBindings,
+  allocRaw,
+  freeRaw,
+  alloc,
+  free,
+  memory_exports
+};