@zlink-systems/zlink 0.17.3

package/dist/zlink/contracts/errors/errors.js

@@ -0,0 +1,89 @@
+"use strict";
+// SPDX-License-Identifier: MPL-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigError = exports.ConnectError = exports.BindError = exports.CloseError = exports.HandlerError = exports.RecvError = exports.RequestError = exports.SubmitError = exports.ZlinkError = exports.SubmitResult = exports.RequestResult = exports.RecvResult = exports.HandlerResult = exports.ConnectResult = exports.ConfigResult = exports.CloseResult = exports.BindResult = void 0;
+var results_1 = require("./results");
+Object.defineProperty(exports, "BindResult", { enumerable: true, get: function () { return results_1.BindResult; } });
+Object.defineProperty(exports, "CloseResult", { enumerable: true, get: function () { return results_1.CloseResult; } });
+Object.defineProperty(exports, "ConfigResult", { enumerable: true, get: function () { return results_1.ConfigResult; } });
+Object.defineProperty(exports, "ConnectResult", { enumerable: true, get: function () { return results_1.ConnectResult; } });
+Object.defineProperty(exports, "HandlerResult", { enumerable: true, get: function () { return results_1.HandlerResult; } });
+Object.defineProperty(exports, "RecvResult", { enumerable: true, get: function () { return results_1.RecvResult; } });
+Object.defineProperty(exports, "RequestResult", { enumerable: true, get: function () { return results_1.RequestResult; } });
+Object.defineProperty(exports, "SubmitResult", { enumerable: true, get: function () { return results_1.SubmitResult; } });
+/** Base class for all errors thrown by the zlink bindings; carries a result `code` and the underlying native errno. */
+class ZlinkError extends Error {
+    code;
+    nativeErrno;
+    constructor(code, nativeErrno = 0) {
+        super(`zlink error ${code}`);
+        this.name = 'ZlinkError';
+        this.code = code | 0;
+        this.nativeErrno = nativeErrno | 0;
+    }
+}
+exports.ZlinkError = ZlinkError;
+class ResultError extends ZlinkError {
+    result;
+    constructor(name, result, nativeErrno = 0) {
+        super(result, nativeErrno);
+        this.name = name;
+        this.result = result;
+    }
+}
+/** Thrown when submitting a send or publish fails. */
+class SubmitError extends ResultError {
+    constructor(result, nativeErrno = 0) {
+        super('SubmitError', result, nativeErrno);
+    }
+}
+exports.SubmitError = SubmitError;
+/** Thrown when a request fails or its reply reports an error. */
+class RequestError extends ResultError {
+    constructor(result, nativeErrno = 0) {
+        super('RequestError', result, nativeErrno);
+    }
+}
+exports.RequestError = RequestError;
+/** Thrown when receiving a message fails. */
+class RecvError extends ResultError {
+    constructor(result, nativeErrno = 0) {
+        super('RecvError', result, nativeErrno);
+    }
+}
+exports.RecvError = RecvError;
+/** Thrown when registering or running a callback handler fails. */
+class HandlerError extends ResultError {
+    constructor(result, nativeErrno = 0) {
+        super('HandlerError', result, nativeErrno);
+    }
+}
+exports.HandlerError = HandlerError;
+/** Thrown when closing a socket or resource fails. */
+class CloseError extends ResultError {
+    constructor(result, nativeErrno = 0) {
+        super('CloseError', result, nativeErrno);
+    }
+}
+exports.CloseError = CloseError;
+/** Thrown when binding a socket to an endpoint fails. */
+class BindError extends ResultError {
+    constructor(result, nativeErrno = 0) {
+        super('BindError', result, nativeErrno);
+    }
+}
+exports.BindError = BindError;
+/** Thrown when connecting a socket to an endpoint fails. */
+class ConnectError extends ResultError {
+    constructor(result, nativeErrno = 0) {
+        super('ConnectError', result, nativeErrno);
+    }
+}
+exports.ConnectError = ConnectError;
+/** Thrown when reading or applying a configuration option fails. */
+class ConfigError extends ResultError {
+    constructor(result, nativeErrno = 0) {
+        super('ConfigError', result, nativeErrno);
+    }
+}
+exports.ConfigError = ConfigError;

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

