knitting 0.1.56 → 0.1.61

package/src/runtime/process-worker.js

@@ -1,8 +1,8 @@
-import { fileURLToPath as fileURLToPathCompat } from "node:url";
 import { HEADER_SLOT_STRIDE_U32, LOCK_SECTOR_BYTE_LENGTH, LockBound, } from "../memory/lock.js";
 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";
@@ -12,47 +12,14 @@ import { FileDescriptor, ProcessSharedBuffer, } from "../connections/index.js";
 import { createNodeConnectionPrimitives, loadNodeFutexAddon, } from "../connections/node.js";
 import { loadNodeNativeAddon } from "../connections/node-addons.js";
 import { detectPosixPlatform } from "../connections/posix.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-addons",
-    "--allow-wasi",
-]);
-const NODE_WORKER_SAFE_EXEC_FLAGS = new Set([
-    "--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);
+// `node:url` resolved lazily so this module evaluates on runtimes without it
+// (e.g. Andromeda); process workers aren't used there, so it never runs.
+const fileURLToPathCompat = (value) => {
+    const url = getNodeBuiltinModule("node:url");
+    if (url === undefined) {
+        throw new Error("node:url is not available in this runtime");
     }
-    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;
+    return url.fileURLToPath(value);
 };
 const toProcessSharedMemorySize = (byteLength) => {
     if (!Number.isFinite(byteLength) || byteLength <= 0) {
@@ -107,10 +74,22 @@ const DENO_PROCESS_WORKER_INTERNAL_FLAGS = [
     `--allow-env=${DENO_PROCESS_WORKER_BOOT_ENV_ALLOW}`,
     "--allow-ffi",
 ];
-const NODE_PROCESS_WORKER_EXEC_ARGV = [
-    "--no-warnings",
-    "--experimental-transform-types",
-];
+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 nodeProcessWorkerUsesFfi = (nodeMajor) => nodeMajor !== undefined && nodeMajor >= 26 && nodeMajor % 2 === 0;
+const nodeProcessWorkerInternalExecArgv = (nodeMajor) => {
+    return [
+        "--no-warnings",
+        ...(nodeProcessWorkerUsesFfi(nodeMajor)
+            ? ["--experimental-ffi"]
+            : ["--experimental-transform-types"]),
+    ];
+};
 const getProcessWorkerSharedMemoryPrimitives = () => {
     switch (RUNTIME) {
         case "bun":
@@ -230,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: {
@@ -393,10 +329,62 @@ const processWorkerNodeBinary = (commandPrefix) => {
             : undefined) ??
         DEFAULT_NODE_BINARY;
 };
-const processWorkerNodeExecArgv = () => {
+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);
@@ -405,8 +393,18 @@ const processWorkerNodeExecArgv = () => {
     for (const flag of toWorkerCompatExecArgv(getNodeProcess()?.execArgv) ?? []) {
         add(flag);
     }
-    for (const flag of NODE_PROCESS_WORKER_EXEC_ARGV)
+    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 && 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(nodeMajor) ? "--allow-ffi" : "--allow-addons");
+    }
     return out;
 };
 const processWorkerCommand = ({ processRuntime, workerUrl, bun, deno, commandPrefix, permission, }) => {
@@ -421,9 +419,10 @@ const processWorkerCommand = ({ processRuntime, workerUrl, bun, deno, commandPre
         ];
     }
     else if (processRuntime === "node") {
+        const nodeMajor = resolveProcessWorkerNodeMajor(commandPrefix);
         command = [
             processWorkerNodeBinary(commandPrefix),
-            ...processWorkerNodeExecArgv(),
+            ...processWorkerNodeExecArgv(permission, nodeMajor),
             workerPath,
         ];
     }
@@ -654,20 +653,17 @@ 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();
     }
     catch {
     }
+    finally {
+        try {
+            memory?.mapping.close?.();
+        }
+        catch {
+        }
+    }
 };

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

@@ -1,6 +1,8 @@
+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;
@@ -9,15 +11,29 @@ type CreateHostTxQueueArgs = {
     max?: number;
     lock: Lock2;
     returnLock: Lock2;
-    releaseBufferReferenceReturn?: (token: bigint) => void;
+    /**
+     * 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

@@ -1,7 +1,10 @@
+// Side-effect import: registers the payload codec (cycle break for Andromeda;
+// see lock.ts), ensuring registration before any lock2() call.
+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";
+import { withBufferReferenceReturnReleaser, } from "../connections/buffer-reference.js";
 const SLOT_INDEX_MASK = 31;
 const SLOT_META_MASK = 0x07ffffff;
 const SLOT_META_SHIFT = 5;
@@ -11,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)");
     };
@@ -34,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;
@@ -82,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 = {
     /**
@@ -83,6 +94,7 @@ type AbortSignalConfig = {
 type AbortSignalOption = true | AbortSignalConfig | undefined;
 type AbortSignalMethods<AS extends AbortSignalOption> = AS extends undefined ? never : {
     hasAborted: () => boolean;
+    now: () => number;
 };
 type AbortSignalToolkit<AS extends AbortSignalOption> = AbortSignalMethods<AS>;
 type TaskFn<A extends TaskInput, B extends Args, AS extends AbortSignalOption = undefined> = BivariantCallback<AS extends undefined ? [NoBlob<Awaited<A>>] : [NoBlob<Awaited<A>>, AbortSignalToolkit<AS>], MaybePromise<NoBlob<B>>>;
@@ -220,6 +232,41 @@ type WorkerBootstrapOptions<Data = unknown> = {
      */
     data?: Data;
 };
+/** Native worker artifact and on-demand compiler settings. */
+type CompiledWorkerOptions = {
+    /**
+     * Native executable path. Relative paths resolve from the createPool caller.
+     * Defaults to the task module path with its extension replaced by `.knt`.
+     */
+    artifact?: string;
+    /**
+     * Versioned metadata sidecar. Defaults to `<artifact>.json`.
+     */
+    manifest?: string;
+    /**
+     * Build a missing/incompatible artifact, or use `"always"` to rebuild once
+     * whenever a pool is created. Defaults to true.
+     */
+    build?: boolean | "always";
+    /**
+     * Porffor main executable or checkout. Defaults to PORFFOR_MAIN/PORF, then
+     * `porf` on PATH; a pinned compiler is cached locally when none is present.
+     */
+    compiler?: string;
+};
+type CompiledWorkerSource = string | URL | {
+    readonly importedFrom: string;
+};
+type CompiledWorkerCheck = {
+    /** True only when the executable and compatible manifest both validate. */
+    compiled: boolean;
+    artifact: string;
+    manifest: string;
+    reason?: string;
+    compiler?: string;
+    protocol?: string;
+    tasks?: readonly string[];
+};
 type WorkerSettings = {
     resolveAfterFinishingAll?: true;
     /**
@@ -230,13 +277,18 @@ type WorkerSettings = {
     /**
      * Experimental worker runtime.
      * "thread" uses Worker/worker_threads. "process" spawns another JavaScript
-     * runtime, useful for process isolation, bwrap, and containers.
+     * runtime, useful for process isolation, bwrap, and containers. "compiled"
+     * validates and runs a `.knt` native worker, building it on first use.
      */
-    runtime?: "thread" | "process";
+    runtime?: "thread" | "process" | "compiled";
+    /** Artifact settings used when runtime is "compiled". */
+    compiled?: CompiledWorkerOptions;
     /**
-     * Runtime executable to use when runtime is "process". Defaults to "deno".
+     * Runtime executable for process workers. Standalone `"porffor"` selects the
+     * compiled backend and rebuilds once per pool; with `runtime: "compiled"` it
+     * reuses the validated artifact.
      */
-    processRuntime?: "bun" | "deno" | "node";
+    processRuntime?: "bun" | "deno" | "node" | "porffor";
     /**
      * Command argv to prepend before the process worker runtime command.
      * Useful for wrappers such as systemd-run, cgexec, nice, taskset, or
@@ -302,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. */
@@ -351,7 +430,8 @@ type CreatePool = {
     debug?: DebugOptions;
     source?: string;
 };
-export type { AbortSignalConfig as AbortSignalConfig, AbortSignalMethods as AbortSignalMethods, AbortSignalOption as AbortSignalOption, AbortSignalToolkit as AbortSignalToolkit, Args as Args, Balancer as Balancer, BalancerStrategy as BalancerStrategy, Composed as Composed, ComposedWithKey as ComposedWithKey, CreateContext as CreateContext, CreatePool as CreatePool, DebugNamespace as DebugNamespace, DebugOptions as DebugOptions, DispatcherSettings as DispatcherSettings, Envelope as Envelope, EnvelopeBody as EnvelopeBody, EnvelopeHeader as EnvelopeHeader, External as External, FixPoint as FixPoint, FunctionMapType as FunctionMapType, ImportTaskOptions as ImportTaskOptions, Inliner as Inliner, LockBuffers as LockBuffers, LockBufferTextCompat as LockBufferTextCompat, MaybePromise as MaybePromise, PayloadBufferMode as PayloadBufferMode, PayloadBufferOptions as PayloadBufferOptions, PermissionProtocol as PermissionProtocol, PermissionProtocolInput as PermissionProtocolInput, Pool as Pool, ProcessSharedMemoryMode as ProcessSharedMemoryMode, ProcessSharedMemorySettings as ProcessSharedMemorySettings, ResolvedPermissionProtocol as ResolvedPermissionProtocol, ReturnFixed as ReturnFixed, SecondPart as SecondPart, SharedBufferRegion as SharedBufferRegion, SharedBufferSource as SharedBufferSource, SharedBufferTextCompat as SharedBufferTextCompat, SingleTaskPool as SingleTaskPool, TaskFn as TaskFn, TaskInput as TaskInput, tasks as tasks, TaskTimeout as TaskTimeout, ValidInput as ValidInput, WorkerBootstrapContext as WorkerBootstrapContext, WorkerBootstrapFunction as WorkerBootstrapFunction, WorkerBootstrapOptions as WorkerBootstrapOptions, WorkerCall as WorkerCall, WorkerContext as WorkerContext, WorkerData as WorkerData, WorkerInvoke as WorkerInvoke, WorkerSettings as WorkerSettings, WorkerTimers as WorkerTimers, };
-export type { Task as Task } from "./memory/lock.js";
+export type { AbortSignalConfig as AbortSignalConfig, AbortSignalMethods as AbortSignalMethods, AbortSignalOption as AbortSignalOption, AbortSignalToolkit as AbortSignalToolkit, Args as Args, Balancer as Balancer, BalancerStrategy as BalancerStrategy, CompiledWorkerCheck as CompiledWorkerCheck, CompiledWorkerOptions as CompiledWorkerOptions, CompiledWorkerSource as CompiledWorkerSource, Composed as Composed, ComposedWithKey as ComposedWithKey, CreateContext as CreateContext, CreatePool as CreatePool, DebugNamespace as DebugNamespace, DebugOptions as DebugOptions, DispatcherSettings as DispatcherSettings, Envelope as Envelope, EnvelopeBody as EnvelopeBody, EnvelopeHeader as EnvelopeHeader, External as External, FixPoint as FixPoint, FunctionMapType as FunctionMapType, ImportTaskOptions as ImportTaskOptions, Inliner as Inliner, LockBuffers as LockBuffers, LockBufferTextCompat as LockBufferTextCompat, MaybePromise as MaybePromise, PayloadBufferMode as PayloadBufferMode, PayloadBufferOptions as PayloadBufferOptions, PermissionProtocol as PermissionProtocol, PermissionProtocolInput as PermissionProtocolInput, Pool as Pool, ProcessSharedMemoryMode as ProcessSharedMemoryMode, ProcessSharedMemorySettings as ProcessSharedMemorySettings, ResolvedPermissionProtocol as ResolvedPermissionProtocol, ReturnFixed as ReturnFixed, SecondPart as SecondPart, SharedBufferRegion as SharedBufferRegion, SharedBufferSource as SharedBufferSource, SharedBufferTextCompat as SharedBufferTextCompat, SingleTaskPool as SingleTaskPool, TaskFn as TaskFn, TaskInput as TaskInput, tasks as tasks, TaskTimeout as TaskTimeout, ValidInput as ValidInput, WorkerBootstrapContext as WorkerBootstrapContext, WorkerBootstrapFunction as WorkerBootstrapFunction, WorkerBootstrapOptions as WorkerBootstrapOptions, WorkerCall as WorkerCall, WorkerContext as WorkerContext, WorkerData as WorkerData, WorkerInvoke as WorkerInvoke, WorkerSettings as WorkerSettings, WorkerTimers as WorkerTimers, };
+import type { Task as TaskType } from "./memory/lock.js";
 export { LockBound as LockBound, PayloadBuffer as PayloadBuffer, PayloadSignal as PayloadSignal, TaskIndex as TaskIndex, } from "./memory/lock.js";
+export type Task = TaskType;
 export type { RegisterMalloc as RegisterMalloc } from "./memory/regionRegistry.js";