@cosyte/mllp 0.0.11 → 0.1.0

package/dist/index.d.cts

@@ -631,9 +631,11 @@ interface SecurityWarning {
  * direct comparison. ITI TF-2 §3.19.6.2.3 mandates four TLS 1.2 cipher
  * suites: `TLS_DHE_RSA_WITH_AES_128_GCM_SHA256`,
  * `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`, `TLS_DHE_RSA_WITH_AES_256_GCM_SHA384`,
- * `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`. Node's default TLS 1.2 cipher list
- * already includes both mandated ECDHE suites, so this package pins to Node
- * defaults rather than bundling a cipher list, see `docs-content/tls.md`.
+ * `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`. Set `atnaTransportSecurity: true`
+ * to offer exactly those four (plus the TLS 1.3 defaults) instead of whatever
+ * the runtime's own list happens to be; it is off by default, and what a link
+ * negotiated is reported on the `'tlsNegotiated'` event either way. See
+ * `docs-content/tls.md`.
  *
  * @example
  * ```typescript
@@ -697,11 +699,40 @@ interface TlsOptions {
     readonly minVersion?: "TLSv1.2" | "TLSv1.3";
     /** Maximum negotiated TLS protocol version. */
     readonly maxVersion?: "TLSv1.2" | "TLSv1.3";
+    /**
+     * Offer exactly the cipher suites the IHE ATNA ITI-19 transport-security
+     * option names (ITI TF-2 §3.19.6.2.3), rather than inheriting the runtime's
+     * own list. Off by default; turning it on only ever **narrows** what is
+     * offered.
+     *
+     * This is the **cipher-suite half** of that option, and it does not make the
+     * declaration on your behalf. Mutual node authentication is
+     * `ServerTlsOptions.clientAuth` plus a client `cert`/`key`, and the TLS 1.2
+     * floor is {@link TlsOptions.minVersion}, which already defaults to it.
+     *
+     * The four TLS 1.2 suites are offered together with the three TLS 1.3 suites
+     * the runtime enables by default, so selecting this never removes a protocol
+     * version that was reachable without it. A peer that supports none of them
+     * fails the handshake rather than falling back, which is the point.
+     *
+     * Mutually exclusive with {@link TlsOptions.ciphers}: both declare the
+     * offered list, so setting both rejects `connect()` with a typed
+     * `MllpTlsConfigurationError`.
+     *
+     * @default false
+     */
+    readonly atnaTransportSecurity?: boolean;
     /**
      * OpenSSL cipher-list string passthrough (`tls.connect`'s `ciphers`).
      * Unset uses Node's compiled-in defaults, which already include both
      * ATNA-mandated ECDHE suites (see the module doc comment). Set this to
-     * restrict to a stricter list (e.g. DHE suites) if your deployment requires it.
+     * restrict to a stricter list of your own choosing; for the ATNA option's
+     * own four suites prefer {@link TlsOptions.atnaTransportSecurity}, which is
+     * the same declaration made once and reported on `'tlsNegotiated'`.
+     *
+     * A list the runtime rejects rejects `connect()` with a typed
+     * `MllpTlsConfigurationError`; it never silently falls back to the default
+     * list.
      *
      * @default undefined (Node defaults)
      */
@@ -779,14 +810,449 @@ interface ServerTlsOptions {
     readonly minVersion?: "TLSv1.2" | "TLSv1.3";
     /** Maximum negotiated TLS protocol version. */
     readonly maxVersion?: "TLSv1.2" | "TLSv1.3";
+    /**
+     * Offer exactly the cipher suites the IHE ATNA ITI-19 transport-security
+     * option names (ITI TF-2 §3.19.6.2.3), rather than inheriting the runtime's
+     * own list. Off by default; turning it on only ever **narrows** what is
+     * offered.
+     *
+     * The server side additionally provides ephemeral Diffie-Hellman parameters,
+     * because two of the four named suites are DHE and a server without them
+     * cannot actually offer a DHE suite. The group is the one the runtime selects
+     * for the certificate in use unless {@link ServerTlsOptions.dhParameters}
+     * names another, which takes precedence. See
+     * {@link TlsOptions.atnaTransportSecurity} for the rest, including what this
+     * setting does **not** claim on your behalf.
+     *
+     * Mutually exclusive with {@link ServerTlsOptions.ciphers}: setting both
+     * rejects `listen()` with a typed `MllpTlsConfigurationError`.
+     *
+     * @default false
+     */
+    readonly atnaTransportSecurity?: boolean;
     /**
      * OpenSSL cipher-list string passthrough. Unset uses Node's defaults
-     * (includes both ATNA-mandated ECDHE suites).
+     * (includes both ATNA-mandated ECDHE suites). For the ATNA option's own four
+     * suites prefer {@link ServerTlsOptions.atnaTransportSecurity}.
+     *
+     * A list the runtime rejects rejects `listen()` with a typed
+     * `MllpTlsConfigurationError`; it never silently falls back to the default
+     * list.
      *
      * @default undefined (Node defaults)
      */
     readonly ciphers?: string;
+    /**
+     * Ephemeral Diffie-Hellman parameters this server answers a DHE key exchange
+     * with, as **PEM content**. There is deliberately no filesystem-path input:
+     * every credential on this type is content, and this package performs no disk
+     * IO for any of it. Generate a group with `openssl dhparam` and read it in
+     * yourself.
+     *
+     * A DHE cipher suite is unofferable by a server with no parameters, so this
+     * is what makes one reachable through {@link ServerTlsOptions.ciphers}: a
+     * list restricted to a DHE suite without this advertises that suite and then
+     * fails every handshake in it.
+     *
+     * **It takes precedence over the group
+     * {@link ServerTlsOptions.atnaTransportSecurity} selects automatically**, and
+     * setting both is not a conflict: the option picks a group when nothing else
+     * says which, and this says which. That is how a deployment whose own policy
+     * names a group puts it in force while still offering exactly the ITI TF-2
+     * §3.19.6.2.3 suites.
+     *
+     * Parameters this package or the TLS library cannot use reject `listen()`
+     * with a typed `MllpTlsConfigurationError` carrying
+     * `MLLP_TLS_DH_PARAMETERS_REJECTED`, before anything is bound. Nothing falls
+     * back to a server running without them, which matters because the TLS
+     * library's own behaviour for unreadable parameters is to discard them in
+     * silence. `'auto'` is not accepted here; that selection is what
+     * `atnaTransportSecurity` already makes.
+     *
+     * There is no counterpart on {@link TlsOptions}: the side that answers the
+     * key exchange supplies the parameters.
+     *
+     * @default undefined (no Diffie-Hellman parameters unless `atnaTransportSecurity` selects them)
+     */
+    readonly dhParameters?: string | Buffer;
+}
+
+/**
+ * Typed TLS **configuration** errors and their stable codes.
+ *
+ * A configuration error is raised before any socket exists: what this package
+ * was asked to offer cannot be honoured, so the connection is refused rather
+ * than opened on some other configuration. Two things can be asked for, and
+ * they carry separate codes: the offered cipher-suite list, and the server's
+ * ephemeral Diffie-Hellman parameters. It rejects the `connect()` / `listen()`
+ * call that asked for it, never a live connection.
+ *
+ * These codes are a **public API**. They appear in caller `catch` blocks, log
+ * pipelines, and monitoring dashboards. Renaming or removing a code is a
+ * breaking change (the same guardrail the security-warning codes carry).
+ *
+ * @example
+ * ```typescript
+ * import { MllpTlsConfigurationError, MLLP_TLS_CIPHER_LIST_REJECTED } from '@cosyte/mllp';
+ * try {
+ *   await client.connect();
+ * } catch (err) {
+ *   if (err instanceof MllpTlsConfigurationError && err.code === MLLP_TLS_CIPHER_LIST_REJECTED) {
+ *     logger.error({ code: err.code });
+ *   }
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+/**
+ * The runtime refused the cipher-suite list it was handed: no suite in it is
+ * available in this Node build's TLS library. Nothing falls back to the
+ * runtime default list, the connection or the bind is refused instead.
+ *
+ * @example
+ * ```typescript
+ * import { MLLP_TLS_CIPHER_LIST_REJECTED } from '@cosyte/mllp';
+ * if (err.code === MLLP_TLS_CIPHER_LIST_REJECTED) process.exit(78); // EX_CONFIG
+ * ```
+ */
+declare const MLLP_TLS_CIPHER_LIST_REJECTED = "MLLP_TLS_CIPHER_LIST_REJECTED";
+/**
+ * Two different offered-suite declarations were made at once:
+ * `atnaTransportSecurity: true` fixes the list, and `ciphers` replaces it.
+ * Honouring either one silently discards the other, so both are refused.
+ *
+ * @example
+ * ```typescript
+ * import { MLLP_TLS_CIPHER_OPTION_CONFLICT } from '@cosyte/mllp';
+ * if (err.code === MLLP_TLS_CIPHER_OPTION_CONFLICT) logger.error('pick one of the two');
+ * ```
+ */
+declare const MLLP_TLS_CIPHER_OPTION_CONFLICT = "MLLP_TLS_CIPHER_OPTION_CONFLICT";
+/**
+ * The ephemeral Diffie-Hellman parameters a server supplied are not usable: not
+ * PEM content, not a Diffie-Hellman parameter block, or a group the TLS library
+ * refuses. Distinct from {@link MLLP_TLS_CIPHER_LIST_REJECTED} because the
+ * remedy is different: one is the offered suite list, the other is the key
+ * exchange behind it.
+ *
+ * Nothing is bound and nothing falls back to a server running with no
+ * Diffie-Hellman parameters, which would advertise its DHE suites and then fail
+ * every handshake in them.
+ *
+ * @example
+ * ```typescript
+ * import { MLLP_TLS_DH_PARAMETERS_REJECTED } from '@cosyte/mllp';
+ * if (err.code === MLLP_TLS_DH_PARAMETERS_REJECTED) process.exit(78); // EX_CONFIG
+ * ```
+ */
+declare const MLLP_TLS_DH_PARAMETERS_REJECTED = "MLLP_TLS_DH_PARAMETERS_REJECTED";
+/**
+ * Union of the stable TLS-configuration error codes.
+ *
+ * @example
+ * ```typescript
+ * const code: TlsConfigurationErrorCode = 'MLLP_TLS_CIPHER_LIST_REJECTED';
+ * ```
+ */
+type TlsConfigurationErrorCode = typeof MLLP_TLS_CIPHER_LIST_REJECTED | typeof MLLP_TLS_CIPHER_OPTION_CONFLICT | typeof MLLP_TLS_DH_PARAMETERS_REJECTED;
+/**
+ * Fixed, human-readable description for a TLS-configuration code.
+ *
+ * Byte-for-byte identical for a given code, whatever the configuration was.
+ *
+ * @param code - The stable configuration-error code.
+ * @returns The frozen registry text for `code`.
+ *
+ * @example
+ * ```typescript
+ * import { tlsConfigurationMessage, MLLP_TLS_CIPHER_OPTION_CONFLICT } from '@cosyte/mllp';
+ * logger.error(tlsConfigurationMessage(MLLP_TLS_CIPHER_OPTION_CONFLICT));
+ * ```
+ */
+declare function tlsConfigurationMessage(code: TlsConfigurationErrorCode): string;
+/**
+ * Thrown for a TLS configuration this package will not open a connection on.
+ * Rejects the originating `MllpClient.connect()` or `MllpServer.listen()`; no
+ * socket is opened and no listener is left bound.
+ *
+ * Identify it by `instanceof` **and** by the stable {@link MllpTlsConfigurationError.code},
+ * never by matching on the message text. `message` is a frozen registry entry
+ * and carries no key material and no passphrase; `cause`, when present, is the
+ * TLS library's own error for one input on its own (the suite list and the
+ * Diffie-Hellman parameters are each validated with no credential in scope).
+ *
+ * @example
+ * ```typescript
+ * import { MllpTlsConfigurationError } from '@cosyte/mllp';
+ * try {
+ *   await server.listen(2575);
+ * } catch (err) {
+ *   if (err instanceof MllpTlsConfigurationError) logger.error({ code: err.code });
+ * }
+ * ```
+ */
+declare class MllpTlsConfigurationError extends Error {
+    readonly name: "MllpTlsConfigurationError";
+    /**
+     * The stable configuration-error code. Public API; branch on this rather
+     * than on the message.
+     */
+    readonly code: TlsConfigurationErrorCode;
+    /**
+     * The TLS library's own error, when the runtime is what refused the list.
+     * `undefined` when this package refused the configuration itself.
+     */
+    readonly cause: Error | undefined;
+    /**
+     * Construct a TLS configuration error.
+     *
+     * @param code - The stable configuration-error code; also selects the message.
+     * @param opts - Optional underlying `cause` from the TLS library.
+     */
+    constructor(code: TlsConfigurationErrorCode, opts?: {
+        cause?: Error;
+    });
+}
+
+/**
+ * The offered-cipher-suite policy behind `tls.atnaTransportSecurity`.
+ *
+ * Spec anchor: IHE ATNA, ITI-19 Authenticate Node
+ * (https://profiles.ihe.net/ITI/TF/Volume2/ITI-19.html), the "STX: TLS 1.2
+ * Floor using BCP195" option, ITI TF-2 §3.19.6.2.3, which names four TLS 1.2
+ * cipher suites an actor claiming that option supports, and allows
+ * "additional cipher suites of similar or greater cryptographic strength".
+ *
+ * With the option off (the default) this module imposes nothing and the
+ * offered list is the runtime's, which the runtime's own documentation says
+ * a distribution may configure at build time and an operator may replace
+ * wholesale from outside the process. With the option on, the offered list is
+ * a property of this package instead, and what a link negotiated is
+ * observable on the `'tlsNegotiated'` event.
+ *
+ * Two of the four suites are DHE, so the server half of the policy also settles
+ * which ephemeral Diffie-Hellman group is in force: the caller's own, when
+ * `ServerTlsOptions.dhParameters` names one, and otherwise the selection the
+ * runtime makes for the certificate in use.
+ *
+ * @example
+ * ```typescript
+ * import { ATNA_CIPHER_SUITES } from '@cosyte/mllp';
+ * console.log(ATNA_CIPHER_SUITES.length); // => 4
+ * ```
+ *
+ * @packageDocumentation
+ */
+/**
+ * The four TLS 1.2 cipher suites ITI TF-2 §3.19.6.2.3 names, in the OpenSSL
+ * spelling a cipher-list string is written in. Their IANA spellings, which are
+ * what the standard prints and what the `'tlsNegotiated'` event reports, are
+ * the same four prefixed `TLS_` and joined with `_WITH_`.
+ *
+ * @example
+ * ```typescript
+ * import { ATNA_CIPHER_SUITES } from '@cosyte/mllp';
+ * console.log(ATNA_CIPHER_SUITES.includes('ECDHE-RSA-AES128-GCM-SHA256')); // => true
+ * ```
+ */
+declare const ATNA_CIPHER_SUITES: readonly string[];
+/**
+ * The three TLS 1.3 cipher suites the runtime enables by default.
+ *
+ * They are carried alongside the four above for one reason: a TLS 1.3 suite is
+ * enabled only by its full name in the cipher list, so a list holding the four
+ * TLS 1.2 suites alone would turn TLS 1.3 **off**. Selecting the option must
+ * never remove a protocol version that was reachable without it, so these are
+ * restated rather than dropped.
+ *
+ * @example
+ * ```typescript
+ * import { TLS13_DEFAULT_CIPHER_SUITES } from '@cosyte/mllp';
+ * console.log(TLS13_DEFAULT_CIPHER_SUITES.length); // => 3
+ * ```
+ */
+declare const TLS13_DEFAULT_CIPHER_SUITES: readonly string[];
+/**
+ * The OpenSSL cipher-list string `tls.atnaTransportSecurity: true` offers:
+ * the three TLS 1.3 default suites followed by the four ITI TF-2 §3.19.6.2.3
+ * suites, and nothing else.
+ *
+ * @example
+ * ```typescript
+ * import { ATNA_CIPHER_LIST } from '@cosyte/mllp';
+ * console.log(ATNA_CIPHER_LIST.split(':').length); // => 7
+ * ```
+ */
+declare const ATNA_CIPHER_LIST: string;
+/**
+ * The cipher-suite half of a client's or server's TLS options, the two fields
+ * that can declare what is offered.
+ */
+interface TlsCipherPolicyInput {
+    /** See `TlsOptions.atnaTransportSecurity`. */
+    readonly atnaTransportSecurity?: boolean;
+    /** See `TlsOptions.ciphers`. */
+    readonly ciphers?: string;
+    /**
+     * See `ServerTlsOptions.dhParameters`. Diffie-Hellman parameters are supplied
+     * by the end that answers the key exchange, so this is read when `side` is
+     * `'server'` and **ignored, without an error, when `side` is `'client'`**.
+     *
+     * That asymmetry is stated rather than enforced because the field is
+     * unreachable from the client option type in the first place: `TlsOptions`
+     * carries no Diffie-Hellman parameter field at all, so a client value can
+     * only arrive through a direct call to
+     * {@link resolveTlsCipherPolicy}.
+     */
+    readonly dhParameters?: string | Buffer;
+}
+/**
+ * The TLS-context fields the resolved policy contributes. Empty when the
+ * option is off and no `ciphers` passthrough is set: this package then imposes
+ * no cipher list at all, exactly as before the option existed.
+ */
+interface ResolvedTlsCipherPolicy {
+    /** OpenSSL cipher-list string, or absent to impose none. */
+    readonly ciphers?: string;
+    /**
+     * Ephemeral Diffie-Hellman parameters, server-side only. Two of the four
+     * named suites are DHE, and a server with no DH parameters cannot offer a
+     * DHE suite at all: without this it would advertise the list and then fail
+     * every DHE handshake in it.
+     *
+     * Exactly two things reach this field. The literal `'auto'` is the TLS
+     * library's own spelling for the selection it makes from the certificate in
+     * use, which is what `atnaTransportSecurity: true` alone yields. Anything
+     * else is PEM content: the caller's own group, taken verbatim from
+     * `ServerTlsOptions.dhParameters` and preferred over the automatic selection.
+     * Absent when neither was asked for, so the not-selected path is untouched.
+     *
+     * Typed `string | Buffer` rather than `'auto' | string | Buffer` because the
+     * literal is absorbed by `string` in a union and says nothing to a reader
+     * there; it is stated here instead.
+     */
+    readonly dhparam?: string | Buffer;
+}
+/**
+ * Resolve the offered-cipher-suite policy for one side of a connection, and
+ * prove the runtime accepts it before any socket is opened.
+ *
+ * Refuses, rather than picking a winner, when both `atnaTransportSecurity` and
+ * `ciphers` are set: each declares the offered list, and honouring one would
+ * silently discard the other on a link whose whole point is being able to say
+ * what it offered.
+ *
+ * **Diffie-Hellman parameters are the one place a winner IS picked, and the
+ * caller wins.** `atnaTransportSecurity: true` selects a group automatically
+ * because two of its four suites are DHE; a caller that also names its own
+ * group is stating site policy, and site policy is more specific than a default
+ * this package chose. So the two are not in conflict and the configuration is
+ * accepted with the caller's group in force.
+ *
+ * Each input is validated **alone**, with no certificate, key or passphrase in
+ * scope, so a rejection can only ever be about that input and the error it
+ * raises cannot carry credential material.
+ *
+ * @param opts - The cipher-suite half of the caller's TLS options.
+ * @param side - Which end of the connection is being configured.
+ * @returns The TLS-context fields to spread into `tls.connect` / `tls.createServer`.
+ * @throws {MllpTlsConfigurationError} On a conflicting declaration, a list the
+ * runtime rejects, or Diffie-Hellman parameters it cannot use. Never falls back
+ * to the runtime default list, and never to a server with no Diffie-Hellman
+ * parameters.
+ *
+ * @example
+ * ```typescript
+ * import { resolveTlsCipherPolicy } from '@cosyte/mllp';
+ * const policy = resolveTlsCipherPolicy({ atnaTransportSecurity: true }, 'server');
+ * console.log(policy.dhparam); // => 'auto'
+ * ```
+ */
+declare function resolveTlsCipherPolicy(opts: TlsCipherPolicyInput, side: "client" | "server"): ResolvedTlsCipherPolicy;
+
+/**
+ * The `'tlsNegotiated'` event payload: what a completed TLS handshake actually
+ * agreed on.
+ *
+ * A deployment that has declared the IHE ATNA ITI-19 transport-security option
+ * on a link needs to be able to show, from its own logs, which protocol
+ * version and which cipher suite that link negotiated. This is that record,
+ * emitted once per completed handshake on both the client and the server.
+ *
+ * It is a **log line**, so it carries no field content: both values are read
+ * from the TLS session and are names out of a closed registry, never anything
+ * derived from the payload, the certificate, or the key.
+ *
+ * @example
+ * ```typescript
+ * import type { NegotiatedTlsParameters } from '@cosyte/mllp';
+ * client.on('tlsNegotiated', (p: NegotiatedTlsParameters) => {
+ *   logger.info({ tls: p.protocolVersion, suite: p.cipherSuite });
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Frozen payload of the `'tlsNegotiated'` event, emitted by both
+ * {@link MllpClient} and {@link MllpServer} once per completed TLS handshake,
+ * including every reconnect. Never emitted on a plaintext connection.
+ *
+ * Carries no HL7 payload content and no certificate or key material: only the
+ * two negotiated names and the same routing metadata a `SecurityWarning`
+ * carries. It is emitted at handshake-completion time, before any HL7 byte has
+ * crossed the link.
+ *
+ * @example
+ * ```typescript
+ * server.on('tlsNegotiated', (p: NegotiatedTlsParameters) => {
+ *   if (p.protocolVersion !== 'TLSv1.3') metrics.increment('mllp.tls12_link');
+ * });
+ * ```
+ */
+interface NegotiatedTlsParameters {
+    /**
+     * Negotiated protocol version as the TLS library reports it, e.g.
+     * `'TLSv1.2'` or `'TLSv1.3'`.
+     */
+    readonly protocolVersion: string;
+    /**
+     * Negotiated cipher suite in its **IANA** spelling, e.g.
+     * `'TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256'`. That is the spelling the IHE
+     * and IETF documents print, so it can be compared with a conformance claim
+     * directly. The OpenSSL spelling, which is what a `ciphers` list is written
+     * in, is a different rendering of the same suite.
+     */
+    readonly cipherSuite: string;
+    /** Host associated with the link (the target host for clients; the bind host for servers). */
+    readonly host: string;
+    /** Port associated with the link. */
+    readonly port: number;
+    /** Wall-clock time at point of emission. */
+    readonly timestamp: Date;
 }
+/**
+ * Read the negotiated parameters off a socket whose handshake has completed.
+ *
+ * Returns `null` for a socket that is not a TLS socket at all, and for a TLS
+ * socket with no session to report. That is what keeps a plaintext connection
+ * from producing an event: it is a structural property of the read, not a
+ * caller-side condition anyone has to remember.
+ *
+ * @param socket - The socket whose handshake completed; plaintext is allowed and yields `null`.
+ * @param host - Routing metadata for the payload's `host`.
+ * @param port - Routing metadata for the payload's `port`.
+ * @returns A frozen payload, or `null` when there is nothing negotiated to report.
+ *
+ * @example
+ * ```typescript
+ * const params = readNegotiatedTlsParameters(tlsSocket, 'mllp.example.com', 2575);
+ * if (params !== null) logger.info({ suite: params.cipherSuite });
+ * ```
+ */
+declare function readNegotiatedTlsParameters(socket: Socket | TLSSocket, host: string, port: number): NegotiatedTlsParameters | null;
 
 /**
  * Connection, 6-state FSM over a Transport with lifecycle events, warning streams,
@@ -1236,263 +1702,81 @@ declare class MllpConnectionError extends Error {
 }
 
 /**
- * Server-side MLLP acknowledgement construction and the **fail-safe commit contract**.
- *
- * This module owns the byte-level ACK builder used by {@link MllpServer}'s auto-ACK
- * path, the HL7 Table 0008 acknowledgement-code union, and the error type a message
- * handler throws to request a specific negative acknowledgement.
- *
- * ## Why this is safety-critical
+ * The frozen diagnostic registry for acknowledgement-mode reporting.
  *
- * A positive acknowledgement (`AA`) tells the sender "you may forget this message, I
- * have it." If a server emits `AA` *before* the message is durably handled and then the
- * process crashes, the message is **silently lost** with no record on either side. For
- * clinical messages (an admit, an order, a result) that is a patient-safety failure.
+ * Every message an acknowledgement-mode diagnostic can carry lives here as a literal, and
+ * the lookup takes **only a code**. There is no value parameter anywhere in this module,
+ * which is the whole point: a factory that cannot be handed a value cannot interpolate one,
+ * regardless of what arrives on the wire. It is the same shape, and for the same reason, as
+ * the correlation registry beside it.
  *
- * The contract this module enforces: a positive ACK (`AA`) is only built once the
- * application handler has resolved success. A handler that throws or rejects yields a
- * **negative** ACK (`AE` by default, `AR` when the handler asks for it), never `AA`.
+ * ## What these diagnostics may carry
  *
- * Spec: HL7 v2.5.1 ch. 2 §2.9.2 (original acknowledgement mode), §2.9.3 (enhanced
- * accept/application acknowledgement), Table 0008 (Acknowledgment Code), §2.9.2.2
- * (MSA-2 echoes the inbound MSH-10 message control ID).
+ * Stable codes, byte counts, byte offsets, elapsed times, and an acknowledgement code drawn
+ * from the closed six-code Table 0008 set. Nothing else. A control ID is payload content, a
+ * field value is payload content, and these go to a log. An MSA-1 that could not be
+ * classified is reported by its **byte length** only, never by its bytes: the whole reason a
+ * value is unclassifiable is that nobody knows what it is, so echoing it into a log is
+ * echoing unknown wire content into a log.
  *
  * @packageDocumentation
  */
 /**
- * HL7 Table 0008, Acknowledgment Code. A **stable public API**.
- *
- * Two families, by mode (HL7 v2.5.1 §2.9):
- *
- * - **Original mode (§2.9.2):** `AA` accept, `AE` application error, `AR` application
- *   reject. The single ACK reports application-level outcome.
- * - **Enhanced mode (§2.9.3):** `CA` commit accept, `CE` commit error, `CR` commit
- *   reject, the *accept* acknowledgement, distinct from a later application ACK.
+ * The stable codes acknowledgement-mode reporting emits.
  *
- * `AE` vs `AR`: `AE` is a processing **error** (the sender may resend later, e.g. a
- * transient downstream outage); `AR` is a **reject** (the sender should not resend the
- * message unchanged, e.g. it is structurally unacceptable). `@cosyte/mllp` builds
- * original-mode ACKs; the `C*` codes are surfaced in the type for completeness and for
- * callers that build their own enhanced-mode ACKs via `autoAck: fn`.
+ * A **public API**: consumers narrow on them in warning handlers, log pipelines and
+ * monitoring. Renaming or removing one is a breaking change. They are deliberately a
+ * family of their own rather than additions to the framing warning-code union, because
+ * that union is the decoder's registry and these are not decoder events.
  *
  * @example
  * ```typescript
- * import type { AckCode } from '@cosyte/mllp';
- * const code: AckCode = 'AE';
+ * import type { AckModeCode } from '@cosyte/mllp';
+ * const code: AckModeCode = 'MLLP_ACK_TWO_PHASE_UNAVAILABLE';
  * ```
  */
-type AckCode = "AA" | "AE" | "AR" | "CA" | "CE" | "CR";
+type AckModeCode = "MLLP_ACK_ACCEPT_TYPE_UNRECOGNISED" | "MLLP_ACK_APPLICATION_TYPE_UNRECOGNISED" | "MLLP_ACK_TWO_PHASE_UNAVAILABLE" | "MLLP_ACK_COMMIT_ALREADY_REPORTED" | "MLLP_ACK_MSA1_ABSENT" | "MLLP_ACK_MSA1_UNCLASSIFIABLE" | "MLLP_ACK_SEND_ALREADY_DISPOSED";
 /**
- * The negative original-mode acknowledgement codes a failed handler can produce.
+ * Look up the frozen diagnostic text for an acknowledgement-mode code.
  *
+ * A pure table read. It takes no value, so no caller can widen it into an interpolation
+ * site.
+ *
+ * @param code - The acknowledgement-mode code being reported.
+ * @returns The registered message for that code, byte-for-byte.
  * @example
  * ```typescript
- * import type { NegativeAckCode } from '@cosyte/mllp';
- * const code: NegativeAckCode = 'AR';
+ * const message = ackModeDiagnosticMessage('MLLP_ACK_MSA1_UNCLASSIFIABLE');
  * ```
  */
-type NegativeAckCode = "AE" | "AR";
+declare function ackModeDiagnosticMessage(code: AckModeCode): string;
+
 /**
- * Error a message handler throws to control the negative acknowledgement the server
- * returns. Throwing **any** error from a commit-gated handler yields `AE` by default;
- * throw an `MllpAckError` to choose `AR` (application reject) instead.
+ * MLLP Server, createServer(), createStarterServer(), and MllpServer class.
  *
- * The `message` is **never** copied into the ACK bytes or any emitted event, it may
- * carry PHI. Only the static, non-PHI `ackCode` influences the wire response.
+ * Provides the server-side MLLP transport: listen for inbound TCP connections,
+ * decode MLLP-framed messages, surface them as Buffer payloads, and support
+ * optional auto-ACK, keepalive, graceful shutdown, and AbortSignal cancellation.
  *
  * @example
  * ```typescript
- * import { createServer, MllpAckError } from '@cosyte/mllp';
+ * import { createServer } from '@cosyte/mllp';
  *
- * createServer({
- *   autoAck: 'AA',
- *   onMessage: async (payload) => {
- *     if (!isAcceptable(payload)) {
- *       // sender should NOT resend unchanged -> AR
- *       throw new MllpAckError('unsupported message type', { ackCode: 'AR' });
- *     }
- *     await db.commit(payload); // throw here -> AE (resend may succeed)
+ * const server = createServer({
+ *   onMessage: (payload, meta, conn) => {
+ *     console.log('received', payload.length, 'bytes from', meta.connectionId);
  *   },
  * });
+ * await server.listen(2575);
  * ```
+ *
+ * @packageDocumentation
  */
-declare class MllpAckError extends Error {
-    /** The negative acknowledgement code to return (`AE` or `AR`). */
-    readonly ackCode: NegativeAckCode;
-    /**
-     * @param message - Diagnostic text for the thrower. Never placed on the wire (may carry PHI).
-     * @param opts.ackCode - Negative code to return. Default `'AE'`.
-     * @param opts.cause - Underlying error, preserved on `.cause`.
-     */
-    constructor(message: string, opts?: {
-        ackCode?: NegativeAckCode;
-        cause?: unknown;
-    });
-}
+
 /**
- * Resolve the negative acknowledgement code for a handler failure.
+ * Metadata attached to each decoded MLLP message.
  *
- * An {@link MllpAckError} carries an explicit `ackCode`; any other thrown value maps to
- * `AE` (application error, the default, since most handler failures are transient and
- * a resend may succeed).
- *
- * @example
- * ```typescript
- * import { resolveNackCode, MllpAckError } from '@cosyte/mllp';
- * resolveNackCode(new Error('boom'));                          // 'AE'
- * resolveNackCode(new MllpAckError('nope', { ackCode: 'AR' })); // 'AR'
- * ```
- */
-declare function resolveNackCode(err: unknown): NegativeAckCode;
-/**
- * True iff a **positive** raw acknowledgement (`AA`/`CA`) cannot be safely correlated to
- * this payload, so {@link buildRawAck} (and the server's auto-ACK path) must **downgrade**
- * it to a non-positive `AE`/`CE` rather than tell the sender "I have it."
- *
- * The rule this enforces: **never answer `AA` for a message you could not correlate.** A
- * positive ACK is a promise the sender may forget the message; if it names a control ID
- * the sender cannot match, or names one of several messages it never read, the sender
- * times out and resends, committing a **duplicate clinical message** (or worse, believes a
- * destroyed message was delivered). Three payload-shaped reasons make a positive ACK
- * uncorrelatable, all peer-reachable off the wire:
- *
- *   1. **No readable `MSH`.** `readMshSegment` returns `null`, e.g. a `BOM`/`SP`/`TAB`
- *      before `MSH` (which shares the `MSH`'s segment line, so `MSH` heads no segment), or
- *      a bare fragment delivered after a mid-payload `VT` discard (`MLLP_TRAILING_BYTES`).
- *      MSA-2 would be empty: an ACK that correlates to nothing.
- *   2. **Empty MSH-10.** The `MSH` is readable but carries no message control ID, so there
- *      is nothing to echo, again `MSA|AA|` with an empty MSA-2.
- *   3. **A batch or concatenated messages.** An `FHS`/`BHS`/`BTS`/`FTS` envelope (§2.10.3)
- *      or a second `MSH` in the same frame: a single MSA-2 can echo only ONE control ID, so
- *      a positive ACK naming the first silently drops the rest (see
- *      {@link containsBatchOrExtraMessage}). Batch ACK is its own feature; until it is
- *      designed, a batch must stay a **loud non-positive** answer.
- *
- * This is a **refusal**, not a tolerance widening: it never makes an unreadable message
- * readable, never re-bases on a located `MSH`, never parses a batch. It only recognizes
- * the shapes for which a positive disposition would be a lie, so the builder can fall back
- * to `AE`. A **negative** requested code (`AE`/`AR`/`CE`/`CR`) is unaffected, it is
- * already non-positive, and echoing whatever control ID it can find is still useful.
- *
- * Pure, byte-level, never throws.
- *
- * @example
- * ```typescript
- * import { rawAckUncorrelatable } from '@cosyte/mllp';
- * rawAckUncorrelatable(oneGoodMessage); // false → AA is safe
- * rawAckUncorrelatable(twoConcatenatedMsh); // true → downgrade AA to AE
- * ```
- */
-declare function rawAckUncorrelatable(payload: Buffer): boolean;
-/**
- * Build a minimal original-mode HL7 v2 acknowledgement from raw inbound payload bytes,
- * **without a parser** (parser-driven ACKs are the `@cosyte/mllp/ack-from-hl7` subpath).
- *
- * Locates the `MSH` segment (the first `CR`/`LF`-delimited segment starting with `MSH`,
- * so a leading `CR` or an `FHS`/`BHS` batch header does not hide it), reads the field
- * separator from **MSH-1** and the encoding characters from **MSH-2**, then splits that
- * segment on that separator to read fields. The ACK swaps sender/receiver per HL7 ACK
- * rules, echoes the inbound MSH-10 into MSA-2 (§2.9.2.2), sets MSA-1 to `code`, and, for
- * negative codes, adds a **static, PHI-free** MSA-3 reason. A fresh control ID fills the
- * ACK's own MSH-10.
- *
- * ## Why the delimiters are read, not assumed
- *
- * MSH-1 **is** the field separator (HL7 v2.5.1 §2.5.4): the byte at offset 3 of the MSH
- * segment *defines* it for the whole message. `|` is overwhelmingly common but it is a
- * convention, not the spec. Assuming it was wrong in two compounding ways:
- *
- *   1. **Reading.** Splitting a `!`-delimited message on `|` yields ONE field, so every
- *      echoed field, including MSH-10, came back empty. The ACK went out as
- *      `MSA|AA|` with **no correlation id at all**: the sender cannot match it, times
- *      out, and resends → a duplicate clinical message. That is the exact failure this
- *      package's correlator exists to prevent, manufactured by the ACK builder itself.
- *   2. **Writing.** The echoed MSH-3..6 and MSH-10 field *content* is copied verbatim
- *      from the inbound, still escaped against the **inbound's** encoding characters. Re-
- *      emitting that content under a different delimiter set silently reinterprets it:
- *      an inbound whose component separator is `#` and whose MSH-10 is `ID#X` would be
- *      re-emitted under `^~\&` as the literal `ID#X`, which the sender then reads as a
- *      single component rather than two. Echoing MSH-1 and MSH-2 keeps the content and
- *      the delimiters that define it together.
- *
- * ## It reads the MSH through the SHARED scanner
- *
- * The MSH read is `readMshSegment` from `src/internal/control-id.ts`, the same call the
- * client's correlator makes to derive the key it will later match this ACK against. That
- * is deliberate and it is the whole point: this builder used to re-derive the read itself
- * (`payload.toString("latin1").split("\r")`, hunting for an `MSH` anywhere in the
- * payload), and the two disagreed on real inputs. On a **truncated MSH** followed by a
- * `PID` the correlator keyed on the PID's MRN while this builder echoed an empty MSA-2. On
- * a payload with a **leading `CR`**, which the MLLP decoder passes straight through, and
- * which real senders emit, this builder found the `MSH` and echoed MSH-10 correctly while
- * the correlator, requiring `MSH` at byte 0, gave up. Every such disagreement is an ACK the
- * sender cannot match → timeout → resend → **duplicate clinical message**.
- *
- * The fix is one scan, but note *which* scan. The first attempt made them agree by
- * requiring `MSH` at byte 0 everywhere, which "resolved" the leading-`CR` disagreement by
- * degrading the side that had been **right**: `buildRawAck` began emitting a positive `AA`
- * with an empty MSA-2, silently, for a message whose MSH-10 was plainly present. Agreement
- * is not the goal; agreeing on the *correct*, *tolerant* answer is. A lenient reader may
- * never drop data that is there (Postel's Law, CLAUDE.md).
- *
- * ## The fail-safe downgrade: never a positive `AA`/`CA` it cannot correlate
- *
- * A positive acknowledgement is a promise the sender may forget the message. If it names a
- * control ID the sender cannot match, or names one message out of several it never read,
- * the sender times out and resends, committing a **duplicate clinical message**. So a
- * requested positive code is **downgraded** to its non-positive counterpart (`AA`→`AE`,
- * `CA`→`CE`) whenever the payload cannot carry a correlatable positive ACK: no readable
- * `MSH`, an empty MSH-10, or a batch/concatenated-message shape that a single MSA-2 cannot
- * acknowledge. See {@link rawAckUncorrelatable} for the exact conditions and why each is a
- * refusal rather than a widened reader. A requested **negative** code (`AE`/`AR`/`CE`/`CR`)
- * is never touched. This mirrors the parser-backed `buildMllpAck`, which downgrades and
- * warns on an unparseable inbound, the two builders' fail-safe semantics now agree.
- *
- * **Never throws** and **never copies payload content** beyond the routing/control
- * metadata above, `readMshSegment` stops at the MSH's segment terminator, so no field of
- * any later segment (PID and friends) can be reached, let alone echoed. On a missing or
- * unreadable `MSH` it returns a minimal well-formed ACK carrying the (downgraded) `code` so
- * the caller can still respond.
- *
- * @param payload - Raw decoded HL7 v2 payload bytes (MLLP framing already stripped).
- * @param code - Requested MSA-1 acknowledgement code. A positive `AA`/`CA` is downgraded to
- *   `AE`/`CE` when the message cannot be correlated (see above).
- * @returns ACK payload bytes (no framing, the caller wraps with `encodeFrame`).
- *
- * @example
- * ```typescript
- * import { buildRawAck } from '@cosyte/mllp';
- * const ack = buildRawAck(inboundPayload, 'AE'); // MSA|AE|<inbound MSH-10>|message could not be processed
- * ```
- */
-declare function buildRawAck(payload: Buffer, code: AckCode): Buffer;
-
-/**
- * MLLP Server, createServer(), createStarterServer(), and MllpServer class.
- *
- * Provides the server-side MLLP transport: listen for inbound TCP connections,
- * decode MLLP-framed messages, surface them as Buffer payloads, and support
- * optional auto-ACK, keepalive, graceful shutdown, and AbortSignal cancellation.
- *
- * @example
- * ```typescript
- * import { createServer } from '@cosyte/mllp';
- *
- * const server = createServer({
- *   onMessage: (payload, meta, conn) => {
- *     console.log('received', payload.length, 'bytes from', meta.connectionId);
- *   },
- * });
- * await server.listen(2575);
- * ```
- *
- * @packageDocumentation
- */
-
-/**
- * Metadata attached to each decoded MLLP message.
- *
- * All fields are `readonly`, the object is `Object.freeze()`'d before emission.
+ * All fields are `readonly`, the object is `Object.freeze()`'d before emission.
  *
  * @example
  * ```typescript
@@ -1548,11 +1832,58 @@ type NackReason = "handler-rejected" | "uncorrelatable-inbound" | "discarded-byt
 interface NackEvent {
     /** Connection that produced the negative acknowledgement. */
     readonly connectionId: string;
-    /** The negative acknowledgement code sent to the peer (`AE` or `AR`). */
-    readonly ackCode: NegativeAckCode;
+    /**
+     * The negative acknowledgement code actually sent to the peer.
+     *
+     * `AE` or `AR` for a message acknowledged in the original mode, and the accept-mode
+     * counterparts `CE` or `CR` where the inbound MSH-15 asked for an accept acknowledgement
+     * for this disposition. It is always the code that went on the wire, so an observer
+     * counting negative acknowledgements sees what the peer saw.
+     */
+    readonly ackCode: NackAckCode;
     /** Why the negative acknowledgement was sent (PHI-free). */
     readonly reason: NackReason;
 }
+/**
+ * The negative acknowledgement codes a {@link NackEvent} can carry: both halves of the
+ * negative side of HL7 Table 0008.
+ *
+ * @example
+ * ```typescript
+ * import type { NackAckCode } from '@cosyte/mllp';
+ * const code: NackAckCode = 'CR';
+ * ```
+ */
+type NackAckCode = "AE" | "AR" | "CE" | "CR";
+/**
+ * Payload of the server `'ackModeWarning'` event: something about an inbound message's
+ * acknowledgement-mode request was read and reported, and the acknowledgement went out
+ * anyway.
+ *
+ * Emitted when MSH-15 carries a value outside HL7 Table 0155. The acknowledgement is **not**
+ * downgraded, negated or otherwise changed for that reason: reading a field is not
+ * validating it, and answering a message the handler committed with anything but a positive
+ * code would make a sender resend a message that is already stored.
+ *
+ * **PHI-safe by construction:** a connection ID, a stable code and a frozen registry
+ * message, never the payload and never the field's value. The object is `Object.freeze()`'d
+ * before emission.
+ *
+ * @example
+ * ```typescript
+ * server.on('ackModeWarning', ({ code }) => metrics.increment('mllp.ack_mode', { code }));
+ * ```
+ */
+interface AckModeWarningEvent {
+    /** Connection the inbound message arrived on. */
+    readonly connectionId: string;
+    /** The acknowledgement-mode code being reported. */
+    readonly code: AckModeCode;
+    /** Frozen registry text for `code`. Never interpolated. */
+    readonly message: string;
+    /** Wall-clock time at point of emission. */
+    readonly timestamp: Date;
+}
 /**
  * Observability snapshot returned by `server.getStats()`.
  *
@@ -1771,9 +2102,12 @@ interface StarterServerOptions extends ServerOptions {
  * during the bind window changes the `listen()` rejection from the bind error to the typed
  * close-during-listen `MllpConnectionError`, match on the `'error'` event payload, not the
  * rejection, if you do that.
- * TLS (MLLPS) adds two more: `'tlsClientError'` (a failed TLS handshake, the
- * server logs it and keeps serving other connections) and `'securityWarning'` (loud,
- * one-time notice when a wildcard host is bound via `allowWildcardBind: true`).
+ * TLS (MLLPS) adds three more: `'tlsClientError'` (a failed TLS handshake, the
+ * server logs it and keeps serving other connections), `'securityWarning'` (loud,
+ * one-time notice when a wildcard host is bound via `allowWildcardBind: true`), and
+ * `'tlsNegotiated'` ({@link NegotiatedTlsParameters}, the protocol version and cipher
+ * suite each accepted link actually negotiated, once per completed handshake and never
+ * on a plaintext listener).
  * All event payloads are `Object.freeze()`'d before emission.
  *
  * @example
@@ -1811,6 +2145,16 @@ declare class MllpServer extends EventEmitter {
     private _closedTotal;
     /** Count of `'tlsClientError'` events since listen(). */
     private _tlsClientErrorsTotal;
+    /**
+     * A TLS configuration this server will not serve on: an offered-suite list
+     * it cannot honour, or ephemeral Diffie-Hellman parameters it cannot use. Set
+     * at construction, and the ONLY thing `listen()` consults before it binds:
+     * such a server never binds, never accepts, and never negotiates anything,
+     * which is what makes "no fallback to the default list, and none to a server
+     * with no Diffie-Hellman parameters" a structural property rather than a
+     * promise. `null` when the configuration is fine.
+     */
+    private readonly _tlsConfigError;
     /**
      * Construct an MLLP server. Created idle; call `listen()` (or use
      * {@link createServer}/{@link createStarterServer}) to begin accepting connections.
@@ -1830,6 +2174,14 @@ declare class MllpServer extends EventEmitter {
      * binds raced each other's post-bind safety checks). Call `close()` before
      * re-listening; sequential `listen()` → `close()` → `listen()` is fine.
      *
+     * **A refused TLS configuration** (the runtime rejects the offered suite
+     * list, `tls.atnaTransportSecurity` and `tls.ciphers` both declare one, or
+     * `tls.dhParameters` are not usable) rejects every `listen()` on this server
+     * with a typed `MllpTlsConfigurationError`, checked before the bind. Such a
+     * server never listens, never negotiates on any other list and never runs
+     * without the Diffie-Hellman parameters it was given; construct a new one
+     * with a configuration that resolves.
+     *
      * **`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
@@ -1991,8 +2343,48 @@ declare class MllpServer extends EventEmitter {
      *     discard, never a neighbouring frame's trailing junk.
      *
      * `'discarded-bytes'` takes precedence in the reason when both hold, it is the root cause.
+     *
+     * `selectCode` puts the resolved disposition in the half of HL7 Table 0008 the inbound
+     * asked for; it is the identity for a message that asked for nothing.
      */
     private _resolveAutoAckPositive;
+    /**
+     * Build this message's acknowledgement-code selector: the function that puts a resolved
+     * disposition in the half of HL7 Table 0008 the inbound asked for.
+     *
+     * MSH-15 (accept acknowledgment type, HL7 Table 0155) says under which conditions the
+     * sender wants an **accept** acknowledgement, and it is a condition rather than a switch:
+     * `AL` always, `NE` never, `ER` on an error or reject only, `SU` on success only. So the
+     * request cannot be evaluated until the disposition is known, which is why this returns a
+     * function rather than a code. Where the answer is yes, the disposition is emitted as its
+     * accept-mode counterpart: `CA` where this server would answer `AA`, `CE` where it would
+     * answer `AE`, `CR` where it would answer `AR`.
+     *
+     * Exactly one acknowledgement still goes out per inbound message; nothing here sends a
+     * second one, and the later application acknowledgement of the two-part protocol remains
+     * the consumer's to send.
+     *
+     * Three inbound shapes leave the table entirely and keep this server's own answer:
+     *
+     *   * a header this server cannot scan for MSH-15: it behaves exactly as it would have,
+     *     adding no new failure and no new report;
+     *   * a **batch or concatenated** frame: it keeps its warned non-positive answer and
+     *     never selects an accept-mode code, whatever MSH-15 says. A single MSA-2 can echo one
+     *     control ID, and commit-accepting a batch nobody read is the same lie in the other
+     *     half of the table;
+     *   * an MSH-15 outside Table 0155: reported, and answered exactly as it would have been.
+     *     Downgrading a message the handler committed would make a discharged sender resend a
+     *     message already in storage.
+     */
+    private _ackModeSelector;
+    /**
+     * Emit the frozen `'ackModeWarning'` event.
+     *
+     * CONTAINED for the same reason every other emit on this path is: it is reached from a
+     * `void`-ed async acknowledgement task, and a throwing metrics tap must never be able to
+     * suppress the acknowledgement that follows it.
+     */
+    private _emitAckModeWarning;
     /**
      * 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
@@ -2054,68 +2446,359 @@ declare function createServer(opts?: ServerOptions): MllpServer;
 declare function createStarterServer(opts: StarterServerOptions): Promise<MllpServer>;
 
 /**
- * The frozen diagnostic registry for ACK correlation.
- *
- * Every message an ACK-correlation diagnostic can carry lives here as a
- * literal, and the lookup takes **only a code**. There is no value parameter
- * anywhere in this module, which is the whole point: a factory that cannot be
- * handed a value cannot interpolate one, regardless of what arrives on the
- * wire.
+ * Server-side MLLP acknowledgement construction and the **fail-safe commit contract**.
  *
- * ## What this replaces, and why the shape matters more than the wording
+ * This module owns the byte-level ACK builder used by {@link MllpServer}'s auto-ACK
+ * path, the HL7 Table 0008 acknowledgement-code union, and the error type a message
+ * handler throws to request a specific negative acknowledgement.
  *
- * The `correlateByControlId` path used to build its diagnostics by
- * interpolation, and both ends of it were consumer-controlled and unbounded.
- * The unmatched-ACK error read the **peer's** MSA-2 straight out of an inbound
- * frame and put it on an `Error.message`; measured against a peer sending a
- * one-megabyte MSA-2, that produced a 1,000,026-byte `message` and an
- * equally large field on the frozen error payload. The late-ACK warning did
- * the same with the control id of the send being reported on. Both go to a
- * log, and in this domain a log is a place a patient identifier must not
- * reach. That is not a hypothetical about control ids either: this package has
- * already shipped one scanner that ran past a segment terminator and returned
- * PID-3, a patient's medical record number, as the "control ID" of a truncated
- * MSH. Withholding the bytes is the defence that survives the next such bug.
+ * ## Why this is safety-critical
  *
- * ## What a correlation diagnostic says instead
+ * A positive acknowledgement (`AA`) tells the sender "you may forget this message, I
+ * have it." If a server emits `AA` *before* the message is durably handled and then the
+ * process crashes, the message is **silently lost** with no record on either side. For
+ * clinical messages (an admit, an order, a result) that is a patient-safety failure.
  *
- * That a control id did not match, plus **numbers**: a byte length, a stream
- * offset, an elapsed time. A number is a shape, not content. A truncated id is
- * not an acceptable middle ground, and neither is a hex or base64 rendering:
- * both still grow the diagnostic with the input and both still disclose the
- * bytes. Nothing is lost by withholding them, because the caller already holds
- * them: the outbound payload is the caller's own argument to `send()`, and the
- * inbound frame is on the `'message'` event.
+ * The contract this module enforces: a positive ACK (`AA`) is only built once the
+ * application handler has resolved success. A handler that throws or rejects yields a
+ * **negative** ACK (`AE` by default, `AR` when the handler asks for it), never `AA`.
  *
- * Mirrors the same answer this package already reached for the ACK adapter's
- * verbatim-echo warning, which reports byte lengths and withholds MSH-10 and
- * MSA-2 themselves.
+ * Spec: HL7 v2.5.1 ch. 2 §2.9.2 (original acknowledgement mode), §2.9.3 (enhanced
+ * accept/application acknowledgement), Table 0008 (Acknowledgment Code), §2.9.2.2
+ * (MSA-2 echoes the inbound MSH-10 message control ID).
  *
  * @packageDocumentation
  */
 /**
- * The two warning codes emitted by ACK correlation rather than by framing.
+ * HL7 Table 0008, Acknowledgment Code. A **stable public API**.
  *
- * A subset of the framing `WarningCode` union; named separately so the
- * registry below is exhaustive over exactly the codes it owns and a new
- * correlation code cannot be added without a message for it.
- */
-type AckCorrelationCode = "MLLP_ACK_UNMATCHED_CONTROL_ID" | "MLLP_ACK_AFTER_TIMEOUT";
-/**
- * Look up the frozen diagnostic text for an ACK-correlation code.
+ * Two families, by mode (HL7 v2.5.1 §2.9):
  *
- * A pure table read. It takes no value, so no caller can widen it into an
- * interpolation site.
+ * - **Original mode (§2.9.2):** `AA` accept, `AE` application error, `AR` application
+ *   reject. The single ACK reports application-level outcome.
+ * - **Enhanced mode (§2.9.3):** `CA` commit accept, `CE` commit error, `CR` commit
+ *   reject, the *accept* acknowledgement, distinct from a later application ACK.
  *
- * @param code - The correlation code being reported.
- * @returns The registered message for that code, byte-for-byte.
- * @example
- * ```typescript
+ * `AE` vs `AR`: `AE` is a processing **error** (the sender may resend later, e.g. a
+ * transient downstream outage); `AR` is a **reject** (the sender should not resend the
+ * message unchanged, e.g. it is structurally unacceptable). `@cosyte/mllp` builds
+ * original-mode ACKs; the `C*` codes are surfaced in the type for completeness and for
+ * callers that build their own enhanced-mode ACKs via `autoAck: fn`.
+ *
+ * @example
+ * ```typescript
+ * import type { AckCode } from '@cosyte/mllp';
+ * const code: AckCode = 'AE';
+ * ```
+ */
+type AckCode = "AA" | "AE" | "AR" | "CA" | "CE" | "CR";
+/**
+ * The negative original-mode acknowledgement codes a failed handler can produce.
+ *
+ * @example
+ * ```typescript
+ * import type { NegativeAckCode } from '@cosyte/mllp';
+ * const code: NegativeAckCode = 'AR';
+ * ```
+ */
+type NegativeAckCode = "AE" | "AR";
+/**
+ * Error a message handler throws to control the negative acknowledgement the server
+ * returns. Throwing **any** error from a commit-gated handler yields `AE` by default;
+ * throw an `MllpAckError` to choose `AR` (application reject) instead.
+ *
+ * The `message` is **never** copied into the ACK bytes or any emitted event, it may
+ * carry PHI. Only the static, non-PHI `ackCode` influences the wire response.
+ *
+ * @example
+ * ```typescript
+ * import { createServer, MllpAckError } from '@cosyte/mllp';
+ *
+ * createServer({
+ *   autoAck: 'AA',
+ *   onMessage: async (payload) => {
+ *     if (!isAcceptable(payload)) {
+ *       // sender should NOT resend unchanged -> AR
+ *       throw new MllpAckError('unsupported message type', { ackCode: 'AR' });
+ *     }
+ *     await db.commit(payload); // throw here -> AE (resend may succeed)
+ *   },
+ * });
+ * ```
+ */
+declare class MllpAckError extends Error {
+    /** The negative acknowledgement code to return (`AE` or `AR`). */
+    readonly ackCode: NegativeAckCode;
+    /**
+     * @param message - Diagnostic text for the thrower. Never placed on the wire (may carry PHI).
+     * @param opts.ackCode - Negative code to return. Default `'AE'`.
+     * @param opts.cause - Underlying error, preserved on `.cause`.
+     */
+    constructor(message: string, opts?: {
+        ackCode?: NegativeAckCode;
+        cause?: unknown;
+    });
+}
+/**
+ * Resolve the negative acknowledgement code for a handler failure.
+ *
+ * An {@link MllpAckError} carries an explicit `ackCode`; any other thrown value maps to
+ * `AE` (application error, the default, since most handler failures are transient and
+ * a resend may succeed).
+ *
+ * @example
+ * ```typescript
+ * import { resolveNackCode, MllpAckError } from '@cosyte/mllp';
+ * resolveNackCode(new Error('boom'));                          // 'AE'
+ * resolveNackCode(new MllpAckError('nope', { ackCode: 'AR' })); // 'AR'
+ * ```
+ */
+declare function resolveNackCode(err: unknown): NegativeAckCode;
+/**
+ * True iff a **positive** raw acknowledgement (`AA`/`CA`) cannot be safely correlated to
+ * this payload, so {@link buildRawAck} (and the server's auto-ACK path) must **downgrade**
+ * it to a non-positive `AE`/`CE` rather than tell the sender "I have it."
+ *
+ * The rule this enforces: **never answer `AA` for a message you could not correlate.** A
+ * positive ACK is a promise the sender may forget the message; if it names a control ID
+ * the sender cannot match, or names one of several messages it never read, the sender
+ * times out and resends, committing a **duplicate clinical message** (or worse, believes a
+ * destroyed message was delivered). Three payload-shaped reasons make a positive ACK
+ * uncorrelatable, all peer-reachable off the wire:
+ *
+ *   1. **No readable `MSH`.** `readMshSegment` returns `null`, e.g. a `BOM`/`SP`/`TAB`
+ *      before `MSH` (which shares the `MSH`'s segment line, so `MSH` heads no segment), or
+ *      a bare fragment delivered after a mid-payload `VT` discard (`MLLP_TRAILING_BYTES`).
+ *      MSA-2 would be empty: an ACK that correlates to nothing.
+ *   2. **Empty MSH-10.** The `MSH` is readable but carries no message control ID, so there
+ *      is nothing to echo, again `MSA|AA|` with an empty MSA-2.
+ *   3. **A batch or concatenated messages.** An `FHS`/`BHS`/`BTS`/`FTS` envelope (§2.10.3)
+ *      or a second `MSH` in the same frame: a single MSA-2 can echo only ONE control ID, so
+ *      a positive ACK naming the first silently drops the rest (see
+ *      {@link containsBatchOrExtraMessage}). Batch ACK is its own feature; until it is
+ *      designed, a batch must stay a **loud non-positive** answer.
+ *
+ * This is a **refusal**, not a tolerance widening: it never makes an unreadable message
+ * readable, never re-bases on a located `MSH`, never parses a batch. It only recognizes
+ * the shapes for which a positive disposition would be a lie, so the builder can fall back
+ * to `AE`. A **negative** requested code (`AE`/`AR`/`CE`/`CR`) is unaffected, it is
+ * already non-positive, and echoing whatever control ID it can find is still useful.
+ *
+ * Pure, byte-level, never throws.
+ *
+ * @example
+ * ```typescript
+ * import { rawAckUncorrelatable } from '@cosyte/mllp';
+ * rawAckUncorrelatable(oneGoodMessage); // false → AA is safe
+ * rawAckUncorrelatable(twoConcatenatedMsh); // true → downgrade AA to AE
+ * ```
+ */
+declare function rawAckUncorrelatable(payload: Buffer): boolean;
+/**
+ * Build a minimal original-mode HL7 v2 acknowledgement from raw inbound payload bytes,
+ * **without a parser** (parser-driven ACKs are the `@cosyte/mllp/ack-from-hl7` subpath).
+ *
+ * Locates the `MSH` segment (the first `CR`/`LF`-delimited segment starting with `MSH`,
+ * so a leading `CR` or an `FHS`/`BHS` batch header does not hide it), reads the field
+ * separator from **MSH-1** and the encoding characters from **MSH-2**, then splits that
+ * segment on that separator to read fields. The ACK swaps sender/receiver per HL7 ACK
+ * rules, echoes the inbound MSH-10 into MSA-2 (§2.9.2.2), sets MSA-1 to `code`, and, for
+ * negative codes, adds a **static, PHI-free** MSA-3 reason. A fresh control ID fills the
+ * ACK's own MSH-10.
+ *
+ * ## Why the delimiters are read, not assumed
+ *
+ * MSH-1 **is** the field separator (HL7 v2.5.1 §2.5.4): the byte at offset 3 of the MSH
+ * segment *defines* it for the whole message. `|` is overwhelmingly common but it is a
+ * convention, not the spec. Assuming it was wrong in two compounding ways:
+ *
+ *   1. **Reading.** Splitting a `!`-delimited message on `|` yields ONE field, so every
+ *      echoed field, including MSH-10, came back empty. The ACK went out as
+ *      `MSA|AA|` with **no correlation id at all**: the sender cannot match it, times
+ *      out, and resends → a duplicate clinical message. That is the exact failure this
+ *      package's correlator exists to prevent, manufactured by the ACK builder itself.
+ *   2. **Writing.** The echoed MSH-3..6 and MSH-10 field *content* is copied verbatim
+ *      from the inbound, still escaped against the **inbound's** encoding characters. Re-
+ *      emitting that content under a different delimiter set silently reinterprets it:
+ *      an inbound whose component separator is `#` and whose MSH-10 is `ID#X` would be
+ *      re-emitted under `^~\&` as the literal `ID#X`, which the sender then reads as a
+ *      single component rather than two. Echoing MSH-1 and MSH-2 keeps the content and
+ *      the delimiters that define it together.
+ *
+ * ## It reads the MSH through the SHARED scanner
+ *
+ * The MSH read is `readMshSegment` from `src/internal/control-id.ts`, the same call the
+ * client's correlator makes to derive the key it will later match this ACK against. That
+ * is deliberate and it is the whole point: this builder used to re-derive the read itself
+ * (`payload.toString("latin1").split("\r")`, hunting for an `MSH` anywhere in the
+ * payload), and the two disagreed on real inputs. On a **truncated MSH** followed by a
+ * `PID` the correlator keyed on the PID's MRN while this builder echoed an empty MSA-2. On
+ * a payload with a **leading `CR`**, which the MLLP decoder passes straight through, and
+ * which real senders emit, this builder found the `MSH` and echoed MSH-10 correctly while
+ * the correlator, requiring `MSH` at byte 0, gave up. Every such disagreement is an ACK the
+ * sender cannot match → timeout → resend → **duplicate clinical message**.
+ *
+ * The fix is one scan, but note *which* scan. The first attempt made them agree by
+ * requiring `MSH` at byte 0 everywhere, which "resolved" the leading-`CR` disagreement by
+ * degrading the side that had been **right**: `buildRawAck` began emitting a positive `AA`
+ * with an empty MSA-2, silently, for a message whose MSH-10 was plainly present. Agreement
+ * is not the goal; agreeing on the *correct*, *tolerant* answer is. A lenient reader may
+ * never drop data that is there (Postel's Law, CLAUDE.md).
+ *
+ * ## The fail-safe downgrade: never a positive `AA`/`CA` it cannot correlate
+ *
+ * A positive acknowledgement is a promise the sender may forget the message. If it names a
+ * control ID the sender cannot match, or names one message out of several it never read,
+ * the sender times out and resends, committing a **duplicate clinical message**. So a
+ * requested positive code is **downgraded** to its non-positive counterpart (`AA`→`AE`,
+ * `CA`→`CE`) whenever the payload cannot carry a correlatable positive ACK: no readable
+ * `MSH`, an empty MSH-10, or a batch/concatenated-message shape that a single MSA-2 cannot
+ * acknowledge. See {@link rawAckUncorrelatable} for the exact conditions and why each is a
+ * refusal rather than a widened reader. A requested **negative** code (`AE`/`AR`/`CE`/`CR`)
+ * is never touched. This mirrors the parser-backed `buildMllpAck`, which downgrades and
+ * warns on an unparseable inbound, the two builders' fail-safe semantics now agree.
+ *
+ * **Never throws** and **never copies payload content** beyond the routing/control
+ * metadata above, `readMshSegment` stops at the MSH's segment terminator, so no field of
+ * any later segment (PID and friends) can be reached, let alone echoed. On a missing or
+ * unreadable `MSH` it returns a minimal well-formed ACK carrying the (downgraded) `code` so
+ * the caller can still respond.
+ *
+ * @param payload - Raw decoded HL7 v2 payload bytes (MLLP framing already stripped).
+ * @param code - Requested MSA-1 acknowledgement code. A positive `AA`/`CA` is downgraded to
+ *   `AE`/`CE` when the message cannot be correlated (see above).
+ * @returns ACK payload bytes (no framing, the caller wraps with `encodeFrame`).
+ *
+ * @example
+ * ```typescript
+ * import { buildRawAck } from '@cosyte/mllp';
+ * const ack = buildRawAck(inboundPayload, 'AE'); // MSA|AE|<inbound MSH-10>|message could not be processed
+ * ```
+ */
+declare function buildRawAck(payload: Buffer, code: AckCode): Buffer;
+
+/**
+ * The frozen diagnostic registry for ACK correlation.
+ *
+ * Every message an ACK-correlation diagnostic can carry lives here as a
+ * literal, and the lookup takes **only a code**. There is no value parameter
+ * anywhere in this module, which is the whole point: a factory that cannot be
+ * handed a value cannot interpolate one, regardless of what arrives on the
+ * wire.
+ *
+ * ## What this replaces, and why the shape matters more than the wording
+ *
+ * The `correlateByControlId` path used to build its diagnostics by
+ * interpolation, and both ends of it were consumer-controlled and unbounded.
+ * The unmatched-ACK error read the **peer's** MSA-2 straight out of an inbound
+ * frame and put it on an `Error.message`; measured against a peer sending a
+ * one-megabyte MSA-2, that produced a 1,000,026-byte `message` and an
+ * equally large field on the frozen error payload. The late-ACK warning did
+ * the same with the control id of the send being reported on. Both go to a
+ * log, and in this domain a log is a place a patient identifier must not
+ * reach. That is not a hypothetical about control ids either: this package has
+ * already shipped one scanner that ran past a segment terminator and returned
+ * PID-3, a patient's medical record number, as the "control ID" of a truncated
+ * MSH. Withholding the bytes is the defence that survives the next such bug.
+ *
+ * ## What a correlation diagnostic says instead
+ *
+ * That a control id did not match, plus **numbers**: a byte length, a stream
+ * offset, an elapsed time. A number is a shape, not content. A truncated id is
+ * not an acceptable middle ground, and neither is a hex or base64 rendering:
+ * both still grow the diagnostic with the input and both still disclose the
+ * bytes. Nothing is lost by withholding them, because the caller already holds
+ * them: the outbound payload is the caller's own argument to `send()`, and the
+ * inbound frame is on the `'message'` event.
+ *
+ * Mirrors the same answer this package already reached for the ACK adapter's
+ * verbatim-echo warning, which reports byte lengths and withholds MSH-10 and
+ * MSA-2 themselves.
+ *
+ * @packageDocumentation
+ */
+/**
+ * The two warning codes emitted by ACK correlation rather than by framing.
+ *
+ * A subset of the framing `WarningCode` union; named separately so the
+ * registry below is exhaustive over exactly the codes it owns and a new
+ * correlation code cannot be added without a message for it.
+ */
+type AckCorrelationCode = "MLLP_ACK_UNMATCHED_CONTROL_ID" | "MLLP_ACK_AFTER_TIMEOUT";
+/**
+ * Look up the frozen diagnostic text for an ACK-correlation code.
+ *
+ * A pure table read. It takes no value, so no caller can widen it into an
+ * interpolation site.
+ *
+ * @param code - The correlation code being reported.
+ * @returns The registered message for that code, byte-for-byte.
+ * @example
+ * ```typescript
  * const message = ackDiagnosticMessage('MLLP_ACK_AFTER_TIMEOUT');
  * ```
  */
 declare function ackDiagnosticMessage(code: AckCorrelationCode): string;
 
+/**
+ * Parser-free reads of the three acknowledgement-mode fields: MSH-15 and MSH-16 on the way
+ * out, MSA-1 on the way in.
+ *
+ * HL7 v2.5.1 §2.9 splits acknowledgement into two protocols. In the **original** protocol
+ * one message draws one acknowledgement. In the **enhanced** protocol it draws two: an
+ * *accept* acknowledgement carrying `CA`/`CE`/`CR` ("I have committed these bytes to safe
+ * storage; you may stop resending"), and a later *application* acknowledgement carrying
+ * `AA`/`AE`/`AR` ("here is what my application did with it"). A message asks for the
+ * enhanced protocol through MSH-15 and MSH-16, and §2.9 states the equivalence that makes
+ * the two one contract rather than two: the original protocol is the enhanced protocol
+ * with MSH-15 = `NE` and MSH-16 = `AL`.
+ *
+ * This module reads those fields the way the rest of this package reads MSH-10: byte-level,
+ * off the shared MSH scan, never through a parser. **Reading a field is not validating
+ * one.** Nothing here refuses, delays or alters a message because of the value of a field;
+ * an unrecognised value reads as its default and is reported, which is the only behaviour
+ * compatible with a transport that does not own HL7 content.
+ *
+ * Two code systems are involved and neither is interpreted beyond membership:
+ *
+ *   * **Table 0008** (MSA-1, acknowledgment code), six codes in two halves:
+ *     accept-mode `CA`/`CE`/`CR`, application-mode `AA`/`AE`/`AR`.
+ *   * **Table 0155** (MSH-15, MSH-16, accept/application acknowledgment conditions), four
+ *     codes: `AL` always, `NE` never, `ER` error or reject conditions only, `SU`
+ *     successful completion only.
+ *
+ * **INTERNAL**, not part of the public API.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Per-send report that the peer has **committed** a message but has not yet said what its
+ * application did with it, handed to the `onCommitAck` callback of the `send()` that drew
+ * it.
+ *
+ * It is scoped to one caller's own send, and it arrives at a point where that send has not
+ * settled: `send()` is still pending and will resolve on the application acknowledgement,
+ * or reject if none arrives. That scoping is the point. The commit disposition belongs to
+ * one send, and a caller learns which send it belongs to by being the one that made it,
+ * never by anything being logged.
+ *
+ * @example
+ * ```typescript
+ * const ack = await client.send(payload, {
+ *   onCommitAck: ({ code }) => logger.info({ commit: code }), // 'CA': the peer has custody
+ * });
+ * ```
+ */
+interface CommitAckReport {
+    /** The accept-mode Table 0008 code received. Always the positive `CA`. */
+    readonly code: "CA";
+    /** The accept acknowledgement's own payload bytes, framing stripped. */
+    readonly payload: Buffer;
+    /** Milliseconds between the send's write-flush and this acknowledgement. */
+    readonly latencyMs: number;
+}
+
 /**
  * MLLP Client, `createClient()` factory and `MllpClient` class.
  *
@@ -2171,6 +2854,52 @@ interface AckCorrelationWarning extends MllpWarning {
      */
     readonly elapsedSinceSendMs: number;
 }