@@ -0,0 +1,2 @@
+export { ZlinkError, SubmitError, RequestError, RecvError, HandlerError, CloseError, BindError, ConnectError, ConfigError, } from './errors';
+export * from './results';

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

@@ -0,0 +1,29 @@
+"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.ConfigError = exports.ConnectError = exports.BindError = exports.CloseError = exports.HandlerError = exports.RecvError = exports.RequestError = exports.SubmitError = exports.ZlinkError = void 0;
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "ZlinkError", { enumerable: true, get: function () { return errors_1.ZlinkError; } });
+Object.defineProperty(exports, "SubmitError", { enumerable: true, get: function () { return errors_1.SubmitError; } });
+Object.defineProperty(exports, "RequestError", { enumerable: true, get: function () { return errors_1.RequestError; } });
+Object.defineProperty(exports, "RecvError", { enumerable: true, get: function () { return errors_1.RecvError; } });
+Object.defineProperty(exports, "HandlerError", { enumerable: true, get: function () { return errors_1.HandlerError; } });
+Object.defineProperty(exports, "CloseError", { enumerable: true, get: function () { return errors_1.CloseError; } });
+Object.defineProperty(exports, "BindError", { enumerable: true, get: function () { return errors_1.BindError; } });
+Object.defineProperty(exports, "ConnectError", { enumerable: true, get: function () { return errors_1.ConnectError; } });
+Object.defineProperty(exports, "ConfigError", { enumerable: true, get: function () { return errors_1.ConfigError; } });
+__exportStar(require("./results"), exports);

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

@@ -0,0 +1,106 @@
+/** The outcome of submitting a send or publish. */
+export declare const SubmitResult: Readonly<{
+    readonly Ok: 0;
+    readonly Backpressured: 1;
+    readonly NotConnected: 2;
+    readonly NotFound: 3;
+    readonly Terminated: 4;
+    readonly InvalidHandle: 5;
+    readonly InvalidArgument: 6;
+    readonly NotSupported: 7;
+    readonly InvalidState: 8;
+    readonly ThreadViolation: 9;
+    readonly OutOfMemory: 10;
+    readonly SeqExhausted: 11;
+    readonly InternalError: 12;
+    readonly NotAdmitted: 13;
+}>;
+export type SubmitResult = typeof SubmitResult[keyof typeof SubmitResult];
+/** The terminal outcome of a request completion. */
+export declare const RequestResult: Readonly<{
+    readonly Ok: 0;
+    readonly TimedOut: 101;
+    readonly NotFound: 102;
+    readonly Terminated: 103;
+    readonly ProtocolError: 104;
+    readonly InternalError: 105;
+    readonly Rejected: 106;
+    readonly Conflict: 107;
+    readonly Busy: 108;
+    readonly NotConnected: 109;
+    readonly InvalidArgument: 110;
+    readonly InvalidState: 111;
+    readonly NotSupported: 112;
+    readonly Backpressured: 113;
+}>;
+export type RequestResult = typeof RequestResult[keyof typeof RequestResult];
+/** The outcome of a receive. */
+export declare const RecvResult: Readonly<{
+    readonly Ok: 0;
+    readonly NoData: 201;
+    readonly Busy: 202;
+    readonly Terminated: 203;
+    readonly InvalidHandle: 204;
+    readonly NotSupported: 205;
+    readonly InternalError: 206;
+    readonly BufferTooSmall: 207;
+    readonly InvalidState: 208;
+}>;
+export type RecvResult = typeof RecvResult[keyof typeof RecvResult];
+/** The outcome of registering or running a callback handler. */
+export declare const HandlerResult: Readonly<{
+    readonly Ok: 0;
+    readonly InvalidArgument: 301;
+    readonly Busy: 302;
+    readonly NotSupported: 303;
+    readonly Deadlock: 304;
+    readonly InvalidHandle: 305;
+    readonly InternalError: 306;
+}>;
+export type HandlerResult = typeof HandlerResult[keyof typeof HandlerResult];
+/** The outcome of closing a socket or resource. */
+export declare const CloseResult: Readonly<{
+    readonly Ok: 0;
+    readonly Busy: 401;
+    readonly Shutdown: 402;
+    readonly InvalidHandle: 403;
+    readonly InternalError: 404;
+}>;
+export type CloseResult = typeof CloseResult[keyof typeof CloseResult];
+/** The outcome of binding to an endpoint. */
+export declare const BindResult: Readonly<{
+    readonly Ok: 0;
+    readonly InvalidArgument: 501;
+    readonly AddrInUse: 502;
+    readonly NotSupported: 503;
+    readonly InvalidHandle: 504;
+    readonly InternalError: 505;
+}>;
+export type BindResult = typeof BindResult[keyof typeof BindResult];
+/** The outcome of connecting to an endpoint. */
+export declare const ConnectResult: Readonly<{
+    readonly Ok: 0;
+    readonly InvalidArgument: 601;
+    readonly NotSupported: 602;
+    readonly InvalidHandle: 603;
+    readonly InternalError: 604;
+    readonly NotFound: 605;
+    readonly Conflict: 606;
+    readonly Busy: 607;
+    readonly AuthFailed: 608;
+}>;
+export type ConnectResult = typeof ConnectResult[keyof typeof ConnectResult];
+/** The outcome of reading or applying a configuration option. */
+export declare const ConfigResult: Readonly<{
+    readonly Ok: 0;
+    readonly InvalidHandle: 701;
+    readonly InvalidArgument: 702;
+    readonly NotSupported: 703;
+    readonly InternalError: 704;
+    readonly InvalidState: 705;
+    readonly NotFound: 706;
+    readonly Conflict: 707;
+    readonly BufferTooSmall: 708;
+    readonly Busy: 709;
+}>;
+export type ConfigResult = typeof ConfigResult[keyof typeof ConfigResult];

