@cosyte/mllp 0.0.1

package/dist/index.cjs

@@ -0,0 +1,3455 @@
+'use strict';
+
+var events = require('events');
+var crypto = require('crypto');
+var net = require('net');
+var tls = require('tls');
+
+// src/framing/registry.ts
+function createWarning(code, byteOffset, message) {
+  return Object.freeze({
+    code,
+    message,
+    byteOffset,
+    connectionId: void 0,
+    timestamp: /* @__PURE__ */ new Date()
+  });
+}
+
+// src/framing/error.ts
+var MAX_SNIPPET_BYTES = 64;
+var MllpFramingError = class _MllpFramingError extends Error {
+  name = "MllpFramingError";
+  /** Stable warning code identifying the violation type. */
+  code;
+  /** Absolute byte offset in the stream where the error was detected. */
+  byteOffset;
+  /**
+   * 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.
+   */
+  snippet;
+  /**
+   * 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, byteOffset, snippet, message) {
+    super(message ?? `MLLP framing error: ${code} at byte offset ${byteOffset}`);
+    this.code = code;
+    this.byteOffset = byteOffset;
+    this.snippet = Buffer.from(snippet.subarray(0, MAX_SNIPPET_BYTES));
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _MllpFramingError);
+    }
+  }
+};
+
+// src/framing/constants.ts
+var VT = 11;
+var FS = 28;
+var CR = 13;
+var LF = 10;
+var DEFAULT_MAX_FRAME_SIZE = 16 * 1024 * 1024;
+
+// src/framing/encoder.ts
+function encodeFrame(payload, opts) {
+  const allow = opts?.allowDelimiterBytesInPayload === true;
+  const onWarning = opts?.onWarning;
+  for (let i = 0; i < payload.length; i++) {
+    const byte = payload[i];
+    if (byte === void 0) break;
+    if (byte === VT || byte === FS) {
+      const code = byte === VT ? "MLLP_PAYLOAD_CONTAINS_VT" : "MLLP_PAYLOAD_CONTAINS_FS";
+      if (!allow) {
+        throw new MllpFramingError(code, i, Buffer.from([byte]));
+      }
+      if (onWarning !== void 0) {
+        const byteHex = byte === VT ? "0x0B" : "0x1C";
+        const warning = createWarning(
+          code,
+          i,
+          `Payload contains ${byte === VT ? "VT" : "FS"} byte (${byteHex}) at offset ${i}; frame will be ambiguous`
+        );
+        try {
+          onWarning(warning);
+        } catch {
+        }
+      }
+    }
+  }
+  const frame = Buffer.allocUnsafe(payload.length + 3);
+  frame[0] = VT;
+  payload.copy(frame, 1);
+  frame[payload.length + 1] = FS;
+  frame[payload.length + 2] = CR;
+  return frame;
+}
+
+// src/framing/decoder.ts
+var INITIAL_ACCUMULATOR_SIZE = 4096;
+var EMPTY_SNIPPET = Buffer.alloc(0);
+var FrameReader = class {
+  _opts;
+  _maxFrameSize;
+  _state = "SCANNING_FOR_VT";
+  /** Reusable accumulator buffer — grown by doubling as needed. */
+  _accumulator = Buffer.allocUnsafe(INITIAL_ACCUMULATOR_SIZE);
+  /** Number of payload bytes written to accumulator in current frame. */
+  _writePos = 0;
+  /** Monotonic absolute stream byte offset across the entire connection lifetime. */
+  _byteOffset = 0;
+  /** Byte offset where current leading-whitespace run started (FRAME-10). */
+  _wsStart = 0;
+  /** Count of leading whitespace bytes accumulated in current run (FRAME-10). */
+  _wsCount = 0;
+  /** Byte offset of the VT byte that started the current frame. */
+  _frameStartOffset = 0;
+  /** Per-frame warning accumulator — cleared after each _deliverFrame(). */
+  _frameWarnings = [];
+  /**
+   * Construct a chunked MLLP frame reader.
+   *
+   * @param opts - Reader options (`onFrame`/`onWarning` callbacks, tolerance, `maxFrameSizeBytes`).
+   */
+  constructor(opts) {
+    this._opts = opts;
+    this._maxFrameSize = opts.maxFrameSizeBytes !== void 0 ? opts.maxFrameSizeBytes : DEFAULT_MAX_FRAME_SIZE;
+  }
+  /**
+   * 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) {
+    for (let i = 0; i < chunk.length; i++, this._byteOffset++) {
+      const byte = chunk[i];
+      if (byte === void 0) break;
+      this._processByte(byte);
+    }
+  }
+  /**
+   * 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() {
+    this._state = "SCANNING_FOR_VT";
+    this._writePos = 0;
+    this._byteOffset = 0;
+    this._wsStart = 0;
+    this._wsCount = 0;
+    this._frameStartOffset = 0;
+    this._frameWarnings = [];
+  }
+  _processByte(byte) {
+    switch (this._state) {
+      case "SCANNING_FOR_VT":
+        this._scanForVt(byte);
+        break;
+      case "READING_PAYLOAD":
+        this._readPayload(byte);
+        break;
+      case "EXPECTING_CR":
+        this._expectCr(byte);
+        break;
+    }
+  }
+  _scanForVt(byte) {
+    if (byte === VT) {
+      if (this._wsCount > 0) {
+        this._emitWarning(
+          "MLLP_LEADING_WHITESPACE",
+          this._wsStart,
+          `${this._wsCount} leading whitespace byte(s) before VT at offset ${this._wsStart}`
+        );
+        this._wsStart = 0;
+        this._wsCount = 0;
+      }
+      this._frameStartOffset = this._byteOffset;
+      this._state = "READING_PAYLOAD";
+      return;
+    }
+    const isWhitespace = byte === 32 || byte === 9 || byte === LF || byte === CR;
+    if (isWhitespace) {
+      if (this._opts.allowLeadingWhitespace === true) {
+        if (this._opts.strict === true) {
+          const snippet3 = Buffer.from([byte]);
+          throw new MllpFramingError(
+            "MLLP_MISSING_LEADING_VT",
+            this._byteOffset,
+            snippet3,
+            `Strict mode: leading whitespace before VT at offset ${this._byteOffset}`
+          );
+        }
+        if (this._wsCount === 0) {
+          this._wsStart = this._byteOffset;
+        }
+        this._wsCount++;
+        return;
+      }
+      const snippet2 = Buffer.from([byte]);
+      throw new MllpFramingError(
+        "MLLP_MISSING_LEADING_VT",
+        this._byteOffset,
+        snippet2,
+        `Expected VT (0x0B) to start MLLP frame, got whitespace 0x${byte.toString(16).padStart(2, "0")} at offset ${this._byteOffset}`
+      );
+    }
+    if (this._wsCount > 0) {
+      this._emitWarning(
+        "MLLP_LEADING_WHITESPACE",
+        this._wsStart,
+        `${this._wsCount} leading whitespace byte(s) before VT at offset ${this._wsStart}`
+      );
+      this._wsStart = 0;
+      this._wsCount = 0;
+    }
+    if (this._opts.allowMissingLeadingVt === true) {
+      if (this._opts.strict === true) {
+        const snippet2 = Buffer.from([byte]);
+        throw new MllpFramingError(
+          "MLLP_MISSING_LEADING_VT",
+          this._byteOffset,
+          snippet2,
+          `Strict mode: missing leading VT at offset ${this._byteOffset}`
+        );
+      }
+      this._emitWarning(
+        "MLLP_MISSING_LEADING_VT",
+        this._byteOffset,
+        `Missing leading VT (0x0B) \u2014 treating byte 0x${byte.toString(16).padStart(2, "0")} at offset ${this._byteOffset} as payload start`
+      );
+      this._frameStartOffset = this._byteOffset;
+      this._state = "READING_PAYLOAD";
+      this._appendByte(byte);
+      return;
+    }
+    const snippet = Buffer.from([byte]);
+    throw new MllpFramingError(
+      "MLLP_MISSING_LEADING_VT",
+      this._byteOffset,
+      snippet,
+      `Expected VT (0x0B) to start MLLP frame, got 0x${byte.toString(16).padStart(2, "0")} at offset ${this._byteOffset}`
+    );
+  }
+  _readPayload(byte) {
+    if (byte === FS) {
+      if (this._writePos === 0) {
+        this._emitWarning(
+          "MLLP_EMPTY_PAYLOAD",
+          this._byteOffset,
+          `Empty payload between VT and FS at offset ${this._byteOffset}`
+        );
+      }
+      this._state = "EXPECTING_CR";
+      return;
+    }
+    if (byte === VT) {
+      this._emitWarning(
+        "MLLP_TRAILING_BYTES",
+        this._byteOffset,
+        `Unexpected VT (0x0B) mid-payload at offset ${this._byteOffset}; discarding ${this._writePos} accumulated bytes`
+      );
+      this._writePos = 0;
+      this._state = "READING_PAYLOAD";
+      return;
+    }
+    if (this._writePos >= this._maxFrameSize) {
+      throw new MllpFramingError(
+        "MLLP_FRAME_TOO_LARGE",
+        this._byteOffset,
+        EMPTY_SNIPPET,
+        `Frame payload exceeded maxFrameSizeBytes (${this._maxFrameSize}) at offset ${this._byteOffset}`
+      );
+    }
+    this._appendByte(byte);
+  }
+  _expectCr(byte) {
+    if (byte === CR) {
+      this._deliverFrame();
+      this._state = "SCANNING_FOR_VT";
+      return;
+    }
+    if (byte === LF) {
+      if (this._opts.allowLfAfterFs === true) {
+        if (this._opts.strict === true) {
+          const snippet3 = Buffer.from([byte]);
+          throw new MllpFramingError(
+            "MLLP_LF_AFTER_FS",
+            this._byteOffset,
+            snippet3,
+            `Strict mode: LF after FS at offset ${this._byteOffset}`
+          );
+        }
+        this._emitWarning(
+          "MLLP_LF_AFTER_FS",
+          this._byteOffset,
+          `LF (0x0A) after FS instead of CR (0x0D) at offset ${this._byteOffset}`
+        );
+        this._deliverFrame();
+        this._state = "SCANNING_FOR_VT";
+        return;
+      }
+      const snippet2 = Buffer.from([byte]);
+      throw new MllpFramingError(
+        "MLLP_LF_AFTER_FS",
+        this._byteOffset,
+        snippet2,
+        `Expected CR (0x0D) after FS, got LF (0x0A) at offset ${this._byteOffset}. Enable allowLfAfterFs to tolerate.`
+      );
+    }
+    if (byte === VT) {
+      if (this._opts.allowFsOnly === true) {
+        if (this._opts.strict === true) {
+          const snippet3 = Buffer.from([byte]);
+          throw new MllpFramingError(
+            "MLLP_FS_WITHOUT_CR",
+            this._byteOffset,
+            snippet3,
+            `Strict mode: FS without CR at offset ${this._byteOffset}`
+          );
+        }
+        this._emitWarning(
+          "MLLP_FS_WITHOUT_CR",
+          this._byteOffset,
+          `FS not followed by CR at offset ${this._byteOffset}; next frame VT found immediately`
+        );
+        this._deliverFrame();
+        this._state = "READING_PAYLOAD";
+        return;
+      }
+      const snippet2 = Buffer.from([byte]);
+      throw new MllpFramingError(
+        "MLLP_FS_WITHOUT_CR",
+        this._byteOffset,
+        snippet2,
+        `Expected CR (0x0D) after FS, got VT (0x0B) at offset ${this._byteOffset}. Enable allowFsOnly to tolerate.`
+      );
+    }
+    if (this._opts.allowFsOnly === true) {
+      if (this._opts.strict === true) {
+        const snippet2 = Buffer.from([byte]);
+        throw new MllpFramingError(
+          "MLLP_FS_WITHOUT_CR",
+          this._byteOffset,
+          snippet2,
+          `Strict mode: FS without CR at offset ${this._byteOffset}`
+        );
+      }
+      this._emitWarning(
+        "MLLP_FS_WITHOUT_CR",
+        this._byteOffset,
+        `FS not followed by CR at offset ${this._byteOffset}; got 0x${byte.toString(16).padStart(2, "0")} (dropped)`
+      );
+      this._deliverFrame();
+      this._state = "SCANNING_FOR_VT";
+      return;
+    }
+    const snippet = Buffer.from([byte]);
+    throw new MllpFramingError(
+      "MLLP_FS_WITHOUT_CR",
+      this._byteOffset,
+      snippet,
+      `Expected CR (0x0D) after FS, got 0x${byte.toString(16).padStart(2, "0")} at offset ${this._byteOffset}`
+    );
+  }
+  /** Grow the internal accumulator by doubling and write one byte. */
+  _appendByte(byte) {
+    if (this._writePos >= this._accumulator.length) {
+      const newSize = this._accumulator.length * 2;
+      const grown = Buffer.allocUnsafe(newSize);
+      this._accumulator.subarray(0, this._writePos).copy(grown);
+      this._accumulator = grown;
+    }
+    this._accumulator[this._writePos++] = byte;
+  }
+  /**
+   * Copy accumulated payload bytes into a new Buffer and deliver via `onFrame`.
+   * The copy isolates callers from internal accumulator reuse (T-02-03-03).
+   */
+  _deliverFrame() {
+    const payload = Buffer.from(this._accumulator.subarray(0, this._writePos));
+    this._writePos = 0;
+    const frameStart = this._frameStartOffset;
+    const frameWarnings = this._frameWarnings;
+    this._frameWarnings = [];
+    this._opts.onFrame(payload, frameStart, frameWarnings);
+  }
+  /** Emit a warning via the `onWarning` callback, swallowing any handler exceptions (WARN-06). */
+  _emitWarning(code, byteOffset, message) {
+    const warning = createWarning(code, byteOffset, message);
+    this._frameWarnings.push(warning);
+    if (this._opts.onWarning !== void 0) {
+      try {
+        this._opts.onWarning(warning);
+      } catch {
+      }
+    }
+  }
+};
+
+// src/transport/net-transport.ts
+var NetTransport = class {
+  _socket;
+  /**
+   * Wrap an existing `net.Socket` (or `tls.TLSSocket`) as a `Transport`.
+   *
+   * @param socket - The connected (or connecting) socket to adapt.
+   */
+  constructor(socket) {
+    this._socket = socket;
+  }
+  /** See {@link Transport.write}. */
+  write(buf) {
+    return this._socket.write(buf);
+  }
+  /** See {@link Transport.close}. */
+  close() {
+    this._socket.end();
+  }
+  /** See {@link Transport.destroy}. */
+  destroy(reason) {
+    this._socket.destroy(reason);
+  }
+  /** See {@link Transport.onData}. */
+  onData(fn) {
+    this._socket.removeAllListeners("data");
+    this._socket.on("data", fn);
+  }
+  /** See {@link Transport.onConnect}. */
+  onConnect(fn) {
+    this._socket.removeAllListeners("connect");
+    this._socket.on("connect", fn);
+  }
+  /** See {@link Transport.onClose}. */
+  onClose(fn) {
+    this._socket.removeAllListeners("close");
+    this._socket.on("close", fn);
+  }
+  /** See {@link Transport.onError}. */
+  onError(fn) {
+    this._socket.removeAllListeners("error");
+    this._socket.on("error", fn);
+  }
+};
+
+// src/transport/tls-transport.ts
+var TlsTransport = class {
+  _socket;
+  /**
+   * Wrap an existing `tls.TLSSocket` (connecting or already secure) as a `Transport`.
+   *
+   * @param socket - The TLS socket to adapt.
+   */
+  constructor(socket) {
+    this._socket = socket;
+  }
+  /** See {@link Transport.write}. */
+  write(buf) {
+    return this._socket.write(buf);
+  }
+  /** See {@link Transport.close}. */
+  close() {
+    this._socket.end();
+  }
+  /** See {@link Transport.destroy}. */
+  destroy(reason) {
+    this._socket.destroy(reason);
+  }
+  /** See {@link Transport.onData}. */
+  onData(fn) {
+    this._socket.removeAllListeners("data");
+    this._socket.on("data", fn);
+  }
+  /**
+   * See {@link Transport.onConnect}. Armed on `'secureConnect'` — the TLS
+   * handshake-complete event — not the raw TCP `'connect'` event.
+   */
+  onConnect(fn) {
+    this._socket.removeAllListeners("secureConnect");
+    this._socket.on("secureConnect", fn);
+  }
+  /** See {@link Transport.onClose}. */
+  onClose(fn) {
+    this._socket.removeAllListeners("close");
+    this._socket.on("close", fn);
+  }
+  /** See {@link Transport.onError}. */
+  onError(fn) {
+    this._socket.removeAllListeners("error");
+    this._socket.on("error", fn);
+  }
+};
+
+// src/transport/security-warnings.ts
+var MLLP_TLS_VERIFY_DISABLED = "MLLP_TLS_VERIFY_DISABLED";
+var MLLP_BIND_ALL_INTERFACES = "MLLP_BIND_ALL_INTERFACES";
+
+// src/connection/error.ts
+var MllpConnectionError = class _MllpConnectionError extends Error {
+  name = "MllpConnectionError";
+  /** The original OS or TLS error that caused this connection failure. */
+  cause;
+  /** Which connection lifecycle phase the failure occurred in. */
+  phase;
+  /**
+   * 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}.
+   */
+  connectionCause;
+  /**
+   * 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, opts) {
+    super(message);
+    this.cause = opts.cause;
+    this.phase = opts.phase;
+    if (opts.connectionCause !== void 0) {
+      this.connectionCause = opts.connectionCause;
+    }
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _MllpConnectionError);
+    }
+  }
+};
+
+// src/connection/connection.ts
+var MAX_WARNINGS = 100;
+var LEGAL_TRANSITIONS = /* @__PURE__ */ new Map([
+  ["CONNECTING", /* @__PURE__ */ new Set(["CONNECTED", "RECONNECTING", "CLOSED"])],
+  ["CONNECTED", /* @__PURE__ */ new Set(["DRAINING", "RECONNECTING", "DISCONNECTED", "CLOSED"])],
+  ["DRAINING", /* @__PURE__ */ new Set(["DISCONNECTED", "CLOSED"])],
+  ["RECONNECTING", /* @__PURE__ */ new Set(["CONNECTING", "CLOSED"])],
+  ["DISCONNECTED", /* @__PURE__ */ new Set(["CLOSED"])],
+  ["CLOSED", /* @__PURE__ */ new Set()]
+]);
+var Connection = class extends events.EventEmitter {
+  /** Stable UUIDv4 identifier for this connection (D-11). */
+  connectionId;
+  _state = "CONNECTING";
+  _transport;
+  _reader;
+  _opts;
+  _remoteAddress = null;
+  _remotePort = null;
+  _connectedAt = null;
+  _bytesIn = 0;
+  _bytesOut = 0;
+  _lastByteInAt = null;
+  _lastByteOutAt = null;
+  /** Ring buffer: last MAX_WARNINGS entries (OBS-05). */
+  _warningBuffer = [];
+  /** Accurate total counts per code — unaffected by ring buffer truncation (OBS-05). */
+  _warningsByCode = /* @__PURE__ */ new Map();
+  /** Set to true once the ring buffer overflows (OBS-05). */
+  _warningsTruncated = false;
+  _onWarningFn = null;
+  _drainPromise = null;
+  /**
+   * 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 = () => Promise.resolve();
+  /**
+   * 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) {
+    super();
+    this.connectionId = crypto.randomUUID();
+    this._opts = opts;
+    this._transport = opts.transport;
+    if (opts.onWarning !== void 0) {
+      this._onWarningFn = opts.onWarning;
+    }
+    this._reader = new FrameReader({
+      ...opts.framing ?? {},
+      onFrame: (payload, byteOffset, warnings) => {
+        this._onFrameDecoded(payload, byteOffset, warnings);
+      },
+      onWarning: (w) => {
+        this._onFramingWarning(w);
+      }
+    });
+    this._transport.onData((chunk) => {
+      this._bytesIn += chunk.length;
+      this._lastByteInAt = /* @__PURE__ */ new Date();
+      try {
+        this._reader.push(chunk);
+      } catch (err) {
+        if (err instanceof MllpFramingError) {
+          this._onFatalFramingError(err);
+        } else {
+          this._onInternalReceiveError(err instanceof Error ? err : new Error(String(err)));
+        }
+      }
+    });
+    this._transport.onClose(() => {
+      this._onTransportClose();
+    });
+    this._transport.onError((err) => {
+      this._onTransportError(err);
+    });
+  }
+  /**
+   * Current FSM state. One of the 6 `ConnectionState` values (LIFE-01).
+   *
+   * Subscribe to `'stateChange'` events for reactive state monitoring.
+   */
+  get state() {
+    return this._state;
+  }
+  /**
+   * 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) {
+    this._onWarningFn = fn;
+  }
+  /**
+   * 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, remotePort) {
+    this._remoteAddress = remoteAddress;
+    this._remotePort = remotePort;
+    this._connectedAt = /* @__PURE__ */ new Date();
+    this._transition("CONNECTED");
+    this._dispatchContained(() => {
+      this.emit("connect", Object.freeze({ connectionId: this.connectionId }));
+    });
+  }
+  /**
+   * 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) {
+    if (this._state === "CLOSED" || this._state === "DISCONNECTED") return false;
+    const ok = this._transport.write(data);
+    this._bytesOut += data.length;
+    this._lastByteOutAt = /* @__PURE__ */ new Date();
+    return ok;
+  }
+  /**
+   * 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 });
+   * ```
+   */
+  async close(opts) {
+    const timeout = opts?.drainTimeoutMs ?? this._opts.drainTimeoutMs ?? 3e4;
+    if (this._state === "CLOSED" || this._state === "DISCONNECTED") return;
+    if (this._state === "CONNECTING" || this._state === "RECONNECTING") {
+      this._transition("CLOSED", "close() during " + this._state);
+      this._transport.destroy();
+      return;
+    }
+    if (this._state === "DRAINING") {
+      return this._drainPromise ?? Promise.resolve();
+    }
+    this._transition("DRAINING");
+    this._drainPromise = this._drainWithTimeout(timeout).finally(() => {
+      this._drainPromise = null;
+    });
+    return this._drainPromise;
+  }
+  /**
+   * Race `beforeClose()` against the drain timeout.
+   *
+   * On normal completion: `DRAINING → DISCONNECTED` + `transport.close()`.
+   * On timeout: `DRAINING → CLOSED` + `transport.destroy()` (T-03-04-01).
+   */
+  async _drainWithTimeout(timeoutMs) {
+    const drainPromise = this.beforeClose(timeoutMs);
+    const timeoutPromise = new Promise((resolve) => {
+      const handle = setTimeout(() => {
+        resolve("timeout");
+      }, timeoutMs);
+      handle.unref();
+    });
+    const result = await Promise.race([drainPromise.then(() => "done"), timeoutPromise]);
+    if (result === "timeout") {
+      if (this._state === "DRAINING") {
+        this._transition("CLOSED", "drain timeout");
+        this._transport.destroy();
+      }
+    } else {
+      if (this._state === "DRAINING") {
+        this._transition("DISCONNECTED");
+        this._transport.close();
+      }
+    }
+  }
+  /**
+   * 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) {
+    if (this._state === "CLOSED") return;
+    this._transition("CLOSED", reason?.message ?? "destroy()");
+    this._transport.destroy(reason);
+  }
+  /**
+   * 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() {
+    const warningsByCode = {};
+    for (const [code, count] of this._warningsByCode) {
+      warningsByCode[code] = count;
+    }
+    return {
+      state: this._state,
+      connectionId: this.connectionId,
+      remoteAddress: this._remoteAddress,
+      remotePort: this._remotePort,
+      warningsByCode,
+      bytesIn: this._bytesIn,
+      bytesOut: this._bytesOut,
+      lastByteInAt: this._lastByteInAt,
+      lastByteOutAt: this._lastByteOutAt,
+      connectedAt: this._connectedAt,
+      warningsTruncated: this._warningsTruncated
+    };
+  }
+  // ---------------------------------------------------------------------------
+  // Private FSM helpers
+  // ---------------------------------------------------------------------------
+  _transition(to, reason) {
+    const from = this._state;
+    const legal = LEGAL_TRANSITIONS.get(from);
+    if (legal === void 0 || !legal.has(to)) {
+      return;
+    }
+    this._state = to;
+    const event = Object.freeze(
+      reason !== void 0 ? { from, to, reason } : { from, to }
+    );
+    this._dispatchContained(() => {
+      this.emit("stateChange", event);
+    });
+    if (to === "DISCONNECTED") {
+      this._dispatchContained(() => {
+        this.emit("disconnect", Object.freeze({ connectionId: this.connectionId }));
+      });
+    }
+    if (to === "RECONNECTING") {
+      this._dispatchContained(() => {
+        this.emit("reconnecting", Object.freeze({ connectionId: this.connectionId }));
+      });
+    }
+    if (to === "CLOSED") {
+      this._dispatchContained(() => {
+        this.emit("close", Object.freeze({ connectionId: this.connectionId }));
+      });
+    }
+  }
+  _onTransportClose() {
+    if (this._state === "DRAINING") {
+      this._transition("DISCONNECTED");
+      return;
+    }
+    if (this._state === "CONNECTED") {
+      this._transition("DISCONNECTED", "peer closed");
+      return;
+    }
+    if (this._state === "CONNECTING" || this._state === "RECONNECTING") {
+      this._transition("CLOSED", "peer closed");
+    }
+  }
+  /**
+   * 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`.
+   */
+  _emitErrorIfListened(error) {
+    if (this.listenerCount("error") === 0) return;
+    try {
+      this.emit("error", Object.freeze({ connectionId: this.connectionId, error }));
+    } catch {
+    }
+  }
+  /**
+   * 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.
+   */
+  _onFatalFramingError(err) {
+    if (this._state === "CLOSED") return;
+    this._emitErrorIfListened(
+      new MllpConnectionError(err.message, {
+        cause: err,
+        phase: "receive",
+        connectionCause: "framing-fatal"
+      })
+    );
+    this.destroy(err);
+  }
+  /**
+   * 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.
+   */
+  _onInternalReceiveError(err) {
+    if (this._state === "CLOSED") return;
+    this._emitErrorIfListened(
+      new MllpConnectionError(err.message, { cause: err, phase: "receive" })
+    );
+    this.destroy(err);
+  }
+  _onTransportError(err) {
+    const phase = this._state === "CONNECTING" ? "connect" : this._state === "RECONNECTING" ? "reconnect" : this._state === "DRAINING" ? "close" : "receive";
+    if (this._state === "CLOSED" || this._state === "DISCONNECTED") return;
+    this._emitErrorIfListened(new MllpConnectionError(err.message, { cause: err, phase }));
+    const target = this._state === "CONNECTING" || this._state === "RECONNECTING" ? "CLOSED" : "DISCONNECTED";
+    this._transition(target, `error: ${err.message}`);
+  }
+  _onFrameDecoded(payload, byteOffset, warnings) {
+    if (this._state !== "CONNECTED" && this._state !== "DRAINING") return;
+    const event = Object.freeze({ payload, connectionId: this.connectionId, byteOffset, warnings });
+    this._dispatchContained(() => {
+      this.emit("message", event);
+    });
+    this._dispatchContained(() => {
+      this._opts.onMessage?.(payload);
+    });
+  }
+  /**
+   * Run a subscriber callback, containing any throw as a connection `'error'` rather than letting
+   * it unwind into the socket callback that (transitively) invoked us.
+   */
+  _dispatchContained(fn) {
+    try {
+      fn();
+    } catch (err) {
+      const cause = err instanceof Error ? err : new Error(String(err));
+      this._emitErrorIfListened(
+        new MllpConnectionError(cause.message, { cause, phase: "receive" })
+      );
+    }
+  }
+  _onFramingWarning(w) {
+    const enriched = Object.freeze({ ...w, connectionId: this.connectionId });
+    this._warningsByCode.set(enriched.code, (this._warningsByCode.get(enriched.code) ?? 0) + 1);
+    if (this._warningBuffer.length >= MAX_WARNINGS) {
+      this._warningBuffer.shift();
+      this._warningsTruncated = true;
+    }
+    this._warningBuffer.push(enriched);
+    if (this._onWarningFn !== null) {
+      try {
+        this._onWarningFn(enriched);
+      } catch {
+      }
+    }
+    this._dispatchContained(() => {
+      this.emit("warning", enriched);
+    });
+  }
+};
+
+// src/internal/control-id.ts
+var ASCII_M = 77;
+var ASCII_S = 83;
+var ASCII_H = 72;
+var ASCII_A = 65;
+var ASCII_B = 66;
+var ASCII_F = 70;
+var ASCII_T = 84;
+var SEGMENT_SEPARATOR_CR = 13;
+var SEGMENT_SEPARATOR_LF = 10;
+var CONTROL_ID_ENCODING = "latin1";
+var UNSAFE_FIELD_SEPARATORS = /* @__PURE__ */ new Set([
+  SEGMENT_SEPARATOR_CR,
+  SEGMENT_SEPARATOR_LF,
+  11,
+  // VT — MLLP start block
+  28
+  // FS — MLLP end block
+]);
+function isMshSegmentAt(buf, i) {
+  return i + 3 < buf.length && buf[i] === ASCII_M && buf[i + 1] === ASCII_S && buf[i + 2] === ASCII_H && !UNSAFE_FIELD_SEPARATORS.has(buf[i + 3]);
+}
+function segmentEnd(buf, i) {
+  let end = i;
+  while (end < buf.length && buf[end] !== SEGMENT_SEPARATOR_CR && buf[end] !== SEGMENT_SEPARATOR_LF) {
+    end++;
+  }
+  return end;
+}
+function findMshSegment(buf) {
+  let segStart = 0;
+  while (segStart < buf.length) {
+    const end = segmentEnd(buf, segStart);
+    if (isMshSegmentAt(buf, segStart)) return { start: segStart, end };
+    let next = end;
+    while (next < buf.length && (buf[next] === SEGMENT_SEPARATOR_CR || buf[next] === SEGMENT_SEPARATOR_LF)) {
+      next++;
+    }
+    if (next === segStart) return null;
+    segStart = next;
+  }
+  return null;
+}
+function isBatchEnvelopeSegmentAt(buf, i) {
+  if (i + 2 >= buf.length) return false;
+  const a = buf[i];
+  const b = buf[i + 1];
+  const c = buf[i + 2];
+  if (a === ASCII_F && (b === ASCII_H && c === ASCII_S || b === ASCII_T && c === ASCII_S)) {
+    return true;
+  }
+  if (a === ASCII_B && (b === ASCII_H && c === ASCII_S || b === ASCII_T && c === ASCII_S)) {
+    return true;
+  }
+  return false;
+}
+function containsBatchOrExtraMessage(buf) {
+  let mshCount = 0;
+  let segStart = 0;
+  while (segStart < buf.length) {
+    const end = segmentEnd(buf, segStart);
+    if (isMshSegmentAt(buf, segStart)) {
+      mshCount++;
+      if (mshCount > 1) return true;
+    } else if (isBatchEnvelopeSegmentAt(buf, segStart)) {
+      return true;
+    }
+    let next = end;
+    while (next < buf.length && (buf[next] === SEGMENT_SEPARATOR_CR || buf[next] === SEGMENT_SEPARATOR_LF)) {
+      next++;
+    }
+    if (next === segStart) return false;
+    segStart = next;
+  }
+  return false;
+}
+function readMshSegment(buf) {
+  const at = findMshSegment(buf);
+  if (at === null) return null;
+  const fieldSep = String.fromCharCode(buf[at.start + 3]);
+  const fields = buf.subarray(at.start, at.end).toString(CONTROL_ID_ENCODING).split(fieldSep);
+  return { fieldSep, fields };
+}
+function extractMshControlId(buf) {
+  const msh = readMshSegment(buf);
+  if (msh === null) return null;
+  const id = msh.fields[9];
+  return id === void 0 || id === "" ? null : id;
+}
+function extractMsaControlId(buf) {
+  const msh = readMshSegment(buf);
+  if (msh === null) return null;
+  const fieldSep = msh.fieldSep.charCodeAt(0);
+  const end = buf.length;
+  let segStart = 0;
+  while (segStart < end) {
+    let segEnd = segStart;
+    while (segEnd < end && buf[segEnd] !== SEGMENT_SEPARATOR_CR && buf[segEnd] !== SEGMENT_SEPARATOR_LF) {
+      segEnd++;
+    }
+    if (segEnd - segStart >= 4 && buf[segStart] === ASCII_M && buf[segStart + 1] === ASCII_S && buf[segStart + 2] === ASCII_A && buf[segStart + 3] === fieldSep) {
+      let fieldIndex = 0;
+      let fieldStart = 0;
+      for (let i = segStart + 3; i <= segEnd; i++) {
+        const b = i < segEnd ? buf[i] : fieldSep;
+        if (b === fieldSep || b === SEGMENT_SEPARATOR_CR || b === SEGMENT_SEPARATOR_LF) {
+          fieldIndex++;
+          if (fieldIndex === 2) {
+            fieldStart = i + 1;
+          } else if (fieldIndex === 3) {
+            if (fieldStart >= i) return null;
+            return buf.subarray(fieldStart, i).toString(CONTROL_ID_ENCODING);
+          }
+        }
+      }
+      return null;
+    }
+    while (segEnd < end && (buf[segEnd] === SEGMENT_SEPARATOR_CR || buf[segEnd] === SEGMENT_SEPARATOR_LF)) {
+      segEnd++;
+    }
+    if (segEnd === segStart) return null;
+    segStart = segEnd;
+  }
+  return null;
+}
+
+// src/server/ack.ts
+var MllpAckError = class extends Error {
+  /** The negative acknowledgement code to return (`AE` or `AR`). */
+  ackCode;
+  /**
+   * @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, opts) {
+    super(message, opts?.cause !== void 0 ? { cause: opts.cause } : void 0);
+    this.name = "MllpAckError";
+    this.ackCode = opts?.ackCode ?? "AE";
+  }
+};
+function resolveNackCode(err) {
+  if (err instanceof MllpAckError) return err.ackCode;
+  if (typeof err === "object" && err !== null && "ackCode" in err && err.ackCode === "AR") {
+    return "AR";
+  }
+  return "AE";
+}
+var NACK_TEXT = Object.freeze({
+  AE: "message could not be processed",
+  AR: "message rejected"
+});
+var DEFAULT_ENCODING_CHARACTERS = "^~\\&";
+var DEFAULT_FIELD_SEPARATOR = "|";
+var ENCODING_CHAR_SUBSTITUTE = "#";
+var UNSAFE_DELIMITER = /[\r\n\v\x1c]/;
+function rawAckUncorrelatable(payload) {
+  const msh = readMshSegment(payload);
+  if (msh === null) return true;
+  const controlId = msh.fields[9];
+  if (controlId === void 0 || controlId === "") return true;
+  return containsBatchOrExtraMessage(payload);
+}
+function downgradePositiveAck(code) {
+  if (code === "AA") return "AE";
+  if (code === "CA") return "CE";
+  return code;
+}
+function buildRawAck(payload, code) {
+  const msh = readMshSegment(payload);
+  if ((code === "AA" || code === "CA") && rawAckUncorrelatable(payload)) {
+    code = downgradePositiveAck(code);
+  }
+  const newControlId = crypto.randomUUID().replace(/-/g, "").substring(0, 20);
+  const now = timestamp14();
+  if (msh === null) {
+    const s2 = DEFAULT_FIELD_SEPARATOR;
+    const e = DEFAULT_ENCODING_CHARACTERS;
+    const tail = code === "AE" || code === "AR" ? `${s2}${NACK_TEXT[code]}` : "";
+    return Buffer.from(
+      `MSH${s2}${e}${s2}${s2}${s2}${s2}${s2}${now}${s2}${s2}ACK${s2}${newControlId}${s2}P${s2}2.3\rMSA${s2}${code}${s2}${tail}\r`,
+      "latin1"
+    );
+  }
+  const { fieldSep, fields } = msh;
+  const declaredEnc = fields[1] ?? "";
+  const usableEnc = declaredEnc !== "" && !UNSAFE_DELIMITER.test(declaredEnc) ? declaredEnc : DEFAULT_ENCODING_CHARACTERS;
+  const s = fieldSep;
+  const encodingChars = usableEnc.includes(fieldSep) ? usableEnc.replace(fieldSep, ENCODING_CHAR_SUBSTITUTE) : usableEnc;
+  const sendingApp = fields[2] ?? "";
+  const sendingFacility = fields[3] ?? "";
+  const receivingApp = fields[4] ?? "";
+  const receivingFacility = fields[5] ?? "";
+  const inboundControlId = fields[9] ?? "";
+  const processingId = fields[10] ?? "P";
+  const version = fields[11] ?? "2.3";
+  const msaTail = code === "AE" || code === "AR" ? `${s}${NACK_TEXT[code]}` : "";
+  const ackStr = `MSH${s}${encodingChars}${s}${receivingApp}${s}${receivingFacility}${s}${sendingApp}${s}${sendingFacility}${s}${now}${s}${s}ACK${s}${newControlId}${s}${processingId}${s}${version}\rMSA${s}${code}${s}${inboundControlId}${msaTail}\r`;
+  return Buffer.from(ackStr, "latin1");
+}
+function timestamp14() {
+  const d = /* @__PURE__ */ new Date();
+  const pad = (n, w = 2) => String(n).padStart(w, "0");
+  return String(d.getUTCFullYear()) + pad(d.getUTCMonth() + 1) + pad(d.getUTCDate()) + pad(d.getUTCHours()) + pad(d.getUTCMinutes()) + pad(d.getUTCSeconds());
+}
+
+// src/internal/safe-emit.ts
+function safeEmit(emitter, event, payload, onSubscriberThrow) {
+  try {
+    emitter.emit(event, payload);
+  } catch (err) {
+    onSubscriberThrow?.(err instanceof Error ? err : new Error(String(err)));
+  }
+}
+function safeEmitError(emitter, payload) {
+  if (emitter.listenerCount("error") === 0) return;
+  try {
+    emitter.emit("error", payload);
+  } catch {
+  }
+}
+
+// src/server/server.ts
+function isWildcardHost(host) {
+  if (host === "") return true;
+  const family = net.isIP(host);
+  if (family === 4) {
+    return host.split(".").every((octet) => Number(octet) === 0);
+  }
+  if (family === 6) {
+    let canonical;
+    try {
+      canonical = new net.SocketAddress({ address: host, family: "ipv6" }).address;
+    } catch {
+      return false;
+    }
+    return canonical === "::" || canonical === "::ffff:0.0.0.0";
+  }
+  return false;
+}
+var SERVER_DEFAULT_FRAMING = {
+  allowFsOnly: true,
+  allowLfAfterFs: true,
+  allowLeadingWhitespace: true,
+  allowMissingLeadingVt: false
+};
+var MllpServer = class extends events.EventEmitter {
+  _netServer;
+  _connections = /* @__PURE__ */ new Set();
+  _opts;
+  /** `true` when `ServerOptions.tls` is set — `_netServer` is actually a `tls.Server`. */
+  _isTls;
+  _listening = false;
+  /** Phase 8 — single-flight guard: `true` while a `listen()` call is settling. */
+  _listenInFlight = false;
+  /**
+   * 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.
+   */
+  _pendingListenSettle = null;
+  _port = null;
+  _host = null;
+  _acceptedTotal = 0;
+  _closedTotal = 0;
+  /** Phase 8 — count of `'tlsClientError'` events since listen(). */
+  _tlsClientErrorsTotal = 0;
+  /**
+   * 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) {
+    super();
+    this._opts = opts;
+    this._isTls = opts.tls !== void 0;
+    if (opts.tls !== void 0) {
+      const tlsOpts = opts.tls;
+      const clientAuth = tlsOpts.clientAuth ?? "NONE";
+      const tlsServer = tls.createServer({
+        cert: tlsOpts.cert,
+        key: tlsOpts.key,
+        ...tlsOpts.ca !== void 0 ? { ca: tlsOpts.ca } : {},
+        ...tlsOpts.passphrase !== void 0 ? { passphrase: tlsOpts.passphrase } : {},
+        minVersion: tlsOpts.minVersion ?? "TLSv1.2",
+        ...tlsOpts.maxVersion !== void 0 ? { maxVersion: tlsOpts.maxVersion } : {},
+        ...tlsOpts.ciphers !== void 0 ? { ciphers: tlsOpts.ciphers } : {},
+        requestCert: clientAuth !== "NONE",
+        rejectUnauthorized: clientAuth === "MUST"
+      });
+      this._netServer = tlsServer;
+      tlsServer.on("secureConnection", (socket) => {
+        this._onSocketAccepted(socket);
+      });
+      tlsServer.on("tlsClientError", (err, socket) => {
+        this._tlsClientErrorsTotal += 1;
+        const nodeErr = err;
+        const event = Object.freeze({
+          remoteAddress: socket.remoteAddress ?? null,
+          remotePort: socket.remotePort ?? null,
+          message: err.message,
+          code: typeof nodeErr.code === "string" ? nodeErr.code : null,
+          timestamp: /* @__PURE__ */ new Date()
+        });
+        this._emitContained("tlsClientError", event);
+      });
+    } else {
+      this._netServer = net.createServer();
+      this._netServer.on("connection", (socket) => {
+        this._onSocketAccepted(socket);
+      });
+    }
+    this._netServer.on("error", (err) => {
+      if (this.listenerCount("error") > 0) {
+        safeEmitError(this, err);
+      } else if (this._listening) {
+        this.emit("error", err);
+      }
+    });
+  }
+  /**
+   * 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, hostOrOpts) {
+    const host = typeof hostOrOpts === "string" ? hostOrOpts : hostOrOpts?.host ?? "127.0.0.1";
+    const signal = typeof hostOrOpts === "object" && hostOrOpts !== null ? hostOrOpts.signal : void 0;
+    if (signal?.aborted) {
+      return Promise.reject(new DOMException("Aborted", "AbortError"));
+    }
+    if (this._listening || this._listenInFlight) {
+      return Promise.reject(
+        new MllpConnectionError(
+          this._listening ? "listen() rejected: server is already listening \u2014 call close() before re-listening" : "listen() rejected: another listen() is already in flight on this server",
+          {
+            cause: new Error("listen already listening or in flight"),
+            phase: "connect"
+          }
+        )
+      );
+    }
+    if (isWildcardHost(host) && this._opts.allowWildcardBind !== true) {
+      return Promise.reject(
+        new MllpConnectionError(
+          `refusing to bind wildcard host '${host}' \u2014 set ServerOptions.allowWildcardBind: true to bind all interfaces`,
+          {
+            cause: new Error("wildcard bind requires allowWildcardBind"),
+            phase: "connect"
+          }
+        )
+      );
+    }
+    this._listenInFlight = true;
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const settle = (outcome, opts) => {
+        if (settled) return;
+        settled = true;
+        this._pendingListenSettle = null;
+        signal?.removeEventListener("abort", abortHandler);
+        this._netServer.removeListener("listening", onListening);
+        this._netServer.removeListener("error", onError);
+        if (opts?.closeServer === true) {
+          this._netServer.close();
+        }
+        this._listenInFlight = false;
+        if (outcome.ok) {
+          resolve();
+        } else {
+          reject(outcome.error);
+        }
+      };
+      const abortHandler = () => {
+        settle(
+          { ok: false, error: new DOMException("Aborted", "AbortError") },
+          {
+            closeServer: true
+          }
+        );
+      };
+      if (signal !== void 0) {
+        signal.addEventListener("abort", abortHandler, { once: true });
+      }
+      this._pendingListenSettle = () => {
+        settle({
+          ok: false,
+          error: new MllpConnectionError(
+            "listen() failed: server was closed while listen() was in flight",
+            {
+              cause: new Error("close() during in-flight listen()"),
+              phase: "connect"
+            }
+          )
+        });
+      };
+      const onListening = () => {
+        if (settled) return;
+        this._pendingListenSettle = null;
+        signal?.removeEventListener("abort", abortHandler);
+        const addr = this._netServer.address();
+        if (addr === null || typeof addr === "string") {
+          settle(
+            {
+              ok: false,
+              error: new MllpConnectionError(
+                "listen() failed: server was closed before the bind completed",
+                {
+                  cause: new Error("server.address() returned no TCP address"),
+                  phase: "connect"
+                }
+              )
+            },
+            { closeServer: true }
+          );
+          return;
+        }
+        const actualPort = addr.port;
+        const actualHost = addr.address;
+        if (isWildcardHost(actualHost) && this._opts.allowWildcardBind !== true) {
+          settle(
+            {
+              ok: false,
+              error: new MllpConnectionError(
+                `refusing to bind wildcard host '${host}' (bound address '${actualHost}') \u2014 set ServerOptions.allowWildcardBind: true to bind all interfaces`,
+                {
+                  cause: new Error("wildcard bind requires allowWildcardBind"),
+                  phase: "connect"
+                }
+              )
+            },
+            { closeServer: true }
+          );
+          return;
+        }
+        this._listening = true;
+        this._port = actualPort;
+        this._host = actualHost;
+        const emitSubscriberSafe = (event, payload) => {
+          try {
+            this.emit(event, payload);
+          } catch (subscriberErr) {
+            try {
+              this._emitErrorIfListened(
+                subscriberErr instanceof Error ? subscriberErr : new Error(String(subscriberErr))
+              );
+            } catch {
+            }
+          }
+        };
+        const wildcardBound = isWildcardHost(actualHost);
+        const wildcardMessage = `MLLP server is bound to ALL network interfaces (host='${actualHost}') \u2014 set a specific bind address unless this is intentional.`;
+        if (wildcardBound) {
+          process.emitWarning(wildcardMessage, { code: MLLP_BIND_ALL_INTERFACES });
+        }
+        emitSubscriberSafe("listening", Object.freeze({ port: actualPort, host: actualHost }));
+        if (wildcardBound) {
+          const warning = Object.freeze({
+            code: MLLP_BIND_ALL_INTERFACES,
+            message: wildcardMessage,
+            host: actualHost,
+            port: actualPort,
+            timestamp: /* @__PURE__ */ new Date()
+          });
+          emitSubscriberSafe("securityWarning", warning);
+        }
+        settle({ ok: true });
+      };
+      const onError = (err) => {
+        settle({ ok: false, error: err });
+      };
+      this._netServer.once("listening", onListening);
+      this._netServer.once("error", onError);
+      this._netServer.listen(port, host);
+    });
+  }
+  /**
+   * 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 });
+   * ```
+   */
+  async close(opts) {
+    const signal = opts?.signal;
+    if (signal?.aborted) {
+      return Promise.reject(new DOMException("Aborted", "AbortError"));
+    }
+    this._pendingListenSettle?.();
+    this._netServer.close();
+    this._listening = false;
+    if (this._connections.size === 0) {
+      this._emitContained("close", Object.freeze({}));
+      return Promise.resolve();
+    }
+    let abortHandler;
+    const abortPromise = signal !== void 0 ? new Promise((_resolve, reject) => {
+      abortHandler = () => {
+        for (const conn of this._connections) {
+          conn.destroy();
+        }
+        reject(new DOMException("Aborted", "AbortError"));
+      };
+      signal.addEventListener("abort", abortHandler, { once: true });
+    }) : null;
+    try {
+      const drainTimeoutMs = opts?.drainTimeoutMs ?? this._opts.drainTimeoutMs ?? 3e4;
+      if (abortPromise !== null) {
+        await Promise.race([this._drainAll(drainTimeoutMs), abortPromise]);
+      } else {
+        await this._drainAll(drainTimeoutMs);
+      }
+    } finally {
+      if (abortHandler !== void 0 && signal !== void 0) {
+        signal.removeEventListener("abort", abortHandler);
+      }
+    }
+    this._emitContained("close", Object.freeze({}));
+  }
+  /**
+   * 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.
+   */
+  async _drainAll(drainTimeoutMs) {
+    const snapshot = [...this._connections];
+    const closePromises = snapshot.map((conn) => conn.close({ drainTimeoutMs }));
+    const timeoutHandle = setTimeout(() => {
+      for (const conn of this._connections) {
+        conn.destroy();
+      }
+    }, drainTimeoutMs);
+    timeoutHandle.unref();
+    try {
+      await Promise.all(closePromises);
+    } finally {
+      clearTimeout(timeoutHandle);
+    }
+  }
+  /**
+   * 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
+   * ```
+   */
+  async [Symbol.asyncDispose]() {
+    return this.close();
+  }
+  /**
+   * 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() {
+    let totalBytesIn = 0;
+    let totalBytesOut = 0;
+    for (const conn of this._connections) {
+      const s = conn.getStats();
+      totalBytesIn += s.bytesIn;
+      totalBytesOut += s.bytesOut;
+    }
+    return {
+      listening: this._listening,
+      port: this._port,
+      host: this._host,
+      connections: this._connections.size,
+      activeConnections: this._connections.size,
+      totalBytesIn,
+      totalBytesOut,
+      acceptedTotal: this._acceptedTotal,
+      closedTotal: this._closedTotal,
+      tls: this._isTls,
+      tlsClientErrorsTotal: this._tlsClientErrorsTotal
+    };
+  }
+  /**
+   * 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'`.
+   */
+  _emitContained(event, payload) {
+    safeEmit(this, event, payload, (err) => {
+      this._emitErrorIfListened(err);
+    });
+  }
+  _emitErrorIfListened(errEvent) {
+    safeEmitError(this, errEvent);
+  }
+  // ---------------------------------------------------------------------------
+  // Private: per-socket setup
+  // ---------------------------------------------------------------------------
+  _onSocketAccepted(socket) {
+    if (this._opts.keepaliveIntervalMs !== void 0) {
+      socket.setKeepAlive(true, this._opts.keepaliveIntervalMs);
+    }
+    const transport = this._isTls ? new TlsTransport(socket) : new NetTransport(socket);
+    const mergedFraming = {
+      ...SERVER_DEFAULT_FRAMING,
+      ...this._opts.framing ?? {}
+    };
+    const connOpts = this._opts.onWarning !== void 0 ? { transport, framing: mergedFraming, onWarning: this._opts.onWarning } : { transport, framing: mergedFraming };
+    const conn = new Connection(connOpts);
+    conn.beforeClose = () => Promise.resolve();
+    conn.on("error", (errEvent) => {
+      this._emitErrorIfListened(errEvent);
+    });
+    this._acceptedTotal++;
+    this._connections.add(conn);
+    let ended = false;
+    const _onConnEnded = () => {
+      if (ended) return;
+      ended = true;
+      this._connections.delete(conn);
+      this._closedTotal++;
+    };
+    conn.once("close", _onConnEnded);
+    conn.once("disconnect", _onConnEnded);
+    if (this._opts.deadPeerTimeoutMs !== void 0) {
+      const timeoutMs = this._opts.deadPeerTimeoutMs;
+      let deadPeerTimer = setTimeout(() => {
+        conn.destroy(new Error("idle timeout"));
+      }, timeoutMs);
+      deadPeerTimer.unref();
+      conn.on("message", () => {
+        clearTimeout(deadPeerTimer);
+        deadPeerTimer = setTimeout(() => {
+          conn.destroy(new Error("idle timeout"));
+        }, timeoutMs);
+        deadPeerTimer.unref();
+      });
+      conn.once("close", () => {
+        clearTimeout(deadPeerTimer);
+      });
+    }
+    conn.notifyConnect(socket.remoteAddress ?? null, socket.remotePort ?? null);
+    conn.on(
+      "message",
+      (event) => {
+        const { payload, connectionId, byteOffset, warnings } = event;
+        const meta = Object.freeze({
+          connectionId,
+          byteOffset,
+          warnings
+        });
+        try {
+          this.emit("message", Object.freeze({ payload, meta }));
+        } catch (err) {
+          this._emitErrorIfListened(
+            Object.freeze({
+              connectionId,
+              error: err instanceof Error ? err : new Error(String(err))
+            })
+          );
+        }
+        const autoAck = this._opts.autoAck;
+        if (autoAck === "AA") {
+          void this._sendCommitAck(payload, meta, conn);
+        } else if (autoAck !== void 0) {
+          this._observeMessage(payload, meta, conn);
+          void this._sendCustomAck(autoAck, payload, meta, conn);
+        } else {
+          this._observeMessage(payload, meta, conn);
+        }
+      }
+    );
+    const peerCertificate = this._isTls && (this._opts.tls?.clientAuth ?? "NONE") !== "NONE" ? this._extractPeerCertificateSummary(socket) : null;
+    this._emitContained(
+      "connection",
+      Object.freeze({
+        connectionId: conn.connectionId,
+        remoteAddress: socket.remoteAddress ?? null,
+        remotePort: socket.remotePort ?? null,
+        peerCertificate
+      })
+    );
+  }
+  /**
+   * 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).
+   */
+  _extractPeerCertificateSummary(socket) {
+    const cert = socket.getPeerCertificate();
+    if (cert === void 0 || cert === null || Object.keys(cert).length === 0) {
+      return null;
+    }
+    const asCn = (value) => {
+      if (value === void 0) return null;
+      return Array.isArray(value) ? value[0] ?? null : value;
+    };
+    return Object.freeze({
+      subjectCN: asCn(cert.subject?.CN),
+      issuerCN: asCn(cert.issuer?.CN),
+      validTo: cert.valid_to ?? null,
+      // Verification outcome — under 'WANT' a certificate can be present yet
+      // UNVERIFIED (see PeerCertificateSummary.authorized JSDoc).
+      authorized: socket.authorized === true
+    });
+  }
+  /**
+   * 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.
+   */
+  async _sendCommitAck(payload, meta, conn) {
+    const handler = this._opts.onMessage;
+    if (handler === void 0) {
+      this._dispatchAck(
+        conn,
+        buildRawAck(payload, this._resolveAutoAckPositive(payload, meta, conn))
+      );
+      return;
+    }
+    let code;
+    try {
+      await handler(payload, meta, conn);
+      code = this._resolveAutoAckPositive(payload, meta, conn);
+    } catch (err) {
+      const nack = resolveNackCode(err);
+      code = nack;
+      this._emitContained(
+        "nack",
+        Object.freeze({
+          connectionId: conn.connectionId,
+          ackCode: nack,
+          reason: "handler-rejected"
+        })
+      );
+    }
+    this._dispatchAck(conn, buildRawAck(payload, code));
+  }
+  /**
+   * 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.
+   */
+  _resolveAutoAckPositive(payload, meta, conn) {
+    const discarded = meta.warnings.some((w) => w.code === "MLLP_TRAILING_BYTES");
+    const uncorrelatable = rawAckUncorrelatable(payload);
+    if (!discarded && !uncorrelatable) return "AA";
+    const reason = discarded ? "discarded-bytes" : "uncorrelatable-inbound";
+    this._emitContained(
+      "nack",
+      Object.freeze({
+        connectionId: conn.connectionId,
+        ackCode: "AE",
+        reason
+      })
+    );
+    return "AE";
+  }
+  /**
+   * 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.
+   */
+  _observeMessage(payload, meta, conn) {
+    const handler = this._opts.onMessage;
+    if (handler === void 0) return;
+    void Promise.resolve().then(() => handler(payload, meta, conn)).catch((err) => {
+      const connErr = err instanceof Error ? err : new Error(String(err));
+      safeEmitError(conn, Object.freeze({ connectionId: conn.connectionId, error: connErr }));
+    });
+  }
+  /**
+   * 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).
+   */
+  async _sendCustomAck(fn, payload, meta, conn) {
+    try {
+      const ackPayload = await Promise.resolve(fn(payload, meta, conn));
+      this._dispatchAck(conn, ackPayload);
+    } catch (err) {
+      const connErr = err instanceof Error ? err : new Error(String(err));
+      safeEmitError(conn, Object.freeze({ connectionId: conn.connectionId, error: connErr }));
+    }
+  }
+  /**
+   * 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.
+   */
+  _dispatchAck(conn, ackPayload) {
+    let framed;
+    try {
+      framed = encodeFrame(ackPayload);
+    } catch (err) {
+      const cause = err instanceof Error ? err : new Error(String(err));
+      safeEmitError(
+        conn,
+        Object.freeze({
+          connectionId: conn.connectionId,
+          error: new MllpConnectionError("ACK could not be framed", { cause, phase: "send" })
+        })
+      );
+      return;
+    }
+    const sent = conn.send(framed);
+    if (!sent) {
+      safeEmitError(
+        conn,
+        Object.freeze({
+          connectionId: conn.connectionId,
+          error: new MllpConnectionError("ACK dropped: socket backpressure", {
+            cause: new Error("backpressure"),
+            phase: "send"
+          })
+        })
+      );
+    }
+  }
+};
+function createServer(opts = {}) {
+  return new MllpServer(opts);
+}
+async function createStarterServer(opts) {
+  const server = createServer({
+    ...opts,
+    autoAck: opts.autoAck ?? "AA",
+    drainTimeoutMs: opts.drainTimeoutMs ?? 3e4
+  });
+  if (opts.handleSignals === true) {
+    const sigHandler = () => {
+      void server.close().then(() => process.exit(0)).catch(() => process.exit(1));
+    };
+    process.once("SIGTERM", sigHandler);
+    process.once("SIGINT", sigHandler);
+    server.once("close", () => {
+      process.removeListener("SIGTERM", sigHandler);
+      process.removeListener("SIGINT", sigHandler);
+    });
+  }
+  await server.listen(opts.port, opts.host ?? "127.0.0.1");
+  return server;
+}
+
+// src/client/correlator.ts
+var Correlator = class {
+  _opts;
+  _pending = /* @__PURE__ */ new Map();
+  _graveyard = /* @__PURE__ */ new Map();
+  _sendSeq = 0;
+  _queueBytes = 0;
+  /**
+   * PLAN-06 — count of pending entries with `sentAt !== null` (D-26 / B-01).
+   * Maintained at every site that mutates `entry.sentAt` or removes a
+   * flushed entry: `markFlushed`, `remove`, `matchAck`, `expireDue`, `clear`.
+   */
+  _inFlight = 0;
+  /**
+   * Construct a send/ACK correlator.
+   *
+   * @param opts - Correlation options (FIFO vs control-id mode, ACK timeout, max in-flight).
+   */
+  constructor(opts) {
+    this._opts = {
+      mode: opts.mode ?? "fifo",
+      ackTimeoutMs: opts.ackTimeoutMs ?? 3e4,
+      maxInFlight: opts.maxInFlight ?? Number.POSITIVE_INFINITY,
+      onWarning: opts.onWarning,
+      onTimeout: opts.onTimeout,
+      onUnmatchedAck: opts.onUnmatchedAck,
+      now: opts.now ?? Date.now
+    };
+  }
+  /** Number of live pending entries. */
+  get size() {
+    return this._pending.size;
+  }
+  /** Sum of `frame.length` across live entries. */
+  get queueBytes() {
+    return this._queueBytes;
+  }
+  /** Number of graveyard entries awaiting lazy eviction. */
+  get graveyardSize() {
+    return this._graveyard.size;
+  }
+  /**
+   * Enqueue a new send awaiting its ACK. Returns the assigned
+   * `correlationKey`, or `null` if `maxInFlight` is reached (caller awaits
+   * drain — PLAN-05's `pipeline:false`).
+   */
+  enqueue(frame, controlIdOrNull, resolve, reject) {
+    if (this._pending.size >= this._opts.maxInFlight) return null;
+    const key = this._opts.mode === "controlId" ? controlIdOrNull ?? `__seq-${++this._sendSeq}` : ++this._sendSeq;
+    const entry = {
+      key,
+      frame,
+      controlId: controlIdOrNull,
+      byteCount: frame.length,
+      sentAt: null,
+      resolve,
+      reject
+    };
+    this._pending.set(key, entry);
+    this._queueBytes += frame.length;
+    return key;
+  }
+  /**
+   * Record write-flush timestamp (CLIENT-04 — clock starts at flush, NOT
+   * at `send()` call). No-op if key is unknown (e.g. removed by abort).
+   */
+  markFlushed(key, now) {
+    const entry = this._pending.get(key);
+    if (entry === void 0) return;
+    if (entry.sentAt === null) this._inFlight += 1;
+    entry.sentAt = now ?? this._opts.now();
+  }
+  /**
+   * Match an inbound ACK against the live store.
+   *
+   * - FIFO: returns first pending entry by insertion order; entry is
+   *   removed from live store. Caller calls `entry.resolve(ackPayload)`.
+   * - controlId: keyed lookup by `controlIdFromAck`. Live-store hit returns
+   *   the entry; graveyard hit fires `MLLP_ACK_AFTER_TIMEOUT` warning
+   *   (CLIENT-16, D-04) and returns `null`; otherwise fires
+   *   `onUnmatchedAck(controlIdFromAck)` (CLIENT-15, D-05) and returns `null`.
+   *
+   * Triggers lazy graveyard eviction (D-04).
+   *
+   * @param _payload Inbound ACK bytes (framing stripped). MSA-2 extraction
+   *   happens at MllpClient's `_onAckPayload` hook; this method takes the
+   *   already-extracted control ID as a parameter.
+   * @param controlIdFromAck MSA-2 extracted from ACK (controlId mode only).
+   * @param byteOffsetFromAck Stream offset; forwarded to `onWarning` (W-05).
+   */
+  matchAck(_payload, controlIdFromAck = null, byteOffsetFromAck = 0) {
+    this._evictGraveyardDue(this._opts.now());
+    if (this._opts.mode === "fifo") {
+      const iter = this._pending.values().next();
+      if (iter.done === true) return null;
+      const entry = iter.value;
+      this._pending.delete(entry.key);
+      this._queueBytes -= entry.byteCount;
+      if (entry.sentAt !== null) this._inFlight -= 1;
+      return entry;
+    }
+    if (controlIdFromAck === null) {
+      if (this._opts.onUnmatchedAck !== void 0) {
+        this._opts.onUnmatchedAck("");
+      }
+      return null;
+    }
+    const live = this._pending.get(controlIdFromAck);
+    if (live !== void 0) {
+      this._pending.delete(controlIdFromAck);
+      this._queueBytes -= live.byteCount;
+      if (live.sentAt !== null) this._inFlight -= 1;
+      return live;
+    }
+    const grave = this._graveyard.get(controlIdFromAck);
+    if (grave !== void 0) {
+      const elapsedSinceSendMs = this._opts.now() - grave.timedOutAt;
+      this._opts.onWarning("MLLP_ACK_AFTER_TIMEOUT", {
+        controlId: grave.controlId,
+        elapsedSinceSendMs,
+        byteOffset: byteOffsetFromAck
+      });
+      this._graveyard.delete(controlIdFromAck);
+      return null;
+    }
+    if (this._opts.onUnmatchedAck !== void 0) {
+      this._opts.onUnmatchedAck(controlIdFromAck);
+    }
+    return null;
+  }
+  /**
+   * Sweep live entries; expire those past `sentAt + ackTimeoutMs`.
+   * Fires `onTimeout(entry, elapsedMs)`; entries move to graveyard (D-04).
+   * Driven externally by `MllpClient`'s periodic sweep tick — Correlator
+   * itself owns no timers (D-03).
+   */
+  expireDue(now) {
+    const t = now ?? this._opts.now();
+    const ackTimeoutMs = this._opts.ackTimeoutMs;
+    for (const [key, entry] of this._pending) {
+      if (entry.sentAt !== null && entry.sentAt + ackTimeoutMs <= t) {
+        const elapsed = t - entry.sentAt;
+        this._pending.delete(key);
+        this._queueBytes -= entry.byteCount;
+        this._inFlight -= 1;
+        this._graveyard.set(key, {
+          timedOutAt: t,
+          controlId: entry.controlId
+        });
+        this._opts.onTimeout(entry, elapsed);
+      }
+    }
+  }
+  /**
+   * Reject every live entry with `reason` (insertion order) and clear
+   * the live store. Graveyard is left intact (ages out via lazy eviction).
+   * Used by FIFO reconnect-reject (D-07 — PLAN-04 wraps in MllpConnectionError)
+   * and `MllpClient.close()` to cancel pending sends.
+   */
+  clear(reason) {
+    for (const entry of this._pending.values()) entry.reject(reason);
+    this._pending.clear();
+    this._queueBytes = 0;
+    this._inFlight = 0;
+  }
+  /** Iterate live entries in insertion order (PLAN-04 reconnect-resend, D-07). */
+  *liveEntries() {
+    for (const entry of this._pending.values()) yield entry;
+  }
+  /**
+   * Remove a live entry by key WITHOUT resolving/rejecting. Returns the
+   * removed entry, or `null` if no entry with that key exists.
+   * Used by `MllpClient.send()` for AbortSignal cleanup and PLAN-04's
+   * reconnect-reject FSM walk.
+   */
+  remove(key) {
+    const entry = this._pending.get(key);
+    if (entry === void 0) return null;
+    this._pending.delete(key);
+    this._queueBytes -= entry.byteCount;
+    if (entry.sentAt !== null) this._inFlight -= 1;
+    return entry;
+  }
+  /** JSON-serializable stats snapshot (no Buffers, no class instances). */
+  getStats() {
+    return {
+      size: this._pending.size,
+      queueBytes: this._queueBytes,
+      graveyardSize: this._graveyard.size,
+      sendSeq: this._sendSeq,
+      inFlight: this._inFlight
+    };
+  }
+  /** Lazy graveyard eviction (D-04): drop entries past `timedOutAt + 2 * ackTimeoutMs`. */
+  _evictGraveyardDue(now) {
+    const threshold = 2 * this._opts.ackTimeoutMs;
+    for (const [key, entry] of this._graveyard) {
+      if (entry.timedOutAt + threshold <= now) this._graveyard.delete(key);
+    }
+  }
+};
+
+// src/client/error.ts
+var MllpTimeoutError = class _MllpTimeoutError extends Error {
+  name = "MllpTimeoutError";
+  /** MSH-10 control ID of the timed-out send (FIFO mode: `undefined`). */
+  messageControlId;
+  /** Milliseconds elapsed between write-flush and timeout fire. */
+  elapsedMs;
+  /** Epoch ms timestamp recorded at write-flush callback. */
+  sentAt;
+  /**
+   * 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, opts) {
+    super(message);
+    this.messageControlId = opts.messageControlId;
+    this.elapsedMs = opts.elapsedMs;
+    this.sentAt = opts.sentAt;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _MllpTimeoutError);
+    }
+  }
+};
+function isTlsVerificationErrorCode(code) {
+  switch (code) {
+    case "UNABLE_TO_VERIFY_LEAF_SIGNATURE":
+    case "DEPTH_ZERO_SELF_SIGNED_CERT":
+    case "SELF_SIGNED_CERT_IN_CHAIN":
+    case "UNABLE_TO_GET_ISSUER_CERT":
+    case "UNABLE_TO_GET_ISSUER_CERT_LOCALLY":
+    case "CERT_HAS_EXPIRED":
+    case "CERT_NOT_YET_VALID":
+    case "CERT_REVOKED":
+    case "CERT_UNTRUSTED":
+    case "CERT_REJECTED":
+    case "CERT_SIGNATURE_FAILURE":
+    case "HOSTNAME_MISMATCH":
+    case "ERR_TLS_CERT_ALTNAME_INVALID":
+      return true;
+    default:
+      return code.startsWith("CERT_");
+  }
+}
+function isTlsProtocolError(err) {
+  if (typeof err !== "object" || err === null) return false;
+  const code = err.code;
+  if (typeof code === "string") {
+    if (code.startsWith("ERR_SSL_")) return true;
+    if (code === "EPROTO") return true;
+  }
+  const message = err.message;
+  if (typeof message === "string" && /\bssl\b|\balert\b/i.test(message)) return true;
+  return false;
+}
+function isTransientConnectionError(err) {
+  if (typeof err !== "object" || err === null) return true;
+  const code = err.code;
+  if (typeof code !== "string") return true;
+  switch (code) {
+    case "ENOTFOUND":
+    case "EACCES":
+      return false;
+    case "ECONNREFUSED":
+    case "ECONNRESET":
+    case "ETIMEDOUT":
+    case "EHOSTUNREACH":
+    case "ENETUNREACH":
+    case "EPIPE":
+      return true;
+    default:
+      if (isTlsVerificationErrorCode(code)) return false;
+      if (code.startsWith("ERR_SSL_")) return false;
+      if (code.startsWith("MLLP_")) return false;
+      return true;
+  }
+}
+var MllpBackpressureError = class _MllpBackpressureError extends Error {
+  name = "MllpBackpressureError";
+  /** Number of in-flight + queued sends at the moment of rejection. */
+  queueDepth;
+  /** Total bytes of in-flight + queued frames at the moment of rejection. */
+  queueBytes;
+  /** The high-water-mark configuration that was triggered (D-23). */
+  highWaterMark;
+  /**
+   * 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, opts) {
+    super(message);
+    this.queueDepth = opts.queueDepth;
+    this.queueBytes = opts.queueBytes;
+    this.highWaterMark = opts.highWaterMark;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _MllpBackpressureError);
+    }
+  }
+};
+
+// src/client/client.ts
+var NEVER_ABORTING_SIGNAL = new AbortController().signal;
+var MllpClient = class extends events.EventEmitter {
+  _opts;
+  _connection = null;
+  _socket = null;
+  /**
+   * Initial state for `get state()` before `_connection` exists. Once a Connection
+   * is attached, `state` mirrors `_connection.state`.
+   */
+  _state = "DISCONNECTED";
+  /** Per-message ACK timeout in ms (CLIENT-04). Resolved at construction. */
+  _ackTimeoutMs;
+  /** controlId-mode flag (CLIENT-03 branch). `false` → FIFO. */
+  _correlateByControlId;
+  /** Unified ACK correlator (D-03/A1). Built during `_attachConnection`. */
+  _correlator = null;
+  /**
+   * Periodic ACK-timeout sweep timer. Drives `_correlator.expireDue()` because
+   * the Correlator is timer-free per D-03. Cleared on close/destroy.
+   */
+  _ackSweepTimer = null;
+  // ── Reconnect state (Plan 04, CLIENT-05/06/12/17/18) ─────────────────────
+  _autoReconnect;
+  _initialDelayMs;
+  _maxDelayMs;
+  _multiplier;
+  _jitter;
+  _retryStrategy;
+  /** 0-indexed attempt counter for the current reconnect cycle. */
+  _attempt = 0;
+  /**
+   * 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.
+   */
+  _reconnectAttempts = 0;
+  /** Epoch ms of the last successful ACK. Drives W-01 backoff-reset. */
+  _lastSuccessAt = null;
+  /** Epoch ms when the current reconnect cycle began. `null` outside a cycle. */
+  _reconnectCycleStartedAt = null;
+  /** Active backoff `setTimeout` handle. `null` when no backoff is armed. */
+  _backoffTimer = null;
+  /** Last delay (ms) used by the strategy. Surfaced via RetryContext.lastDelayMs. */
+  _lastDelayMs = 0;
+  // ── Backpressure + pipeline state (Plan 05, CLIENT-07/CLIENT-19, D-23) ───
+  /** Count cap; `Number.POSITIVE_INFINITY` when only bytes configured. */
+  _hwmCount;
+  /** Byte cap; `Number.POSITIVE_INFINITY` when only count configured. */
+  _hwmBytes;
+  /** Backpressure policy; default `'reject'`. */
+  _onBackpressure;
+  /** Pipeline flag; default `true` (parallel up to highWaterMark). */
+  _pipeline;
+  /** Dead-peer idle timer (Plan 05 — D-11). `null` when not armed. */
+  _deadPeerTimer = null;
+  /** True once the self-'ack' listener that resets the dead-peer timer
+   * has been attached. Guards against duplicate listeners on reconnect. */
+  _ackResetWired = false;
+  /** Most recently bound `connect()` signal. Reread on every RetryContext build (W-07). */
+  _connectSignal;
+  /** Set when close()/destroy()/abort fires; reconnect handler short-circuits. */
+  _userClosed = false;
+  /** Captured Connection error feeding `RetryContext.lastError`. */
+  _lastError = null;
+  /** Listener-removal handle for the abort listener bound in connect(). */
+  _abortListener = null;
+  /**
+   * Test-only seam — when set, `_beginReconnectAttempt` builds the new
+   * Connection through this factory instead of opening a real net.Socket.
+   *
+   * @internal
+   */
+  _reconnectFactory = null;
+  // ── PLAN-06 — observability counters for getStats (OBS-01, D-26) ─────────
+  /** Total successful `conn.send()` flushes since construction. */
+  _sentTotal = 0;
+  /** Total ACKs resolved since construction. */
+  _ackedTotal = 0;
+  /** Total ACK timeouts since construction. */
+  _timedOutTotal = 0;
+  /** Epoch ms of the most recent CONNECTED transition (null until first). */
+  _lastConnectedAt = null;
+  /** Epoch ms of the most recent successful ACK (null until first). */
+  _lastAckAt = null;
+  /**
+   * 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).
+   */
+  _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) {
+    super();
+    this._opts = opts;
+    this._ackTimeoutMs = opts.ackTimeoutMs ?? 3e4;
+    this._correlateByControlId = opts.correlateByControlId === true;
+    this._autoReconnect = opts.autoReconnect === true;
+    this._initialDelayMs = opts.initialDelayMs ?? 100;
+    this._maxDelayMs = opts.maxDelayMs ?? 3e4;
+    this._multiplier = opts.multiplier ?? 2;
+    this._jitter = opts.jitter ?? 0.2;
+    this._retryStrategy = opts.retryStrategy;
+    const hwm = opts.highWaterMark ?? 64;
+    if (typeof hwm === "number") {
+      this._hwmCount = hwm;
+      this._hwmBytes = Number.POSITIVE_INFINITY;
+    } else {
+      this._hwmCount = hwm.count ?? Number.POSITIVE_INFINITY;
+      this._hwmBytes = hwm.bytes ?? Number.POSITIVE_INFINITY;
+    }
+    this._onBackpressure = opts.onBackpressure ?? "reject";
+    this._pipeline = opts.pipeline !== false;
+  }
+  /**
+   * 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() {
+    return this._connection?.state ?? this._state;
+  }
+  /**
+   * 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) {
+    const signal = opts?.signal;
+    if (signal?.aborted) {
+      return Promise.reject(new DOMException("Aborted", "AbortError"));
+    }
+    if (this._connection !== null && this._connection.state !== "CLOSED" && this._connection.state !== "DISCONNECTED") {
+      return Promise.reject(
+        new MllpConnectionError("already connected or connecting", {
+          cause: new Error("already connected"),
+          phase: "connect"
+        })
+      );
+    }
+    if (signal !== void 0) {
+      this._captureConnectSignal(signal);
+    }
+    return new Promise((resolve, reject) => {
+      let aborted = false;
+      const { socket, transport } = this._createSocketAndTransport();
+      if (this._opts.keepaliveIntervalMs !== void 0) {
+        socket.setKeepAlive(true, this._opts.keepaliveIntervalMs);
+      }
+      this._socket = socket;
+      const connOpts = this._opts.framing !== void 0 ? { transport, framing: this._opts.framing } : { transport };
+      if (this._opts.drainTimeoutMs !== void 0) {
+        connOpts.drainTimeoutMs = this._opts.drainTimeoutMs;
+      }
+      const conn = new Connection(connOpts);
+      this._attachConnection(conn);
+      const connectEventName = this._opts.tls !== void 0 ? "secureConnect" : "connect";
+      const cleanup = () => {
+        if (signal !== void 0) {
+          signal.removeEventListener("abort", abortHandler);
+        }
+        socket.removeListener(connectEventName, onSocketConnect);
+        socket.removeListener("error", onSocketError);
+      };
+      const abortHandler = () => {
+        aborted = true;
+        cleanup();
+        this._teardownCorrelator(
+          new MllpConnectionError("connect aborted", {
+            cause: new Error("aborted"),
+            phase: "connect"
+          })
+        );
+        conn.destroy(new Error("aborted"));
+        reject(new DOMException("Aborted", "AbortError"));
+      };
+      const onSocketConnect = () => {
+        if (aborted) return;
+        cleanup();
+        conn.notifyConnect(socket.remoteAddress ?? null, socket.remotePort ?? null);
+        this._emitInsecureWarningIfNeeded();
+        resolve();
+      };
+      const onSocketError = (err) => {
+        if (aborted) return;
+        cleanup();
+        reject(this._wrapConnectError(err, "connect"));
+      };
+      if (signal !== void 0) {
+        signal.addEventListener("abort", abortHandler, { once: true });
+      }
+      socket.once(connectEventName, onSocketConnect);
+      socket.once("error", onSocketError);
+    });
+  }
+  /**
+   * 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`.
+   */
+  _createSocketAndTransport() {
+    const tlsOpt = this._opts.tls;
+    if (tlsOpt === void 0) {
+      const socket2 = net.createConnection({ host: this._opts.host, port: this._opts.port });
+      return { socket: socket2, transport: new NetTransport(socket2) };
+    }
+    const tlsOpts = tlsOpt === true ? {} : tlsOpt;
+    const socket = tls.connect({
+      host: this._opts.host,
+      port: this._opts.port,
+      servername: tlsOpts.servername ?? this._opts.host,
+      ...tlsOpts.ca !== void 0 ? { ca: tlsOpts.ca } : {},
+      ...tlsOpts.cert !== void 0 ? { cert: tlsOpts.cert } : {},
+      ...tlsOpts.key !== void 0 ? { key: tlsOpts.key } : {},
+      ...tlsOpts.passphrase !== void 0 ? { passphrase: tlsOpts.passphrase } : {},
+      minVersion: tlsOpts.minVersion ?? "TLSv1.2",
+      ...tlsOpts.maxVersion !== void 0 ? { maxVersion: tlsOpts.maxVersion } : {},
+      ...tlsOpts.ciphers !== void 0 ? { ciphers: tlsOpts.ciphers } : {},
+      rejectUnauthorized: tlsOpts.allowUnverified !== true
+    });
+    return { socket, transport: new TlsTransport(socket) };
+  }
+  /**
+   * 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.
+   */
+  _wrapConnectError(err, phase) {
+    if (this._opts.tls === void 0) {
+      return new MllpConnectionError(err.message, { cause: err, phase });
+    }
+    const code = err.code;
+    if (typeof code === "string" && isTlsVerificationErrorCode(code)) {
+      return new MllpConnectionError(err.message, {
+        cause: err,
+        phase,
+        connectionCause: "tls-verify"
+      });
+    }
+    if (isTlsProtocolError(err)) {
+      return new MllpConnectionError(err.message, {
+        cause: err,
+        phase,
+        connectionCause: "tls-handshake"
+      });
+    }
+    return new MllpConnectionError(err.message, { cause: err, phase });
+  }
+  /**
+   * 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'`.
+   */
+  _emitContained(event, payload) {
+    safeEmit(this, event, payload, (err) => {
+      safeEmitError(this, Object.freeze({ error: err }));
+    });
+  }
+  /**
+   * 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.
+   */
+  _emitInsecureWarningIfNeeded() {
+    const tlsOpt = this._opts.tls;
+    if (tlsOpt === void 0 || tlsOpt === true) return;
+    if (tlsOpt.allowUnverified !== true) return;
+    const message = "MLLP TLS certificate verification is DISABLED (allowUnverified: true) \u2014 this connection does not authenticate the peer.";
+    const warning = Object.freeze({
+      code: MLLP_TLS_VERIFY_DISABLED,
+      message,
+      host: this._opts.host,
+      port: this._opts.port,
+      timestamp: /* @__PURE__ */ new Date()
+    });
+    this._emitContained("securityWarning", warning);
+    process.emitWarning(message, { code: MLLP_TLS_VERIFY_DISABLED });
+  }
+  /**
+   * 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.
+   */
+  _attachConnection(conn) {
+    if (this._correlator === null) {
+      this._correlator = new Correlator({
+        mode: this._correlateByControlId ? "controlId" : "fifo",
+        ackTimeoutMs: this._ackTimeoutMs,
+        // Plan 05 — pipeline:false collapses the in-flight set to ≤1 (D-06).
+        maxInFlight: this._pipeline ? Number.POSITIVE_INFINITY : 1,
+        onWarning: (code, ctx) => {
+          this._aggregatedWarningsByCode[code] = (this._aggregatedWarningsByCode[code] ?? 0) + 1;
+          this._emitContained(
+            "warning",
+            Object.freeze({
+              code,
+              byteOffset: ctx.byteOffset,
+              message: `${code}: controlId=${ctx.controlId} elapsed=${ctx.elapsedSinceSendMs}ms`,
+              connectionId: this._connection?.connectionId ?? conn.connectionId,
+              timestamp: /* @__PURE__ */ new Date()
+            })
+          );
+        },
+        onUnmatchedAck: (controlId) => {
+          if (this.listenerCount("error") === 0) return;
+          const err = new MllpFramingError(
+            "MLLP_ACK_UNMATCHED_CONTROL_ID",
+            0,
+            Buffer.alloc(0),
+            `Unmatched ACK control ID${controlId === "" ? "" : `: ${controlId}`}`
+          );
+          safeEmitError(
+            this,
+            Object.freeze({
+              connectionId: this._connection?.connectionId ?? conn.connectionId,
+              error: err,
+              controlId
+            })
+          );
+        },
+        onTimeout: (entry, elapsedMs) => {
+          this._timedOutTotal += 1;
+          entry.reject(
+            new MllpTimeoutError(`ACK timeout after ${elapsedMs}ms`, {
+              messageControlId: entry.controlId ?? void 0,
+              elapsedMs,
+              sentAt: entry.sentAt ?? 0
+            })
+          );
+          this._maybeEmitDrain();
+        }
+      });
+    }
+    if (this._ackSweepTimer === null) {
+      const sweepIntervalMs = Math.max(50, Math.min(1e3, Math.floor(this._ackTimeoutMs / 4)));
+      this._ackSweepTimer = setInterval(() => {
+        this._correlator?.expireDue();
+      }, sweepIntervalMs);
+      this._ackSweepTimer.unref();
+    }
+    conn.on("stateChange", (e) => {
+      this._onStateChange(e);
+    });
+    conn.on(
+      "message",
+      (e) => {
+        this._emitContained("message", Object.freeze({ ...e }));
+        this._armDeadPeerTimer();
+        this._onAckPayload(e.payload, e.byteOffset);
+      }
+    );
+    conn.on("connect", (e) => {
+      this._emitContained("connect", Object.freeze({ ...e }));
+    });
+    conn.on("disconnect", (e) => {
+      this._emitContained("disconnect", Object.freeze({ ...e }));
+    });
+    conn.on("reconnecting", (e) => {
+      this._emitContained("reconnecting", Object.freeze({ ...e }));
+    });
+    conn.on("close", (e) => {
+      this._emitContained("close", Object.freeze({ ...e }));
+    });
+    conn.on("warning", (w) => {
+      this._emitContained("warning", w);
+      this._armDeadPeerTimer();
+    });
+    conn.on("error", (e) => {
+      const wrapper = e instanceof Error ? e : e?.error;
+      if (wrapper instanceof Error) {
+        const inner = wrapper.cause;
+        this._lastError = inner instanceof Error ? inner : wrapper;
+      }
+      safeEmitError(this, e);
+    });
+    this._connection = conn;
+    if (!this._ackResetWired) {
+      this._ackResetWired = true;
+      this.on("ack", () => {
+        this._armDeadPeerTimer();
+      });
+    }
+    if (conn.state === "CONNECTED") {
+      this._armDeadPeerTimer();
+    }
+  }
+  /**
+   * Arm (or re-arm) the dead-peer idle timer (Plan 05 — CLIENT-08, D-11).
+   * No-op when `deadPeerTimeoutMs` is unset.
+   */
+  _armDeadPeerTimer() {
+    if (this._opts.deadPeerTimeoutMs === void 0) return;
+    if (this._deadPeerTimer !== null) {
+      clearTimeout(this._deadPeerTimer);
+    }
+    this._deadPeerTimer = setTimeout(() => {
+      this._connection?.destroy(new Error("dead peer timeout"));
+    }, this._opts.deadPeerTimeoutMs);
+    this._deadPeerTimer.unref();
+  }
+  /**
+   * Clear the dead-peer idle timer (Plan 05 — D-14 timer cleanup on
+   * every transition out of CONNECTED).
+   */
+  _clearDeadPeerTimer() {
+    if (this._deadPeerTimer !== null) {
+      clearTimeout(this._deadPeerTimer);
+      this._deadPeerTimer = null;
+    }
+  }
+  /**
+   * 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.
+   */
+  _handleDisconnect(err) {
+    if (this._userClosed) return;
+    if (this._correlator !== null) {
+      if (this._correlateByControlId) ; else {
+        const orphans = [];
+        const queued = [];
+        for (const entry of this._correlator.liveEntries()) {
+          if (entry.sentAt !== null) orphans.push(entry);
+          else queued.push(entry);
+        }
+        for (const o of orphans) {
+          o.reject(
+            new MllpConnectionError("in-flight send orphaned by reconnect", {
+              cause: err,
+              phase: "reconnect",
+              connectionCause: "in-flight-orphan"
+            })
+          );
+        }
+        for (const q of queued) {
+          q.reject(
+            new MllpConnectionError("queued send rejected by FIFO reconnect", {
+              cause: err,
+              phase: "reconnect",
+              connectionCause: "fifo-unsafe"
+            })
+          );
+        }
+        for (const entry of [...orphans, ...queued]) {
+          this._correlator.remove(entry.key);
+        }
+      }
+    }
+    const tlsProtocolShaped = this._opts.tls !== void 0 && isTlsProtocolError(err);
+    const classifiedAs = !tlsProtocolShaped && isTransientConnectionError(err) ? "transient" : "permanent";
+    if (classifiedAs === "permanent") {
+      this._userClosed = true;
+      this._connection?.destroy(err);
+      return;
+    }
+    this._reconnectAttempts += 1;
+    if (this._reconnectCycleStartedAt === null && this._lastSuccessAt !== null) {
+      this._attempt = 0;
+    }
+    if (this._reconnectCycleStartedAt === null) {
+      this._reconnectCycleStartedAt = Date.now();
+    }
+    const ctx = Object.freeze({
+      attempt: this._attempt,
+      lastError: err,
+      lastDelayMs: this._lastDelayMs,
+      totalElapsedMs: Date.now() - this._reconnectCycleStartedAt,
+      sinceLastSuccessMs: this._lastSuccessAt !== null ? Date.now() - this._lastSuccessAt : Number.POSITIVE_INFINITY,
+      classifiedAs,
+      signal: this._connectSignal ?? NEVER_ABORTING_SIGNAL
+    });
+    let delay;
+    try {
+      const strategy = this._retryStrategy ?? this._defaultRetryStrategy;
+      delay = strategy(ctx);
+    } catch (hookErr) {
+      this._lastError = hookErr instanceof Error ? hookErr : new Error(String(hookErr));
+      {
+        safeEmitError(
+          this,
+          Object.freeze({
+            connectionId: this._connection?.connectionId ?? "<none>",
+            error: this._lastError
+          })
+        );
+      }
+      this._userClosed = true;
+      this._connection?.destroy(this._lastError);
+      return;
+    }
+    if (delay === null) {
+      this._userClosed = true;
+      this._connection?.destroy(err);
+      return;
+    }
+    this._emitContained(
+      "reconnecting",
+      Object.freeze({
+        connectionId: this._connection?.connectionId ?? "<none>",
+        attempt: this._attempt,
+        delayMs: delay
+      })
+    );
+    this._lastDelayMs = delay;
+    this._backoffTimer = setTimeout(() => {
+      this._backoffTimer = null;
+      this._attempt += 1;
+      this._beginReconnectAttempt();
+    }, delay);
+    this._backoffTimer.unref();
+  }
+  /**
+   * Default retry strategy (D-19): `min(maxDelay, initialDelay * multiplier^attempt)`
+   * with ±jitter applied.
+   */
+  _defaultRetryStrategy = (ctx) => {
+    const base = Math.min(
+      this._maxDelayMs,
+      this._initialDelayMs * Math.pow(this._multiplier, ctx.attempt)
+    );
+    const jitterFactor = 1 + (Math.random() * 2 - 1) * this._jitter;
+    return Math.max(0, Math.floor(base * jitterFactor));
+  };
+  /**
+   * 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.
+   */
+  _beginReconnectAttempt() {
+    if (this._userClosed) return;
+    try {
+      let conn;
+      let arm;
+      if (this._reconnectFactory !== null) {
+        ({ conn, arm } = this._reconnectFactory());
+      } else {
+        const { socket, transport } = this._createSocketAndTransport();
+        if (this._opts.keepaliveIntervalMs !== void 0) {
+          socket.setKeepAlive(true, this._opts.keepaliveIntervalMs);
+        }
+        this._socket = socket;
+        const connOpts = this._opts.framing !== void 0 ? { transport, framing: this._opts.framing } : { transport };
+        if (this._opts.drainTimeoutMs !== void 0) {
+          connOpts.drainTimeoutMs = this._opts.drainTimeoutMs;
+        }
+        conn = new Connection(connOpts);
+        arm = () => {
+          conn.notifyConnect(socket.remoteAddress ?? null, socket.remotePort ?? null);
+          this._emitInsecureWarningIfNeeded();
+        };
+        const connectEventName = this._opts.tls !== void 0 ? "secureConnect" : "connect";
+        socket.once("error", (sErr) => {
+          if (this._lastError === null || this._lastError.message !== sErr.message) {
+            this._lastError = sErr;
+          }
+        });
+        socket.once(connectEventName, () => {
+          arm();
+          this._afterReconnectArmed();
+        });
+        this._connection = null;
+        this._attachConnection(conn);
+        return;
+      }
+      this._connection = null;
+      this._attachConnection(conn);
+      arm();
+      this._afterReconnectArmed();
+    } catch (err) {
+      this._lastError = err instanceof Error ? err : new Error(String(err));
+      this._handleDisconnect(this._lastError);
+    }
+  }
+  /**
+   * 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.
+   */
+  _afterReconnectArmed() {
+    if (this._correlateByControlId && this._correlator !== null && this._connection !== null) {
+      const conn = this._connection;
+      const corr = this._correlator;
+      const entries = [...corr.liveEntries()];
+      for (const entry of entries) conn.send(entry.frame);
+      const now = Date.now();
+      for (const entry of entries) corr.markFlushed(entry.key, now);
+    }
+    this._reconnectCycleStartedAt = null;
+  }
+  /**
+   * Test seam — install a factory that produces the next reconnect Connection.
+   *
+   * @internal
+   */
+  _setReconnectFactory(factory) {
+    this._reconnectFactory = factory;
+  }
+  /**
+   * Test seam — capture or rebind the connect-signal mid-flight (W-07).
+   *
+   * @internal
+   */
+  _captureConnectSignal(signal) {
+    this._connectSignal = signal;
+    if (this._abortListener !== null) {
+      this._abortListener.signal.removeEventListener("abort", this._abortListener.handler);
+      this._abortListener = null;
+    }
+    const handler = () => {
+      this._userClosed = true;
+      if (this._backoffTimer !== null) {
+        clearTimeout(this._backoffTimer);
+        this._backoffTimer = null;
+      }
+      this._connection?.destroy(new DOMException("Aborted", "AbortError"));
+    };
+    signal.addEventListener("abort", handler, { once: true });
+    this._abortListener = { signal, handler };
+  }
+  /**
+   * 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).
+   */
+  _onAckPayload(ackPayload, byteOffset) {
+    if (this._correlator === null) return;
+    const ackControlId = this._correlateByControlId ? extractMsaControlId(ackPayload) : null;
+    const matched = this._correlator.matchAck(ackPayload, ackControlId, byteOffset);
+    if (matched !== null) {
+      this._onAckMatched(matched, ackPayload);
+    }
+  }
+  /**
+   * 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.
+   */
+  _onAckMatched(matched, ackPayload) {
+    const latencyMs = matched.sentAt !== null ? Date.now() - matched.sentAt : 0;
+    this._emitContained(
+      "ack",
+      Object.freeze({
+        payload: ackPayload,
+        controlId: matched.controlId,
+        latencyMs
+      })
+    );
+    this._lastSuccessAt = Date.now();
+    this._ackedTotal += 1;
+    this._lastAckAt = Date.now();
+    matched.resolve(ackPayload);
+    this._maybeEmitDrain();
+  }
+  /**
+   * 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.
+   */
+  _maybeEmitDrain() {
+    const corr = this._correlator;
+    if (corr === null) return;
+    const belowCount = corr.size < this._hwmCount;
+    const belowBytes = corr.queueBytes < this._hwmBytes;
+    if (belowCount && belowBytes) {
+      this._emitContained(
+        "drain",
+        Object.freeze({
+          queueDepth: corr.size,
+          queueBytes: corr.queueBytes
+        })
+      );
+    }
+  }
+  /**
+   * 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.
+   */
+  _onStateChange(e) {
+    this._emitContained("stateChange", Object.freeze({ ...e }));
+    if (e.to === "CONNECTED") {
+      this._armDeadPeerTimer();
+      this._lastConnectedAt = Date.now();
+    }
+    if (e.from === "CONNECTED" && e.to !== "CONNECTED") {
+      this._clearDeadPeerTimer();
+    }
+    const isPostConnectedDrop = e.from === "CONNECTED" && (e.to === "DISCONNECTED" || e.to === "RECONNECTING" || e.to === "CLOSED");
+    const isReconnectAttemptFailure = this._reconnectCycleStartedAt !== null && (e.from === "CONNECTING" || e.from === "RECONNECTING") && (e.to === "CLOSED" || e.to === "DISCONNECTED");
+    if (isPostConnectedDrop || isReconnectAttemptFailure) {
+      const cause = this._lastError ?? new Error(e.reason ?? "disconnect");
+      if (this._userClosed) return;
+      if (!this._autoReconnect) {
+        this._teardownCorrelator(
+          new MllpConnectionError("disconnected; autoReconnect disabled", {
+            cause,
+            phase: "send"
+          })
+        );
+        return;
+      }
+      this._handleDisconnect(cause);
+    }
+  }
+  /**
+   * 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, opts) {
+    const signal = opts?.signal;
+    if (signal?.aborted === true) {
+      return Promise.reject(new DOMException("Aborted", "AbortError"));
+    }
+    if (this._connection === null || this._correlator === null || this._connection.state !== "CONNECTED") {
+      return Promise.reject(
+        new MllpConnectionError("send before connect", {
+          cause: new Error(`client state is ${this.state}`),
+          phase: "send"
+        })
+      );
+    }
+    const controlId = this._correlateByControlId ? extractMshControlId(payload) : null;
+    const correlator = this._correlator;
+    const conn = this._connection;
+    const frame = encodeFrame(payload);
+    const newQueueDepth = correlator.size + 1;
+    const newQueueBytes = correlator.queueBytes + frame.length;
+    const overCount = newQueueDepth > this._hwmCount;
+    const overBytes = newQueueBytes > this._hwmBytes;
+    if (overCount || overBytes) {
+      const hwmDesc = {};
+      if (this._hwmCount !== Number.POSITIVE_INFINITY) {
+        hwmDesc.count = this._hwmCount;
+      }
+      if (this._hwmBytes !== Number.POSITIVE_INFINITY) {
+        hwmDesc.bytes = this._hwmBytes;
+      }
+      if (this._onBackpressure === "reject") {
+        return Promise.reject(
+          new MllpBackpressureError(
+            `queue at high-water mark (depth=${correlator.size}, bytes=${correlator.queueBytes})`,
+            {
+              queueDepth: correlator.size,
+              queueBytes: correlator.queueBytes,
+              highWaterMark: hwmDesc
+            }
+          )
+        );
+      }
+      return this._waitThenSend(payload, opts);
+    }
+    return new Promise((resolve, reject) => {
+      let abortListener = null;
+      const wrappedResolve = (ack) => {
+        if (signal !== void 0 && abortListener !== null) {
+          signal.removeEventListener("abort", abortListener);
+        }
+        resolve(ack);
+      };
+      const wrappedReject = (err) => {
+        if (signal !== void 0 && abortListener !== null) {
+          signal.removeEventListener("abort", abortListener);
+        }
+        reject(err);
+      };
+      const key = correlator.enqueue(frame, controlId, wrappedResolve, wrappedReject);
+      if (key === null) {
+        const onDrain = () => {
+          this.off("drain", onDrain);
+          this.send(payload, opts).then(wrappedResolve, wrappedReject);
+        };
+        this.on("drain", onDrain);
+        if (signal !== void 0) {
+          abortListener = () => {
+            this.off("drain", onDrain);
+            wrappedReject(new DOMException("Aborted", "AbortError"));
+          };
+          signal.addEventListener("abort", abortListener, { once: true });
+        }
+        return;
+      }
+      if (signal !== void 0) {
+        abortListener = () => {
+          correlator.remove(key);
+          wrappedReject(new DOMException("Aborted", "AbortError"));
+        };
+        signal.addEventListener("abort", abortListener, { once: true });
+      }
+      conn.send(frame);
+      correlator.markFlushed(key, Date.now());
+      this._sentTotal += 1;
+    });
+  }
+  /**
+   * '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.
+   */
+  _waitThenSend(payload, opts) {
+    const signal = opts?.signal;
+    return new Promise((resolve, reject) => {
+      const ackTimeoutMs = opts?.ackTimeoutMs ?? this._ackTimeoutMs;
+      let abortListener = null;
+      const cleanup = () => {
+        this.off("drain", onDrain);
+        clearTimeout(timer);
+        if (signal !== void 0 && abortListener !== null) {
+          signal.removeEventListener("abort", abortListener);
+        }
+      };
+      const onDrain = () => {
+        cleanup();
+        this.send(payload, opts).then(resolve, reject);
+      };
+      const timer = setTimeout(() => {
+        cleanup();
+        reject(
+          new MllpTimeoutError(`waiting for drain timed out after ${ackTimeoutMs}ms`, {
+            messageControlId: void 0,
+            elapsedMs: ackTimeoutMs,
+            sentAt: Date.now()
+          })
+        );
+      }, ackTimeoutMs);
+      timer.unref();
+      this.on("drain", onDrain);
+      if (signal !== void 0) {
+        abortListener = () => {
+          cleanup();
+          reject(new DOMException("Aborted", "AbortError"));
+        };
+        signal.addEventListener("abort", abortListener, { once: true });
+      }
+    });
+  }
+  /**
+   * Tear down per-connection state (sweep timer + correlator) when the
+   * client is closing or destroying. Safe to call multiple times.
+   */
+  _teardownCorrelator(reason) {
+    if (this._ackSweepTimer !== null) {
+      clearInterval(this._ackSweepTimer);
+      this._ackSweepTimer = null;
+    }
+    if (this._correlator !== null) {
+      this._correlator.clear(reason);
+      this._correlator = null;
+    }
+    this._clearDeadPeerTimer();
+  }
+  /**
+   * **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) {
+    if (this._connection !== null) {
+      throw new MllpConnectionError("connection already attached", {
+        cause: new Error("attach twice"),
+        phase: "connect"
+      });
+    }
+    this._attachConnection(conn);
+  }
+  /**
+   * 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 });
+   * ```
+   */
+  async close(opts) {
+    const signal = opts?.signal;
+    if (signal?.aborted) {
+      return Promise.reject(new DOMException("Aborted", "AbortError"));
+    }
+    this._userClosed = true;
+    if (this._backoffTimer !== null) {
+      clearTimeout(this._backoffTimer);
+      this._backoffTimer = null;
+    }
+    const conn = this._connection;
+    if (conn === null) {
+      this._teardownCorrelator(
+        new MllpConnectionError("client closed", {
+          cause: new Error("closed"),
+          phase: "close"
+        })
+      );
+      return;
+    }
+    this._teardownCorrelator(
+      new MllpConnectionError("client closed", {
+        cause: new Error("closed"),
+        phase: "close"
+      })
+    );
+    if (signal === void 0) {
+      const closeOpts = opts?.drainTimeoutMs !== void 0 ? { drainTimeoutMs: opts.drainTimeoutMs } : void 0;
+      await conn.close(closeOpts);
+      return;
+    }
+    let abortHandler;
+    const abortPromise = new Promise((_resolve, reject) => {
+      abortHandler = () => {
+        conn.destroy(new Error("aborted"));
+        reject(new DOMException("Aborted", "AbortError"));
+      };
+      signal.addEventListener("abort", abortHandler, { once: true });
+    });
+    try {
+      const closeOpts = opts?.drainTimeoutMs !== void 0 ? { drainTimeoutMs: opts.drainTimeoutMs } : void 0;
+      await Promise.race([conn.close(closeOpts), abortPromise]);
+    } finally {
+      if (abortHandler !== void 0) {
+        signal.removeEventListener("abort", abortHandler);
+      }
+    }
+  }
+  /**
+   * 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) {
+    this._userClosed = true;
+    if (this._backoffTimer !== null) {
+      clearTimeout(this._backoffTimer);
+      this._backoffTimer = null;
+    }
+    const teardownReason = reason ?? new MllpConnectionError("client destroyed", {
+      cause: new Error("destroyed"),
+      phase: "close"
+    });
+    this._teardownCorrelator(teardownReason);
+    const conn = this._connection;
+    if (conn === null) return;
+    conn.destroy(reason);
+  }
+  /**
+   * 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() {
+    const connStats = this._connection?.getStats();
+    const corrStats = this._correlator?.getStats();
+    const merged = {
+      ...this._aggregatedWarningsByCode
+    };
+    if (connStats !== void 0) {
+      for (const [k, v] of Object.entries(connStats.warningsByCode)) {
+        const code = k;
+        merged[code] = (merged[code] ?? 0) + v;
+      }
+    }
+    return {
+      state: this.state,
+      connectionId: connStats?.connectionId ?? null,
+      queueDepth: corrStats?.size ?? 0,
+      queueBytes: corrStats?.queueBytes ?? 0,
+      inFlight: corrStats?.inFlight ?? 0,
+      warningsByCode: merged,
+      totalBytesIn: connStats?.bytesIn ?? 0,
+      totalBytesOut: connStats?.bytesOut ?? 0,
+      sentTotal: this._sentTotal,
+      ackedTotal: this._ackedTotal,
+      timedOutTotal: this._timedOutTotal,
+      reconnectAttempts: this._reconnectAttempts,
+      lastConnectedAt: this._lastConnectedAt,
+      lastAckAt: this._lastAckAt,
+      tls: this._opts.tls !== void 0
+    };
+  }
+  /**
+   * 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
+   * ```
+   */
+  async [Symbol.asyncDispose]() {
+    return this.close();
+  }
+};
+function createClient(opts) {
+  return new MllpClient(opts);
+}
+async function createStarterClient(opts) {
+  const clientOpts = {
+    host: opts.host,
+    port: opts.port,
+    autoReconnect: opts.autoReconnect ?? true,
+    ackTimeoutMs: opts.ackTimeoutMs ?? 3e4,
+    correlateByControlId: opts.correlateByControlId ?? false,
+    pipeline: opts.pipeline ?? true,
+    highWaterMark: opts.highWaterMark ?? 64,
+    onBackpressure: opts.onBackpressure ?? "reject",
+    ...opts.drainTimeoutMs !== void 0 ? { drainTimeoutMs: opts.drainTimeoutMs } : {},
+    ...opts.framing !== void 0 ? { framing: opts.framing } : {},
+    ...opts.retryStrategy !== void 0 ? { retryStrategy: opts.retryStrategy } : {},
+    ...opts.keepaliveIntervalMs !== void 0 ? { keepaliveIntervalMs: opts.keepaliveIntervalMs } : {},
+    ...opts.deadPeerTimeoutMs !== void 0 ? { deadPeerTimeoutMs: opts.deadPeerTimeoutMs } : {},
+    ...opts.tls !== void 0 ? { tls: opts.tls } : {}
+  };
+  const client = createClient(clientOpts);
+  if (opts.onMessage !== void 0) {
+    const handler = opts.onMessage;
+    client.on("message", (e) => {
+      handler(e.payload);
+    });
+  }
+  if (opts.handleSignals === true) {
+    const sigHandler = () => {
+      void client.close().then(() => process.exit(0)).catch(() => process.exit(1));
+    };
+    process.once("SIGTERM", sigHandler);
+    process.once("SIGINT", sigHandler);
+    client.once("close", () => {
+      process.removeListener("SIGTERM", sigHandler);
+      process.removeListener("SIGINT", sigHandler);
+    });
+  }
+  await client.connect();
+  return client;
+}
+
+// src/index.ts
+var VERSION = "0.0.1";
+
+exports.Connection = Connection;
+exports.FrameReader = FrameReader;
+exports.MLLP_BIND_ALL_INTERFACES = MLLP_BIND_ALL_INTERFACES;
+exports.MLLP_TLS_VERIFY_DISABLED = MLLP_TLS_VERIFY_DISABLED;
+exports.MllpAckError = MllpAckError;
+exports.MllpBackpressureError = MllpBackpressureError;
+exports.MllpClient = MllpClient;
+exports.MllpConnectionError = MllpConnectionError;
+exports.MllpFramingError = MllpFramingError;
+exports.MllpServer = MllpServer;
+exports.MllpTimeoutError = MllpTimeoutError;
+exports.NetTransport = NetTransport;
+exports.TlsTransport = TlsTransport;
+exports.VERSION = VERSION;
+exports.buildRawAck = buildRawAck;
+exports.createClient = createClient;
+exports.createServer = createServer;
+exports.createStarterClient = createStarterClient;
+exports.createStarterServer = createStarterServer;
+exports.createWarning = createWarning;
+exports.encodeFrame = encodeFrame;
+exports.isTlsProtocolError = isTlsProtocolError;
+exports.isTlsVerificationErrorCode = isTlsVerificationErrorCode;
+exports.isTransientConnectionError = isTransientConnectionError;
+exports.rawAckUncorrelatable = rawAckUncorrelatable;
+exports.resolveNackCode = resolveNackCode;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map