knitting 0.1.55 → 0.1.56

package/src/connections/shared-array-buffer-payload.js

@@ -0,0 +1,235 @@
+import { RUNTIME } from "../common/runtime.js";
+import { getNodeProcess } from "../common/node-compat.js";
+import { getBufferReferenceCapabilities } from "./buffer-reference-native.js";
+// Thread-worker SharedArrayBuffer transport by process-local pointer.
+// SABs are shared, not moved or detached; process workers reject them.
+export const SHARED_ARRAY_BUFFER_CODEC_ID = "knitting.sharedArrayBuffer";
+export const SHARED_ARRAY_BUFFER_NUMERIC_TRANSFER = Symbol.for("knitting.sharedArrayBuffer.numericTransfer");
+export const SHARED_ARRAY_BUFFER_NUMERIC_WORDS = 8;
+const SHARED_ARRAY_BUFFER_TOKEN_NUMERIC_WORDS = 2;
+const EXTERNAL_PAYLOAD_BRAND = Symbol.for("knitting.payloadCodec");
+const getProcessId = () => {
+    const proc = getNodeProcess();
+    if (proc !== undefined && typeof proc.pid === "number")
+        return proc.pid;
+    const deno = globalThis.Deno;
+    if (typeof deno?.pid === "number")
+        return deno.pid;
+    return 0;
+};
+const PROCESS_ORIGIN = `${RUNTIME}:${getProcessId()}`;
+const hasSharedArrayBuffer = typeof SharedArrayBuffer === "function";
+export const isSharedArrayBufferValue = (value) => hasSharedArrayBuffer && value instanceof SharedArrayBuffer;
+const pinnedBySab = new WeakMap();
+const payloadBySharedBuffer = new WeakMap();
+const warmedTokensByTransport = new WeakMap();
+const cachedSharedBuffersByToken = new Map();
+const pinFinalizer = typeof FinalizationRegistry === "function"
+    ? new FinalizationRegistry((token) => {
+        try {
+            getBufferReferenceCapabilities().releaseShared(token);
+        }
+        catch {
+            // best effort
+        }
+    })
+    : undefined;
+const splitU64 = (value) => [
+    Number(value & 0xffffffffn) >>> 0,
+    Number((value >> 32n) & 0xffffffffn) >>> 0,
+];
+const joinU64 = (low, high) => (BigInt(high >>> 0) << 32n) | BigInt(low >>> 0);
+const encodeRuntime = (runtime) => {
+    switch (runtime) {
+        case "node":
+            return 1;
+        case "deno":
+            return 2;
+        case "bun":
+            return 3;
+        default:
+            return 0;
+    }
+};
+const decodeRuntime = (value) => {
+    switch (value) {
+        case 1:
+            return "node";
+        case 2:
+            return "deno";
+        case 3:
+            return "bun";
+        default:
+            return undefined;
+    }
+};
+const getWarmTokens = (transportKey) => {
+    if (transportKey === undefined)
+        return undefined;
+    let warmTokens = warmedTokensByTransport.get(transportKey);
+    if (warmTokens === undefined) {
+        warmTokens = new Set();
+        warmedTokensByTransport.set(transportKey, warmTokens);
+    }
+    return warmTokens;
+};
+const pinSab = (sab) => {
+    let pin = pinnedBySab.get(sab);
+    if (pin === undefined) {
+        const produced = getBufferReferenceCapabilities().produceShared(sab);
+        pin = {
+            token: produced.token,
+            pointer: produced.pointer,
+            byteLength: produced.byteLength,
+        };
+        pinnedBySab.set(sab, pin);
+        pinFinalizer?.register(sab, pin.token);
+    }
+    return pin;
+};
+const makeMetadata = (pin) => ({
+    kind: SHARED_ARRAY_BUFFER_CODEC_ID,
+    origin: PROCESS_ORIGIN,
+    runtime: RUNTIME,
+    pointer: pin.pointer.toString(),
+    token: pin.token.toString(),
+    byteLength: pin.byteLength,
+});
+const makeFullNumericMetadata = (pin) => {
+    if (pin.byteLength > 0xffffffff)
+        return undefined;
+    const [tokenLow, tokenHigh] = splitU64(pin.token);
+    const [pointerLow, pointerHigh] = splitU64(pin.pointer);
+    return [
+        tokenLow,
+        tokenHigh,
+        pointerLow,
+        pointerHigh,
+        pin.byteLength >>> 0,
+        encodeRuntime(RUNTIME),
+        getProcessId() >>> 0,
+        0,
+    ];
+};
+const makeTokenNumericMetadata = (pin) => {
+    const [tokenLow, tokenHigh] = splitU64(pin.token);
+    return [tokenLow, tokenHigh];
+};
+/** Wrap a SAB as external payload; GC-managed pins mean no settle finalizer. */
+export const wrapSharedArrayBufferPayload = (sab) => {
+    let payload = payloadBySharedBuffer.get(sab);
+    if (payload !== undefined)
+        return payload;
+    const pin = pinSab(sab);
+    payload = createSharedArrayBufferPayload(sab, pin, makeMetadata(pin));
+    return payload;
+};
+const createSharedArrayBufferPayload = (buffer, pin, metadata) => {
+    let payload = payloadBySharedBuffer.get(buffer);
+    if (payload !== undefined)
+        return payload;
+    const fullNumeric = makeFullNumericMetadata(pin);
+    const tokenOnlyNumeric = makeTokenNumericMetadata(pin);
+    payload = {
+        [EXTERNAL_PAYLOAD_BRAND]: SHARED_ARRAY_BUFFER_CODEC_ID,
+        toMetadata: () => metadata,
+        [SHARED_ARRAY_BUFFER_NUMERIC_TRANSFER]: (transportKey) => {
+            if (fullNumeric === undefined) {
+                return undefined;
+            }
+            const warmTokens = getWarmTokens(transportKey);
+            if (warmTokens === undefined)
+                return fullNumeric;
+            if (warmTokens.has(pin.token))
+                return tokenOnlyNumeric;
+            warmTokens.add(pin.token);
+            return fullNumeric;
+        },
+    };
+    payloadBySharedBuffer.set(buffer, payload);
+    return payload;
+};
+export const getSharedArrayBufferPayload = (value) => {
+    if (isSharedArrayBufferValue(value))
+        return wrapSharedArrayBufferPayload(value);
+    return payloadBySharedBuffer.get(value);
+};
+const isSharedArrayBufferMetadata = (value) => {
+    if (value === null || typeof value !== "object")
+        return false;
+    const meta = value;
+    return (meta.kind === SHARED_ARRAY_BUFFER_CODEC_ID &&
+        typeof meta.origin === "string" &&
+        typeof meta.runtime === "string" &&
+        typeof meta.pointer === "string" &&
+        typeof meta.token === "string" &&
+        typeof meta.byteLength === "number" &&
+        Number.isInteger(meta.byteLength) &&
+        meta.byteLength >= 0);
+};
+const materializeSharedBuffer = (metadata, warmOnly) => {
+    if (metadata.origin !== PROCESS_ORIGIN) {
+        throw new Error(`SharedArrayBuffer cannot cross a process boundary (origin ${metadata.origin} ` +
+            `!= ${PROCESS_ORIGIN}); it is shared by reference to thread workers only.`);
+    }
+    const token = BigInt(metadata.token);
+    const cached = cachedSharedBuffersByToken.get(token);
+    if (cached !== undefined)
+        return cached;
+    if (warmOnly) {
+        throw new TypeError("SharedArrayBuffer cache miss for warm token payload");
+    }
+    const region = getBufferReferenceCapabilities().adoptShared({
+        token,
+        pointer: BigInt(metadata.pointer),
+        byteOffset: 0,
+        byteLength: metadata.byteLength,
+    });
+    cachedSharedBuffersByToken.set(token, region.buffer);
+    createSharedArrayBufferPayload(region.buffer, {
+        token,
+        pointer: BigInt(metadata.pointer),
+        byteLength: metadata.byteLength,
+    }, metadata);
+    return region.buffer;
+};
+const decode = (metadata) => {
+    if (!isSharedArrayBufferMetadata(metadata)) {
+        throw new TypeError("Invalid SharedArrayBuffer payload metadata");
+    }
+    return materializeSharedBuffer(metadata, false);
+};
+const decodeNumeric = (words) => {
+    if (words.length === SHARED_ARRAY_BUFFER_TOKEN_NUMERIC_WORDS) {
+        const token = joinU64(words[0] ?? 0, words[1] ?? 0);
+        const cached = cachedSharedBuffersByToken.get(token);
+        if (cached !== undefined)
+            return cached;
+        throw new TypeError("SharedArrayBuffer cache miss for warm token payload");
+    }
+    const runtime = decodeRuntime(words[5] ?? 0);
+    if (runtime === undefined) {
+        throw new TypeError("Invalid SharedArrayBuffer numeric runtime");
+    }
+    const originPid = words[6];
+    if (originPid === undefined ||
+        !Number.isInteger(originPid) ||
+        originPid < 0) {
+        throw new TypeError("Invalid SharedArrayBuffer numeric origin");
+    }
+    if (words.length !== SHARED_ARRAY_BUFFER_NUMERIC_WORDS) {
+        throw new TypeError("Invalid SharedArrayBuffer numeric word count");
+    }
+    const metadata = {
+        kind: SHARED_ARRAY_BUFFER_CODEC_ID,
+        origin: `${runtime}:${originPid >>> 0}`,
+        runtime,
+        pointer: joinU64(words[2] ?? 0, words[3] ?? 0).toString(),
+        token: joinU64(words[0] ?? 0, words[1] ?? 0).toString(),
+        byteLength: words[4] ?? 0,
+    };
+    return materializeSharedBuffer(metadata, false);
+};
+const codecGlobal = globalThis;
+const codecs = codecGlobal.__KNITTING_PAYLOAD_CODECS__ ??= Object.create(null);
+codecs[SHARED_ARRAY_BUFFER_CODEC_ID] = { decode, decodeNumeric };

