knitting 0.1.63 → 0.1.70

package/src/runtime/deno-doorbell.js

@@ -0,0 +1,117 @@
+import { RUNTIME } from "../common/runtime.js";
+const getDeno = () => globalThis.Deno;
+/**
+ * Creates Deno's native thread-to-event-loop bridge without loading a custom
+ * library. `threadSafe()` is essential: ordinary UnsafeCallbacks may be
+ * called cross-thread, but do not wake an idle Deno event loop.
+ *
+ * The default pool configuration asks Deno for FFI permission once, so the
+ * native wake path is used whenever the caller approves it. `--allow-ffi`
+ * skips the prompt; `--deny-ffi`, `--no-prompt`, or a rejection preserves the
+ * portable polling dispatcher. Set `host.doorbell` to `false` to avoid asking.
+ */
+export const createDenoCompletionDoorbell = () => {
+    if (RUNTIME !== "deno")
+        return undefined;
+    const deno = getDeno();
+    const queryPermission = deno?.permissions?.querySync;
+    const requestPermission = deno?.permissions?.requestSync;
+    const Callback = deno?.UnsafeCallback;
+    const pointerValue = deno?.UnsafePointer?.value;
+    if (typeof queryPermission !== "function" ||
+        typeof Callback?.threadSafe !== "function" ||
+        typeof pointerValue !== "function") {
+        return undefined;
+    }
+    // `querySync` avoids a redundant prompt for an already granted or explicitly
+    // denied capability. Only the normal `prompt` state asks, and a refusal
+    // leaves the portable polling path intact.
+    try {
+        let state = queryPermission({ name: "ffi" }).state;
+        if (state === "prompt" && typeof requestPermission === "function") {
+            state = requestPermission({ name: "ffi" }).state;
+        }
+        if (state !== "granted")
+            return undefined;
+    }
+    catch {
+        return undefined;
+    }
+    const listeners = new Map();
+    let closed = false;
+    let callback;
+    try {
+        callback = Callback.threadSafe({ parameters: ["i32"], result: "void" }, (lane) => {
+            if (closed)
+                return;
+            try {
+                listeners.get(lane)?.();
+            }
+            catch {
+                // FFI callbacks must never propagate an exception into the worker
+                // thread that rang them. The dispatcher watchdog remains a final
+                // liveness backstop if a host pump has already been closed.
+            }
+        });
+        const pointer = pointerValue(callback.pointer);
+        if (typeof pointer !== "bigint" || pointer === 0n) {
+            callback.close();
+            return undefined;
+        }
+        return {
+            pointer,
+            listen: (lane, notify) => {
+                if (!closed)
+                    listeners.set(lane, notify);
+            },
+            unref: () => {
+                try {
+                    callback.unref?.();
+                }
+                catch {
+                    // best effort; a runtime may already be tearing down its callback
+                }
+            },
+            close: () => {
+                if (closed)
+                    return;
+                closed = true;
+                listeners.clear();
+                callback.close();
+            },
+        };
+    }
+    catch {
+        // Creating a callback is native code. Treat an unsupported Deno build just
+        // like a denied FFI capability and keep the portable poll path.
+        try {
+            callback?.close();
+        }
+        catch {
+            // best effort; callback may not have been initialized
+        }
+        return undefined;
+    }
+};
+/**
+ * Reconstruct a host-owned thread-safe callback in a Deno worker. The pointer
+ * stays process-local and is never included in process-worker boot payloads.
+ */
+export const createDenoCompletionNotifier = (pointer) => {
+    if (RUNTIME !== "deno" || pointer === undefined || pointer === 0n) {
+        return undefined;
+    }
+    const deno = getDeno();
+    const FnPointer = deno?.UnsafeFnPointer;
+    const pointerCreate = deno?.UnsafePointer?.create;
+    if (typeof FnPointer !== "function" || typeof pointerCreate !== "function") {
+        return undefined;
+    }
+    try {
+        const callback = new FnPointer(pointerCreate(pointer), { parameters: ["i32"], result: "void" });
+        return (lane) => callback.call(lane);
+    }
+    catch {
+        return undefined;
+    }
+};

package/src/runtime/dispatcher.d.ts

