knitting 0.1.52 → 0.1.54

package/src/debug/handle.js

@@ -0,0 +1,48 @@
+/**
+ * Worker-side debug handle. Lazily imported (see {@link ./gate.ts}) only when
+ * `KNITTING_DEBUG` names at least one namespace, so neither this code nor the
+ * baseline snapshot it takes exists when debug is off.
+ *
+ * Diagnostics go to stderr so they never corrupt a worker's stdout, and every
+ * line is tagged with the worker id, runtime, and a clock relative to when this
+ * worker's debug initialised. The clock is worker-local on purpose: a main-thread
+ * timestamp can't be compared against `performance.now()` here because the time
+ * origins differ across the thread/process boundary (it would read negative).
+ */
+import { describeGlobalKey, diffGlobals, snapshotGlobals, } from "./env-diff.js";
+export const initDebug = ({ name, runtime, namespaces }) => {
+    const all = namespaces.has("*");
+    const enabled = (namespace) => all || namespaces.has(namespace);
+    const base = performance.now();
+    const tag = `${name}·${runtime}`;
+    const log = (namespace, message) => {
+        if (!enabled(namespace))
+            return;
+        const elapsed = (performance.now() - base).toFixed(1);
+        console.error(`[${tag}·+${elapsed}ms] ${namespace}: ${message}`);
+    };
+    // Baseline for the environment diff, taken the moment debug initialises:
+    // before worker bootstrap and before any task module is imported. Only paid
+    // when `globals` tracing is actually on.
+    let previous = enabled("globals")
+        ? snapshotGlobals()
+        : undefined;
+    const envPhase = (label) => {
+        if (previous === undefined)
+            return;
+        const current = snapshotGlobals();
+        const { added, removed } = diffGlobals(previous, current);
+        previous = current;
+        if (added.length === 0 && removed.length === 0) {
+            log("globals", `${label}: no new globals`);
+            return;
+        }
+        if (added.length > 0) {
+            log("globals", `${label} +${added.length}: ${added.map(describeGlobalKey).join("  ")}`);
+        }
+        if (removed.length > 0) {
+            log("globals", `${label} -${removed.length}: ${removed.map(String).join("  ")}`);
+        }
+    };
+    return { enabled, log, envPhase };
+};

package/src/ipc/transport/shared-memory.d.ts

@@ -1,6 +1,5 @@
 export type SignalArguments = ReturnType<typeof createSharedMemoryTransport>;
 import { type SharedBufferSource } from "../../common/shared-buffer-region.js";
