@aztec/ipc-runtime 0.0.1-commit.4da4de7

package/dest/index.d.ts

@@ -0,0 +1,5 @@
+export type { IpcClientAsync, IpcClientSync } from "./types.js";
+export { UdsIpcClient, type UdsIpcClientConnectOptions } from "./uds_client.js";
+export { UdsIpcServer, type IpcServerHandler } from "./uds_server.js";
+export { NapiShmSyncClient, NapiShmAsyncClient, createNapiShmSyncClient, createNapiShmAsyncClient, type NapiMsgpackClientSync, type NapiMsgpackClientAsync, } from "./shm_client.js";
+export { findIpcRuntimeNapi, loadIpcRuntimeNapi, type Platform, } from "./native_loader.js";

package/dest/index.js

@@ -0,0 +1,4 @@
+export { UdsIpcClient } from "./uds_client.js";
+export { UdsIpcServer } from "./uds_server.js";
+export { NapiShmSyncClient, NapiShmAsyncClient, createNapiShmSyncClient, createNapiShmAsyncClient, } from "./shm_client.js";
+export { findIpcRuntimeNapi, loadIpcRuntimeNapi, } from "./native_loader.js";

package/dest/native_loader.d.ts

@@ -0,0 +1,16 @@
+export type Platform = "x86_64-linux" | "x86_64-darwin" | "aarch64-linux" | "aarch64-darwin";
+/**
+ * Resolve the path of `ipc_runtime_napi.node` for the current platform.
+ * Returns null if either the platform is unsupported or the artifact is
+ * absent (typical reason: ipc-runtime/bootstrap.sh hasn't run yet).
+ */
+export declare function findIpcRuntimeNapi(customPath?: string): string | null;
+/**
+ * Load `ipc_runtime_napi.node` and return its native exports
+ * (`MsgpackClient`, `MsgpackClientAsync`). Throws a descriptive error when
+ * the addon cannot be located or fails to dlopen.
+ */
+export declare function loadIpcRuntimeNapi(customPath?: string): {
+    MsgpackClient: new (shmName: string, clientId?: number) => any;
+    MsgpackClientAsync: new (shmName: string, clientId?: number) => any;
+};

package/dest/native_loader.js

@@ -0,0 +1,81 @@
+// Locate the prebuilt ipc_runtime_napi.node addon shipped with this package.
+//
+// The addon is built by `ipc-runtime/bootstrap.sh` (CMake target
+// `ipc_runtime_napi`) and copied into `build/<arch>-<os>/` next to this
+// package's `package.json`. Resolution walks up from this file's URL to the
+// first `package.json` adjacent to a `build/` directory — that's the
+// package root in both `file:`-linked and published consumption.
+import { createRequire } from "node:module";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+const PLATFORM_TO_BUILD_DIR = {
+    "x86_64-linux": "amd64-linux",
+    "x86_64-darwin": "amd64-macos",
+    "aarch64-linux": "arm64-linux",
+    "aarch64-darwin": "arm64-macos",
+};
+function detectPlatform() {
+    const arch = process.arch;
+    const platform = process.platform;
+    if (arch === "x64" && platform === "linux")
+        return "x86_64-linux";
+    if (arch === "x64" && platform === "darwin")
+        return "x86_64-darwin";
+    if (arch === "arm64" && platform === "linux")
+        return "aarch64-linux";
+    if (arch === "arm64" && platform === "darwin")
+        return "aarch64-darwin";
+    return null;
+}
+function findPackageRoot() {
+    // `import.meta.url` after tsc compile points at the .js file under
+    // <pkg>/dest/...; climb until we find package.json with a sibling build/.
+    let currentDir = path.dirname(fileURLToPath(import.meta.url));
+    const root = path.parse(currentDir).root;
+    while (currentDir !== root) {
+        const packageJsonPath = path.join(currentDir, "package.json");
+        if (fs.existsSync(packageJsonPath)) {
+            const buildDir = path.join(currentDir, "build");
+            if (fs.existsSync(buildDir)) {
+                return currentDir;
+            }
+        }
+        currentDir = path.dirname(currentDir);
+    }
+    return null;
+}
+/**
+ * Resolve the path of `ipc_runtime_napi.node` for the current platform.
+ * Returns null if either the platform is unsupported or the artifact is
+ * absent (typical reason: ipc-runtime/bootstrap.sh hasn't run yet).
+ */
+export function findIpcRuntimeNapi(customPath) {
+    if (customPath) {
+        return fs.existsSync(customPath) ? path.resolve(customPath) : null;
+    }
+    const platform = detectPlatform();
+    if (!platform)
+        return null;
+    const packageRoot = findPackageRoot();
+    if (!packageRoot)
+        return null;
+    const buildDir = PLATFORM_TO_BUILD_DIR[platform];
+    const candidate = path.join(packageRoot, "build", buildDir, "ipc_runtime_napi.node");
+    return fs.existsSync(candidate) ? candidate : null;
+}
+/**
+ * Load `ipc_runtime_napi.node` and return its native exports
+ * (`MsgpackClient`, `MsgpackClientAsync`). Throws a descriptive error when
+ * the addon cannot be located or fails to dlopen.
+ */
+export function loadIpcRuntimeNapi(customPath) {
+    const addonPath = findIpcRuntimeNapi(customPath);
+    if (!addonPath) {
+        throw new Error("Could not locate ipc_runtime_napi.node. Build with `ipc-runtime/bootstrap.sh` " +
+            "or set the optional `customPath` argument to point at a prebuilt addon.");
+    }
+    // createRequire so this works in both ESM and CJS callers.
+    const require = createRequire(import.meta.url);
+    return require(addonPath);
+}