package/src/connections/types.d.ts

@@ -0,0 +1,50 @@
+export declare const CACHE_LINE_SIZE = 64;
+export type ConnectionRuntime = "node" | "deno" | "bun";
+export type SharedMemoryBuffer = ArrayBuffer | SharedArrayBuffer;
+export type SharedMemoryBufferKind = "shared-array-buffer" | "external-array-buffer";
+export type SharedMemoryCreateMode = "anonymous" | "create" | "open";
+export 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;
+};
+export 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;
+};
+export type MapSharedMemoryOptions = {
+    fd: number;
+    name?: string;
+    size: number;
+    duplicateFd?: boolean;
+};
+export type SharedMemoryConnectionPrimitives<Mapping extends SharedMemoryMapping = SharedMemoryMapping> = {
+    runtime: ConnectionRuntime;
+    createSharedMemory: (options: number | CreateSharedMemoryOptions) => Mapping;
+    mapSharedMemory: (options: MapSharedMemoryOptions) => Mapping;
+    unlinkSharedMemory?: (name: string) => boolean;
+};
+export declare const alignToCacheLine: (size: number) => number;
+export declare const readCreateSize: (options: number | CreateSharedMemoryOptions) => number;
+export declare const readCreateName: (options: number | CreateSharedMemoryOptions, fallback: string) => string;
+export declare const readCreateMode: (options: number | CreateSharedMemoryOptions) => SharedMemoryCreateMode;
+export declare const expectSharedMemoryName: (name: string) => string;
+export declare const readRequiredCreateName: (options: number | CreateSharedMemoryOptions) => string;
+export declare const expectPositiveSize: (size: number) => number;
+export declare const expectFd: (fd: number) => number;
+export declare const requireSharedArrayBuffer: (mapping: SharedMemoryMapping) => SharedArrayBuffer;

