knitting 0.1.70 → 0.1.73

package/src/runtime/worker-common.js

@@ -6,24 +6,29 @@ const execFlagKey = (flag) => flag.split("=", 1)[0];
 const NODE_PERMISSION_EXEC_FLAGS = new Set([
     "--permission",
     "--experimental-permission",
+    "--experimental-config-file",
+    "--experimental-default-config-file",
     "--allow-fs-read",
     "--allow-fs-write",
+    "--allow-fs-vfs",
     "--allow-worker",
     "--allow-child-process",
+    "--allow-env",
     "--allow-net",
     "--allow-addons",
     "--allow-ffi",
     "--allow-wasi",
+    "--allow-inspector",
+    "--allow-openssl-store",
 ]);
 const NODE_WORKER_SAFE_EXEC_FLAGS = new Set([
     "--experimental-ffi",
     "--experimental-transform-types",
-    "--expose-gc",
     "--no-warnings",
     ...NODE_PERMISSION_EXEC_FLAGS,
 ]);
 const isNodeWorkerSafeExecFlag = (flag) => NODE_WORKER_SAFE_EXEC_FLAGS.has(execFlagKey(flag));
-const isNodePermissionExecFlag = (flag) => NODE_PERMISSION_EXEC_FLAGS.has(execFlagKey(flag));
+export const isNodePermissionExecFlag = (flag) => NODE_PERMISSION_EXEC_FLAGS.has(execFlagKey(flag));
 export const toWorkerSafeExecArgv = (flags) => {
     if (!flags || flags.length === 0)
         return undefined;
@@ -40,6 +45,7 @@ export const toWorkerSafeExecArgv = (flags) => {
     }
     return deduped;
 };
