@zlink-systems/zlink 0.17.3

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

@@ -0,0 +1,38 @@
+/** A timer that fires on an interval and can be polled or awaited. */
+export interface Timer {
+    /** Start the timer firing once per `intervalNs` nanoseconds; `repeatCount` sets how many times it fires. */
+    start(intervalNs: bigint, repeatCount: bigint): void;
+    /** Stop the timer; it can be restarted with {@link Timer.start}. */
+    stop(): void;
+    /** Receive the next expiration as the cumulative fire count, or null when none is pending. */
+    recv(): bigint | null;
+    /** Close the timer and release its resources. */
+    close(): void;
+}
+/** A handle to a running background thread. */
+export interface Thread {
+    /** Block the caller until the thread finishes running its task. */
+    join(): void;
+}
+/** A high-resolution elapsed-time stopwatch. */
+export interface Stopwatch {
+    /** Return the elapsed time so far, in microseconds, without stopping. */
+    intermediate(): number;
+    /** Stop the stopwatch and return the total elapsed time in microseconds. */
+    stop(): number;
+    /** Release the stopwatch. */
+    close(): void;
+}
+/** A thread-safe integer counter that can be shared across threads. */
+export interface AtomicCounter {
+    /** Atomically set the value. */
+    set(value: number): void;
+    /** Atomically increment the counter and return the new value. */
+    inc(): number;
+    /** Atomically decrement the counter and return the new value. */
+    dec(): number;
+    /** Return the current value, read atomically. */
+    value(): number;
+    /** Release the counter. */
+    close(): void;
+}

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

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

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

@@ -0,0 +1,5 @@
+export * from './sockets';
+export * from './eventing';
+export * from './core';
+export * from './messaging';
+export * from './errors';

package/dist/zlink/contracts/index.js

@@ -0,0 +1,22 @@
+"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("./sockets"), exports);
+__exportStar(require("./eventing"), exports);
+__exportStar(require("./core"), exports);
+__exportStar(require("./messaging"), exports);
+__exportStar(require("./errors"), exports);

package/dist/zlink/contracts/messaging/handlers.d.ts

@@ -0,0 +1,5 @@
+/** One active subscription: a topic filter and whether it is a pattern. */
+export interface SubscriptionEntry {
+    readonly filter: string;
+    readonly isPattern: boolean;
+}

package/dist/zlink/contracts/messaging/handlers.js

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

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

@@ -0,0 +1,8 @@
+export { Message, } from './message';
+export type { MessageLike, } from './message';
+export { Received, ReplyToken, } from './received';
+export { StreamPacket } from './stream_packet';
+export { TopicMessage, } from './topic_message';
+export { SubscriptionEvent, } from './subscription_event';
+export type * from './operations';
+export type * from './handlers';

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

@@ -0,0 +1,15 @@
+"use strict";
+// SPDX-License-Identifier: MPL-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SubscriptionEvent = exports.TopicMessage = exports.StreamPacket = exports.ReplyToken = exports.Received = exports.Message = void 0;
+var message_1 = require("./message");
+Object.defineProperty(exports, "Message", { enumerable: true, get: function () { return message_1.Message; } });
+var received_1 = require("./received");
+Object.defineProperty(exports, "Received", { enumerable: true, get: function () { return received_1.Received; } });
+Object.defineProperty(exports, "ReplyToken", { enumerable: true, get: function () { return received_1.ReplyToken; } });
+var stream_packet_1 = require("./stream_packet");
+Object.defineProperty(exports, "StreamPacket", { enumerable: true, get: function () { return stream_packet_1.StreamPacket; } });
+var topic_message_1 = require("./topic_message");
+Object.defineProperty(exports, "TopicMessage", { enumerable: true, get: function () { return topic_message_1.TopicMessage; } });
+var subscription_event_1 = require("./subscription_event");
+Object.defineProperty(exports, "SubscriptionEvent", { enumerable: true, get: function () { return subscription_event_1.SubscriptionEvent; } });

package/dist/zlink/contracts/messaging/message.d.ts