package/src/connections/types.js

@@ -0,0 +1,37 @@
+export const CACHE_LINE_SIZE = 64;
+export const alignToCacheLine = (size) => size + ((CACHE_LINE_SIZE - (size % CACHE_LINE_SIZE)) % CACHE_LINE_SIZE);
+export const readCreateSize = (options) => typeof options === "number" ? options : options.size;
+export const readCreateName = (options, fallback) => typeof options === "number" ? fallback : options.name ?? fallback;
+export const readCreateMode = (options) => typeof options === "number" ? "anonymous" : options.mode ?? "anonymous";
+export const expectSharedMemoryName = (name) => {
+    if (typeof name !== "string" || name.length === 0) {
+        throw new TypeError("shared memory name must be a non-empty string");
+    }
+    if (name.includes("\0")) {
+        throw new TypeError("shared memory name must not contain NUL bytes");
+    }
+    return name;
+};
+export const readRequiredCreateName = (options) => {
+    if (typeof options === "number" || options.name === undefined) {
+        throw new TypeError("named shared memory requires a name");
+    }
+    return expectSharedMemoryName(options.name);
+};
+export const expectPositiveSize = (size) => {
+    if (!Number.isFinite(size) || size <= 0) {
+        throw new RangeError("shared memory size must be positive");
+    }
+    return alignToCacheLine(Math.trunc(size));
+};
+export const expectFd = (fd) => {
+    if (!Number.isInteger(fd) || fd < 0) {
+        throw new RangeError("shared memory fd must be non-negative");
+    }
+    return fd;
+};
+export const requireSharedArrayBuffer = (mapping) => {
+    if (mapping.sab !== undefined)
+        return mapping.sab;
+    throw new TypeError(`${mapping.runtime} mapping is ${mapping.kind}; a native SAB wrapper is required`);
+};

