knitting 0.1.61 → 0.1.63

package/src/api.js

@@ -1,6 +1,6 @@
 import { getCallerFilePath, getCallerHref, setModuleUrl, } from "./common/task-source.js";
 import { DEBUG_ENABLED, resolveDebugNamespaces } from "./debug/gate.js";
-import { genTaskID } from "./common/task-source.js";
+import { genTaskID, stableTaskID } from "./common/task-source.js";
 import { toModuleUrl } from "./common/module-url.js";
 import { endpointSymbol } from "./common/task-symbol.js";
 import { createStealPoolBuffers, MAX_STEAL_CONSUMERS, spawnWorkerContext, } from "./runtime/pool.js";
@@ -9,7 +9,8 @@ import { createSharedArrayBuffer, RUNTIME } from "./common/runtime.js";
 import { RUNTIME_IS_MAIN_THREAD, RUNTIME_POOL_DEPTH, RUNTIME_WORKER_DATA, } from "./common/worker-runtime.js";
 import { classifyProcessPermissionCompatibility, enforceProcessPermissionCompatibility, resolvePermissionProtocol, toRuntimePermissionFlags, } from "./permission/index.js";
 import { getNodeProcess } from "./common/node-compat.js";
-import { readProcessWorkerNodeMajor, readProcessWorkerRuntime, } from "./runtime/process-worker.js";
+import { readProcessSharedMemorySettings, readProcessWorkerNodeMajor, readProcessWorkerRuntime, } from "./runtime/process-worker.js";
+import { TRANSPORT_SIGNAL_BYTES } from "./ipc/transport/shared-memory.js";
 import { inspectCompiledWorkerArtifact } from "./runtime/compiled-artifact.js";
 import { managerMethod } from "./runtime/balancer.js";
 import { createInlineExecutor } from "./runtime/inline-executor.js";
@@ -370,17 +371,14 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
         : stealEnvRaw === "0" || stealEnvRaw === "false"
             ? false
             : undefined;
-    // Shared-submit stealing is the default for compatible multi-worker thread
-    // pools. An explicit option wins over the environment; process/compiled/
-    // inline transports retain their existing topology unless the caller
-    // explicitly requests an unsupported combination.
+    // Shared-submit stealing is the default for compatible multi-worker pools.
+    // An explicit option wins over the environment; compiled and inline
+    // transports retain their existing topology.
     const dispatcherExplicitlySelected = host?.dispatcher !== undefined ||
         dispatcherEnv === "serial-channel" || dispatcherEnv === "per-thread";
     const stealDefaultCompatible = balancer === undefined &&
         !dispatcherExplicitlySelected && (threads ?? 1) <= MAX_STEAL_CONSUMERS;
     const stealRequested = host?.steal ?? stealEnv ?? stealDefaultCompatible;
