knitting 0.1.53 → 0.1.55

package/src/debug/gate.js

@@ -1,69 +0,0 @@
-/**
- * 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

@@ -1,23 +0,0 @@
-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

@@ -1,48 +0,0 @@
-/**
- * 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

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

package/src/error.js

@@ -1,49 +0,0 @@
-import { beginPromisePayload, finishPromisePayload, TaskFlag, TaskIndex, } from "./memory/lock.js";
-import { RUNTIME_IS_MAIN_THREAD } from "./common/worker-runtime.js";
-export var ErrorKnitting;
-(function (ErrorKnitting) {
-    ErrorKnitting[ErrorKnitting["Function"] = 0] = "Function";
-    ErrorKnitting[ErrorKnitting["Symbol"] = 1] = "Symbol";
-    ErrorKnitting[ErrorKnitting["Json"] = 2] = "Json";
-    ErrorKnitting[ErrorKnitting["Serializable"] = 3] = "Serializable";
-})(ErrorKnitting || (ErrorKnitting = {}));
-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

@@ -1,33 +0,0 @@
-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;
-}

package/src/ipc/tools/ring-queue.js

@@ -1,159 +0,0 @@
-;
-export default class RingQueue {
-    #buf;
-    #mask;
-    #head = 0;
-    #tail = 0;
-    #size = 0;
-    constructor(capacity = 512) {
-        let cap = 2;
-        while (cap < capacity)
-            cap <<= 1;
-        // Keep the array packed (avoid holey elements in hot queue paths).
-        this.#buf = new Array(cap).fill(null);
-        this.#mask = cap - 1;
-    }
-    get size() {
-        return this.#size;
-    }
-    get isEmpty() {
-        return this.#size === 0;
-    }
-    get capacity() {
-        return this.#mask + 1;
-    }
-    clear() {
-        // Keep buffer allocated; reset pointers (fast)
-        // (optional) also drop references to help GC if you want:
-        // for (let i = 0; i < this.#size; i++) this.#buf[(this.#head + i) & this.#mask] = null;
-        this.#head = 0;
-        this.#tail = 0;
-        this.#size = 0;
-    }
-    peek() {
-        return this.#size === 0 ? undefined : this.#buf[this.#head];
-    }
-    /** Ensure internal capacity >= requested (rounds up to next power of two). */
-    reserve(minCapacity) {
-        if (minCapacity <= this.capacity)
-            return;
-        let cap = this.capacity;
-        while (cap < minCapacity)
-            cap <<= 1;
-        this.#growTo(cap);
-    }
-    // --- hot path internal ---
-    #growIfFull() {
-        if (this.#size !== (this.#mask + 1))
-            return;
-        this.#growTo((this.#mask + 1) << 1);
-    }
-    #growTo(newCap) {
-        const oldBuf = this.#buf;
-        const oldCap = this.#mask + 1;
-        const n = this.#size;
-        const next = new Array(newCap).fill(null);
-        const head = this.#head;
-        const firstLen = Math.min(n, oldCap - head);
-        // copy [head..end)
-        for (let i = 0; i < firstLen; i++) {
-            next[i] = oldBuf[head + i];
-        }
-        // copy [0..remaining)
-        for (let i = firstLen; i < n; i++) {
-            next[i] = oldBuf[i - firstLen];
-        }
-        this.#buf = next;
-        this.#mask = newCap - 1;
-        this.#head = 0;
-        this.#tail = n;
-    }
-    /**
-     * Push to back
-     * Always succeeds (grows if full)
-     */
-    push(value) {
-        this.#growIfFull();
-        const buf = this.#buf;
-        const mask = this.#mask;
-        const tail = this.#tail;
-        buf[tail] = value;
-        this.#tail = (tail + 1) & mask;
-        this.#size++;
-        return true;
-    }
-    /**
-     * Push to front (unshift)
-     * Always succeeds (grows if full)
-     */
-    unshift(value) {
-        this.#growIfFull();
-        const buf = this.#buf;
-        const mask = this.#mask;
-        const head = (this.#head - 1) & mask;
-        this.#head = head;
-        buf[head] = value;
-        this.#size++;
-        return true;
-    }
-    /**
-     * Pop from front (shift)
-     */
-    shift() {
-        const size = this.#size;
-        if (size === 0)
-            return undefined;
-        const head = this.#head;
-        const buf = this.#buf;
-        const v = buf[head];
-        buf[head] = null; // help GC while keeping packed elements
-        this.#head = (head + 1) & this.#mask;
-        this.#size = size - 1;
-        return v;
-    }
-    /**
-     * Pop from front (shift) without clearing the slot.
-     * Use only for internal pooled-object queues where retaining references is acceptable.
-     */
-    shiftNoClear() {
-        const size = this.#size;
-        if (size === 0)
-            return undefined;
-        const head = this.#head;
-        const v = this.#buf[head];
-        this.#head = (head + 1) & this.#mask;
-        this.#size = size - 1;
-        return v;
-    }
-    *[Symbol.iterator]() {
-        const buf = this.#buf;
-        const mask = this.#mask;
-        let idx = this.#head;
-        let i = 0;
-        const n = this.#size;
-        while (i < n) {
-            // values should never be null inside active range, but keep it safe
-            const v = buf[idx];
-            if (v !== null)
-                yield v;
-            idx = (idx + 1) & mask;
-            i++;
-        }
-    }
-    toArray() {
-        // faster than Array.from(this) in some cases because it avoids iterator overhead,
-        // but keep iterator version if you prefer simplicity.
-        const out = new Array(this.#size);
-        const buf = this.#buf;
-        const mask = this.#mask;
-        let idx = this.#head;
-        for (let i = 0; i < out.length; i++) {
-            out[i] = buf[idx];
-            idx = (idx + 1) & mask;
-        }
-        return out;
-    }
-    get [Symbol.toStringTag]() {
-        return `RingQueue(size=${this.#size}, cap=${this.capacity})`;
-    }
-}

package/src/ipc/transport/shared-memory.d.ts

@@ -1,23 +0,0 @@
-export type SignalArguments = ReturnType<typeof createSharedMemoryTransport>;
-import { type SharedBufferSource } from "../../common/shared-buffer-region.js";
-export declare const TRANSPORT_SIGNAL_BYTES: number;
-export type Sab = {
-    size?: number;
-    sharedSab?: SharedBufferSource;
-};
-type SignalForWorker = {
-    sabObject?: Sab;
-    isMain: boolean;
-    thread: number;
-    startTime?: number;
-};
-export declare const createSharedMemoryTransport: ({ sabObject, isMain, startTime }: SignalForWorker) => {
-    sab: import("../../common/shared-buffer-region.js").SharedBufferRegion;
-    op: Int32Array<import("../../common/shared-buffer-region.js").SharedBuffer>;
-    startAt: number;
-    opView: Int32Array<import("../../common/shared-buffer-region.js").SharedBuffer>;
-    rxStatus: Int32Array<import("../../common/shared-buffer-region.js").SharedBuffer>;
-    txStatus: Int32Array<import("../../common/shared-buffer-region.js").SharedBuffer>;
-};
-export type MainSignal = Pick<SignalArguments, "opView" | "startAt" | "rxStatus" | "txStatus">;
-export {};

package/src/ipc/transport/shared-memory.js

@@ -1,35 +0,0 @@
-import { createSharedArrayBuffer } from "../../common/runtime.js";
-import { toSharedBufferRegion, } from "../../common/shared-buffer-region.js";
-const page = 1024 * 4;
-const CACHE_LINE_BYTES = 64;
-// Keep hot signals on separate cache lines to avoid false sharing.
-const SIGNAL_OFFSETS = {
-    op: 0,
-    rxStatus: CACHE_LINE_BYTES,
-    txStatus: CACHE_LINE_BYTES * 2,
-};
-export const TRANSPORT_SIGNAL_BYTES = CACHE_LINE_BYTES * 3;
-const a_store = Atomics.store;
-export const createSharedMemoryTransport = ({ sabObject, isMain, startTime }) => {
-    const toGrow = sabObject?.size ?? page;
-    const roundedSize = toGrow + ((page - (toGrow % page)) % page);
-    const signalRegion = toSharedBufferRegion(sabObject?.sharedSab
-        ? sabObject.sharedSab
-        : createSharedArrayBuffer(roundedSize, page * page));
-    const sab = signalRegion.sab;
-    const baseByteOffset = signalRegion.byteOffset;
-    const startAt = startTime ?? performance.now();
-    const opView = new Int32Array(sab, baseByteOffset + SIGNAL_OFFSETS.op, 1);
-    if (isMain)
-        a_store(opView, 0, 0);
-    const rxStatus = new Int32Array(sab, baseByteOffset + SIGNAL_OFFSETS.rxStatus, 1);
-    a_store(rxStatus, 0, 1);
-    return {
-        sab: signalRegion,
-        op: opView,
-        startAt,
-        opView,
-        rxStatus,
-        txStatus: new Int32Array(sab, baseByteOffset + SIGNAL_OFFSETS.txStatus, 1),
-    };
-};

package/src/memory/byte-carpet.d.ts

@@ -1,73 +0,0 @@
-import type { SharedBuffer, SharedBufferRegion } from "../common/shared-buffer-region.js";
-export declare const BYTE_CARPET_ALIGN_BYTES = 64;
-export declare const alignBytes: (value: number, alignment?: number) => number;
-export declare const makeSharedBufferRegion: (sab: SharedBuffer, byteOffset: number, byteLength: number) => SharedBufferRegion;
-export type ByteCarpetSlice = {
-    name: string;
-    byteOffset: number;
-    byteLength: number;
-    reservedByteLength: number;
-};
-export declare const createByteCarpet: ({ alignTo, startByteOffset, }?: {
-    alignTo?: number;
-    startByteOffset?: number;
-}) => {
-    slices: ByteCarpetSlice[];
-    take: (name: string, byteLength: number, { alignTo: sliceAlignment, reserveByteLength, }?: {
-        alignTo?: number;
-        reserveByteLength?: number;
-    }) => ByteCarpetSlice;
-    byteLength: () => number;
-    bind: (sab: SharedBuffer, slice: ByteCarpetSlice) => SharedBufferRegion;
-};
-export declare const getStridedSlotOffsetU32: ({ slotIndex, slotStrideU32, baseU32, extraU32, }: {
-    slotIndex: number;
-    slotStrideU32: number;
-    baseU32?: number;
-    extraU32?: number;
-}) => number;
-export declare const getStridedSlotByteOffset: ({ slotIndex, slotStrideU32, baseByteOffset, baseU32, extraU32, }: {
-    slotIndex: number;
-    slotStrideU32: number;
-    baseByteOffset?: number;
-    baseU32?: number;
-    extraU32?: number;
-}) => number;
-export declare const getStridedRegionSpanBytes: ({ slotCount, slotStrideU32, slotLengthU32, baseU32, }: {
-    slotCount: number;
-    slotStrideU32: number;
-    slotLengthU32: number;
-    baseU32?: number;
-}) => number;
-export declare const getInterleavedSlotStrideU32: (slotStrideU32: number) => number;
-export declare const getHeaderBlockByteLength: ({ slotCount, slotStrideU32, queues, alignTo, }: {
-    slotCount: number;
-    slotStrideU32: number;
-    queues?: number;
-    alignTo?: number;
-}) => number;
-export type HeaderLayoutMode = "split" | "interleaved";
-export type QueueControlByteLayout = {
-    headers: SharedBufferRegion;
-    headerSlotStrideU32: number;
-    lockSector: SharedBufferRegion;
-    payloadSector: SharedBufferRegion;
-};
-export type LockControlCarpet = {
-    controlSAB: SharedBuffer;
-    signals: SharedBufferRegion;
-    abortSignals: SharedBufferRegion;
-    lock: QueueControlByteLayout;
-    returnLock: QueueControlByteLayout;
-    slices: readonly ByteCarpetSlice[];
-};
-export declare const createLockControlCarpet: ({ signalBytes, abortBytes, lockSectorBytes, headerSlotStrideU32, slotCount, headerLayout, alignTo, createBuffer, }: {
-    signalBytes: number;
-    abortBytes: number;
-    lockSectorBytes: number;
-    headerSlotStrideU32: number;
-    slotCount: number;
-    headerLayout?: HeaderLayoutMode;
-    alignTo?: number;
-    createBuffer?: (byteLength: number) => SharedBuffer;
-}) => LockControlCarpet;