+/**
+ * The `'warning'` payload the client emits for an **acknowledgement-mode** deviation: an
+ * enhanced-mode send on a client that cannot correlate two acknowledgements, a Table 0155
+ * value it did not recognise, an acknowledgement it could not classify into a mode, and a
+ * further acknowledgement for a send that is already settled or failed.
+ *
+ * It arrives on the same `'warning'` event as a framing warning and an
+ * {@link AckCorrelationWarning}, so narrow on `code` before reading its fields. It is
+ * **not** an `MllpWarning`: its `code` is an {@link AckModeCode}, deliberately a family of
+ * its own rather than an addition to the decoder's registry, and it is not counted in
+ * `getStats().warningsByCode`, whose keys are the decoder's codes.
+ *
+ * Everything input-derived on it is a number or a member of the closed six-code Table 0008
+ * set. `message` is a **frozen registry entry**, byte-for-byte identical for a given code
+ * no matter what arrived on the wire. A warning is a log line, so it carries no field
+ * content: an MSA-1 nobody could classify is reported by its byte length alone.
+ *
+ * @example
+ * ```typescript
+ * client.on('warning', (w: AckModeWarning) => {
+ *   if (w.code === 'MLLP_ACK_MSA1_UNCLASSIFIABLE') {
+ *     logger.warn({ code: w.code, msa1Bytes: w.msa1Bytes, at: w.byteOffset });
+ *   }
+ * });
+ * ```
+ */
+interface AckModeWarning {
+    /** The acknowledgement-mode code this warning reports. */
+    readonly code: AckModeCode;
+    /** Frozen registry text for `code`. Never interpolated. */
+    readonly message: string;
+    /** Inbound frame's stream byte offset; `0` for a warning raised on an outbound send. */
+    readonly byteOffset: number;
+    /** Byte length of the MSA-1 field involved, or `null` when the code reports none. */
+    readonly msa1Bytes: number | null;
+    /** Table 0008 code involved, or `null` when the code reports none. */
+    readonly ackCode: "AA" | "AE" | "AR" | "CA" | "CE" | "CR" | null;
+    /** Byte length of the control ID involved, or `null` when there was none to read. */
+    readonly controlIdBytes: number | null;
+    /** Milliseconds since the send's write-flush, or since its disposal for a late ACK. */
+    readonly elapsedSinceSendMs: number;
+    /** Connection identifier, `undefined` before a connection is attached. */
+    readonly connectionId: string | undefined;
+    /** Wall-clock time at point of emission. */
+    readonly timestamp: Date;
+}
 /**
  * Context passed to a custom `retryStrategy` hook on each reconnect attempt.
  *
@@ -2244,7 +2973,11 @@ interface ClientOptions {
     readonly port: number;
     /** FrameReader tolerance / size options. `onFrame` and `onWarning` are managed internally. */
     readonly framing?: Omit<FrameReaderOptions, "onFrame" | "onWarning">;