package/dest/shm_client.d.ts

@@ -0,0 +1,65 @@
+import { IpcClientAsync, IpcClientSync } from "./types.js";
+/**
+ * Minimum surface a NAPI msgpack client must expose. Satisfied by the
+ * `MsgpackClient` / `MsgpackClientAsync` classes exported from this
+ * package's own `ipc_runtime_napi.node` addon (see ipc-runtime/cpp/napi/),
+ * which wraps the C++ ipc::IpcClient.
+ *
+ * The interface is exposed for tests / consumers that want to inject a
+ * mock or alternative implementation; the standard production path is the
+ * `createNapiShm{Sync,Async}Client` factories below, which load the
+ * prebuilt addon shipped in this package's `build/<arch>-<os>/` directory.
+ *
+ * Note on the async contract: `MsgpackClientAsync.call` is *fire and
+ * forget*. Responses arrive via `setResponseCallback` in FIFO order on a
+ * background-thread → main-thread bridge (Napi::ThreadSafeFunction).
+ * The TS wrapper below owns the request queue and matches responses.
+ */
+export interface NapiMsgpackClientSync {
+    call(input: Buffer): Buffer;
+    close(): void;
+}
+export interface NapiMsgpackClientAsync {
+    setResponseCallback(cb: (response: Buffer) => void): void;
+    call(input: Buffer): void;
+    acquire(): void;
+    release(): void;
+}
+/** Wraps a sync NAPI msgpack client behind the IpcClientSync interface. */
+export declare class NapiShmSyncClient implements IpcClientSync {
+    private inner;
+    constructor(inner: NapiMsgpackClientSync);
+    call(input: Uint8Array): Uint8Array;
+    destroy(): void;
+}
+/**
+ * Wraps the fire-and-forget async NAPI msgpack client behind the
+ * `IpcClientAsync` interface. Owns a FIFO queue of pending calls; the C++
+ * background polling thread invokes `setResponseCallback` once per
+ * response, and this wrapper matches it to the next queued caller.
+ *
+ * `acquire` / `release` are reference-count hooks the NAPI exposes so the
+ * libuv loop is kept alive only while requests are outstanding — without
+ * them a `node script.js` would never exit naturally.
+ */
+export declare class NapiShmAsyncClient implements IpcClientAsync {
+    private inner;
+    private readonly pending;
+    constructor(inner: NapiMsgpackClientAsync);
+    call(input: Uint8Array): Promise<Uint8Array>;
+    destroy(): Promise<void>;
+}
+export interface CreateNapiShmOptions {
+    /** MPSC client slot id (default 0). Distinct clients on the same shmName must use distinct slots. */
+    clientId?: number;
+    /** Override addon path lookup. Rarely needed; useful for tests / unusual deployments. */
+    customAddonPath?: string;
+}
+/**
+ * Factories that load the bundled `ipc_runtime_napi.node` addon and
+ * construct an MPSC-SHM client wrapped behind the `IpcClient*` interface.
+ * Matches the transport used by `ipc::make_server` on the C++ side, so any
+ * server started via that helper accepts these clients directly.
+ */
+export declare function createNapiShmSyncClient(shmName: string, options?: CreateNapiShmOptions): NapiShmSyncClient;
+export declare function createNapiShmAsyncClient(shmName: string, options?: CreateNapiShmOptions): NapiShmAsyncClient;

package/dest/shm_client.js

