tricu

lib.js (9715B)

---

 /**
  * lib.js — FFI wrapper around libarboricx.so via koffi.
  *
  * Exports low-level C ABI bindings and high-level helpers.
  */
 
 import { existsSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import koffi from 'koffi';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
 koffi.opaque('arb_ctx_t');
 
 // ── Library discovery ───────────────────────────────────────────────────────
 
 export function findLib() {
   const env = process.env.ARBORICX_LIB;
   if (env) {
     if (existsSync(env)) return env;
     throw new Error(`ARBORICX_LIB set but file not found: ${env}`);
   }
 
   const candidates = [
     resolve(__dirname, 'libarboricx.so'),
     'libarboricx.so',
     './libarboricx.so',
     '/usr/local/lib/libarboricx.so',
     '/usr/lib/libarboricx.so',
   ];
 
   for (const p of candidates) {
     if (existsSync(p)) return p;
   }
 
   throw new Error('libarboricx.so not found. Set ARBORICX_LIB to its full path.');
 }
 
 // ── FFI setup ───────────────────────────────────────────────────────────────
 
 let _lib = null;
 let _libPath = null;
 
 function ensureLib() {
   if (_lib) return _lib;
   const path = findLib();
   _lib = koffi.load(path);
   _libPath = path;
   return _lib;
 }
 
 export function loadLib(path) {
   if (_lib && _libPath === path) return;
   _lib = koffi.load(path);
   _libPath = path;
 }
 
 function getLib() {
   if (_lib) return _lib;
   return ensureLib();
 }
 
 // ── Context lifecycle ───────────────────────────────────────────────────────
 
 export function init(libPath) {
   if (libPath) loadLib(libPath);
   const lib = getLib();
   if (lib.func('uint32_t arb_abi_version(void)')() !== 2) throw new Error('Arboricx ABI v2 required');
   const ctx = lib.func('arb_ctx_t *arboricx_init(void)')();
   if (!ctx) throw new Error('arboricx_init failed');
   return ctx;
 }
 
 export function free(ctx) {
   getLib().func('void arboricx_free(arb_ctx_t *ctx)')(ctx);
 }
 
 // Each handle returned below is owned until release() or context teardown.
 // Handles are always bigint; converting one to Number can lose identity bits.
 function owned(signature, ...args) {
   const out = [0n];
   const declaration = signature.replace(/^uint64_t /, 'int ').replace(/\)$/, ', _Out_ uint64_t *out)');
   const status = getLib().func(declaration)(...args, out);
   if (status !== 0) throw new Error(`${signature.split('(')[0]}: status ${status}`);
   return BigInt(out[0]);
 }
 
 export function retain(ctx, handle) {
   return owned('uint64_t arb_retain(arb_ctx_t *ctx, uint64_t handle)', ctx, handle);
 }
 export function release(ctx, handle) {
   const status = getLib().func('int arb_release(arb_ctx_t *ctx, uint64_t handle)')(ctx, handle);
   if (status !== 0) throw new Error(`arb_release: status ${status}`);
 }
 export function collect(ctx) {
   const status = getLib().func('int arb_collect(arb_ctx_t *ctx)')(ctx);
   if (status !== 0) throw new Error(`arb_collect: status ${status}`);
 }
 
 // ── Bundle loading ──────────────────────────────────────────────────────────
 
 export function loadBundle(ctx, bytes, name) {
   const result = owned('uint64_t arb_load_bundle(arb_ctx_t *ctx, _In_ uint8_t *bytes, size_t len, const char *name)', ctx, bytes, bytes.length, name);
   return result;
 }
 
 export function loadBundleDefault(ctx, bytes) {
   const result = owned('uint64_t arb_load_bundle_default(arb_ctx_t *ctx, _In_ uint8_t *bytes, size_t len)', ctx, bytes, bytes.length);
   return result;
 }
 
 // ── Reduction ───────────────────────────────────────────────────────────────
 
 export function reduce(ctx, root, fuel = 1_000_000_000n) {
   return owned('uint64_t arb_reduce(arb_ctx_t *ctx, uint64_t root, uint64_t fuel)', ctx, root, BigInt(fuel));
 }
 
 // ── Tree construction ───────────────────────────────────────────────────────
 
 export function leaf(ctx) {
   return owned('uint64_t arb_leaf(arb_ctx_t *ctx)', ctx);
 }
 
 export function stem(ctx, child) {
   return owned('uint64_t arb_stem(arb_ctx_t *ctx, uint64_t child)', ctx, child);
 }
 
 export function fork(ctx, left, right) {
   return owned('uint64_t arb_fork(arb_ctx_t *ctx, uint64_t left, uint64_t right)', ctx, left, right);
 }
 
 export function app(ctx, func, arg) {
   return owned('uint64_t arb_app(arb_ctx_t *ctx, uint64_t func, uint64_t arg)', ctx, func, arg);
 }
 
 // ── Codec constructors ──────────────────────────────────────────────────────
 
 export function ofNumber(ctx, n) {
   const big = typeof n === 'bigint' ? n : BigInt(n);
   return owned('uint64_t arb_of_number(arb_ctx_t *ctx, uint64_t n)', ctx, big);
 }
 
 export function ofString(ctx, s) {
   return owned('uint64_t arb_of_string(arb_ctx_t *ctx, const char *s)', ctx, s);
 }
 
 export function ofBytes(ctx, bytes) {
   return owned('uint64_t arb_of_bytes(arb_ctx_t *ctx, _In_ uint8_t *bytes, size_t len)', ctx, bytes, bytes.length);
 }
 
 export function ofList(ctx, items) {
   const arr = new BigUint64Array(items.map(BigInt));
   return owned('uint64_t arb_of_list(arb_ctx_t *ctx, _In_ uint64_t *items, size_t len)', ctx, arr, arr.length);
 }
 
 // ── Codec destructors ───────────────────────────────────────────────────────
 
 export function toNumber(ctx, root) {
   const out = [0];
   const ok = getLib().func('int arb_to_number(arb_ctx_t *ctx, uint64_t root, _Out_ uint64_t *out)')(ctx, root, out);
   if (ok !== 0) throw new Error('arb_to_number failed');
   return typeof out[0] === 'bigint' ? Number(out[0]) : out[0];
 }
 
 export function toString(ctx, root) {
   const ptrOut = [null];
   const lenOut = [0];
   const ok = getLib().func('int arb_to_string(arb_ctx_t *ctx, uint64_t root, _Out_ uint8_t **out_ptr, _Out_ size_t *out_len)')(ctx, root, ptrOut, lenOut);
   if (ok !== 0) throw new Error('arb_to_string failed');
 
   const bytes = koffi.decode(ptrOut[0], 'uint8_t', lenOut[0]);
   const str = Buffer.from(bytes).toString('utf-8');
   getLib().func('void arboricx_free_buf(arb_ctx_t *ctx, uint8_t *ptr, size_t len)')(ctx, ptrOut[0], lenOut[0]);
   return str;
 }
 
 export function toBytes(ctx, root) {
   const ptrOut = [null];
   const lenOut = [0];
   const ok = getLib().func('int arb_to_bytes(arb_ctx_t *ctx, uint64_t root, _Out_ uint8_t **out_ptr, _Out_ size_t *out_len)')(ctx, root, ptrOut, lenOut);
   if (ok !== 0) throw new Error('arb_to_bytes failed');
 
   const bytes = Buffer.from(koffi.decode(ptrOut[0], 'uint8_t', lenOut[0]));
   getLib().func('void arboricx_free_buf(arb_ctx_t *ctx, uint8_t *ptr, size_t len)')(ctx, ptrOut[0], lenOut[0]);
   return bytes;
 }
 
 export function toBool(ctx, root) {
   const out = [0];
   const ok = getLib().func('int arb_to_bool(arb_ctx_t *ctx, uint64_t root, _Out_ int *out)')(ctx, root, out);
   if (ok !== 0) throw new Error('arb_to_bool failed');
   return out[0] !== 0;
 }
 
 // ── Result unwrapping ───────────────────────────────────────────────────────
 
 export function unwrapResult(ctx, root) {
   const outOk = [0];
   const outValue = [0];
   const outRest = [0];
   const ok = getLib().func('int arb_unwrap_result(arb_ctx_t *ctx, uint64_t root, _Out_ int *out_ok, _Out_ uint64_t *out_value, _Out_ uint64_t *out_rest)')(ctx, root, outOk, outValue, outRest);
   if (ok !== 0) throw new Error('arb_unwrap_result failed');
   return { ok: outOk[0] !== 0, value: BigInt(outValue[0]), rest: BigInt(outRest[0]) };
 }
 
 export function unwrapHostValue(ctx, root) {
   const outTag = [0n];
   const outPayload = [0];
   const ok = getLib().func('int arb_unwrap_host_value(arb_ctx_t *ctx, uint64_t root, _Out_ uint64_t *out_tag, _Out_ uint64_t *out_payload)')(ctx, root, outTag, outPayload);
   if (ok !== 0) throw new Error('arb_unwrap_host_value failed');
   return { tag: outTag[0], payload: BigInt(outPayload[0]) };
 }
 
 // ── Kernel ──────────────────────────────────────────────────────────────────
 
 export function kernelRoot(ctx) {
   return owned('uint64_t arb_kernel_root(arb_ctx_t *ctx)', ctx);
 }
 
 // ── High-level helpers ──────────────────────────────────────────────────────
 
 export function decode(ctx, root) {
   try {
     return toBool(ctx, root) ? 'true' : 'false';
   } catch {
     try {
       return toString(ctx, root);
     } catch {
       try {
         return String(toNumber(ctx, root));
       } catch {
         throw new Error('could not decode result');
       }
     }
   }
 }
 
 export function decodeType(ctx, root) {
   try { toBool(ctx, root); return 'bool'; } catch {}
   try { toString(ctx, root); return 'string'; } catch {}
   try { toNumber(ctx, root); return 'number'; } catch {}
   return 'unknown (raw tree)';
 }