knitting 0.1.51 → 0.1.52

package/src/runtime/tx-queue.js

@@ -1,6 +1,7 @@
-import { makeTask, resetTaskLocalFlags, TaskIndex, } from "../memory/lock.js";
+import { makeTask, resetTaskLocalFlags, runTaskFinalizers, TaskIndex, } from "../memory/lock.js";
 import { withResolvers } from "../common/with-resolvers.js";
 import { AbortSignalPoolExhausted, OneShotDeferred, } from "../shared/abortSignal.js";
+import { withBufferReferenceReturnReleaser } from "../connections/buffer-reference.js";
 const SLOT_INDEX_MASK = 31;
 const SLOT_META_MASK = 0x07ffffff;
 const SLOT_META_SHIFT = 5;
@@ -10,7 +11,7 @@ const FUNCTION_META_SHIFT = 16;
 const ABORT_SIGNAL_META_OFFSET = 1;
 const NO_ABORT_SIGNAL = -1;
 const p_now = performance.now.bind(performance);
-export function createHostTxQueue({ max, lock, returnLock, abortSignals, now, }) {
+export function createHostTxQueue({ max, lock, returnLock, releaseBufferReferenceReturn, abortSignals, now, }) {
     const PLACE_HOLDER = (_) => {
         throw ("UNREACHABLE FROM PLACE HOLDER (main)");
     };
@@ -26,7 +27,6 @@ export function createHostTxQueue({ max, lock, returnLock, abortSignals, now, })
     const initialSize = max ?? 10;
     const queue = Array.from({ length: initialSize }, (_, index) => newSlot(index));
     const freeSockets = Array.from({ length: initialSize }, (_, i) => i);
-    // Local count
     const freePush = (id) => freeSockets.push(id);
     const freePop = () => freeSockets.pop();
     const queuePush = (task) => queue.push(task);
@@ -40,13 +40,16 @@ export function createHostTxQueue({ max, lock, returnLock, abortSignals, now, })
         onResolved: (task) => {
             inUsed = (inUsed - 1) | 0;
             resetTaskLocalFlags(task);
+            runTaskFinalizers(task);
             task.value = null;
             task.resolve = PLACE_HOLDER;
             task.reject = PLACE_HOLDER;
             freePush(task[TaskIndex.ID]);
         },
     });
