knitting 0.1.51 → 0.1.52

package/src/memory/lock.js

@@ -54,6 +54,12 @@ export var PayloadBuffer;
     PayloadBuffer[PayloadBuffer["ExternalPayload"] = 44] = "ExternalPayload";
     PayloadBuffer[PayloadBuffer["StaticExternalPayload"] = 45] = "StaticExternalPayload";
     PayloadBuffer[PayloadBuffer["ProcessSharedBuffer"] = 46] = "ProcessSharedBuffer";
+    PayloadBuffer[PayloadBuffer["BufferReference"] = 47] = "BufferReference";
+    PayloadBuffer[PayloadBuffer["SharedArrayBuffer"] = 48] = "SharedArrayBuffer";
+    PayloadBuffer[PayloadBuffer["EnvelopeStaticHeaderExternal"] = 49] = "EnvelopeStaticHeaderExternal";
+    PayloadBuffer[PayloadBuffer["EnvelopeDynamicHeaderExternal"] = 50] = "EnvelopeDynamicHeaderExternal";
+    PayloadBuffer[PayloadBuffer["EnvelopeStaticHeaderStringExternal"] = 51] = "EnvelopeStaticHeaderStringExternal";
+    PayloadBuffer[PayloadBuffer["EnvelopeDynamicHeaderStringExternal"] = 52] = "EnvelopeDynamicHeaderStringExternal";
 })(PayloadBuffer || (PayloadBuffer = {}));
 export var LockBound;
 (function (LockBound) {
@@ -64,6 +70,7 @@ export var LockBound;
 })(LockBound || (LockBound = {}));
 export const LOCK_CACHE_LINE_BYTES = 64;
 export const LOCK_SECTOR_BYTES = 256;
+export const PayloadTransportFinalizer = Symbol.for("knitting.payloadCodec.transportFinalizer");
 export const PromisePayloadMarker = Symbol.for("knitting.promise.payload");
 const TASK_LOCAL_FLAGS_INDEX = 7;
 const TASK_LOCAL_PROMISE_PENDING_FLAG = 1 << 0;