package/dist/zlink/contracts/errors/results.js

@@ -0,0 +1,102 @@
+"use strict";
+// SPDX-License-Identifier: MPL-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigResult = exports.ConnectResult = exports.BindResult = exports.CloseResult = exports.HandlerResult = exports.RecvResult = exports.RequestResult = exports.SubmitResult = void 0;
+/** The outcome of submitting a send or publish. */
+exports.SubmitResult = Object.freeze({
+    Ok: 0,
+    Backpressured: 1,
+    NotConnected: 2,
+    NotFound: 3,
+    Terminated: 4,
+    InvalidHandle: 5,
+    InvalidArgument: 6,
+    NotSupported: 7,
+    InvalidState: 8,
+    ThreadViolation: 9,
+    OutOfMemory: 10,
+    SeqExhausted: 11,
+    InternalError: 12,
+    NotAdmitted: 13
+});
+/** The terminal outcome of a request completion. */
+exports.RequestResult = Object.freeze({
+    Ok: 0,
+    TimedOut: 101,
+    NotFound: 102,
+    Terminated: 103,
+    ProtocolError: 104,
+    InternalError: 105,
+    Rejected: 106,
+    Conflict: 107,
+    Busy: 108,
+    NotConnected: 109,
+    InvalidArgument: 110,
+    InvalidState: 111,
+    NotSupported: 112,
+    Backpressured: 113
+});
+/** The outcome of a receive. */
+exports.RecvResult = Object.freeze({
+    Ok: 0,
+    NoData: 201,
+    Busy: 202,
+    Terminated: 203,
+    InvalidHandle: 204,
+    NotSupported: 205,
+    InternalError: 206,
+    BufferTooSmall: 207,
+    InvalidState: 208
+});
+/** The outcome of registering or running a callback handler. */
+exports.HandlerResult = Object.freeze({
+    Ok: 0,
+    InvalidArgument: 301,
+    Busy: 302,
+    NotSupported: 303,
+    Deadlock: 304,
+    InvalidHandle: 305,
+    InternalError: 306
+});
+/** The outcome of closing a socket or resource. */
+exports.CloseResult = Object.freeze({
+    Ok: 0,
+    Busy: 401,
+    Shutdown: 402,
+    InvalidHandle: 403,
+    InternalError: 404
+});
+/** The outcome of binding to an endpoint. */
+exports.BindResult = Object.freeze({
+    Ok: 0,
+    InvalidArgument: 501,
+    AddrInUse: 502,
+    NotSupported: 503,
+    InvalidHandle: 504,
+    InternalError: 505
+});
+/** The outcome of connecting to an endpoint. */
+exports.ConnectResult = Object.freeze({
+    Ok: 0,
+    InvalidArgument: 601,
+    NotSupported: 602,
+    InvalidHandle: 603,
+    InternalError: 604,
+    NotFound: 605,
+    Conflict: 606,
+    Busy: 607,
+    AuthFailed: 608
+});
+/** The outcome of reading or applying a configuration option. */
+exports.ConfigResult = Object.freeze({
+    Ok: 0,
+    InvalidHandle: 701,
+    InvalidArgument: 702,
+    NotSupported: 703,
+    InternalError: 704,
+    InvalidState: 705,
+    NotFound: 706,
+    Conflict: 707,
+    BufferTooSmall: 708,
+    Busy: 709
+});

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

