knitting 0.1.63 → 0.1.73

package/src/worker/loop.js

@@ -1,23 +1,26 @@
-import { addRuntimeDataListener, createRuntimeMessageChannel, RUNTIME_IS_MAIN_THREAD, RUNTIME_IS_PROCESS_WORKER, RUNTIME_PARENT_PORT, RUNTIME_WORKER_DATA, } from "../common/worker-runtime.js";
+import { createRuntimeMessageChannel, PROCESS_COMPLETION_DOORBELL, 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 { createDenoCompletionNotifier } from "../runtime/deno-doorbell.js";
+import { createNodeCompletionNotifier } from "../runtime/node-doorbell.js";
 import { createWorkerRxQueue } from "./rx-queue.js";
+import { installSharedReturn } from "./shared-return.js";
 import { createSharedMemoryTransport, WORKER_STOP, } from "../ipc/transport/shared-memory.js";
 import { lock2 } from "../memory/lock.js";
-// Side-effect import: registers the payload codec (cycle break for Andromeda;
-// see lock.ts). Must run before any lock2() call.
+// Registers the payload codec before any lock is built.
 import "../memory/payloadCodec.js";
 import { getFunctions } from "./task-loader.js";
-import { pauseGeneric, sleepUntilChanged, whilePausing } from "./timers.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 { readBufferReferenceReturnReleaseMessage, } from "../connections/buffer-reference.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 = {
@@ -53,38 +56,28 @@ const reportWorkerStartupFatal = (error) => {
         }
     }
 };
