knitting 0.1.56 → 0.1.61

package/src/connections/external-array-buffer.d.ts

@@ -0,0 +1,2 @@
+export declare const detachExternalArrayBuffer: (buffer: ArrayBuffer) => boolean;
+export declare const requireDetachedExternalArrayBuffer: (buffer: ArrayBuffer) => void;

package/src/connections/external-array-buffer.js

@@ -0,0 +1,33 @@
+export const detachExternalArrayBuffer = (buffer) => {
+    if (buffer.byteLength === 0)
+        return true;
+    const detachable = buffer;
+    try {
+        if (typeof detachable.transferToFixedLength === "function") {
+            detachable.transferToFixedLength(0);
+            return buffer.byteLength === 0;
+        }
+    }
+    catch {
+    }
+    try {
+        if (typeof detachable.transfer === "function") {
+            detachable.transfer(0);
+            return buffer.byteLength === 0;
+        }
+    }
+    catch {
+    }
+    try {
+        structuredClone(buffer, { transfer: [buffer] });
+        return buffer.byteLength === 0;
+    }
+    catch {
+        return false;
+    }
+};
+export const requireDetachedExternalArrayBuffer = (buffer) => {
+    if (detachExternalArrayBuffer(buffer))
+        return;
+    throw new Error("knitting: could not detach external ArrayBuffer; refusing to unmap memory still reachable from JavaScript");
+};

package/src/connections/node-addons.d.ts

@@ -1,5 +1,16 @@
 type NodeRequire = (specifier: string) => unknown;
 export type NodeNativeAddonName = "knitting_shared_memory" | "knitting_shm" | "knitting_buffer_pointer";
+export type NodePlatformInfo = {
+    arch: string;
+    modules?: string;
+    platform: string;
+    version?: string;
+};
+export declare const SUPPORTED_NODE_NATIVE_ADDON_ABIS: {
+    readonly "127": "22";
+    readonly "137": "24";
+};
+export declare const formatNodeNativeAddonLoadError: (name: NodeNativeAddonName, platformInfo: NodePlatformInfo | undefined, errors: readonly string[]) => string;
 export declare const nodeNativeAddonSpecifiers: (name: NodeNativeAddonName) => readonly string[];
 export declare const loadNodeNativeAddon: <T>(require: NodeRequire, name: NodeNativeAddonName, specifier?: string) => T;
 export {};

package/src/connections/node-addons.js

@@ -1,4 +1,15 @@
 import { resolveKnittingPackageAsset } from "./package-assets.js";