@@ -0,0 +1,68 @@
+import type { BufferLike } from '../core/buffer_like';
+/** Reserved native metadata key range; metadata lookup is not implemented yet. */
+export declare const METADATA_KEY_USER_MIN = 256;
+/** Reserved native metadata value limit; metadata lookup is not implemented yet. */
+export declare const METADATA_VALUE_MAX = 65535;
+/**
+ * A message payload owned by this wrapper. The payload can use a JavaScript
+ * Buffer or native storage. A successful synchronous submit consumes the
+ * message. Managed async SEND also consumes it after taking a back-pressure
+ * snapshot, which can happen before the Promise resolves. `close` releases it.
+ * Do not use a reference after ownership transfers or after `close`, because
+ * the runtime may reuse the returned wrapper identity.
+ */
+export declare class Message {
+    private _buffer;
+    private _refCount;
+    private _properties;
+    /** Opaque owner when this message uses native storage. */
+    private _nativeMessage?;
+    /** True when a received frame remains movable until data() exposes it. */
+    private _nativeReadOnly;
+    /** True after ownership has ended and this facade has entered the pool. */
+    private _released;
+    /**
+     * Create a message holding an independent copy of `buffer` (a buffer-like
+     * value or another {@link Message}); the source may be freely reused
+     * afterward.
+     */
+    static from(buffer: BufferLike | Message): Message;
+    /** Allocate a message with `size` bytes of writable payload storage. */
+    static allocate(size: number): Message;
+    /** Return the payload as a Buffer backed by this message's storage. */
+    data(): Buffer;
+    /** Return a new Buffer copying the payload. */
+    toBytes(): Buffer;
+    /** Return a new message holding an independent copy of this payload. */
+    copy(): Message;
+    /** Return the payload size in bytes. */
+    size(): number;
+    /** Return true when the payload is empty. */
+    isEmpty(): boolean;
+    /**
+     * Copy the payload (or `length` bytes from `sourceOffset`) into `destination`
+     * at `destinationOffset`; return the number of bytes written. Throws
+     * {@link RangeError} when the range is out of bounds.
+     */
+    copyTo(destination: Buffer | Uint8Array, sourceOffset?: number, destinationOffset?: number, length?: number): number;
+    /**
+     * Copy the payload into `destination` when it fits; return true on success,
+     * or false when `destination` is too small.
+     */
+    tryCopyTo(destination: Buffer | Uint8Array): boolean;
+    /** Decode the payload as text using `encoding`. */
+    getString(encoding?: BufferEncoding): string;
+    /**
+     * Return the native message property `name`, or null when it is absent.
+     * Native message metadata is reserved in the current binding and is not
+     * populated yet, so public factory and receive paths currently return null.
+     */
+    getProperty(name: string): string | null;
+    /** Return the native payload reference count (a diagnostic only). */
+    refCount(): number;
+    /** Release native storage and return this wrapper; do not use it afterward. */
+    close(): void;
+    /** Return the payload decoded as a UTF-8 string. */
+    toString(): string;
+    private ensureBuffer;
+}

package/dist/zlink/contracts/messaging/message.js

