knitting 0.1.55 → 0.1.60

package/src/types.d.ts

@@ -0,0 +1,399 @@
+import { endpointSymbol } from "./common/task-symbol.js";
+import type { Envelope, EnvelopeBody, EnvelopeHeader } from "./common/envelope.js";
+import type { LockBufferTextCompat, SharedBufferTextCompat } from "./common/shared-buffer-text.js";
+import type { SharedBufferRegion, SharedBufferSource } from "./common/shared-buffer-region.js";
+import type { PayloadBufferMode, PayloadBufferOptions } from "./memory/payload-config.js";
+import type { PermissionProtocol, PermissionProtocolInput, ResolvedPermissionProtocol } from "./permission/protocol.js";
+type WorkerCall = {
+    fnNumber: number;
+    timeout?: TaskTimeout;
+    abortSignal?: AbortSignalOption;
+};
+type WorkerInvoke = (args: Uint8Array) => Promise<unknown>;
+interface WorkerContext {
+    txIdle(): boolean;
+    call(descriptor: WorkerCall): WorkerInvoke;
+    kills(): Promise<void>;
+}
+type CreateContext = WorkerContext;
+type WorkerData = {
+    sab: SharedBufferSource;
+    abortSignalSAB?: SharedBufferSource;
+    abortSignalMax?: number;
+    list: string[];
+    ids: number[];
+    names: string[];
+    thread: number;
+    totalNumberOfThread: number;
+    debug?: DebugOptions;
+    startAt: number;
+    workerOptions?: WorkerSettings;
+    at: number[];
+    lock: LockBuffers;
+    returnLock: LockBuffers;
+    payloadConfig?: PayloadBufferOptions;
+    bufferReferenceReturn?: "copy" | "borrow";
+    permission?: ResolvedPermissionProtocol;
+};
+type UnsafeOptions = {
+    /**
+     * Experimental `BufferReference` return lifetime.
+     *
+     * `"copy"` is safe after worker release. `"borrow"` skips the Deno/Bun copy,
+     * but must be released before producer shutdown and must not outlive its ref.
+     */
+    BufferReferenceReturn?: "copy" | "borrow";
+};
+type LockBuffers = {
+    headers: SharedBufferSource;
+    headerSlotStrideU32?: number;
+    lockSector: SharedBufferSource;
+    payload: SharedBufferSource;
+    payloadSector: SharedBufferSource;
+    textCompat?: LockBufferTextCompat;
+};
+type JSONValue = string | number | boolean | null | JSONArray | JSONObject;
+interface JSONObject {
+    [key: string]: JSONValue;
+}
+interface JSONArray extends Array<JSONValue> {
+}
+type Serializable = string | object | number | boolean | bigint;
+type ValidInput = bigint | void | JSONValue | symbol | ArrayBuffer | Uint8Array | Int32Array | Float64Array | BigInt64Array | BigUint64Array | DataView | Error | Date | Envelope<EnvelopeHeader, EnvelopeBody>;
+type Args = ValidInput | Serializable;
+type MaybePromise<T> = T | Promise<T>;
+/** Blob payloads are not supported; pass ArrayBuffer/typed arrays instead. */
+type NoBlob<T> = T extends Blob ? never : T;
+/** Task input may be a direct value or native Promise; thenables are plain values. */
+type TaskInput = NoBlob<Args> | Promise<NoBlob<Args>>;
+/** Per-call timeout. A number is milliseconds; object form can return a default. */
+type TaskTimeout = number | {
+    time: number;
+    maybe?: true;
+    default?: unknown;
+    error?: unknown;
+};
+type BivariantCallback<Args extends unknown[], R> = {
+    bivarianceHack(...args: Args): R;
+}["bivarianceHack"];
+type AbortSignalConfig = {
+    readonly hasAborted: true;
+};
+/** `true` or config injects an abort toolkit as the task's second parameter. */
+type AbortSignalOption = true | AbortSignalConfig | undefined;
+type AbortSignalMethods<AS extends AbortSignalOption> = AS extends undefined ? never : {
+    hasAborted: () => boolean;
+    now: () => number;
+};
+type AbortSignalToolkit<AS extends AbortSignalOption> = AbortSignalMethods<AS>;
+type TaskFn<A extends TaskInput, B extends Args, AS extends AbortSignalOption = undefined> = BivariantCallback<AS extends undefined ? [NoBlob<Awaited<A>>] : [NoBlob<Awaited<A>>, AbortSignalToolkit<AS>], MaybePromise<NoBlob<B>>>;
+type PromiseWithMaybeReject<T> = Promise<T> & {
+    reject: (reason?: unknown) => void;
+};
+type TaskLike<AS extends AbortSignalOption = AbortSignalOption> = {
+    readonly f: (...args: any[]) => any;
+} & (AS extends undefined ? {
+    readonly abortSignal?: undefined;
+} : {
+    readonly abortSignal: AS;
+});
+type TaskFunctionLike = (...args: any[]) => any;
+type Composed<A extends TaskInput = Args, B extends Args = Args, AS extends AbortSignalOption = undefined> = FixPoint<A, B, AS> & SecondPart;
+type tasks = Record<string, Composed<any, any, any> | TaskFunctionLike>;
+type ComposedWithKey = Composed<any, any, AbortSignalOption> & {
+    name: string;
+};
+type PromiseWrapped<F extends (...args: any[]) => any, AS extends AbortSignalOption = undefined> = (...args: PromisifyCallArgs<F, AS>) => AS extends undefined ? Promise<Awaited<ReturnType<F>>> : PromiseWithMaybeReject<Awaited<ReturnType<F>>>;
+type PromiseInput<T> = T | Promise<T>;
+type PromisifyArgs<T extends unknown[]> = {
+    [K in keyof T]: PromiseInput<T[K]>;
+};
+type NormalizeUndefinedSingleArg<T extends unknown[]> = T extends [undefined] ? [] | [undefined] : T;
+type AbortAwareCallArgs<T extends unknown[]> = T extends [
+    ...infer Head,
+    AbortSignalToolkit<any>
+] ? NormalizeUndefinedSingleArg<Head> : NormalizeUndefinedSingleArg<T>;
+type HostCallArgs<F extends (...args: any[]) => any, AS extends AbortSignalOption> = AS extends undefined ? Parameters<F> : AbortAwareCallArgs<Parameters<F>>;
+type PromisifyCallArgs<F extends (...args: any[]) => any, AS extends AbortSignalOption> = HostCallArgs<F, AS> extends infer T ? T extends unknown[] ? PromisifyArgs<T> : never : never;
+type TaskCallable<T> = T extends TaskLike<any> ? T["f"] : T extends TaskFunctionLike ? T : never;
+type AbortSignalOfTask<T> = T extends {
+    readonly abortSignal: infer AS;
+} ? Extract<AS, AbortSignalOption> : undefined;
+type FunctionMapType<T extends Record<string, TaskLike<any> | TaskFunctionLike>> = {
+    [K in keyof T]: PromiseWrapped<TaskCallable<T[K]>, AbortSignalOfTask<T[K]>>;
+};
+interface FixPointBase<A extends TaskInput, B extends Args, AS extends AbortSignalOption = undefined> {
+    /** Worker function. It receives one value; use a tuple/object for many inputs. */
+    readonly f: TaskFn<A, B, AS>;
+    /** Soft call timeout. Use `worker.hardTimeoutMs` for runaway CPU walls. */
+    readonly timeout?: TaskTimeout;
+}
+type FixPoint<A extends TaskInput, B extends Args, AS extends AbortSignalOption = undefined> = FixPointBase<A, B, AS> & (AS extends undefined ? {
+    readonly abortSignal?: undefined;
+} : {
+    readonly abortSignal: AS;
+});
+type ImportTaskOptions<A extends TaskInput = void, B extends Args = void, AS extends AbortSignalOption = undefined> = Omit<FixPoint<A, B, AS>, "f"> & {
+    /** Module imported by the worker only. Relative paths resolve from caller. */
+    readonly href: string;
+    /** Plain function export name. Defaults to `"default"`; do not target `task()`. */
+    readonly name?: string;
+};
+type SecondPart = {
+    readonly [endpointSymbol]: true;
+    readonly id: number;
+    /** Logical export order used to match worker tasks before names are known. */
+    readonly at: number;
+    readonly importedFrom: string;
+    /**
+     * Imported tasks stay on worker lanes so imports run under worker permissions.
+     */
+    readonly imported?: boolean;
+};
+type SingleTaskPool<A extends TaskInput = Args, B extends Args = Args, AS extends AbortSignalOption = undefined> = {
+    /** Invoke the single task. Arguments may be native Promises. */
+    call: PromiseWrapped<TaskFn<A, B, AS>, AS>;
+    /** Await worker teardown now. `using` disposes at scope exit without awaiting. */
+    shutdown: (delayMs?: number) => Promise<void>;
+    /** Starts shutdown at scope exit. Use `shutdown()` when you must await it. */
+    [Symbol.dispose]: () => void;
+};
+type Pool<T extends Record<string, TaskLike<any> | TaskFunctionLike>> = {
+    /** Await worker teardown now. `using` disposes at scope exit without awaiting. */
+    shutdown: (delayMs?: number) => Promise<void>;
+    /** Starts shutdown at scope exit. Use `shutdown()` when you must await it. */
+    [Symbol.dispose]: () => void;
+    /**
+     * Typed task callers. Each call accepts the task input or a native Promise.
+     * Thrown errors/rejections reject here as Error objects with cause chains.
+     */
+    call: FunctionMapType<T>;
+};
+type ReturnFixed<A extends TaskInput = undefined, B extends Args = undefined, AS extends AbortSignalOption = undefined> = FixPoint<A, B, AS> & SecondPart & {
+    createPool: (options?: CreatePool) => SingleTaskPool<A, B, AS>;
+};
+type External = unknown;
+type Inliner = {
+    position?: "first" | "last";
+    /**
+     * Inline tasks per event loop tick.
+     * Defaults to 1 when inliner is enabled.
+     */
+    batchSize?: number;
+    /**
+     * Minimum in-flight calls before routing can use the inline host lane.
+     * Defaults to 1 (inline lane available immediately).
+     */
+    dispatchThreshold?: number;
+};
+type BalancerStrategy = "roundRobin" | "robinRound" | "firstIdle" | "randomLane" | "firstIdleOrRandom";
+type Balancer = BalancerStrategy | {
+    /**
+     * Optional. Defaults to "roundRobin".
+     */
+    strategy?: BalancerStrategy;
+};
+/** Debug namespaces for host setup, worker state, imports, globals, and lifecycle. */
+type DebugNamespace = "host" | "globals" | "signals" | "imports" | "lifecycle";
+type DebugFlags = {
+    [Namespace in DebugNamespace]?: boolean;
+};
+/** Pass `true` for all debug, or enable namespaces by name. */
+type DebugOptions = boolean | DebugFlags;
+type WorkerBootstrapContext = {
+    readonly thread: number;
+    readonly totalNumberOfThread: number;
+    readonly runtime: "node" | "deno" | "bun" | "unknown";
+};
+type WorkerBootstrapFunction<Data = unknown> = (data: Data, context: WorkerBootstrapContext) => MaybePromise<void>;
+type WorkerBootstrapOptions<Data = unknown> = {
+    /**
+     * Module imported inside the worker before task modules are imported.
+     * Relative paths are resolved from the `createPool(...)` caller.
+     */
+    href: string;
+    /**
+     * Exported bootstrap function name. Defaults to `"default"`.
+     */
+    name?: string;
+    /**
+     * Structured data passed to the bootstrap function.
+     */
+    data?: Data;
+};
+/** Native worker artifact and on-demand compiler settings. */
+type CompiledWorkerOptions = {
+    /**
+     * Native executable path. Relative paths resolve from the createPool caller.
+     * Defaults to the task module path with its extension replaced by `.knt`.
+     */
+    artifact?: string;
+    /**
+     * Versioned metadata sidecar. Defaults to `<artifact>.json`.
+     */
+    manifest?: string;
+    /**
+     * Build a missing/incompatible artifact, or use `"always"` to rebuild once
+     * whenever a pool is created. Defaults to true.
+     */
+    build?: boolean | "always";
+    /**
+     * Porffor main executable or checkout. Defaults to PORFFOR_MAIN/PORF, then
+     * `porf` on PATH; a pinned compiler is cached locally when none is present.
+     */
+    compiler?: string;
+};
+type CompiledWorkerSource = string | URL | {
+    readonly importedFrom: string;
+};
+type CompiledWorkerCheck = {
+    /** True only when the executable and compatible manifest both validate. */
+    compiled: boolean;
+    artifact: string;
+    manifest: string;
+    reason?: string;
+    compiler?: string;
+    protocol?: string;
+    tasks?: readonly string[];
+};
+type WorkerSettings = {
+    resolveAfterFinishingAll?: true;
+    /**
+     * Privileged async worker hook that runs once before task modules import.
+     * Use it to shape the worker environment before user task code loads.
+     */
+    bootstrap?: WorkerBootstrapOptions;
+    /**
+     * Experimental worker runtime.
+     * "thread" uses Worker/worker_threads. "process" spawns another JavaScript
+     * runtime, useful for process isolation, bwrap, and containers. "compiled"
+     * validates and runs a `.knt` native worker, building it on first use.
+     */
+    runtime?: "thread" | "process" | "compiled";
+    /** Artifact settings used when runtime is "compiled". */
+    compiled?: CompiledWorkerOptions;
+    /**
+     * Runtime executable for process workers. Standalone `"porffor"` selects the
+     * compiled backend and rebuilds once per pool; with `runtime: "compiled"` it
+     * reuses the validated artifact.
+     */
+    processRuntime?: "bun" | "deno" | "node" | "porffor";
+    /**
+     * Command argv to prepend before the process worker runtime command.
+     * Useful for wrappers such as systemd-run, cgexec, nice, taskset, or
+     * docker. Knitting appends the runtime command after this prefix.
+     *
+     * Example:
+     * ["systemd-run", "--scope", "-p", "MemoryMax=500M", "-p", "CPUQuota=25%"]
+     *
+     * With containers, use processSharedMemory: "named", share the IPC
+     * namespace, mount the worker files at the same path, and forward
+     * KNITTING_PROCESS_WORKER plus KNITTING_PROCESS_WORKER_BOOT.
+     */
+    processCommandPrefix?: string[];
+    /**
+     * How process workers discover their shared-memory control channel.
+     *
+     * "inherit" keeps the POSIX fd-inheritance path and is the default outside
+     * Windows. "named" creates an OS-named shared-memory object that wrappers
+     * such as containers can reopen by name when they share the same IPC
+     * namespace.
+     */
+    processSharedMemory?: ProcessSharedMemoryMode | ProcessSharedMemorySettings;
+    timers?: WorkerTimers;
+    /**
+     * Hard task execution timeout in milliseconds.
+     * When exceeded, the pool is force-shutdown to stop runaway CPU tasks.
+     */
+    hardTimeoutMs?: number;
+};
+type ProcessSharedMemoryMode = "inherit" | "named";
+type ProcessSharedMemorySettings = {
+    mode?: ProcessSharedMemoryMode;
+    namePrefix?: string;
+    unlinkOnShutdown?: boolean;
+};
+type WorkerTimers = {
+    /**
+     * Busy-spin budget before parking (microseconds).
+     */
+    spinMicroseconds?: number;
+    /**
+     * Atomics.wait timeout when parked (milliseconds).
+     */
+    parkMs?: number;
+    /**
+     * Atomics.pause duration during spin (nanoseconds).
+     * Set to 0 (or less) to disable pause calls.
+     */
+    pauseNanoseconds?: number;
+};
+type DispatcherSettings = {
+    /**
+     * How many immediate notify loops before backoff kicks in.
+     */
+    stallFreeLoops?: number;
+    /**
+     * Max backoff delay (milliseconds).
+     */
+    maxBackoffMs?: number;
+    /**
+     * Host dispatcher topology.
+     * - `"per-thread"`: each worker owns its dispatcher and macro channel.
+     * - `"serial-channel"`: each worker keeps its own dispatcher check state, but
+     *   one shared channel runs all lane checks from first to last.
+     *
+     * Experimental default: `"per-thread"` on Bun or with one worker, otherwise
+     * `"serial-channel"` for multi-worker Node/Deno pools. Can also be forced
+     * with the `KNITTING_DISPATCHER` env var (`serial-channel` or `per-thread`).
+     */
+    dispatcher?: "per-thread" | "serial-channel";
+};
+type CreatePool = {
+    /** Number of workers. Default: 1. */
+    threads?: number;
+    /** Add a host inline lane for regular tasks. Imported tasks still use workers. */
+    inliner?: Inliner;
+    balancer?: Balancer;
+    worker?: WorkerSettings;
+    /**
+     * Payload transport settings. Default dynamic payload cap is about 8 MiB
+     * (`payloadMaxByteLength >> 3`, with a 64 MiB growth cap).
+     */
+    payload?: PayloadBufferOptions;
+    /**
+     * Experimental unsafe options.
+     */
+    unsafe?: UnsafeOptions;
+    /**
+     * Abort-aware signal pool capacity.
+     * Defaults to `258`.
+     */
+    abortSignalCapacity?: number;
+    /**
+     * Host dispatcher backoff and scheduling options.
+     */
+    host?: DispatcherSettings;
+    /**
+     * Extra Node.js execArgv flags for worker threads (e.g. ["--expose-gc"]).
+     * Defaults to process.execArgv plus "--expose-gc" when allowed.
+     */
+    workerExecArgv?: string[];
+    /**
+     * Runtime permission protocol.
+     * Omit to use strict defaults with `allowImport: true`; worker console is
+     * quiet unless `permission: { console: true }`.
+     *
+     * Task code cannot terminate the host: process/Deno exit APIs are blocked.
+     * Use `"strict"` (default for object mode) or `"unsafe"`.
+     * Accepts object form for fine-grained permission controls.
+     */
+    permission?: PermissionProtocolInput;
+    debug?: DebugOptions;
+    source?: string;
+};
+export type { AbortSignalConfig as AbortSignalConfig, AbortSignalMethods as AbortSignalMethods, AbortSignalOption as AbortSignalOption, AbortSignalToolkit as AbortSignalToolkit, Args as Args, Balancer as Balancer, BalancerStrategy as BalancerStrategy, CompiledWorkerCheck as CompiledWorkerCheck, CompiledWorkerOptions as CompiledWorkerOptions, CompiledWorkerSource as CompiledWorkerSource, Composed as Composed, ComposedWithKey as ComposedWithKey, CreateContext as CreateContext, CreatePool as CreatePool, DebugNamespace as DebugNamespace, DebugOptions as DebugOptions, DispatcherSettings as DispatcherSettings, Envelope as Envelope, EnvelopeBody as EnvelopeBody, EnvelopeHeader as EnvelopeHeader, External as External, FixPoint as FixPoint, FunctionMapType as FunctionMapType, ImportTaskOptions as ImportTaskOptions, Inliner as Inliner, LockBuffers as LockBuffers, LockBufferTextCompat as LockBufferTextCompat, MaybePromise as MaybePromise, PayloadBufferMode as PayloadBufferMode, PayloadBufferOptions as PayloadBufferOptions, PermissionProtocol as PermissionProtocol, PermissionProtocolInput as PermissionProtocolInput, Pool as Pool, ProcessSharedMemoryMode as ProcessSharedMemoryMode, ProcessSharedMemorySettings as ProcessSharedMemorySettings, ResolvedPermissionProtocol as ResolvedPermissionProtocol, ReturnFixed as ReturnFixed, SecondPart as SecondPart, SharedBufferRegion as SharedBufferRegion, SharedBufferSource as SharedBufferSource, SharedBufferTextCompat as SharedBufferTextCompat, SingleTaskPool as SingleTaskPool, TaskFn as TaskFn, TaskInput as TaskInput, tasks as tasks, TaskTimeout as TaskTimeout, ValidInput as ValidInput, WorkerBootstrapContext as WorkerBootstrapContext, WorkerBootstrapFunction as WorkerBootstrapFunction, WorkerBootstrapOptions as WorkerBootstrapOptions, WorkerCall as WorkerCall, WorkerContext as WorkerContext, WorkerData as WorkerData, WorkerInvoke as WorkerInvoke, WorkerSettings as WorkerSettings, WorkerTimers as WorkerTimers, };
+import type { Task as TaskType } from "./memory/lock.js";
+export { LockBound as LockBound, PayloadBuffer as PayloadBuffer, PayloadSignal as PayloadSignal, TaskIndex as TaskIndex, } from "./memory/lock.js";
+export type Task = TaskType;
+export type { RegisterMalloc as RegisterMalloc } from "./memory/regionRegistry.js";