+export const SUPPORTED_NODE_NATIVE_ADDON_ABIS = {
+    "127": "22",
+    "137": "24",
+};
+const NODE_26_MODULE_ABI = "147";
+const SUPPORTED_NODE_NATIVE_TARGETS = new Set([
+    "darwin-arm64",
+    "darwin-x64",
+    "linux-x64",
+    "win32-x64",
+]);
 const readNodePlatformInfo = () => {
     const processLike = globalThis.process;
     if (typeof processLike?.platform !== "string" ||
@@ -9,8 +20,45 @@ const readNodePlatformInfo = () => {
         arch: processLike.arch,
         modules: processLike.versions?.modules,
         platform: processLike.platform,
+        version: processLike.versions?.node,
     };
 };
+const formatAttemptErrors = (errors) => errors.length > 0 ? `\nTried:\n${errors.join("\n")}` : "";
+export const formatNodeNativeAddonLoadError = (name, platformInfo, errors) => {
+    const attempts = formatAttemptErrors(errors);
+    if (platformInfo === undefined) {
+        return `knitting: could not load native addon ${name}.${attempts}`;
+    }
+    const abi = platformInfo.modules;
+    const version = platformInfo.version === undefined
+        ? "an unknown version"
+        : `v${platformInfo.version}`;
+    const target = `${platformInfo.platform}-${platformInfo.arch}`;
+    if (abi === NODE_26_MODULE_ABI) {
+        return (`knitting: Node.js 26 uses node:ffi instead of ABI-specific addons. ` +
+            `Restart Node with the --experimental-ffi flag` +
+            ` (--allow-ffi is also required when using Node's Permission Model). ` +
+            `No Node ABI 147 addon is shipped.${attempts}`);
+    }
+    if (typeof abi === "string" &&
+        !(abi in SUPPORTED_NODE_NATIVE_ADDON_ABIS)) {
+        return (`knitting: no native addon is shipped for Node.js ${version} ` +
+            `(ABI ${abi}). Packaged native features support Node.js 22 ` +
+            `(ABI 127) and Node.js 24 (ABI 137) only. Plain thread workers that do ` +
+            `not use ProcessSharedBuffer or BufferReference do not need these ` +
+            `addons.${attempts}`);
+    }
+    if (!SUPPORTED_NODE_NATIVE_TARGETS.has(target)) {
+        return (`knitting: Node.js ${version} uses a supported ABI (${abi ?? "unknown"}), ` +
+            `but no packaged native addon target is shipped for ${target}. ` +
+            `Published targets are linux-x64, darwin-x64, darwin-arm64, and ` +
+            `win32-x64. You can build locally with "bun run build:native".${attempts}`);
+    }
+    return (`knitting: could not load native addon ${name} for Node.js ${version} ` +
+        `(ABI ${abi ?? "unknown"}, ${target}). The prebuild may be missing, ` +
+        `damaged, or incompatible; reinstall the package or build locally with ` +
+        `"bun run build:native".${attempts}`);
+};
 export const nodeNativeAddonSpecifiers = (name) => {
     const platformInfo = readNodePlatformInfo();
     const fallback = resolveKnittingPackageAsset("build", "Release", `${name}.node`);
@@ -40,5 +88,5 @@ export const loadNodeNativeAddon = (require, name, specifier) => {
             errors.push(`${candidate}: ${String(error)}`);
         }
     }
-    throw new Error(`Could not load native addon ${name}. Tried:\n${errors.join("\n")}`);
+    throw new Error(formatNodeNativeAddonLoadError(name, readNodePlatformInfo(), errors));
 };

package/src/connections/node-ffi-api.d.ts

@@ -0,0 +1,19 @@
+export type NodeFfiFunctionSignature = {
+    arguments?: string[];
+    return?: string;
+};
+export type NodeFfiLibrary = {
+    close: () => void;
+};
+export type NodeFfiDlopenResult<Functions extends Record<string, (...args: never[]) => unknown>> = {
+    functions: Functions;
+    lib: NodeFfiLibrary;
+};
+export type NodeFfiApi = {
+    dlopen: <Functions extends Record<string, (...args: never[]) => unknown>>(path: string | null, definitions: Record<string, NodeFfiFunctionSignature>) => NodeFfiDlopenResult<Functions>;
+    getRawPointer: (source: ArrayBuffer | SharedArrayBuffer | ArrayBufferView) => bigint;
+    suffix: string;
+    toArrayBuffer: (pointer: bigint, length: number, copy?: boolean) => ArrayBuffer;
+};
+export declare const isNodeFfiTarget: () => boolean;
+export declare const getNodeFfi: () => NodeFfiApi;

package/src/connections/node-ffi-api.js

@@ -0,0 +1,28 @@
+import { getNodeBuiltinModule, getNodeProcess } from "../common/node-compat.js";
+const readNodeMajor = () => {
+    const version = getNodeProcess()?.versions?.node;
+    if (typeof version !== "string")
+        return undefined;
+    const major = Number.parseInt(version.split(".", 1)[0] ?? "", 10);
+    return Number.isInteger(major) ? major : undefined;
+};
+export const isNodeFfiTarget = () => {
+    const major = readNodeMajor() ?? 0;
+    return major >= 26 && major % 2 === 0;
+};
+let cachedNodeFfi;
+export const getNodeFfi = () => {
+    if (cachedNodeFfi !== undefined)
+        return cachedNodeFfi;
+    const ffi = getNodeBuiltinModule("node:ffi");
+    if (ffi === undefined ||
+        typeof ffi.dlopen !== "function" ||
+        typeof ffi.getRawPointer !== "function" ||
+        typeof ffi.toArrayBuffer !== "function") {
+        throw new Error("knitting: Node.js 26 native features require node:ffi. " +
+            "Restart Node with --experimental-ffi" +
+            " (--allow-ffi is also required when using Node's Permission Model).");
+    }
+    cachedNodeFfi = ffi;
+    return ffi;
+};

