knitting 0.1.56 → 0.1.60

package/src/memory/lock.js

@@ -1,5 +1,10 @@
 import RingQueue from "../ipc/tools/ring-queue.js";
-import { decodePayload, encodePayload } from "./payloadCodec.js";
+let registeredEncodePayload;
+let registeredDecodePayload;
+export const registerLockPayloadCodec = (encode, decode) => {
+    registeredEncodePayload = encode;
+    registeredDecodePayload = decode;
+};
 import { createSharedArrayBuffer, createWasmSharedArrayBuffer, } from "../common/runtime.js";
 import { toSharedBufferRegion, } from "../common/shared-buffer-region.js";
 import { probeLockBufferTextCompat, } from "../common/shared-buffer-text.js";
@@ -7,69 +12,76 @@ import { resolvePayloadBufferOptions, } from "./payload-config.js";
 /**
  * TODO: Compose all the instance where the array is passed as argument
  */
-export var PayloadSignal;
-(function (PayloadSignal) {
-    PayloadSignal[PayloadSignal["UNREACHABLE"] = 0] = "UNREACHABLE";
-    PayloadSignal[PayloadSignal["BigInt"] = 2] = "BigInt";
-    PayloadSignal[PayloadSignal["True"] = 3] = "True";
-    PayloadSignal[PayloadSignal["False"] = 4] = "False";
-    PayloadSignal[PayloadSignal["Undefined"] = 5] = "Undefined";
-    PayloadSignal[PayloadSignal["NaN"] = 6] = "NaN";
-    PayloadSignal[PayloadSignal["Float64"] = 9] = "Float64";
-    PayloadSignal[PayloadSignal["Null"] = 10] = "Null";
-})(PayloadSignal || (PayloadSignal = {}));
-export var PayloadBuffer;
-(function (PayloadBuffer) {
-    PayloadBuffer[PayloadBuffer["BORDER_SIGNAL_BUFFER"] = 11] = "BORDER_SIGNAL_BUFFER";
-    PayloadBuffer[PayloadBuffer["String"] = 11] = "String";
-    PayloadBuffer[PayloadBuffer["Json"] = 12] = "Json";
-    PayloadBuffer[PayloadBuffer["StaticString"] = 15] = "StaticString";
-    PayloadBuffer[PayloadBuffer["StaticJson"] = 16] = "StaticJson";
-    PayloadBuffer[PayloadBuffer["Binary"] = 17] = "Binary";
-    PayloadBuffer[PayloadBuffer["StaticBinary"] = 18] = "StaticBinary";
-    PayloadBuffer[PayloadBuffer["Int32Array"] = 19] = "Int32Array";
-    PayloadBuffer[PayloadBuffer["Float64Array"] = 20] = "Float64Array";
-    PayloadBuffer[PayloadBuffer["BigInt64Array"] = 21] = "BigInt64Array";
-    PayloadBuffer[PayloadBuffer["BigUint64Array"] = 22] = "BigUint64Array";
-    PayloadBuffer[PayloadBuffer["DataView"] = 23] = "DataView";
-    PayloadBuffer[PayloadBuffer["Error"] = 24] = "Error";
-    PayloadBuffer[PayloadBuffer["Date"] = 25] = "Date";
-    PayloadBuffer[PayloadBuffer["Symbol"] = 26] = "Symbol";
-    PayloadBuffer[PayloadBuffer["StaticSymbol"] = 27] = "StaticSymbol";
-    PayloadBuffer[PayloadBuffer["BigInt"] = 28] = "BigInt";
-    PayloadBuffer[PayloadBuffer["StaticBigInt"] = 29] = "StaticBigInt";
-    PayloadBuffer[PayloadBuffer["StaticInt32Array"] = 31] = "StaticInt32Array";
-    PayloadBuffer[PayloadBuffer["StaticFloat64Array"] = 32] = "StaticFloat64Array";
-    PayloadBuffer[PayloadBuffer["StaticBigInt64Array"] = 33] = "StaticBigInt64Array";
-    PayloadBuffer[PayloadBuffer["StaticBigUint64Array"] = 34] = "StaticBigUint64Array";
-    PayloadBuffer[PayloadBuffer["StaticDataView"] = 35] = "StaticDataView";
-    PayloadBuffer[PayloadBuffer["ArrayBuffer"] = 36] = "ArrayBuffer";
-    PayloadBuffer[PayloadBuffer["StaticArrayBuffer"] = 37] = "StaticArrayBuffer";
-    PayloadBuffer[PayloadBuffer["Buffer"] = 38] = "Buffer";
-    PayloadBuffer[PayloadBuffer["StaticBuffer"] = 39] = "StaticBuffer";
-    PayloadBuffer[PayloadBuffer["EnvelopeStaticHeader"] = 40] = "EnvelopeStaticHeader";
-    PayloadBuffer[PayloadBuffer["EnvelopeDynamicHeader"] = 41] = "EnvelopeDynamicHeader";
-    PayloadBuffer[PayloadBuffer["EnvelopeStaticHeaderString"] = 42] = "EnvelopeStaticHeaderString";
-    PayloadBuffer[PayloadBuffer["EnvelopeDynamicHeaderString"] = 43] = "EnvelopeDynamicHeaderString";
-    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["NumericArray"] = 53] = "NumericArray";
-    PayloadBuffer[PayloadBuffer["StaticNumericArray"] = 54] = "StaticNumericArray";
-})(PayloadBuffer || (PayloadBuffer = {}));
-export var LockBound;
-(function (LockBound) {
-    LockBound[LockBound["paddingLock"] = 0] = "paddingLock";
-    LockBound[LockBound["padding"] = 0] = "padding";
-    LockBound[LockBound["slots"] = 32] = "slots";
-    LockBound[LockBound["header"] = 0] = "header";
-})(LockBound || (LockBound = {}));
+// const objects replace `enum`s throughout this module: Andromeda's Nova engine
+// panics on `enum`. Value access, duplicate-value members, and type preserved;
+// identical emit on Node/Deno/Bun.
+export const PayloadSignal = {
+    UNREACHABLE: 0,
+    BigInt: 2,
+    True: 3,
+    False: 4,
+    Undefined: 5,
+    NaN: 6,
+    Float64: 9,
+    Null: 10,
+};
+export const PayloadBuffer = {
+    BORDER_SIGNAL_BUFFER: 11,
+    String: 11,
+    Json: 12,
+    StaticString: 15,
+    StaticJson: 16,
+    Binary: 17,
+    StaticBinary: 18,
+    Int32Array: 19,
+    Float64Array: 20,
+    BigInt64Array: 21,
+    BigUint64Array: 22,
+    DataView: 23,
+    Error: 24,
+    Date: 25,
+    Symbol: 26,
+    StaticSymbol: 27,
+    BigInt: 28,
+    StaticBigInt: 29,
+    StaticInt32Array: 31,
+    StaticFloat64Array: 32,
+    StaticBigInt64Array: 33,
+    StaticBigUint64Array: 34,
+    StaticDataView: 35,
+    ArrayBuffer: 36,
+    StaticArrayBuffer: 37,
+    Buffer: 38,
+    StaticBuffer: 39,
+    EnvelopeStaticHeader: 40,
+    EnvelopeDynamicHeader: 41,
+    EnvelopeStaticHeaderString: 42,
+    EnvelopeDynamicHeaderString: 43,
+    ExternalPayload: 44,
+    StaticExternalPayload: 45,
+    ProcessSharedBuffer: 46,
+    BufferReference: 47,
+    SharedArrayBuffer: 48,
+    EnvelopeStaticHeaderExternal: 49,
+    EnvelopeDynamicHeaderExternal: 50,
+    EnvelopeStaticHeaderStringExternal: 51,
+    EnvelopeDynamicHeaderStringExternal: 52,
+    NumericArray: 53,
+    StaticNumericArray: 54,
+};
+// Value -> name lookup (enum reverse-map), for payload-limit error labels.
+// Later keys win on duplicate values (11 -> "String"), as TS enums do.
+const PayloadBufferName = {};
+for (const key of Object.keys(PayloadBuffer)) {
+    PayloadBufferName[PayloadBuffer[key]] = key;
+}
+export const payloadBufferName = (value) => PayloadBufferName[value] ?? String(value);
+export const LockBound = {
+    paddingLock: 0,
+    padding: 0,
+    slots: 32,
+    header: 0,
+};
 export const LOCK_CACHE_LINE_BYTES = 64;
 export const LOCK_SECTOR_BYTES = 256;
 export const PayloadTransportFinalizer = Symbol.for("knitting.payloadCodec.transportFinalizer");