@@ -0,0 +1,3 @@
+export * from './monitor';
+export * from './poller';
+export * from './timer';

package/dist/zlink/contracts/eventing/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("./monitor"), exports);
+__exportStar(require("./poller"), exports);
+__exportStar(require("./timer"), exports);

package/dist/zlink/contracts/eventing/monitor.d.ts

@@ -0,0 +1,157 @@
+import { RoutingId } from '../core';
+/** Identifies what a monitored source is. The Core raw API defines only the socket source. */
+export declare const MonitorSourceKind: Readonly<{
+    readonly Socket: 1;
+}>;
+export type MonitorSourceKindValue = typeof MonitorSourceKind[keyof typeof MonitorSourceKind];
+/** The kind of a delivered socket monitor connection-lifecycle event. */
+export declare const MonitorEventType: Readonly<{
+    readonly Connected: 1;
+    readonly ConnectDelayed: 2;
+    readonly ConnectRetried: 4;
+    readonly Listening: 8;
+    readonly BindFailed: 16;
+    readonly Accepted: 32;
+    readonly AcceptFailed: 64;
+    readonly Closed: 128;
+    readonly CloseFailed: 256;
+    readonly Disconnected: 512;
+    readonly MonitorStopped: 1024;
+    readonly HandshakeFailedNoDetail: 2048;
+    readonly ConnectionReady: 4096;
+    readonly HandshakeFailedProtocol: 8192;
+    readonly HandshakeFailedAuth: 16384;
+    readonly PeerWeightChanged: 32768;
+    /** A remote-PAUSE condition was first applied to an affected application pipe. */
+    readonly SendFlowPaused: 65536;
+    /** A remote-PAUSE condition was cleared on an affected application pipe. */
+    readonly SendFlowResumed: 131072;
+    /** A stale or duplicate receive-flow-state frame (old generation or non-advancing epoch) was ignored. */
+    readonly FlowStateStale: 262144;
+}>;
+export type MonitorEventType = typeof MonitorEventType[keyof typeof MonitorEventType];
+/**
+ * Bits carried in `MonitorEvent.flags`. Values match
+ * `ZLINK_MONITOR_EVENT_FLAG_*` in `zlink/eventing/api.h`.
+ */
+export declare const MonitorEventFlag: Readonly<{
+    /** Set on `ConnectionReady` when the connection changed from not-ready to ready. */
+    readonly ConnectionReadyEdge: 1;
+    /**
+     * Set on `SendFlowResumed` when clearing the remote pause left the pipe
+     * actually writable. `value` carries the flow epoch.
+     */
+    readonly SendFlowWritable: 2;
+    /**
+     * Set on `FlowStateStale` when the frame named a different connection
+     * generation. `value` carries the received generation.
+     */
+    readonly FlowStateStaleGeneration: 4;
+    /**
+     * Set on `FlowStateStale` when the epoch did not advance inside the
+     * current generation. `value` carries the received epoch.
+     */
+    readonly FlowStateStaleEpoch: 8;
+}>;
+export type MonitorEventFlag = typeof MonitorEventFlag[keyof typeof MonitorEventFlag];
+/**
+ * A snapshot of a monitored socket's state and auto-high-water-mark telemetry.
+ *
+ * `sourceKind` identifies the monitored source; `stateFlags`/`detailFlags` are
+ * bit masks of its current state; `snd/rcvPendingMsgs` and
+ * `snd/rcvPendingBytes` are queued message and byte counts;
+ * counts; and the `autoHwm*` fields report the automatic high-water-mark sizing
+ * decisions (applied marks, effective buffers, last recalculation, deferred
+ * shrinks).
+ */
+export interface MonitorStatus {
+    readonly abiVersion: number;
+    readonly structSize: number;
+    readonly sourceKind: MonitorSourceKindValue;
+    readonly stateFlags: number;
+    readonly detailFlags: number;
+    readonly sndPendingMsgs: bigint;
+    readonly rcvPendingMsgs: bigint;
+    readonly sndPendingBytes: bigint;
+    readonly rcvPendingBytes: bigint;
+    readonly autoHwmEnabled: boolean;
+    readonly autoHwmProfile: number;
+    readonly autoHwmRole: number;
+    readonly autoHwmPolicyClass: number;
+    readonly autoHwmPlannedSndHwmBytes: bigint;
+    readonly autoHwmPlannedRcvHwmBytes: bigint;
+    readonly autoHwmAppliedSndHwmBytes: bigint;
+    readonly autoHwmAppliedRcvHwmBytes: bigint;
+    readonly autoHwmEffectiveSndBuf: number;
+    readonly autoHwmEffectiveRcvBuf: number;
+    readonly autoHwmLastRecalcMs: bigint;
+    readonly autoHwmLastRecalcReason: number;
+    readonly autoHwmSendBlockedRatioPpm: number;
+    readonly autoHwmDeferredSndHwmBytes: bigint;
+    readonly autoHwmDeferredRcvHwmBytes: bigint;
+    readonly autoHwmDeferredSndHwmValid: boolean;
+    readonly autoHwmDeferredRcvHwmValid: boolean;
+    readonly sndBytesInFlight: bigint;
+    readonly rcvBytesInFlight: bigint;
+    readonly minimumCoreMessageChargeBytes: bigint;
+    readonly oversizeMessageAdmissionCount: bigint;
+    readonly oversizeMessageAdmissionMaxBytes: bigint;
+    /**
+     * DEALER/ROUTER receive-flow telemetry for affected application pipes
+     * (present since ABI 4). Populated only for DEALER/ROUTER sockets; other socket
+     * types report zero for all five fields.
+     */
+    /** Current count of application pipes this socket sees as remote-PAUSED. */
+    readonly flowPausedConnections: bigint;
+    /** Total PAUSED transitions actually applied (never a stale/duplicate). */
+    readonly flowPauseAppliedTotal: bigint;
+    /** Total RUNNING transitions actually applied (never a stale/duplicate). */
+    readonly flowResumeAppliedTotal: bigint;
+    /** Total stale or duplicate flow-state frames ignored. */
+    readonly flowStateStaleTotal: bigint;
+    /** Duration of the most recently completed PAUSED interval, in milliseconds. 0 if none has completed yet. */
+    readonly flowPauseDurationMs: bigint;
+    /** Whether the monitored socket is in the ready state. */
+    isReady(): boolean;
+    /**
+     * Whether `flowPausedConnections` and the other `flow*` fields are
+     * populated (ABI 4+, paired DEALER/ROUTER sockets only). Mirrors
+     * `ZLINK_MONITOR_STATUS_DETAIL_FLOW_STATE` in `zlink_enum.h`.
+     */
+    isFlowStateDetailPopulated(): boolean;
+}
+/** A single socket connection-lifecycle event reported by a monitor. */
+export declare class MonitorEvent {
+    /** The kind of lifecycle event. */
+    readonly event: MonitorEventType;
+    /**
+     * An event-specific value, such as an error code, reconnect interval, or
+     * (for the flow events) a generation/epoch counter. A full 64-bit unsigned
+     * value; use `bigint` arithmetic to read it losslessly.
+     */
+    readonly value: bigint;
+    /** The peer routing id, or null when the event carries none. */
+    readonly routingId: RoutingId | null;
+    /** The local endpoint address. */
+    readonly localAddr: string;
+    /** The remote endpoint address. */
+    readonly remoteAddr: string;
+    /** Process-local identity of the physical transport attempt. */
+    readonly connectionId: bigint;
+    /** The transport lane associated with the event: 0 Application, 1 Completion. */
+    readonly transportLane: number;
+    /** Event-specific flags, including the connection-ready edge flag. */
+    readonly flags: number;
+    private constructor();
+}
+/** Observes a socket's connection lifecycle events and current status. */
+export interface MonitorSocket {
+    /** Receive the next monitor event, or null when `DontWait` is set and none is available. */
+    recv(flags?: number): MonitorEvent | null;
+    /** Return a snapshot of the monitored socket's current status. */
+    status(): MonitorStatus;
+    /** Close the monitor and release its resources. */
+    close(): void;
+}
+/** Canonical socket-monitor name used by event-source APIs. */
+export type SocketMonitor = MonitorSocket;