package/src/connections/node-ffi.d.ts

@@ -0,0 +1,27 @@
+import { type NodeFfiLibrary } from "./node-ffi-api.js";
+import { type CreateSharedMemoryOptions, type MapSharedMemoryOptions, type SharedMemoryConnectionPrimitives, type SharedMemoryMapping } from "./types.js";
+export { getNodeFfi, isNodeFfiTarget } from "./node-ffi-api.js";
+export type { NodeFfiApi, NodeFfiDlopenResult, NodeFfiFunctionSignature, NodeFfiLibrary, } from "./node-ffi-api.js";
+type NodePosixFunctions = {
+    memfd_create?: (name: Uint8Array, flags: number) => number;
+    shm_open?: (name: Uint8Array, flags: number, ...rest: number[]) => number;
+    shm_unlink?: (name: Uint8Array) => number;
+    __error?: () => bigint;
+    __errno_location?: () => bigint;
+    ftruncate: (fd: number, length: bigint) => number;
+    dup: (fd: number) => number;
+    fcntl: (fd: number, cmd: number, arg: number) => number;
+    mmap: (address: null, length: bigint, protection: number, flags: number, fd: number, offset: bigint) => bigint;
+    munmap: (address: bigint, length: bigint) => number;
+    close: (fd: number) => number;
+};
+type NodePosixLibrary = {
+    functions: NodePosixFunctions;
+    lib: NodeFfiLibrary;
+};
+export declare const openNodePosixLibrary: () => NodePosixLibrary;
+export declare const mapNodeFfiSharedMemory: (options: MapSharedMemoryOptions, library?: NodePosixLibrary) => SharedMemoryMapping<ArrayBuffer>;
+export declare const createNodeFfiSharedMemory: (options: number | CreateSharedMemoryOptions, library?: NodePosixLibrary) => SharedMemoryMapping<ArrayBuffer>;
+export declare const unlinkNodeFfiSharedMemory: (name: string, library?: NodePosixLibrary) => boolean;
+export declare const createNodeFfiPosixConnectionPrimitives: (library?: NodePosixLibrary) => SharedMemoryConnectionPrimitives<SharedMemoryMapping<ArrayBuffer>>;
+export declare const createNodeFfiConnectionPrimitives: () => SharedMemoryConnectionPrimitives<SharedMemoryMapping<ArrayBuffer>>;

package/src/connections/node-ffi.js