@@ -123,34 +135,33 @@ export const runTaskFinalizers = (task) => {
         }
     }
 };
-export var TaskIndex;
-(function (TaskIndex) {
+export const TaskIndex = {
     /**
      * Worker -> host response flags word.
      */
-    TaskIndex[TaskIndex["FlagsToHost"] = 0] = "FlagsToHost";
+    FlagsToHost: 0,
     /**
      * Host -> worker request function id (low 16 bits).
      * High 16 bits are reserved for caller metadata on request path.
      * NOTE: shares the same storage word as `FlagsToHost`.
      */
-    TaskIndex[TaskIndex["FunctionID"] = 0] = "FunctionID";
-    TaskIndex[TaskIndex["ID"] = 1] = "ID";
-    TaskIndex[TaskIndex["Type"] = 2] = "Type";
-    TaskIndex[TaskIndex["Start"] = 3] = "Start";
-    TaskIndex[TaskIndex["End"] = 4] = "End";
-    TaskIndex[TaskIndex["PayloadLen"] = 5] = "PayloadLen";
+    FunctionID: 0,
+    ID: 1,
+    Type: 2,
+    Start: 3,
+    End: 4,
+    PayloadLen: 5,
     /**
      * Low 5 bits: region slot index (0..31).
      * High 27 bits: reserved for caller metadata (e.g. enqueue timing).
      */
-    TaskIndex[TaskIndex["slotBuffer"] = 6] = "slotBuffer";
-    TaskIndex[TaskIndex["Size"] = 8] = "Size";
+    slotBuffer: 6,
+    Size: 8,
     /**
      * Total slot length in Uint32 words, including the task header.
      */
-    TaskIndex[TaskIndex["TotalBuff"] = 144] = "TotalBuff";
-})(TaskIndex || (TaskIndex = {}));
+    TotalBuff: 144,
+};
 export const TASK_SLOT_INDEX_BITS = 5;
 export const TASK_SLOT_INDEX_MASK = (1 << TASK_SLOT_INDEX_BITS) - 1;
 export const TASK_SLOT_META_BITS = 32 - TASK_SLOT_INDEX_BITS;