@@ -72,7 +79,8 @@ export const beginPromisePayload = (task) => {
     const flags = task[TASK_LOCAL_FLAGS_INDEX];
     if ((flags & TASK_LOCAL_PROMISE_PENDING_FLAG) !== 0)
         return false;
-    task[TASK_LOCAL_FLAGS_INDEX] = (flags | TASK_LOCAL_PROMISE_PENDING_FLAG) >>> 0;
+    task[TASK_LOCAL_FLAGS_INDEX] = (flags | TASK_LOCAL_PROMISE_PENDING_FLAG) >>>
+        0;
     return true;
 };
 export const finishPromisePayload = (task) => {
@@ -83,6 +91,36 @@ export const isPromisePayloadPending = (task) => (task[TASK_LOCAL_FLAGS_INDEX] &
 export const resetTaskLocalFlags = (task) => {
     task[TASK_LOCAL_FLAGS_INDEX] = 0;
 };
+export const addTaskFinalizer = (task, finalizer) => {
+    const previous = task.finalize;
+    task.finalize = previous === undefined ? finalizer : () => {
+        try {
+            previous();
+        }
+        finally {
+            finalizer();
+        }
+    };
+};
+export const attachPayloadTransportFinalizer = (task, value) => {
+    if (task.finalize !== undefined || value === null || typeof value !== "object") {
+        return;
+    }
+    const finalizer = value[PayloadTransportFinalizer]?.();
+    if (typeof finalizer === "function")
+        addTaskFinalizer(task, finalizer);
+};
+export const runTaskFinalizers = (task) => {
+    const finalizer = task.finalize;
+    task.finalize = undefined;
+    if (finalizer !== undefined) {
+        try {
+            finalizer();
+        }
+        catch {
+        }
+    }
+};
 export var TaskIndex;
 (function (TaskIndex) {
     /**
@@ -186,6 +224,7 @@ const def = (_) => { };
 const createTaskShell = () => {
     const task = new Uint32Array(TaskIndex.Size);
     task.value = null;
+    task.finalize = undefined;
     task.resolve = def;
     task.reject = def;
     task[TASK_LOCAL_FLAGS_INDEX] = 0;
@@ -266,10 +305,12 @@ export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload,
         lockSector: payloadLockRegion,
         textCompat: resolvedTextCompat,
         onPromise: (task, isRejected, value) => {
-            if ((task[TASK_LOCAL_FLAGS_INDEX] & TASK_LOCAL_PROMISE_TRACKED_FLAG) !== 0 &&
+            if ((task[TASK_LOCAL_FLAGS_INDEX] & TASK_LOCAL_PROMISE_TRACKED_FLAG) !==
+                0 &&
                 pendingPromiseCount > 0) {
                 task[TASK_LOCAL_FLAGS_INDEX] =
-                    (task[TASK_LOCAL_FLAGS_INDEX] & ~TASK_LOCAL_PROMISE_TRACKED_FLAG) >>> 0;
+                    (task[TASK_LOCAL_FLAGS_INDEX] & ~TASK_LOCAL_PROMISE_TRACKED_FLAG) >>>
+                        0;
                 pendingPromiseCount = (pendingPromiseCount - 1) | 0;
             }
             promiseHandler(task, isRejected, value);
@@ -322,7 +363,8 @@ export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload,
         const flags = task[TASK_LOCAL_FLAGS_INDEX];
         if ((flags & TASK_LOCAL_PROMISE_TRACKED_FLAG) !== 0)
             return;
-        task[TASK_LOCAL_FLAGS_INDEX] = (flags | TASK_LOCAL_PROMISE_TRACKED_FLAG) >>> 0;
+        task[TASK_LOCAL_FLAGS_INDEX] = (flags | TASK_LOCAL_PROMISE_TRACKED_FLAG) >>>
+            0;
         pendingPromiseCount = (pendingPromiseCount + 1) | 0;
     };
     const encodeTaskValue = (task, slotIndex) => encodeTask(task, slotIndex);
@@ -633,6 +675,7 @@ export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload,
         if (recycled) {
             fillTaskFrom(recycled, headersBuffer, off);
             recycled.value = null;
+            recycled.finalize = undefined;
             recycled.resolve = def;
             recycled.reject = def;
             task = recycled;

package/src/memory/payloadCodec.js

@@ -1,10 +1,12 @@
-import { beginPromisePayload, finishPromisePayload, getTaskSlotIndex, HEADER_BYTE_LENGTH, HEADER_SLOT_STRIDE_U32, HEADER_STATIC_PAYLOAD_U32, LockBound, PayloadBuffer, PayloadSignal, TaskIndex, } from "./lock.js";
+import { attachPayloadTransportFinalizer, beginPromisePayload, finishPromisePayload, getTaskSlotIndex, HEADER_BYTE_LENGTH, HEADER_SLOT_STRIDE_U32, HEADER_STATIC_PAYLOAD_U32, LockBound, PayloadBuffer, PayloadSignal, TaskIndex, } from "./lock.js";
 import { register } from "./regionRegistry.js";
 import { createSharedDynamicBufferIO, createSharedStaticBufferIO, } from "./shared-buffer-io.js";
 import { getStridedRegionSpanBytes } from "./byte-carpet.js";
 import { encoderError, ErrorKnitting } from "../error.js";
 import { Envelope } from "../common/envelope.js";
 import { resolvePayloadBufferOptions, } from "./payload-config.js";
+import { getSharedArrayBufferPayload, SHARED_ARRAY_BUFFER_CODEC_ID, SHARED_ARRAY_BUFFER_NUMERIC_TRANSFER, SHARED_ARRAY_BUFFER_NUMERIC_WORDS, } from "../connections/shared-array-buffer-payload.js";
+const BUFFER_REFERENCE_NUMERIC_TRANSFER = Symbol.for("knitting.bufferReference.numericTransfer");
 const memory = new ArrayBuffer(8);
 const Float64View = new Float64Array(memory);
 const BigInt64View = new BigInt64Array(memory);
@@ -28,6 +30,7 @@ const BIGINT64_MAX = (1n << 63n) - 1n;
 const { parse: parseJSON, stringify: stringifyJSON } = JSON;
 const { for: symbolFor, keyFor: symbolKeyFor } = Symbol;
 const EXTERNAL_PAYLOAD_BRAND = symbolFor("knitting.payloadCodec");
+const BUFFER_REFERENCE_CODEC_ID = "knitting.bufferReference";
 const PROCESS_SHARED_BUFFER_CODEC_ID = "knitting.processSharedBuffer";
 const externalPayloadGlobal = globalThis;
 const objectGetPrototypeOf = Object.getPrototypeOf;
@@ -35,7 +38,8 @@ const objectHasOwn = Object.prototype.hasOwnProperty;
 const arrayIsArray = Array.isArray;
 const objectPrototype = Object.prototype;
 const UNSUPPORTED_OBJECT_DETAIL = "Unsupported object type. Allowed: plain object, array, Error, Date, Envelope, Buffer, ArrayBuffer, DataView, typed arrays, and registered external payloads. Serialize it yourself.";
-const ENVELOPE_PAYLOAD_DETAIL = "Envelope payload must be an ArrayBuffer.";
+const ENVELOPE_PAYLOAD_DETAIL = "Envelope payload must be an ArrayBuffer, SharedArrayBuffer, " +
+    "ProcessSharedBuffer, or BufferReference.";
 const ENVELOPE_HEADER_DETAIL = "Envelope header must be a JSON-like value or string.";
 const ENVELOPE_PROMISE_DETAIL = "Envelope header cannot contain Promise values.";
 const DYNAMIC_PAYLOAD_LIMIT_DETAIL = "Dynamic payload exceeds maxPayloadBytes.";
@@ -92,15 +96,18 @@ const decodeExternalPayload = (raw) => {
         : { codec: codecId, metadata };
 };
 const PROCESS_SHARED_BUFFER_NUMERIC_WORDS = 8;
+const BUFFER_REFERENCE_NUMERIC_WORDS = 8;
 const NUMERIC_SENTINEL = 0xffffffff;
-const decodeProcessSharedBufferNumericWords = (words) => {
-    const codec = externalPayloadGlobal.__KNITTING_PAYLOAD_CODECS__?.[PROCESS_SHARED_BUFFER_CODEC_ID];
-    if (typeof codec?.decodeNumeric === "function")
+const decodeNumericExternalPayload = (codecId, words) => {
+    const codec = externalPayloadGlobal.__KNITTING_PAYLOAD_CODECS__?.[codecId];
+    if (typeof codec?.decodeNumeric === "function") {
         return codec.decodeNumeric(words);
-    // `words` is a reusable scratch; copy it on the (unreachable in practice)
-    // codec-missing diagnostic path so the escaped value never aliases it.
-    return { codec: PROCESS_SHARED_BUFFER_CODEC_ID, metadata: Array.from(words) };
+    }
+    return { codec: codecId, metadata: Array.from(words) };
 };
+const decodeProcessSharedBufferNumericWords = (words) => decodeNumericExternalPayload(PROCESS_SHARED_BUFFER_CODEC_ID, words);
+const decodeBufferReferenceNumericWords = (words) => decodeNumericExternalPayload(BUFFER_REFERENCE_CODEC_ID, words);
+const decodeSharedArrayBufferNumericWords = (words) => decodeNumericExternalPayload(SHARED_ARRAY_BUFFER_CODEC_ID, words);
 const tryEncodePrimitiveTask = (task) => {
     const value = task.value;
     switch (typeof value) {
@@ -516,6 +523,7 @@ export const encodePayload = ({ lockSector, payload, sab, payloadConfig, headers
         return true;
     };
     const processSharedBufferWords = new Uint32Array(PROCESS_SHARED_BUFFER_NUMERIC_WORDS);
+    const sharedArrayBufferWords = new Uint32Array(SHARED_ARRAY_BUFFER_NUMERIC_WORDS);
     const tryEncodeProcessSharedBufferNumeric = (task, slotIndex, value) => {
         const descriptor = value.descriptor;
         if (descriptor === undefined ||
@@ -549,6 +557,33 @@ export const encodePayload = ({ lockSector, payload, sab, payloadConfig, headers
         task.value = null;
         return true;
     };
+    const tryEncodeBufferReferenceNumeric = (task, slotIndex, value) => {
+        const words = value[BUFFER_REFERENCE_NUMERIC_TRANSFER]?.();
+        if (words === undefined)
+            return false;
+        task[TaskIndex.Type] = PayloadBuffer.BufferReference;
+        task[TaskIndex.PayloadLen] = writeStaticU32Words(words, BUFFER_REFERENCE_NUMERIC_WORDS, slotIndex);
+        attachPayloadTransportFinalizer(task, value);
+        task.value = null;
+        return true;
+    };
+    const tryEncodeSharedArrayBufferNumeric = (task, slotIndex, value) => {
+        const words = value[SHARED_ARRAY_BUFFER_NUMERIC_TRANSFER]?.(lockSector);
+        if (words === undefined)
+            return false;
+        sharedArrayBufferWords[0] = words[0] ?? 0;
+        sharedArrayBufferWords[1] = words[1] ?? 0;
+        sharedArrayBufferWords[2] = words[2] ?? 0;
+        sharedArrayBufferWords[3] = words[3] ?? 0;
+        sharedArrayBufferWords[4] = words[4] ?? 0;
+        sharedArrayBufferWords[5] = words[5] ?? 0;
+        sharedArrayBufferWords[6] = words[6] ?? 0;
+        sharedArrayBufferWords[7] = words[7] ?? 0;
+        task[TaskIndex.Type] = PayloadBuffer.SharedArrayBuffer;
+        task[TaskIndex.PayloadLen] = writeStaticU32Words(sharedArrayBufferWords, words.length, slotIndex);
+        task.value = null;
+        return true;
+    };
     const encodeObjectExternalPayload = (task, slotIndex, externalPayload) => {
         const codecId = readExternalPayloadCodecId(externalPayload);
         if (codecId === undefined) {
@@ -559,6 +594,14 @@ export const encodePayload = ({ lockSector, payload, sab, payloadConfig, headers
                 detail: UNSUPPORTED_OBJECT_DETAIL,
             });
         }
+        if (codecId === SHARED_ARRAY_BUFFER_CODEC_ID &&
+            tryEncodeSharedArrayBufferNumeric(task, slotIndex, externalPayload)) {
+            return true;
+        }
+        if (codecId === BUFFER_REFERENCE_CODEC_ID &&
+            tryEncodeBufferReferenceNumeric(task, slotIndex, externalPayload)) {
+            return true;
+        }
         if (codecId === PROCESS_SHARED_BUFFER_CODEC_ID &&
             tryEncodeProcessSharedBufferNumeric(task, slotIndex, externalPayload)) {
             return true;
@@ -589,6 +632,7 @@ export const encodePayload = ({ lockSector, payload, sab, payloadConfig, headers
             if (written !== -1) {
                 task[TaskIndex.Type] = PayloadBuffer.StaticExternalPayload;
                 task[TaskIndex.PayloadLen] = written;
+                attachPayloadTransportFinalizer(task, externalPayload);
                 task.value = null;
                 return true;
             }
@@ -603,6 +647,7 @@ export const encodePayload = ({ lockSector, payload, sab, payloadConfig, headers
             return failDynamicWriteAfterReserve(task, reservedSlot);
         task[TaskIndex.PayloadLen] = written;
         setSlotLength(reservedSlot, written);
+        attachPayloadTransportFinalizer(task, externalPayload);
         task.value = null;
         return true;
     };
@@ -614,52 +659,50 @@ export const encodePayload = ({ lockSector, payload, sab, payloadConfig, headers
         task.value = null;
         return true;
     };
-    const encodeObjectEnvelope = (task, slotIndex, envelope) => {
-        const header = envelope.header;
-        const payload = envelope.payload;
-        const headerIsString = typeof header === "string";
-        if (!(payload instanceof ArrayBuffer)) {
-            return encoderError({
-                task,
-                type: ErrorKnitting.Serializable,
-                onPromise,
-                detail: ENVELOPE_PAYLOAD_DETAIL,
-            });
-        }
+    const encodeEnvelopeHeaderText = (task, header, headerIsString) => {
         if (hasPromiseInEnvelopeHeader(header)) {
-            return encoderError({
+            encoderError({
                 task,
                 type: ErrorKnitting.Serializable,
                 onPromise,
                 detail: ENVELOPE_PROMISE_DETAIL,
             });
+            return undefined;
         }
+        if (headerIsString)
+            return header;
         let headerText;
-        if (headerIsString) {
-            headerText = header;
+        try {
+            headerText = stringifyJSON(header);
         }
-        else {
-            try {
-                headerText = stringifyJSON(header);
-            }
-            catch (error) {
-                const detail = error instanceof Error ? error.message : String(error);
-                return encoderError({
-                    task,
-                    type: ErrorKnitting.Json,
-                    onPromise,
-                    detail,
-                });
-            }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            encoderError({ task, type: ErrorKnitting.Json, onPromise, detail });
+            return undefined;
         }
         if (typeof headerText !== "string") {
-            return encoderError({
+            encoderError({
                 task,
                 type: ErrorKnitting.Serializable,
                 onPromise,
                 detail: ENVELOPE_HEADER_DETAIL,
             });
+            return undefined;
+        }
+        return headerText;
+    };
+    const resolveEnvelopeExternalBody = (body) => {
+        if (body === null || typeof body !== "object")
+            return undefined;
+        const sharedArrayBuffer = getSharedArrayBufferPayload(body);
+        if (sharedArrayBuffer !== undefined)
+            return sharedArrayBuffer;
+        if (isExternalPayloadLike(body)) {
+            return body;
         }
+        return undefined;
+    };
+    const encodeEnvelopeArrayBufferBody = (task, slotIndex, headerText, headerIsString, payload) => {
         const payloadBytes = new Uint8Array(payload);
         const payloadLength = payloadBytes.byteLength;
         const payloadReserveBytes = payloadLength > 0 ? payloadLength : 1;
@@ -707,6 +750,107 @@ export const encodePayload = ({ lockSector, payload, sab, payloadConfig, headers
         task.value = null;
         return true;
     };
+    const encodeEnvelopeExternalBody = (task, slotIndex, headerText, headerIsString, externalBody) => {
+        const codecId = readExternalPayloadCodecId(externalBody);
+        if (codecId === undefined) {
+            return encoderError({
+                task,
+                type: ErrorKnitting.Serializable,
+                onPromise,
+                detail: ENVELOPE_PAYLOAD_DETAIL,
+            });
+        }
+        let bodyText;
+        try {
+            bodyText = stringifyJSON([codecId, externalBody.toMetadata()]);
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            return encoderError({
+                task,
+                type: ErrorKnitting.Serializable,
+                onPromise,
+                detail,
+            });
+        }
+        if (typeof bodyText !== "string") {
+            return encoderError({
+                task,
+                type: ErrorKnitting.Serializable,
+                onPromise,
+                detail: "Envelope body metadata must be JSON serializable.",
+            });
+        }
+        const bodyBytes = textEncode.encode(bodyText);
+        const bodyLength = bodyBytes.byteLength;
+        const staticHeaderWritten = writeStaticUtf8(headerText, slotIndex);
+        if (staticHeaderWritten !== -1) {
+            if (!ensureWithinDynamicLimit(task, bodyLength, "EnvelopeStaticHeaderExternal"))
+                return false;
+            const reservedSlot = reserveDynamicObject(task, bodyLength);
+            task[TaskIndex.Type] = headerIsString
+                ? PayloadBuffer.EnvelopeStaticHeaderStringExternal
+                : PayloadBuffer.EnvelopeStaticHeaderExternal;
+            task[TaskIndex.PayloadLen] = staticHeaderWritten;
+            task[TaskIndex.End] = bodyLength;
+            const bodyWritten = writeDynamicBinary(bodyBytes, task[TaskIndex.Start]);
+            if (bodyWritten < 0) {
+                return failDynamicWriteAfterReserve(task, reservedSlot);
+            }
+            setSlotLength(reservedSlot, bodyWritten);
+            attachPayloadTransportFinalizer(task, externalBody);
+            task.value = null;
+            return true;
+        }
+        const headerReserveBytes = dynamicUtf8ReserveBytesWithExtra(task, headerText, bodyLength, headerIsString
+            ? "EnvelopeDynamicHeaderStringExternal"
+            : "EnvelopeDynamicHeaderExternal");
+        if (headerReserveBytes < 0)
+            return false;
+        task[TaskIndex.Type] = headerIsString
+            ? PayloadBuffer.EnvelopeDynamicHeaderStringExternal
+            : PayloadBuffer.EnvelopeDynamicHeaderExternal;
+        const reservedSlot = reserveDynamicObject(task, headerReserveBytes + bodyLength);
+        const baseStart = task[TaskIndex.Start];
+        const writtenHeaderBytes = writeDynamicUtf8(headerText, baseStart, headerReserveBytes);
+        if (writtenHeaderBytes < 0) {
+            return failDynamicWriteAfterReserve(task, reservedSlot);
+        }
+        const bodyWritten = writeDynamicBinary(bodyBytes, baseStart + writtenHeaderBytes);
+        if (bodyWritten < 0) {
+            return failDynamicWriteAfterReserve(task, reservedSlot);
+        }
+        task[TaskIndex.PayloadLen] = writtenHeaderBytes;
+        task[TaskIndex.End] = bodyLength;
+        setSlotLength(reservedSlot, writtenHeaderBytes + bodyLength);
+        attachPayloadTransportFinalizer(task, externalBody);
+        task.value = null;
+        return true;
+    };
+    const encodeObjectEnvelope = (task, slotIndex, envelope) => {
+        const header = envelope.header;
+        const payload = envelope.payload;
+        const headerIsString = typeof header === "string";
+        if (payload instanceof ArrayBuffer) {
+            const headerText = encodeEnvelopeHeaderText(task, header, headerIsString);
+            if (headerText === undefined)
+                return false;
+            return encodeEnvelopeArrayBufferBody(task, slotIndex, headerText, headerIsString, payload);
+        }
+        const externalBody = resolveEnvelopeExternalBody(payload);
+        if (externalBody !== undefined) {
+            const headerText = encodeEnvelopeHeaderText(task, header, headerIsString);
+            if (headerText === undefined)
+                return false;
+            return encodeEnvelopeExternalBody(task, slotIndex, headerText, headerIsString, externalBody);
+        }
+        return encoderError({
+            task,
+            type: ErrorKnitting.Serializable,
+            onPromise,
+            detail: ENVELOPE_PAYLOAD_DETAIL,
+        });
+    };
     const encodeObjectPromise = (task, promise) => {
         if (beginPromisePayload(task)) {
             promise.then((value) => {
@@ -769,6 +913,10 @@ export const encodePayload = ({ lockSector, payload, sab, payloadConfig, headers
                 objectDynamicSlot = -1;
                 try {
                     const objectValue = args;
+                    const sharedArrayBufferPayload = getSharedArrayBufferPayload(objectValue);
+                    if (sharedArrayBufferPayload !== undefined) {
+                        return encodeObjectExternalPayload(task, slotIndex, sharedArrayBufferPayload);
+                    }
                     const objectProto = objectGetPrototypeOf(objectValue);
                     if (isRuntimeUint8Array(objectValue)) {
                         return encodeObjectUint8Array(task, slotIndex, objectValue);
@@ -963,6 +1111,8 @@ export const decodePayload = ({ lockSector, payload, sab, payloadConfig, headers
     // decode is single-consumer and not re-entrant, and the words are consumed
     // synchronously when building the ProcessSharedBuffer.
     const processSharedBufferWords = new Uint32Array(PROCESS_SHARED_BUFFER_NUMERIC_WORDS);
+    const sharedArrayBufferWords = new Uint32Array(SHARED_ARRAY_BUFFER_NUMERIC_WORDS);
+    const bufferReferenceWords = new Uint32Array(BUFFER_REFERENCE_NUMERIC_WORDS);
     // TODO: remove slotIndex and make that all their callers
     // store the slot in their Task, to just get it when it comes
     // to the static versions of decoding
@@ -1037,6 +1187,33 @@ export const decodePayload = ({ lockSector, payload, sab, payloadConfig, headers
                 freeTaskSlot(task);
                 return;
             }
+            case PayloadBuffer.EnvelopeStaticHeaderExternal:
+            case PayloadBuffer.EnvelopeStaticHeaderStringExternal: {
+                const rawHeader = readStaticUtf8(0, task[TaskIndex.PayloadLen], slotIndex);
+                const header = task[TaskIndex.Type] ===
+                    PayloadBuffer.EnvelopeStaticHeaderStringExternal
+                    ? rawHeader
+                    : parseJSON(rawHeader);
+                const bodyStart = task[TaskIndex.Start];
+                const body = decodeExternalPayload(readDynamicUtf8(bodyStart, bodyStart + task[TaskIndex.End]));
+                task.value = new Envelope(header, body);
+                freeTaskSlot(task);
+                return;
+            }
+            case PayloadBuffer.EnvelopeDynamicHeaderExternal:
+            case PayloadBuffer.EnvelopeDynamicHeaderStringExternal: {
+                const headerStart = task[TaskIndex.Start];
+                const bodyStart = headerStart + task[TaskIndex.PayloadLen];
+                const rawHeader = readDynamicUtf8(headerStart, bodyStart);
+                const header = task[TaskIndex.Type] ===
+                    PayloadBuffer.EnvelopeDynamicHeaderStringExternal
+                    ? rawHeader
+                    : parseJSON(rawHeader);
+                const body = decodeExternalPayload(readDynamicUtf8(bodyStart, bodyStart + task[TaskIndex.End]));
+                task.value = new Envelope(header, body);
+                freeTaskSlot(task);
+                return;
+            }
             case PayloadBuffer.BigInt:
                 task.value = decodeBigIntBinary(readDynamicBufferCopy(task[TaskIndex.Start], task[TaskIndex.Start] + task[TaskIndex.PayloadLen]));
                 freeTaskSlot(task);
@@ -1113,6 +1290,12 @@ export const decodePayload = ({ lockSector, payload, sab, payloadConfig, headers
             case PayloadBuffer.ProcessSharedBuffer:
                 task.value = decodeProcessSharedBufferNumericWords(readStaticU32Words(processSharedBufferWords, PROCESS_SHARED_BUFFER_NUMERIC_WORDS, slotIndex));
                 return;
+            case PayloadBuffer.SharedArrayBuffer:
+                task.value = decodeSharedArrayBufferNumericWords(readStaticU32Words(sharedArrayBufferWords, task[TaskIndex.PayloadLen] >>> 2, slotIndex));
+                return;
+            case PayloadBuffer.BufferReference:
+                task.value = decodeBufferReferenceNumericWords(readStaticU32Words(bufferReferenceWords, BUFFER_REFERENCE_NUMERIC_WORDS, slotIndex));
+                return;
             case PayloadBuffer.Date:
                 Uint32View[0] = task[TaskIndex.Start];
                 Uint32View[1] = task[TaskIndex.End];

package/src/runtime/pool.d.ts

@@ -4,7 +4,7 @@ import { lock2 } from "../memory/lock.js";
 import type { DebugOptions, DispatcherSettings, WorkerContext, WorkerData, WorkerSettings } from "../types.js";
 import "../worker/loop.js";
 import { type PayloadBufferOptions } from "../memory/payload-config.js";
-export declare const spawnWorkerContext: ({ list, ids, names, sab, thread, debug, totalNumberOfThread, source, at, workerOptions, workerExecArgv, permission, host, payload, payloadInitialBytes, payloadMaxBytes, bufferMode, maxPayloadBytes, abortSignalCapacity, usesAbortSignal, }: {
+export declare const spawnWorkerContext: ({ list, ids, names, sab, thread, debug, totalNumberOfThread, source, at, workerOptions, workerExecArgv, permission, host, payload, bufferReferenceReturn, payloadInitialBytes, payloadMaxBytes, bufferMode, maxPayloadBytes, abortSignalCapacity, usesAbortSignal, }: {
     list: string[];
     ids: number[];
     names: string[];
@@ -19,6 +19,7 @@ export declare const spawnWorkerContext: ({ list, ids, names, sab, thread, debug
     permission?: WorkerData["permission"];
     host?: DispatcherSettings;
     payload?: PayloadBufferOptions;
+    bufferReferenceReturn?: "copy" | "borrow";
     payloadInitialBytes?: number;
     payloadMaxBytes?: number;
     bufferMode?: PayloadBufferOptions["mode"];

package/src/runtime/pool.js

@@ -10,6 +10,7 @@ import { probeLockBufferTextCompat } from "../common/shared-buffer-text.js";
 import { signalAbortFactory } from "../shared/abortSignal.js";
 import { createLockControlCarpet } from "../memory/byte-carpet.js";
 import { resolvePayloadBufferOptions, } from "../memory/payload-config.js";
+import { createBufferReferenceReturnReleaseMessage } from "../connections/buffer-reference.js";
 const WORKER_FATAL_MESSAGE_KEY = "__knittingWorkerFatal";
 const isWorkerFatalMessage = (value) => !!value &&
     typeof value === "object" &&
@@ -33,7 +34,7 @@ const withFixedPayloadConfig = (config) => ({
     mode: "fixed",
     payloadInitialBytes: config.payloadMaxByteLength,
 });
-export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, totalNumberOfThread, source, at, workerOptions, workerExecArgv, permission, host, payload, payloadInitialBytes, payloadMaxBytes, bufferMode, maxPayloadBytes, abortSignalCapacity, usesAbortSignal, }) => {
+export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, totalNumberOfThread, source, at, workerOptions, workerExecArgv, permission, host, payload, bufferReferenceReturn, payloadInitialBytes, payloadMaxBytes, bufferMode, maxPayloadBytes, abortSignalCapacity, usesAbortSignal, }) => {
     const tsFileUrl = new URL(import.meta.url);
     const poliWorker = RUNTIME_WORKER;
     const resolvedWorkerOptions = serializeWorkerBootstrapData(withDefaultWorkerTimers(workerOptions));
@@ -193,6 +194,11 @@ export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, total
         lock,
         returnLock,
         abortSignals,
+        releaseBufferReferenceReturn: bufferReferenceReturn === "borrow"
+            ? (token) => {
+                worker?.postMessage?.(createBufferReferenceReturnReleaseMessage(token));
+            }
+            : undefined,
     });
     const { enqueue, rejectAll, txIdle, } = queue;
     const channelHandler = new ChannelHandler();
@@ -227,6 +233,7 @@ export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, total
         lock: lockBuffers,
         returnLock: returnLockBuffers,
         payloadConfig: resolvedPayloadConfig,
+        bufferReferenceReturn,
         permission,
     };
     const baseWorkerOptions = {

package/src/runtime/process-worker.js

@@ -2,7 +2,7 @@ import { fileURLToPath as fileURLToPathCompat } from "node:url";
 import { HEADER_SLOT_STRIDE_U32, LOCK_SECTOR_BYTE_LENGTH, LockBound, } from "../memory/lock.js";
 import { createByteCarpet, getHeaderBlockByteLength, makeSharedBufferRegion, } from "../memory/byte-carpet.js";
 import { RUNTIME } from "../common/runtime.js";
-import { RUNTIME_PROCESS_WORKER_BOOT_ENV, RUNTIME_PROCESS_WORKER_BOOT_VERSION, RUNTIME_PROCESS_WORKER_ENV, } from "../common/worker-runtime.js";
+import { RUNTIME_POOL_DEPTH, RUNTIME_POOL_DEPTH_ENV, RUNTIME_PROCESS_WORKER_BOOT_ENV, RUNTIME_PROCESS_WORKER_BOOT_VERSION, RUNTIME_PROCESS_WORKER_ENV, } from "../common/worker-runtime.js";
 import { getNodeBuiltinModule, getNodeProcess } from "../common/node-compat.js";
 import { toSharedBufferRegion, } from "../common/shared-buffer-region.js";
 import { createBunConnectionPrimitives } from "../connections/bun.js";
@@ -100,6 +100,7 @@ const DEFAULT_NODE_BINARY = "node";
 const DENO_PROCESS_WORKER_BOOT_ENV_ALLOW = [
     RUNTIME_PROCESS_WORKER_ENV,
     RUNTIME_PROCESS_WORKER_BOOT_ENV,
+    RUNTIME_POOL_DEPTH_ENV,
 ].join(",");
 const DENO_PROCESS_WORKER_INTERNAL_FLAGS = [
     `--allow-env=${DENO_PROCESS_WORKER_BOOT_ENV_ALLOW}`,
@@ -354,6 +355,7 @@ const currentProcessEnv = () => ({
 const processWorkerEnv = (extra) => ({
     ...currentProcessEnv(),
     [RUNTIME_PROCESS_WORKER_ENV]: "1",
+    [RUNTIME_POOL_DEPTH_ENV]: String(RUNTIME_POOL_DEPTH + 1),
     ...extra,
 });
 const processWorkerBootEnv = (bootPayload) => processWorkerEnv({

package/src/runtime/tx-queue.d.ts

@@ -1,4 +1,4 @@
-import { type Task, type Lock2 } from "../memory/lock.js";
+import { type Lock2, type Task } from "../memory/lock.js";
 import type { AbortSignalOption, TaskTimeout } from "../types.js";
 import { type SignalAbortStore } from "../shared/abortSignal.js";
 type RawArguments = unknown;
@@ -9,10 +9,11 @@ type CreateHostTxQueueArgs = {
     max?: number;
     lock: Lock2;
     returnLock: Lock2;
+    releaseBufferReferenceReturn?: (token: bigint) => void;
     abortSignals?: Pick<SignalAbortStore, "getSignal" | "setSignal" | "resetSignal" | "closeNow">;
     now?: () => number;
 };
-export declare function createHostTxQueue({ max, lock, returnLock, abortSignals, now, }: CreateHostTxQueueArgs): {
+export declare function createHostTxQueue({ max, lock, returnLock, releaseBufferReferenceReturn, abortSignals, now, }: CreateHostTxQueueArgs): {
     rejectAll: (reason: string) => void;
     hasPendingFrames: () => boolean;
     txIdle: () => boolean;