@@ -0,0 +1,262 @@
+import { assertNamedSharedMemoryIsReopenable, checkPosixResult, DARWIN_O_CREAT, DARWIN_O_EXCL, DARWIN_SHM_MODE, detectPosixPlatform, encodeCString, getErrnoSymbolName, getPosixLibcPath, LINUX_O_CREAT, LINUX_O_EXCL, makeDarwinSharedMemoryName, makeErrnoReader, MAP_SHARED, O_RDWR, POSIX_SHM_MODE, posixError, PROT_READ, PROT_WRITE, setCloseOnExec, SHM_OPEN_STACK_PAD, shmOpenModeIsStackPassed, toPosixSharedMemoryName, } from "./posix.js";
+import { createNodeWindowsConnectionPrimitives, isWindowsRuntime, } from "./windows.js";
+import { requireDetachedExternalArrayBuffer } from "./external-array-buffer.js";
+import { getNodeFfi, } from "./node-ffi-api.js";
+import { expectFd, expectPositiveSize, readCreateMode, readCreateName, readCreateSize, readRequiredCreateName, } from "./types.js";
+export { getNodeFfi, isNodeFfiTarget } from "./node-ffi-api.js";
+let cachedNodePosixLibrary;
+const getNodeCreateSymbols = (platform = detectPosixPlatform()) => {
+    if (platform === "darwin") {
+        return {
+            shm_open: {
+                arguments: shmOpenModeIsStackPassed(platform)
+                    ? ["pointer", "i32", ...SHM_OPEN_STACK_PAD.map(() => "i32"), "u32"]
+                    : ["pointer", "i32", "u32"],
+                return: "i32",
+            },
+            shm_unlink: {
+                arguments: ["pointer"],
+                return: "i32",
+            },
+        };
+    }
+    return {
+        memfd_create: {
+            arguments: ["pointer", "u32"],
+            return: "i32",
+        },
+        shm_open: {
+            arguments: ["pointer", "i32", "u32"],
+            return: "i32",
+        },
+        shm_unlink: {
+            arguments: ["pointer"],
+            return: "i32",
+        },
+    };
+};
+const getNodeErrnoSymbols = (platform = detectPosixPlatform()) => ({
+    [getErrnoSymbolName(platform)]: {
+        arguments: [],
+        return: "pointer",
+    },
+});
+const getNodePosixSymbols = () => ({
+    ...getNodeCreateSymbols(),
+    ftruncate: {
+        arguments: ["i32", "i64"],
+        return: "i32",
+    },
+    dup: {
+        arguments: ["i32"],
+        return: "i32",
+    },
+    fcntl: {
+        arguments: ["i32", "i32", "i32"],
+        return: "i32",
+    },
+    mmap: {
+        arguments: ["pointer", "u64", "i32", "i32", "i32", "i64"],
+        return: "pointer",
+    },
+    munmap: {
+        arguments: ["pointer", "u64"],
+        return: "i32",
+    },
+    close: {
+        arguments: ["i32"],
+        return: "i32",
+    },
+});
+export const openNodePosixLibrary = () => {
+    if (cachedNodePosixLibrary !== undefined)
+        return cachedNodePosixLibrary;
+    const symbols = getNodePosixSymbols();
+    const ffi = getNodeFfi();
+    // errno is diagnostics only: if this libc or FFI build will not bind the
+    // nullary errno accessor, open without it rather than lose shared memory.
+    let opened;
+    try {
+        opened = ffi.dlopen(getPosixLibcPath(), {
+            ...symbols,
+            ...getNodeErrnoSymbols(),
+        });
+    }
+    catch {
+        opened = ffi.dlopen(getPosixLibcPath(), symbols);
+    }
+    cachedNodePosixLibrary = opened;
+    return opened;
+};
+const callShmOpen = (shmOpen, name, flags, mode, platform) => shmOpenModeIsStackPassed(platform)
+    ? shmOpen(name, flags, ...SHM_OPEN_STACK_PAD, mode)
+    : shmOpen(name, flags, mode);
+const errnoOf = (libc, platform = detectPosixPlatform()) => makeErrnoReader(platform === "darwin" ? libc.__error : libc.__errno_location, (pointer) => new Int32Array(getNodeFfi().toArrayBuffer(pointer, 4, true))[0]);
+const isMapFailed = (pointer) => pointer === 0n ||
+    pointer === -1n ||
+    pointer === BigInt.asUintN(64, -1n);
+const createAnonymousFd = (name, platform, libc) => {
+    if (platform === "darwin") {
+        const shmOpen = libc.shm_open;
+        const shmUnlink = libc.shm_unlink;
+        if (shmOpen === undefined || shmUnlink === undefined) {
+            throw new Error("shm_open symbols are not available");
+        }
+        const shmName = encodeCString(makeDarwinSharedMemoryName(name, "node"));
+        const fd = checkPosixResult(callShmOpen(shmOpen, shmName, O_RDWR | DARWIN_O_CREAT | DARWIN_O_EXCL, DARWIN_SHM_MODE, platform), "shm_open failed", errnoOf(libc, platform), platform);
+        shmUnlink(shmName);
+        try {
+            return setCloseOnExec({ symbols: libc }, fd);
+        }
+        catch (error) {
+            libc.close(fd);
+            throw error;
+        }
+    }
+    const memfdCreate = libc.memfd_create;
+    if (memfdCreate === undefined) {
+        throw new Error("memfd_create symbol is not available");
+    }
+    const fd = checkPosixResult(memfdCreate(encodeCString(name), 0), "memfd_create failed", errnoOf(libc, platform), platform);
+    try {
+        return setCloseOnExec({ symbols: libc }, fd);
+    }
+    catch (error) {
+        libc.close(fd);
+        throw error;
+    }
+};
+const createNamedFd = (name, mode, platform, libc) => {
+    const shmOpen = libc.shm_open;
+    if (shmOpen === undefined) {
+        throw new Error("shm_open symbol is not available");
+    }
+    const createFlag = platform === "darwin" ? DARWIN_O_CREAT : LINUX_O_CREAT;
+    const exclusiveFlag = platform === "darwin" ? DARWIN_O_EXCL : LINUX_O_EXCL;
+    const flags = mode === "create"
+        ? O_RDWR | createFlag | exclusiveFlag
+        : O_RDWR;
+    const shmMode = platform === "darwin" ? DARWIN_SHM_MODE : POSIX_SHM_MODE;
+    const shmName = encodeCString(toPosixSharedMemoryName(name));
+    const fd = checkPosixResult(callShmOpen(shmOpen, shmName, flags, shmMode, platform), "shm_open failed", errnoOf(libc, platform), platform);
+    if (mode === "create") {
+        assertNamedSharedMemoryIsReopenable(platform, fd, () => callShmOpen(shmOpen, shmName, O_RDWR, shmMode, platform), libc.close, errnoOf(libc, platform));
+    }
+    try {
+        return setCloseOnExec({ symbols: libc }, fd);
+    }
+    catch (error) {
+        libc.close(fd);
+        throw error;
+    }
+};
+const mapFd = (fd, size, name, libc, closeFdOnFailure) => {
+    const pointer = libc.mmap(null, BigInt(size), PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0n);
+    if (isMapFailed(pointer)) {
+        // errno first: fcntl below overwrites it.
+        const error = posixError("mmap failed", errnoOf(libc));
+        const descriptorFlags = libc.fcntl(fd, 1, 0);
+        if (closeFdOnFailure)
+            libc.close(fd);
+        error.message +=
+            ` (fd ${fd}, size ${size}, descriptor flags ${descriptorFlags})`;
+        throw error;
+    }
+    let arrayBuffer;
+    try {
+        arrayBuffer = getNodeFfi().toArrayBuffer(pointer, size, false);
+    }
+    catch (error) {
+        libc.munmap(pointer, BigInt(size));
+        if (closeFdOnFailure)
+            libc.close(fd);
+        throw error;
+    }
+    let closed = false;
+    return {
+        runtime: "node",
+        fd,
+        name,
+        size,
+        byteLength: arrayBuffer.byteLength,
+        buffer: arrayBuffer,
+        kind: "external-array-buffer",
+        arrayBuffer,
+        unsafePointer: pointer,
+        baseAddressMod64: Number(pointer % 64n),
+        close: () => {
+            if (closed)
+                return;
+            requireDetachedExternalArrayBuffer(arrayBuffer);
+            closed = true;
+            try {
+                libc.munmap(pointer, BigInt(size));
+            }
+            finally {
+                libc.close(fd);
+            }
+        },
+    };
+};
+export const mapNodeFfiSharedMemory = (options, library = openNodePosixLibrary()) => {
+    const libc = library.functions;
+    const size = expectPositiveSize(options.size);
+    let fd;
+    let closeFdOnFailure = true;
+    if (options.name !== undefined) {
+        fd = createNamedFd(options.name, "open", detectPosixPlatform(), libc);
+    }
+    else {
+        const sourceFd = expectFd(options.fd);
+        closeFdOnFailure = options.duplicateFd !== false;
+        fd = closeFdOnFailure
+            ? checkPosixResult(libc.dup(sourceFd), "dup(fd) failed", errnoOf(libc))
+            : sourceFd;
+        if (closeFdOnFailure) {
+            try {
+                setCloseOnExec({ symbols: libc }, fd);
+            }
+            catch (error) {
+                libc.close(fd);
+                throw error;
+            }
+        }
+    }
+    // A non-duplicated descriptor remains caller-owned until mmap and the
+    // JavaScript wrapper both succeed. The returned mapping owns it thereafter.
+    return mapFd(fd, size, options.name, libc, closeFdOnFailure);
+};
+export const createNodeFfiSharedMemory = (options, library = openNodePosixLibrary()) => {
+    const libc = library.functions;
+    const size = expectPositiveSize(readCreateSize(options));
+    const mode = readCreateMode(options);
+    const name = mode === "anonymous"
+        ? readCreateName(options, "knitting_shared_memory")
+        : readRequiredCreateName(options);
+    const platform = detectPosixPlatform();
+    const fd = mode === "anonymous"
+        ? createAnonymousFd(name, platform, libc)
+        : createNamedFd(name, mode, platform, libc);
+    if (mode !== "open" && libc.ftruncate(fd, BigInt(size)) < 0) {
+        const error = posixError("ftruncate failed", errnoOf(libc, platform), platform);
+        libc.close(fd);
+        throw error;
+    }
+    return mapFd(fd, size, mode === "anonymous" ? undefined : name, libc, true);
+};
+export const unlinkNodeFfiSharedMemory = (name, library = openNodePosixLibrary()) => {
+    const shmUnlink = library.functions.shm_unlink;
+    if (shmUnlink === undefined) {
+        throw new Error("shm_unlink symbol is not available");
+    }
+    return shmUnlink(encodeCString(toPosixSharedMemoryName(name))) === 0;
+};
+export const createNodeFfiPosixConnectionPrimitives = (library = openNodePosixLibrary()) => ({
+    runtime: "node",
+    createSharedMemory: (options) => createNodeFfiSharedMemory(options, library),
+    mapSharedMemory: (options) => mapNodeFfiSharedMemory(options, library),
+    unlinkSharedMemory: (name) => unlinkNodeFfiSharedMemory(name, library),
+});
+export const createNodeFfiConnectionPrimitives = () => isWindowsRuntime()
+    ? createNodeWindowsConnectionPrimitives()
+    : createNodeFfiPosixConnectionPrimitives();

