@cosyte/mllp 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,3112 @@
+import { T as Transport } from './index-DjGQJtYE.js';
+import { EventEmitter } from 'node:events';
+import { Socket } from 'node:net';
+import { TLSSocket } from 'node:tls';
+
+/**
+ * MLLP warning code registry and `MllpWarning` factory.
+ *
+ * `WarningCode` is a **stable public API**. Renaming or removing a code is a breaking change.
+ * New codes may only be added in minor versions.
+ *
+ * @example
+ * ```typescript
+ * import { createWarning, type MllpWarning, type WarningCode } from '@cosyte/mllp';
+ * const w: MllpWarning = createWarning('MLLP_EMPTY_PAYLOAD', 128, 'Empty payload between VT and FS');
+ * ```
+ *
+ * @packageDocumentation
+ */
+/**
+ * Union of all stable MLLP warning codes.
+ *
+ * These codes are a **public API** — they appear in `onWarning` handlers, log pipelines,
+ * monitoring dashboards, and error messages. Renaming is a breaking change.
+ *
+ * @example
+ * ```typescript
+ * const code: WarningCode = 'MLLP_FS_WITHOUT_CR';
+ * ```
+ */
+type WarningCode = "MLLP_MISSING_LEADING_VT" | "MLLP_FS_WITHOUT_CR" | "MLLP_LF_AFTER_FS" | "MLLP_LEADING_WHITESPACE" | "MLLP_TRAILING_BYTES" | "MLLP_PAYLOAD_CONTAINS_VT" | "MLLP_PAYLOAD_CONTAINS_FS" | "MLLP_EMPTY_PAYLOAD" | "MLLP_FRAME_TOO_LARGE" | "MLLP_ACK_UNMATCHED_CONTROL_ID" | "MLLP_ACK_AFTER_TIMEOUT";
+/**
+ * A frozen warning object emitted when the decoder tolerates a framing deviation.
+ *
+ * `connectionId` is `undefined` when emitted by a standalone `FrameReader` (Phase 2).
+ * Phase 3 `Connection` enriches it to the real UUIDv4 before forwarding upstream.
+ *
+ * @example
+ * ```typescript
+ * const reader = new FrameReader({
+ *   onFrame: (p) => process(p),
+ *   onWarning: (w: MllpWarning) => logger.warn(w),
+ *   allowFsOnly: true,
+ * });
+ * ```
+ */
+interface MllpWarning {
+    readonly code: WarningCode;
+    /** Stable human-readable description. Never contains payload bytes or secrets. */
+    readonly message: string;
+    /** Absolute stream byte offset where the anomaly was detected. */
+    readonly byteOffset: number;
+    /**
+     * Connection identifier. `undefined` at the framing layer;
+     * enriched by Phase 3 `Connection` before emitting upstream.
+     */
+    readonly connectionId: string | undefined;
+    /** Wall-clock time at point of emission. */
+    readonly timestamp: Date;
+}
+/**
+ * Create a frozen `MllpWarning` object. The returned object is `Object.freeze()`'d
+ * so subscribers cannot mutate shared warning state.
+ *
+ * `connectionId` is always `undefined` here — Phase 3 enriches via
+ * `{ ...w, connectionId: this.connectionId }` then re-freezes (D-08).
+ *
+ * @example
+ * ```typescript
+ * const w = createWarning('MLLP_EMPTY_PAYLOAD', 64, 'Empty payload between VT and FS');
+ * // w.connectionId === undefined
+ * ```
+ */
+declare function createWarning(code: WarningCode, byteOffset: number, message: string): MllpWarning;
+
+/**
+ * Typed framing error class for unrecoverable MLLP wire-format violations.
+ *
+ * @example
+ * ```typescript
+ * import { MllpFramingError } from '@cosyte/mllp';
+ * try {
+ *   encodeFrame(payloadWithVt);
+ * } catch (err) {
+ *   if (err instanceof MllpFramingError) {
+ *     logger.error({ code: err.code, offset: err.byteOffset });
+ *   }
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Thrown for unrecoverable MLLP wire-format violations.
+ *
+ * - `code` — stable `WarningCode` identifying the violation
+ * - `byteOffset` — absolute stream position where the violation was detected
+ * - `snippet` — the single framing-boundary byte that broke the structure, or empty when the
+ *   anomaly is not a specific byte. **Never a run of payload content** (see the `snippet` PHI
+ *   contract below); the constructor caps whatever it is given to 64 bytes as a backstop.
+ *
+ * @example
+ * ```typescript
+ * // Pass only the offending framing-boundary byte — never a slice of payload content.
+ * throw new MllpFramingError('MLLP_MISSING_LEADING_VT', byteOffset, Buffer.from([byte]));
+ * ```
+ */
+declare class MllpFramingError extends Error {
+    readonly name: "MllpFramingError";
+    /** Stable warning code identifying the violation type. */
+    readonly code: WarningCode;
+    /** Absolute byte offset in the stream where the error was detected. */
+    readonly byteOffset: number;
+    /**
+     * Up to 64 bytes copied from around the anomaly.
+     *
+     * This is a **copied** Buffer — isolated from the source buffer so it remains
+     * valid after the underlying buffer is reused or overwritten.
+     *
+     * **PHI contract (MLLP-9):** the decoder only ever populates this with the single
+     * framing-boundary byte that violated the frame structure (whose hex value the
+     * `message` already discloses) — never a run of payload content bytes. For anomalies
+     * whose fault is not a specific byte (`MLLP_FRAME_TOO_LARGE` — the accumulated size),
+     * the snippet is **empty**: a payload slice on a public error field would leak a
+     * field-body slice of clinical content. Callers constructing this directly are
+     * responsible for the same discipline.
+     */
+    readonly snippet: Buffer;
+    /**
+     * Construct an MLLP framing error.
+     *
+     * @param code - The stable warning code classifying the violation.
+     * @param byteOffset - Absolute stream byte offset where the violation was detected.
+     * @param snippet - Raw bytes copied from around the anomaly (capped to 64 bytes).
+     * @param message - Optional human-readable override message.
+     */
+    constructor(code: WarningCode, byteOffset: number, 
+    /** Raw bytes around the anomaly. Capped to MAX_SNIPPET_BYTES (64). */
+    snippet: Buffer, message?: string);
+}
+
+/**
+ * MLLP frame encoder — canonical `VT + payload + FS + CR` wrapping.
+ *
+ * The encoder is a **strict emitter** (Postel's Law: conservative on write).
+ * There is no option to loosen the output format — it always emits canonical framing.
+ * Tolerance for delimiter bytes in the payload is available via `allowDelimiterBytesInPayload`,
+ * which passes bytes through verbatim and emits an `MllpWarning` for each offending byte.
+ *
+ * @example
+ * ```typescript
+ * import { encodeFrame } from '@cosyte/mllp';
+ * const frame = encodeFrame(Buffer.from('MSH|^~\\&|...'));
+ * // frame[0] === 0x0B (VT), frame[frame.length - 2] === 0x1C (FS), frame[frame.length - 1] === 0x0D (CR)
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Options for {@link encodeFrame}.
+ *
+ * @example
+ * ```typescript
+ * const frame = encodeFrame(payload, {
+ *   allowDelimiterBytesInPayload: true,
+ *   onWarning: (w) => logger.warn(w),
+ * });
+ * ```
+ */
+interface EncoderOptions {
+    /**
+     * When `true`, VT (0x0B) or FS (0x1C) bytes within the payload are preserved
+     * verbatim in the output frame instead of throwing `MllpFramingError`.
+     * An `MllpWarning` is emitted per offending byte if `onWarning` is provided.
+     *
+     * Default: `false` (strict — throws on delimiter bytes).
+     */
+    allowDelimiterBytesInPayload?: boolean;
+    /**
+     * Called for each offending delimiter byte when `allowDelimiterBytesInPayload` is `true`.
+     * Invocation is wrapped in try/catch — a throwing handler does not interrupt encoding (WARN-06).
+     *
+     * @example
+     * ```typescript
+     * const frame = encodeFrame(payload, {
+     *   allowDelimiterBytesInPayload: true,
+     *   onWarning: (w) => logger.warn({ code: w.code, offset: w.byteOffset }),
+     * });
+     * ```
+     */
+    onWarning?: (w: MllpWarning) => void;
+}
+/**
+ * Encode `payload` in canonical MLLP framing: `VT (0x0B) + payload + FS (0x1C) + CR (0x0D)`.
+ *
+ * Strict by default: throws `MllpFramingError` if the payload contains VT or FS bytes.
+ * Set `{ allowDelimiterBytesInPayload: true }` to pass those bytes through verbatim
+ * and receive an `MllpWarning` per offending byte via `onWarning` instead.
+ *
+ * The returned Buffer has length `payload.length + 3`. Bytes at positions 1 through
+ * `payload.length` are an exact copy of the payload (independent of the input buffer).
+ *
+ * @throws {MllpFramingError} with code `MLLP_PAYLOAD_CONTAINS_VT` when payload contains
+ *   byte `0x0B` and `allowDelimiterBytesInPayload` is `false` (default).
+ * @throws {MllpFramingError} with code `MLLP_PAYLOAD_CONTAINS_FS` when payload contains
+ *   byte `0x1C` and `allowDelimiterBytesInPayload` is `false` (default).
+ *
+ * @example
+ * ```typescript
+ * import { encodeFrame } from '@cosyte/mllp';
+ *
+ * // Strict (default) — throws on delimiter bytes in payload
+ * const frame = encodeFrame(Buffer.from('MSH|^~\\&|SEND|FAC|RECV|FAC|...'));
+ * socket.write(frame);
+ *
+ * // Tolerant — passes delimiter bytes through with a warning
+ * const frame2 = encodeFrame(dirtyPayload, {
+ *   allowDelimiterBytesInPayload: true,
+ *   onWarning: (w) => logger.warn(w),
+ * });
+ * ```
+ */
+declare function encodeFrame(payload: Buffer, opts?: EncoderOptions): Buffer;
+
+/**
+ * MLLP frame decoder — stateful 3-state FSM for chunked byte-stream parsing.
+ *
+ * Feed raw TCP chunks via `push(chunk)`. Complete MLLP frames fire synchronously
+ * via the `onFrame` callback during each `push()` call.
+ *
+ * The decoder is **strict by default**: any framing deviation throws `MllpFramingError`
+ * unless the matching tolerance option is explicitly enabled (Postel's Law — liberal receiver
+ * means explicit tolerance, not silent acceptance).
+ *
+ * @example
+ * ```typescript
+ * import { FrameReader } from '@cosyte/mllp';
+ * const reader = new FrameReader({
+ *   onFrame: (payload) => handleMessage(payload),
+ *   onWarning: (w) => logger.warn(w),
+ *   allowFsOnly: true,
+ * });
+ * socket.on('data', (chunk) => reader.push(chunk));
+ * socket.on('close', () => reader.reset());
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Options for `FrameReader`.
+ *
+ * All tolerance opts default to `false` — every framing deviation throws unless
+ * explicitly enabled. Server-level defaults (allowFsOnly, allowLfAfterFs, allowLeadingWhitespace)
+ * are applied by Phase 4 when constructing readers per SERVER-12.
+ *
+ * @example
+ * ```typescript
+ * const opts: FrameReaderOptions = {
+ *   onFrame: (payload, byteOffset, warnings) => process(payload, byteOffset, warnings),
+ *   onWarning: (w) => logger.warn(w),
+ *   maxFrameSizeBytes: 4 * 1024 * 1024, // 4 MiB limit
+ *   allowFsOnly: true,
+ *   allowLfAfterFs: true,
+ * };
+ * ```
+ */
+interface FrameReaderOptions {
+    /**
+     * Called synchronously during `push()` for each complete MLLP payload.
+     *
+     * @param payload - Raw MLLP payload bytes (framing stripped).
+     * @param byteOffset - Stream byte offset of the VT byte that opened this frame.
+     *   Monotonic across the connection lifetime; reset to 0 by `reset()`.
+     * @param warnings - Framing warnings emitted during decoding of this specific frame.
+     *   Empty array when no tolerance deviations were detected.
+     */
+    onFrame: (payload: Buffer, byteOffset: number, warnings: readonly MllpWarning[]) => void;
+    /**
+     * Called for each tolerated framing deviation. Wrapped in try/catch per WARN-06.
+     * A throwing handler will not corrupt FSM state.
+     */
+    onWarning?: (w: MllpWarning) => void;
+    /**
+     * Maximum accumulated payload bytes before `MllpFramingError('MLLP_FRAME_TOO_LARGE')`.
+     * Default: 16 MiB (FRAME-11 DoS prevention).
+     */
+    maxFrameSizeBytes?: number;
+    /** FRAME-07: Tolerate FS without trailing CR; emits `MLLP_FS_WITHOUT_CR`. */
+    allowFsOnly?: boolean;
+    /** FRAME-08: Tolerate FS+LF instead of FS+CR; emits `MLLP_LF_AFTER_FS`. */
+    allowLfAfterFs?: boolean;
+    /** FRAME-09: Tolerate missing leading VT; emits `MLLP_MISSING_LEADING_VT`. */
+    allowMissingLeadingVt?: boolean;
+    /** FRAME-10: Tolerate SP/TAB/LF/CR before VT; emits `MLLP_LEADING_WHITESPACE`. */
+    allowLeadingWhitespace?: boolean;
+    /**
+     * When `true`, escalates the following tolerances to thrown `MllpFramingError`
+     * even if individual opt-ins (`allowFsOnly`, `allowLfAfterFs`, `allowMissingLeadingVt`,
+     * `allowLeadingWhitespace`) are enabled (WARN-08):
+     * - `MLLP_MISSING_LEADING_VT`
+     * - `MLLP_FS_WITHOUT_CR`
+     * - `MLLP_LF_AFTER_FS`
+     * - `MLLP_LEADING_WHITESPACE` (leading whitespace escalates as `MLLP_MISSING_LEADING_VT`)
+     *
+     * `MLLP_EMPTY_PAYLOAD` and `MLLP_TRAILING_BYTES` remain warnings even in strict mode.
+     *
+     * @example
+     * ```typescript
+     * // Hardened enforcement — no tolerance, all violations throw
+     * const reader = new FrameReader({ onFrame: fn, strict: true });
+     * ```
+     */
+    strict?: boolean;
+}
+/**
+ * Stateful MLLP frame decoder. Feed raw TCP byte chunks via `push(chunk)`.
+ * Complete frames fire synchronously via `onFrame` callback during `push()`.
+ *
+ * The decoder operates as a 3-state FSM:
+ * - `SCANNING_FOR_VT` — waiting for the 0x0B frame-start byte
+ * - `READING_PAYLOAD` — accumulating payload bytes until FS (0x1C)
+ * - `EXPECTING_CR` — received FS, waiting for CR (0x0D) to complete the frame
+ *
+ * @example
+ * ```typescript
+ * const reader = new FrameReader({
+ *   onFrame: (payload, byteOffset, warnings) => process(payload, byteOffset, warnings),
+ *   onWarning: (w) => logger.warn(w),
+ * });
+ * socket.on('data', (chunk) => reader.push(chunk));
+ * ```
+ */
+declare class FrameReader {
+    private readonly _opts;
+    private readonly _maxFrameSize;
+    private _state;
+    /** Reusable accumulator buffer — grown by doubling as needed. */
+    private _accumulator;
+    /** Number of payload bytes written to accumulator in current frame. */
+    private _writePos;
+    /** Monotonic absolute stream byte offset across the entire connection lifetime. */
+    private _byteOffset;
+    /** Byte offset where current leading-whitespace run started (FRAME-10). */
+    private _wsStart;
+    /** Count of leading whitespace bytes accumulated in current run (FRAME-10). */
+    private _wsCount;
+    /** Byte offset of the VT byte that started the current frame. */
+    private _frameStartOffset;
+    /** Per-frame warning accumulator — cleared after each _deliverFrame(). */
+    private _frameWarnings;
+    /**
+     * Construct a chunked MLLP frame reader.
+     *
+     * @param opts - Reader options (`onFrame`/`onWarning` callbacks, tolerance, `maxFrameSizeBytes`).
+     */
+    constructor(opts: FrameReaderOptions);
+    /**
+     * Feed a chunk of raw TCP bytes into the FSM. Frames fire synchronously via `onFrame`
+     * during this call. May throw `MllpFramingError` for unrecoverable framing violations
+     * when the matching tolerance is not enabled.
+     *
+     * @example
+     * ```typescript
+     * socket.on('data', (chunk) => reader.push(chunk));
+     * ```
+     */
+    push(chunk: Buffer): void;
+    /**
+     * Clear internal accumulator state and reset byte offset to 0.
+     *
+     * Call on reconnect / connection reuse to start fresh without allocating a new reader (D-03).
+     * Pending partial frame state is discarded silently.
+     *
+     * @example
+     * ```typescript
+     * socket.on('close', () => reader.reset());
+     * ```
+     */
+    reset(): void;
+    private _processByte;
+    private _scanForVt;
+    private _readPayload;
+    private _expectCr;
+    /** Grow the internal accumulator by doubling and write one byte. */
+    private _appendByte;
+    /**
+     * Copy accumulated payload bytes into a new Buffer and deliver via `onFrame`.
+     * The copy isolates callers from internal accumulator reuse (T-02-03-03).
+     */
+    private _deliverFrame;
+    /** Emit a warning via the `onWarning` callback, swallowing any handler exceptions (WARN-06). */
+    private _emitWarning;
+}
+
+/**
+ * NetTransport — `Transport` implementation wrapping a `net.Socket`.
+ *
+ * This is the **only** place in the codebase that consumes `net.Socket`'s
+ * EventEmitter surface. All higher layers (Connection, Server, Client) work
+ * against the `Transport` interface, never against `net.Socket` directly.
+ *
+ * @example
+ * ```typescript
+ * import { createConnection } from 'node:net';
+ * import { NetTransport } from '@cosyte/mllp';
+ *
+ * const socket = createConnection({ host: 'mllp.example.com', port: 2575 });
+ * const transport = new NetTransport(socket);
+ * transport.onConnect(() => console.log('connected'));
+ * transport.onData((chunk) => reader.push(chunk));
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Wraps a `net.Socket` as a `Transport`, mapping socket EventEmitter events
+ * to registered single-handler callbacks.
+ *
+ * Each `onXxx(fn)` call replaces the prior handler and re-registers on the socket
+ * (uses `socket.removeAllListeners(event)` + `socket.on(event, fn)`).
+ *
+ * @example
+ * ```typescript
+ * const t = new NetTransport(socket);
+ * t.onData((chunk) => process(chunk));
+ * t.onError((err) => handleError(err));
+ * ```
+ */
+declare class NetTransport implements Transport {
+    private readonly _socket;
+    /**
+     * Wrap an existing `net.Socket` (or `tls.TLSSocket`) as a `Transport`.
+     *
+     * @param socket - The connected (or connecting) socket to adapt.
+     */
+    constructor(socket: Socket);
+    /** See {@link Transport.write}. */
+    write(buf: Buffer): boolean;
+    /** See {@link Transport.close}. */
+    close(): void;
+    /** See {@link Transport.destroy}. */
+    destroy(reason?: Error): void;
+    /** See {@link Transport.onData}. */
+    onData(fn: (chunk: Buffer) => void): void;
+    /** See {@link Transport.onConnect}. */
+    onConnect(fn: () => void): void;
+    /** See {@link Transport.onClose}. */
+    onClose(fn: () => void): void;
+    /** See {@link Transport.onError}. */
+    onError(fn: (err: Error) => void): void;
+}
+
+/**
+ * TlsTransport — `Transport` implementation wrapping a `tls.TLSSocket` (Phase 8).
+ *
+ * Identical wiring to `NetTransport` with one deliberate difference: `onConnect`
+ * maps to the socket's `'secureConnect'` event (fires once the TLS handshake
+ * completes) rather than `'connect'` (fires once the raw TCP handshake
+ * completes). Consumers of `Transport` (Connection, Client, Server) never see
+ * the difference — they only ever observe "the transport is ready."
+ *
+ * @example
+ * ```typescript
+ * import { connect } from 'node:tls';
+ * import { TlsTransport } from '@cosyte/mllp';
+ *
+ * const socket = connect({ host: 'mllp.example.com', port: 2575, ca: caPem });
+ * const transport = new TlsTransport(socket);
+ * transport.onConnect(() => console.log('TLS handshake complete'));
+ * transport.onData((chunk) => reader.push(chunk));
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Wraps a `tls.TLSSocket` as a `Transport`. `onConnect(fn)` is armed on the
+ * `'secureConnect'` event (handshake complete, including certificate
+ * verification when `rejectUnauthorized` is on) rather than the raw TCP
+ * `'connect'` event that `NetTransport` uses.
+ *
+ * Each `onXxx(fn)` call replaces the prior handler and re-registers on the
+ * socket (`socket.removeAllListeners(event)` + `socket.on(event, fn)`) —
+ * the same set-once semantics as `NetTransport`.
+ *
+ * @example
+ * ```typescript
+ * const t = new TlsTransport(tlsSocket);
+ * t.onConnect(() => logger.info('secure'));
+ * t.onError((err) => handleTlsError(err));
+ * ```
+ */
+declare class TlsTransport implements Transport {
+    private readonly _socket;
+    /**
+     * Wrap an existing `tls.TLSSocket` (connecting or already secure) as a `Transport`.
+     *
+     * @param socket - The TLS socket to adapt.
+     */
+    constructor(socket: TLSSocket);
+    /** See {@link Transport.write}. */
+    write(buf: Buffer): boolean;
+    /** See {@link Transport.close}. */
+    close(): void;
+    /** See {@link Transport.destroy}. */
+    destroy(reason?: Error): void;
+    /** See {@link Transport.onData}. */
+    onData(fn: (chunk: Buffer) => void): void;
+    /**
+     * See {@link Transport.onConnect}. Armed on `'secureConnect'` — the TLS
+     * handshake-complete event — not the raw TCP `'connect'` event.
+     */
+    onConnect(fn: () => void): void;
+    /** See {@link Transport.onClose}. */
+    onClose(fn: () => void): void;
+    /** See {@link Transport.onError}. */
+    onError(fn: (err: Error) => void): void;
+}
+
+/**
+ * Security-warning codes and payload shape shared by the client and server (Phase 8).
+ *
+ * These codes are a **public API** — they appear in `'securityWarning'` event
+ * handlers, log pipelines, and monitoring dashboards. Renaming or removing a
+ * code is a breaking change (mirrors the `WarningCode` guardrail in
+ * `src/framing/registry.ts`).
+ *
+ * @example
+ * ```typescript
+ * import { MLLP_TLS_VERIFY_DISABLED, MLLP_BIND_ALL_INTERFACES } from '@cosyte/mllp';
+ * client.on('securityWarning', (w) => {
+ *   if (w.code === MLLP_TLS_VERIFY_DISABLED) logger.warn(w.message);
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+/**
+ * Emitted (client-side) on every successful `secureConnect` — initial connect
+ * AND every reconnect — when {@link TlsOptions.allowUnverified} is `true`.
+ * Certificate verification is disabled for the connection; this is the loud,
+ * per-connection reminder that the channel is not authenticated per IHE ATNA
+ * ITI-19 (https://profiles.ihe.net/ITI/TF/Volume2/ITI-19.html).
+ *
+ * @example
+ * ```typescript
+ * import { MLLP_TLS_VERIFY_DISABLED } from '@cosyte/mllp';
+ * client.on('securityWarning', (w) => {
+ *   if (w.code === MLLP_TLS_VERIFY_DISABLED) metrics.increment('mllp.tls_verify_disabled');
+ * });
+ * ```
+ */
+declare const MLLP_TLS_VERIFY_DISABLED = "MLLP_TLS_VERIFY_DISABLED";
+/**
+ * Emitted (server-side) once at `listen()` time when the server binds a
+ * wildcard host (`'0.0.0.0'` or `'::'`) with `ServerOptions.allowWildcardBind: true`.
+ * Binding all interfaces widens the network exposure of the listener; this is
+ * the loud, one-time reminder that the operator opted in.
+ *
+ * @example
+ * ```typescript
+ * import { MLLP_BIND_ALL_INTERFACES } from '@cosyte/mllp';
+ * server.on('securityWarning', (w) => {
+ *   if (w.code === MLLP_BIND_ALL_INTERFACES) logger.warn(w.message);
+ * });
+ * ```
+ */
+declare const MLLP_BIND_ALL_INTERFACES = "MLLP_BIND_ALL_INTERFACES";
+/**
+ * Union of the two stable security-warning codes.
+ *
+ * @example
+ * ```typescript
+ * const code: SecurityWarningCode = 'MLLP_TLS_VERIFY_DISABLED';
+ * ```
+ */
+type SecurityWarningCode = typeof MLLP_TLS_VERIFY_DISABLED | typeof MLLP_BIND_ALL_INTERFACES;
+/**
+ * Frozen payload of the `'securityWarning'` event, emitted by both
+ * {@link MllpClient} (`MLLP_TLS_VERIFY_DISABLED`) and {@link MllpServer}
+ * (`MLLP_BIND_ALL_INTERFACES`).
+ *
+ * Never carries payload bytes or PHI — only routing metadata (host/port) and
+ * a fixed, static message string.
+ *
+ * @example
+ * ```typescript
+ * client.on('securityWarning', (w: SecurityWarning) => {
+ *   logger.warn({ code: w.code, host: w.host, port: w.port });
+ * });
+ * ```
+ */
+interface SecurityWarning {
+    /** The stable security-warning code. */
+    readonly code: SecurityWarningCode;
+    /** Fixed, human-readable description. Never contains payload bytes or PHI. */
+    readonly message: string;
+    /** Host associated with the warning (the target host for clients; the bind host for servers). */
+    readonly host: string;
+    /** Port associated with the warning. */
+    readonly port: number;
+    /** Wall-clock time at point of emission. */
+    readonly timestamp: Date;
+}
+
+/**
+ * TLS (MLLPS) option types for the client and server (Phase 8).
+ *
+ * Spec anchor: IHE ATNA, ITI-19 Authenticate Node
+ * (https://profiles.ihe.net/ITI/TF/Volume2/ITI-19.html), the "STX: TLS 1.2
+ * Floor using BCP195" option, ITI TF-2 §3.19.6.2.3 — TLS >= 1.2 required;
+ * mutual node authentication; certificate validation via chain-of-trust or
+ * direct comparison. ITI TF-2 §3.19.6.2.3 mandates four TLS 1.2 cipher
+ * suites: `TLS_DHE_RSA_WITH_AES_128_GCM_SHA256`,
+ * `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`, `TLS_DHE_RSA_WITH_AES_256_GCM_SHA384`,
+ * `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`. Node's default TLS 1.2 cipher list
+ * already includes both mandated ECDHE suites, so this package pins to Node
+ * defaults rather than bundling a cipher list — see `docs-content/tls.md`.
+ *
+ * @example
+ * ```typescript
+ * import type { TlsOptions } from '@cosyte/mllp';
+ * const tls: TlsOptions = { ca: caPem, servername: 'mllp.example.com' };
+ * ```
+ *
+ * @packageDocumentation
+ */
+/**
+ * A PEM-encoded credential (certificate, key, or CA), matching Node's
+ * `tls.connect`/`tls.createServer` input shape — a single PEM string/Buffer,
+ * or an array of them (chain / multiple trust anchors).
+ *
+ * @example
+ * ```typescript
+ * import { readFileSync } from 'node:fs';
+ * const ca: PemInput = readFileSync('ca.pem');
+ * ```
+ */
+type PemInput = string | Buffer | Array<string | Buffer>;
+/**
+ * Client-side TLS options (Phase 8, `ClientOptions.tls`).
+ *
+ * Passing `true` for `ClientOptions.tls` is equivalent to `{}` — TLS enabled
+ * with all defaults, including certificate verification **on**.
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from '@cosyte/mllp';
+ * const client = createClient({
+ *   host: 'mllp.example.com',
+ *   port: 2575,
+ *   tls: { ca: caPem, minVersion: 'TLSv1.2' },
+ * });
+ * ```
+ */
+interface TlsOptions {
+    /** Trust anchor(s) for verifying the server's certificate chain. */
+    readonly ca?: PemInput;
+    /** Client certificate presented for mutual TLS (ATNA ITI-19). */
+    readonly cert?: PemInput;
+    /** Private key matching {@link TlsOptions.cert}. */
+    readonly key?: PemInput;
+    /** Passphrase for an encrypted {@link TlsOptions.key}. */
+    readonly passphrase?: string;
+    /**
+     * SNI hostname and the identity-check target (matched against the server
+     * certificate's Subject/SAN). Defaults to `ClientOptions.host` when unset.
+     */
+    readonly servername?: string;
+    /**
+     * Minimum negotiated TLS protocol version.
+     *
+     * Default `'TLSv1.2'` — the IHE ATNA ITI-19 "TLS 1.2 Floor" (BCP195) floor
+     * (ITI TF-2 §3.19.6.2.3). `'TLSv1.0'`/`'TLSv1.1'` are intentionally **not**
+     * expressible by this type — the floor cannot be lowered through this API.
+     *
+     * @default 'TLSv1.2'
+     */
+    readonly minVersion?: "TLSv1.2" | "TLSv1.3";
+    /** Maximum negotiated TLS protocol version. */
+    readonly maxVersion?: "TLSv1.2" | "TLSv1.3";
+    /**
+     * OpenSSL cipher-list string passthrough (`tls.connect`'s `ciphers`).
+     * Unset uses Node's compiled-in defaults, which already include both
+     * ATNA-mandated ECDHE suites (see the module doc comment). Set this to
+     * restrict to a stricter list (e.g. DHE suites) if your deployment requires it.
+     *
+     * @default undefined (Node defaults)
+     */
+    readonly ciphers?: string;
+    /**
+     * Loud, explicit dev opt-out from certificate verification (maps to
+     * `tls.connect`'s `rejectUnauthorized: false`). There is deliberately no
+     * raw `rejectUnauthorized` surface on this type — this is the only door,
+     * and it is loud: every successful connection (initial + every reconnect)
+     * emits a `'securityWarning'` (`MLLP_TLS_VERIFY_DISABLED`) event and calls
+     * `process.emitWarning`.
+     *
+     * Never set this in production against an untrusted network.
+     *
+     * @default false
+     */
+    readonly allowUnverified?: boolean;
+}
+/**
+ * ATNA ITI-19 mutual-authentication modes for {@link ServerTlsOptions.clientAuth}.
+ *
+ * Mirrors the IHE ATNA "Authenticate Node" mutual-auth requirement
+ * (https://profiles.ihe.net/ITI/TF/Volume2/ITI-19.html):
+ *
+ * - `'NONE'` — no client certificate requested (default).
+ * - `'WANT'` — client certificate requested but NOT required; an untrusted or
+ *   absent client certificate does not reject the connection. The peer
+ *   certificate (if any) is surfaced on the `'connection'` event.
+ * - `'MUST'` — client certificate required AND verified against
+ *   {@link ServerTlsOptions.ca}; the ATNA mutual-authentication mode. A
+ *   missing or untrusted client certificate rejects the handshake.
+ *
+ * @example
+ * ```typescript
+ * import type { ClientAuth } from '@cosyte/mllp';
+ * const mode: ClientAuth = 'MUST'; // ATNA ITI-19 mutual node authentication
+ * ```
+ */
+type ClientAuth = "NONE" | "WANT" | "MUST";
+/**
+ * Server-side TLS options (Phase 8, `ServerOptions.tls`).
+ *
+ * @example
+ * ```typescript
+ * import { createServer } from '@cosyte/mllp';
+ * const server = createServer({
+ *   tls: { cert: certPem, key: keyPem, clientAuth: 'MUST', ca: clientCaPem },
+ * });
+ * ```
+ */
+interface ServerTlsOptions {
+    /** Server certificate (PEM). Required. */
+    readonly cert: PemInput;
+    /** Private key matching {@link ServerTlsOptions.cert}. Required. */
+    readonly key: PemInput;
+    /** Trust anchor(s) for verifying client certificates under `WANT`/`MUST`. */
+    readonly ca?: PemInput;
+    /** Passphrase for an encrypted {@link ServerTlsOptions.key}. */
+    readonly passphrase?: string;
+    /**
+     * ATNA ITI-19 mutual-authentication mode. `'WANT'` requests a client
+     * certificate without rejecting unauthorized/absent ones (surfaced, not
+     * enforced); `'MUST'` requests AND enforces verification (ATNA mutual
+     * auth). See {@link ClientAuth}.
+     *
+     * @default 'NONE'
+     */
+    readonly clientAuth?: ClientAuth;
+    /**
+     * Minimum negotiated TLS protocol version — the IHE ATNA ITI-19 "TLS 1.2
+     * Floor" (BCP195) floor (ITI TF-2 §3.19.6.2.3).
+     *
+     * @default 'TLSv1.2'
+     */
+    readonly minVersion?: "TLSv1.2" | "TLSv1.3";
+    /** Maximum negotiated TLS protocol version. */
+    readonly maxVersion?: "TLSv1.2" | "TLSv1.3";
+    /**
+     * OpenSSL cipher-list string passthrough. Unset uses Node's defaults
+     * (includes both ATNA-mandated ECDHE suites).
+     *
+     * @default undefined (Node defaults)
+     */
+    readonly ciphers?: string;
+}
+
+/**
+ * Connection — 6-state FSM over a Transport with lifecycle events, warning streams,
+ * and getStats() observability.
+ *
+ * @example
+ * ```typescript
+ * import { Connection, NetTransport } from '@cosyte/mllp';
+ * import { createConnection } from 'node:net';
+ *
+ * const socket = createConnection({ host: 'localhost', port: 2575 });
+ * const transport = new NetTransport(socket);
+ * const conn = new Connection({ transport });
+ * conn.on('message', ({ payload }) => conn.send(ackBuffer));
+ * conn.on('stateChange', ({ from, to }) => logger.info({ from, to }));
+ * socket.on('connect', () => conn.notifyConnect(socket.remoteAddress ?? null, socket.remotePort ?? null));
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * The 6 connection states from LIFE-01.
+ *
+ * Transitions are validated against the LIFE-02 edge graph. Illegal transitions
+ * are silently ignored to preserve FSM integrity.
+ */
+type ConnectionState = "CONNECTING" | "CONNECTED" | "DRAINING" | "RECONNECTING" | "DISCONNECTED" | "CLOSED";
+/**
+ * Payload for the 'stateChange' event. Always `Object.freeze`'d.
+ *
+ * @example
+ * ```typescript
+ * conn.on('stateChange', ({ from, to, reason }) => {
+ *   logger.info({ from, to, reason });
+ * });
+ * ```
+ */
+interface StateChangeEvent {
+    readonly from: ConnectionState;
+    readonly to: ConnectionState;
+    readonly reason?: string;
+}
+/**
+ * Payload for the 'reconnecting' event. Always `Object.freeze`'d.
+ *
+ * Phase 5 will populate `attempt` and `delayMs` once the reconnect backoff loop
+ * is implemented. For now only `connectionId` is present at the point of emission.
+ *
+ * @example
+ * ```typescript
+ * conn.on('reconnecting', ({ connectionId }) => {
+ *   logger.info(`Reconnecting connection ${connectionId}`);
+ * });
+ * ```
+ */
+interface ReconnectingEvent {
+    readonly connectionId: string;
+    readonly attempt?: number;
+    readonly delayMs?: number;
+}
+/**
+ * Return type of `connection.getStats()` — JSON-serializable per OBS-04.
+ *
+ * All timestamps are `Date | null` (not epoch milliseconds). `JSON.stringify()`
+ * serialises them to ISO 8601 strings by default with no information loss.
+ *
+ * @example
+ * ```typescript
+ * const stats = conn.getStats();
+ * logger.info(JSON.stringify(stats)); // safe: all values are JSON-serializable
+ * ```
+ */
+interface ConnectionStats {
+    readonly state: ConnectionState;
+    readonly connectionId: string;
+    readonly remoteAddress: string | null;
+    readonly remotePort: number | null;
+    readonly warningsByCode: Record<string, number>;
+    readonly bytesIn: number;
+    readonly bytesOut: number;
+    readonly lastByteInAt: Date | null;
+    readonly lastByteOutAt: Date | null;
+    readonly connectedAt: Date | null;
+    readonly warningsTruncated: boolean;
+}
+/**
+ * Options for constructing a {@link Connection}.
+ *
+ * @example
+ * ```typescript
+ * const opts: ConnectionOptions = {
+ *   transport: new NetTransport(socket),
+ *   onMessage: (payload) => handleMessage(payload),
+ *   onWarning: (w) => logger.warn(w),
+ *   drainTimeoutMs: 10_000,
+ * };
+ * ```
+ */
+interface ConnectionOptions {
+    /** The transport this Connection will drive. */
+    transport: Transport;
+    /** Called for each decoded MLLP frame (raw payload bytes, framing stripped). */
+    onMessage?: (payload: Buffer) => void;
+    /** Per-connection warning subscriber (WARN-10). Replaces previous subscription. */
+    onWarning?: (w: MllpWarning) => void;
+    /** Drain timeout used by close() in Phase 4/5 (default: 30_000 ms). */
+    drainTimeoutMs?: number;
+    /** FrameReader options (tolerance, maxFrameSizeBytes). onFrame/onWarning are managed internally. */
+    framing?: Omit<FrameReaderOptions, "onFrame" | "onWarning">;
+}
+/**
+ * A single MLLP connection wrapping a {@link Transport} with a 6-state FSM,
+ * lifecycle events, per-connection warning streams, and `getStats()` observability.
+ *
+ * Emits events: `stateChange`, `connect`, `disconnect`, `reconnecting`, `close`,
+ * `message`, `warning`, `error`.
+ *
+ * @example
+ * ```typescript
+ * import { Connection, NetTransport } from '@cosyte/mllp';
+ * import { createConnection } from 'node:net';
+ *
+ * const socket = createConnection({ host: 'localhost', port: 2575 });
+ * const conn = new Connection({ transport: new NetTransport(socket) });
+ * conn.on('stateChange', ({ from, to }) => console.log(from, '->', to));
+ * conn.on('message', ({ payload }) => console.log('received', payload.length, 'bytes'));
+ * socket.on('connect', () =>
+ *   conn.notifyConnect(socket.remoteAddress ?? null, socket.remotePort ?? null)
+ * );
+ * ```
+ */
+declare class Connection extends EventEmitter {
+    /** Stable UUIDv4 identifier for this connection (D-11). */
+    readonly connectionId: string;
+    private _state;
+    private readonly _transport;
+    private readonly _reader;
+    private readonly _opts;
+    private _remoteAddress;
+    private _remotePort;
+    private _connectedAt;
+    private _bytesIn;
+    private _bytesOut;
+    private _lastByteInAt;
+    private _lastByteOutAt;
+    /** Ring buffer: last MAX_WARNINGS entries (OBS-05). */
+    private _warningBuffer;
+    /** Accurate total counts per code — unaffected by ring buffer truncation (OBS-05). */
+    private readonly _warningsByCode;
+    /** Set to true once the ring buffer overflows (OBS-05). */
+    private _warningsTruncated;
+    private _onWarningFn;
+    private _drainPromise;
+    /**
+     * beforeClose hook — no-op default that resolves immediately.
+     *
+     * Phase 4 (Server) and Phase 5 (Client) override this instance property to
+     * register ACK-drain and send-queue drain logic respectively (D-07/D-08).
+     * Connection calls this during `close()`, racing against `drainTimeoutMs`.
+     */
+    beforeClose: (drainTimeoutMs: number) => Promise<void>;
+    /**
+     * Construct a connection over the given transport. Starts in `CONNECTING`; call
+     * {@link Connection.notifyConnect} once the transport handshake completes.
+     *
+     * @param opts - Connection options (the transport, message/warning handlers, drain timeout, framing).
+     */
+    constructor(opts: ConnectionOptions);
+    /**
+     * Current FSM state. One of the 6 `ConnectionState` values (LIFE-01).
+     *
+     * Subscribe to `'stateChange'` events for reactive state monitoring.
+     */
+    get state(): ConnectionState;
+    /**
+     * Register or replace the per-connection warning subscriber (WARN-10).
+     *
+     * Subsequent calls replace the previous handler (set-once semantics prevent leaks).
+     * The handler is called synchronously and any exception it throws is swallowed (WARN-06).
+     *
+     * @example
+     * ```typescript
+     * conn.onWarning((w) => logger.warn({ code: w.code, connectionId: w.connectionId }));
+     * ```
+     */
+    onWarning(fn: (w: MllpWarning) => void): void;
+    /**
+     * Notify the connection that the transport handshake has completed.
+     *
+     * Transitions `CONNECTING → CONNECTED` and emits the `'connect'` event.
+     * Called externally by Server/Client after the socket connects.
+     *
+     * @param remoteAddress - Remote peer IP address, or `null` if unavailable.
+     * @param remotePort - Remote peer port, or `null` if unavailable.
+     *
+     * @example
+     * ```typescript
+     * socket.on('connect', () =>
+     *   conn.notifyConnect(socket.remoteAddress ?? null, socket.remotePort ?? null)
+     * );
+     * ```
+     */
+    notifyConnect(remoteAddress: string | null, remotePort: number | null): void;
+    /**
+     * Write raw bytes to the transport (no framing applied).
+     *
+     * Phase 4 (Server) and Phase 5 (Client) wrap this with `encodeFrame()` to add MLLP framing.
+     * Returns `false` if the connection is CLOSED or DISCONNECTED (no bytes written).
+     *
+     * @returns `true` if bytes flushed immediately; `false` if buffered (backpressure) or not writable.
+     *
+     * @example
+     * ```typescript
+     * const flushed = conn.send(encodeFrame(payload));
+     * if (!flushed) logger.warn('backpressure detected');
+     * ```
+     */
+    send(data: Buffer): boolean;
+    /**
+     * Initiate graceful close of the connection.
+     *
+     * - If `CONNECTING` or `RECONNECTING`: cancels the pending attempt, transitions
+     *   directly to `CLOSED`, and calls `transport.destroy()` (LIFE-05).
+     * - If `CONNECTED`: transitions to `DRAINING`, calls `beforeClose(drainTimeoutMs)`,
+     *   then `DRAINING → DISCONNECTED` once the hook resolves, or `DRAINING → CLOSED`
+     *   if the drain timeout elapses first.
+     * - If `DRAINING`: waits for the existing drain to complete (idempotent).
+     * - If `CLOSED` or `DISCONNECTED`: no-op.
+     *
+     * @param opts.drainTimeoutMs - Override drain timeout (default: `opts.drainTimeoutMs ?? 30_000`).
+     *
+     * @example
+     * ```typescript
+     * await conn.close({ drainTimeoutMs: 5_000 });
+     * ```
+     */
+    close(opts?: {
+        drainTimeoutMs?: number;
+    }): Promise<void>;
+    /**
+     * Race `beforeClose()` against the drain timeout.
+     *
+     * On normal completion: `DRAINING → DISCONNECTED` + `transport.close()`.
+     * On timeout: `DRAINING → CLOSED` + `transport.destroy()` (T-03-04-01).
+     */
+    private _drainWithTimeout;
+    /**
+     * Abruptly destroy the connection, discarding any pending writes.
+     *
+     * Transitions from any non-terminal state directly to `CLOSED` and calls
+     * `transport.destroy(reason)`. Emits `'close'` event. Idempotent — safe to
+     * call multiple times.
+     *
+     * @param reason - Optional error to propagate to the transport.
+     *
+     * @example
+     * ```typescript
+     * conn.destroy(new Error('Timeout exceeded'));
+     * ```
+     */
+    destroy(reason?: Error): void;
+    /**
+     * Return a JSON-serializable observability snapshot (OBS-03/04/05).
+     *
+     * All timestamp fields are `Date | null` (not epoch milliseconds). `JSON.stringify()`
+     * serialises them to ISO 8601 strings with no information loss.
+     *
+     * `warningsByCode` reflects every warning ever received regardless of ring buffer truncation.
+     * `warningsTruncated` is `true` if the 100-entry ring buffer has overflowed.
+     *
+     * @example
+     * ```typescript
+     * const stats = conn.getStats();
+     * console.log(JSON.stringify(stats)); // log-pipeline friendly
+     * ```
+     */
+    getStats(): ConnectionStats;
+    private _transition;
+    private _onTransportClose;
+    /**
+     * Emit on `'error'` only when a listener is attached.
+     *
+     * Node throws `ERR_UNHANDLED_ERROR` when `'error'` is emitted on an `EventEmitter` with no
+     * listener. Every `'error'` emission in this class is reached from inside a transport callback
+     * (the socket's `'data'`/`'error'` listener), so an unguarded emit would become an **uncaught
+     * exception that kills the process** — the exact failure the containment above exists to
+     * prevent, merely relocated one frame up the stack.
+     *
+     * `Connection` is a public export and can legitimately be driven with no `'error'` listener
+     * (`MllpServer` and `MllpClient` each attach one; a bare `Connection` need not). The connection
+     * is still torn down and `'stateChange'`/`'close'` still fire, so a caller is never blind —
+     * they simply do not get the typed error object they never asked for. Mirrors
+     * `MllpServer._emitErrorIfListened`.
+     */
+    private _emitErrorIfListened;
+    /**
+     * Handle a fatal framing error thrown out of `FrameReader.push` (FRAME-FATAL).
+     *
+     * Contract: surface it as a connection `'error'` (frozen payload, `phase: 'receive'`,
+     * `connectionCause: 'framing-fatal'`, the original `MllpFramingError` preserved as `cause` so
+     * consumers keep the stable `code` and `byteOffset`), then **destroy this connection only**.
+     *
+     * Why destroy rather than resynchronize: once `push` has thrown, the reader's position within
+     * the byte stream is no longer trustworthy — the next bytes could be the middle of a message.
+     * Guessing where the next frame starts is how a clinical message gets silently mis-split, so
+     * the connection is dropped instead. A server drops that one peer and keeps serving everyone
+     * else.
+     *
+     * `'framing-fatal'` is classified **permanent** by `isTransientConnectionError`, so a client
+     * does **not** auto-reconnect into it. That matters: a peer speaking something that is not MLLP
+     * (an HTTP probe, a health check, a wrong-port misconfiguration) would otherwise be retried
+     * forever, and the backoff would become an unbounded reconnect storm against an interface
+     * engine that is already unwell. A compatibility failure is not a network blip.
+     *
+     * If a peer's quirk is *expected* (trailing junk, keepalive bytes, a missing leading VT), the
+     * decoder's tolerance opt-ins are the supported answer — they turn the throw into a warning.
+     */
+    private _onFatalFramingError;
+    /**
+     * Backstop for a NON-framing throw escaping `FrameReader.push` — i.e. our own bug, or a
+     * subscriber's, rather than the peer's bytes.
+     *
+     * `_onFrameDecoded` already contains subscriber throws at the dispatch site, so this should be
+     * unreachable. It exists because "unreachable" and "cannot kill the process from inside a
+     * socket `'data'` handler" are different claims, and only the second one is safe to bet a
+     * clinical interface on. Reported honestly as an internal receive error — never dressed up as
+     * a peer framing fault.
+     */
+    private _onInternalReceiveError;
+    private _onTransportError;
+    private _onFrameDecoded;
+    /**
+     * Run a subscriber callback, containing any throw as a connection `'error'` rather than letting
+     * it unwind into the socket callback that (transitively) invoked us.
+     */
+    private _dispatchContained;
+    private _onFramingWarning;
+}
+
+/**
+ * Typed error for socket-layer connection problems.
+ *
+ * @example
+ * ```typescript
+ * import { MllpConnectionError } from '@cosyte/mllp';
+ * try {
+ *   await client.connect();
+ * } catch (err) {
+ *   if (err instanceof MllpConnectionError) {
+ *     console.log(err.phase, err.cause);
+ *   }
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+/**
+ * Connection lifecycle phase where the error occurred.
+ *
+ * All 5 phases are defined in Phase 3 even though `'reconnect'` is only
+ * exercised in Phase 5 (CLIENT-17). Locking the full union now prevents a
+ * breaking type change later (ERR-03).
+ */
+type ConnectionErrorPhase = "connect" | "send" | "receive" | "close" | "reconnect";
+/**
+ * Stable cause codes for `MllpConnectionError`.
+ *
+ * These codes are a **public API** — they appear in error inspection
+ * by callers, log pipelines, and monitoring dashboards. Renaming or
+ * removing a member is a breaking change.
+ *
+ * - `'fifo-unsafe'` — A queued send was rejected during reconnect because
+ *   FIFO ordering cannot be safely resumed across sessions (CLIENT-17).
+ * - `'in-flight-orphan'` — An in-flight send (already write-flushed,
+ *   ACK timer started) was rejected during reconnect in FIFO mode because
+ *   the at-most-once delivery contract cannot be preserved across a
+ *   socket drop (D-08, healthcare medication/orders semantics).
+ * - `'tls-verify'` (Phase 8) — The TLS handshake failed certificate
+ *   verification (untrusted chain, expired/not-yet-valid cert, hostname
+ *   mismatch, revocation, …). See {@link isTlsVerificationErrorCode} for the
+ *   exact underlying error codes. Classified **permanent** by
+ *   `isTransientConnectionError` — never auto-reconnect-looped into a
+ *   misconfigured or MITM'd endpoint.
+ * - `'tls-handshake'` (Phase 8) — A TLS-**protocol**-shaped handshake
+ *   failure observed before `'secureConnect'`: `ERR_SSL_*` codes, `EPROTO`,
+ *   or an OpenSSL alert-bearing error (protocol version mismatch, no shared
+ *   cipher, a required mutual-TLS client certificate rejected by the
+ *   server, …). See `isTlsProtocolError` for the boundary. Pure TCP-level
+ *   failures (`ECONNREFUSED`, `ETIMEDOUT`, …) on a TLS-configured
+ *   connection carry **no** `connectionCause` — the same shape as plaintext.
+ *
+ * Scope note: the `'tls-verify'`/`'tls-handshake'` values are attached on
+ * the client's **initial `connect()` path**. Failures on the auto-reconnect
+ * path surface as raw socket errors — their transient/permanent
+ * classification still applies, but they do not (yet) carry a
+ * `connectionCause`.
+ *
+ * @example
+ * ```typescript
+ * if (err instanceof MllpConnectionError && err.connectionCause === 'in-flight-orphan') {
+ *   // Treat as at-most-once: do NOT auto-retry; bubble up to caller for
+ *   // application-level dedupe / replay decisions.
+ * }
+ * ```
+ */
+type ConnectionErrorCause = "fifo-unsafe" | "in-flight-orphan" | "tls-verify" | "tls-handshake" | "framing-fatal";
+/**
+ * Thrown (or emitted via `onError`) for socket-layer problems such as
+ * connection refused, ECONNRESET, ETIMEDOUT, or DNS failure.
+ *
+ * - `cause` — the original OS or TLS error
+ * - `phase` — which connection lifecycle phase the failure occurred in
+ * - `connectionCause` — optional stable cause-code (e.g. for FIFO reconnect rejections)
+ *
+ * @example
+ * ```typescript
+ * throw new MllpConnectionError('Connection refused', {
+ *   cause: osError,
+ *   phase: 'connect',
+ * });
+ * ```
+ */
+declare class MllpConnectionError extends Error {
+    readonly name: "MllpConnectionError";
+    /** The original OS or TLS error that caused this connection failure. */
+    readonly cause: Error;
+    /** Which connection lifecycle phase the failure occurred in. */
+    readonly phase: ConnectionErrorPhase;
+    /**
+     * Optional stable cause code. Present on FIFO reconnect rejections
+     * (`'fifo-unsafe'` for queued sends, `'in-flight-orphan'` for in-flight sends).
+     *
+     * The set of values is a **public API**; see {@link ConnectionErrorCause}.
+     */
+    readonly connectionCause?: ConnectionErrorCause;
+    /**
+     * Construct an MLLP connection error.
+     *
+     * @param message - Human-readable error message.
+     * @param opts - Error context (underlying `cause`, the lifecycle `phase`, optional stable cause code).
+     */
+    constructor(message: string, opts: {
+        cause: Error;
+        phase: ConnectionErrorPhase;
+        connectionCause?: ConnectionErrorCause;
+    });
+}
+
+/**
+ * Server-side MLLP acknowledgement construction and the **fail-safe commit contract**.
+ *
+ * This module owns the byte-level ACK builder used by {@link MllpServer}'s auto-ACK
+ * path, the HL7 Table 0008 acknowledgement-code union, and the error type a message
+ * handler throws to request a specific negative acknowledgement.
+ *
+ * ## Why this is safety-critical
+ *
+ * A positive acknowledgement (`AA`) tells the sender "you may forget this message — I
+ * have it." If a server emits `AA` *before* the message is durably handled and then the
+ * process crashes, the message is **silently lost** with no record on either side. For
+ * clinical messages (an admit, an order, a result) that is a patient-safety failure.
+ *
+ * The contract this module enforces: a positive ACK (`AA`) is only built once the
+ * application handler has resolved success. A handler that throws or rejects yields a
+ * **negative** ACK (`AE` by default, `AR` when the handler asks for it) — never `AA`.
+ *
+ * Spec: HL7 v2.5.1 ch. 2 §2.9.2 (original acknowledgement mode), §2.9.3 (enhanced
+ * accept/application acknowledgement), Table 0008 (Acknowledgment Code), §2.9.2.2
+ * (MSA-2 echoes the inbound MSH-10 message control ID).
+ *
+ * @packageDocumentation
+ */
+/**
+ * HL7 Table 0008 — Acknowledgment Code. A **stable public API**.
+ *
+ * Two families, by mode (HL7 v2.5.1 §2.9):
+ *
+ * - **Original mode (§2.9.2):** `AA` accept, `AE` application error, `AR` application
+ *   reject. The single ACK reports application-level outcome.
+ * - **Enhanced mode (§2.9.3):** `CA` commit accept, `CE` commit error, `CR` commit
+ *   reject — the *accept* acknowledgement, distinct from a later application ACK.
+ *
+ * `AE` vs `AR`: `AE` is a processing **error** (the sender may resend later, e.g. a
+ * transient downstream outage); `AR` is a **reject** (the sender should not resend the
+ * message unchanged, e.g. it is structurally unacceptable). `@cosyte/mllp` builds
+ * original-mode ACKs; the `C*` codes are surfaced in the type for completeness and for
+ * callers that build their own enhanced-mode ACKs via `autoAck: fn`.
+ *
+ * @example
+ * ```typescript
+ * import type { AckCode } from '@cosyte/mllp';
+ * const code: AckCode = 'AE';
+ * ```
+ */
+type AckCode = "AA" | "AE" | "AR" | "CA" | "CE" | "CR";
+/**
+ * The negative original-mode acknowledgement codes a failed handler can produce.
+ *
+ * @example
+ * ```typescript
+ * import type { NegativeAckCode } from '@cosyte/mllp';
+ * const code: NegativeAckCode = 'AR';
+ * ```
+ */
+type NegativeAckCode = "AE" | "AR";
+/**
+ * Error a message handler throws to control the negative acknowledgement the server
+ * returns. Throwing **any** error from a commit-gated handler yields `AE` by default;
+ * throw an `MllpAckError` to choose `AR` (application reject) instead.
+ *
+ * The `message` is **never** copied into the ACK bytes or any emitted event — it may
+ * carry PHI. Only the static, non-PHI `ackCode` influences the wire response.
+ *
+ * @example
+ * ```typescript
+ * import { createServer, MllpAckError } from '@cosyte/mllp';
+ *
+ * createServer({
+ *   autoAck: 'AA',
+ *   onMessage: async (payload) => {
+ *     if (!isAcceptable(payload)) {
+ *       // sender should NOT resend unchanged -> AR
+ *       throw new MllpAckError('unsupported message type', { ackCode: 'AR' });
+ *     }
+ *     await db.commit(payload); // throw here -> AE (resend may succeed)
+ *   },
+ * });
+ * ```
+ */
+declare class MllpAckError extends Error {
+    /** The negative acknowledgement code to return (`AE` or `AR`). */
+    readonly ackCode: NegativeAckCode;
+    /**
+     * @param message - Diagnostic text for the thrower. Never placed on the wire (may carry PHI).
+     * @param opts.ackCode - Negative code to return. Default `'AE'`.
+     * @param opts.cause - Underlying error, preserved on `.cause`.
+     */
+    constructor(message: string, opts?: {
+        ackCode?: NegativeAckCode;
+        cause?: unknown;
+    });
+}
+/**
+ * Resolve the negative acknowledgement code for a handler failure.
+ *
+ * An {@link MllpAckError} carries an explicit `ackCode`; any other thrown value maps to
+ * `AE` (application error — the default, since most handler failures are transient and
+ * a resend may succeed).
+ *
+ * @example
+ * ```typescript
+ * import { resolveNackCode, MllpAckError } from '@cosyte/mllp';
+ * resolveNackCode(new Error('boom'));                          // 'AE'
+ * resolveNackCode(new MllpAckError('nope', { ackCode: 'AR' })); // 'AR'
+ * ```
+ */
+declare function resolveNackCode(err: unknown): NegativeAckCode;
+/**
+ * True iff a **positive** raw acknowledgement (`AA`/`CA`) cannot be safely correlated to
+ * this payload, so {@link buildRawAck} (and the server's auto-ACK path) must **downgrade**
+ * it to a non-positive `AE`/`CE` rather than tell the sender "I have it."
+ *
+ * The rule this enforces: **never answer `AA` for a message you could not correlate.** A
+ * positive ACK is a promise the sender may forget the message; if it names a control ID
+ * the sender cannot match — or names one of several messages it never read — the sender
+ * times out and resends, committing a **duplicate clinical message** (or worse, believes a
+ * destroyed message was delivered). Three payload-shaped reasons make a positive ACK
+ * uncorrelatable, all peer-reachable off the wire:
+ *
+ *   1. **No readable `MSH`.** `readMshSegment` returns `null` — e.g. a `BOM`/`SP`/`TAB`
+ *      before `MSH` (which shares the `MSH`'s segment line, so `MSH` heads no segment), or
+ *      a bare fragment delivered after a mid-payload `VT` discard (`MLLP_TRAILING_BYTES`).
+ *      MSA-2 would be empty: an ACK that correlates to nothing.
+ *   2. **Empty MSH-10.** The `MSH` is readable but carries no message control ID, so there
+ *      is nothing to echo — again `MSA|AA|` with an empty MSA-2.
+ *   3. **A batch or concatenated messages.** An `FHS`/`BHS`/`BTS`/`FTS` envelope (§2.10.3)
+ *      or a second `MSH` in the same frame: a single MSA-2 can echo only ONE control ID, so
+ *      a positive ACK naming the first silently drops the rest (see
+ *      {@link containsBatchOrExtraMessage}). Batch ACK is its own feature (`MLLP-BATCH`) —
+ *      until it is designed, a batch must stay a **loud non-positive** answer.
+ *
+ * This is a **refusal**, not a tolerance widening: it never makes an unreadable message
+ * readable, never re-bases on a located `MSH`, never parses a batch. It only recognizes
+ * the shapes for which a positive disposition would be a lie, so the builder can fall back
+ * to `AE`. A **negative** requested code (`AE`/`AR`/`CE`/`CR`) is unaffected — it is
+ * already non-positive, and echoing whatever control ID it can find is still useful.
+ *
+ * Pure, byte-level, never throws.
+ *
+ * @example
+ * ```typescript
+ * import { rawAckUncorrelatable } from '@cosyte/mllp';
+ * rawAckUncorrelatable(oneGoodMessage); // false → AA is safe
+ * rawAckUncorrelatable(twoConcatenatedMsh); // true → downgrade AA to AE
+ * ```
+ */
+declare function rawAckUncorrelatable(payload: Buffer): boolean;
+/**
+ * Build a minimal original-mode HL7 v2 acknowledgement from raw inbound payload bytes,
+ * **without a parser** (parser-driven ACKs are the `@cosyte/mllp/ack-from-hl7` subpath).
+ *
+ * Locates the `MSH` segment (the first `CR`/`LF`-delimited segment starting with `MSH` —
+ * so a leading `CR` or an `FHS`/`BHS` batch header does not hide it), reads the field
+ * separator from **MSH-1** and the encoding characters from **MSH-2**, then splits that
+ * segment on that separator to read fields. The ACK swaps sender/receiver per HL7 ACK
+ * rules, echoes the inbound MSH-10 into MSA-2 (§2.9.2.2), sets MSA-1 to `code`, and — for
+ * negative codes — adds a **static, PHI-free** MSA-3 reason. A fresh control ID fills the
+ * ACK's own MSH-10.
+ *
+ * ## Why the delimiters are read, not assumed
+ *
+ * MSH-1 **is** the field separator (HL7 v2.5.1 §2.5.4): the byte at offset 3 of the MSH
+ * segment *defines* it for the whole message. `|` is overwhelmingly common but it is a
+ * convention, not the spec. Assuming it was wrong in two compounding ways:
+ *
+ *   1. **Reading.** Splitting a `!`-delimited message on `|` yields ONE field, so every
+ *      echoed field — including MSH-10 — came back empty. The ACK went out as
+ *      `MSA|AA|` with **no correlation id at all**: the sender cannot match it, times
+ *      out, and resends → a duplicate clinical message. That is the exact failure this
+ *      package's correlator exists to prevent, manufactured by the ACK builder itself.
+ *   2. **Writing.** The echoed MSH-3..6 and MSH-10 field *content* is copied verbatim
+ *      from the inbound, still escaped against the **inbound's** encoding characters. Re-
+ *      emitting that content under a different delimiter set silently reinterprets it:
+ *      an inbound whose component separator is `#` and whose MSH-10 is `ID#X` would be
+ *      re-emitted under `^~\&` as the literal `ID#X`, which the sender then reads as a
+ *      single component rather than two. Echoing MSH-1 and MSH-2 keeps the content and
+ *      the delimiters that define it together.
+ *
+ * ## It reads the MSH through the SHARED scanner
+ *
+ * The MSH read is `readMshSegment` from `src/internal/control-id.ts` — the same call the
+ * client's correlator makes to derive the key it will later match this ACK against. That
+ * is deliberate and it is the whole point: this builder used to re-derive the read itself
+ * (`payload.toString("latin1").split("\r")`, hunting for an `MSH` anywhere in the
+ * payload), and the two disagreed on real inputs. On a **truncated MSH** followed by a
+ * `PID` the correlator keyed on the PID's MRN while this builder echoed an empty MSA-2. On
+ * a payload with a **leading `CR`** — which the MLLP decoder passes straight through, and
+ * which real senders emit — this builder found the `MSH` and echoed MSH-10 correctly while
+ * the correlator, requiring `MSH` at byte 0, gave up. Every such disagreement is an ACK the
+ * sender cannot match → timeout → resend → **duplicate clinical message**.
+ *
+ * The fix is one scan — but note *which* scan. The first attempt made them agree by
+ * requiring `MSH` at byte 0 everywhere, which "resolved" the leading-`CR` disagreement by
+ * degrading the side that had been **right**: `buildRawAck` began emitting a positive `AA`
+ * with an empty MSA-2, silently, for a message whose MSH-10 was plainly present. Agreement
+ * is not the goal; agreeing on the *correct*, *tolerant* answer is. A lenient reader may
+ * never drop data that is there (Postel's Law — CLAUDE.md).
+ *
+ * ## The fail-safe downgrade: never a positive `AA`/`CA` it cannot correlate
+ *
+ * A positive acknowledgement is a promise the sender may forget the message. If it names a
+ * control ID the sender cannot match — or names one message out of several it never read —
+ * the sender times out and resends, committing a **duplicate clinical message**. So a
+ * requested positive code is **downgraded** to its non-positive counterpart (`AA`→`AE`,
+ * `CA`→`CE`) whenever the payload cannot carry a correlatable positive ACK: no readable
+ * `MSH`, an empty MSH-10, or a batch/concatenated-message shape that a single MSA-2 cannot
+ * acknowledge. See {@link rawAckUncorrelatable} for the exact conditions and why each is a
+ * refusal rather than a widened reader. A requested **negative** code (`AE`/`AR`/`CE`/`CR`)
+ * is never touched. This mirrors the parser-backed `buildMllpAck`, which downgrades and
+ * warns on an unparseable inbound — the two builders' fail-safe semantics now agree.
+ *
+ * **Never throws** and **never copies payload content** beyond the routing/control
+ * metadata above — `readMshSegment` stops at the MSH's segment terminator, so no field of
+ * any later segment (PID and friends) can be reached, let alone echoed. On a missing or
+ * unreadable `MSH` it returns a minimal well-formed ACK carrying the (downgraded) `code` so
+ * the caller can still respond.
+ *
+ * @param payload - Raw decoded HL7 v2 payload bytes (MLLP framing already stripped).
+ * @param code - Requested MSA-1 acknowledgement code. A positive `AA`/`CA` is downgraded to
+ *   `AE`/`CE` when the message cannot be correlated (see above).
+ * @returns ACK payload bytes (no framing — the caller wraps with `encodeFrame`).
+ *
+ * @example
+ * ```typescript
+ * import { buildRawAck } from '@cosyte/mllp';
+ * const ack = buildRawAck(inboundPayload, 'AE'); // MSA|AE|<inbound MSH-10>|message could not be processed
+ * ```
+ */
+declare function buildRawAck(payload: Buffer, code: AckCode): Buffer;
+
+/**
+ * MLLP Server — createServer(), createStarterServer(), and MllpServer class.
+ *
+ * Provides the server-side MLLP transport: listen for inbound TCP connections,
+ * decode MLLP-framed messages, surface them as Buffer payloads, and support
+ * optional auto-ACK, keepalive, graceful shutdown, and AbortSignal cancellation.
+ *
+ * @example
+ * ```typescript
+ * import { createServer } from '@cosyte/mllp';
+ *
+ * const server = createServer({
+ *   onMessage: (payload, meta, conn) => {
+ *     console.log('received', payload.length, 'bytes from', meta.connectionId);
+ *   },
+ * });
+ * await server.listen(2575);
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Metadata attached to each decoded MLLP message (SERVER-03).
+ *
+ * All fields are `readonly` — the object is `Object.freeze()`'d before emission.
+ *
+ * @example
+ * ```typescript
+ * server.on('message', ({ payload, meta }) => {
+ *   console.log(meta.connectionId, '@', meta.byteOffset, 'warnings:', meta.warnings.length);
+ * });
+ * ```
+ */
+interface MessageMeta {
+    /** Stable UUID identifying the connection that delivered this message. */
+    readonly connectionId: string;
+    /** Byte offset of the frame start in the connection's data stream. */
+    readonly byteOffset: number;
+    /** Framing warnings emitted during decoding of this frame. */
+    readonly warnings: readonly MllpWarning[];
+}
+/**
+ * Why the server sent a **negative** acknowledgement instead of `AA` on the auto-ACK path.
+ * A stable, **PHI-free** enum (no payload bytes, no control ID) — safe to log and to key
+ * metrics on.
+ *
+ * - `'handler-rejected'` — a commit-gated `onMessage` handler threw/rejected (the commit
+ *   contract: a positive ACK cannot precede a successful commit).
+ * - `'uncorrelatable-inbound'` — the inbound could not carry a correlatable positive ACK
+ *   (no readable `MSH`, an empty MSH-10, or a batch/concatenated-message shape). A positive
+ *   `AA` here names a control ID the sender cannot match → timeout → resend → **duplicate
+ *   clinical message**. See {@link rawAckUncorrelatable}.
+ * - `'discarded-bytes'` — the decoder flagged `MLLP_TRAILING_BYTES` for this frame: a
+ *   mid-payload `VT` made it **discard accumulated bytes** and deliver only the fragment
+ *   after it. The clinical message was destroyed in transit; a positive `AA` would tell the
+ *   sender a message we never received was delivered.
+ */
+type NackReason = "handler-rejected" | "uncorrelatable-inbound" | "discarded-bytes";
+/**
+ * Payload of the server `'nack'` event — emitted whenever the server responds with a
+ * **negative** acknowledgement instead of `AA` on the auto-ACK path (the fail-safe commit
+ * contract). This fires both when a commit-gated `autoAck: 'AA'` handler throws/rejects and
+ * when the server **downgrades** a positive auto-ACK because the inbound could not be
+ * correlated ({@link NackReason}).
+ *
+ * **PHI-safe by construction:** carries only the connection ID, the resolved
+ * acknowledgement code, and a static `reason` — never the payload, the inbound control ID,
+ * or the thrown error's message (which may carry PHI). The object is `Object.freeze()`'d
+ * before emission.
+ *
+ * @example
+ * ```typescript
+ * server.on('nack', ({ connectionId, ackCode, reason }) => {
+ *   metrics.increment('mllp.nack', { code: ackCode, reason }); // e.g. reason='discarded-bytes'
+ * });
+ * ```
+ */
+interface NackEvent {
+    /** Connection that produced the negative acknowledgement. */
+    readonly connectionId: string;
+    /** The negative acknowledgement code sent to the peer (`AE` or `AR`). */
+    readonly ackCode: NegativeAckCode;
+    /** Why the negative acknowledgement was sent (PHI-free). */
+    readonly reason: NackReason;
+}
+/**
+ * Observability snapshot returned by `server.getStats()` (OBS-02).
+ *
+ * All fields are JSON-serializable. `connections` and `activeConnections` both
+ * reflect the current live connection count (ROADMAP SC-5 / OBS-02).
+ *
+ * @example
+ * ```typescript
+ * const stats = server.getStats();
+ * console.log(JSON.stringify(stats)); // log-pipeline friendly
+ * ```
+ */
+interface ServerStats {
+    /** Whether the server is currently accepting connections. */
+    readonly listening: boolean;
+    /** Bound port, or `null` before listen(). */
+    readonly port: number | null;
+    /** Bound host, or `null` before listen(). */
+    readonly host: string | null;
+    /**
+     * Current live connection count (OBS-02, ROADMAP SC-5).
+     * Same value as `activeConnections`.
+     */
+    readonly connections: number;
+    /** Current live connection count. Same value as `connections`. */
+    readonly activeConnections: number;
+    /** Aggregate bytes received across all current connections. */
+    readonly totalBytesIn: number;
+    /** Aggregate bytes sent across all current connections. */
+    readonly totalBytesOut: number;
+    /** Total connections accepted since listen() (monotonically increasing). */
+    readonly acceptedTotal: number;
+    /** Total connections closed since listen() (monotonically increasing). */
+    readonly closedTotal: number;
+    /** Whether this server is configured for TLS (Phase 8). Mirrors `ServerOptions.tls` being set. */
+    readonly tls: boolean;
+    /** Total `'tlsClientError'` events (failed TLS handshakes, incl. rejected client certs) since listen() (Phase 8). */
+    readonly tlsClientErrorsTotal: number;
+}
+/**
+ * Options for `createServer()`.
+ *
+ * @example
+ * ```typescript
+ * const opts: ServerOptions = {
+ *   onMessage: (payload, meta, conn) => {
+ *     const ack = buildAck(payload);
+ *     conn.send(ack);
+ *   },
+ *   framing: { maxFrameSizeBytes: 4 * 1024 * 1024 },
+ *   keepaliveIntervalMs: 60_000,
+ *   deadPeerTimeoutMs: 300_000,
+ *   drainTimeoutMs: 30_000,
+ * };
+ * ```
+ */
+interface ServerOptions {
+    /**
+     * Called for each decoded MLLP message.
+     *
+     * Its role depends on `autoAck` — this is the **commit contract** (HL7 v2.5.1 §2.9.2):
+     *
+     * - **`autoAck: 'AA'` + this handler ⇒ commit-gated (the safe default).** The handler
+     *   is the durable-commit step. The server **awaits** it and only then sends the ACK:
+     *   resolve ⇒ `AA`; **throw/reject ⇒ `AE`** (or `AR` via {@link MllpAckError}) — a
+     *   positive ACK can never precede a successful commit. Do **not** call `conn.send()`
+     *   here in this mode.
+     * - **`autoAck` unset ⇒ manual mode.** The handler owns the response; build and send the
+     *   ACK yourself via `conn.send(encodeFrame(ackPayload))`. Its return value is ignored.
+     * - **`autoAck: fn` ⇒ observation only.** `fn` builds the ACK; this handler runs first as
+     *   a side effect and its return value is ignored. Do not call `conn.send()` here.
+     *
+     * May be sync or async; an async handler is awaited in commit-gated mode.
+     */
+    onMessage?: (payload: Buffer, meta: MessageMeta, conn: Connection) => void | Promise<void>;
+    /**
+     * FrameReader tolerance options applied to every accepted connection (SERVER-12).
+     * Merged with SERVER_DEFAULT_FRAMING — caller-supplied values override defaults.
+     * `onFrame` and `onWarning` are managed internally and must not be supplied here.
+     */
+    framing?: Omit<FrameReaderOptions, "onFrame" | "onWarning">;
+    /**
+     * Per-connection warning subscriber. Called for every framing warning on every connection.
+     */
+    onWarning?: (w: MllpWarning) => void;
+    /**
+     * Auto-ACK mode. When set, the server builds and sends the ACK for each message.
+     *
+     * - **`'AA'`** — auto-acknowledge with the fail-safe **commit contract**:
+     *   - **With an `onMessage` handler ⇒ commit-gated (recommended).** The server awaits
+     *     `onMessage` (the durable-commit step), then sends `AA` on success or a **negative**
+     *     ACK on failure (`AE` by default; `AR` via {@link MllpAckError}). The positive ACK
+     *     **cannot precede a successful commit** — a handler throw can never yield `AA`.
+     *   - **Without an `onMessage` handler ⇒ transport-accept.** `AA` is sent on frame
+     *     receipt. This `AA` means only **"bytes received and framed"** — *not*
+     *     "application-processed". ⚠️ For clinical messages this is unsafe on its own:
+     *     pair `'AA'` with an `onMessage` handler that durably commits, so the ACK reflects
+     *     real processing.
+     * - **`fn`** — `fn(payload, meta, conn)` builds the ACK bytes the server sends; the
+     *   caller fully owns MSA-1 (e.g. to emit enhanced-mode `CA`/`CE`/`CR`).
+     *
+     * The `'message'` event always fires BEFORE the ACK is sent (D-03). Do NOT call
+     * `conn.send()` in `onMessage` when `autoAck` is set — this results in two ACKs.
+     */
+    autoAck?: "AA" | ((payload: Buffer, meta: MessageMeta, conn: Connection) => Buffer | Promise<Buffer>);
+    /**
+     * TCP keepalive probe interval in ms (D-10).
+     * Calls `socket.setKeepAlive(true, ms)` on each accepted socket.
+     * Uses OS TCP stack to detect dead peers (half-open, network partitions).
+     * Distinct from `deadPeerTimeoutMs` (application-level idle close).
+     */
+    keepaliveIntervalMs?: number;
+    /**
+     * Application-level idle close timeout in ms (D-11, ROADMAP SC-5).
+     * If no HL7 messages are received on a connection for this interval, the connection
+     * is destroyed via `conn.destroy(new Error('idle timeout'))`.
+     * Resets on every `'message'` event. Distinct from `keepaliveIntervalMs` (OS TCP probe).
+     */
+    deadPeerTimeoutMs?: number;
+    /**
+     * Graceful drain timeout passed to `conn.close()` during `server.close()` (D-06).
+     * Default: 30 000 ms.
+     */
+    drainTimeoutMs?: number;
+    /**
+     * Enable TLS (MLLPS) for this server (Phase 8). When set, the server binds a
+     * `tls.Server` instead of a plain `net.Server`, consumes `'secureConnection'`
+     * (post-handshake sockets) instead of `'connection'`, and surfaces failed
+     * handshakes via the `'tlsClientError'` event rather than crashing.
+     *
+     * Spec anchor: IHE ATNA ITI-19 (https://profiles.ihe.net/ITI/TF/Volume2/ITI-19.html).
+     *
+     * @default undefined (plaintext TCP)
+     */
+    tls?: ServerTlsOptions;
+    /**
+     * Opt-in required to bind a wildcard host — a bind-safety guardrail
+     * (Phase 8). Without this flag, `listen()` rejects a wildcard host in
+     * two tiers: **literal spellings** (`'0.0.0.0'`, `'::'`, `''`, `'::0'`,
+     * `'0:0:0:0:0:0:0:0'`, `'::ffff:0.0.0.0'`, …) reject **pre-bind** (fast
+     * path, nothing is ever bound); **resolver-only shorthands** (`'0'`,
+     * `'0.0'`, `'0x0.0.0.0'`, hostnames resolving to the unspecified
+     * address, …) are caught **post-bind** against the OS-normalized bound
+     * address — the just-bound server closes before any connection can be
+     * accepted and `listen()` rejects, with no listening state and no
+     * `'listening'` event either way. When `true`, binding a wildcard host
+     * emits a one-time `'securityWarning'` (`MLLP_BIND_ALL_INTERFACES`) at
+     * listen time.
+     *
+     * @default false
+     */
+    allowWildcardBind?: boolean;
+}
+/**
+ * Options for `createStarterServer()` — the "three lines of code" factory (SERVER-08).
+ *
+ * Extends `ServerOptions` with `port`, `host`, and `handleSignals`. Defaults:
+ * `autoAck: 'AA'`, `drainTimeoutMs: 30_000`, `Symbol.asyncDispose` wired.
+ *
+ * @example
+ * ```typescript
+ * import { createStarterServer } from '@cosyte/mllp';
+ *
+ * const server = await createStarterServer({
+ *   port: 2575,
+ *   onMessage: (buf) => buildAckBuffer(buf),
+ * });
+ * // server is listening, auto-ACK enabled, Symbol.asyncDispose wired
+ * await using _ = server; // closes on scope exit
+ * ```
+ */
+interface StarterServerOptions extends ServerOptions {
+    /** Port to listen on. */
+    port: number;
+    /**
+     * Host to bind to. Default `'127.0.0.1'` (Phase 8 bind-safety hardening —
+     * was `'0.0.0.0'`; binding all interfaces now requires
+     * `ServerOptions.allowWildcardBind: true`).
+     */
+    host?: string;
+    /**
+     * Register `process.once('SIGTERM')` and `process.once('SIGINT')` handlers that
+     * call `server.close()` then `process.exit(0)` (D-09). Default: `false`.
+     *
+     * Handlers are automatically removed when `server.close()` is called, so
+     * `process.listenerCount('SIGTERM') === 0` after close() completes — preventing
+     * handler accumulation across test instances or multiple server restarts.
+     */
+    handleSignals?: boolean;
+}
+/**
+ * MLLP TCP server — wraps `net.Server` without extending it (D-02).
+ *
+ * Each accepted socket is wrapped in a `NetTransport`, connected to a `Connection`
+ * with server-level framing options, and added to `_connections`. Messages are
+ * surfaced via the `'message'` event and the `onMessage` callback.
+ *
+ * Public events: `'listening'`, `'connection'`, `'message'`, `'nack'`, `'error'`, `'close'`.
+ * The `'nack'` event ({@link NackEvent}) fires whenever the server returns a negative ACK
+ * instead of `AA` on the auto-ACK path — a commit-gated `autoAck: 'AA'` handler failing, or
+ * a positive auto-ACK **downgraded** because the inbound could not be correlated (an
+ * unreadable/uncorrelatable message, or one whose bytes the decoder discarded). The
+ * {@link NackReason} distinguishes the causes.
+ *
+ * **`'error'` contract:** underlying `net.Server`/`tls.Server` errors are forwarded to the
+ * `'error'` event whenever a listener is attached. With **no** listener, the outcome depends on
+ * server state: during a `listen()` (the bind window) the error **rejects the `listen()` promise**
+ * — the primary error surface — and the process never crashes on a bind error; with no `listen()`
+ * in flight and the server not serving (e.g. a stale async error after `close()`) the error is
+ * dropped; but **while serving**, an unlistened runtime error (e.g. accept-loop `EMFILE`) keeps
+ * Node's fail-loud crash-on-unlistened-`'error'` convention — a silent accept outage is
+ * impossible. Caveat for `'error'` listeners: the forwarder runs **before** the internal
+ * `listen()` rejection handler, so an `'error'` listener that synchronously calls `close()`
+ * during the bind window changes the `listen()` rejection from the bind error to the typed
+ * close-during-listen `MllpConnectionError` — match on the `'error'` event payload, not the
+ * rejection, if you do that.
+ * Phase 8 (TLS/MLLPS) adds two more: `'tlsClientError'` (a failed TLS handshake — the
+ * server logs it and keeps serving other connections) and `'securityWarning'` (loud,
+ * one-time notice when a wildcard host is bound via `allowWildcardBind: true`).
+ * All event payloads are `Object.freeze()`'d before emission (SERVER-10).
+ *
+ * @example
+ * ```typescript
+ * import { createServer } from '@cosyte/mllp';
+ *
+ * const server = createServer({
+ *   onMessage: (payload, meta, conn) => {
+ *     console.log('received from', meta.connectionId);
+ *   },
+ * });
+ * await server.listen(2575);
+ * // await using server = createServer({ ... }); // Symbol.asyncDispose
+ * ```
+ */
+declare class MllpServer extends EventEmitter {
+    private readonly _netServer;
+    private readonly _connections;
+    private readonly _opts;
+    /** `true` when `ServerOptions.tls` is set — `_netServer` is actually a `tls.Server`. */
+    private readonly _isTls;
+    private _listening;
+    /** Phase 8 — single-flight guard: `true` while a `listen()` call is settling. */
+    private _listenInFlight;
+    /**
+     * Phase 8 — settle hook for an in-flight `listen()`. Non-null only while a
+     * `listen()` is in flight; invoked by `close()` so a close racing startup
+     * rejects the pending `listen()` (typed) instead of leaving it hung with
+     * the single-flight guard stuck. Cleared on every settle path.
+     */
+    private _pendingListenSettle;
+    private _port;
+    private _host;
+    private _acceptedTotal;
+    private _closedTotal;
+    /** Phase 8 — count of `'tlsClientError'` events since listen(). */
+    private _tlsClientErrorsTotal;
+    /**
+     * Construct an MLLP server. Created idle; call `listen()` (or use
+     * {@link createServer}/{@link createStarterServer}) to begin accepting connections.
+     *
+     * @param opts - Server options (bind host/port, auto-ACK policy, message handler, framing, …).
+     */
+    constructor(opts: ServerOptions);
+    /**
+     * Start listening on the given port.
+     *
+     * Resolves once the TCP socket is bound and emits `'listening'` with
+     * `Object.freeze({ port: actualPort, host: actualHost })`.
+     *
+     * **Single-flight:** one `listen()` per server lifecycle at a time. A call
+     * while the server is already listening — or while another `listen()` is
+     * still in flight — rejects with a typed `MllpConnectionError` (concurrent
+     * binds raced each other's post-bind safety checks). Call `close()` before
+     * re-listening; sequential `listen()` → `close()` → `listen()` is fine.
+     *
+     * **`close()` during an in-flight `listen()`** rejects that `listen()` with
+     * a typed `MllpConnectionError` (never a hang) and clears the single-flight
+     * guard — a subsequent `listen()` on the same server works. This makes
+     * `Symbol.asyncDispose` (which delegates to `close()`) safe even before a
+     * `listen()` has settled. (Exception: `close({ signal })` with an
+     * already-aborted signal is a no-op AbortError rejection — the in-flight
+     * `listen()` is left to settle on its own bind outcome; see `close()`.)
+     *
+     * @param port - TCP port to bind. Use `0` to let the OS assign an ephemeral port.
+     * @param hostOrOpts - Host string or object with `host` and optional `signal`.
+     *   Default host: `'127.0.0.1'` (Phase 8 bind-safety hardening). Wildcard hosts
+     *   are rejected unless `ServerOptions.allowWildcardBind: true` — literal
+     *   spellings pre-bind, resolver-only shorthands post-bind via the
+     *   OS-normalized bound address.
+     *
+     * @example
+     * ```typescript
+     * await server.listen(2575); // binds 127.0.0.1
+     * await server.listen(0, '127.0.0.1');
+     * await server.listen(0, { host: '127.0.0.1', signal: ac.signal });
+     * ```
+     */
+    listen(port: number, hostOrOpts?: string | {
+        host?: string;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * Stop accepting new connections and gracefully close all active connections.
+     *
+     * Sequence (D-06):
+     * 1. `net.Server.close()` — stops accepting new connections immediately
+     * 2. If `_connections` is empty: resolves immediately (no drain needed)
+     * 3. Calls `_drainAll(drainTimeoutMs)` — Promise.all + side-effect setTimeout
+     *    that force-destroys stragglers after the drain window
+     *
+     * Calling `close()` while a `listen()` is still in flight proactively
+     * settles that `listen()` with a typed `MllpConnectionError` rejection
+     * and clears the single-flight guard — the server is immediately
+     * re-listenable. `Symbol.asyncDispose` (which delegates here) is
+     * therefore safe before `listen()` settles. **Qualification:** a
+     * `close({ signal })` whose signal is **already aborted** rejects
+     * immediately with `AbortError` and performs no work — it does NOT close
+     * the server and does NOT settle the in-flight `listen()`, which simply
+     * continues and settles on its own bind outcome.
+     *
+     * @param opts.drainTimeoutMs - Override drain timeout (default: `opts.drainTimeoutMs ?? 30_000`).
+     * @param opts.signal - AbortSignal to cancel the close operation. On abort, all
+     *   active connections are destroyed and the promise rejects with AbortError.
+     *
+     * @example
+     * ```typescript
+     * await server.close({ drainTimeoutMs: 5_000 });
+     * ```
+     */
+    close(opts?: {
+        drainTimeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * Drain all active connections with a shared timeout.
+     *
+     * Uses Promise.all (not Promise.race) for coordination — the timeout is a
+     * side effect that calls `conn.destroy()` on stragglers after `drainTimeoutMs`.
+     * Promise.all resolves when all `conn.close()` promises settle (which happens
+     * because `conn.destroy()` transitions connections to CLOSED).
+     *
+     * @param drainTimeoutMs - Maximum time to wait for connections to drain.
+     */
+    private _drainAll;
+    /**
+     * Async disposal — delegates to `close()` for `await using` support.
+     *
+     * @example
+     * ```typescript
+     * await using server = createServer({ onMessage: handler });
+     * await server.listen(2575);
+     * // server.close() is called automatically at end of block
+     * ```
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * Return a JSON-serializable observability snapshot (OBS-02).
+     *
+     * `totalBytesIn` and `totalBytesOut` aggregate from live connections at call time.
+     * Plan 04 adds full aggregation; at Plan 01 scope they return 0.
+     *
+     * @example
+     * ```typescript
+     * const stats = server.getStats();
+     * logger.info(JSON.stringify(stats));
+     * ```
+     */
+    getStats(): ServerStats;
+    /**
+     * Emit on `'error'` only when a listener is attached — an unlistened
+     * `EventEmitter` `'error'` emission throws (see the class JSDoc error
+     * contract). The single guard shared by the optional-tap forwarding sites
+     * in this class; the constructor's net.Server forwarder deliberately does
+     * NOT use it (its while-serving branch re-emits unguarded to keep Node's
+     * fail-loud convention).
+     */
+    /**
+     * Emit a server event, containing a throwing subscriber.
+     *
+     * Every event this server emits is reachable from a callback we do not own — the `net.Server`
+     * `'connection'` listener, the `tls.Server` `'tlsClientError'` listener, a socket's `'data'`
+     * listener (via `Connection`), or the `catch` block of a `void`-ed async ACK task. A throwing
+     * subscriber would therefore unwind into that callback and kill the process (or reject a void-ed
+     * promise, which does the same and additionally skips the rest of the method).
+     *
+     * See `src/internal/safe-emit.ts` for the full rationale. The throw is re-surfaced on `'error'`.
+     */
+    private _emitContained;
+    private _emitErrorIfListened;
+    private _onSocketAccepted;
+    /**
+     * Extract a minimal, content-free peer-certificate summary (Phase 8, ATNA
+     * ITI-19 mutual authentication) — CN strings, expiry, and the verification
+     * outcome (`authorized`) only; never the full certificate object. Returns
+     * `null` when no peer certificate was presented (e.g. `clientAuth: 'WANT'`
+     * with no client cert).
+     */
+    private _extractPeerCertificateSummary;
+    /**
+     * The fail-safe commit path for `autoAck: 'AA'` (HL7 v2.5.1 §2.9.2).
+     *
+     * With an `onMessage` handler this **awaits** it (the durable-commit step) and only
+     * then dispatches: resolve ⇒ `AA`; throw/reject ⇒ a negative ACK (`AE` by default,
+     * `AR` via {@link MllpAckError}). A positive ACK can never precede a successful commit.
+     *
+     * Without an `onMessage` handler, `'AA'` degrades to a **transport-accept** — `AA`
+     * meaning "bytes received and framed", not "application-processed".
+     *
+     * A handler failure is **expected flow**, not a server error: it produces a negative
+     * ACK and a `'nack'` event. The thrown error's message is never placed on the wire or
+     * in the event (it may carry PHI) — only the static `ackCode` and the inbound control
+     * metadata reach the peer.
+     */
+    private _sendCommitAck;
+    /**
+     * Resolve the auto-ACK code for a message the server would otherwise acknowledge
+     * **positively** (`AA`) — the no-handler transport-accept and the post-commit success
+     * paths. Fail-safe: downgrade to `AE` and emit a PHI-safe `'nack'` whenever the message
+     * cannot carry a correlatable positive ACK, so `AA` never names a control ID the sender
+     * cannot match (→ timeout → resend → **duplicate clinical message**).
+     *
+     * Two independent disqualifiers, one from the bytes and one from the frame:
+     *
+     *   - **`rawAckUncorrelatable(payload)`** — no readable `MSH`, an empty MSH-10, or a
+     *     batch/concatenated-message shape. This is the SAME predicate `buildRawAck` enforces
+     *     on the wire; it is re-checked here so the downgrade is **observable** (a `'nack'`
+     *     event) rather than a silent code change inside the builder.
+     *   - **`MLLP_TRAILING_BYTES`** in the frame's warnings — a mid-payload `VT` made the
+     *     decoder discard accumulated bytes and deliver only the fragment after it. The
+     *     clinical message was destroyed in transit, so even a fragment that happens to carry
+     *     a readable MSH must not be positively acknowledged. This condition is invisible to
+     *     `buildRawAck` (it sees only the fragment), which is why it lives here. The code is
+     *     **reserved** for that discard (see the decoder's `_readPayload`) and is emitted while
+     *     accumulating the delivered frame, so it is frame-scoped: it names *this* payload's own
+     *     discard, never a neighbouring frame's trailing junk.
+     *
+     * `'discarded-bytes'` takes precedence in the reason when both hold — it is the root cause.
+     */
+    private _resolveAutoAckPositive;
+    /**
+     * Run `onMessage` for its side effects only (custom-ACK and manual modes), guarding
+     * against a synchronous throw or a rejected promise. In these modes the handler does
+     * **not** gate the ACK, so a failure is re-emitted as a PHI-safe `'error'` on the
+     * connection (D-04: a handler error never crashes the server) rather than escaping as
+     * an unhandled rejection. The error text is never placed on the wire.
+     */
+    private _observeMessage;
+    /**
+     * The custom-builder path for `autoAck: fn`. Awaits the builder and dispatches its
+     * Buffer as the ACK; the caller owns MSA-1. A builder error is re-emitted as `'error'`
+     * on the connection — the server never crashes (D-04).
+     */
+    private _sendCustomAck;
+    /**
+     * Frame an ACK payload and write it to the connection. `Connection.send()` returns
+     * `false` under backpressure (socket write buffer full); that drops the ACK and emits
+     * a `MllpConnectionError({ phase: 'send' })` on the connection (D-04) — the peer will
+     * time out waiting and may retry. The server never crashes.
+     */
+    private _dispatchAck;
+}
+/**
+ * Factory function — creates a new `MllpServer` with the supplied options.
+ *
+ * Prefer `createServer()` over `new MllpServer()` for forward-compatible construction.
+ *
+ * @example
+ * ```typescript
+ * import { createServer } from '@cosyte/mllp';
+ *
+ * const server = createServer({
+ *   onMessage: (payload, meta, conn) => {
+ *     console.log('received', payload.length, 'bytes');
+ *   },
+ * });
+ * await server.listen(2575);
+ * ```
+ */
+declare function createServer(opts?: ServerOptions): MllpServer;
+/**
+ * Starter factory — creates, configures, and starts an `MllpServer` in one call.
+ *
+ * Provides the "three lines of code" north-star experience with sensible defaults:
+ * `autoAck: 'AA'`, `drainTimeoutMs: 30_000`, `Symbol.asyncDispose` wired.
+ *
+ * NOTE: Stub at Plan 01 scope — Plan 04 fills in the full implementation.
+ *
+ * @example
+ * ```typescript
+ * import { createStarterServer } from '@cosyte/mllp';
+ *
+ * const server = await createStarterServer({
+ *   port: 2575,
+ *   onMessage: (payload) => buildAck(payload),
+ * });
+ * ```
+ */
+declare function createStarterServer(opts: StarterServerOptions): Promise<MllpServer>;
+
+/**
+ * MLLP Client — `createClient()` factory and `MllpClient` class.
+ *
+ * Provides the client-side MLLP transport: connect to an MLLP server over TCP,
+ * encode and send framed messages, decode inbound ACKs, and surface lifecycle
+ * events with frozen payloads. Supports `AbortSignal` cancellation on every
+ * awaitable and `Symbol.asyncDispose` for `await using` ergonomics.
+ *
+ * Phase 5 PLAN-01 shipped the lifecycle scaffolding — `connect()`, `close()`,
+ * `destroy()`, event re-emission. PLAN-02 added `send()` + `MllpTimeoutError`.
+ * The `correlateByControlId` option (MSH-10 → MSA-2 ACK matching) lights up
+ * out-of-order ACK handling. Subsequent plans add auto-reconnect (Plan 04),
+ * backpressure (Plan 05), and `createStarterClient` + `getStats()` (PLAN-06).
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from '@cosyte/mllp';
+ *
+ * const client = createClient({ host: 'localhost', port: 2575 });
+ * await client.connect();
+ * // PLAN-02 will add: const ack = await client.send(payloadBuffer);
+ * await client.close();
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Context passed to a custom `retryStrategy` hook on each reconnect attempt
+ * (CLIENT-12, D-15).
+ *
+ * Frozen via `Object.freeze` before invocation — handlers cannot mutate
+ * (T-05-04-04 mitigation).
+ *
+ * @example
+ * ```typescript
+ * const retryStrategy: RetryStrategy = (ctx) => {
+ *   if (ctx.attempt >= 5) return null;
+ *   if (ctx.classifiedAs === 'permanent') return null;
+ *   return Math.min(30_000, 1000 * (ctx.attempt + 1));
+ * };
+ * ```
+ */
+interface RetryContext {
+    /** 0-indexed attempt counter for the current reconnect cycle. */
+    readonly attempt: number;
+    /** The error that triggered the disconnect. */
+    readonly lastError: Error;
+    /** Delay used for the previous attempt (ms). 0 on the first attempt. */
+    readonly lastDelayMs: number;
+    /** Total wall-clock ms elapsed since the disconnect that started this cycle. */
+    readonly totalElapsedMs: number;
+    /** Ms since the last successful ACK. `Infinity` if no success seen. */
+    readonly sinceLastSuccessMs: number;
+    /** CLIENT-18 classification (Composition A — D-16). */
+    readonly classifiedAs: "transient" | "permanent";
+    /**
+     * The same `AbortSignal` passed into `connect()`. If no signal was
+     * supplied, the module-level `NEVER_ABORTING_SIGNAL` sentinel is provided
+     * so handlers always have a real `AbortSignal` to inspect. (D-18, W-07)
+     */
+    readonly signal: AbortSignal;
+}
+/**
+ * Custom reconnect-backoff hook (CLIENT-12). Return `null` to halt
+ * reconnection (D-17) — the FSM transitions to `CLOSED`.
+ */
+type RetryStrategy = (ctx: RetryContext) => number | null;
+/**
+ * Combined count + byte-based queue cap. Stricter-of-two wins (D-23).
+ *
+ * - `number` — count cap only (default 64).
+ * - `{ bytes }` — byte cap only.
+ * - `{ count, bytes }` — both caps; whichever trips first wins.
+ *
+ * @example
+ * ```typescript
+ * const opts: ClientOptions = {
+ *   host: 'localhost', port: 2575,
+ *   highWaterMark: { count: 100, bytes: 1_000_000 },
+ * };
+ * ```
+ */
+type HighWaterMark = number | {
+    readonly count?: number;
+    readonly bytes?: number;
+};
+/**
+ * Options for {@link createClient} and the {@link MllpClient} constructor.
+ *
+ * Phase 5 plans extend this incrementally — new fields are additive and optional.
+ *
+ * @example
+ * ```typescript
+ * const opts: ClientOptions = { host: 'localhost', port: 2575, drainTimeoutMs: 10_000 };
+ * ```
+ */
+interface ClientOptions {
+    /** Host to connect to (e.g. `'localhost'` or `'mllp.example.com'`). */
+    readonly host: string;
+    /** TCP port. */
+    readonly port: number;
+    /** FrameReader tolerance / size options. `onFrame` and `onWarning` are managed internally. */
+    readonly framing?: Omit<FrameReaderOptions, "onFrame" | "onWarning">;
+    /** Drain timeout for {@link MllpClient.close} (default: `30_000` ms). */
+    readonly drainTimeoutMs?: number;
+    /**
+     * Per-message ACK timeout in milliseconds (CLIENT-04). The clock starts at
+     * the underlying `write()` flush callback, NOT at the `send()` call —
+     * pre-flush queue time is not charged to the peer. Default: `30_000`.
+     */
+    readonly ackTimeoutMs?: number;
+    /**
+     * If `true`, ACKs are matched against outgoing sends by MSH-10 → MSA-2
+     * (CLIENT-03 controlId branch). Default `false` (FIFO mode).
+     *
+     * Out-of-order ACKs from the peer are supported in this mode. MSH-10 is
+     * extracted from the outbound payload before send; MSA-2 is extracted from
+     * the inbound ACK payload. An ACK whose MSA-2 matches no pending send
+     * (and is not in the late-ACK graveyard) emits a frozen
+     * `MllpFramingError('MLLP_ACK_UNMATCHED_CONTROL_ID')` to the `'error'` event
+     * (CLIENT-15). A late ACK whose MSA-2 matches a graveyard entry emits a
+     * `MLLP_ACK_AFTER_TIMEOUT` warning (CLIENT-16) and is dropped.
+     *
+     * @default false
+     */
+    readonly correlateByControlId?: boolean;
+    /**
+     * Auto-reconnect on transient disconnect (CLIENT-05). Default `false`.
+     *
+     * When `true`, dropped connections caused by transient errors (per
+     * {@link isTransientConnectionError}) trigger the FSM cycle
+     * `CONNECTED → DISCONNECTED → RECONNECTING → CONNECTING → CONNECTED`
+     * with exponential backoff per D-19 unless overridden by
+     * {@link ClientOptions.retryStrategy}. Permanent errors halt and
+     * transition directly to `CLOSED` (Composition A — D-16).
+     */
+    readonly autoReconnect?: boolean;
+    /**
+     * Custom reconnect-backoff hook (CLIENT-12, D-15). Return `null` to halt
+     * reconnection (D-17). Receives a frozen {@link RetryContext}. Defaults
+     * to the exponential strategy described in D-19.
+     */
+    readonly retryStrategy?: RetryStrategy;
+    /** First delay (ms) on auto-reconnect; default 100. (CLIENT-05, D-19) */
+    readonly initialDelayMs?: number;
+    /** Maximum backoff cap (ms); default 30_000. (CLIENT-05, D-19) */
+    readonly maxDelayMs?: number;
+    /** Backoff multiplier; default 2. (CLIENT-05, D-19) */
+    readonly multiplier?: number;
+    /** Jitter fraction, e.g. 0.2 = ±20%; default 0.2. (CLIENT-05, D-19) */
+    readonly jitter?: number;
+    /**
+     * Application-level high-water mark on the in-flight + queued send set
+     * (CLIENT-07, D-23). `number` configures a count cap (default 64);
+     * `{ bytes }` configures a byte cap; `{ count, bytes }` configures
+     * both, with the stricter-of-two trigger winning.
+     *
+     * When the cap is exceeded, behavior is governed by
+     * {@link ClientOptions.onBackpressure}.
+     *
+     * @default 64
+     */
+    readonly highWaterMark?: HighWaterMark;
+    /**
+     * Behavior when the high-water mark is exceeded (CLIENT-07).
+     *
+     * - `'reject'` (default) — `send()` rejects with `MllpBackpressureError`.
+     * - `'wait'` — `send()` awaits the `'drain'` event OR the per-message
+     *   `ackTimeoutMs` OR `signal` abort, whichever fires first (CLIENT-11).
+     *
+     * @default 'reject'
+     */
+    readonly onBackpressure?: "reject" | "wait";
+    /**
+     * Strict serialization send → await-ACK → send (CLIENT-19, D-06).
+     *
+     * - `true` (default) — concurrent in-flight sends up to
+     *   {@link ClientOptions.highWaterMark}.
+     * - `false` — collapses the in-flight set to ≤1 (the unified Correlator's
+     *   `maxInFlight=1`); the next `send()` waits for the prior ACK before
+     *   reaching the wire.
+     *
+     * @default true
+     */
+    readonly pipeline?: boolean;
+    /**
+     * TCP keepalive interval (ms). Sets `socket.setKeepAlive(true, ms)` on
+     * the underlying `net.Socket` BEFORE wrapping in `NetTransport`. OS-level
+     * half-open detection (network partitions, NAT-table eviction). Independent
+     * of {@link ClientOptions.deadPeerTimeoutMs} (CLIENT-08, D-11/A3).
+     *
+     * @default undefined (off)
+     */
+    readonly keepaliveIntervalMs?: number;
+    /**
+     * Application-idle timeout (ms) keyed on last inbound bytes / ACK / warning
+     * (CLIENT-08, D-11). On trip, calls `connection.destroy(new Error('dead
+     * peer timeout'))` which surfaces as `MllpConnectionError({ phase: 'receive' })`.
+     * Trip honors {@link ClientOptions.autoReconnect} (D-13). Independent of
+     * {@link ClientOptions.keepaliveIntervalMs} (D-11/A3).
+     *
+     * @default undefined (off)
+     */
+    readonly deadPeerTimeoutMs?: number;
+    /**
+     * Enable TLS (MLLPS) for this connection (Phase 8). `true` enables TLS with
+     * all defaults — including certificate verification **on**. Pass a
+     * {@link TlsOptions} object to customize (`ca`/`cert`/`key`, minimum
+     * version, ciphers, `allowUnverified`, …).
+     *
+     * Spec anchor: IHE ATNA ITI-19 (https://profiles.ihe.net/ITI/TF/Volume2/ITI-19.html).
+     *
+     * @default undefined (plaintext TCP)
+     */
+    readonly tls?: TlsOptions | true;
+}
+/**
+ * Observability snapshot returned by {@link MllpClient.getStats} (OBS-01, D-26).
+ *
+ * All fields are JSON-serializable (OBS-04) — no Buffers, no class instances,
+ * no Maps, no circular references. `lastConnectedAt` and `lastAckAt` are
+ * **epoch milliseconds** (numbers), NOT `Date` instances — log-pipeline
+ * friendly per D-26.
+ *
+ * `warningsByCode` keys are constrained to the public {@link WarningCode}
+ * union — adding/removing a code is a breaking change (CLAUDE.md
+ * stable-codes guardrail enforced at the type boundary, B-05).
+ *
+ * @example
+ * ```typescript
+ * const stats = client.getStats();
+ * logger.info(JSON.stringify(stats));
+ * // {"state":"CONNECTED","connectionId":"…","queueDepth":0, … }
+ * ```
+ */
+interface ClientStats {
+    /** Current FSM state — mirrors `client.state`. */
+    readonly state: ConnectionState;
+    /** Live Connection's id, or `null` before the first connect (or post-CLOSED). */
+    readonly connectionId: string | null;
+    /** Total live correlator entries (in-flight + pre-flush + serialization-queued). */
+    readonly queueDepth: number;
+    /** Sum of `frame.length` across live correlator entries. */
+    readonly queueBytes: number;
+    /** Entries with `sentAt !== null` — actually written to the wire / awaiting ACK. */
+    readonly inFlight: number;
+    /**
+     * Aggregated warning counts. Keys are constrained to the public
+     * {@link WarningCode} union (B-05). Connection-level warnings + Correlator
+     * `MLLP_ACK_*` warnings are merged.
+     */
+    readonly warningsByCode: Partial<Record<WarningCode, number>>;
+    /** Bytes received from the peer (current Connection). */
+    readonly totalBytesIn: number;
+    /** Bytes written to the peer (current Connection). */
+    readonly totalBytesOut: number;
+    /** Total successful `connection.send()` calls since construction. */
+    readonly sentTotal: number;
+    /** Total ACKs matched + resolved since construction. */
+    readonly ackedTotal: number;
+    /** Total ACK timeouts since construction. */
+    readonly timedOutTotal: number;
+    /** Total reconnect attempts since construction (W-02). */
+    readonly reconnectAttempts: number;
+    /** Epoch ms of the last `CONNECTED` transition. `null` until first connect. */
+    readonly lastConnectedAt: number | null;
+    /** Epoch ms of the most recent successful ACK. `null` until first ACK. */
+    readonly lastAckAt: number | null;
+    /** Whether this client is configured for TLS (Phase 8). Mirrors `ClientOptions.tls` being set. */
+    readonly tls: boolean;
+}
+/**
+ * MLLP client — composes a single Phase 3 {@link Connection} over a {@link NetTransport}
+ * (production) or any other `Transport` (testing via {@link InMemoryTransport}).
+ *
+ * Public events — every payload `Object.freeze`'d before emission (D-25):
+ * - `'stateChange'` — `{ from, to, reason? }` from the underlying Connection FSM
+ * - `'connect'` — `{ connectionId }` once the FSM enters `CONNECTED`
+ * - `'disconnect'` — `{ connectionId }` once the FSM enters `DISCONNECTED`
+ * - `'reconnecting'` — `{ connectionId, attempt?, delayMs? }` (Plan 04 populates)
+ * - `'close'` — `{ connectionId }` once the FSM enters terminal `CLOSED`
+ * - `'message'` — `{ payload, connectionId, byteOffset, warnings }` for every inbound frame
+ * - `'warning'` — `MllpWarning` enriched with `connectionId` from the Connection layer
+ * - `'securityWarning'` — `SecurityWarning` (Phase 8). Emitted on every successful
+ *   `secureConnect` (initial + every reconnect) when `tls.allowUnverified` is `true`
+ *   — code `MLLP_TLS_VERIFY_DISABLED`. Also mirrored to `process.emitWarning`.
+ * - `'error'` — re-emitted from Connection. Guarded by `listenerCount('error') > 0` so
+ *   absence of a listener does NOT crash the process (server precedent).
+ *
+ * @example
+ * ```typescript
+ * const client = createClient({ host: 'localhost', port: 2575 });
+ * client.on('stateChange', ({ from, to }) => logger.info({ from, to }));
+ * client.on('message', ({ payload }) => logger.info({ bytes: payload.length }));
+ * await client.connect();
+ * // PLAN-02 will add: const ack = await client.send(payloadBuffer);
+ * await client.close();
+ * ```
+ */
+declare class MllpClient extends EventEmitter {
+    private readonly _opts;
+    private _connection;
+    private _socket;
+    /**
+     * Initial state for `get state()` before `_connection` exists. Once a Connection
+     * is attached, `state` mirrors `_connection.state`.
+     */
+    private _state;
+    /** Per-message ACK timeout in ms (CLIENT-04). Resolved at construction. */
+    private readonly _ackTimeoutMs;
+    /** controlId-mode flag (CLIENT-03 branch). `false` → FIFO. */
+    private readonly _correlateByControlId;
+    /** Unified ACK correlator (D-03/A1). Built during `_attachConnection`. */
+    private _correlator;
+    /**
+     * Periodic ACK-timeout sweep timer. Drives `_correlator.expireDue()` because
+     * the Correlator is timer-free per D-03. Cleared on close/destroy.
+     */
+    private _ackSweepTimer;
+    private readonly _autoReconnect;
+    private readonly _initialDelayMs;
+    private readonly _maxDelayMs;
+    private readonly _multiplier;
+    private readonly _jitter;
+    private readonly _retryStrategy;
+    /** 0-indexed attempt counter for the current reconnect cycle. */
+    private _attempt;
+    /**
+     * W-02 — total reconnect attempts since construction. Read by PLAN-06 for
+     * `getStats().reconnectAttempts`. Incremented at the entry of every
+     * `_handleDisconnect` invocation that proceeds to schedule a backoff.
+     */
+    private _reconnectAttempts;
+    /** Epoch ms of the last successful ACK. Drives W-01 backoff-reset. */
+    private _lastSuccessAt;
+    /** Epoch ms when the current reconnect cycle began. `null` outside a cycle. */
+    private _reconnectCycleStartedAt;
+    /** Active backoff `setTimeout` handle. `null` when no backoff is armed. */
+    private _backoffTimer;
+    /** Last delay (ms) used by the strategy. Surfaced via RetryContext.lastDelayMs. */
+    private _lastDelayMs;
+    /** Count cap; `Number.POSITIVE_INFINITY` when only bytes configured. */
+    private readonly _hwmCount;
+    /** Byte cap; `Number.POSITIVE_INFINITY` when only count configured. */
+    private readonly _hwmBytes;
+    /** Backpressure policy; default `'reject'`. */
+    private readonly _onBackpressure;
+    /** Pipeline flag; default `true` (parallel up to highWaterMark). */
+    private readonly _pipeline;
+    /** Dead-peer idle timer (Plan 05 — D-11). `null` when not armed. */
+    private _deadPeerTimer;
+    /** True once the self-'ack' listener that resets the dead-peer timer
+     * has been attached. Guards against duplicate listeners on reconnect. */
+    private _ackResetWired;
+    /** Most recently bound `connect()` signal. Reread on every RetryContext build (W-07). */
+    private _connectSignal;
+    /** Set when close()/destroy()/abort fires; reconnect handler short-circuits. */
+    private _userClosed;
+    /** Captured Connection error feeding `RetryContext.lastError`. */
+    private _lastError;
+    /** Listener-removal handle for the abort listener bound in connect(). */
+    private _abortListener;
+    /**
+     * Test-only seam — when set, `_beginReconnectAttempt` builds the new
+     * Connection through this factory instead of opening a real net.Socket.
+     *
+     * @internal
+     */
+    private _reconnectFactory;
+    /** Total successful `conn.send()` flushes since construction. */
+    private _sentTotal;
+    /** Total ACKs resolved since construction. */
+    private _ackedTotal;
+    /** Total ACK timeouts since construction. */
+    private _timedOutTotal;
+    /** Epoch ms of the most recent CONNECTED transition (null until first). */
+    private _lastConnectedAt;
+    /** Epoch ms of the most recent successful ACK (null until first). */
+    private _lastAckAt;
+    /**
+     * Aggregated Correlator-emitted warning counts (MLLP_ACK_*). Connection-level
+     * warnings are read directly from `_connection.getStats().warningsByCode`
+     * at observation time and merged into the snapshot (D-26).
+     */
+    private _aggregatedWarningsByCode;
+    /**
+     * Construct an MLLP client. Created idle; call `connect()` (or use
+     * {@link createClient}/{@link createStarterClient}) to open the connection.
+     *
+     * @param opts - Client options (host/port, ACK timeout, reconnect/backpressure policy, …).
+     */
+    constructor(opts: ClientOptions);
+    /**
+     * Current FSM state. Mirrors the underlying Connection's state once attached;
+     * before `connect()` (or after a `CLOSED` Connection is dropped) reports
+     * the client-level baseline (`'DISCONNECTED'`).
+     */
+    get state(): ConnectionState;
+    /**
+     * Open a TCP (or TLS — Phase 8) connection to the configured `host:port`
+     * and attach a Phase 3 {@link Connection} to it. Resolves once the FSM
+     * enters `CONNECTED` — for TLS, on `'secureConnect'` (handshake complete,
+     * including certificate verification when it is on).
+     *
+     * Rejects with:
+     * - `DOMException('Aborted', 'AbortError')` if `signal` is provided and aborts
+     *   before the connect resolves.
+     * - `MllpConnectionError({ phase: 'connect' })` if the underlying socket emits
+     *   `error` before connecting, OR if the client is already connecting/connected.
+     *   TLS failures carry a `connectionCause`: `'tls-verify'` for certificate
+     *   verification failures, `'tls-handshake'` for TLS-protocol-shaped failures
+     *   ({@link isTlsProtocolError}); pure TCP failures carry none.
+     *
+     * **Dual failure signal on initial connect:** the Connection's transport
+     * error handler is attached before this promise's own error listener, so a
+     * pre-connect socket error produces BOTH the promise rejection AND a
+     * client `'error'` event (when an `'error'` listener is attached). Handle
+     * whichever fits your flow; they describe the same underlying failure.
+     *
+     * **TLS 1.3 + mutual TLS caveat (RFC 8446 §4.4.2):** `connect()` resolving
+     * does NOT guarantee that a `clientAuth: 'MUST'` server accepted your
+     * client certificate. Under TLS 1.3 the client's handshake — and its
+     * `'secureConnect'` — can complete before the server finishes validating
+     * the certificate; a rejection then surfaces moments later as a typed
+     * post-connect error (`'error'` event with an `ERR_SSL_*`/alert cause,
+     * classified **permanent** — no auto-reconnect loop). ACK correlation via
+     * {@link MllpClient.send} remains the delivery guarantee: no send resolves
+     * without its ACK, so a rejected session can never silently "deliver".
+     *
+     * @example
+     * ```typescript
+     * const ac = new AbortController();
+     * setTimeout(() => ac.abort(), 5_000);
+     * await client.connect({ signal: ac.signal });
+     * ```
+     */
+    connect(opts?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * Build the raw socket + `Transport` pair for a connect / reconnect attempt.
+     *
+     * Plaintext (`ClientOptions.tls` unset): a `net.Socket` wrapped in
+     * `NetTransport`. TLS (Phase 8): a `tls.TLSSocket` wrapped in
+     * `TlsTransport` — verification defaults **on**
+     * (`rejectUnauthorized: !allowUnverified`), floor `minVersion: 'TLSv1.2'`
+     * (the IHE ATNA ITI-19 BCP195 floor), `servername` defaulting to
+     * `ClientOptions.host`.
+     */
+    private _createSocketAndTransport;
+    /**
+     * Wrap a connect-phase socket error as `MllpConnectionError`, classifying
+     * TLS failures (Phase 8) into the additive `connectionCause`:
+     *
+     * - `'tls-verify'` — certificate-verification failures
+     *   ({@link isTlsVerificationErrorCode}).
+     * - `'tls-handshake'` — TLS-**protocol**-shaped failures only
+     *   ({@link isTlsProtocolError}): `ERR_SSL_*`, `EPROTO`, OpenSSL
+     *   alert-bearing errors.
+     * - **No `connectionCause`** — pure TCP-level failures (`ECONNREFUSED`,
+     *   `ETIMEDOUT`, …) even on a TLS-configured connection; these carry the
+     *   same shape as plaintext connect failures.
+     */
+    private _wrapConnectError;
+    /**
+     * Emit a client event, containing a throwing subscriber.
+     *
+     * Every event this client emits is reached from a callback we do not own — a socket's
+     * `'connect'`/`'secureConnect'`/`'data'`/`'error'` listener, or a backoff timer. A throwing
+     * subscriber would unwind into it and kill the process, and on several paths it would also skip
+     * the work queued after the emit (the `resolve()` of `connect()`, the backoff scheduling).
+     *
+     * See `src/internal/safe-emit.ts`. The throw is re-surfaced on `'error'`.
+     */
+    private _emitContained;
+    /**
+     * Emit the per-connection insecure-TLS warning (Phase 8) when
+     * `tls.allowUnverified === true` — fires on EVERY successful
+     * `secureConnect`, initial connect and every reconnect. Emits both a frozen
+     * `'securityWarning'` event and `process.emitWarning`. No-op for plaintext
+     * connections or when verification is on.
+     */
+    private _emitInsecureWarningIfNeeded;
+    /**
+     * Wire a Connection's events through to this MllpClient. Every re-emitted
+     * payload is `Object.freeze`'d before emission (D-25), even though the
+     * Connection layer already freezes — defense-in-depth, harmless on
+     * already-frozen objects.
+     *
+     * Builds the unified `Correlator` (D-03/A1) bound to this Connection and
+     * arms the periodic ACK-timeout sweep. The Correlator is teardown-aware:
+     * `close()` / `destroy()` clear the sweep timer and reject pending sends.
+     *
+     * @param conn - Connection to subscribe to.
+     */
+    private _attachConnection;
+    /**
+     * Arm (or re-arm) the dead-peer idle timer (Plan 05 — CLIENT-08, D-11).
+     * No-op when `deadPeerTimeoutMs` is unset.
+     */
+    private _armDeadPeerTimer;
+    /**
+     * Clear the dead-peer idle timer (Plan 05 — D-14 timer cleanup on
+     * every transition out of CONNECTED).
+     */
+    private _clearDeadPeerTimer;
+    /**
+     * Disconnect handler — Plan 04 reconnect FSM core.
+     *
+     * Implements:
+     * - CLIENT-17 hybrid in-flight handling (D-08): controlId mode preserves
+     *   pending sends for resend; FIFO mode rejects in-flight with
+     *   `connectionCause: 'in-flight-orphan'` and queued with `'fifo-unsafe'`.
+     * - CLIENT-18 classifier-first (Composition A — D-16): permanent errors
+     *   transition straight to CLOSED without invoking `retryStrategy`.
+     * - W-01 backoff-reset on recent success: first disconnect after a
+     *   successful ACK on the prior session resets `_attempt` to 0.
+     * - W-02 `_reconnectAttempts` counter increment.
+     * - D-15 frozen RetryContext + D-17 null-return halts.
+     * - D-19 default exponential strategy.
+     *
+     * Invoked from the SINGLE `_onStateChange` hook — no parallel listener
+     * (B-04). Idempotent across same-cycle re-entry: cycle-start flag
+     * coordinates first-disconnect vs subsequent-within-cycle behavior.
+     */
+    private _handleDisconnect;
+    /**
+     * Default retry strategy (D-19): `min(maxDelay, initialDelay * multiplier^attempt)`
+     * with ±jitter applied.
+     */
+    private _defaultRetryStrategy;
+    /**
+     * Open a fresh Connection for the next reconnect attempt.
+     *
+     * In production, builds a new `net.Socket` + `NetTransport` + `Connection`.
+     * In tests, the `_reconnectFactory` seam returns a pre-built Connection
+     * over `InMemoryTransport.pair()`.
+     *
+     * On successful CONNECTED transition:
+     * - controlId mode: re-transmits every live correlator entry via the
+     *   already-encoded `PendingAck.frame`, then `markFlushed`'s each one
+     *   so ACK timeouts restart from the new flush time.
+     * - All modes: clears the cycle-start flag so the next disconnect
+     *   can re-enter `_handleDisconnect` cleanly.
+     */
+    private _beginReconnectAttempt;
+    /**
+     * Post-CONNECTED steps for a reconnect attempt:
+     * - controlId mode: resend every live correlator entry's frame, then
+     *   re-stamp `markFlushed` so ACK timers reset from the new flush.
+     * - Clear the cycle-start flag so the next disconnect re-enters cleanly.
+     */
+    private _afterReconnectArmed;
+    /**
+     * Test seam — install a factory that produces the next reconnect Connection.
+     *
+     * @internal
+     */
+    _setReconnectFactory(factory: () => {
+        conn: Connection;
+        arm: () => void;
+    }): void;
+    /**
+     * Test seam — capture or rebind the connect-signal mid-flight (W-07).
+     *
+     * @internal
+     */
+    _captureConnectSignal(signal: AbortSignal): void;
+    /**
+     * Single source-of-truth for inbound ACK payload handling.
+     *
+     * - FIFO mode: passes `null` controlId so `matchAck` returns the head of
+     *   the live store.
+     * - controlId mode: extracts MSA-2 at the `HOOK_EXTENSION_POINT: ack-payload`
+     *   anchor and passes it to `matchAck` for keyed lookup.
+     *
+     * Called from the SINGLE `'message'` listener registered in `_attachConnection`.
+     * No parallel listener is registered — downstream plans extend at the named
+     * anchor (B-04).
+     */
+    private _onAckPayload;
+    /**
+     * Single source-of-truth for a successfully matched ACK (live-store hit).
+     *
+     * PLAN-02: emit frozen 'ack' event, call matched.resolve().
+     * Plan 04 extends at HOOK_EXTENSION_POINT: ack-matched to update _lastSuccessAt.
+     * PLAN-06 extends at HOOK_EXTENSION_POINT: ack-matched to bump _ackedTotal and
+     *   set _lastAckAt.
+     *
+     * Called from _onAckPayload when matchAck() returns a non-null PendingAck.
+     */
+    private _onAckMatched;
+    /**
+     * Emit a frozen `'drain'` event when the queue depth and bytes fall below
+     * both configured caps (Plan 05 — D-24). Called from `_onAckMatched`
+     * (every successful ACK) and from the Correlator's `onTimeout` callback
+     * (every expired send) — both code paths free a live-store slot.
+     */
+    private _maybeEmitDrain;
+    /**
+     * Single source-of-truth for Connection FSM transitions.
+     *
+     * PLAN-02: re-emit frozen 'stateChange' (was inline in PLAN-01; centralized
+     * here so Plan 04 / Plan 05 can extend at named anchors).
+     * Plan 04 extends at HOOK_EXTENSION_POINT: state-change to detect
+     *   CONNECTED → DISCONNECTED|RECONNECTING and trigger _handleDisconnect.
+     * Plan 05 extends at HOOK_EXTENSION_POINT: state-change to clear/arm
+     *   dead-peer timer on transitions out of / into CONNECTED.
+     *
+     * Called from the SINGLE 'stateChange' listener registered in _attachConnection.
+     */
+    private _onStateChange;
+    /**
+     * Send an MLLP-framed payload and await the inbound ACK (CLIENT-02).
+     *
+     * Resolves with the ACK Buffer (framing stripped). Rejects with:
+     * - `DOMException('Aborted', 'AbortError')` if `signal` aborts before ACK
+     *   (CLIENT-11 send branch).
+     * - `MllpTimeoutError` if no ACK arrives within `ackTimeoutMs` (ERR-02).
+     *   The clock starts at the underlying `write()` flush callback, NOT at
+     *   the `send()` call (CLIENT-04, D-19).
+     * - `MllpConnectionError({ phase: 'send' })` if the client is not connected.
+     *
+     * Emits a frozen `'ack'` event on every successful match (D-25 + Specifics).
+     *
+     * @example
+     * ```typescript
+     * const ack = await client.send(payloadBuffer);
+     * logger.info({ ack: ack.toString('utf8') });
+     * ```
+     *
+     * @param payload Raw bytes; MLLP framing is added internally via `encodeFrame`.
+     * @param opts.signal AbortSignal — aborting cancels the ACK wait (CLIENT-11).
+     */
+    send(payload: Buffer, opts?: {
+        signal?: AbortSignal;
+        ackTimeoutMs?: number;
+    }): Promise<Buffer>;
+    /**
+     * 'wait'-mode backpressure handler (Plan 05 — CLIENT-07/CLIENT-11).
+     *
+     * Awaits one of three terminating signals, in order:
+     * - `'drain'` event → re-enter `send()` (the gate will now pass).
+     * - `ackTimeoutMs` elapses → reject with `MllpTimeoutError`.
+     * - Caller's `signal` aborts → reject with `AbortError` (B-06). Cleanup
+     *   removes the drain listener AND the abort listener AND clears the
+     *   timer to prevent leaks.
+     */
+    private _waitThenSend;
+    /**
+     * Tear down per-connection state (sweep timer + correlator) when the
+     * client is closing or destroying. Safe to call multiple times.
+     */
+    private _teardownCorrelator;
+    /**
+     * **Test seam** — attach an externally-built {@link Connection} directly,
+     * bypassing the `net.createConnection` + `NetTransport` path. Used by
+     * lifecycle tests driving `InMemoryTransport.pair()` for determinism.
+     *
+     * @internal
+     */
+    _attachExistingConnection(conn: Connection): void;
+    /**
+     * Gracefully close the client.
+     *
+     * Delegates to {@link Connection.close}, which transitions `CONNECTED → DRAINING
+     * → DISCONNECTED` (or `CLOSED` on drain timeout). No-op if no Connection is
+     * attached.
+     *
+     * Rejects with `DOMException('Aborted', 'AbortError')` if `signal` aborts mid-drain;
+     * on abort, the underlying Connection is force-destroyed.
+     *
+     * @example
+     * ```typescript
+     * await client.close({ drainTimeoutMs: 5_000 });
+     * ```
+     */
+    close(opts?: {
+        drainTimeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * Abruptly destroy the client — force-transitions the underlying Connection
+     * to `CLOSED` immediately. No-op if no Connection is attached. Idempotent.
+     *
+     * @example
+     * ```typescript
+     * client.destroy(new Error('shutting down'));
+     * ```
+     */
+    destroy(reason?: Error): void;
+    /**
+     * Returns a JSON-serializable observability snapshot (OBS-01, D-26).
+     *
+     * All fields are plain values — no Buffers, no class instances, no Maps,
+     * no circular refs. Safe to `JSON.stringify` directly.
+     *
+     * `inFlight` is the count of correlator entries with `sentAt !== null`
+     * (entries actually written to the wire and awaiting ACK), distinct from
+     * `queueDepth` which counts ALL live correlator entries (including
+     * pre-flush and serialization-queued sends).
+     *
+     * @example
+     * ```typescript
+     * setInterval(() => logger.info(JSON.stringify(client.getStats())), 60_000);
+     * ```
+     */
+    getStats(): ClientStats;
+    /**
+     * Async disposal — delegates to {@link MllpClient.close} for `await using` support.
+     *
+     * @example
+     * ```typescript
+     * await using client = createClient({ host: 'localhost', port: 2575 });
+     * await client.connect();
+     * // client.close() is called automatically at end of block
+     * ```
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+}
+/**
+ * Create an {@link MllpClient}. Equivalent to `new MllpClient(opts)`.
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from '@cosyte/mllp';
+ *
+ * const client = createClient({ host: 'localhost', port: 2575 });
+ * await client.connect();
+ * // PLAN-02 will add: const ack = await client.send(payloadBuffer);
+ * await client.close();
+ * ```
+ */
+declare function createClient(opts: ClientOptions): MllpClient;
+/**
+ * Options for {@link createStarterClient} (PLAN-06, CLIENT-10).
+ *
+ * The starter applies opinionated D-22 defaults on top of `ClientOptions`,
+ * so every override here is optional except `host` + `port`. The
+ * starter-specific addition is `handleSignals` (mirrors `createStarterServer`).
+ *
+ * @example
+ * ```typescript
+ * const opts: StarterClientOptions = {
+ *   host: 'localhost',
+ *   port: 2575,
+ *   onMessage: (payload) => logger.info({ bytes: payload.length }),
+ *   handleSignals: true,
+ * };
+ * ```
+ */
+interface StarterClientOptions {
+    /** Host to connect to. */
+    readonly host: string;
+    /** TCP port. */
+    readonly port: number;
+    /**
+     * Inbound-message callback (any framed payload from the peer, including
+     * non-ACK messages on bidirectional channels). Mirrors the server-side
+     * `onMessage` ergonomics.
+     */
+    readonly onMessage?: (payload: Buffer) => void;
+    /** Override default `30_000`. */
+    readonly ackTimeoutMs?: number;
+    /** Override default `false` (FIFO mode). */
+    readonly correlateByControlId?: boolean;
+    /** Override default `true` (parallel up to highWaterMark). */
+    readonly pipeline?: boolean;
+    /** Override default `64`. */
+    readonly highWaterMark?: HighWaterMark;
+    /** Override default `'reject'`. */
+    readonly onBackpressure?: "reject" | "wait";
+    /** Override default `true` (auto-reconnect on transient errors). */
+    readonly autoReconnect?: boolean;
+    /** Custom reconnect-backoff hook (CLIENT-12). */
+    readonly retryStrategy?: RetryStrategy;
+    /** Drain timeout for `close()` (default `30_000`). */
+    readonly drainTimeoutMs?: number;
+    /** FrameReader options (passthrough). */
+    readonly framing?: ClientOptions["framing"];
+    /** TCP keepalive interval ms (CLIENT-08). */
+    readonly keepaliveIntervalMs?: number;
+    /** Application-idle dead-peer timeout ms (CLIENT-08). */
+    readonly deadPeerTimeoutMs?: number;
+    /** Enable TLS (MLLPS) for this connection (Phase 8). Passthrough to `ClientOptions.tls`. */
+    readonly tls?: TlsOptions | true;
+    /**
+     * Register process SIGTERM/SIGINT handlers that close the client. Default
+     * `false` (D-22). When `true`, SIGTERM/SIGINT both call `client.close()`
+     * and exit the process. Handlers self-deregister on `'close'` (T-05-06-01).
+     */
+    readonly handleSignals?: boolean;
+}
+/**
+ * Three-line MLLP client with batteries-included defaults (PLAN-06,
+ * CLIENT-10, D-22). The returned client is already CONNECTED — `connect()`
+ * has been awaited.
+ *
+ * D-22 defaults:
+ * - `autoReconnect: true`
+ * - `ackTimeoutMs: 30_000`
+ * - `correlateByControlId: false` (FIFO mode — simplest mental model)
+ * - `pipeline: true`
+ * - `highWaterMark: 64`
+ * - `onBackpressure: 'reject'`
+ * - `handleSignals: false` (opt-in)
+ *
+ * The factory is **async**, so the literal three-line north-star snippet
+ * has an explicit `await` BEFORE `createStarterClient(...)` — without it,
+ * the `using` declaration would receive a `Promise`, not an `MllpClient`,
+ * and `Symbol.asyncDispose` would not run at scope exit.
+ *
+ * @example
+ * ```typescript
+ * import { createStarterClient } from '@cosyte/mllp';
+ * await using c = await createStarterClient({ host: 'localhost', port: 2575 });
+ * const ack = await c.send(payloadBuffer);
+ * ```
+ */
+declare function createStarterClient(opts: StarterClientOptions): Promise<MllpClient>;
+
+/**
+ * MLLP Client typed errors and classifiers.
+ *
+ * Exports:
+ * - `MllpTimeoutError` (PLAN-02) — ACK timeout (ERR-02)
+ * - `MllpBackpressureError` — high-water mark exceeded (ERR-04, plan 05)
+ * - `isTransientConnectionError` (PLAN-04) — transient/permanent classifier (CLIENT-18)
+ *
+ * Re-exported from `src/client/index.ts` and `src/index.ts`.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Thrown (or rejects the `send()` promise) when an ACK does not arrive within
+ * the configured `ackTimeoutMs` (ERR-02).
+ *
+ * The timeout clock starts at the underlying `write()` flush callback, NOT
+ * at the `send()` call — pre-flush queue time is not charged to the peer
+ * (CLIENT-04).
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.send(payload);
+ * } catch (err) {
+ *   if (err instanceof MllpTimeoutError) {
+ *     logger.warn({ elapsedMs: err.elapsedMs, controlId: err.messageControlId });
+ *   }
+ * }
+ * ```
+ */
+declare class MllpTimeoutError extends Error {
+    readonly name: "MllpTimeoutError";
+    /** MSH-10 control ID of the timed-out send (FIFO mode: `undefined`). */
+    readonly messageControlId: string | undefined;
+    /** Milliseconds elapsed between write-flush and timeout fire. */
+    readonly elapsedMs: number;
+    /** Epoch ms timestamp recorded at write-flush callback. */
+    readonly sentAt: number;
+    /**
+     * Construct an MLLP timeout error.
+     *
+     * @param message - Human-readable error message.
+     * @param opts - Timeout context (originating message control id, elapsed time, flush timestamp).
+     */
+    constructor(message: string, opts: {
+        messageControlId: string | undefined;
+        elapsedMs: number;
+        sentAt: number;
+    });
+}
+/**
+ * Set of Node/OpenSSL error codes that indicate a **certificate-verification**
+ * failure (as opposed to some other TLS handshake failure) — untrusted chain,
+ * expired/not-yet-valid certificate, hostname mismatch, revocation, etc.
+ *
+ * Used by `MllpClient` (Phase 8) to classify a TLS connect failure's
+ * `connectionCause` as `'tls-verify'` (this set) vs `'tls-handshake'`
+ * (everything else observed before `'secureConnect'`). Exported so callers
+ * can apply the same classification to their own error handling.
+ *
+ * @example
+ * ```typescript
+ * import { isTlsVerificationErrorCode } from '@cosyte/mllp';
+ * if (isTlsVerificationErrorCode('CERT_HAS_EXPIRED')) {
+ *   // definitely a verification failure, not a protocol/cipher mismatch
+ * }
+ * ```
+ */
+declare function isTlsVerificationErrorCode(code: string): boolean;
+/**
+ * Detects **TLS-protocol-shaped** errors — failures of the TLS protocol
+ * itself, as opposed to plain TCP-level network failures (Phase 8).
+ *
+ * Apply this only to errors raised on a **TLS** connection; `MllpClient`
+ * does exactly that (the predicate is consulted only when `ClientOptions.tls`
+ * is set). The boundary:
+ *
+ * **TLS-protocol-shaped (`true`):**
+ * - `code` starting `ERR_SSL_` (Node's TLS alert codes, e.g.
+ *   `ERR_SSL_TLSV13_ALERT_CERTIFICATE_REQUIRED` — a `clientAuth: 'MUST'`
+ *   server rejecting the client's certificate).
+ * - `code === 'EPROTO'` — on a TLS connection this is OpenSSL failing the
+ *   handshake (protocol version mismatch, no shared cipher, a TLS ≤1.2
+ *   mTLS rejection).
+ * - `message` containing `ssl` or `alert` (`/\bssl\b|\balert\b/i` — "SSL
+ *   routines", "tlsv13 alert certificate required", …). This message check
+ *   is a **heuristic backstop** over the code-based checks above, not a
+ *   precise boundary: it exists to catch OpenSSL errors that surface without
+ *   a usable `code`, and `MllpClient` consults it only on connections where
+ *   TLS is configured. An arbitrary non-TLS error whose message happens to
+ *   contain those words would also match.
+ *
+ * **NOT TLS-protocol-shaped (`false`) — plain network failures, which stay
+ * transient for the reconnect classifier:** `ECONNREFUSED`, `ETIMEDOUT`,
+ * `EHOSTUNREACH`, `ENETUNREACH`, `EPIPE`, and a plain `ECONNRESET` carrying
+ * no TLS alert context — a network blip during (or after) a handshake
+ * should still auto-heal.
+ *
+ * Certificate-**verification** failures are a separate class — see
+ * {@link isTlsVerificationErrorCode}; `MllpClient` checks that first and
+ * labels those `connectionCause: 'tls-verify'`.
+ *
+ * Why this matters: under TLS 1.3 (RFC 8446 §4.4.2) a `clientAuth: 'MUST'`
+ * server can reject the client's certificate AFTER the client's own
+ * `'secureConnect'` — the rejection then surfaces as a post-connect socket
+ * error. A misconfigured mTLS client must never auto-reconnect-loop against
+ * a server that will always reject it, so `MllpClient` classifies
+ * TLS-protocol-shaped errors as **permanent**.
+ *
+ * @example
+ * ```typescript
+ * import { isTlsProtocolError, MllpConnectionError } from '@cosyte/mllp';
+ * client.on('error', ({ error }) => {
+ *   if (error instanceof MllpConnectionError && isTlsProtocolError(error.cause)) {
+ *     // TLS protocol failure — a configuration problem, not a network blip.
+ *   }
+ * });
+ * ```
+ */
+declare function isTlsProtocolError(err: unknown): boolean;
+/**
+ * Classifies a connection error as transient (eligible for auto-reconnect)
+ * or permanent (halts auto-reconnect, transitions to CLOSED).
+ *
+ * Used internally by `MllpClient` BEFORE invoking `retryStrategy` (Composition A
+ * — see `RetryContext.classifiedAs`). Re-exported so callers can implement
+ * their own retry policies.
+ *
+ * Classification table (CLIENT-18, D-16):
+ * - `ENOTFOUND`, `EACCES` → **permanent** (`false`)
+ * - `ECONNREFUSED`, `ECONNRESET`, `ETIMEDOUT`, `EHOSTUNREACH`,
+ *   `ENETUNREACH`, `EPIPE` → **transient** (`true`)
+ * - `CERT_*` and `UNABLE_TO_VERIFY_LEAF_SIGNATURE` /
+ *   `DEPTH_ZERO_SELF_SIGNED_CERT` / `SELF_SIGNED_CERT_IN_CHAIN`
+ *   (any {@link isTlsVerificationErrorCode} code) → **permanent** (`false`) —
+ *   never auto-reconnect-loop into a misconfigured or MITM'd endpoint (Phase 8).
+ * - `ERR_SSL_*` (Node TLS alert codes) → **permanent** (`false`) — a TLS
+ *   protocol failure such as a `clientAuth: 'MUST'` server rejecting the
+ *   client certificate recurs on every attempt (Phase 8). On TLS-configured
+ *   connections `MllpClient` additionally consults {@link isTlsProtocolError},
+ *   which also catches `EPROTO`/alert-bearing OpenSSL errors that this
+ *   generic classifier (which cannot know the connection was TLS) leaves
+ *   transient.
+ * - `MLLP_*` (any {@link MllpFramingError} code — a fatal decoder throw, surfaced with
+ *   `connectionCause: 'framing-fatal'`) → **permanent** (`false`) (MLLP-10). The peer is not
+ *   speaking MLLP — an HTTP probe, a health check, a wrong-port misconfiguration — or is emitting
+ *   frames past `maxFrameSizeBytes`. Every reconnect meets the same bytes, so retrying is an
+ *   unbounded storm against a peer that is already misconfigured. If a peer's quirk is *expected*,
+ *   the decoder's tolerance opt-ins are the supported answer — they make it a warning, not a fatal.
+ * - non-Error / unknown / no-code → **transient** (`true`) — Postel's Law
+ *   default. Reconnect attempts are bounded by `retryStrategy` and the
+ *   30s backoff cap, so the default is safe.
+ *
+ * @example
+ * ```typescript
+ * import { isTransientConnectionError } from '@cosyte/mllp';
+ * client.on('error', (err) => {
+ *   if (isTransientConnectionError(err)) {
+ *     metrics.increment('mllp.transient_error');
+ *   } else {
+ *     metrics.increment('mllp.permanent_error');
+ *   }
+ * });
+ * ```
+ */
+declare function isTransientConnectionError(err: unknown): boolean;
+/**
+ * Thrown (or rejects the `send()` promise) when the in-flight queue exceeds
+ * the configured high-water mark and `onBackpressure: 'reject'` is set
+ * (CLIENT-07, ERR-04).
+ *
+ * `highWaterMark` accepts a count cap, a byte cap, or both — when both are
+ * present, the stricter-of-two trigger wins (D-23).
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.send(payload);
+ * } catch (err) {
+ *   if (err instanceof MllpBackpressureError) {
+ *     logger.warn({
+ *       queueDepth: err.queueDepth,
+ *       queueBytes: err.queueBytes,
+ *       cap: err.highWaterMark,
+ *     });
+ *   }
+ * }
+ * ```
+ */
+declare class MllpBackpressureError extends Error {
+    readonly name: "MllpBackpressureError";
+    /** Number of in-flight + queued sends at the moment of rejection. */
+    readonly queueDepth: number;
+    /** Total bytes of in-flight + queued frames at the moment of rejection. */
+    readonly queueBytes: number;
+    /** The high-water-mark configuration that was triggered (D-23). */
+    readonly highWaterMark: {
+        readonly count?: number;
+        readonly bytes?: number;
+    };
+    /**
+     * Construct an MLLP backpressure error.
+     *
+     * @param message - Human-readable error message.
+     * @param opts - Backpressure context (queue depth, queued bytes, the high-water-mark hit).
+     */
+    constructor(message: string, opts: {
+        queueDepth: number;
+        queueBytes: number;
+        highWaterMark: {
+            count?: number;
+            bytes?: number;
+        };
+    });
+}
+
+/**
+ * `@cosyte/mllp` — Production-grade MLLP client and server for Node.js.
+ *
+ * Transport-only sibling to `@cosyte/hl7`. Handles framing, ACKs, reconnects,
+ * backpressure, and TLS without requiring knowledge of the MLLP spec.
+ *
+ * @example
+ * ```typescript
+ * import { createStarterServer } from '@cosyte/mllp';
+ * const server = await createStarterServer({ port: 2575, onMessage: (buf) => buf });
+ * ```
+ *
+ * @packageDocumentation
+ */
+/**
+ * Package version marker exported from the `@cosyte/mllp` root.
+ *
+ * Kept in lockstep with `package.json` by `scripts/sync-version.mjs`, which the `version` script
+ * runs immediately after `changeset version`. The `: string` annotation is deliberate — without it
+ * TypeScript infers the *literal* type (`declare const VERSION = "0.0.0"`), which leaks the current
+ * release into consumers' types and makes an equality check against any other version a compile
+ * error.
+ *
+ * @example
+ * ```typescript
+ * import { VERSION } from '@cosyte/mllp';
+ * console.log(VERSION);
+ * ```
+ */
+declare const VERSION: string;
+
+export { type AckCode, type ClientAuth, type ClientOptions, type ClientStats, Connection, type ConnectionErrorCause, type ConnectionErrorPhase, type ConnectionOptions, type ConnectionState, type ConnectionStats, type EncoderOptions, FrameReader, type FrameReaderOptions, MLLP_BIND_ALL_INTERFACES, MLLP_TLS_VERIFY_DISABLED, type MessageMeta, MllpAckError, MllpBackpressureError, MllpClient, MllpConnectionError, MllpFramingError, MllpServer, MllpTimeoutError, type MllpWarning, type NackEvent, type NackReason, type NegativeAckCode, NetTransport, type PemInput, type ReconnectingEvent, type RetryContext, type RetryStrategy, type SecurityWarning, type SecurityWarningCode, type ServerOptions, type ServerStats, type ServerTlsOptions, type StarterClientOptions, type StarterServerOptions, type StateChangeEvent, type TlsOptions, TlsTransport, Transport, VERSION, type WarningCode, buildRawAck, createClient, createServer, createStarterClient, createStarterServer, createWarning, encodeFrame, isTlsProtocolError, isTlsVerificationErrorCode, isTransientConnectionError, rawAckUncorrelatable, resolveNackCode };