knitting 0.1.56 → 0.1.60

package/src/api.js

@@ -1,4 +1,4 @@
-import { getCallerFilePath, getCallerHref } from "./common/task-source.js";
+import { getCallerFilePath, getCallerHref, setModuleUrl, } from "./common/task-source.js";
 import { DEBUG_ENABLED, resolveDebugNamespaces } from "./debug/gate.js";
 import { genTaskID } from "./common/task-source.js";
 import { toModuleUrl } from "./common/module-url.js";
@@ -7,8 +7,10 @@ import { spawnWorkerContext } from "./runtime/pool.js";
 import { ChannelHandler } from "./runtime/dispatcher.js";
 import { RUNTIME } from "./common/runtime.js";
 import { RUNTIME_IS_MAIN_THREAD, RUNTIME_POOL_DEPTH, RUNTIME_WORKER_DATA, } from "./common/worker-runtime.js";
-import { resolvePermissionProtocol, toRuntimePermissionFlags, } from "./permission/index.js";
+import { classifyProcessPermissionCompatibility, enforceProcessPermissionCompatibility, resolvePermissionProtocol, toRuntimePermissionFlags, } from "./permission/index.js";
 import { getNodeProcess } from "./common/node-compat.js";
+import { readProcessWorkerCommandPrefix, readProcessWorkerRuntime, } from "./runtime/process-worker.js";
+import { inspectCompiledWorkerArtifact } from "./runtime/compiled-artifact.js";
 import { managerMethod } from "./runtime/balancer.js";
 import { createInlineExecutor } from "./runtime/inline-executor.js";
 const hasDebugNamespace = (namespaces, namespace) => namespaces.has("*") || namespaces.has(namespace);
@@ -44,12 +46,39 @@ const readHostCwd = () => {
     }
     return undefined;
 };
+const readKnownProcessWorkerNodeMajor = (worker) => {
+    if (RUNTIME !== "node")
+        return undefined;
+    if (readProcessWorkerCommandPrefix(worker) !== undefined)
+        return undefined;
+    const nodeProcess = getNodeProcess();
+    if (nodeProcess?.env?.NODE_BINARY !== undefined)
+        return undefined;
+    const raw = nodeProcess?.versions?.node;
+    const major = Number.parseInt(String(raw).split(".", 1)[0] ?? "", 10);
+    return Number.isInteger(major) && major > 0 ? major : undefined;
+};
 const formatDebugList = (values, empty = "(none)") => values && values.length > 0 ? values.join(",") : empty;
 const MAX_FUNCTION_ID = 0xFFFF;
 const MAX_FUNCTION_COUNT = MAX_FUNCTION_ID + 1;
 const DEFAULT_IMPORT_EXPORT_NAME = "default";
 export const isMain = RUNTIME_IS_MAIN_THREAD;
 export { endpointSymbol as endpointSymbol };
+/**
+ * Declare the task module's URL for runtimes without stack traces (e.g.
+ * Andromeda) that can't auto-discover the caller. Call once at module top
+ * level, before defining tasks:
+ *
+ * ```ts
+ * import { setModuleUrl, task } from "knitting";
+ * setModuleUrl(import.meta.url);
+ * export const add = task({ f: ([a, b]: [number, number]) => a + b });
+ * ```
+ *
+ * Runs in both host and worker (same module re-imported), so both agree on the
+ * path. No-op-safe on Node/Deno/Bun, where stack discovery already works.
+ */
+export { setModuleUrl as setModuleUrl };
 /**
  * Reconstructs stable task order from top-level exports before names are bound.
  */
@@ -80,25 +109,112 @@ const resolveImportHref = (href, callerHref) => {
         return toModuleUrl(href);
     }
 };
