knitting 0.1.70 → 0.1.73

package/src/memory/lock.js

@@ -257,8 +257,30 @@ 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;
+/**
+ * Non-wrapping 64-bit claim head for the `ticket` discipline. The producer
+ * publishes only the low 32 bits of the tail. A successful head CAS validates
+ * the snapshot: with that head unchanged, at most 32 tickets can be pending,
+ * so unsigned subtraction recovers the exact distance even across tail wrap.
+ * Head and tail occupy different slots' header lines (slots 0 and 1).
+ */
+export const STEAL_TICKET_HEAD_SLOT_OFFSET_U32 = DOORBELL_ARMED_SLOT_OFFSET_U32 + 2; // Keep the 64-bit head aligned.
+/** Negative head permanently closes a failed ticket queue. */
+export const STEAL_TICKET_FAILED = -1n;
+const STEAL_TICKET_LIMIT = (1n << 63n) - 1n;
+const STEAL_TICKET_LOW_MASK = 0xffffffffn;
+/**
+ * Publication-order ring. `order[t & 31]` is the slot the producer filled for
+ * ticket `t`, so a ticket names a lane without the ticket having to *be* the
+ * lane: the producer keeps its free-bit allocation and claims follow publication
+ * order. Cell `i` uses the former ACK word; words 14..15
+ * are reserved for the head in slot 0 and the tail in slot 1.
+ */
+export const STEAL_TICKET_ORDER_SLOT_OFFSET_U32 = STEAL_ACK_SLOT_OFFSET_U32;
+/** Ring cells, and therefore the wrap mask, follow the slot count. */
+export const STEAL_TICKET_RING_MASK = (LockBound.slots - 1) | 0;
+/** Bounded CAS retries before a claimant re-polls from the worker loop. */
+const STEAL_TICKET_ATTEMPTS = 2;
 // 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;
@@ -313,7 +335,46 @@ const settleTask = (task) => {
         task[TaskIndex["FlagsToHost"]] = 0;
     }
 };
