knitting 0.1.61 → 0.1.62

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,
@@ -533,6 +537,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 +570,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) => {
@@ -843,7 +849,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/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

@@ -247,6 +247,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 +299,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 +318,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,
@@ -428,6 +435,11 @@ 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
@@ -560,7 +572,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);
@@ -878,6 +895,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 +996,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;
 }

package/src/runtime/dispatcher.js

@@ -1,5 +1,34 @@
 import { createRuntimeMessageChannel, } from "../common/worker-runtime.js";
-export const hostDispatcherLoop = ({ signalBox: { opView, txStatus, rxStatus, }, queue: { completeFrame, hasPendingFrames, flushToWorker, txIdle, }, channelHandler, dispatcherOptions, notifySignal, }) => {
+import { RUNTIME, SET_IMMEDIATE } from "../common/runtime.js";
+/**
+ * Macrotask primitive for the host pump, picked per runtime: a round trip costs
+ * 757ns on Bun via MessageChannel but 4662ns on Deno, where `setImmediate` is
+ * 1110ns. Bun keeps the channel; browser and Andromeda have no choice.
+ *
+ * `serial-channel` opts back into the channel explicitly (see `src/api.ts`): one
+ * hop drives every lane's check in turn and relies on the channel's delivery to
+ * do it, so a merely cheaper pump starves it -- it cost 25% throughput there.
+ */
+const IMMEDIATE_PUMP = RUNTIME === "deno" || RUNTIME === "node"
+    ? SET_IMMEDIATE
+    : undefined;
+/**
+ * Free drain hops before `scheduleNotify` stops re-arming the pump for free.
+ *
+ * The window has to match what the dispatcher escalates *to*, so these are
+ * chosen together and `canUseDoorbell` picks between them. Polling escalates to
+ * the `setTimeout` ladder, whose finest rung is ~1.1ms on every runtime, so it
+ * wants a wide window; that sleep is also load-bearing, since it batches
+ * completions. A doorbell escalates to `Atomics.waitAsync` at about the price of
+ * one hop, so it wants a narrow one.
+ *
+ * Mixing them is the trap: a doorbell behind the wide window keeps every poll
+ * hop *and* adds the arm, and loses to plain polling at every thread count.
+ * Measurements behind both values: `docs/host-doorbell-proposal.md`.
+ */
+const POLL_STALL_FREE_LOOPS = 128;
+const DOORBELL_STALL_FREE_LOOPS = 1;
+export const hostDispatcherLoop = ({ signalBox: { opView, txStatus, rxStatus, }, queue: { completeFrame, hasPendingFrames, flushToWorker, txIdle, waitForCompletion, setCompletionWaiterArmed, }, channelHandler, dispatcherOptions, notifySignal, crossProcess, }) => {
     const a_load = Atomics.load;
     const a_store = Atomics.store;
     const a_notify = Atomics.notify;
@@ -10,13 +39,81 @@ export const hostDispatcherLoop = ({ signalBox: { opView, txStatus, rxStatus, },
                 a_notify(opView, 0, 1);
         });
     const notify = () => channelHandler.notify();
+    // `crossProcess` is a capability, not a preference, so it overrides an
+    // explicit `doorbell: true`: V8's Atomics waiter list is per isolate, so a
+    // worker in another process can never ring the host's waiter, and an armed
+    // doorbell would just sleep to the watchdog.
+    const canUseDoorbell = crossProcess !== true &&
+        (dispatcherOptions?.doorbell ?? true) &&
+        (RUNTIME === "bun" || RUNTIME === "node") &&
+        typeof Atomics.waitAsync === "function";
+    let doorbellEnabled = canUseDoorbell;
+    let doorbellArmed = false;
+    let doorbellEpoch = 0 | 0;
+    const DOORBELL_WATCHDOG_MS = 1000;
     let stallCount = 0 | 0;
-    const STALL_FREE_LOOPS = Math.max(0, (dispatcherOptions?.stallFreeLoops ?? 128) | 0);
+    const requestedStallFreeLoops = dispatcherOptions?.stallFreeLoops;
+    let stallFreeLoops = requestedStallFreeLoops !== undefined
+        ? Math.max(0, requestedStallFreeLoops | 0)
+        : canUseDoorbell
+            ? DOORBELL_STALL_FREE_LOOPS
+            : POLL_STALL_FREE_LOOPS;
     const MAX_BACKOFF_MS = Math.max(0, (dispatcherOptions?.maxBackoffMs ?? 10) | 0);
     let backoffTimer;
     // inFlight prevents re-entrancy when pool.ts fires check() concurrently
     // from both send() and the channel callback. Cheaper than try/finally.
     let inFlight = false;
+    const cancelDoorbell = () => {
+        if (!doorbellArmed)
+            return;
+        doorbellEpoch = (doorbellEpoch + 1) | 0;
+        doorbellArmed = false;
+        setCompletionWaiterArmed(false);
+    };
+    const armDoorbell = () => {
+        if (!doorbellEnabled || doorbellArmed === true) {
+            if (!doorbellEnabled)
+                notify();
+            return;
+        }
+        const token = (doorbellEpoch + 1) | 0;
+        doorbellEpoch = token;
+        doorbellArmed = true;
+        let woke = false;
+        const wake = () => {
+            if (!doorbellArmed || doorbellEpoch !== token || woke)
+                return;
+            woke = true;
+            doorbellArmed = false;
+            doorbellEpoch = (doorbellEpoch + 1) | 0;
+            setCompletionWaiterArmed(false);
+            // Keep the existing macrotask boundary. Calling check directly from a
+            // resolved waitAsync promise can chain microtasks under a hot workload
+            // and starve host I/O.
+            notify();
+        };
+        let supported = false;
+        try {
+            supported = waitForCompletion(wake, DOORBELL_WATCHDOG_MS);
+        }
+        catch {
+            supported = false;
+        }
+        // Some runtimes reject waitAsync on their SharedArrayBuffer variants; fall
+        // back to polling rather than hanging the pool.
+        if (!supported) {
+            doorbellEnabled = false;
+            // The window was narrowed for a doorbell that no longer exists; widen it
+            // back or the ladder fires after a single fruitless drain.
+            if (requestedStallFreeLoops === undefined) {
+                stallFreeLoops = POLL_STALL_FREE_LOOPS;
+            }
+            doorbellArmed = false;
+            doorbellEpoch = (doorbellEpoch + 1) | 0;
+            setCompletionWaiterArmed(false);
+            notify();
+        }
+    };
     const check = () => {
         if (inFlight) {
             // Another check() is already mid-drain; mark that a re-run is needed
@@ -24,11 +121,12 @@ export const hostDispatcherLoop = ({ signalBox: { opView, txStatus, rxStatus, },
             check.rerun = true;
             return;
         }
-        // Nothing enqueued and nothing outstanding at the worker: skip the drain.
-        // Without this an idle lane still pays a txStatus write, an rxStatus load
-        // and — worst of all — an Atomics.notify that wakes a parked worker for no
-        // reason. Under the serial-channel dispatcher every lane is checked on
-        // every tick, so that waste is what makes latency grow with thread count.
+        // A waitAsync cannot be cancelled, so bumping its epoch makes the eventual
+        // callback inert instead.
+        cancelDoorbell();
+        // Idle lane: skip the drain. Otherwise it pays a txStatus write, an rxStatus
+        // load, and an Atomics.notify that wakes a parked worker for nothing — the
+        // waste that makes serial-channel latency grow with thread count.
         if (txIdle()) {
             check.isRunning = false;
             return;
@@ -46,25 +144,27 @@ export const hostDispatcherLoop = ({ signalBox: { opView, txStatus, rxStatus, },
                 a_store(opView, 0, 1);
                 wakeSignal();
             }
-            // Drain loop: local vars so V8 keeps them as unboxed int32.
-            let anyProgressed = false;
+            // Local vars so V8 keeps them as unboxed int32. Only a reaped completion
+            // counts as progress for `stallCount`: the pump exists to notice work a
+            // worker cannot announce, and letting a flush reset the counter would
+            // leave the escalation unreachable for a pool that never runs dry.
+            let completed = false;
             let progressed = true;
             while (progressed) {
                 progressed = false;
                 if (completeFrame() > 0) {
                     progressed = true;
-                    anyProgressed = true;
+                    completed = true;
                 }
                 while (hasPendingFrames()) {
                     if (!flushToWorker())
                         break;
                     progressed = true;
-                    anyProgressed = true;
                 }
             }
             txStatus[0] = 0;
             if (!txIdle()) {
-                if (anyProgressed || hasPendingFrames()) {
+                if (completed || hasPendingFrames()) {
                     stallCount = 0 | 0;
                 }
                 else {
@@ -83,14 +183,22 @@ export const hostDispatcherLoop = ({ signalBox: { opView, txStatus, rxStatus, },
     check.isRunning = false;
     check.rerun = false;
     const scheduleNotify = () => {
-        if (stallCount <= STALL_FREE_LOOPS) {
+        if (stallCount <= stallFreeLoops) {
             notify();
             return;
         }
+        if (doorbellEnabled) {
+            // Release isRunning during the wait so a fresh send() can restart the
+            // dispatcher immediately. The epoch in cancelDoorbell() invalidates the
+            // old waiter in that case.
+            check.isRunning = false;
+            armDoorbell();
+            return;
+        }
         // One delayed wakeup at a time; fresh send() calls preempt via check directly.
         if (backoffTimer !== undefined)
             return;
-        let delay = (stallCount - STALL_FREE_LOOPS - 1) | 0;
+        let delay = (stallCount - stallFreeLoops - 1) | 0;
         if (delay < 0)
             delay = 0;
         else if (delay > MAX_BACKOFF_MS)
@@ -108,25 +216,47 @@ export const hostDispatcherLoop = ({ signalBox: { opView, txStatus, rxStatus, },
     return { check };
 };
 export class ChannelHandler {
+    // Set only when the pump is a MessageChannel. The `setImmediate` pump has no
+    // ports, and nothing outside this class reads them.
     channel;
     port1;
     port2;
-    #post2;
-    constructor() {
-        this.channel = createRuntimeMessageChannel();
-        this.port1 = this.channel.port1;
-        this.port2 = this.channel.port2;
-        this.#post2 = (message) => this.port2.postMessage(message);
+    #handler;
+    #notify;
+    constructor(pump = "auto") {
+        if (pump === "auto" && IMMEDIATE_PUMP !== undefined) {
+            const immediate = IMMEDIATE_PUMP;
+            // Allocated once; the pump fires hundreds of thousands of times a second.
+            // Routing via `#handler` also makes a callback outliving `close()` inert.
+            const run = () => {
+                this.#handler?.();
+            };
+            this.#notify = () => {
+                immediate(run);
+            };
+            return;
+        }
+        const channel = createRuntimeMessageChannel();
+        const port2 = channel.port2;
+        this.channel = channel;
+        this.port1 = channel.port1;
+        this.port2 = port2;
+        this.#notify = () => {
+            port2.postMessage(null);
+        };
     }
     notify() {
-        this.#post2(null);
+        this.#notify();
     }
     /**
-     * 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) {
+        this.#handler = f;
         const port1 = this.port1;
+        if (port1 === undefined)
+            return;
         if (typeof port1.on === "function") {
             port1.on("message", f);
         }
@@ -134,13 +264,16 @@ export class ChannelHandler {
             // @ts-ignore
             port1.onmessage = f;
         }
-        this.port1.start?.();
-        this.port2.start?.();
+        this.port1?.start?.();
+        this.port2?.start?.();
     }
     /**
-     * Closes the channel if it is open.
+     * Detaches the handler, and closes the channel if this pump has one.
      */
     close() {
+        this.#handler = undefined;
+        if (this.port1 === undefined || this.port2 === undefined)
+            return;
         //@ts-ignore
         this.port1.onmessage = null;
         //@ts-ignore

package/src/runtime/inline-executor.js

@@ -81,9 +81,14 @@ const composeInlineCallable = (fn, timeout, useAbortToolkit = false) => {
     };
 };
 export const createInlineExecutor = ({ tasks, genTaskID, batchSize, }) => {
+    // `createPool` passes an already name-sorted array, which is the order
+    // `fnNumber` indexes into. The object form has to reach the same order on its
+    // own: task ids identify a task, they do not rank it, so sorting by id would
+    // hand callers a different lane than the one they addressed.
     const entries = Array.isArray(tasks)
         ? tasks
-        : Object.values(tasks).sort((a, b) => a.id - b.id);
+        : Object.values(tasks)
+            .sort((a, b) => a.name.localeCompare(b.name));
     const runners = entries.map((entry) => {
         // Imported tasks must never execute on the host inline lane: their module
         // import is meant to stay inside the worker so worker permission policies