knitting 0.1.51 → 0.1.53

package/src/api.js

@@ -7,27 +7,58 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     return path;
 };
 import { getCallerFilePath, getCallerHref } 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";
 import { endpointSymbol } from "./common/task-symbol.js";
 import { spawnWorkerContext } from "./runtime/pool.js";
-import { RUNTIME_IS_MAIN_THREAD, RUNTIME_WORKER_DATA, } from "./common/worker-runtime.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 { getNodeProcess } from "./common/node-compat.js";
 import { managerMethod } from "./runtime/balancer.js";
 import { createInlineExecutor } from "./runtime/inline-executor.js";
+const hasDebugNamespace = (namespaces, namespace) => namespaces.has("*") || namespaces.has(namespace);
+const createHostDebug = (namespaces) => {
+    const enabled = (namespace) => hasDebugNamespace(namespaces, namespace);
+    if (!enabled("host"))
+        return undefined;
+    const base = performance.now();
+    const tag = `host·${RUNTIME}`;
+    const log = (message) => {
+        const elapsed = (performance.now() - base).toFixed(1);
+        console.error(`[${tag}·+${elapsed}ms] host: ${message}`);
+    };
+    return { log };
+};
+const readHostCwd = () => {
+    const denoCwd = globalThis.Deno?.cwd;
+    if (typeof denoCwd === "function") {
+        try {
+            return denoCwd();
+        }
+        catch {
+        }
+    }
+    const nodeProcess = getNodeProcess();
+    if (typeof nodeProcess?.cwd === "function") {
+        try {
+            return nodeProcess.cwd();
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return 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 };
 /**
- *  With this information we can recreate the logical order of
- *  relevant exported functions from a file, also it helps to
- *  track a task before naming, ` export ` elements have to be declared
- *  at top level and without branching, we take advantage of this to
- *  correctly map them.
- *
+ * Reconstructs stable task order from top-level exports before names are bound.
  */
 export const toListAndIds = (args) => {
     const result = args
@@ -98,13 +129,36 @@ const toPoolTaskEntries = (input, callerHref) => Object.entries(input).map(([nam
     }
     throw new TypeError(`createPool task "${name}" must be a task definition or exported function`);
 });
-export const createPool = ({ threads, debug, inliner, balancer, payload, payloadInitialBytes, payloadMaxBytes, bufferMode, maxPayloadBytes, abortSignalCapacity, source, worker, workerExecArgv, permission, dispatcher, host, }) => (tasks) => {
+/**
+ * Create a typed worker pool from module-scope exported tasks/functions.
+ *
+ * Install/import as `knitting` on npm or `@vixeny/knitting` on JSR. Requires
+ * Node 22+, Deno 2+, or Bun 1+.
+ *
+ * Use `createPool(options)({ taskA })`, call `await pool.call.taskA(arg)`, and
+ * clean up with `using pool = ...` or `await pool.shutdown()`.
+ *
+ * Guard host-only pool setup with `isMain`: workers re-import task modules, and
+ * top-level imports in those modules run in every worker. Keep task modules
+ * lean and separate from server/framework setup. Each task receives one
+ * argument; use an object or tuple for multiple values.
+ */
+export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe, abortSignalCapacity, source, worker, workerExecArgv, permission, host, }) => (tasks) => {
+    const bufferReferenceReturn = unsafe?.BufferReferenceReturn;
+    const debugRequested = DEBUG_ENABLED ||
+        (debug !== undefined && debug !== false);
+    let debugNamespaces;
+    const getDebugNamespaces = () => debugNamespaces ??= resolveDebugNamespaces(debug);
+    const hostDebug = debugRequested
+        ? createHostDebug(getDebugNamespaces())
+        : undefined;
+    const debugEnabled = (namespace) => debugRequested && hasDebugNamespace(getDebugNamespaces(), namespace);
     /**
      *  This functions is only available in the main thread.
      *  Also triggers when debug extra is enabled.
      */
     if (RUNTIME_IS_MAIN_THREAD === false) {
-        if ((debug?.extras === true)) {
+        if (debugEnabled("lifecycle")) {
             console.warn("createPool has been called with : " + JSON.stringify(RUNTIME_WORKER_DATA));
         }
         const notMainThreadError = () => {
@@ -130,6 +184,10 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, payload
     const listOfFunctions = toPoolTaskEntries(tasks, callerHref)
         .sort((a, b) => a.name.localeCompare(b.name));
     const { list, ids, names, at } = toListAndIds(listOfFunctions);
+    hostDebug?.log(`cwd=${readHostCwd() ?? "(unknown)"} caller=${callerHref}`);
+    listOfFunctions.forEach((fn) => {
+        hostDebug?.log(`task name=${fn.name} id=${fn.id} from=${fn.importedFrom}`);
+    });
     if (listOfFunctions.length > MAX_FUNCTION_COUNT) {
         throw new RangeError(`Too many tasks: received ${listOfFunctions.length}. ` +
             `Maximum is ${MAX_FUNCTION_COUNT} (Uint16 function IDs: 0..${MAX_FUNCTION_ID}).`);
@@ -200,15 +258,31 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, payload
         ...(defaultExecArgv ?? []),
     ]);
     const execArgv = sanitizeExecArgv(combinedExecArgv.length > 0 ? combinedExecArgv : undefined);
-    const hostDispatcher = host ?? dispatcher;
+    hostDebug?.log(`pool runtime=${RUNTIME} workers=${threads ?? 1}` +
+        ` lanes=${totalNumberOfThread} inliner=${usingInliner ? "on" : "off"}`);
+    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);
+    if (resolvedWorker?.bootstrap !== undefined) {
+        hostDebug?.log(`bootstrap href=${resolvedWorker.bootstrap.href}` +
+            ` name=${resolvedWorker.bootstrap.name}`);
+    }
     if (usingInliner && resolvedWorker?.bootstrap !== undefined) {
         throw new Error("worker.bootstrap cannot be used with the inliner");
     }
     const hardTimeoutMs = Number.isFinite(resolvedWorker?.hardTimeoutMs)
         ? Math.max(1, Math.floor(resolvedWorker?.hardTimeoutMs))
         : undefined;
+    if (RUNTIME_POOL_DEPTH >= 1) {
+        throw new Error(`createPool() tried to spawn workers from inside a worker process ` +
+            `(pool depth ${RUNTIME_POOL_DEPTH}). This usually means a pool is ` +
+            `created at module scope in a module your workers import, so every ` +
+            `worker spawns its own pool recursively. Is your createPool protected ` +
+            `by isMain? Guard pool creation behind \`if (isMain) { ... }\` ` +
+            `(import { isMain } from "knitting") so only the main program starts ` +
+            `the pool.`);
+    }
     let workers = Array.from({
         length: threads ?? 1,
     }).map((_, thread) => spawnWorkerContext({
@@ -218,16 +292,14 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, payload
         at,
         thread,
         debug,
+        hostDebug: hostDebug?.log,
         totalNumberOfThread,
         source,
         workerOptions: resolvedWorker,
         workerExecArgv: execArgv,
-        host: hostDispatcher,
+        host,
         payload,
-        payloadInitialBytes,
-        payloadMaxBytes,
-        bufferMode,
-        maxPayloadBytes,
+        bufferReferenceReturn,
         abortSignalCapacity,
         usesAbortSignal,
         permission: permissionProtocol,
@@ -377,19 +449,17 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, payload
         if (imported && usingInliner) {
             return buildImportedInvoker(handlers);
         }
-        return useDirectHandler
-            ? handlers[0]
-            : managerMethod({
-                contexts: workers,
-                balancer,
-                handlers,
-                inlinerGate: usingInliner
-                    ? {
-                        index: inlinerIndex,
-                        threshold: inlinerDispatchThreshold,
-                    }
-                    : undefined,
-            });
+        return useDirectHandler ? handlers[0] : managerMethod({
+            contexts: workers,
+            balancer,
+            handlers,
+            inlinerGate: usingInliner
+                ? {
+                    index: inlinerIndex,
+                    threshold: inlinerDispatchThreshold,
+                }
+                : undefined,
+        });
     };
     let callEntries;
     try {

package/src/common/envelope.d.ts

@@ -1,11 +1,17 @@
+import type { BufferReference } from "../connections/buffer-reference.js";
+import type { ProcessSharedBuffer } from "../connections/process-shared-buffer.js";
 type EnvelopeHeaderPrimitive = string | number | boolean | null;
 type EnvelopeHeaderValue = EnvelopeHeaderPrimitive | EnvelopeHeaderValue[] | {
     [key: string]: EnvelopeHeaderValue;
 };
 export type EnvelopeHeader = EnvelopeHeaderValue;
-export declare class Envelope<H extends EnvelopeHeader = EnvelopeHeader> {
+export type EnvelopeBody = ArrayBuffer | SharedArrayBuffer | BufferReference | ProcessSharedBuffer;
+declare const PayloadTransportFinalizer: unique symbol;
+export declare class Envelope<H extends EnvelopeHeader = EnvelopeHeader, B extends EnvelopeBody = ArrayBuffer> {
     readonly header: H;
-    readonly payload: ArrayBuffer;
-    constructor(header: H, payload: ArrayBuffer);
+    readonly payload: B;
+    constructor(header: H, payload: B);
+    [Symbol.dispose](): void;
+    [PayloadTransportFinalizer](): (() => void) | undefined;
 }
 export {};

package/src/common/envelope.js

@@ -1,3 +1,4 @@
+const PayloadTransportFinalizer = Symbol.for("knitting.payloadCodec.transportFinalizer");
 export class Envelope {
     header;
     payload;
@@ -5,4 +6,17 @@ export class Envelope {
         this.header = header;
         this.payload = payload;
     }
+    [Symbol.dispose]() {
+        const body = this.payload;
+        if (body !== null && typeof body === "object") {
+            body[Symbol.dispose]?.();
+        }
+    }
+    [PayloadTransportFinalizer]() {
+        const body = this.payload;
+        if (body === null || typeof body !== "object")
+            return undefined;
+        const finalizer = body[PayloadTransportFinalizer];
+        return typeof finalizer === "function" ? finalizer.call(body) : undefined;
+    }
 }

package/src/common/worker-runtime.d.ts

@@ -28,7 +28,9 @@ export type RuntimeMessageChannelLike = {
 export declare const RUNTIME_PROCESS_WORKER_ENV = "KNITTING_PROCESS_WORKER";
 export declare const RUNTIME_PROCESS_WORKER_BOOT_ENV = "KNITTING_PROCESS_WORKER_BOOT";
 export declare const RUNTIME_PROCESS_WORKER_BOOT_VERSION = 1;
+export declare const RUNTIME_POOL_DEPTH_ENV = "KNITTING_POOL_DEPTH";
 export declare const RUNTIME_IS_PROCESS_WORKER: boolean;
+export declare const RUNTIME_POOL_DEPTH: number;
 export declare const RUNTIME_WORKER: new (specifier: string | URL, options?: Record<string, unknown>) => RuntimeWorkerLike;
 export declare const RUNTIME_MESSAGE_CHANNEL: new () => RuntimeMessageChannelLike;
 export declare const HAS_NODE_WORKER_THREADS: boolean;

package/src/common/worker-runtime.js

@@ -2,8 +2,17 @@ import { getNodeBuiltinModule, getNodeProcess } from "./node-compat.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;
+export const RUNTIME_POOL_DEPTH_ENV = "KNITTING_POOL_DEPTH";
 const nodeProcess = getNodeProcess();
 export const RUNTIME_IS_PROCESS_WORKER = nodeProcess?.env?.[RUNTIME_PROCESS_WORKER_ENV] === "1";
+const readPoolDepth = () => {
+    const raw = nodeProcess?.env?.[RUNTIME_POOL_DEPTH_ENV];
+    if (typeof raw !== "string")
+        return 0;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
+};
+export const RUNTIME_POOL_DEPTH = readPoolDepth();
 const workerThreads = getNodeBuiltinModule("node:worker_threads");
 const isWorkerGlobalScope = () => {
     const scopeCtor = globalThis.WorkerGlobalScope;

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

@@ -0,0 +1,56 @@
+export type BufferReferenceRuntime = "node" | "deno" | "bun";
+/** A backing store the producer has taken exclusive ownership of (source detached). */
+export type ProducedBuffer = {
+    /** Producer-side release handle. */
+    token: bigint;
+    /** Address of the region start (view offset already applied). */
+    pointer: bigint;
+    /** Offset of the region inside the backing store (used by the Node owning adopt). */
+    byteOffset: number;
+    byteLength: number;
+};
+export type AdoptInput = {
+    token: bigint;
+    pointer: bigint;
+    byteOffset: number;
+    byteLength: number;
+};
+/** The materialized region: bytes live in `buffer` at `[byteOffset, byteOffset+byteLength)`. */
+export type AdoptedRegion = {
+    buffer: ArrayBuffer;
+    byteOffset: number;
+    byteLength: number;
+};
+/** Materialized SAB region; `isShared` means `buffer` is a real SharedArrayBuffer. */
+export type SharedAdoptedRegion = {
+    buffer: SharedArrayBuffer | ArrayBuffer;
+    byteOffset: number;
+    byteLength: number;
+    isShared: boolean;
+};
+export type AdoptOptions = {
+    /** Copy when bytes must survive producer release on non-owning runtimes. */
+    copy?: boolean;
+};
+type MovableBufferSource = ArrayBuffer | ArrayBufferView;
+export type BufferReferenceCapabilities = {
+    readonly runtime: BufferReferenceRuntime;
+    /** True when `adopt` returns a buffer that co-owns the store and survives `release`. */
+    readonly supportsOwningAdopt: boolean;
+    /** Take exclusive ownership of `source`'s bytes, detaching the source. */
+    produce(source: MovableBufferSource): ProducedBuffer;
+    /** Materialize the region in the current isolate (owning on Node, alias/copy elsewhere). */
+    adopt(input: AdoptInput, opts?: AdoptOptions): AdoptedRegion;
+    /** Drop the producer's hold on the backing store. */
+    release(token: bigint): void;
+    /** True when `adoptShared` returns a real SharedArrayBuffer (Node). */
+    readonly supportsSharedAdopt: boolean;
+    /** Share a SharedArrayBuffer by reference (no detach — SABs persist). */
+    produceShared(sab: SharedArrayBuffer): ProducedBuffer;
+    /** Materialize a shared region as a non-owning alias over the same bytes. */
+    adoptShared(input: AdoptInput): SharedAdoptedRegion;
+    /** Drop the producer's pin on a shared buffer (JS-side; teardown-safe). */
+    releaseShared(token: bigint): void;
+};
+export declare const getBufferReferenceCapabilities: () => BufferReferenceCapabilities;
+export {};

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

@@ -0,0 +1,217 @@
+import { RUNTIME } from "../common/runtime.js";
+import { loadNodeBufferPointerAddon } from "./node-buffer-pointer.js";
+const isSharedArrayBufferInstance = (value) => typeof SharedArrayBuffer === "function" && value instanceof SharedArrayBuffer;
+const assertMovableSource = (source) => {
+    const buffer = ArrayBuffer.isView(source) ? source.buffer : source;
+    if (isSharedArrayBufferInstance(buffer)) {
+        throw new TypeError("BufferReference expects ArrayBuffer-backed views; SharedArrayBuffer is already " +
+            "shared and cannot be moved");
+    }
+};
+const readSourceRegion = (source) => {
+    if (ArrayBuffer.isView(source)) {
+        return {
+            buffer: source.buffer,
+            byteOffset: source.byteOffset,
+            byteLength: source.byteLength,
+        };
+    }
+    return { buffer: source, byteOffset: 0, byteLength: source.byteLength };
+};
+/** Detach `buffer`, returning a fixed-length buffer over the same bytes (the move). */
+const detachIntoFixedLength = (buffer) => {
+    const transferable = buffer;
+    if (typeof transferable.transferToFixedLength === "function") {
+        return transferable.transferToFixedLength();
+    }
+    if (typeof transferable.transfer === "function") {
+        return transferable.transfer();
+    }
+    throw new TypeError("BufferReference requires ArrayBuffer.prototype.transfer to move a buffer in this runtime");
+};
+// ---------------------------------------------------------------------------
+// Deno/Bun pin moved buffers in JS and expose non-owning FFI aliases.
+// Tokens stay producer-isolate-local; consumers materialize from the pointer.
+// ---------------------------------------------------------------------------
+const ffiPinned = new Map();
+let nextFfiToken = 1n;
+const pinTransferred = (buffer) => {
+    const token = nextFfiToken++;
+    ffiPinned.set(token, buffer);
+    return token;
+};
+const pinShared = (sab) => {
+    const token = nextFfiToken++;
+    ffiPinned.set(token, sab);
+    return token;
+};
+const releaseFfi = (token) => {
+    ffiPinned.delete(token);
+};
+const produceSharedFfi = (sab, readPointer) => {
+    // SABs are shared, not detached; pin keeps producer bytes alive.
+    const pointer = readPointer(new Uint8Array(sab));
+    const token = pinShared(sab);
+    return { token, pointer, byteOffset: 0, byteLength: sab.byteLength };
+};
+const getDeno = () => {
+    const deno = globalThis.Deno;
+    if (deno?.UnsafePointer === undefined || deno.UnsafePointerView === undefined) {
+        throw new Error("Deno FFI (UnsafePointer) is not available in this runtime");
+    }
+    return deno;
+};
+const getBunFFI = () => {
+    const ffi = globalThis.Bun?.FFI;
+    if (typeof ffi?.ptr !== "function" || typeof ffi?.toArrayBuffer !== "function") {
+        throw new Error("Bun FFI (ptr/toArrayBuffer) is not available in this runtime");
+    }
+    return ffi;
+};
+const produceFfi = (source, readPointer) => {
+    assertMovableSource(source);
+    const { buffer, byteOffset, byteLength } = readSourceRegion(source);
+    const moved = detachIntoFixedLength(buffer);
+    // Region view over the moved buffer; the pointer captures the offset.
+    const region = new Uint8Array(moved, byteOffset, byteLength);
+    const pointer = readPointer(region);
+    const token = pinTransferred(moved);
+    return { token, pointer, byteOffset, byteLength };
+};
+const finishAlias = (alias, copy) => {
+    if (copy) {
+        const owned = alias.slice(0);
+        return { buffer: owned, byteOffset: 0, byteLength: owned.byteLength };
+    }
+    return { buffer: alias, byteOffset: 0, byteLength: alias.byteLength };
+};
+const createDenoCapabilities = () => {
+    const deno = getDeno();
+    return {
+        runtime: "deno",
+        supportsOwningAdopt: false,
+        produce: (view) => produceFfi(view, (region) => deno.UnsafePointer.value(deno.UnsafePointer.of(region))),
+        adopt: ({ pointer, byteLength }, opts) => {
+            const alias = denoAlias(deno, pointer, byteLength);
+            return finishAlias(alias, opts?.copy);
+        },
+        release: releaseFfi,
+        supportsSharedAdopt: false,
+        produceShared: (sab) => produceSharedFfi(sab, (region) => deno.UnsafePointer.value(deno.UnsafePointer.of(region))),
+        adoptShared: ({ pointer, byteLength }) => {
+            const alias = denoAlias(deno, pointer, byteLength);
+            return { buffer: alias, byteOffset: 0, byteLength, isShared: false };
+        },
+        releaseShared: releaseFfi,
+    };
+};
+const denoAlias = (deno, pointer, byteLength) => {
+    const handle = deno.UnsafePointer.create(pointer);
+    if (handle === null || handle === undefined) {
+        throw new Error("Deno.UnsafePointer.create returned null");
+    }
+    return new deno.UnsafePointerView(handle).getArrayBuffer(byteLength);
+};
+const createBunCapabilities = () => {
+    const ffi = getBunFFI();
+    return {
+        runtime: "bun",
+        supportsOwningAdopt: false,
+        produce: (view) => produceFfi(view, (region) => BigInt(ffi.ptr(region))),
+        adopt: ({ pointer, byteLength }, opts) => {
+            const alias = ffi.toArrayBuffer(Number(pointer), 0, byteLength);
+            return finishAlias(alias, opts?.copy);
+        },
+        release: releaseFfi,
+        supportsSharedAdopt: false,
+        produceShared: (sab) => produceSharedFfi(sab, (region) => BigInt(ffi.ptr(region))),
+        adoptShared: ({ pointer, byteLength }) => {
+            const alias = ffi.toArrayBuffer(Number(pointer), 0, byteLength);
+            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.
+// ---------------------------------------------------------------------------
+const createNodeCapabilities = () => {
+    const addon = loadNodeBufferPointerAddon();
+    const owning = typeof addon.retainBackingStore === "function" &&
+        typeof addon.adoptBackingStore === "function" &&
+        typeof addon.releaseBackingStore === "function";
+    // SABs use JS pins plus non-owning aliases so no native handle survives teardown.
+    const sharedCapabilities = {
+        supportsSharedAdopt: false,
+        produceShared: (sab) => produceSharedFfi(sab, (region) => addon.getPointer(region)),
+        adoptShared: ({ pointer, byteLength }) => {
+            const alias = addon.wrapPointer(pointer, byteLength);
+            return { buffer: alias, byteOffset: 0, byteLength, isShared: false };
+        },
+        releaseShared: releaseFfi,
+    };
+    if (owning) {
+        return {
+            runtime: "node",
+            supportsOwningAdopt: true,
+            produce: (source) => {
+                assertMovableSource(source);
+                const r = addon.retainBackingStore(source);
+                return {
+                    token: r.token,
+                    pointer: r.pointer,
+                    byteOffset: r.byteOffset,
+                    byteLength: r.byteLength,
+                };
+            },
+            adopt: ({ token, byteOffset, byteLength }, opts) => {
+                const buffer = addon.adoptBackingStore(token);
+                if (opts?.copy) {
+                    const owned = buffer.slice(byteOffset, byteOffset + byteLength);
+                    return { buffer: owned, byteOffset: 0, byteLength: owned.byteLength };
+                }
+                return { buffer, byteOffset, byteLength };
+            },
+            release: (token) => void addon.releaseBackingStore(token),
+            ...sharedCapabilities,
+        };
+    }
+    // Legacy fallback: producer pins via retainPointer, consumer wraps non-owning.
+    return {
+        runtime: "node",
+        supportsOwningAdopt: false,
+        produce: (source) => {
+            assertMovableSource(source);
+            const retained = addon.retainPointer(source);
+            const byteOffset = ArrayBuffer.isView(source) ? source.byteOffset : 0;
+            return {
+                token: retained.token,
+                pointer: retained.pointer,
+                byteOffset,
+                byteLength: retained.byteLength,
+            };
+        },
+        adopt: ({ pointer, byteLength }, opts) => {
+            const alias = addon.wrapPointer(pointer, byteLength);
+            return finishAlias(alias, opts?.copy);
+        },
+        release: (token) => void addon.releasePointer(token),
+        ...sharedCapabilities,
+    };
+};
+let cached;
+export const getBufferReferenceCapabilities = () => {
+    if (cached !== undefined)
+        return cached;
+    switch (RUNTIME) {
+        case "node":
+            return cached = createNodeCapabilities();
+        case "deno":
+            return cached = createDenoCapabilities();
+        case "bun":
+            return cached = createBunCapabilities();
+        default:
+            throw new Error(`BufferReference cannot run in runtime "${RUNTIME}"`);
+    }
+};

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

@@ -0,0 +1,78 @@
+import { type BufferReferenceRuntime } from "./buffer-reference-native.js";
+export type { BufferReferenceRuntime } from "./buffer-reference-native.js";
+export declare const BUFFER_REFERENCE_KIND: "knitting.bufferReference";
+/** Named values for the `unsafe.BufferReferenceReturn` pool option. */
+export declare const BufferReferenceReturn: {
+    /** Safe default: Deno/Bun copy the returned bytes so they outlive the worker. */
+    readonly Copy: "copy";
+    /** Zero-copy: borrow the worker's backing store until the reference is released. */
+    readonly Borrow: "borrow";
+};
+export type BufferReferenceReturn = (typeof BufferReferenceReturn)[keyof typeof BufferReferenceReturn];
+export declare const BUFFER_REFERENCE_NUMERIC_TRANSFER: unique symbol;
+export declare const BUFFER_REFERENCE_RETURN_RELEASE_TOKEN: unique symbol;
+declare const EXTERNAL_PAYLOAD_BRAND: unique symbol;
+export declare const BUFFER_REFERENCE_CODEC_ID: "knitting.bufferReference";
+declare const BUFFER_REFERENCE_RETURN_RELEASE_MESSAGE_KEY = "__knittingBufferReferenceRelease";
+export type BufferReferenceNumericMetadata = readonly [
+    pointerLow: number,
+    pointerHigh: number,
+    tokenLow: number,
+    tokenHigh: number,
+    byteOffset: number,
+    byteLength: number,
+    runtime: number,
+    originPid: number
+];
+export type BufferReferenceMetadata = {
+    readonly kind: typeof BUFFER_REFERENCE_KIND;
+    readonly origin: string;
+    readonly runtime: BufferReferenceRuntime;
+    readonly pointer: string;
+    /** Producer-side release handle (process-local). */
+    readonly token: string;
+    readonly byteOffset: number;
+    readonly byteLength: number;
+};
+export type BufferReferenceReturnReleaseMessage = {
+    readonly [BUFFER_REFERENCE_RETURN_RELEASE_MESSAGE_KEY]: string;
+};
+type BufferReferenceReturnReleaser = (token: bigint) => 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 createBufferReferenceReturnReleaseMessage: (token: bigint) => BufferReferenceReturnReleaseMessage;
+export declare const readBufferReferenceReturnReleaseMessage: (value: unknown) => bigint | undefined;
+export declare const isBufferReferenceMetadata: (value: unknown) => value is BufferReferenceMetadata;
+/**
+ * Zero-copy handle for moving ArrayBuffer bytes to/from **thread** workers.
+ *
+ * Construction detaches the source. Consumers materialize the moved region in
+ * their isolate: owning on Node, alias/copy on Deno/Bun. Return a
+ * `BufferReference` for large binary results to avoid copying back through the
+ * transport. Use `ProcessSharedBuffer` across process boundaries.
+ */
+export declare class BufferReference {
+    #private;
+    readonly [EXTERNAL_PAYLOAD_BRAND]: "knitting.bufferReference";
+    readonly runtime: BufferReferenceRuntime;
+    readonly origin: string;
+    readonly pointer: bigint;
+    readonly byteOffset: number;
+    readonly byteLength: number;
+    constructor(source: BufferSource);
+    constructor(source: BufferSource | undefined, meta: BufferReferenceMetadata);
+    static fromMetadata(meta: BufferReferenceMetadata): BufferReference;
+    toMetadata(): BufferReferenceMetadata;
+    [BUFFER_REFERENCE_NUMERIC_TRANSFER](): BufferReferenceNumericMetadata | undefined;
+    get isLocal(): boolean;
+    /** Prepare a returned reference before the worker-side producer hold drains. */
+    claimOwnership(releaser?: BufferReferenceReturnReleaser): this;
+    toArrayBuffer(): ArrayBuffer;
+    toUint8Array(): Uint8Array;
+    /** The source is moved on construction, so it is never retained here. */
+    get source(): undefined;
+    release(): void;
+    [Symbol.dispose](): void;
+    [PAYLOAD_TRANSPORT_FINALIZER](): (() => void) | undefined;
+}