knitting 0.1.56 → 0.1.60

package/src/connections/buffer-reference.js

@@ -37,7 +37,8 @@ const RUNTIME_NODE = 1;
 const RUNTIME_DENO = 2;
 const RUNTIME_BUN = 3;
 const PAYLOAD_TRANSPORT_FINALIZER = Symbol.for("knitting.payloadCodec.transportFinalizer");
-let currentReturnReleaser;
+let currentReturnHooks;
+const bufferReferenceInstances = new WeakSet();
 const encodeRuntime = (runtime) => {
     switch (runtime) {
         case "node":
@@ -95,16 +96,17 @@ const numericMetadataToMetadata = (words) => {
         byteLength: words[5] ?? 0,
     };
 };
+const toReturnHooks = (releaser) => typeof releaser === "function" ? { release: releaser } : releaser;
 export const withBufferReferenceReturnReleaser = (releaser, run) => {
     if (releaser === undefined)
         return run();
-    const previous = currentReturnReleaser;
-    currentReturnReleaser = releaser;
+    const previous = currentReturnHooks;
+    currentReturnHooks = toReturnHooks(releaser);
     try {
         return run();
     }
     finally {
-        currentReturnReleaser = previous;
+        currentReturnHooks = previous;
     }
 };
 export const createBufferReferenceReturnReleaseMessage = (token) => ({
@@ -124,11 +126,13 @@ export const readBufferReferenceReturnReleaseMessage = (value) => {
         return undefined;
     }
 };
-// Backstop for references that never flow through the transport.
 const producerFinalizer = typeof FinalizationRegistry === "function"
-    ? new FinalizationRegistry(({ token, release }) => {
+    ? new FinalizationRegistry((backstop) => {
+        backstop.count -= 1;
+        if (backstop.count > 0)
+            return;
         try {
-            release(token);
+            backstop.release(backstop.token);
         }
         catch {
             // best effort
@@ -162,7 +166,8 @@ const assertMovableSource = (source) => {
 };
 const isDetached = (buffer) => buffer.detached === true ||
     buffer.byteLength === 0;
-const detachArrayBufferBestEffort = (runtime, buffer) => {
+/** Revocation primitive: detach `buffer` so every view over it is neutralized. */
+export const detachArrayBufferBestEffort = (runtime, buffer) => {
     if (isDetached(buffer))
         return true;
     if (runtime === "node") {
@@ -233,9 +238,11 @@ export class BufferReference {
     #token;
     #isProducer;
     #finalizerToken;
+    #producerBackstop;
     #materializedRegions;
     #owned;
     #borrowedReturnReleaser;
+    #borrowedReturnTrack;
     #borrowedReturnFinalizerToken;
     #transportRefs = 0;
     #released = false;
@@ -249,6 +256,7 @@ export class BufferReference {
             this.byteLength = meta.byteLength;
             this.#token = BigInt(meta.token);
             this.#isProducer = false;
+            bufferReferenceInstances.add(this);
             return;
         }
         if (source === undefined) {
@@ -264,8 +272,16 @@ export class BufferReference {
         this.byteLength = produced.byteLength;
         this.#token = produced.token;
         this.#isProducer = true;
-        this.#finalizerToken = {};
-        producerFinalizer?.register(this, { token: this.#token, release: caps.release }, this.#finalizerToken);
+        bufferReferenceInstances.add(this);
+        if (producerFinalizer !== undefined) {
+            this.#finalizerToken = {};
+            this.#producerBackstop = {
+                count: 1,
+                token: this.#token,
+                release: caps.release,
+            };
+            producerFinalizer.register(this, this.#producerBackstop, this.#finalizerToken);
+        }
     }
     static fromMetadata(meta) {
         if (!isBufferReferenceMetadata(meta)) {
@@ -325,7 +341,7 @@ export class BufferReference {
         }
     }
     /** Prepare a returned reference before the worker-side producer hold drains. */
-    claimOwnership(releaser = currentReturnReleaser) {
+    claimOwnership(releaser = currentReturnHooks) {
         if (this.#owned !== undefined || this.#borrowedReturnReleaser !== undefined ||
             this.#released)
             return this;
@@ -338,9 +354,18 @@ export class BufferReference {
             byteLength: this.byteLength,
         };
         if (releaser !== undefined) {
-            this.#borrowedReturnReleaser = releaser;
+            const hooks = toReturnHooks(releaser);
+            // Borrow: adopt lazily — the alias costs GC-visible external memory on
+            // FFI runtimes, so it is only created when the bytes are actually read.
+            // Until then no view can exist, so the GC backstop safely watches the
+            // reference itself; first materialize migrates it to the alias buffer
+            // (views strongly reference their buffer, so the worker pin can only
+            // drop once no view can reach the borrowed bytes).
+            this.#borrowedReturnReleaser = hooks.release;
+            this.#borrowedReturnTrack = hooks.track;
             this.#borrowedReturnFinalizerToken = {};
-            borrowedReturnFinalizer?.register(this, { token: this.#token, release: releaser }, this.#borrowedReturnFinalizerToken);
+            borrowedReturnFinalizer?.register(this, { token: this.#token, release: hooks.release }, this.#borrowedReturnFinalizerToken);
+            hooks.track?.(this, this.#token);
             return this;
         }
         this.#owned = caps.adopt(input, caps.supportsOwningAdopt ? undefined : { copy: true });
@@ -358,10 +383,22 @@ export class BufferReference {
             byteLength: this.byteLength,
         });
         if (this.#borrowedReturnReleaser !== undefined) {
+            // First borrowed read: views over this alias exist from here on, so
+            // move the GC backstop from the reference onto the alias buffer.
             this.#owned = region;
+            if (this.#borrowedReturnFinalizerToken !== undefined &&
+                borrowedReturnFinalizer !== undefined) {
+                borrowedReturnFinalizer.unregister(this.#borrowedReturnFinalizerToken);
+                borrowedReturnFinalizer.register(region.buffer, { token: this.#token, release: this.#borrowedReturnReleaser }, this.#borrowedReturnFinalizerToken);
+            }
+            this.#borrowedReturnTrack?.(this, this.#token, region.buffer);
             return region;
         }
         (this.#materializedRegions ??= []).push(region);
+        if (this.#producerBackstop !== undefined && producerFinalizer !== undefined) {
+            this.#producerBackstop.count += 1;
+            producerFinalizer.register(region.buffer, this.#producerBackstop, this.#finalizerToken);
+        }
         return region;
     }
     toArrayBuffer() {
@@ -383,38 +420,51 @@ export class BufferReference {
         if (this.#released)
             return;
         this.#released = true;
+        // Revoke every alias this reference handed out before any pin can drop.
+        // Leak-not-UAF: if a detach fails, the pin must stay held — the GC
+        // backstops remain registered and retry once the buffers are unreachable.
+        let allDetached = true;
         const regions = this.#materializedRegions;
         this.#materializedRegions = undefined;
         if (regions !== undefined) {
             for (let i = 0; i < regions.length; i++) {
-                detachArrayBufferBestEffort(this.runtime, regions[i].buffer);
+                allDetached =
+                    detachArrayBufferBestEffort(this.runtime, regions[i].buffer) &&
+                        allDetached;
             }
         }
-        if (this.#borrowedReturnFinalizerToken !== undefined) {
-            borrowedReturnFinalizer?.unregister(this.#borrowedReturnFinalizerToken);
-            this.#borrowedReturnFinalizerToken = undefined;
-        }
         const borrowedReturnReleaser = this.#borrowedReturnReleaser;
         this.#borrowedReturnReleaser = undefined;
+        this.#borrowedReturnTrack = undefined;
         if (borrowedReturnReleaser !== undefined) {
             const owned = this.#owned;
             this.#owned = undefined;
             if (owned !== undefined) {
-                detachArrayBufferBestEffort(this.runtime, owned.buffer);
-            }
-            try {
-                borrowedReturnReleaser(this.#token);
+                allDetached = detachArrayBufferBestEffort(this.runtime, owned.buffer) &&
+                    allDetached;
             }
-            catch {
-                // best effort
+            if (allDetached) {
+                if (this.#borrowedReturnFinalizerToken !== undefined) {
+                    borrowedReturnFinalizer?.unregister(this.#borrowedReturnFinalizerToken);
+                    this.#borrowedReturnFinalizerToken = undefined;
+                }
+                try {
+                    borrowedReturnReleaser(this.#token);
+                }
+                catch {
+                    // best effort
+                }
             }
-        }
-        if (this.#finalizerToken !== undefined) {
-            producerFinalizer?.unregister(this.#finalizerToken);
-            this.#finalizerToken = undefined;
+            // else: the finalizer stays registered on the alias buffer and sends
+            // the release once every escaped view is gone.
         }
         // Only the producer owns the registry hold; consumers must not drop it.
-        if (this.#isProducer) {
+        if (this.#isProducer && allDetached) {
+            if (this.#finalizerToken !== undefined) {
+                producerFinalizer?.unregister(this.#finalizerToken);
+                this.#finalizerToken = undefined;
+            }
+            this.#producerBackstop = undefined;
             try {
                 getBufferReferenceCapabilities().release(this.#token);
             }
@@ -422,6 +472,67 @@ export class BufferReference {
                 // best effort
             }
         }
+        // else on failed detach: the countdown backstop drops the pin when the
+        // reference and every materialized alias are unreachable.
+    }
+    /**
+     * Revoke a borrowed return before its producing worker goes away: detach
+     * the borrowed alias so no view can dangle. With `copyBytes` the reference
+     * itself survives on an owned copy; without it (worker bytes already gone)
+     * later reads fail loud instead of aliasing freed memory.
+     */
+    revokeBorrow(copyBytes) {
+        const releaser = this.#borrowedReturnReleaser;
+        if (releaser === undefined || this.#released)
+            return;
+        const owned = this.#owned;
+        let nextOwned;
+        let detached = true;
+        if (owned !== undefined) {
+            if (copyBytes) {
+                nextOwned = {
+                    buffer: owned.buffer.slice(owned.byteOffset, owned.byteOffset + owned.byteLength),
+                    byteOffset: 0,
+                    byteLength: owned.byteLength,
+                };
+            }
+            // Without a copy, keep the (now detached) region so reads throw
+            // instead of re-materializing an alias over freed worker memory.
+            detached = detachArrayBufferBestEffort(this.runtime, owned.buffer);
+        }
+        else if (copyBytes) {
+            // Never materialized: take the bytes now, while the worker still pins
+            // them, so the reference stays readable after its worker dies.
+            const caps = getBufferReferenceCapabilities();
+            nextOwned = caps.adopt({
+                token: this.#token,
+                pointer: this.pointer,
+                byteOffset: this.byteOffset,
+                byteLength: this.byteLength,
+            }, { copy: !caps.supportsOwningAdopt });
+        }
+        else {
+            // Never materialized and the worker bytes are already gone: no view
+            // exists, so poison future reads instead of aliasing freed memory.
+            this.#released = true;
+        }
+        if (!detached)
+            return;
+        if (nextOwned !== undefined)
+            this.#owned = nextOwned;
+        this.#borrowedReturnReleaser = undefined;
+        this.#borrowedReturnTrack = undefined;
+        if (this.#borrowedReturnFinalizerToken !== undefined) {
+            borrowedReturnFinalizer?.unregister(this.#borrowedReturnFinalizerToken);
+            this.#borrowedReturnFinalizerToken = undefined;
+        }
+        // Best effort: if the worker is still alive it can drop its pin early.
+        try {
+            releaser(this.#token);
+        }
+        catch {
+            // best effort
+        }
     }
     [Symbol.dispose]() {
         this.release();
@@ -445,6 +556,9 @@ export class BufferReference {
         return finalizer;
     }
 }
+export const isBufferReferenceValue = (value) => value !== null &&
+    typeof value === "object" &&
+    bufferReferenceInstances.has(value);
 const codecGlobal = globalThis;
 const codecs = codecGlobal.__KNITTING_PAYLOAD_CODECS__ ??= Object.create(null);
 codecs[BUFFER_REFERENCE_CODEC_ID] = {

package/src/connections/bun.d.ts

@@ -3,7 +3,7 @@ type BunPointer = number;
 type BunLibc = {
     symbols: {
         memfd_create?: (name: Uint8Array, flags: number) => number;
-        shm_open?: (name: Uint8Array, flags: number, mode: number) => number;
+        shm_open?: (name: Uint8Array, flags: number, ...rest: number[]) => number;
         shm_unlink?: (name: Uint8Array) => number;
         ftruncate: (fd: number, length: bigint) => number;
         dup: (fd: number) => number;

package/src/connections/bun.js

@@ -1,5 +1,5 @@
-import { DARWIN_O_CREAT, DARWIN_O_EXCL, DARWIN_SHM_MODE, LINUX_O_CREAT, LINUX_O_EXCL, setCloseOnExec, detectPosixPlatform, encodeCString, getPosixLibcPath, makeDarwinSharedMemoryName, MAP_SHARED, O_RDWR, POSIX_SHM_MODE, PROT_READ, PROT_WRITE, toPosixSharedMemoryName, } from "./posix.js";
-import { expectFd, expectPositiveSize, readCreateName, readCreateMode, readRequiredCreateName, readCreateSize, } from "./types.js";
+import { assertNamedSharedMemoryIsReopenable, checkPosixResult, DARWIN_O_CREAT, DARWIN_O_EXCL, DARWIN_SHM_MODE, detectPosixPlatform, encodeCString, getPosixLibcPath, LINUX_O_CREAT, LINUX_O_EXCL, makeDarwinSharedMemoryName, MAP_SHARED, O_RDWR, POSIX_SHM_MODE, posixError, PROT_READ, PROT_WRITE, setCloseOnExec, SHM_OPEN_STACK_PAD, shmOpenModeIsStackPassed, toPosixSharedMemoryName, } from "./posix.js";
+import { expectFd, expectPositiveSize, readCreateMode, readCreateName, readCreateSize, readRequiredCreateName, } from "./types.js";
 import { createBunWindowsConnectionPrimitives, isWindowsRuntime, } from "./windows.js";
 const FFIType = {
     i32: 5,
@@ -53,7 +53,14 @@ export const openBunLibc = () => getBunFFI().dlopen(getPosixLibcPath(), {
 const getBunCreateSymbols = (platform = detectPosixPlatform()) => platform === "darwin"
     ? {
         shm_open: {
-            args: [FFIType.ptr, FFIType.i32, FFIType.u32],
+            args: shmOpenModeIsStackPassed(platform)
+                ? [
+                    FFIType.ptr,
+                    FFIType.i32,
+                    ...SHM_OPEN_STACK_PAD.map(() => FFIType.i32),
+                    FFIType.u32,
+                ]
+                : [FFIType.ptr, FFIType.i32, FFIType.u32],
             returns: FFIType.i32,
         },
         shm_unlink: {
@@ -75,11 +82,9 @@ const getBunCreateSymbols = (platform = detectPosixPlatform()) => platform === "
             returns: FFIType.i32,
         },
     };
-const checkResult = (result, message) => {
-    if (result < 0)
-        throw new Error(message);
-    return result;
-};
+const callShmOpen = (shmOpen, name, flags, mode, platform) => shmOpenModeIsStackPassed(platform)
+    ? shmOpen(name, flags, ...SHM_OPEN_STACK_PAD, mode)
+    : shmOpen(name, flags, mode);
 const isBunMmapFailed = (pointer) => !pointer || pointer < 0 || pointer >= Number.MAX_SAFE_INTEGER;
 const createBunSharedMemoryFd = (name, platform, libc) => {
     if (platform === "darwin") {
@@ -89,7 +94,7 @@ const createBunSharedMemoryFd = (name, platform, libc) => {
             throw new Error("shm_open symbols are not available");
         }
         const shmName = encodeCString(makeDarwinSharedMemoryName(name, "bun"));
-        const fd = checkResult(shmOpen(shmName, O_RDWR | DARWIN_O_CREAT | DARWIN_O_EXCL, DARWIN_SHM_MODE), "shm_open failed");
+        const fd = checkPosixResult(callShmOpen(shmOpen, shmName, O_RDWR | DARWIN_O_CREAT | DARWIN_O_EXCL, DARWIN_SHM_MODE, platform), "shm_open failed");
         shmUnlink(shmName);
         try {
             return setCloseOnExec(libc, fd);
@@ -103,7 +108,7 @@ const createBunSharedMemoryFd = (name, platform, libc) => {
     if (memfdCreate === undefined) {
         throw new Error("memfd_create symbol is not available");
     }
-    const fd = checkResult(memfdCreate(encodeCString(name), 0), "memfd_create failed");
+    const fd = checkPosixResult(memfdCreate(encodeCString(name), 0), "memfd_create failed");
     try {
         return setCloseOnExec(libc, fd);
     }
@@ -122,7 +127,12 @@ const createNamedBunSharedMemoryFd = (name, mode, platform, libc) => {
     const flags = mode === "create"
         ? O_RDWR | createFlags | exclusiveFlags
         : O_RDWR;
-    const fd = checkResult(shmOpen(encodeCString(toPosixSharedMemoryName(name)), flags, platform === "darwin" ? DARWIN_SHM_MODE : POSIX_SHM_MODE), "shm_open failed");
+    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");
+    if (mode === "create") {
+        assertNamedSharedMemoryIsReopenable(platform, fd, () => callShmOpen(shmOpen, shmName, O_RDWR, shmMode, platform), libc.symbols.close);
+    }
     try {
         return setCloseOnExec(libc, fd);
     }
@@ -139,7 +149,7 @@ export const mapBunSharedMemory = (options, libc = openBunLibc()) => {
         fd = createNamedBunSharedMemoryFd(options.name, "open", detectPosixPlatform(), libc);
     }
     else if (options.duplicateFd !== false) {
-        fd = checkResult(libc.symbols.dup(sourceFd), "dup(fd) failed");
+        fd = checkPosixResult(libc.symbols.dup(sourceFd), "dup(fd) failed");
         try {
             setCloseOnExec(libc, fd);
         }
@@ -150,9 +160,10 @@ export const mapBunSharedMemory = (options, libc = openBunLibc()) => {
     }
     const pointer = libc.symbols.mmap(null, size, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0n);
     if (isBunMmapFailed(pointer)) {
+        const error = posixError("mmap failed");
         if (options.duplicateFd !== false)
             libc.symbols.close(fd);
-        throw new Error("mmap failed");
+        throw error;
     }
     const arrayBuffer = getBunFFI().toArrayBuffer(pointer, 0, size);
     return {
@@ -183,7 +194,7 @@ export const createBunSharedMemory = (options, libc = openBunLibc()) => {
         : createNamedBunSharedMemoryFd(name, mode, platform, libc);
     try {
         if (mode !== "open") {
-            checkResult(libc.symbols.ftruncate(fd, BigInt(size)), "ftruncate failed");
+            checkPosixResult(libc.symbols.ftruncate(fd, BigInt(size)), "ftruncate failed");
         }
         const mapping = mapBunSharedMemory({ fd, size, duplicateFd: false }, libc);
         if (mode !== "anonymous") {

package/src/connections/deno.d.ts

@@ -2,8 +2,10 @@ import { type CreateSharedMemoryOptions, type MapSharedMemoryOptions, type Share
 type DenoLibc = {
     symbols: {
         memfd_create?: (name: Uint8Array, flags: number) => number;
-        shm_open?: (name: Uint8Array, flags: number, mode: number) => number;
+        shm_open?: (name: Uint8Array, flags: number, ...rest: number[]) => number;
         shm_unlink?: (name: Uint8Array) => number;
+        __error?: () => unknown;
+        __errno_location?: () => unknown;
         ftruncate: (fd: number, length: bigint) => number;
         dup: (fd: number) => number;
         fcntl: (fd: number, cmd: number, arg: number) => number;

package/src/connections/deno.js

@@ -1,5 +1,5 @@
-import { DARWIN_O_CREAT, DARWIN_O_EXCL, DARWIN_SHM_MODE, LINUX_O_CREAT, LINUX_O_EXCL, setCloseOnExec, detectPosixPlatform, encodeCString, getPosixLibcPath, makeDarwinSharedMemoryName, MAP_SHARED, O_RDWR, POSIX_SHM_MODE, PROT_READ, PROT_WRITE, toPosixSharedMemoryName, } from "./posix.js";
-import { expectFd, expectPositiveSize, readCreateName, readCreateMode, readRequiredCreateName, readCreateSize, } from "./types.js";
+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 { expectFd, expectPositiveSize, readCreateMode, readCreateName, readCreateSize, readRequiredCreateName, } from "./types.js";
 import { createDenoWindowsConnectionPrimitives, isWindowsRuntime, } from "./windows.js";
 const getDeno = () => {
     const deno = globalThis.Deno;
@@ -8,8 +8,15 @@ const getDeno = () => {
     }
     return deno;
 };
+const getDenoErrnoSymbols = (platform = detectPosixPlatform()) => ({
+    [getErrnoSymbolName(platform)]: {
+        parameters: [],
+        result: "pointer",
+    },
+});
 export const openDenoLibc = () => getDeno().dlopen(getPosixLibcPath(), {
     ...getDenoCreateSymbols(),
+    ...getDenoErrnoSymbols(),
     ftruncate: {
         parameters: ["i32", "i64"],
         result: "i32",
@@ -38,7 +45,14 @@ export const openDenoLibc = () => getDeno().dlopen(getPosixLibcPath(), {
 const getDenoCreateSymbols = (platform = detectPosixPlatform()) => platform === "darwin"
     ? {
         shm_open: {
-            parameters: ["buffer", "i32", "u32"],
+            parameters: shmOpenModeIsStackPassed(platform)
+                ? [
+                    "buffer",
+                    "i32",
+                    ...SHM_OPEN_STACK_PAD.map(() => "i32"),
+                    "u32",
+                ]
+                : ["buffer", "i32", "u32"],
             result: "i32",
         },
         shm_unlink: {
@@ -60,11 +74,12 @@ const getDenoCreateSymbols = (platform = detectPosixPlatform()) => platform ===
             result: "i32",
         },
     };
-const checkResult = (result, message) => {
-    if (result < 0)
-        throw new Error(message);
-    return result;
-};
+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.symbols.__error
+    : libc.symbols.__errno_location, (pointer) => new Int32Array(new (getDeno().UnsafePointerView)(pointer).getArrayBuffer(4))[0]);
 const isDenoMmapFailed = (pointer) => {
     if (pointer === null)
         return true;
@@ -79,7 +94,7 @@ const createDenoSharedMemoryFd = (name, platform, libc) => {
             throw new Error("shm_open symbols are not available");
         }
         const shmName = encodeCString(makeDarwinSharedMemoryName(name, "deno"));
-        const fd = checkResult(shmOpen(shmName, O_RDWR | DARWIN_O_CREAT | DARWIN_O_EXCL, DARWIN_SHM_MODE), "shm_open failed");
+        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(libc, fd);
@@ -93,7 +108,7 @@ const createDenoSharedMemoryFd = (name, platform, libc) => {
     if (memfdCreate === undefined) {
         throw new Error("memfd_create symbol is not available");
     }
-    const fd = checkResult(memfdCreate(encodeCString(name), 0), "memfd_create failed");
+    const fd = checkPosixResult(memfdCreate(encodeCString(name), 0), "memfd_create failed", errnoOf(libc, platform), platform);
     try {
         return setCloseOnExec(libc, fd);
     }
@@ -112,7 +127,12 @@ const createNamedDenoSharedMemoryFd = (name, mode, platform, libc) => {
     const flags = mode === "create"
         ? O_RDWR | createFlags | exclusiveFlags
         : O_RDWR;
-    const fd = checkResult(shmOpen(encodeCString(toPosixSharedMemoryName(name)), flags, platform === "darwin" ? DARWIN_SHM_MODE : POSIX_SHM_MODE), "shm_open failed");
+    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.symbols.close, errnoOf(libc, platform));
+    }
     try {
         return setCloseOnExec(libc, fd);
     }
@@ -129,7 +149,7 @@ export const mapDenoSharedMemory = (options, libc = openDenoLibc()) => {
         fd = createNamedDenoSharedMemoryFd(options.name, "open", detectPosixPlatform(), libc);
     }
     else if (options.duplicateFd !== false) {
-        fd = checkResult(libc.symbols.dup(sourceFd), "dup(fd) failed");
+        fd = checkPosixResult(libc.symbols.dup(sourceFd), "dup(fd) failed", errnoOf(libc));
         try {
             setCloseOnExec(libc, fd);
         }
@@ -140,9 +160,10 @@ export const mapDenoSharedMemory = (options, libc = openDenoLibc()) => {
     }
     const pointer = libc.symbols.mmap(null, size, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0n);
     if (isDenoMmapFailed(pointer)) {
+        const error = posixError("mmap failed", errnoOf(libc));
         if (options.duplicateFd !== false)
             libc.symbols.close(fd);
-        throw new Error("mmap failed");
+        throw error;
     }
     const arrayBuffer = new (getDeno().UnsafePointerView)(pointer)
         .getArrayBuffer(size);
@@ -174,7 +195,7 @@ export const createDenoSharedMemory = (options, libc = openDenoLibc()) => {
         : createNamedDenoSharedMemoryFd(name, mode, platform, libc);
     try {
         if (mode !== "open") {
-            checkResult(libc.symbols.ftruncate(fd, BigInt(size)), "ftruncate failed");
+            checkPosixResult(libc.symbols.ftruncate(fd, BigInt(size)), "ftruncate failed", errnoOf(libc, platform), platform);
         }
         const mapping = mapDenoSharedMemory({ fd, size, duplicateFd: false }, libc);
         if (mode !== "anonymous") {

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));
 };