@@ -0,0 +1,93 @@
+import { loadIpcRuntimeNapi } from "./native_loader.js";
+/** Wraps a sync NAPI msgpack client behind the IpcClientSync interface. */
+export class NapiShmSyncClient {
+    inner;
+    constructor(inner) {
+        this.inner = inner;
+    }
+    call(input) {
+        const buf = Buffer.isBuffer(input)
+            ? input
+            : Buffer.from(input.buffer, input.byteOffset, input.byteLength);
+        const resp = this.inner.call(buf);
+        return new Uint8Array(resp.buffer, resp.byteOffset, resp.byteLength);
+    }
+    destroy() {
+        this.inner.close();
+    }
+}
+/**
+ * Wraps the fire-and-forget async NAPI msgpack client behind the
+ * `IpcClientAsync` interface. Owns a FIFO queue of pending calls; the C++
+ * background polling thread invokes `setResponseCallback` once per
+ * response, and this wrapper matches it to the next queued caller.
+ *
+ * `acquire` / `release` are reference-count hooks the NAPI exposes so the
+ * libuv loop is kept alive only while requests are outstanding — without
+ * them a `node script.js` would never exit naturally.
+ */
+export class NapiShmAsyncClient {
+    inner;
+    pending = [];
+    constructor(inner) {
+        this.inner = inner;
+        this.inner.setResponseCallback((response) => {
+            const cb = this.pending.shift();
+            if (cb) {
+                cb.resolve(new Uint8Array(response));
+            }
+            else {
+                // Unexpected — a response arrived but no caller is waiting.
+                // Drop it; there is no caller left to resolve.
+            }
+            if (this.pending.length === 0) {
+                this.inner.release();
+            }
+        });
+    }
+    call(input) {
+        const buf = Buffer.isBuffer(input)
+            ? input
+            : Buffer.from(input.buffer, input.byteOffset, input.byteLength);
+        return new Promise((resolve, reject) => {
+            if (this.pending.length === 0) {
+                this.inner.acquire();
+            }
+            this.pending.push({ resolve, reject });
+            try {
+                this.inner.call(buf);
+            }
+            catch (err) {
+                // Send failed — unwind the queue entry we just added.
+                this.pending.pop();
+                if (this.pending.length === 0) {
+                    this.inner.release();
+                }
+                reject(err instanceof Error
+                    ? err
+                    : new Error(`SHM async call failed: ${String(err)}`));
+            }
+        });
+    }
+    async destroy() {
+        // Reject anything still in flight.
+        while (this.pending.length > 0) {
+            const cb = this.pending.shift();
+            cb?.reject(new Error("ipc-runtime SHM client destroyed before response"));
+        }
+    }
+}
+/**
+ * Factories that load the bundled `ipc_runtime_napi.node` addon and
+ * construct an MPSC-SHM client wrapped behind the `IpcClient*` interface.
+ * Matches the transport used by `ipc::make_server` on the C++ side, so any
+ * server started via that helper accepts these clients directly.
+ */
+export function createNapiShmSyncClient(shmName, options = {}) {
+    const napi = loadIpcRuntimeNapi(options.customAddonPath);
+    return new NapiShmSyncClient(new napi.MsgpackClient(shmName, options.clientId ?? 0));
+}
+export function createNapiShmAsyncClient(shmName, options = {}) {
+    const napi = loadIpcRuntimeNapi(options.customAddonPath);
+    return new NapiShmAsyncClient(new napi.MsgpackClientAsync(shmName, options.clientId ?? 0));
+}

package/dest/types.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Minimal byte-in / byte-out interface that the ipc-codegen-emitted
+ * <Service>Api types consume. Both UDS and SHM transports satisfy this.
+ */
+export interface IpcClientAsync {
+    call(input: Uint8Array): Promise<Uint8Array>;
+    destroy(): Promise<void>;
+}
+export interface IpcClientSync {
+    call(input: Uint8Array): Uint8Array;
+    destroy(): void;
+}

package/dest/types.js

@@ -0,0 +1 @@
+export {};

package/dest/uds_client.d.ts

@@ -0,0 +1,37 @@
+import * as net from "node:net";
+import { IpcClientAsync } from "./types.js";
+export interface UdsIpcClientConnectOptions {
+    /** Mark the socket as unref'd so it doesn't keep the Node event loop alive when idle. */
+    unref?: boolean;
+    /**
+     * Retry budget (ms) for the initial connect when the server has bound the
+     * path but not yet called listen(). Set to 0 to fail immediately on
+     * ECONNREFUSED. Default 5000.
+     */
+    connectTimeoutMs?: number;
+}
+/**
+ * Async IPC client over a Unix Domain Socket. Wire format matches the C++
+ * ipc::IpcServer/IpcClient socket transport: 4-byte little-endian length
+ * prefix followed by `length` bytes of msgpack payload, per direction.
+ *
+ * Supports pipelining: multiple concurrent `call()` invocations are queued
+ * FIFO and matched with responses in order. Pipelining keeps the server-side
+ * socket window full and matches the native client behaviour.
+ */
+export declare class UdsIpcClient implements IpcClientAsync {
+    private conn;
+    private buffer;
+    private pending;
+    private destroyed;
+    private constructor();
+    static connect(socketPath: string, opts?: UdsIpcClientConnectOptions): Promise<UdsIpcClient>;
+    /** Number of in-flight calls awaiting a response. */
+    get inflight(): number;
+    /** Underlying socket — exposed for ref/unref control (event-loop tuning). */
+    get socket(): net.Socket;
+    call(input: Uint8Array): Promise<Uint8Array>;
+    destroy(): Promise<void>;
+    private onData;
+    private failAll;
+}

package/dest/uds_client.js

