knitting 0.1.51 → 0.1.53

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/permission/protocol.d.ts

@@ -163,4 +163,4 @@ export declare const resolvePermissionProtocol: ({ permission, modules, }: {
     modules?: string[];
 }) => ResolvedPermissionProtocol | undefined;
 export declare const toRuntimePermissionFlags: (protocol: ResolvedPermissionProtocol | undefined) => string[];
-export type { PermissionPath, PermissionMode, PermissionLegacyMode, SysApiName, NodePermissionSettings, DenoPermissionSettings, PermissionEnvironment, PermissionProtocol, PermissionProtocolInput, ResolvedPermissionProtocol, };
+export type { DenoPermissionSettings, NodePermissionSettings, PermissionEnvironment, PermissionLegacyMode, PermissionMode, PermissionPath, PermissionProtocol, PermissionProtocolInput, ResolvedPermissionProtocol, SysApiName, };

package/src/permission/protocol.js

@@ -107,11 +107,14 @@ const normalizeSysApiList = (values) => {
     return out;
 };
 const hasOwn = (value, key) => Object.prototype.hasOwnProperty.call(value, key);
-const normalizeProtocolInput = (input) => !input ? undefined : (typeof input === "string" ? { mode: input } : input);
+const normalizeProtocolInput = (input) => !input
+    ? undefined
+    : (typeof input === "string" ? { mode: input } : input);
 const isWindows = () => {
     const nodeProcess = getNodeProcess();
-    if (typeof nodeProcess?.platform === "string")
+    if (typeof nodeProcess?.platform === "string") {
         return nodeProcess.platform === "win32";
+    }
     const g = globalThis;
     return g.Deno?.build?.os === "windows";
 };
@@ -146,7 +149,8 @@ const getHome = () => {
     }
     const g = globalThis;
     try {
-        const home = g.Deno?.env?.get?.("HOME") ?? g.Deno?.env?.get?.("USERPROFILE");
+        const home = g.Deno?.env?.get?.("HOME") ??
+            g.Deno?.env?.get?.("USERPROFILE");
         if (typeof home === "string" && home.length > 0)
             return home;
     }
@@ -198,7 +202,11 @@ const toPathList = (values, cwd, home) => {
 };
 const toUniquePathList = (values, cwd, home) => normalizeList(toPathList(values, cwd, home));
 const toEnvFiles = (input, cwd, home) => {
-    const values = Array.isArray(input) ? input : input ? [input] : [DEFAULT_ENV_FILE];
+    const values = Array.isArray(input)
+        ? input
+        : input
+            ? [input]
+            : [DEFAULT_ENV_FILE];
     return toUniquePathList(values, cwd, home);
 };
 const rawRealpathSync = realpathSyncCompat.native ?? realpathSyncCompat;