@@ -186,10 +197,9 @@ export const setTaskSlotMeta = (task, value) => {
     task[TaskIndex.slotBuffer] =
         ((task[TaskIndex.slotBuffer] & TASK_SLOT_INDEX_MASK) | encodedMeta) >>> 0;
 };
-export var TaskFlag;
-(function (TaskFlag) {
-    TaskFlag[TaskFlag["Reject"] = 1] = "Reject";
-})(TaskFlag || (TaskFlag = {}));
+export const TaskFlag = {
+    Reject: 1,
+};
 // Main queue lock layout in bytes.
 // The queue protocol uses two Int32 signal words, each on its own cache line:
 // - hostBits at byte 0
@@ -240,6 +250,8 @@ export const makeTask = () => {
 const fillTaskFrom = (task, array, at) => {
     task[0] = array[at];
     task[1] = array[at + 1];
+    // Raw numeric tag word; const-object payload "enums" are strict literal unions
+    // (numeric `enum` accepted any number), so cast back on restore.
     task[2] = array[at + 2];
     task[3] = array[at + 3];
     task[4] = array[at + 4];
@@ -264,7 +276,7 @@ const settleTask = (task) => {
         task[TaskIndex["FlagsToHost"]] = 0;
     }
 };
-export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload, payloadConfig, payloadSector, textCompat, resultList, toSentList, recycleList, }) => {
+export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload, payloadConfig, payloadSector, textCompat, resultList, toSentList, recycleList, processBoundary, }) => {
     // Layout within `lockSectorRegion`:
     // - hostBits starts at byte 0
     // - workerBits starts at byte 64
@@ -297,7 +309,12 @@ export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload,
         payload: payloadSAB,
     });
     let promiseHandler;