-    // Helpers
+    const completeFrame = releaseBufferReferenceReturn === undefined
+        ? resolveReturn
+        : () => withBufferReferenceReturnReleaser(releaseBufferReferenceReturn, resolveReturn);
     const txIdle = () => getPendingFrameCount() === 0 && inUsed === getPendingPromiseCount();
     const rejectAll = (reason) => {
         for (let index = 0; index < queue.length; index++) {
@@ -57,6 +60,7 @@ export function createHostTxQueue({ max, lock, returnLock, abortSignals, now, })
                 }
                 catch {
                 }
+                runTaskFinalizers(slot);
                 slot.resolve = PLACE_HOLDER;
                 slot.reject = PLACE_HOLDER;
                 queue[index] = newSlot(index);
@@ -73,13 +77,13 @@ export function createHostTxQueue({ max, lock, returnLock, abortSignals, now, })
         rejectAll,
         hasPendingFrames,
         txIdle,
-        completeFrame: resolveReturn,
+        completeFrame,
         enqueue: (functionID, timeout, abortSignal) => {
             const HAS_TIMER = timeout !== undefined;
             const functionIDMasked = functionID & FUNCTION_ID_MASK;
-            const USE_SIGNAL = abortSignal !== undefined && abortSignals !== undefined;
+            const USE_SIGNAL = abortSignal !== undefined &&
+                abortSignals !== undefined;
             return (rawArgs) => {
-                // Expanding size if needed
                 if (inUsed === queue.length) {
                     const newSize = inUsed + 32;
                     let current = queue.length;
@@ -101,19 +105,19 @@ export function createHostTxQueue({ max, lock, returnLock, abortSignals, now, })
                     new OneShotDeferred(deferred, () => resetSignal(maybeSignal), () => {
                         abortSignals.setSignal(maybeSignal);
                     });
-                    const encodedSignalMeta = ((maybeSignal + ABORT_SIGNAL_META_OFFSET) & FUNCTION_META_MASK) >>> 0;
+                    const encodedSignalMeta = ((maybeSignal + ABORT_SIGNAL_META_OFFSET) & FUNCTION_META_MASK) >>>
+                        0;
                     slot[TaskIndex.FunctionID] =
-                        ((encodedSignalMeta << FUNCTION_META_SHIFT) | functionIDMasked) >>> 0;
+                        ((encodedSignalMeta << FUNCTION_META_SHIFT) | functionIDMasked) >>>
+                            0;
                 }
-                // Set info
                 slot.value = rawArgs;
                 slot[TaskIndex.ID] = index;
                 slot.resolve = deferred.resolve;
                 slot.reject = deferred.reject;
                 if (HAS_TIMER) {
-                    slot[TaskIndex.slotBuffer] =
-                        ((slot[TaskIndex.slotBuffer] & SLOT_INDEX_MASK) |
-                            ((((nowTime() >>> 0) & SLOT_META_MASK) << SLOT_META_SHIFT) >>> 0)) >>> 0;
+                    slot[TaskIndex.slotBuffer] = ((slot[TaskIndex.slotBuffer] & SLOT_INDEX_MASK) |
+                        ((((nowTime() >>> 0) & SLOT_META_MASK) << SLOT_META_SHIFT) >>> 0)) >>> 0;
                 }
                 void publish(slot);
                 inUsed = (inUsed + 1) | 0;
@@ -132,6 +136,7 @@ export function createHostTxQueue({ max, lock, returnLock, abortSignals, now, })
                 catch {
                 }
                 resetTaskLocalFlags(task);
+                runTaskFinalizers(task);
                 task.value = null;
                 task.resolve = PLACE_HOLDER;
                 task.reject = PLACE_HOLDER;

package/src/types.d.ts

@@ -1,5 +1,5 @@
 import { endpointSymbol } from "./common/task-symbol.js";
-import type { Envelope } from "./common/envelope.js";
+import type { Envelope, EnvelopeBody, EnvelopeHeader } from "./common/envelope.js";
 import type { LockBufferTextCompat, SharedBufferTextCompat } from "./common/shared-buffer-text.js";
 import type { SharedBufferRegion, SharedBufferSource } from "./common/shared-buffer-region.js";
 import type { PayloadBufferMode, PayloadBufferOptions } from "./memory/payload-config.js";
@@ -32,8 +32,18 @@ type WorkerData = {
     lock: LockBuffers;
     returnLock: LockBuffers;
     payloadConfig?: PayloadBufferOptions;
+    bufferReferenceReturn?: "copy" | "borrow";
     permission?: ResolvedPermissionProtocol;
 };
+type UnsafeOptions = {
+    /**
+     * Experimental `BufferReference` return lifetime.
+     *
+     * `"copy"` is safe after worker release. `"borrow"` skips the Deno/Bun copy,
+     * but must be released before producer shutdown and must not outlive its ref.
+     */
+    BufferReferenceReturn?: "copy" | "borrow";
+};
 type LockBuffers = {
     headers: SharedBufferSource;
     headerSlotStrideU32?: number;
@@ -49,7 +59,7 @@ interface JSONObject {
 interface JSONArray extends Array<JSONValue> {
 }
 type Serializable = string | object | number | boolean | bigint;
-type ValidInput = bigint | void | JSONValue | symbol | ArrayBuffer | Uint8Array | Int32Array | Float64Array | BigInt64Array | BigUint64Array | DataView | Error | Date | Envelope;
+type ValidInput = bigint | void | JSONValue | symbol | ArrayBuffer | Uint8Array | Int32Array | Float64Array | BigInt64Array | BigUint64Array | DataView | Error | Date | Envelope<EnvelopeHeader, EnvelopeBody>;
 type Args = ValidInput | Serializable;
 type MaybePromise<T> = T | Promise<T>;
 type NoBlob<T> = T extends Blob ? never : T;
@@ -88,13 +98,16 @@ type tasks = Record<string, Composed<any, any, AbortSignalOption> | TaskFunction
 type ComposedWithKey = Composed<any, any, AbortSignalOption> & {
     name: string;
 };
-type PromiseWrapped<F extends (...args: any[]) => any, AS extends AbortSignalOption = undefined> = (...args: PromisifyCallArgs<F, AS>) => (AS extends undefined ? Promise<Awaited<ReturnType<F>>> : PromiseWithMaybeReject<Awaited<ReturnType<F>>>);
+type PromiseWrapped<F extends (...args: any[]) => any, AS extends AbortSignalOption = undefined> = (...args: PromisifyCallArgs<F, AS>) => AS extends undefined ? Promise<Awaited<ReturnType<F>>> : PromiseWithMaybeReject<Awaited<ReturnType<F>>>;
 type PromiseInput<T> = T | Promise<T>;
 type PromisifyArgs<T extends unknown[]> = {
     [K in keyof T]: PromiseInput<T[K]>;
 };
 type NormalizeUndefinedSingleArg<T extends unknown[]> = T extends [undefined] ? [] | [undefined] : T;
-type AbortAwareCallArgs<T extends unknown[]> = T extends [...infer Head, AbortSignalToolkit<any>] ? NormalizeUndefinedSingleArg<Head> : NormalizeUndefinedSingleArg<T>;
+type AbortAwareCallArgs<T extends unknown[]> = T extends [
+    ...infer Head,
+    AbortSignalToolkit<any>
+] ? NormalizeUndefinedSingleArg<Head> : NormalizeUndefinedSingleArg<T>;
 type HostCallArgs<F extends (...args: any[]) => any, AS extends AbortSignalOption> = AS extends undefined ? Parameters<F> : AbortAwareCallArgs<Parameters<F>>;
 type PromisifyCallArgs<F extends (...args: any[]) => any, AS extends AbortSignalOption> = HostCallArgs<F, AS> extends infer T ? T extends unknown[] ? PromisifyArgs<T> : never : never;
 type TaskCallable<T> = T extends TaskLike<any> ? T["f"] : T extends TaskFunctionLike ? T : never;
@@ -120,20 +133,11 @@ type ImportTaskOptions<A extends TaskInput = void, B extends Args = void, AS ext
 type SecondPart = {
     readonly [endpointSymbol]: true;
     readonly id: number;
-    /**
-     * IMPORTANT: `at` helps to create a `createPool` because we dont know
-     * the name of the variable at runtime, so basically this gets the logical order
-     * of the exported file, so no matter the name the worker can track which ` task `
-     * to track
-     */
+    /** Logical export order used to match worker tasks before names are known. */
     readonly at: number;
     readonly importedFrom: string;
     /**
-     * Marks a task whose worker-side function is imported dynamically (via
-     * `importTask`). Such tasks must never run on the host inliner lane: their
-     * module import is meant to happen inside the worker so worker permission
-     * policies apply. The pool routes them to worker lanes only, even when the
-     * inliner is enabled for other tasks.
+     * Imported tasks stay on worker lanes so imports run under worker permissions.
      */
     readonly imported?: boolean;
 };
@@ -278,8 +282,8 @@ type DispatcherSettings = {
 type CreatePool = {
     threads?: number;
     /**
-   * @deprecated Too risky with processes, need to rewrite or delete.
-   */
+     * @deprecated Too risky with processes, need to rewrite or delete.
+     */
     inliner?: Inliner;
     balancer?: Balancer;
     worker?: WorkerSettings;
@@ -287,6 +291,10 @@ type CreatePool = {
      * Payload transport settings.
      */
     payload?: PayloadBufferOptions;
+    /**
+     * Experimental unsafe options.
+     */
+    unsafe?: UnsafeOptions;
     /**
      * Initial payload SharedArrayBuffer size (bytes) per worker direction.
      * Defaults to 4 MiB when growable SAB is available, otherwise defaults to
@@ -336,7 +344,7 @@ type CreatePool = {
     debug?: DebugOptions;
     source?: string;
 };
-export type { WorkerCall as WorkerCall, WorkerInvoke as WorkerInvoke, WorkerContext as WorkerContext, CreateContext as CreateContext, WorkerData as WorkerData, LockBuffers as LockBuffers, ValidInput as ValidInput, Args as Args, MaybePromise as MaybePromise, TaskInput as TaskInput, TaskTimeout as TaskTimeout, TaskFn as TaskFn, AbortSignalConfig as AbortSignalConfig, AbortSignalOption as AbortSignalOption, AbortSignalMethods as AbortSignalMethods, AbortSignalToolkit as AbortSignalToolkit, Composed as Composed, tasks as tasks, ComposedWithKey as ComposedWithKey, FunctionMapType as FunctionMapType, FixPoint as FixPoint, ImportTaskOptions as ImportTaskOptions, SecondPart as SecondPart, SingleTaskPool as SingleTaskPool, Pool as Pool, ReturnFixed as ReturnFixed, External as External, Inliner as Inliner, BalancerStrategy as BalancerStrategy, Balancer as Balancer, DebugOptions as DebugOptions, WorkerBootstrapContext as WorkerBootstrapContext, WorkerBootstrapFunction as WorkerBootstrapFunction, WorkerBootstrapOptions as WorkerBootstrapOptions, WorkerSettings as WorkerSettings, ProcessSharedMemoryMode as ProcessSharedMemoryMode, ProcessSharedMemorySettings as ProcessSharedMemorySettings, WorkerTimers as WorkerTimers, DispatcherSettings as DispatcherSettings, CreatePool as CreatePool, PayloadBufferMode as PayloadBufferMode, PayloadBufferOptions as PayloadBufferOptions, PermissionProtocol as PermissionProtocol, PermissionProtocolInput as PermissionProtocolInput, ResolvedPermissionProtocol as ResolvedPermissionProtocol, Envelope as Envelope, SharedBufferTextCompat as SharedBufferTextCompat, LockBufferTextCompat as LockBufferTextCompat, SharedBufferRegion as SharedBufferRegion, SharedBufferSource as SharedBufferSource, };
+export type { AbortSignalConfig as AbortSignalConfig, AbortSignalMethods as AbortSignalMethods, AbortSignalOption as AbortSignalOption, AbortSignalToolkit as AbortSignalToolkit, Args as Args, Balancer as Balancer, BalancerStrategy as BalancerStrategy, Composed as Composed, ComposedWithKey as ComposedWithKey, CreateContext as CreateContext, CreatePool as CreatePool, DebugOptions as DebugOptions, DispatcherSettings as DispatcherSettings, Envelope as Envelope, EnvelopeBody as EnvelopeBody, EnvelopeHeader as EnvelopeHeader, External as External, FixPoint as FixPoint, FunctionMapType as FunctionMapType, ImportTaskOptions as ImportTaskOptions, Inliner as Inliner, LockBuffers as LockBuffers, LockBufferTextCompat as LockBufferTextCompat, MaybePromise as MaybePromise, PayloadBufferMode as PayloadBufferMode, PayloadBufferOptions as PayloadBufferOptions, PermissionProtocol as PermissionProtocol, PermissionProtocolInput as PermissionProtocolInput, Pool as Pool, ProcessSharedMemoryMode as ProcessSharedMemoryMode, ProcessSharedMemorySettings as ProcessSharedMemorySettings, ResolvedPermissionProtocol as ResolvedPermissionProtocol, ReturnFixed as ReturnFixed, SecondPart as SecondPart, SharedBufferRegion as SharedBufferRegion, SharedBufferSource as SharedBufferSource, SharedBufferTextCompat as SharedBufferTextCompat, SingleTaskPool as SingleTaskPool, TaskFn as TaskFn, TaskInput as TaskInput, tasks as tasks, TaskTimeout as TaskTimeout, ValidInput as ValidInput, WorkerBootstrapContext as WorkerBootstrapContext, WorkerBootstrapFunction as WorkerBootstrapFunction, WorkerBootstrapOptions as WorkerBootstrapOptions, WorkerCall as WorkerCall, WorkerContext as WorkerContext, WorkerData as WorkerData, WorkerInvoke as WorkerInvoke, WorkerSettings as WorkerSettings, WorkerTimers as WorkerTimers, };
 export type { Task as Task } from "./memory/lock.js";
 export { LockBound as LockBound, PayloadBuffer as PayloadBuffer, PayloadSignal as PayloadSignal, TaskIndex as TaskIndex, } from "./memory/lock.js";
 export type { RegisterMalloc as RegisterMalloc } from "./memory/regionRegistry.js";

package/src/utils/http.d.ts

@@ -0,0 +1,21 @@
+export type BufferLike = ArrayBuffer | SharedArrayBuffer | ArrayBufferView;
+export type NumberFormat = "f64" | "f32" | "i32";
+export type NumberBufferOptions = {
+    format?: NumberFormat;
+};
+export declare const bufferToBytes: (source: BufferLike) => Uint8Array;
+export declare const bytesToBuffer: (source: BufferLike) => SharedArrayBuffer;
+export declare const bufferToString: (source: BufferLike) => string;
+export declare const stringToBuffer: (text: string) => SharedArrayBuffer;
+export declare const bufferToJson: <T = unknown>(source: BufferLike) => T;
+export declare const jsonToBuffer: (value: unknown) => SharedArrayBuffer;
+export declare const numbersToBuffer: (numbers: ArrayLike<number>, options?: NumberBufferOptions) => SharedArrayBuffer;
+export declare function bufferToNumbers(source: BufferLike, options?: {
+    format?: "f64";
+}): Float64Array;
+export declare function bufferToNumbers(source: BufferLike, options: {
+    format: "f32";
+}): Float32Array;
+export declare function bufferToNumbers(source: BufferLike, options: {
+    format: "i32";
+}): Int32Array;

package/src/utils/http.js

@@ -0,0 +1,93 @@
+const nodeBuffer = globalThis.Buffer;
+const hasNodeBuffer = typeof nodeBuffer?.from === "function" &&
+    typeof nodeBuffer?.byteLength === "function";
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+const hasSharedArrayBuffer = typeof SharedArrayBuffer === "function";
+const isSharedArrayBuffer = (value) => hasSharedArrayBuffer && value instanceof SharedArrayBuffer;
+const BYTES_PER_ELEMENT = {
+    f64: 8,
+    f32: 4,
+    i32: 4,
+};
+const toBytes = (source) => {
+    if (source instanceof Uint8Array)
+        return source;
+    if (ArrayBuffer.isView(source)) {
+        return new Uint8Array(source.buffer, source.byteOffset, source.byteLength);
+    }
+    if (source instanceof ArrayBuffer || isSharedArrayBuffer(source)) {
+        return new Uint8Array(source);
+    }
+    throw new TypeError("Expected an ArrayBuffer, SharedArrayBuffer, or typed-array view.");
+};
+export const bufferToBytes = (source) => toBytes(source);
+export const bytesToBuffer = (source) => {
+    const bytes = toBytes(source);
+    const sab = new SharedArrayBuffer(bytes.byteLength);
+    new Uint8Array(sab).set(bytes);
+    return sab;
+};
+const makeNumberView = (format, buffer, byteOffset, length) => {
+    switch (format) {
+        case "f64":
+            return new Float64Array(buffer, byteOffset, length);
+        case "f32":
+            return new Float32Array(buffer, byteOffset, length);
+        case "i32":
+            return new Int32Array(buffer, byteOffset, length);
+    }
+};
+export const bufferToString = (source) => {
+    const bytes = toBytes(source);
+    if (hasNodeBuffer) {
+        return nodeBuffer
+            .from(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+            .toString("utf8");
+    }
+    return textDecoder.decode(bytes);
+};
+export const stringToBuffer = (text) => {
+    if (typeof text !== "string") {
+        throw new TypeError("stringToBuffer expects a string.");
+    }
+    if (hasNodeBuffer) {
+        const byteLength = nodeBuffer.byteLength(text, "utf8");
+        const sab = new SharedArrayBuffer(byteLength);
+        nodeBuffer.from(sab).write(text, "utf8");
+        return sab;
+    }
+    const encoded = textEncoder.encode(text);
+    const sab = new SharedArrayBuffer(encoded.byteLength);
+    new Uint8Array(sab).set(encoded);
+    return sab;
+};
+export const bufferToJson = (source) => JSON.parse(bufferToString(source));
+export const jsonToBuffer = (value) => {
+    const text = JSON.stringify(value);
+    if (typeof text !== "string") {
+        throw new TypeError("jsonToBuffer: value is not JSON-serializable (stringify returned undefined).");
+    }
+    return stringToBuffer(text);
+};
+export const numbersToBuffer = (numbers, options) => {
+    const format = options?.format ?? "f64";
+    const sab = new SharedArrayBuffer(numbers.length * BYTES_PER_ELEMENT[format]);
+    makeNumberView(format, sab, 0, numbers.length).set(numbers);
+    return sab;
+};
+export function bufferToNumbers(source, options) {
+    const format = options?.format ?? "f64";
+    const bytesPer = BYTES_PER_ELEMENT[format];
+    const bytes = toBytes(source);
+    if (bytes.byteLength % bytesPer !== 0) {
+        throw new RangeError(`bufferToNumbers: byte length ${bytes.byteLength} is not a multiple of ` +
+            `${bytesPer} for format "${format}".`);
+    }
+    const length = bytes.byteLength / bytesPer;
+    if (bytes.byteOffset % bytesPer === 0) {
+        return makeNumberView(format, bytes.buffer, bytes.byteOffset, length);
+    }
+    const copy = bytes.slice();
+    return makeNumberView(format, copy.buffer, 0, length);
+}

package/src/worker/loop.js

@@ -1,4 +1,4 @@
-import { createRuntimeMessageChannel, RUNTIME_IS_MAIN_THREAD, RUNTIME_IS_PROCESS_WORKER, RUNTIME_PARENT_PORT, RUNTIME_WORKER_DATA, } from "../common/worker-runtime.js";
+import { addRuntimeDataListener, createRuntimeMessageChannel, RUNTIME_IS_MAIN_THREAD, RUNTIME_IS_PROCESS_WORKER, RUNTIME_PARENT_PORT, RUNTIME_WORKER_DATA, } from "../common/worker-runtime.js";
 import { isSharedBufferSource } from "../common/shared-buffer-region.js";
 import { isLockBufferTextCompat } from "../common/shared-buffer-text.js";
 import { createWorkerRxQueue } from "./rx-queue.js";
@@ -12,6 +12,7 @@ import { assertWorkerImportsResolved, assertWorkerSharedMemoryBootData, installP
 import { signalAbortFactory } from "../shared/abortSignal.js";
 import { runWorkerBootstrap } from "./bootstrap.js";
 import { getProcessWorkerNativeWaitU32, installProcessWorkerBootstrap, } from "./process-worker-bootstrap.js";
+import { readBufferReferenceReturnReleaseMessage, } from "../connections/buffer-reference.js";
 const WORKER_FATAL_MESSAGE_KEY = "__knittingWorkerFatal";
 const reportWorkerStartupFatal = (error) => {
     const message = String(error?.message ?? error);
@@ -48,12 +49,27 @@ const reportWorkerStartupFatal = (error) => {
         }
     }
 };
+const installBufferReferenceReleaseListener = (releaseReturnedBufferReference) => {
+    const handleMessage = (message) => {
+        const token = readBufferReferenceReturnReleaseMessage(message);
+        if (token !== undefined)
+            releaseReturnedBufferReference(token);
+    };
+    if (RUNTIME_PARENT_PORT !== undefined) {
+        addRuntimeDataListener(RUNTIME_PARENT_PORT, handleMessage);
+        return;
+    }
+    const scope = globalThis;
+    scope.addEventListener?.("message", (event) => {
+        handleMessage(event?.data);
+    });
+};
 export const workerMainLoop = async (startupData) => {
     // Startup-only safety layer: no per-iteration checks in the hot loop.
     installTerminationGuard();
     installUnhandledRejectionSilencer();
     installPerformanceNowGuard();
-    const { debug, sab, thread, startAt, workerOptions, lock, returnLock, abortSignalSAB, abortSignalMax, payloadConfig, permission, totalNumberOfThread, list, ids, names, at, } = startupData;
+    const { debug, sab, thread, startAt, workerOptions, lock, returnLock, abortSignalSAB, abortSignalMax, payloadConfig, bufferReferenceReturn, permission, totalNumberOfThread, list, ids, names, at, } = startupData;
     scrubWorkerDataSensitiveBuffers(startupData);
     assertWorkerSharedMemoryBootData({ sab, lock, returnLock });
     let Comment;
@@ -122,13 +138,15 @@ export const workerMainLoop = async (startupData) => {
             maxSignals: abortSignalMax,
         })
         : undefined;
-    const { enqueueLock, serviceBatchImmediate, hasCompleted, writeBatch, hasPending, getAwaiting, } = createWorkerRxQueue({
+    const { enqueueLock, serviceBatchImmediate, hasCompleted, writeBatch, hasPending, getAwaiting, drainReturnReleases, releaseReturnedBufferReference, } = createWorkerRxQueue({
         listOfFunctions,
         workerOptions,
         lock: lockState,
         returnLock: returnLockState,
+        borrowReturnedBufferReferences: bufferReferenceReturn === "borrow",
         hasAborted: abortSignals?.hasAborted,
     });
+    installBufferReferenceReleaseListener(releaseReturnedBufferReference);
     a_store(rxStatus, 0, 1);
     const WRITE_MAX = 64;
     const pauseUntil = sleepUntilChanged({
@@ -183,6 +201,7 @@ export const workerMainLoop = async (startupData) => {
     const _hasPending = hasPending;
     const _serviceBatchImmediate = serviceBatchImmediate;
     const _getAwaiting = getAwaiting;
+    const _drainReturnReleases = drainReturnReleases;
     const _pauseSpin = pauseSpin;
     const _pauseUntil = pauseUntil;
     const loop = () => {
@@ -195,6 +214,7 @@ export const workerMainLoop = async (startupData) => {
                 if (_writeBatch(WRITE_MAX) > 0)
                     progressed = true;
             }
+            _drainReturnReleases();
             if (_hasPending()) {
                 if (_serviceBatchImmediate() > 0)
                     progressed = true;

package/src/worker/rx-queue.d.ts

@@ -6,16 +6,19 @@ type ArgumentsForCreateWorkerQueue = {
     workerOptions?: WorkerSettings;
     lock: Lock2;
     returnLock: Lock2;
+    borrowReturnedBufferReferences?: boolean;
     hasAborted?: (signal: number) => boolean;
     now?: () => number;
 };
 export type CreateWorkerRxQueue = ReturnType<typeof createWorkerRxQueue>;
-export declare const createWorkerRxQueue: ({ listOfFunctions, workerOptions, lock, returnLock, hasAborted, now, }: ArgumentsForCreateWorkerQueue) => {
+export declare const createWorkerRxQueue: ({ listOfFunctions, workerOptions, lock, returnLock, borrowReturnedBufferReferences, hasAborted, now, }: ArgumentsForCreateWorkerQueue) => {
     hasCompleted: () => boolean;
     hasPending: () => boolean;
     writeBatch: (max: number) => number;
     serviceBatchImmediate: () => number;
     enqueueLock: () => boolean;
+    drainReturnReleases: () => void;
+    releaseReturnedBufferReference: (token: bigint) => void;
     hasAwaiting: () => boolean;
     getAwaiting: () => number;
 };

package/src/worker/rx-queue.js

@@ -1,8 +1,8 @@
 import RingQueue from "../ipc/tools/ring-queue.js";
-import { TaskFlag, TaskIndex, } from "../memory/lock.js";
+import { attachPayloadTransportFinalizer, runTaskFinalizers, TaskFlag, TaskIndex, } from "../memory/lock.js";
 import { composeWorkerRunner } from "./composable-runners.js";
-// Create and manage a working queue.
-export const createWorkerRxQueue = ({ listOfFunctions, workerOptions, lock, returnLock, hasAborted, now, }) => {
+import { BUFFER_REFERENCE_RETURN_RELEASE_TOKEN } from "../connections/buffer-reference.js";
+export const createWorkerRxQueue = ({ listOfFunctions, workerOptions, lock, returnLock, borrowReturnedBufferReferences, hasAborted, now, }) => {
     const PLACE_HOLDER = (_) => {
         throw ("UNREACHABLE FROM PLACE HOLDER (thread)");
     };
@@ -20,6 +20,41 @@ export const createWorkerRxQueue = ({ listOfFunctions, workerOptions, lock, retu
     const FUNCTION_ID_MASK = 0xFFFF;
     const IDX_FLAGS = TaskIndex.FlagsToHost;
     const FLAG_REJECT = TaskFlag.Reject;
+    // Return-payload finalizers wait until the host consumes the return.
+    // Quiescence (hostBits XOR workerBits == 0) lets us release them in batch.
+    const a_load = Atomics.load;
+    const returnHostBits = returnLock.hostBits;
+    const returnWorkerBits = returnLock.workerBits;
+    const deferredReleases = [];
+    const explicitReturnReleases = new Map();
+    const drainReturnReleases = () => {
+        if (deferredReleases.length === 0)
+            return;
+        if ((a_load(returnHostBits, 0) ^ a_load(returnWorkerBits, 0)) !== 0)
+            return;
+        for (let i = 0; i < deferredReleases.length; i++) {
+            try {
+                deferredReleases[i]();
+            }
+            catch {
+                // best effort
+            }
+        }
+        deferredReleases.length = 0;
+    };
+    const releaseReturnedBufferReference = (token) => {
+        const key = token.toString();
+        const release = explicitReturnReleases.get(key);
+        if (release === undefined)
+            return;
+        explicitReturnReleases.delete(key);
+        try {
+            release();
+        }
+        catch {
+            // best effort
+        }
+    };
     const runByIndex = listOfFunctions.reduce((acc, fixed, idx) => {
         const job = jobs[idx];
         acc.push(composeWorkerRunner({
@@ -42,6 +77,7 @@ export const createWorkerRxQueue = ({ listOfFunctions, workerOptions, lock, retu
         while (task) {
             task.resolve = PLACE_HOLDER;
             task.reject = PLACE_HOLDER;
+            attachPayloadTransportFinalizer(task, task.value);
             toWorkPush(task);
             task = resolvedShift();
         }
@@ -56,11 +92,23 @@ export const createWorkerRxQueue = ({ listOfFunctions, workerOptions, lock, retu
         slot[IDX_FLAGS] = shouldReject ? FLAG_REJECT : 0;
         if (!encodeReturnSafe(slot))
             return false;
+        // Preserve return finalizers past slot recycle; release after drain.
+        if (slot.finalize !== undefined) {
+            const token = slot.finalize[BUFFER_REFERENCE_RETURN_RELEASE_TOKEN];
+            if (token === undefined || borrowReturnedBufferReferences !== true) {
+                deferredReleases.push(slot.finalize);
+            }
+            else {
+                explicitReturnReleases.set(token.toString(), slot.finalize);
+            }
+            slot.finalize = undefined;
+        }
         hasAnythingFinished--;
         recyclePush(slot);
         return true;
     };
     const settleNow = (slot, isError, value, wasAwaited) => {
+        runTaskFinalizers(slot);
         slot.value = value;
         hasAnythingFinished++;
         if (wasAwaited && awaiting > 0)
@@ -99,7 +147,6 @@ export const createWorkerRxQueue = ({ listOfFunctions, workerOptions, lock, retu
                 try {
                     const fnIndex = slot[TaskIndex.FunctionID] & FUNCTION_ID_MASK;
                     const result = runByIndex[fnIndex](slot);
-                    // Slot 0 is reused for response flags; clear request FunctionID value.
                     slot[IDX_FLAGS] = 0;
                     slot.value = null;
                     if (result instanceof Promise) {
@@ -118,6 +165,8 @@ export const createWorkerRxQueue = ({ listOfFunctions, workerOptions, lock, retu
             return processed;
         },
         enqueueLock,
+        drainReturnReleases,
+        releaseReturnedBufferReference,
         hasAwaiting: () => awaiting > 0,
         getAwaiting: () => awaiting,
     };

package/unsafe.d.ts

@@ -0,0 +1 @@
+export { BUFFER_REFERENCE_CODEC_ID, BUFFER_REFERENCE_KIND, BufferReference, type BufferReferenceMetadata, BufferReferenceReturn, type BufferReferenceRuntime, isBufferReferenceMetadata, } from "./src/connections/buffer-reference.js";

package/unsafe.js

@@ -0,0 +1 @@
+export { BUFFER_REFERENCE_CODEC_ID, BUFFER_REFERENCE_KIND, BufferReference, BufferReferenceReturn, isBufferReferenceMetadata, } from "./src/connections/buffer-reference.js";

package/utils.d.ts

@@ -0,0 +1 @@
+export { type BufferLike, bufferToBytes, bufferToJson, bufferToNumbers, bufferToString, bytesToBuffer, jsonToBuffer, type NumberBufferOptions, type NumberFormat, numbersToBuffer, stringToBuffer, } from "./src/utils/http.js";

package/utils.js

@@ -0,0 +1 @@
+export { bufferToBytes, bufferToJson, bufferToNumbers, bufferToString, bytesToBuffer, jsonToBuffer, numbersToBuffer, stringToBuffer, } from "./src/utils/http.js";