@@ -0,0 +1,280 @@
+"use strict";
+// SPDX-License-Identifier: MPL-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Message = exports.METADATA_VALUE_MAX = exports.METADATA_KEY_USER_MIN = void 0;
+exports.configureMessageNativeOperations = configureMessageNativeOperations;
+exports.acquireMessageWrapper = acquireMessageWrapper;
+exports.refillMessageWrapper = refillMessageWrapper;
+exports.canShareNativeMessage = canShareNativeMessage;
+exports.hasObservedManagedReceiveData = hasObservedManagedReceiveData;
+exports.consumeSubmittedMessage = consumeSubmittedMessage;
+/** Reserved native metadata key range; metadata lookup is not implemented yet. */
+exports.METADATA_KEY_USER_MIN = 0x0100;
+/** Reserved native metadata value limit; metadata lookup is not implemented yet. */
+exports.METADATA_VALUE_MAX = 65535;
+const EMPTY_PROPERTIES = Object.freeze({});
+const EMPTY_METADATA = Object.freeze(new Map());
+const EMPTY_BUFFER = Buffer.alloc(0);
+const MESSAGE_WRAPPER_POOL_CAPACITY = 64;
+const messageWrapperPool = [];
+let nativeOperations;
+/** @internal Configure the runtime operations hidden behind the Message contract. */
+function configureMessageNativeOperations(operations) {
+    nativeOperations = operations;
+}
+function requireMessageNativeOperations() {
+    if (!nativeOperations) {
+        throw new Error('Message native operations are not configured');
+    }
+    return nativeOperations;
+}
+function normalizeMessageProperties(properties) {
+    if (!properties) {
+        return EMPTY_PROPERTIES;
+    }
+    return Object.isFrozen(properties) ? properties : Object.freeze(properties);
+}
+function normalizeBufferLike(value, label = 'value') {
+    if (Buffer.isBuffer(value)) {
+        return value;
+    }
+    if (value instanceof Uint8Array) {
+        return Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+    }
+    if (typeof value === 'string') {
+        return Buffer.from(value);
+    }
+    throw new TypeError(`${label} must be Buffer, Uint8Array, or string`);
+}
+/**
+ * A message payload owned by this wrapper. The payload can use a JavaScript
+ * Buffer or native storage. A successful synchronous submit consumes the
+ * message. Managed async SEND also consumes it after taking a back-pressure
+ * snapshot, which can happen before the Promise resolves. `close` releases it.
+ * Do not use a reference after ownership transfers or after `close`, because
+ * the runtime may reuse the returned wrapper identity.
+ */
+class Message {
+    _buffer;
+    _refCount;
+    _properties;
+    /** Opaque owner when this message uses native storage. */
+    _nativeMessage;
+    /** True when a received frame remains movable until data() exposes it. */
+    _nativeReadOnly;
+    /** True after ownership has ended and this facade has entered the pool. */
+    _released;
+    /**
+     * Create a message holding an independent copy of `buffer` (a buffer-like
+     * value or another {@link Message}); the source may be freely reused
+     * afterward.
+     */
+    static from(buffer) {
+        const source = buffer instanceof Message
+            ? buffer.ensureBuffer()
+            : normalizeBufferLike(buffer, 'data');
+        const nativeMessage = requireMessageNativeOperations().fromBuffer(source);
+        return acquireMessageWrapper(nativeMessage.data, 1, undefined, nativeMessage.nativeMessage);
+    }
+    /** Allocate a message with `size` bytes of writable payload storage. */
+    static allocate(size) {
+        if (!Number.isSafeInteger(size) || size < 0) {
+            throw new RangeError('size must be a non-negative safe integer');
+        }
+        const nativeMessage = requireMessageNativeOperations().allocate(size);
+        return acquireMessageWrapper(nativeMessage.data, 1, undefined, nativeMessage.nativeMessage);
+    }
+    /** Return the payload as a Buffer backed by this message's storage. */
+    data() {
+        return this.ensureBuffer();
+    }
+    /** Return a new Buffer copying the payload. */
+    toBytes() {
+        return Buffer.from(this.ensureBuffer());
+    }
+    /** Return a new message holding an independent copy of this payload. */
+    copy() {
+        return Message.from(this);
+    }
+    /** Return the payload size in bytes. */
+    size() {
+        if (this._buffer !== undefined) {
+            return this._buffer.length;
+        }
+        if (this._nativeMessage !== undefined) {
+            return requireMessageNativeOperations().size(this._nativeMessage);
+        }
+        return 0;
+    }
+    /** Return true when the payload is empty. */
+    isEmpty() {
+        return this.size() === 0;
+    }
+    /**
+     * Copy the payload (or `length` bytes from `sourceOffset`) into `destination`
+     * at `destinationOffset`; return the number of bytes written. Throws
+     * {@link RangeError} when the range is out of bounds.
+     */
+    copyTo(destination, sourceOffset = 0, destinationOffset = 0, length = this.size() - sourceOffset) {
+        if (!Buffer.isBuffer(destination) && !(destination instanceof Uint8Array)) {
+            throw new TypeError('destination must be a Buffer or Uint8Array');
+        }
+        if (!Number.isSafeInteger(sourceOffset)
+            || sourceOffset < 0
+            || !Number.isSafeInteger(destinationOffset)
+            || destinationOffset < 0
+            || !Number.isSafeInteger(length)
+            || length < 0
+            || sourceOffset + length > this.size()
+            || destinationOffset + length > destination.byteLength) {
+            throw new RangeError('copy range is out of bounds');
+        }
+        const target = Buffer.isBuffer(destination)
+            ? destination
+            : Buffer.from(destination.buffer, destination.byteOffset, destination.byteLength);
+        return this.ensureBuffer().copy(target, destinationOffset, sourceOffset, sourceOffset + length);
+    }
+    /**
+     * Copy the payload into `destination` when it fits; return true on success,
+     * or false when `destination` is too small.
+     */
+    tryCopyTo(destination) {
+        if (destination.byteLength < this.size()) {
+            return false;
+        }
+        this.copyTo(destination);
+        return true;
+    }
+    /** Decode the payload as text using `encoding`. */
+    getString(encoding = 'utf8') {
+        return this.ensureBuffer().toString(encoding);
+    }
+    /**
+     * Return the native message property `name`, or null when it is absent.
+     * Native message metadata is reserved in the current binding and is not
+     * populated yet, so public factory and receive paths currently return null.
+     */
+    getProperty(name) {
+        if (typeof name !== 'string') {
+            throw new TypeError('property name must be a string');
+        }
+        return Object.prototype.hasOwnProperty.call(this._properties, name)
+            ? this._properties[name]
+            : null;
+    }
+    /** Return the native payload reference count (a diagnostic only). */
+    refCount() {
+        return this._refCount;
+    }
+    /** Release native storage and return this wrapper; do not use it afterward. */
+    close() {
+        if (this._released) {
+            return;
+        }
+        if (this._nativeMessage !== undefined) {
+            requireMessageNativeOperations().close(this._nativeMessage);
+        }
+        releaseMessageWrapper(this);
+    }
+    /** Return the payload decoded as a UTF-8 string. */
+    toString() {
+        return this.getString();
+    }
+    ensureBuffer() {
+        if (this._buffer !== undefined) {
+            return this._buffer;
+        }
+        if (this._nativeMessage === undefined) {
+            return EMPTY_BUFFER;
+        }
+        const nativeMessage = this._nativeMessage;
+        const operations = requireMessageNativeOperations();
+        if (this._nativeReadOnly) {
+            // Router receive storage is movable until JavaScript observes it. Once
+            // exposed, materialize a managed Buffer and release the native frame.
+            this._buffer = operations.copyData(nativeMessage);
+            operations.close(nativeMessage);
+            this._nativeMessage = undefined;
+            this._nativeReadOnly = false;
+            return this._buffer;
+        }
+        this._buffer = operations.data(nativeMessage);
+        return this._buffer;
+    }
+}
+exports.Message = Message;
+/** @internal Acquire a Message facade for runtime-owned receive state. */
+function acquireMessageWrapper(buffer, refCount = 1, properties, nativeMessage, metadata, nativeReadOnly = false) {
+    const message = messageWrapperPool.pop()
+        ?? Object.create(Message.prototype);
+    const state = message;
+    state._buffer = buffer;
+    state._refCount = refCount | 0;
+    state._properties = normalizeMessageProperties(properties);
+    state._metadata = metadata ?? EMPTY_METADATA;
+    state._nativeMessage = nativeMessage;
+    state._nativeReadOnly = nativeReadOnly;
+    state._released = false;
+    return message;
+}
+/** @internal Refill an exclusively owned receive wrapper without pool traffic. */
+function refillMessageWrapper(message, buffer, nativeMessage) {
+    const state = message;
+    if (state._nativeMessage !== undefined && state._nativeMessage !== nativeMessage) {
+        requireMessageNativeOperations().close(state._nativeMessage);
+    }
+    state._buffer = buffer;
+    state._refCount = 1;
+    state._properties = EMPTY_PROPERTIES;
+    state._metadata = EMPTY_METADATA;
+    state._nativeMessage = nativeMessage;
+    state._nativeReadOnly = false;
+    state._released = false;
+    return message;
+}
+function releaseMessageWrapper(message) {
+    const state = message;
+    if (state._released) {
+        return;
+    }
+    state._buffer = EMPTY_BUFFER;
+    state._refCount = 0;
+    state._properties = EMPTY_PROPERTIES;
+    state._metadata = EMPTY_METADATA;
+    state._nativeMessage = undefined;
+    state._nativeReadOnly = false;
+    state._released = true;
+    if (messageWrapperPool.length < MESSAGE_WRAPPER_POOL_CAPACITY) {
+        messageWrapperPool.push(message);
+    }
+}
+function markMessageConsumed(message) {
+    const state = message;
+    state._buffer = EMPTY_BUFFER;
+    state._refCount = 0;
+    state._properties = EMPTY_PROPERTIES;
+    state._metadata = EMPTY_METADATA;
+    state._nativeMessage = undefined;
+    state._nativeReadOnly = false;
+}
+/** @internal */
+function canShareNativeMessage(message) {
+    const state = message;
+    return state._nativeMessage !== undefined;
+}
+/** @internal True when receive data was observed and remains in managed storage. */
+function hasObservedManagedReceiveData(message) {
+    const state = message;
+    return state._buffer !== undefined
+        && state._nativeMessage === undefined
+        && state._refCount > 0
+        && !state._released;
+}
+/** @internal Mark a message whose ownership transferred to an operation empty. */
+function consumeSubmittedMessage(message) {
+    const state = message;
+    if (state._nativeMessage !== undefined) {
+        requireMessageNativeOperations().close(state._nativeMessage);
+    }
+    markMessageConsumed(message);
+}