@@ -0,0 +1,120 @@
+import * as net from "node:net";
+/**
+ * Async IPC client over a Unix Domain Socket. Wire format matches the C++
+ * ipc::IpcServer/IpcClient socket transport: 4-byte little-endian length
+ * prefix followed by `length` bytes of msgpack payload, per direction.
+ *
+ * Supports pipelining: multiple concurrent `call()` invocations are queued
+ * FIFO and matched with responses in order. Pipelining keeps the server-side
+ * socket window full and matches the native client behaviour.
+ */
+export class UdsIpcClient {
+    conn;
+    buffer = Buffer.alloc(0);
+    pending = [];
+    destroyed = false;
+    constructor(conn) {
+        this.conn = conn;
+        conn.on("data", (chunk) => this.onData(chunk));
+        conn.on("error", (err) => this.failAll(err));
+        conn.on("close", () => this.failAll(new Error("socket closed")));
+    }
+    static async connect(socketPath, opts) {
+        const conn = await connectWithRetry(socketPath, opts?.connectTimeoutMs ?? 5000);
+        conn.setNoDelay(true);
+        if (opts?.unref)
+            conn.unref();
+        return new UdsIpcClient(conn);
+    }
+    /** Number of in-flight calls awaiting a response. */
+    get inflight() {
+        return this.pending.length;
+    }
+    /** Underlying socket — exposed for ref/unref control (event-loop tuning). */
+    get socket() {
+        return this.conn;
+    }
+    async call(input) {
+        if (this.destroyed) {
+            throw new Error("UdsIpcClient: call() after destroy()");
+        }
+        return new Promise((resolve, reject) => {
+            this.pending.push({ resolve, reject });
+            const lenBuf = Buffer.allocUnsafe(4);
+            lenBuf.writeUInt32LE(input.length, 0);
+            this.conn.write(lenBuf);
+            this.conn.write(input);
+        });
+    }
+    async destroy() {
+        this.destroyed = true;
+        this.conn.removeAllListeners();
+        this.conn.destroy();
+        this.failAll(new Error("UdsIpcClient destroyed"));
+    }
+    onData(chunk) {
+        this.buffer =
+            this.buffer.length === 0
+                ? Buffer.from(chunk)
+                : Buffer.concat([this.buffer, chunk]);
+        while (this.buffer.length >= 4) {
+            const len = this.buffer.readUInt32LE(0);
+            if (this.buffer.length < 4 + len)
+                return;
+            const payload = this.buffer.subarray(4, 4 + len);
+            this.buffer = this.buffer.subarray(4 + len);
+            const next = this.pending.shift();
+            if (next)
+                next.resolve(new Uint8Array(payload));
+        }
+    }
+    failAll(err) {
+        const pending = this.pending;
+        this.pending = [];
+        for (const p of pending)
+            p.reject(err);
+    }
+}
+/**
+ * Connect to `socketPath`, retrying on ECONNREFUSED until `timeoutMs`
+ * elapses. ECONNREFUSED happens in the narrow window between the server's
+ * bind() and listen(); other errors fail immediately.
+ */
+async function connectWithRetry(socketPath, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    let attempt = 0;
+    let lastErr;
+    while (true) {
+        try {
+            return await attemptConnect(socketPath);
+        }
+        catch (err) {
+            lastErr = err;
+            const code = err.code;
+            if (code !== "ECONNREFUSED" && code !== "ENOENT") {
+                throw new Error(`UdsIpcClient: connect failed: ${lastErr.message}`);
+            }
+            if (Date.now() >= deadline) {
+                throw new Error(`UdsIpcClient: connect timed out: ${lastErr.message}`);
+            }
+            const delay = Math.min(50, 5 * 2 ** attempt++);
+            await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+    }
+}
+function attemptConnect(socketPath) {
+    return new Promise((resolve, reject) => {
+        const conn = net.createConnection(socketPath);
+        const onError = (err) => {
+            conn.removeListener("connect", onConnect);
+            conn.destroy();
+            reject(err);
+        };
+        const onConnect = () => {
+            conn.removeListener("error", onError);
+            resolve(conn);
+        };
+        conn.once("connect", onConnect);
+        conn.once("error", onError);
+    });
+}

package/dest/uds_server.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Handler signature mirrors the C++ ipc::IpcServer::Handler: receive raw
+ * bytes, return raw bytes. msgpack decode/encode and command dispatch are
+ * the caller's responsibility (or the codegen's, when a generated dispatcher
+ * is wired in).
+ */
+export type IpcServerHandler = (clientId: number, request: Uint8Array) => Promise<Uint8Array> | Uint8Array;
+/**
+ * UDS server with the same 4-byte-LE-length-prefix wire as UdsIpcClient and
+ * the C++ ipc::IpcServer socket transport. Accepts multiple concurrent
+ * connections; handler invocations are serialised per-connection.
+ */
+export declare class UdsIpcServer {
+    private socketPath;
+    private server;
+    private nextClientId;
+    private constructor();
+    static listen(socketPath: string, handler: IpcServerHandler): Promise<UdsIpcServer>;
+    close(): Promise<void>;
+    private handleConnection;
+}

package/dest/uds_server.js