@@ -2,20 +2,25 @@ 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, waitForCompletion, setCompletionWaiterArmed, }, channelHandler, dispatcherOptions, notifySignal, crossProcess, }: {
+export declare const hostDispatcherLoop: ({ signalBox: { opView, txStatus, rxStatus, }, queue: { completeFrame, hasPendingFrames, flushToWorker, txIdle, waitForCompletion, armCompletionNotifier, setCompletionWaiterArmed, }, channelHandler, dispatcherOptions, notifySignal, crossProcess, nativeCompletionDoorbell, processCompletionDoorbell, }: {
     queue: MultiQueue;
     signalBox: MainSignal;
     channelHandler: ChannelHandler;
     dispatcherOptions?: DispatcherSettings;
     notifySignal?: () => void;
-    /** Workers live in other processes; disables the doorbell. */
+    /** Workers live in other processes; disables only the atomic doorbell. */
     crossProcess?: boolean;
+    /** A runtime-native completion ring that wakes the host event loop. */
+    nativeCompletionDoorbell?: boolean;
+    /** A process IPC completion doorbell that wakes the host event loop. */
+    processCompletionDoorbell?: boolean;
 }) => {
     check: {
         (): void;
         isRunning: boolean;
         rerun: boolean;
     };
+    wakeCompletion: () => void;
 };
 type CheckWithState = (() => void) & {
     isRunning: boolean;
@@ -30,10 +35,7 @@ export declare class ChannelHandler {
     port2: RuntimeMessagePortLike | undefined;
     constructor(pump?: ChannelHandlerPump);
     notify(): void;
-    /**
-     * 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.
-     */
+    /** Register the pump handler and start channel ports when present. */
     open(f: () => void): void;
     /**
      * Detaches the handler, and closes the channel if this pump has one.

package/src/runtime/dispatcher.js

@@ -1,34 +1,13 @@
 import { createRuntimeMessageChannel, } from "../common/worker-runtime.js";
 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.
- */
+/** Runtime-specific macrotask primitive used by the host dispatcher. */
 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`.
- */
+// Polling tolerates a wider free window; a doorbell should arm promptly.
 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, }) => {
+export const hostDispatcherLoop = ({ signalBox: { opView, txStatus, rxStatus, }, queue: { completeFrame, hasPendingFrames, flushToWorker, txIdle, waitForCompletion, armCompletionNotifier, setCompletionWaiterArmed, }, channelHandler, dispatcherOptions, notifySignal, crossProcess, nativeCompletionDoorbell, processCompletionDoorbell, }) => {
     const a_load = Atomics.load;
     const a_store = Atomics.store;
     const a_notify = Atomics.notify;
@@ -39,14 +18,14 @@ 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") &&
+    // Atomics waiters are process-local, so cross-process workers cannot use this
+    // doorbell.
+    const canUseAtomicDoorbell = (RUNTIME === "bun" || RUNTIME === "node") &&
         typeof Atomics.waitAsync === "function";
+    const canUseDoorbell = (dispatcherOptions?.doorbell ?? true) &&
+        (processCompletionDoorbell === true ||
+            (crossProcess !== true &&
+                (canUseAtomicDoorbell || nativeCompletionDoorbell === true)));
     let doorbellEnabled = canUseDoorbell;
     let doorbellArmed = false;
     let doorbellEpoch = 0 | 0;
@@ -80,24 +59,55 @@ export const hostDispatcherLoop = ({ signalBox: { opView, txStatus, rxStatus, },
         doorbellEpoch = token;
         doorbellArmed = true;
         let woke = false;
-        const wake = () => {
+        const wake = (direct = false) => {
             if (!doorbellArmed || doorbellEpoch !== token || woke)
                 return;
             woke = true;
             doorbellArmed = false;
             doorbellEpoch = (doorbellEpoch + 1) | 0;
             setCompletionWaiterArmed(false);
+            if (direct) {
+                // A native arm that observes an already-published completion has no
+                // callback to wait for. Drain it now: routing this known result back
+                // through setImmediate recreates the very millisecond-sized hop that
+                // the native doorbell exists to remove.
+                check.isRunning = true;
+                check();
+                return;
+            }
             // 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);
+        if (nativeCompletionDoorbell === true ||
+            processCompletionDoorbell === true) {
+            // A native arm reports two different things and they must not be
+            // conflated: `false` means a completion was already published so the arm
+            // deliberately did not ring, which is a normal hot-path outcome. Only a
+            // throw means the transport is unusable. Treating the race as
+            // "unsupported" disabled the doorbell permanently on its second arm.
+            let armed = false;
+            let usable = true;
+            try {
+                armed = armCompletionNotifier();
+            }
+            catch {
+                usable = false;
+            }
+            supported = usable;
+            // The arm itself drains the completion it just observed.
+            if (usable && !armed)
+                wake(true);
         }
-        catch {
-            supported = false;
+        else {
+            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.
@@ -111,7 +121,9 @@ export const hostDispatcherLoop = ({ signalBox: { opView, txStatus, rxStatus, },
             doorbellArmed = false;
             doorbellEpoch = (doorbellEpoch + 1) | 0;
             setCompletionWaiterArmed(false);
-            notify();
+            if (nativeCompletionDoorbell !== true &&
+                processCompletionDoorbell !== true)
+                notify();
         }
     };
     const check = () => {
@@ -124,9 +136,7 @@ export const hostDispatcherLoop = ({ signalBox: { opView, txStatus, rxStatus, },
         // 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.
+        // Avoid waking an idle lane.
         if (txIdle()) {
             check.isRunning = false;
             return;
@@ -139,15 +149,13 @@ export const hostDispatcherLoop = ({ signalBox: { opView, txStatus, rxStatus, },
         do {
             check.rerun = false;
             txStatus[0] = 1;
-            // Wake the worker before draining so it can start processing while we flush.
+            // Wake a parked worker whenever its receive status is clear. Pending
+            // frames are not a reliable gate because the queue may have room.
             if (a_load(rxStatus, 0) === 0) {
                 a_store(opView, 0, 1);
                 wakeSignal();
             }
-            // 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.
+            // Only completed frames count as progress for backoff purposes.
             let completed = false;
             let progressed = true;
             while (progressed) {
@@ -164,7 +172,9 @@ export const hostDispatcherLoop = ({ signalBox: { opView, txStatus, rxStatus, },
             }
             txStatus[0] = 0;
             if (!txIdle()) {
-                if (completed || hasPendingFrames()) {
+                // Queued frames indicate back-pressure, not progress; only a completion
+                // frees a request slot.
+                if (completed) {
                     stallCount = 0 | 0;
                 }
                 else {
@@ -182,6 +192,15 @@ export const hostDispatcherLoop = ({ signalBox: { opView, txStatus, rxStatus, },
     };
     check.isRunning = false;
     check.rerun = false;
+    /** Enter the drain from a native or IPC completion event. */
+    const wakeCompletion = () => {
+        if (inFlight || check.isRunning) {
+            check.rerun = true;
+            return;
+        }
+        check.isRunning = true;
+        check();
+    };
     const scheduleNotify = () => {
         if (stallCount <= stallFreeLoops) {
             notify();
@@ -213,7 +232,7 @@ export const hostDispatcherLoop = ({ signalBox: { opView, txStatus, rxStatus, },
             }
         }, delay);
     };
-    return { check };
+    return { check, wakeCompletion };
 };
 export class ChannelHandler {
     // Set only when the pump is a MessageChannel. The `setImmediate` pump has no
@@ -223,14 +242,16 @@ export class ChannelHandler {
     port2;
     #handler;
     #notify;
+    #pending = false;
+    #run = () => {
+        // Clear before draining so a busy lane can request the next turn.
+        this.#pending = false;
+        this.#handler?.();
+    };
     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?.();
-            };
+            const run = this.#run;
             this.#notify = () => {
                 immediate(run);
             };
@@ -246,23 +267,24 @@ export class ChannelHandler {
         };
     }
     notify() {
+        // Coalesce notifications into one pending drain.
+        if (this.#pending)
+            return;
+        this.#pending = true;
         this.#notify();
     }
-    /**
-     * 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.
-     */
+    /** Register the pump handler and start channel ports when present. */
     open(f) {
         this.#handler = f;
         const port1 = this.port1;
         if (port1 === undefined)
             return;
         if (typeof port1.on === "function") {
-            port1.on("message", f);
+            port1.on("message", this.#run);
         }
         else {
             // @ts-ignore
-            port1.onmessage = f;
+            port1.onmessage = this.#run;
         }
         this.port1?.start?.();
         this.port2?.start?.();

package/src/runtime/host-arg-arena.d.ts

@@ -0,0 +1,3 @@
+export type HostArgAllocator = (byteLength: number) => Uint8Array;
+/** Create an argument allocator with a plain-allocation fallback. */
+export declare const createHostArgAllocator: (payload: object | undefined) => HostArgAllocator;

package/src/runtime/host-arg-arena.js

@@ -0,0 +1,16 @@
+import { getSharedReturnAllocator } from "../memory/payloadCodec.js";
+/** Create an argument allocator with a plain-allocation fallback. */
+export const createHostArgAllocator = (payload) => {
+    const allocate = payload === undefined
+        ? undefined
+        : getSharedReturnAllocator(payload);
+    if (allocate === undefined) {
+        return (byteLength) => new Uint8Array(byteLength);
+    }
+    return (byteLength) => {
+        if (!Number.isInteger(byteLength) || byteLength < 0) {
+            throw new RangeError("sharedArgBytes(byteLength) requires a non-negative integer");
+        }
+        return allocate(byteLength, false) ?? new Uint8Array(byteLength);
+    };
+};

package/src/runtime/node-doorbell.d.ts

@@ -0,0 +1,14 @@
+export type NodeCompletionDoorbell = {
+    /** Process-local handle a Node thread worker may ring through the addon. */
+    pointer: bigint;
+    /** Invalidates the native handle after every worker that holds it has exited. */
+    close: () => void;
+};
+/**
+ * Bridge a Node worker thread into the host's libuv I/O phase. The addon owns
+ * the `uv_async_t`; this wrapper owns the JS callback and makes missing native
+ * prebuilds a normal capability fallback.
+ */
+export declare const createNodeCompletionDoorbell: (notify: () => void) => NodeCompletionDoorbell | undefined;
+/** Rebuild the process-local native ring in a Node thread worker. */
+export declare const createNodeCompletionNotifier: (pointer: bigint | undefined) => (() => void) | undefined;

package/src/runtime/node-doorbell.js

@@ -0,0 +1,84 @@
+import { RUNTIME } from "../common/runtime.js";
+import { getNodeBuiltinModule } from "../common/node-compat.js";
+import { loadNodeNativeAddon } from "../connections/node-addons.js";
+const loadDoorbellAddon = () => {
+    if (RUNTIME !== "node")
+        return undefined;
+    const nodeModule = getNodeBuiltinModule("node:module");
+    if (nodeModule === undefined)
+        return undefined;
+    try {
+        return loadNodeNativeAddon(nodeModule.createRequire(import.meta.url), "knitting_doorbell");
+    }
+    catch {
+        // Native wakeups are an optional fast path. A missing prebuild must retain
+        // the portable Atomics.waitAsync dispatcher rather than preventing plain
+        // thread workers from starting.
+        return undefined;
+    }
+};
+/**
+ * Bridge a Node worker thread into the host's libuv I/O phase. The addon owns
+ * the `uv_async_t`; this wrapper owns the JS callback and makes missing native
+ * prebuilds a normal capability fallback.
+ */
+export const createNodeCompletionDoorbell = (notify) => {
+    const addon = loadDoorbellAddon();
+    if (addon === undefined)
+        return undefined;
+    let pointer;
+    let closed = false;
+    try {
+        pointer = addon.createCompletionDoorbell(() => {
+            if (closed)
+                return;
+            try {
+                notify();
+            }
+            catch {
+                // An exception must not escape a libuv callback. A scheduled host
+                // drain or the dispatcher watchdog still provides a liveness backstop.
+            }
+        });
+        if (typeof pointer !== "bigint" || pointer === 0n)
+            return undefined;
+        // A dormant pool must not be kept alive solely by an idle uv_async_t.
+        addon.unrefCompletionDoorbell(pointer);
+    }
+    catch {
+        return undefined;
+    }
+    return {
+        pointer,
+        close: () => {
+            if (closed)
+                return;
+            closed = true;
+            try {
+                addon.closeCompletionDoorbell(pointer);
+            }
+            catch {
+                // Shutdown can race Node environment teardown; the addon's environment
+                // cleanup hook owns the remaining lifetime in that case.
+            }
+        },
+    };
+};
+/** Rebuild the process-local native ring in a Node thread worker. */
+export const createNodeCompletionNotifier = (pointer) => {
+    if (RUNTIME !== "node" || pointer === undefined || pointer === 0n) {
+        return undefined;
+    }
+    const addon = loadDoorbellAddon();
+    if (addon === undefined)
+        return undefined;
+    return () => {
+        try {
+            addon.ringCompletionDoorbell(pointer);
+        }
+        catch {
+            // The host can close while a forced worker teardown is in flight. Its
+            // return-lock watchdog covers that final in-flight publication.
+        }
+    };
+};

package/src/runtime/pool.d.ts

@@ -2,28 +2,25 @@ import { createHostTxQueue } from "./tx-queue.js";
 import { type ProcessSharedMemoryBacking, type ProcessStealMemoryLayout, type ResolvedProcessSharedMemorySettings } from "./process-worker.js";
 import { type Sab } from "../ipc/transport/shared-memory.js";
 import { ChannelHandler, type DispatcherCheck } from "./dispatcher.js";
-import { lock2, type Task } from "../memory/lock.js";
+import type { DenoCompletionDoorbell } from "./deno-doorbell.js";
+import { lock2, type StealClaimDiscipline, type Task } from "../memory/lock.js";
 import "../memory/payloadCodec.js";
 import type { DebugOptions, DispatcherSettings, LockBuffers, WorkerContext, WorkerData, WorkerSettings } from "../types.js";
 import "../worker/loop.js";
 import { type PayloadBufferOptions } from "../memory/payload-config.js";
-/**
- * Build the buffers, host-side locks and pending registry that a stealing pool
- * shares. One submit region for every worker to claim from, one private return
- * region per worker, and a single pool-global queue so a response arriving on
- * any lane settles the right promise.
- *
- * Region width follows paper §6.1: the largest power-of-two `g` leaving a spare
- * region for a delayed claimant (`slots / g >= consumers + 1`). At 32 slots that
- * caps how wide a region can be well before it caps the worker count.
- */
+/** Build the shared submit and private return buffers for a stealing pool. */
 export declare const resolveStealRegionLanes: (consumers: number) => number;
+/** Return the widest region allowed by the selected claim discipline. */
+export declare const resolveMaxStealRegionLanes: (consumers: number, stealClaim?: StealClaimDiscipline) => number;
 /** Maximum claimants that leave the protocol's required spare region. */
 export declare const MAX_STEAL_CONSUMERS: number;
-export declare const createStealPoolBuffers: ({ threads, payload, regionLanes, abortSignalCapacity, usesAbortSignal, processWorker, }: {
+export declare const createStealPoolBuffers: ({ threads, payload, sharedArgs, regionLanes, stealClaim, abortSignalCapacity, usesAbortSignal, processWorker, }: {
     threads: number;
     payload?: PayloadBufferOptions;
+    /** Hand large arguments to workers as borrowed regions. See `unsafe.SharedArgs`. */
+    sharedArgs?: boolean;
     regionLanes?: number;
+    stealClaim?: StealClaimDiscipline;
     abortSignalCapacity?: number;
     usesAbortSignal?: boolean;
     processWorker?: {
@@ -53,6 +50,7 @@ export declare const createStealPoolBuffers: ({ threads, payload, regionLanes, a
             activeRejectPlaceholder?: Task["reject"];
         }) => () => number;
         waitForHostChange: (timeoutMs?: number) => import("../memory/lock.js").WaitAsyncResult | undefined;
+        armHostNotifier: () => boolean;
         setHostWaiterArmed: (armed: boolean) => void;
         hasPendingFrames: () => boolean;
         getPendingFrameCount: () => number;
@@ -82,6 +80,7 @@ export declare const createStealPoolBuffers: ({ threads, payload, regionLanes, a
             activeRejectPlaceholder?: Task["reject"];
         }) => () => number;
         waitForHostChange: (timeoutMs?: number) => import("../memory/lock.js").WaitAsyncResult | undefined;
+        armHostNotifier: () => boolean;
         setHostWaiterArmed: (armed: boolean) => void;
         hasPendingFrames: () => boolean;
         getPendingFrameCount: () => number;
@@ -97,19 +96,20 @@ export declare const createStealPoolBuffers: ({ threads, payload, regionLanes, a
         txIdle: () => boolean;
         completeFrame: () => number;
         waitForCompletion: (onWake: () => void, timeoutMs?: number) => boolean;
+        armCompletionNotifier: () => boolean;
         setCompletionWaiterArmed: (armed: boolean) => void;
-        setReturnHooks: (lane: number, hooks: (import("../connections/buffer-reference.js").BufferReferenceReturnHooks | ((token: bigint) => void)) | undefined) => void;
         enqueue: (functionID: number, timeout?: import("../types.js").TaskTimeout, abortSignal?: import("../types.js").AbortSignalOption) => (rawArgs: unknown) => Promise<never> | import("../common/with-resolvers.js").PromiseWithMaybeReject<unknown>;
         flushToWorker: () => boolean;
         enqueueKnown: (task: Task) => boolean;
         settlePromisePayload: (task: Task, isRejected: boolean, value: unknown) => boolean;
     };
     regionLanes: number;
+    stealClaim: StealClaimDiscipline;
     processMemory: ProcessStealMemoryLayout;
     abortSignalSAB: SharedArrayBuffer | import("../types.js").SharedBufferRegion;
     abortSignalMax: number;
 };
-export declare const spawnWorkerContext: ({ list, ids, names, sab, thread, debug, hostDebug, totalNumberOfThread, workerCount, source, at, workerOptions, workerExecArgv, permission, host, payload, bufferReferenceReturn, abortSignalCapacity, usesAbortSignal, sharedChannelHandler, stealPool, }: {
+export declare const spawnWorkerContext: ({ list, ids, names, sab, thread, debug, hostDebug, totalNumberOfThread, workerCount, source, at, workerOptions, workerExecArgv, permission, host, payload, sharedBytesEnabled, abortSignalCapacity, usesAbortSignal, sharedChannelHandler, denoCompletionDoorbell, stealPool, }: {
     list: string[];
     ids: number[];
     names: string[];
@@ -131,7 +131,7 @@ export declare const spawnWorkerContext: ({ list, ids, names, sab, thread, debug
     permission?: WorkerData["permission"];
     host?: DispatcherSettings;
     payload?: PayloadBufferOptions;
-    bufferReferenceReturn?: "copy" | "borrow";
+    sharedBytesEnabled?: boolean;
     abortSignalCapacity?: number;
     usesAbortSignal?: boolean;
     /**
@@ -139,6 +139,8 @@ export declare const spawnWorkerContext: ({ list, ids, names, sab, thread, debug
      * macro channel that runs all lane checks.
      */
     sharedChannelHandler?: ChannelHandler;
+    /** Deno-only native callback shared by every thread worker in this pool. */
+    denoCompletionDoorbell?: DenoCompletionDoorbell;
     /**
      * Work-stealing wiring. When present the submit region, both host-side locks
      * and the pending registry are owned by `createPool` and shared: every worker
@@ -155,6 +157,7 @@ export declare const spawnWorkerContext: ({ list, ids, names, sab, thread, debug
         consumers: number;
         consumerId: number;
         regionLanes: number;
+        stealClaim?: StealClaimDiscipline;
         abortSignalSAB?: LockBuffers["headers"];
         abortSignalMax?: number;
         processMemory?: ProcessStealMemoryLayout;
@@ -169,5 +172,8 @@ export declare const spawnWorkerContext: ({ list, ids, names, sab, thread, debug
     dispatcherCheck?: DispatcherCheck;
     laneWake?: () => void;
     bindSend?: (fn: () => void) => void;
+    bindCompletionWake?: (fn: () => void) => void;
+    processCompletionDoorbell?: boolean;
+    nodeCompletionDoorbell?: boolean;
 });
 export type CreateContext = WorkerContext;