package/dist/zlink/contracts/eventing/monitor.js

@@ -0,0 +1,82 @@
+"use strict";
+// SPDX-License-Identifier: MPL-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MonitorEvent = exports.MonitorEventFlag = exports.MonitorEventType = exports.MonitorSourceKind = void 0;
+/** Identifies what a monitored source is. The Core raw API defines only the socket source. */
+exports.MonitorSourceKind = Object.freeze({ Socket: 1 });
+/** The kind of a delivered socket monitor connection-lifecycle event. */
+exports.MonitorEventType = Object.freeze({
+    Connected: 0x0001,
+    ConnectDelayed: 0x0002,
+    ConnectRetried: 0x0004,
+    Listening: 0x0008,
+    BindFailed: 0x0010,
+    Accepted: 0x0020,
+    AcceptFailed: 0x0040,
+    Closed: 0x0080,
+    CloseFailed: 0x0100,
+    Disconnected: 0x0200,
+    MonitorStopped: 0x0400,
+    HandshakeFailedNoDetail: 0x0800,
+    ConnectionReady: 0x1000,
+    HandshakeFailedProtocol: 0x2000,
+    HandshakeFailedAuth: 0x4000,
+    PeerWeightChanged: 0x8000,
+    /** A remote-PAUSE condition was first applied to an affected application pipe. */
+    SendFlowPaused: 0x10000,
+    /** A remote-PAUSE condition was cleared on an affected application pipe. */
+    SendFlowResumed: 0x20000,
+    /** A stale or duplicate receive-flow-state frame (old generation or non-advancing epoch) was ignored. */
+    FlowStateStale: 0x40000
+});
+/**
+ * Bits carried in `MonitorEvent.flags`. Values match
+ * `ZLINK_MONITOR_EVENT_FLAG_*` in `zlink/eventing/api.h`.
+ */
+exports.MonitorEventFlag = Object.freeze({
+    /** Set on `ConnectionReady` when the connection changed from not-ready to ready. */
+    ConnectionReadyEdge: 0x1,
+    /**
+     * Set on `SendFlowResumed` when clearing the remote pause left the pipe
+     * actually writable. `value` carries the flow epoch.
+     */
+    SendFlowWritable: 0x2,
+    /**
+     * Set on `FlowStateStale` when the frame named a different connection
+     * generation. `value` carries the received generation.
+     */
+    FlowStateStaleGeneration: 0x4,
+    /**
+     * Set on `FlowStateStale` when the epoch did not advance inside the
+     * current generation. `value` carries the received epoch.
+     */
+    FlowStateStaleEpoch: 0x8
+});
+/** A single socket connection-lifecycle event reported by a monitor. */
+class MonitorEvent {
+    /** The kind of lifecycle event. */
+    event;
+    /**
+     * An event-specific value, such as an error code, reconnect interval, or
+     * (for the flow events) a generation/epoch counter. A full 64-bit unsigned
+     * value; use `bigint` arithmetic to read it losslessly.
+     */
+    value;
+    /** The peer routing id, or null when the event carries none. */
+    routingId;
+    /** The local endpoint address. */
+    localAddr;
+    /** The remote endpoint address. */
+    remoteAddr;
+    /** Process-local identity of the physical transport attempt. */
+    connectionId;
+    /** The transport lane associated with the event: 0 Application, 1 Completion. */
+    transportLane;
+    /** Event-specific flags, including the connection-ready edge flag. */
+    flags;
+    constructor() {
+        throw new TypeError('MonitorEvent values are created by monitor recv operations');
+    }
+}
+exports.MonitorEvent = MonitorEvent;
+Object.freeze(MonitorEvent);

