@zlink-systems/zlink 0.17.3

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,84 @@
+# Third-Party Notices
+
+This repository contains third-party source code and/or redistributable binaries.
+This file summarizes known components and where their license texts are located.
+
+## Bundled source dependencies
+
+- Boost (header-only subset)
+  - Location: `core/external/boost/`
+  - License text: `core/external/boost/LICENSE_1_0.txt`
+  - License type: Boost Software License 1.0
+
+- moodycamel::ConcurrentQueue
+  - Location: `core/external/moodycamel/`
+  - License text: `core/external/moodycamel/LICENSE`
+  - License type: Simplified BSD (2-Clause)
+
+- wepoll
+  - Location: `core/external/wepoll/`
+  - License text: `core/external/wepoll/license.txt`
+  - License type: BSD-2-Clause style
+
+- Unity test framework
+  - Location: `core/external/unity/`
+  - License text: `core/external/unity/license.txt`
+  - License type: MIT
+
+- SHA1 implementation (WIDE Project)
+  - Location: `core/external/sha1/`
+  - License text: `core/external/sha1/license.txt`
+  - License type: BSD-3-Clause style
+
+## Bundled runtime binaries in bindings
+
+The following folders include prebuilt runtime binaries for convenience:
+
+- `bindings/node/prebuilds/`
+- `bindings/dotnet/runtimes/*/native/`
+- `bindings/java/src/main/resources/native/`
+- `bindings/cpp/native/`
+- `bindings/python/src/zlink/native/`
+
+These artifacts may include components such as:
+
+- zlink/libzlink binaries
+- Microsoft Visual C++ runtime DLLs (Windows targets)
+- OpenSSL runtime libraries, depending on package/target
+
+When redistributing these artifacts, ensure the corresponding third-party
+license obligations are met for your target platform and package format.
+
+## Origin of `core/`
+
+`core/` began as a fork of [libzmq](https://github.com/zeromq/libzmq) v4.3.5,
+narrowed to a smaller set of socket patterns and re-platformed onto Boost.Asio
+and OpenSSL (see `core/doc/guide/design-rationale.ko.md` for the technical
+rationale). Separately, as public upstream history: libzmq v4.3.5 is the
+release at which the libzmq project itself completed relicensing from
+LGPLv3 + static-linking exception to MPL-2.0. `core/` therefore carries the
+MPL-2.0 license forward from that upstream lineage. The upstream copyright
+holders and contributors are recorded verbatim (as of v4.3.5) in
+[`core/AUTHORS`](./core/AUTHORS), vendored from libzmq for that reason.
+
+## Project License
+
+This repository uses three licenses, split by layer:
+
+- `core/` and `bindings/` (per-language native bindings) are licensed under
+  MPL-2.0. See `LICENSE`.
+- `framework/` (the higher-level framework built on top of the bindings) is
+  licensed under FSL-1.1-ALv2 (Functional Source License 1.1, Apache-2.0
+  Future License). See `framework/LICENSE`.
+- Each language's `http-client` package under `framework/` (a thin wrapper
+  over that platform's commonly used HTTP client library — .NET's
+  `System.Net.Http`, Java/Kotlin's `java.net.http`, Node's `undici`, C++'s
+  Boost.Beast) is licensed under Apache License 2.0 instead of FSL, because
+  it wraps a permissively-licensed library rather than any zlink-original
+  transport. The .NET and Node packages declare this directly in their own
+  manifest; the Java and Kotlin packages receive it from the shared Gradle
+  publish configuration; the C++ package ships the license text alongside
+  its sources.
+
+Unless otherwise noted, source code outside `framework/` is licensed under
+MPL-2.0.

package/binding.gyp

