knitting 0.1.55 → 0.1.60

package/src/connections/windows.js

@@ -0,0 +1,245 @@
+import { resolveKnittingPackageAsset } from "./package-assets.js";
+import { requireDetachedExternalArrayBuffer } from "./external-array-buffer.js";
+import { getNodeFfi, } from "./node-ffi-api.js";
+import { expectFd, expectPositiveSize, readCreateMode, readCreateSize, readRequiredCreateName, } from "./types.js";
+const WINDOWS_CREATE_MODE_CREATE = 1;
+const WINDOWS_CREATE_MODE_OPEN = 2;
+const WINDOWS_MAPPING_RECORD_BYTES = 32;
+const POINTER_OFFSET = 0;
+const HANDLE_OFFSET = 8;
+const SIZE_OFFSET = 16;
+const BASE_ADDRESS_MOD_64_OFFSET = 24;
+const WINDOWS_CREATE_SHARED_MEMORY = "knitting_windows_create_shared_memory";
+const WINDOWS_MAP_SHARED_MEMORY = "knitting_windows_map_shared_memory";
+const WINDOWS_CLOSE_SHARED_MEMORY = "knitting_windows_close_shared_memory";
+const FFIType = {
+    i32: 5,
+    u32: 6,
+    i64: 7,
+    ptr: 12,
+};
+let anonymousNameCounter = 0;
+const getDeno = () => {
+    const deno = globalThis.Deno;
+    if (deno === undefined) {
+        throw new Error("Deno Windows shared memory primitives can only run in Deno");
+    }
+    return deno;
+};
+const getBunFFI = () => {
+    const ffi = globalThis.Bun?.FFI;
+    if (typeof ffi?.dlopen !== "function" ||
+        typeof ffi?.toArrayBuffer !== "function") {
+        throw new Error("Bun FFI is not available in this runtime");
+    }
+    return ffi;
+};
+export const isWindowsRuntime = () => {
+    const denoOs = globalThis.Deno?.build?.os;
+    if (denoOs !== undefined)
+        return denoOs === "windows";
+    const processPlatform = globalThis.process?.platform;
+    return processPlatform === "win32";
+};
+const windowsArch = () => {
+    const denoArch = globalThis.Deno?.build?.arch;
+    if (denoArch === "x86_64")
+        return "x64";
+    const processArch = globalThis.process?.arch;
+    if (processArch === "x64")
+        return processArch;
+    throw new Error("Windows shared memory prebuilds support x64 only");
+};
+export const windowsSharedMemoryPrebuildPath = () => resolveKnittingPackageAsset("prebuilds", `win32-${windowsArch()}`, "knitting_windows_shared_memory.dll");
+export const makeWindowsAnonymousSharedMemoryName = (runtime) => {
+    const processId = globalThis.process?.pid ??
+        globalThis.Deno?.pid ??
+        0;
+    const next = anonymousNameCounter++;
+    const timeTag = Date.now().toString(36);
+    const randomTag = Math.random().toString(36).slice(2, 10);
+    const runtimeTag = runtime.replace(/[^a-z0-9_-]/gi, "").slice(0, 12) || "js";
+    return `Local\\knit_${runtimeTag}_${processId}_${timeTag}_${next}_${randomTag}`;
+};
+const readWindowsCreate = (options, runtime) => {
+    const mode = readCreateMode(options);
+    if (mode === "anonymous") {
+        return {
+            mode: WINDOWS_CREATE_MODE_CREATE,
+            name: makeWindowsAnonymousSharedMemoryName(runtime),
+        };
+    }
+    return {
+        mode: mode === "open"
+            ? WINDOWS_CREATE_MODE_OPEN
+            : WINDOWS_CREATE_MODE_CREATE,
+        name: readRequiredCreateName(options),
+    };
+};
+const encodeWideCString = (value) => {
+    const out = new Uint16Array((value?.length ?? 0) + 1);
+    if (value === undefined)
+        return out;
+    for (let index = 0; index < value.length; index += 1) {
+        out[index] = value.charCodeAt(index);
+    }
+    return out;
+};
+const readWindowsNativeMapping = (record) => {
+    const view = new DataView(record.buffer, record.byteOffset, record.byteLength);
+    const address = view.getBigUint64(POINTER_OFFSET, true);
+    const handle = view.getBigUint64(HANDLE_OFFSET, true);
+    const size = view.getBigUint64(SIZE_OFFSET, true);
+    if (address === 0n || handle === 0n) {
+        throw new Error("Windows shared memory backend returned an empty mapping");
+    }
+    if (size > BigInt(Number.MAX_SAFE_INTEGER)) {
+        throw new RangeError("Windows shared memory mapping is too large");
+    }
+    return {
+        address,
+        handle,
+        size: Number(size),
+        baseAddressMod64: view.getUint32(BASE_ADDRESS_MOD_64_OFFSET, true),
+    };
+};
+const fdFromHandle = (handle) => handle <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(handle) : 0;
+const checkWindowsResult = (result, message) => {
+    if (result !== 0) {
+        throw new Error(`${message} failed with Windows error ${result}`);
+    }
+};
+const createRecord = () => new Uint8Array(WINDOWS_MAPPING_RECORD_BYTES);
+const DENO_WINDOWS_SYMBOLS = {
+    [WINDOWS_CREATE_SHARED_MEMORY]: {
+        parameters: ["u64", "buffer", "u32", "buffer"],
+        result: "i32",
+    },
+    [WINDOWS_MAP_SHARED_MEMORY]: {
+        parameters: ["u64", "u64", "buffer", "buffer"],
+        result: "i32",
+    },
+    [WINDOWS_CLOSE_SHARED_MEMORY]: {
+        parameters: ["buffer"],
+        result: "i32",
+    },
+};
+const BUN_WINDOWS_SYMBOLS = {
+    [WINDOWS_CREATE_SHARED_MEMORY]: {
+        args: [FFIType.i64, FFIType.ptr, FFIType.u32, FFIType.ptr],
+        returns: FFIType.i32,
+    },
+    [WINDOWS_MAP_SHARED_MEMORY]: {
+        args: [FFIType.i64, FFIType.i64, FFIType.ptr, FFIType.ptr],
+        returns: FFIType.i32,
+    },
+    [WINDOWS_CLOSE_SHARED_MEMORY]: {
+        args: [FFIType.ptr],
+        returns: FFIType.i32,
+    },
+};
+const NODE_WINDOWS_SYMBOLS = {
+    [WINDOWS_CREATE_SHARED_MEMORY]: {
+        arguments: ["u64", "pointer", "u32", "pointer"],
+        return: "i32",
+    },
+    [WINDOWS_MAP_SHARED_MEMORY]: {
+        arguments: ["u64", "u64", "pointer", "pointer"],
+        return: "i32",
+    },
+    [WINDOWS_CLOSE_SHARED_MEMORY]: {
+        arguments: ["pointer"],
+        return: "i32",
+    },
+};
+export const openDenoWindowsSharedMemoryLibrary = () => getDeno().dlopen(windowsSharedMemoryPrebuildPath(), DENO_WINDOWS_SYMBOLS);
+export const openBunWindowsSharedMemoryLibrary = () => getBunFFI().dlopen(windowsSharedMemoryPrebuildPath(), BUN_WINDOWS_SYMBOLS);
+let cachedNodeWindowsLibrary;
+export const openNodeWindowsSharedMemoryLibrary = () => {
+    if (cachedNodeWindowsLibrary !== undefined) {
+        return cachedNodeWindowsLibrary;
+    }
+    const opened = getNodeFfi().dlopen(windowsSharedMemoryPrebuildPath(), NODE_WINDOWS_SYMBOLS);
+    cachedNodeWindowsLibrary = opened;
+    return opened;
+};
+const closeWindowsMapping = (record, closeSharedMemory) => {
+    let closed = false;
+    return () => {
+        if (closed)
+            return;
+        closed = true;
+        checkWindowsResult(closeSharedMemory(record), "knitting_windows_close_shared_memory");
+    };
+};
+const makeWindowsMapping = (runtime, mapping, name, arrayBuffer, unsafePointer, close) => ({
+    runtime,
+    fd: fdFromHandle(mapping.handle),
+    name,
+    size: mapping.size,
+    byteLength: arrayBuffer.byteLength,
+    buffer: arrayBuffer,
+    kind: "external-array-buffer",
+    arrayBuffer,
+    unsafePointer,
+    baseAddressMod64: mapping.baseAddressMod64,
+    close,
+});
+const fromDenoWindowsRecord = (record, name, lib) => {
+    const mapping = readWindowsNativeMapping(record);
+    const pointer = getDeno().UnsafePointer?.create(mapping.address);
+    if (pointer === undefined || pointer === null || typeof pointer !== "object") {
+        throw new Error("Deno UnsafePointer.create is not available");
+    }
+    const arrayBuffer = new (getDeno().UnsafePointerView)(pointer)
+        .getArrayBuffer(mapping.size);
+    return makeWindowsMapping("deno", mapping, name, arrayBuffer, pointer, closeWindowsMapping(record, lib.symbols[WINDOWS_CLOSE_SHARED_MEMORY]));
+};
+const fromBunWindowsRecord = (record, name, lib) => {
+    const mapping = readWindowsNativeMapping(record);
+    if (mapping.address > BigInt(Number.MAX_SAFE_INTEGER)) {
+        throw new RangeError("Windows mapping pointer is too large for Bun FFI");
+    }
+    const arrayBuffer = getBunFFI().toArrayBuffer(Number(mapping.address), 0, mapping.size);
+    return makeWindowsMapping("bun", mapping, name, arrayBuffer, Number(mapping.address), closeWindowsMapping(record, lib.symbols[WINDOWS_CLOSE_SHARED_MEMORY]));
+};
+const fromNodeWindowsRecord = (record, name, lib) => {
+    const mapping = readWindowsNativeMapping(record);
+    const arrayBuffer = getNodeFfi().toArrayBuffer(mapping.address, mapping.size, false);
+    let closed = false;
+    return makeWindowsMapping("node", mapping, name, arrayBuffer, mapping.address, () => {
+        if (closed)
+            return;
+        requireDetachedExternalArrayBuffer(arrayBuffer);
+        checkWindowsResult(lib.functions[WINDOWS_CLOSE_SHARED_MEMORY](record), WINDOWS_CLOSE_SHARED_MEMORY);
+        closed = true;
+    });
+};
+const createWindowsSharedMemory = (options, runtime, lib, createSharedMemory, fromRecord) => {
+    const size = expectPositiveSize(readCreateSize(options));
+    const { mode, name } = readWindowsCreate(options, runtime);
+    const record = createRecord();
+    checkWindowsResult(createSharedMemory(BigInt(size), encodeWideCString(name), mode, record), WINDOWS_CREATE_SHARED_MEMORY);
+    return fromRecord(record, name, lib);
+};
+const mapWindowsSharedMemory = (options, lib, mapSharedMemory, fromRecord) => {
+    const fd = expectFd(options.fd);
+    const size = expectPositiveSize(options.size);
+    const record = createRecord();
+    checkWindowsResult(mapSharedMemory(BigInt(fd), BigInt(size), encodeWideCString(options.name), record), WINDOWS_MAP_SHARED_MEMORY);
+    return fromRecord(record, options.name, lib);
+};
+export const createDenoWindowsSharedMemory = (options, lib = openDenoWindowsSharedMemoryLibrary()) => createWindowsSharedMemory(options, "deno", lib, lib.symbols[WINDOWS_CREATE_SHARED_MEMORY], fromDenoWindowsRecord);
+export const mapDenoWindowsSharedMemory = (options, lib = openDenoWindowsSharedMemoryLibrary()) => mapWindowsSharedMemory(options, lib, lib.symbols[WINDOWS_MAP_SHARED_MEMORY], fromDenoWindowsRecord);
+const createWindowsConnectionPrimitives = (runtime, lib, createSharedMemory, mapSharedMemory) => ({
+    runtime,
+    createSharedMemory: (options) => createSharedMemory(options, lib),
+    mapSharedMemory: (options) => mapSharedMemory(options, lib),
+});
+export const createDenoWindowsConnectionPrimitives = (lib = openDenoWindowsSharedMemoryLibrary()) => createWindowsConnectionPrimitives("deno", lib, createDenoWindowsSharedMemory, mapDenoWindowsSharedMemory);
+export const createBunWindowsSharedMemory = (options, lib = openBunWindowsSharedMemoryLibrary()) => createWindowsSharedMemory(options, "bun", lib, lib.symbols[WINDOWS_CREATE_SHARED_MEMORY], fromBunWindowsRecord);
+export const mapBunWindowsSharedMemory = (options, lib = openBunWindowsSharedMemoryLibrary()) => mapWindowsSharedMemory(options, lib, lib.symbols[WINDOWS_MAP_SHARED_MEMORY], fromBunWindowsRecord);
+export const createBunWindowsConnectionPrimitives = (lib = openBunWindowsSharedMemoryLibrary()) => createWindowsConnectionPrimitives("bun", lib, createBunWindowsSharedMemory, mapBunWindowsSharedMemory);
+export const createNodeWindowsSharedMemory = (options, lib = openNodeWindowsSharedMemoryLibrary()) => createWindowsSharedMemory(options, "node", lib, lib.functions[WINDOWS_CREATE_SHARED_MEMORY], fromNodeWindowsRecord);
+export const mapNodeWindowsSharedMemory = (options, lib = openNodeWindowsSharedMemoryLibrary()) => mapWindowsSharedMemory(options, lib, lib.functions[WINDOWS_MAP_SHARED_MEMORY], fromNodeWindowsRecord);
+export const createNodeWindowsConnectionPrimitives = (lib = openNodeWindowsSharedMemoryLibrary()) => createWindowsConnectionPrimitives("node", lib, createNodeWindowsSharedMemory, mapNodeWindowsSharedMemory);

