knitting 0.1.52 → 0.1.54

package/README.md

@@ -11,18 +11,22 @@
 [![Deno](https://img.shields.io/badge/deno-2%2B-000000?logo=deno&logoColor=white)](https://deno.com/)
 [![Bun](https://img.shields.io/badge/bun-1%2B-f472b6?logo=bun&logoColor=white)](https://bun.sh/)
 
-Knitting is a worker pool over a shared-memory IPC runtime for Node.js, Deno,
-and Bun. Our mission is to make JavaScript a multicore language with real
-inter-runtime communication.
+Website: [knittingdocs.netlify.app](https://knittingdocs.netlify.app/)
 
-Thanks to its memory design, it can be 5x to 25x faster than using
-`postMessages` , bypassing OS socket communication entirely with a novel
-protocol written from scratch.
+If you are an agent trying to understand the project, the website also serves an
+[`llms.txt`](https://knittingdocs.netlify.app/llms.txt) file with a compact map
+of the docs.
 
-Use it for parts of your program that should run in different environments, such
-as CPU-intensive tasks, small jobs, runtime-isolated tasks, custom isolation for
-workers in Docker or bwrap environments, long-running tools, or any processes
-that require speed and type flexibility.
+Knitting is a worker pool built on shared-memory IPC for Node.js, Deno, and Bun.
+It lets you call work running on other threads or processes as if it were a
+normal async function.
+
+Because calls move through shared memory instead of `postMessage` or sockets,
+some workloads can be 5x to 25x faster than the usual worker-message path.
+
+Use it when part of your program should run somewhere else: CPU-heavy work,
+bursty small jobs, runtime-isolated code, Docker or bwrap workers, long-running
+tools, or cross-runtime process work that still needs to be fast and typed.
 
 You export a function or task, spin up a pool, and call it like a normal async
 function:
@@ -31,29 +35,28 @@ function:
 const result = await pool.call.resizeImage(file);
 ```
 
-So you only have to take care of 4 things:
+Most of the time, you only have to take care of four things:
 
 - Export a function or task
 - Create a pool
 - Call it
 - Let `using` or `shutdown()` close the pool
 
-Under the hood, we take care of scheduling and orchestration across worker
-threads or separate processes, also handling signals, timeouts, life cycles,
-memory allocation, garbage collection, and cross-runtime memory over the
-processes.
+Under the hood, Knitting handles scheduling across worker threads or separate
+processes, plus signals, timeouts, lifecycles, memory allocation, cleanup, and
+cross-runtime shared memory.
 
 ## Why use it?
 
-- Easy to use: Have a multithreaded environment or process with few lines of
-  code.
-- Great type support: pass primitives, JSON, Promise of these, and special types
-  (typed arrays, `Node Buffer`, `Envelope`, and `ProcessSharedBuffer`).
+- Easy to use: spin up threads or processes with a small API.
+- Great type support: pass primitives, JSON, promises of those values, and
+  special types like typed arrays, `Node Buffer`, `Envelope`, and
+  `ProcessSharedBuffer`.
 - Runtime flexibility: the same API across Node.js, Deno, and Bun.
 - Worker choices: use threads for fast pools or processes for stronger
   isolation.
-- All out-of-the-box experiences: strict-by-default permissions, payload-size
-  limits, task timeouts, abort-aware tasks, and worker hard timeouts.
+- Practical defaults: strict worker permissions, payload-size limits, task
+  timeouts, abort-aware tasks, and worker hard timeouts.
 
 ## Requirements
 
@@ -96,9 +99,9 @@ if (isMain) {
 }
 ```
 
-The `isMain` guard when the same module is loaded by workers or process. Export
-exposes the tasks or functions at module scope, so knitting maps down the
-imports, then use and use the pool only from the main program.
+Use the `isMain` guard when a module can be loaded by both the host and its
+workers. Export tasks at module scope so Knitting can find them, then create and
+use the pool only from the main program.
 
 ## The Mental Model
 
@@ -335,9 +338,17 @@ 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.                                                                                                         |
+| `host.dispatcher`                 | Experimental host dispatcher topology: `"per-thread"` or `"serial-channel"`.                                                      |
+| `debug`                           | Enable diagnostics (`host`, `globals`, `signals`, `imports`, `lifecycle`) or use `KNITTING_DEBUG`.                                |
 | `source`                          | Worker source override for advanced runtimes.                                                                                     |
 
+Most users can leave `host.dispatcher` alone. The current default is
+experimental: Bun and single-worker pools use `"per-thread"`, while multi-worker
+Node/Deno pools use `"serial-channel"` because it tends to behave well for
+bursty HTTP-style fan-out. If you are tuning a server or comparing runtimes, you
+can force either mode with `KNITTING_DISPATCHER=per-thread` or
+`KNITTING_DISPATCHER=serial-channel`.
+
 ### Worker bootstrap
 
 Use `worker.bootstrap` when a worker needs privileged setup before task modules

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knitting",
-  "version": "0.1.52",
+  "version": "0.1.54",
   "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,52 @@ 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 { ChannelHandler } from "./runtime/dispatcher.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 +130,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 +185,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 +259,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");
     }
@@ -214,6 +284,26 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
             `(import { isMain } from "knitting") so only the main program starts ` +
             `the pool.`);
     }
+    const dispatcherEnv = nodeProcess?.env?.KNITTING_DISPATCHER;
+    const explicitDispatcher = host?.dispatcher ??
+        (dispatcherEnv === "serial-channel" || dispatcherEnv === "per-thread"
+            ? dispatcherEnv
+            : undefined);
+    const autoDispatcher = (() => {
+        // Experimental default for HTTP-style bursts: Bun still favors direct
+        // per-thread channels, while Node/Deno multi-worker pools favor one shared
+        // macro channel over the per-lane dispatcher checks.
+        if (RUNTIME === "bun")
+            return "per-thread";
+        if ((threads ?? 1) <= 1)
+            return "per-thread";
+        return "serial-channel";
+    })();
+    const dispatcher = explicitDispatcher ?? autoDispatcher;
+    const serialChannel = dispatcher === "serial-channel";
+    const serialDispatcherChannel = serialChannel
+        ? new ChannelHandler()
+        : undefined;
     let workers = Array.from({
         length: threads ?? 1,
     }).map((_, thread) => spawnWorkerContext({
@@ -223,21 +313,67 @@ 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,
+        sharedChannelHandler: serialDispatcherChannel,
     }));
+    const sharedDispatcherChannel = serialDispatcherChannel;
+    if (serialChannel) {
+        const channel = serialDispatcherChannel;
+        const checks = workers.map((context) => context.dispatcherCheck);
+        let serialScheduled = false;
+        let serialInFlight = false;
+        let serialRerun = false;
+        const runSerialChecks = () => {
+            if (serialInFlight) {
+                serialRerun = true;
+                return;
+            }
+            serialInFlight = true;
+            do {
+                serialRerun = false;
+                serialScheduled = false;
+                for (let index = 0; index < checks.length; index++) {
+                    const check = checks[index];
+                    if (check.isRunning !== true)
+                        check.isRunning = true;
+                    check();
+                }
+            } while (serialRerun);
+            serialInFlight = false;
+        };
+        const scheduleSerialCheck = () => {
+            if (serialInFlight) {
+                serialRerun = true;
+                return;
+            }
+            if (serialScheduled)
+                return;
+            serialScheduled = true;
+            Promise.resolve().then(runSerialChecks);
+        };
+        channel.open(runSerialChecks);
+        workers.forEach((context) => {
+            const wake = context.laneWake;
+            context.bindSend(() => {
+                scheduleSerialCheck();
+                wake();
+            });
+        });
+        hostDebug?.log(`dispatcher=serial-channel lanes=${checks.length}`);
+    }
+    else {
+        hostDebug?.log(`dispatcher=per-thread lanes=${workers.length}`);
+    }
     if (usingInliner) {
         const mainThread = createInlineExecutor({
             tasks: listOfFunctions,
@@ -271,7 +407,9 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
             return closePromise;
         closing = true;
         closePromise = Promise.allSettled(workers.map((context) => context.kills()))
-            .then(() => undefined);
+            .then(() => {
+            sharedDispatcherChannel?.close();
+        });
         return closePromise;
     };
     const wrapGuardedInvoke = ({ invoke, taskName, }) => (args) => {

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;