-export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload, payloadConfig, payloadSector, textCompat, resultList, toSentList, recycleList, processBoundary, sharedReturn, moveReturn, consumers, consumerId, regionLanes, stealClaim, notifyOnHostPublish, notifyHostPublish, }) => {
+/**
+ * Claim discipline for stealing consumers.
+ *
+ * - `dekker`: per-consumer intent words and an O(N) peer survey.
+ * - `ticket`: one monotonic counter; a CAS on the head claims lanes in
+ *   publication order, with no regions and no per-consumer state.
+ */
+export const STEAL_CLAIM_DISCIPLINES = ["dekker", "ticket"];
+/** Disciplines that once existed, so a stale config gets a useful error. */
+const REMOVED_STEAL_CLAIMS = {
+    "cas-mask": "cas-mask was removed; use ticket",
+};
+/**
+ * Validate a claim discipline coming from an untrusted source — an env var, or
+ * a JS caller the type system never saw.
+ *
+ * This throws rather than falling back, because a silent fallback is worse than
+ * a crash here: a stale `cas-mask` setting or a typo would quietly run Dekker,
+ * and every benchmark and test built on it would report Dekker's numbers under
+ * another name. Both sides of a lock must also agree, so an unrecognised value
+ * that resolved differently on host and worker would corrupt the protocol.
+ */
+export const assertStealClaim = (value, source) => {
+    if (typeof value === "string" &&
+        STEAL_CLAIM_DISCIPLINES.includes(value)) {
+        return value;
+    }
+    const hint = typeof value === "string" && REMOVED_STEAL_CLAIMS[value] !== undefined
+        ? ` (${REMOVED_STEAL_CLAIMS[value]})`
+        : "";
+    throw new RangeError(`${source} must be one of ${STEAL_CLAIM_DISCIPLINES.join(", ")}; ` +
+        `got ${JSON.stringify(value)}${hint}`);
+};
+/**
+ * The discipline chosen when nothing selects one. Host and worker default
+ * independently, so this must be a single shared constant: two sides landing on
+ * different disciplines would read the same buffer under different protocols.
+ */
+export const DEFAULT_STEAL_CLAIM = "ticket";
+export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload, payloadConfig, payloadSector, textCompat, resultList, toSentList, recycleList, processBoundary, sharedReturn, moveReturn, consumers, consumerId, regionLanes, stealClaim, notifyOnHostPublish, notifyHostPublish, traceClaim, }) => {
     // Layout within `lockSectorRegion`:
     // - hostBits starts at byte 0
     // - workerBits starts at byte 64
@@ -357,14 +418,20 @@ export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload,
     const stealId = (consumerId ?? 0) | 0;
     const stealRegionLanes = (regionLanes ?? 8) | 0;
     const stealRegions = (LockBound.slots / stealRegionLanes) | 0;
-    const stealClaimMask = stealClaim === "cas-mask";
+    // Validate before use: an unrecognised value must not degrade to Dekker.
+    const stealClaimResolved = stealClaim === undefined
+        ? DEFAULT_STEAL_CLAIM
+        : assertStealClaim(stealClaim, "stealClaim");
+    const stealTicket = stealClaimResolved === "ticket";
     if (stealEnabled) {
+        if (stealTicket && headersSlotStride % 2 !== 0) {
+            throw new RangeError("ticket headers must have an 8-byte aligned slot stride");
+        }
         if (stealRegionLanes < 1 || (stealRegionLanes & (stealRegionLanes - 1)) !== 0) {
             throw new RangeError("regionLanes must be a power of two");
         }
-        // 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) {
+        // Dekker requires at least one region per consumer.
+        if (!stealTicket && stealRegions < stealConsumers) {
             throw new RangeError(`regionLanes=${stealRegionLanes} yields ${stealRegions} regions, ` +
                 `too few for ${stealConsumers} consumers`);
         }
@@ -381,16 +448,41 @@ export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload,
             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;
+    /** Head (consumer-CAS) and tail (producer-store) on separate slot lines. */
+    const stealTicketHeadIndex = LockBound.header +
+        STEAL_TICKET_HEAD_SLOT_OFFSET_U32;
+    const stealTicketTailIndex = headersSlotStride + LockBound.header +
+        STEAL_TICKET_HEAD_SLOT_OFFSET_U32;
+    const stealTicketTailWord = stealEnabled && stealTicket
+        ? new Int32Array(headersRegion.sab, headersRegion.byteOffset + stealTicketTailIndex * Int32Array.BYTES_PER_ELEMENT, 1)
+        : undefined;
+    const stealTicketView = stealEnabled && stealTicket
+        ? new BigInt64Array(headersRegion.sab, headersRegion.byteOffset, headersRegion.byteLength >>> 3)
+        : undefined;
+    const stealTicketHead64 = stealTicketHeadIndex >>> 1;
+    const stealTicketOrderIndex = new Int32Array(LockBound.slots);
+    for (let slot = 0; slot < LockBound.slots; slot++) {
+        stealTicketOrderIndex[slot] = (slot * headersSlotStride) +
+            LockBound.header + STEAL_TICKET_ORDER_SLOT_OFFSET_U32;
+    }
+    /** A claimant drains at most one region's worth of tickets per CAS. */
+    const stealTicketBatch = stealRegionLanes;
+    const stealTicketSlots = new Int32Array(stealTicketBatch);
+    const stealTicketPublish = stealEnabled && stealIsProducer && stealTicket;
+    /** Producer-private shadow of the tail; the producer is its only writer. */
+    let stealTicketTail = 0 | 0;
+    /** At most 32 tickets can be staged, so equality is safe across uint32 wrap. */
+    let stealTicketPublishedTail = 0 | 0;
     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);
+        if (stealTicket) {
+            Atomics.store(stealTicketView, stealTicketHead64, 0n);
+            Atomics.store(stealTicketTailWord, 0, 0);
+        }
     }
     const stealIsLive = (mask, consumer) => (mask & (1 << consumer)) !== 0;
     let promiseHandler;