-    /** Drain timeout for {@link MllpClient.close} (default: `30_000` ms). */
+    /**
+     * Bound on the acknowledgement wait {@link MllpClient.close} performs (default: `30_000`
+     * ms). Sends already written to the transport are awaited until it elapses; the wait ends
+     * early the moment the last of them is answered.
+     */
     readonly drainTimeoutMs?: number;
     /**
      * Per-message ACK timeout in milliseconds. The clock starts at
@@ -2252,6 +2985,20 @@ interface ClientOptions {
      * pre-flush queue time is not charged to the peer. Default: `30_000`.
      */
     readonly ackTimeoutMs?: number;
+    /**
+     * Bound, in milliseconds, on the **second** wait an enhanced-mode send can enter: the
+     * one that starts when an accept acknowledgement (`CA`) reports that the peer has
+     * committed the message, and ends when the application acknowledgement arrives.
+     *
+     * Measured from the moment that accept acknowledgement was received, not from the send,
+     * so a peer that commits at 9 s and applies at 12 s settles the send successfully at
+     * 12 s. Defaults to whatever `ackTimeoutMs` is in force for the send, and can be
+     * overridden per send. It only ever applies to a send whose MSH-16 asks for an
+     * application acknowledgement, so it changes nothing for an original-mode interface.
+     *
+     * @default the send's own `ackTimeoutMs`
+     */
+    readonly applicationAckTimeoutMs?: number;
     /**
      * If `true`, ACKs are matched against outgoing sends by MSH-10 → MSA-2.
      * Default `false` (FIFO mode).
@@ -2430,6 +3177,9 @@ interface ClientStats {
  * - `'securityWarning'`, `SecurityWarning`. Emitted on every successful
  *   `secureConnect` (initial + every reconnect) when `tls.allowUnverified` is `true`
  *   with code `MLLP_TLS_VERIFY_DISABLED`. Also mirrored to `process.emitWarning`.
+ * - `'tlsNegotiated'`, {@link NegotiatedTlsParameters}. Emitted once per completed TLS
+ *   handshake (initial + every reconnect) with the negotiated protocol version and
+ *   cipher suite. Never emitted on a plaintext connection.
  * - `'error'`, re-emitted from Connection. Guarded by `listenerCount('error') > 0` so
  *   absence of a listener does NOT crash the process (server precedent).
  *
@@ -2454,6 +3204,11 @@ declare class MllpClient extends EventEmitter {
     private _state;
     /** Per-message ACK timeout in ms. Resolved at construction. */
     private readonly _ackTimeoutMs;