package/src/debug/env-diff.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Environment-diff primitive: snapshot the keys present on `globalThis`, then
+ * later compare to see what the loaded code added, removed, or redefined.
+ *
+ * This is the core of "check what happens" debugging — a concrete before/after
+ * of the real runtime a worker's modules created, not an aggregate metric. The
+ * same snapshot/diff shape generalises to other ambient state (process
+ * listeners, open handles, prototype patches); `globalThis` keys are the first
+ * instance.
+ */
+export type EnvSnapshot = {
+    readonly keys: ReadonlySet<string | symbol>;
+};
+/** Capture every own key on `globalThis`, including symbols. */
+export declare const snapshotGlobals: () => EnvSnapshot;
+export type GlobalsDiff = {
+    readonly added: (string | symbol)[];
+    readonly removed: (string | symbol)[];
+};
+export declare const diffGlobals: (before: EnvSnapshot, after: EnvSnapshot) => GlobalsDiff;
+/**
+ * Render a key with enough provenance to tell a fresh global from a
+ * monkeypatch: its `typeof`/accessor kind plus writable/configurable/enumerable
+ * flags (`w`/`c`/`e`).
+ */
+export declare const describeGlobalKey: (key: string | symbol) => string;

package/src/debug/env-diff.js

@@ -0,0 +1,49 @@
+/**
+ * Environment-diff primitive: snapshot the keys present on `globalThis`, then
+ * later compare to see what the loaded code added, removed, or redefined.
+ *
+ * This is the core of "check what happens" debugging — a concrete before/after
+ * of the real runtime a worker's modules created, not an aggregate metric. The
+ * same snapshot/diff shape generalises to other ambient state (process
+ * listeners, open handles, prototype patches); `globalThis` keys are the first
+ * instance.
+ */
+/** Capture every own key on `globalThis`, including symbols. */
+export const snapshotGlobals = () => ({
+    keys: new Set(Reflect.ownKeys(globalThis)),
+});
+export const diffGlobals = (before, after) => {
+    const added = [];
+    const removed = [];
+    for (const key of after.keys) {
+        if (!before.keys.has(key))
+            added.push(key);
+    }
+    for (const key of before.keys) {
+        if (!after.keys.has(key))
+            removed.push(key);
+    }
+    return { added, removed };
+};
+/**
+ * Render a key with enough provenance to tell a fresh global from a
+ * monkeypatch: its `typeof`/accessor kind plus writable/configurable/enumerable
+ * flags (`w`/`c`/`e`).
+ */
+export const describeGlobalKey = (key) => {
+    const name = typeof key === "symbol" ? key.toString() : key;
+    let descriptor;
+    try {
+        descriptor = Object.getOwnPropertyDescriptor(globalThis, key);
+    }
+    catch {
+        return name;
+    }
+    if (descriptor === undefined)
+        return name;
+    const kind = descriptor.get !== undefined || descriptor.set !== undefined
+        ? "accessor"
+        : typeof descriptor.value;
+    const flags = `${descriptor.writable === false ? "" : "w"}${descriptor.configurable ? "c" : ""}${descriptor.enumerable ? "e" : ""}`;
+    return flags.length > 0 ? `${name} (${kind} ${flags})` : `${name} (${kind})`;
+};

