knitting 0.1.52 → 0.1.53

package/README.md

@@ -335,7 +335,7 @@ Common options you might tweak:
 | `worker.runtime`                  | Choose `"thread"` or `"process"` workers.                                                                                         |
 | `worker.processSharedMemory`      | Process-worker memory discovery: `"inherit"` by default on POSIX, or `"named"` for wrappers/containers that cannot preserve fd 0. |
 | `permission`                      | Runtime permission policy for workers.                                                                                            |
-| `debug`                           | Enable extra diagnostics.                                                                                                         |
+| `debug`                           | Enable diagnostics (`host`, `globals`, `signals`, `imports`, `lifecycle`) or use `KNITTING_DEBUG`.                                |
 | `source`                          | Worker source override for advanced runtimes.                                                                                     |
 
 ### Worker bootstrap

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knitting",
-  "version": "0.1.52",
+  "version": "0.1.53",
   "description": "Shared-memory IPC runtime for Node.js, Deno, and Bun.",
   "license": "Apache-2.0",
   "repository": {

package/src/api.d.ts

@@ -25,12 +25,31 @@ export { endpointSymbol as endpointSymbol };
  * Reconstructs stable task order from top-level exports before names are bound.
  */
 export declare const toListAndIds: ToListAndIdsFn;
+/**
+ * Create a typed worker pool from module-scope exported tasks/functions.
+ *
+ * Install/import as `knitting` on npm or `@vixeny/knitting` on JSR. Requires
+ * Node 22+, Deno 2+, or Bun 1+.
+ *
+ * Use `createPool(options)({ taskA })`, call `await pool.call.taskA(arg)`, and
+ * clean up with `using pool = ...` or `await pool.shutdown()`.
+ *
+ * Guard host-only pool setup with `isMain`: workers re-import task modules, and
+ * top-level imports in those modules run in every worker. Keep task modules
+ * lean and separate from server/framework setup. Each task receives one
+ * argument; use an object or tuple for multiple values.
+ */
 export declare const createPool: CreatePoolFactory;
 /**
- * Define a worker task.
+ * Define a worker task with options.
+ *
+ * Pass raw module-scope exported functions to `createPool` directly when you do
+ * not need options. Use `task({ f })` for timeouts, abort signals, or the
+ * single-task `.createPool()` shorthand.
  *
- * Input may be a direct value or a native Promise of that value.
- * Thenables/PromiseLike values are treated as plain values.
+ * The function receives one argument; use a tuple/object for multiple values.
+ * Inputs may be direct values or native Promises, so `request.arrayBuffer()` can
+ * be forwarded without awaiting on the host.
  */
 export declare function task<F extends InferredTaskFunction>(I: InferredTaskShape<F, undefined>): ReturnFixed<InferredTaskInput<F, undefined>, InferredTaskOutput<F>, undefined>;
 export declare function task<F extends InferredTaskFunction>(I: InferredTaskShape<F, true>): ReturnFixed<InferredTaskInput<F, true>, InferredTaskOutput<F>, true>;
@@ -39,10 +58,11 @@ export declare function task<A extends TaskInput = void, B extends Args = void>(
 export declare function task<A extends TaskInput = void, B extends Args = void, AS extends AbortSignalConfig = AbortSignalConfig>(I: FixPoint<A, B, AS>): ReturnFixed<A, B, AS>;
 export declare function task<A extends TaskInput = void, B extends Args = void>(I: FixPoint<A, B, undefined>): ReturnFixed<A, B, undefined>;
 /**
- * Define a task whose worker-side function is imported dynamically from `href`.
+ * Define a task whose worker-side code is imported only by workers.
  *
- * This keeps module import/evaluation inside the worker, so worker permission
- * policies apply to that import path.
+ * Use this for untrusted or security-sensitive code: the host keeps a typed
+ * wrapper and does not import/evaluate `href`. The target export must be a
+ * plain function, not a `task()` wrapper.
  */
 export declare function importTask<A extends TaskInput = void, B extends Args = void>(options: ImportTaskOptions<A, B, true>): ReturnFixed<A, B, true>;
 export declare function importTask<A extends TaskInput = void, B extends Args = void, AS extends AbortSignalConfig = AbortSignalConfig>(options: ImportTaskOptions<A, B, AS>): ReturnFixed<A, B, AS>;

package/src/api.js

@@ -7,15 +7,51 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     return path;
 };
 import { getCallerFilePath, getCallerHref } from "./common/task-source.js";
+import { DEBUG_ENABLED, resolveDebugNamespaces } from "./debug/gate.js";
 import { genTaskID } from "./common/task-source.js";
 import { toModuleUrl } from "./common/module-url.js";
 import { endpointSymbol } from "./common/task-symbol.js";
 import { spawnWorkerContext } from "./runtime/pool.js";
+import { RUNTIME } from "./common/runtime.js";
 import { RUNTIME_IS_MAIN_THREAD, RUNTIME_POOL_DEPTH, RUNTIME_WORKER_DATA, } from "./common/worker-runtime.js";
 import { resolvePermissionProtocol, toRuntimePermissionFlags, } from "./permission/index.js";
 import { getNodeProcess } from "./common/node-compat.js";
 import { managerMethod } from "./runtime/balancer.js";
 import { createInlineExecutor } from "./runtime/inline-executor.js";
+const hasDebugNamespace = (namespaces, namespace) => namespaces.has("*") || namespaces.has(namespace);
+const createHostDebug = (namespaces) => {
+    const enabled = (namespace) => hasDebugNamespace(namespaces, namespace);
+    if (!enabled("host"))
+        return undefined;
+    const base = performance.now();
+    const tag = `host·${RUNTIME}`;
+    const log = (message) => {
+        const elapsed = (performance.now() - base).toFixed(1);
+        console.error(`[${tag}·+${elapsed}ms] host: ${message}`);
+    };
+    return { log };
+};
+const readHostCwd = () => {
+    const denoCwd = globalThis.Deno?.cwd;
+    if (typeof denoCwd === "function") {
+        try {
+            return denoCwd();
+        }
+        catch {
+        }
+    }
+    const nodeProcess = getNodeProcess();
+    if (typeof nodeProcess?.cwd === "function") {
+        try {
+            return nodeProcess.cwd();
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+};
+const formatDebugList = (values, empty = "(none)") => values && values.length > 0 ? values.join(",") : empty;
 const MAX_FUNCTION_ID = 0xFFFF;
 const MAX_FUNCTION_COUNT = MAX_FUNCTION_ID + 1;
 const DEFAULT_IMPORT_EXPORT_NAME = "default";
@@ -93,14 +129,36 @@ const toPoolTaskEntries = (input, callerHref) => Object.entries(input).map(([nam
     }
     throw new TypeError(`createPool task "${name}" must be a task definition or exported function`);
 });
-export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe, payloadInitialBytes, payloadMaxBytes, bufferMode, maxPayloadBytes, abortSignalCapacity, source, worker, workerExecArgv, permission, dispatcher, host, }) => (tasks) => {
+/**
+ * Create a typed worker pool from module-scope exported tasks/functions.
+ *
+ * Install/import as `knitting` on npm or `@vixeny/knitting` on JSR. Requires
+ * Node 22+, Deno 2+, or Bun 1+.
+ *
+ * Use `createPool(options)({ taskA })`, call `await pool.call.taskA(arg)`, and
+ * clean up with `using pool = ...` or `await pool.shutdown()`.
+ *
+ * Guard host-only pool setup with `isMain`: workers re-import task modules, and
+ * top-level imports in those modules run in every worker. Keep task modules
+ * lean and separate from server/framework setup. Each task receives one
+ * argument; use an object or tuple for multiple values.
+ */
+export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe, abortSignalCapacity, source, worker, workerExecArgv, permission, host, }) => (tasks) => {
     const bufferReferenceReturn = unsafe?.BufferReferenceReturn;
+    const debugRequested = DEBUG_ENABLED ||
+        (debug !== undefined && debug !== false);
+    let debugNamespaces;
+    const getDebugNamespaces = () => debugNamespaces ??= resolveDebugNamespaces(debug);
+    const hostDebug = debugRequested
+        ? createHostDebug(getDebugNamespaces())
+        : undefined;
+    const debugEnabled = (namespace) => debugRequested && hasDebugNamespace(getDebugNamespaces(), namespace);
     /**
      *  This functions is only available in the main thread.
      *  Also triggers when debug extra is enabled.
      */
     if (RUNTIME_IS_MAIN_THREAD === false) {
-        if ((debug?.extras === true)) {
+        if (debugEnabled("lifecycle")) {
             console.warn("createPool has been called with : " + JSON.stringify(RUNTIME_WORKER_DATA));
         }
         const notMainThreadError = () => {
@@ -126,6 +184,10 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
     const listOfFunctions = toPoolTaskEntries(tasks, callerHref)
         .sort((a, b) => a.name.localeCompare(b.name));
     const { list, ids, names, at } = toListAndIds(listOfFunctions);
+    hostDebug?.log(`cwd=${readHostCwd() ?? "(unknown)"} caller=${callerHref}`);
+    listOfFunctions.forEach((fn) => {
+        hostDebug?.log(`task name=${fn.name} id=${fn.id} from=${fn.importedFrom}`);
+    });
     if (listOfFunctions.length > MAX_FUNCTION_COUNT) {
         throw new RangeError(`Too many tasks: received ${listOfFunctions.length}. ` +
             `Maximum is ${MAX_FUNCTION_COUNT} (Uint16 function IDs: 0..${MAX_FUNCTION_ID}).`);
@@ -196,9 +258,16 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
         ...(defaultExecArgv ?? []),
     ]);
     const execArgv = sanitizeExecArgv(combinedExecArgv.length > 0 ? combinedExecArgv : undefined);
-    const hostDispatcher = host ?? dispatcher;
+    hostDebug?.log(`pool runtime=${RUNTIME} workers=${threads ?? 1}` +
+        ` lanes=${totalNumberOfThread} inliner=${usingInliner ? "on" : "off"}`);
+    hostDebug?.log(`modules=${formatDebugList(list)}`);
+    hostDebug?.log(`permission=${permissionProtocol?.mode ?? "off"} execArgv=${formatDebugList(execArgv)}`);
     const usesAbortSignal = listOfFunctions.some((fn) => fn.abortSignal !== undefined);
     const resolvedWorker = resolveWorkerBootstrapSettings(worker, callerHref);
+    if (resolvedWorker?.bootstrap !== undefined) {
+        hostDebug?.log(`bootstrap href=${resolvedWorker.bootstrap.href}` +
+            ` name=${resolvedWorker.bootstrap.name}`);
+    }
     if (usingInliner && resolvedWorker?.bootstrap !== undefined) {
         throw new Error("worker.bootstrap cannot be used with the inliner");
     }
@@ -223,17 +292,14 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
         at,
         thread,
         debug,
+        hostDebug: hostDebug?.log,
         totalNumberOfThread,
         source,
         workerOptions: resolvedWorker,
         workerExecArgv: execArgv,
-        host: hostDispatcher,
+        host,
         payload,
         bufferReferenceReturn,
-        payloadInitialBytes,
-        payloadMaxBytes,
-        bufferMode,
-        maxPayloadBytes,
         abortSignalCapacity,
         usesAbortSignal,
         permission: permissionProtocol,

package/src/connections/buffer-reference.d.ts

@@ -45,10 +45,12 @@ export declare const createBufferReferenceReturnReleaseMessage: (token: bigint)
 export declare const readBufferReferenceReturnReleaseMessage: (value: unknown) => bigint | undefined;
 export declare const isBufferReferenceMetadata: (value: unknown) => value is BufferReferenceMetadata;
 /**
- * Zero-copy handle for moving ArrayBuffer bytes to **thread** workers.
+ * Zero-copy handle for moving ArrayBuffer bytes to/from **thread** workers.
  *
  * Construction detaches the source. Consumers materialize the moved region in
- * their isolate: owning on Node, alias/copy on Deno/Bun.
+ * their isolate: owning on Node, alias/copy on Deno/Bun. Return a
+ * `BufferReference` for large binary results to avoid copying back through the
+ * transport. Use `ProcessSharedBuffer` across process boundaries.
  */
 export declare class BufferReference {
     #private;

package/src/connections/buffer-reference.js

@@ -216,10 +216,12 @@ export const isBufferReferenceMetadata = (value) => {
         meta.byteLength >= 0);
 };
 /**
- * Zero-copy handle for moving ArrayBuffer bytes to **thread** workers.
+ * Zero-copy handle for moving ArrayBuffer bytes to/from **thread** workers.
  *
  * Construction detaches the source. Consumers materialize the moved region in
- * their isolate: owning on Node, alias/copy on Deno/Bun.
+ * their isolate: owning on Node, alias/copy on Deno/Bun. Return a
+ * `BufferReference` for large binary results to avoid copying back through the
+ * transport. Use `ProcessSharedBuffer` across process boundaries.
  */
 export class BufferReference {
     [EXTERNAL_PAYLOAD_BRAND] = BUFFER_REFERENCE_CODEC_ID;

package/src/connections/process-shared-buffer.d.ts

@@ -36,6 +36,12 @@ export type ProcessSharedBufferViewConstructor<View extends ProcessSharedBufferV
 };
 export declare const setDefaultProcessSharedBufferPrimitives: (primitives: ProcessSharedBufferPrimitives | undefined) => void;
 export declare const getDefaultProcessSharedBufferPrimitives: () => ProcessSharedBufferPrimitives;
+/**
+ * Zero-copy shared bytes for process workers.
+ *
+ * Use this when the boundary is a separate process, container, or sandbox.
+ * For thread workers, `SharedArrayBuffer` or `BufferReference` can be cheaper.
+ */
 export declare class ProcessSharedBuffer {
     readonly [PROCESS_SHARED_BUFFER_BRAND] = true;
     readonly [EXTERNAL_PAYLOAD_BRAND] = "knitting.processSharedBuffer";

package/src/connections/process-shared-buffer.js

@@ -116,6 +116,12 @@ const expectRange = (byteOffset, byteLength, availableByteLength) => {
         throw new RangeError("process shared buffer byteLength is out of bounds");
     }
 };
+/**
+ * Zero-copy shared bytes for process workers.
+ *
+ * Use this when the boundary is a separate process, container, or sandbox.
+ * For thread workers, `SharedArrayBuffer` or `BufferReference` can be cheaper.
+ */
 export class ProcessSharedBuffer {
     [PROCESS_SHARED_BUFFER_BRAND] = true;
     [EXTERNAL_PAYLOAD_BRAND] = PROCESS_SHARED_BUFFER_CODEC_ID;

package/src/debug/env-diff.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Environment-diff primitive: snapshot the keys present on `globalThis`, then
+ * later compare to see what the loaded code added, removed, or redefined.
+ *
+ * This is the core of "check what happens" debugging — a concrete before/after
+ * of the real runtime a worker's modules created, not an aggregate metric. The
+ * same snapshot/diff shape generalises to other ambient state (process
+ * listeners, open handles, prototype patches); `globalThis` keys are the first
+ * instance.
+ */
+export type EnvSnapshot = {
+    readonly keys: ReadonlySet<string | symbol>;
+};
+/** Capture every own key on `globalThis`, including symbols. */
+export declare const snapshotGlobals: () => EnvSnapshot;
+export type GlobalsDiff = {
+    readonly added: (string | symbol)[];
+    readonly removed: (string | symbol)[];
+};
+export declare const diffGlobals: (before: EnvSnapshot, after: EnvSnapshot) => GlobalsDiff;
+/**
+ * Render a key with enough provenance to tell a fresh global from a
+ * monkeypatch: its `typeof`/accessor kind plus writable/configurable/enumerable
+ * flags (`w`/`c`/`e`).
+ */
+export declare const describeGlobalKey: (key: string | symbol) => string;

package/src/debug/env-diff.js

@@ -0,0 +1,49 @@
+/**
+ * Environment-diff primitive: snapshot the keys present on `globalThis`, then
+ * later compare to see what the loaded code added, removed, or redefined.
+ *
+ * This is the core of "check what happens" debugging — a concrete before/after
+ * of the real runtime a worker's modules created, not an aggregate metric. The
+ * same snapshot/diff shape generalises to other ambient state (process
+ * listeners, open handles, prototype patches); `globalThis` keys are the first
+ * instance.
+ */
+/** Capture every own key on `globalThis`, including symbols. */
+export const snapshotGlobals = () => ({
+    keys: new Set(Reflect.ownKeys(globalThis)),
+});
+export const diffGlobals = (before, after) => {
+    const added = [];
+    const removed = [];
+    for (const key of after.keys) {
+        if (!before.keys.has(key))
+            added.push(key);
+    }
+    for (const key of before.keys) {
+        if (!after.keys.has(key))
+            removed.push(key);
+    }
+    return { added, removed };
+};
+/**
+ * Render a key with enough provenance to tell a fresh global from a
+ * monkeypatch: its `typeof`/accessor kind plus writable/configurable/enumerable
+ * flags (`w`/`c`/`e`).
+ */
+export const describeGlobalKey = (key) => {
+    const name = typeof key === "symbol" ? key.toString() : key;
+    let descriptor;
+    try {
+        descriptor = Object.getOwnPropertyDescriptor(globalThis, key);
+    }
+    catch {
+        return name;
+    }
+    if (descriptor === undefined)
+        return name;
+    const kind = descriptor.get !== undefined || descriptor.set !== undefined
+        ? "accessor"
+        : typeof descriptor.value;
+    const flags = `${descriptor.writable === false ? "" : "w"}${descriptor.configurable ? "c" : ""}${descriptor.enumerable ? "e" : ""}`;
+    return flags.length > 0 ? `${name} (${kind} ${flags})` : `${name} (${kind})`;
+};

package/src/debug/gate.d.ts

@@ -0,0 +1,18 @@
+import type { DebugOptions } from "../types.js";
+/** Namespaces explicitly requested via `KNITTING_DEBUG`. */
+export declare const DEBUG_NAMESPACES: ReadonlySet<string>;
+/**
+ * True when at least one namespace is requested via the env var alone. Guards
+ * the env-only paths; callers that also accept a `debug` option should use
+ * {@link resolveDebugNamespaces} instead.
+ */
+export declare const DEBUG_ENABLED: boolean;
+/**
+ * Merge the namespaces requested through the `debug` pool option with those from
+ * `KNITTING_DEBUG`; either source can enable a namespace. Returns an empty set
+ * when nothing is requested, so callers use `.size === 0` to keep the rest of
+ * `src/debug` unloaded — zero cost when off.
+ */
+export declare const resolveDebugNamespaces: (debug?: DebugOptions) => Set<string>;
+/** True when `namespace` (or `"*"`) is active for the given `debug` config + env. */
+export declare const debugHas: (debug: DebugOptions | undefined, namespace: string) => boolean;

package/src/debug/gate.js

@@ -0,0 +1,69 @@
+/**
+ * Zero-cost debug gate.
+ *
+ * Read once at module load from `KNITTING_DEBUG`. This module is deliberately
+ * tiny and dependency-light: importing it must never pull in the logger or the
+ * environment-diff machinery. Callers branch on {@link DEBUG_ENABLED} and only
+ * then `await import("./handle.ts")`, so when debug is off nothing else under
+ * `src/debug` is ever loaded — literally zero cost, not merely cheap.
+ *
+ * `KNITTING_DEBUG` is a comma-separated list of namespaces:
+ *   KNITTING_DEBUG=host,imports      # only those
+ *   KNITTING_DEBUG=*                 # everything
+ */
+import { getNodeProcess } from "../common/node-compat.js";
+const readEnv = (key) => {
+    // Deno: `process.env` exists under node-compat, but reading it may require
+    // --allow-env. Prefer the typed `Deno.env` and swallow permission errors.
+    const denoEnv = globalThis.Deno?.env;
+    if (typeof denoEnv?.get === "function") {
+        try {
+            return denoEnv.get(key);
+        }
+        catch {
+            /* env permission denied — fall through to node/bun */
+        }
+    }
+    try {
+        return getNodeProcess()?.env?.[key];
+    }
+    catch {
+        return undefined;
+    }
+};
+const raw = readEnv("KNITTING_DEBUG");
+/** Namespaces explicitly requested via `KNITTING_DEBUG`. */
+export const DEBUG_NAMESPACES = new Set((raw ?? "")
+    .split(",")
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0));
+/**
+ * True when at least one namespace is requested via the env var alone. Guards
+ * the env-only paths; callers that also accept a `debug` option should use
+ * {@link resolveDebugNamespaces} instead.
+ */
+export const DEBUG_ENABLED = DEBUG_NAMESPACES.size > 0;
+/**
+ * Merge the namespaces requested through the `debug` pool option with those from
+ * `KNITTING_DEBUG`; either source can enable a namespace. Returns an empty set
+ * when nothing is requested, so callers use `.size === 0` to keep the rest of
+ * `src/debug` unloaded — zero cost when off.
+ */
+export const resolveDebugNamespaces = (debug) => {
+    const namespaces = new Set(DEBUG_NAMESPACES);
+    if (debug === true) {
+        namespaces.add("*");
+    }
+    else if (debug !== undefined && debug !== false) {
+        for (const [key, value] of Object.entries(debug)) {
+            if (value === true)
+                namespaces.add(key);
+        }
+    }
+    return namespaces;
+};
+/** True when `namespace` (or `"*"`) is active for the given `debug` config + env. */
+export const debugHas = (debug, namespace) => {
+    const namespaces = resolveDebugNamespaces(debug);
+    return namespaces.has("*") || namespaces.has(namespace);
+};

package/src/debug/handle.d.ts

@@ -0,0 +1,23 @@
+export type DebugInit = {
+    /** Identity prefix for log tags, e.g. `"w0"` for a worker or `"main"`. */
+    readonly name: string;
+    readonly runtime: string;
+    readonly namespaces: ReadonlySet<string>;
+};
+export type Debug = {
+    /**
+     * Is a namespace active? Capture this once before a hot loop and branch on
+     * the boolean — never call per-iteration.
+     */
+    enabled: (namespace: string) => boolean;
+    /** Emit a tagged line to stderr when `namespace` is active. */
+    log: (namespace: string, message: string) => void;
+    /**
+     * Re-snapshot `globalThis` and report what changed since the previous phase.
+     * Drives two-phase pollution attribution (e.g. `"bootstrap"` then
+     * `"tasks"`), so you can see which loader injected which global. No-op unless
+     * the `globals` namespace is active.
+     */
+    envPhase: (label: string) => void;
+};
+export declare const initDebug: ({ name, runtime, namespaces }: DebugInit) => Debug;

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/pool.d.ts

@@ -4,7 +4,7 @@ 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, }: {
     list: string[];
     ids: number[];
     names: string[];
@@ -12,6 +12,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,10 +21,6 @@ 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;
 }) => WorkerContext & {

package/src/runtime/pool.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, }) => {
     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({
@@ -208,13 +196,18 @@ export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, total
         channelHandler,
         dispatcherOptions: host,
         notifySignal: nativeNotifySignal,
-        //thread,
-        //debugSignal: debug?.logMain ?? false,
-        //perf,
     });
     channelHandler.open(check);
     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,
@@ -365,7 +358,7 @@ export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, total
         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.
+        // Use opView as a wake token in lock2 mode to avoid lost wakeups.
         if (a_load(signalBox.rxStatus, 0) === 0) {
             a_add(thisSignal, 0, 1);
             notifySignal?.();

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/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;
@@ -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";
     /**
@@ -280,42 +298,21 @@ type DispatcherSettings = {
     maxBackoffMs?: number;
 };
 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 +329,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";

package/src/utils/http.d.ts

@@ -3,13 +3,21 @@ export type NumberFormat = "f64" | "f32" | "i32";
 export type NumberBufferOptions = {
     format?: NumberFormat;
 };
+/** View ArrayBuffer/SharedArrayBuffer/typed-array bytes as Uint8Array. */
 export declare const bufferToBytes: (source: BufferLike) => Uint8Array;
+/** Copy bytes into a SharedArrayBuffer for zero-copy worker inputs. */
 export declare const bytesToBuffer: (source: BufferLike) => SharedArrayBuffer;
+/** Decode UTF-8 bytes from ArrayBuffer/SharedArrayBuffer/typed-array input. */
 export declare const bufferToString: (source: BufferLike) => string;
+/** Encode UTF-8 text into a SharedArrayBuffer. */
 export declare const stringToBuffer: (text: string) => SharedArrayBuffer;
+/** Decode JSON from UTF-8 bytes. */
 export declare const bufferToJson: <T = unknown>(source: BufferLike) => T;
+/** Encode JSON into a SharedArrayBuffer. */
 export declare const jsonToBuffer: (value: unknown) => SharedArrayBuffer;
+/** Encode numbers into a SharedArrayBuffer (`f64` by default). */
 export declare const numbersToBuffer: (numbers: ArrayLike<number>, options?: NumberBufferOptions) => SharedArrayBuffer;
+/** Decode numeric typed-array views from worker-friendly byte buffers. */
 export declare function bufferToNumbers(source: BufferLike, options?: {
     format?: "f64";
 }): Float64Array;

package/src/utils/http.js

@@ -21,7 +21,9 @@ const toBytes = (source) => {
     }
     throw new TypeError("Expected an ArrayBuffer, SharedArrayBuffer, or typed-array view.");
 };
+/** View ArrayBuffer/SharedArrayBuffer/typed-array bytes as Uint8Array. */
 export const bufferToBytes = (source) => toBytes(source);
+/** Copy bytes into a SharedArrayBuffer for zero-copy worker inputs. */
 export const bytesToBuffer = (source) => {
     const bytes = toBytes(source);
     const sab = new SharedArrayBuffer(bytes.byteLength);
@@ -38,6 +40,7 @@ const makeNumberView = (format, buffer, byteOffset, length) => {
             return new Int32Array(buffer, byteOffset, length);
     }
 };
+/** Decode UTF-8 bytes from ArrayBuffer/SharedArrayBuffer/typed-array input. */
 export const bufferToString = (source) => {
     const bytes = toBytes(source);
     if (hasNodeBuffer) {
@@ -47,6 +50,7 @@ export const bufferToString = (source) => {
     }
     return textDecoder.decode(bytes);
 };
+/** Encode UTF-8 text into a SharedArrayBuffer. */
 export const stringToBuffer = (text) => {
     if (typeof text !== "string") {
         throw new TypeError("stringToBuffer expects a string.");
@@ -62,7 +66,9 @@ export const stringToBuffer = (text) => {
     new Uint8Array(sab).set(encoded);
     return sab;
 };
+/** Decode JSON from UTF-8 bytes. */
 export const bufferToJson = (source) => JSON.parse(bufferToString(source));
+/** Encode JSON into a SharedArrayBuffer. */
 export const jsonToBuffer = (value) => {
     const text = JSON.stringify(value);
     if (typeof text !== "string") {
@@ -70,6 +76,7 @@ export const jsonToBuffer = (value) => {
     }
     return stringToBuffer(text);
 };
+/** Encode numbers into a SharedArrayBuffer (`f64` by default). */
 export const numbersToBuffer = (numbers, options) => {
     const format = options?.format ?? "f64";
     const sab = new SharedArrayBuffer(numbers.length * BYTES_PER_ELEMENT[format]);

package/src/worker/loop.js

@@ -13,6 +13,7 @@ import { signalAbortFactory } from "../shared/abortSignal.js";
 import { runWorkerBootstrap } from "./bootstrap.js";
 import { getProcessWorkerNativeWaitU32, installProcessWorkerBootstrap, } from "./process-worker-bootstrap.js";
 import { readBufferReferenceReturnReleaseMessage, } from "../connections/buffer-reference.js";
+import { resolveDebugNamespaces } from "../debug/gate.js";
 const WORKER_FATAL_MESSAGE_KEY = "__knittingWorkerFatal";
 const reportWorkerStartupFatal = (error) => {
     const message = String(error?.message ?? error);
@@ -72,6 +73,14 @@ export const workerMainLoop = async (startupData) => {
     const { debug, sab, thread, startAt, workerOptions, lock, returnLock, abortSignalSAB, abortSignalMax, payloadConfig, bufferReferenceReturn, permission, totalNumberOfThread, list, ids, names, at, } = startupData;
     scrubWorkerDataSensitiveBuffers(startupData);
     assertWorkerSharedMemoryBootData({ sab, lock, returnLock });
+    const debugNamespaces = resolveDebugNamespaces(debug);
+    const dbg = debugNamespaces.size > 0
+        ? await import("../debug/handle.js").then((module) => module.initDebug({
+            name: `w${thread}`,
+            runtime: RUNTIME,
+            namespaces: debugNamespaces,
+        }))
+        : undefined;
     let Comment;
     (function (Comment) {
         Comment[Comment["thisIsAHint"] = 0] = "thisIsAHint";
@@ -82,7 +91,6 @@ export const workerMainLoop = async (startupData) => {
         },
         isMain: false,
         thread,
-        debug,
         startTime: startAt,
     });
     const lockState = lock2({
@@ -106,8 +114,10 @@ export const workerMainLoop = async (startupData) => {
     const timers = workerOptions?.timers;
     const spinMicroseconds = timers?.spinMicroseconds ??
         Math.max(1, totalNumberOfThread) * 50;
-    const parkMs = timers?.parkMs ??
-        Math.max(1, totalNumberOfThread) * 50;
+    const parkMs = dbg !== undefined
+        ? Number.POSITIVE_INFINITY
+        : (timers?.parkMs ??
+            Math.max(1, totalNumberOfThread) * 50);
     const pauseSpin = (() => {
         const fn = typeof timers?.pauseNanoseconds === "number"
             ? whilePausing({ pauseInNanoseconds: timers.pauseNanoseconds })
@@ -123,6 +133,7 @@ export const workerMainLoop = async (startupData) => {
         thread,
         totalNumberOfThread,
     });
+    dbg?.envPhase("bootstrap");
     const listOfFunctions = await getFunctions({
         list,
         isWorker: true,
@@ -131,7 +142,9 @@ export const workerMainLoop = async (startupData) => {
         at,
         permission,
     });
-    assertWorkerImportsResolved({ debug, list, ids, names, listOfFunctions });
+    dbg?.envPhase("tasks");
+    dbg?.log("imports", `${listOfFunctions.length} task(s) from ${list.map((spec) => spec.split(/[\\/]/).pop() || spec).join(", ")}`);
+    assertWorkerImportsResolved({ list, ids, names, listOfFunctions });
     const abortSignals = abortSignalSAB
         ? signalAbortFactory({
             sab: abortSignalSAB,
@@ -170,7 +183,7 @@ export const workerMainLoop = async (startupData) => {
     let awaitingSpins = 0;
     let lastAwaiting = 0;
     const MAX_AWAITING_MS = 10;
-    let wakeSeq = a_load(opView, 0);
+    let wakeToken = a_load(opView, 0);
     const scheduleMacro = () => {
         if (isInMacro)
             return;
@@ -195,15 +208,43 @@ export const workerMainLoop = async (startupData) => {
         }
         post2(null);
     };
-    const _enqueueLock = enqueueLock;
+    const traceSignals = dbg?.enabled("signals") === true;
     const _hasCompleted = hasCompleted;
-    const _writeBatch = writeBatch;
     const _hasPending = hasPending;
-    const _serviceBatchImmediate = serviceBatchImmediate;
     const _getAwaiting = getAwaiting;
     const _drainReturnReleases = drainReturnReleases;
     const _pauseSpin = pauseSpin;
-    const _pauseUntil = pauseUntil;
+    const _enqueueLock = traceSignals
+        ? () => {
+            const progressed = enqueueLock();
+            if (progressed) {
+                dbg.log("signals", "work from=host");
+            }
+            return progressed;
+        }
+        : enqueueLock;
+    const _writeBatch = traceSignals
+        ? (max) => {
+            const wrote = writeBatch(max);
+            if (wrote > 0)
+                dbg.log("signals", `result count=${wrote}`);
+            return wrote;
+        }
+        : writeBatch;
+    const _serviceBatchImmediate = traceSignals
+        ? () => {
+            const ran = serviceBatchImmediate();
+            if (ran > 0)
+                dbg.log("signals", `run count=${ran}`);
+            return ran;
+        }
+        : serviceBatchImmediate;
+    const _pauseUntil = traceSignals
+        ? (value, spinMicroseconds, parkMs) => {
+            dbg.log("signals", `idle token=${value}`);
+            pauseUntil(value, spinMicroseconds, parkMs);
+        }
+        : pauseUntil;
     const loop = () => {
         isInMacro = false;
         let progressed = true;
@@ -234,8 +275,8 @@ export const workerMainLoop = async (startupData) => {
                     _pauseSpin();
                     continue;
                 }
-                _pauseUntil(wakeSeq, spinMicroseconds, parkMs);
-                wakeSeq = a_load(opView, 0);
+                _pauseUntil(wakeToken, spinMicroseconds, parkMs);
+                wakeToken = a_load(opView, 0);
             }
         }
     };
@@ -249,6 +290,7 @@ export const workerMainLoop = async (startupData) => {
     }
     port1Any.start?.();
     port2.start?.();
+    dbg?.log("lifecycle", `ready: ${listOfFunctions.length} task(s) on thread ${thread}/${totalNumberOfThread}, entering dispatch loop`);
     scheduleMacro();
 };
 const isWorkerGlobalScope = () => {

package/src/worker/safety/startup.d.ts

@@ -1,17 +1,16 @@
 import { type SharedBufferSource } from "../../common/shared-buffer-region.js";
-import type { DebugOptions, LockBuffers } from "../../types.js";
+import type { LockBuffers } from "../../types.js";
 type SharedMemoryBootData = {
     sab: SharedBufferSource | undefined;
     lock: LockBuffers | undefined;
     returnLock: LockBuffers | undefined;
 };
 type ImportedFunctionsState = {
-    debug: DebugOptions | undefined;
     list: string[];
     ids: number[];
     names?: string[];
     listOfFunctions: readonly unknown[];
 };
 export declare const assertWorkerSharedMemoryBootData: ({ sab, lock, returnLock }: SharedMemoryBootData) => void;
-export declare const assertWorkerImportsResolved: ({ debug, list, ids, names, listOfFunctions }: ImportedFunctionsState) => void;
+export declare const assertWorkerImportsResolved: ({ list, ids, names, listOfFunctions }: ImportedFunctionsState) => void;
 export {};

package/src/worker/safety/startup.js

@@ -17,10 +17,7 @@ export const assertWorkerSharedMemoryBootData = ({ sab, lock, returnLock }) => {
         throw new Error("worker missing return lock SABs");
     }
 };
-export const assertWorkerImportsResolved = ({ debug, list, ids, names, listOfFunctions }) => {
-    if (debug?.logImportedUrl === true) {
-        console.log(list);
-    }
+export const assertWorkerImportsResolved = ({ list, ids, names, listOfFunctions }) => {
     if (listOfFunctions.length > 0 &&
         (names === undefined || listOfFunctions.length === names.length))
         return;

package/src/worker/timers.js

@@ -50,7 +50,7 @@ const isPlainNodeWindows = runtimeGlobals.process?.platform === "win32" &&
 // full parkMs (up to seconds); the long park with no wake is what made CI
 // runners appear to hang. The native wait already polls internally, so this is
 // just bounding each poll slice.
-const nativeWaitTimeoutMs = (parkMs) => isPlainNodeWindows ? 1 : parkMs ?? 60;
+const nativeWaitTimeoutMs = (parkMs) => isPlainNodeWindows ? 1 : Number.isFinite(parkMs) ? parkMs : 60;
 export const whilePausing = ({ pauseInNanoseconds }) => {
     const forNanoseconds = pauseInNanoseconds ?? DEFAULT_PAUSE_TIME;
     if (!a_pause || forNanoseconds <= 0)
@@ -101,10 +101,15 @@ export const sleepUntilChanged = ({ at, opView, pauseInNanoseconds, rxStatus, tx
         else if (useSharedMemoryWait &&
             a_wait &&
             opView.buffer instanceof SharedArrayBuffer) {
+            // This is the notify-able path: a host Atomics.notify on opView wakes it.
+            // An infinite parkMs (debug) is intentional here — the worker blocks until
+            // a real signal instead of re-polling on a timeout.
             a_wait(opView, at, value, parkMs ?? 60);
         }
         else if (a_wait && waitFallbackView) {
-            a_wait(waitFallbackView, 0, 0, parkMs ?? 1);
+            // waitFallbackView is never notified — this wait only ever times out and
+            // re-polls, so it must stay finite or the worker would hang forever.
+            a_wait(waitFallbackView, 0, 0, Number.isFinite(parkMs) ? parkMs : 1);
         }
         a_store(rxStatus, 0, 1);
     };