relaxnative 0.1.0-beta.1

package/dist/index.d.ts

@@ -0,0 +1,407 @@
+type ExecutionMode = 'sync' | 'async';
+type RelaxConfig = {
+    /**
+     * Force execution mode by function name (exact match).
+     * Example: { heavy: 'async', add: 'sync' }
+     */
+    functionMode?: Record<string, ExecutionMode>;
+    /**
+     * Default mode when no annotation/config provided.
+     * Keeping default as 'sync' for low-latency trivial calls.
+     */
+    defaultMode?: ExecutionMode;
+};
+type IsolationMode = 'in-process' | 'worker' | 'process';
+declare function loadNative(sourcePath: string, options?: {
+    config?: RelaxConfig;
+    isolation?: IsolationMode;
+}): Promise<any>;
+/**
+ * Advanced API: returns both the wrapped module and the computed bindings.
+ * Useful for registry loaders to attach safety metadata.
+ */
+declare function loadNativeWithBindings(sourcePath: string, options?: {
+    config?: RelaxConfig;
+    isolation?: IsolationMode;
+    mutateBindings?: (bindings: any) => void;
+}): Promise<{
+    mod: any;
+    bindings: any;
+}>;
+
+type Ownership = 'js' | 'native' | 'borrowed';
+declare class MemoryError extends Error {
+    name: string;
+}
+declare class UseAfterFreeError extends MemoryError {
+    name: string;
+}
+declare class InvalidFreeError extends MemoryError {
+    name: string;
+}
+declare class NullPointerError extends MemoryError {
+    name: string;
+}
+
+declare const kBrand$1: unique symbol;
+declare class NativeBuffer {
+    readonly [kBrand$1] = true;
+    private _handle;
+    private _view;
+    private _freed;
+    readonly ownership: Ownership;
+    constructor(allocation: {
+        handle: any;
+        view: Uint8Array;
+    }, opts?: {
+        ownership?: Ownership;
+        autoFree?: boolean;
+    });
+    get address(): number;
+    get size(): number;
+    get freed(): boolean;
+    assertAlive(): void;
+    toUint8Array(): Uint8Array;
+    /**
+     * Create a bounds-checked DataView into this buffer.
+     *
+     * Tip: prefer the typed view helpers (u32(), f64(), etc.) when possible.
+     */
+    dataView(offset?: number, length?: number): DataView;
+    private _typed;
+    u8(offset?: number, length?: number): Uint8Array<ArrayBuffer>;
+    i8(offset?: number, length?: number): Int8Array<ArrayBuffer>;
+    u16(offset?: number, length?: number): Uint16Array<ArrayBuffer>;
+    i16(offset?: number, length?: number): Int16Array<ArrayBuffer>;
+    u32(offset?: number, length?: number): Uint32Array<ArrayBuffer>;
+    i32(offset?: number, length?: number): Int32Array<ArrayBuffer>;
+    f32(offset?: number, length?: number): Float32Array<ArrayBuffer>;
+    f64(offset?: number, length?: number): Float64Array<ArrayBuffer>;
+    write(src: Uint8Array, offset?: number): void;
+    free(): void;
+    toJSON(): {
+        address: number;
+        size: number;
+        ownership: Ownership;
+    };
+    static isNativeBuffer(v: any): v is NativeBuffer;
+    /**
+     * Return the koffi allocation handle.
+     *
+     * Important: passing raw numeric addresses to koffi is not reliably supported
+     * across platforms/Node versions and can segfault. The handle returned by
+     * `koffi.alloc()` is the safe thing to pass back into FFI calls.
+     */
+    toKoffiPointer(): any;
+}
+
+declare const kBrand: unique symbol;
+declare class NativePointer {
+    readonly [kBrand] = true;
+    /** Opaque native address (number). */
+    readonly address: number;
+    /** Size in bytes when known (0 means unknown). */
+    readonly size: number;
+    /** Ownership of the pointee memory. */
+    readonly ownership: Ownership;
+    private _freed;
+    constructor(opts: {
+        address: number;
+        size?: number;
+        ownership?: Ownership;
+    });
+    get freed(): boolean;
+    /**
+     * Marks this pointer as freed (used internally by NativeBuffer).
+     * This does *not* free underlying memory.
+     */
+    _markFreed(): void;
+    assertAlive(): void;
+    /**
+     * Convert to the koffi pointer value.
+     *
+    * Note: numeric-address pointers are inherently less safe than passing a
+    * koffi External handle (like NativeBuffer does). Use NativePointer for
+    * borrowed/opaque pointers returned by native code.
+     */
+    toKoffiPointer(): number;
+    static isNativePointer(v: any): v is NativePointer;
+    /**
+     * Convenience for koffi type declarations.
+     * Example: lib.func('foo', 'int', [NativePointer.koffiType()])
+     */
+    static koffiType(): any;
+}
+
+/**
+ * Low-level process memory primitives.
+ *
+ * Notes:
+ * - This uses koffi's built-in allocator so we don't need a bespoke native shim.
+ * - Returned pointers are *opaque* JS numbers (addresses). Wrap them in
+ *   NativePointer/NativeBuffer for safety checks + ownership tracking.
+ */
+type NativeAddress = number;
+type RawAllocation = {
+    handle: any;
+    view: Uint8Array;
+};
+declare function allocRaw(size: number): RawAllocation;
+declare function freeRaw(ptr: unknown): void;
+
+/**
+ * High-level user-facing API.
+ */
+declare function alloc(size: number, opts?: {
+    autoFree?: boolean;
+}): NativeBuffer;
+declare function free(ptr: NativeBuffer | NativePointer): void;
+
+type index_InvalidFreeError = InvalidFreeError;
+declare const index_InvalidFreeError: typeof InvalidFreeError;
+type index_MemoryError = MemoryError;
+declare const index_MemoryError: typeof MemoryError;
+type index_NativeAddress = NativeAddress;
+type index_NativeBuffer = NativeBuffer;
+declare const index_NativeBuffer: typeof NativeBuffer;
+type index_NativePointer = NativePointer;
+declare const index_NativePointer: typeof NativePointer;
+type index_NullPointerError = NullPointerError;
+declare const index_NullPointerError: typeof NullPointerError;
+type index_Ownership = Ownership;
+type index_RawAllocation = RawAllocation;
+type index_UseAfterFreeError = UseAfterFreeError;
+declare const index_UseAfterFreeError: typeof UseAfterFreeError;
+declare const index_alloc: typeof alloc;
+declare const index_allocRaw: typeof allocRaw;
+declare const index_free: typeof free;
+declare const index_freeRaw: typeof freeRaw;
+declare namespace index {
+  export { index_InvalidFreeError as InvalidFreeError, index_MemoryError as MemoryError, type index_NativeAddress as NativeAddress, index_NativeBuffer as NativeBuffer, index_NativePointer as NativePointer, index_NullPointerError as NullPointerError, type index_Ownership as Ownership, type index_RawAllocation as RawAllocation, index_UseAfterFreeError as UseAfterFreeError, index_alloc as alloc, index_allocRaw as allocRaw, index_free as free, index_freeRaw as freeRaw };
+}
+
+declare function getProjectRoot(cwd?: string): string;
+declare function getRegistryRoot(projectRoot?: string): string;
+declare function getInstalledPackageDir(pkg: string, projectRoot?: string): string;
+declare function resolveRegistryImport(specifier: string, projectRoot?: string): string | null;
+
+type RelaxPermissions = {
+    fs?: {
+        read?: string[];
+        write?: string[];
+    };
+    network?: {
+        outbound?: boolean;
+    };
+    process?: {
+        spawn?: boolean;
+    };
+};
+type RelaxExport = {
+    /** source file relative to the package root */
+    source: string;
+    /** optional name for JS default export (defaults to package name) */
+    name?: string;
+};
+type RelaxJson = {
+    name: string;
+    version: string;
+    /** Trust level of the package (affects UX + defaults). */
+    trust?: 'local' | 'community' | 'verified';
+    /** Required for verified packages (provided by registry, validated at install). */
+    registrySignature?: {
+        alg: 'sha256';
+        digest: string;
+    };
+    language?: 'c' | 'cpp' | 'rust';
+    exports: RelaxExport[];
+    /** compiler flags applied during compilation */
+    flags?: string[];
+    /** security permissions requested by this package */
+    permissions?: RelaxPermissions;
+    /** runtime limits (best-effort) */
+    limits?: {
+        /** max wall clock time per call in ms (process isolation enforces by killing helper) */
+        timeoutMs?: number;
+        /** best-effort soft cap for native heap in bytes (enforced only in process isolation) */
+        memoryBytes?: number;
+    };
+    /** execution hints by function name */
+    functionMode?: Record<string, 'sync' | 'async'>;
+    /** Default isolation preference for this package (installer may enforce stricter). */
+    defaultIsolation?: 'in-process' | 'worker' | 'process';
+    /** Default execution mode for functions when not specified; most useful for async-only APIs. */
+    defaultExecutionMode?: 'sync' | 'async';
+};
+
+declare function readRelaxJson(pkgDir: string): RelaxJson;
+
+type TrustLevel = 'local' | 'community' | 'verified';
+
+type InstallResult = {
+    pkg: string;
+    dir: string;
+    warnings: string[];
+    trust: TrustLevel;
+};
+declare function installPackage(pkgSpecifier: string, projectRoot?: string): InstallResult;
+type InstallOptions = {
+    /** If true, skip interactive prompt (still refuses community unless previously trusted). */
+    yes?: boolean;
+};
+declare function installPackageEnforcingTrust(pkgSpecifier: string, projectRoot?: string, options?: InstallOptions): Promise<InstallResult>;
+declare function removePackage(pkg: string, projectRoot?: string): void;
+declare function listPackages(projectRoot?: string): string[];
+declare function updateIndex(projectRoot?: string): void;
+
+declare function loadRegistry(pkg: string, projectRoot?: string): Promise<any>;
+
+type NativeTestKind = 'int' | 'cstring';
+type NativeTestCase = {
+    name: string;
+    sourcePath: string;
+    line?: number;
+    kind: NativeTestKind;
+};
+type NativeTestResult = {
+    name: string;
+    ok: boolean;
+    message?: string;
+    sourcePath: string;
+    line?: number;
+    durationMs: number;
+};
+declare function discoverNativeTestFiles(rootDir: string): string[];
+declare function discoverNativeTestsFromFile(sourcePath: string): NativeTestCase[];
+declare function discoverNativeTests(rootDir: string): NativeTestCase[];
+declare function formatNativeTestResults(results: NativeTestResult[]): string;
+declare function runNativeTests(rootDir: string, opts?: {
+    isolation?: 'in-process' | 'worker' | 'process';
+}): Promise<{
+    results: NativeTestResult[];
+    exitCode: number;
+}>;
+declare function getSourceLine(sourcePath: string, line?: number): string | null;
+
+type BenchmarkOptions = {
+    iterations?: number;
+    warmup?: number;
+    mode?: 'sync' | 'worker';
+    /**
+     * Arguments to pass to the benchmarked function.
+     * If omitted, we try a small default based on arity (0 args => [], else => [1,2]).
+     */
+    args?: any[];
+    json?: boolean;
+    confirmExpensive?: boolean;
+};
+type BenchmarkResult = {
+    fnName: string;
+    mode: 'sync' | 'worker';
+    iterations: number;
+    warmup: number;
+    callsPerSec: number;
+    avgLatencyMs: number;
+    minLatencyMs: number;
+    maxLatencyMs: number;
+};
+type TraditionalBenchmarkResult = {
+    name: string;
+    iterations: number;
+    warmup: number;
+    callsPerSec: number;
+    avgLatencyMs: number;
+    minLatencyMs: number;
+    maxLatencyMs: number;
+};
+declare function benchmarkJsFunction(name: string, fn: (...args: any[]) => any, opts?: {
+    iterations?: number;
+    warmup?: number;
+    args?: any[];
+}): Promise<TraditionalBenchmarkResult>;
+declare function benchmarkNativeFunction(nativePath: string, fnName: string, opts?: BenchmarkOptions): Promise<BenchmarkResult>;
+declare function benchmarkCompareSyncVsWorker(nativePath: string, fnName: string, opts?: Omit<BenchmarkOptions, 'mode'>): Promise<{
+    sync: BenchmarkResult;
+    worker: BenchmarkResult;
+}>;
+declare function benchmarkCompareTraditionalVsRelaxnative(nativePath: string, fnName: string, opts?: Omit<BenchmarkOptions, 'mode'> & {
+    /**
+     * JS baseline implementation to compare against.
+     * If omitted, we provide a tiny baseline only for a couple of known demo functions.
+     */
+    baseline?: (...args: any[]) => any;
+    baselineName?: string;
+}): Promise<{
+    traditional: TraditionalBenchmarkResult;
+    relaxnative: {
+        sync: BenchmarkResult;
+        worker: BenchmarkResult;
+    };
+}>;
+declare function formatBenchmarkResult(r: BenchmarkResult): string;
+declare function formatBenchmarkCompare(res: {
+    sync: BenchmarkResult;
+    worker: BenchmarkResult;
+}): string;
+declare function formatBenchmarkTraditionalCompare(res: {
+    traditional: TraditionalBenchmarkResult;
+    relaxnative: {
+        sync: BenchmarkResult;
+        worker: BenchmarkResult;
+    };
+}): string;
+
+type HotReloadOptions = {
+    isolation?: 'in-process' | 'worker' | 'process';
+    onReload?: (info: {
+        sourcePath: string;
+        durationMs: number;
+    }) => void;
+};
+type HotReloadHandle = {
+    /** current module; stable identity, updated on reload */
+    mod: any;
+    close(): void;
+};
+declare function loadNativeDevHot(sourcePath: string, opts?: HotReloadOptions): Promise<HotReloadHandle>;
+
+type PlatformInfo = {
+    platform: NodeJS.Platform;
+    arch: string;
+    isWindows: boolean;
+    isMac: boolean;
+    isLinux: boolean;
+};
+
+declare function detectCompilers(): {
+    platform: PlatformInfo;
+    c: CompilerInfo;
+    rust: any;
+};
+
+type CompilerKind = 'c' | 'cpp' | 'rust';
+type CompilerInfo$1 = {
+    kind: CompilerKind;
+    path: string;
+    version: string;
+    vendor?: string;
+};
+
+type NativeLanguage = 'c' | 'cpp' | 'rust';
+
+type CompileRequest = {
+    sourcePath: string;
+    outDir: string;
+    flags?: string[];
+};
+type CompileResult = {
+    language: NativeLanguage;
+    outputPath: string;
+    command: string[];
+};
+
+declare function compileNative(compiler: CompilerInfo$1, platform: PlatformInfo, request: CompileRequest): CompileResult;
+
+declare function compileWithCache(compiler: CompilerInfo$1, platform: PlatformInfo, request: CompileRequest): CompileResult;
+
+export { type BenchmarkOptions, type BenchmarkResult, type ExecutionMode, type HotReloadHandle, type HotReloadOptions, type InstallOptions, type InstallResult, InvalidFreeError, type IsolationMode, MemoryError, type NativeAddress, NativeBuffer, NativePointer, type NativeTestCase, type NativeTestKind, type NativeTestResult, NullPointerError, type Ownership, type RawAllocation, type RelaxConfig, type TraditionalBenchmarkResult, UseAfterFreeError, alloc, allocRaw, benchmarkCompareSyncVsWorker, benchmarkCompareTraditionalVsRelaxnative, benchmarkJsFunction, benchmarkNativeFunction, compileNative, compileWithCache, detectCompilers, discoverNativeTestFiles, discoverNativeTests, discoverNativeTestsFromFile, formatBenchmarkCompare, formatBenchmarkResult, formatBenchmarkTraditionalCompare, formatNativeTestResults, free, freeRaw, getInstalledPackageDir, getProjectRoot, getRegistryRoot, getSourceLine, installPackage, installPackageEnforcingTrust, listPackages, loadNative, loadNativeDevHot, loadNativeWithBindings, loadRegistry, index as native, readRelaxJson, removePackage, resolveRegistryImport, runNativeTests, updateIndex };