package/src/debug/gate.d.ts

@@ -0,0 +1,18 @@
+import type { DebugOptions } from "../types.js";
+/** Namespaces explicitly requested via `KNITTING_DEBUG`. */
+export declare const DEBUG_NAMESPACES: ReadonlySet<string>;
+/**
+ * True when at least one namespace is requested via the env var alone. Guards
+ * the env-only paths; callers that also accept a `debug` option should use
+ * {@link resolveDebugNamespaces} instead.
+ */
+export declare const DEBUG_ENABLED: boolean;
+/**
+ * Merge the namespaces requested through the `debug` pool option with those from
+ * `KNITTING_DEBUG`; either source can enable a namespace. Returns an empty set
+ * when nothing is requested, so callers use `.size === 0` to keep the rest of
+ * `src/debug` unloaded — zero cost when off.
+ */
+export declare const resolveDebugNamespaces: (debug?: DebugOptions) => Set<string>;
+/** True when `namespace` (or `"*"`) is active for the given `debug` config + env. */
+export declare const debugHas: (debug: DebugOptions | undefined, namespace: string) => boolean;

package/src/debug/gate.js

@@ -0,0 +1,69 @@
+/**
+ * Zero-cost debug gate.
+ *
+ * Read once at module load from `KNITTING_DEBUG`. This module is deliberately
+ * tiny and dependency-light: importing it must never pull in the logger or the
+ * environment-diff machinery. Callers branch on {@link DEBUG_ENABLED} and only
+ * then `await import("./handle.ts")`, so when debug is off nothing else under
+ * `src/debug` is ever loaded — literally zero cost, not merely cheap.
+ *
+ * `KNITTING_DEBUG` is a comma-separated list of namespaces:
+ *   KNITTING_DEBUG=host,imports      # only those
+ *   KNITTING_DEBUG=*                 # everything
+ */
+import { getNodeProcess } from "../common/node-compat.js";
+const readEnv = (key) => {
+    // Deno: `process.env` exists under node-compat, but reading it may require
+    // --allow-env. Prefer the typed `Deno.env` and swallow permission errors.
+    const denoEnv = globalThis.Deno?.env;
+    if (typeof denoEnv?.get === "function") {
+        try {
+            return denoEnv.get(key);
+        }
+        catch {
+            /* env permission denied — fall through to node/bun */
+        }
+    }
+    try {
+        return getNodeProcess()?.env?.[key];
+    }
+    catch {
+        return undefined;
+    }
+};
+const raw = readEnv("KNITTING_DEBUG");
+/** Namespaces explicitly requested via `KNITTING_DEBUG`. */
+export const DEBUG_NAMESPACES = new Set((raw ?? "")
+    .split(",")
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0));
+/**
+ * True when at least one namespace is requested via the env var alone. Guards
+ * the env-only paths; callers that also accept a `debug` option should use
+ * {@link resolveDebugNamespaces} instead.
+ */
+export const DEBUG_ENABLED = DEBUG_NAMESPACES.size > 0;
+/**
+ * Merge the namespaces requested through the `debug` pool option with those from
+ * `KNITTING_DEBUG`; either source can enable a namespace. Returns an empty set
+ * when nothing is requested, so callers use `.size === 0` to keep the rest of
+ * `src/debug` unloaded — zero cost when off.
+ */
+export const resolveDebugNamespaces = (debug) => {
+    const namespaces = new Set(DEBUG_NAMESPACES);
+    if (debug === true) {
+        namespaces.add("*");
+    }
+    else if (debug !== undefined && debug !== false) {
+        for (const [key, value] of Object.entries(debug)) {
+            if (value === true)
+                namespaces.add(key);
+        }
+    }
+    return namespaces;
+};
+/** True when `namespace` (or `"*"`) is active for the given `debug` config + env. */
+export const debugHas = (debug, namespace) => {
+    const namespaces = resolveDebugNamespaces(debug);
+    return namespaces.has("*") || namespaces.has(namespace);
+};