package/src/connections/windows.d.ts

@@ -0,0 +1,28 @@
+import { type CreateSharedMemoryOptions, type MapSharedMemoryOptions, type SharedMemoryConnectionPrimitives, type SharedMemoryMapping } from "./types.js";
+type DenoWindowsLibrary = {
+    symbols: {
+        knitting_windows_create_shared_memory: (size: bigint, name: Uint16Array, mode: number, out: Uint8Array) => number;
+        knitting_windows_map_shared_memory: (handle: bigint, size: bigint, name: Uint16Array, out: Uint8Array) => number;
+        knitting_windows_close_shared_memory: (mapping: Uint8Array) => number;
+    };
+    close: () => void;
+};
+type BunWindowsLibrary = {
+    symbols: {
+        knitting_windows_create_shared_memory: (size: bigint, name: Uint16Array, mode: number, out: Uint8Array) => number;
+        knitting_windows_map_shared_memory: (handle: bigint, size: bigint, name: Uint16Array, out: Uint8Array) => number;
+        knitting_windows_close_shared_memory: (mapping: Uint8Array) => number;
+    };
+};
+export declare const isWindowsRuntime: () => boolean;
+export declare const windowsSharedMemoryPrebuildPath: () => string;
+export declare const makeWindowsAnonymousSharedMemoryName: (runtime: string) => string;
+export declare const openDenoWindowsSharedMemoryLibrary: () => DenoWindowsLibrary;
+export declare const openBunWindowsSharedMemoryLibrary: () => BunWindowsLibrary;
+export declare const createDenoWindowsSharedMemory: (options: number | CreateSharedMemoryOptions, lib?: DenoWindowsLibrary) => SharedMemoryMapping<ArrayBuffer>;
+export declare const mapDenoWindowsSharedMemory: (options: MapSharedMemoryOptions, lib?: DenoWindowsLibrary) => SharedMemoryMapping<ArrayBuffer>;
+export declare const createDenoWindowsConnectionPrimitives: (lib?: DenoWindowsLibrary) => SharedMemoryConnectionPrimitives<SharedMemoryMapping<ArrayBuffer>>;
+export declare const createBunWindowsSharedMemory: (options: number | CreateSharedMemoryOptions, lib?: BunWindowsLibrary) => SharedMemoryMapping<ArrayBuffer>;
+export declare const mapBunWindowsSharedMemory: (options: MapSharedMemoryOptions, lib?: BunWindowsLibrary) => SharedMemoryMapping<ArrayBuffer>;
+export declare const createBunWindowsConnectionPrimitives: (lib?: BunWindowsLibrary) => SharedMemoryConnectionPrimitives<SharedMemoryMapping<ArrayBuffer>>;
+export {};

package/src/connections/windows.js

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

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

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

package/src/debug/env-diff.js

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

package/src/debug/gate.d.ts

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