@@ -0,0 +1,27 @@
+{
+  "targets": [
+    {
+      "target_name": "zlink",
+      "sources": [
+        "native/src/addon.cc",
+        "native/src/addon_core.cc",
+        "native/src/addon_core_options.cc",
+        "native/src/addon_exports.cc"
+      ],
+      "include_dirs": [ "<!(node scripts/resolve_core.js include)" ],
+      "variables": {
+        "zlink_lib%": "<!(node scripts/resolve_core.js library)"
+      },
+      "conditions": [
+        [ "\"<(zlink_lib)\" != \"\"", { "libraries": [ "<(zlink_lib)" ] } ],
+        [ "OS==\"linux\"", { "ldflags": [ "-Wl,-rpath,\\$$ORIGIN" ] } ],
+        [ "OS==\"mac\"", {
+          "ldflags": [ "-Wl,-rpath,@loader_path" ],
+          "xcode_settings": {
+            "LD_RUNPATH_SEARCH_PATHS": [ "@loader_path" ]
+          }
+        } ]
+      ]
+    }
+  ]
+}

package/dist/index.d.mts

@@ -0,0 +1,3 @@
+export * from './index.js';
+import cjs = require('./index.js');
+export default cjs;

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+export * from './zlink/contracts';
+import type { AtomicCounter, Context, DealerSocket, PairSocket, Poller, PollEvents, PubSocket, RouterSocket, Stopwatch, StreamSocket, SubSocket, Thread, Timer, XPubSocket, XSubSocket } from './zlink/contracts';
+import type { BaseSocket, Message } from './zlink/contracts';
+export declare function createContext(): Context;
+export declare function createPairSocket(ctx: Context): PairSocket;
+export declare function createPubSocket(ctx: Context): PubSocket;
+export declare function createSubSocket(ctx: Context): SubSocket;
+export declare function createXPubSocket(ctx: Context): XPubSocket;
+export declare function createXSubSocket(ctx: Context): XSubSocket;
+export declare function createDealerSocket(ctx: Context): DealerSocket;
+export declare function createRouterSocket(ctx: Context): RouterSocket;
+export declare function createStreamSocket(ctx: Context): StreamSocket;
+export declare function createPoller(): Poller;
+export declare function createPollEvents(capacity: number): PollEvents;
+export declare function createTimer(): Timer;
+export declare function createThread(handler: () => void): Thread;
+export declare function createStopwatch(): Stopwatch;
+export declare function createAtomicCounter(initialValue?: number): AtomicCounter;
+export declare function version(): [number, number, number];
+export declare function strerror(code: number): string;
+export declare function has(capability: string): boolean;
+export declare function proxy(frontend: BaseSocket, backend: BaseSocket, capture?: BaseSocket): void;
+export declare function sleep(seconds: number): void;
+export declare function multipartClose(parts: Message[]): void;

package/dist/index.js