package/src/debug/handle.d.ts

@@ -0,0 +1,23 @@
+export type DebugInit = {
+    /** Identity prefix for log tags, e.g. `"w0"` for a worker or `"main"`. */
+    readonly name: string;
+    readonly runtime: string;
+    readonly namespaces: ReadonlySet<string>;
+};
+export type Debug = {
+    /**
+     * Is a namespace active? Capture this once before a hot loop and branch on
+     * the boolean — never call per-iteration.
+     */
+    enabled: (namespace: string) => boolean;
+    /** Emit a tagged line to stderr when `namespace` is active. */
+    log: (namespace: string, message: string) => void;
+    /**
+     * Re-snapshot `globalThis` and report what changed since the previous phase.
+     * Drives two-phase pollution attribution (e.g. `"bootstrap"` then
+     * `"tasks"`), so you can see which loader injected which global. No-op unless
+     * the `globals` namespace is active.
+     */
+    envPhase: (label: string) => void;
+};
+export declare const initDebug: ({ name, runtime, namespaces }: DebugInit) => Debug;

package/src/debug/handle.js

@@ -0,0 +1,48 @@
+/**
+ * Worker-side debug handle. Lazily imported (see {@link ./gate.ts}) only when
+ * `KNITTING_DEBUG` names at least one namespace, so neither this code nor the
+ * 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).
+ */
+import { describeGlobalKey, diffGlobals, snapshotGlobals, } from "./env-diff.js";
+export const initDebug = ({ name, runtime, namespaces }) => {
+    const all = namespaces.has("*");
+    const enabled = (namespace) => all || namespaces.has(namespace);
+    const base = performance.now();
+    const tag = `${name}·${runtime}`;
+    const log = (namespace, message) => {
+        if (!enabled(namespace))
+            return;
+        const elapsed = (performance.now() - base).toFixed(1);
+        console.error(`[${tag}·+${elapsed}ms] ${namespace}: ${message}`);
+    };
+    // Baseline for the environment diff, taken the moment debug initialises:
+    // before worker bootstrap and before any task module is imported. Only paid
+    // when `globals` tracing is actually on.
+    let previous = enabled("globals")
+        ? snapshotGlobals()
+        : undefined;
+    const envPhase = (label) => {
+        if (previous === undefined)
+            return;
+        const current = snapshotGlobals();
+        const { added, removed } = diffGlobals(previous, current);
+        previous = current;
+        if (added.length === 0 && removed.length === 0) {
+            log("globals", `${label}: no new globals`);
+            return;
+        }
+        if (added.length > 0) {
+            log("globals", `${label} +${added.length}: ${added.map(describeGlobalKey).join("  ")}`);
+        }
+        if (removed.length > 0) {
+            log("globals", `${label} -${removed.length}: ${removed.map(String).join("  ")}`);
+        }
+    };
+    return { enabled, log, envPhase };
+};

