@gjsify/sab-native 0.51.1 → 0.53.0

package/README.md

@@ -1,17 +1,17 @@
 # @gjsify/sab-native
 
-Optional native Vala bridge providing cross-process shared memory and atomics for `@gjsify/worker_threads` on GJS. Implements `SharedBuffer` via Linux `memfd_create` + `mmap(MAP_SHARED)` with typed accessors and SEQ_CST atomics backed by `__atomic_*` GCC builtins and `SYS_futex` for wait/notify. Also exposes `FdChannel` for passing file descriptors between processes via SCM_RIGHTS over a Unix-domain socket.
+Optional native Vala bridge providing cross-process shared memory and atomics for `@gjsify/worker_threads` on GJS. Implements `SharedBuffer` as an anonymous `mmap(MAP_SHARED)` region (Linux `memfd_create`, macOS `shm_open` + immediate `shm_unlink`) with typed accessors and SEQ_CST atomics backed by `__atomic_*` builtins, and an address-keyed cross-process wait/notify (Linux `SYS_futex`, macOS `os_sync_wait_on_address`). Also exposes `FdChannel` for passing file descriptors between processes via SCM_RIGHTS over a Unix-domain socket.
 
 Part of the [gjsify](https://github.com/gjsify/gjsify) project — Node.js and Web APIs for GJS (GNOME JavaScript).
 
 ## Platform support
 
-**Cross-process `SharedBuffer` is Linux-only today.** This is a property of the package, not of your installation — see [ADR 0013](../../../docs/adr/0013-sab-native-platform-scope.md) for the full reasoning.
+**Cross-process `SharedBuffer` works on Linux and macOS 14.4+; Windows is not supported.** This is a property of the package, not of your installation — see [ADR 0013](../../../docs/adr/0013-sab-native-platform-scope.md) for the full reasoning.
 
 | Platform | Cross-process `SharedBuffer` | Notes |
 |---|---|---|
 | Linux `x86_64`, `aarch64`, `ppc64`, `s390x`, `riscv64` | ✅ Supported | `memfd_create(2)` + `mmap(MAP_SHARED)`, `SYS_futex` (non-private flavour, so waits match across processes), `SCM_RIGHTS`. Prebuilds ship for all five architectures. |
-| macOS | ❌ Not yet | Planned, design fixed: `shm_open` + `ftruncate` + immediate `shm_unlink` for the region, unchanged `SCM_RIGHTS`, and `os_sync_wait_on_address` / `os_sync_wake_by_address_*` with the `…_SHARED` flag for wait/notify. Requires **macOS 14.4+**. Blocked on a macOS prebuild CI job. |
+| macOS `arm64`, `x86_64` | ✅ Supported | `shm_open` + `ftruncate` + immediate `shm_unlink` for the region, `os_sync_wait_on_address` / `os_sync_wake_by_address_any` with the `…_SHARED` flag for wait/notify, `SCM_RIGHTS` over a `SOCK_STREAM` pair (Darwin has no Unix-domain `SOCK_SEQPACKET`). Requires **macOS 14.4+**. Prebuilds come from CI's macOS job. |
 | Windows | ❌ Not supported | Blocked twice over: GJS itself does not run on Windows, and Windows has no cross-process address-keyed wait — `WaitOnAddress`/`WakeByAddressSingle` are process-local by documentation, so `wait32`/`notify32` would need a different contract (named kernel objects). Revisit only via a new ADR. |
 | Node.js / browser | ❌ n/a | GJS-only package (`runtimes.node`/`.browser` = `none`). |
 
@@ -63,7 +63,7 @@ if (hasNativeSab()) {
 }
 ```
 
-Ships as a prebuilt `.so` + `.typelib` for `linux-{x64,arm64,ppc64,s390x,riscv64}`.
+Ships as a prebuilt library + `.typelib` for `linux-{x64,arm64,ppc64,s390x,riscv64}` (`.so`) and `darwin-{arm64,x64}` (`.dylib`), each in its own `@gjsify/sab-native-<os>-<arch>` package.
 
 ## License
 

package/lib/esm/index.js

@@ -1 +1 @@
-import"./_virtual/_rolldown/runtime.js";const e=globalThis;function resolveNativeSab(e){if(!e)return null;let t;try{t=e.GjsifySabNative}catch{return null}if(!t||typeof t!=`object`)return null;let n=t;return typeof n.SharedBuffer?.create!=`function`||typeof n.FdChannel?.make_pair!=`function`?null:n}const t=resolveNativeSab(e.imports?.gi),n=t;function hasNativeSab(){return t!==null}const r="@gjsify/sab-native: the native backend is not available on this platform. Cross-process SharedBuffer is currently Linux-only (memfd_create + futex + SCM_RIGHTS); prebuilds ship for linux-{x64,arm64,ppc64,s390x,riscv64} only — macOS support is planned and Windows is unsupported (see docs/adr/0013-sab-native-platform-scope.md). Guard with hasNativeSab() before using SharedBuffer. On Linux, a missing prebuild can be built locally with `gjsify workspace @gjsify/sab-native build:prebuilds`.";var i=class SharedBuffer{_native;constructor(e){this._native=e}static create(e){if(!t)throw Error(r);if(!Number.isInteger(e)||e<=0)throw TypeError(`SharedBuffer.create: size must be a positive integer`);let n=t.SharedBuffer.create(e);if(!n)throw Error(`memfd_create or mmap failed`);return new SharedBuffer(n)}static fromFd(e,n){if(!t)throw Error(r);if(!Number.isInteger(e)||e<0)throw TypeError(`SharedBuffer.fromFd: fd must be a non-negative integer`);if(!Number.isInteger(n)||n<=0)throw TypeError(`SharedBuffer.fromFd: size must be a positive integer`);let i=t.SharedBuffer.from_fd(e,n);if(!i)throw Error(`mmap failed`);return new SharedBuffer(i)}get byteLength(){return this._assertOpen().byte_length}get fd(){return this._assertOpen().fd}get closed(){return this._native===null}close(){this._native=null}getUint8(e){return this._assertOpen().get_u8(e)}setUint8(e,t){this._assertOpen().set_u8(e,t&255)}getUint32LE(e){return this._assertOpen().get_u32_le(e)}setUint32LE(e,t){this._assertOpen().set_u32_le(e,t>>>0)}getInt32LE(e){return this._assertOpen().get_i32_le(e)}setInt32LE(e,t){this._assertOpen().set_i32_le(e,t|0)}getBigUint64LE(e){return this._assertOpen().get_u64_le(e)}setBigUint64LE(e,t){this._assertOpen().set_u64_le(e,t)}readBytes(t,n){let r=this._assertOpen().read_bytes(t,n),i=e.imports?.byteArray;if(i&&typeof i.fromGBytes==`function`){let e=i.fromGBytes(r);return new Uint8Array(e)}return new Uint8Array(r.toArray())}viewBytes(e,t){return this.readBytes(e,t)}toBuffer(t=0,n){let r=n??this.byteLength-t,i=this.viewBytes(t,r),a=e.Buffer;if(typeof a?.from!=`function`)throw Error(`SharedBuffer.toBuffer: globalThis.Buffer is not registered. Import "@gjsify/buffer/register" or rely on --globals auto.`);return a.from(i.buffer,i.byteOffset,i.byteLength)}writeBytes(t,n){let r=e.imports?.byteArray,i;if(r&&typeof r.toGBytes==`function`)i=r.toGBytes(n);else{let t=e.imports?.gi?.GLib;i=t?.Bytes?new t.Bytes(n):n}this._assertOpen().write_bytes(t,i)}get _nativeHandle(){return this._assertOpen()}_assertOpen(){if(!this._native)throw Error(`SharedBuffer has been closed`);return this._native}};const a={add32(e,t,n){return e._nativeHandle.atomic_add_i32(t,n|0)},sub32(e,t,n){return e._nativeHandle.atomic_sub_i32(t,n|0)},load32(e,t){return e._nativeHandle.atomic_load_i32(t)},store32(e,t,n){e._nativeHandle.atomic_store_i32(t,n|0)},exchange32(e,t,n){return e._nativeHandle.atomic_xchg_i32(t,n|0)},compareExchange32(e,t,n,r){return e._nativeHandle.atomic_cmpxchg_i32(t,n|0,r|0)},wait32(e,t,n,r){let i=e._nativeHandle.futex_wait(t,n|0,r|0);if(i===0)return`ok`;if(i===-1)return`not-equal`;if(i===-2)return`timed-out`;if(i===-3)return`interrupted`;throw Error(`futex_wait returned errno ${-i}`)},notify32(e,t,n){return e._nativeHandle.futex_wake(t,n|0)}},o=t?{makePair(){let[e,n,r]=t.FdChannel.make_pair();if(!e)throw Error(`socketpair() failed`);return{parentFd:n,childFd:r}},sendFd(e,n,r){return t.FdChannel.send_fd(e,n,r>>>0)},recvFd(e){let[n,r]=t.FdChannel.recv_fd(e);if(n===0)return null;if(n<0)throw Error(`recvmsg failed`);return{fd:n,tag:r>>>0}},closeFd(e){t.FdChannel.close_fd(e)}}:null;export{r as NATIVE_SAB_UNAVAILABLE,i as SharedBuffer,a as atomics,o as fdChannel,hasNativeSab,n as nativeSab,resolveNativeSab};
+import"./_virtual/_rolldown/runtime.js";import{openNativeLibrary as e}from"@gjsify/utils/core";const t=globalThis;function resolveNativeSab(t){if(!t)return null;let n;try{n=t.GjsifySabNative}catch{return null}if(!n||typeof n!=`object`)return null;let r=e(`GjsifySabNative`,t);if(r)return console.debug(r.message),null;let i=n;return typeof i.SharedBuffer?.create!=`function`||typeof i.FdChannel?.make_pair!=`function`?null:i}const n=resolveNativeSab(t.imports?.gi),r=n;function hasNativeSab(){return n!==null}const i="@gjsify/sab-native: the native backend is not available on this platform. Cross-process SharedBuffer is supported on Linux (memfd_create + futex + SCM_RIGHTS; prebuilds for linux-{x64,arm64,ppc64,s390x,riscv64}) and on macOS 14.4+ (shm_open + os_sync_wait_on_address; prebuilds for darwin-{arm64,x64}) — Windows is unsupported (see docs/adr/0013-sab-native-platform-scope.md). Guard with hasNativeSab() before using SharedBuffer. On Linux or macOS, a missing prebuild can be built locally with `gjsify workspace @gjsify/sab-native build:prebuilds`.";var a=class SharedBuffer{_native;constructor(e){this._native=e}static create(e){if(!n)throw Error(i);if(!Number.isInteger(e)||e<=0)throw TypeError(`SharedBuffer.create: size must be a positive integer`);let t=n.SharedBuffer.create(e);if(!t)throw Error(`memfd_create or mmap failed`);return new SharedBuffer(t)}static fromFd(e,t){if(!n)throw Error(i);if(!Number.isInteger(e)||e<0)throw TypeError(`SharedBuffer.fromFd: fd must be a non-negative integer`);if(!Number.isInteger(t)||t<=0)throw TypeError(`SharedBuffer.fromFd: size must be a positive integer`);let r=n.SharedBuffer.from_fd(e,t);if(!r)throw Error(`mmap failed`);return new SharedBuffer(r)}get byteLength(){return this._assertOpen().byte_length}get fd(){return this._assertOpen().fd}get closed(){return this._native===null}close(){this._native=null}getUint8(e){return this._assertOpen().get_u8(e)}setUint8(e,t){this._assertOpen().set_u8(e,t&255)}getUint32LE(e){return this._assertOpen().get_u32_le(e)}setUint32LE(e,t){this._assertOpen().set_u32_le(e,t>>>0)}getInt32LE(e){return this._assertOpen().get_i32_le(e)}setInt32LE(e,t){this._assertOpen().set_i32_le(e,t|0)}getBigUint64LE(e){return this._assertOpen().get_u64_le(e)}setBigUint64LE(e,t){this._assertOpen().set_u64_le(e,t)}readBytes(e,n){let r=this._assertOpen().read_bytes(e,n),i=t.imports?.byteArray;if(i&&typeof i.fromGBytes==`function`){let e=i.fromGBytes(r);return new Uint8Array(e)}return new Uint8Array(r.toArray())}viewBytes(e,t){return this.readBytes(e,t)}toBuffer(e=0,n){let r=n??this.byteLength-e,i=this.viewBytes(e,r),a=t.Buffer;if(typeof a?.from!=`function`)throw Error(`SharedBuffer.toBuffer: globalThis.Buffer is not registered. Import "@gjsify/buffer/register" or rely on --globals auto.`);return a.from(i.buffer,i.byteOffset,i.byteLength)}writeBytes(e,n){let r=t.imports?.byteArray,i;if(r&&typeof r.toGBytes==`function`)i=r.toGBytes(n);else{let e=t.imports?.gi?.GLib;i=e?.Bytes?new e.Bytes(n):n}this._assertOpen().write_bytes(e,i)}get _nativeHandle(){return this._assertOpen()}_assertOpen(){if(!this._native)throw Error(`SharedBuffer has been closed`);return this._native}};const o={add32(e,t,n){return e._nativeHandle.atomic_add_i32(t,n|0)},sub32(e,t,n){return e._nativeHandle.atomic_sub_i32(t,n|0)},load32(e,t){return e._nativeHandle.atomic_load_i32(t)},store32(e,t,n){e._nativeHandle.atomic_store_i32(t,n|0)},exchange32(e,t,n){return e._nativeHandle.atomic_xchg_i32(t,n|0)},compareExchange32(e,t,n,r){return e._nativeHandle.atomic_cmpxchg_i32(t,n|0,r|0)},wait32(e,t,n,r){let i=e._nativeHandle.futex_wait(t,n|0,r|0);if(i===0)return`ok`;if(i===-1)return`not-equal`;if(i===-2)return`timed-out`;if(i===-3)return`interrupted`;throw Error(`futex_wait returned errno ${-i}`)},notify32(e,t,n){return e._nativeHandle.futex_wake(t,n|0)}},s=n?{makePair(){let[e,t,r]=n.FdChannel.make_pair();if(!e)throw Error(`socketpair() failed`);return{parentFd:t,childFd:r}},sendFd(e,t,r){return n.FdChannel.send_fd(e,t,r>>>0)},recvFd(e){let[t,r]=n.FdChannel.recv_fd(e);if(t===0)return null;if(t<0)throw Error(`recvmsg failed`);return{fd:t,tag:r>>>0}},closeFd(e){n.FdChannel.close_fd(e)}}:null;export{i as NATIVE_SAB_UNAVAILABLE,a as SharedBuffer,o as atomics,s as fdChannel,hasNativeSab,r as nativeSab,resolveNativeSab};

package/lib/types/index.d.ts

@@ -37,7 +37,7 @@ export interface GjsifySabNativeModule {
 /**
  * Resolve the `GjsifySabNative` GI module, normalising EVERY unavailable case to
  * `null`: no `gi` at all (not GJS), a throwing property access (typelib not on
- * `GI_TYPELIB_PATH` — the macOS/Windows case), and a value that is not the module
+ * `GI_TYPELIB_PATH` — the Windows case, or a target with no prebuild), and a value that is not the module
  * we expect (stale, partial or shadowed typelib). The third needs the shape check:
  * a partial value otherwise leaves `hasNativeSab()` reporting `true` and fails with
  * an opaque `TypeError` at first use.
@@ -50,7 +50,7 @@ export declare function resolveNativeSab(gi: Record<string, unknown> | undefined
 export declare const nativeSab: GjsifySabNativeModule | null;
 /**
  * THE gate for cross-process `SharedBuffer`, and platform-conditional by design:
- * `true` only on Linux (ADR 0013), `false` on macOS, Windows, Node and the browser.
+ * `true` only on Linux and macOS (ADR 0013), `false` on Windows, Node and the browser.
  * Guard every use of `SharedBuffer` / `atomics` / `fdChannel` with it.
  */
 export declare function hasNativeSab(): boolean;

package/meson.build

@@ -1,4 +1,10 @@
-project('GjsifySabNative', ['c', 'vala'], version: '1.0')
+# `buildtype=plain` = NO `-g`. ld64 emits a DEBUG MAP into any image whose objects
+# carry DWARF — one `N_OSO` stab per object, holding its MTIME — so with `-g` every
+# rebuild of this commit differed in bytes (plus the `LC_UUID` and the ad-hoc signature
+# computed over them) and `commit-prebuilds` re-committed all 16 darwin dylibs. That map
+# names intermediate `.o` files no consumer can have. Why: docs/prebuilds.md.
+project('GjsifySabNative', ['c', 'vala'], version: '1.0',
+        default_options: ['buildtype=plain'])
 
 root_dir = meson.current_source_dir()
 
@@ -6,8 +12,12 @@ root_dir = meson.current_source_dir()
 #   dnf install vala meson ninja-build
 #
 # No external C libraries — sab-native uses libc-only primitives:
-#   memfd_create(2), mmap(2), syscall(SYS_futex), __atomic_* GCC builtins,
-#   AF_UNIX socketpair + SCM_RIGHTS.  All available on every Linux glibc since 3.17.
+#   Linux:  memfd_create(2), mmap(2), syscall(SYS_futex), __atomic_* builtins,
+#           AF_UNIX socketpair + SCM_RIGHTS. Every Linux glibc since 3.17.
+#   darwin: shm_open(2), mmap(2), os_sync_wait_on_address (macOS 14.4+),
+#           __atomic_* builtins, AF_UNIX socketpair + SCM_RIGHTS
+#           (Homebrew: brew install vala meson ninja gobject-introspection).
+#   See docs/adr/0013-sab-native-platform-scope.md for why the two differ.
 #
 # Vala can't express the futex syscall + SCM_RIGHTS ancillary-data dance
 # cleanly, so we wrap them in a small C shim (src/vala/sab-helpers.{h,c})
@@ -29,8 +39,19 @@ sources = files(
 # Compiler picks up sab-helpers.h via the include dir.
 inc = include_directories('src/vala')
 
+host_system = host_machine.system()
+
 # -D_GNU_SOURCE: needed for memfd_create + MFD_CLOEXEC + SYS_futex visibility.
-c_args = ['-D_GNU_SOURCE']
+# darwin exposes everything its backend uses by default.
+c_args = host_system == 'darwin' ? [] : ['-D_GNU_SOURCE']
+
+# The typelib records the library's leaf, and GI dlopens exactly that name —
+# a `.so` leaf on darwin is found via GI_TYPELIB_PATH and then never loads.
+if host_system == 'darwin'
+    shared_lib_name = 'libgjsifysabnative.dylib'
+else
+    shared_lib_name = 'libgjsifysabnative.so'
+endif
 
 libGjsifySabNative = library('gjsifysabnative', sources,
     dependencies: vala_deps,
@@ -46,7 +67,7 @@ g_ir_compiler = find_program('g-ir-compiler')
 custom_target(meson.project_name() + '-1.0.typelib',
     command: [
         g_ir_compiler,
-        '--shared-library', 'libgjsifysabnative.so',
+        '--shared-library', shared_lib_name,
         '--output', '@OUTPUT@',
         meson.current_build_dir() / meson.project_name() + '-1.0.gir',
     ],

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/sab-native",
-    "version": "0.51.1",
+    "version": "0.53.0",
     "description": "Optional Vala/GObject bridge providing cross-process shared memory + atomics for @gjsify/worker_threads. Wraps Linux memfd_create(2) + mmap(MAP_SHARED) to back JS-visible SharedBuffer regions whose fds can be passed to child workers via SCM_RIGHTS over a Unix-domain socket; exposes typed accessors (getInt32LE / setUint8 / etc.) plus atomics built on __atomic_* GCC builtins and SYS_futex for wait/notify. Workaround for the stock-GJS gap where SharedArrayBuffer is unavailable (Mozilla disables the SAB constructor without COOP/COEP opts) and SAB cannot share backing stores across Gio.Subprocess workers anyway.",
     "type": "module",
     "main": "lib/esm/index.js",
@@ -25,7 +25,9 @@
             "linux-arm64-musl",
             "linux-ppc64",
             "linux-s390x",
-            "linux-riscv64"
+            "linux-riscv64",
+            "darwin-arm64",
+            "darwin-x64"
         ],
         "runtimes": {
             "gjs": "polyfill",
@@ -64,14 +66,15 @@
         "native"
     ],
     "dependencies": {
-        "@girs/gjs": "5.0.0",
-        "@girs/glib-2.0": "5.0.0",
-        "@girs/gobject-2.0": "5.0.0",
-        "@girs/gio-2.0": "5.0.0"
+        "@girs/gjs": "5.4.0",
+        "@girs/glib-2.0": "5.4.0",
+        "@girs/gobject-2.0": "5.4.0",
+        "@girs/gio-2.0": "5.4.0",
+        "@gjsify/utils": "^0.53.0"
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.51.1",
-        "@gjsify/unit": "^0.51.1",
+        "@gjsify/cli": "^0.53.0",
+        "@gjsify/unit": "^0.53.0",
         "@ts-for-gir/cli": "^4.1.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
@@ -87,12 +90,14 @@
     },
     "homepage": "https://github.com/gjsify/gjsify/tree/main/packages/node/sab-native#readme",
     "optionalDependencies": {
-        "@gjsify/sab-native-linux-arm64": "0.51.1",
-        "@gjsify/sab-native-linux-arm64-musl": "0.51.1",
-        "@gjsify/sab-native-linux-ppc64": "0.51.1",
-        "@gjsify/sab-native-linux-riscv64": "0.51.1",
-        "@gjsify/sab-native-linux-s390x": "0.51.1",
-        "@gjsify/sab-native-linux-x64": "0.51.1",
-        "@gjsify/sab-native-linux-x64-musl": "0.51.1"
+        "@gjsify/sab-native-darwin-arm64": "0.53.0",
+        "@gjsify/sab-native-darwin-x64": "0.53.0",
+        "@gjsify/sab-native-linux-arm64": "0.53.0",
+        "@gjsify/sab-native-linux-arm64-musl": "0.53.0",
+        "@gjsify/sab-native-linux-ppc64": "0.53.0",
+        "@gjsify/sab-native-linux-riscv64": "0.53.0",
+        "@gjsify/sab-native-linux-s390x": "0.53.0",
+        "@gjsify/sab-native-linux-x64": "0.53.0",
+        "@gjsify/sab-native-linux-x64-musl": "0.53.0"
     }
 }

package/src/vala/sab-helpers.c

@@ -1,8 +1,16 @@
 /*
  * sab-helpers.c — see sab-helpers.h for the contract.
  *
- * Linux-only. Compile with -D_GNU_SOURCE so memfd_create, MFD_CLOEXEC,
- * and the FUTEX_*_PRIVATE constants are visible.
+ * Two backends behind one contract (ADR 0013 §1: the seam is this shim, not
+ * the primitive — every platform supplies an ADDRESS-KEYED compare-and-wait):
+ *
+ *   Linux  — memfd_create + non-private SYS_futex + SOCK_SEQPACKET. Compile
+ *            with -D_GNU_SOURCE so memfd_create, MFD_CLOEXEC and the FUTEX_*
+ *            constants are visible.
+ *   darwin — shm_open + immediate shm_unlink, os_sync_wait_on_address with
+ *            the _SHARED flag (macOS 14.4+), SOCK_STREAM with fixed 4-byte
+ *            frames. Every darwin difference is marked `#if defined(__APPLE__)`
+ *            at the point it applies, with the measured reason next to it.
  *
  * ONE ARTIFACT MUST SERVE BOTH LIBCS — no glibc-private symbols.
  *
@@ -37,19 +45,82 @@
 
 #include <errno.h>
 #include <fcntl.h>
-#include <linux/futex.h>
 #include <stdatomic.h>
 #include <stdint.h>
 #include <string.h>
 #include <sys/mman.h>
 #include <sys/socket.h>
-#include <sys/syscall.h>
 #include <sys/time.h>
 #include <sys/types.h>
 #include <sys/un.h>
 #include <time.h>
 #include <unistd.h>
 
+#if defined(__APPLE__)
+#  include <os/clock.h>
+#  include <os/os_sync_wait_on_address.h>
+#  include <sys/stat.h>
+#else
+#  include <linux/futex.h>
+#  include <sys/syscall.h>
+#endif
+
+#if defined(__APPLE__)
+
+/* ── darwin: anonymous shared memory ────────────────────────────────────
+ *
+ * Darwin has neither memfd_create nor FreeBSD's SHM_ANON, so the closest
+ * equivalent of an anonymous memfd is a POSIX shm object that is unlinked
+ * the moment it exists: the fd stays valid, mmap/SCM_RIGHTS work on it as on
+ * any descriptor, and the object dies with its last reference (ADR 0013 §3).
+ *
+ * The name is visible in a global namespace only between shm_open and
+ * shm_unlink; a crash inside that window leaks one object until reboot —
+ * the documented difference from the Linux backend. PSHMNAMLEN caps names at
+ * 31 bytes, hence a short random name rather than a descriptive one, and
+ * O_EXCL + retry so two processes can never open each other's region. */
+static int
+gjsify_shm_anonymous (void)
+{
+  for (int attempt = 0; attempt < 16; attempt++) {
+    char name[32];
+    g_snprintf (name, sizeof name, "/gsab.%x.%08x",
+                (unsigned) getpid (), (unsigned) g_random_int ());
+    /* POSIX sets FD_CLOEXEC on a shm_open descriptor. */
+    int fd = shm_open (name, O_CREAT | O_EXCL | O_RDWR, 0600);
+    if (fd >= 0) {
+      shm_unlink (name);
+      return fd;
+    }
+    if (errno != EEXIST) return -1;
+  }
+  errno = EEXIST;
+  return -1;
+}
+
+/* Plain fcntl: darwin has no LFS redirect (the musl concern below is a
+ * Linux one), and syscall(2) is deprecated there. */
+static int
+gjsify_dup_cloexec (int fd)
+{
+  return fcntl (fd, F_DUPFD_CLOEXEC, 0);
+}
+
+/* Darwin's CMSG_* macros align to 4 bytes (__DARWIN_ALIGN32) and it defines
+ * no CMSG_ALIGN, so the size_t-aligned fallback the Linux path carries would
+ * compute the WRONG next header here. There is no second libc to stay
+ * compatible with on darwin, so the system macro is the correct one. */
+#define gjsify_cmsg_nxthdr(msg, cmsg) CMSG_NXTHDR ((msg), (cmsg))
+
+static gboolean
+gjsify_set_cloexec (int fd)
+{
+  int flags = fcntl (fd, F_GETFD);
+  return flags >= 0 && fcntl (fd, F_SETFD, flags | FD_CLOEXEC) == 0;
+}
+
+#else /* Linux */
+
 /* glibc < 2.27 doesn't expose memfd_create() as a libc wrapper. We use the
  * raw syscall to stay portable across the prebuild distro matrix. */
 #ifndef MFD_CLOEXEC
@@ -97,6 +168,8 @@ gjsify_cmsg_nxthdr (const struct msghdr *msg, struct cmsghdr *cmsg)
   return (struct cmsghdr *) next;
 }
 
