knitting 0.1.51 → 0.1.52

package/src/common/envelope.d.ts

@@ -1,11 +1,17 @@
+import type { BufferReference } from "../connections/buffer-reference.js";
+import type { ProcessSharedBuffer } from "../connections/process-shared-buffer.js";
 type EnvelopeHeaderPrimitive = string | number | boolean | null;
 type EnvelopeHeaderValue = EnvelopeHeaderPrimitive | EnvelopeHeaderValue[] | {
     [key: string]: EnvelopeHeaderValue;
 };
 export type EnvelopeHeader = EnvelopeHeaderValue;
-export declare class Envelope<H extends EnvelopeHeader = EnvelopeHeader> {
+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: ArrayBuffer;
-    constructor(header: H, payload: ArrayBuffer);
+    readonly payload: B;
+    constructor(header: H, payload: B);
+    [Symbol.dispose](): void;
+    [PayloadTransportFinalizer](): (() => void) | undefined;
 }
 export {};

package/src/common/envelope.js

@@ -1,3 +1,4 @@
+const PayloadTransportFinalizer = Symbol.for("knitting.payloadCodec.transportFinalizer");
 export class Envelope {
     header;
     payload;
@@ -5,4 +6,17 @@ export class Envelope {
         this.header = header;
         this.payload = payload;
     }
+    [Symbol.dispose]() {
+        const body = this.payload;
+        if (body !== null && typeof body === "object") {
+            body[Symbol.dispose]?.();
+        }
+    }
+    [PayloadTransportFinalizer]() {
+        const body = this.payload;
+        if (body === null || typeof body !== "object")
+            return undefined;
+        const finalizer = body[PayloadTransportFinalizer];
+        return typeof finalizer === "function" ? finalizer.call(body) : undefined;
+    }
 }

package/src/common/worker-runtime.d.ts