package/src/types.js

@@ -0,0 +1,2 @@
+import { endpointSymbol } from "./common/task-symbol.js";
+export { LockBound as LockBound, PayloadBuffer as PayloadBuffer, PayloadSignal as PayloadSignal, TaskIndex as TaskIndex, } from "./memory/lock.js";

package/src/utils/http.d.ts

@@ -0,0 +1,29 @@
+export type BufferLike = ArrayBuffer | SharedArrayBuffer | ArrayBufferView;
+export type NumberFormat = "f64" | "f32" | "i32";
+export type NumberBufferOptions = {
+    format?: NumberFormat;
+};
+/** View ArrayBuffer/SharedArrayBuffer/typed-array bytes as Uint8Array. */
+export declare const bufferToBytes: (source: BufferLike) => Uint8Array;
+/** Copy bytes into a SharedArrayBuffer for zero-copy worker inputs. */
+export declare const bytesToBuffer: (source: BufferLike) => SharedArrayBuffer;
+/** Decode UTF-8 bytes from ArrayBuffer/SharedArrayBuffer/typed-array input. */
+export declare const bufferToString: (source: BufferLike) => string;
+/** Encode UTF-8 text into a SharedArrayBuffer. */
+export declare const stringToBuffer: (text: string) => SharedArrayBuffer;
+/** Decode JSON from UTF-8 bytes. */
+export declare const bufferToJson: <T = unknown>(source: BufferLike) => T;
+/** Encode JSON into a SharedArrayBuffer. */
+export declare const jsonToBuffer: (value: unknown) => SharedArrayBuffer;
+/** Encode numbers into a SharedArrayBuffer (`f64` by default). */
+export declare const numbersToBuffer: (numbers: ArrayLike<number>, options?: NumberBufferOptions) => SharedArrayBuffer;
+/** Decode numeric typed-array views from worker-friendly byte buffers. */
+export declare function bufferToNumbers(source: BufferLike, options?: {
+    format?: "f64";
+}): Float64Array;
+export declare function bufferToNumbers(source: BufferLike, options: {
+    format: "f32";
+}): Float32Array;
+export declare function bufferToNumbers(source: BufferLike, options: {
+    format: "i32";
+}): Int32Array;