-const resolveWorkerBootstrapSettings = (worker, callerHref) => {
-    const bootstrap = worker?.bootstrap;
-    if (bootstrap === undefined)
-        return worker;
-    const name = bootstrap.name ?? DEFAULT_IMPORT_EXPORT_NAME;
-    if (typeof bootstrap.href !== "string" || bootstrap.href.length === 0) {
-        throw new TypeError("worker.bootstrap.href must be a non-empty string");
+const resolveWorkerSettings = (worker, callerHref) => {
+    if (worker === undefined)
+        return undefined;
+    const usingPorffor = worker.processRuntime === "porffor";
+    if (usingPorffor && worker.runtime !== undefined &&
+        worker.runtime !== "compiled") {
+        throw new Error('worker.processRuntime "porffor" requires worker.runtime to be compiled or omitted');
     }
-    if (typeof name !== "string" || name.length === 0) {
-        throw new TypeError("worker.bootstrap.name must be a non-empty string");
+    const forcePorfforBuild = usingPorffor && worker.runtime === undefined;
+    let resolved = usingPorffor
+        ? {
+            ...worker,
+            runtime: "compiled",
+            processRuntime: undefined,
+            compiled: forcePorfforBuild
+                ? { ...worker.compiled, build: "always" }
+                : worker.compiled,
+        }
+        : worker;
+    const bootstrap = resolved.bootstrap;
+    if (bootstrap !== undefined) {
+        const name = bootstrap.name ?? DEFAULT_IMPORT_EXPORT_NAME;
+        if (typeof bootstrap.href !== "string" || bootstrap.href.length === 0) {
+            throw new TypeError("worker.bootstrap.href must be a non-empty string");
+        }
+        if (typeof name !== "string" || name.length === 0) {
+            throw new TypeError("worker.bootstrap.name must be a non-empty string");
+        }
+        resolved = {
+            ...resolved,
+            bootstrap: {
+                ...bootstrap,
+                href: resolveImportHref(bootstrap.href, callerHref),
+                name,
+            },
+        };
     }
-    return {
-        ...worker,
-        bootstrap: {
-            ...bootstrap,
-            href: resolveImportHref(bootstrap.href, callerHref),
-            name,
-        },
+    const compiled = resolved.compiled;
+    if (compiled !== undefined) {
+        if (compiled.build !== undefined && typeof compiled.build !== "boolean" &&
+            compiled.build !== "always") {
+            throw new TypeError('worker.compiled.build must be a boolean or "always"');
+        }
+        for (const [name, value] of Object.entries({
+            artifact: compiled.artifact,
+            manifest: compiled.manifest,
+            compiler: compiled.compiler,
+        })) {
+            if (value !== undefined &&
+                (typeof value !== "string" || value.length === 0)) {
+                throw new TypeError("worker.compiled." + name + " must be a non-empty string");
+            }
+        }
+        resolved = {
+            ...resolved,
+            compiled: {
+                build: compiled.build,
+                compiler: compiled.compiler === undefined
+                    ? undefined
+                    : compiled.compiler.startsWith(".") ||
+                        compiled.compiler.startsWith("/") ||
+                        compiled.compiler.startsWith("file:") ||
+                        /^[A-Za-z]:[\\/]/.test(compiled.compiler)
+                        ? resolveImportHref(compiled.compiler, callerHref)
+                        : compiled.compiler,
+                artifact: compiled.artifact === undefined
+                    ? undefined
+                    : resolveImportHref(compiled.artifact, callerHref),
+                manifest: compiled.manifest === undefined
+                    ? undefined
+                    : resolveImportHref(compiled.manifest, callerHref),
+            },
+        };
+    }
+    return resolved;
+};
+/**
+ * Check whether a task module has a compatible prebuilt native worker.
+ *
+ * By default tasks.ts resolves to tasks.knt plus tasks.knt.json.
+ * This only inspects the artifact; it never executes it.
+ */
+export const checkCompiledWorker = (source, options) => {
+    const moduleSource = typeof source === "string" || source instanceof URL
+        ? source
+        : source?.importedFrom;
+    if (typeof moduleSource !== "string" && !(moduleSource instanceof URL)) {
+        throw new TypeError("checkCompiledWorker expects a task definition, module path, or URL");
+    }
+    const callerHref = getCallerHref(2);
+    const resolvedOptions = options === undefined ? undefined : {
+        build: options.build,
+        compiler: options.compiler,
+        artifact: options.artifact === undefined
+            ? undefined
+            : resolveImportHref(options.artifact, callerHref),
+        manifest: options.manifest === undefined
+            ? undefined
+            : resolveImportHref(options.manifest, callerHref),
     };
+    const inspection = inspectCompiledWorkerArtifact({
+        source: moduleSource,
+        options: resolvedOptions,
+    });
+    const { artifactHref: _artifactHref, manifestHref: _manifestHref, taskEntries: _taskEntries, ...result } = inspection;
+    return result;
 };
 const isTaskDefinition = (value) => value != null &&
     typeof value === "object" &&
@@ -206,7 +322,9 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
             key === "--allow-fs-write" ||
             key === "--allow-worker" ||
             key === "--allow-child-process" ||
+            key === "--allow-net" ||
             key === "--allow-addons" ||
+            key === "--allow-ffi" ||
             key === "--allow-wasi";
     };
     const stripNodePermissionFlags = (flags) => flags?.filter((flag) => !isNodePermissionFlag(flag));
@@ -256,7 +374,54 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
     hostDebug?.log(`modules=${formatDebugList(list)}`);
     hostDebug?.log(`permission=${permissionProtocol?.mode ?? "off"} execArgv=${formatDebugList(execArgv)}`);
     const usesAbortSignal = listOfFunctions.some((fn) => fn.abortSignal !== undefined);
-    const resolvedWorker = resolveWorkerBootstrapSettings(worker, callerHref);
+    const resolvedWorker = resolveWorkerSettings(worker, callerHref);
+    const usingCompiledWorker = resolvedWorker?.runtime === "compiled";
+    if (resolvedWorker?.compiled !== undefined && !usingCompiledWorker) {
+        throw new Error("worker.compiled requires worker.runtime to be compiled");
+    }
+    if (usingCompiledWorker) {
+        const unsupported = [];
+        if (usingInliner)
+            unsupported.push("inliner");
+        if (payload !== undefined)
+            unsupported.push("payload");
+        if (unsafe !== undefined)
+            unsupported.push("unsafe");
+        if (source !== undefined)
+            unsupported.push("source");
+        if (workerExecArgv !== undefined)
+            unsupported.push("workerExecArgv");
+        if (permission !== undefined)
+            unsupported.push("permission");
+        if (host !== undefined)
+            unsupported.push("host");
+        if (resolvedWorker.bootstrap !== undefined) {
+            unsupported.push("worker.bootstrap");
+        }
+        if (resolvedWorker.timers !== undefined)
+            unsupported.push("worker.timers");
+        if (resolvedWorker.processRuntime !== undefined) {
+            unsupported.push("worker.processRuntime");
+        }
+        if (resolvedWorker.processCommandPrefix !== undefined) {
+            unsupported.push("worker.processCommandPrefix");
+        }
+        if (resolvedWorker.processSharedMemory !== undefined) {
+            unsupported.push("worker.processSharedMemory");
+        }
+        if (resolvedWorker.resolveAfterFinishingAll !== undefined) {
+            unsupported.push("worker.resolveAfterFinishingAll");
+        }
+        if (listOfFunctions.some((fn) => fn.timeout !== undefined)) {
+            unsupported.push("task timeout");
+        }
+        if (listOfFunctions.some((fn) => fn.imported === true)) {
+            unsupported.push("importTask");
+        }
+        if (unsupported.length > 0) {
+            throw new Error("Compiled workers do not support: " + unsupported.join(", "));
+        }
+    }
     if (resolvedWorker?.bootstrap !== undefined) {
         hostDebug?.log(`bootstrap href=${resolvedWorker.bootstrap.href}` +
             ` name=${resolvedWorker.bootstrap.name}`);
@@ -264,6 +429,19 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
     if (usingInliner && resolvedWorker?.bootstrap !== undefined) {
         throw new Error("worker.bootstrap cannot be used with the inliner");
     }
+    if (resolvedWorker?.runtime === "process") {
+        const processRuntime = readProcessWorkerRuntime(resolvedWorker);
+        enforceProcessPermissionCompatibility(classifyProcessPermissionCompatibility({
+            permission,
+            resolved: permissionProtocol,
+            target: {
+                runtime: processRuntime,
+                nodeMajor: processRuntime === "node"
+                    ? readKnownProcessWorkerNodeMajor(resolvedWorker)
+                    : undefined,
+            },
+        }));
+    }
     const hardTimeoutMs = Number.isFinite(resolvedWorker?.hardTimeoutMs)
         ? Math.max(1, Math.floor(resolvedWorker?.hardTimeoutMs))
         : undefined;
@@ -292,7 +470,8 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
         return "serial-channel";
     })();
     const dispatcher = explicitDispatcher ?? autoDispatcher;
-    const serialChannel = dispatcher === "serial-channel";
+    const serialChannel = !usingCompiledWorker &&
+        dispatcher === "serial-channel";
     const serialDispatcherChannel = serialChannel
         ? new ChannelHandler()
         : undefined;

package/src/common/module-url.d.ts

@@ -1 +1,2 @@
 export declare const toModuleUrl: (specifier: string) => string;
+export declare const toImportSpecifier: (moduleUrl: string) => string;

package/src/common/module-url.js

@@ -1,9 +1,18 @@
-import { pathToFileURL } from "node:url";
+import { getNodeBuiltinModule } from "./node-compat.js";
+import { IS_ANDROMEDA } from "./runtime.js";
 const WINDOWS_DRIVE_PATH = /^[A-Za-z]:[\\/]/;
 const WINDOWS_UNC_PATH = /^\\\\[^\\/?]+\\[^\\/?]+/;
 const encodeFilePath = (path) => encodeURI(path)
     .replace(/\?/g, "%3F")
     .replace(/#/g, "%23");
+// `node:url` resolved lazily (absent on Andromeda); fall back to a pure
+// path->file-URL conversion when it is missing.
+const nodePathToFileURL = () => getNodeBuiltinModule("node:url")
+    ?.pathToFileURL;
+const pathToFileUrlFallback = (specifier) => {
+    const absolute = specifier.startsWith("/") ? specifier : `/${specifier}`;
+    return `file://${encodeFilePath(absolute)}`;
+};
 export const toModuleUrl = (specifier) => {
     if (WINDOWS_DRIVE_PATH.test(specifier)) {
         const normalized = specifier.replace(/\\/g, "/");
@@ -19,6 +28,25 @@ export const toModuleUrl = (specifier) => {
         return new URL(specifier).href;
     }
     catch {
-        return pathToFileURL(specifier).href;
+        const pathToFileURL = nodePathToFileURL();
+        return pathToFileURL
+            ? pathToFileURL(specifier).href
+            : pathToFileUrlFallback(specifier);
+    }
+};
+// Andromeda's loader treats `file://` import specifiers as relative paths;
+// convert back to a plain filesystem path there. No-op elsewhere.
+export const toImportSpecifier = (moduleUrl) => {
+    if (!IS_ANDROMEDA || !moduleUrl.startsWith("file://"))
+        return moduleUrl;
+    const withoutScheme = moduleUrl.slice("file://".length);
+    const path = withoutScheme.startsWith("/")
+        ? withoutScheme
+        : `/${withoutScheme}`;
+    try {
+        return decodeURIComponent(path);
+    }
+    catch {
+        return path;
     }
 };

package/src/common/node-compat.d.ts

@@ -1,8 +1,10 @@
 export type NodeProcessLike = {
     getBuiltinModule?: (id: string) => unknown;
     versions?: {
+        modules?: string;
         node?: string;
     };
+    pid?: number;
     platform?: string;
     allowedNodeEnvironmentFlags?: ReadonlySet<string>;
     execArgv?: string[];

package/src/common/path-canonical.js

@@ -1,9 +1,23 @@
-import { existsSync, realpathSync, } from "node:fs";
-import { basename as pathBasename, dirname as pathDirname, join as pathJoin, resolve as pathResolve, } from "node:path";
-export const toCanonicalPath = (candidate, fsApi = {
-    existsSync,
-    realpathSync: realpathSync.native ?? realpathSync,
-}) => {
+import { getNodeBuiltinModule } from "./node-compat.js";
+const nodeFs = () => getNodeBuiltinModule("node:fs");
+const nodePath = () => {
+    const module = getNodeBuiltinModule("node:path");
+    if (module === undefined) {
+        throw new Error("node:path is not available in this runtime");
+    }
+    return module;
+};
+const defaultFsApi = () => {
+    const fs = nodeFs();
+    if (fs === undefined)
+        return {};
+    return {
+        existsSync: fs.existsSync,
+        realpathSync: fs.realpathSync.native ?? fs.realpathSync,
+    };
+};
+export const toCanonicalPath = (candidate, fsApi = defaultFsApi()) => {
+    const { basename: pathBasename, dirname: pathDirname, join: pathJoin, resolve: pathResolve, } = nodePath();
     const absolute = pathResolve(candidate);
     const { existsSync, realpathSync } = fsApi;
     if (typeof realpathSync === "function") {

package/src/common/runtime.d.ts

@@ -1,7 +1,8 @@
-type RuntimeName = "deno" | "bun" | "node" | "unknown";
+type RuntimeName = "deno" | "bun" | "node" | "andromeda" | "unknown";
 export declare const IS_DENO: boolean;
 export declare const IS_BUN: boolean;
 export declare const IS_NODE: boolean;
+export declare const IS_ANDROMEDA: boolean;
 export declare const RUNTIME: RuntimeName;
 export declare const SET_IMMEDIATE: typeof setImmediate & ((cb: () => void) => void);
 export declare const HAS_SHARED_WASM_MEMORY: boolean;

package/src/common/runtime.js

@@ -4,16 +4,30 @@ const nodeProcess = getNodeProcess();
 export const IS_DENO = typeof globals.Deno?.version?.deno === "string";
 export const IS_BUN = typeof globals.Bun?.version === "string";
 export const IS_NODE = typeof nodeProcess?.versions?.node === "string";
-export const RUNTIME = (IS_DENO ? "deno" : IS_BUN ? "bun" : IS_NODE ? "node" : "unknown");
+// Andromeda (Nova engine): no `node:` builtins or `WebAssembly`; detect via
+// its private bootstrap global.
+export const IS_ANDROMEDA = typeof globals.__andromeda__ !== "undefined";
+export const RUNTIME = (IS_DENO
+    ? "deno"
+    : IS_BUN
+        ? "bun"
+        : IS_NODE
+            ? "node"
+            : IS_ANDROMEDA
+                ? "andromeda"
+                : "unknown");
+// `WebAssembly` may be undeclared (not just undefined) on Andromeda, where a
+// bare reference throws; capture it through `globalThis` so access is safe.
+const WebAssemblyRef = globals.WebAssembly;
 export const SET_IMMEDIATE = typeof globals.setImmediate === "function" ? globals.setImmediate : undefined;
 const WASM_MEMORY_PAGE_BYTES = 64 * 1024;
 const wasmSharedBufferMemory = new WeakMap();
 const wasmSharedBufferMaxByteLength = new WeakMap();
 const hasSharedWasmMemory = (() => {
-    if (typeof WebAssembly?.Memory !== "function")
+    if (typeof WebAssemblyRef?.Memory !== "function")
         return false;
     try {
-        void new WebAssembly.Memory({ initial: 0, maximum: 1, shared: true });
+        void new WebAssemblyRef.Memory({ initial: 0, maximum: 1, shared: true });
         return true;
     }
     catch {
@@ -23,7 +37,7 @@ const hasSharedWasmMemory = (() => {
 export const HAS_SHARED_WASM_MEMORY = hasSharedWasmMemory;
 const roundupWasmPages = (byteLength) => Math.ceil(Math.max(0, byteLength) / WASM_MEMORY_PAGE_BYTES);
 const createSharedWasmBuffer = (byteLength, maxByteLength) => {
-    const memory = new WebAssembly.Memory({
+    const memory = new WebAssemblyRef.Memory({
         initial: roundupWasmPages(byteLength),
         maximum: Math.max(roundupWasmPages(byteLength), roundupWasmPages(maxByteLength)),
         shared: true,

package/src/common/task-source.d.ts

@@ -1,3 +1,5 @@
 export declare const genTaskID: () => number;
+export declare const setModuleUrl: (url: string | undefined) => void;
+export declare const getModuleUrlOverride: () => string | undefined;
 export declare const getCallerHref: (offset?: number) => string;
 export declare const getCallerFilePath: (offset?: number) => [string, number];

package/src/common/task-source.js

@@ -61,7 +61,21 @@ const collectStackFrames = () => {
 const isInternalFrame = (frame) => isRuntimeInternalFrame(frame.file) ||
     isInternalCallerFrame(frame.file) ||
     isInternalCallerFunction(frame.functionName, frame.methodName);
+// Module-URL override for runtimes without stack traces (e.g. Andromeda, where
+// `new Error().stack` is undefined). When set, caller discovery skips stack
+// inspection and attributes every task here. Set via
+// `setModuleUrl(import.meta.url)`, which runs in both host and worker copies so
+// both agree on the path.
+let moduleUrlOverride;
+export const setModuleUrl = (url) => {
+    moduleUrlOverride = typeof url === "string" && url.length > 0
+        ? toModuleUrl(url)
+        : undefined;
+};
+export const getModuleUrlOverride = () => moduleUrlOverride;
 const resolveCallerHref = (offset) => {
+    if (moduleUrlOverride !== undefined)
+        return moduleUrlOverride;
     const frames = collectStackFrames();
     const direct = frames[offset];
     const caller = (direct && !isInternalFrame(direct)
@@ -70,7 +84,9 @@ const resolveCallerHref = (offset) => {
         frames.find((frame) => !isInternalFrame(frame))?.file ??
         frames.find((frame) => !isRuntimeInternalFrame(frame.file))?.file;
     if (!caller) {
-        throw new Error("Unable to determine caller file.");
+        throw new Error("Unable to determine caller file. This runtime exposes no stack traces " +
+            "(e.g. Andromeda); call setModuleUrl(import.meta.url) at the top of " +
+            "the module that defines your tasks before creating a pool.");
     }
     return toModuleUrl(caller);
 };

package/src/common/worker-runtime.js

@@ -1,4 +1,5 @@
 import { getNodeBuiltinModule, getNodeProcess } from "./node-compat.js";
+import { IS_ANDROMEDA } from "./runtime.js";
 export const RUNTIME_PROCESS_WORKER_ENV = "KNITTING_PROCESS_WORKER";
 export const RUNTIME_PROCESS_WORKER_BOOT_ENV = "KNITTING_PROCESS_WORKER_BOOT";
 export const RUNTIME_PROCESS_WORKER_BOOT_VERSION = 1;
@@ -16,15 +17,23 @@ export const RUNTIME_POOL_DEPTH = readPoolDepth();
 const workerThreads = getNodeBuiltinModule("node:worker_threads");
 const isWorkerGlobalScope = () => {
     const scopeCtor = globalThis.WorkerGlobalScope;
-    if (typeof scopeCtor !== "function")
-        return false;
-    try {
-        return globalThis instanceof
-            scopeCtor;
+    if (typeof scopeCtor === "function") {
+        try {
+            if (globalThis instanceof scopeCtor) {
+                return true;
+            }
+        }
+        catch {
+            // fall through to runtime-specific checks
+        }
     }
-    catch {
-        return false;
+    // Andromeda has no `WorkerGlobalScope`; its worker scope is distinguished by a
+    // `self` global that the main thread lacks.
+    if (IS_ANDROMEDA &&
+        typeof globalThis.self !== "undefined") {
+        return true;
     }
+    return false;
 };
 export const RUNTIME_WORKER = workerThreads?.Worker ??
     (globalThis.Worker);

package/src/connections/buffer-reference-native.js

@@ -1,5 +1,6 @@
 import { RUNTIME } from "../common/runtime.js";
 import { loadNodeBufferPointerAddon } from "./node-buffer-pointer.js";
+import { getNodeFfi, isNodeFfiTarget } from "./node-ffi.js";
 const isSharedArrayBufferInstance = (value) => typeof SharedArrayBuffer === "function" && value instanceof SharedArrayBuffer;
 const assertMovableSource = (source) => {
     const buffer = ArrayBuffer.isView(source) ? source.buffer : source;
@@ -132,6 +133,27 @@ const createBunCapabilities = () => {
         releaseShared: releaseFfi,
     };
 };
+const createNodeFfiCapabilities = () => {
+    const ffi = getNodeFfi();
+    const readPointer = (region) => ffi.getRawPointer(region);
+    return {
+        runtime: "node",
+        supportsOwningAdopt: false,
+        produce: (view) => produceFfi(view, readPointer),
+        adopt: ({ pointer, byteLength }, opts) => {
+            const alias = ffi.toArrayBuffer(pointer, byteLength, false);
+            return finishAlias(alias, opts?.copy);
+        },
+        release: releaseFfi,
+        supportsSharedAdopt: false,
+        produceShared: (sab) => produceSharedFfi(sab, readPointer),
+        adoptShared: ({ pointer, byteLength }) => {
+            const alias = ffi.toArrayBuffer(pointer, byteLength, false);
+            return { buffer: alias, byteOffset: 0, byteLength, isShared: false };
+        },
+        releaseShared: releaseFfi,
+    };
+};
 // ---------------------------------------------------------------------------
 // Node: addon-backed owning move via shared_ptr<BackingStore>.
 // Older prebuilds fall back to non-owning retain/wrap.
@@ -206,7 +228,9 @@ export const getBufferReferenceCapabilities = () => {
         return cached;
     switch (RUNTIME) {
         case "node":
-            return cached = createNodeCapabilities();
+            return cached = isNodeFfiTarget()
+                ? createNodeFfiCapabilities()
+                : createNodeCapabilities();
         case "deno":
             return cached = createDenoCapabilities();
         case "bun":

package/src/connections/buffer-reference.d.ts

@@ -38,11 +38,24 @@ export type BufferReferenceReturnReleaseMessage = {
     readonly [BUFFER_REFERENCE_RETURN_RELEASE_MESSAGE_KEY]: string;
 };
 type BufferReferenceReturnReleaser = (token: bigint) => void;
+/** Host-side hooks for borrowed returns: release channel plus shutdown tracking. */
+export type BufferReferenceReturnHooks = {
+    /** Ask the producing worker to drop its pin for `token`. */
+    release: BufferReferenceReturnReleaser;
+    /**
+     * Record a borrowed reference so the pool can revoke it before its worker
+     * dies. Called at claim time without `aliasBuffer`, then again on first
+     * materialize with the alias buffer once it exists.
+     */
+    track?: (ref: BufferReference, token: bigint, aliasBuffer?: ArrayBuffer) => void;
+};
 type BufferSource = ArrayBufferView | ArrayBuffer;
 declare const PAYLOAD_TRANSPORT_FINALIZER: unique symbol;
-export declare const withBufferReferenceReturnReleaser: <T>(releaser: BufferReferenceReturnReleaser | undefined, run: () => T) => T;
+export declare const withBufferReferenceReturnReleaser: <T>(releaser: BufferReferenceReturnReleaser | BufferReferenceReturnHooks | undefined, run: () => T) => T;
 export declare const createBufferReferenceReturnReleaseMessage: (token: bigint) => BufferReferenceReturnReleaseMessage;
 export declare const readBufferReferenceReturnReleaseMessage: (value: unknown) => bigint | undefined;
+/** Revocation primitive: detach `buffer` so every view over it is neutralized. */
+export declare const detachArrayBufferBestEffort: (runtime: BufferReferenceRuntime, buffer: ArrayBuffer) => boolean;
 export declare const isBufferReferenceMetadata: (value: unknown) => value is BufferReferenceMetadata;
 /**
  * Zero-copy handle for moving ArrayBuffer bytes to/from **thread** workers.
@@ -67,12 +80,20 @@ export declare class BufferReference {
     [BUFFER_REFERENCE_NUMERIC_TRANSFER](): BufferReferenceNumericMetadata | undefined;
     get isLocal(): boolean;
     /** Prepare a returned reference before the worker-side producer hold drains. */
-    claimOwnership(releaser?: BufferReferenceReturnReleaser): this;
+    claimOwnership(releaser?: BufferReferenceReturnReleaser | BufferReferenceReturnHooks | undefined): this;
     toArrayBuffer(): ArrayBuffer;
     toUint8Array(): Uint8Array;
     /** The source is moved on construction, so it is never retained here. */
     get source(): undefined;
     release(): void;
+    /**
+     * Revoke a borrowed return before its producing worker goes away: detach
+     * the borrowed alias so no view can dangle. With `copyBytes` the reference
+     * itself survives on an owned copy; without it (worker bytes already gone)
+     * later reads fail loud instead of aliasing freed memory.
+     */
+    revokeBorrow(copyBytes: boolean): void;
     [Symbol.dispose](): void;
     [PAYLOAD_TRANSPORT_FINALIZER](): (() => void) | undefined;
 }
+export declare const isBufferReferenceValue: (value: unknown) => value is BufferReference;