@@ -0,0 +1,117 @@
+"use strict";
+// SPDX-License-Identifier: MPL-2.0
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createContext = createContext;
+exports.createPairSocket = createPairSocket;
+exports.createPubSocket = createPubSocket;
+exports.createSubSocket = createSubSocket;
+exports.createXPubSocket = createXPubSocket;
+exports.createXSubSocket = createXSubSocket;
+exports.createDealerSocket = createDealerSocket;
+exports.createRouterSocket = createRouterSocket;
+exports.createStreamSocket = createStreamSocket;
+exports.createPoller = createPoller;
+exports.createPollEvents = createPollEvents;
+exports.createTimer = createTimer;
+exports.createThread = createThread;
+exports.createStopwatch = createStopwatch;
+exports.createAtomicCounter = createAtomicCounter;
+exports.version = version;
+exports.strerror = strerror;
+exports.has = has;
+exports.proxy = proxy;
+exports.sleep = sleep;
+exports.multipartClose = multipartClose;
+__exportStar(require("./zlink/contracts"), exports);
+const message_1 = require("./zlink/contracts/messaging/message");
+const native_1 = require("./zlink/runtime/native/native");
+const runtime_info_1 = require("./zlink/runtime/core/runtime_info");
+const context_1 = require("./zlink/runtime/core/context");
+const eventing_1 = require("./zlink/runtime/eventing");
+const sockets_1 = require("./zlink/runtime/sockets");
+const public_bridge_1 = require("./zlink/runtime/public_bridge");
+(0, message_1.configureMessageNativeOperations)({
+    allocate: (size) => (0, native_1.requireNative)().messageAllocate(size),
+    close: (nativeMessage) => (0, native_1.requireNative)().messageFrameClose(nativeMessage),
+    data: (nativeMessage) => (0, native_1.requireNative)().messageFrameData(nativeMessage),
+    copyData: (nativeMessage) => (0, native_1.requireNative)().messageFrameCopyData(nativeMessage),
+    fromBuffer: (data) => (0, native_1.requireNative)().messageFromBuffer(data),
+    size: (nativeMessage) => (0, native_1.requireNative)().messageFrameSize(nativeMessage),
+});
+function createContext() {
+    return (0, public_bridge_1.asPublicContract)(new context_1.RuntimeContext());
+}
+function createPairSocket(ctx) {
+    return (0, public_bridge_1.asPublicContract)(new sockets_1.RuntimePairSocket((0, public_bridge_1.asRuntimeContext)(ctx)));
+}
+function createPubSocket(ctx) {
+    return (0, public_bridge_1.asPublicContract)(new sockets_1.RuntimePubSocket((0, public_bridge_1.asRuntimeContext)(ctx)));
+}
+function createSubSocket(ctx) {
+    return (0, public_bridge_1.asPublicContract)(new sockets_1.RuntimeSubSocket((0, public_bridge_1.asRuntimeContext)(ctx)));
+}
+function createXPubSocket(ctx) {
+    return (0, public_bridge_1.asPublicContract)(new sockets_1.RuntimeXPubSocket((0, public_bridge_1.asRuntimeContext)(ctx)));
+}
+function createXSubSocket(ctx) {
+    return (0, public_bridge_1.asPublicContract)(new sockets_1.RuntimeXSubSocket((0, public_bridge_1.asRuntimeContext)(ctx)));
+}
+function createDealerSocket(ctx) {
+    return (0, public_bridge_1.asPublicContract)(new sockets_1.RuntimeDealerSocket((0, public_bridge_1.asRuntimeContext)(ctx)));
+}
+function createRouterSocket(ctx) {
+    return (0, public_bridge_1.asPublicContract)(new sockets_1.RuntimeRouterSocket((0, public_bridge_1.asRuntimeContext)(ctx)));
+}
+function createStreamSocket(ctx) {
+    return (0, public_bridge_1.asPublicContract)(new sockets_1.RuntimeStreamSocket((0, public_bridge_1.asRuntimeContext)(ctx)));
+}
+function createPoller() {
+    return (0, public_bridge_1.asPublicContract)(new eventing_1.RuntimePoller());
+}
+function createPollEvents(capacity) {
+    return (0, public_bridge_1.asPublicContract)(new eventing_1.RuntimePollEvents(capacity));
+}
+function createTimer() {
+    return (0, public_bridge_1.asPublicContract)(new eventing_1.RuntimeTimer());
+}
+function createThread(handler) {
+    return (0, public_bridge_1.asPublicContract)(new eventing_1.RuntimeThread(handler));
+}
+function createStopwatch() {
+    return (0, public_bridge_1.asPublicContract)(new eventing_1.RuntimeStopwatch());
+}
+function createAtomicCounter(initialValue = 0) {
+    return (0, public_bridge_1.asPublicContract)(new eventing_1.RuntimeAtomicCounter(initialValue));
+}
+function version() {
+    return (0, runtime_info_1.version)();
+}
+function strerror(code) {
+    return (0, runtime_info_1.strerror)(code);
+}
+function has(capability) {
+    return (0, runtime_info_1.has)(capability);
+}
+function proxy(frontend, backend, capture) {
+    (0, runtime_info_1.proxy)((0, public_bridge_1.asRuntimeSocket)(frontend), (0, public_bridge_1.asRuntimeSocket)(backend), capture ? (0, public_bridge_1.asRuntimeSocket)(capture) : undefined);
+}
+function sleep(seconds) {
+    (0, runtime_info_1.sleep)(seconds);
+}
+function multipartClose(parts) {
+    (0, runtime_info_1.multipartClose)(parts);
+}

package/dist/index.mjs