package/dist/zlink/contracts/messaging/message_parts_envelope.d.ts

@@ -0,0 +1,14 @@
+import { Message } from './message';
+export declare abstract class MessagePartsEnvelope {
+    /** The message parts, owned by this envelope. */
+    parts: Message[];
+    protected constructor();
+    /** Return true when the envelope holds exactly one part. */
+    isSinglePart(): boolean;
+    /** Return the first part without transferring ownership; throws when the envelope has no parts. */
+    firstPart(): Message;
+    /** Return the only part; throws unless the envelope holds exactly one part. */
+    singlePartOrThrow(): Message;
+    /** Close every part, releasing their storage. */
+    close(): void;
+}

package/dist/zlink/contracts/messaging/message_parts_envelope.js

@@ -0,0 +1,56 @@
+"use strict";
+// SPDX-License-Identifier: MPL-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MessagePartsEnvelope = void 0;
+const errors_1 = require("../errors/errors");
+function freezeMessageParts(parts) {
+    return Object.freeze(parts.slice());
+}
+const EMPTY_MESSAGE_PARTS = freezeMessageParts([]);
+function invalidMultipartError(partsLength) {
+    const error = new errors_1.RecvError(errors_1.RecvResult.NotSupported, 0);
+    error.message = `expected exactly 1 part but received ${partsLength}`;
+    return error;
+}
+function missingPartError() {
+    const error = new errors_1.RecvError(errors_1.RecvResult.NotSupported, 0);
+    error.message = 'message has no parts';
+    return error;
+}
+class MessagePartsEnvelope {
+    /** The message parts, owned by this envelope. */
+    parts;
+    constructor() {
+        this.parts = EMPTY_MESSAGE_PARTS;
+    }
+    /** Return true when the envelope holds exactly one part. */
+    isSinglePart() {
+        return this.parts.length === 1;
+    }
+    /** Return the first part without transferring ownership; throws when the envelope has no parts. */
+    firstPart() {
+        if (this.parts.length === 0) {
+            throw missingPartError();
+        }
+        return this.parts[0];
+    }
+    /** Return the only part; throws unless the envelope holds exactly one part. */
+    singlePartOrThrow() {
+        if (!this.isSinglePart()) {
+            throw invalidMultipartError(this.parts.length);
+        }
+        return this.parts[0];
+    }
+    /** Close every part, releasing their storage. */
+    close() {
+        try {
+            for (const part of this.parts) {
+                part.close();
+            }
+        }
+        finally {
+            this.parts = EMPTY_MESSAGE_PARTS;
+        }
+    }
+}
+exports.MessagePartsEnvelope = MessagePartsEnvelope;

