knitting 0.1.54 → 0.1.55

package/knitting.d.ts

@@ -1,5 +1,797 @@
-import { workerMainLoop } from "./src/worker/loop.js";
-import { createPool, importTask, isMain, task } from "./src/api.js";
-import { Envelope } from "./src/common/envelope.js";
-export { createPool as createPool, Envelope as Envelope, importTask as importTask, isMain as isMain, task as task, workerMainLoop as workerMainLoop, };
-export type { EnvelopeBody as EnvelopeBody, EnvelopeHeader as EnvelopeHeader, } from "./src/common/envelope.js";
+declare const endpointSymbol: unique symbol;
+type BufferReferenceRuntime = "node" | "deno" | "bun";
+declare const BUFFER_REFERENCE_KIND: "knitting.bufferReference";
+declare const BUFFER_REFERENCE_NUMERIC_TRANSFER: unique symbol;
+declare const EXTERNAL_PAYLOAD_BRAND: unique symbol;
+type BufferReferenceNumericMetadata = readonly [
+	pointerLow: number,
+	pointerHigh: number,
+	tokenLow: number,
+	tokenHigh: number,
+	byteOffset: number,
+	byteLength: number,
+	runtime: number,
+	originPid: number
+];
+type BufferReferenceMetadata = {
+	readonly kind: typeof BUFFER_REFERENCE_KIND;
+	readonly origin: string;
+	readonly runtime: BufferReferenceRuntime;
+	readonly pointer: string;
+	/** Producer-side release handle (process-local). */
+	readonly token: string;
+	readonly byteOffset: number;
+	readonly byteLength: number;
+};
+type BufferReferenceReturnReleaser = (token: bigint) => void;
+type BufferSource$1 = ArrayBufferView | ArrayBuffer;
+declare const PAYLOAD_TRANSPORT_FINALIZER: unique symbol;
+declare class BufferReference {
+	#private;
+	readonly [EXTERNAL_PAYLOAD_BRAND]: "knitting.bufferReference";
+	readonly runtime: BufferReferenceRuntime;
+	readonly origin: string;
+	readonly pointer: bigint;
+	readonly byteOffset: number;
+	readonly byteLength: number;
+	constructor(source: BufferSource$1);
+	constructor(source: BufferSource$1 | undefined, meta: BufferReferenceMetadata);
+	static fromMetadata(meta: BufferReferenceMetadata): BufferReference;
+	toMetadata(): BufferReferenceMetadata;
+	[BUFFER_REFERENCE_NUMERIC_TRANSFER](): BufferReferenceNumericMetadata | undefined;
+	get isLocal(): boolean;
+	/** Prepare a returned reference before the worker-side producer hold drains. */
+	claimOwnership(releaser?: BufferReferenceReturnReleaser): this;
+	toArrayBuffer(): ArrayBuffer;
+	toUint8Array(): Uint8Array;
+	/** The source is moved on construction, so it is never retained here. */
+	get source(): undefined;
+	release(): void;
+	[Symbol.dispose](): void;
+	[PAYLOAD_TRANSPORT_FINALIZER](): (() => void) | undefined;
+}
+type SharedBuffer = SharedArrayBuffer | ArrayBuffer;
+type SharedBufferRegion = {
+	sab: SharedBuffer;
+	byteOffset: number;
+	byteLength: number;
+};
+type SharedBufferSource = SharedBuffer | SharedBufferRegion;
+type ConnectionRuntime = "node" | "deno" | "bun";
+type SharedMemoryBuffer = ArrayBuffer | SharedArrayBuffer;
+type SharedMemoryBufferKind = "shared-array-buffer" | "external-array-buffer";
+type SharedMemoryCreateMode = "anonymous" | "create" | "open";
+type SharedMemoryMapping<Buffer extends SharedMemoryBuffer = SharedMemoryBuffer> = {
+	runtime: ConnectionRuntime;
+	fd: number;
+	name?: string;
+	size: number;
+	byteLength: number;
+	buffer: Buffer;
+	kind: SharedMemoryBufferKind;
+	sab?: SharedArrayBuffer;
+	arrayBuffer?: ArrayBuffer;
+	baseAddressMod64?: number;
+	unsafePointer?: unknown;
+	close?: () => void;
+};
+type CreateSharedMemoryOptions = {
+	size: number;
+	/**
+	 * `anonymous` keeps the current fd-backed private mapping behavior.
+	 * `create` and `open` use a named shared-memory object so independent
+	 * processes can rendezvous by name.
+	 */
+	mode?: SharedMemoryCreateMode;
+	name?: string;
+};
+type MapSharedMemoryOptions = {
+	fd: number;
+	name?: string;
+	size: number;
+	duplicateFd?: boolean;
+};
+type SharedMemoryConnectionPrimitives<Mapping extends SharedMemoryMapping = SharedMemoryMapping> = {
+	runtime: ConnectionRuntime;
+	createSharedMemory: (options: number | CreateSharedMemoryOptions) => Mapping;
+	mapSharedMemory: (options: MapSharedMemoryOptions) => Mapping;
+	unlinkSharedMemory?: (name: string) => boolean;
+};
+type FileDescriptorMetadata = {
+	version: 1;
+	fd: number;
+	name?: string;
+	size: number;
+	byteLength: number;
+	runtime?: ConnectionRuntime;
+	kind?: SharedMemoryMapping["kind"];
+	baseAddressMod64?: number;
+};
+type FileDescriptorMapper = Pick<SharedMemoryConnectionPrimitives, "mapSharedMemory">;
+declare class FileDescriptor {
+	#private;
+	readonly fd: number;
+	readonly name?: string;
+	readonly size: number;
+	readonly byteLength: number;
+	readonly runtime?: ConnectionRuntime;
+	readonly kind?: SharedMemoryMapping["kind"];
+	readonly baseAddressMod64?: number;
+	constructor(metadata: FileDescriptorMetadata, mapping?: SharedMemoryMapping);
+	static fromMapping(mapping: SharedMemoryMapping): FileDescriptor;
+	static fromMetadata(metadata: unknown): FileDescriptor;
+	static parse(serialized: string): FileDescriptor;
+	toMetadata(): FileDescriptorMetadata;
+	toJSON(): FileDescriptorMetadata;
+	stringify(): string;
+	stringifyMetadata(): string;
+	toString(): string;
+	attach(mapping: SharedMemoryMapping): this;
+	get mapping(): SharedMemoryMapping | undefined;
+	map(mapper: FileDescriptorMapper): SharedMemoryMapping;
+	getBuffer(mapper?: FileDescriptorMapper): SharedMemoryBuffer;
+	getSharedArrayBuffer(mapper?: FileDescriptorMapper): SharedArrayBuffer;
+	getSAB(mapper?: FileDescriptorMapper): SharedArrayBuffer;
+}
+type ProcessSharedBufferMetadata = {
+	version: 1;
+	descriptor: FileDescriptorMetadata;
+	byteOffset: number;
+	byteLength: number;
+};
+declare const PROCESS_SHARED_BUFFER_BRAND: unique symbol;
+declare const PROCESS_SHARED_BUFFER_NUMERIC_TRANSFER: unique symbol;
+declare const EXTERNAL_PAYLOAD_BRAND$1: unique symbol;
+type ProcessSharedBufferNumericMetadata = readonly [
+	fd: number,
+	size: number,
+	descriptorByteLength: number,
+	byteOffset: number,
+	byteLength: number,
+	runtime: number,
+	kind: number,
+	baseAddressMod64: number
+];
+type ProcessSharedBufferRange = {
+	byteOffset?: number;
+	byteLength?: number;
+};
+type ProcessSharedBufferCreator = Pick<SharedMemoryConnectionPrimitives, "createSharedMemory">;
+type ProcessSharedBufferMapper = Pick<SharedMemoryConnectionPrimitives, "mapSharedMemory">;
+type ProcessSharedBufferView = Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | BigInt64Array | BigUint64Array | Float32Array | Float64Array;
+type ProcessSharedBufferViewConstructor<View extends ProcessSharedBufferView = ProcessSharedBufferView> = {
+	readonly BYTES_PER_ELEMENT: number;
+	new (buffer: SharedBuffer, byteOffset: number, length: number): View;
+};
+declare class ProcessSharedBuffer {
+	readonly [PROCESS_SHARED_BUFFER_BRAND] = true;
+	readonly [EXTERNAL_PAYLOAD_BRAND$1] = "knitting.processSharedBuffer";
+	readonly descriptor: FileDescriptor;
+	readonly byteOffset: number;
+	readonly byteLength: number;
+	constructor(descriptor: FileDescriptor, range?: ProcessSharedBufferRange);
+	static create(options: number | CreateSharedMemoryOptions, creator?: ProcessSharedBufferCreator): ProcessSharedBuffer;
+	static fromMapping(mapping: SharedMemoryMapping): ProcessSharedBuffer;
+	static fromDescriptor(descriptor: FileDescriptor, range?: ProcessSharedBufferRange): ProcessSharedBuffer;
+	static fromMetadata(metadata: unknown): ProcessSharedBuffer;
+	static parse(serialized: string): ProcessSharedBuffer;
+	static [PROCESS_SHARED_BUFFER_NUMERIC_TRANSFER](metadata: ProcessSharedBufferNumericMetadata): ProcessSharedBuffer;
+	get fd(): number;
+	get size(): number;
+	subbuffer(byteOffset: number, byteLength?: number): ProcessSharedBuffer;
+	getSharedArrayBuffer(mapper?: ProcessSharedBufferMapper): SharedArrayBuffer;
+	getSAB(mapper?: ProcessSharedBufferMapper): SharedArrayBuffer;
+	getBuffer(mapper?: ProcessSharedBufferMapper): SharedBuffer;
+	getRegion(mapper?: ProcessSharedBufferMapper): SharedBufferRegion;
+	view<View extends ProcessSharedBufferView>(constructor: ProcessSharedBufferViewConstructor<View>, mapper?: ProcessSharedBufferMapper): View;
+	bytes(mapper?: ProcessSharedBufferMapper): Uint8Array;
+	dataView(mapper?: ProcessSharedBufferMapper): DataView;
+	toMetadata(): ProcessSharedBufferMetadata;
+	toJSON(): ProcessSharedBufferMetadata;
+	stringify(): string;
+	stringifyMetadata(): string;
+	toString(): string;
+}
+type EnvelopeHeaderPrimitive = string | number | boolean | null;
+type EnvelopeHeaderValue = EnvelopeHeaderPrimitive | EnvelopeHeaderValue[] | {
+	[key: string]: EnvelopeHeaderValue;
+};
+export type EnvelopeHeader = EnvelopeHeaderValue;
+export type EnvelopeBody = ArrayBuffer | SharedArrayBuffer | BufferReference | ProcessSharedBuffer;
+declare const PayloadTransportFinalizer: unique symbol;
+export declare class Envelope<H extends EnvelopeHeader = EnvelopeHeader, B extends EnvelopeBody = ArrayBuffer> {
+	readonly header: H;
+	readonly payload: B;
+	constructor(header: H, payload: B);
+	[Symbol.dispose](): void;
+	[PayloadTransportFinalizer](): (() => void) | undefined;
+}
+type SharedBufferTextCompat = {
+	encodeInto: boolean;
+	decode: boolean;
+};
+type LockBufferTextCompat = {
+	headers: SharedBufferTextCompat;
+	payload: SharedBufferTextCompat;
+};
+type PayloadBufferMode = "growable" | "fixed";
+type PayloadBufferOptions = {
+	/** Shared payload buffer mode. Defaults to growable when available. */
+	mode?: PayloadBufferMode;
+	/** Initial shared payload bytes per direction. Defaults to 4 MiB when growable. */
+	payloadInitialBytes?: number;
+	/** Shared payload growth cap. Defaults to 64 MiB. */
+	payloadMaxByteLength?: number;
+	/**
+	 * Max dynamic payload bytes for one call. Defaults to `payloadMaxByteLength >> 3`
+	 * (about 8 MiB by default) and must stay `<= payloadMaxByteLength >> 3`.
+	 * Over-cap payloads reject with `KNT_ERROR_3`.
+	 */
+	maxPayloadBytes?: number;
+};
+type PermissionPath = string | URL;
+type NodePermissionSettings = {
+	allowWorker?: boolean;
+	allowChildProcess?: boolean;
+	allowAddons?: boolean;
+	allowWasi?: boolean;
+};
+type DenoPermissionSettings = {
+	lock?: boolean | PermissionPath;
+	frozen?: boolean;
+	/**
+	 * Legacy compatibility: superseded by top-level `run`.
+	 */
+	allowRun?: boolean;
+};
+type SysApiName = "hostname" | "osRelease" | "osUptime" | "loadavg" | "networkInterfaces" | "systemMemoryInfo" | "uid" | "gid";
+type PermissionEnvironment = {
+	allow?: string[] | true;
+	deny?: string[];
+	files?: PermissionPath | PermissionPath[];
+};
+type PermissionMode = "strict" | "unsafe" | "custom";
+type PermissionLegacyMode = "off";
+type PermissionProtocol = {
+	/**
+	 * `strict` = hardened defaults, `unsafe` = full access,
+	 * `custom` = strict baseline with user overrides.
+	 */
+	mode?: PermissionMode;
+	/**
+	 * Console access for worker task code.
+	 * Defaults to `false` in strict/custom mode, `true` in unsafe mode.
+	 */
+	console?: boolean;
+	/**
+	 * Base directory used to resolve relative paths.
+	 * Defaults to the current shell working directory.
+	 */
+	cwd?: string;
+	/**
+	 * Read allow-list. `true` means unrestricted access.
+	 */
+	read?: PermissionPath[] | true;
+	/**
+	 * Write allow-list. `true` means unrestricted access.
+	 */
+	write?: PermissionPath[] | true;
+	/**
+	 * Explicit deny-read entries.
+	 */
+	denyRead?: PermissionPath[];
+	/**
+	 * Explicit deny-write entries.
+	 */
+	denyWrite?: PermissionPath[];
+	/**
+	 * Network allow-list. `true` means unrestricted access.
+	 */
+	net?: string[] | true;
+	/**
+	 * Explicit network deny-list.
+	 */
+	denyNet?: string[];
+	/**
+	 * Allowed import hostnames. `true` means unrestricted import hosts.
+	 */
+	allowImport?: string[] | true;
+	/**
+	 * Environment permission settings.
+	 */
+	env?: PermissionEnvironment;
+	/**
+	 * Subprocess allow-list. `true` means unrestricted access.
+	 */
+	run?: string[] | true;
+	/**
+	 * Explicit subprocess deny-list.
+	 */
+	denyRun?: string[];
+	/**
+	 * Whether worker spawning is allowed.
+	 */
+	workers?: boolean;
+	/**
+	 * FFI allow-list or toggle.
+	 */
+	ffi?: PermissionPath[] | boolean;
+	/**
+	 * Explicit FFI deny-list.
+	 */
+	denyFfi?: PermissionPath[];
+	/**
+	 * System API allow-list. `true` means unrestricted access.
+	 */
+	sys?: SysApiName[] | true;
+	/**
+	 * Explicit system API deny-list.
+	 */
+	denySys?: SysApiName[];
+	/**
+	 * Whether WASI is allowed.
+	 */
+	wasi?: boolean;
+	/**
+	 * Backward-compat runtime overrides.
+	 */
+	node?: NodePermissionSettings;
+	deno?: DenoPermissionSettings;
+};
+type PermissionProtocolInput = PermissionMode | PermissionLegacyMode | PermissionProtocol;
+type L3RuntimeKeys = {
+	deno: string[];
+	node: string[];
+};
+type ResolvedPermissionProtocol = {
+	enabled: boolean;
+	mode: PermissionMode;
+	unsafe: boolean;
+	allowConsole: boolean;
+	cwd: string;
+	read: string[];
+	readAll: boolean;
+	write: string[];
+	writeAll: boolean;
+	denyRead: string[];
+	denyWrite: string[];
+	net: string[];
+	netAll: boolean;
+	denyNet: string[];
+	allowImport: string[];
+	allowImportAll: boolean;
+	env: {
+		allow: string[];
+		allowAll: boolean;
+		deny: string[];
+		files: string[];
+	};
+	envFiles: string[];
+	run: string[];
+	runAll: boolean;
+	denyRun: string[];
+	workers: boolean;
+	ffi: string[];
+	ffiAll: boolean;
+	denyFfi: string[];
+	sys: SysApiName[];
+	sysAll: boolean;
+	denySys: SysApiName[];
+	wasi: boolean;
+	lockFiles: {
+		deno?: string;
+	};
+	node: Required<NodePermissionSettings> & {
+		flags: string[];
+	};
+	deno: Required<Omit<DenoPermissionSettings, "lock">> & {
+		flags: string[];
+	};
+	l3: L3RuntimeKeys;
+};
+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>;
+type NoBlob<T> = T extends Blob ? never : T;
+type TaskInput = NoBlob<Args> | Promise<NoBlob<Args>>;
+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;
+};
+type AbortSignalOption = true | AbortSignalConfig | undefined;
+type AbortSignalMethods<AS extends AbortSignalOption> = AS extends undefined ? never : {
+	hasAborted: () => boolean;
+};
+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 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 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;
+};
+type DebugNamespace = "host" | "globals" | "signals" | "imports" | "lifecycle";
+type DebugFlags = {
+	[Namespace in DebugNamespace]?: boolean;
+};
+type DebugOptions = boolean | DebugFlags;
+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;
+};
+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.
+	 */
+	runtime?: "thread" | "process";
+	/**
+	 * Runtime executable to use when runtime is "process". Defaults to "deno".
+	 */
+	processRuntime?: "bun" | "deno" | "node";
+	/**
+	 * 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 declare const workerMainLoop: (startupData: WorkerData) => Promise<void>;
+type CreatePoolFactory = (options: CreatePool) => <T extends tasks>(tasks: T) => Pool<T>;
+type InferredTaskFunction = (...args: any[]) => MaybePromise<Args>;
+type InferredTaskInput<F extends InferredTaskFunction, AS extends AbortSignalOption> = Parameters<F> extends [
+] ? void : AS extends undefined ? Parameters<F> extends [
+	infer A
+] ? A extends TaskInput ? A : never : never : Parameters<F> extends [
+	infer A
+] ? A extends TaskInput ? A : never : Parameters<F> extends [
+	infer A,
+	AbortSignalToolkit<AS>
+] ? A extends TaskInput ? A : never : never;
+type InferredTaskOutput<F extends InferredTaskFunction> = Awaited<ReturnType<F>> extends infer R ? R extends Blob ? never : R extends Args ? R : never : never;
+type InferredTaskShape<F extends InferredTaskFunction, AS extends AbortSignalOption> = [
+	InferredTaskInput<F, AS>
+] extends [
+	never
+] ? never : [
+	InferredTaskOutput<F>
+] extends [
+	never
+] ? never : {
+	readonly f: F;
+	readonly timeout?: TaskTimeout;
+} & (AS extends undefined ? {
+	readonly abortSignal?: undefined;
+} : {
+	readonly abortSignal: AS;
+});
+export declare const isMain: boolean;
+/**
+ * Create a typed worker pool from module-scope exported tasks/functions.
+ *
+ * Install/import as `knitting` on npm or `@vixeny/knitting` on JSR. Requires
+ * Node 22+, Deno 2+, or Bun 1+.
+ *
+ * Use `createPool(options)({ taskA })`, call `await pool.call.taskA(arg)`, and
+ * clean up with `using pool = ...` or `await pool.shutdown()`.
+ *
+ * Guard host-only pool setup with `isMain`: workers re-import task modules, and
+ * top-level imports in those modules run in every worker. Keep task modules
+ * lean and separate from server/framework setup. Each task receives one
+ * argument; use an object or tuple for multiple values.
+ */
+export declare const createPool: CreatePoolFactory;
+/**
+ * Define a worker task with options.
+ *
+ * Pass raw module-scope exported functions to `createPool` directly when you do
+ * not need options. Use `task({ f })` for timeouts, abort signals, or the
+ * single-task `.createPool()` shorthand.
+ *
+ * The function receives one argument; use a tuple/object for multiple values.
+ * Inputs may be direct values or native Promises, so `request.arrayBuffer()` can
+ * be forwarded without awaiting on the host.
+ */
+export declare function task<F extends InferredTaskFunction>(I: InferredTaskShape<F, undefined>): ReturnFixed<InferredTaskInput<F, undefined>, InferredTaskOutput<F>, undefined>;
+export declare function task<F extends InferredTaskFunction>(I: InferredTaskShape<F, true>): ReturnFixed<InferredTaskInput<F, true>, InferredTaskOutput<F>, true>;
+export declare function task<AS extends AbortSignalConfig, F extends InferredTaskFunction>(I: InferredTaskShape<F, AS>): ReturnFixed<InferredTaskInput<F, AS>, InferredTaskOutput<F>, AS>;
+export declare function task<A extends TaskInput = void, B extends Args = void>(I: FixPoint<A, B, true>): ReturnFixed<A, B, true>;
+export declare function task<A extends TaskInput = void, B extends Args = void, AS extends AbortSignalConfig = AbortSignalConfig>(I: FixPoint<A, B, AS>): ReturnFixed<A, B, AS>;
+export declare function task<A extends TaskInput = void, B extends Args = void>(I: FixPoint<A, B, undefined>): ReturnFixed<A, B, undefined>;
+/**
+ * Define a task whose worker-side code is imported only by workers.
+ *
+ * Use this for untrusted or security-sensitive code: the host keeps a typed
+ * wrapper and does not import/evaluate `href`. The target export must be a
+ * plain function, not a `task()` wrapper.
+ */
+export declare function importTask<A extends TaskInput = void, B extends Args = void>(options: ImportTaskOptions<A, B, true>): ReturnFixed<A, B, true>;
+export declare function importTask<A extends TaskInput = void, B extends Args = void, AS extends AbortSignalConfig = AbortSignalConfig>(options: ImportTaskOptions<A, B, AS>): ReturnFixed<A, B, AS>;
+export declare function importTask<A extends TaskInput = void, B extends Args = void>(options: ImportTaskOptions<A, B, undefined>): ReturnFixed<A, B, undefined>;
+export declare class NumericArray extends Array<number> {
+}
+export declare const isNumericArray: (value: object) => value is NumericArray;
+
+export {};