package/src/error.d.ts

@@ -0,0 +1,14 @@
+import { type PromisePayloadHandler, type Task } from "./memory/lock.js";
+export declare const ErrorKnitting: {
+    readonly Function: 0;
+    readonly Symbol: 1;
+    readonly Json: 2;
+    readonly Serializable: 3;
+};
+export type ErrorKnitting = typeof ErrorKnitting[keyof typeof ErrorKnitting];
+export declare const encoderError: ({ task, type, onPromise, detail, }: {
+    task: Task;
+    type: ErrorKnitting;
+    onPromise?: PromisePayloadHandler;
+    detail?: string;
+}) => false;

package/src/error.js

@@ -0,0 +1,50 @@
+import { beginPromisePayload, finishPromisePayload, TaskFlag, TaskIndex, } from "./memory/lock.js";
+import { RUNTIME_IS_MAIN_THREAD } from "./common/worker-runtime.js";
+// const object, not `enum`: Andromeda's Nova engine can't parse `enum`. Same
+// value access and emit on Node/Deno/Bun.
+export const ErrorKnitting = {
+    Function: 0,
+    Symbol: 1,
+    Json: 2,
+    Serializable: 3,
+};
+const reasonFrom = (task, type, detail) => {
+    switch (type) {
+        case ErrorKnitting.Function: {
+            const name = typeof task.value === "function"
+                ? (task.value.name || "<anonymous>")
+                : "<unknown>";
+            return `KNT_ERROR_0: Function is not a valid type; name: ${name}`;
+        }
+        case ErrorKnitting.Symbol:
+            return "KNT_ERROR_1: Symbol must use Symbol.for(...) keys";
+        case ErrorKnitting.Json:
+            return detail == null || detail.length === 0
+                ? "KNT_ERROR_2: JSON stringify failed; payload must be JSON-safe"
+                : `KNT_ERROR_2: JSON stringify failed; ${detail}`;
+        case ErrorKnitting.Serializable:
+            return detail == null || detail.length === 0
+                ? "KNT_ERROR_3: Unsupported payload type; serialize it yourself"
+                : `KNT_ERROR_3: Unsupported payload type; ${detail}`;
+    }
+};
+export const encoderError = ({ task, type, onPromise, detail, }) => {
+    const reason = reasonFrom(task, type, detail);
+    if (!RUNTIME_IS_MAIN_THREAD) {
+        task.value = reason;
+        task[TaskIndex.FlagsToHost] = TaskFlag.Reject;
+        return false;
+    }
+    // Fallback for direct codec usage where no async settle callback is wired.
+    if (onPromise == null) {
+        throw new TypeError(reason);
+    }
+    if (!beginPromisePayload(task))
+        return false;
+    queueMicrotask(() => {
+        finishPromisePayload(task);
+        task.value = reason;
+        onPromise(task, true, reason);
+    });
+    return false;
+};

package/src/ipc/tools/ring-queue.d.ts

@@ -0,0 +1,33 @@
+export default class RingQueue<T> implements Iterable<T> {
+    #private;
+    constructor(capacity?: number);
+    get size(): number;
+    get isEmpty(): boolean;
+    get capacity(): number;
+    clear(): void;
+    peek(): T | undefined;
+    /** Ensure internal capacity >= requested (rounds up to next power of two). */
+    reserve(minCapacity: number): void;
+    /**
+     * Push to back
+     * Always succeeds (grows if full)
+     */
+    push(value: T): true;
+    /**
+     * Push to front (unshift)
+     * Always succeeds (grows if full)
+     */
+    unshift(value: T): true;
+    /**
+     * Pop from front (shift)
+     */
+    shift(): T | undefined;
+    /**
+     * Pop from front (shift) without clearing the slot.
+     * Use only for internal pooled-object queues where retaining references is acceptable.
+     */
+    shiftNoClear(): T | undefined;
+    [Symbol.iterator](): Generator<T, void, void>;
+    toArray(): T[];
+    get [Symbol.toStringTag](): string;
+}