package/dist/index.js

@@ -0,0 +1,126 @@
+import {
+  benchmarkCompareSyncVsWorker,
+  benchmarkCompareTraditionalVsRelaxnative,
+  benchmarkJsFunction,
+  benchmarkNativeFunction,
+  discoverNativeTestFiles,
+  discoverNativeTests,
+  discoverNativeTestsFromFile,
+  formatBenchmarkCompare,
+  formatBenchmarkResult,
+  formatBenchmarkTraditionalCompare,
+  formatNativeTestResults,
+  getInstalledPackageDir,
+  getProjectRoot,
+  getRegistryRoot,
+  getSourceLine,
+  installPackage,
+  installPackageEnforcingTrust,
+  listPackages,
+  normalizeTrustLevel,
+  readRelaxJson,
+  removePackage,
+  resolveRegistryImport,
+  runNativeTests,
+  trustPolicy,
+  updateIndex
+} from "./chunk-OVMTFGE7.js";
+import {
+  alloc,
+  allocRaw,
+  compileNative,
+  compileWithCache,
+  detectCompilers,
+  free,
+  freeRaw,
+  loadNative,
+  loadNativeDevHot,
+  loadNativeWithBindings,
+  memory_exports
+} from "./chunk-LFTO3Z7N.js";
+import "./chunk-HDIVY47T.js";
+import {
+  InvalidFreeError,
+  MemoryError,
+  NativeBuffer,
+  NativePointer,
+  NullPointerError,
+  UseAfterFreeError
+} from "./chunk-LLZ4I4OR.js";
+import "./chunk-MLKGABMK.js";
+
+// src/registry/loadRegistry.ts
+import { join } from "path";
+async function loadRegistry(pkg, projectRoot = process.cwd()) {
+  const pkgDir = getInstalledPackageDir(pkg, projectRoot);
+  const manifest = readRelaxJson(pkgDir);
+  const entry = manifest.exports[0];
+  if (!entry?.source) throw new Error(`No exports[0].source for ${pkg}`);
+  const trust = normalizeTrustLevel(manifest.trust);
+  const policy = trustPolicy(trust);
+  const safety = {
+    trust,
+    permissions: manifest.permissions,
+    limits: manifest.limits
+  };
+  const sourcePath = join(pkgDir, entry.source);
+  const { mod } = await loadNativeWithBindings(sourcePath, {
+    isolation: manifest.defaultIsolation ?? policy.defaultIsolation,
+    config: {
+      functionMode: manifest.functionMode,
+      defaultMode: manifest.defaultExecutionMode ?? policy.defaultExecutionMode
+    },
+    mutateBindings(bindings) {
+      bindings.__safety = safety;
+    }
+  });
+  if (process.env.VITEST) {
+    mod.__test_forbidden_fs = () => mod.__call("__test_forbidden_fs");
+    mod.__test_forbidden_net = () => mod.__call("__test_forbidden_net");
+    mod.__test_forbidden_spawn = () => mod.__call("__test_forbidden_spawn");
+  }
+  return mod;
+}
+export {
+  InvalidFreeError,
+  MemoryError,
+  NativeBuffer,
+  NativePointer,
+  NullPointerError,
+  UseAfterFreeError,
+  alloc,
+  allocRaw,
+  benchmarkCompareSyncVsWorker,
+  benchmarkCompareTraditionalVsRelaxnative,
+  benchmarkJsFunction,
+  benchmarkNativeFunction,
+  compileNative,
+  compileWithCache,
+  detectCompilers,
+  discoverNativeTestFiles,
+  discoverNativeTests,
+  discoverNativeTestsFromFile,
+  formatBenchmarkCompare,
+  formatBenchmarkResult,
+  formatBenchmarkTraditionalCompare,
+  formatNativeTestResults,
+  free,
+  freeRaw,
+  getInstalledPackageDir,
+  getProjectRoot,
+  getRegistryRoot,
+  getSourceLine,
+  installPackage,
+  installPackageEnforcingTrust,
+  listPackages,
+  loadNative,
+  loadNativeDevHot,
+  loadNativeWithBindings,
+  loadRegistry,
+  memory_exports as native,
+  readRelaxJson,
+  removePackage,
+  resolveRegistryImport,
+  runNativeTests,
+  updateIndex
+};

package/dist/memory/memory.selftest.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/memory/memory.selftest.js

@@ -0,0 +1,25 @@
+import {
+  alloc,
+  loadNative
+} from "../chunk-LFTO3Z7N.js";
+import "../chunk-HDIVY47T.js";
+import "../chunk-LLZ4I4OR.js";
+import "../chunk-MLKGABMK.js";
+
+// src/memory/memory.selftest.ts
+import { strict as assert } from "assert";
+async function main() {
+  const buf = alloc(16);
+  assert.equal(buf.size, 16);
+  buf.write(new Uint8Array([1, 2, 3, 4]));
+  assert.equal(buf.toUint8Array()[0], 1);
+  const mod = await loadNative("examples/buffer.c");
+  assert.equal(typeof mod.fill_u8, "function");
+  assert.equal(typeof mod.sum_u8, "function");
+  mod.fill_u8(buf, buf.size, 7);
+  const sum = mod.sum_u8(buf, buf.size);
+  assert.equal(sum, 112);
+  buf.free();
+  console.log("memory selftest: ok");
+}
+main();

package/dist/worker/processEntry.d.ts

@@ -0,0 +1,2 @@
+
+export {  }