@@ -212,7 +220,8 @@ const isPathWithin = (base, candidate) => {
     const canonicalBase = toCanonicalPath(base);
     const canonicalCandidate = toCanonicalPath(candidate);
     const relative = pathRelative(canonicalBase, canonicalCandidate);
-    return relative === "" || (!relative.startsWith("..") && !pathIsAbsolute(relative));
+    return relative === "" ||
+        (!relative.startsWith("..") && !pathIsAbsolute(relative));
 };
 const defaultSensitiveProjectAndHomePaths = (cwd, home) => {
     const projectSensitive = DEFAULT_DENY_RELATIVE.map((entry) => pathResolve(cwd, entry));
@@ -343,6 +352,13 @@ const toDenoFlags = ({ read, readAll, write, writeAll, denyRead, denyWrite, net,
         flags.push(`--deny-env=${envDeny.join(",")}`);
     }
     for (const file of envFiles) {
+        try {
+            if (!existsSyncCompat(file))
+                continue;
+        }
+        catch {
+            continue;
+        }
         flags.push(`--env-file=${file}`);
     }
     if (runAll) {
@@ -476,9 +492,7 @@ export const resolvePermissionProtocol = ({ permission, modules, }) => {
     const configuredRead = readAll
         ? []
         : toPathList(Array.isArray(input.read) ? input.read : undefined, cwd, home);
-    const configuredWrite = writeAll
-        ? []
-        : toPathList(Array.isArray(input.write) ? input.write : undefined, cwd, home);
+    const configuredWrite = writeAll ? [] : toPathList(Array.isArray(input.write) ? input.write : undefined, cwd, home);
     const resolvedRead = readAll
         ? []
         : hasExplicitRead
@@ -501,19 +515,17 @@ export const resolvePermissionProtocol = ({ permission, modules, }) => {
         : normalizeStringList(Array.isArray(input.net) ? input.net : []);
     const denyNet = normalizeStringList(input.denyNet);
     const allowImportAll = input.allowImport === true;
-    const allowImport = allowImportAll
-        ? []
-        : normalizeStringList(Array.isArray(input.allowImport)
-            ? input.allowImport
-            : [...DEFAULT_ALLOW_IMPORT_HOSTS]);
+    const allowImport = allowImportAll ? [] : normalizeStringList(Array.isArray(input.allowImport)
+        ? input.allowImport
+        : [...DEFAULT_ALLOW_IMPORT_HOSTS]);
     const envAllowAll = input.env?.allow === true;
-    const envAllow = envAllowAll
-        ? []
-        : normalizeStringList(Array.isArray(input.env?.allow) ? input.env.allow : []);
+    const envAllow = envAllowAll ? [] : normalizeStringList(Array.isArray(input.env?.allow) ? input.env.allow : []);
     const envDeny = normalizeStringList(input.env?.deny);
     const legacyRunEnabled = input.node?.allowChildProcess === true ||
         input.deno?.allowRun === true;
-    const runSource = hasOwn(input, "run") ? input.run : (legacyRunEnabled ? true : []);
+    const runSource = hasOwn(input, "run")
+        ? input.run
+        : (legacyRunEnabled ? true : []);
     const runAll = runSource === true;
     const run = runAll
         ? []
@@ -526,9 +538,7 @@ export const resolvePermissionProtocol = ({ permission, modules, }) => {
         ? input.ffi
         : (input.node?.allowAddons === true ? true : false);
     const ffiAll = ffiSource === true;
-    const ffi = ffiAll
-        ? []
-        : toUniquePathList(Array.isArray(ffiSource) ? ffiSource : undefined, cwd, home);
+    const ffi = ffiAll ? [] : toUniquePathList(Array.isArray(ffiSource) ? ffiSource : undefined, cwd, home);
     const denyFfi = toUniquePathList(input.denyFfi, cwd, home);
     const sysSource = input.sys;
     const sysAll = sysSource === true;

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, hostDebug, totalNumberOfThread, source, at, workerOptions, workerExecArgv, permission, host, payload, bufferReferenceReturn, abortSignalCapacity, usesAbortSignal, }: {
     list: string[];
     ids: number[];
     names: string[];
@@ -12,6 +12,7 @@ export declare const spawnWorkerContext: ({ list, ids, names, sab, thread, debug
     sab?: Sab;
     thread: number;
     debug?: DebugOptions;
+    hostDebug?: (message: string) => void;
     totalNumberOfThread: number;
     source?: string;
     workerOptions?: WorkerSettings;
@@ -19,10 +20,7 @@ export declare const spawnWorkerContext: ({ list, ids, names, sab, thread, debug
     permission?: WorkerData["permission"];
     host?: DispatcherSettings;
     payload?: PayloadBufferOptions;
-    payloadInitialBytes?: number;
-    payloadMaxBytes?: number;
-    bufferMode?: PayloadBufferOptions["mode"];
-    maxPayloadBytes?: number;
+    bufferReferenceReturn?: "copy" | "borrow";
     abortSignalCapacity?: number;
     usesAbortSignal?: boolean;
 }) => WorkerContext & {

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, hostDebug, totalNumberOfThread, source, at, workerOptions, workerExecArgv, permission, host, payload, bufferReferenceReturn, abortSignalCapacity, usesAbortSignal, }) => {
     const tsFileUrl = new URL(import.meta.url);
     const poliWorker = RUNTIME_WORKER;
     const resolvedWorkerOptions = serializeWorkerBootstrapData(withDefaultWorkerTimers(workerOptions));
@@ -47,9 +48,6 @@ export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, total
     const processSharedMemorySettings = useProcessWorkerRuntime
         ? readProcessSharedMemorySettings(resolvedWorkerOptions)
         : undefined;
-    if (debug?.logHref === true) {
-        console.log(tsFileUrl);
-    }
     if (!useProcessWorkerRuntime && typeof poliWorker !== "function") {
         throw new Error("Worker is not available in this runtime");
     }
@@ -62,15 +60,7 @@ export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, total
         return bytes > 0 ? bytes : undefined;
     };
     const basePayloadConfig = resolvePayloadBufferOptions({
-        options: {
-            ...payload,
-            mode: payload?.mode ?? bufferMode,
-            maxPayloadBytes: payload?.maxPayloadBytes ?? maxPayloadBytes,
-            payloadInitialBytes: payload?.payloadInitialBytes ??
-                sanitizeBytes(payloadInitialBytes),
-            payloadMaxByteLength: payload?.payloadMaxByteLength ??
-                sanitizeBytes(payloadMaxBytes),
-        },
+        options: payload,
     });
     const resolvedPayloadConfig = useProcessWorkerRuntime
         ? withFixedPayloadConfig(basePayloadConfig)
@@ -182,7 +172,6 @@ export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, total
             : sab,
         isMain: true,
         thread,
-        debug,
     });
     const signalBox = signals;
     const nativeNotifySignal = createProcessWorkerNativeSignalNotifier({
@@ -193,6 +182,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();
@@ -202,13 +196,18 @@ export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, total
         channelHandler,
         dispatcherOptions: host,
         notifySignal: nativeNotifySignal,
-        //thread,
-        //debugSignal: debug?.logMain ?? false,
-        //perf,
     });
     channelHandler.open(check);
     let worker;
     const workerUrl = source ?? tsFileUrl;
+    const workerMode = useProcessWorkerRuntime
+        ? "process"
+        : HAS_NODE_WORKER_THREADS
+            ? "worker_threads"
+            : "worker";
+    hostDebug?.(`worker thread=${thread} mode=${workerMode}` +
+        `${processWorkerRuntime ? ` runtime=${processWorkerRuntime}` : ""}` +
+        ` url=${String(workerUrl)}`);
     const workerDataPayload = {
         sab: signals.sab,
         abortSignalSAB,
@@ -227,6 +226,7 @@ export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, total
         lock: lockBuffers,
         returnLock: returnLockBuffers,
         payloadConfig: resolvedPayloadConfig,
+        bufferReferenceReturn,
         permission,
     };
     const baseWorkerOptions = {
@@ -358,7 +358,7 @@ export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, total
         Promise.resolve().then(check);
         // Macro lane: dispatcher check is driven by the channel callback.
         // channelHandler.notify();
-        // Use opView as a wake counter in lock2 mode to avoid lost wakeups.
+        // Use opView as a wake token in lock2 mode to avoid lost wakeups.
         if (a_load(signalBox.rxStatus, 0) === 0) {
             a_add(thisSignal, 0, 1);
             notifySignal?.();

package/src/runtime/process-worker.js

@@ -2,7 +2,8 @@ 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 { debugHas } from "../debug/gate.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";
@@ -72,7 +73,7 @@ export const createProcessSharedMemoryAllocator = (debug) => {
         addon = loadNodeNativeAddon(require, "knitting_shared_memory");
     }
     catch (error) {
-        if (debug?.extras === true) {
+        if (debugHas(debug, "lifecycle")) {
             console.warn("Process-shared memory allocator unavailable; falling back to SharedArrayBuffer.", error);
         }
         return undefined;
@@ -100,6 +101,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 +356,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({