package/src/utils/http.js

@@ -0,0 +1,100 @@
+const nodeBuffer = globalThis.Buffer;
+const hasNodeBuffer = typeof nodeBuffer?.from === "function" &&
+    typeof nodeBuffer?.byteLength === "function";
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+const hasSharedArrayBuffer = typeof SharedArrayBuffer === "function";
+const isSharedArrayBuffer = (value) => hasSharedArrayBuffer && value instanceof SharedArrayBuffer;
+const BYTES_PER_ELEMENT = {
+    f64: 8,
+    f32: 4,
+    i32: 4,
+};
+const toBytes = (source) => {
+    if (source instanceof Uint8Array)
+        return source;
+    if (ArrayBuffer.isView(source)) {
+        return new Uint8Array(source.buffer, source.byteOffset, source.byteLength);
+    }
+    if (source instanceof ArrayBuffer || isSharedArrayBuffer(source)) {
+        return new Uint8Array(source);
+    }
+    throw new TypeError("Expected an ArrayBuffer, SharedArrayBuffer, or typed-array view.");
+};
+/** View ArrayBuffer/SharedArrayBuffer/typed-array bytes as Uint8Array. */
+export const bufferToBytes = (source) => toBytes(source);
+/** Copy bytes into a SharedArrayBuffer for zero-copy worker inputs. */
+export const bytesToBuffer = (source) => {
+    const bytes = toBytes(source);
+    const sab = new SharedArrayBuffer(bytes.byteLength);
+    new Uint8Array(sab).set(bytes);
+    return sab;
+};
+const makeNumberView = (format, buffer, byteOffset, length) => {
+    switch (format) {
+        case "f64":
+            return new Float64Array(buffer, byteOffset, length);
+        case "f32":
+            return new Float32Array(buffer, byteOffset, length);
+        case "i32":
+            return new Int32Array(buffer, byteOffset, length);
+    }
+};
+/** Decode UTF-8 bytes from ArrayBuffer/SharedArrayBuffer/typed-array input. */
+export const bufferToString = (source) => {
+    const bytes = toBytes(source);
+    if (hasNodeBuffer) {
+        return nodeBuffer
+            .from(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+            .toString("utf8");
+    }
+    return textDecoder.decode(bytes);
+};
+/** Encode UTF-8 text into a SharedArrayBuffer. */
+export const stringToBuffer = (text) => {
+    if (typeof text !== "string") {
+        throw new TypeError("stringToBuffer expects a string.");
+    }
+    if (hasNodeBuffer) {
+        const byteLength = nodeBuffer.byteLength(text, "utf8");
+        const sab = new SharedArrayBuffer(byteLength);
+        nodeBuffer.from(sab).write(text, "utf8");
+        return sab;
+    }
+    const encoded = textEncoder.encode(text);
+    const sab = new SharedArrayBuffer(encoded.byteLength);
+    new Uint8Array(sab).set(encoded);
+    return sab;
+};
+/** Decode JSON from UTF-8 bytes. */
+export const bufferToJson = (source) => JSON.parse(bufferToString(source));
+/** Encode JSON into a SharedArrayBuffer. */
+export const jsonToBuffer = (value) => {
+    const text = JSON.stringify(value);
+    if (typeof text !== "string") {
+        throw new TypeError("jsonToBuffer: value is not JSON-serializable (stringify returned undefined).");
+    }
+    return stringToBuffer(text);
+};
+/** Encode numbers into a SharedArrayBuffer (`f64` by default). */
+export const numbersToBuffer = (numbers, options) => {
+    const format = options?.format ?? "f64";
+    const sab = new SharedArrayBuffer(numbers.length * BYTES_PER_ELEMENT[format]);
+    makeNumberView(format, sab, 0, numbers.length).set(numbers);
+    return sab;
+};
+export function bufferToNumbers(source, options) {
+    const format = options?.format ?? "f64";
+    const bytesPer = BYTES_PER_ELEMENT[format];
+    const bytes = toBytes(source);
+    if (bytes.byteLength % bytesPer !== 0) {
+        throw new RangeError(`bufferToNumbers: byte length ${bytes.byteLength} is not a multiple of ` +
+            `${bytesPer} for format "${format}".`);
+    }
+    const length = bytes.byteLength / bytesPer;
+    if (bytes.byteOffset % bytesPer === 0) {
+        return makeNumberView(format, bytes.buffer, bytes.byteOffset, length);
+    }
+    const copy = bytes.slice();
+    return makeNumberView(format, copy.buffer, 0, length);
+}

package/src/worker/bootstrap.d.ts

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

package/src/worker/bootstrap.js

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

package/src/worker/composable-runners.d.ts

@@ -0,0 +1,12 @@
+import { type Task } from "../memory/lock.js";
+import type { TimeoutSpec } from "./task-loader.js";
+type WorkerJob = (args: unknown, abortToolkit?: unknown) => unknown;
+type SlotRunner = (slot: Task) => unknown;
+type HasAborted = (signal: number) => boolean;
+export declare const composeWorkerRunner: ({ job, timeout, hasAborted, now, }: {
+    job: WorkerJob;
+    timeout?: TimeoutSpec;
+    hasAborted?: HasAborted;
+    now?: () => number;
+}) => SlotRunner;
+export {};