@@ -0,0 +1,4 @@
+// Generated from src/index.ts by scripts/generate_esm_wrapper.js.
+import cjs from './index.js';
+export default cjs;
+export const { AutoHwmProfile, BindError, BindResult, CloseError, CloseResult, CompletionKind, ConfigError, ConfigResult, ConnectError, ConnectResult, createAtomicCounter, createContext, createDealerSocket, createPairSocket, createPoller, createPollEvents, createPubSocket, createRouterSocket, createStopwatch, createStreamSocket, createSubSocket, createThread, createTimer, createXPubSocket, createXSubSocket, HandlerError, HandlerResult, has, Message, MonitorEvent, MonitorEventFlag, MonitorEventType, MonitorSourceKind, multipartClose, PollEventFlag, proxy, Received, ReceiveFlowState, RecvError, RecvFlags, RecvResult, ReplyToken, RequestError, RequestResult, RidDuplicatePolicy, RoutingId, SendFlags, sleep, SOCKET_MONITOR_EVENT_ALL, SocketType, StreamPacket, StreamRecvMode, strerror, SubmitError, SubmitResult, SubmitRetryMode, SubscriptionEvent, TopicMessage, version, ZlinkError } = cjs;

package/dist/zlink/contracts/core/buffer_like.d.ts

@@ -0,0 +1,2 @@
+/** A value accepted where bytes are expected: a `Buffer`, `Uint8Array`, or `string` (encoded as UTF-8). */
+export type BufferLike = Buffer | Uint8Array | string;

package/dist/zlink/contracts/core/buffer_like.js

@@ -0,0 +1,3 @@
+"use strict";
+// SPDX-License-Identifier: MPL-2.0
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/zlink/contracts/core/context.d.ts

