knitting 0.1.62 → 0.1.70

package/src/memory/lock.js

@@ -9,12 +9,7 @@ import { createSharedArrayBuffer, createWasmSharedArrayBuffer, } from "../common
 import { toSharedBufferRegion, } from "../common/shared-buffer-region.js";
 import { probeLockBufferTextCompat, } from "../common/shared-buffer-text.js";
 import { resolvePayloadBufferOptions, } from "./payload-config.js";
-/**
- * TODO: Compose all the instance where the array is passed as argument
- */
-// 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.
+// Use const objects instead of enums; Andromeda's Nova engine cannot parse enums.
 export const PayloadSignal = {
     UNREACHABLE: 0,
     BigInt: 2,
@@ -68,6 +63,12 @@ export const PayloadBuffer = {
     EnvelopeDynamicHeaderStringExternal: 52,
     NumericArray: 53,
     StaticNumericArray: 54,
+    /** Binary payload already stored in the dynamic arena. */
+    ArenaBinary: 55,
+    /** A returned Uint8Array whose ArrayBuffer ownership was moved to the host. */
+    MovedBinary: 56,
+    /** A returned ArrayBuffer whose ownership was moved to the host. */
+    MovedArrayBuffer: 57,
 };
 // Value -> name lookup (enum reverse-map), for payload-limit error labels.
 // Later keys win on duplicate values (11 -> "String"), as TS enums do.
@@ -116,6 +117,13 @@ export const addTaskFinalizer = (task, finalizer) => {
         }
     };
 };