-    const stealExplicitlyEnabled = host?.steal === true ||
-        (host?.steal === undefined && stealEnv === true);
     const usingCompiledWorker = resolvedWorker?.runtime === "compiled";
     if (resolvedWorker?.compiled !== undefined && !usingCompiledWorker) {
         throw new Error("worker.compiled requires worker.runtime to be compiled");
@@ -435,9 +433,6 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
     if (usingInliner && resolvedWorker?.bootstrap !== undefined) {
         throw new Error("worker.bootstrap cannot be used with the inliner");
     }
-    if (stealExplicitlyEnabled && resolvedWorker?.runtime === "process") {
-        throw new Error("host.steal does not support process workers; use worker threads or disable stealing");
-    }
     if (resolvedWorker?.runtime === "process") {
         const processRuntime = readProcessWorkerRuntime(resolvedWorker);
         enforceProcessPermissionCompatibility(classifyProcessPermissionCompatibility({
@@ -479,12 +474,11 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
     })();
     const dispatcher = explicitDispatcher ?? autoDispatcher;
     // Work stealing: one shared submit region, private return lanes, one
-    // pool-global pending registry. It is the compatible multi-thread default;
+    // pool-global pending registry. It is the compatible multi-worker default;
     // an explicit balancer/dispatcher keeps the private-lane topology unless
     // stealing itself was explicitly requested.
     const useSteal = stealRequested &&
         !usingCompiledWorker &&
-        resolvedWorker?.runtime !== "process" &&
         (threads ?? 1) > 1 &&
         !usingInliner;
     const stealBuffers = useSteal
@@ -494,12 +488,22 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
             regionLanes: host?.stealRegionLanes,
             abortSignalCapacity,
             usesAbortSignal,
+            processWorker: resolvedWorker?.runtime === "process"
+                ? {
+                    signalBytes: TRANSPORT_SIGNAL_BYTES,
+                    sharedMemory: readProcessSharedMemorySettings(resolvedWorker),
+                }
+                : undefined,
         })
         : undefined;
     const serialChannel = !usingCompiledWorker && !useSteal &&
         dispatcher === "serial-channel";
+    // One serial-channel hop drives every lane check in turn, and it depends on
+    // the channel's delivery to do that: swapping in the cheaper `setImmediate`
+    // pump cost 25% throughput and tripled p99 here, where every other topology
+    // gained. See ChannelHandler's note.
     const serialDispatcherChannel = serialChannel
-        ? new ChannelHandler()
+        ? new ChannelHandler("channel")
         : undefined;
     let workers = Array.from({
         length: threads ?? 1,
@@ -512,6 +516,9 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
         debug,
         hostDebug: hostDebug?.log,
         totalNumberOfThread,
+        // Worker count without the inline lane. The inliner runs on the host
+        // thread and never spins, so it must not count towards the spin policy.
+        workerCount: threads ?? 1,
         source,
         workerOptions: resolvedWorker,
         workerExecArgv: execArgv,
@@ -533,6 +540,7 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
             regionLanes: stealBuffers.regionLanes,
             abortSignalSAB: stealBuffers.abortSignalSAB,
             abortSignalMax: stealBuffers.abortSignalMax,
+            processMemory: stealBuffers.processMemory,
         },
     }));
     const stealChannel = useSteal ? new ChannelHandler() : undefined;
@@ -565,6 +573,7 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
             channelHandler: channel,
             dispatcherOptions: host,
             notifySignal: wakeOne,