+/** Preserve process-worker runtime flags while replacing inherited permissions. */
 export const toWorkerCompatExecArgv = (flags) => {
     const safe = toWorkerSafeExecArgv(flags);
     if (!safe || safe.length === 0)
@@ -47,6 +53,26 @@ export const toWorkerCompatExecArgv = (flags) => {
     const compat = safe.filter((flag) => !isNodePermissionExecFlag(flag));
     return compat.length > 0 ? compat : undefined;
 };
+const droppedExecArgvWarnings = new Set();
+/**
+ * Warn once per flag set when a `workerExecArgv` flag the caller asked for did
+ * not reach the worker thread, instead of dropping it silently.
+ */
+export const warnDroppedWorkerExecArgv = (requested, applied) => {
+    if (!requested || requested.length === 0)
+        return;
+    const kept = new Set(applied ?? []);
+    const dropped = requested.filter((flag) => !kept.has(flag));
+    if (dropped.length === 0)
+        return;
+    const key = dropped.join(" ");
+    if (droppedExecArgvWarnings.has(key))
+        return;
+    droppedExecArgvWarnings.add(key);
+    console.warn(`knitting: workerExecArgv ${dropped.join(", ")} cannot be applied to a ` +
+        `worker thread and was dropped. V8 and process-wide flags must be ` +
+        `passed to the host process instead.`);
+};
 const isPlainRecord = (value) => {
     if (value === null || typeof value !== "object")
         return false;

package/src/types.d.ts

@@ -28,6 +28,12 @@ type WorkerData = {
     thread: number;
     totalNumberOfThread: number;
     debug?: DebugOptions;
+    /**
+     * Host's debug zero as `performance.timeOrigin + performance.now()` (Unix
+     * epoch ms), so worker debug clocks line up with the host's. Set only when
+     * debug is requested.
+     */
+    debugEpoch?: number;
     startAt: number;
     workerOptions?: WorkerSettings;
     at: number[];
@@ -50,8 +56,8 @@ type WorkerData = {
         consumers: number;
         consumerId: number;
         regionLanes: number;
-        /** Region mutual-exclusion discipline; see `DispatcherSettings.stealClaim`. */
-        claim?: "dekker" | "cas-mask";
+        /** Claim discipline; see `DispatcherSettings.stealClaim`. */
+        claim?: "dekker" | "ticket";
     };
 };
 type UnsafeOptions = {
@@ -173,12 +179,16 @@ type SingleTaskPool<A extends TaskInput = Args, B extends Args = Args, AS extend
     shutdown: (delayMs?: number) => Promise<void>;
     /** Starts shutdown at scope exit. Use `shutdown()` when you must await it. */
     [Symbol.dispose]: () => void;
+    /** `await using` awaits worker teardown at scope exit. */
+    [Symbol.asyncDispose]: () => Promise<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;
+    /** `await using` awaits worker teardown at scope exit. */
+    [Symbol.asyncDispose]: () => Promise<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.
@@ -214,8 +224,8 @@ type Balancer = BalancerStrategy | {
      */
     strategy?: BalancerStrategy;
 };
-/** Debug namespaces for host setup, worker state, imports, globals, and lifecycle. */
-type DebugNamespace = "host" | "globals" | "signals" | "imports" | "lifecycle";
+/** Debug namespaces for host setup, worker state, imports, globals, lifecycle, and steal claims. */
+type DebugNamespace = "host" | "globals" | "signals" | "imports" | "lifecycle" | "steal";
 type DebugFlags = {
     [Namespace in DebugNamespace]?: boolean;
 };
@@ -340,7 +350,10 @@ type WorkerTimers = {
      */
     spinMicroseconds?: number;
     /**
-     * Atomics.wait timeout when parked (milliseconds).
+     * Atomics.wait timeout when parked (milliseconds). Defaults to 1000 for
+     * thread workers, which the host wakes on every publish, so the timeout is
+     * only a safety net; 1 for process workers, most of which only rediscover
+     * work when it expires.
      */
     parkMs?: number;
     /**
@@ -383,8 +396,13 @@ type DispatcherSettings = {
      * tasks; Dekker requires at least one spare region per live consumer.
      */
     stealRegionLanes?: number;
-    /** Region-claim discipline: per-consumer Dekker intents or a shared CAS mask. */
-    stealClaim?: "dekker" | "cas-mask";
+    /**
+     * Publication-ordered tickets (`"ticket"`, the default) or Dekker regions
+     * (`"dekker"`). Unrecognised values are rejected rather than defaulted, so a
+     * removed discipline such as `cas-mask` fails at pool creation. Ticket pools
+     * reject pending and future calls on worker failure.
+     */
+    stealClaim?: "dekker" | "ticket";
 };
 type CreatePool = {
     /** Number of workers. Default: 1. */
@@ -412,14 +430,20 @@ type CreatePool = {
      */
     host?: DispatcherSettings;
     /**
-     * Extra Node.js execArgv flags for worker threads (e.g. ["--expose-gc"]).
-     * Defaults to process.execArgv plus "--expose-gc" when allowed.
+     * Extra Node.js execArgv flags for worker threads (e.g. ["--no-warnings"]).
+     * Defaults to compatible flags from process.execArgv. Node permission flags
+     * are replaced by the resolved `permission` policy.
+     *
+     * Node rejects V8 and process-wide flags (`--expose-gc`,
+     * `--max-old-space-size`, ...). Unsupported caller flags are dropped with a
+     * warning. Permission flags are never dropped to start an unpermissioned
+     * thread worker; pool creation fails if Node cannot apply them.
      */
     workerExecArgv?: string[];
     /**
      * Runtime permission protocol.
-     * Omit to use strict defaults with `allowImport: true`; worker console is
-     * quiet unless `permission: { console: true }`.
+     * Omit to use strict defaults with `allowImport: true`. `console` is
+     * accepted but not enforced: worker console output is always forwarded.
      *
      * Task code cannot terminate the host: process/Deno exit APIs are blocked.
      * Use `"strict"` (default for object mode) or `"unsafe"`.

package/src/worker/loop.js

@@ -13,12 +13,14 @@ import { getFunctions } from "./task-loader.js";
 import { IS_BUN_WINDOWS, pauseGeneric, sleepUntilChanged, whilePausing, } from "./timers.js";
 import { IS_ANDROMEDA, RUNTIME, SET_IMMEDIATE } from "../common/runtime.js";
 import { getNodeProcess } from "../common/node-compat.js";
-import { assertWorkerImportsResolved, assertWorkerSharedMemoryBootData, installPerformanceNowGuard, installTerminationGuard, installUnhandledRejectionSilencer, scrubWorkerDataSensitiveBuffers, } from "./safety/index.js";
+import { assertWorkerImportsResolved, assertWorkerSharedMemoryBootData, installPerformanceNowGuard, installTerminationGuard, installUnhandledRejectionSilencer, reportSilencedRejections, scrubWorkerDataSensitiveBuffers, } from "./safety/index.js";
 import { signalAbortFactory } from "../shared/abortSignal.js";
 import { runWorkerBootstrap } from "./bootstrap.js";
 import { getProcessWorkerNativeWaitU32, installProcessWorkerBootstrap, } from "./process-worker-bootstrap.js";
 import { resolveDebugNamespaces } from "../debug/gate.js";
 const WORKER_FATAL_MESSAGE_KEY = "__knittingWorkerFatal";
+// Park timeout while finished results wait for return slots (see the loop).
+const BLOCKED_RETURN_PARK_MS = 1;
 const reportWorkerStartupFatal = (error) => {
     const message = String(error?.message ?? error);
     const payload = {
@@ -59,17 +61,22 @@ export const workerMainLoop = async (startupData) => {
     installTerminationGuard();
     installUnhandledRejectionSilencer();
     installPerformanceNowGuard();
-    const { debug, sab, thread, startAt, workerOptions, lock, returnLock, abortSignalSAB, abortSignalMax, payloadConfig, sharedReturn, permission, notifyOnHostPublish, processCompletionDoorbell, denoCompletionDoorbell, nodeCompletionDoorbell, totalNumberOfThread, list, ids, names, at, steal, } = startupData;
+    const { debug, debugEpoch, sab, thread, startAt, workerOptions, lock, returnLock, abortSignalSAB, abortSignalMax, payloadConfig, sharedReturn, permission, notifyOnHostPublish, processCompletionDoorbell, denoCompletionDoorbell, nodeCompletionDoorbell, totalNumberOfThread, list, ids, names, at, steal, } = startupData;
     scrubWorkerDataSensitiveBuffers(startupData);
     assertWorkerSharedMemoryBootData({ sab, lock, returnLock });
     const debugNamespaces = resolveDebugNamespaces(debug);
     const dbg = debugNamespaces.size > 0
-        ? await import("../debug/handle.ts").then((module) => module.initDebug({
+        ? await import("../debug/handle.js").then((module) => module.initDebug({
             name: `w${thread}`,
             runtime: RUNTIME,
             namespaces: debugNamespaces,
+            epoch: debugEpoch,
         }))
         : undefined;
+    if (dbg?.enabled("lifecycle") === true) {
+        // Detached task promises reject silently otherwise (see the silencer).
+        reportSilencedRejections((reason) => dbg.log("lifecycle", `unhandled rejection silenced: ${reason instanceof Error ? reason.stack ?? reason.message : String(reason)}`));
+    }
     // Andromeda cannot parse enums.
     const Comment = {
         thisIsAHint: 0,
@@ -97,6 +104,10 @@ export const workerMainLoop = async (startupData) => {
         consumerId: steal?.consumerId,
         regionLanes: steal?.regionLanes,
         stealClaim: steal?.claim,
+        // Undefined unless `steal` is traced, so the claim path stays untouched.
+        traceClaim: steal !== undefined && dbg?.enabled("steal") === true
+            ? (message) => dbg.log("steal", message)
+            : undefined,
     });
     const notifyDenoHost = createDenoCompletionNotifier(denoCompletionDoorbell);
     const notifyNodeHost = createNodeCompletionNotifier(nodeCompletionDoorbell);
@@ -342,7 +353,9 @@ export const workerMainLoop = async (startupData) => {
                     } while (txStatus[Comment.thisIsAHint] === 1);
                     continue;
                 }
-                _pauseUntil(wakeToken, spinMicroseconds, parkMs);
+                // Results that could not be written wait on the host freeing return
+                // slots, which rings no worker in particular: keep that park short.
+                _pauseUntil(wakeToken, spinMicroseconds, _hasCompleted() ? Math.min(parkMs, BLOCKED_RETURN_PARK_MS) : parkMs);
                 wakeToken = a_load(opView, 0);
             }
         }

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

@@ -1,4 +1,4 @@
-export { installTerminationGuard, installUnhandledRejectionSilencer, } from "./process.js";
+export { installTerminationGuard, installUnhandledRejectionSilencer, reportSilencedRejections, } from "./process.js";
 export { installPerformanceNowGuard } from "./performance.js";
 export { scrubWorkerDataSensitiveBuffers } from "./worker-data.js";
 export { assertWorkerSharedMemoryBootData, assertWorkerImportsResolved, } from "./startup.js";

package/src/worker/safety/index.js

@@ -1,4 +1,4 @@
-export { installTerminationGuard, installUnhandledRejectionSilencer, } from "./process.js";
+export { installTerminationGuard, installUnhandledRejectionSilencer, reportSilencedRejections, } from "./process.js";
 export { installPerformanceNowGuard } from "./performance.js";
 export { scrubWorkerDataSensitiveBuffers } from "./worker-data.js";
 export { assertWorkerSharedMemoryBootData, assertWorkerImportsResolved, } from "./startup.js";

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

@@ -1,2 +1,4 @@
 export declare const installTerminationGuard: () => void;
+/** Debug hook: see what the silencer below swallows. Unset by default. */
+export declare const reportSilencedRejections: (report: ((reason: unknown) => void) | undefined) => void;
 export declare const installUnhandledRejectionSilencer: () => void;

package/src/worker/safety/process.js

@@ -66,6 +66,11 @@ export const installTerminationGuard = () => {
     }
     proc.__knittingTerminationGuard = true;
 };
+let reportSilencedRejection;
+/** Debug hook: see what the silencer below swallows. Unset by default. */
+export const reportSilencedRejections = (report) => {
+    reportSilencedRejection = report;
+};
 export const installUnhandledRejectionSilencer = () => {
     const proc = getNodeProcess();
     if (!proc || typeof proc.on !== "function") {
@@ -75,5 +80,7 @@ export const installUnhandledRejectionSilencer = () => {
         return;
     proc.__knittingUnhandledRejectionSilencer = true;
     // Worker task code may create detached promises; keep workers alive.
-    proc.on("unhandledRejection", () => { });
+    proc.on("unhandledRejection", (reason) => {
+        reportSilencedRejection?.(reason);
+    });
 };

package/src/worker/safety/startup.js

@@ -21,10 +21,15 @@ export const assertWorkerImportsResolved = ({ list, ids, names, listOfFunctions
     if (listOfFunctions.length > 0 &&
         (names === undefined || listOfFunctions.length === names.length))
         return;
-    console.log(list);
-    console.log(ids);
-    if (names !== undefined)
-        console.log(names);
-    console.log(listOfFunctions);
-    throw new Error("No imports were found.");
+    const found = new Set(listOfFunctions.map((entry) => entry?.name));
+    const missing = (names ?? []).filter((name) => !found.has(name));
+    const tasks = missing.length > 0
+        ? ` Missing task export(s): ${missing.join(", ")}.`
+        : "";
+    const modules = list.length > 0 ? ` Looked in: ${list.join(", ")}.` : "";
+    throw new Error(`No imports were found.${tasks}${modules}` +
+        " Workers re-import each listed module and look tasks up by export" +
+        " name: a bare function must be exported from the module that calls" +
+        " createPool, and a bundle that inlines task modules drops their" +
+        " exports.");
 };

package/src/worker/timers.js

@@ -2,10 +2,24 @@
 const Comment = {
     thisIsAHint: 0,
 };
+// A full collection costs milliseconds. Run on every idle entry, it made each
+// sequential call ~1000x slower under --expose-gc; once a second keeps the
+// idle collection without paying it per call.
+const IDLE_GC_INTERVAL_MS = 1000;
 const maybeGc = (() => {
     const host = globalThis;
-    const gc = typeof host.gc === "function"
-        ? (() => host.gc())
+    // Capture the function itself: the global is deleted below, so reading
+    // `host.gc` at call time would throw on the first idle pass.
+    const exposedGc = host.gc;
+    let lastGcAt = -Infinity;
+    const gc = typeof exposedGc === "function"
+        ? (() => {
+            const now = performance.now();
+            if (now - lastGcAt < IDLE_GC_INTERVAL_MS)
+                return;
+            lastGcAt = now;
+            exposedGc();
+        })
         : undefined;
     if (gc) {
         try {
@@ -82,7 +96,6 @@ export const sleepUntilChanged = ({ at, opView, pauseInNanoseconds, rxStatus, tx
         };
     return (value, spinMicroseconds, parkMs) => {
         const until = p_now() + (spinMicroseconds / 1000);
-        maybeGc();
         let spinChecks = 0;
         while (true) {
             if (a_load(opView, at) !== value ||
@@ -94,9 +107,18 @@ export const sleepUntilChanged = ({ at, opView, pauseInNanoseconds, rxStatus, tx
             if ((spinChecks++ & 63) === 0 && p_now() >= until)
                 break;
         }
+        // Collect only once the spin found nothing, then re-check before parking.
+        maybeGc();
         if (tryProgress())
             return;
         a_store(rxStatus, 0, 0);
+        // The other half of the host's post-publish check: a publication that
+        // landed before rxStatus cleared is visible now, and one after it finds
+        // rxStatus clear and rings.
+        if (a_load(opView, at) !== value || tryProgress()) {
+            a_store(rxStatus, 0, 1);
+            return;
+        }
         if (nativeWaitU32 !== undefined) {
             nativeWaitU32(opView.buffer, opView.byteOffset + (at * Int32Array.BYTES_PER_ELEMENT), value >>> 0, nativeWaitTimeoutMs(parkMs));
         }