+/** Take an owner-lifetime transport hold, if the value supports one. */
+export const takePayloadTransportHold = (value) => {
+    if (value === null || typeof value !== "object")
+        return undefined;
+    const finalizer = value[PayloadTransportFinalizer]?.();
+    return typeof finalizer === "function" ? finalizer : undefined;
+};
 export const attachPayloadTransportFinalizer = (task, value) => {
     if (task.finalize !== undefined || value === null || typeof value !== "object") {
         return;
@@ -143,18 +151,19 @@ export const TaskIndex = {
     /**
      * 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`.
+     * Shares storage with `FlagsToHost`.
      */
     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).
+     * Payload length; bit 31 stores the high bit of a dynamic-region index.
+     * Write the length before `tagTaskSlot()` and mask bit 31 when reading it.
      */
+    End: 4,
+    PayloadLen: 5,
+    /** Low 5 bits hold the dynamic-region index; the remaining bits hold metadata. */
     slotBuffer: 6,
     Size: 8,
     /**
@@ -228,10 +237,9 @@ export const HEADER_STATIC_PAYLOAD_U32 = TaskIndex.TotalBuff -
 export const HEADER_TASK_OFFSET_IN_SLOT_U32 = HEADER_STATIC_PAYLOAD_U32;
 // Work-stealing control words live in the unused tail of each slot's header
 // cache line. Task words occupy 0..7 (`TASK_LOCAL_FLAGS_INDEX = 7`) of the
-// 16-word line, leaving words 8..15 free. Consumer `c` owns slot `c`'s pair, and
-// because the slot stride is exactly 9 cache lines those pairs land on distinct
-// lines. `ACK[c]` and `WANT[c]` share one line on purpose: same single writer,
-// and a peer reading one pulls the other for free.
+// 16-word line, leaving words 8..15 free. Consumer `c` owns slot `c`'s words,
+// and the slot stride keeps those words on separate cache lines.
+// The ACK word was removed; retirement is folded into `workerBits`.
 export const STEAL_ACK_SLOT_OFFSET_U32 = HEADER_TASK_OFFSET_IN_SLOT_U32 +
     TaskIndex.Size;
 export const STEAL_WANT_SLOT_OFFSET_U32 = STEAL_ACK_SLOT_OFFSET_U32 + 1;
@@ -249,6 +257,13 @@ export const STEAL_PAYLOAD_ACK_SLOT_OFFSET_U32 = STEAL_ACK_SLOT_OFFSET_U32 + 2;
 export const STEAL_LIVE_SLOT_OFFSET_U32 = STEAL_PAYLOAD_ACK_SLOT_OFFSET_U32 + 1;
 /** Host-owned arm word for the return-lock completion doorbell. */
 export const DOORBELL_ARMED_SLOT_OFFSET_U32 = STEAL_LIVE_SLOT_OFFSET_U32 + 1;
+/** Shared region-owner mask for the `cas-mask` claim discipline. */
+export const STEAL_CLAIM_MASK_SLOT_OFFSET_U32 = DOORBELL_ARMED_SLOT_OFFSET_U32 + 1;
+// A producer claims ARMED before ringing the host. Keeping SIGNALLED until the
+// host drains coalesces a burst of published frames into one native/IPC wake.
+const DOORBELL_OFF = 0;
+const DOORBELL_ARMED = 1;
+const DOORBELL_SIGNALLED = 2;
 export const HEADER_U32_LENGTH = LockBound.header +
     (HEADER_SLOT_STRIDE_U32 * LockBound.slots);
 export const HEADER_BYTE_LENGTH = HEADER_U32_LENGTH *
@@ -288,18 +303,17 @@ const makeTaskFrom = (array, at) => {
     fillTaskFrom(task, array, at);
     return task;
 };
-// could be inlined
 const settleTask = (task) => {
     if (task[TaskIndex["FlagsToHost"]] === 0) {
         task.resolve(task.value);
     }
     else {
         task.reject(task.value);
-        // restarting the flag
+        // Clear the rejection marker before the task slot is reused.
         task[TaskIndex["FlagsToHost"]] = 0;
     }
 };
-export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload, payloadConfig, payloadSector, textCompat, resultList, toSentList, recycleList, processBoundary, consumers, consumerId, regionLanes, notifyOnHostPublish, }) => {
+export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload, payloadConfig, payloadSector, textCompat, resultList, toSentList, recycleList, processBoundary, sharedReturn, moveReturn, consumers, consumerId, regionLanes, stealClaim, notifyOnHostPublish, notifyHostPublish, }) => {
     // Layout within `lockSectorRegion`:
     // - hostBits starts at byte 0
     // - workerBits starts at byte 64
@@ -307,9 +321,8 @@ export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload,
     // The remaining two cache lines in the 256-byte sector are reserved for the
     // payload allocator lock (`PAYLOAD_LOCK_*` at bytes 128 and 192).
     //
-    // Important: encode() always toggles `hostBits` and decode/resolveHost always
-    // toggles `workerBits`, regardless of which thread calls them. This is why
-    // the "return lock" (worker->host responses) still publishes into `hostBits`.
+    // encode toggles hostBits; decode/resolveHost toggles workerBits. The return
+    // lock therefore publishes responses through hostBits as well.
     const lockSectorRegion = toSharedBufferRegion(LockBoundSector ??
         createWasmSharedArrayBuffer(LOCK_SECTOR_BYTE_LENGTH));
     const LockBoundSAB = lockSectorRegion.sab;
@@ -336,23 +349,22 @@ export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload,
         headers: headersRegion,
         payload: payloadSAB,
     });
-    // ---- work stealing (multi-consumer) state ----
-    // With N consumers the pending set is A ^ ACK[0] ^ ... ^ ACK[N-1]; every word
-    // still has exactly one writer, so no shared writable word is introduced.
+    // Work-stealing state. Pending lanes are A ^ ACK[0] ^ ... ^ ACK[N-1].
     const stealConsumers = Math.max(1, (consumers ?? 1) | 0);
     const stealEnabled = stealConsumers > 1;
-    // A lock2 built without `consumerId` is the producer endpoint: it encodes but
-    // never claims. It still frees payload slots, so it needs an acknowledgement
-    // word of its own rather than sharing consumer 0's.
+    // The producer encodes and frees payload slots but never claims a region.
     const stealIsProducer = consumerId === undefined;
     const stealId = (consumerId ?? 0) | 0;
     const stealRegionLanes = (regionLanes ?? 8) | 0;
     const stealRegions = (LockBound.slots / stealRegionLanes) | 0;