-    const encodeTask = encodePayload({
+    if (registeredEncodePayload === undefined ||
+        registeredDecodePayload === undefined) {
+        throw new Error("Payload codec not registered before lock2(). Ensure the module that " +
+            'builds locks imports "./payloadCodec.ts" (it self-registers on load).');
+    }
+    const encodeTask = registeredEncodePayload({
         payload: {
             sab: payloadSAB,
             config: resolvedPayloadConfig,
@@ -306,6 +323,7 @@ export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload,
         headerSlotStrideU32: headersSlotStride,
         lockSector: payloadLockRegion,
         textCompat: resolvedTextCompat,
+        processBoundary,
         onPromise: (task, isRejected, value) => {
             if ((task[TASK_LOCAL_FLAGS_INDEX] & TASK_LOCAL_PROMISE_TRACKED_FLAG) !==
                 0 &&
@@ -318,7 +336,7 @@ export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload,
             promiseHandler(task, isRejected, value);
         },
     });
-    const decodeTask = decodePayload({
+    const decodeTask = registeredDecodePayload({
         payload: {
             sab: payloadSAB,
             config: resolvedPayloadConfig,
@@ -327,6 +345,7 @@ export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload,
         headerSlotStrideU32: headersSlotStride,
         lockSector: payloadLockRegion,
         textCompat: resolvedTextCompat,
+        processBoundary,
     });
     let LastLocal = 0 | 0;
     let LastWorker = 0 | 0;

package/src/memory/payloadCodec.d.ts

@@ -6,7 +6,7 @@ import type { SharedBufferSource } from "../common/shared-buffer-region.js";
  * Returns `true` when the payload is encoded successfully.
  * Returns `false` when dynamic payload space could not be reserved.
  */
-export declare const encodePayload: ({ lockSector, payload, sab, payloadConfig, headersBuffer, headerSlotStrideU32, textCompat, onPromise, }: {
+export declare const encodePayload: ({ lockSector, payload, sab, payloadConfig, headersBuffer, headerSlotStrideU32, textCompat, onPromise, processBoundary, }: {
     lockSector?: SharedBufferSource;
     payload?: {
         sab?: SharedBufferSource;
@@ -24,8 +24,13 @@ export declare const encodePayload: ({ lockSector, payload, sab, payloadConfig,
     headerSlotStrideU32?: number;
     textCompat?: LockBufferTextCompat;
     onPromise?: PromisePayloadHandler;
+    /**
+     * Reject process-local pointer payloads while preserving ProcessSharedBuffer.
+     * Process transports must set this on both encoders and decoders.
+     */
+    processBoundary?: boolean;
 }) => (task: Task, slotIndex: number) => boolean;
-export declare const decodePayload: ({ lockSector, payload, sab, payloadConfig, headersBuffer, headerSlotStrideU32, textCompat, host, }: {
+export declare const decodePayload: ({ lockSector, payload, sab, payloadConfig, headersBuffer, headerSlotStrideU32, textCompat, host, processBoundary, }: {
     lockSector?: SharedBufferSource;
     payload?: {
         sab?: SharedBufferSource;
@@ -43,4 +48,8 @@ export declare const decodePayload: ({ lockSector, payload, sab, payloadConfig,
     headerSlotStrideU32?: number;
     textCompat?: LockBufferTextCompat;
     host?: true;
+    /**
+     * Reject process-local pointer payloads before reading pointer/token metadata.
+     */
+    processBoundary?: boolean;
 }) => (task: Task, slotIndex: number, specialFlags?: number) => void;

package/src/memory/payloadCodec.js

@@ -1,4 +1,4 @@
-import { attachPayloadTransportFinalizer, 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, payloadBufferName, PayloadSignal, registerLockPayloadCodec, TaskIndex, } from "./lock.js";
 import { register } from "./regionRegistry.js";
 import { createSharedDynamicBufferIO, createSharedStaticBufferIO, } from "./shared-buffer-io.js";
 import { getStridedRegionSpanBytes } from "./byte-carpet.js";
@@ -6,8 +6,9 @@ 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";
+import { BUFFER_REFERENCE_NUMERIC_TRANSFER, BufferReference, isBufferReferenceValue, } from "../connections/buffer-reference.js";
+import { isProcessSharedBufferValue, ProcessSharedBuffer, } from "../connections/process-shared-buffer.js";
 import { isNumericArray, numericArrayFromFloat64, } from "../connections/numeric-array.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);
@@ -45,6 +46,13 @@ const ENVELOPE_HEADER_DETAIL = "Envelope header must be a JSON-like value or str
 const ENVELOPE_PROMISE_DETAIL = "Envelope header cannot contain Promise values.";
 const DYNAMIC_PAYLOAD_LIMIT_DETAIL = "Dynamic payload exceeds maxPayloadBytes.";
 const DYNAMIC_PAYLOAD_CAPACITY_DETAIL = "Dynamic payload buffer capacity exceeded.";
+const PROCESS_BOUNDARY_POINTER_PAYLOAD_DETAIL = "SharedArrayBuffer and BufferReference are process-local pointer payloads " +
+    "and cannot cross a process-worker boundary; use ProcessSharedBuffer instead.";
+const RESERVED_EXTERNAL_PAYLOAD_DETAIL = "Reserved Knitting external payload codec cannot be forged.";
+const isProcessLocalPointerCodec = (codecId) => codecId === SHARED_ARRAY_BUFFER_CODEC_ID ||
+    codecId === BUFFER_REFERENCE_CODEC_ID;
+const isReservedExternalPayloadCodec = (codecId) => isProcessLocalPointerCodec(codecId) ||
+    codecId === PROCESS_SHARED_BUFFER_CODEC_ID;
 const isPlainJsonObject = (value) => {
     const proto = objectGetPrototypeOf(value);
     return proto === objectPrototype || proto === null;
@@ -82,7 +90,16 @@ const isU32 = (value) => typeof value === "number" &&
 const isExternalPayloadLike = (value) => typeof value.toMetadata === "function" &&
     typeof value[EXTERNAL_PAYLOAD_BRAND] ===
         "string";
-const decodeExternalPayload = (raw) => {
+const readTrustedExternalPayloadMetadata = (value) => {
+    if (isBufferReferenceValue(value)) {
+        return BufferReference.prototype.toMetadata.call(value);
+    }
+    if (isProcessSharedBufferValue(value)) {
+        return ProcessSharedBuffer.prototype.toMetadata.call(value);
+    }
+    return value.toMetadata();
+};
+const decodeExternalPayload = (raw, processBoundary) => {
     const payload = parseJSON(raw);
     if (!arrayIsArray(payload) || payload.length !== 2)
         return payload;
@@ -91,6 +108,9 @@ const decodeExternalPayload = (raw) => {
     if (typeof codecId !== "string") {
         return { codec: codecId, metadata };
     }
+    if (processBoundary && isProcessLocalPointerCodec(codecId)) {
+        throw new TypeError(PROCESS_BOUNDARY_POINTER_PAYLOAD_DETAIL);
+    }
     const codec = externalPayloadGlobal.__KNITTING_PAYLOAD_CODECS__?.[codecId];
     return typeof codec?.decode === "function"
         ? codec.decode(metadata)
@@ -284,7 +304,7 @@ const requireStaticIO = (headersBuffer, headerSlotStrideU32, textCompat) => {
  * Returns `true` when the payload is encoded successfully.
  * Returns `false` when dynamic payload space could not be reserved.
  */
-export const encodePayload = ({ lockSector, payload, sab, payloadConfig, headersBuffer, headerSlotStrideU32, textCompat, onPromise, }) => {
+export const encodePayload = ({ lockSector, payload, sab, payloadConfig, headersBuffer, headerSlotStrideU32, textCompat, onPromise, processBoundary = false, }) => {
     const payloadSab = payload?.sab ?? sab;
     const resolvedPayloadConfig = resolvePayloadBufferOptions({
         sab: payloadSab,
@@ -421,7 +441,7 @@ export const encodePayload = ({ lockSector, payload, sab, payloadConfig, headers
             }
         }
         task[TaskIndex.Type] = dynamicType;
-        if (!ensureWithinDynamicLimit(task, bytes, PayloadBuffer[dynamicType])) {
+        if (!ensureWithinDynamicLimit(task, bytes, payloadBufferName(dynamicType))) {
             return false;
         }
         const reservedSlot = reserveDynamicObject(task, bytes);
@@ -590,7 +610,9 @@ export const encodePayload = ({ lockSector, payload, sab, payloadConfig, headers
         return true;
     };
     const tryEncodeBufferReferenceNumeric = (task, slotIndex, value) => {
-        const words = value[BUFFER_REFERENCE_NUMERIC_TRANSFER]?.();
+        const words = isBufferReferenceValue(value)
+            ? BufferReference.prototype[BUFFER_REFERENCE_NUMERIC_TRANSFER].call(value)
+            : value[BUFFER_REFERENCE_NUMERIC_TRANSFER]?.();
         if (words === undefined)
             return false;
         task[TaskIndex.Type] = PayloadBuffer.BufferReference;
@@ -616,7 +638,7 @@ export const encodePayload = ({ lockSector, payload, sab, payloadConfig, headers
         task.value = null;
         return true;
     };
-    const encodeObjectExternalPayload = (task, slotIndex, externalPayload) => {
+    const encodeObjectExternalPayload = (task, slotIndex, externalPayload, trustedReservedCodec = false) => {
         const codecId = readExternalPayloadCodecId(externalPayload);
         if (codecId === undefined) {
             return encoderError({
@@ -626,21 +648,46 @@ 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 (trustedReservedCodec) {
+            if (processBoundary && isProcessLocalPointerCodec(codecId)) {
+                return encoderError({
+                    task,
+                    type: ErrorKnitting.Serializable,
+                    onPromise,
+                    detail: PROCESS_BOUNDARY_POINTER_PAYLOAD_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;
+            }
         }
-        if (codecId === PROCESS_SHARED_BUFFER_CODEC_ID &&
-            tryEncodeProcessSharedBufferNumeric(task, slotIndex, externalPayload)) {
-            return true;
+        else if (isReservedExternalPayloadCodec(codecId)) {
+            return encoderError({
+                task,
+                type: ErrorKnitting.Serializable,
+                onPromise,
+                detail: processBoundary && isProcessLocalPointerCodec(codecId)
+                    ? PROCESS_BOUNDARY_POINTER_PAYLOAD_DETAIL
+                    : RESERVED_EXTERNAL_PAYLOAD_DETAIL,
+            });
         }
         let text;
         try {
-            text = stringifyJSON([codecId, externalPayload.toMetadata()]);
+            text = stringifyJSON([
+                codecId,
+                trustedReservedCodec
+                    ? readTrustedExternalPayloadMetadata(externalPayload)
+                    : externalPayload.toMetadata(),
+            ]);
         }
         catch (error) {
             const detail = error instanceof Error ? error.message : String(error);
@@ -727,10 +774,21 @@ export const encodePayload = ({ lockSector, payload, sab, payloadConfig, headers
         if (body === null || typeof body !== "object")
             return undefined;
         const sharedArrayBuffer = getSharedArrayBufferPayload(body);
-        if (sharedArrayBuffer !== undefined)
-            return sharedArrayBuffer;
+        if (sharedArrayBuffer !== undefined) {
+            return { payload: sharedArrayBuffer, trustedReservedCodec: true };
+        }
+        if (isBufferReferenceValue(body) ||
+            isProcessSharedBufferValue(body)) {
+            return {
+                payload: body,
+                trustedReservedCodec: true,
+            };
+        }
         if (isExternalPayloadLike(body)) {
-            return body;
+            return {
+                payload: body,
+                trustedReservedCodec: false,
+            };
         }
         return undefined;
     };
@@ -782,7 +840,7 @@ export const encodePayload = ({ lockSector, payload, sab, payloadConfig, headers
         task.value = null;
         return true;
     };
-    const encodeEnvelopeExternalBody = (task, slotIndex, headerText, headerIsString, externalBody) => {
+    const encodeEnvelopeExternalBody = (task, slotIndex, headerText, headerIsString, externalBody, trustedReservedCodec) => {
         const codecId = readExternalPayloadCodecId(externalBody);
         if (codecId === undefined) {
             return encoderError({
@@ -792,9 +850,34 @@ export const encodePayload = ({ lockSector, payload, sab, payloadConfig, headers
                 detail: ENVELOPE_PAYLOAD_DETAIL,
             });
         }
+        if (trustedReservedCodec) {
+            if (processBoundary && isProcessLocalPointerCodec(codecId)) {
+                return encoderError({
+                    task,
+                    type: ErrorKnitting.Serializable,
+                    onPromise,
+                    detail: PROCESS_BOUNDARY_POINTER_PAYLOAD_DETAIL,
+                });
+            }
+        }
+        else if (isReservedExternalPayloadCodec(codecId)) {
+            return encoderError({
+                task,
+                type: ErrorKnitting.Serializable,
+                onPromise,
+                detail: processBoundary && isProcessLocalPointerCodec(codecId)
+                    ? PROCESS_BOUNDARY_POINTER_PAYLOAD_DETAIL
+                    : RESERVED_EXTERNAL_PAYLOAD_DETAIL,
+            });
+        }
         let bodyText;
         try {
-            bodyText = stringifyJSON([codecId, externalBody.toMetadata()]);
+            bodyText = stringifyJSON([
+                codecId,
+                trustedReservedCodec
+                    ? readTrustedExternalPayloadMetadata(externalBody)
+                    : externalBody.toMetadata(),
+            ]);
         }
         catch (error) {
             const detail = error instanceof Error ? error.message : String(error);
@@ -874,7 +957,7 @@ export const encodePayload = ({ lockSector, payload, sab, payloadConfig, headers
             const headerText = encodeEnvelopeHeaderText(task, header, headerIsString);
             if (headerText === undefined)
                 return false;
-            return encodeEnvelopeExternalBody(task, slotIndex, headerText, headerIsString, externalBody);
+            return encodeEnvelopeExternalBody(task, slotIndex, headerText, headerIsString, externalBody.payload, externalBody.trustedReservedCodec);
         }
         return encoderError({
             task,
@@ -947,7 +1030,7 @@ export const encodePayload = ({ lockSector, payload, sab, payloadConfig, headers
                     const objectValue = args;
                     const sharedArrayBufferPayload = getSharedArrayBufferPayload(objectValue);
                     if (sharedArrayBufferPayload !== undefined) {
-                        return encodeObjectExternalPayload(task, slotIndex, sharedArrayBufferPayload);
+                        return encodeObjectExternalPayload(task, slotIndex, sharedArrayBufferPayload, true);
                     }
                     const objectProto = objectGetPrototypeOf(objectValue);
                     if (isRuntimeUint8Array(objectValue)) {
@@ -997,6 +1080,10 @@ export const encodePayload = ({ lockSector, payload, sab, payloadConfig, headers
                         task.value = null;
                         return true;
                     }
+                    if (isBufferReferenceValue(objectValue) ||
+                        isProcessSharedBufferValue(objectValue)) {
+                        return encodeObjectExternalPayload(task, slotIndex, objectValue, true);
+                    }
                     const objectCtor = objectValue
                         .constructor;
                     if (isRuntimeBuffer(objectValue)) {
@@ -1126,7 +1213,7 @@ export const encodePayload = ({ lockSector, payload, sab, payloadConfig, headers
     };
     return encodeDispatch;
 };
-export const decodePayload = ({ lockSector, payload, sab, payloadConfig, headersBuffer, headerSlotStrideU32, textCompat, host, }) => {
+export const decodePayload = ({ lockSector, payload, sab, payloadConfig, headersBuffer, headerSlotStrideU32, textCompat, host, processBoundary = false, }) => {
     const payloadSab = payload?.sab ?? sab;
     const resolvedPayloadConfig = resolvePayloadBufferOptions({
         sab: payloadSab,
@@ -1152,7 +1239,13 @@ export const decodePayload = ({ lockSector, payload, sab, payloadConfig, headers
     // store the slot in their Task, to just get it when it comes
     // to the static versions of decoding
     return (task, slotIndex, specialFlags) => {
-        switch (task[TaskIndex.Type]) {
+        const payloadType = task[TaskIndex.Type];
+        if (processBoundary &&
+            (payloadType === PayloadBuffer.SharedArrayBuffer ||
+                payloadType === PayloadBuffer.BufferReference)) {
+            throw new TypeError(PROCESS_BOUNDARY_POINTER_PAYLOAD_DETAIL);
+        }
+        switch (payloadType) {
             case PayloadSignal.BigInt:
                 Uint32View[0] = task[TaskIndex.Start];
                 Uint32View[1] = task[TaskIndex.End];
@@ -1230,7 +1323,7 @@ export const decodePayload = ({ lockSector, payload, sab, payloadConfig, headers
                     ? rawHeader
                     : parseJSON(rawHeader);
                 const bodyStart = task[TaskIndex.Start];
-                const body = decodeExternalPayload(readDynamicUtf8(bodyStart, bodyStart + task[TaskIndex.End]));
+                const body = decodeExternalPayload(readDynamicUtf8(bodyStart, bodyStart + task[TaskIndex.End]), processBoundary);
                 task.value = new Envelope(header, body);
                 freeTaskSlot(task);
                 return;
@@ -1244,7 +1337,7 @@ export const decodePayload = ({ lockSector, payload, sab, payloadConfig, headers
                     PayloadBuffer.EnvelopeDynamicHeaderStringExternal
                     ? rawHeader
                     : parseJSON(rawHeader);
-                const body = decodeExternalPayload(readDynamicUtf8(bodyStart, bodyStart + task[TaskIndex.End]));
+                const body = decodeExternalPayload(readDynamicUtf8(bodyStart, bodyStart + task[TaskIndex.End]), processBoundary);
                 task.value = new Envelope(header, body);
                 freeTaskSlot(task);
                 return;
@@ -1324,11 +1417,11 @@ export const decodePayload = ({ lockSector, payload, sab, payloadConfig, headers
                 return;
             }
             case PayloadBuffer.ExternalPayload:
-                task.value = decodeExternalPayload(readDynamicUtf8(task[TaskIndex.Start], task[TaskIndex.Start] + task[TaskIndex.PayloadLen]));
+                task.value = decodeExternalPayload(readDynamicUtf8(task[TaskIndex.Start], task[TaskIndex.Start] + task[TaskIndex.PayloadLen]), processBoundary);
                 freeTaskSlot(task);
                 return;
             case PayloadBuffer.StaticExternalPayload:
-                task.value = decodeExternalPayload(readStaticUtf8(0, task[TaskIndex.PayloadLen], slotIndex));
+                task.value = decodeExternalPayload(readStaticUtf8(0, task[TaskIndex.PayloadLen], slotIndex), processBoundary);
                 return;
             case PayloadBuffer.ProcessSharedBuffer:
                 task.value = decodeProcessSharedBufferNumericWords(readStaticU32Words(processSharedBufferWords, PROCESS_SHARED_BUFFER_NUMERIC_WORDS, slotIndex));
@@ -1375,3 +1468,6 @@ export const decodePayload = ({ lockSector, payload, sab, payloadConfig, headers
         }
     };
 };
+// Break the lock.ts <-> payloadCodec.ts cycle (see lock.ts): register the codec
+// factories on load instead of having lock.ts import them.
+registerLockPayloadCodec(encodePayload, decodePayload);

package/src/permission/compatibility.d.ts

@@ -0,0 +1,28 @@
+import type { PermissionProtocolInput, ResolvedPermissionProtocol } from "./protocol.js";
+type ProcessPermissionRuntime = "bun" | "deno" | "node";
+type PermissionCompatibilityLevel = "exact" | "coarse" | "unsupported";
+type ProcessPermissionTarget = {
+    runtime: ProcessPermissionRuntime;
+    /**
+     * Omitted when a wrapper or another host runtime makes the Node version
+     * impossible to prove synchronously.
+     */
+    nodeMajor?: number;
+};
+type PermissionCompatibilityCheck = {
+    permission: string;
+    level: PermissionCompatibilityLevel;
+    explicit: boolean;
+    reason: string;
+};
+type ProcessPermissionCompatibilityReport = {
+    target: ProcessPermissionTarget;
+    checks: PermissionCompatibilityCheck[];
+};
+export declare const classifyProcessPermissionCompatibility: ({ permission, resolved, target, }: {
+    permission: PermissionProtocolInput | undefined;
+    resolved: ResolvedPermissionProtocol | undefined;
+    target: ProcessPermissionTarget;
+}) => ProcessPermissionCompatibilityReport;
+export declare const enforceProcessPermissionCompatibility: (report: ProcessPermissionCompatibilityReport) => void;
+export type { PermissionCompatibilityCheck, PermissionCompatibilityLevel, ProcessPermissionCompatibilityReport, ProcessPermissionRuntime, ProcessPermissionTarget, };