package/src/connections/node.d.ts

@@ -26,5 +26,5 @@ export declare const loadNodeFutexAddon: (specifier?: string) => NodeFutexAddon;
 export declare const fromNodeNativeMapping: (mapped: NodeSharedMemoryNativeMapping) => SharedMemoryMapping<SharedArrayBuffer>;
 export declare const createNodeSharedMemory: (options: number | CreateSharedMemoryOptions, addon?: NodeSharedMemoryAddon) => SharedMemoryMapping<SharedArrayBuffer>;
 export declare const mapNodeSharedMemory: (options: MapSharedMemoryOptions, addon?: NodeSharedMemoryAddon) => SharedMemoryMapping<SharedArrayBuffer>;
-export declare const createNodeConnectionPrimitives: (addon?: NodeSharedMemoryAddon) => SharedMemoryConnectionPrimitives<SharedMemoryMapping<SharedArrayBuffer>>;
+export declare const createNodeConnectionPrimitives: (addon?: NodeSharedMemoryAddon) => SharedMemoryConnectionPrimitives;
 export declare const unlinkNodeSharedMemory: (name: string, addon?: NodeSharedMemoryAddon) => boolean;

package/src/connections/node.js

@@ -1,24 +1,18 @@
 import { getNodeBuiltinModule } from "../common/node-compat.js";
