knitting 0.1.62 → 0.1.70

package/src/runtime/tx-queue.js

@@ -4,7 +4,6 @@ import "../memory/payloadCodec.js";
 import { makeTask, resetTaskLocalFlags, runTaskFinalizers, TaskIndex, } from "../memory/lock.js";
 import { withResolvers } from "../common/with-resolvers.js";
 import { AbortSignalPoolExhausted, OneShotDeferred, } from "../shared/abortSignal.js";
-import { withBufferReferenceReturnReleaser, } from "../connections/buffer-reference.js";
 const SLOT_INDEX_MASK = 31;
 const SLOT_META_MASK = 0x07ffffff;
 const SLOT_META_SHIFT = 5;
@@ -14,7 +13,7 @@ const FUNCTION_META_SHIFT = 16;
 const ABORT_SIGNAL_META_OFFSET = 1;
 const NO_ABORT_SIGNAL = -1;
 const p_now = performance.now.bind(performance);
-export function createHostTxQueue({ max, lock, returnLock, extraReturnLocks, releaseBufferReferenceReturn, abortSignals, now, }) {
+export function createHostTxQueue({ max, lock, returnLock, extraReturnLocks, abortSignals, now, }) {
     const PLACE_HOLDER = (_) => {
         throw ("UNREACHABLE FROM PLACE HOLDER (main)");
     };
@@ -66,33 +65,18 @@ export function createHostTxQueue({ max, lock, returnLock, extraReturnLocks, rel
     ].map((each) => typeof each.setHostWaiterArmed === "function"
         ? each.setHostWaiterArmed
         : (_armed) => { });
-    // A stealing queue drains one private return lock per worker. Borrowed
-    // BufferReferences must therefore be claimed with the hooks belonging to the
-    // worker that produced that particular return. The hooks are bound after the
-    // worker context exists, while the pool-global queue is built before workers
-    // spawn, so keep one mutable hook slot per return lane.
-    const returnHooks = new Array(returnResolvers.length);
-    if (releaseBufferReferenceReturn !== undefined) {
-        returnHooks[0] = releaseBufferReferenceReturn;
-    }
-    const resolveReturnAt = (index) => {
-        const resolve = returnResolvers[index];
-        const hooks = returnHooks[index];
-        return hooks === undefined
-            ? resolve()
-            : withBufferReferenceReturnReleaser(hooks, resolve);
-    };
-    // Preserve the original one-lane fast path exactly: no wrapper, array lookup,
-    // or hook branch is paid by the default one-worker transport. Mutable
-    // per-return-lane hooks are needed only by a multi-worker stealing queue.
+    const returnNativeArmers = [
+        returnLock,
+        ...(extraReturnLocks ?? []),
+    ].map((each) => typeof each.armHostNotifier === "function"
+        ? each.armHostNotifier
+        : () => false);
     const completeFrame = returnResolvers.length === 1
-        ? releaseBufferReferenceReturn === undefined
-            ? returnResolvers[0]
-            : () => withBufferReferenceReturnReleaser(releaseBufferReferenceReturn, returnResolvers[0])
+        ? returnResolvers[0]
         : () => {
             let resolved = 0 | 0;
             for (let i = 0; i < returnResolvers.length; i++) {
-                resolved = (resolved + resolveReturnAt(i)) | 0;
+                resolved = (resolved + returnResolvers[i]()) | 0;
             }
             return resolved;
         };
@@ -103,19 +87,35 @@ export function createHostTxQueue({ max, lock, returnLock, extraReturnLocks, rel
     const completionArmed = new Uint8Array(returnWaiters.length);
     let completionWake;
     let completionGeneration = 0 | 0;
+    const completionGenerations = new Int32Array(returnWaiters.length);
+    // Reuse one callback per lane and capture the generation before re-arming.
+    const completionCallbacks = returnWaiters.map((_, index) => () => {
+        if (completionArmed[index] === 0)
+            return;
+        const generation = completionGenerations[index];
+        completionArmed[index] = 0;
+        returnArmers[index](false);
+        if (generation !== completionGeneration)
+            return;
+        completionWake?.();
+    });
     const setCompletionWaiterArmed = (armed) => {
         for (const setArmed of returnArmers)
             setArmed(armed);
     };
     const waitForCompletion = (onWake, timeoutMs) => {
         completionWake = onWake;
-        // A persistent waiter may still be pending after a send preempted the
-        // dispatcher. Re-arm its shared gate before relying on that waiter again.
-        setCompletionWaiterArmed(true);
         let supported = true;
         for (let index = 0; index < returnWaiters.length; index++) {
-            if (completionArmed[index] !== 0)
+            if (completionArmed[index] !== 0) {
+                // Re-arm persistent waiters with an atomic check; a result may have
+                // arrived while the gate was off, and setting ARMED alone can strand it.
+                if (!returnNativeArmers[index]()) {
+                    onWake();
+                    return true;
+                }
                 continue;
+            }
             let wait;
             try {
                 wait = returnWaiters[index](timeoutMs);
@@ -128,20 +128,14 @@ export function createHostTxQueue({ max, lock, returnLock, extraReturnLocks, rel
                 break;
             }
             completionArmed[index] = 1;
-            const generation = completionGeneration;
-            const wakeLane = () => {
-                if (completionArmed[index] === 0)
-                    return;
-                completionArmed[index] = 0;
-                returnArmers[index](false);
-                if (generation !== completionGeneration)
-                    return;
-                completionWake?.();
-            };
-            if (!wait.async)
+            completionGenerations[index] = completionGeneration;
+            const wakeLane = completionCallbacks[index];
+            if (!wait.async) {
                 wakeLane();
-            else
-                Promise.resolve(wait.value).then(wakeLane, wakeLane);
+                // A synchronous wake may disarm the whole queue, so stop here.
+                return true;
+            }
+            Promise.resolve(wait.value).then(wakeLane, wakeLane);
         }
         if (!supported) {
             completionWake = undefined;
@@ -150,6 +144,21 @@ export function createHostTxQueue({ max, lock, returnLock, extraReturnLocks, rel
         }
         return supported;
     };
+    /**
+     * Native callbacks (Deno's threadSafe UnsafeCallback) cannot use waitAsync,
+     * but they use the same shared arm word. Each lane is armed and checked for
+     * a publication in one operation; a false return means the dispatcher must
+     * drain again rather than sleep waiting for a ring that already happened.
+     */
+    const armCompletionNotifier = () => {
+        for (const arm of returnNativeArmers) {
+            if (arm())
+                continue;
+            setCompletionWaiterArmed(false);
+            return false;
+        }
+        return true;
+    };
     const hasActiveTasks = () => {
         const count = (inUsed - getPendingPromiseCount()) | 0;
         return count > 0;
@@ -183,13 +192,8 @@ export function createHostTxQueue({ max, lock, returnLock, extraReturnLocks, rel
         txIdle,
         completeFrame,
         waitForCompletion,
+        armCompletionNotifier,
         setCompletionWaiterArmed,
-        setReturnHooks: (lane, hooks) => {
-            if (!Number.isInteger(lane) || lane < 0 || lane >= returnHooks.length) {
-                throw new RangeError(`return lane ${lane} out of range`);
-            }
-            returnHooks[lane] = hooks;
-        },
         enqueue: (functionID, timeout, abortSignal) => {
             const HAS_TIMER = timeout !== undefined;
             const functionIDMasked = functionID & FUNCTION_ID_MASK;

package/src/runtime/worker-common.d.ts

@@ -10,4 +10,5 @@ export type NodeWorkerLike = {
 export declare const toWorkerSafeExecArgv: (flags: string[] | undefined) => string[] | undefined;
 export declare const toWorkerCompatExecArgv: (flags: string[] | undefined) => string[] | undefined;
 export declare const serializeWorkerBootstrapData: (options: WorkerSettings) => WorkerSettings;
-export declare const terminateWorkerQuietly: (worker: SpawnedWorker) => Promise<void>;
+/** Terminate a worker, optionally waiting for it to exit. */
+export declare const terminateWorkerQuietly: (worker: SpawnedWorker, awaitExit?: boolean) => Promise<void>;

package/src/runtime/worker-common.js

@@ -90,12 +90,26 @@ export const serializeWorkerBootstrapData = (options) => {
         },
     };
 };
-export const terminateWorkerQuietly = (worker) => {
+// Bound the wait for process-worker exit.
+const WORKER_EXIT_WAIT_MS = 2_000;
+/** Terminate a worker, optionally waiting for it to exit. */
+export const terminateWorkerQuietly = (worker, awaitExit = false) => {
     try {
-        // Runaway worker termination can be slow or stuck on some runtimes; once the
-        // pool is closing it must not keep the host process alive.
-        worker.unref?.();
-        return Promise.resolve(worker.terminate()).then(() => { }, () => { });
+        if (!awaitExit)
+            worker.unref?.();
+        const exited = Promise.resolve(worker.terminate()).then(() => { }, () => { });
+        if (!awaitExit)
+            return exited;
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                worker.unref?.();
+                resolve();
+            }, WORKER_EXIT_WAIT_MS);
+            void exited.then(() => {
+                clearTimeout(timer);
+                resolve();
+            });
+        });
     }
     catch {
         return Promise.resolve();

package/src/types.d.ts

@@ -13,6 +13,8 @@ type WorkerInvoke = (args: Uint8Array) => Promise<unknown>;
 interface WorkerContext {
     txIdle(): boolean;
     call(descriptor: WorkerCall): WorkerInvoke;
+    /** Ask the worker to leave its dispatch loop before termination. */
+    requestStop?(): Promise<boolean>;
     kills(): Promise<void>;
 }
 type CreateContext = WorkerContext;
@@ -32,30 +34,31 @@ type WorkerData = {
     lock: LockBuffers;
     returnLock: LockBuffers;
     payloadConfig?: PayloadBufferOptions;
-    bufferReferenceReturn?: "copy" | "borrow";
+    /** Enable borrowed returns for this worker's return lane. */
+    sharedReturn?: boolean;
     permission?: ResolvedPermissionProtocol;
     /** Whether this host can arm an async completion waiter on the return lock. */
     notifyOnHostPublish?: boolean;
-    /**
-     * Work stealing. When present, `lock` is a submit region shared by every
-     * worker and this worker claims from it as consumer `consumerId` of
-     * `consumers`, rather than owning a private request lane. `returnLock` stays
-     * private — the endpoint that claims a task owns its response.
-     */
+    /** Process-local IPC channel can carry coalesced completion doorbells. */
+    processCompletionDoorbell?: boolean;
+    /** Process-local Deno callback pointer for waking the host completion pump. */
+    denoCompletionDoorbell?: bigint;
+    /** Process-local Node uv_async handle for waking the host completion pump. */
+    nodeCompletionDoorbell?: bigint;
+    /** Shared submit lock and private return lock for a stealing worker. */
     steal?: {
         consumers: number;
         consumerId: number;
         regionLanes: number;
+        /** Region mutual-exclusion discipline; see `DispatcherSettings.stealClaim`. */
+        claim?: "dekker" | "cas-mask";
     };
 };
 type UnsafeOptions = {
-    /**
-     * Experimental `BufferReference` return lifetime.
-     *
-     * `"copy"` is safe after worker release. `"borrow"` skips the Deno/Bun copy,
-     * but must be released before producer shutdown and must not outlive its ref.
-     */
-    BufferReferenceReturn?: "copy" | "borrow";
+    /** Enable borrowed large returns and the zero-copy `sharedBytes()` path. */
+    SharedBytes?: boolean;
+    /** Enable borrowed large arguments and `pool.sharedArgBytes()`. */
+    SharedArgs?: boolean;
 };
 type LockBuffers = {
     headers: SharedBufferSource;
@@ -181,6 +184,11 @@ type Pool<T extends Record<string, TaskLike<any> | TaskFunctionLike>> = {
      * Thrown errors/rejections reject here as Error objects with cause chains.
      */
     call: FunctionMapType<T>;
+    /**
+     * Allocate an argument buffer. Borrowed buffers are recycled after 32 later
+     * large arguments, so the receiving task must consume them before awaiting.
+     */
+    sharedArgBytes: (byteLength: number) => Uint8Array;
 };
 type ReturnFixed<A extends TaskInput = undefined, B extends Args = undefined, AS extends AbortSignalOption = undefined> = FixPoint<A, B, AS> & SecondPart & {
     createPool: (options?: CreatePool) => SingleTaskPool<A, B, AS>;
@@ -307,10 +315,10 @@ type WorkerSettings = {
     /**
      * How process workers discover their shared-memory control channel.
      *
-     * "inherit" keeps the POSIX fd-inheritance path and is the default outside
-     * Windows. "named" creates an OS-named shared-memory object that wrappers
-     * such as containers can reopen by name when they share the same IPC
-     * namespace.
+     * "inherit" keeps the POSIX fd-inheritance path. "named" creates an
+     * OS-named shared-memory object that wrappers such as containers can reopen
+     * by name when they share the same IPC namespace. Deno-hosted pools and
+     * Windows use a named mapping automatically.
      */
     processSharedMemory?: ProcessSharedMemoryMode | ProcessSharedMemorySettings;
     timers?: WorkerTimers;
@@ -342,47 +350,19 @@ type WorkerTimers = {
     pauseNanoseconds?: number;
 };
 type DispatcherSettings = {
-    /**
-     * How many immediate notify loops before the dispatcher stops re-arming the
-     * pump for free.
-     *
-     * The default depends on what the dispatcher escalates *to*. Polling
-     * escalates to a `setTimeout` ladder costing ~1.1ms even at delay 0, so it
-     * defaults to 128 — escalating is expensive and the wide window also batches
-     * completions. A doorbell escalates to `Atomics.waitAsync` at roughly the
-     * price of one hop, so pools that have one default to 1. Pools without a
-     * doorbell — Deno, or `doorbell: false` — keep 128.
-     *
-     * Setting this explicitly opts out of that coupling for every pool shape.
-     */
+    /** Number of immediate notify loops before backoff starts. */
     stallFreeLoops?: number;
     /**
      * Max backoff delay (milliseconds).
      */
     maxBackoffMs?: number;
     /**
-     * Replace idle completion polling with an `Atomics.waitAsync` doorbell when
-     * the host runtime supports it.
-     *
-     * Defaults to enabled on Node and Bun at any worker count, where it costs
-     * 1.6-3.9x less host CPU per completed call. Under HTTP load, where the host
-     * has real work of its own, that converts to +13% to +36% throughput.
-     *
-     * Turn it off for a pool that oversubscribes its machine. The doorbell only
-     * progresses when the host gets scheduled, so once workers occupy every core
-     * a wake must preempt one: measured +5% to +12.6% rps while workers+host fit
-     * within the cores, -22% to -32% once they do not. That is not gated
-     * automatically because the core count cannot be probed portably.
-     *
-     * Forced off, overriding an explicit `true`, where a doorbell cannot work:
-     * on Deno, whose `waitAsync` does not wake an idle event loop, and for
-     * process workers, which live in another process and so cannot ring a host
-     * waiter at all — V8 keeps its Atomics waiter list per isolate, which is why
-     * they wake through a native futex addon instead. Compiled (Porffor) workers
-     * never reach this path: they reject `host` outright and use pipes rather
-     * than shared memory.
+     * Use a completion doorbell when supported. Deno uses a thread-safe FFI
+     * callback; process and compiled workers use their own completion transport.
      */
     doorbell?: boolean;
+    /** Use Node's native `uv_async_t` completion bridge when available. */
+    nativeDoorbell?: boolean;
     /**
      * Host dispatcher topology.
      * - `"per-thread"`: each worker owns its dispatcher and macro channel.
@@ -396,29 +376,15 @@ type DispatcherSettings = {
      * `KNITTING_DISPATCHER` env var (`serial-channel` or `per-thread`).
      */
     dispatcher?: "per-thread" | "serial-channel";
-    /**
-     * Work stealing: one shared submit region that any worker may
-     * claim from, private return lanes, and a pool-global pending registry. The
-     * endpoint that claims a task owns its response.
-     *
-     * Enabled by default for compatible multi-worker thread and process pools
-     * unless a balancer or private-lane dispatcher was explicitly selected.
-     * One-worker pools, inliners, compiled/Porffor workers, and pools above the
-     * current 31-claimant protocol limit retain their existing transport. Set
-     * `false` (or `KNITTING_STEAL=0`) to opt out; `KNITTING_STEAL=1` explicitly
-     * opts in and overrides a balancer/dispatcher selection.
-     */
+    /** Use a shared submit region with private return lanes. */
     steal?: boolean;
     /**
-     * Lanes claimed per stealing handshake (a power of two, `slots / g >=
-     * workers + 1`). Defaults to the widest region the lane budget allows, which
-     * amortises arbitration best for cheap tasks.
-     *
-     * **A region is a batch.** For expensive tasks, a wide region lets one worker
-     * claim work the others could have run in parallel; set this to `1` (or a
-     * small value) when per-task cost dominates arbitration cost.
+     * Number of lanes claimed per handshake. Use smaller regions for expensive
+     * tasks; Dekker requires at least one spare region per live consumer.
      */
     stealRegionLanes?: number;
+    /** Region-claim discipline: per-consumer Dekker intents or a shared CAS mask. */
+    stealClaim?: "dekker" | "cas-mask";
 };
 type CreatePool = {
     /** Number of workers. Default: 1. */

package/src/worker/loop.js

@@ -1,21 +1,22 @@
-import { addRuntimeDataListener, createRuntimeMessageChannel, RUNTIME_IS_MAIN_THREAD, RUNTIME_IS_PROCESS_WORKER, RUNTIME_PARENT_PORT, RUNTIME_WORKER_DATA, } from "../common/worker-runtime.js";
+import { createRuntimeMessageChannel, PROCESS_COMPLETION_DOORBELL, RUNTIME_IS_MAIN_THREAD, RUNTIME_IS_PROCESS_WORKER, RUNTIME_PARENT_PORT, RUNTIME_WORKER_DATA, } from "../common/worker-runtime.js";
 import { isSharedBufferSource } from "../common/shared-buffer-region.js";
 import { isLockBufferTextCompat } from "../common/shared-buffer-text.js";
+import { createDenoCompletionNotifier } from "../runtime/deno-doorbell.js";
+import { createNodeCompletionNotifier } from "../runtime/node-doorbell.js";
 import { createWorkerRxQueue } from "./rx-queue.js";
-import { createSharedMemoryTransport } from "../ipc/transport/shared-memory.js";
+import { installSharedReturn } from "./shared-return.js";
+import { createSharedMemoryTransport, WORKER_STOP, } from "../ipc/transport/shared-memory.js";
 import { lock2 } from "../memory/lock.js";
-// Side-effect import: registers the payload codec (cycle break for Andromeda;
-// see lock.ts). Must run before any lock2() call.
+// Registers the payload codec before any lock is built.
 import "../memory/payloadCodec.js";
 import { getFunctions } from "./task-loader.js";
-import { pauseGeneric, sleepUntilChanged, whilePausing } from "./timers.js";
+import { IS_BUN_WINDOWS, pauseGeneric, sleepUntilChanged, whilePausing, } from "./timers.js";
 import { IS_ANDROMEDA, RUNTIME, SET_IMMEDIATE } from "../common/runtime.js";
 import { getNodeProcess } from "../common/node-compat.js";
 import { assertWorkerImportsResolved, assertWorkerSharedMemoryBootData, installPerformanceNowGuard, installTerminationGuard, installUnhandledRejectionSilencer, scrubWorkerDataSensitiveBuffers, } from "./safety/index.js";
 import { signalAbortFactory } from "../shared/abortSignal.js";
 import { runWorkerBootstrap } from "./bootstrap.js";
 import { getProcessWorkerNativeWaitU32, installProcessWorkerBootstrap, } from "./process-worker-bootstrap.js";
-import { readBufferReferenceReturnReleaseMessage, } from "../connections/buffer-reference.js";
 import { resolveDebugNamespaces } from "../debug/gate.js";
 const WORKER_FATAL_MESSAGE_KEY = "__knittingWorkerFatal";
 const reportWorkerStartupFatal = (error) => {
@@ -53,27 +54,12 @@ const reportWorkerStartupFatal = (error) => {
         }
     }
 };
-const installBufferReferenceReleaseListener = (releaseReturnedBufferReference) => {
-    const handleMessage = (message) => {
-        const token = readBufferReferenceReturnReleaseMessage(message);
-        if (token !== undefined)
-            releaseReturnedBufferReference(token);
-    };
-    if (RUNTIME_PARENT_PORT !== undefined) {
-        addRuntimeDataListener(RUNTIME_PARENT_PORT, handleMessage);
-        return;
-    }
-    const scope = globalThis;
-    scope.addEventListener?.("message", (event) => {
-        handleMessage(event?.data);
-    });
-};
 export const workerMainLoop = async (startupData) => {
     // Startup-only safety layer: no per-iteration checks in the hot loop.
     installTerminationGuard();
     installUnhandledRejectionSilencer();
     installPerformanceNowGuard();
-    const { debug, sab, thread, startAt, workerOptions, lock, returnLock, abortSignalSAB, abortSignalMax, payloadConfig, bufferReferenceReturn, permission, notifyOnHostPublish, totalNumberOfThread, list, ids, names, at, steal, } = startupData;
+    const { debug, sab, thread, startAt, workerOptions, lock, returnLock, abortSignalSAB, abortSignalMax, payloadConfig, sharedReturn, permission, notifyOnHostPublish, processCompletionDoorbell, denoCompletionDoorbell, nodeCompletionDoorbell, totalNumberOfThread, list, ids, names, at, steal, } = startupData;
     scrubWorkerDataSensitiveBuffers(startupData);
     assertWorkerSharedMemoryBootData({ sab, lock, returnLock });
     const debugNamespaces = resolveDebugNamespaces(debug);
@@ -84,7 +70,7 @@ export const workerMainLoop = async (startupData) => {
             namespaces: debugNamespaces,
         }))
         : undefined;
-    // const object, not `enum`: Andromeda's Nova engine can't parse `enum`.
+    // Andromeda cannot parse enums.
     const Comment = {
         thisIsAHint: 0,
     };
@@ -110,7 +96,24 @@ export const workerMainLoop = async (startupData) => {
         consumers: steal?.consumers,
         consumerId: steal?.consumerId,
         regionLanes: steal?.regionLanes,
+        stealClaim: steal?.claim,
     });
+    const notifyDenoHost = createDenoCompletionNotifier(denoCompletionDoorbell);
+    const notifyNodeHost = createNodeCompletionNotifier(nodeCompletionDoorbell);
+    const processParentPort = processCompletionDoorbell === true
+        ? RUNTIME_PARENT_PORT
+        : undefined;
+    // Bun on Windows flushes process messages only after an event-loop turn.
+    let processRingPending = false;
+    const flushProcessRing = IS_BUN_WINDOWS;
+    const notifyProcessHost = processParentPort === undefined
+        ? undefined
+        : flushProcessRing
+            ? () => {
+                processParentPort.postMessage(PROCESS_COMPLETION_DOORBELL);
+                processRingPending = true;
+            }
+            : () => processParentPort.postMessage(PROCESS_COMPLETION_DOORBELL);
     const returnLockState = lock2({
         headers: returnLock.headers,
         headerSlotStrideU32: returnLock.headerSlotStrideU32,
@@ -120,24 +123,36 @@ export const workerMainLoop = async (startupData) => {
         payloadConfig,
         textCompat: returnLock.textCompat,
         processBoundary: RUNTIME_IS_PROCESS_WORKER,
+        sharedReturn: sharedReturn === true,
+        // A thread return moves its source before publication. Node transfers the
+        // backing-store ownership; Deno and Bun make one owned host copy before
+        // the worker drops its pin. Both avoid the borrowed-return lifetime.
+        moveReturn: !RUNTIME_IS_PROCESS_WORKER,
         // The host parks on this lock's publication word when it has no work to
         // flush. Request locks are host-produced and must not wake that waiter.
-        notifyOnHostPublish,
+        notifyOnHostPublish: notifyOnHostPublish ||
+            notifyDenoHost !== undefined ||
+            notifyNodeHost !== undefined ||
+            notifyProcessHost !== undefined,
+        notifyHostPublish: notifyDenoHost !== undefined
+            ? () => notifyDenoHost(thread)
+            : notifyNodeHost !== undefined
+                ? notifyNodeHost
+                : notifyProcessHost,
     });
     const timers = workerOptions?.timers;
     const spinMicroseconds = timers?.spinMicroseconds ??
-        Math.max(1, totalNumberOfThread) * 50;
+        (totalNumberOfThread <= 1 ? 50 : 0);
     const parkMs = dbg !== undefined
         ? Number.POSITIVE_INFINITY
-        : (timers?.parkMs ??
-            Math.max(1, totalNumberOfThread) * 50);
+        : (timers?.parkMs ?? 1);
     const pauseSpin = (() => {
         const fn = typeof timers?.pauseNanoseconds === "number"
             ? whilePausing({ pauseInNanoseconds: timers.pauseNanoseconds })
             : pauseGeneric;
         return () => fn(); // always a closure wrapper
     })();
-    const { opView, rxStatus, txStatus } = signals;
+    const { opView, rxStatus, txStatus, stopView } = signals;
     const a_store = Atomics.store;
     const a_load = Atomics.load;
     const nativeWaitU32 = getProcessWorkerNativeWaitU32();
@@ -164,16 +179,16 @@ export const workerMainLoop = async (startupData) => {
             maxSignals: abortSignalMax,
         })
         : undefined;
-    const { enqueueLock, serviceBatchImmediate, hasCompleted, writeBatch, hasPending, getAwaiting, drainReturnReleases, releaseReturnedBufferReference, } = createWorkerRxQueue({
+    const { enqueueLock, serviceBatchImmediate, hasCompleted, writeBatch, getAwaiting, drainReturnReleases, releaseDeferredReturns, } = createWorkerRxQueue({
         listOfFunctions,
         workerOptions,
         lock: lockState,
         returnLock: returnLockState,
-        borrowReturnedBufferReferences: bufferReferenceReturn === "borrow",
         hasAborted: abortSignals?.hasAborted,
         stealing: steal !== undefined,
     });
-    installBufferReferenceReleaseListener(releaseReturnedBufferReference);
+    if (sharedReturn === true)
+        installSharedReturn(returnLock.payload);
     a_store(rxStatus, 0, 1);
     const WRITE_MAX = 64;
     const pauseUntil = sleepUntilChanged({
@@ -225,9 +240,9 @@ export const workerMainLoop = async (startupData) => {
     };
     const traceSignals = dbg?.enabled("signals") === true;
     const _hasCompleted = hasCompleted;
-    const _hasPending = hasPending;
     const _getAwaiting = getAwaiting;
     const _drainReturnReleases = drainReturnReleases;
+    const _releaseDeferredReturns = releaseDeferredReturns;
     const _pauseSpin = pauseSpin;
     const _enqueueLock = traceSignals
         ? () => {
@@ -260,42 +275,48 @@ export const workerMainLoop = async (startupData) => {
             pauseUntil(value, spinMicroseconds, parkMs);
         }
         : pauseUntil;
-    const flushBeforeClaim = steal !== undefined;
+    // Stealing flushes completed work before claiming more; private lanes claim
+    // first to keep their single-consumer path short.
+    const pump = steal !== undefined
+        ? () => {
+            let progressed = false;
+            if (_hasCompleted() && _writeBatch(WRITE_MAX) > 0)
+                progressed = true;
+            return _enqueueLock() || progressed;
+        }
+        : () => {
+            const claimed = _enqueueLock();
+            return (_hasCompleted() && _writeBatch(WRITE_MAX) > 0) || claimed;
+        };
+    /** Leave the dispatch loop and acknowledge shutdown. */
+    const stopLoop = () => {
+        // A shutdown rejects unconsumed calls, so no return can still be adopted.
+        // Do not let a worker-isolate exit strand native BufferReference pins.
+        _releaseDeferredReturns();
+        a_store(stopView, 0, WORKER_STOP.acknowledged);
+        a_store(rxStatus, 0, 0);
+        try {
+            port1.close?.();
+            port2.close?.();
+        }
+        catch { }
+    };
     const loop = () => {
         isInMacro = false;
+        // Recompute progress on every pass so idle workers can park.
         let progressed = true;
         let awaiting = 0;
         while (true) {
-            if (flushBeforeClaim) {
-                // Stealing only. Flush finished work before taking more on: a computed
-                // response should not wait behind a claim, and that claim can block on
-                // a peer withdrawing its intent. Measured to hurt the per-lane path,
-                // where a claim is a cheap private decode and picking work up promptly
-                // matters more, so the classic order is kept below.
-                // Reordering must not make `progressed` sticky: it answers "did this
-                // iteration move anything", so it has to start false every pass or the
-                // park below is unreachable and the worker spins a core forever.
-                progressed = false;
-                if (_hasCompleted()) {
-                    if (_writeBatch(WRITE_MAX) > 0)
-                        progressed = true;
-                }
-                progressed = _enqueueLock() || progressed;
-            }
-            else {
-                progressed = _enqueueLock();
-                if (_hasCompleted()) {
-                    if (_writeBatch(WRITE_MAX) > 0)
-                        progressed = true;
-                }
-            }
+            if (stopView[0] !== WORKER_STOP.running)
+                return stopLoop();
+            progressed = pump();
             _drainReturnReleases();
-            if (_hasPending()) {
-                if (_serviceBatchImmediate() > 0)
-                    progressed = true;
-            }
+            if (_serviceBatchImmediate() > 0)
+                progressed = true;
             if ((awaiting = _getAwaiting()) > 0) {
-                if (awaiting !== lastAwaiting)
+                // Promise callbacks need the loop to yield; delay only when no progress
+                // was made, otherwise queued work pays an unnecessary timer hop.
+                if (progressed || awaiting !== lastAwaiting)
                     awaitingSpins = 0;
                 lastAwaiting = awaiting;
                 awaitingSpins++;
@@ -304,9 +325,21 @@ export const workerMainLoop = async (startupData) => {
                 return;
             }
             awaitingSpins = lastAwaiting = 0;
+            if (processRingPending) {
+                processRingPending = false;
+                scheduleTimer(0);
+                return;
+            }
             if (!progressed) {
                 if (txStatus[Comment.thisIsAHint] === 1) {
-                    _pauseSpin();
+                    // During a hint spin only host-driven state can change.
+                    do {
+                        _pauseSpin();
+                        if (stopView[0] !== WORKER_STOP.running)
+                            return stopLoop();
+                        if (pump())
+                            break;
+                    } while (txStatus[Comment.thisIsAHint] === 1);
                     continue;
                 }
                 _pauseUntil(wakeToken, spinMicroseconds, parkMs);

package/src/worker/rx-queue.d.ts

@@ -6,7 +6,6 @@ type ArgumentsForCreateWorkerQueue = {
     workerOptions?: WorkerSettings;
     lock: Lock2;
     returnLock: Lock2;
-    borrowReturnedBufferReferences?: boolean;
     hasAborted?: (signal: number) => boolean;
     now?: () => number;
     /**
@@ -21,14 +20,14 @@ type ArgumentsForCreateWorkerQueue = {
     stealing?: boolean;
 };
 export type CreateWorkerRxQueue = ReturnType<typeof createWorkerRxQueue>;
-export declare const createWorkerRxQueue: ({ listOfFunctions, workerOptions, lock, returnLock, borrowReturnedBufferReferences, hasAborted, now, stealing, }: ArgumentsForCreateWorkerQueue) => {
+export declare const createWorkerRxQueue: ({ listOfFunctions, workerOptions, lock, returnLock, hasAborted, now, stealing, }: ArgumentsForCreateWorkerQueue) => {
     hasCompleted: () => boolean;
     hasPending: () => boolean;
     writeBatch: (max: number) => number;
     serviceBatchImmediate: () => number;
     enqueueLock: () => boolean;
     drainReturnReleases: () => void;
-    releaseReturnedBufferReference: (token: bigint) => void;
+    releaseDeferredReturns: () => void;
     hasAwaiting: () => boolean;
     getAwaiting: () => number;
 };