@@ -0,0 +1,103 @@
+/** An automatic high-water-mark sizing profile trading memory, latency, and throughput. */
+export declare const AutoHwmProfile: Readonly<{
+    readonly Compact: 0;
+    readonly LowLatency: 1;
+    readonly Balanced: 2;
+    readonly Throughput: 3;
+}>;
+export type AutoHwmProfileValue = typeof AutoHwmProfile[keyof typeof AutoHwmProfile];
+/** Immutable Core Auto HWM ABI-v1 context budget snapshot. */
+export interface CoreHwmBudgetSnapshot {
+    readonly abiVersion: number;
+    readonly structSize: number;
+    readonly budgetGeneration: bigint;
+    readonly measurementEpoch: bigint;
+    readonly configuredMemoryLimitBytes: bigint;
+    readonly runtimeMemoryLimitBytes: bigint;
+    readonly resolvedMemoryLimitBytes: bigint;
+    readonly configuredCoreBudgetBytes: bigint;
+    readonly effectiveCoreBudgetBytes: bigint;
+    readonly totalPlannedHwmBytes: bigint;
+    readonly totalAppliedHwmBytes: bigint;
+    readonly manualReservedHwmBytes: bigint;
+    readonly coreQueueAccountedBytes: bigint;
+    readonly applicationAccountedBytes: bigint;
+    readonly currentAccountedBytes: bigint;
+    readonly provisionalAccountedBytes: bigint;
+    readonly peakAccountedBytes: bigint;
+    readonly completionCurrentAccountedBytes: bigint;
+    readonly completionPeakAccountedBytes: bigint;
+    readonly completionPendingMessageCount: bigint;
+    readonly totalMessagingAccountedBytes: bigint;
+    readonly monitorQueueAppliedHwmBytes: bigint;
+    readonly monitorQueueAccountedBytes: bigint;
+    readonly totalInstanceAppliedHwmBytes: bigint;
+    readonly totalInstanceAccountedBytes: bigint;
+    readonly oversizeAdmissionCount: bigint;
+    readonly largestOversizeMessageBytes: bigint;
+    readonly activeDirectionalQueueCount: bigint;
+    readonly activeCompletionDirectionalQueueCount: bigint;
+    readonly activeSendQueueCount: bigint;
+    readonly activeReceiveQueueCount: bigint;
+    readonly outstandingApplicationLeaseCount: bigint;
+    readonly retiredQueueCount: bigint;
+    readonly deferredOriginCreditBytes: bigint;
+    readonly unlimitedManualQueueCount: bigint;
+    readonly blockedRatioPpm: number;
+    readonly flags: number;
+    readonly reservedUInt64: readonly bigint[];
+    readonly budgetPlanningActive: boolean;
+    readonly budgetInsufficient: boolean;
+    readonly aggregateHwmValid: boolean;
+    readonly aggregateOverflow: boolean;
+}
+/** Context-wide options governing the I/O threads and defaults shared by every socket. */
+export interface ContextOptions {
+    /** The number of background I/O threads serving the context. */
+    ioThreads: number;
+    /** The maximum number of sockets the context may create. */
+    maxSockets: number;
+    /** The largest value `maxSockets` may take on this build. */
+    readonly socketLimit: number;
+    /** The default maximum inbound message size, in bytes, for new sockets. */
+    maxMsgSize: number;
+    /** The size of the context's message worker thread pool. */
+    readonly msgTSize: number;
+    /** The OS scheduling priority of the context's I/O threads. */
+    threadPriority: number;
+    /** The OS scheduling policy of the context's I/O threads. */
+    threadSchedulingPolicy: number;
+    /** Whether the context blocks on termination until queued messages are sent. */
+    blocky: boolean;
+    /** Whether high-water marks are sized automatically. */
+    autoHwmEnabled: boolean;
+    /** The minimum delay, in ms, between automatic high-water-mark recalculations. */
+    autoHwmRecalcDebounceMs: number;
+    /** The profile used to divide the Core memory budget. */
+    coreHwmProfile: AutoHwmProfileValue;
+    /** Explicit context memory limit in bytes; 0n selects automatic detection. */
+    coreHwmMemoryLimitBytes: bigint;
+    /** Explicit context-wide Core budget in bytes; 0n derives it from the memory limit. */
+    coreHwmBudgetBytes: bigint;
+    /** The prefix applied to the names of threads the context creates. */
+    threadNamePrefix: string;
+    /** Pin the context's I/O threads to also run on CPU core `cpu`. */
+    addThreadAffinity(cpu: number): void;
+    /** Remove CPU core `cpu` from the context's I/O thread affinity. */
+    removeThreadAffinity(cpu: number): void;
+}
+/** A messaging context: the factory and owner of sockets and event sources. */
+export interface Context {
+    /** The context-wide options facade. */
+    readonly options: ContextOptions;
+    /** Terminate the context, interrupting blocking operations on its sockets without closing them. */
+    shutdown(): void;
+    /** Recompute automatic high-water marks for the context's sockets immediately. */
+    recalculateAutoHwm(): void;
+    /** Return an immutable value snapshot of Core's context-wide HWM budget state. */
+    getCoreHwmBudgetSnapshot(): CoreHwmBudgetSnapshot;
+    /** Reset epoch metrics while preserving current HWM budget gauges. */
+    resetCoreHwmBudgetMetrics(): void;
+    /** Close the context and release its resources, terminating anything still open under it. */
+    close(): void;
+}

package/dist/zlink/contracts/core/context.js

@@ -0,0 +1,11 @@
+"use strict";
+// SPDX-License-Identifier: MPL-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AutoHwmProfile = void 0;
+/** An automatic high-water-mark sizing profile trading memory, latency, and throughput. */
+exports.AutoHwmProfile = Object.freeze({
+    Compact: 0,
+    LowLatency: 1,
+    Balanced: 2,
+    Throughput: 3
+});

package/dist/zlink/contracts/core/index.d.ts

@@ -0,0 +1,3 @@
+export * from './buffer_like';
+export * from './context';
+export * from './routing_id';

package/dist/zlink/contracts/core/index.js

@@ -0,0 +1,20 @@
+"use strict";
+// SPDX-License-Identifier: MPL-2.0
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./buffer_like"), exports);
+__exportStar(require("./context"), exports);
+__exportStar(require("./routing_id"), exports);

package/dist/zlink/contracts/core/routing_id.d.ts