+    const stealClaimMask = stealClaim === "cas-mask";
     if (stealEnabled) {
         if (stealRegionLanes < 1 || (stealRegionLanes & (stealRegionLanes - 1)) !== 0) {
             throw new RangeError("regionLanes must be a power of two");
         }
-        if (stealRegions < stealConsumers) {
+        // Dekker requires at least one region per live consumer plus a spare.
+        // CAS-mask claimants can retry when all regions are owned.
+        if (!stealClaimMask && stealRegions < stealConsumers) {
             throw new RangeError(`regionLanes=${stealRegionLanes} yields ${stealRegions} regions, ` +
                 `too few for ${stealConsumers} consumers`);
         }
@@ -363,28 +375,24 @@ export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload,
     // Int32 alias over the headers SAB so the control words get signed bit math
     // consistent with the rest of the protocol.
     const stealView = new Int32Array(headersRegion.sab, headersRegion.byteOffset, headersRegion.byteLength >>> 2);
-    const stealAckIndex = new Int32Array(stealConsumers);
     const stealWantIndex = new Int32Array(stealConsumers);
     for (let c = 0; c < stealConsumers; c++) {
-        const slotBase = (c * headersSlotStride) + LockBound.header;
-        stealAckIndex[c] = slotBase + STEAL_ACK_SLOT_OFFSET_U32;
-        stealWantIndex[c] = slotBase + STEAL_WANT_SLOT_OFFSET_U32;
+        stealWantIndex[c] = (c * headersSlotStride) + LockBound.header +
+            STEAL_WANT_SLOT_OFFSET_U32;
     }
     const stealLiveIndex = LockBound.header + STEAL_LIVE_SLOT_OFFSET_U32;
+    /** Single shared owner bitmask, used by `cas-mask` only. */
+    const stealMaskIndex = LockBound.header + STEAL_CLAIM_MASK_SLOT_OFFSET_U32;
     const stealAllLiveMask = stealConsumers === 32
         ? -1
         : ((1 << stealConsumers) - 1) | 0;
     if (stealEnabled && stealIsProducer) {
         Atomics.store(stealView, stealLiveIndex, stealAllLiveMask);
+        // A carpet can outlive one pool on a reused buffer; never inherit owners.
+        if (stealClaimMask)
+            Atomics.store(stealView, stealMaskIndex, 0);
     }
     const stealIsLive = (mask, consumer) => (mask & (1 << consumer)) !== 0;
-    const stealAckXorAll = () => {
-        let x = 0 | 0;
-        for (let c = 0; c < stealConsumers; c++) {
-            x = (x ^ a_load(stealView, stealAckIndex[c])) | 0;
-        }
-        return x;
-    };
     let promiseHandler;
     if (registeredEncodePayload === undefined ||
         registeredDecodePayload === undefined) {
@@ -401,6 +409,8 @@ export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload,
         lockSector: payloadLockRegion,
         textCompat: resolvedTextCompat,
         processBoundary,
+        sharedReturn,
+        moveReturn,
         onPromise: (task, isRejected, value) => {
             if ((task[TASK_LOCAL_FLAGS_INDEX] & TASK_LOCAL_PROMISE_TRACKED_FLAG) !==
                 0 &&
@@ -432,9 +442,9 @@ export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload,
     const resolved = resultList ?? new RingQueue();
     let deferredCount = 0 | 0;
     let pendingPromiseCount = 0 | 0;
-    // Atomics aliases (hot path)
     const a_load = Atomics.load;
     const a_store = Atomics.store;
+    const a_compareExchange = Atomics.compareExchange;
     const a_notify = Atomics.notify;
     const shouldNotifyHostPublish = notifyOnHostPublish === true;
     const a_waitAsync = typeof Atomics.waitAsync === "function"
@@ -442,15 +452,13 @@ export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload,
         : undefined;
     // Sender-side cached shadow of the receiver-owned queue word. Under the XSC
     // false-busy-only sender-side staleness property, this may hide newly freed
-    // lanes but cannot make a genuinely pending lane appear free. Refresh only
+    // lanes but cannot make a pending lane appear free. Refresh only
     // when the cached free set is exhausted.
     let workerShadow = 0 | 0;
-    const refreshWorkerShadow = stealEnabled
-        ? () => workerShadow = stealAckXorAll()
-        : () => workerShadow = a_load(workerBits, 0) | 0;
+    // Under stealing, workerBits also records retired lanes.
+    const refreshWorkerShadow = () => workerShadow = a_load(workerBits, 0) | 0;
     refreshWorkerShadow();
     const ensureSenderStateHasFree = (state) => (~state) !== 0 ? state : (LastLocal ^ refreshWorkerShadow()) | 0;
-    // RingQueue method aliases (hot path)
     const toBeSentPush = (task) => toBeSent.push(task);
     const toBeSentShift = () => toBeSent.shiftNoClear();
     const toBeSentUnshift = (task) => toBeSent.unshift(task);
@@ -574,8 +582,22 @@ export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload,
     };
     const storeHost = (bit) => {
         a_store(hostBits, 0, LastLocal = (LastLocal ^ bit) | 0);
-        if (shouldNotifyHostPublish && a_load(doorbellArmed, 0) !== 0) {
-            a_notify(hostBits, 0, 1);
+        if (shouldNotifyHostPublish &&
+            a_compareExchange(doorbellArmed, 0, DOORBELL_ARMED, DOORBELL_SIGNALLED) === DOORBELL_ARMED) {
+            if (notifyHostPublish !== undefined) {
+                try {
+                    notifyHostPublish();
+                }
+                catch {
+                    // A callback can be unavailable after forced worker teardown. Restore
+                    // the arm only when it still belongs to this publication, so a later
+                    // result can retry without overwriting a host-side disarm/re-arm.
+                    a_compareExchange(doorbellArmed, 0, DOORBELL_SIGNALLED, DOORBELL_ARMED);
+                }
+            }
+            else {
+                a_notify(hostBits, 0, 1);
+            }
         }
     };
     const storeWorker = (bit) => a_store(workerBits, 0, LastWorker = (LastWorker ^ bit) | 0);
@@ -618,9 +640,6 @@ export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload,
         return true;
     };
     const hasSpace = () => (hostBits[0] ^ LastWorker) !== 0;
-    /**
-     * WORKER SIDE: decode
-     */
     const decode = () => {
         let diff = (a_load(hostBits, 0) ^ LastWorker) | 0;
         if (diff === 0)
@@ -651,28 +670,20 @@ export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload,
         lastTake = last;
         return true;
     };
-    /**
-     * WORKER SIDE: decode, region-Dekker stealing variant.
-     *
-     * Claims one whole region of `stealRegionLanes` lanes per handshake, so the
-     * StoreLoad barrier is amortised over the region rather than paid per task.
-     * Priority is fixed by endpoint id: a junior withdraws for a senior, so at
-     * most one consumer ever acknowledges a published generation.
-     *
-     * The C reference needs an explicit mfence between the intent store and the
-     * peer loads. `Atomics.store` is sequentially consistent in JS, so that
-     * barrier is implicit here and holds on x86 and ARM alike.
-     */
     const stealLaneMask = (region) => stealRegionLanes === 32
         ? -1
         : ((((1 << stealRegionLanes) - 1) << (region * stealRegionLanes)) | 0);
-    const stealPeerAcks = () => {
-        let x = 0 | 0;
-        for (let c = 0; c < stealConsumers; c++) {
-            if (c !== stealId)
-                x = (x ^ a_load(stealView, stealAckIndex[c])) | 0;
-        }
-        return x;
+    const stealRegionBits = stealRegionLanes === 32
+        ? -1
+        : ((1 << stealRegionLanes) - 1) | 0;
+    /** Find the oldest pending lane in a claimed region. */
+    const stealOldestLane = (region, take) => {
+        const low = (region * stealRegionLanes) | 0;
+        const lanes = ((take >>> low) & stealRegionBits) | 0;
+        const predecessors = ((lanes >>> 1) | (lanes << (stealRegionLanes - 1))) & stealRegionBits;
+        const oldest = (lanes & ~predecessors) | 0;
+        return low +
+            (oldest === 0 ? stealRegionLanes - 1 : 31 - clz32(oldest >>> 0));
     };
     const stealJuniorWants = (intent) => {
         const live = a_load(stealView, stealLiveIndex) | 0;
@@ -684,9 +695,12 @@ export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload,
         }
         return false;
     };
-    let stealCursor = ((stealRegions * stealId) / stealConsumers) | 0;
+    const stealHome = ((stealRegions * stealId) / stealConsumers) | 0;
+    let stealCursor = stealHome;
+    /** Decode one region using the Dekker claim protocol. */
     const decodeSteal = () => {
-        const pending = (a_load(hostBits, 0) ^ LastWorker ^ stealPeerAcks()) | 0;
+        // workerBits includes retired lanes under stealing.
+        const pending = (a_load(hostBits, 0) ^ a_load(workerBits, 0)) | 0;
         if (pending === 0)
             return false;
         let pendingRegions = 0 | 0;
@@ -699,6 +713,8 @@ export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload,
             }
         }
         const liveBeforeClaim = a_load(stealView, stealLiveIndex) | 0;
+        // Prefer regions no live peer currently wants; the handshake below provides
+        // the actual mutual exclusion.
         let peerIntent = 0 | 0;
         let seniorIntent = 0 | 0;
         for (let c = 0; c < stealConsumers; c++) {
@@ -726,50 +742,138 @@ export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload,
             return false;
         const intent = (1 << region) | 0;
         a_store(stealView, stealWantIndex[stealId], intent);
-        // Dekker StoreLoad: implicit, `Atomics.store` above is seq-cst.
+        // Atomics.store is sequentially consistent, so it supplies the StoreLoad
+        // barrier required by Dekker.
+        // A senior claimant has priority.
         let seniorConflict = false;
-        let juniorConflict = false;
-        for (let c = 0; c < stealConsumers; c++) {
-            if (c === stealId || !stealIsLive(liveBeforeClaim, c))
+        for (let c = 0; c < stealId; c++) {
+            if (!stealIsLive(liveBeforeClaim, c))
                 continue;
-            if ((a_load(stealView, stealWantIndex[c]) & intent) === 0)
-                continue;
-            if (c < stealId)
+            if ((a_load(stealView, stealWantIndex[c]) & intent) !== 0) {
                 seniorConflict = true;
-            else
-                juniorConflict = true;
+                break;
+            }
         }
         if (seniorConflict) {
             a_store(stealView, stealWantIndex[stealId], 0);
             return false;
         }
+        let juniorConflict = false;
+        for (let c = stealId + 1; c < stealConsumers; c++) {
+            if (!stealIsLive(liveBeforeClaim, c))
+                continue;
+            if ((a_load(stealView, stealWantIndex[c]) & intent) !== 0) {
+                juniorConflict = true;
+                break;
+            }
+        }
         if (juniorConflict) {
             while (stealJuniorWants(intent)) { /* junior withdraws */ }
         }
-        // Last control loads before ownership. After this no control word is read
-        // until every slot in `take` has been decoded.
-        const take = ((a_load(hostBits, 0) ^ LastWorker ^ stealPeerAcks()) &
+        // No control word is read again until all selected slots are decoded.
+        const take = ((a_load(hostBits, 0) ^ a_load(workerBits, 0)) &
             stealLaneMask(region)) | 0;
         if (take === 0) {
             a_store(stealView, stealWantIndex[stealId], 0);
             return false;
         }
+        // Retire lanes and release the claim even if decoding throws.
         let lanes = take;
-        while (lanes !== 0) {
-            decodeAt(31 - clz32((lanes & -lanes) >>> 0));
-            lanes = (lanes & (lanes - 1)) | 0;
-        }
-        // Retire the whole claimed mask with one ACK store, then release the region.
-        // ACK before intent-clear (paper Assumption 2(ii)).
-        LastWorker = (LastWorker ^ take) | 0;
-        a_store(stealView, stealAckIndex[stealId], LastWorker);
-        a_store(stealView, stealWantIndex[stealId], 0);
-        stealCursor = (region + 1) % stealRegions;
+        let done = 0 | 0;
+        // Decode the claimed lanes in producer order.
+        let at = stealOldestLane(region, take);
+        const regionLow = (region * stealRegionLanes) | 0;
+        const regionHigh = (regionLow + stealRegionLanes - 1) | 0;
+        try {
+            for (let step = 0; step < stealRegionLanes; step++) {
+                const bit = (1 << at) | 0;
+                if ((lanes & bit) !== 0) {
+                    decodeAt(at);
+                    lanes = (lanes ^ bit) | 0;
+                    done = (done ^ bit) | 0;
+                    if (lanes === 0)
+                        break;
+                }
+                at = at === regionLow ? regionHigh : at - 1;
+            }
+        }
+        finally {
+            // Publish the ACK before clearing intent.
+            LastWorker = (LastWorker ^ done) | 0;
+            if (done !== 0)
+                Atomics.xor(workerBits, 0, done);
+            a_store(stealView, stealWantIndex[stealId], 0);
+            stealCursor = stealHome;
+        }
+        return true;
+    };
+    /** Claim one region in the shared owner mask. */
+    const decodeStealCasMask = () => {
+        const pending = (a_load(hostBits, 0) ^ a_load(workerBits, 0)) | 0;
+        if (pending === 0)
+            return false;
+        let owners = a_load(stealView, stealMaskIndex) | 0;
+        let region = -1;
+        let intent = 0 | 0;
+        for (let step = 0; step < stealRegions && region < 0; step++) {
+            const candidate = stealCursor + step < stealRegions
+                ? stealCursor + step
+                : stealCursor + step - stealRegions;
+            if ((pending & stealLaneMask(candidate)) === 0)
+                continue;
+            const bit = (1 << candidate) | 0;
+            // Retry a changed mask once before trying another region.
+            for (let attempt = 0; attempt < 2; attempt++) {
+                if ((owners & bit) !== 0)
+                    break;
+                const previous = a_compareExchange(stealView, stealMaskIndex, owners, (owners | bit) | 0) | 0;
+                if (previous === owners) {
+                    region = candidate;
+                    intent = bit;
+                    break;
+                }
+                owners = previous;
+            }
+        }
+        if (region < 0)
+            return false;
+        a_store(stealView, stealWantIndex[stealId], intent);
+        const take = ((a_load(hostBits, 0) ^ a_load(workerBits, 0)) &
+            stealLaneMask(region)) | 0;
+        if (take === 0) {
+            a_store(stealView, stealWantIndex[stealId], 0);
+            Atomics.and(stealView, stealMaskIndex, ~intent);
+            return false;
+        }
+        let lanes = take;
+        let done = 0 | 0;
+        // Decode the claimed lanes in producer order.
+        let at = stealOldestLane(region, take);
+        const regionLow = (region * stealRegionLanes) | 0;
+        const regionHigh = (regionLow + stealRegionLanes - 1) | 0;
+        try {
+            for (let step = 0; step < stealRegionLanes; step++) {
+                const bit = (1 << at) | 0;
+                if ((lanes & bit) !== 0) {
+                    decodeAt(at);
+                    lanes = (lanes ^ bit) | 0;
+                    done = (done ^ bit) | 0;
+                    if (lanes === 0)
+                        break;
+                }
+                at = at === regionLow ? regionHigh : at - 1;
+            }
+        }
+        finally {
+            LastWorker = (LastWorker ^ done) | 0;
+            if (done !== 0)
+                Atomics.xor(workerBits, 0, done);
+            a_store(stealView, stealWantIndex[stealId], 0);
+            Atomics.and(stealView, stealMaskIndex, ~intent);
+            stealCursor = stealHome;
+        }
         return true;
     };
-    /**
-     * HOST SIDE: decode version
-     */
     const resolveHost = ({ queue, onResolved, shouldSettle, activeRejectPlaceholder, }) => {
         const getTask = takeTask({ queue });
         let lastResolved = 32;
@@ -895,27 +999,21 @@ export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload,
             return modified;
         };
     };
-    /**
-     * HOST SIDE: wait until the producer changes hostBits.
-     *
-     * LastWorker is the host's acknowledgement shadow. Passing it as the
-     * expected value makes the arm race-free: a publication between the drain
-     * and this call returns `not-equal` synchronously instead of being lost.
-    */
+    /** Wait for a producer publication without losing an intervening wakeup. */
     const waitForHostChange = (timeoutMs) => {
         if (a_waitAsync === undefined) {
-            a_store(doorbellArmed, 0, 0);
+            a_store(doorbellArmed, 0, DOORBELL_OFF);
             return undefined;
         }
-        a_store(doorbellArmed, 0, 1);
+        a_store(doorbellArmed, 0, DOORBELL_ARMED);
         try {
             const wait = a_waitAsync(hostBits, 0, LastWorker | 0, timeoutMs);
             if (!wait.async)
-                a_store(doorbellArmed, 0, 0);
+                a_store(doorbellArmed, 0, DOORBELL_OFF);
             return wait;
         }
         catch {
-            a_store(doorbellArmed, 0, 0);
+            a_store(doorbellArmed, 0, DOORBELL_OFF);
             // Some runtimes reject particular SharedArrayBuffer implementations
             // (for example a growable or native-backed buffer). Fall back to the
             // existing dispatcher rather than turning a capability issue into a
@@ -923,6 +1021,18 @@ export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload,
             return undefined;
         }
     };
+    /**
+     * Arm a native host notifier with the same no-lost-wakeup property as
+     * waitAsync: a publication before or during the arm is observed directly,
+     * while one after the observation sees the shared armed bit and rings.
+     */
+    const armHostNotifier = () => {
+        a_store(doorbellArmed, 0, DOORBELL_ARMED);
+        if (a_load(hostBits, 0) === (LastWorker | 0))
+            return true;
+        a_store(doorbellArmed, 0, DOORBELL_OFF);
+        return false;
+    };
     const decodeAt = (at) => {
         const off = (at * headersSlotStride) + slotBaseU32;
         const recycled = recycleShift();
@@ -980,6 +1090,11 @@ export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload,
         }
         const bit = 1 << id;
         const previous = Atomics.and(stealView, stealLiveIndex, ~bit);
+        if (stealClaimMask) {
+            const stranded = a_load(stealView, stealWantIndex[id]) | 0;
+            if (stranded !== 0)
+                Atomics.and(stealView, stealMaskIndex, ~stranded);
+        }
         return (previous & bit) !== 0;
     };
     return {
@@ -989,7 +1104,9 @@ export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload,
         encodeAll,
         publish,
         flushPending,
-        decode: stealEnabled ? decodeSteal : decode,
+        decode: stealEnabled
+            ? (stealClaimMask ? decodeStealCasMask : decodeSteal)
+            : decode,
         hasSpace,
         resolved,
         hostBits,
@@ -997,8 +1114,9 @@ export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload,
         recyclecList,
         resolveHost,
         waitForHostChange,
+        armHostNotifier,
         setHostWaiterArmed: (armed) => {
-            a_store(doorbellArmed, 0, armed ? 1 : 0);
+            a_store(doorbellArmed, 0, armed ? DOORBELL_ARMED : DOORBELL_OFF);
         },
         hasPendingFrames: () => toBeSent.size !== 0,
         getPendingFrameCount: () => toBeSent.size | 0,

package/src/memory/payloadCodec.d.ts

@@ -1,12 +1,18 @@
 import { type PromisePayloadHandler, type Task } from "./lock.js";
 import type { LockBufferTextCompat } from "../common/shared-buffer-text.js";
 import { type PayloadBufferOptions } from "./payload-config.js";
-import type { SharedBufferSource } from "../common/shared-buffer-region.js";
+import { type SharedBufferSource } from "../common/shared-buffer-region.js";
+/** Minimum size for automatically borrowed byte returns. */
+export declare const SHARED_RETURN_MIN_BYTES: number;
+/** Number of later borrowed returns kept before a region is recycled. */
+export declare const SHARED_RETURN_BORROW_WINDOW = 32;
+/** The borrowed-region allocator for `payload`, if an encoder built one. */
+export declare const getSharedReturnAllocator: (payload: object) => ((byteLength: number, zeroFill?: boolean) => Uint8Array | undefined) | undefined;
 /**
  * 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, processBoundary, }: {
+export declare const encodePayload: ({ lockSector, payload, sab, payloadConfig, headersBuffer, headerSlotStrideU32, textCompat, onPromise, processBoundary, sharedReturn, moveReturn, }: {
     lockSector?: SharedBufferSource;
     payload?: {
         sab?: SharedBufferSource;
@@ -29,6 +35,16 @@ export declare const encodePayload: ({ lockSector, payload, sab, payloadConfig,
      * Process transports must set this on both encoders and decoders.
      */
     processBoundary?: boolean;
+    /**
+     * Enable explicit `sharedBytes()` allocations on a worker return lane.
+     * Ordinary byte returns never become borrowed implicitly.
+     */
+    sharedReturn?: boolean;
+    /**
+     * Move large top-level byte returns into an owned host ArrayBuffer. Unlike a
+     * borrowed return, the result stays valid until the host drops it.
+     */
+    moveReturn?: boolean;
 }) => (task: Task, slotIndex: number) => boolean;
 export declare const decodePayload: ({ lockSector, payload, sab, payloadConfig, headersBuffer, headerSlotStrideU32, textCompat, host, processBoundary, }: {
     lockSector?: SharedBufferSource;