knitting 0.1.50 → 0.1.52

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,23 +96,18 @@ const decodeExternalPayload = (raw) => {
         : { codec: codecId, metadata };
 };
 const PROCESS_SHARED_BUFFER_NUMERIC_WORDS = 8;
-const PROCESS_SHARED_BUFFER_NUMERIC_BYTES = PROCESS_SHARED_BUFFER_NUMERIC_WORDS * Uint32Array.BYTES_PER_ELEMENT;
+const BUFFER_REFERENCE_NUMERIC_WORDS = 8;
 const NUMERIC_SENTINEL = 0xffffffff;
-const readProcessSharedBufferNumericPayload = (bytes) => {
-    const out = new Uint32Array(PROCESS_SHARED_BUFFER_NUMERIC_WORDS);
-    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
-    for (let i = 0; i < PROCESS_SHARED_BUFFER_NUMERIC_WORDS; i++) {
-        out[i] = view.getUint32(i * Uint32Array.BYTES_PER_ELEMENT, true);
+const decodeNumericExternalPayload = (codecId, words) => {
+    const codec = externalPayloadGlobal.__KNITTING_PAYLOAD_CODECS__?.[codecId];
+    if (typeof codec?.decodeNumeric === "function") {
+        return codec.decodeNumeric(words);
     }
-    return out;
-};
-const decodeProcessSharedBufferNumeric = (bytes) => {
-    const metadata = readProcessSharedBufferNumericPayload(bytes);
-    const codec = externalPayloadGlobal.__KNITTING_PAYLOAD_CODECS__?.[PROCESS_SHARED_BUFFER_CODEC_ID];
-    return typeof codec?.decodeNumeric === "function"
-        ? codec.decodeNumeric(metadata)
-        : { codec: PROCESS_SHARED_BUFFER_CODEC_ID, metadata };
+    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) {
@@ -299,7 +298,7 @@ export const encodePayload = ({ lockSector, payload, sab, payloadConfig, headers
         payloadConfig: resolvedPayloadConfig,
         textCompat: textCompat?.payload,
     });
-    const { maxBytes: staticMaxBytes, writeBinary: writeStaticBinary, writeBuffer: writeStaticBuffer, writeArrayBuffer: writeStaticArrayBuffer, writeExactUint8Array: writeStaticExactUint8Array, write8Binary: writeStatic8Binary, writeUtf8: writeStaticUtf8, } = requireStaticIO(headersBuffer, headerSlotStrideU32, textCompat?.headers);
+    const { maxBytes: staticMaxBytes, writeBinary: writeStaticBinary, writeBuffer: writeStaticBuffer, writeArrayBuffer: writeStaticArrayBuffer, writeExactUint8Array: writeStaticExactUint8Array, writeU32Words: writeStaticU32Words, write8Binary: writeStatic8Binary, writeUtf8: writeStaticUtf8, } = requireStaticIO(headersBuffer, headerSlotStrideU32, textCompat?.headers);
     const dynamicLimitError = (task, actualBytes, label) => encoderError({
         task,
         type: ErrorKnitting.Serializable,
@@ -523,11 +522,8 @@ export const encodePayload = ({ lockSector, payload, sab, payloadConfig, headers
         task.value = null;
         return true;
     };
-    const processSharedBufferScratch = new Uint8Array(PROCESS_SHARED_BUFFER_NUMERIC_BYTES);
-    const processSharedBufferScratchView = new DataView(processSharedBufferScratch.buffer);
-    const writeProcessSharedBufferWord = (index, value) => {
-        processSharedBufferScratchView.setUint32(index * Uint32Array.BYTES_PER_ELEMENT, value, 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 ||
@@ -544,19 +540,47 @@ export const encodePayload = ({ lockSector, payload, sab, payloadConfig, headers
             !isU32(baseAddressMod64)) {
             return false;
         }
-        writeProcessSharedBufferWord(0, descriptor.fd);
-        writeProcessSharedBufferWord(1, descriptor.size);
-        writeProcessSharedBufferWord(2, descriptor.byteLength);
-        writeProcessSharedBufferWord(3, value.byteOffset);
-        writeProcessSharedBufferWord(4, value.byteLength);
-        writeProcessSharedBufferWord(5, runtimeCode(descriptor.runtime));
-        writeProcessSharedBufferWord(6, kindCode(descriptor.kind));
-        writeProcessSharedBufferWord(7, baseAddressMod64 === undefined ? NUMERIC_SENTINEL : baseAddressMod64);
-        const written = writeStaticBinary(processSharedBufferScratch, slotIndex);
-        if (written !== PROCESS_SHARED_BUFFER_NUMERIC_BYTES)
-            return false;
+        processSharedBufferWords[0] = descriptor.fd;
+        processSharedBufferWords[1] = descriptor.size;
+        processSharedBufferWords[2] = descriptor.byteLength;
+        processSharedBufferWords[3] = value.byteOffset;
+        processSharedBufferWords[4] = value.byteLength;
+        processSharedBufferWords[5] = runtimeCode(descriptor.runtime);
+        processSharedBufferWords[6] = kindCode(descriptor.kind);
+        processSharedBufferWords[7] = baseAddressMod64 === undefined
+            ? NUMERIC_SENTINEL
+            : baseAddressMod64;
         task[TaskIndex.Type] = PayloadBuffer.ProcessSharedBuffer;
-        task[TaskIndex.PayloadLen] = written;
+        // Static region is a Uint32Array shared in-process; write the descriptor
+        // words straight in instead of staging bytes through a DataView + copy.
+        task[TaskIndex.PayloadLen] = writeStaticU32Words(processSharedBufferWords, PROCESS_SHARED_BUFFER_NUMERIC_WORDS, slotIndex);
+        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;
     };
@@ -570,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;
@@ -600,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;
             }
@@ -614,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;
     };
@@ -625,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;
@@ -718,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) => {
@@ -780,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);
@@ -969,7 +1106,13 @@ export const decodePayload = ({ lockSector, payload, sab, payloadConfig, headers
         payloadConfig: resolvedPayloadConfig,
         textCompat: textCompat?.payload,
     });
-    const { readUtf8: readStaticUtf8, readBytesCopy: readStaticBytesCopy, readBytesBufferCopy: readStaticBufferCopy, readBufferCopy: readStaticBuffer, readUint8ArrayCopy: readStaticUint8ArrayCopy, readBytesArrayBufferCopy: readStaticArrayBufferCopy, readArrayBufferCopy: readStaticArrayBuffer, read8BytesFloatCopy: readStatic8BytesFloatCopy, } = requireStaticIO(headersBuffer, headerSlotStrideU32, textCompat?.headers);
+    const { readUtf8: readStaticUtf8, readBytesBufferCopy: readStaticBufferCopy, readBufferCopy: readStaticBuffer, readUint8ArrayCopy: readStaticUint8ArrayCopy, readBytesArrayBufferCopy: readStaticArrayBufferCopy, readArrayBufferCopy: readStaticArrayBuffer, read8BytesFloatCopy: readStatic8BytesFloatCopy, readU32Words: readStaticU32Words, } = requireStaticIO(headersBuffer, headerSlotStrideU32, textCompat?.headers);
+    // Reusable scratch for the ProcessSharedBuffer raw-word decode. Safe to share:
+    // 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
@@ -1044,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);
@@ -1118,7 +1288,13 @@ export const decodePayload = ({ lockSector, payload, sab, payloadConfig, headers
                 task.value = decodeExternalPayload(readStaticUtf8(0, task[TaskIndex.PayloadLen], slotIndex));
                 return;
             case PayloadBuffer.ProcessSharedBuffer:
-                task.value = decodeProcessSharedBufferNumeric(readStaticBytesCopy(0, task[TaskIndex.PayloadLen], slotIndex));
+                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];

package/src/memory/shared-buffer-io.d.ts

@@ -37,6 +37,8 @@ export declare const createSharedStaticBufferIO: ({ headersBuffer, slotStrideU32
     writeArrayBuffer: (src: ArrayBuffer, at: number, start?: number) => number;
     writeExactUint8Array: (src: Uint8Array, at: number, start?: number) => number;
     writeUint8Array: (src: Uint8Array, at: number, start?: number) => number;
+    writeU32Words: (words: ArrayLike<number>, count: number, at: number) => number;
+    readU32Words: (out: Uint32Array, count: number, at: number) => Uint32Array;
     write8Binary: (src: Float64Array, at: number, start?: number) => number;
     readBytesCopy: (start: number, end: number, at: number) => Uint8Array<ArrayBuffer>;
     readBytesView: (start: number, end: number, at: number) => Uint8Array<SharedArrayBuffer>;

package/src/memory/shared-buffer-io.js

@@ -269,6 +269,27 @@ export const createSharedStaticBufferIO = ({ headersBuffer, slotStrideU32, textC
     for (let i = 0; i < LockBound.slots; i++) {
         slotByteOffsets[i] = slotStartBytes(i) - baseByteOffset;
     }
+    // The static region is itself a Uint32Array, shared in-process with native
+    // endianness. Fixed-shape numeric payloads (e.g. ProcessSharedBuffer
+    // descriptors) can be written/read as raw words straight into the slot,
+    // skipping the byte scratch + DataView + copy that the generic paths require.
+    const baseU32 = new Uint32Array(buffer, baseByteOffset, (buffer.byteLength - baseByteOffset) >>> 2);
+    const slotU32Offsets = new Uint32Array(LockBound.slots);
+    for (let i = 0; i < LockBound.slots; i++) {
+        slotU32Offsets[i] = slotByteOffsets[i] >>> 2;
+    }
+    const writeU32Words = (words, count, at) => {
+        const base = slotU32Offsets[at];
+        for (let i = 0; i < count; i++)
+            baseU32[base + i] = words[i];
+        return count * u32Bytes;
+    };
+    const readU32Words = (out, count, at) => {
+        const base = slotU32Offsets[at];
+        for (let i = 0; i < count; i++)
+            out[i] = baseU32[base + i];
+        return out;
+    };
     const canWrite = (start, length) => (start | 0) >= 0 && (start + length) <= writableBytes;
     const writeUtf8 = (str, at) => {
         const start = slotByteOffsets[at];
@@ -364,6 +385,8 @@ export const createSharedStaticBufferIO = ({ headersBuffer, slotStrideU32, textC
         writeArrayBuffer,
         writeExactUint8Array,
         writeUint8Array,
+        writeU32Words,
+        readU32Words,
         write8Binary,
         readBytesCopy,
         readBytesView,

package/src/runtime/inline-executor.d.ts

@@ -1,6 +1,6 @@
-import type { WorkerCall, tasks } from "../types.js";
+import type { ComposedWithKey, tasks, WorkerCall } from "../types.js";
 export declare const createInlineExecutor: ({ tasks, genTaskID, batchSize, }: {
-    tasks: tasks;
+    tasks: tasks | ComposedWithKey[];
     genTaskID: () => number;
     batchSize?: number;
 }) => {

package/src/runtime/inline-executor.js

@@ -69,9 +69,21 @@ const composeInlineCallable = (fn, timeout, useAbortToolkit = false) => {
     };
 };
 export const createInlineExecutor = ({ tasks, genTaskID, batchSize, }) => {
-    const entries = Object.values(tasks)
-        .sort((a, b) => a.id - b.id);
-    const runners = entries.map((entry) => composeInlineCallable(entry.f, entry.timeout, entry.abortSignal !== undefined));
+    const entries = Array.isArray(tasks)
+        ? tasks
+        : Object.values(tasks).sort((a, b) => a.id - b.id);
+    const runners = entries.map((entry) => {
+        // Imported tasks must never execute on the host inline lane: their module
+        // import is meant to stay inside the worker so worker permission policies
+        // apply. The pool already routes them to worker lanes, but guard here as
+        // defense in depth so a dispatch regression can't silently import on host.
+        if (entry.imported === true) {
+            return () => {
+                throw new Error("Imported task cannot run on the host inline lane");
+            };
+        }
+        return composeInlineCallable(entry.f, entry.timeout, entry.abortSignal !== undefined);
+    });
     const initCap = 16;
     let fnByIndex = new Int32Array(initCap);
     let stateByIndex = new Int8Array(initCap).fill(-1 /* SlotStateMacro.Free */);

package/src/runtime/pool.d.ts

@@ -4,9 +4,10 @@ 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, 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[];
     at: number[];
     sab?: Sab;
     thread: number;
@@ -18,6 +19,7 @@ export declare const spawnWorkerContext: ({ list, ids, sab, thread, debug, total
     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, 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, sab, thread, debug, totalNumberO
         lock,
         returnLock,
         abortSignals,
+        releaseBufferReferenceReturn: bufferReferenceReturn === "borrow"
+            ? (token) => {
+                worker?.postMessage?.(createBufferReferenceReturnReleaseMessage(token));
+            }
+            : undefined,
     });
     const { enqueue, rejectAll, txIdle, } = queue;
     const channelHandler = new ChannelHandler();
@@ -217,6 +223,7 @@ export const spawnWorkerContext = ({ list, ids, sab, thread, debug, totalNumberO
             : undefined,
         list,
         ids,
+        names,
         at,
         thread,
         debug,
@@ -226,6 +233,7 @@ export const spawnWorkerContext = ({ list, ids, sab, thread, debug, totalNumberO
         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;