package/dist/zlink/contracts/eventing/poller.d.ts

@@ -0,0 +1,76 @@
+import type { BaseSocket } from '../sockets';
+import type { PollEventFlagValue } from '../sockets/socket_constants';
+import type { SocketMonitor } from './monitor';
+import type { Timer } from './timer';
+/** A source that can be identified in a poll result; numbers are raw file descriptors. */
+export type Pollable = BaseSocket | SocketMonitor | Timer | number;
+/** One ready source reported by {@link Poller.wait}. */
+export interface PollEvent {
+    /** The registered object, or the raw file descriptor, that became ready. */
+    readonly source: Pollable;
+    /** Whether the ready source is a socket, file descriptor, or timer. */
+    readonly sourceKind: number;
+    /** The caller token supplied when the source was registered. */
+    readonly slot: number;
+    /** The events that fired, as a mask of poll flags. */
+    readonly revents: number;
+    /** The file descriptor, when the source is a raw fd. */
+    readonly fd: number;
+}
+/** A reusable buffer of poll results filled by {@link Poller.wait}. */
+export interface PollEvents {
+    /** The maximum number of results the buffer can hold. */
+    readonly capacity: number;
+    /** The number of ready sources written by the last wait. */
+    readonly readyCount: number;
+    /** The source kind of the result at `index`. */
+    sourceKind(index: number): number;
+    /** The registered object, or raw file descriptor, for the result at `index`. */
+    source(index: number): Pollable;
+    /** The caller token of the result at `index`. */
+    slot(index: number): number;
+    /** The fired-event mask of the result at `index`. */
+    revents(index: number): number;
+    /** The file descriptor of the result at `index`. */
+    fd(index: number): number;
+    /** Whether the result at `index` includes `event`. */
+    hasEvent(index: number, event: PollEventFlagValue): boolean;
+    /** Release the buffer. */
+    close(): void;
+}
+/** Multiplexes sockets, socket monitors, file descriptors, and timers. */
+export interface Poller {
+    /** The number of registered sources. */
+    readonly size: number;
+    /** Register `socket` to be watched for `events`; `slot` is echoed back in the matching result. */
+    add(socket: BaseSocket, events: readonly PollEventFlagValue[], slot: number): void;
+    /** Register `monitor`; socket monitors support `PollIn` only. */
+    add(monitor: SocketMonitor, events: readonly PollEventFlagValue[], slot: number): void;
+    /** Register `timer`; its expirations surface as poll events tagged with `slot`. */
+    add(timer: Timer, slot: number): void;
+    /** Change the watched events for an already-registered socket. */
+    modify(socket: BaseSocket, events: readonly PollEventFlagValue[]): void;
+    /** Change a monitor registration; socket monitors support `PollIn` only. */
+    modify(monitor: SocketMonitor, events: readonly PollEventFlagValue[]): void;
+    /** Unregister `socket`; return true when it was registered. */
+    remove(socket: BaseSocket): boolean;
+    /** Unregister `monitor`; return true when it was registered. */
+    remove(monitor: SocketMonitor): boolean;
+    /** Unregister `timer`; return true when it was registered. */
+    remove(timer: Timer): boolean;
+    /** Register raw file descriptor `fd` to be watched for `events`; `slot` is echoed back. */
+    addFd(fd: number, events: readonly PollEventFlagValue[], slot: number): void;
+    /** Change the watched events for an already-registered file descriptor. */
+    modifyFd(fd: number, events: readonly PollEventFlagValue[]): void;
+    /** Unregister file descriptor `fd`; return true when it was registered. */
+    removeFd(fd: number): boolean;
+    /**
+     * Wait up to `timeoutMs` for sources to become ready, filling `events`; a
+     * negative timeout blocks indefinitely. `PollOut` is the WRITABLE wake for
+     * managed sends; `PollCompletion` means the owned completion queue
+     * (REQUEST and any WRITABLE records) was drained.
+     */
+    wait(events: PollEvents, timeoutMs: number): number;
+    /** Close the poller and release its resources. */
+    close(): void;
+}

package/dist/zlink/contracts/eventing/poller.js

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