knitting 0.1.60 → 0.1.61

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

@@ -1,17 +1,10 @@
 import { type LockControlCarpet } from "../memory/byte-carpet.js";
 import type { DebugOptions, LockBuffers, WorkerData, WorkerSettings } from "../types.js";
+import { type NodeWorkerLike, type SpawnedWorker } from "./worker-common.js";
 import { RUNTIME_PROCESS_WORKER_BOOT_VERSION } from "../common/worker-runtime.js";
 import { type SharedBufferSource } from "../common/shared-buffer-region.js";
 import { FileDescriptor, type ProcessSharedBufferMetadata } from "../connections/index.js";
 import type { SharedMemoryBuffer, SharedMemoryMapping } from "../connections/types.js";
-export type SpawnedWorker = {
-    terminate: () => unknown;
-    unref?: () => unknown;
-    postMessage?: (message: unknown) => void;
-};
-export type NodeWorkerLike = {
-    on?: (event: "error" | "exit" | "message", listener: (...args: unknown[]) => void) => void;
-};
 type ProcessWorkerWireLockBuffers = Omit<LockBuffers, "headers" | "lockSector" | "payload" | "payloadSector"> & {
     headers: ProcessSharedBufferMetadata;
     lockSector: ProcessSharedBufferMetadata;
@@ -60,8 +53,6 @@ type ProcessSharedMemoryAllocator = {
     createBuffer: (byteLength: number) => SharedArrayBuffer;
     backings: ProcessSharedMemoryBacking[];
 };
-export declare const toWorkerSafeExecArgv: (flags: string[] | undefined) => string[] | undefined;
-export declare const toWorkerCompatExecArgv: (flags: string[] | undefined) => string[] | undefined;
 export declare const createProcessSharedMemoryAllocator: (debug: DebugOptions | undefined) => ProcessSharedMemoryAllocator | undefined;
 export declare const createProcessWorkerMemoryLayout: ({ signalBytes, abortBytes, payloadBytes, thread, sharedMemory, }: {
     signalBytes: number;
@@ -70,11 +61,11 @@ export declare const createProcessWorkerMemoryLayout: ({ signalBytes, abortBytes
     thread: number;
     sharedMemory: ResolvedProcessSharedMemorySettings;
 }) => ProcessWorkerMemoryLayout;
-export declare const serializeWorkerBootstrapData: (options: WorkerSettings) => WorkerSettings;
 export declare const toProcessWorkerBootPayload: (workerData: WorkerData, memory: ProcessWorkerMemoryLayout) => ProcessWorkerBootPayload;
 export declare const readProcessWorkerRuntime: (options: WorkerSettings | undefined) => ProcessWorkerRuntime;
 export declare const readProcessWorkerCommandPrefix: (options: WorkerSettings | undefined) => ProcessWorkerCommandPrefix | undefined;
 export declare const readProcessSharedMemorySettings: (options: WorkerSettings | undefined) => ResolvedProcessSharedMemorySettings;
+export declare const readProcessWorkerNodeMajor: (options: WorkerSettings | undefined) => number | undefined;
 export declare const createProcessWorkerNativeSignalNotifier: ({ processRuntime, signal, }: {
     processRuntime: ProcessWorkerRuntime | undefined;
     signal: Int32Array;
@@ -87,6 +78,5 @@ export declare const spawnProcessWorker: (options: {
     commandPrefix?: ProcessWorkerCommandPrefix;
     permission?: WorkerData["permission"];
 }) => SpawnedWorker & NodeWorkerLike;
-export declare const terminateWorkerQuietly: (worker: SpawnedWorker) => void;
 export declare const cleanupProcessWorkerMemoryQuietly: (memory: ProcessWorkerMemoryLayout | undefined) => void;
 export {};

package/src/runtime/process-worker.js

@@ -2,6 +2,7 @@ import { HEADER_SLOT_STRIDE_U32, LOCK_SECTOR_BYTE_LENGTH, LockBound, } from "../
 import { createByteCarpet, getHeaderBlockByteLength, makeSharedBufferRegion, } from "../memory/byte-carpet.js";
 import { RUNTIME } from "../common/runtime.js";
 import { debugHas } from "../debug/gate.js";
+import { toWorkerCompatExecArgv, } from "./worker-common.js";
 import { RUNTIME_POOL_DEPTH, RUNTIME_POOL_DEPTH_ENV, RUNTIME_PROCESS_WORKER_BOOT_ENV, RUNTIME_PROCESS_WORKER_BOOT_VERSION, RUNTIME_PROCESS_WORKER_ENV, } from "../common/worker-runtime.js";
 import { getNodeBuiltinModule, getNodeProcess } from "../common/node-compat.js";
 import { toSharedBufferRegion, } from "../common/shared-buffer-region.js";
@@ -20,51 +21,6 @@ const fileURLToPathCompat = (value) => {
     }
     return url.fileURLToPath(value);
 };
-const execFlagKey = (flag) => flag.split("=", 1)[0];
-const NODE_PERMISSION_EXEC_FLAGS = new Set([
-    "--permission",
-    "--experimental-permission",
-    "--allow-fs-read",
-    "--allow-fs-write",
-    "--allow-worker",
-    "--allow-child-process",
-    "--allow-net",
-    "--allow-addons",
-    "--allow-ffi",
-    "--allow-wasi",
-]);
-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 toWorkerSafeExecArgv = (flags) => {
-    if (!flags || flags.length === 0)
-        return undefined;
-    const filtered = flags.filter(isNodeWorkerSafeExecFlag);
-    if (filtered.length === 0)
-        return undefined;
-    const seen = new Set();
-    const deduped = [];
-    for (const flag of filtered) {
-        if (seen.has(flag))
-            continue;
-        seen.add(flag);
-        deduped.push(flag);
-    }
-    return deduped;
-};
-export const toWorkerCompatExecArgv = (flags) => {
-    const safe = toWorkerSafeExecArgv(flags);
-    if (!safe || safe.length === 0)
-        return undefined;
-    const compat = safe.filter((flag) => !isNodePermissionExecFlag(flag));
-    return compat.length > 0 ? compat : undefined;
-};
 const toProcessSharedMemorySize = (byteLength) => {
     if (!Number.isFinite(byteLength) || byteLength <= 0) {
         throw new RangeError("process shared memory byteLength must be positive");
@@ -118,19 +74,18 @@ const DENO_PROCESS_WORKER_INTERNAL_FLAGS = [
     `--allow-env=${DENO_PROCESS_WORKER_BOOT_ENV_ALLOW}`,
     "--allow-ffi",
 ];
-const nodeMajorVersion = () => {
-    const version = getNodeProcess()?.versions?.node ?? "";
-    const major = Number.parseInt(version.split(".", 1)[0] ?? "", 10);
-    return Number.isInteger(major) ? major : 0;
-};
-const nodeProcessWorkerUsesFfi = () => {
-    const major = nodeMajorVersion();
-    return major >= 26 && major % 2 === 0;
+const parseNodeMajorVersion = (version) => {
+    const match = /^v?(\d+)/.exec(String(version).trim());
+    if (match === null)
+        return undefined;
+    const major = Number.parseInt(match[1], 10);
+    return Number.isInteger(major) && major > 0 ? major : undefined;
 };
-const nodeProcessWorkerInternalExecArgv = () => {
+const nodeProcessWorkerUsesFfi = (nodeMajor) => nodeMajor !== undefined && nodeMajor >= 26 && nodeMajor % 2 === 0;
+const nodeProcessWorkerInternalExecArgv = (nodeMajor) => {
     return [
         "--no-warnings",
-        ...(nodeProcessWorkerUsesFfi()
+        ...(nodeProcessWorkerUsesFfi(nodeMajor)
             ? ["--experimental-ffi"]
             : ["--experimental-transform-types"]),
     ];
@@ -254,49 +209,6 @@ const toProcessWorkerWireLockBuffers = (lock, descriptor) => ({
     payload: toChildProcessSharedBufferMetadata(lock.payload, descriptor),
     payloadSector: toChildProcessSharedBufferMetadata(lock.payloadSector, descriptor),
 });
-const isPlainRecord = (value) => {
-    if (value === null || typeof value !== "object")
-        return false;
-    const prototype = Object.getPrototypeOf(value);
-    return prototype === Object.prototype || prototype === null;
-};
-const serializeWorkerBootstrapValue = (value, seen = new WeakMap()) => {
-    if (value instanceof ProcessSharedBuffer)
-        return value.toMetadata();
-    if (value === null || typeof value !== "object")
-        return value;
-    const existing = seen.get(value);
-    if (existing !== undefined)
-        return existing;
-    if (Array.isArray(value)) {
-        const out = [];
-        seen.set(value, out);
-        for (const item of value) {
-            out.push(serializeWorkerBootstrapValue(item, seen));
-        }
-        return out;
-    }
-    if (!isPlainRecord(value))
-        return value;
-    const out = {};
-    seen.set(value, out);
-    for (const [key, item] of Object.entries(value)) {
-        out[key] = serializeWorkerBootstrapValue(item, seen);
-    }
-    return out;
-};
-export const serializeWorkerBootstrapData = (options) => {
-    const bootstrap = options.bootstrap;
-    if (bootstrap === undefined || bootstrap.data === undefined)
-        return options;
-    return {
-        ...options,
-        bootstrap: {
-            ...bootstrap,
-            data: serializeWorkerBootstrapValue(bootstrap.data),
-        },
-    };
-};
 export const toProcessWorkerBootPayload = (workerData, memory) => ({
     version: RUNTIME_PROCESS_WORKER_BOOT_VERSION,
     workerData: {
@@ -417,10 +329,62 @@ const processWorkerNodeBinary = (commandPrefix) => {
             : undefined) ??
         DEFAULT_NODE_BINARY;
 };
-const processWorkerNodeExecArgv = (permission) => {
+const processWorkerNodeMajorCache = new Map();
+const resolveProcessWorkerNodeMajor = (commandPrefix) => {
+    const nodeProcess = getNodeProcess();
+    if (commandPrefix === undefined &&
+        nodeProcess !== undefined &&
+        nodeProcess?.env?.NODE_BINARY === undefined &&
+        RUNTIME === "node") {
+        return parseNodeMajorVersion(nodeProcess.versions?.node);
+    }
+    const nodeBinary = processWorkerNodeBinary(commandPrefix);
+    const cacheKey = JSON.stringify([commandPrefix ?? null, nodeBinary]);
+    if (processWorkerNodeMajorCache.has(cacheKey)) {
+        return processWorkerNodeMajorCache.get(cacheKey);
+    }
+    let major;
+    try {
+        const childProcess = getNodeBuiltinModule("node:child_process");
+        if (typeof childProcess?.spawnSync === "function") {
+            const command = commandPrefix?.[0] ?? nodeBinary;
+            const args = commandPrefix === undefined
+                ? ["--version"]
+                : [...commandPrefix.slice(1), nodeBinary, "--version"];
+            const probe = childProcess.spawnSync(command, args, {
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", "ignore"],
+                timeout: 2_000,
+                windowsHide: true,
+            });
+            if (probe.status === 0) {
+                major = parseNodeMajorVersion(probe.stdout);
+            }
+        }
+    }
+    catch {
+        // Unknown targets conservatively use the Node 22/24 addon transport.
+    }
+    processWorkerNodeMajorCache.set(cacheKey, major);
+    return major;
+};
+export const readProcessWorkerNodeMajor = (options) => resolveProcessWorkerNodeMajor(readProcessWorkerCommandPrefix(options));
+const nodeProcessWorkerFlagIsSupported = (flag, nodeMajor) => {
+    const key = flag.split("=", 1)[0];
+    if (key === "--experimental-ffi" || key === "--allow-ffi") {
+        return nodeProcessWorkerUsesFfi(nodeMajor);
+    }
+    if (key === "--allow-net") {
+        return nodeMajor !== undefined && nodeMajor >= 25;
+    }
+    return true;
+};
+const processWorkerNodeExecArgv = (permission, nodeMajor) => {
     const out = [];
     const seen = new Set();
     const add = (flag) => {
+        if (!nodeProcessWorkerFlagIsSupported(flag, nodeMajor))
+            return;
         if (seen.has(flag))
             return;
         seen.add(flag);
@@ -429,16 +393,17 @@ const processWorkerNodeExecArgv = (permission) => {
     for (const flag of toWorkerCompatExecArgv(getNodeProcess()?.execArgv) ?? []) {
         add(flag);
     }
-    for (const flag of nodeProcessWorkerInternalExecArgv())
+    for (const flag of nodeProcessWorkerInternalExecArgv(nodeMajor))
         add(flag);
     if (permission?.enabled === true && permission.unsafe !== true) {
         for (const flag of permission.node.flags)
             add(flag);
-        if (permission.netAll && nodeMajorVersion() >= 25)
+        if (permission.netAll && nodeMajor !== undefined && nodeMajor >= 25) {
             add("--allow-net");
+        }
         // Node process workers need one native transport capability regardless of
         // task permissions: addons on Node 22/24, node:ffi on supported Node 26+ LTS.
-        add(nodeProcessWorkerUsesFfi() ? "--allow-ffi" : "--allow-addons");
+        add(nodeProcessWorkerUsesFfi(nodeMajor) ? "--allow-ffi" : "--allow-addons");
     }
     return out;
 };
@@ -454,9 +419,10 @@ const processWorkerCommand = ({ processRuntime, workerUrl, bun, deno, commandPre
         ];
     }
     else if (processRuntime === "node") {
+        const nodeMajor = resolveProcessWorkerNodeMajor(commandPrefix);
         command = [
             processWorkerNodeBinary(commandPrefix),
-            ...processWorkerNodeExecArgv(permission),
+            ...processWorkerNodeExecArgv(permission, nodeMajor),
             workerPath,
         ];
     }
@@ -687,16 +653,6 @@ export const spawnProcessWorker = (options) => {
             throw new Error("process worker runtime is only available in Node, Deno, or Bun");
     }
 };
-export const terminateWorkerQuietly = (worker) => {
-    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?.();
-        void Promise.resolve(worker.terminate()).catch(() => { });
-    }
-    catch {
-    }
-};
 export const cleanupProcessWorkerMemoryQuietly = (memory) => {
     try {
         memory?.cleanup();

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

@@ -11,15 +11,29 @@ type CreateHostTxQueueArgs = {
     max?: number;
     lock: Lock2;
     returnLock: Lock2;
+    /**
+     * Extra return locks to drain into the same pending registry.
+     *
+     * Under work stealing the host publishes into one shared submit lock and any
+     * worker may claim the task, so the response comes back on whichever lane
+     * executed it. Task IDs index this queue's `queue` array, which is
+     * pool-global, so every lane's `resolveHost` can settle into it — the
+     * stealing worker owns the response and the host demultiplexes by ID.
+     *
+     * 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;
 };
-export declare function createHostTxQueue({ max, lock, returnLock, releaseBufferReferenceReturn, abortSignals, now, }: CreateHostTxQueueArgs): {
+type ReturnHooks = ((token: bigint) => void) | BufferReferenceReturnHooks;
+export declare function createHostTxQueue({ max, lock, returnLock, extraReturnLocks, releaseBufferReferenceReturn, abortSignals, now, }: CreateHostTxQueueArgs): {
     rejectAll: (reason: string) => void;
     hasPendingFrames: () => boolean;
     txIdle: () => boolean;
     completeFrame: () => number;
+    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

@@ -14,7 +14,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, releaseBufferReferenceReturn, abortSignals, now, }) {
+export function createHostTxQueue({ max, lock, returnLock, extraReturnLocks, releaseBufferReferenceReturn, abortSignals, now, }) {
     const PLACE_HOLDER = (_) => {
         throw ("UNREACHABLE FROM PLACE HOLDER (main)");
     };
@@ -37,22 +37,53 @@ export function createHostTxQueue({ max, lock, returnLock, releaseBufferReferenc
     let inUsed = 0 | 0;
     const resetSignal = abortSignals?.resetSignal;
     const nowTime = now ?? p_now;
-    const resolveReturn = returnLock.resolveHost({
+    const onReturnResolved = (task) => {
+        inUsed = (inUsed - 1) | 0;
+        resetTaskLocalFlags(task);
+        runTaskFinalizers(task);
+        task.value = null;
+        task.resolve = PLACE_HOLDER;
+        task.reject = PLACE_HOLDER;
+        freePush(task[TaskIndex.ID]);
+    };
+    const returnResolvers = [
+        returnLock,
+        ...(extraReturnLocks ?? []),
+    ].map((each) => each.resolveHost({
         queue,
         activeRejectPlaceholder: PLACE_HOLDER,
-        onResolved: (task) => {
-            inUsed = (inUsed - 1) | 0;
-            resetTaskLocalFlags(task);
-            runTaskFinalizers(task);
-            task.value = null;
-            task.resolve = PLACE_HOLDER;
-            task.reject = PLACE_HOLDER;
-            freePush(task[TaskIndex.ID]);
-        },
-    });
-    const completeFrame = releaseBufferReferenceReturn === undefined
-        ? resolveReturn
-        : () => withBufferReferenceReturnReleaser(releaseBufferReferenceReturn, resolveReturn);
+        onResolved: onReturnResolved,
+    }));
+    // 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 completeFrame = returnResolvers.length === 1
+        ? releaseBufferReferenceReturn === undefined
+            ? returnResolvers[0]
+            : () => withBufferReferenceReturnReleaser(releaseBufferReferenceReturn, returnResolvers[0])
+        : () => {
+            let resolved = 0 | 0;
+            for (let i = 0; i < returnResolvers.length; i++) {
+                resolved = (resolved + resolveReturnAt(i)) | 0;
+            }
+            return resolved;
+        };
     const hasActiveTasks = () => {
         const count = (inUsed - getPendingPromiseCount()) | 0;
         return count > 0;
@@ -85,6 +116,12 @@ export function createHostTxQueue({ max, lock, returnLock, releaseBufferReferenc
         hasPendingFrames,
         txIdle,
         completeFrame,
+        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

@@ -0,0 +1,13 @@
+import type { WorkerSettings } from "../types.js";
+export type SpawnedWorker = {
+    terminate: () => unknown;
+    unref?: () => unknown;
+    postMessage?: (message: unknown) => void;
+};
+export type NodeWorkerLike = {
+    on?: (event: "error" | "exit" | "message", listener: (...args: unknown[]) => void) => void;
+};
+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) => void;

package/src/runtime/worker-common.js

@@ -0,0 +1,102 @@
+// Worker helpers shared by every worker mode. Kept out of `process-worker.ts`
+// so the thread and web-worker paths do not pull the process-worker module —
+// and, through it, the whole native connections tree — into their bundles.
+import { ProcessSharedBuffer } from "../connections/process-shared-buffer.js";
+const execFlagKey = (flag) => flag.split("=", 1)[0];
+const NODE_PERMISSION_EXEC_FLAGS = new Set([
+    "--permission",
+    "--experimental-permission",
+    "--allow-fs-read",
+    "--allow-fs-write",
+    "--allow-worker",
+    "--allow-child-process",
+    "--allow-net",
+    "--allow-addons",
+    "--allow-ffi",
+    "--allow-wasi",
+]);
+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 toWorkerSafeExecArgv = (flags) => {
+    if (!flags || flags.length === 0)
+        return undefined;
+    const filtered = flags.filter(isNodeWorkerSafeExecFlag);
+    if (filtered.length === 0)
+        return undefined;
+    const seen = new Set();
+    const deduped = [];
+    for (const flag of filtered) {
+        if (seen.has(flag))
+            continue;
+        seen.add(flag);
+        deduped.push(flag);
+    }
+    return deduped;
+};
+export const toWorkerCompatExecArgv = (flags) => {
+    const safe = toWorkerSafeExecArgv(flags);
+    if (!safe || safe.length === 0)
+        return undefined;
+    const compat = safe.filter((flag) => !isNodePermissionExecFlag(flag));
+    return compat.length > 0 ? compat : undefined;
+};
+const isPlainRecord = (value) => {
+    if (value === null || typeof value !== "object")
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+};
+const serializeWorkerBootstrapValue = (value, seen = new WeakMap()) => {
+    if (value instanceof ProcessSharedBuffer)
+        return value.toMetadata();
+    if (value === null || typeof value !== "object")
+        return value;
+    const existing = seen.get(value);
+    if (existing !== undefined)
+        return existing;
+    if (Array.isArray(value)) {
+        const out = [];
+        seen.set(value, out);
+        for (const item of value) {
+            out.push(serializeWorkerBootstrapValue(item, seen));
+        }
+        return out;
+    }
+    if (!isPlainRecord(value))
+        return value;
+    const out = {};
+    seen.set(value, out);
+    for (const [key, item] of Object.entries(value)) {
+        out[key] = serializeWorkerBootstrapValue(item, seen);
+    }
+    return out;
+};
+export const serializeWorkerBootstrapData = (options) => {
+    const bootstrap = options.bootstrap;
+    if (bootstrap === undefined || bootstrap.data === undefined)
+        return options;
+    return {
+        ...options,
+        bootstrap: {
+            ...bootstrap,
+            data: serializeWorkerBootstrapValue(bootstrap.data),
+        },
+    };
+};
+export const terminateWorkerQuietly = (worker) => {
+    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?.();
+        void Promise.resolve(worker.terminate()).catch(() => { });
+    }
+    catch {
+    }
+};

package/src/types.d.ts

@@ -34,6 +34,17 @@ type WorkerData = {
     payloadConfig?: PayloadBufferOptions;
     bufferReferenceReturn?: "copy" | "borrow";
     permission?: ResolvedPermissionProtocol;
+    /**
+     * 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.
+     */
+    steal?: {
+        consumers: number;
+        consumerId: number;
+        regionLanes: number;
+    };
 };
 type UnsafeOptions = {
     /**
@@ -343,11 +354,38 @@ type DispatcherSettings = {
      * - `"serial-channel"`: each worker keeps its own dispatcher check state, but
      *   one shared channel runs all lane checks from first to last.
      *
-     * Experimental default: `"per-thread"` on Bun or with one worker, otherwise
-     * `"serial-channel"` for multi-worker Node/Deno pools. Can also be forced
-     * with the `KNITTING_DISPATCHER` env var (`serial-channel` or `per-thread`).
+     * Used by private-lane pools. Its experimental default is `"per-thread"` on
+     * Bun or with one worker, otherwise `"serial-channel"` for multi-worker
+     * Node/Deno pools. Selecting it explicitly keeps private lanes unless
+     * `steal: true` is also explicit. Can also be forced with the
+     * `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 multi-worker thread pools unless a balancer or
+     * private-lane dispatcher was explicitly selected. One-worker pools,
+     * inliners, compiled/Porffor workers, process workers, and pools above the
+     * current 31-claimant protocol limit retain their existing transport.
+     * Explicitly requesting `true` with process workers is rejected because
+     * their transport uses separately mapped process-shared memory. Set `false`
+     * (or `KNITTING_STEAL=0`) to opt out; `KNITTING_STEAL=1` explicitly opts in
+     * and overrides a balancer/dispatcher selection.
+     */
+    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.
+     */
+    stealRegionLanes?: number;
 };
 type CreatePool = {
     /** Number of workers. Default: 1. */

package/src/worker/loop.js

@@ -73,7 +73,7 @@ export const workerMainLoop = async (startupData) => {
     installTerminationGuard();
     installUnhandledRejectionSilencer();
     installPerformanceNowGuard();
-    const { debug, sab, thread, startAt, workerOptions, lock, returnLock, abortSignalSAB, abortSignalMax, payloadConfig, bufferReferenceReturn, permission, totalNumberOfThread, list, ids, names, at, } = startupData;
+    const { debug, sab, thread, startAt, workerOptions, lock, returnLock, abortSignalSAB, abortSignalMax, payloadConfig, bufferReferenceReturn, permission, totalNumberOfThread, list, ids, names, at, steal, } = startupData;
     scrubWorkerDataSensitiveBuffers(startupData);
     assertWorkerSharedMemoryBootData({ sab, lock, returnLock });
     const debugNamespaces = resolveDebugNamespaces(debug);
@@ -105,6 +105,11 @@ export const workerMainLoop = async (startupData) => {
         payloadConfig,
         textCompat: lock.textCompat,
         processBoundary: RUNTIME_IS_PROCESS_WORKER,
+        // Under stealing the request region is shared, so decode() becomes a
+        // region-Dekker claim against the other endpoints.
+        consumers: steal?.consumers,
+        consumerId: steal?.consumerId,
+        regionLanes: steal?.regionLanes,
     });
     const returnLockState = lock2({
         headers: returnLock.headers,
@@ -163,6 +168,7 @@ export const workerMainLoop = async (startupData) => {
         returnLock: returnLockState,
         borrowReturnedBufferReferences: bufferReferenceReturn === "borrow",
         hasAborted: abortSignals?.hasAborted,
+        stealing: steal !== undefined,
     });
     installBufferReferenceReleaseListener(releaseReturnedBufferReference);
     a_store(rxStatus, 0, 1);
@@ -175,6 +181,7 @@ export const workerMainLoop = async (startupData) => {
         pauseInNanoseconds: timers?.pauseNanoseconds,
         enqueueLock,
         write: () => hasCompleted() ? writeBatch(WRITE_MAX) : 0,
+        flushBeforeClaim: steal !== undefined,
         nativeWaitU32,
         useSharedMemoryWait: !(RUNTIME_IS_PROCESS_WORKER &&
             RUNTIME === "node" &&
@@ -250,15 +257,30 @@ export const workerMainLoop = async (startupData) => {
             pauseUntil(value, spinMicroseconds, parkMs);
         }
         : pauseUntil;
+    const flushBeforeClaim = steal !== undefined;
     const loop = () => {
         isInMacro = false;
         let progressed = true;
         let awaiting = 0;
         while (true) {
-            progressed = _enqueueLock();
-            if (_hasCompleted()) {
-                if (_writeBatch(WRITE_MAX) > 0)
-                    progressed = 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.
+                if (_hasCompleted()) {
+                    if (_writeBatch(WRITE_MAX) > 0)
+                        progressed = true;
+                }
+                progressed = _enqueueLock() || progressed;
+            }
+            else {
+                progressed = _enqueueLock();
+                if (_hasCompleted()) {
+                    if (_writeBatch(WRITE_MAX) > 0)
+                        progressed = true;
+                }
             }
             _drainReturnReleases();
             if (_hasPending()) {