knitting 0.1.46 → 0.1.50

package/src/shared/abortSignal.js

@@ -111,7 +111,7 @@ export const signalAbortFactory = ({ sab, maxSignals, }) => {
 };
 export class OneShotDeferred {
     #triggered = false;
-    constructor(deferred, onSettle) {
+    constructor(deferred, onSettle, onEmptyReject) {
         const settleOnce = (fn) => (...args) => {
             if (this.#triggered)
                 return;
@@ -121,6 +121,14 @@ export class OneShotDeferred {
         };
         deferred.resolve = settleOnce(deferred.resolve);
         deferred.reject = settleOnce(deferred.reject);
-        deferred.promise.reject = deferred.reject;
+        deferred.promise.reject = (reason) => {
+            if (this.#triggered)
+                return;
+            if (reason === undefined && onEmptyReject !== undefined) {
+                onEmptyReject();
+                return;
+            }
+            deferred.reject(reason);
+        };
     }
 }

package/src/types.d.ts

@@ -164,8 +164,34 @@ type DebugOptions = {
     logHref?: boolean;
     logImportedUrl?: boolean;
 };
+type WorkerBootstrapContext = {
+    readonly thread: number;
+    readonly totalNumberOfThread: number;
+    readonly runtime: "node" | "deno" | "bun" | "unknown";
+};
+type WorkerBootstrapFunction<Data = unknown> = (data: Data, context: WorkerBootstrapContext) => MaybePromise<void>;
+type WorkerBootstrapOptions<Data = unknown> = {
+    /**
+     * Module imported inside the worker before task modules are imported.
+     * Relative paths are resolved from the `createPool(...)` caller.
+     */
+    href: string;
+    /**
+     * Exported bootstrap function name. Defaults to `"default"`.
+     */
+    name?: string;
+    /**
+     * Structured data passed to the bootstrap function.
+     */
+    data?: Data;
+};
 type WorkerSettings = {
     resolveAfterFinishingAll?: true;
+    /**
+     * Privileged async worker hook that runs once before task modules import.
+     * Use it to shape the worker environment before user task code loads.
+     */
+    bootstrap?: WorkerBootstrapOptions;
     /**
      * Experimental worker runtime.
      * "thread" uses Worker/worker_threads. "process" spawns another JavaScript
@@ -173,17 +199,31 @@ type WorkerSettings = {
      */
     runtime?: "thread" | "process";
     /**
-     * Runtime executable to use when runtime is "process". Defaults to "bun".
+     * Runtime executable to use when runtime is "process". Defaults to "deno".
      */
     processRuntime?: "bun" | "deno" | "node";
     /**
      * Command argv to prepend before the process worker runtime command.
-     * Useful for wrappers such as systemd-run, cgexec, nice, or taskset.
+     * Useful for wrappers such as systemd-run, cgexec, nice, taskset, or
+     * docker. Knitting appends the runtime command after this prefix.
      *
      * Example:
      * ["systemd-run", "--scope", "-p", "MemoryMax=500M", "-p", "CPUQuota=25%"]
+     *
+     * With containers, use processSharedMemory: "named", share the IPC
+     * namespace, mount the worker files at the same path, and forward
+     * KNITTING_PROCESS_WORKER plus KNITTING_PROCESS_WORKER_BOOT.
      */
     processCommandPrefix?: string[];
+    /**
+     * How process workers discover their shared-memory control channel.
+     *
+     * "inherit" keeps the POSIX fd-inheritance path and is the default outside
+     * Windows. "named" creates an OS-named shared-memory object that wrappers
+     * such as containers can reopen by name when they share the same IPC
+     * namespace.
+     */
+    processSharedMemory?: ProcessSharedMemoryMode | ProcessSharedMemorySettings;
     timers?: WorkerTimers;
     /**
      * Hard task execution timeout in milliseconds.
@@ -191,6 +231,12 @@ type WorkerSettings = {
      */
     hardTimeoutMs?: number;
 };
+type ProcessSharedMemoryMode = "inherit" | "named";
+type ProcessSharedMemorySettings = {
+    mode?: ProcessSharedMemoryMode;
+    namePrefix?: string;
+    unlinkOnShutdown?: boolean;
+};
 type WorkerTimers = {
     /**
      * Busy-spin budget before parking (microseconds).
@@ -277,7 +323,7 @@ type CreatePool = {
     debug?: DebugOptions;
     source?: string;
 };
-export type { WorkerCall as WorkerCall, WorkerInvoke as WorkerInvoke, WorkerContext as WorkerContext, CreateContext as CreateContext, WorkerData as WorkerData, LockBuffers as LockBuffers, ValidInput as ValidInput, Args as Args, MaybePromise as MaybePromise, TaskInput as TaskInput, TaskTimeout as TaskTimeout, TaskFn as TaskFn, AbortSignalConfig as AbortSignalConfig, AbortSignalOption as AbortSignalOption, AbortSignalMethods as AbortSignalMethods, AbortSignalToolkit as AbortSignalToolkit, Composed as Composed, tasks as tasks, ComposedWithKey as ComposedWithKey, FunctionMapType as FunctionMapType, FixPoint as FixPoint, ImportTaskOptions as ImportTaskOptions, SecondPart as SecondPart, SingleTaskPool as SingleTaskPool, Pool as Pool, ReturnFixed as ReturnFixed, External as External, Inliner as Inliner, BalancerStrategy as BalancerStrategy, Balancer as Balancer, DebugOptions as DebugOptions, WorkerSettings as WorkerSettings, WorkerTimers as WorkerTimers, DispatcherSettings as DispatcherSettings, CreatePool as CreatePool, PayloadBufferMode as PayloadBufferMode, PayloadBufferOptions as PayloadBufferOptions, PermissionProtocol as PermissionProtocol, PermissionProtocolInput as PermissionProtocolInput, ResolvedPermissionProtocol as ResolvedPermissionProtocol, Envelope as Envelope, SharedBufferTextCompat as SharedBufferTextCompat, LockBufferTextCompat as LockBufferTextCompat, SharedBufferRegion as SharedBufferRegion, SharedBufferSource as SharedBufferSource, };
+export type { WorkerCall as WorkerCall, WorkerInvoke as WorkerInvoke, WorkerContext as WorkerContext, CreateContext as CreateContext, WorkerData as WorkerData, LockBuffers as LockBuffers, ValidInput as ValidInput, Args as Args, MaybePromise as MaybePromise, TaskInput as TaskInput, TaskTimeout as TaskTimeout, TaskFn as TaskFn, AbortSignalConfig as AbortSignalConfig, AbortSignalOption as AbortSignalOption, AbortSignalMethods as AbortSignalMethods, AbortSignalToolkit as AbortSignalToolkit, Composed as Composed, tasks as tasks, ComposedWithKey as ComposedWithKey, FunctionMapType as FunctionMapType, FixPoint as FixPoint, ImportTaskOptions as ImportTaskOptions, SecondPart as SecondPart, SingleTaskPool as SingleTaskPool, Pool as Pool, ReturnFixed as ReturnFixed, External as External, Inliner as Inliner, BalancerStrategy as BalancerStrategy, Balancer as Balancer, DebugOptions as DebugOptions, WorkerBootstrapContext as WorkerBootstrapContext, WorkerBootstrapFunction as WorkerBootstrapFunction, WorkerBootstrapOptions as WorkerBootstrapOptions, WorkerSettings as WorkerSettings, ProcessSharedMemoryMode as ProcessSharedMemoryMode, ProcessSharedMemorySettings as ProcessSharedMemorySettings, WorkerTimers as WorkerTimers, DispatcherSettings as DispatcherSettings, CreatePool as CreatePool, PayloadBufferMode as PayloadBufferMode, PayloadBufferOptions as PayloadBufferOptions, PermissionProtocol as PermissionProtocol, PermissionProtocolInput as PermissionProtocolInput, ResolvedPermissionProtocol as ResolvedPermissionProtocol, Envelope as Envelope, SharedBufferTextCompat as SharedBufferTextCompat, LockBufferTextCompat as LockBufferTextCompat, SharedBufferRegion as SharedBufferRegion, SharedBufferSource as SharedBufferSource, };
 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/worker/bootstrap.d.ts

@@ -0,0 +1,5 @@
+export declare const runWorkerBootstrap: ({ bootstrap, thread, totalNumberOfThread, }: {
+    bootstrap: unknown;
+    thread: number;
+    totalNumberOfThread: number;
+}) => Promise<void>;

package/src/worker/bootstrap.js

@@ -0,0 +1,78 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { RUNTIME } from "../common/runtime.js";
+import { toModuleUrl } from "../common/module-url.js";
+import { ProcessSharedBuffer } from "../connections/process-shared-buffer.js";
+const DEFAULT_BOOTSTRAP_EXPORT_NAME = "default";
+const isWorkerBootstrapOptions = (value) => {
+    if (!value || typeof value !== "object")
+        return false;
+    const candidate = value;
+    return typeof candidate.href === "string" &&
+        candidate.href.length > 0 &&
+        (candidate.name === undefined ||
+            (typeof candidate.name === "string" && candidate.name.length > 0));
+};
+const isProcessSharedBufferMetadata = (value) => {
+    try {
+        ProcessSharedBuffer.fromMetadata(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const reviveWorkerBootstrapValue = (value, seen = new WeakMap()) => {
+    if (isProcessSharedBufferMetadata(value)) {
+        return ProcessSharedBuffer.fromMetadata(value);
+    }
+    if (value === null || typeof value !== "object")
+        return value;
+    const existing = seen.get(value);
+    if (existing !== undefined)
+        return existing;
+    if (Array.isArray(value)) {
+        const out = [];
+        seen.set(value, out);
+        for (const item of value) {
+            out.push(reviveWorkerBootstrapValue(item, seen));
+        }
+        return out;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+        return value;
+    const out = {};
+    seen.set(value, out);
+    for (const [key, item] of Object.entries(value)) {
+        out[key] = reviveWorkerBootstrapValue(item, seen);
+    }
+    return out;
+};
+export const runWorkerBootstrap = async ({ bootstrap, thread, totalNumberOfThread, }) => {
+    if (bootstrap === undefined)
+        return;
+    if (!isWorkerBootstrapOptions(bootstrap)) {
+        throw new TypeError("worker.bootstrap must include a non-empty href");
+    }
+    const module = await import(__rewriteRelativeImportExtension(toModuleUrl(bootstrap.href)));
+    const name = bootstrap.name ?? DEFAULT_BOOTSTRAP_EXPORT_NAME;
+    const selected = module[name];
+    if (typeof selected !== "function") {
+        const available = Object.keys(module).join(", ");
+        throw new TypeError(`worker.bootstrap expected export "${name}" from "${bootstrap.href}" to be a function.` +
+            ` Available exports: ${available || "(none)"}`);
+    }
+    const context = Object.freeze({
+        thread,
+        totalNumberOfThread,
+        runtime: RUNTIME,
+    });
+    await selected(reviveWorkerBootstrapValue(bootstrap.data), context);
+};

package/src/worker/composable-runners.js

@@ -49,12 +49,6 @@ const readSignal = (slot) => {
     const signal = (encodedSignal - ABORT_SIGNAL_META_OFFSET) | 0;
     return signal >= 0 ? signal : NO_ABORT_SIGNAL;
 };
-const throwIfAborted = (signal, hasAborted) => {
-    if (signal === NO_ABORT_SIGNAL)
-        return;
-    if (hasAborted(signal))
-        throw new Error("Task aborted");
-};
 const makeToolkitCache = (hasAborted) => {
     const bySignal = [];
     return (signal) => {
@@ -86,7 +80,6 @@ export const composeWorkerRunner = ({ job, timeout, hasAborted, now, }) => {
     if (!timeout) {
         return (slot) => {
             const signal = readSignal(slot);
-            throwIfAborted(signal, hasAborted);
             if (signal === NO_ABORT_SIGNAL)
                 return job(slot.value);
             return job(slot.value, getToolkit(signal));
@@ -94,7 +87,6 @@ export const composeWorkerRunner = ({ job, timeout, hasAborted, now, }) => {
     }
     return (slot) => {
         const signal = readSignal(slot);
-        throwIfAborted(signal, hasAborted);
         const result = signal === NO_ABORT_SIGNAL
             ? job(slot.value)
             : job(slot.value, getToolkit(signal));

package/src/worker/loop.js

@@ -1,30 +1,18 @@
-import { RUNTIME_IS_MAIN_THREAD, RUNTIME_IS_PROCESS_WORKER, RUNTIME_PARENT_PORT, RUNTIME_PROCESS_WORKER_BOOT_ENV, RUNTIME_PROCESS_WORKER_BOOT_VERSION, RUNTIME_WORKER_DATA, createRuntimeMessageChannel, } from "../common/worker-runtime.js";
-import { isSharedBufferSource, } from "../common/shared-buffer-region.js";
+import { createRuntimeMessageChannel, RUNTIME_IS_MAIN_THREAD, RUNTIME_IS_PROCESS_WORKER, RUNTIME_PARENT_PORT, RUNTIME_WORKER_DATA, } from "../common/worker-runtime.js";
+import { isSharedBufferSource } from "../common/shared-buffer-region.js";
 import { isLockBufferTextCompat } from "../common/shared-buffer-text.js";
 import { createWorkerRxQueue } from "./rx-queue.js";
-import { createSharedMemoryTransport, } from "../ipc/transport/shared-memory.js";
+import { createSharedMemoryTransport } from "../ipc/transport/shared-memory.js";
 import { lock2 } from "../memory/lock.js";
 import { getFunctions } from "./task-loader.js";
-import { pauseGeneric, sleepUntilChanged, whilePausing, } from "./timers.js";
+import { pauseGeneric, sleepUntilChanged, whilePausing } from "./timers.js";
 import { RUNTIME, SET_IMMEDIATE } from "../common/runtime.js";
 import { getNodeProcess } from "../common/node-compat.js";
-import { getDefaultProcessSharedBufferPrimitives, ProcessSharedBuffer, setDefaultProcessSharedBufferPrimitives, } from "../connections/process-shared-buffer.js";
-import { createBunConnectionPrimitives } from "../connections/bun.js";
-import { createDenoConnectionPrimitives } from "../connections/deno.js";
-import { loadNodeFutexAddon } from "../connections/node.js";
-import { installTerminationGuard, installUnhandledRejectionSilencer, installPerformanceNowGuard, scrubWorkerDataSensitiveBuffers, assertWorkerSharedMemoryBootData, assertWorkerImportsResolved, } from "./safety/index.js";
+import { assertWorkerImportsResolved, assertWorkerSharedMemoryBootData, installPerformanceNowGuard, installTerminationGuard, installUnhandledRejectionSilencer, scrubWorkerDataSensitiveBuffers, } from "./safety/index.js";
 import { signalAbortFactory } from "../shared/abortSignal.js";
+import { runWorkerBootstrap } from "./bootstrap.js";
+import { getProcessWorkerNativeWaitU32, installProcessWorkerBootstrap, } from "./process-worker-bootstrap.js";
 const WORKER_FATAL_MESSAGE_KEY = "__knittingWorkerFatal";
-const getProcessWorkerNativeWaitU32 = () => {
-    if (!RUNTIME_IS_PROCESS_WORKER || RUNTIME !== "node")
-        return undefined;
-    try {
-        return loadNodeFutexAddon().waitU32;
-    }
-    catch {
-        return undefined;
-    }
-};
 const reportWorkerStartupFatal = (error) => {
     const message = String(error?.message ?? error);
     const payload = {
@@ -114,6 +102,11 @@ export const workerMainLoop = async (startupData) => {
     const a_store = Atomics.store;
     const a_load = Atomics.load;
     const nativeWaitU32 = getProcessWorkerNativeWaitU32();
+    await runWorkerBootstrap({
+        bootstrap: workerOptions?.bootstrap,
+        thread,
+        totalNumberOfThread,
+    });
     const listOfFunctions = await getFunctions({
         list,
         isWorker: true,
@@ -307,146 +300,18 @@ const installWorkerGlobalBootstrap = () => {
         start(data);
     };
 };
-const isProcessSharedBufferMetadata = (value) => {
-    try {
-        ProcessSharedBuffer.fromMetadata(value);
-        return true;
-    }
-    catch {
-        return false;
-    }
-};
-const isProcessWorkerWireLockBuffers = (value) => {
-    if (!value || typeof value !== "object")
-        return false;
-    const candidate = value;
-    return isProcessSharedBufferMetadata(candidate.headers) &&
-        isProcessSharedBufferMetadata(candidate.lockSector) &&
-        isProcessSharedBufferMetadata(candidate.payload) &&
-        isProcessSharedBufferMetadata(candidate.payloadSector) &&
-        (candidate.textCompat === undefined ||
-            isLockBufferTextCompat(candidate.textCompat));
-};
-const isProcessWorkerBootPayload = (value) => {
-    if (!value || typeof value !== "object")
-        return false;
-    const candidate = value;
-    const workerData = candidate.workerData;
-    return candidate.version === RUNTIME_PROCESS_WORKER_BOOT_VERSION &&
-        !!workerData &&
-        isProcessSharedBufferMetadata(workerData.sab) &&
-        Array.isArray(workerData.list) &&
-        Array.isArray(workerData.ids) &&
-        Array.isArray(workerData.at) &&
-        typeof workerData.thread === "number" &&
-        typeof workerData.totalNumberOfThread === "number" &&
-        typeof workerData.startAt === "number" &&
-        (workerData.abortSignalSAB === undefined ||
-            isProcessSharedBufferMetadata(workerData.abortSignalSAB)) &&
-        isProcessWorkerWireLockBuffers(workerData.lock) &&
-        isProcessWorkerWireLockBuffers(workerData.returnLock);
-};
-const getProcessWorkerPrimitives = () => {
-    const primitives = RUNTIME === "bun"
-        ? createBunConnectionPrimitives()
-        : RUNTIME === "deno"
-            ? createDenoConnectionPrimitives()
-            : getDefaultProcessSharedBufferPrimitives();
-    setDefaultProcessSharedBufferPrimitives(primitives);
-    return primitives;
-};
-const reviveProcessWorkerData = (wire) => {
-    const primitives = getProcessWorkerPrimitives();
-    const mappings = new Map();
-    const reviveRegion = (metadata) => {
-        const processBuffer = ProcessSharedBuffer.fromMetadata(metadata);
-        const descriptor = processBuffer.descriptor;
-        const key = `${descriptor.fd}:${descriptor.size}:${descriptor.runtime ?? ""}`;
-        let mapping = mappings.get(key);
-        if (mapping === undefined) {
-            mapping = descriptor.map(primitives);
-            mappings.set(key, mapping);
-        }
-        else {
-            descriptor.attach(mapping);
-        }
-        return {
-            sab: mapping.buffer,
-            byteOffset: processBuffer.byteOffset,
-            byteLength: processBuffer.byteLength,
-        };
-    };
-    const reviveLockBuffers = (lock) => ({
-        ...lock,
-        headers: reviveRegion(lock.headers),
-        lockSector: reviveRegion(lock.lockSector),
-        payload: reviveRegion(lock.payload),
-        payloadSector: reviveRegion(lock.payloadSector),
-    });
-    return {
-        ...wire,
-        sab: reviveRegion(wire.sab),
-        abortSignalSAB: wire.abortSignalSAB === undefined
-            ? undefined
-            : reviveRegion(wire.abortSignalSAB),
-        lock: reviveLockBuffers(wire.lock),
-        returnLock: reviveLockBuffers(wire.returnLock),
-    };
-};
-const installProcessWorkerBootstrap = () => {
-    const processLike = getNodeProcess();
-    const start = (payload) => {
-        const data = reviveProcessWorkerData(payload.workerData);
-        if (!isWorkerBootPayload(data)) {
-            throw new TypeError("invalid process worker boot payload");
-        }
-        void workerMainLoop(data).catch(reportWorkerStartupFatal);
-    };
-    const envBoot = processLike?.env?.[RUNTIME_PROCESS_WORKER_BOOT_ENV];
-    if (typeof envBoot === "string" && envBoot.length > 0) {
-        try {
-            const payload = JSON.parse(envBoot);
-            if (!isProcessWorkerBootPayload(payload)) {
-                throw new TypeError("invalid process worker boot payload");
-            }
-            try {
-                delete processLike?.env?.[RUNTIME_PROCESS_WORKER_BOOT_ENV];
-            }
-            catch {
-            }
-            start(payload);
-        }
-        catch (error) {
-            reportWorkerStartupFatal(error);
-        }
-        return;
-    }
-    if (typeof processLike?.on !== "function")
-        return;
-    const onMessage = (message) => {
-        if (!isProcessWorkerBootPayload(message))
-            return;
-        try {
-            processLike.off?.("message", onMessage);
-            processLike.removeListener?.("message", onMessage);
-        }
-        catch {
-        }
-        try {
-            start(message);
-        }
-        catch (error) {
-            reportWorkerStartupFatal(error);
-        }
-    };
-    processLike.on("message", onMessage);
-};
 if (RUNTIME_IS_MAIN_THREAD === false &&
     isWorkerBootPayload(RUNTIME_WORKER_DATA)) {
     void workerMainLoop(RUNTIME_WORKER_DATA).catch(reportWorkerStartupFatal);
 }
 else if (RUNTIME_IS_PROCESS_WORKER) {
-    installProcessWorkerBootstrap();
+    installProcessWorkerBootstrap({
+        isWorkerBootPayload,
+        reportWorkerStartupFatal,
+        startWorker: (data) => {
+            void workerMainLoop(data).catch(reportWorkerStartupFatal);
+        },
+    });
 }
 else if (isWorkerGlobalScope()) {
     installWorkerGlobalBootstrap();

package/src/worker/process-worker-bootstrap.d.ts

@@ -0,0 +1,8 @@
+import type { WorkerData } from "../types.js";
+import type { NativeWaitU32 } from "./timers.js";
+export declare const getProcessWorkerNativeWaitU32: () => NativeWaitU32 | undefined;
+export declare const installProcessWorkerBootstrap: ({ isWorkerBootPayload, reportWorkerStartupFatal, startWorker, }: {
+    isWorkerBootPayload: (value: unknown) => value is WorkerData;
+    reportWorkerStartupFatal: (error: unknown) => void;
+    startWorker: (data: WorkerData) => void;
+}) => void;

package/src/worker/process-worker-bootstrap.js

@@ -0,0 +1,159 @@
+import { RUNTIME } from "../common/runtime.js";
+import { RUNTIME_IS_PROCESS_WORKER, RUNTIME_PARENT_PORT, RUNTIME_PROCESS_WORKER_BOOT_ENV, RUNTIME_PROCESS_WORKER_BOOT_VERSION, } from "../common/worker-runtime.js";
+import { getNodeProcess } from "../common/node-compat.js";
+import { isLockBufferTextCompat } from "../common/shared-buffer-text.js";
+import { getDefaultProcessSharedBufferPrimitives, ProcessSharedBuffer, setDefaultProcessSharedBufferPrimitives, } from "../connections/process-shared-buffer.js";
+import { createBunConnectionPrimitives } from "../connections/bun.js";
+import { createDenoConnectionPrimitives } from "../connections/deno.js";
+import { loadNodeFutexAddon } from "../connections/node.js";
+export const getProcessWorkerNativeWaitU32 = () => {
+    if (!RUNTIME_IS_PROCESS_WORKER || RUNTIME !== "node")
+        return undefined;
+    try {
+        return loadNodeFutexAddon().waitU32;
+    }
+    catch {
+        return undefined;
+    }
+};
+const isProcessSharedBufferMetadata = (value) => {
+    try {
+        ProcessSharedBuffer.fromMetadata(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const isProcessWorkerWireLockBuffers = (value) => {
+    if (!value || typeof value !== "object")
+        return false;
+    const candidate = value;
+    return isProcessSharedBufferMetadata(candidate.headers) &&
+        isProcessSharedBufferMetadata(candidate.lockSector) &&
+        isProcessSharedBufferMetadata(candidate.payload) &&
+        isProcessSharedBufferMetadata(candidate.payloadSector) &&
+        (candidate.textCompat === undefined ||
+            isLockBufferTextCompat(candidate.textCompat));
+};
+const isProcessWorkerBootPayload = (value) => {
+    if (!value || typeof value !== "object")
+        return false;
+    const candidate = value;
+    const workerData = candidate.workerData;
+    return candidate.version === RUNTIME_PROCESS_WORKER_BOOT_VERSION &&
+        !!workerData &&
+        isProcessSharedBufferMetadata(workerData.sab) &&
+        Array.isArray(workerData.list) &&
+        Array.isArray(workerData.ids) &&
+        Array.isArray(workerData.at) &&
+        typeof workerData.thread === "number" &&
+        typeof workerData.totalNumberOfThread === "number" &&
+        typeof workerData.startAt === "number" &&
+        (workerData.abortSignalSAB === undefined ||
+            isProcessSharedBufferMetadata(workerData.abortSignalSAB)) &&
+        isProcessWorkerWireLockBuffers(workerData.lock) &&
+        isProcessWorkerWireLockBuffers(workerData.returnLock);
+};
+const getProcessWorkerPrimitives = () => {
+    const primitives = RUNTIME === "bun"
+        ? createBunConnectionPrimitives()
+        : RUNTIME === "deno"
+            ? createDenoConnectionPrimitives()
+            : getDefaultProcessSharedBufferPrimitives();
+    setDefaultProcessSharedBufferPrimitives(primitives);
+    return primitives;
+};
+const reviveProcessWorkerData = (wire) => {
+    const primitives = getProcessWorkerPrimitives();
+    const mappings = new Map();
+    const mappingKey = (descriptor) => descriptor.name === undefined
+        ? `fd:${descriptor.fd}:${descriptor.size}:${descriptor.runtime ?? ""}`
+        : `name:${descriptor.name}:${descriptor.size}:${descriptor.runtime ?? ""}`;
+    const reviveRegion = (metadata) => {
+        const processBuffer = ProcessSharedBuffer.fromMetadata(metadata);
+        const descriptor = processBuffer.descriptor;
+        const key = mappingKey(descriptor);
+        let mapping = mappings.get(key);
+        if (mapping === undefined) {
+            mapping = descriptor.map(primitives);
+            mappings.set(key, mapping);
+        }
+        else {
+            descriptor.attach(mapping);
+        }
+        return {
+            sab: mapping.buffer,
+            byteOffset: processBuffer.byteOffset,
+            byteLength: processBuffer.byteLength,
+        };
+    };
+    const reviveLockBuffers = (lock) => ({
+        ...lock,
+        headers: reviveRegion(lock.headers),
+        lockSector: reviveRegion(lock.lockSector),
+        payload: reviveRegion(lock.payload),
+        payloadSector: reviveRegion(lock.payloadSector),
+    });
+    return {
+        ...wire,
+        sab: reviveRegion(wire.sab),
+        abortSignalSAB: wire.abortSignalSAB === undefined
+            ? undefined
+            : reviveRegion(wire.abortSignalSAB),
+        lock: reviveLockBuffers(wire.lock),
+        returnLock: reviveLockBuffers(wire.returnLock),
+    };
+};
+export const installProcessWorkerBootstrap = ({ isWorkerBootPayload, reportWorkerStartupFatal, startWorker, }) => {
+    const processLike = getNodeProcess();
+    const start = (payload) => {
+        const data = reviveProcessWorkerData(payload.workerData);
+        if (!isWorkerBootPayload(data)) {
+            throw new TypeError("invalid process worker boot payload");
+        }
+        startWorker(data);
+    };
+    const envBoot = processLike?.env?.[RUNTIME_PROCESS_WORKER_BOOT_ENV];
+    if (typeof envBoot === "string" && envBoot.length > 0) {
+        try {
+            const payload = JSON.parse(envBoot);
+            if (!isProcessWorkerBootPayload(payload)) {
+                throw new TypeError("invalid process worker boot payload");
+            }
+            try {
+                delete processLike?.env?.[RUNTIME_PROCESS_WORKER_BOOT_ENV];
+            }
+            catch {
+            }
+            start(payload);
+        }
+        catch (error) {
+            reportWorkerStartupFatal(error);
+        }
+        return;
+    }
+    if (RUNTIME_PARENT_PORT === undefined) {
+        reportWorkerStartupFatal(new TypeError("missing process worker boot payload"));
+        return;
+    }
+    if (typeof processLike?.on !== "function")
+        return;
+    const onMessage = (message) => {
+        if (!isProcessWorkerBootPayload(message))
+            return;
+        try {
+            processLike.off?.("message", onMessage);
+            processLike.removeListener?.("message", onMessage);
+        }
+        catch {
+        }
+        try {
+            start(message);
+        }
+        catch (error) {
+            reportWorkerStartupFatal(error);
+        }
+    };
+    processLike.on("message", onMessage);
+};

package/src/worker/timers.js

@@ -36,6 +36,21 @@ const waitFallbackView = a_wait === undefined
 const a_pause = "pause" in Atomics
     ? Atomics.pause
     : undefined;
+const runtimeGlobals = globalThis;
+const isPlainNodeWindows = runtimeGlobals.process?.platform === "win32" &&
+    typeof runtimeGlobals.process?.versions?.node === "string" &&
+    runtimeGlobals.process?.versions?.bun === undefined &&
+    runtimeGlobals.Deno === undefined;
+// Windows has no working cross-process wake. The native wake (WakeByAddress)
+// is keyed to a virtual address, so a host cannot wake a process worker parked
+// on the same physical page mapped at a different address in the child — the
+// addon's FutexWake is a no-op there. A parked Windows Node process worker can
+// therefore never be signalled and must rediscover work by polling. Cap the
+// native wait at 1ms so it re-checks every millisecond instead of sleeping the
+// 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;
 export const whilePausing = ({ pauseInNanoseconds }) => {
     const forNanoseconds = pauseInNanoseconds ?? DEFAULT_PAUSE_TIME;
     if (!a_pause || forNanoseconds <= 0)
@@ -44,10 +59,9 @@ export const whilePausing = ({ pauseInNanoseconds }) => {
 };
 export const pauseGeneric = whilePausing({});
 export const sleepUntilChanged = ({ at, opView, pauseInNanoseconds, rxStatus, txStatus, enqueueLock, write, nativeWaitU32, useSharedMemoryWait = true, }) => {
-    const pause = pauseInNanoseconds
-        !== undefined
-        ? whilePausing({ pauseInNanoseconds })
-        : pauseGeneric;
+    const pause = pauseInNanoseconds === undefined
+        ? pauseGeneric
+        : whilePausing({ pauseInNanoseconds });
     const tryProgress = () => {
         let progressed = false;
         if (enqueueLock())
@@ -82,7 +96,7 @@ export const sleepUntilChanged = ({ at, opView, pauseInNanoseconds, rxStatus, tx
             return;
         a_store(rxStatus, 0, 0);
         if (nativeWaitU32 !== undefined) {
-            nativeWaitU32(opView.buffer, opView.byteOffset + (at * Int32Array.BYTES_PER_ELEMENT), value >>> 0, parkMs ?? 60);
+            nativeWaitU32(opView.buffer, opView.byteOffset + (at * Int32Array.BYTES_PER_ELEMENT), value >>> 0, nativeWaitTimeoutMs(parkMs));
         }
         else if (useSharedMemoryWait &&
             a_wait &&