-const installBufferReferenceReleaseListener = (releaseReturnedBufferReference) => {
-    const handleMessage = (message) => {
-        const token = readBufferReferenceReturnReleaseMessage(message);
-        if (token !== undefined)
-            releaseReturnedBufferReference(token);
-    };
-    if (RUNTIME_PARENT_PORT !== undefined) {
-        addRuntimeDataListener(RUNTIME_PARENT_PORT, handleMessage);
-        return;
-    }
-    const scope = globalThis;
-    scope.addEventListener?.("message", (event) => {
-        handleMessage(event?.data);
-    });
-};
 export const workerMainLoop = async (startupData) => {
     // Startup-only safety layer: no per-iteration checks in the hot loop.
     installTerminationGuard();
     installUnhandledRejectionSilencer();
     installPerformanceNowGuard();
-    const { debug, sab, thread, startAt, workerOptions, lock, returnLock, abortSignalSAB, abortSignalMax, payloadConfig, bufferReferenceReturn, permission, notifyOnHostPublish, 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;
-    // const object, not `enum`: Andromeda's Nova engine can't parse `enum`.
+    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,
     };
@@ -110,7 +103,28 @@ export const workerMainLoop = async (startupData) => {
         consumers: steal?.consumers,
         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);
+    const processParentPort = processCompletionDoorbell === true
+        ? RUNTIME_PARENT_PORT
+        : undefined;
+    // Bun on Windows flushes process messages only after an event-loop turn.
+    let processRingPending = false;
+    const flushProcessRing = IS_BUN_WINDOWS;
+    const notifyProcessHost = processParentPort === undefined
+        ? undefined
+        : flushProcessRing
+            ? () => {
+                processParentPort.postMessage(PROCESS_COMPLETION_DOORBELL);
+                processRingPending = true;
+            }
+            : () => processParentPort.postMessage(PROCESS_COMPLETION_DOORBELL);
     const returnLockState = lock2({
         headers: returnLock.headers,
         headerSlotStrideU32: returnLock.headerSlotStrideU32,
@@ -120,9 +134,22 @@ export const workerMainLoop = async (startupData) => {
         payloadConfig,
         textCompat: returnLock.textCompat,
         processBoundary: RUNTIME_IS_PROCESS_WORKER,
+        sharedReturn: sharedReturn === true,
+        // A thread return moves its source before publication. Node transfers the
+        // backing-store ownership; Deno and Bun make one owned host copy before
+        // the worker drops its pin. Both avoid the borrowed-return lifetime.
+        moveReturn: !RUNTIME_IS_PROCESS_WORKER,
         // The host parks on this lock's publication word when it has no work to
         // flush. Request locks are host-produced and must not wake that waiter.
-        notifyOnHostPublish,
+        notifyOnHostPublish: notifyOnHostPublish ||
+            notifyDenoHost !== undefined ||
+            notifyNodeHost !== undefined ||
+            notifyProcessHost !== undefined,
+        notifyHostPublish: notifyDenoHost !== undefined
+            ? () => notifyDenoHost(thread)
+            : notifyNodeHost !== undefined
+                ? notifyNodeHost
+                : notifyProcessHost,
     });
     const timers = workerOptions?.timers;
     const spinMicroseconds = timers?.spinMicroseconds ??
@@ -163,16 +190,16 @@ export const workerMainLoop = async (startupData) => {
             maxSignals: abortSignalMax,
         })
         : undefined;
-    const { enqueueLock, serviceBatchImmediate, hasCompleted, writeBatch, hasPending, getAwaiting, drainReturnReleases, releaseReturnedBufferReference, } = createWorkerRxQueue({
+    const { enqueueLock, serviceBatchImmediate, hasCompleted, writeBatch, getAwaiting, drainReturnReleases, releaseDeferredReturns, } = createWorkerRxQueue({
         listOfFunctions,
         workerOptions,
         lock: lockState,
         returnLock: returnLockState,
-        borrowReturnedBufferReferences: bufferReferenceReturn === "borrow",
         hasAborted: abortSignals?.hasAborted,
         stealing: steal !== undefined,
     });
-    installBufferReferenceReleaseListener(releaseReturnedBufferReference);
+    if (sharedReturn === true)
+        installSharedReturn(returnLock.payload);
     a_store(rxStatus, 0, 1);
     const WRITE_MAX = 64;
     const pauseUntil = sleepUntilChanged({
@@ -224,9 +251,9 @@ export const workerMainLoop = async (startupData) => {
     };
     const traceSignals = dbg?.enabled("signals") === true;
     const _hasCompleted = hasCompleted;
-    const _hasPending = hasPending;
     const _getAwaiting = getAwaiting;
     const _drainReturnReleases = drainReturnReleases;
+    const _releaseDeferredReturns = releaseDeferredReturns;
     const _pauseSpin = pauseSpin;
     const _enqueueLock = traceSignals
         ? () => {
@@ -259,9 +286,24 @@ export const workerMainLoop = async (startupData) => {
             pauseUntil(value, spinMicroseconds, parkMs);
         }
         : pauseUntil;
-    const flushBeforeClaim = steal !== undefined;
+    // Stealing flushes completed work before claiming more; private lanes claim
+    // first to keep their single-consumer path short.
+    const pump = steal !== undefined
+        ? () => {
+            let progressed = false;
+            if (_hasCompleted() && _writeBatch(WRITE_MAX) > 0)
+                progressed = true;
+            return _enqueueLock() || progressed;
+        }
+        : () => {
+            const claimed = _enqueueLock();
+            return (_hasCompleted() && _writeBatch(WRITE_MAX) > 0) || claimed;
+        };
     /** Leave the dispatch loop and acknowledge shutdown. */
     const stopLoop = () => {
+        // A shutdown rejects unconsumed calls, so no return can still be adopted.
+        // Do not let a worker-isolate exit strand native BufferReference pins.
+        _releaseDeferredReturns();
         a_store(stopView, 0, WORKER_STOP.acknowledged);
         a_store(rxStatus, 0, 0);
         try {
@@ -272,41 +314,20 @@ export const workerMainLoop = async (startupData) => {
     };
     const loop = () => {
         isInMacro = false;
+        // Recompute progress on every pass so idle workers can park.
         let progressed = true;
         let awaiting = 0;
         while (true) {
             if (stopView[0] !== WORKER_STOP.running)
                 return stopLoop();
-            if (flushBeforeClaim) {
-                // Stealing only. Flush finished work before taking more on: a computed
-                // response should not wait behind a claim, and that claim can block on
-                // a peer withdrawing its intent. Measured to hurt the per-lane path,
-                // where a claim is a cheap private decode and picking work up promptly
-                // matters more, so the classic order is kept below.
-                // Reordering must not make `progressed` sticky: it answers "did this
-                // iteration move anything", so it has to start false every pass or the
-                // park below is unreachable and the worker spins a core forever.
-                progressed = false;
-                if (_hasCompleted()) {
-                    if (_writeBatch(WRITE_MAX) > 0)
-                        progressed = true;
-                }
-                progressed = _enqueueLock() || progressed;
-            }
-            else {
-                progressed = _enqueueLock();
-                if (_hasCompleted()) {
-                    if (_writeBatch(WRITE_MAX) > 0)
-                        progressed = true;
-                }
-            }
+            progressed = pump();
             _drainReturnReleases();
-            if (_hasPending()) {
-                if (_serviceBatchImmediate() > 0)
-                    progressed = true;
-            }
+            if (_serviceBatchImmediate() > 0)
+                progressed = true;
             if ((awaiting = _getAwaiting()) > 0) {
-                if (awaiting !== lastAwaiting)
+                // Promise callbacks need the loop to yield; delay only when no progress
+                // was made, otherwise queued work pays an unnecessary timer hop.
+                if (progressed || awaiting !== lastAwaiting)
                     awaitingSpins = 0;
                 lastAwaiting = awaiting;
                 awaitingSpins++;
@@ -315,12 +336,26 @@ export const workerMainLoop = async (startupData) => {
                 return;
             }
             awaitingSpins = lastAwaiting = 0;
+            if (processRingPending) {
+                processRingPending = false;
+                scheduleTimer(0);
+                return;
+            }
             if (!progressed) {
                 if (txStatus[Comment.thisIsAHint] === 1) {
-                    _pauseSpin();
+                    // During a hint spin only host-driven state can change.
+                    do {
+                        _pauseSpin();
+                        if (stopView[0] !== WORKER_STOP.running)
+                            return stopLoop();
+                        if (pump())
+                            break;
+                    } 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/rx-queue.d.ts

@@ -6,7 +6,6 @@ type ArgumentsForCreateWorkerQueue = {
     workerOptions?: WorkerSettings;
     lock: Lock2;
     returnLock: Lock2;
-    borrowReturnedBufferReferences?: boolean;
     hasAborted?: (signal: number) => boolean;
     now?: () => number;
     /**
@@ -21,14 +20,14 @@ type ArgumentsForCreateWorkerQueue = {
     stealing?: boolean;
 };
 export type CreateWorkerRxQueue = ReturnType<typeof createWorkerRxQueue>;
-export declare const createWorkerRxQueue: ({ listOfFunctions, workerOptions, lock, returnLock, borrowReturnedBufferReferences, hasAborted, now, stealing, }: ArgumentsForCreateWorkerQueue) => {
+export declare const createWorkerRxQueue: ({ listOfFunctions, workerOptions, lock, returnLock, hasAborted, now, stealing, }: ArgumentsForCreateWorkerQueue) => {
     hasCompleted: () => boolean;
     hasPending: () => boolean;
     writeBatch: (max: number) => number;
     serviceBatchImmediate: () => number;
     enqueueLock: () => boolean;
     drainReturnReleases: () => void;
-    releaseReturnedBufferReference: (token: bigint) => void;
+    releaseDeferredReturns: () => void;
     hasAwaiting: () => boolean;
     getAwaiting: () => number;
 };

package/src/worker/rx-queue.js

@@ -1,12 +1,12 @@
 import RingQueue from "../ipc/tools/ring-queue.js";
 import { attachPayloadTransportFinalizer, runTaskFinalizers, TaskFlag, TaskIndex, } from "../memory/lock.js";
 import { composeWorkerRunner } from "./composable-runners.js";
-import { BUFFER_REFERENCE_RETURN_RELEASE_TOKEN } from "../connections/buffer-reference.js";
-export const createWorkerRxQueue = ({ listOfFunctions, workerOptions, lock, returnLock, borrowReturnedBufferReferences, hasAborted, now, stealing, }) => {
+/** Tasks run per `serviceBatchImmediate` call before returning to the loop. */
+const SERVICE_BATCH_MAX = 32;
+export const createWorkerRxQueue = ({ listOfFunctions, workerOptions, lock, returnLock, hasAborted, now, stealing, }) => {
     const PLACE_HOLDER = (_) => {
         throw ("UNREACHABLE FROM PLACE HOLDER (thread)");
     };
-    let hasAnythingFinished = 0;
     let awaiting = 0;
     const jobs = listOfFunctions.reduce((acc, fixed) => (acc.push(fixed.run), acc), []);
     const toWork = new RingQueue();
@@ -26,12 +26,7 @@ export const createWorkerRxQueue = ({ listOfFunctions, workerOptions, lock, retu
     const returnHostBits = returnLock.hostBits;
     const returnWorkerBits = returnLock.workerBits;
     const deferredReleases = [];
-    const explicitReturnReleases = new Map();
-    const drainReturnReleases = () => {
-        if (deferredReleases.length === 0)
-            return;
-        if ((a_load(returnHostBits, 0) ^ a_load(returnWorkerBits, 0)) !== 0)
-            return;
+    const releaseDeferredReturns = () => {
         for (let i = 0; i < deferredReleases.length; i++) {
             try {
                 deferredReleases[i]();
@@ -42,18 +37,17 @@ export const createWorkerRxQueue = ({ listOfFunctions, workerOptions, lock, retu
         }
         deferredReleases.length = 0;
     };
-    const releaseReturnedBufferReference = (token) => {
-        const key = token.toString();
-        const release = explicitReturnReleases.get(key);
-        if (release === undefined)
+    const drainReturnReleases = () => {
+        if (deferredReleases.length === 0)
             return;
-        explicitReturnReleases.delete(key);
-        try {
-            release();
-        }
-        catch {
-            // best effort
-        }
+        // `returnHostBits` is the publication word of the return lock, and only
+        // this thread ever writes it (encode() toggles hostBits, the host toggles
+        // workerBits). Reading our own word plainly skips an `Atomics.load`, which
+        // is a non-inlined call an order of magnitude dearer than a plain read;
+        // the peer's word still needs the atomic.
+        if ((returnHostBits[0] ^ a_load(returnWorkerBits, 0)) !== 0)
+            return;
+        releaseDeferredReturns();
     };
     const runByIndex = listOfFunctions.reduce((acc, fixed, idx) => {
         const job = jobs[idx];
@@ -65,9 +59,13 @@ export const createWorkerRxQueue = ({ listOfFunctions, workerOptions, lock, retu
         }));
         return acc;
     }, []);
+    // A settled task is either written into the return lock straight away or
+    // parked in `pendingFrames`, so the queue's own size already answers "is
+    // there anything left to flush" — the separate counter this used to keep was
+    // an increment and a decrement per task tracking a value it could read.
     const hasCompleted = workerOptions?.resolveAfterFinishingAll === true
-        ? () => hasAnythingFinished !== 0 && toWork.size === 0
-        : () => hasAnythingFinished !== 0;
+        ? () => pendingFrames.size !== 0 && toWork.size === 0
+        : () => pendingFrames.size !== 0;
     const { decode, resolved } = lock;
     const resolvedShift = () => resolved.shiftNoClear();
     const enqueueLock = () => {
@@ -86,34 +84,22 @@ export const createWorkerRxQueue = ({ listOfFunctions, workerOptions, lock, retu
         }
         return true;
     };
-    const encodeReturnSafe = (slot) => {
-        if (!returnLock.encode(slot))
-            return false;
-        return true;
-    };
+    const returnEncode = returnLock.encode;
     const sendReturn = (slot, shouldReject) => {
         slot[IDX_FLAGS] = shouldReject ? FLAG_REJECT : 0;
-        if (!encodeReturnSafe(slot))
+        if (!returnEncode(slot))
             return false;
         // Preserve return finalizers past slot recycle; release after drain.
         if (slot.finalize !== undefined) {
-            const token = slot.finalize[BUFFER_REFERENCE_RETURN_RELEASE_TOKEN];
-            if (token === undefined || borrowReturnedBufferReferences !== true) {
-                deferredReleases.push(slot.finalize);
-            }
-            else {
-                explicitReturnReleases.set(token.toString(), slot.finalize);
-            }
+            deferredReleases.push(slot.finalize);
             slot.finalize = undefined;
         }
-        hasAnythingFinished--;
         recyclePush(slot);
         return true;
     };
     const settleNow = (slot, isError, value, wasAwaited) => {
         runTaskFinalizers(slot);
         slot.value = value;
-        hasAnythingFinished++;
         if (wasAwaited && awaiting > 0)
             awaiting--;
         const shouldReject = isError ||
@@ -145,14 +131,20 @@ export const createWorkerRxQueue = ({ listOfFunctions, workerOptions, lock, retu
         },
         serviceBatchImmediate: () => {
             let processed = 0;
-            while (processed < 5 && toWork.size !== 0) {
+            // Every trip back out to the dispatch loop costs a claim attempt and the
+            // per-pass bookkeeping, so a low cap makes that scaffolding a per-task
+            // tax on cheap tasks. Run a longer run when the return lock is keeping
+            // up, and cut it short the moment a settle lands in `pendingFrames` --
+            // that means the return region is full and the right move is to go
+            // flush it rather than pile up more finished work.
+            while (processed < SERVICE_BATCH_MAX && toWork.size !== 0) {
                 const slot = toWorkShift();
                 try {
                     const fnIndex = slot[TaskIndex.FunctionID] & FUNCTION_ID_MASK;
                     const result = runByIndex[fnIndex](slot);
                     slot[IDX_FLAGS] = 0;
-                    slot.value = null;
                     if (result instanceof Promise) {
+                        slot.value = null;
                         awaiting++;
                         result.then((value) => settleNow(slot, false, value, true), (err) => settleNow(slot, true, err, true));
                     }
@@ -164,12 +156,14 @@ export const createWorkerRxQueue = ({ listOfFunctions, workerOptions, lock, retu
                     settleNow(slot, true, err, false);
                 }
                 ++processed;
+                if (pendingFrames.size !== 0)
+                    break;
             }
             return processed;
         },
         enqueueLock,
         drainReturnReleases,
-        releaseReturnedBufferReference,
+        releaseDeferredReturns,
         hasAwaiting: () => awaiting > 0,
         getAwaiting: () => awaiting,
     };

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

@@ -0,0 +1,9 @@
+/** Point `sharedBytes` at the arena of `payload`, this worker's return lane. */
+export declare const installSharedReturn: (payload: object) => void;
+export declare const resetSharedReturn: () => void;
+/**
+ * Allocate an uninitialized borrowed return buffer. The caller must write every
+ * byte it returns and must not retain the view beyond the borrow window.
+ * Ordinary allocation is used when borrowing is unavailable.
+ */
+export declare const sharedBytes: (byteLength: number, zeroFill?: boolean) => Uint8Array;

package/src/worker/shared-return.js

@@ -0,0 +1,22 @@
+import { getSharedReturnAllocator } from "../memory/payloadCodec.js";
+// `sharedBytes` uses the worker's return-lane arena; outside that context it
+// falls back to an ordinary Uint8Array.
+let allocate;
+/** Point `sharedBytes` at the arena of `payload`, this worker's return lane. */
+export const installSharedReturn = (payload) => {
+    allocate = getSharedReturnAllocator(payload);
+};
+export const resetSharedReturn = () => {
+    allocate = undefined;
+};
+/**
+ * Allocate an uninitialized borrowed return buffer. The caller must write every
+ * byte it returns and must not retain the view beyond the borrow window.
+ * Ordinary allocation is used when borrowing is unavailable.
+ */
+export const sharedBytes = (byteLength, zeroFill = false) => {
+    if (!Number.isInteger(byteLength) || byteLength < 0) {
+        throw new RangeError("sharedBytes(byteLength) requires a non-negative integer");
+    }
+    return allocate?.(byteLength, zeroFill) ?? new Uint8Array(byteLength);
+};

package/src/worker/task-loader.js

@@ -1,7 +1,6 @@
 import { endpointSymbol } from "../common/task-symbol.js";
 import { toImportSpecifier, toModuleUrl } from "../common/module-url.js";
-// const object, not `const enum`: Andromeda's Nova engine can't parse `enum`.
-// No longer inlined, but only read on cold paths.
+// Use a const object; Andromeda's Nova engine cannot parse `enum`.
 export const TimeoutKind = {
     Reject: 0,
     Resolve: 1,

package/src/worker/timers.d.ts

@@ -2,6 +2,7 @@ type PauseOptions = {
     pauseInNanoseconds?: number;
 };
 export type NativeWaitU32 = (buffer: ArrayBuffer | SharedArrayBuffer, byteOffset: number, expected: number, timeoutMs?: number) => unknown;
+export declare const IS_BUN_WINDOWS: boolean;
 export declare const whilePausing: ({ pauseInNanoseconds }: PauseOptions) => () => void;
 export declare const pauseGeneric: () => void;
 export declare const sleepUntilChanged: ({ at, opView, pauseInNanoseconds, rxStatus, txStatus, enqueueLock, write, nativeWaitU32, useSharedMemoryWait, flushBeforeClaim, }: {
@@ -14,12 +15,7 @@ export declare const sleepUntilChanged: ({ at, opView, pauseInNanoseconds, rxSta
     write?: () => number | boolean;
     nativeWaitU32?: NativeWaitU32;
     useSharedMemoryWait?: boolean;
-    /**
-     * Stealing only: write results back before attempting to claim more work.
-     * A claim can spin waiting for a peer to withdraw its intent, so claiming
-     * first puts arbitration latency in front of a finished response. Measured
-     * to hurt the per-lane path, so it stays off by default.
-     */
+    /** Stealing only: flush results before claiming more work. */
     flushBeforeClaim?: boolean;
 }) => (value: number, spinMicroseconds: number, parkMs?: number) => void;
 export {};