package/dist/zlink/contracts/messaging/operations.d.ts

@@ -0,0 +1,54 @@
+import type { Message, MessageLike } from './message';
+/** Builder stage that accepts one message part and returns the next stage. */
+export interface PartBuilder<TNext> {
+    /** Add one message part; its terminal method defines when ownership transfers. */
+    message(message: MessageLike): TNext;
+}
+/** Builder stage that sets an operation timeout and returns the next stage. */
+export interface Timeoutable<TNext> {
+    /** Set how long the operation waits before timing out. */
+    timeout(timeoutMs: number): TNext;
+}
+/** Builds a multipart send with managed nonblocking back-pressure retry. */
+export interface SendOperation extends PartBuilder<SendSubmitOperation> {
+}
+/** Accepts further parts and the synchronous or Promise terminal. */
+export interface SendSubmitOperation extends PartBuilder<SendSubmitOperation> {
+    /**
+     * Resolve after admission. On back-pressure the runtime waits for the exact
+     * WRITABLE token and retries an owned packet snapshot. Message ownership
+     * transfers on immediate admission or after the first back-pressure snapshot,
+     * which can occur before this Promise resolves. Terminal failures reject.
+     */
+    submit(): Promise<void>;
+    /** Submit synchronously with Core blocking admission semantics. */
+    submit_sync(): void;
+}
+/** Builds a synchronous lossy PUB/XPUB publish. */
+export interface PublishOperation extends PartBuilder<PublishSubmitOperation> {
+}
+/** PUB/XPUB submit is void-or-throw; Core owns lossy/NODROP behavior. */
+export interface PublishSubmitOperation extends PartBuilder<PublishSubmitOperation> {
+    submit(): void;
+}
+/** Builds a request: add the request parts, then submit and await a reply. */
+export interface RequestOperation extends PartBuilder<RequestSubmitOperation> {
+}
+/** Accepts further parts, reply timeout, and the two request terminals. */
+export interface RequestSubmitOperation extends PartBuilder<RequestSubmitOperation>, Timeoutable<RequestSubmitOperation> {
+    /**
+     * Submit the request and return the caller-owned reply parts. Backpressure
+     * waits for this request's WRITABLE token before resubmitting the same packet;
+     * the reply timeout starts only after admission.
+     */
+    submit(): Promise<Message[]>;
+    submit_sync(): Message[];
+}
+/** Builds a reply to a received request: add the reply parts, then submit. */
+export interface ReplyOperation extends PartBuilder<ReplySubmitOperation> {
+}
+/** Accepts further parts and the flag-free synchronous reply terminal. */
+export interface ReplySubmitOperation extends PartBuilder<ReplySubmitOperation> {
+    /** Submit the accumulated reply parts. */
+    submit(): void;
+}