-import { loadNodeNativeAddon } from "./node-addons.js";
-import { expectFd, expectPositiveSize, readCreateMode, readCreateName, readRequiredCreateName, readCreateSize, } from "./types.js";
+import { loadNodeNativeAddon, } from "./node-addons.js";
+import { createNodeFfiConnectionPrimitives, isNodeFfiTarget, } from "./node-ffi.js";
+import { expectFd, expectPositiveSize, readCreateMode, readCreateName, readCreateSize, readRequiredCreateName, } from "./types.js";
 export const DEFAULT_NODE_SHARED_MEMORY_ADDON = "../../build/Release/knitting_shared_memory.node";
 export const DEFAULT_NODE_FUTEX_ADDON = "../../build/Release/knitting_shm.node";
-export const loadNodeSharedMemoryAddon = (specifier) => {
+const loadNodeAddon = (label, name, specifier) => {
     const nodeModule = getNodeBuiltinModule("node:module");
     if (nodeModule === undefined) {
-        throw new Error("Node shared memory addon can only be loaded in Node");
+        throw new Error(`Node ${label} addon can only be loaded in Node`);
     }
-    const require = nodeModule.createRequire(import.meta.url);
-    return loadNodeNativeAddon(require, "knitting_shared_memory", specifier);
-};
-export const loadNodeFutexAddon = (specifier) => {
-    const nodeModule = getNodeBuiltinModule("node:module");
-    if (nodeModule === undefined) {
-        throw new Error("Node futex addon can only be loaded in Node");
-    }
-    const require = nodeModule.createRequire(import.meta.url);
-    return loadNodeNativeAddon(require, "knitting_shm", specifier);
+    return loadNodeNativeAddon(nodeModule.createRequire(import.meta.url), name, specifier);
 };
+export const loadNodeSharedMemoryAddon = (specifier) => loadNodeAddon("shared memory", "knitting_shared_memory", specifier);
+export const loadNodeFutexAddon = (specifier) => loadNodeAddon("futex", "knitting_shm", specifier);
 export const fromNodeNativeMapping = (mapped) => {
     const mapping = {
         runtime: "node",
@@ -48,12 +42,18 @@ export const mapNodeSharedMemory = (options, addon = loadNodeSharedMemoryAddon()
     const size = expectPositiveSize(options.size);
     return fromNodeNativeMapping(addon.mapSharedMemory(fd, size, options.name));
 };
-export const createNodeConnectionPrimitives = (addon = loadNodeSharedMemoryAddon()) => ({
-    runtime: "node",
-    createSharedMemory: (options) => createNodeSharedMemory(options, addon),
-    mapSharedMemory: (options) => mapNodeSharedMemory(options, addon),
-    unlinkSharedMemory: (name) => unlinkNodeSharedMemory(name, addon),
-});
+export const createNodeConnectionPrimitives = (addon) => {
+    if (addon === undefined && isNodeFfiTarget()) {
+        return createNodeFfiConnectionPrimitives();
+    }
+    const resolvedAddon = addon ?? loadNodeSharedMemoryAddon();
+    return {
+        runtime: "node",
+        createSharedMemory: (options) => createNodeSharedMemory(options, resolvedAddon),
+        mapSharedMemory: (options) => mapNodeSharedMemory(options, resolvedAddon),
+        unlinkSharedMemory: (name) => unlinkNodeSharedMemory(name, resolvedAddon),
+    };
+};
 export const unlinkNodeSharedMemory = (name, addon = loadNodeSharedMemoryAddon()) => {
     if (typeof addon.unlinkSharedMemory !== "function") {
         throw new Error("Node shared memory addon cannot unlink named mappings");

package/src/connections/package-assets.js

@@ -1,30 +1,40 @@
-import { existsSync, statSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-const safeExists = (path) => {
+import { getNodeBuiltinModule } from "../common/node-compat.js";
+let fsModule;
+let pathModule;
+let urlModule;
+const requireNode = (value, specifier) => {
+    if (value === undefined) {
+        throw new Error(`${specifier} is not available in this runtime`);
+    }
+    return value;
+};
+const fs = () => requireNode(fsModule ??= getNodeBuiltinModule("node:fs"), "node:fs");
+const path = () => requireNode(pathModule ??= getNodeBuiltinModule("node:path"), "node:path");
+const url = () => requireNode(urlModule ??= getNodeBuiltinModule("node:url"), "node:url");
+const safeExists = (target) => {
     try {
-        return existsSync(path);
+        return fs().existsSync(target);
     }
     catch {
         return false;
     }
 };
-const safeIsDirectory = (path) => {
+const safeIsDirectory = (target) => {
     try {
-        return statSync(path).isDirectory();
+        return fs().statSync(target).isDirectory();
     }
     catch {
         return false;
     }
 };
 const moduleDirectory = (moduleUrl) => {
-    const path = fileURLToPath(moduleUrl);
-    return safeIsDirectory(path) ? path : dirname(path);
+    const target = url().fileURLToPath(moduleUrl);
+    return safeIsDirectory(target) ? target : path().dirname(target);
 };
-const isKnittingPackageRoot = (dir) => safeExists(join(dir, "package.json")) &&
-    (safeExists(join(dir, "prebuilds")) ||
-        safeExists(join(dir, "src")) ||
-        safeExists(join(dir, "build")));
+const isKnittingPackageRoot = (dir) => safeExists(path().join(dir, "package.json")) &&
+    (safeExists(path().join(dir, "prebuilds")) ||
+        safeExists(path().join(dir, "src")) ||
+        safeExists(path().join(dir, "build")));
 let cachedPackageRoot;
 export const findKnittingPackageRoot = (moduleUrl = import.meta.url) => {
     if (cachedPackageRoot !== undefined)
@@ -35,11 +45,11 @@ export const findKnittingPackageRoot = (moduleUrl = import.meta.url) => {
             cachedPackageRoot = current;
             return current;
         }
-        const parent = dirname(current);
+        const parent = path().dirname(current);
         if (parent === current) {
             throw new Error(`Could not locate knitting package root from ${moduleUrl}`);
         }
         current = parent;
     }
 };
-export const resolveKnittingPackageAsset = (...segments) => join(findKnittingPackageRoot(), ...segments);
+export const resolveKnittingPackageAsset = (...segments) => path().join(findKnittingPackageRoot(), ...segments);

package/src/connections/posix.d.ts

@@ -15,11 +15,53 @@ export declare const F_GETFD = 1;
 export declare const F_SETFD = 2;
 export declare const FD_CLOEXEC = 1;
 export declare const encodeCString: (value: string) => Uint8Array;
+export declare const getErrnoSymbolName: (platform: PosixPlatform) => string;
+/** Best effort: the runtime can issue its own libc call before errno is read. */
+export type ErrnoReader = () => number | undefined;
+/**
+ * Wraps a bound `__error`/`__errno_location` into a reader that never throws.
+ * Runtimes differ only in how they turn the returned address into an int.
+ */
+export declare const makeErrnoReader: <Pointer>(locate: (() => Pointer) | undefined, readInt32: (pointer: Pointer) => number) => ErrnoReader;
+/**
+ * Builds `<message>: EACCES (13)`, reading errno as late as possible, or the
+ * bare message when the runtime has no errno reader.
+ */
+export declare const posixError: (message: string, errno?: ErrnoReader, platform?: PosixPlatform) => Error;
+export declare const checkPosixResult: (result: number, message: string, errno?: ErrnoReader, platform?: PosixPlatform) => number;
 type FcntlLibc = {
     symbols: {
         fcntl: (fd: number, cmd: number, arg: number) => number;
     };
 };
+/**
+ * Whether `shm_open`'s mode argument has to be delivered on the stack.
+ *
+ * macOS declares `shm_open(const char *, int, ...)` variadic and its libc
+ * wrapper reads the mode with `va_arg`. Apple's arm64 ABI passes variadic
+ * arguments on the stack, not in registers, so the mode a fixed-arity FFI call
+ * leaves in a register is never read: the segment is created with whatever the
+ * stack happened to hold. The creator's own descriptor still works, so the
+ * damage only surfaces when the name is opened again and fails with EACCES —
+ * and because the value comes from uninitialized stack, unrelated changes to
+ * the calling code can flip it between working and not.
+ *
+ * Declaring six extra register arguments moves the mode into the first stack
+ * slot, which is exactly where `va_arg` looks. Linux (fixed prototype) and
+ * x86-64 macOS (variadic arguments in registers) both want the plain form.
+ */
+export declare const shmOpenModeIsStackPassed: (platform?: PosixPlatform) => boolean;
+/** Fills x2–x7 so the mode becomes the first stack argument. */
+export declare const SHM_OPEN_STACK_PAD: readonly number[];
+/**
+ * Proves a freshly created macOS segment can be reopened by name, closing the
+ * owner descriptor and throwing if it cannot.
+ *
+ * Without this, a mode that failed to apply produces a confusing EACCES in
+ * whichever process later opens the name, far from the call that caused it.
+ * No-ops off macOS, where the mode always applies.
+ */
+export declare const assertNamedSharedMemoryIsReopenable: (platform: PosixPlatform, ownerFd: number, reopen: () => number, close: (fd: number) => number, errno?: ErrnoReader) => void;
 export declare const setCloseOnExec: <T extends FcntlLibc>(libc: T, fd: number) => number;
 export declare const shmOpenCreateFlag: (platform: PosixPlatform) => number;
 export declare const shmOpenExclusiveFlag: (platform: PosixPlatform) => number;