+    /**
+     * Default bound on the second (application-acknowledgement) wait, in ms.
+     * `undefined` means "whatever ACK timeout is in force for that send".
+     */
+    private readonly _applicationAckTimeoutMs;
     /** controlId-mode flag. `false` → FIFO. */
     private readonly _correlateByControlId;
     /** Unified ACK correlator. Built during `_attachConnection`. */
@@ -2502,6 +3257,26 @@ declare class MllpClient extends EventEmitter {
     private _connectSignal;
     /** Set when close()/destroy()/abort fires; reconnect handler short-circuits. */
     private _userClosed;
+    /**
+     * Sends parked inside the client with nothing written for them. See {@link ParkedSend}.
+     * Every entry removes itself the moment its own wait ends, however it ends.
+     */
+    private readonly _parkedSends;
+    /**
+     * Re-checks whether the shutdown drain is over, `null` when no `close()` is waiting.
+     * Called from every point at which a pending send is settled.
+     */
+    private _drainWaiter;
+    /**
+     * Ends the shutdown drain wait now, whatever is still outstanding. `null` when no `close()`
+     * is waiting. `destroy()` calls it, which is what makes a destroy during a drain prompt.
+     */
+    private _endDrainWait;
+    /**
+     * The `beforeClose` hook this client installed on its Connection, so a second `close()` call
+     * composes nothing twice. Compared by identity, never by shape.
+     */
+    private _drainHook;
     /** Captured Connection error feeding `RetryContext.lastError`. */
     private _lastError;
     /** Listener-removal handle for the abort listener bound in connect(). */
@@ -2556,6 +3331,10 @@ declare class MllpClient extends EventEmitter {
      *   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.
+     * - `MllpTlsConfigurationError` if the configured cipher-suite list cannot be
+     *   honoured (the runtime rejects it, or `atnaTransportSecurity` and `ciphers`
+     *   both declare one). Raised **before** a socket is opened, so nothing is left
+     *   connected; identify it by `instanceof` plus its stable `code`.
      *
      * **Dual failure signal on initial connect:** the Connection's transport
      * error handler is attached before this promise's own error listener, so a
@@ -2619,6 +3398,30 @@ declare class MllpClient extends EventEmitter {
      * See `src/internal/safe-emit.ts`. The throw is re-surfaced on `'error'`.
      */
     private _emitContained;
+    /**
+     * Emit a frozen {@link AckModeWarning} on the `'warning'` event.
+     *
+     * The message is a **registry lookup**, not an interpolation, and everything
+     * input-derived on the payload is a number or a closed-set code. This holds in every
+     * mode: an original-mode send emits nothing new, but when it does reach one of these
+     * codes the same discipline applies.
+     */
+    private _emitAckModeWarning;
+    /**
+     * Build the typed error for a send that was left waiting on its application
+     * acknowledgement: the peer committed the message and then either fell silent past the
+     * second window or lost the link.
+     */
+    private _applicationAckError;
+    /**
+     * Fail every pending send that is waiting on its application acknowledgement, with an
+     * error naming the commit disposition already received. Used on the paths where the link
+     * goes away: such a send must not be held for a resend (the peer already has the
+     * message), nor left pending, nor reported as successful.
+     *
+     * Returns the entries it removed. Sends without a reported commit are untouched.
+     */
+    private _failCommitPendingSends;
     /**
      * Emit the per-connection insecure-TLS warning when
      * `tls.allowUnverified === true`, fires on EVERY successful
@@ -2627,6 +3430,17 @@ declare class MllpClient extends EventEmitter {
      * connections or when verification is on.
      */
     private _emitInsecureWarningIfNeeded;
+    /**
+     * Emit the frozen negotiated-parameters record for a completed TLS
+     * handshake, once per connection, initial connect and every reconnect
+     * alike. No-op for a plaintext connection: there is nothing negotiated to
+     * report, so no event is emitted at all.
+     *
+     * The payload is read off the TLS session, so it is a pair of registry names
+     * plus this client's own host and port. It never sees a payload byte: it is
+     * built at handshake-completion time, before any HL7 byte crosses the link.
+     */
+    private _emitNegotiatedTlsParameters;
     /**
      * Wire a Connection's events through to this MllpClient. Every re-emitted
      * payload is `Object.freeze`'d before emission, even though the
@@ -2761,6 +3575,21 @@ declare class MllpClient extends EventEmitter {
      *
      * Emits a frozen `'ack'` event on every successful match.
      *
+     * ## Enhanced acknowledgement mode
+     *
+     * A message whose MSH-15 or MSH-16 is not null asks for the two-part protocol of HL7
+     * v2.5.1 §2.9, and on a client correlating by control ID this method delivers it: the
+     * accept acknowledgement (`CA`) is reported through `onCommitAck` **without** settling
+     * the send, and the later application acknowledgement (`AA`/`AE`/`AR`) is what resolves
+     * it. All three application-mode codes resolve, because which of them the receiving
+     * application chose is its clinical verdict and not this transport's to judge; read MSA-1
+     * off the acknowledgement you are handed. A negative commit (`CE`/`CR`) rejects with
+     * {@link MllpCommitRejectedError} at once, since no application acknowledgement follows a
+     * refusal to take custody.
+     *
+     * A message with both fields empty is an original-mode send and behaves exactly as it
+     * always has, one acknowledgement, settled by the first match.
+     *
      * @example
      * ```typescript
      * const ack = await client.send(payloadBuffer);
@@ -2769,27 +3598,160 @@ declare class MllpClient extends EventEmitter {
      *
      * @param payload Raw bytes; MLLP framing is added internally via `encodeFrame`.
      * @param opts.signal AbortSignal, aborting cancels the ACK wait.
+     * @param opts.ackTimeoutMs Per-send override of the backpressure wait budget.
+     * @param opts.applicationAckTimeoutMs Per-send override of the second wait's bound.
+     * @param opts.onCommitAck Called with the commit disposition when the peer commits the
+     *   message ahead of its application acknowledgement. See {@link CommitAckReport}.
      */
     send(payload: Buffer, opts?: {
         signal?: AbortSignal;
         ackTimeoutMs?: number;
+        applicationAckTimeoutMs?: number;
+        onCommitAck?: (report: CommitAckReport) => void;
     }): Promise<Buffer>;
+    /**
+     * Decide what a send's own MSH-15 and MSH-16 buy it, and report anything worth reporting
+     * about them. Runs before the message reaches the transport.
+     *
+     * Three answers:
+     *
+     *   * an **original-mode** message (both fields null, or a header this package cannot
+     *     scan) gets `null`, which is the state every send had before enhanced mode existed;
+     *   * an **enhanced-mode** message on a client that correlates in order rather than by
+     *     control ID also gets `null`, plus a warning saying so. MSA-2 is the only thing that
+     *     can attribute a second acknowledgement to a send, so without control-ID correlation
+     *     a two-acknowledgement conversation cannot be delivered. The alternative, leaving
+     *     such a send pending on an acknowledgement this client would otherwise have settled
+     *     it with, would break a working interface to signal a configuration gap;
+     *   * an **enhanced-mode** message on a control-ID client gets its two-phase state.
+     *
+     * An unrecognised Table 0155 value is warned and defaulted, never fatal: this is a
+     * transport, and refusing to transmit a clinical message over a vendor value in MSH-15
+     * would be HL7 content validation with the worst failure mode available. The message goes
+     * out unaltered either way.
+     */
+    private _twoPhaseStateFor;
     /**
      * 'wait'-mode backpressure handler.
      *
-     * Awaits one of three terminating signals, in order:
+     * Awaits one of four 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`. Cleanup
      *   removes the drain listener AND the abort listener AND clears the
      *   timer to prevent leaks.
+     * - the client shuts down → reject with `MllpNeverDeliveredError`, because a send waiting
+     *   here has written nothing and the peer cannot have seen it. Registering the wait as a
+     *   {@link ParkedSend} is what makes that reachable at all.
+     *
+     * @param held - What this send would have written, for the never-delivered report. Counts
+     *   only: the caller still holds the payload it passed to `send()`.
      */
     private _waitThenSend;
     /**
      * Tear down per-connection state (sweep timer + correlator) when the
      * client is closing or destroying. Safe to call multiple times.
+     *
+     * A send that is waiting on its application acknowledgement is failed with an error
+     * naming the commit disposition it did receive, rather than with the generic
+     * connection error every other pending send gets. The two are genuinely different
+     * outcomes: one send may never have reached the peer, the other is known to be in its
+     * custody with only its application disposition unknown. That branch runs FIRST and is not
+     * overridable by the caller, because the peer's custody of those bytes is a known fact and
+     * no shutdown report may downgrade it to an unknown one.
+     *
+     * @param reason - Error for every entry the caller offers no better answer for.
+     * @param unresolvedFor - Per-entry error for an entry whose commit disposition has NOT
+     *   arrived. This is where the shutdown path splits the two populations; omitted, every such
+     *   entry gets `reason`.
      */
     private _teardownCorrelator;
+    /**
+     * Number of pending sends whose bytes ARE on the transport and whose acknowledgement has not
+     * arrived. This is what a shutdown drain waits for, and nothing else: a send still held
+     * inside the client cannot be acknowledged, so holding the drain open for one would spend a
+     * clinical shutdown's timeout waiting for an answer that cannot come.
+     */
+    private _outstandingAckCount;
+    /**
+     * The report a still-pending send gets when the client has finished shutting down, for the
+     * one population `_teardownCorrelator` leaves to this method: entries whose commit
+     * disposition never arrived.
+     *
+     * The split is the whole point of the shutdown contract. `sentAt` is stamped at the
+     * transport write and is `null` until then, so it says exactly which side of the wire a
+     * message was on when the client stopped:
+     *
+     *   * written, unanswered: {@link MllpUnknownFateError}, ambiguous, and reported as
+     *     ambiguous, carrying the flush timestamp a replay decision reasons about;
+     *   * never written: {@link MllpNeverDeliveredError}, and a resend of one of those cannot
+     *     duplicate anything.
+     *
+     * **The unflushed branch is a structural guard, and today no caller can reach it.** `send()`
+     * writes and stamps in the same synchronous run, so an entry that is in the live store is an
+     * entry that went out, and the never-written population arrives instead as a
+     * {@link ParkedSend}, which never enters the store at all. The branch stays because the
+     * store MODELS the state, `sentAt` being nullable is its own claim about it, and the
+     * reconnect path already splits the same two ways on the same field. Deleting it would make
+     * this report say the opposite of the truth the day anything does produce one, which on this
+     * surface means telling a consumer to treat an unwritten message as possibly committed.
+     */
+    private _shutdownErrorFor;
+    /**
+     * Has this client begun shutting down? A send parked inside it must not be resumed once it
+     * has: nothing was ever written for such a send, so its report is that delivery did not
+     * occur, and re-entering `send()` would trade that report for the generic not-connected one.
+     *
+     * True from the moment `close()` or `destroy()` is called, true on every halt that has
+     * already given up on the connection (a permanent connect failure, an exhausted retry
+     * policy, an aborted connect), and true while the underlying connection is draining, which
+     * is how a connection closed from outside this client is caught. Each of those is a state a
+     * fresh `send()` cannot succeed from.
+     *
+     * Read on the `'drain'` listener of every {@link ParkedSend}, because a shutdown drain ends
+     * when the last outstanding acknowledgement (or timeout, or abort) settles, and that same
+     * settlement emits `'drain'`. A park woken by it unregisters itself, so the settle pass that
+     * runs after the drain no longer sees it: the choice has to be made here or not at all.
+     */
+    private _shutdownBegun;
+    /**
+     * Fail every send parked inside the client. See {@link ParkedSend}.
+     *
+     * Iterates a copy and clears the register first, because each `cancel()` removes its own
+     * entry as it unwinds.
+     */
+    private _cancelParkedSends;
+    /**
+     * Settle everything still unresolved once the shutdown drain is over, under the
+     * two-population rule. Runs on every exit from `close()`, including the aborted one, so no
+     * send's promise is left pending by a shutdown.
+     */
+    private _settleUnresolvedSends;
+    /**
+     * Install this client's acknowledgement drain on a Connection's `beforeClose` seam, which is
+     * what gives `drainTimeoutMs` a meaning on the client at all.
+     *
+     * Whatever hook is already there is **composed with**, not replaced: the seam is a public
+     * instance property an owner may legitimately have assigned, and a shutdown that silently
+     * dropped that work would be a worse defect than the one this fixes. Installing is
+     * idempotent by hook identity, so a second `close()` composes nothing twice.
+     */
+    private _installDrainHook;
+    /**
+     * Resolve once there is nothing left to wait for. Three ways that happens:
+     *
+     *   * the last outstanding acknowledgement lands (or its send is otherwise settled), which
+     *     is what lets `close()` return in a fraction of the drain timeout;
+     *   * the connection leaves `DRAINING`, i.e. the link failed, the peer went away or the
+     *     client was destroyed. Nothing further can be acknowledged over a link that is gone, so
+     *     waiting out the rest of the timeout would buy nothing and hang the shutdown. That one
+     *     arrives through `_onStateChange`, the single delegating listener, rather than through a
+     *     second `'stateChange'` registration of its own;
+     *   * never, in which case `Connection.close` times the whole thing out at `drainTimeoutMs`
+     *     and the still-unanswered sends are reported with their fate unknown. The bound lives
+     *     there, in the drain race, rather than being duplicated here.
+     */
+    private _awaitOutstandingAcks;
     /**
      * **Test seam**, attach an externally-built {@link Connection} directly,
      * bypassing the `net.createConnection` + `NetTransport` path. Used by
@@ -2799,14 +3761,35 @@ declare class MllpClient extends EventEmitter {
      */
     _attachExistingConnection(conn: Connection): void;
     /**
-     * Gracefully close the client.
+     * Gracefully close the client, awaiting the acknowledgements of sends already written to
+     * the transport.
      *
      * Delegates to {@link Connection.close}, which transitions `CONNECTED → DRAINING
      * → DISCONNECTED` (or `CLOSED` on drain timeout). No-op if no Connection is
-     * attached.
+     * attached, or if the close has already completed.
+     *
+     * The drain ends as soon as the last outstanding acknowledgement arrives, so a caller whose
+     * peer answers promptly does not wait out `drainTimeoutMs`. Whatever is still unresolved
+     * when it does end is reported to its own `send()` caller under one rule, and the whole
+     * point of this method is that the two halves of that rule are told apart:
+     *
+     *   * a send already written to the transport rejects with {@link MllpUnknownFateError},
+     *     carrying the timestamp at which its bytes went out. It may have been committed;
+     *     resending it may duplicate a clinical message. Nothing is retried here.
+     *   * a send still held inside the client rejects with {@link MllpNeverDeliveredError}.
+     *     The peer never saw those bytes, so resending them is safe.
+     *   * a send whose commit disposition the peer had already reported keeps its
+     *     {@link MllpApplicationAckError}, which names that disposition. The peer's custody of
+     *     those bytes is known, and a shutdown never downgrades a known fact to an unknown one.
      *
      * Rejects with `DOMException('Aborted', 'AbortError')` if `signal` aborts mid-drain;
-     * on abort, the underlying Connection is force-destroyed.
+     * on abort, the underlying Connection is force-destroyed and every still-pending send is
+     * settled under the same rule rather than left pending.
+     *
+     * A drain cannot make delivery certain, and nothing here claims otherwise: an
+     * acknowledgement lost in flight is indistinguishable from a message never received. That is
+     * what the unknown-fate report says, and it is why the application still owns idempotency,
+     * keyed on MSH-10 plus MSH-7.
      *
      * @example
      * ```typescript
@@ -2821,6 +3804,13 @@ declare class MllpClient extends EventEmitter {
      * Abruptly destroy the client, force-transitions the underlying Connection
      * to `CLOSED` immediately. No-op if no Connection is attached. Idempotent.
      *
+     * Every pending send is settled at once: no acknowledgement is awaited and no drain timeout
+     * is honoured, which is exactly what separates this from {@link MllpClient.close}. A
+     * `close()` already waiting on acknowledgements stops waiting here and returns. A send still
+     * held inside the client is failed with {@link MllpNeverDeliveredError}, because nothing was
+     * ever written for it; that is a statement about the bytes, not about how the client was
+     * shut down, so it holds on this path too.
+     *
      * @example
      * ```typescript
      * client.destroy(new Error('shutting down'));
@@ -2962,6 +3952,8 @@ declare function createStarterClient(opts: StarterClientOptions): Promise<MllpCl
  * Exports:
  * - `MllpTimeoutError`, ACK timeout
  * - `MllpBackpressureError`, high-water mark exceeded
+ * - `MllpNeverDeliveredError`, a send that never reached the transport
+ * - `MllpUnknownFateError`, a send whose bytes went out and drew no answer
  * - `isTransientConnectionError`, transient/permanent classifier
  *
  * Re-exported from `src/client/index.ts` and `src/index.ts`.
@@ -3002,20 +3994,249 @@ declare class MllpTimeoutError extends Error {
      * `latin1`, a 1:1 byte to code-unit map, so this count is a byte count.
      */
     readonly messageControlIdBytes: number | undefined;
-    /** Milliseconds elapsed between write-flush and timeout fire. */
-    readonly elapsedMs: number;
-    /** Epoch ms timestamp recorded at write-flush callback. */
-    readonly sentAt: number;
+    /** Milliseconds elapsed between write-flush and timeout fire. */
+    readonly elapsedMs: number;
+    /** Epoch ms timestamp recorded at write-flush callback. */
+    readonly sentAt: number;
+    /**
+     * Construct an MLLP timeout error.
+     *
+     * @param message - Human-readable error message. Structural facts only, never field content.
+     * @param opts - Timeout context (control-id byte length, elapsed time, flush timestamp).
+     */
+    constructor(message: string, opts: {
+        messageControlIdBytes: number | undefined;
+        elapsedMs: number;
+        sentAt: number;
+    });
+}
+/**
+ * Why a send waiting on its application acknowledgement was failed.
+ *
+ * - `'timeout'`, the wait that started at the accept acknowledgement expired.
+ * - `'connection-lost'`, the link failed or was closed while the send was still pending on
+ *   it. The send is failed rather than left pending or reported as successful, because
+ *   nobody can say what the receiving application did with a message whose second
+ *   acknowledgement never arrived.
+ *
+ * @example
+ * ```typescript
+ * import { MllpApplicationAckError } from '@cosyte/mllp';
+ * if (err instanceof MllpApplicationAckError && err.reason === 'timeout') {
+ *   // committed by the peer, application disposition unknown
+ * }
+ * ```
+ */
+type ApplicationAckFailure = "timeout" | "connection-lost";
+/**
+ * Rejects a `send()` whose peer **committed** the message and then never reported what its
+ * application did with it.
+ *
+ * This is the enhanced-mode outcome that has no original-mode counterpart, and it is
+ * deliberately a distinct type from {@link MllpTimeoutError}: that one means "no
+ * acknowledgement at all arrived", and this one means "the accept acknowledgement arrived,
+ * the peer took custody, and the application acknowledgement did not follow". Confusing the
+ * two would tell an operator a message may never have been received when the peer has said
+ * in writing that it was.
+ *
+ * `commitCode` is the Table 0008 code already received, so a caller can act on the custody
+ * transfer even though the application disposition is unknown. It is a member of a closed
+ * six-code set, never wire content.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.send(payload);
+ * } catch (err) {
+ *   if (err instanceof MllpApplicationAckError) {
+ *     logger.warn({ commit: err.commitCode, reason: err.reason, elapsedMs: err.elapsedMs });
+ *   }
+ * }
+ * ```
+ */
+declare class MllpApplicationAckError extends Error {
+    readonly name: "MllpApplicationAckError";
+    /** Why the wait ended. See {@link ApplicationAckFailure}. */
+    readonly reason: ApplicationAckFailure;
+    /** The commit disposition already received. Always the positive accept-mode code. */
+    readonly commitCode: "CA";
+    /**
+     * Byte length of the send's MSH-10 control ID, or `undefined` when there was none to
+     * read. The control ID itself is deliberately not here, for the reason given on
+     * {@link MllpTimeoutError.messageControlIdBytes}.
+     */
+    readonly messageControlIdBytes: number | undefined;
+    /** Milliseconds between the accept acknowledgement and this failure. */
+    readonly elapsedMs: number;
+    /** Epoch ms at which the accept acknowledgement was received. */
+    readonly commitReceivedAt: number;
+    /**
+     * Construct an application-acknowledgement failure.
+     *
+     * @param message - Human-readable error message. Structural facts only, never field content.
+     * @param opts - Failure context (why, the commit code, control-id byte length, timings).
+     */
+    constructor(message: string, opts: {
+        reason: ApplicationAckFailure;
+        commitCode: "CA";
+        messageControlIdBytes: number | undefined;
+        elapsedMs: number;
+        commitReceivedAt: number;
+    });
+}
+/**
+ * Rejects a `send()` whose peer answered with a **negative commit**: HL7 Table 0008 `CE`
+ * (commit error) or `CR` (commit reject).
+ *
+ * Either says the peer did not take custody of the bytes, so no application acknowledgement
+ * is coming and there is nothing to wait for. The send fails immediately rather than sitting
+ * out a window that would report the same failure later and less precisely.
+ *
+ * `commitCode` is a member of a closed six-code set, never wire content.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.send(payload);
+ * } catch (err) {
+ *   if (err instanceof MllpCommitRejectedError && err.commitCode === 'CR') {
+ *     // the peer will not take this message; do not resend it unchanged
+ *   }
+ * }
+ * ```
+ */
+declare class MllpCommitRejectedError extends Error {
+    readonly name: "MllpCommitRejectedError";
+    /** The negative accept-mode code the peer sent. */
+    readonly commitCode: "CE" | "CR";
+    /**
+     * Byte length of the send's MSH-10 control ID, or `undefined` when there was none to
+     * read. The control ID itself is deliberately not here.
+     */
+    readonly messageControlIdBytes: number | undefined;
+    /** Milliseconds between the send's write-flush and this acknowledgement. */
+    readonly elapsedMs: number;
+    /**
+     * Construct a negative-commit error.
+     *
+     * @param message - Human-readable error message. Structural facts only, never field content.
+     * @param opts - Failure context (the commit code, control-id byte length, elapsed time).
+     */
+    constructor(message: string, opts: {
+        commitCode: "CE" | "CR";
+        messageControlIdBytes: number | undefined;
+        elapsedMs: number;
+    });
+}
+/**
+ * Rejects a `send()` whose bytes **never reached the transport**: the message was still held
+ * inside the client when the client shut down, waiting for room in the send queue or for the
+ * single in-flight slot.
+ *
+ * This is the safe half of a shutdown report. Nothing was written, so the peer cannot have
+ * seen this message, cannot have committed it, and cannot produce a duplicate if the
+ * application sends it again. It is deliberately a distinct type from
+ * {@link MllpUnknownFateError}, so a caller decides between resending and escalating on
+ * `instanceof` rather than on the wording of a message.
+ *
+ * Every field is a count. There is nothing else to carry: the caller passed the payload to
+ * `send()` and still holds it.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.send(payload);
+ * } catch (err) {
+ *   if (err instanceof MllpNeverDeliveredError) {
+ *     // safe to resend: these bytes were never written
+ *     await backupClient.send(payload);
+ *   }
+ * }
+ * ```
+ */
+declare class MllpNeverDeliveredError extends Error {
+    readonly name: "MllpNeverDeliveredError";
+    /** Byte count of the framed message this send would have written. */
+    readonly byteCount: number;
+    /**
+     * Byte length of the send's MSH-10 control ID, or `undefined` when there was none to read.
+     * The control ID itself is deliberately not here, for the reason given on
+     * {@link MllpTimeoutError.messageControlIdBytes}.
+     */
+    readonly messageControlIdBytes: number | undefined;
+    /**
+     * Construct a never-delivered report.
+     *
+     * There is no `message` parameter, deliberately: see {@link NEVER_DELIVERED_MESSAGE}.
+     *
+     * @param opts - Report context (framed byte count, control-id byte length).
+     */
+    constructor(opts: {
+        byteCount: number;
+        messageControlIdBytes: number | undefined;
+    });
+}
+/**
+ * Rejects a `send()` that **was** written to the transport and whose acknowledgement had still
+ * not arrived when the client finished closing.
+ *
+ * The ambiguous half of a shutdown report, and it is reported as ambiguous because it is: an
+ * acknowledgement lost on the way back is indistinguishable from a message the peer never
+ * received. Nothing is retried automatically. HL7 makes the accept acknowledgement the thing
+ * that releases a sender from resending, and puts the retransmission decision on the
+ * application and on its peer's duplicate detection, keyed on MSH-10 plus MSH-7.
+ *
+ * Distinct from {@link MllpNeverDeliveredError} (nothing was written, so a resend is safe) and
+ * from {@link MllpApplicationAckError} (the peer said in writing that it took custody, so a
+ * resend would commit the message twice). Confusing the three is how a consumer's replay logic
+ * either duplicates a clinical message or drops one.
+ *
+ * `flushedAt` is what a replay decision reasons about: it says when these bytes went out, so a
+ * caller can compare it against the peer's own record.
+ *
+ * **Every field is a byte count or a timestamp, and the message is a constant.** No part of
+ * the payload reaches this error, not the control ID, not a truncation of it, and not a hex
+ * rendering. An `Error` is a diagnostic surface: it is logged, and its `stack` plus its own
+ * properties are what an error reporter ships off the box.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.send(payload);
+ * } catch (err) {
+ *   if (err instanceof MllpUnknownFateError) {
+ *     // do NOT blindly resend: the peer may already hold this message
+ *     logger.warn({ flushedAt: err.flushedAt, bytes: err.byteCount });
+ *   }
+ * }
+ * ```
+ */
+declare class MllpUnknownFateError extends Error {
+    readonly name: "MllpUnknownFateError";
+    /** Epoch ms at which this send's bytes were written to the transport. */
+    readonly flushedAt: number;
+    /** Milliseconds between that write and this report. */
+    readonly elapsedMs: number;
+    /** Byte count of the framed message that was written. */
+    readonly byteCount: number;
+    /**
+     * Byte length of the send's MSH-10 control ID, or `undefined` when there was none to read.
+     * The control ID itself is deliberately not here, for the reason given on
+     * {@link MllpTimeoutError.messageControlIdBytes}.
+     */
+    readonly messageControlIdBytes: number | undefined;
     /**
-     * Construct an MLLP timeout error.
+     * Construct an unknown-fate report.
      *
-     * @param message - Human-readable error message. Structural facts only, never field content.
-     * @param opts - Timeout context (control-id byte length, elapsed time, flush timestamp).
+     * There is no `message` parameter, deliberately: see {@link UNKNOWN_FATE_MESSAGE}.
+     *
+     * @param opts - Report context (flush timestamp, elapsed time, byte counts).
      */
-    constructor(message: string, opts: {
-        messageControlIdBytes: number | undefined;
+    constructor(opts: {
+        flushedAt: number;
         elapsedMs: number;
-        sentAt: number;
+        byteCount: number;
+        messageControlIdBytes: number | undefined;
     });
 }
 /**
@@ -3183,6 +4404,548 @@ declare class MllpBackpressureError extends Error {
     });
 }
 
+/**
+ * The canonical exchange corpus the differential harness sends, and the canonical
+ * acknowledgement it compares a peer's answer against.
+ *
+ * Every message here is **synthetic**: the identifiers, names and dates are fabricated
+ * and declared as such in this repository's PHI allow-list. Nothing in this file is, or
+ * may become, a real patient. The corpus ships inside the published package so a consumer
+ * who installed `@cosyte/mllp` and has no checkout of this repository can still run the
+ * harness against their own interface engine.
+ *
+ * Each message is written as segment string literals joined by the HL7 segment separator
+ * (`CR`) rather than as a byte blob, deliberately: the identifiers stay readable to a human
+ * reviewer and to this repository's structured PHI scan, which is what keeps a planted
+ * identifier from slipping through as opaque bytes.
+ *
+ * @example
+ * ```typescript
+ * import { canonicalExchanges } from '@cosyte/mllp';
+ * for (const exchange of canonicalExchanges()) {
+ *   console.log(exchange.id, exchange.payload.length);
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+/**
+ * One send-and-await-response pair the harness runs against a peer.
+ *
+ * `payload` is the HL7 v2 message body with **no** MLLP framing on it. The harness frames
+ * it canonically (`VT` + payload + `FS` + `CR`) with the package's own strict encoder
+ * before it goes on the wire, so what a peer receives is the Release 1 block this package
+ * emits for every message.
+ *
+ * @example
+ * ```typescript
+ * const [first] = canonicalExchanges();
+ * // first?.id === 'adt-a01'; first?.controlId === 'MSG00001'
+ * ```
+ */
+interface CanonicalExchange {
+    /**
+     * Stable identifier for this exchange, and the identifier the report uses. It names the
+     * message, never a patient, so it is safe to log.
+     */
+    readonly id: string;
+    /** One-line description of what the message is, for a human reading the report. */
+    readonly description: string;
+    /**
+     * The `MSH-10` message control ID this message carries. A conformant peer echoes it in
+     * the `MSA-2` of its acknowledgement, which is the correlation the harness checks.
+     */
+    readonly controlId: string;
+    /** The unframed HL7 v2 message bytes. A fresh copy per call; mutating it is harmless. */
+    readonly payload: Buffer;
+}
+/**
+ * The canonical exchange corpus, freshly built on every call so a caller cannot mutate the
+ * corpus another caller will send.
+ *
+ * Two messages, both drawn from the framing goldens this package already pins itself
+ * against, so what a consumer sends at their own engine is byte-identical to what this
+ * package's own framing tests assert. The positive acknowledgement golden is deliberately
+ * NOT one of them: it is the reference ANSWER (see {@link canonicalAcknowledgement}), and
+ * an engine that correctly declines to acknowledge an unsolicited acknowledgement would
+ * otherwise be reported as having failed to answer.
+ *
+ * @returns One entry per exchange, in the order the harness runs them.
+ *
+ * @example
+ * ```typescript
+ * const exchanges = canonicalExchanges();
+ * // exchanges.map((e) => e.id) is ['adt-a01', 'oru-r01']
+ * ```
+ */
+declare function canonicalExchanges(): readonly CanonicalExchange[];
+/**
+ * The canonical positive acknowledgement, unframed, freshly built on every call.
+ *
+ * This is what a conformant Release 1 peer's answer to the first canonical exchange looks
+ * like on the wire once the framing is stripped. The harness never sends it; it is here so
+ * a test double, or a consumer building one, can answer with the shape the package itself
+ * emits.
+ *
+ * @returns The unframed acknowledgement bytes.
+ *
+ * @example
+ * ```typescript
+ * import { canonicalAcknowledgement, encodeFrame } from '@cosyte/mllp';
+ * const wire = encodeFrame(canonicalAcknowledgement());
+ * // wire[0] === 0x0b
+ * ```
+ */
+declare function canonicalAcknowledgement(): Buffer;
+
+/**
+ * Typed **configuration** error for the differential harness, and its stable code.
+ *
+ * A configuration error is raised before any socket exists: the peer address the caller
+ * supplied cannot be resolved into a host and a port, so the run is refused rather than
+ * quietly skipped. Skipping it would be the worse answer by far, because a skip is what
+ * "no peer configured" means, and a developer who mistyped an address would read the skip
+ * as proof the harness ran.
+ *
+ * This code is a **public API**. It appears in caller `catch` blocks, log pipelines and
+ * monitoring dashboards. Renaming or removing it is a breaking change, the same guardrail
+ * the framing warning codes and the security-warning codes carry.
+ *
+ * @example
+ * ```typescript
+ * import { MllpDifferentialConfigurationError, runDifferential } from '@cosyte/mllp';
+ * try {
+ *   await runDifferential({ peer: process.env['MLLP_DIFF_PEER'] });
+ * } catch (err) {
+ *   if (err instanceof MllpDifferentialConfigurationError) {
+ *     logger.error({ code: err.code, value: err.value });
+ *   }
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+/**
+ * A peer address was configured and could not be resolved into a host and a port.
+ *
+ * Distinct from no peer at all, which is not an error and skips the run.
+ *
+ * @example
+ * ```typescript
+ * import { MLLP_DIFF_PEER_UNPARSEABLE } from '@cosyte/mllp';
+ * if (err.code === MLLP_DIFF_PEER_UNPARSEABLE) process.exit(78); // EX_CONFIG
+ * ```
+ */
+declare const MLLP_DIFF_PEER_UNPARSEABLE = "MLLP_DIFF_PEER_UNPARSEABLE";
+/**
+ * Union of the stable differential-configuration error codes.
+ *
+ * @example
+ * ```typescript
+ * const code: DifferentialConfigurationErrorCode = 'MLLP_DIFF_PEER_UNPARSEABLE';
+ * ```
+ */
+type DifferentialConfigurationErrorCode = typeof MLLP_DIFF_PEER_UNPARSEABLE;
+/**
+ * Fixed, human-readable description for a differential-configuration code.
+ *
+ * Byte-for-byte identical for a given code, whatever was configured.
+ *
+ * @param code - The stable configuration-error code.
+ * @returns The frozen registry text for `code`.
+ *
+ * @example
+ * ```typescript
+ * import { differentialConfigurationMessage, MLLP_DIFF_PEER_UNPARSEABLE } from '@cosyte/mllp';
+ * logger.error(differentialConfigurationMessage(MLLP_DIFF_PEER_UNPARSEABLE));
+ * ```
+ */
+declare function differentialConfigurationMessage(code: DifferentialConfigurationErrorCode): string;
+/**
+ * Thrown when the differential harness is configured with a peer address it cannot use.
+ *
+ * Rejects the originating `runDifferential()` call. No socket is opened, no canonical
+ * message is sent, and no report is produced: there is nothing to report about.
+ *
+ * Identify it by `instanceof` **and** by the stable
+ * {@link MllpDifferentialConfigurationError.code}, never by matching on the message text.
+ *
+ * @example
+ * ```typescript
+ * import { MllpDifferentialConfigurationError } from '@cosyte/mllp';
+ * try {
+ *   await runDifferential({ peer: 'not-an-address' });
+ * } catch (err) {
+ *   if (err instanceof MllpDifferentialConfigurationError) logger.error({ value: err.value });
+ * }
+ * ```
+ */
+declare class MllpDifferentialConfigurationError extends Error {
+    readonly name: "MllpDifferentialConfigurationError";
+    /**
+     * The stable configuration-error code. Public API; branch on this rather than on the
+     * message.
+     */
+    readonly code: DifferentialConfigurationErrorCode;
+    /**
+     * The offending value exactly as it was configured, so the operator can see which of
+     * their settings is wrong without guessing. It is caller configuration, never anything
+     * read off a peer.
+     */
+    readonly value: string;
+    /**
+     * Construct a differential configuration error.
+     *
+     * @param code - The stable configuration-error code; also selects the message.
+     * @param value - The offending configured value, reported verbatim.
+     */
+    constructor(code: DifferentialConfigurationErrorCode, value: string);
+}
+
+/**
+ * Peer-address resolution for the differential harness.
+ *
+ * Two states are deliberately told apart, and conflating them is the defect this module
+ * exists to prevent:
+ *
+ *   * **No peer configured.** The address is absent or empty. There is nothing to point
+ *     the harness at, so the run skips cleanly and the default verification stays green.
+ *   * **A peer configured that cannot be read.** The address is present and is not a host
+ *     and a port. That is a mistake in someone's configuration, and it is refused by name.
+ *
+ * A single "return undefined for both" rule silently skips the live run while the operator
+ * believes it ran, which is the one outcome a pre-go-live check must never produce.
+ *
+ * @packageDocumentation
+ */
+/**
+ * A resolved peer endpoint: where the harness opens its connections.
+ *
+ * @example
+ * ```typescript
+ * const peer: DifferentialPeer = { host: '127.0.0.1', port: 2575 };
+ * ```
+ */
+interface DifferentialPeer {
+    /** Host name or address literal, with any IPv6 brackets already removed. */
+    readonly host: string;
+    /** TCP port, an integer in 1..65535. */
+    readonly port: number;
+}
+/**
+ * Resolve a configured peer address into a host and a port.
+ *
+ * The address is split on its **last** colon, so an IPv6 literal resolves as well as a
+ * host name: `[::1]:2575` and `::1:2575` both give host `::1`. A naive split on the first
+ * colon mangles the host and produces a NaN port, which is precisely how a live run gets
+ * skipped while the operator believes it happened.
+ *
+ * @param raw - The configured address, or `undefined`/`null`/empty for no peer at all.
+ * @returns The resolved peer, or `undefined` when no peer is configured.
+ * @throws MllpDifferentialConfigurationError when an address is present and unusable.
+ *
+ * @example
+ * ```typescript
+ * import { resolveDifferentialPeer } from '@cosyte/mllp';
+ * const peer = resolveDifferentialPeer('127.0.0.1:2575');
+ * // peer?.host === '127.0.0.1'; peer?.port === 2575
+ * // resolveDifferentialPeer(undefined) === undefined
+ * ```
+ */
+declare function resolveDifferentialPeer(raw: string | undefined | null): DifferentialPeer | undefined;
+
+/**
+ * The report shape the differential harness returns.
+ *
+ * Everything here is a plain, JSON-serializable value: strings, numbers, booleans and
+ * arrays of them. No `Buffer`, no `Date`, no class instance, so a consumer can
+ * `JSON.stringify` a run straight into a log pipeline or a review artifact and read it
+ * programmatically without scraping human-readable text.
+ *
+ * ## What this report is, and what it is not
+ *
+ * It records what was **observed** on the wire. It is not a conformance verdict and never
+ * becomes one: no field says a peer is conformant, no field says a run passed, and nothing
+ * here decides whether an interface is fit to carry clinical traffic. That judgement
+ * belongs to the people standing the interface up, with this evidence in front of them.
+ *
+ * ## Why no payload content appears anywhere
+ *
+ * A peer answering this harness may be a live engine holding real patients, and a report
+ * is a diagnostic surface that gets written to a file, pasted into a ticket and mailed to
+ * a vendor. So a deviation is described by its stable code, a byte offset and structural
+ * counts only. Not a run of the peer's bytes, not the acknowledged control ID, not a
+ * truncation of either.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * What became of one canonical exchange.
+ *
+ * - `answered`, the peer returned a decodable frame, so parity and correlation are
+ *   reported for it.
+ * - `unanswered`, the connection held and no complete frame arrived before the deadline.
+ * - `undecodable-response`, bytes arrived and the decoder could not complete a frame from
+ *   them even with every tolerance enabled. The deviation is still named by its code.
+ * - `connection-refused`, the peer refused the connection outright.
+ * - `connection-failed`, the connection could not be established for some other reason.
+ * - `connection-dropped`, the connection was established and then went away mid-exchange.
+ *
+ * @example
+ * ```typescript
+ * const outcome: DifferentialExchangeOutcome = 'answered';
+ * ```
+ */
+type DifferentialExchangeOutcome = "answered" | "unanswered" | "undecodable-response" | "connection-refused" | "connection-failed" | "connection-dropped";
+/**
+ * Whether the peer's response frame was byte-identical to the canonical Release 1 block.
+ *
+ * `not-observed` is the honest answer when no frame arrived: an exchange that was never
+ * answered has no parity, and reporting one as a failure would confuse a silent peer with
+ * a mis-framing one.
+ *
+ * @example
+ * ```typescript
+ * const parity: DifferentialParityOutcome = 'match';
+ * ```
+ */
+type DifferentialParityOutcome = "match" | "deviation" | "not-observed";
+/**
+ * Whether the peer's acknowledgement echoed the control ID of the message it answered.
+ *
+ * `absent` means the response carried no readable acknowledged control ID at all, which
+ * is a different failure from echoing the wrong one and is worth telling apart.
+ *
+ * @example
+ * ```typescript
+ * const correlation: DifferentialCorrelationOutcome = 'match';
+ * ```
+ */
+type DifferentialCorrelationOutcome = "match" | "mismatch" | "absent" | "not-observed";
+/**
+ * One named deviation, located by offset.
+ *
+ * @example
+ * ```typescript
+ * const deviation: DifferentialDeviation = { code: 'MLLP_MISSING_LEADING_VT', byteOffset: 0 };
+ * ```
+ */
+interface DifferentialDeviation {
+    /** The package's stable warning code for this deviation. */
+    readonly code: WarningCode;
+    /** Byte offset within the peer's response stream where it was detected. */
+    readonly byteOffset: number;
+}
+/**
+ * What one canonical exchange produced.
+ *
+ * @example
+ * ```typescript
+ * for (const exchange of report.exchanges) {
+ *   console.log(exchange.exchangeId, exchange.outcome, exchange.byteParity);
+ * }
+ * ```
+ */
+interface DifferentialExchangeReport {
+    /** The corpus identifier of the message that was sent. Names a message, never a patient. */
+    readonly exchangeId: string;
+    /** What became of the exchange. */
+    readonly outcome: DifferentialExchangeOutcome;
+    /** Whether the response frame matched the canonical Release 1 block byte for byte. */
+    readonly byteParity: DifferentialParityOutcome;
+    /** Whether the response echoed the control ID of the message that was sent. */
+    readonly correlation: DifferentialCorrelationOutcome;
+    /** Every stable warning code observed on this exchange, in the order they were seen. */
+    readonly warningCodes: readonly WarningCode[];
+    /** The same deviations with the byte offset each was detected at. */
+    readonly deviations: readonly DifferentialDeviation[];
+    /** How many bytes were sent to the peer, framing included. A count, never content. */
+    readonly requestByteCount: number;
+    /** How many bytes were read back before the exchange concluded. A count, never content. */
+    readonly responseByteCount: number;
+    /** The response deadline this exchange waited, in milliseconds. */
+    readonly deadlineMs: number;
+    /** How long the exchange actually took, in milliseconds. */
+    readonly elapsedMs: number;
+}
+/**
+ * The overall shape of a run, in three values plus the skip.
+ *
+ * - `parity-observed`, every attempted exchange was answered with a byte-identical
+ *   canonical block and a correlating acknowledgement.
+ * - `deviations-observed`, at least one exchange was answered and at least one exchange
+ *   deviated, went unanswered or failed.
+ * - `no-observation`, nothing was answered, so the run observed nothing about the peer.
+ * - `skipped`, no peer was configured and nothing was sent.
+ *
+ * **None of these is a pass**, and `parity-observed` in particular is not one: it says
+ * what this corpus saw on this run, not that a peer is conformant.
+ *
+ * @example
+ * ```typescript
+ * const result: DifferentialRunResult = 'no-observation';
+ * ```
+ */
+type DifferentialRunResult = "parity-observed" | "deviations-observed" | "no-observation" | "skipped";
+/**
+ * Why a run was skipped, when it was.
+ *
+ * @example
+ * ```typescript
+ * const reason: DifferentialSkipReason = 'no-peer-configured';
+ * ```
+ */
+type DifferentialSkipReason = "no-peer-configured";
+/**
+ * The report a run returns. Frozen, and JSON-serializable throughout.
+ *
+ * @example
+ * ```typescript
+ * const report = await runDifferential({ peer: '127.0.0.1:2575' });
+ * console.log(JSON.stringify(report, null, 2));
+ * ```
+ */
+interface DifferentialReport {
+    /** The peer that was contacted, or `undefined` when the run was skipped. */
+    readonly peer: DifferentialReportPeer | undefined;
+    /** What the run as a whole observed. Never a conformance verdict. */
+    readonly result: DifferentialRunResult;
+    /** Why the run was skipped, or `undefined` when it ran. */
+    readonly skipReason: DifferentialSkipReason | undefined;
+    /** One entry per canonical exchange attempted, in the order they ran. */
+    readonly exchanges: readonly DifferentialExchangeReport[];
+    /** How many exchanges were attempted. */
+    readonly exchangesAttempted: number;
+    /** How many of them the peer answered with a decodable frame. */
+    readonly exchangesAnswered: number;
+    /** The per-exchange response deadline the run used, in milliseconds. */
+    readonly deadlineMs: number;
+    /** When the run started, as an ISO 8601 string. */
+    readonly startedAt: string;
+    /** When the run finished, as an ISO 8601 string. */
+    readonly finishedAt: string;
+}
+/**
+ * The peer a report describes. Host and port as configured, nothing resolved or probed.
+ *
+ * @example
+ * ```typescript
+ * const peer: DifferentialReportPeer = { host: '127.0.0.1', port: 2575 };
+ * ```
+ */
+interface DifferentialReportPeer {
+    /** Host name or address literal the run connected to. */
+    readonly host: string;
+    /** TCP port the run connected to. */
+    readonly port: number;
+}
+
+/**
+ * The differential run: send each canonical message at a peer, read what comes back, and
+ * report what was observed.
+ *
+ * ## What it does, exchange by exchange
+ *
+ * One connection per exchange, opened, used and closed. That is deliberate: a peer that
+ * refuses or drops one connection then costs one exchange rather than the whole run, which
+ * is what lets the report say "this message was answered and that one was not" instead of
+ * "the run failed".
+ *
+ * The message goes out through this package's own strict encoder, so what the peer
+ * receives is the canonical Release 1 block: `VT` + payload + `FS` + `CR`. The answer is
+ * read back through this package's own decoder with **every tolerance enabled**, so a peer
+ * that deviates from the block is described by the stable warning code for that deviation
+ * rather than killing the run with an opaque error.
+ *
+ * ## What byte parity means here
+ *
+ * The MLLP **envelope** the peer emitted, compared against the canonical Release 1 block
+ * this package emits for the same payload. It is not equality of message content, which
+ * can never hold: an acknowledgement carries the peer's own control ID, its own timestamp
+ * and its own sending application, and it is supposed to.
+ *
+ * ## Aim it with care
+ *
+ * A run sends real bytes into whatever engine it is pointed at. Those bytes are synthetic
+ * patients, so an engine that accepts them stores synthetic patients. Point it at a test
+ * or staging endpoint, never at a production interface carrying live traffic.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Opens a connection to the peer. Supply your own to run the harness over something other
+ * than a plain TCP socket, a TLS transport for an MLLPS peer being the obvious case.
+ *
+ * The returned transport must not be connected yet: the harness registers its handlers
+ * first and writes only once `onConnect` fires.
+ *
+ * @example
+ * ```typescript
+ * const connect: DifferentialConnect = (peer) =>
+ *   new TlsTransport(tls.connect({ host: peer.host, port: peer.port }));
+ * ```
+ */
+type DifferentialConnect = (peer: DifferentialPeer) => Transport;
+/**
+ * Options for {@link runDifferential}.
+ *
+ * @example
+ * ```typescript
+ * const report = await runDifferential({ peer: '127.0.0.1:2575', deadlineMs: 5_000 });
+ * ```
+ */
+interface DifferentialRunOptions {
+    /**
+     * The peer to run against, as `host:port`. Absent or empty means no peer is configured,
+     * and the run skips cleanly. A value that is present and cannot be resolved into a host
+     * and a port is refused by name instead, because a silent skip there would read as
+     * proof the harness ran.
+     */
+    readonly peer?: string | undefined;
+    /** Per-exchange response deadline in milliseconds. Default 10000. */
+    readonly deadlineMs?: number;
+    /**
+     * Largest response payload the decoder will accumulate before it refuses, in bytes.
+     * Defaults to the package's own 16 MiB frame cap. A peer that exceeds it is reported as
+     * a deviation named by the oversize warning code, not as an unhandled error.
+     */
+    readonly maxFrameSizeBytes?: number;
+    /** The exchanges to run. Defaults to the shipped canonical corpus. */
+    readonly exchanges?: readonly CanonicalExchange[];
+    /** How to open each connection. Defaults to a plain TCP socket. */
+    readonly connect?: DifferentialConnect;
+    /** Aborts the run. The rejection carries the signal's own reason. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Run the canonical exchanges against a peer and report what was observed.
+ *
+ * With no peer configured the run skips cleanly and returns a report saying so, so a
+ * default verification stays green on a machine that has no engine to point at. With a
+ * peer configured that cannot be resolved into a host and a port, the run is refused by
+ * name instead of skipped.
+ *
+ * The returned report is frozen and JSON-serializable, and carries no content read off the
+ * peer: deviations are named by stable code and byte offset, never by quoting bytes.
+ *
+ * **The run sends synthetic patient messages into whatever engine it is aimed at.** Aim it
+ * at a test or staging endpoint.
+ *
+ * @param options - Peer address, deadline, corpus, connection factory and abort signal.
+ * @returns The report for the whole run, whatever each exchange did.
+ * @throws MllpDifferentialConfigurationError when a peer address is configured and unusable.
+ *
+ * @example
+ * ```typescript
+ * import { runDifferential } from '@cosyte/mllp';
+ * const report = await runDifferential({ peer: process.env['MLLP_DIFF_PEER'] });
+ * console.log(JSON.stringify(report, null, 2));
+ * ```
+ */
+declare function runDifferential(options?: DifferentialRunOptions): Promise<DifferentialReport>;
+
 /**
  * `@cosyte/mllp`, Production-grade MLLP client and server for Node.js.
  *
@@ -3214,4 +4977,4 @@ declare class MllpBackpressureError extends Error {
  */
 declare const VERSION: string;
 
-export { type AckCode, type AckCorrelationCode, type AckCorrelationWarning, type ClientAuth, type ClientOptions, type ClientStats, Connection, type ConnectionErrorCause, type ConnectionErrorPhase, type ConnectionOptions, type ConnectionState, type ConnectionStats, type EncoderOptions, FrameReader, type FrameReaderOptions, MLLP_BIND_ALL_INTERFACES, MLLP_TLS_VERIFY_DISABLED, type MessageMeta, MllpAckError, MllpBackpressureError, MllpClient, MllpConnectionError, MllpFramingError, MllpServer, MllpTimeoutError, type MllpWarning, type NackEvent, type NackReason, type NegativeAckCode, NetTransport, type PemInput, type ReconnectingEvent, type RetryContext, type RetryStrategy, type SecurityWarning, type SecurityWarningCode, type ServerOptions, type ServerStats, type ServerTlsOptions, type StarterClientOptions, type StarterServerOptions, type StateChangeEvent, type TlsOptions, TlsTransport, Transport, VERSION, type WarningCode, ackDiagnosticMessage, buildRawAck, createClient, createServer, createStarterClient, createStarterServer, createWarning, encodeFrame, isTlsProtocolError, isTlsVerificationErrorCode, isTransientConnectionError, rawAckUncorrelatable, resolveNackCode };
+export { ATNA_CIPHER_LIST, ATNA_CIPHER_SUITES, type AckCode, type AckCorrelationCode, type AckCorrelationWarning, type AckModeCode, type AckModeWarning, type AckModeWarningEvent, type ApplicationAckFailure, type CanonicalExchange, type ClientAuth, type ClientOptions, type ClientStats, type CommitAckReport, Connection, type ConnectionErrorCause, type ConnectionErrorPhase, type ConnectionOptions, type ConnectionState, type ConnectionStats, type DifferentialConfigurationErrorCode, type DifferentialConnect, type DifferentialCorrelationOutcome, type DifferentialDeviation, type DifferentialExchangeOutcome, type DifferentialExchangeReport, type DifferentialParityOutcome, type DifferentialPeer, type DifferentialReport, type DifferentialReportPeer, type DifferentialRunOptions, type DifferentialRunResult, type DifferentialSkipReason, type EncoderOptions, FrameReader, type FrameReaderOptions, MLLP_BIND_ALL_INTERFACES, MLLP_DIFF_PEER_UNPARSEABLE, MLLP_TLS_CIPHER_LIST_REJECTED, MLLP_TLS_CIPHER_OPTION_CONFLICT, MLLP_TLS_DH_PARAMETERS_REJECTED, MLLP_TLS_VERIFY_DISABLED, type MessageMeta, MllpAckError, MllpApplicationAckError, MllpBackpressureError, MllpClient, MllpCommitRejectedError, MllpConnectionError, MllpDifferentialConfigurationError, MllpFramingError, MllpNeverDeliveredError, MllpServer, MllpTimeoutError, MllpTlsConfigurationError, MllpUnknownFateError, type MllpWarning, type NackAckCode, type NackEvent, type NackReason, type NegativeAckCode, type NegotiatedTlsParameters, NetTransport, type PemInput, type ReconnectingEvent, type ResolvedTlsCipherPolicy, type RetryContext, type RetryStrategy, type SecurityWarning, type SecurityWarningCode, type ServerOptions, type ServerStats, type ServerTlsOptions, type StarterClientOptions, type StarterServerOptions, type StateChangeEvent, TLS13_DEFAULT_CIPHER_SUITES, type TlsCipherPolicyInput, type TlsConfigurationErrorCode, type TlsOptions, TlsTransport, Transport, VERSION, type WarningCode, ackDiagnosticMessage, ackModeDiagnosticMessage, buildRawAck, canonicalAcknowledgement, canonicalExchanges, createClient, createServer, createStarterClient, createStarterServer, createWarning, differentialConfigurationMessage, encodeFrame, isTlsProtocolError, isTlsVerificationErrorCode, isTransientConnectionError, rawAckUncorrelatable, readNegotiatedTlsParameters, resolveDifferentialPeer, resolveNackCode, resolveTlsCipherPolicy, runDifferential, tlsConfigurationMessage };