+#endif /* __APPLE__ */
+
 /* ────────────────────────────────────────────────────────────────────── *
  * GjsifySabRegion: opaque shared-memory region
  * ────────────────────────────────────────────────────────────────────── */
@@ -139,7 +212,11 @@ gjsify_sab_region_new_anonymous (gsize size)
 {
   if (size == 0) { errno = EINVAL; return NULL; }
 
+#if defined(__APPLE__)
+  int fd = gjsify_shm_anonymous ();
+#else
   int fd = gjsify_memfd_create ("gjsify-sab", MFD_CLOEXEC);
+#endif
   if (fd < 0) return NULL;
 
   if (ftruncate (fd, (off_t) size) < 0) {
@@ -378,6 +455,39 @@ gjsify_sab_region_futex_wait (GjsifySabRegion *region,
   BOUNDS_CHECK (region, offset, 4);
   int32_t *addr = (int32_t *) ((guint8 *) region->ptr + offset);
 
+#if defined(__APPLE__)
+  /* os_sync_wait_on_address reports "value differed" as SUCCESS, exactly
+   * like a wake, so the not-equal answer has to come from our own compare.
+   * The window between this load and the kernel's compare only ever turns
+   * a would-be 'not-equal' into 'ok' — indistinguishable from a notify that
+   * landed just after we slept, which Atomics.wait already permits. */
+  if (__atomic_load_n (addr, __ATOMIC_SEQ_CST) != expected) return -1;
+  /* A zero timeout is EINVAL to the timed variant, and a 0 ms wait on a
+   * matching value is by definition an immediate time-out. */
+  if (timeout_ms == 0) return -2;
+
+  /* _SHARED is the darwin spelling of Linux's non-private FUTEX_WAIT: the
+   * address lives in a region other processes map at other addresses, and
+   * the wake may come from one of them. */
+  int ret;
+  if (timeout_ms < 0) {
+    ret = os_sync_wait_on_address (addr, (uint64_t) (uint32_t) expected, 4,
+                                   OS_SYNC_WAIT_ON_ADDRESS_SHARED);
+  } else {
+    ret = os_sync_wait_on_address_with_timeout (addr, (uint64_t) (uint32_t) expected, 4,
+                                                OS_SYNC_WAIT_ON_ADDRESS_SHARED,
+                                                OS_CLOCK_MACH_ABSOLUTE_TIME,
+                                                (uint64_t) timeout_ms * 1000000ULL);
+  }
+  if (ret >= 0) return 0;
+  int e = errno;
+  if (e == ETIMEDOUT) return -2;
+  /* Apple documents EFAULT and ENOMEM as TRANSIENT early returns the caller
+   * should retry after re-reading the value (the address itself is already
+   * bounds-checked) — the same contract as EINTR. */
+  if (e == EINTR || e == EFAULT || e == ENOMEM) return -3;
+  return -e;
+#else
   struct timespec ts;
   struct timespec *ts_ptr = NULL;
   if (timeout_ms >= 0) {
@@ -399,6 +509,7 @@ gjsify_sab_region_futex_wait (GjsifySabRegion *region,
   if (e == ETIMEDOUT) return -2;
   if (e == EINTR)     return -3;
   return -e;
+#endif
 }
 
 gint
@@ -408,9 +519,25 @@ gjsify_sab_region_futex_wake (GjsifySabRegion *region,
 {
   BOUNDS_CHECK (region, offset, 4);
   int32_t *addr = (int32_t *) ((guint8 *) region->ptr + offset);
+#if defined(__APPLE__)
+  /* FUTEX_WAKE returns how many it woke; os_sync_wake_by_address_all does
+   * not, and notify32's return value is that count. So wake one at a time:
+   * each successful _any wakes exactly one waiter, and ENOENT means none is
+   * left — which also makes `count` a real upper bound, as on Linux. */
+  gint woken = 0;
+  while (woken < count) {
+    if (os_sync_wake_by_address_any (addr, 4, OS_SYNC_WAKE_BY_ADDRESS_SHARED) != 0) {
+      if (errno == ENOENT) break;
+      return woken > 0 ? woken : -errno;
+    }
+    woken++;
+  }
+  return woken;
+#else
   long ret = syscall (SYS_futex, addr, FUTEX_WAKE, count,
                       NULL, NULL, 0);
   return (gint) ret;
+#endif
 }
 
 /* ────────────────────────────────────────────────────────────────────── *
@@ -421,9 +548,35 @@ gboolean
 gjsify_sab_socketpair (gint *parent_fd, gint *child_fd)
 {
   int sv[2];
+#if defined(__APPLE__)
+  /* Measured on macOS 27: socketpair(AF_UNIX, SOCK_SEQPACKET) fails with
+   * EPROTONOSUPPORT, and SOCK_CLOEXEC does not exist. SOCK_DGRAM keeps
+   * message boundaries but reports a closed peer as ECONNRESET once and then
+   * blocks forever, losing recv_fd's "0 = orderly EOF". SOCK_STREAM keeps the
+   * EOF, and the boundaries come back by framing: every message is exactly
+   * one 4-byte tag carrying one SCM_RIGHTS fd, and recv reads exactly 4. */
+  if (socketpair (AF_UNIX, SOCK_STREAM, 0, sv) < 0) {
+    return FALSE;
+  }
+  /* Not atomic with creation as SOCK_CLOEXEC is: a fork() on another thread
+   * in between would leak the pair into that child. Nothing forks
+   * concurrently with FdChannel.make_pair in a GJS process. */
+  for (int i = 0; i < 2; i++) {
+    int one = 1;
+    if (!gjsify_set_cloexec (sv[i])
+        || setsockopt (sv[i], SOL_SOCKET, SO_NOSIGPIPE, &one, sizeof one) < 0) {
+      int e = errno;
+      close (sv[0]);
+      close (sv[1]);
+      errno = e;
+      return FALSE;
+    }
+  }
+#else
   if (socketpair (AF_UNIX, SOCK_SEQPACKET | SOCK_CLOEXEC, 0, sv) < 0) {
     return FALSE;
   }
+#endif
   *parent_fd = sv[0];
   *child_fd  = sv[1];
   return TRUE;
@@ -462,6 +615,17 @@ gjsify_sab_send_fd (gint socket_fd, gint fd_to_send, guint32 tag)
   do {
     n = sendmsg (socket_fd, &msg, MSG_NOSIGNAL);
   } while (n < 0 && errno == EINTR);
+#if defined(__APPLE__)
+  /* SOCK_STREAM (see gjsify_sab_socketpair) may accept a frame short; the
+   * receiver reads exactly four bytes per frame, so a missing tail would shift
+   * every later tag. The fd already travelled with the first byte. */
+  while (n >= 0 && (size_t) n < sizeof tag_be) {
+    ssize_t m = send (socket_fd, (guint8 *) &tag_be + n, sizeof tag_be - (size_t) n, 0);
+    if (m < 0 && errno == EINTR) continue;
+    if (m < 0) return FALSE;
+    n += m;
+  }
+#endif
   return n >= 0;
 }
 
@@ -488,13 +652,45 @@ gjsify_sab_recv_fd (gint socket_fd, guint32 *tag)
   msg.msg_controllen = sizeof cmsg_buf.buf;
 
   ssize_t n;
+#if defined(__APPLE__)
+  /* No MSG_CMSG_CLOEXEC on darwin — the received fd gets FD_CLOEXEC below. */
+  do {
+    n = recvmsg (socket_fd, &msg, 0);
+  } while (n < 0 && errno == EINTR);
+#else
   do {
     n = recvmsg (socket_fd, &msg, MSG_CMSG_CLOEXEC);
   } while (n < 0 && errno == EINTR);
+#endif
 
   if (n == 0) return 0;       /* orderly EOF */
   if (n < 0)  return -1;      /* error — errno preserved */
 
+#if defined(__APPLE__)
+  /* SOCK_STREAM (see gjsify_sab_socketpair): a frame may in principle arrive
+   * short. The fd rides on the frame's first byte, so it is already in the
+   * control buffer; only the rest of the tag is still to read. */
+  while ((size_t) n < sizeof tag_be) {
+    ssize_t m = recv (socket_fd, (guint8 *) &tag_be + n, sizeof tag_be - (size_t) n, 0);
+    if (m < 0 && errno == EINTR) continue;
+    if (m <= 0) {
+      int e = m == 0 ? EBADMSG : errno;
+      /* The frame's fd was already installed in this process by the first
+       * recvmsg; the caller never sees it on this path, so close it here. */
+      for (struct cmsghdr *cm = CMSG_FIRSTHDR (&msg); cm != NULL; cm = gjsify_cmsg_nxthdr (&msg, cm)) {
+        if (cm->cmsg_level == SOL_SOCKET && cm->cmsg_type == SCM_RIGHTS) {
+          int fd;
+          memcpy (&fd, CMSG_DATA (cm), sizeof (int));
+          close (fd);
+        }
+      }
+      errno = e;
+      return -1;
+    }
+    n += m;
+  }
+#endif
+
   *tag = GUINT32_FROM_BE (tag_be);
 
   /* Extract the fd from the control message. */
@@ -502,6 +698,9 @@ gjsify_sab_recv_fd (gint socket_fd, guint32 *tag)
     if (cm->cmsg_level == SOL_SOCKET && cm->cmsg_type == SCM_RIGHTS) {
       int fd;
       memcpy (&fd, CMSG_DATA (cm), sizeof (int));
+#if defined(__APPLE__)
+      gjsify_set_cloexec (fd);
+#endif
       return fd;
     }
   }

package/src/vala/sab-helpers.h

@@ -1,12 +1,13 @@
 /*
- * Tiny C shim around Linux shared-memory + atomics primitives that Vala
- * can't express cleanly:
+ * Tiny C shim around the shared-memory + atomics primitives that Vala
+ * can't express cleanly (Linux first, darwin in brackets — the per-platform
+ * reasons live in sab-helpers.c):
  *
- *   - memfd_create(2)         — anonymous shared-memory fd (no path needed)
+ *   - memfd_create(2) [shm_open + shm_unlink] — anonymous shared-memory fd
  *   - mmap(2) / munmap(2)     — MAP_SHARED region creation
- *   - SYS_futex (FUTEX_WAIT_PRIVATE / FUTEX_WAKE_PRIVATE) — wait/notify
+ *   - SYS_futex, non-private [os_sync_wait_on_address, _SHARED] — wait/notify
  *   - __atomic_* GCC builtins — load/store/add/cmpxchg with SEQ_CST
- *   - socketpair(AF_UNIX, SOCK_SEQPACKET) — IPC side-channel for fd-passing
+ *   - socketpair(AF_UNIX, SOCK_SEQPACKET [SOCK_STREAM]) — fd-passing channel
  *   - sendmsg/recvmsg + SCM_RIGHTS — cross-process fd transfer
  *
  * Same design as @gjsify/http2-native: opaque struct (full definition in .c),
@@ -99,7 +100,7 @@ gint32   gjsify_sab_region_atomic_xchg_i32    (GjsifySabRegion *region, gsize of
 gboolean gjsify_sab_region_atomic_cmpxchg_i32 (GjsifySabRegion *region, gsize offset, gint32 *expected, gint32 desired);
 
 /* ────────────────────────────────────────────────────────────────────── *
- * Futex wait / wake (Linux SYS_futex, FUTEX_*_PRIVATE flavour)
+ * Futex wait / wake (Linux non-private SYS_futex; darwin os_sync _SHARED)
  * ────────────────────────────────────────────────────────────────────── *
  *
  * `futex_wait`:

package/src/vala/shared-buffer.vala

@@ -23,7 +23,8 @@
  * ───────
  * `atomic_*_i32` family operates with SEQ_CST memory ordering via GCC
  * `__atomic_*` builtins. `futex_wait` / `futex_wake` give cross-process
- * wait/notify via Linux SYS_futex (FUTEX_*_PRIVATE flavour).
+ * wait/notify: Linux SYS_futex (the NON-private flavour) and, on macOS,
+ * os_sync_wait_on_address with the _SHARED flag — see sab-helpers.c.
  *
  * Buffer ownership: read_bytes returns a GLib.Bytes that borrows the
  * mmap'd memory (no copy) and ref-counts the region so the mapping
@@ -173,7 +174,7 @@ namespace GjsifySabNative {
         }
 
         /**
-         * Linux futex_wait. Compares *((int32_t*)region+offset) to @expected;
+         * Address-keyed wait (futex on Linux, os_sync on macOS). Compares *((int32_t*)region+offset) to @expected;
          * if equal, blocks until woken or timeout. timeout_ms < 0 = infinite.
          *
          * Return: 0 woken, -1 not-equal (EAGAIN), -2 timed-out, -3 interrupted,