@@ -0,0 +1,28 @@
+export declare class RoutingId {
+    private readonly _bytes;
+    private constructor();
+    /**
+     * Create a routing id from a string (its UTF-8 bytes), a number (a 4-byte
+     * big-endian uint32), or a Buffer/Uint8Array (copied). Throws when the byte
+     * length is not 1..255.
+     */
+    static from(value: string | Buffer | Uint8Array | number): RoutingId;
+    /**
+     * Create a routing id by decoding `value` as a hex string (non-empty, even
+     * length, up to 510 digits for 255 bytes).
+     */
+    static fromHex(value: string): RoutingId;
+    /** Return a copy of the routing id bytes. */
+    toBytes(): Buffer;
+    /** The length of the routing id in bytes. */
+    get size(): number;
+    /** Return true when `other` has identical bytes. */
+    equals(other: RoutingId): boolean;
+    /** Return the routing id as a lowercase hex string. */
+    toHex(): string;
+    /**
+     * Return a human-readable form: printable UTF-8 text when possible, otherwise
+     * a uint, a UUID, or a `hex:` fallback.
+     */
+    toString(): string;
+}

package/dist/zlink/contracts/core/routing_id.js

@@ -0,0 +1,120 @@
+"use strict";
+// SPDX-License-Identifier: MPL-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RoutingId = void 0;
+const errors_1 = require("../errors/errors");
+const ROUTING_ID_MAX_LENGTH = 255;
+function normalizeRoutingIdBytes(bytes, name) {
+    if (!Buffer.isBuffer(bytes) && !(bytes instanceof Uint8Array)) {
+        throw new TypeError(`${name} must be a Buffer or Uint8Array`);
+    }
+    const normalized = Buffer.from(bytes);
+    if (normalized.length === 0 || normalized.length > ROUTING_ID_MAX_LENGTH) {
+        const error = new errors_1.ConfigError(errors_1.ConfigResult.InvalidArgument, 0);
+        error.message = `${name} must be 1..${ROUTING_ID_MAX_LENGTH} bytes`;
+        throw error;
+    }
+    return normalized;
+}
+function normalizeRoutingIdHex(value) {
+    if (typeof value !== 'string') {
+        throw new TypeError('value must be a string');
+    }
+    if (value.length === 0 || value.length % 2 !== 0 || !/^[0-9a-fA-F]+$/.test(value)) {
+        const error = new errors_1.ConfigError(errors_1.ConfigResult.InvalidArgument, 0);
+        error.message = 'value must be a non-empty even-length hex string';
+        throw error;
+    }
+    if (value.length > ROUTING_ID_MAX_LENGTH * 2) {
+        const error = new errors_1.ConfigError(errors_1.ConfigResult.InvalidArgument, 0);
+        error.message = `value must decode to at most ${ROUTING_ID_MAX_LENGTH} bytes`;
+        throw error;
+    }
+    return normalizeRoutingIdBytes(Buffer.from(value, 'hex'), 'value');
+}
+function normalizeRoutingIdValue(value) {
+    if (typeof value === 'string') {
+        return normalizeRoutingIdBytes(Buffer.from(value, 'utf8'), 'value');
+    }
+    if (typeof value === 'number') {
+        if (!Number.isInteger(value) || value < 0 || value > 0xFFFF_FFFF) {
+            throw new RangeError('routing id uint32 value must be in range 0..4294967295');
+        }
+        const buffer = Buffer.allocUnsafe(4);
+        buffer.writeUInt32BE(value >>> 0, 0);
+        return buffer;
+    }
+    return normalizeRoutingIdBytes(value, 'value');
+}
+function tryPrintableUtf8(bytes) {
+    const text = bytes.toString('utf8');
+    if (!Buffer.from(text, 'utf8').equals(bytes)) {
+        return null;
+    }
+    return /[\u0000-\u001f\u007f-\u009f]/u.test(text) ? null : text;
+}
+function uuidString(bytes) {
+    const hex = bytes.toString('hex');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+/** An opaque identifier for a messaging peer or route, 1 to 255 bytes long. */
+const ROUTING_ID_CONSTRUCTOR_TOKEN = Symbol('RoutingId.constructor');
+class RoutingId {
+    _bytes;
+    constructor(bytes, token) {
+        if (token !== ROUTING_ID_CONSTRUCTOR_TOKEN) {
+            throw new TypeError('RoutingId values are created by RoutingId.from or RoutingId.fromHex');
+        }
+        this._bytes = bytes;
+        Object.freeze(this);
+    }
+    /**
+     * Create a routing id from a string (its UTF-8 bytes), a number (a 4-byte
+     * big-endian uint32), or a Buffer/Uint8Array (copied). Throws when the byte
+     * length is not 1..255.
+     */
+    static from(value) {
+        return new RoutingId(normalizeRoutingIdValue(value), ROUTING_ID_CONSTRUCTOR_TOKEN);
+    }
+    /**
+     * Create a routing id by decoding `value` as a hex string (non-empty, even
+     * length, up to 510 digits for 255 bytes).
+     */
+    static fromHex(value) {
+        return new RoutingId(normalizeRoutingIdHex(value), ROUTING_ID_CONSTRUCTOR_TOKEN);
+    }
+    /** Return a copy of the routing id bytes. */
+    toBytes() {
+        return Buffer.from(this._bytes);
+    }
+    /** The length of the routing id in bytes. */
+    get size() {
+        return this._bytes.length;
+    }
+    /** Return true when `other` has identical bytes. */
+    equals(other) {
+        return other instanceof RoutingId && this._bytes.equals(other._bytes);
+    }
+    /** Return the routing id as a lowercase hex string. */
+    toHex() {
+        return this._bytes.toString('hex');
+    }
+    /**
+     * Return a human-readable form: printable UTF-8 text when possible, otherwise
+     * a uint, a UUID, or a `hex:` fallback.
+     */
+    toString() {
+        const utf8 = tryPrintableUtf8(this._bytes);
+        if (utf8 !== null) {
+            return utf8;
+        }
+        if (this._bytes.length === 4) {
+            return this._bytes.readUInt32BE(0).toString(10);
+        }
+        if (this._bytes.length === 16) {
+            return uuidString(this._bytes);
+        }
+        return `hex:${this.toHex()}`;
+    }
+}
+exports.RoutingId = RoutingId;

package/dist/zlink/contracts/errors/errors.d.ts

@@ -0,0 +1,44 @@
+import { BindResult, CloseResult, ConfigResult, ConnectResult, HandlerResult, RecvResult, RequestResult, SubmitResult } from './results';
+export { BindResult, CloseResult, ConfigResult, ConnectResult, HandlerResult, RecvResult, RequestResult, SubmitResult, } from './results';
+/** Base class for all errors thrown by the zlink bindings; carries a result `code` and the underlying native errno. */
+export declare class ZlinkError extends Error {
+    readonly code: number;
+    readonly nativeErrno: number;
+    constructor(code: number, nativeErrno?: number);
+}
+declare class ResultError<TResult extends number> extends ZlinkError {
+    readonly result: TResult;
+    protected constructor(name: string, result: TResult, nativeErrno?: number);
+}
+/** Thrown when submitting a send or publish fails. */
+export declare class SubmitError extends ResultError<SubmitResult> {
+    constructor(result: SubmitResult, nativeErrno?: number);
+}
+/** Thrown when a request fails or its reply reports an error. */
+export declare class RequestError extends ResultError<RequestResult> {
+    constructor(result: RequestResult, nativeErrno?: number);
+}
+/** Thrown when receiving a message fails. */
+export declare class RecvError extends ResultError<RecvResult> {
+    constructor(result: RecvResult, nativeErrno?: number);
+}
+/** Thrown when registering or running a callback handler fails. */
+export declare class HandlerError extends ResultError<HandlerResult> {
+    constructor(result: HandlerResult, nativeErrno?: number);
+}
+/** Thrown when closing a socket or resource fails. */
+export declare class CloseError extends ResultError<CloseResult> {
+    constructor(result: CloseResult, nativeErrno?: number);
+}
+/** Thrown when binding a socket to an endpoint fails. */
+export declare class BindError extends ResultError<BindResult> {
+    constructor(result: BindResult, nativeErrno?: number);
+}
+/** Thrown when connecting a socket to an endpoint fails. */
+export declare class ConnectError extends ResultError<ConnectResult> {
+    constructor(result: ConnectResult, nativeErrno?: number);
+}
+/** Thrown when reading or applying a configuration option fails. */
+export declare class ConfigError extends ResultError<ConfigResult> {
+    constructor(result: ConfigResult, nativeErrno?: number);
+}