+            crossProcess: resolvedWorker?.runtime === "process",
         });
         channel.open(check);
         workers.forEach((context) => {
@@ -681,7 +690,8 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
         if (closePromise)
             return closePromise;
         closing = true;
-        closePromise = Promise.allSettled(workers.map((context) => context.kills()))
+        closePromise = Promise.allSettled(workers.map((context) => context.requestStop?.()))
+            .then(() => Promise.allSettled(workers.map((context) => context.kills())))
             .then(() => {
             sharedDispatcherChannel?.close();
             stealChannel?.close();
@@ -843,7 +853,7 @@ const buildTaskDefinitionFromCaller = (input, callerHref, at, imported = false)
     const importedFrom = new URL(callerHref).href;
     const out = ({
         ...input,
-        id: genTaskID(),
+        id: stableTaskID(importedFrom, at),
         importedFrom,
         at,
         imported,

package/src/common/task-source.d.ts

@@ -1,4 +1,13 @@
 export declare const genTaskID: () => number;
+/**
+ * Identity of a task, stable across processes.
+ *
+ * `genTaskID` numbers tasks by the order their module happened to be evaluated,
+ * which host and worker do not share: the host imports in its own source order
+ * and the worker imports in task-name order. `(href, at)` is the same pair in
+ * both, because `at` counts `task()` calls within one module.
+ */
+export declare const stableTaskID: (href: string, at: number) => number;
 export declare const setModuleUrl: (url: string | undefined) => void;
 export declare const getModuleUrlOverride: () => string | undefined;
 export declare const getCallerHref: (offset?: number) => string;

package/src/common/task-source.js

@@ -1,5 +1,20 @@
 import { toModuleUrl } from "./module-url.js";
 export const genTaskID = ((counter) => () => counter++)(0);
+/**
+ * Identity of a task, stable across processes.
+ *
+ * `genTaskID` numbers tasks by the order their module happened to be evaluated,
+ * which host and worker do not share: the host imports in its own source order
+ * and the worker imports in task-name order. `(href, at)` is the same pair in
+ * both, because `at` counts `task()` calls within one module.
+ */
+export const stableTaskID = (href, at) => {
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < href.length; index++) {
+        hash = Math.imul(hash ^ href.charCodeAt(index), 0x01000193);
+    }
+    return (Math.imul(hash ^ at, 0x01000193) >>> 0);
+};
 const INTERNAL_CALLER_HINTS = [
     "/src/common/task-source.ts",
     "/src/common/task-source.js",

package/src/ipc/transport/shared-memory.d.ts

@@ -1,6 +1,13 @@
 export type SignalArguments = ReturnType<typeof createSharedMemoryTransport>;
 import { type SharedBufferSource } from "../../common/shared-buffer-region.js";
 export declare const TRANSPORT_SIGNAL_BYTES: number;
+/** States of the worker-stop word. */
+export declare const WORKER_STOP: {
+    readonly running: 0;
+    readonly requested: 1;
+    /** The worker has left its dispatch loop. */
+    readonly acknowledged: 2;
+};
 export type Sab = {
     size?: number;
     sharedSab?: SharedBufferSource;
@@ -18,6 +25,7 @@ export declare const createSharedMemoryTransport: ({ sabObject, isMain, startTim
     opView: Int32Array<import("../../common/shared-buffer-region.js").SharedBuffer>;
     rxStatus: Int32Array<import("../../common/shared-buffer-region.js").SharedBuffer>;
     txStatus: Int32Array<import("../../common/shared-buffer-region.js").SharedBuffer>;
+    stopView: Int32Array<import("../../common/shared-buffer-region.js").SharedBuffer>;
 };
-export type MainSignal = Pick<SignalArguments, "opView" | "startAt" | "rxStatus" | "txStatus">;
+export type MainSignal = Pick<SignalArguments, "opView" | "startAt" | "rxStatus" | "txStatus" | "stopView">;
 export {};

package/src/ipc/transport/shared-memory.js

@@ -7,8 +7,16 @@ const SIGNAL_OFFSETS = {
     op: 0,
     rxStatus: CACHE_LINE_BYTES,
     txStatus: CACHE_LINE_BYTES * 2,
+    stop: CACHE_LINE_BYTES * 3,
+};
+export const TRANSPORT_SIGNAL_BYTES = CACHE_LINE_BYTES * 4;
+/** States of the worker-stop word. */
+export const WORKER_STOP = {
+    running: 0,
+    requested: 1,
+    /** The worker has left its dispatch loop. */
+    acknowledged: 2,
 };
-export const TRANSPORT_SIGNAL_BYTES = CACHE_LINE_BYTES * 3;
 const a_store = Atomics.store;
 export const createSharedMemoryTransport = ({ sabObject, isMain, startTime }) => {
     const toGrow = sabObject?.size ?? page;
@@ -24,6 +32,9 @@ export const createSharedMemoryTransport = ({ sabObject, isMain, startTime }) =>
         a_store(opView, 0, 0);
     const rxStatus = new Int32Array(sab, baseByteOffset + SIGNAL_OFFSETS.rxStatus, 1);
     a_store(rxStatus, 0, 1);
+    const stopView = new Int32Array(sab, baseByteOffset + SIGNAL_OFFSETS.stop, 1);
+    if (isMain)
+        a_store(stopView, 0, WORKER_STOP.running);
     return {
         sab: signalRegion,
         op: opView,
@@ -31,5 +42,6 @@ export const createSharedMemoryTransport = ({ sabObject, isMain, startTime }) =>
         opView,
         rxStatus,
         txStatus: new Int32Array(sab, baseByteOffset + SIGNAL_OFFSETS.txStatus, 1),
+        stopView,
     };
 };

package/src/memory/lock.d.ts

@@ -173,6 +173,8 @@ export declare const STEAL_PAYLOAD_ACK_SLOT_OFFSET_U32: number;
  * clear here. This preserves single-writer ownership of every WANT word.
  */
 export declare const STEAL_LIVE_SLOT_OFFSET_U32: number;
+/** Host-owned arm word for the return-lock completion doorbell. */
+export declare const DOORBELL_ARMED_SLOT_OFFSET_U32: number;
 export declare const HEADER_U32_LENGTH: number;
 export declare const HEADER_BYTE_LENGTH: number;
 export declare const makeTask: () => Task;
@@ -191,7 +193,12 @@ type ResolveHostOptions = {
  *  - encode/decode are not re-entrant; payload codec uses a shared scratch buffer.
  */
 export type Lock2 = ReturnType<typeof lock2>;
-export declare const lock2: ({ headers, headerSlotStrideU32, LockBoundSector, payload, payloadConfig, payloadSector, textCompat, resultList, toSentList, recycleList, processBoundary, consumers, consumerId, regionLanes, }: {
+export type WaitAsyncState = "not-equal" | "ok" | "timed-out";
+export type WaitAsyncResult = {
+    async: boolean;
+    value: WaitAsyncState | PromiseLike<WaitAsyncState>;
+};
+export declare const lock2: ({ headers, headerSlotStrideU32, LockBoundSector, payload, payloadConfig, payloadSector, textCompat, resultList, toSentList, recycleList, processBoundary, consumers, consumerId, regionLanes, notifyOnHostPublish, }: {
     headers?: SharedBufferSource;
     headerSlotStrideU32?: number;
     LockBoundSector?: SharedBufferSource;
@@ -213,6 +220,8 @@ export declare const lock2: ({ headers, headerSlotStrideU32, LockBoundSector, pa
     consumerId?: number;
     /** Lanes claimed per Dekker handshake. Paper rule: `slots / regionLanes >= consumers + 1`. */
     regionLanes?: number;
+    /** Notify a host-side wait after this endpoint publishes a frame. */
+    notifyOnHostPublish?: boolean;
 }) => {
     enlist: (task: Task) => true;
     encode: (task: Task, state?: number) => boolean;
@@ -227,6 +236,8 @@ export declare const lock2: ({ headers, headerSlotStrideU32, LockBoundSector, pa
     workerBits: Int32Array<import("../common/shared-buffer-region.js").SharedBuffer>;
     recyclecList: RingQueue<Task>;
     resolveHost: ({ queue, onResolved, shouldSettle, activeRejectPlaceholder, }: ResolveHostOptions) => () => number;
+    waitForHostChange: (timeoutMs?: number) => WaitAsyncResult | undefined;
+    setHostWaiterArmed: (armed: boolean) => void;
     hasPendingFrames: () => boolean;
     getPendingFrameCount: () => number;
     getPendingPromiseCount: () => number;

package/src/memory/lock.js

@@ -228,10 +228,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;
@@ -247,6 +246,8 @@ export const STEAL_PAYLOAD_ACK_SLOT_OFFSET_U32 = STEAL_ACK_SLOT_OFFSET_U32 + 2;
  * clear here. This preserves single-writer ownership of every WANT word.
  */
 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;
 export const HEADER_U32_LENGTH = LockBound.header +
     (HEADER_SLOT_STRIDE_U32 * LockBound.slots);
 export const HEADER_BYTE_LENGTH = HEADER_U32_LENGTH *
@@ -297,7 +298,7 @@ const settleTask = (task) => {
         task[TaskIndex["FlagsToHost"]] = 0;
     }
 };
-export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload, payloadConfig, payloadSector, textCompat, resultList, toSentList, recycleList, processBoundary, consumers, consumerId, regionLanes, }) => {
+export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload, payloadConfig, payloadSector, textCompat, resultList, toSentList, recycleList, processBoundary, consumers, consumerId, regionLanes, notifyOnHostPublish, }) => {
     // Layout within `lockSectorRegion`:
     // - hostBits starts at byte 0
     // - workerBits starts at byte 64
@@ -316,6 +317,11 @@ export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload,
     const headersRegion = toSharedBufferRegion(headers ?? createWasmSharedArrayBuffer(HEADER_BYTE_LENGTH));
     const headersBuffer = new Uint32Array(headersRegion.sab, headersRegion.byteOffset, headersRegion.byteLength >>> 2);
     const headersSlotStride = headerSlotStrideU32 ?? HEADER_SLOT_STRIDE_U32;
+    // The first task cache line has four unused control words after the task
+    // header. Keep the doorbell arm bit in one of those words so the host and
+    // worker lock instances can share it without allocating another SAB.
+    const doorbellArmed = new Int32Array(headersRegion.sab, headersRegion.byteOffset +
+        (DOORBELL_ARMED_SLOT_OFFSET_U32 * Uint32Array.BYTES_PER_ELEMENT), 1);
     const resolvedPayloadConfig = resolvePayloadBufferOptions({
         sab: payload,
         options: payloadConfig,
@@ -356,12 +362,10 @@ 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;
     const stealAllLiveMask = stealConsumers === 32
@@ -371,13 +375,6 @@ export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload,
         Atomics.store(stealView, stealLiveIndex, stealAllLiveMask);
     }
     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) {
@@ -428,14 +425,18 @@ export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload,
     // Atomics aliases (hot path)
     const a_load = Atomics.load;
     const a_store = Atomics.store;
+    const a_notify = Atomics.notify;
+    const shouldNotifyHostPublish = notifyOnHostPublish === true;
+    const a_waitAsync = typeof Atomics.waitAsync === "function"
+        ? Atomics.waitAsync.bind(Atomics)
+        : 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
     // 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)
@@ -560,7 +561,12 @@ export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload,
         deferredCount = 0 | 0;
         return toBeSent.isEmpty;
     };
-    const storeHost = (bit) => a_store(hostBits, 0, LastLocal = (LastLocal ^ bit) | 0);
+    const storeHost = (bit) => {
+        a_store(hostBits, 0, LastLocal = (LastLocal ^ bit) | 0);
+        if (shouldNotifyHostPublish && a_load(doorbellArmed, 0) !== 0) {
+            a_notify(hostBits, 0, 1);
+        }
+    };
     const storeWorker = (bit) => a_store(workerBits, 0, LastWorker = (LastWorker ^ bit) | 0);
     const encode = (task, state = (LastLocal ^ workerShadow) | 0) => {
         state = ensureSenderStateHasFree(state);
@@ -649,14 +655,6 @@ export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload,
     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 stealJuniorWants = (intent) => {
         const live = a_load(stealView, stealLiveIndex) | 0;
         for (let c = stealId + 1; c < stealConsumers; c++) {
@@ -667,9 +665,11 @@ export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload,
         }
         return false;
     };
-    let stealCursor = ((stealRegions * stealId) / stealConsumers) | 0;
+    const stealHome = ((stealRegions * stealId) / stealConsumers) | 0;
+    let stealCursor = stealHome;
     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;
@@ -731,23 +731,32 @@ export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload,
         }
         // 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()) &
+        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 decoded lanes and release the region 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;
+        try {
+            while (lanes !== 0) {
+                const bit = (lanes & -lanes) | 0;
+                decodeAt(31 - clz32(bit >>> 0));
+                lanes = (lanes & (lanes - 1)) | 0;
+                done = (done ^ bit) | 0;
+            }
+        }
+        finally {
+            // ACK before clearing intent.
+            LastWorker = (LastWorker ^ done) | 0;
+            if (done !== 0)
+                Atomics.xor(workerBits, 0, done);
+            a_store(stealView, stealWantIndex[stealId], 0);
+            // Restart from this consumer's home region.
+            stealCursor = stealHome;
+        }
         return true;
     };
     /**
@@ -878,6 +887,34 @@ 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.
+    */
+    const waitForHostChange = (timeoutMs) => {
+        if (a_waitAsync === undefined) {
+            a_store(doorbellArmed, 0, 0);
+            return undefined;
+        }
+        a_store(doorbellArmed, 0, 1);
+        try {
+            const wait = a_waitAsync(hostBits, 0, LastWorker | 0, timeoutMs);
+            if (!wait.async)
+                a_store(doorbellArmed, 0, 0);
+            return wait;
+        }
+        catch {
+            a_store(doorbellArmed, 0, 0);
+            // 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
+            // hung pool.
+            return undefined;
+        }
+    };
     const decodeAt = (at) => {
         const off = (at * headersSlotStride) + slotBaseU32;
         const recycled = recycleShift();
@@ -951,6 +988,10 @@ export const lock2 = ({ headers, headerSlotStrideU32, LockBoundSector, payload,
         workerBits,
         recyclecList,
         resolveHost,
+        waitForHostChange,
+        setHostWaiterArmed: (armed) => {
+            a_store(doorbellArmed, 0, armed ? 1 : 0);
+        },
         hasPendingFrames: () => toBeSent.size !== 0,
         getPendingFrameCount: () => toBeSent.size | 0,
         getPendingPromiseCount: () => pendingPromiseCount | 0,

package/src/runtime/dispatcher.d.ts

@@ -2,12 +2,14 @@ import { type MultiQueue } from "./tx-queue.js";
 import { type MainSignal } from "../ipc/transport/shared-memory.js";
 import { type RuntimeMessageChannelLike, type RuntimeMessagePortLike } from "../common/worker-runtime.js";
 import type { DispatcherSettings } from "../types.js";
-export declare const hostDispatcherLoop: ({ signalBox: { opView, txStatus, rxStatus, }, queue: { completeFrame, hasPendingFrames, flushToWorker, txIdle, }, channelHandler, dispatcherOptions, notifySignal, }: {
+export declare const hostDispatcherLoop: ({ signalBox: { opView, txStatus, rxStatus, }, queue: { completeFrame, hasPendingFrames, flushToWorker, txIdle, waitForCompletion, setCompletionWaiterArmed, }, channelHandler, dispatcherOptions, notifySignal, crossProcess, }: {
     queue: MultiQueue;
     signalBox: MainSignal;
     channelHandler: ChannelHandler;
     dispatcherOptions?: DispatcherSettings;
     notifySignal?: () => void;
+    /** Workers live in other processes; disables the doorbell. */
+    crossProcess?: boolean;
 }) => {
     check: {
         (): void;
@@ -20,20 +22,21 @@ type CheckWithState = (() => void) & {
     rerun: boolean;
 };
 export type DispatcherCheck = CheckWithState;
+export type ChannelHandlerPump = "auto" | "channel";
 export declare class ChannelHandler {
     #private;
-    channel: RuntimeMessageChannelLike;
-    port1: RuntimeMessagePortLike;
-    port2: RuntimeMessagePortLike;
-    constructor();
+    channel: RuntimeMessageChannelLike | undefined;
+    port1: RuntimeMessagePortLike | undefined;
+    port2: RuntimeMessagePortLike | undefined;
+    constructor(pump?: ChannelHandlerPump);
     notify(): void;
     /**
-     * Opens the channel (if not already open) and sets the onmessage handler.
-     * This is the setup so `notify` can send a message to the port 1.
+     * Registers the handler the pump calls back into. On the channel pump this is
+     * also where the ports are opened, so `notify` can reach port 1.
      */
     open(f: () => void): void;
     /**
-     * Closes the channel if it is open.
+     * Detaches the handler, and closes the channel if this pump has one.
      */
     close(): void;
 }