@@ -28,7 +28,9 @@ export type RuntimeMessageChannelLike = {
 export declare const RUNTIME_PROCESS_WORKER_ENV = "KNITTING_PROCESS_WORKER";
 export declare const RUNTIME_PROCESS_WORKER_BOOT_ENV = "KNITTING_PROCESS_WORKER_BOOT";
 export declare const RUNTIME_PROCESS_WORKER_BOOT_VERSION = 1;
+export declare const RUNTIME_POOL_DEPTH_ENV = "KNITTING_POOL_DEPTH";
 export declare const RUNTIME_IS_PROCESS_WORKER: boolean;
+export declare const RUNTIME_POOL_DEPTH: number;
 export declare const RUNTIME_WORKER: new (specifier: string | URL, options?: Record<string, unknown>) => RuntimeWorkerLike;
 export declare const RUNTIME_MESSAGE_CHANNEL: new () => RuntimeMessageChannelLike;
 export declare const HAS_NODE_WORKER_THREADS: boolean;

package/src/common/worker-runtime.js

@@ -2,8 +2,17 @@ import { getNodeBuiltinModule, getNodeProcess } from "./node-compat.js";
 export const RUNTIME_PROCESS_WORKER_ENV = "KNITTING_PROCESS_WORKER";
 export const RUNTIME_PROCESS_WORKER_BOOT_ENV = "KNITTING_PROCESS_WORKER_BOOT";
 export const RUNTIME_PROCESS_WORKER_BOOT_VERSION = 1;
+export const RUNTIME_POOL_DEPTH_ENV = "KNITTING_POOL_DEPTH";
 const nodeProcess = getNodeProcess();
 export const RUNTIME_IS_PROCESS_WORKER = nodeProcess?.env?.[RUNTIME_PROCESS_WORKER_ENV] === "1";
+const readPoolDepth = () => {
+    const raw = nodeProcess?.env?.[RUNTIME_POOL_DEPTH_ENV];
+    if (typeof raw !== "string")
+        return 0;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
+};
+export const RUNTIME_POOL_DEPTH = readPoolDepth();
 const workerThreads = getNodeBuiltinModule("node:worker_threads");
 const isWorkerGlobalScope = () => {
     const scopeCtor = globalThis.WorkerGlobalScope;

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

@@ -0,0 +1,56 @@
+export type BufferReferenceRuntime = "node" | "deno" | "bun";
+/** A backing store the producer has taken exclusive ownership of (source detached). */
+export type ProducedBuffer = {
+    /** Producer-side release handle. */
+    token: bigint;
+    /** Address of the region start (view offset already applied). */
+    pointer: bigint;
+    /** Offset of the region inside the backing store (used by the Node owning adopt). */
+    byteOffset: number;
+    byteLength: number;
+};
+export type AdoptInput = {
+    token: bigint;
+    pointer: bigint;
+    byteOffset: number;
+    byteLength: number;
+};
+/** The materialized region: bytes live in `buffer` at `[byteOffset, byteOffset+byteLength)`. */
+export type AdoptedRegion = {
+    buffer: ArrayBuffer;
+    byteOffset: number;
+    byteLength: number;
+};
+/** Materialized SAB region; `isShared` means `buffer` is a real SharedArrayBuffer. */
+export type SharedAdoptedRegion = {
+    buffer: SharedArrayBuffer | ArrayBuffer;
+    byteOffset: number;
+    byteLength: number;
+    isShared: boolean;
+};
+export type AdoptOptions = {
+    /** Copy when bytes must survive producer release on non-owning runtimes. */
+    copy?: boolean;
+};
+type MovableBufferSource = ArrayBuffer | ArrayBufferView;
+export type BufferReferenceCapabilities = {
+    readonly runtime: BufferReferenceRuntime;
+    /** True when `adopt` returns a buffer that co-owns the store and survives `release`. */
+    readonly supportsOwningAdopt: boolean;
+    /** Take exclusive ownership of `source`'s bytes, detaching the source. */
+    produce(source: MovableBufferSource): ProducedBuffer;
+    /** Materialize the region in the current isolate (owning on Node, alias/copy elsewhere). */
+    adopt(input: AdoptInput, opts?: AdoptOptions): AdoptedRegion;
+    /** Drop the producer's hold on the backing store. */
+    release(token: bigint): void;
+    /** True when `adoptShared` returns a real SharedArrayBuffer (Node). */
+    readonly supportsSharedAdopt: boolean;
+    /** Share a SharedArrayBuffer by reference (no detach — SABs persist). */
+    produceShared(sab: SharedArrayBuffer): ProducedBuffer;
+    /** Materialize a shared region as a non-owning alias over the same bytes. */
+    adoptShared(input: AdoptInput): SharedAdoptedRegion;
+    /** Drop the producer's pin on a shared buffer (JS-side; teardown-safe). */
+    releaseShared(token: bigint): void;
+};
+export declare const getBufferReferenceCapabilities: () => BufferReferenceCapabilities;
+export {};

package/src/connections/buffer-reference-native.js

@@ -0,0 +1,217 @@
+import { RUNTIME } from "../common/runtime.js";
+import { loadNodeBufferPointerAddon } from "./node-buffer-pointer.js";
+const isSharedArrayBufferInstance = (value) => typeof SharedArrayBuffer === "function" && value instanceof SharedArrayBuffer;
+const assertMovableSource = (source) => {
+    const buffer = ArrayBuffer.isView(source) ? source.buffer : source;
+    if (isSharedArrayBufferInstance(buffer)) {
+        throw new TypeError("BufferReference expects ArrayBuffer-backed views; SharedArrayBuffer is already " +
+            "shared and cannot be moved");
+    }
+};
+const readSourceRegion = (source) => {
+    if (ArrayBuffer.isView(source)) {
+        return {
+            buffer: source.buffer,
+            byteOffset: source.byteOffset,
+            byteLength: source.byteLength,
+        };
+    }
+    return { buffer: source, byteOffset: 0, byteLength: source.byteLength };
+};
+/** Detach `buffer`, returning a fixed-length buffer over the same bytes (the move). */
+const detachIntoFixedLength = (buffer) => {
+    const transferable = buffer;
+    if (typeof transferable.transferToFixedLength === "function") {
+        return transferable.transferToFixedLength();
+    }
+    if (typeof transferable.transfer === "function") {
+        return transferable.transfer();
+    }
+    throw new TypeError("BufferReference requires ArrayBuffer.prototype.transfer to move a buffer in this runtime");
+};
+// ---------------------------------------------------------------------------
+// Deno/Bun pin moved buffers in JS and expose non-owning FFI aliases.
+// Tokens stay producer-isolate-local; consumers materialize from the pointer.
+// ---------------------------------------------------------------------------
+const ffiPinned = new Map();
+let nextFfiToken = 1n;
+const pinTransferred = (buffer) => {
+    const token = nextFfiToken++;
+    ffiPinned.set(token, buffer);
+    return token;
+};
+const pinShared = (sab) => {
+    const token = nextFfiToken++;
+    ffiPinned.set(token, sab);
+    return token;
+};
+const releaseFfi = (token) => {
+    ffiPinned.delete(token);
+};
+const produceSharedFfi = (sab, readPointer) => {
+    // SABs are shared, not detached; pin keeps producer bytes alive.
+    const pointer = readPointer(new Uint8Array(sab));
+    const token = pinShared(sab);
+    return { token, pointer, byteOffset: 0, byteLength: sab.byteLength };
+};
+const getDeno = () => {
+    const deno = globalThis.Deno;
+    if (deno?.UnsafePointer === undefined || deno.UnsafePointerView === undefined) {
+        throw new Error("Deno FFI (UnsafePointer) is not available in this runtime");
+    }
+    return deno;
+};
+const getBunFFI = () => {
+    const ffi = globalThis.Bun?.FFI;
+    if (typeof ffi?.ptr !== "function" || typeof ffi?.toArrayBuffer !== "function") {
+        throw new Error("Bun FFI (ptr/toArrayBuffer) is not available in this runtime");
+    }
+    return ffi;
+};
+const produceFfi = (source, readPointer) => {
+    assertMovableSource(source);
+    const { buffer, byteOffset, byteLength } = readSourceRegion(source);
+    const moved = detachIntoFixedLength(buffer);
+    // Region view over the moved buffer; the pointer captures the offset.
+    const region = new Uint8Array(moved, byteOffset, byteLength);
+    const pointer = readPointer(region);
+    const token = pinTransferred(moved);
+    return { token, pointer, byteOffset, byteLength };
+};
+const finishAlias = (alias, copy) => {
+    if (copy) {
+        const owned = alias.slice(0);
+        return { buffer: owned, byteOffset: 0, byteLength: owned.byteLength };
+    }
+    return { buffer: alias, byteOffset: 0, byteLength: alias.byteLength };
+};
+const createDenoCapabilities = () => {
+    const deno = getDeno();
+    return {
+        runtime: "deno",
+        supportsOwningAdopt: false,
+        produce: (view) => produceFfi(view, (region) => deno.UnsafePointer.value(deno.UnsafePointer.of(region))),
+        adopt: ({ pointer, byteLength }, opts) => {
+            const alias = denoAlias(deno, pointer, byteLength);
+            return finishAlias(alias, opts?.copy);
+        },
+        release: releaseFfi,
+        supportsSharedAdopt: false,
+        produceShared: (sab) => produceSharedFfi(sab, (region) => deno.UnsafePointer.value(deno.UnsafePointer.of(region))),
+        adoptShared: ({ pointer, byteLength }) => {
+            const alias = denoAlias(deno, pointer, byteLength);
+            return { buffer: alias, byteOffset: 0, byteLength, isShared: false };
+        },
+        releaseShared: releaseFfi,
+    };
+};
+const denoAlias = (deno, pointer, byteLength) => {
+    const handle = deno.UnsafePointer.create(pointer);
+    if (handle === null || handle === undefined) {
+        throw new Error("Deno.UnsafePointer.create returned null");
+    }
+    return new deno.UnsafePointerView(handle).getArrayBuffer(byteLength);
+};
+const createBunCapabilities = () => {
+    const ffi = getBunFFI();
+    return {
+        runtime: "bun",
+        supportsOwningAdopt: false,
+        produce: (view) => produceFfi(view, (region) => BigInt(ffi.ptr(region))),
+        adopt: ({ pointer, byteLength }, opts) => {
+            const alias = ffi.toArrayBuffer(Number(pointer), 0, byteLength);
+            return finishAlias(alias, opts?.copy);
+        },
+        release: releaseFfi,
+        supportsSharedAdopt: false,
+        produceShared: (sab) => produceSharedFfi(sab, (region) => BigInt(ffi.ptr(region))),
+        adoptShared: ({ pointer, byteLength }) => {
+            const alias = ffi.toArrayBuffer(Number(pointer), 0, byteLength);
+            return { buffer: alias, byteOffset: 0, byteLength, isShared: false };
+        },
+        releaseShared: releaseFfi,
+    };
+};
+// ---------------------------------------------------------------------------
+// Node: addon-backed owning move via shared_ptr<BackingStore>.
+// Older prebuilds fall back to non-owning retain/wrap.
+// ---------------------------------------------------------------------------
+const createNodeCapabilities = () => {
+    const addon = loadNodeBufferPointerAddon();
+    const owning = typeof addon.retainBackingStore === "function" &&
+        typeof addon.adoptBackingStore === "function" &&
+        typeof addon.releaseBackingStore === "function";
+    // SABs use JS pins plus non-owning aliases so no native handle survives teardown.
+    const sharedCapabilities = {
+        supportsSharedAdopt: false,
+        produceShared: (sab) => produceSharedFfi(sab, (region) => addon.getPointer(region)),
+        adoptShared: ({ pointer, byteLength }) => {
+            const alias = addon.wrapPointer(pointer, byteLength);
+            return { buffer: alias, byteOffset: 0, byteLength, isShared: false };
+        },
+        releaseShared: releaseFfi,
+    };
+    if (owning) {
+        return {
+            runtime: "node",
+            supportsOwningAdopt: true,
+            produce: (source) => {
+                assertMovableSource(source);
+                const r = addon.retainBackingStore(source);
+                return {
+                    token: r.token,
+                    pointer: r.pointer,
+                    byteOffset: r.byteOffset,
+                    byteLength: r.byteLength,
+                };
+            },
+            adopt: ({ token, byteOffset, byteLength }, opts) => {
+                const buffer = addon.adoptBackingStore(token);
+                if (opts?.copy) {
+                    const owned = buffer.slice(byteOffset, byteOffset + byteLength);
+                    return { buffer: owned, byteOffset: 0, byteLength: owned.byteLength };
+                }
+                return { buffer, byteOffset, byteLength };
+            },
+            release: (token) => void addon.releaseBackingStore(token),
+            ...sharedCapabilities,
+        };
+    }
+    // Legacy fallback: producer pins via retainPointer, consumer wraps non-owning.
+    return {
+        runtime: "node",
+        supportsOwningAdopt: false,
+        produce: (source) => {
+            assertMovableSource(source);
+            const retained = addon.retainPointer(source);
+            const byteOffset = ArrayBuffer.isView(source) ? source.byteOffset : 0;
+            return {
+                token: retained.token,
+                pointer: retained.pointer,
+                byteOffset,
+                byteLength: retained.byteLength,
+            };
+        },
+        adopt: ({ pointer, byteLength }, opts) => {
+            const alias = addon.wrapPointer(pointer, byteLength);
+            return finishAlias(alias, opts?.copy);
+        },
+        release: (token) => void addon.releasePointer(token),
+        ...sharedCapabilities,
+    };
+};
+let cached;
+export const getBufferReferenceCapabilities = () => {
+    if (cached !== undefined)
+        return cached;
+    switch (RUNTIME) {
+        case "node":
+            return cached = createNodeCapabilities();
+        case "deno":
+            return cached = createDenoCapabilities();
+        case "bun":
+            return cached = createBunCapabilities();
+        default:
+            throw new Error(`BufferReference cannot run in runtime "${RUNTIME}"`);
+    }
+};

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

@@ -0,0 +1,76 @@
+import { type BufferReferenceRuntime } from "./buffer-reference-native.js";
+export type { BufferReferenceRuntime } from "./buffer-reference-native.js";
+export declare const BUFFER_REFERENCE_KIND: "knitting.bufferReference";
+/** Named values for the `unsafe.BufferReferenceReturn` pool option. */
+export declare const BufferReferenceReturn: {
+    /** Safe default: Deno/Bun copy the returned bytes so they outlive the worker. */
+    readonly Copy: "copy";
+    /** Zero-copy: borrow the worker's backing store until the reference is released. */
+    readonly Borrow: "borrow";
+};
+export type BufferReferenceReturn = (typeof BufferReferenceReturn)[keyof typeof BufferReferenceReturn];
+export declare const BUFFER_REFERENCE_NUMERIC_TRANSFER: unique symbol;
+export declare const BUFFER_REFERENCE_RETURN_RELEASE_TOKEN: unique symbol;
+declare const EXTERNAL_PAYLOAD_BRAND: unique symbol;
+export declare const BUFFER_REFERENCE_CODEC_ID: "knitting.bufferReference";
+declare const BUFFER_REFERENCE_RETURN_RELEASE_MESSAGE_KEY = "__knittingBufferReferenceRelease";
+export type BufferReferenceNumericMetadata = readonly [
+    pointerLow: number,
+    pointerHigh: number,
+    tokenLow: number,
+    tokenHigh: number,
+    byteOffset: number,
+    byteLength: number,
+    runtime: number,
+    originPid: number
+];
+export 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;
+};
+export type BufferReferenceReturnReleaseMessage = {
+    readonly [BUFFER_REFERENCE_RETURN_RELEASE_MESSAGE_KEY]: string;
+};
+type BufferReferenceReturnReleaser = (token: bigint) => void;
+type BufferSource = ArrayBufferView | ArrayBuffer;
+declare const PAYLOAD_TRANSPORT_FINALIZER: unique symbol;
+export declare const withBufferReferenceReturnReleaser: <T>(releaser: BufferReferenceReturnReleaser | undefined, run: () => T) => T;
+export declare const createBufferReferenceReturnReleaseMessage: (token: bigint) => BufferReferenceReturnReleaseMessage;
+export declare const readBufferReferenceReturnReleaseMessage: (value: unknown) => bigint | undefined;
+export declare const isBufferReferenceMetadata: (value: unknown) => value is BufferReferenceMetadata;
+/**
+ * Zero-copy handle for moving ArrayBuffer bytes to **thread** workers.
+ *
+ * Construction detaches the source. Consumers materialize the moved region in
+ * their isolate: owning on Node, alias/copy on Deno/Bun.
+ */
+export 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);
+    constructor(source: BufferSource | 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;
+}