@@ -0,0 +1,88 @@
+import * as net from "node:net";
+import * as fs from "node:fs";
+/**
+ * UDS server with the same 4-byte-LE-length-prefix wire as UdsIpcClient and
+ * the C++ ipc::IpcServer socket transport. Accepts multiple concurrent
+ * connections; handler invocations are serialised per-connection.
+ */
+export class UdsIpcServer {
+    socketPath;
+    server;
+    nextClientId = 0;
+    constructor(server, socketPath) {
+        this.socketPath = socketPath;
+        this.server = server;
+    }
+    static async listen(socketPath, handler) {
+        try {
+            fs.unlinkSync(socketPath);
+        }
+        catch {
+            /* socket file may not exist; ignore */
+        }
+        const server = net.createServer();
+        const instance = new UdsIpcServer(server, socketPath);
+        server.on("connection", (conn) => instance.handleConnection(conn, handler));
+        await new Promise((resolve, reject) => {
+            const onError = (err) => {
+                server.removeListener("listening", onListening);
+                reject(err);
+            };
+            const onListening = () => {
+                server.removeListener("error", onError);
+                resolve();
+            };
+            server.once("error", onError);
+            server.once("listening", onListening);
+            server.listen(socketPath);
+        });
+        return instance;
+    }
+    async close() {
+        await new Promise((resolve) => this.server.close(() => resolve()));
+        try {
+            fs.unlinkSync(this.socketPath);
+        }
+        catch {
+            /* may already be gone */
+        }
+    }
+    handleConnection(conn, handler) {
+        const clientId = this.nextClientId++;
+        let buffer = Buffer.alloc(0);
+        let chain = Promise.resolve();
+        conn.on("data", (chunk) => {
+            buffer =
+                buffer.length === 0
+                    ? Buffer.from(chunk)
+                    : Buffer.concat([buffer, chunk]);
+            while (buffer.length >= 4) {
+                const len = buffer.readUInt32LE(0);
+                if (buffer.length < 4 + len)
+                    break;
+                const payload = new Uint8Array(buffer.subarray(4, 4 + len));
+                buffer = buffer.subarray(4 + len);
+                const prev = chain;
+                chain = (async () => {
+                    await prev;
+                    try {
+                        const resp = await handler(clientId, payload);
+                        const lenBuf = Buffer.allocUnsafe(4);
+                        lenBuf.writeUInt32LE(resp.length, 0);
+                        conn.write(lenBuf);
+                        conn.write(resp);
+                    }
+                    catch (err) {
+                        conn.destroy(err);
+                    }
+                })();
+                void chain.catch(() => {
+                    /* errors already handled by destroying the connection */
+                });
+            }
+        });
+        conn.on("error", () => {
+            /* swallowed — clients reconnect */
+        });
+    }
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@aztec/ipc-runtime",
+  "packageManager": "yarn@4.13.0",
+  "version": "0.0.1-commit.4da4de7",
+  "type": "module",
+  "main": "dest/index.js",
+  "types": "dest/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dest/index.d.ts",
+      "import": "./dest/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dest"
+  },
+  "files": [
+    "dest",
+    "src",
+    "build"
+  ],
+  "devDependencies": {
+    "@types/node": "^22",
+    "typescript": "^5.6.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+export type { IpcClientAsync, IpcClientSync } from "./types.js";
+export { UdsIpcClient, type UdsIpcClientConnectOptions } from "./uds_client.js";
+export { UdsIpcServer, type IpcServerHandler } from "./uds_server.js";
+export {
+  NapiShmSyncClient,
+  NapiShmAsyncClient,
+  createNapiShmSyncClient,
+  createNapiShmAsyncClient,
+  type NapiMsgpackClientSync,
+  type NapiMsgpackClientAsync,
+} from "./shm_client.js";
+export {
+  findIpcRuntimeNapi,
+  loadIpcRuntimeNapi,
+  type Platform,
+} from "./native_loader.js";

package/src/native_loader.ts

@@ -0,0 +1,97 @@
+// Locate the prebuilt ipc_runtime_napi.node addon shipped with this package.
+//
+// The addon is built by `ipc-runtime/bootstrap.sh` (CMake target
+// `ipc_runtime_napi`) and copied into `build/<arch>-<os>/` next to this
+// package's `package.json`. Resolution walks up from this file's URL to the
+// first `package.json` adjacent to a `build/` directory — that's the
+// package root in both `file:`-linked and published consumption.
+
+import { createRequire } from "node:module";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export type Platform =
+  | "x86_64-linux"
+  | "x86_64-darwin"
+  | "aarch64-linux"
+  | "aarch64-darwin";
+
+const PLATFORM_TO_BUILD_DIR: Record<Platform, string> = {
+  "x86_64-linux": "amd64-linux",
+  "x86_64-darwin": "amd64-macos",
+  "aarch64-linux": "arm64-linux",
+  "aarch64-darwin": "arm64-macos",
+};
+
+function detectPlatform(): Platform | null {
+  const arch = process.arch;
+  const platform = process.platform;
+  if (arch === "x64" && platform === "linux") return "x86_64-linux";
+  if (arch === "x64" && platform === "darwin") return "x86_64-darwin";
+  if (arch === "arm64" && platform === "linux") return "aarch64-linux";
+  if (arch === "arm64" && platform === "darwin") return "aarch64-darwin";
+  return null;
+}
+
+function findPackageRoot(): string | null {
+  // `import.meta.url` after tsc compile points at the .js file under
+  // <pkg>/dest/...; climb until we find package.json with a sibling build/.
+  let currentDir = path.dirname(fileURLToPath(import.meta.url));
+  const root = path.parse(currentDir).root;
+  while (currentDir !== root) {
+    const packageJsonPath = path.join(currentDir, "package.json");
+    if (fs.existsSync(packageJsonPath)) {
+      const buildDir = path.join(currentDir, "build");
+      if (fs.existsSync(buildDir)) {
+        return currentDir;
+      }
+    }
+    currentDir = path.dirname(currentDir);
+  }
+  return null;
+}
+
+/**
+ * Resolve the path of `ipc_runtime_napi.node` for the current platform.
+ * Returns null if either the platform is unsupported or the artifact is
+ * absent (typical reason: ipc-runtime/bootstrap.sh hasn't run yet).
+ */
+export function findIpcRuntimeNapi(customPath?: string): string | null {
+  if (customPath) {
+    return fs.existsSync(customPath) ? path.resolve(customPath) : null;
+  }
+  const platform = detectPlatform();
+  if (!platform) return null;
+  const packageRoot = findPackageRoot();
+  if (!packageRoot) return null;
+  const buildDir = PLATFORM_TO_BUILD_DIR[platform];
+  const candidate = path.join(
+    packageRoot,
+    "build",
+    buildDir,
+    "ipc_runtime_napi.node",
+  );
+  return fs.existsSync(candidate) ? candidate : null;
+}
+
+/**
+ * Load `ipc_runtime_napi.node` and return its native exports
+ * (`MsgpackClient`, `MsgpackClientAsync`). Throws a descriptive error when
+ * the addon cannot be located or fails to dlopen.
+ */
+export function loadIpcRuntimeNapi(customPath?: string): {
+  MsgpackClient: new (shmName: string, clientId?: number) => any;
+  MsgpackClientAsync: new (shmName: string, clientId?: number) => any;
+} {
+  const addonPath = findIpcRuntimeNapi(customPath);
+  if (!addonPath) {
+    throw new Error(
+      "Could not locate ipc_runtime_napi.node. Build with `ipc-runtime/bootstrap.sh` " +
+        "or set the optional `customPath` argument to point at a prebuilt addon.",
+    );
+  }
+  // createRequire so this works in both ESM and CJS callers.
+  const require = createRequire(import.meta.url);
+  return require(addonPath);
+}

package/src/shm_client.ts

@@ -0,0 +1,148 @@
+import { loadIpcRuntimeNapi } from "./native_loader.js";
+import { IpcClientAsync, IpcClientSync } from "./types.js";
+
+/**
+ * Minimum surface a NAPI msgpack client must expose. Satisfied by the
+ * `MsgpackClient` / `MsgpackClientAsync` classes exported from this
+ * package's own `ipc_runtime_napi.node` addon (see ipc-runtime/cpp/napi/),
+ * which wraps the C++ ipc::IpcClient.
+ *
+ * The interface is exposed for tests / consumers that want to inject a
+ * mock or alternative implementation; the standard production path is the
+ * `createNapiShm{Sync,Async}Client` factories below, which load the
+ * prebuilt addon shipped in this package's `build/<arch>-<os>/` directory.
+ *
+ * Note on the async contract: `MsgpackClientAsync.call` is *fire and
+ * forget*. Responses arrive via `setResponseCallback` in FIFO order on a
+ * background-thread → main-thread bridge (Napi::ThreadSafeFunction).
+ * The TS wrapper below owns the request queue and matches responses.
+ */
+export interface NapiMsgpackClientSync {
+  call(input: Buffer): Buffer;
+  close(): void;
+}
+
+export interface NapiMsgpackClientAsync {
+  setResponseCallback(cb: (response: Buffer) => void): void;
+  call(input: Buffer): void;
+  acquire(): void;
+  release(): void;
+}
+
+/** Wraps a sync NAPI msgpack client behind the IpcClientSync interface. */
+export class NapiShmSyncClient implements IpcClientSync {
+  constructor(private inner: NapiMsgpackClientSync) {}
+
+  call(input: Uint8Array): Uint8Array {
+    const buf = Buffer.isBuffer(input)
+      ? input
+      : Buffer.from(input.buffer, input.byteOffset, input.byteLength);
+    const resp = this.inner.call(buf);
+    return new Uint8Array(resp.buffer, resp.byteOffset, resp.byteLength);
+  }
+
+  destroy(): void {
+    this.inner.close();
+  }
+}
+
+interface PendingCallback {
+  resolve: (data: Uint8Array) => void;
+  reject: (error: Error) => void;
+}
+
+/**
+ * Wraps the fire-and-forget async NAPI msgpack client behind the
+ * `IpcClientAsync` interface. Owns a FIFO queue of pending calls; the C++
+ * background polling thread invokes `setResponseCallback` once per
+ * response, and this wrapper matches it to the next queued caller.
+ *
+ * `acquire` / `release` are reference-count hooks the NAPI exposes so the
+ * libuv loop is kept alive only while requests are outstanding — without
+ * them a `node script.js` would never exit naturally.
+ */
+export class NapiShmAsyncClient implements IpcClientAsync {
+  private readonly pending: PendingCallback[] = [];
+
+  constructor(private inner: NapiMsgpackClientAsync) {
+    this.inner.setResponseCallback((response: Buffer) => {
+      const cb = this.pending.shift();
+      if (cb) {
+        cb.resolve(new Uint8Array(response));
+      } else {
+        // Unexpected — a response arrived but no caller is waiting.
+        // Drop it; there is no caller left to resolve.
+      }
+      if (this.pending.length === 0) {
+        this.inner.release();
+      }
+    });
+  }
+
+  call(input: Uint8Array): Promise<Uint8Array> {
+    const buf = Buffer.isBuffer(input)
+      ? input
+      : Buffer.from(input.buffer, input.byteOffset, input.byteLength);
+    return new Promise<Uint8Array>((resolve, reject) => {
+      if (this.pending.length === 0) {
+        this.inner.acquire();
+      }
+      this.pending.push({ resolve, reject });
+      try {
+        this.inner.call(buf);
+      } catch (err: any) {
+        // Send failed — unwind the queue entry we just added.
+        this.pending.pop();
+        if (this.pending.length === 0) {
+          this.inner.release();
+        }
+        reject(
+          err instanceof Error
+            ? err
+            : new Error(`SHM async call failed: ${String(err)}`),
+        );
+      }
+    });
+  }
+
+  async destroy(): Promise<void> {
+    // Reject anything still in flight.
+    while (this.pending.length > 0) {
+      const cb = this.pending.shift();
+      cb?.reject(new Error("ipc-runtime SHM client destroyed before response"));
+    }
+  }
+}
+
+export interface CreateNapiShmOptions {
+  /** MPSC client slot id (default 0). Distinct clients on the same shmName must use distinct slots. */
+  clientId?: number;
+  /** Override addon path lookup. Rarely needed; useful for tests / unusual deployments. */
+  customAddonPath?: string;
+}
+
+/**
+ * Factories that load the bundled `ipc_runtime_napi.node` addon and
+ * construct an MPSC-SHM client wrapped behind the `IpcClient*` interface.
+ * Matches the transport used by `ipc::make_server` on the C++ side, so any
+ * server started via that helper accepts these clients directly.
+ */
+export function createNapiShmSyncClient(
+  shmName: string,
+  options: CreateNapiShmOptions = {},
+): NapiShmSyncClient {
+  const napi = loadIpcRuntimeNapi(options.customAddonPath);
+  return new NapiShmSyncClient(
+    new napi.MsgpackClient(shmName, options.clientId ?? 0),
+  );
+}
+
+export function createNapiShmAsyncClient(
+  shmName: string,
+  options: CreateNapiShmOptions = {},
+): NapiShmAsyncClient {
+  const napi = loadIpcRuntimeNapi(options.customAddonPath);
+  return new NapiShmAsyncClient(
+    new napi.MsgpackClientAsync(shmName, options.clientId ?? 0),
+  );
+}

package/src/types.ts

@@ -0,0 +1,13 @@
+/**
+ * Minimal byte-in / byte-out interface that the ipc-codegen-emitted
+ * <Service>Api types consume. Both UDS and SHM transports satisfy this.
+ */
+export interface IpcClientAsync {
+  call(input: Uint8Array): Promise<Uint8Array>;
+  destroy(): Promise<void>;
+}
+
+export interface IpcClientSync {
+  call(input: Uint8Array): Uint8Array;
+  destroy(): void;
+}

package/src/uds_client.ts

@@ -0,0 +1,150 @@
+import * as net from "node:net";
+import { IpcClientAsync } from "./types.js";
+
+interface PendingCall {
+  resolve: (resp: Uint8Array) => void;
+  reject: (err: Error) => void;
+}
+
+export interface UdsIpcClientConnectOptions {
+  /** Mark the socket as unref'd so it doesn't keep the Node event loop alive when idle. */
+  unref?: boolean;
+  /**
+   * Retry budget (ms) for the initial connect when the server has bound the
+   * path but not yet called listen(). Set to 0 to fail immediately on
+   * ECONNREFUSED. Default 5000.
+   */
+  connectTimeoutMs?: number;
+}
+
+/**
+ * Async IPC client over a Unix Domain Socket. Wire format matches the C++
+ * ipc::IpcServer/IpcClient socket transport: 4-byte little-endian length
+ * prefix followed by `length` bytes of msgpack payload, per direction.
+ *
+ * Supports pipelining: multiple concurrent `call()` invocations are queued
+ * FIFO and matched with responses in order. Pipelining keeps the server-side
+ * socket window full and matches the native client behaviour.
+ */
+export class UdsIpcClient implements IpcClientAsync {
+  private buffer: Buffer = Buffer.alloc(0);
+  private pending: PendingCall[] = [];
+  private destroyed = false;
+
+  private constructor(private conn: net.Socket) {
+    conn.on("data", (chunk) => this.onData(chunk));
+    conn.on("error", (err) => this.failAll(err));
+    conn.on("close", () => this.failAll(new Error("socket closed")));
+  }
+
+  static async connect(
+    socketPath: string,
+    opts?: UdsIpcClientConnectOptions,
+  ): Promise<UdsIpcClient> {
+    const conn = await connectWithRetry(
+      socketPath,
+      opts?.connectTimeoutMs ?? 5000,
+    );
+    conn.setNoDelay(true);
+    if (opts?.unref) conn.unref();
+    return new UdsIpcClient(conn);
+  }
+
+  /** Number of in-flight calls awaiting a response. */
+  get inflight(): number {
+    return this.pending.length;
+  }
+
+  /** Underlying socket — exposed for ref/unref control (event-loop tuning). */
+  get socket(): net.Socket {
+    return this.conn;
+  }
+
+  async call(input: Uint8Array): Promise<Uint8Array> {
+    if (this.destroyed) {
+      throw new Error("UdsIpcClient: call() after destroy()");
+    }
+    return new Promise<Uint8Array>((resolve, reject) => {
+      this.pending.push({ resolve, reject });
+      const lenBuf = Buffer.allocUnsafe(4);
+      lenBuf.writeUInt32LE(input.length, 0);
+      this.conn.write(lenBuf);
+      this.conn.write(input);
+    });
+  }
+
+  async destroy(): Promise<void> {
+    this.destroyed = true;
+    this.conn.removeAllListeners();
+    this.conn.destroy();
+    this.failAll(new Error("UdsIpcClient destroyed"));
+  }
+
+  private onData(chunk: Buffer): void {
+    this.buffer =
+      this.buffer.length === 0
+        ? Buffer.from(chunk)
+        : Buffer.concat([this.buffer, chunk]);
+    while (this.buffer.length >= 4) {
+      const len = this.buffer.readUInt32LE(0);
+      if (this.buffer.length < 4 + len) return;
+      const payload = this.buffer.subarray(4, 4 + len);
+      this.buffer = this.buffer.subarray(4 + len);
+      const next = this.pending.shift();
+      if (next) next.resolve(new Uint8Array(payload));
+    }
+  }
+
+  private failAll(err: Error): void {
+    const pending = this.pending;
+    this.pending = [];
+    for (const p of pending) p.reject(err);
+  }
+}
+
+/**
+ * Connect to `socketPath`, retrying on ECONNREFUSED until `timeoutMs`
+ * elapses. ECONNREFUSED happens in the narrow window between the server's
+ * bind() and listen(); other errors fail immediately.
+ */
+async function connectWithRetry(
+  socketPath: string,
+  timeoutMs: number,
+): Promise<net.Socket> {
+  const deadline = Date.now() + timeoutMs;
+  let attempt = 0;
+  let lastErr: Error | undefined;
+  while (true) {
+    try {
+      return await attemptConnect(socketPath);
+    } catch (err) {
+      lastErr = err as Error;
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code !== "ECONNREFUSED" && code !== "ENOENT") {
+        throw new Error(`UdsIpcClient: connect failed: ${lastErr.message}`);
+      }
+      if (Date.now() >= deadline) {
+        throw new Error(`UdsIpcClient: connect timed out: ${lastErr.message}`);
+      }
+      const delay = Math.min(50, 5 * 2 ** attempt++);
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+  }
+}
+
+function attemptConnect(socketPath: string): Promise<net.Socket> {
+  return new Promise<net.Socket>((resolve, reject) => {
+    const conn = net.createConnection(socketPath);
+    const onError = (err: Error) => {
+      conn.removeListener("connect", onConnect);
+      conn.destroy();
+      reject(err);
+    };
+    const onConnect = () => {
+      conn.removeListener("error", onError);
+      resolve(conn);
+    };
+    conn.once("connect", onConnect);
+    conn.once("error", onError);
+  });
+}

package/src/uds_server.ts

@@ -0,0 +1,110 @@
+import * as net from "node:net";
+import * as fs from "node:fs";
+
+/**
+ * Handler signature mirrors the C++ ipc::IpcServer::Handler: receive raw
+ * bytes, return raw bytes. msgpack decode/encode and command dispatch are
+ * the caller's responsibility (or the codegen's, when a generated dispatcher
+ * is wired in).
+ */
+export type IpcServerHandler = (
+  clientId: number,
+  request: Uint8Array,
+) => Promise<Uint8Array> | Uint8Array;
+
+/**
+ * UDS server with the same 4-byte-LE-length-prefix wire as UdsIpcClient and
+ * the C++ ipc::IpcServer socket transport. Accepts multiple concurrent
+ * connections; handler invocations are serialised per-connection.
+ */
+export class UdsIpcServer {
+  private server: net.Server;
+  private nextClientId = 0;
+
+  private constructor(
+    server: net.Server,
+    private socketPath: string,
+  ) {
+    this.server = server;
+  }
+
+  static async listen(
+    socketPath: string,
+    handler: IpcServerHandler,
+  ): Promise<UdsIpcServer> {
+    try {
+      fs.unlinkSync(socketPath);
+    } catch {
+      /* socket file may not exist; ignore */
+    }
+
+    const server = net.createServer();
+    const instance = new UdsIpcServer(server, socketPath);
+    server.on("connection", (conn) => instance.handleConnection(conn, handler));
+
+    await new Promise<void>((resolve, reject) => {
+      const onError = (err: Error) => {
+        server.removeListener("listening", onListening);
+        reject(err);
+      };
+      const onListening = () => {
+        server.removeListener("error", onError);
+        resolve();
+      };
+      server.once("error", onError);
+      server.once("listening", onListening);
+      server.listen(socketPath);
+    });
+
+    return instance;
+  }
+
+  async close(): Promise<void> {
+    await new Promise<void>((resolve) => this.server.close(() => resolve()));
+    try {
+      fs.unlinkSync(this.socketPath);
+    } catch {
+      /* may already be gone */
+    }
+  }
+
+  private handleConnection(conn: net.Socket, handler: IpcServerHandler): void {
+    const clientId = this.nextClientId++;
+    let buffer = Buffer.alloc(0);
+    let chain: Promise<void> = Promise.resolve();
+
+    conn.on("data", (chunk: Buffer) => {
+      buffer =
+        buffer.length === 0
+          ? Buffer.from(chunk)
+          : Buffer.concat([buffer, chunk]);
+      while (buffer.length >= 4) {
+        const len = buffer.readUInt32LE(0);
+        if (buffer.length < 4 + len) break;
+        const payload = new Uint8Array(buffer.subarray(4, 4 + len));
+        buffer = buffer.subarray(4 + len);
+
+        const prev = chain;
+        chain = (async () => {
+          await prev;
+          try {
+            const resp = await handler(clientId, payload);
+            const lenBuf = Buffer.allocUnsafe(4);
+            lenBuf.writeUInt32LE(resp.length, 0);
+            conn.write(lenBuf);
+            conn.write(resp);
+          } catch (err) {
+            conn.destroy(err as Error);
+          }
+        })();
+        void chain.catch(() => {
+          /* errors already handled by destroying the connection */
+        });
+      }
+    });
+
+    conn.on("error", () => {
+      /* swallowed — clients reconnect */
+    });
+  }
+}