knitting 0.1.63 → 0.1.73

package/src/runtime/process-worker.js

@@ -109,6 +109,13 @@ const isWindowsRuntimeHost = () => {
         return denoOs === "windows";
     return globalThis.process?.platform === "win32";
 };
+const processWorkerNeedsNamedMemory = (sharedMemory) => 
+// `Deno.Command` does not reliably carry an anonymous memfd/shm fd into a
+// child as stdin: Linux can hand the child a non-mappable descriptor and
+// macOS cannot always reopen the host fd through `/dev/fd`. Named mappings
+// are reopened by the worker instead, which works across Deno's supported
+// hosts and process-worker runtimes.
+sharedMemory.mode === "named" || isWindowsRuntimeHost() || RUNTIME === "deno";
 let processWorkerMemoryNameCounter = 0;
 const makeProcessWorkerMemoryName = (thread, prefix = "kpw") => {
     const processId = globalThis.process?.pid ??
@@ -142,7 +149,7 @@ export const createProcessWorkerMemoryLayout = ({ signalBytes, abortBytes, paylo
     const requestPayloadSlice = carpet.take("requestPayload", payloadBytes);
     const returnPayloadSlice = carpet.take("returnPayload", payloadBytes);
     const primitives = getProcessWorkerSharedMemoryPrimitives();
-    const forceNamed = sharedMemory.mode === "named" || isWindowsRuntimeHost();
+    const forceNamed = processWorkerNeedsNamedMemory(sharedMemory);
     const mapping = primitives.createSharedMemory(forceNamed
         ? {
             size: carpet.byteLength(),
@@ -215,7 +222,7 @@ export const createProcessStealMemoryLayout = ({ threads, signalBytes, abortByte
         returnPayload: carpet.take(`returnPayload-${thread}`, payloadBytes),
     }));
     const primitives = getProcessWorkerSharedMemoryPrimitives();
-    const forceNamed = sharedMemory.mode === "named" || isWindowsRuntimeHost();
+    const forceNamed = processWorkerNeedsNamedMemory(sharedMemory);
     const mapping = primitives.createSharedMemory(forceNamed
         ? {
             size: carpet.byteLength(),
@@ -546,6 +553,19 @@ export const createProcessWorkerNativeSignalNotifier = ({ processRuntime, signal
         return undefined;
     }
 };
+/**
+ * Whether this host/child pair has the Node-compatible IPC channel that the
+ * process completion-doorbell prototype uses. Deno process workers currently
+ * boot through environment data and do not have that channel.
+ */
+export const processWorkerUsesIpc = ({ processRuntime, commandPrefix, }) => {
+    if (processRuntime === undefined || commandPrefix !== undefined)
+        return false;
+    if (RUNTIME === "node") {
+        return processRuntime === "node" || processRuntime === "bun";
+    }
+    return RUNTIME === "bun" && processRuntime === "bun";
+};
 const createProcessWorkerEventHub = () => {
     const messageHandlers = [];
     const errorHandlers = [];
@@ -661,7 +681,16 @@ const spawnNodeHostedProcessWorker = ({ workerUrl, bootPayload, memory, processR
         child.on("message", events.emitMessage);
         queueMicrotask(() => child.send?.(bootPayload));
     }
-    child.on("error", events.emitError);
+    child.on("error", (error) => {
+        if (error?.code !== "ENOENT") {
+            events.emitError(error);
+            return;
+        }
+        // A bare "spawn deno ENOENT" does not say which option chose the binary.
+        events.emitError(new Error(`process worker binary "${command}" was not found (spawn ENOENT). ` +
+            `Install ${processRuntime} or set worker.processRuntime to "node", ` +
+            `"deno" or "bun"; it defaults to "deno".`, { cause: error }));
+    });
     let resolveExit = () => { };
     const exited = new Promise((resolve) => {
         resolveExit = resolve;

package/src/runtime/tx-queue.d.ts

@@ -2,7 +2,6 @@ import "../memory/payloadCodec.js";
 import { type Lock2, type Task } from "../memory/lock.js";
 import type { AbortSignalOption, TaskTimeout } from "../types.js";
 import { type SignalAbortStore } from "../shared/abortSignal.js";
-import { type BufferReferenceReturnHooks } from "../connections/buffer-reference.js";
 type RawArguments = unknown;
 type FunctionID = number;
 type QueueTask = Task;
@@ -23,19 +22,18 @@ type CreateHostTxQueueArgs = {
      * When omitted, only `returnLock` is drained (the classic one-lane shape).
      */
     extraReturnLocks?: readonly Lock2[];
-    releaseBufferReferenceReturn?: ((token: bigint) => void) | BufferReferenceReturnHooks;
     abortSignals?: Pick<SignalAbortStore, "getSignal" | "setSignal" | "resetSignal" | "closeNow">;
     now?: () => number;
 };
-type ReturnHooks = ((token: bigint) => void) | BufferReferenceReturnHooks;
-export declare function createHostTxQueue({ max, lock, returnLock, extraReturnLocks, releaseBufferReferenceReturn, abortSignals, now, }: CreateHostTxQueueArgs): {
-    rejectAll: (reason: string) => void;
+export declare function createHostTxQueue({ max, lock, returnLock, extraReturnLocks, abortSignals, now, }: CreateHostTxQueueArgs): {
+    close: (reason: unknown) => void;
+    rejectAll: (reason: unknown) => void;
     hasPendingFrames: () => boolean;
     txIdle: () => boolean;
     completeFrame: () => number;
     waitForCompletion: (onWake: () => void, timeoutMs?: number) => boolean;
+    armCompletionNotifier: () => boolean;
     setCompletionWaiterArmed: (armed: boolean) => void;
-    setReturnHooks: (lane: number, hooks: ReturnHooks | undefined) => void;
     enqueue: (functionID: FunctionID, timeout?: TaskTimeout, abortSignal?: AbortSignalOption) => (rawArgs: RawArguments) => Promise<never> | import("../common/with-resolvers.js").PromiseWithMaybeReject<unknown>;
     flushToWorker: () => boolean;
     enqueueKnown: (task: QueueTask) => boolean;

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)");
     };
@@ -35,6 +34,7 @@ export function createHostTxQueue({ max, lock, returnLock, extraReturnLocks, rel
     const queuePush = (task) => queue.push(task);
     const { publish, flushPending, hasPendingFrames, getPendingFrameCount, getPendingPromiseCount, resetPendingState, } = lock;
     let inUsed = 0 | 0;
+    let closedReason;
     const resetSignal = abortSignals?.resetSignal;
     const nowTime = now ?? p_now;
     const onReturnResolved = (task) => {
@@ -66,33 +66,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 +88,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 +129,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 +145,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;
@@ -173,29 +183,34 @@ export function createHostTxQueue({ max, lock, returnLock, extraReturnLocks, rel
         resetPendingState();
         inUsed = 0 | 0;
     };
+    /** Reject everything in flight, and every later call, with `reason`. */
+    const close = (reason) => {
+        if (closedReason !== undefined)
+            return;
+        closedReason = reason;
+        rejectAll(reason);
+    };
     const flushToWorker = () => flushPending();
     const enqueueKnown = (task) => {
         return publish(task);
     };
     return {
+        close,
         rejectAll,
         hasPendingFrames,
         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;
             const USE_SIGNAL = abortSignal !== undefined &&
                 abortSignals !== undefined;
             return (rawArgs) => {
+                if (closedReason !== undefined)
+                    return Promise.reject(closedReason);
                 if (inUsed === queue.length) {
                     const newSize = inUsed + 32;
                     let current = queue.length;

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

@@ -7,8 +7,15 @@ export type SpawnedWorker = {
 export type NodeWorkerLike = {
     on?: (event: "error" | "exit" | "message", listener: (...args: unknown[]) => void) => void;
 };
+export declare const isNodePermissionExecFlag: (flag: string) => boolean;
 export declare const toWorkerSafeExecArgv: (flags: string[] | undefined) => string[] | undefined;
+/** Preserve process-worker runtime flags while replacing inherited permissions. */
 export declare const toWorkerCompatExecArgv: (flags: string[] | undefined) => string[] | undefined;
+/**
+ * Warn once per flag set when a `workerExecArgv` flag the caller asked for did
+ * not reach the worker thread, instead of dropping it silently.
+ */
+export declare const warnDroppedWorkerExecArgv: (requested: string[] | undefined, applied: string[] | undefined) => void;
 export declare const serializeWorkerBootstrapData: (options: WorkerSettings) => WorkerSettings;
 /** 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

@@ -6,24 +6,29 @@ const execFlagKey = (flag) => flag.split("=", 1)[0];
 const NODE_PERMISSION_EXEC_FLAGS = new Set([
     "--permission",
     "--experimental-permission",
+    "--experimental-config-file",
+    "--experimental-default-config-file",
     "--allow-fs-read",
     "--allow-fs-write",
+    "--allow-fs-vfs",
     "--allow-worker",
     "--allow-child-process",
+    "--allow-env",
     "--allow-net",
     "--allow-addons",
     "--allow-ffi",
     "--allow-wasi",
+    "--allow-inspector",
+    "--allow-openssl-store",
 ]);
 const NODE_WORKER_SAFE_EXEC_FLAGS = new Set([
     "--experimental-ffi",
     "--experimental-transform-types",
-    "--expose-gc",
     "--no-warnings",
     ...NODE_PERMISSION_EXEC_FLAGS,
 ]);
 const isNodeWorkerSafeExecFlag = (flag) => NODE_WORKER_SAFE_EXEC_FLAGS.has(execFlagKey(flag));
-const isNodePermissionExecFlag = (flag) => NODE_PERMISSION_EXEC_FLAGS.has(execFlagKey(flag));
+export const isNodePermissionExecFlag = (flag) => NODE_PERMISSION_EXEC_FLAGS.has(execFlagKey(flag));
 export const toWorkerSafeExecArgv = (flags) => {
     if (!flags || flags.length === 0)
         return undefined;
@@ -40,6 +45,7 @@ export const toWorkerSafeExecArgv = (flags) => {
     }
     return deduped;
 };
+/** Preserve process-worker runtime flags while replacing inherited permissions. */
 export const toWorkerCompatExecArgv = (flags) => {
     const safe = toWorkerSafeExecArgv(flags);
     if (!safe || safe.length === 0)
@@ -47,6 +53,26 @@ export const toWorkerCompatExecArgv = (flags) => {
     const compat = safe.filter((flag) => !isNodePermissionExecFlag(flag));
     return compat.length > 0 ? compat : undefined;
 };
+const droppedExecArgvWarnings = new Set();
+/**
+ * Warn once per flag set when a `workerExecArgv` flag the caller asked for did
+ * not reach the worker thread, instead of dropping it silently.
+ */
+export const warnDroppedWorkerExecArgv = (requested, applied) => {
+    if (!requested || requested.length === 0)
+        return;
+    const kept = new Set(applied ?? []);
+    const dropped = requested.filter((flag) => !kept.has(flag));
+    if (dropped.length === 0)
+        return;
+    const key = dropped.join(" ");
+    if (droppedExecArgvWarnings.has(key))
+        return;
+    droppedExecArgvWarnings.add(key);
+    console.warn(`knitting: workerExecArgv ${dropped.join(", ")} cannot be applied to a ` +
+        `worker thread and was dropped. V8 and process-wide flags must be ` +
+        `passed to the host process instead.`);
+};
 const isPlainRecord = (value) => {
     if (value === null || typeof value !== "object")
         return false;

package/src/types.d.ts

@@ -14,7 +14,7 @@ interface WorkerContext {
     txIdle(): boolean;
     call(descriptor: WorkerCall): WorkerInvoke;
     /** Ask the worker to leave its dispatch loop before termination. */
-    requestStop?(): Promise<void>;
+    requestStop?(): Promise<boolean>;
     kills(): Promise<void>;
 }
 type CreateContext = WorkerContext;
@@ -28,36 +28,43 @@ type WorkerData = {
     thread: number;
     totalNumberOfThread: number;
     debug?: DebugOptions;
+    /**
+     * Host's debug zero as `performance.timeOrigin + performance.now()` (Unix
+     * epoch ms), so worker debug clocks line up with the host's. Set only when
+     * debug is requested.
+     */
+    debugEpoch?: number;
     startAt: number;
     workerOptions?: WorkerSettings;
     at: number[];
     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;
+        /** Claim discipline; see `DispatcherSettings.stealClaim`. */
+        claim?: "dekker" | "ticket";
     };
 };
 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;
@@ -172,17 +179,26 @@ type SingleTaskPool<A extends TaskInput = Args, B extends Args = Args, AS extend
     shutdown: (delayMs?: number) => Promise<void>;
     /** Starts shutdown at scope exit. Use `shutdown()` when you must await it. */
     [Symbol.dispose]: () => void;
+    /** `await using` awaits worker teardown at scope exit. */
+    [Symbol.asyncDispose]: () => Promise<void>;
 };
 type Pool<T extends Record<string, TaskLike<any> | TaskFunctionLike>> = {
     /** Await worker teardown now. `using` disposes at scope exit without awaiting. */
     shutdown: (delayMs?: number) => Promise<void>;
     /** Starts shutdown at scope exit. Use `shutdown()` when you must await it. */
     [Symbol.dispose]: () => void;
+    /** `await using` awaits worker teardown at scope exit. */
+    [Symbol.asyncDispose]: () => Promise<void>;
     /**
      * Typed task callers. Each call accepts the task input or a native Promise.
      * 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>;
@@ -208,8 +224,8 @@ type Balancer = BalancerStrategy | {
      */
     strategy?: BalancerStrategy;
 };
-/** Debug namespaces for host setup, worker state, imports, globals, and lifecycle. */
-type DebugNamespace = "host" | "globals" | "signals" | "imports" | "lifecycle";
+/** Debug namespaces for host setup, worker state, imports, globals, lifecycle, and steal claims. */
+type DebugNamespace = "host" | "globals" | "signals" | "imports" | "lifecycle" | "steal";
 type DebugFlags = {
     [Namespace in DebugNamespace]?: boolean;
 };
@@ -309,10 +325,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;
@@ -334,7 +350,10 @@ type WorkerTimers = {
      */
     spinMicroseconds?: number;
     /**
-     * Atomics.wait timeout when parked (milliseconds).
+     * Atomics.wait timeout when parked (milliseconds). Defaults to 1000 for
+     * thread workers, which the host wakes on every publish, so the timeout is
+     * only a safety net; 1 for process workers, most of which only rediscover
+     * work when it expires.
      */
     parkMs?: number;
     /**
@@ -344,47 +363,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.
@@ -398,29 +389,20 @@ 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;
+    /**
+     * Publication-ordered tickets (`"ticket"`, the default) or Dekker regions
+     * (`"dekker"`). Unrecognised values are rejected rather than defaulted, so a
+     * removed discipline such as `cas-mask` fails at pool creation. Ticket pools
+     * reject pending and future calls on worker failure.
+     */
+    stealClaim?: "dekker" | "ticket";
 };
 type CreatePool = {
     /** Number of workers. Default: 1. */
@@ -448,14 +430,20 @@ type CreatePool = {
      */
     host?: DispatcherSettings;
     /**
-     * Extra Node.js execArgv flags for worker threads (e.g. ["--expose-gc"]).
-     * Defaults to process.execArgv plus "--expose-gc" when allowed.
+     * Extra Node.js execArgv flags for worker threads (e.g. ["--no-warnings"]).
+     * Defaults to compatible flags from process.execArgv. Node permission flags
+     * are replaced by the resolved `permission` policy.
+     *
+     * Node rejects V8 and process-wide flags (`--expose-gc`,
+     * `--max-old-space-size`, ...). Unsupported caller flags are dropped with a
+     * warning. Permission flags are never dropped to start an unpermissioned
+     * thread worker; pool creation fails if Node cannot apply them.
      */
     workerExecArgv?: string[];
     /**
      * Runtime permission protocol.
-     * Omit to use strict defaults with `allowImport: true`; worker console is
-     * quiet unless `permission: { console: true }`.
+     * Omit to use strict defaults with `allowImport: true`. `console` is
+     * accepted but not enforced: worker console output is always forwarded.
      *
      * Task code cannot terminate the host: process/Deno exit APIs are blocked.
      * Use `"strict"` (default for object mode) or `"unsafe"`.