-import { type DebugOptions } from "../../types.js";
 export declare const TRANSPORT_SIGNAL_BYTES: number;
 export type Sab = {
     size?: number;
@@ -10,11 +9,10 @@ type SignalForWorker = {
     sabObject?: Sab;
     isMain: boolean;
     thread: number;
-    debug?: DebugOptions;
     startTime?: number;
 };
 export declare const createSharedMemoryTransport: ({ sabObject, isMain, startTime }: SignalForWorker) => {
-    sab: import("../../types.js").SharedBufferRegion;
+    sab: import("../../common/shared-buffer-region.js").SharedBufferRegion;
     op: Int32Array<import("../../common/shared-buffer-region.js").SharedBuffer>;
     startAt: number;
     opView: Int32Array<import("../../common/shared-buffer-region.js").SharedBuffer>;

package/src/memory/payload-config.d.ts

@@ -1,11 +1,20 @@
 import { type SharedBufferSource } from "../common/shared-buffer-region.js";
 export declare const PAYLOAD_DEFAULT_MAX_BYTE_LENGTH: number;
 export declare const PAYLOAD_DEFAULT_INITIAL_BYTES: number;
+/** Payload backing mode. Growable uses SAB growth when the runtime supports it. */
 export type PayloadBufferMode = "growable" | "fixed";
 export type PayloadBufferOptions = {
+    /** Shared payload buffer mode. Defaults to growable when available. */
     mode?: PayloadBufferMode;
+    /** Initial shared payload bytes per direction. Defaults to 4 MiB when growable. */
     payloadInitialBytes?: number;
+    /** Shared payload growth cap. Defaults to 64 MiB. */
     payloadMaxByteLength?: number;
+    /**
+     * Max dynamic payload bytes for one call. Defaults to `payloadMaxByteLength >> 3`
+     * (about 8 MiB by default) and must stay `<= payloadMaxByteLength >> 3`.
+     * Over-cap payloads reject with `KNT_ERROR_3`.
+     */
     maxPayloadBytes?: number;
 };
 export type ResolvedPayloadBufferOptions = {

package/src/permission/protocol.d.ts

@@ -163,4 +163,4 @@ export declare const resolvePermissionProtocol: ({ permission, modules, }: {
     modules?: string[];
 }) => ResolvedPermissionProtocol | undefined;
 export declare const toRuntimePermissionFlags: (protocol: ResolvedPermissionProtocol | undefined) => string[];
-export type { PermissionPath, PermissionMode, PermissionLegacyMode, SysApiName, NodePermissionSettings, DenoPermissionSettings, PermissionEnvironment, PermissionProtocol, PermissionProtocolInput, ResolvedPermissionProtocol, };
+export type { DenoPermissionSettings, NodePermissionSettings, PermissionEnvironment, PermissionLegacyMode, PermissionMode, PermissionPath, PermissionProtocol, PermissionProtocolInput, ResolvedPermissionProtocol, SysApiName, };

package/src/permission/protocol.js

@@ -107,11 +107,14 @@ const normalizeSysApiList = (values) => {
     return out;
 };
 const hasOwn = (value, key) => Object.prototype.hasOwnProperty.call(value, key);
-const normalizeProtocolInput = (input) => !input ? undefined : (typeof input === "string" ? { mode: input } : input);
+const normalizeProtocolInput = (input) => !input
+    ? undefined
+    : (typeof input === "string" ? { mode: input } : input);
 const isWindows = () => {
     const nodeProcess = getNodeProcess();
-    if (typeof nodeProcess?.platform === "string")
+    if (typeof nodeProcess?.platform === "string") {
         return nodeProcess.platform === "win32";
+    }
     const g = globalThis;
     return g.Deno?.build?.os === "windows";
 };
@@ -146,7 +149,8 @@ const getHome = () => {
     }
     const g = globalThis;
     try {
-        const home = g.Deno?.env?.get?.("HOME") ?? g.Deno?.env?.get?.("USERPROFILE");
+        const home = g.Deno?.env?.get?.("HOME") ??
+            g.Deno?.env?.get?.("USERPROFILE");
         if (typeof home === "string" && home.length > 0)
             return home;
     }
@@ -198,7 +202,11 @@ const toPathList = (values, cwd, home) => {
 };
 const toUniquePathList = (values, cwd, home) => normalizeList(toPathList(values, cwd, home));
 const toEnvFiles = (input, cwd, home) => {
-    const values = Array.isArray(input) ? input : input ? [input] : [DEFAULT_ENV_FILE];
+    const values = Array.isArray(input)
+        ? input
+        : input
+            ? [input]
+            : [DEFAULT_ENV_FILE];
     return toUniquePathList(values, cwd, home);
 };
 const rawRealpathSync = realpathSyncCompat.native ?? realpathSyncCompat;
@@ -212,7 +220,8 @@ const isPathWithin = (base, candidate) => {
     const canonicalBase = toCanonicalPath(base);
     const canonicalCandidate = toCanonicalPath(candidate);
     const relative = pathRelative(canonicalBase, canonicalCandidate);
-    return relative === "" || (!relative.startsWith("..") && !pathIsAbsolute(relative));
+    return relative === "" ||
+        (!relative.startsWith("..") && !pathIsAbsolute(relative));
 };
 const defaultSensitiveProjectAndHomePaths = (cwd, home) => {
     const projectSensitive = DEFAULT_DENY_RELATIVE.map((entry) => pathResolve(cwd, entry));
@@ -343,6 +352,13 @@ const toDenoFlags = ({ read, readAll, write, writeAll, denyRead, denyWrite, net,
         flags.push(`--deny-env=${envDeny.join(",")}`);
     }
     for (const file of envFiles) {
+        try {
+            if (!existsSyncCompat(file))
+                continue;
+        }
+        catch {
+            continue;
+        }
         flags.push(`--env-file=${file}`);
     }
     if (runAll) {
@@ -476,9 +492,7 @@ export const resolvePermissionProtocol = ({ permission, modules, }) => {
     const configuredRead = readAll
         ? []
         : toPathList(Array.isArray(input.read) ? input.read : undefined, cwd, home);
-    const configuredWrite = writeAll
-        ? []
-        : toPathList(Array.isArray(input.write) ? input.write : undefined, cwd, home);
+    const configuredWrite = writeAll ? [] : toPathList(Array.isArray(input.write) ? input.write : undefined, cwd, home);
     const resolvedRead = readAll
         ? []
         : hasExplicitRead
@@ -501,19 +515,17 @@ export const resolvePermissionProtocol = ({ permission, modules, }) => {
         : normalizeStringList(Array.isArray(input.net) ? input.net : []);
     const denyNet = normalizeStringList(input.denyNet);
     const allowImportAll = input.allowImport === true;
-    const allowImport = allowImportAll
-        ? []
-        : normalizeStringList(Array.isArray(input.allowImport)
-            ? input.allowImport
-            : [...DEFAULT_ALLOW_IMPORT_HOSTS]);
+    const allowImport = allowImportAll ? [] : normalizeStringList(Array.isArray(input.allowImport)
+        ? input.allowImport
+        : [...DEFAULT_ALLOW_IMPORT_HOSTS]);
     const envAllowAll = input.env?.allow === true;
-    const envAllow = envAllowAll
-        ? []
-        : normalizeStringList(Array.isArray(input.env?.allow) ? input.env.allow : []);
+    const envAllow = envAllowAll ? [] : normalizeStringList(Array.isArray(input.env?.allow) ? input.env.allow : []);
     const envDeny = normalizeStringList(input.env?.deny);
     const legacyRunEnabled = input.node?.allowChildProcess === true ||
         input.deno?.allowRun === true;
-    const runSource = hasOwn(input, "run") ? input.run : (legacyRunEnabled ? true : []);
+    const runSource = hasOwn(input, "run")
+        ? input.run
+        : (legacyRunEnabled ? true : []);
     const runAll = runSource === true;
     const run = runAll
         ? []
@@ -526,9 +538,7 @@ export const resolvePermissionProtocol = ({ permission, modules, }) => {
         ? input.ffi
         : (input.node?.allowAddons === true ? true : false);
     const ffiAll = ffiSource === true;
-    const ffi = ffiAll
-        ? []
-        : toUniquePathList(Array.isArray(ffiSource) ? ffiSource : undefined, cwd, home);
+    const ffi = ffiAll ? [] : toUniquePathList(Array.isArray(ffiSource) ? ffiSource : undefined, cwd, home);
     const denyFfi = toUniquePathList(input.denyFfi, cwd, home);
     const sysSource = input.sys;
     const sysAll = sysSource === true;

package/src/runtime/dispatcher.d.ts

@@ -15,6 +15,11 @@ export declare const hostDispatcherLoop: ({ signalBox: { opView, txStatus, rxSta
         rerun: boolean;
     };
 };
+type CheckWithState = (() => void) & {
+    isRunning: boolean;
+    rerun: boolean;
+};
+export type DispatcherCheck = CheckWithState;
 export declare class ChannelHandler {
     #private;
     channel: RuntimeMessageChannelLike;
@@ -32,3 +37,4 @@ export declare class ChannelHandler {
      */
     close(): void;
 }
+export {};

package/src/runtime/pool.d.ts

@@ -1,10 +1,11 @@
 import { type ProcessSharedMemoryBacking } from "./process-worker.js";
 import { type Sab } from "../ipc/transport/shared-memory.js";
+import { ChannelHandler, type DispatcherCheck } from "./dispatcher.js";
 import { lock2 } from "../memory/lock.js";
 import type { DebugOptions, DispatcherSettings, WorkerContext, WorkerData, WorkerSettings } from "../types.js";
 import "../worker/loop.js";
 import { type PayloadBufferOptions } from "../memory/payload-config.js";
-export declare const spawnWorkerContext: ({ list, ids, names, sab, thread, debug, totalNumberOfThread, source, at, workerOptions, workerExecArgv, permission, host, payload, bufferReferenceReturn, payloadInitialBytes, payloadMaxBytes, bufferMode, maxPayloadBytes, abortSignalCapacity, usesAbortSignal, }: {
+export declare const spawnWorkerContext: ({ list, ids, names, sab, thread, debug, hostDebug, totalNumberOfThread, source, at, workerOptions, workerExecArgv, permission, host, payload, bufferReferenceReturn, abortSignalCapacity, usesAbortSignal, sharedChannelHandler, }: {
     list: string[];
     ids: number[];
     names: string[];
@@ -12,6 +13,7 @@ export declare const spawnWorkerContext: ({ list, ids, names, sab, thread, debug
     sab?: Sab;
     thread: number;
     debug?: DebugOptions;
+    hostDebug?: (message: string) => void;
     totalNumberOfThread: number;
     source?: string;
     workerOptions?: WorkerSettings;
@@ -20,14 +22,18 @@ export declare const spawnWorkerContext: ({ list, ids, names, sab, thread, debug
     host?: DispatcherSettings;
     payload?: PayloadBufferOptions;
     bufferReferenceReturn?: "copy" | "borrow";
-    payloadInitialBytes?: number;
-    payloadMaxBytes?: number;
-    bufferMode?: PayloadBufferOptions["mode"];
-    maxPayloadBytes?: number;
     abortSignalCapacity?: number;
     usesAbortSignal?: boolean;
+    /**
+     * When set, this lane keeps its dispatcher state while the pool owns the
+     * macro channel that runs all lane checks.
+     */
+    sharedChannelHandler?: ChannelHandler;
 }) => WorkerContext & {
     lock: ReturnType<typeof lock2>;
     processSharedMemoryBackings?: readonly ProcessSharedMemoryBacking[];
+    dispatcherCheck?: DispatcherCheck;
+    laneWake?: () => void;
+    bindSend?: (fn: () => void) => void;
 };
 export type CreateContext = WorkerContext;

package/src/runtime/pool.js

@@ -1,7 +1,7 @@
 import { createHostTxQueue } from "./tx-queue.js";
 import { cleanupProcessWorkerMemoryQuietly, createProcessSharedMemoryAllocator, createProcessWorkerMemoryLayout, createProcessWorkerNativeSignalNotifier, readProcessSharedMemorySettings, readProcessWorkerCommandPrefix, readProcessWorkerRuntime, serializeWorkerBootstrapData, spawnProcessWorker, terminateWorkerQuietly, toProcessWorkerBootPayload, toWorkerCompatExecArgv, toWorkerSafeExecArgv, } from "./process-worker.js";
 import { createSharedMemoryTransport, TRANSPORT_SIGNAL_BYTES, } from "../ipc/transport/shared-memory.js";
-import { ChannelHandler, hostDispatcherLoop } from "./dispatcher.js";
+import { ChannelHandler, hostDispatcherLoop, } from "./dispatcher.js";
 import { HEADER_SLOT_STRIDE_U32, lock2, LOCK_SECTOR_BYTE_LENGTH, LockBound, } from "../memory/lock.js";
 import "../worker/loop.js";
 import { createSharedArrayBuffer, createWasmSharedArrayBuffer, } from "../common/runtime.js";
@@ -34,7 +34,7 @@ const withFixedPayloadConfig = (config) => ({
     mode: "fixed",
     payloadInitialBytes: config.payloadMaxByteLength,
 });
-export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, totalNumberOfThread, source, at, workerOptions, workerExecArgv, permission, host, payload, bufferReferenceReturn, payloadInitialBytes, payloadMaxBytes, bufferMode, maxPayloadBytes, abortSignalCapacity, usesAbortSignal, }) => {
+export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, hostDebug, totalNumberOfThread, source, at, workerOptions, workerExecArgv, permission, host, payload, bufferReferenceReturn, abortSignalCapacity, usesAbortSignal, sharedChannelHandler, }) => {
     const tsFileUrl = new URL(import.meta.url);
     const poliWorker = RUNTIME_WORKER;
     const resolvedWorkerOptions = serializeWorkerBootstrapData(withDefaultWorkerTimers(workerOptions));
@@ -48,9 +48,6 @@ export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, total
     const processSharedMemorySettings = useProcessWorkerRuntime
         ? readProcessSharedMemorySettings(resolvedWorkerOptions)
         : undefined;
-    if (debug?.logHref === true) {
-        console.log(tsFileUrl);
-    }
     if (!useProcessWorkerRuntime && typeof poliWorker !== "function") {
         throw new Error("Worker is not available in this runtime");
     }
@@ -63,15 +60,7 @@ export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, total
         return bytes > 0 ? bytes : undefined;
     };
     const basePayloadConfig = resolvePayloadBufferOptions({
-        options: {
-            ...payload,
-            mode: payload?.mode ?? bufferMode,
-            maxPayloadBytes: payload?.maxPayloadBytes ?? maxPayloadBytes,
-            payloadInitialBytes: payload?.payloadInitialBytes ??
-                sanitizeBytes(payloadInitialBytes),
-            payloadMaxByteLength: payload?.payloadMaxByteLength ??
-                sanitizeBytes(payloadMaxBytes),
-        },
+        options: payload,
     });
     const resolvedPayloadConfig = useProcessWorkerRuntime
         ? withFixedPayloadConfig(basePayloadConfig)
@@ -183,7 +172,6 @@ export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, total
             : sab,
         isMain: true,
         thread,
-        debug,
     });
     const signalBox = signals;
     const nativeNotifySignal = createProcessWorkerNativeSignalNotifier({
@@ -201,20 +189,54 @@ export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, total
             : undefined,
     });
     const { enqueue, rejectAll, txIdle, } = queue;
-    const channelHandler = new ChannelHandler();
-    const { check } = hostDispatcherLoop({
+    const thisSignal = signalBox.opView;
+    const a_add = Atomics.add;
+    const a_load = Atomics.load;
+    const a_notify = Atomics.notify;
+    const canNotifySignal = thisSignal.buffer instanceof SharedArrayBuffer;
+    const notifySignal = nativeNotifySignal ??
+        (canNotifySignal ? (() => a_notify(thisSignal, 0, 1)) : undefined);
+    // Wakes this lane's worker when it is parked (rxStatus 0). Used by send()
+    // (new work just arrived) — the dispatcher drain wakes it the same way.
+    const laneWake = () => {
+        if (a_load(signalBox.rxStatus, 0) === 0) {
+            a_add(thisSignal, 0, 1);
+            notifySignal?.();
+        }
+    };
+    let dispatchSend = () => { };
+    const send = () => dispatchSend();
+    let channelHandler;
+    const ownsChannel = sharedChannelHandler === undefined;
+    const ownChannel = sharedChannelHandler ?? new ChannelHandler();
+    const { check: dispatcherCheck } = hostDispatcherLoop({
         signalBox,
         queue,
-        channelHandler,
+        channelHandler: ownChannel,
         dispatcherOptions: host,
         notifySignal: nativeNotifySignal,
-        //thread,
-        //debugSignal: debug?.logMain ?? false,
-        //perf,
     });
-    channelHandler.open(check);
+    if (ownsChannel) {
+        ownChannel.open(dispatcherCheck);
+        channelHandler = ownChannel;
+        dispatchSend = () => {
+            if (dispatcherCheck.isRunning === true)
+                return;
+            dispatcherCheck.isRunning = true;
+            Promise.resolve().then(dispatcherCheck);
+            laneWake();
+        };
+    }
     let worker;
     const workerUrl = source ?? tsFileUrl;
+    const workerMode = useProcessWorkerRuntime
+        ? "process"
+        : HAS_NODE_WORKER_THREADS
+            ? "worker_threads"
+            : "worker";
+    hostDebug?.(`worker thread=${thread} mode=${workerMode}` +
+        `${processWorkerRuntime ? ` runtime=${processWorkerRuntime}` : ""}` +
+        ` url=${String(workerUrl)}`);
     const workerDataPayload = {
         sab: signals.sab,
         abortSignalSAB,
@@ -308,7 +330,7 @@ export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, total
             return;
         closedReason = reason;
         rejectAll(reason);
-        channelHandler.close();
+        channelHandler?.close();
     };
     const onWorkerMessage = (message) => {
         if (!isWorkerFatalMessage(message))
@@ -350,27 +372,6 @@ export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, total
             };
         }
     }
-    const thisSignal = signalBox.opView;
-    const a_add = Atomics.add;
-    const a_load = Atomics.load;
-    const a_notify = Atomics.notify;
-    const canNotifySignal = thisSignal.buffer instanceof SharedArrayBuffer;
-    const notifySignal = nativeNotifySignal ??
-        (canNotifySignal ? (() => a_notify(thisSignal, 0, 1)) : undefined);
-    //const scheduleFastCheck = queueMicrotask;
-    const send = () => {
-        if (check.isRunning === true)
-            return;
-        check.isRunning = true;
-        Promise.resolve().then(check);
-        // Macro lane: dispatcher check is driven by the channel callback.
-        // channelHandler.notify();
-        // Use opView as a wake counter in lock2 mode to avoid lost wakeups.
-        if (a_load(signalBox.rxStatus, 0) === 0) {
-            a_add(thisSignal, 0, 1);
-            notifySignal?.();
-        }
-    };
     lock.setPromiseHandler((task, isRejected, value) => {
         queue.settlePromisePayload(task, isRejected, value);
         send();
@@ -393,6 +394,11 @@ export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, total
         },
         lock,
         processSharedMemoryBackings: processSharedMemory?.backings,
+        dispatcherCheck,
+        laneWake: sharedChannelHandler !== undefined ? laneWake : undefined,
+        bindSend: sharedChannelHandler !== undefined
+            ? ((fn) => void (dispatchSend = fn))
+            : undefined,
     };
     return context;
 };

package/src/runtime/process-worker.js

@@ -2,6 +2,7 @@ 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 { 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";
@@ -72,7 +73,7 @@ export const createProcessSharedMemoryAllocator = (debug) => {
         addon = loadNodeNativeAddon(require, "knitting_shared_memory");
     }
     catch (error) {
-        if (debug?.extras === true) {
+        if (debugHas(debug, "lifecycle")) {
             console.warn("Process-shared memory allocator unavailable; falling back to SharedArrayBuffer.", error);
         }
         return undefined;

package/src/runtime/tx-queue.js

@@ -50,7 +50,11 @@ export function createHostTxQueue({ max, lock, returnLock, releaseBufferReferenc
     const completeFrame = releaseBufferReferenceReturn === undefined
         ? resolveReturn
         : () => withBufferReferenceReturnReleaser(releaseBufferReferenceReturn, resolveReturn);
-    const txIdle = () => getPendingFrameCount() === 0 && inUsed === getPendingPromiseCount();
+    const hasActiveTasks = () => {
+        const count = (inUsed - getPendingPromiseCount()) | 0;
+        return count > 0;
+    };
+    const txIdle = () => getPendingFrameCount() === 0 && !hasActiveTasks();
     const rejectAll = (reason) => {
         for (let index = 0; index < queue.length; index++) {
             const slot = queue[index];

package/src/types.d.ts

@@ -62,8 +62,11 @@ type Serializable = string | object | number | boolean | bigint;
 type ValidInput = bigint | void | JSONValue | symbol | ArrayBuffer | Uint8Array | Int32Array | Float64Array | BigInt64Array | BigUint64Array | DataView | Error | Date | Envelope<EnvelopeHeader, EnvelopeBody>;
 type Args = ValidInput | Serializable;
 type MaybePromise<T> = T | Promise<T>;
+/** Blob payloads are not supported; pass ArrayBuffer/typed arrays instead. */
 type NoBlob<T> = T extends Blob ? never : T;
+/** Task input may be a direct value or native Promise; thenables are plain values. */
 type TaskInput = NoBlob<Args> | Promise<NoBlob<Args>>;
+/** Per-call timeout. A number is milliseconds; object form can return a default. */
 type TaskTimeout = number | {
     time: number;
     maybe?: true;
@@ -76,6 +79,7 @@ type BivariantCallback<Args extends unknown[], R> = {
 type AbortSignalConfig = {
     readonly hasAborted: true;
 };
+/** `true` or config injects an abort toolkit as the task's second parameter. */
 type AbortSignalOption = true | AbortSignalConfig | undefined;
 type AbortSignalMethods<AS extends AbortSignalOption> = AS extends undefined ? never : {
     hasAborted: () => boolean;
@@ -94,7 +98,7 @@ type TaskLike<AS extends AbortSignalOption = AbortSignalOption> = {
 });
 type TaskFunctionLike = (...args: any[]) => any;
 type Composed<A extends TaskInput = Args, B extends Args = Args, AS extends AbortSignalOption = undefined> = FixPoint<A, B, AS> & SecondPart;
-type tasks = Record<string, Composed<any, any, AbortSignalOption> | TaskFunctionLike>;
+type tasks = Record<string, Composed<any, any, any> | TaskFunctionLike>;
 type ComposedWithKey = Composed<any, any, AbortSignalOption> & {
     name: string;
 };
@@ -118,7 +122,9 @@ type FunctionMapType<T extends Record<string, TaskLike<any> | TaskFunctionLike>>
     [K in keyof T]: PromiseWrapped<TaskCallable<T[K]>, AbortSignalOfTask<T[K]>>;
 };
 interface FixPointBase<A extends TaskInput, B extends Args, AS extends AbortSignalOption = undefined> {
+    /** Worker function. It receives one value; use a tuple/object for many inputs. */
     readonly f: TaskFn<A, B, AS>;
+    /** Soft call timeout. Use `worker.hardTimeoutMs` for runaway CPU walls. */
     readonly timeout?: TaskTimeout;
 }
 type FixPoint<A extends TaskInput, B extends Args, AS extends AbortSignalOption = undefined> = FixPointBase<A, B, AS> & (AS extends undefined ? {
@@ -127,7 +133,9 @@ type FixPoint<A extends TaskInput, B extends Args, AS extends AbortSignalOption
     readonly abortSignal: AS;
 });
 type ImportTaskOptions<A extends TaskInput = void, B extends Args = void, AS extends AbortSignalOption = undefined> = Omit<FixPoint<A, B, AS>, "f"> & {
+    /** Module imported by the worker only. Relative paths resolve from caller. */
     readonly href: string;
+    /** Plain function export name. Defaults to `"default"`; do not target `task()`. */
     readonly name?: string;
 };
 type SecondPart = {
@@ -142,13 +150,22 @@ type SecondPart = {
     readonly imported?: boolean;
 };
 type SingleTaskPool<A extends TaskInput = Args, B extends Args = Args, AS extends AbortSignalOption = undefined> = {
+    /** Invoke the single task. Arguments may be native Promises. */
     call: PromiseWrapped<TaskFn<A, B, AS>, AS>;
+    /** 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;
 };
 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;
+    /**
+     * 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>;
 };
 type ReturnFixed<A extends TaskInput = undefined, B extends Args = undefined, AS extends AbortSignalOption = undefined> = FixPoint<A, B, AS> & SecondPart & {
@@ -175,12 +192,13 @@ type Balancer = BalancerStrategy | {
      */
     strategy?: BalancerStrategy;
 };
-type DebugOptions = {
-    extras?: boolean;
-    logMain?: boolean;
-    logHref?: boolean;
-    logImportedUrl?: boolean;
+/** Debug namespaces for host setup, worker state, imports, globals, and lifecycle. */
+type DebugNamespace = "host" | "globals" | "signals" | "imports" | "lifecycle";
+type DebugFlags = {
+    [Namespace in DebugNamespace]?: boolean;
 };
+/** Pass `true` for all debug, or enable namespaces by name. */
+type DebugOptions = boolean | DebugFlags;
 type WorkerBootstrapContext = {
     readonly thread: number;
     readonly totalNumberOfThread: number;
@@ -212,7 +230,7 @@ type WorkerSettings = {
     /**
      * Experimental worker runtime.
      * "thread" uses Worker/worker_threads. "process" spawns another JavaScript
-     * runtime and shares one inherited fd-backed memory mapping.
+     * runtime, useful for process isolation, bwrap, and containers.
      */
     runtime?: "thread" | "process";
     /**
@@ -278,44 +296,34 @@ type DispatcherSettings = {
      * Max backoff delay (milliseconds).
      */
     maxBackoffMs?: number;
+    /**
+     * Host dispatcher topology.
+     * - `"per-thread"`: each worker owns its dispatcher and macro channel.
+     * - `"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`).
+     */
+    dispatcher?: "per-thread" | "serial-channel";
 };
 type CreatePool = {
+    /** Number of workers. Default: 1. */
     threads?: number;
-    /**
-     * @deprecated Too risky with processes, need to rewrite or delete.
-     */
+    /** Add a host inline lane for regular tasks. Imported tasks still use workers. */
     inliner?: Inliner;
     balancer?: Balancer;
     worker?: WorkerSettings;
     /**
-     * Payload transport settings.
+     * Payload transport settings. Default dynamic payload cap is about 8 MiB
+     * (`payloadMaxByteLength >> 3`, with a 64 MiB growth cap).
      */
     payload?: PayloadBufferOptions;
     /**
      * Experimental unsafe options.
      */
     unsafe?: UnsafeOptions;
-    /**
-     * Initial payload SharedArrayBuffer size (bytes) per worker direction.
-     * Defaults to 4 MiB when growable SAB is available, otherwise defaults to
-     * `payloadMaxBytes`.
-     * @deprecated Use `payload.payloadInitialBytes`.
-     */
-    payloadInitialBytes?: number;
-    /**
-     * Maximum payload SharedArrayBuffer size (bytes) per worker direction.
-     * Defaults to 64 MiB.
-     * @deprecated Use `payload.payloadMaxByteLength`.
-     */
-    payloadMaxBytes?: number;
-    /**
-     * @deprecated Use `payload.mode`.
-     */
-    bufferMode?: PayloadBufferMode;
-    /**
-     * @deprecated Use `payload.maxPayloadBytes`.
-     */
-    maxPayloadBytes?: number;
     /**
      * Abort-aware signal pool capacity.
      * Defaults to `258`.
@@ -332,19 +340,18 @@ type CreatePool = {
     workerExecArgv?: string[];
     /**
      * Runtime permission protocol.
-     * Omit to use strict defaults with `allowImport: true`.
+     * Omit to use strict defaults with `allowImport: true`; worker console is
+     * quiet unless `permission: { console: true }`.
+     *
+     * Task code cannot terminate the host: process/Deno exit APIs are blocked.
      * Use `"strict"` (default for object mode) or `"unsafe"`.
      * Accepts object form for fine-grained permission controls.
      */
     permission?: PermissionProtocolInput;
-    /**
-     * @deprecated Use `host` instead.
-     */
-    dispatcher?: DispatcherSettings;
     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, 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 { 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 { LockBound as LockBound, PayloadBuffer as PayloadBuffer, PayloadSignal as PayloadSignal, TaskIndex as TaskIndex, } from "./memory/lock.js";
 export type { RegisterMalloc as RegisterMalloc } from "./memory/regionRegistry.js";