package/dist/zlink/contracts/messaging/operations.js

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

package/dist/zlink/contracts/messaging/received.d.ts

@@ -0,0 +1,41 @@
+import type { ReplyOperation, SendOperation } from './operations';
+import { RoutingId } from '../core/routing_id';
+import { MessagePartsEnvelope } from './message_parts_envelope';
+/** Opaque capability required to reply to one ROUTER request. */
+export declare class ReplyToken {
+    #private;
+    private constructor();
+    equals(other: ReplyToken): boolean;
+    hashCode(): number;
+    toString(): 'ReplyToken';
+}
+/**
+ * A received message envelope: its routing metadata and message parts, plus an
+ * optional reply/send context.
+ *
+ * Owns its parts until closed. Reuse one instance across `recv` calls to avoid
+ * a per-receive allocation.
+ */
+export declare class Received extends MessagePartsEnvelope {
+    /** The source routing id, or null when the receive path provides none. */
+    routingId: RoutingId | null;
+    /** Opaque reply capability, present only for a ROUTER REQUEST receive. */
+    replyToken: ReplyToken | null;
+    private _replyContext;
+    private _sendContext;
+    /** Create an empty reusable envelope for use with `recv`. */
+    constructor(...args: never[]);
+    /**
+     * Begin a reply to this request: add parts on the returned builder, then
+     * submit. Parts are consumed on a successful submit. Throws when the envelope
+     * is not replyable (has no reply token).
+     */
+    reply(): ReplyOperation;
+    /**
+     * Begin a send addressed to this envelope's source route: add parts, then
+     * submit. Message ownership transfers on immediate admission or after the
+     * managed send takes its first back-pressure snapshot, before the Promise may
+     * resolve. Throws when the envelope carries no send context.
+     */
+    send(): SendOperation;
+}