@@ -495,83 +587,93 @@ export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload,
     const encodeManyFrom = (list) => {
         let state = ensureSenderStateHasFree((LastLocal ^ workerShadow) | 0);
         let encoded = 0 | 0;
-        if (list === toBeSent) {
-            while (true) {
-                const task = toBeSentShift();
-                if (!task)
-                    break;
-                state = ensureSenderStateHasFree(state);
-                const bit = encodeWithState(task, state) | 0;
-                if (bit === 0) {
-                    toBeSentUnshift(task);
-                    break;
+        try {
+            if (list === toBeSent) {
+                while (true) {
+                    const task = toBeSentShift();
+                    if (!task)
+                        break;
+                    state = ensureSenderStateHasFree(state);
+                    const bit = encodeWithState(task, state) | 0;
+                    if (bit === 0) {
+                        toBeSentUnshift(task);
+                        break;
+                    }
+                    state = (state ^ bit) | 0;
+                    encoded = (encoded + 1) | 0;
                 }
-                state = (state ^ bit) | 0;
-                encoded = (encoded + 1) | 0;
             }
-        }
-        else {
-            while (true) {
-                const task = list.shiftNoClear();
-                if (!task)
-                    break;
-                state = ensureSenderStateHasFree(state);
-                const bit = encodeWithState(task, state) | 0;
-                if (bit === 0) {
-                    list.unshift(task);
-                    break;
+            else {
+                while (true) {
+                    const task = list.shiftNoClear();
+                    if (!task)
+                        break;
+                    state = ensureSenderStateHasFree(state);
+                    const bit = encodeWithState(task, state) | 0;
+                    if (bit === 0) {
+                        list.unshift(task);
+                        break;
+                    }
+                    state = (state ^ bit) | 0;
+                    encoded = (encoded + 1) | 0;
                 }
-                state = (state ^ bit) | 0;
-                encoded = (encoded + 1) | 0;
             }
+            return encoded;
+        }
+        finally {
+            flushTicketTail();
         }
-        return encoded;
     };
     const encodeManyTrackedFrom = (list) => {
         let state = ensureSenderStateHasFree((LastLocal ^ workerShadow) | 0);
         let encoded = 0 | 0;
         deferredCount = 0 | 0;
-        if (list === toBeSent) {
-            while (true) {
-                const task = toBeSentShift();
-                if (!task)
-                    break;
-                state = ensureSenderStateHasFree(state);
-                const bit = encodeWithState(task, state) | 0;
-                if (bit === 0) {
-                    if (isPromisePayloadPending(task)) {
-                        deferredCount = (deferredCount + 1) | 0;
-                        trackDeferredTask(task);
-                        continue;
+        try {
+            if (list === toBeSent) {
+                while (true) {
+                    const task = toBeSentShift();
+                    if (!task)
+                        break;
+                    state = ensureSenderStateHasFree(state);
+                    const bit = encodeWithState(task, state) | 0;
+                    if (bit === 0) {
+                        if (isPromisePayloadPending(task)) {
+                            deferredCount = (deferredCount + 1) | 0;
+                            trackDeferredTask(task);
+                            continue;
+                        }
+                        toBeSentUnshift(task);
+                        break;
                     }
-                    toBeSentUnshift(task);
-                    break;
+                    state = (state ^ bit) | 0;
+                    encoded = (encoded + 1) | 0;
                 }
-                state = (state ^ bit) | 0;
-                encoded = (encoded + 1) | 0;
             }
-        }
-        else {
-            while (true) {
-                const task = list.shiftNoClear();
-                if (!task)
-                    break;
-                state = ensureSenderStateHasFree(state);
-                const bit = encodeWithState(task, state) | 0;
-                if (bit === 0) {
-                    if (isPromisePayloadPending(task)) {
-                        deferredCount = (deferredCount + 1) | 0;
-                        trackDeferredTask(task);
-                        continue;
+            else {
+                while (true) {
+                    const task = list.shiftNoClear();
+                    if (!task)
+                        break;
+                    state = ensureSenderStateHasFree(state);
+                    const bit = encodeWithState(task, state) | 0;
+                    if (bit === 0) {
+                        if (isPromisePayloadPending(task)) {
+                            deferredCount = (deferredCount + 1) | 0;
+                            trackDeferredTask(task);
+                            continue;
+                        }
+                        list.unshift(task);
+                        break;
                     }
-                    list.unshift(task);
-                    break;
+                    state = (state ^ bit) | 0;
+                    encoded = (encoded + 1) | 0;
                 }
-                state = (state ^ bit) | 0;
-                encoded = (encoded + 1) | 0;
             }
+            return encoded;
+        }
+        finally {
+            flushTicketTail();
         }
-        return encoded;
     };
     const encodeAll = () => {
         if (toBeSent.isEmpty)
@@ -580,10 +682,8 @@ export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload,
         deferredCount = 0 | 0;
         return toBeSent.isEmpty;
     };
-    const storeHost = (bit) => {
-        a_store(hostBits, 0, LastLocal = (LastLocal ^ bit) | 0);
-        if (shouldNotifyHostPublish &&
-            a_compareExchange(doorbellArmed, 0, DOORBELL_ARMED, DOORBELL_SIGNALLED) === DOORBELL_ARMED) {
+    const notifyHostPublication = () => {
+        if (a_compareExchange(doorbellArmed, 0, DOORBELL_ARMED, DOORBELL_SIGNALLED) === DOORBELL_ARMED) {
             if (notifyHostPublish !== undefined) {
                 try {
                     notifyHostPublish();
@@ -600,6 +700,11 @@ export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload,
             }
         }
     };
+    const storeHost = (bit) => {
+        a_store(hostBits, 0, LastLocal = (LastLocal ^ bit) | 0);
+        if (shouldNotifyHostPublish)
+            notifyHostPublication();
+    };
     const storeWorker = (bit) => a_store(workerBits, 0, LastWorker = (LastWorker ^ bit) | 0);
     const encode = (task, state = (LastLocal ^ workerShadow) | 0) => {
         state = ensureSenderStateHasFree(state);
@@ -609,7 +714,12 @@ export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload,
         if (!encodeTaskValue(task, selectedSlotIndex = 31 - clz32(free))) {
             return false;
         }
-        return encodeAt(task, selectedSlotIndex, selectedSlotBit = 1 << selectedSlotIndex);
+        try {
+            return encodeAt(task, selectedSlotIndex, selectedSlotBit = 1 << selectedSlotIndex);
+        }
+        finally {
+            flushTicketTail();
+        }
     };
     const encodeTracked = (task, state = (LastLocal ^ workerShadow) | 0) => {
         deferredCount = 0 | 0;
@@ -624,7 +734,12 @@ export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload,
             }
             return false;
         }
-        return encodeAt(task, selectedSlotIndex, selectedSlotBit = 1 << selectedSlotIndex);
+        try {
+            return encodeAt(task, selectedSlotIndex, selectedSlotBit = 1 << selectedSlotIndex);
+        }
+        finally {
+            flushTicketTail();
+        }
     };
     const encodeAt = (task, at, bit) => {
         const off = (at * headersSlotStride) + slotBaseU32;
@@ -636,9 +751,39 @@ export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload,
         headersBuffer[off + 5] = task[5];
         headersBuffer[off + 6] = task[6];
         headersBuffer[off + TASK_LOCAL_FLAGS_INDEX] = 0;
+        if (stealTicketPublish) {
+            // The tail's seq-cst store publishes the header, ring cell and host bit
+            // together. Ticket consumers acquire the tail before reading a lane;
+            // unlike region consumers, they never arbitrate through hostBits.
+            stealView[stealTicketOrderIndex[stealTicketTail & STEAL_TICKET_RING_MASK]] = at;
+            stealTicketTail = (stealTicketTail + 1) | 0;
+            if (shouldNotifyHostPublish) {
+                a_store(hostBits, 0, LastLocal = (LastLocal ^ bit) | 0);
+            }
+            else {
+                hostBits[0] = LastLocal = (LastLocal ^ bit) | 0;
+            }
+            // The tail store is deferred so a burst pays one atomic, not one each.
+            // Nothing is claimable until it lands, which is what makes the batch
+            // atomic; every exit from an encode path must flush, including throws.
+            return true;
+        }
         storeHost(bit);
         return true;
     };
+    /**
+     * Publish accumulated tickets. Consumers cannot see any lane of the batch
+     * until this store lands, so skipping it strands the slots forever.
+     */
+    const flushTicketTail = () => {
+        if (stealTicketPublishedTail === stealTicketTail)
+            return;
+        stealTicketPublishedTail = stealTicketTail;
+        a_store(stealTicketTailWord, 0, stealTicketTail);
+        // A notifier must not run while its tickets are still invisible.
+        if (shouldNotifyHostPublish)
+            notifyHostPublication();
+    };
     const hasSpace = () => (hostBits[0] ^ LastWorker) !== 0;
     const decode = () => {
         let diff = (a_load(hostBits, 0) ^ LastWorker) | 0;
@@ -804,75 +949,135 @@ export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload,
                 Atomics.xor(workerBits, 0, done);
             a_store(stealView, stealWantIndex[stealId], 0);
             stealCursor = stealHome;
+            // Maybe in the future
+            // stealCursor = (region + 1) % stealRegions;
         }
         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)
+    /**
+     * Claim tickets from one monotonic counter.
+     *
+     * The ticket is the arbiter and the FIFO order at once: a winning CAS owns
+     * lanes nobody else can name, so there are no regions, no intent words, no
+     * peer survey and no liveness mask. An idle poll costs two loads and no RMW.
+     */
+    const decodeStealTicket = () => {
+        for (let attempt = 0; attempt < STEAL_TICKET_ATTEMPTS; attempt++) {
+            const head = Atomics.load(stealTicketView, stealTicketHead64);
+            if (head === STEAL_TICKET_FAILED)
+                return false;
+            const lowHead = Number(head & STEAL_TICKET_LOW_MASK);
+            const available = (a_load(stealTicketTailWord, 0) - lowHead) >>> 0;
+            if (available === 0)
+                return false;
+            // A valid head has at most 32 published tickets ahead of it. Larger
+            // distances are stale snapshots; the 64-bit head is still the arbiter.
+            if (available > LockBound.slots)
                 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;
+            const batch = Math.min(available, stealTicketBatch);
+            const next = head + BigInt(batch);
+            if (next > STEAL_TICKET_LIMIT) {
+                Atomics.store(stealTicketView, stealTicketHead64, STEAL_TICKET_FAILED);
+                throw new RangeError("ticket queue exhausted its 64-bit sequence");
             }
-        }
-        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) {
+            const ringHead = lowHead & STEAL_TICKET_RING_MASK;
+            // Read the lane ids *before* the CAS. Cell `head & 31` cannot be refilled
+            // while the head still sits at `head` (refilling it needs a free slot,
+            // which needs a retire, which needs a claim), but once the CAS moves the
+            // head past a ticket the producer may reuse that cell immediately.
+            for (let i = 0; i < batch; i++) {
+                stealTicketSlots[i] = stealView[stealTicketOrderIndex[(ringHead + i) & STEAL_TICKET_RING_MASK]] & STEAL_TICKET_RING_MASK;
+            }
+            if (Atomics.compareExchange(stealTicketView, stealTicketHead64, head, next) !== head)
+                continue;
+            let done = 0 | 0;
+            try {
+                for (let i = 0; i < batch; i++) {
+                    const at = stealTicketSlots[i];
                     decodeAt(at);
-                    lanes = (lanes ^ bit) | 0;
-                    done = (done ^ bit) | 0;
-                    if (lanes === 0)
-                        break;
+                    done = (done ^ (1 << at)) | 0;
                 }
-                at = at === regionLow ? regionHigh : at - 1;
             }
+            catch (error) {
+                // Decoding may already have consumed payload state. Replaying the
+                // unfinished batch is unsafe; report the fatal error and stop claims.
+                Atomics.store(stealTicketView, stealTicketHead64, STEAL_TICKET_FAILED);
+                throw error;
+            }
+            finally {
+                LastWorker = (LastWorker ^ done) | 0;
+                if (done !== 0)
+                    Atomics.xor(workerBits, 0, done);
+            }
+            return true;
         }
-        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;
+        return false;
+    };
+    /**
+     * Debug-only wrapper around a steal claim, for the `steal` namespace.
+     *
+     * It is selected once, when `decode` is chosen below, so an untraced lock
+     * hands out the bare claim function: no flag test, no extra load, no change
+     * to the claim path. Everything reported is read from outside the claim,
+     * before and after it, so the wrapper cannot perturb the protocol either.
+     *
+     * - `lanes`: in ticket order for `ticket`, ascending for `dekker`.
+     * - `head`: ticket head before and after. `peers` is how many tickets other
+     *   consumers took in between; 0 means `head` spans exactly this claim.
+     * - `region`/`home`: `dekker` only; `steal` marks a region off this
+     *   consumer's home.
+     * - `lost`: polls since the last claim that saw work and still came back
+     *   empty, i.e. a peer got there first.
+     */
+    const traceStealClaims = (claim, trace) => {
+        let lost = 0;
+        return () => {
+            const before = LastWorker;
+            let head = 0n;
+            let visible = 0;
+            if (stealTicket) {
+                head = Atomics.load(stealTicketView, stealTicketHead64);
+                if (head !== STEAL_TICKET_FAILED) {
+                    visible = (a_load(stealTicketTailWord, 0) -
+                        Number(head & STEAL_TICKET_LOW_MASK)) >>> 0;
+                }
+            }
+            else {
+                visible = (a_load(hostBits, 0) ^ a_load(workerBits, 0)) | 0;
+            }
+            if (!claim()) {
+                if (visible !== 0)
+                    lost++;
+                return false;
+            }
+            const taken = (LastWorker ^ before) | 0;
+            let count = 0;
+            for (let bits = taken; bits !== 0; bits &= bits - 1)
+                count++;
+            let message;
+            if (stealTicket) {
+                const after = Atomics.load(stealTicketView, stealTicketHead64);
+                const lanes = [];
+                for (let i = 0; i < count; i++)
+                    lanes.push(stealTicketSlots[i]);
+                message = `claim count=${count} lanes=${lanes.join(",")}` +
+                    ` head=${head}→${after} peers=${Number(after - head) - count}`;
+            }
+            else {
+                const lanes = [];
+                for (let lane = 0; lane < LockBound.slots; lane++) {
+                    if ((taken & (1 << lane)) !== 0)
+                        lanes.push(lane);
+                }
+                const region = (lanes[0] / stealRegionLanes) | 0;
+                message = `claim count=${count} lanes=${lanes.join(",")}` +
+                    ` region=${region} home=${stealHome}` +
+                    (region === stealHome ? "" : " steal");
+            }
+            trace(`${message} lost=${lost}`);
+            lost = 0;
+            return true;
+        };
     };
     const resolveHost = ({ queue, onResolved, shouldSettle, activeRejectPlaceholder, }) => {
         const getTask = takeTask({ queue });
@@ -1090,10 +1295,10 @@ 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);
+        if (stealTicket) {
+            // No durable ownership record exists for a dead claimant. The host must
+            // close the shared pending registry instead of reusing this queue.
+            Atomics.store(stealTicketView, stealTicketHead64, STEAL_TICKET_FAILED);
         }
         return (previous & bit) !== 0;
     };
@@ -1104,8 +1309,11 @@ export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload,
         encodeAll,
         publish,
         flushPending,
+        // Chosen once: an untraced lock gets the claim function itself.
         decode: stealEnabled
-            ? (stealClaimMask ? decodeStealCasMask : decodeSteal)
+            ? (traceClaim === undefined
+                ? (stealTicket ? decodeStealTicket : decodeSteal)
+                : traceStealClaims(stealTicket ? decodeStealTicket : decodeSteal, traceClaim))
             : decode,
         hasSpace,
         resolved,