knitting 0.1.63 → 0.1.73

package/src/common/worker-runtime.js

@@ -4,6 +4,13 @@ export const RUNTIME_PROCESS_WORKER_ENV = "KNITTING_PROCESS_WORKER";
 export const RUNTIME_PROCESS_WORKER_BOOT_ENV = "KNITTING_PROCESS_WORKER_BOOT";
 export const RUNTIME_PROCESS_WORKER_BOOT_VERSION = 1;
 export const RUNTIME_POOL_DEPTH_ENV = "KNITTING_POOL_DEPTH";
+/**
+ * A coalesced completion wake sent over a process worker's existing IPC
+ * channel. The result itself remains in shared memory; this is only the
+ * doorbell byte.
+ */
+export const PROCESS_COMPLETION_DOORBELL = "__knittingCompletionDoorbell";
+export const isProcessCompletionDoorbell = (value) => value === PROCESS_COMPLETION_DOORBELL;
 const nodeProcess = getNodeProcess();
 export const RUNTIME_IS_PROCESS_WORKER = nodeProcess?.env?.[RUNTIME_PROCESS_WORKER_ENV] === "1";
 const readPoolDepth = () => {

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

@@ -1,19 +1,9 @@
 import { type BufferReferenceRuntime } from "./buffer-reference-native.js";
 export type { BufferReferenceRuntime } from "./buffer-reference-native.js";
 export declare const BUFFER_REFERENCE_KIND: "knitting.bufferReference";
-/** Named values for the `unsafe.BufferReferenceReturn` pool option. */
-export declare const BufferReferenceReturn: {
-    /** Safe default: Deno/Bun copy the returned bytes so they outlive the worker. */
-    readonly Copy: "copy";
-    /** Zero-copy: borrow the worker's backing store until the reference is released. */
-    readonly Borrow: "borrow";
-};
-export type BufferReferenceReturn = (typeof BufferReferenceReturn)[keyof typeof BufferReferenceReturn];
 export declare const BUFFER_REFERENCE_NUMERIC_TRANSFER: unique symbol;
-export declare const BUFFER_REFERENCE_RETURN_RELEASE_TOKEN: unique symbol;
 declare const EXTERNAL_PAYLOAD_BRAND: unique symbol;
 export declare const BUFFER_REFERENCE_CODEC_ID: "knitting.bufferReference";
-declare const BUFFER_REFERENCE_RETURN_RELEASE_MESSAGE_KEY = "__knittingBufferReferenceRelease";
 export type BufferReferenceNumericMetadata = readonly [
     pointerLow: number,
     pointerHigh: number,
@@ -34,26 +24,17 @@ export type BufferReferenceMetadata = {
     readonly byteOffset: number;
     readonly byteLength: number;
 };
-export type BufferReferenceReturnReleaseMessage = {
-    readonly [BUFFER_REFERENCE_RETURN_RELEASE_MESSAGE_KEY]: string;
-};
-type BufferReferenceReturnReleaser = (token: bigint) => void;
-/** Host-side hooks for borrowed returns: release channel plus shutdown tracking. */
-export type BufferReferenceReturnHooks = {
-    /** Ask the producing worker to drop its pin for `token`. */
-    release: BufferReferenceReturnReleaser;
-    /**
-     * Record a borrowed reference so the pool can revoke it before its worker
-     * dies. Called at claim time without `aliasBuffer`, then again on first
-     * materialize with the alias buffer once it exists.
-     */
-    track?: (ref: BufferReference, token: bigint, aliasBuffer?: ArrayBuffer) => void;
-};
 type BufferSource = ArrayBufferView | ArrayBuffer;
 declare const PAYLOAD_TRANSPORT_FINALIZER: unique symbol;
-export declare const withBufferReferenceReturnReleaser: <T>(releaser: BufferReferenceReturnReleaser | BufferReferenceReturnHooks | undefined, run: () => T) => T;
-export declare const createBufferReferenceReturnReleaseMessage: (token: bigint) => BufferReferenceReturnReleaseMessage;
-export declare const readBufferReferenceReturnReleaseMessage: (value: unknown) => bigint | undefined;
+/**
+ * Whether a buffer has given up its bytes.
+ *
+ * Exported so a caller that *moved* a source can confirm the move actually
+ * happened. A runtime that cannot detach a buffer -- WASM memory, anything an
+ * external API has pinned -- otherwise leaves the producer still able to write
+ * memory the consumer has been told it owns.
+ */
+export declare const isArrayBufferDetached: (buffer: ArrayBuffer) => boolean;
 /** Revocation primitive: detach `buffer` so every view over it is neutralized. */
 export declare const detachArrayBufferBestEffort: (runtime: BufferReferenceRuntime, buffer: ArrayBuffer) => boolean;
 export declare const isBufferReferenceMetadata: (value: unknown) => value is BufferReferenceMetadata;
@@ -80,19 +61,12 @@ export declare class BufferReference {
     [BUFFER_REFERENCE_NUMERIC_TRANSFER](): BufferReferenceNumericMetadata | undefined;
     get isLocal(): boolean;
     /** Prepare a returned reference before the worker-side producer hold drains. */
-    claimOwnership(releaser?: BufferReferenceReturnReleaser | BufferReferenceReturnHooks | undefined): this;
+    claimOwnership(): this;
     toArrayBuffer(): ArrayBuffer;
     toUint8Array(): Uint8Array;
     /** The source is moved on construction, so it is never retained here. */
     get source(): undefined;
     release(): void;
-    /**
-     * Revoke a borrowed return before its producing worker goes away: detach
-     * the borrowed alias so no view can dangle. With `copyBytes` the reference
-     * itself survives on an owned copy; without it (worker bytes already gone)
-     * later reads fail loud instead of aliasing freed memory.
-     */
-    revokeBorrow(copyBytes: boolean): void;
     [Symbol.dispose](): void;
     [PAYLOAD_TRANSPORT_FINALIZER](): (() => void) | undefined;
 }

package/src/connections/buffer-reference.js

@@ -4,18 +4,9 @@ import { RUNTIME_IS_MAIN_THREAD } from "../common/worker-runtime.js";
 import { loadNodeBufferPointerAddon } from "./node-buffer-pointer.js";
 import { getBufferReferenceCapabilities, } from "./buffer-reference-native.js";
 export const BUFFER_REFERENCE_KIND = "knitting.bufferReference";
-/** Named values for the `unsafe.BufferReferenceReturn` pool option. */
-export const BufferReferenceReturn = {
-    /** Safe default: Deno/Bun copy the returned bytes so they outlive the worker. */
-    Copy: "copy",
-    /** Zero-copy: borrow the worker's backing store until the reference is released. */
-    Borrow: "borrow",
-};
 export const BUFFER_REFERENCE_NUMERIC_TRANSFER = Symbol.for("knitting.bufferReference.numericTransfer");
-export const BUFFER_REFERENCE_RETURN_RELEASE_TOKEN = Symbol.for("knitting.bufferReference.returnReleaseToken");
 const EXTERNAL_PAYLOAD_BRAND = Symbol.for("knitting.payloadCodec");
 export const BUFFER_REFERENCE_CODEC_ID = BUFFER_REFERENCE_KIND;
-const BUFFER_REFERENCE_RETURN_RELEASE_MESSAGE_KEY = "__knittingBufferReferenceRelease";
 const getRuntime = () => {
     if (RUNTIME === "deno" || RUNTIME === "bun" || RUNTIME === "node") {
         return RUNTIME;
@@ -37,7 +28,6 @@ const RUNTIME_NODE = 1;
 const RUNTIME_DENO = 2;
 const RUNTIME_BUN = 3;
 const PAYLOAD_TRANSPORT_FINALIZER = Symbol.for("knitting.payloadCodec.transportFinalizer");
-let currentReturnHooks;
 const bufferReferenceInstances = new WeakSet();
 const encodeRuntime = (runtime) => {
     switch (runtime) {
@@ -96,36 +86,6 @@ const numericMetadataToMetadata = (words) => {
         byteLength: words[5] ?? 0,
     };
 };
-const toReturnHooks = (releaser) => typeof releaser === "function" ? { release: releaser } : releaser;
-export const withBufferReferenceReturnReleaser = (releaser, run) => {
-    if (releaser === undefined)
-        return run();
-    const previous = currentReturnHooks;
-    currentReturnHooks = toReturnHooks(releaser);
-    try {
-        return run();
-    }
-    finally {
-        currentReturnHooks = previous;
-    }
-};
-export const createBufferReferenceReturnReleaseMessage = (token) => ({
-    [BUFFER_REFERENCE_RETURN_RELEASE_MESSAGE_KEY]: token.toString(),
-});
-export const readBufferReferenceReturnReleaseMessage = (value) => {
-    if (value === null || typeof value !== "object")
-        return undefined;
-    const raw = value[BUFFER_REFERENCE_RETURN_RELEASE_MESSAGE_KEY];
-    if (typeof raw !== "string")
-        return undefined;
-    try {
-        const token = BigInt(raw);
-        return token > 0n ? token : undefined;
-    }
-    catch {
-        return undefined;
-    }
-};
 const producerFinalizer = typeof FinalizationRegistry === "function"
     ? new FinalizationRegistry((backstop) => {
         backstop.count -= 1;
@@ -139,16 +99,6 @@ const producerFinalizer = typeof FinalizationRegistry === "function"
         }
     })
     : undefined;
-const borrowedReturnFinalizer = typeof FinalizationRegistry === "function"
-    ? new FinalizationRegistry(({ token, release }) => {
-        try {
-            release(token);
-        }
-        catch {
-            // best effort
-        }
-    })
-    : undefined;
 const isSharedArrayBufferInstance = (value) => typeof SharedArrayBuffer === "function" && value instanceof SharedArrayBuffer;
 const assertMovableSource = (source) => {
     if (isSharedArrayBufferInstance(source)) {
@@ -166,6 +116,15 @@ const assertMovableSource = (source) => {
 };
 const isDetached = (buffer) => buffer.detached === true ||
     buffer.byteLength === 0;
+/**
+ * Whether a buffer has given up its bytes.
+ *
+ * Exported so a caller that *moved* a source can confirm the move actually
+ * happened. A runtime that cannot detach a buffer -- WASM memory, anything an
+ * external API has pinned -- otherwise leaves the producer still able to write
+ * memory the consumer has been told it owns.
+ */
+export const isArrayBufferDetached = (buffer) => isDetached(buffer);
 /** Revocation primitive: detach `buffer` so every view over it is neutralized. */
 export const detachArrayBufferBestEffort = (runtime, buffer) => {
     if (isDetached(buffer))
@@ -241,9 +200,6 @@ export class BufferReference {
     #producerBackstop;
     #materializedRegions;
     #owned;
-    #borrowedReturnReleaser;
-    #borrowedReturnTrack;
-    #borrowedReturnFinalizerToken;
     #transportRefs = 0;
     #released = false;
     constructor(source, meta) {
@@ -341,9 +297,8 @@ export class BufferReference {
         }
     }
     /** Prepare a returned reference before the worker-side producer hold drains. */
-    claimOwnership(releaser = currentReturnHooks) {
-        if (this.#owned !== undefined || this.#borrowedReturnReleaser !== undefined ||
-            this.#released)
+    claimOwnership() {
+        if (this.#owned !== undefined || this.#released)
             return this;
         this.#assertLocal();
         const caps = getBufferReferenceCapabilities();
@@ -353,21 +308,6 @@ export class BufferReference {
             byteOffset: this.byteOffset,
             byteLength: this.byteLength,
         };
-        if (releaser !== undefined) {
-            const hooks = toReturnHooks(releaser);
-            // Borrow: adopt lazily — the alias costs GC-visible external memory on
-            // FFI runtimes, so it is only created when the bytes are actually read.
-            // Until then no view can exist, so the GC backstop safely watches the
-            // reference itself; first materialize migrates it to the alias buffer
-            // (views strongly reference their buffer, so the worker pin can only
-            // drop once no view can reach the borrowed bytes).
-            this.#borrowedReturnReleaser = hooks.release;
-            this.#borrowedReturnTrack = hooks.track;
-            this.#borrowedReturnFinalizerToken = {};
-            borrowedReturnFinalizer?.register(this, { token: this.#token, release: hooks.release }, this.#borrowedReturnFinalizerToken);
-            hooks.track?.(this, this.#token);
-            return this;
-        }
         this.#owned = caps.adopt(input, caps.supportsOwningAdopt ? undefined : { copy: true });
         return this;
     }
@@ -382,18 +322,6 @@ export class BufferReference {
             byteOffset: this.byteOffset,
             byteLength: this.byteLength,
         });
-        if (this.#borrowedReturnReleaser !== undefined) {
-            // First borrowed read: views over this alias exist from here on, so
-            // move the GC backstop from the reference onto the alias buffer.
-            this.#owned = region;
-            if (this.#borrowedReturnFinalizerToken !== undefined &&
-                borrowedReturnFinalizer !== undefined) {
-                borrowedReturnFinalizer.unregister(this.#borrowedReturnFinalizerToken);
-                borrowedReturnFinalizer.register(region.buffer, { token: this.#token, release: this.#borrowedReturnReleaser }, this.#borrowedReturnFinalizerToken);
-            }
-            this.#borrowedReturnTrack?.(this, this.#token, region.buffer);
-            return region;
-        }
         (this.#materializedRegions ??= []).push(region);
         if (this.#producerBackstop !== undefined && producerFinalizer !== undefined) {
             this.#producerBackstop.count += 1;
@@ -420,6 +348,10 @@ export class BufferReference {
         if (this.#released)
             return;
         this.#released = true;
+        // A claimed Node return is an owning ArrayBuffer, not a borrow. Drop this
+        // wrapper's ownership immediately; any ArrayBuffer or typed-array the
+        // caller kept still co-owns the backing store and stays valid.
+        this.#owned = undefined;
         // Revoke every alias this reference handed out before any pin can drop.
         // Leak-not-UAF: if a detach fails, the pin must stay held — the GC
         // backstops remain registered and retry once the buffers are unreachable.
@@ -433,31 +365,6 @@ export class BufferReference {
                         allDetached;
             }
         }
-        const borrowedReturnReleaser = this.#borrowedReturnReleaser;
-        this.#borrowedReturnReleaser = undefined;
-        this.#borrowedReturnTrack = undefined;
-        if (borrowedReturnReleaser !== undefined) {
-            const owned = this.#owned;
-            this.#owned = undefined;
-            if (owned !== undefined) {
-                allDetached = detachArrayBufferBestEffort(this.runtime, owned.buffer) &&
-                    allDetached;
-            }
-            if (allDetached) {
-                if (this.#borrowedReturnFinalizerToken !== undefined) {
-                    borrowedReturnFinalizer?.unregister(this.#borrowedReturnFinalizerToken);
-                    this.#borrowedReturnFinalizerToken = undefined;
-                }
-                try {
-                    borrowedReturnReleaser(this.#token);
-                }
-                catch {
-                    // best effort
-                }
-            }
-            // else: the finalizer stays registered on the alias buffer and sends
-            // the release once every escaped view is gone.
-        }
         // Only the producer owns the registry hold; consumers must not drop it.
         if (this.#isProducer && allDetached) {
             if (this.#finalizerToken !== undefined) {
@@ -475,65 +382,6 @@ export class BufferReference {
         // else on failed detach: the countdown backstop drops the pin when the
         // reference and every materialized alias are unreachable.
     }
-    /**
-     * Revoke a borrowed return before its producing worker goes away: detach
-     * the borrowed alias so no view can dangle. With `copyBytes` the reference
-     * itself survives on an owned copy; without it (worker bytes already gone)
-     * later reads fail loud instead of aliasing freed memory.
-     */
-    revokeBorrow(copyBytes) {
-        const releaser = this.#borrowedReturnReleaser;
-        if (releaser === undefined || this.#released)
-            return;
-        const owned = this.#owned;
-        let nextOwned;
-        let detached = true;
-        if (owned !== undefined) {
-            if (copyBytes) {
-                nextOwned = {
-                    buffer: owned.buffer.slice(owned.byteOffset, owned.byteOffset + owned.byteLength),
-                    byteOffset: 0,
-                    byteLength: owned.byteLength,
-                };
-            }
-            // Without a copy, keep the (now detached) region so reads throw
-            // instead of re-materializing an alias over freed worker memory.
-            detached = detachArrayBufferBestEffort(this.runtime, owned.buffer);
-        }
-        else if (copyBytes) {
-            // Never materialized: take the bytes now, while the worker still pins
-            // them, so the reference stays readable after its worker dies.
-            const caps = getBufferReferenceCapabilities();
-            nextOwned = caps.adopt({
-                token: this.#token,
-                pointer: this.pointer,
-                byteOffset: this.byteOffset,
-                byteLength: this.byteLength,
-            }, { copy: !caps.supportsOwningAdopt });
-        }
-        else {
-            // Never materialized and the worker bytes are already gone: no view
-            // exists, so poison future reads instead of aliasing freed memory.
-            this.#released = true;
-        }
-        if (!detached)
-            return;
-        if (nextOwned !== undefined)
-            this.#owned = nextOwned;
-        this.#borrowedReturnReleaser = undefined;
-        this.#borrowedReturnTrack = undefined;
-        if (this.#borrowedReturnFinalizerToken !== undefined) {
-            borrowedReturnFinalizer?.unregister(this.#borrowedReturnFinalizerToken);
-            this.#borrowedReturnFinalizerToken = undefined;
-        }
-        // Best effort: if the worker is still alive it can drop its pin early.
-        try {
-            releaser(this.#token);
-        }
-        catch {
-            // best effort
-        }
-    }
     [Symbol.dispose]() {
         this.release();
     }
@@ -550,9 +398,6 @@ export class BufferReference {
             if (this.#transportRefs <= 0)
                 this.release();
         });
-        if (this.#isProducer) {
-            finalizer[BUFFER_REFERENCE_RETURN_RELEASE_TOKEN] = this.#token;
-        }
         return finalizer;
     }
 }

package/src/connections/node-addons.d.ts

@@ -1,5 +1,5 @@
 type NodeRequire = (specifier: string) => unknown;
-export type NodeNativeAddonName = "knitting_shared_memory" | "knitting_shm" | "knitting_buffer_pointer";
+export type NodeNativeAddonName = "knitting_shared_memory" | "knitting_shm" | "knitting_buffer_pointer" | "knitting_doorbell";
 export type NodePlatformInfo = {
     arch: string;
     modules?: string;

package/src/connections/node-addons.js

@@ -34,6 +34,14 @@ export const formatNodeNativeAddonLoadError = (name, platformInfo, errors) => {
         ? "an unknown version"
         : `v${platformInfo.version}`;
     const target = `${platformInfo.platform}-${platformInfo.arch}`;
+    if (errors.some((error) => error.includes("ERR_DLOPEN_DISABLED"))) {
+        return (`knitting: Node.js ${version} blocked loading native addon ${name} ` +
+            `because --allow-addons is not enabled. For a thread worker pool, ` +
+            `set permission.node.allowAddons to true; if the host itself runs ` +
+            `with --permission, start it with --allow-addons too. This permits ` +
+            `task code to load Node native addons; only enable it for trusted ` +
+            `tasks.${attempts}`);
+    }
     if (abi === NODE_26_MODULE_ABI) {
         return (`knitting: Node.js 26 uses node:ffi instead of ABI-specific addons. ` +
             `Restart Node with the --experimental-ffi flag` +
@@ -85,7 +93,9 @@ export const loadNodeNativeAddon = (require, name, specifier) => {
             return require(candidate);
         }
         catch (error) {
-            errors.push(`${candidate}: ${String(error)}`);
+            const code = error?.code;
+            errors.push(`${candidate}: ${typeof code === "string" ? `${code}: ` : ""}` +
+                String(error));
         }
     }
     throw new Error(formatNodeNativeAddonLoadError(name, readNodePlatformInfo(), errors));

package/src/connections/shared-array-buffer-payload.d.ts

@@ -30,6 +30,13 @@ type SharedArrayBufferPayload = {
     readonly [SHARED_ARRAY_BUFFER_NUMERIC_TRANSFER]: (transportKey?: object) => SharedArrayBufferNumericMetadata | SharedArrayBufferTokenNumericMetadata | undefined;
 };
 export declare const isSharedArrayBufferValue: (value: unknown) => value is SharedArrayBuffer;
+type SharedPin = {
+    token: bigint;
+    pointer: bigint;
+    byteLength: number;
+};
+/** The pin backing `buffer`, when it has been shared at least once. */
+export declare const getSharedPin: (buffer: object) => SharedPin | undefined;
 /** Wrap a SAB as external payload; GC-managed pins mean no settle finalizer. */
 export declare const wrapSharedArrayBufferPayload: (sab: SharedArrayBuffer) => SharedArrayBufferPayload;
 export declare const getSharedArrayBufferPayload: (value: object) => SharedArrayBufferPayload | undefined;

package/src/connections/shared-array-buffer-payload.js

@@ -1,12 +1,13 @@
 import { RUNTIME } from "../common/runtime.js";
 import { getNodeProcess } from "../common/node-compat.js";
 import { getBufferReferenceCapabilities } from "./buffer-reference-native.js";
-// Thread-worker SharedArrayBuffer transport by process-local pointer.
-// SABs are shared, not moved or detached; process workers reject them.
+// SharedArrayBuffer transport uses a process-local pointer and is limited to
+// thread workers; SABs are not moved or detached.
 export const SHARED_ARRAY_BUFFER_CODEC_ID = "knitting.sharedArrayBuffer";
 export const SHARED_ARRAY_BUFFER_NUMERIC_TRANSFER = Symbol.for("knitting.sharedArrayBuffer.numericTransfer");
 export const SHARED_ARRAY_BUFFER_NUMERIC_WORDS = 8;
 const SHARED_ARRAY_BUFFER_TOKEN_NUMERIC_WORDS = 2;
+// Slice frames carry an explicit length; warm frames carry only the token.
 const EXTERNAL_PAYLOAD_BRAND = Symbol.for("knitting.payloadCodec");
 const getProcessId = () => {
     const proc = getNodeProcess();
@@ -23,7 +24,19 @@ export const isSharedArrayBufferValue = (value) => hasSharedArrayBuffer && value
 const pinnedBySab = new WeakMap();
 const payloadBySharedBuffer = new WeakMap();
 const warmedTokensByTransport = new WeakMap();
-const cachedSharedBuffersByToken = new Map();
+// Tokens are isolate-local, so adopted aliases are cached per transport lane.
+const adoptedByTransport = new WeakMap();
+const adoptedWithoutTransport = new Map();
+const adoptedCacheFor = (transportKey) => {
+    if (transportKey === undefined)
+        return adoptedWithoutTransport;
+    let cache = adoptedByTransport.get(transportKey);
+    if (cache === undefined) {
+        cache = new Map();
+        adoptedByTransport.set(transportKey, cache);
+    }
+    return cache;
+};
 const pinFinalizer = typeof FinalizationRegistry === "function"
     ? new FinalizationRegistry((token) => {
         try {
@@ -87,6 +100,8 @@ const pinSab = (sab) => {
     }
     return pin;
 };
+/** The pin backing `buffer`, when it has been shared at least once. */
+export const getSharedPin = (buffer) => pinnedBySab.get(buffer);
 const makeMetadata = (pin) => ({
     kind: SHARED_ARRAY_BUFFER_CODEC_ID,
     origin: PROCESS_ORIGIN,
@@ -167,13 +182,14 @@ const isSharedArrayBufferMetadata = (value) => {
         Number.isInteger(meta.byteLength) &&
         meta.byteLength >= 0);
 };
-const materializeSharedBuffer = (metadata, warmOnly) => {
+const materializeSharedBuffer = (metadata, warmOnly, transportKey) => {
     if (metadata.origin !== PROCESS_ORIGIN) {
         throw new Error(`SharedArrayBuffer cannot cross a process boundary (origin ${metadata.origin} ` +
             `!= ${PROCESS_ORIGIN}); it is shared by reference to thread workers only.`);
     }
     const token = BigInt(metadata.token);
-    const cached = cachedSharedBuffersByToken.get(token);
+    const cache = adoptedCacheFor(transportKey);
+    const cached = cache.get(token);
     if (cached !== undefined)
         return cached;
     if (warmOnly) {
@@ -185,7 +201,7 @@ const materializeSharedBuffer = (metadata, warmOnly) => {
         byteOffset: 0,
         byteLength: metadata.byteLength,
     });
-    cachedSharedBuffersByToken.set(token, region.buffer);
+    cache.set(token, region.buffer);
     createSharedArrayBufferPayload(region.buffer, {
         token,
         pointer: BigInt(metadata.pointer),
@@ -193,16 +209,16 @@ const materializeSharedBuffer = (metadata, warmOnly) => {
     }, metadata);
     return region.buffer;
 };
-const decode = (metadata) => {
+const decode = (metadata, transportKey) => {
     if (!isSharedArrayBufferMetadata(metadata)) {
         throw new TypeError("Invalid SharedArrayBuffer payload metadata");
     }
-    return materializeSharedBuffer(metadata, false);
+    return materializeSharedBuffer(metadata, false, transportKey);
 };
-const decodeNumeric = (words) => {
+const decodeNumeric = (words, transportKey) => {
     if (words.length === SHARED_ARRAY_BUFFER_TOKEN_NUMERIC_WORDS) {
         const token = joinU64(words[0] ?? 0, words[1] ?? 0);
-        const cached = cachedSharedBuffersByToken.get(token);
+        const cached = adoptedCacheFor(transportKey).get(token);
         if (cached !== undefined)
             return cached;
         throw new TypeError("SharedArrayBuffer cache miss for warm token payload");
@@ -228,7 +244,7 @@ const decodeNumeric = (words) => {
         token: joinU64(words[0] ?? 0, words[1] ?? 0).toString(),
         byteLength: words[4] ?? 0,
     };
-    return materializeSharedBuffer(metadata, false);
+    return materializeSharedBuffer(metadata, false, transportKey);
 };
 const codecGlobal = globalThis;
 const codecs = codecGlobal.__KNITTING_PAYLOAD_CODECS__ ??= Object.create(null);

package/src/debug/gate.js

@@ -4,7 +4,7 @@
  * 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
+ * then `await import("./handle.js")`, 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:

package/src/debug/handle.d.ts

@@ -3,6 +3,11 @@ export type DebugInit = {
     readonly name: string;
     readonly runtime: string;
     readonly namespaces: ReadonlySet<string>;
+    /**
+     * Host debug epoch as `timeOrigin + now()`. When absent (debug enabled only
+     * inside the worker), the clock starts when this handle initialises.
+     */
+    readonly epoch?: number;
 };
 export type Debug = {
     /**
@@ -20,4 +25,4 @@ export type Debug = {
      */
     envPhase: (label: string) => void;
 };
-export declare const initDebug: ({ name, runtime, namespaces }: DebugInit) => Debug;
+export declare const initDebug: ({ name, runtime, namespaces, epoch }: DebugInit) => Debug;

package/src/debug/handle.js

@@ -4,16 +4,24 @@
  * baseline snapshot it takes exists when debug is off.
  *
  * Diagnostics go to stderr so they never corrupt a worker's stdout, and every
- * line is tagged with the worker id, runtime, and a clock relative to when this
- * worker's debug initialised. The clock is worker-local on purpose: a main-thread
- * timestamp can't be compared against `performance.now()` here because the time
- * origins differ across the thread/process boundary (it would read negative).
+ * line is tagged with the worker id, runtime, and a clock in milliseconds since
+ * the host's debug epoch, so host and worker lines interleave on one timeline.
+ *
+ * Raw `performance.now()` can't be compared across the thread/process boundary:
+ * bun and deno give each worker its own time origin, and a process worker's
+ * origin is its own process start. `performance.timeOrigin + performance.now()`
+ * is comparable (measured within a few µs on bun, node and deno, for both
+ * threads and processes), so the host sends that absolute value and each worker
+ * rebases onto it once. Staying in the local `now()` frame afterwards keeps
+ * full precision; the absolute sum alone only resolves ~0.24µs.
  */
 import { describeGlobalKey, diffGlobals, snapshotGlobals, } from "./env-diff.js";
-export const initDebug = ({ name, runtime, namespaces }) => {
+export const initDebug = ({ name, runtime, namespaces, epoch }) => {
     const all = namespaces.has("*");
     const enabled = (namespace) => all || namespaces.has(namespace);
-    const base = performance.now();
+    const base = epoch === undefined
+        ? performance.now()
+        : epoch - performance.timeOrigin;
     const tag = `${name}·${runtime}`;
     const log = (namespace, message) => {
         if (!enabled(namespace))

package/src/error.d.ts

@@ -6,6 +6,15 @@ export declare const ErrorKnitting: {
     readonly Serializable: 3;
 };
 export type ErrorKnitting = typeof ErrorKnitting[keyof typeof ErrorKnitting];
+export type KnittingErrorCode = "KNT_ERROR_0" | "KNT_ERROR_1" | "KNT_ERROR_2" | "KNT_ERROR_3" | "THREAD_CLOSED" | "WORKER_CRASHED" | "WORKER_EXITED" | "WORKER_STARTUP_FAILED";
+/**
+ * Rejection raised by Knitting itself rather than by task code. Branch on
+ * `code`; `message` keeps the human-readable text.
+ */
+export declare class KnittingError extends Error {
+    readonly code: KnittingErrorCode;
+    constructor(code: KnittingErrorCode, message: string, cause?: unknown);
+}
 export declare const encoderError: ({ task, type, onPromise, detail, }: {
     task: Task;
     type: ErrorKnitting;

package/src/error.js

@@ -8,6 +8,18 @@ export const ErrorKnitting = {
     Json: 2,
     Serializable: 3,
 };
+/**
+ * Rejection raised by Knitting itself rather than by task code. Branch on
+ * `code`; `message` keeps the human-readable text.
+ */
+export class KnittingError extends Error {
+    code;
+    constructor(code, message, cause) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.name = "KnittingError";
+        this.code = code;
+    }
+}
 const reasonFrom = (task, type, detail) => {
     switch (type) {
         case ErrorKnitting.Function: {
@@ -41,10 +53,12 @@ export const encoderError = ({ task, type, onPromise, detail, }) => {
     }
     if (!beginPromisePayload(task))
         return false;
+    // Built here, not in the microtask, so the stack still names the caller.
+    const error = new KnittingError(`KNT_ERROR_${type}`, reason);
     queueMicrotask(() => {
         finishPromisePayload(task);
-        task.value = reason;
-        onPromise(task, true, reason);
+        task.value = error;
+        onPromise(task, true, error);
     });
     return false;
 };