@cosyte/mllp 0.0.10 → 0.1.0

package/dist/index.mjs

@@ -1,7 +1,7 @@
+import { createSecureContext, createServer as createServer$2, connect } from 'tls';
 import { EventEmitter } from 'events';
 import { randomUUID } from 'crypto';
-import { createServer as createServer$2, createConnection, isIP, SocketAddress } from 'net';
-import { createServer as createServer$1, connect } from 'tls';
+import { createServer as createServer$1, createConnection, isIP, SocketAddress } from 'net';
 
 // src/framing/registry.ts
 function createWarning(code, byteOffset, message) {
@@ -508,6 +508,241 @@ var TlsTransport = class {
 var MLLP_TLS_VERIFY_DISABLED = "MLLP_TLS_VERIFY_DISABLED";
 var MLLP_BIND_ALL_INTERFACES = "MLLP_BIND_ALL_INTERFACES";
 
+// src/transport/error.ts
+var MLLP_TLS_CIPHER_LIST_REJECTED = "MLLP_TLS_CIPHER_LIST_REJECTED";
+var MLLP_TLS_CIPHER_OPTION_CONFLICT = "MLLP_TLS_CIPHER_OPTION_CONFLICT";
+var MLLP_TLS_DH_PARAMETERS_REJECTED = "MLLP_TLS_DH_PARAMETERS_REJECTED";
+var TLS_CONFIGURATION_MESSAGES = Object.freeze({
+  [MLLP_TLS_CIPHER_LIST_REJECTED]: "the TLS library rejected the configured cipher-suite list; no connection was opened and no fallback to the runtime default list was made",
+  [MLLP_TLS_CIPHER_OPTION_CONFLICT]: "tls.atnaTransportSecurity and tls.ciphers both declare the offered cipher-suite list; set exactly one of them",
+  [MLLP_TLS_DH_PARAMETERS_REJECTED]: "the configured ephemeral Diffie-Hellman parameters are not usable; nothing was bound and no fallback to a server without Diffie-Hellman parameters was made"
+});
+function tlsConfigurationMessage(code) {
+  return TLS_CONFIGURATION_MESSAGES[code];
+}
+var MllpTlsConfigurationError = class _MllpTlsConfigurationError extends Error {
+  name = "MllpTlsConfigurationError";
+  /**
+   * The stable configuration-error code. Public API; branch on this rather
+   * than on the message.
+   */
+  code;
+  /**
+   * The TLS library's own error, when the runtime is what refused the list.
+   * `undefined` when this package refused the configuration itself.
+   */
+  cause;
+  /**
+   * 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, opts) {
+    super(tlsConfigurationMessage(code));
+    this.code = code;
+    this.cause = opts?.cause;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _MllpTlsConfigurationError);
+    }
+  }
+};
+
+// src/transport/dh-parameters.ts
+var BEGIN_BOUNDARY = "-----BEGIN DH PARAMETERS-----";
+var END_BOUNDARY = "-----END DH PARAMETERS-----";
+var BOM_SPELLINGS = [
+  String.fromCharCode(65279),
+  String.fromCharCode(239, 187, 191)
+];
+var BASE64_BODY = /^[A-Za-z0-9+/]+={0,2}$/;
+var DER_SEQUENCE = 48;
+var DER_INTEGER = 2;
+var INT32_CONTENT_OCTETS = 4;
+function readDerElement(der, offset) {
+  if (offset + 2 > der.length) return null;
+  const tag = der[offset];
+  const first = der[offset + 1];
+  if (tag === void 0 || first === void 0) return null;
+  let contentStart;
+  let length;
+  if (first < 128) {
+    contentStart = offset + 2;
+    length = first;
+  } else {
+    const lengthBytes = first & 127;
+    if (lengthBytes === 0 || lengthBytes > 4) return null;
+    if (offset + 2 + lengthBytes > der.length) return null;
+    length = 0;
+    for (let i = 0; i < lengthBytes; i += 1) {
+      const byte = der[offset + 2 + i];
+      if (byte === void 0) return null;
+      length = length * 256 + byte;
+    }
+    contentStart = offset + 2 + lengthBytes;
+  }
+  const contentEnd = contentStart + length;
+  if (contentEnd > der.length) return null;
+  return { tag, contentStart, contentEnd };
+}
+function readsAsInt32(der, element) {
+  const octets = element.contentEnd - element.contentStart;
+  if (octets > INT32_CONTENT_OCTETS) return false;
+  if (octets < 2) return true;
+  const first = der[element.contentStart];
+  const second = der[element.contentStart + 1];
+  if (first === void 0 || second === void 0) return false;
+  const secondIsNegative = (second & 128) !== 0;
+  if (first === 0 && !secondIsNegative) return false;
+  if (first === 255 && secondIsNegative) return false;
+  return true;
+}
+function magnitudeOf(der, element) {
+  let start = element.contentStart;
+  while (start + 1 < element.contentEnd && der[start] === 0) start += 1;
+  return der.subarray(start, element.contentEnd);
+}
+function compareMagnitudes(left, right) {
+  if (left.length !== right.length) return left.length < right.length ? -1 : 1;
+  return Buffer.compare(left, right);
+}
+function isOneBelow(value, oddPrime) {
+  if (value.length !== oddPrime.length) return false;
+  const last = value.length - 1;
+  for (let i = 0; i < last; i += 1) {
+    if (value[i] !== oddPrime[i]) return false;
+  }
+  const tail = value[last];
+  const primeTail = oddPrime[last];
+  return tail !== void 0 && primeTail !== void 0 && tail === primeTail - 1;
+}
+function isUsableGroup(der, prime, generator) {
+  const primeValue = magnitudeOf(der, prime);
+  const generatorValue = magnitudeOf(der, generator);
+  const lowest = primeValue[primeValue.length - 1];
+  if (lowest === void 0 || (lowest & 1) === 0) return false;
+  const smallest = generatorValue[0];
+  if (generatorValue.length === 1 && (smallest === void 0 || smallest < 2)) return false;
+  if (compareMagnitudes(generatorValue, primeValue) >= 0) return false;
+  return !isOneBelow(generatorValue, primeValue);
+}
+function sanitizeLine(line) {
+  let end = line.length;
+  while (end > 0 && line.charCodeAt(end - 1) <= 32) end -= 1;
+  return line.slice(0, end);
+}
+function readArmouredBody(text) {
+  let head = text;
+  for (const bom of BOM_SPELLINGS) {
+    if (head.startsWith(bom)) {
+      head = head.slice(bom.length);
+      break;
+    }
+  }
+  const lines = head.split("\n").map(sanitizeLine);
+  const begin = lines.indexOf(BEGIN_BOUNDARY);
+  if (begin === -1) return null;
+  const end = lines.indexOf(END_BOUNDARY, begin + 1);
+  if (end === -1) return null;
+  const inner = lines.slice(begin + 1, end);
+  const blank = inner.indexOf("");
+  if (blank !== -1) {
+    if (blank !== 0) return null;
+    if (inner.indexOf("", 1) !== -1) return null;
+  }
+  const body = inner.join("").replace(/\s+/g, "");
+  return body.length === 0 ? null : body;
+}
+function isDhParametersPem(input) {
+  const text = typeof input === "string" ? input : input.toString("latin1");
+  const body = readArmouredBody(text);
+  if (body === null) return false;
+  if (body.length % 4 !== 0 || !BASE64_BODY.test(body)) return false;
+  const der = Buffer.from(body, "base64");
+  const sequence = readDerElement(der, 0);
+  if (sequence === null || sequence.tag !== DER_SEQUENCE) return false;
+  if (sequence.contentEnd !== der.length) return false;
+  const prime = readDerElement(der, sequence.contentStart);
+  if (prime === null || prime.tag !== DER_INTEGER) return false;
+  const generator = readDerElement(der, prime.contentEnd);
+  if (generator === null || generator.tag !== DER_INTEGER) return false;
+  if (prime.contentEnd === prime.contentStart) return false;
+  if (generator.contentEnd === generator.contentStart) return false;
+  if (!isUsableGroup(der, prime, generator)) return false;
+  if (generator.contentEnd === sequence.contentEnd) return true;
+  const privateValueLength = readDerElement(der, generator.contentEnd);
+  if (privateValueLength === null || privateValueLength.tag !== DER_INTEGER) return false;
+  if (privateValueLength.contentEnd !== sequence.contentEnd) return false;
+  return readsAsInt32(der, privateValueLength);
+}
+
+// src/transport/tls-cipher-policy.ts
+var ATNA_CIPHER_SUITES = Object.freeze([
+  "DHE-RSA-AES128-GCM-SHA256",
+  "ECDHE-RSA-AES128-GCM-SHA256",
+  "DHE-RSA-AES256-GCM-SHA384",
+  "ECDHE-RSA-AES256-GCM-SHA384"
+]);
+var TLS13_DEFAULT_CIPHER_SUITES = Object.freeze([
+  "TLS_AES_256_GCM_SHA384",
+  "TLS_CHACHA20_POLY1305_SHA256",
+  "TLS_AES_128_GCM_SHA256"
+]);
+var ATNA_CIPHER_LIST = [
+  ...TLS13_DEFAULT_CIPHER_SUITES,
+  ...ATNA_CIPHER_SUITES
+].join(":");
+function assertUsableDhParameters(dhParameters) {
+  if (!isDhParametersPem(dhParameters)) {
+    throw new MllpTlsConfigurationError(MLLP_TLS_DH_PARAMETERS_REJECTED);
+  }
+  try {
+    createSecureContext({ dhparam: dhParameters });
+  } catch (err) {
+    throw new MllpTlsConfigurationError(MLLP_TLS_DH_PARAMETERS_REJECTED, {
+      cause: err instanceof Error ? err : new Error(String(err))
+    });
+  }
+}
+function resolveTlsCipherPolicy(opts, side) {
+  const atna = opts.atnaTransportSecurity === true;
+  if (atna && opts.ciphers !== void 0) {
+    throw new MllpTlsConfigurationError(MLLP_TLS_CIPHER_OPTION_CONFLICT);
+  }
+  const ciphers = atna ? ATNA_CIPHER_LIST : opts.ciphers;
+  const supplied = side === "server" ? opts.dhParameters : void 0;
+  if (supplied !== void 0) assertUsableDhParameters(supplied);
+  const dhparam = supplied ?? (atna && side === "server" ? "auto" : void 0);
+  if (ciphers !== void 0) {
+    try {
+      createSecureContext({ ciphers });
+    } catch (err) {
+      throw new MllpTlsConfigurationError(MLLP_TLS_CIPHER_LIST_REJECTED, {
+        cause: err instanceof Error ? err : new Error(String(err))
+      });
+    }
+  }
+  if (ciphers === void 0) return dhparam === void 0 ? {} : { dhparam };
+  return dhparam === void 0 ? { ciphers } : { ciphers, dhparam };
+}
+
+// src/transport/negotiated-tls.ts
+function readNegotiatedTlsParameters(socket, host, port) {
+  if (!("getProtocol" in socket)) return null;
+  const protocolVersion = socket.getProtocol();
+  if (protocolVersion === null) return null;
+  const cipher = socket.getCipher();
+  const cipherSuite = cipher.standardName === "" ? cipher.name : cipher.standardName;
+  if (cipherSuite === "") return null;
+  return Object.freeze({
+    protocolVersion,
+    cipherSuite,
+    host,
+    port,
+    timestamp: /* @__PURE__ */ new Date()
+  });
+}
+
 // src/connection/error.ts
 var MllpConnectionError = class _MllpConnectionError extends Error {
   name = "MllpConnectionError";
@@ -1057,13 +1292,18 @@ function readMshSegment(buf) {
   const fields = buf.subarray(at.start, at.end).toString(CONTROL_ID_ENCODING).split(fieldSep);
   return { fieldSep, fields };
 }
-function extractMshControlId(buf) {
-  const msh = readMshSegment(buf);
+function controlIdFromMsh(msh) {
   if (msh === null) return null;
   const id = msh.fields[9];
   return id === void 0 || id === "" ? null : id;
 }
 function extractMsaControlId(buf) {
+  const msa = readMsaSegment(buf);
+  if (msa === null) return null;
+  const id = msa.fields[2];
+  return id === void 0 || id === "" ? null : id;
+}
+function readMsaSegment(buf) {
   const msh = readMshSegment(buf);
   if (msh === null) return null;
   const fieldSep = msh.fieldSep.charCodeAt(0);
@@ -1075,21 +1315,8 @@ function extractMsaControlId(buf) {
       segEnd++;
     }
     if (segEnd - segStart >= 4 && buf[segStart] === ASCII_M && buf[segStart + 1] === ASCII_S && buf[segStart + 2] === ASCII_A && buf[segStart + 3] === fieldSep) {
-      let fieldIndex = 0;
-      let fieldStart = 0;
-      for (let i = segStart + 3; i <= segEnd; i++) {
-        const b = i < segEnd ? buf[i] : fieldSep;
-        if (b === fieldSep || b === SEGMENT_SEPARATOR_CR || b === SEGMENT_SEPARATOR_LF) {
-          fieldIndex++;
-          if (fieldIndex === 2) {
-            fieldStart = i + 1;
-          } else if (fieldIndex === 3) {
-            if (fieldStart >= i) return null;
-            return buf.subarray(fieldStart, i).toString(CONTROL_ID_ENCODING);
-          }
-        }
-      }
-      return null;
+      const fields = buf.subarray(segStart, segEnd).toString(CONTROL_ID_ENCODING).split(msh.fieldSep);
+      return { fieldSep: msh.fieldSep, fields };
     }
     while (segEnd < end && (buf[segEnd] === SEGMENT_SEPARATOR_CR || buf[segEnd] === SEGMENT_SEPARATOR_LF)) {
       segEnd++;
@@ -1180,6 +1407,125 @@ function timestamp14() {
   return String(d.getUTCFullYear()) + pad(d.getUTCMonth() + 1) + pad(d.getUTCDate()) + pad(d.getUTCHours()) + pad(d.getUTCMinutes()) + pad(d.getUTCSeconds());
 }
 
+// src/internal/ack-mode.ts
+var TABLE_0155 = Object.freeze(["AL", "NE", "ER", "SU"]);
+var TABLE_0008 = Object.freeze(["AA", "AE", "AR", "CA", "CE", "CR"]);
+var MSH_15_INDEX = 14;
+var MSH_16_INDEX = 15;
+var SPACE = " ";
+function delimitersFrom(encodingCharacters) {
+  const chars = encodingCharacters ?? "";
+  return {
+    componentSep: chars.length >= 1 ? chars.charAt(0) : null,
+    repetitionSep: chars.length >= 2 ? chars.charAt(1) : null
+  };
+}
+function trimSpaces(value) {
+  let start = 0;
+  let end = value.length;
+  while (start < end && value.charAt(start) === SPACE) start++;
+  while (end > start && value.charAt(end - 1) === SPACE) end--;
+  return value.substring(start, end);
+}
+function readTableField(raw, delimiters, table) {
+  if (raw === void 0) return { kind: "null", byteLength: 0 };
+  const byteLength = raw.length;
+  let value = raw;
+  if (delimiters.repetitionSep !== null) {
+    const at = value.indexOf(delimiters.repetitionSep);
+    if (at !== -1) value = value.substring(0, at);
+  }
+  if (delimiters.componentSep !== null) {
+    const at = value.indexOf(delimiters.componentSep);
+    if (at !== -1) value = value.substring(0, at);
+  }
+  value = trimSpaces(value);
+  if (value === "" || value === '""') return { kind: "null", byteLength };
+  for (const code of table) {
+    if (code === value) return { kind: "code", code, byteLength };
+  }
+  return { kind: "unrecognised", byteLength };
+}
+var ORIGINAL_MODE = Object.freeze({
+  enhanced: false,
+  acceptCondition: "NE",
+  applicationCondition: "AL",
+  awaitsApplicationAck: false,
+  acceptFieldUnrecognised: false,
+  applicationFieldUnrecognised: false
+});
+function classifyOutboundAckMode(msh) {
+  if (msh === null) return ORIGINAL_MODE;
+  const delimiters = delimitersFrom(msh.fields[1]);
+  const accept = readTableField(msh.fields[MSH_15_INDEX], delimiters, TABLE_0155);
+  const application = readTableField(msh.fields[MSH_16_INDEX], delimiters, TABLE_0155);
+  if (accept.kind === "null" && application.kind === "null") return ORIGINAL_MODE;
+  const applicationCondition = application.kind === "code" ? application.code : "AL";
+  return Object.freeze({
+    enhanced: true,
+    acceptCondition: accept.kind === "code" ? accept.code : "NE",
+    applicationCondition,
+    awaitsApplicationAck: applicationCondition !== "NE",
+    acceptFieldUnrecognised: accept.kind === "unrecognised",
+    applicationFieldUnrecognised: application.kind === "unrecognised"
+  });
+}
+function readAcceptCondition(msh) {
+  if (msh === null) return { kind: "null", byteLength: 0 };
+  return readTableField(msh.fields[MSH_15_INDEX], delimitersFrom(msh.fields[1]), TABLE_0155);
+}
+function classifyMsa1(ackPayload) {
+  const msh = readMshSegment(ackPayload);
+  if (msh === null) return { kind: "unclassifiable", byteLength: 0 };
+  const msa = readMsaSegment(ackPayload);
+  if (msa === null) return { kind: "null", byteLength: 0 };
+  const read = readTableField(msa.fields[1], delimitersFrom(msh.fields[1]), TABLE_0008);
+  if (read.kind === "code") return { kind: "code", code: read.code, byteLength: read.byteLength };
+  if (read.kind === "null") return { kind: "null", byteLength: read.byteLength };
+  return { kind: "unclassifiable", byteLength: read.byteLength };
+}
+function acceptAckRequested(accept, disposition) {
+  if (accept.kind !== "code") return false;
+  switch (accept.code) {
+    case "AL":
+      return true;
+    case "NE":
+      return false;
+    case "ER":
+      return disposition === "AE" || disposition === "AR";
+    case "SU":
+      return disposition === "AA";
+  }
+}
+function acceptModeCounterpart(code) {
+  switch (code) {
+    case "AA":
+      return "CA";
+    case "AE":
+      return "CE";
+    case "AR":
+      return "CR";
+    case "CA":
+    case "CE":
+    case "CR":
+      return code;
+  }
+}
+
+// src/internal/ack-mode-diagnostics.ts
+var ACK_MODE_MESSAGES = Object.freeze({
+  MLLP_ACK_ACCEPT_TYPE_UNRECOGNISED: "MSH-15 (accept acknowledgment type) carried a value outside HL7 Table 0155; it was read as the table's default and the message was transmitted or answered unchanged. Field values are withheld: a field value is payload content and this diagnostic goes to a log.",
+  MLLP_ACK_APPLICATION_TYPE_UNRECOGNISED: "MSH-16 (application acknowledgment type) carried a value outside HL7 Table 0155; it was read as the table's default and the message was transmitted unchanged. Field values are withheld: a field value is payload content and this diagnostic goes to a log.",
+  MLLP_ACK_TWO_PHASE_UNAVAILABLE: "An enhanced-mode send was made on a client that correlates acknowledgements in order rather than by control ID, so two-phase correlation was not applied and the first acknowledgement matched to this send settles it. Set correlateByControlId to enable it.",
+  MLLP_ACK_COMMIT_ALREADY_REPORTED: "A further commit-accept acknowledgement arrived for a send whose commit disposition had already been reported; it was surfaced and neither re-reported nor allowed to restart the application-acknowledgement wait. The send is still pending.",
+  MLLP_ACK_MSA1_ABSENT: "An acknowledgement matched to an enhanced-mode send carried no MSA-1 acknowledgement code, so it was not classified into a mode and the send was left pending. Field values are withheld; msa1Bytes gives the field's length.",
+  MLLP_ACK_MSA1_UNCLASSIFIABLE: "An acknowledgement matched to an enhanced-mode send carried an MSA-1 value outside HL7 Table 0008, so it was not classified into a mode and the send was left pending. Field values are withheld; msa1Bytes gives the field's length.",
+  MLLP_ACK_SEND_ALREADY_DISPOSED: "An acknowledgement arrived for a send that had already been settled or failed; it was dropped and that outcome was left unchanged. Field values are withheld: a control ID is payload content and this diagnostic goes to a log."
+});
+function ackModeDiagnosticMessage(code) {
+  return ACK_MODE_MESSAGES[code];
+}
+
 // src/internal/safe-emit.ts
 function safeEmit(emitter, event, payload, onSubscriberThrow) {
   try {
@@ -1242,6 +1588,16 @@ var MllpServer = class extends EventEmitter {
   _closedTotal = 0;
   /** Count of `'tlsClientError'` events since listen(). */
   _tlsClientErrorsTotal = 0;
+  /**
+   * 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.
+   */
+  _tlsConfigError = null;
   /**
    * Construct an MLLP server. Created idle; call `listen()` (or use
    * {@link createServer}/{@link createStarterServer}) to begin accepting connections.
@@ -1252,17 +1608,28 @@ var MllpServer = class extends EventEmitter {
     super();
     this._opts = opts;
     this._isTls = opts.tls !== void 0;
+    let cipherPolicy = null;
     if (opts.tls !== void 0) {
+      try {
+        cipherPolicy = resolveTlsCipherPolicy(opts.tls, "server");
+      } catch (err) {
+        if (!(err instanceof MllpTlsConfigurationError)) throw err;
+        this._tlsConfigError = err;
+      }
+    }
+    if (opts.tls !== void 0 && cipherPolicy === null) {
+      this._netServer = createServer$1();
+    } else if (opts.tls !== void 0 && cipherPolicy !== null) {
       const tlsOpts = opts.tls;
       const clientAuth = tlsOpts.clientAuth ?? "NONE";
-      const tlsServer = createServer$1({
+      const tlsServer = createServer$2({
         cert: tlsOpts.cert,
         key: tlsOpts.key,
         ...tlsOpts.ca !== void 0 ? { ca: tlsOpts.ca } : {},
         ...tlsOpts.passphrase !== void 0 ? { passphrase: tlsOpts.passphrase } : {},
         minVersion: tlsOpts.minVersion ?? "TLSv1.2",
         ...tlsOpts.maxVersion !== void 0 ? { maxVersion: tlsOpts.maxVersion } : {},
-        ...tlsOpts.ciphers !== void 0 ? { ciphers: tlsOpts.ciphers } : {},
+        ...cipherPolicy,
         requestCert: clientAuth !== "NONE",
         rejectUnauthorized: clientAuth === "MUST"
       });
@@ -1283,7 +1650,7 @@ var MllpServer = class extends EventEmitter {
         this._emitContained("tlsClientError", event);
       });
     } else {
-      this._netServer = createServer$2();
+      this._netServer = createServer$1();
       this._netServer.on("connection", (socket) => {
         this._onSocketAccepted(socket);
       });
@@ -1308,6 +1675,14 @@ var MllpServer = class 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
@@ -1336,6 +1711,9 @@ var MllpServer = class extends EventEmitter {
     if (signal?.aborted) {
       return Promise.reject(new DOMException("Aborted", "AbortError"));
     }
+    if (this._tlsConfigError !== null) {
+      return Promise.reject(this._tlsConfigError);
+    }
     if (this._listening || this._listenInFlight) {
       return Promise.reject(
         new MllpConnectionError(
@@ -1730,6 +2108,10 @@ var MllpServer = class extends EventEmitter {
         peerCertificate
       })
     );
+    const negotiated = readNegotiatedTlsParameters(socket, this._host ?? "", this._port ?? 0);
+    if (negotiated !== null) {
+      this._emitContained("tlsNegotiated", negotiated);
+    }
   }
   /**
    * Extract a minimal, content-free peer-certificate summary (ATNA ITI-19
@@ -1773,25 +2155,26 @@ var MllpServer = class extends EventEmitter {
    */
   async _sendCommitAck(payload, meta, conn) {
     const handler = this._opts.onMessage;
+    const selectCode = this._ackModeSelector(payload, conn);
     if (handler === void 0) {
       this._dispatchAck(
         conn,
-        buildRawAck(payload, this._resolveAutoAckPositive(payload, meta, conn))
+        buildRawAck(payload, this._resolveAutoAckPositive(payload, meta, conn, selectCode))
       );
       return;
     }
     let code;
     try {
       await handler(payload, meta, conn);
-      code = this._resolveAutoAckPositive(payload, meta, conn);
+      code = this._resolveAutoAckPositive(payload, meta, conn, selectCode);
     } catch (err) {
       const nack = resolveNackCode(err);
-      code = nack;
+      code = selectCode(nack);
       this._emitContained(
         "nack",
         Object.freeze({
           connectionId: conn.connectionId,
-          ackCode: nack,
+          ackCode: code,
           reason: "handler-rejected"
         })
       );
@@ -1821,21 +2204,82 @@ var MllpServer = class 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.
    */
-  _resolveAutoAckPositive(payload, meta, conn) {
+  _resolveAutoAckPositive(payload, meta, conn, selectCode) {
     const discarded = meta.warnings.some((w) => w.code === "MLLP_TRAILING_BYTES");
     const uncorrelatable = rawAckUncorrelatable(payload);
-    if (!discarded && !uncorrelatable) return "AA";
+    if (!discarded && !uncorrelatable) return selectCode("AA");
     const reason = discarded ? "discarded-bytes" : "uncorrelatable-inbound";
+    const code = selectCode("AE");
     this._emitContained(
       "nack",
       Object.freeze({
         connectionId: conn.connectionId,
-        ackCode: "AE",
+        ackCode: code,
         reason
       })
     );
-    return "AE";
+    return code;
+  }
+  /**
+   * 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.
+   */
+  _ackModeSelector(payload, conn) {
+    const identity = (disposition) => disposition;
+    const msh = readMshSegment(payload);
+    if (msh === null) return identity;
+    const accept = readAcceptCondition(msh);
+    if (accept.kind === "unrecognised") {
+      this._emitAckModeWarning("MLLP_ACK_ACCEPT_TYPE_UNRECOGNISED", conn);
+      return identity;
+    }
+    if (accept.kind === "null") return identity;
+    if (containsBatchOrExtraMessage(payload)) return identity;
+    return (disposition) => acceptAckRequested(accept, disposition) ? acceptModeCounterpart(disposition) : disposition;
+  }
+  /**
+   * 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.
+   */
+  _emitAckModeWarning(code, conn) {
+    const event = Object.freeze({
+      connectionId: conn.connectionId,
+      code,
+      message: ackModeDiagnosticMessage(code),
+      timestamp: /* @__PURE__ */ new Date()
+    });
+    this._emitContained("ackModeWarning", event);
   }
   /**
    * Run `onMessage` for its side effects only (custom-ACK and manual modes), guarding
@@ -1931,6 +2375,18 @@ var Correlator = class {
   _opts;
   _pending = /* @__PURE__ */ new Map();
   _graveyard = /* @__PURE__ */ new Map();
+  /**
+   * Control IDs of two-phase sends already disposed of (settled or failed), with the epoch
+   * ms at which that happened.
+   *
+   * Separate from the graveyard, and separate on purpose. The graveyard is a memory of
+   * **timed-out** sends and is evicted one-shot, on the first late acknowledgement that
+   * hits it. This one is a memory of **every** disposal and is evicted by elapsed time
+   * alone, so a peer that repeats an acknowledgement twice inside the window is told
+   * "already disposed" both times rather than "already disposed" and then "no such send".
+   * The two windows are the same length; only the eviction rules differ.
+   */
+  _disposed = /* @__PURE__ */ new Map();
   _sendSeq = 0;
   _queueBytes = 0;
   /**
@@ -1952,6 +2408,10 @@ var Correlator = class {
       onWarning: opts.onWarning,
       onTimeout: opts.onTimeout,
       onUnmatchedAck: opts.onUnmatchedAck,
+      onAckModeWarning: opts.onAckModeWarning,
+      onCommitReported: opts.onCommitReported,
+      onCommitRejected: opts.onCommitRejected,
+      onApplicationAckTimeout: opts.onApplicationAckTimeout,
       now: opts.now ?? Date.now
     };
   }
@@ -1967,12 +2427,20 @@ var Correlator = class {
   get graveyardSize() {
     return this._graveyard.size;
   }
+  /** Number of disposed two-phase sends still inside their remembered window. */
+  get disposedSize() {
+    return this._disposed.size;
+  }
   /**
    * Enqueue a new send awaiting its ACK. Returns the assigned
    * `correlationKey`, or `null` if `maxInFlight` is reached (caller awaits
    * drain, `pipeline:false`).
+   *
+   * `twoPhase` is the enhanced-mode state for a send being correlated by control ID.
+   * Omitting it (or passing `null`) is what every other send does, and such an entry is
+   * settled by the first acknowledgement matched to it, exactly as before.
    */
-  enqueue(frame, controlIdOrNull, resolve, reject) {
+  enqueue(frame, controlIdOrNull, resolve, reject, twoPhase = null) {
     if (this._pending.size >= this._opts.maxInFlight) return null;
     const key = this._opts.mode === "controlId" ? controlIdOrNull ?? `__seq-${++this._sendSeq}` : ++this._sendSeq;
     const entry = {
@@ -1982,7 +2450,8 @@ var Correlator = class {
       byteCount: frame.length,
       sentAt: null,
       resolve,
-      reject
+      reject,
+      twoPhase
     };
     this._pending.set(key, entry);
     this._queueBytes += frame.length;
@@ -2008,15 +2477,19 @@ var Correlator = class {
    *   and returns `null`; otherwise fires `onUnmatchedAck` with the id's
    *   **byte length** and returns `null`.
    *
+   * A live-store hit on a **two-phase** entry is decided by the acknowledgement's MSA-1
+   * instead, see {@link Correlator.matchTwoPhase}.
+   *
    * Triggers lazy graveyard eviction.
    *
-   * @param _payload Inbound ACK bytes (framing stripped). MSA-2 extraction
+   * @param payload Inbound ACK bytes (framing stripped). MSA-2 extraction
    *   happens at MllpClient's `_onAckPayload` hook; this method takes the
-   *   already-extracted control ID as a parameter.
+   *   already-extracted control ID as a parameter. The bytes themselves are read
+   *   only for a two-phase entry's MSA-1.
    * @param controlIdFromAck MSA-2 extracted from ACK (controlId mode only).
    * @param byteOffsetFromAck Stream offset; forwarded to `onWarning`.
    */
-  matchAck(_payload, controlIdFromAck = null, byteOffsetFromAck = 0) {
+  matchAck(payload, controlIdFromAck = null, byteOffsetFromAck = 0) {
     this._evictGraveyardDue(this._opts.now());
     if (this._opts.mode === "fifo") {
       const iter = this._pending.values().next();
@@ -2035,11 +2508,25 @@ var Correlator = class {
     }
     const live = this._pending.get(controlIdFromAck);
     if (live !== void 0) {
+      if (live.twoPhase !== null) {
+        return this.matchTwoPhase(live, payload, byteOffsetFromAck);
+      }
       this._pending.delete(controlIdFromAck);
       this._queueBytes -= live.byteCount;
       if (live.sentAt !== null) this._inFlight -= 1;
       return live;
     }
+    const disposedAt = this._disposed.get(controlIdFromAck);
+    if (disposedAt !== void 0) {
+      this._ackModeWarn("MLLP_ACK_SEND_ALREADY_DISPOSED", {
+        msa1Bytes: null,
+        ackCode: null,
+        controlIdBytes: controlIdFromAck.length,
+        byteOffset: byteOffsetFromAck,
+        elapsedSinceSendMs: this._opts.now() - disposedAt
+      });
+      return null;
+    }
     const grave = this._graveyard.get(controlIdFromAck);
     if (grave !== void 0) {
       const elapsedSinceSendMs = this._opts.now() - grave.timedOutAt;
@@ -2058,25 +2545,127 @@ var Correlator = class {
     }
     return null;
   }
+  /**
+   * Decide what an acknowledgement matched to a **two-phase** send does to it, from its
+   * MSA-1 and from nothing else. No other property of the acknowledgement, its length, its
+   * MSH-9 or its other segments, takes part.
+   *
+   * Six outcomes, one per classification:
+   *
+   *   * `AA`, `AE` or `AR`: the application acknowledgement. It **settles** the send,
+   *     whether or not an accept-mode acknowledgement was seen first, and all three settle
+   *     it the same way, successfully, with the acknowledgement handed to the caller. `AE`
+   *     and `AR` are the receiving application's clinical verdict on a message it did take
+   *     custody of, and judging that verdict is not this package's job. The caller reads
+   *     MSA-1 off the acknowledgement it is given.
+   *   * `CA` on a send awaiting no application acknowledgement: it **settles** the send.
+   *     MSH-15 `AL` with MSH-16 `NE` is a legal pair and a peer answering it with one `CA`
+   *     has done exactly what was asked.
+   *   * `CA` on a send awaiting one: **reported, not settled.** The send stays pending and
+   *     its second wait starts here.
+   *   * a second `CA` on a send already reported: surfaced, and neither re-reported nor
+   *     allowed to restart the second wait.
+   *   * `CE` or `CR`: the peer refused custody of the bytes, so no application
+   *     acknowledgement is coming. The send **fails now**, whatever its application
+   *     condition and whether or not a `CA` was already reported. Waiting out the second
+   *     window would report the same failure later and less precisely.
+   *   * NULL or unclassifiable: surfaced with a code that distinguishes the two, and the
+   *     send is left pending until its outstanding wait expires. An acknowledgement that
+   *     cannot be classified into a mode is not guessed.
+   *
+   * Returns the entry when it is to be settled (the caller resolves it), `null` otherwise.
+   */
+  matchTwoPhase(entry, payload, byteOffsetFromAck) {
+    const twoPhase = entry.twoPhase;
+    if (twoPhase === null) return entry;
+    const now = this._opts.now();
+    const classification = classifyMsa1(payload);
+    const elapsedSinceSendMs = entry.sentAt === null ? 0 : now - entry.sentAt;
+    const controlIdBytes = entry.controlId === null ? null : entry.controlId.length;
+    if (classification.kind === "code") {
+      const code = classification.code;
+      if (code === "AA" || code === "AE" || code === "AR") {
+        this._disposeTwoPhase(entry, now);
+        return entry;
+      }
+      if (code === "CE" || code === "CR") {
+        this._disposeTwoPhase(entry, now);
+        this._opts.onCommitRejected?.(entry, code);
+        return null;
+      }
+      if (!twoPhase.awaitsApplicationAck) {
+        this._disposeTwoPhase(entry, now);
+        return entry;
+      }
+      if (twoPhase.commitCode !== null) {
+        this._ackModeWarn("MLLP_ACK_COMMIT_ALREADY_REPORTED", {
+          msa1Bytes: classification.byteLength,
+          ackCode: code,
+          controlIdBytes,
+          byteOffset: byteOffsetFromAck,
+          elapsedSinceSendMs
+        });
+        return null;
+      }
+      twoPhase.commitCode = code;
+      twoPhase.commitReceivedAt = now;
+      this._opts.onCommitReported?.(entry, payload, elapsedSinceSendMs);
+      return null;
+    }
+    this._ackModeWarn(
+      classification.kind === "null" ? "MLLP_ACK_MSA1_ABSENT" : "MLLP_ACK_MSA1_UNCLASSIFIABLE",
+      {
+        msa1Bytes: classification.byteLength,
+        ackCode: null,
+        controlIdBytes,
+        byteOffset: byteOffsetFromAck,
+        elapsedSinceSendMs
+      }
+    );
+    return null;
+  }
   /**
    * Sweep live entries; expire those past `sentAt + ackTimeoutMs`.
    * Fires `onTimeout(entry, elapsedMs)`; entries move to graveyard.
    * Driven externally by `MllpClient`'s periodic sweep tick, Correlator
    * itself owns no timers.
+   *
+   * A two-phase entry whose accept acknowledgement has arrived is bounded by the **second**
+   * window instead, measured from that acknowledgement: the first-acknowledgement timeout
+   * is stopped, so it can no longer expire against a send the peer has already answered.
+   * Both windows are finite, so no send waits forever either way.
    */
   expireDue(now) {
     const t = now ?? this._opts.now();
     const ackTimeoutMs = this._opts.ackTimeoutMs;
     for (const [key, entry] of this._pending) {
-      if (entry.sentAt !== null && entry.sentAt + ackTimeoutMs <= t) {
+      if (entry.sentAt === null) continue;
+      const twoPhase = entry.twoPhase;
+      const commitReceivedAt = twoPhase?.commitReceivedAt ?? null;
+      if (twoPhase !== null && commitReceivedAt !== null) {
+        if (commitReceivedAt + twoPhase.applicationAckTimeoutMs <= t) {
+          this._removeExpired(key, entry);
+          this._disposed.set(key, t);
+          const elapsed = t - commitReceivedAt;
+          if (this._opts.onApplicationAckTimeout !== void 0) {
+            this._opts.onApplicationAckTimeout(entry, elapsed);
+          } else {
+            this._opts.onTimeout(entry, elapsed);
+          }
+        }
+        continue;
+      }
+      if (entry.sentAt + ackTimeoutMs <= t) {
         const elapsed = t - entry.sentAt;
-        this._pending.delete(key);
-        this._queueBytes -= entry.byteCount;
-        this._inFlight -= 1;
-        this._graveyard.set(key, {
-          timedOutAt: t,
-          controlId: entry.controlId
-        });
+        this._removeExpired(key, entry);
+        if (twoPhase !== null) {
+          this._disposed.set(key, t);
+        } else {
+          this._graveyard.set(key, {
+            timedOutAt: t,
+            controlId: entry.controlId
+          });
+        }
         this._opts.onTimeout(entry, elapsed);
       }
     }
@@ -2085,9 +2674,17 @@ var Correlator = class {
    * Reject every live entry with `reason` (insertion order) and clear
    * the live store. Graveyard is left intact (ages out via lazy eviction).
    * Used by `MllpClient`'s correlator teardown to cancel pending sends.
+   *
+   * `reasonFor` lets the caller substitute a different error per entry, which is how a send
+   * whose commit disposition has already been reported is failed with an error that carries
+   * that disposition rather than with the generic one.
    */
-  clear(reason) {
-    for (const entry of this._pending.values()) entry.reject(reason);
+  clear(reason, reasonFor) {
+    const now = this._opts.now();
+    for (const entry of this._pending.values()) {
+      if (entry.twoPhase !== null) this._disposed.set(entry.key, now);
+      entry.reject(reasonFor === void 0 ? reason : reasonFor(entry, reason));
+    }
     this._pending.clear();
     this._queueBytes = 0;
     this._inFlight = 0;
@@ -2110,6 +2707,20 @@ var Correlator = class {
     if (entry.sentAt !== null) this._inFlight -= 1;
     return entry;
   }
+  /**
+   * Remove a live entry by key WITHOUT resolving/rejecting it, and remember that it was
+   * disposed of, so a later acknowledgement for it is answered "already disposed" rather
+   * than "no such send" for as long as the window lasts.
+   *
+   * The caller settles or fails the returned entry itself. Used where the client fails a
+   * send that had already drawn a commit disposition.
+   */
+  dispose(key) {
+    const entry = this.remove(key);
+    if (entry === null) return null;
+    if (entry.twoPhase !== null) this._disposed.set(key, this._opts.now());
+    return entry;
+  }
   /** JSON-serializable stats snapshot (no Buffers, no class instances). */
   getStats() {
     return {
@@ -2120,12 +2731,38 @@ var Correlator = class {
       inFlight: this._inFlight
     };
   }
-  /** Lazy graveyard eviction: drop entries past `timedOutAt + 2 * ackTimeoutMs`. */
+  /**
+   * Lazy eviction of both bounded memories: graveyard entries past
+   * `timedOutAt + 2 * ackTimeoutMs`, and disposed two-phase sends past
+   * `disposedAt + 2 * ackTimeoutMs`. Same window, so "already disposed" and "arrived after
+   * its timeout" are remembered for the same length of time, and past it both correctly
+   * read as "no such send". The memory is bounded, not perpetual.
+   */
   _evictGraveyardDue(now) {
     const threshold = 2 * this._opts.ackTimeoutMs;
     for (const [key, entry] of this._graveyard) {
       if (entry.timedOutAt + threshold <= now) this._graveyard.delete(key);
     }
+    for (const [key, disposedAt] of this._disposed) {
+      if (disposedAt + threshold <= now) this._disposed.delete(key);
+    }
+  }
+  /** Remove a live entry that has just expired, keeping the counters straight. */
+  _removeExpired(key, entry) {
+    this._pending.delete(key);
+    this._queueBytes -= entry.byteCount;
+    this._inFlight -= 1;
+  }
+  /** Drop a two-phase entry from the live store and remember that it was disposed of. */
+  _disposeTwoPhase(entry, now) {
+    this._pending.delete(entry.key);
+    this._queueBytes -= entry.byteCount;
+    if (entry.sentAt !== null) this._inFlight -= 1;
+    this._disposed.set(entry.key, now);
+  }
+  /** Emit an acknowledgement-mode diagnostic, when the caller wired a sink for them. */
+  _ackModeWarn(code, ctx) {
+    this._opts.onAckModeWarning?.(code, ctx);
   }
 };
 
@@ -2175,6 +2812,127 @@ var MllpTimeoutError = class _MllpTimeoutError extends Error {
     }
   }
 };
+var MllpApplicationAckError = class _MllpApplicationAckError extends Error {
+  name = "MllpApplicationAckError";
+  /** Why the wait ended. See {@link ApplicationAckFailure}. */
+  reason;
+  /** The commit disposition already received. Always the positive accept-mode code. */
+  commitCode;
+  /**
+   * 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}.
+   */
+  messageControlIdBytes;
+  /** Milliseconds between the accept acknowledgement and this failure. */
+  elapsedMs;
+  /** Epoch ms at which the accept acknowledgement was received. */
+  commitReceivedAt;
+  /**
+   * 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, opts) {
+    super(message);
+    this.reason = opts.reason;
+    this.commitCode = opts.commitCode;
+    this.messageControlIdBytes = opts.messageControlIdBytes;
+    this.elapsedMs = opts.elapsedMs;
+    this.commitReceivedAt = opts.commitReceivedAt;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _MllpApplicationAckError);
+    }
+  }
+};
+var MllpCommitRejectedError = class _MllpCommitRejectedError extends Error {
+  name = "MllpCommitRejectedError";
+  /** The negative accept-mode code the peer sent. */
+  commitCode;
+  /**
+   * 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.
+   */
+  messageControlIdBytes;
+  /** Milliseconds between the send's write-flush and this acknowledgement. */
+  elapsedMs;
+  /**
+   * 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, opts) {
+    super(message);
+    this.commitCode = opts.commitCode;
+    this.messageControlIdBytes = opts.messageControlIdBytes;
+    this.elapsedMs = opts.elapsedMs;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _MllpCommitRejectedError);
+    }
+  }
+};
+var NEVER_DELIVERED_MESSAGE = "delivery did not occur: the message was still held by the client and no bytes were written to the transport, so the peer never saw it";
+var UNKNOWN_FATE_MESSAGE = "fate unknown: the message was written to the transport and no acknowledgement arrived before the client finished closing, so whether the peer received it cannot be determined from here";
+var MllpNeverDeliveredError = class _MllpNeverDeliveredError extends Error {
+  name = "MllpNeverDeliveredError";
+  /** Byte count of the framed message this send would have written. */
+  byteCount;
+  /**
+   * 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}.
+   */
+  messageControlIdBytes;
+  /**
+   * 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) {
+    super(NEVER_DELIVERED_MESSAGE);
+    this.byteCount = opts.byteCount;
+    this.messageControlIdBytes = opts.messageControlIdBytes;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _MllpNeverDeliveredError);
+    }
+  }
+};
+var MllpUnknownFateError = class _MllpUnknownFateError extends Error {
+  name = "MllpUnknownFateError";
+  /** Epoch ms at which this send's bytes were written to the transport. */
+  flushedAt;
+  /** Milliseconds between that write and this report. */
+  elapsedMs;
+  /** Byte count of the framed message that was written. */
+  byteCount;
+  /**
+   * 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}.
+   */
+  messageControlIdBytes;
+  /**
+   * Construct an unknown-fate report.
+   *
+   * There is no `message` parameter, deliberately: see {@link UNKNOWN_FATE_MESSAGE}.
+   *
+   * @param opts - Report context (flush timestamp, elapsed time, byte counts).
+   */
+  constructor(opts) {
+    super(UNKNOWN_FATE_MESSAGE);
+    this.flushedAt = opts.flushedAt;
+    this.elapsedMs = opts.elapsedMs;
+    this.byteCount = opts.byteCount;
+    this.messageControlIdBytes = opts.messageControlIdBytes;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _MllpUnknownFateError);
+    }
+  }
+};
 function isTlsVerificationErrorCode(code) {
   switch (code) {
     case "UNABLE_TO_VERIFY_LEAF_SIGNATURE":
@@ -2255,6 +3013,13 @@ var MllpBackpressureError = class _MllpBackpressureError extends Error {
 
 // src/client/client.ts
 var NEVER_ABORTING_SIGNAL = new AbortController().signal;
+var OUTBOUND_WARNING_CONTEXT = Object.freeze({
+  msa1Bytes: null,
+  ackCode: null,
+  controlIdBytes: null,
+  byteOffset: 0,
+  elapsedSinceSendMs: 0
+});
 var MllpClient = class extends EventEmitter {
   _opts;
   _connection = null;
@@ -2266,6 +3031,11 @@ var MllpClient = class extends EventEmitter {
   _state = "DISCONNECTED";
   /** Per-message ACK timeout in ms. Resolved at construction. */
   _ackTimeoutMs;
+  /**
+   * Default bound on the second (application-acknowledgement) wait, in ms.
+   * `undefined` means "whatever ACK timeout is in force for that send".
+   */
+  _applicationAckTimeoutMs;
   /** controlId-mode flag. `false` → FIFO. */
   _correlateByControlId;
   /** Unified ACK correlator. Built during `_attachConnection`. */
@@ -2316,6 +3086,26 @@ var MllpClient = class extends EventEmitter {
   _connectSignal;
   /** Set when close()/destroy()/abort fires; reconnect handler short-circuits. */
   _userClosed = false;
+  /**
+   * 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.
+   */
+  _parkedSends = /* @__PURE__ */ new Set();
+  /**
+   * 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.
+   */
+  _drainWaiter = null;
+  /**
+   * 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.
+   */
+  _endDrainWait = null;
+  /**
+   * The `beforeClose` hook this client installed on its Connection, so a second `close()` call
+   * composes nothing twice. Compared by identity, never by shape.
+   */
+  _drainHook = null;
   /** Captured Connection error feeding `RetryContext.lastError`. */
   _lastError = null;
   /** Listener-removal handle for the abort listener bound in connect(). */
@@ -2354,6 +3144,7 @@ var MllpClient = class extends EventEmitter {
     super();
     this._opts = opts;
     this._ackTimeoutMs = opts.ackTimeoutMs ?? 3e4;
+    this._applicationAckTimeoutMs = opts.applicationAckTimeoutMs;
     this._correlateByControlId = opts.correlateByControlId === true;
     this._autoReconnect = opts.autoReconnect === true;
     this._initialDelayMs = opts.initialDelayMs ?? 100;
@@ -2394,6 +3185,10 @@ var MllpClient = class 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
@@ -2472,6 +3267,7 @@ var MllpClient = class extends EventEmitter {
         cleanup();
         conn.notifyConnect(socket.remoteAddress ?? null, socket.remotePort ?? null);
         this._emitInsecureWarningIfNeeded();
+        this._emitNegotiatedTlsParameters(socket);
         resolve();
       };
       const onSocketError = (err) => {
@@ -2503,6 +3299,7 @@ var MllpClient = class extends EventEmitter {
       return { socket: socket2, transport: new NetTransport(socket2) };
     }
     const tlsOpts = tlsOpt === true ? {} : tlsOpt;
+    const cipherPolicy = resolveTlsCipherPolicy(tlsOpts, "client");
     const socket = connect({
       host: this._opts.host,
       port: this._opts.port,
@@ -2513,7 +3310,7 @@ var MllpClient = class extends EventEmitter {
       ...tlsOpts.passphrase !== void 0 ? { passphrase: tlsOpts.passphrase } : {},
       minVersion: tlsOpts.minVersion ?? "TLSv1.2",
       ...tlsOpts.maxVersion !== void 0 ? { maxVersion: tlsOpts.maxVersion } : {},
-      ...tlsOpts.ciphers !== void 0 ? { ciphers: tlsOpts.ciphers } : {},
+      ...cipherPolicy,
       rejectUnauthorized: tlsOpts.allowUnverified !== true
     });
     return { socket, transport: new TlsTransport(socket) };
@@ -2567,6 +3364,71 @@ var MllpClient = class extends EventEmitter {
       safeEmitError(this, Object.freeze({ error: err }));
     });
   }
+  /**
+   * 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.
+   */
+  _emitAckModeWarning(code, ctx, conn) {
+    const warning = Object.freeze({
+      code,
+      message: ackModeDiagnosticMessage(code),
+      byteOffset: ctx.byteOffset,
+      msa1Bytes: ctx.msa1Bytes,
+      ackCode: ctx.ackCode,
+      controlIdBytes: ctx.controlIdBytes,
+      elapsedSinceSendMs: ctx.elapsedSinceSendMs,
+      connectionId: this._connection?.connectionId ?? conn?.connectionId,
+      timestamp: /* @__PURE__ */ new Date()
+    });
+    this._emitContained("warning", warning);
+  }
+  /**
+   * 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.
+   */
+  _applicationAckError(entry, reason, elapsedMs, detail) {
+    const commitReceivedAt = entry.twoPhase?.commitReceivedAt ?? 0;
+    return new MllpApplicationAckError(
+      `commit accepted (CA); no application acknowledgement ${detail}`,
+      {
+        reason,
+        commitCode: "CA",
+        messageControlIdBytes: entry.controlId?.length,
+        elapsedMs,
+        commitReceivedAt
+      }
+    );
+  }
+  /**
+   * 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.
+   */
+  _failCommitPendingSends(cause) {
+    const corr = this._correlator;
+    if (corr === null) return [];
+    const stranded = [];
+    for (const entry of corr.liveEntries()) {
+      if ((entry.twoPhase?.commitReceivedAt ?? null) !== null) stranded.push(entry);
+    }
+    const now = Date.now();
+    for (const entry of stranded) {
+      corr.dispose(entry.key);
+      const commitReceivedAt = entry.twoPhase?.commitReceivedAt ?? now;
+      entry.reject(
+        this._applicationAckError(entry, "connection-lost", now - commitReceivedAt, cause)
+      );
+    }
+    return stranded;
+  }
   /**
    * Emit the per-connection insecure-TLS warning when
    * `tls.allowUnverified === true`, fires on EVERY successful
@@ -2589,6 +3451,22 @@ var MllpClient = class extends EventEmitter {
     this._emitContained("securityWarning", warning);
     process.emitWarning(message, { code: MLLP_TLS_VERIFY_DISABLED });
   }
+  /**
+   * 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.
+   */
+  _emitNegotiatedTlsParameters(socket) {
+    if (this._opts.tls === void 0) return;
+    const params = readNegotiatedTlsParameters(socket, this._opts.host, this._opts.port);
+    if (params === null) return;
+    this._emitContained("tlsNegotiated", params);
+  }
   /**
    * Wire a Connection's events through to this MllpClient. Every re-emitted
    * payload is `Object.freeze`'d before emission, even though the
@@ -2651,11 +3529,50 @@ var MllpClient = class extends EventEmitter {
             })
           );
           this._maybeEmitDrain();
+        },
+        onApplicationAckTimeout: (entry, elapsedMs) => {
+          this._timedOutTotal += 1;
+          entry.reject(
+            this._applicationAckError(entry, "timeout", elapsedMs, `after ${elapsedMs}ms`)
+          );
+          this._maybeEmitDrain();
+        },
+        onCommitRejected: (entry, code) => {
+          entry.reject(
+            new MllpCommitRejectedError(`peer answered a negative commit (${code})`, {
+              commitCode: code,
+              messageControlIdBytes: entry.controlId?.length,
+              elapsedMs: entry.sentAt === null ? 0 : Date.now() - entry.sentAt
+            })
+          );
+          this._maybeEmitDrain();
+        },
+        onCommitReported: (entry, ack, latencyMs) => {
+          const report = entry.twoPhase?.onCommitReport ?? null;
+          if (report === null) return;
+          try {
+            report(Object.freeze({ code: "CA", payload: ack, latencyMs }));
+          } catch (err) {
+            safeEmitError(
+              this,
+              Object.freeze({
+                connectionId: this._connection?.connectionId ?? conn.connectionId,
+                error: err instanceof Error ? err : new Error(String(err))
+              })
+            );
+          }
+        },
+        onAckModeWarning: (code, ctx) => {
+          this._emitAckModeWarning(code, ctx, conn);
         }
       });
     }
     if (this._ackSweepTimer === null) {
-      const sweepIntervalMs = Math.max(50, Math.min(1e3, Math.floor(this._ackTimeoutMs / 4)));
+      const shortestWindowMs = Math.min(
+        this._ackTimeoutMs,
+        this._applicationAckTimeoutMs ?? this._ackTimeoutMs
+      );
+      const sweepIntervalMs = Math.max(50, Math.min(1e3, Math.floor(shortestWindowMs / 4)));
       this._ackSweepTimer = setInterval(() => {
         this._correlator?.expireDue();
       }, sweepIntervalMs);
@@ -2752,7 +3669,9 @@ var MllpClient = class extends EventEmitter {
   _handleDisconnect(err) {
     if (this._userClosed) return;
     if (this._correlator !== null) {
-      if (this._correlateByControlId) ; else {
+      if (this._correlateByControlId) {
+        this._failCommitPendingSends("before the link dropped");
+      } else {
         const orphans = [];
         const queued = [];
         for (const entry of this._correlator.liveEntries()) {
@@ -2892,6 +3811,7 @@ var MllpClient = class extends EventEmitter {
         arm = () => {
           conn.notifyConnect(socket.remoteAddress ?? null, socket.remotePort ?? null);
           this._emitInsecureWarningIfNeeded();
+          this._emitNegotiatedTlsParameters(socket);
         };
         const connectEventName = this._opts.tls !== void 0 ? "secureConnect" : "connect";
         socket.once("error", (sErr) => {
@@ -3013,6 +3933,7 @@ var MllpClient = class extends EventEmitter {
    * (every expired send), both code paths free a live-store slot.
    */
   _maybeEmitDrain() {
+    this._drainWaiter?.();
     const corr = this._correlator;
     if (corr === null) return;
     const belowCount = corr.size < this._hwmCount;
@@ -3038,6 +3959,7 @@ var MllpClient = class extends EventEmitter {
    */
   _onStateChange(e) {
     this._emitContained("stateChange", Object.freeze({ ...e }));
+    if (e.to !== "DRAINING") this._endDrainWait?.();
     if (e.to === "CONNECTED") {
       this._armDeadPeerTimer();
       this._lastConnectedAt = Date.now();
@@ -3074,6 +3996,21 @@ var MllpClient = class 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);
@@ -3082,6 +4019,10 @@ var MllpClient = class 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, opts) {
     const signal = opts?.signal;
@@ -3096,7 +4037,10 @@ var MllpClient = class extends EventEmitter {
         })
       );
     }
-    const controlId = this._correlateByControlId ? extractMshControlId(payload) : null;
+    const msh = readMshSegment(payload);
+    const controlId = this._correlateByControlId ? controlIdFromMsh(msh) : null;
+    const ackMode = classifyOutboundAckMode(msh);
+    const twoPhase = this._twoPhaseStateFor(ackMode, opts);
     const correlator = this._correlator;
     const conn = this._connection;
     const frame = encodeFrame(payload);
@@ -3124,7 +4068,11 @@ var MllpClient = class extends EventEmitter {
           )
         );
       }
-      return this._waitThenSend(payload, opts);
+      return this._waitThenSend(
+        payload,
+        { byteCount: frame.length, messageControlIdBytes: controlId?.length },
+        opts
+      );
     }
     return new Promise((resolve, reject) => {
       let abortListener = null;
@@ -3140,15 +4088,31 @@ var MllpClient = class extends EventEmitter {
         }
         reject(err);
       };
-      const key = correlator.enqueue(frame, controlId, wrappedResolve, wrappedReject);
+      const key = correlator.enqueue(frame, controlId, wrappedResolve, wrappedReject, twoPhase);
       if (key === null) {
+        const parked = { cancel: () => void 0 };
+        const neverDelivered = () => new MllpNeverDeliveredError({
+          byteCount: frame.length,
+          messageControlIdBytes: controlId?.length
+        });
         const onDrain = () => {
+          this._parkedSends.delete(parked);
           this.off("drain", onDrain);
+          if (this._shutdownBegun()) {
+            wrappedReject(neverDelivered());
+            return;
+          }
           this.send(payload, opts).then(wrappedResolve, wrappedReject);
         };
+        parked.cancel = () => {
+          this.off("drain", onDrain);
+          wrappedReject(neverDelivered());
+        };
+        this._parkedSends.add(parked);
         this.on("drain", onDrain);
         if (signal !== void 0) {
           abortListener = () => {
+            this._parkedSends.delete(parked);
             this.off("drain", onDrain);
             wrappedReject(new DOMException("Aborted", "AbortError"));
           };
@@ -3159,6 +4123,7 @@ var MllpClient = class extends EventEmitter {
       if (signal !== void 0) {
         abortListener = () => {
           correlator.remove(key);
+          this._drainWaiter?.();
           wrappedReject(new DOMException("Aborted", "AbortError"));
         };
         signal.addEventListener("abort", abortListener, { once: true });
@@ -3168,22 +4133,71 @@ var MllpClient = class extends EventEmitter {
       this._sentTotal += 1;
     });
   }
+  /**
+   * 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.
+   */
+  _twoPhaseStateFor(ackMode, opts) {
+    if (!ackMode.enhanced) return null;
+    if (ackMode.acceptFieldUnrecognised) {
+      this._emitAckModeWarning("MLLP_ACK_ACCEPT_TYPE_UNRECOGNISED", OUTBOUND_WARNING_CONTEXT);
+    }
+    if (ackMode.applicationFieldUnrecognised) {
+      this._emitAckModeWarning("MLLP_ACK_APPLICATION_TYPE_UNRECOGNISED", OUTBOUND_WARNING_CONTEXT);
+    }
+    if (!this._correlateByControlId) {
+      this._emitAckModeWarning("MLLP_ACK_TWO_PHASE_UNAVAILABLE", OUTBOUND_WARNING_CONTEXT);
+      return null;
+    }
+    return {
+      awaitsApplicationAck: ackMode.awaitsApplicationAck,
+      applicationAckTimeoutMs: opts?.applicationAckTimeoutMs ?? this._applicationAckTimeoutMs ?? opts?.ackTimeoutMs ?? this._ackTimeoutMs,
+      onCommitReport: opts?.onCommitAck ?? null,
+      commitCode: null,
+      commitReceivedAt: null
+    };
+  }
   /**
    * '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()`.
    */
-  _waitThenSend(payload, opts) {
+  _waitThenSend(payload, held, opts) {
     const signal = opts?.signal;
     return new Promise((resolve, reject) => {
       const ackTimeoutMs = opts?.ackTimeoutMs ?? this._ackTimeoutMs;
       let abortListener = null;
+      const parked = { cancel: () => void 0 };
       const cleanup = () => {
+        this._parkedSends.delete(parked);
         this.off("drain", onDrain);
         clearTimeout(timer);
         if (signal !== void 0 && abortListener !== null) {
@@ -3192,6 +4206,10 @@ var MllpClient = class extends EventEmitter {
       };
       const onDrain = () => {
         cleanup();
+        if (this._shutdownBegun()) {
+          reject(new MllpNeverDeliveredError(held));
+          return;
+        }
         this.send(payload, opts).then(resolve, reject);
       };
       const timer = setTimeout(() => {
@@ -3205,6 +4223,11 @@ var MllpClient = class extends EventEmitter {
         );
       }, ackTimeoutMs);
       timer.unref();
+      parked.cancel = () => {
+        cleanup();
+        reject(new MllpNeverDeliveredError(held));
+      };
+      this._parkedSends.add(parked);
       this.on("drain", onDrain);
       if (signal !== void 0) {
         abortListener = () => {
@@ -3218,18 +4241,186 @@ var MllpClient = class extends EventEmitter {
   /**
    * 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`.
    */
-  _teardownCorrelator(reason) {
+  _teardownCorrelator(reason, unresolvedFor) {
     if (this._ackSweepTimer !== null) {
       clearInterval(this._ackSweepTimer);
       this._ackSweepTimer = null;
     }
     if (this._correlator !== null) {
-      this._correlator.clear(reason);
+      this._correlator.clear(reason, (entry, fallback) => {
+        const commitReceivedAt = entry.twoPhase?.commitReceivedAt ?? null;
+        if (commitReceivedAt !== null) {
+          return this._applicationAckError(
+            entry,
+            "connection-lost",
+            Date.now() - commitReceivedAt,
+            "before the connection closed"
+          );
+        }
+        return unresolvedFor === void 0 ? fallback : unresolvedFor(entry);
+      });
       this._correlator = null;
     }
     this._clearDeadPeerTimer();
   }
+  /**
+   * 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.
+   */
+  _outstandingAckCount() {
+    return this._correlator?.getStats().inFlight ?? 0;
+  }
+  /**
+   * 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.
+   */
+  _shutdownErrorFor(entry) {
+    const flushedAt = entry.sentAt;
+    if (flushedAt === null) {
+      return new MllpNeverDeliveredError({
+        byteCount: entry.byteCount,
+        messageControlIdBytes: entry.controlId?.length
+      });
+    }
+    return new MllpUnknownFateError({
+      flushedAt,
+      elapsedMs: Date.now() - flushedAt,
+      byteCount: entry.byteCount,
+      messageControlIdBytes: entry.controlId?.length
+    });
+  }
+  /**
+   * 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.
+   */
+  _shutdownBegun() {
+    return this._userClosed || this._connection?.state === "DRAINING";
+  }
+  /**
+   * 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.
+   */
+  _cancelParkedSends() {
+    if (this._parkedSends.size === 0) return;
+    const parked = [...this._parkedSends];
+    this._parkedSends.clear();
+    for (const send of parked) send.cancel();
+  }
+  /**
+   * 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.
+   */
+  _settleUnresolvedSends() {
+    this._endDrainWait?.();
+    this._cancelParkedSends();
+    this._teardownCorrelator(
+      new MllpConnectionError("client closed", {
+        cause: new Error("closed"),
+        phase: "close"
+      }),
+      (entry) => this._shutdownErrorFor(entry)
+    );
+  }
+  /**
+   * 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.
+   */
+  _installDrainHook(conn) {
+    if (conn.beforeClose === this._drainHook) return;
+    const inherited = conn.beforeClose;
+    const hook = (drainTimeoutMs) => Promise.all([inherited.call(conn, drainTimeoutMs), this._awaitOutstandingAcks()]).then(
+      () => void 0
+    );
+    this._drainHook = hook;
+    conn.beforeClose = hook;
+  }
+  /**
+   * 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.
+   */
+  _awaitOutstandingAcks() {
+    return new Promise((resolve) => {
+      let done = false;
+      const finish = () => {
+        if (done) return;
+        done = true;
+        this._drainWaiter = null;
+        this._endDrainWait = null;
+        resolve();
+      };
+      const recheck = () => {
+        if (this._outstandingAckCount() === 0) finish();
+      };
+      this._drainWaiter = recheck;
+      this._endDrainWait = finish;
+      recheck();
+    });
+  }
   /**
    * **Test seam**, attach an externally-built {@link Connection} directly,
    * bypassing the `net.createConnection` + `NetTransport` path. Used by
@@ -3247,14 +4438,35 @@ var MllpClient = class extends EventEmitter {
     this._attachConnection(conn);
   }
   /**
-   * 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
@@ -3273,23 +4485,17 @@ var MllpClient = class extends EventEmitter {
     }
     const conn = this._connection;
     if (conn === null) {
-      this._teardownCorrelator(
-        new MllpConnectionError("client closed", {
-          cause: new Error("closed"),
-          phase: "close"
-        })
-      );
+      this._settleUnresolvedSends();
       return;
     }
-    this._teardownCorrelator(
-      new MllpConnectionError("client closed", {
-        cause: new Error("closed"),
-        phase: "close"
-      })
-    );
+    this._installDrainHook(conn);
+    const closeOpts = opts?.drainTimeoutMs !== void 0 ? { drainTimeoutMs: opts.drainTimeoutMs } : void 0;
     if (signal === void 0) {
-      const closeOpts = opts?.drainTimeoutMs !== void 0 ? { drainTimeoutMs: opts.drainTimeoutMs } : void 0;
-      await conn.close(closeOpts);
+      try {
+        await conn.close(closeOpts);
+      } finally {
+        this._settleUnresolvedSends();
+      }
       return;
     }
     let abortHandler;
@@ -3301,18 +4507,25 @@ var MllpClient = class extends EventEmitter {
       signal.addEventListener("abort", abortHandler, { once: true });
     });
     try {
-      const closeOpts = opts?.drainTimeoutMs !== void 0 ? { drainTimeoutMs: opts.drainTimeoutMs } : void 0;
       await Promise.race([conn.close(closeOpts), abortPromise]);
     } finally {
       if (abortHandler !== void 0) {
         signal.removeEventListener("abort", abortHandler);
       }
+      this._settleUnresolvedSends();
     }
   }
   /**
    * 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'));
@@ -3328,6 +4541,8 @@ var MllpClient = class extends EventEmitter {
       cause: new Error("destroyed"),
       phase: "close"
     });
+    this._endDrainWait?.();
+    this._cancelParkedSends();
     this._teardownCorrelator(teardownReason);
     const conn = this._connection;
     if (conn === null) return;
@@ -3435,9 +4650,303 @@ async function createStarterClient(opts) {
   return client;
 }
 
+// src/differential/corpus.ts
+var SEGMENT_SEPARATOR = "\r";
+var ADT_A01_SEGMENTS = [
+  "MSH|^~\\&|SENDING_APP|SENDING_FAC|RECV_APP|RECV_FAC|20260709120000||ADT^A01|MSG00001|P|2.5",
+  "EVN|A01|20260709120000",
+  "PID|1||900000001^^^FAC^MR||DOE^JANE^Q||19700101|F",
+  "PV1|1|I|WARD^101^1^FAC"
+];
+var ORU_R01_SEGMENTS = [
+  "MSH|^~\\&|LAB|LFAC|EHR|EFAC|20260709130000||ORU^R01|MSG00002|P|2.5",
+  "PID|1||900000002^^^FAC^MR||ROE^RICHARD",
+  "OBR|1||ORD123|CBC^COMPLETE BLOOD COUNT",
+  "OBX|1|NM|WBC^WHITE BLOOD COUNT||7.2|10*9/L|4.0-11.0|N"
+];
+var ACK_AA_SEGMENTS = [
+  "MSH|^~\\&|RECV_APP|RECV_FAC|SENDING_APP|SENDING_FAC|20260709120001||ACK^A01|ACK00001|P|2.5",
+  "MSA|AA|MSG00001"
+];
+function messageBytes(segments) {
+  return Buffer.from(segments.join(SEGMENT_SEPARATOR), CONTROL_ID_ENCODING);
+}
+function canonicalExchanges() {
+  return Object.freeze([
+    Object.freeze({
+      id: "adt-a01",
+      description: "Patient admit, four segments, synthetic identity",
+      controlId: "MSG00001",
+      payload: messageBytes(ADT_A01_SEGMENTS)
+    }),
+    Object.freeze({
+      id: "oru-r01",
+      description: "Observation result, four segments, synthetic identity",
+      controlId: "MSG00002",
+      payload: messageBytes(ORU_R01_SEGMENTS)
+    })
+  ]);
+}
+function canonicalAcknowledgement() {
+  return messageBytes(ACK_AA_SEGMENTS);
+}
+
+// src/differential/error.ts
+var MLLP_DIFF_PEER_UNPARSEABLE = "MLLP_DIFF_PEER_UNPARSEABLE";
+var DIFFERENTIAL_CONFIGURATION_MESSAGES = Object.freeze({
+  [MLLP_DIFF_PEER_UNPARSEABLE]: "the configured differential peer address could not be resolved into a host and a port, so the run was refused rather than skipped; expected the form host:port"
+});
+function differentialConfigurationMessage(code) {
+  return DIFFERENTIAL_CONFIGURATION_MESSAGES[code];
+}
+var MllpDifferentialConfigurationError = class _MllpDifferentialConfigurationError extends Error {
+  name = "MllpDifferentialConfigurationError";
+  /**
+   * The stable configuration-error code. Public API; branch on this rather than on the
+   * message.
+   */
+  code;
+  /**
+   * 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.
+   */
+  value;
+  /**
+   * 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, value) {
+    super(`${differentialConfigurationMessage(code)}; got: ${JSON.stringify(value)}`);
+    this.code = code;
+    this.value = value;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _MllpDifferentialConfigurationError);
+    }
+  }
+};
+
+// src/differential/peer.ts
+var MAX_PORT = 65535;
+function resolveDifferentialPeer(raw) {
+  if (raw === void 0 || raw === null) return void 0;
+  const trimmed = raw.trim();
+  if (trimmed === "") return void 0;
+  const refuse = () => {
+    throw new MllpDifferentialConfigurationError(MLLP_DIFF_PEER_UNPARSEABLE, raw);
+  };
+  const lastColon = trimmed.lastIndexOf(":");
+  if (lastColon <= 0 || lastColon === trimmed.length - 1) refuse();
+  const host = trimmed.slice(0, lastColon).replace(/^\[|\]$/g, "");
+  if (host === "") refuse();
+  const portText = trimmed.slice(lastColon + 1);
+  if (!/^\d+$/.test(portText)) refuse();
+  const port = Number(portText);
+  if (!Number.isInteger(port) || port <= 0 || port > MAX_PORT) refuse();
+  return Object.freeze({ host, port });
+}
+var DEFAULT_DEADLINE_MS = 1e4;
+var ACK_CORRELATION_CODE = "MLLP_ACK_UNMATCHED_CONTROL_ID";
+function connectOverTcp(peer) {
+  return new NetTransport(createConnection({ host: peer.host, port: peer.port }));
+}
+function isConnectionRefused(err) {
+  if (!("code" in err)) return false;
+  const { code } = err;
+  return typeof code === "string" && code === "ECONNREFUSED";
+}
+function failureOutcome(err, connected) {
+  if (err !== void 0 && isConnectionRefused(err)) return "connection-refused";
+  return connected ? "connection-dropped" : "connection-failed";
+}
+function throwIfAborted(signal) {
+  if (signal !== void 0 && signal.aborted) throw signal.reason;
+}
+async function runExchange(exchange, settings) {
+  const { peer, connect, deadlineMs, maxFrameSizeBytes, signal } = settings;
+  const framed = encodeFrame(exchange.payload);
+  const startedAt = Date.now();
+  const deviations = [];
+  const chunks = [];
+  let responseByteCount = 0;
+  let connected = false;
+  const finish = (outcome, byteParity, correlation) => Object.freeze({
+    exchangeId: exchange.id,
+    outcome,
+    byteParity,
+    correlation,
+    warningCodes: Object.freeze(deviations.map((d) => d.code)),
+    deviations: Object.freeze([...deviations]),
+    requestByteCount: framed.length,
+    responseByteCount,
+    deadlineMs,
+    elapsedMs: Date.now() - startedAt
+  });
+  let transport;
+  try {
+    transport = connect(peer);
+  } catch {
+    return finish("connection-failed", "not-observed", "not-observed");
+  }
+  const end = await new Promise((resolve) => {
+    let settled = false;
+    let abortListener;
+    const settle = (value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (abortListener !== void 0) signal?.removeEventListener("abort", abortListener);
+      resolve(value);
+    };
+    const timer = setTimeout(() => {
+      settle({ kind: "timeout" });
+    }, deadlineMs);
+    const reader = new FrameReader({
+      onFrame: (payload, frameStart, warnings) => {
+        for (const w of warnings) recordWarning(deviations, w);
+        settle({ kind: "frame", payload, frameStart });
+      },
+      allowFsOnly: true,
+      allowLfAfterFs: true,
+      allowMissingLeadingVt: true,
+      allowLeadingWhitespace: true,
+      ...maxFrameSizeBytes === void 0 ? {} : { maxFrameSizeBytes }
+    });
+    transport.onData((chunk) => {
+      if (settled) return;
+      responseByteCount += chunk.length;
+      chunks.push(Buffer.from(chunk));
+      try {
+        reader.push(chunk);
+      } catch (err) {
+        if (err instanceof MllpFramingError) {
+          deviations.push(Object.freeze({ code: err.code, byteOffset: err.byteOffset }));
+          settle({ kind: "framing-error", code: err.code, byteOffset: err.byteOffset });
+          return;
+        }
+        settle({ kind: "error", error: err instanceof Error ? err : new Error(String(err)) });
+      }
+    });
+    transport.onConnect(() => {
+      connected = true;
+      transport.write(framed);
+    });
+    transport.onError((err) => {
+      settle({ kind: "error", error: err });
+    });
+    transport.onClose(() => {
+      settle({ kind: "closed" });
+    });
+    if (signal !== void 0) {
+      if (signal.aborted) {
+        settle({ kind: "aborted" });
+        return;
+      }
+      abortListener = () => {
+        settle({ kind: "aborted" });
+      };
+      signal.addEventListener("abort", abortListener, { once: true });
+    }
+  });
+  transport.destroy();
+  if (end.kind === "aborted") {
+    throwIfAborted(signal);
+    return finish("connection-failed", "not-observed", "not-observed");
+  }
+  switch (end.kind) {
+    case "frame":
+      return classifyFrame(exchange, end.payload, end.frameStart, chunks, deviations, finish);
+    case "framing-error":
+      return finish("undecodable-response", "deviation", "not-observed");
+    case "timeout":
+      return finish("unanswered", "not-observed", "not-observed");
+    case "closed":
+      return finish(failureOutcome(void 0, connected), "not-observed", "not-observed");
+    case "error":
+      return finish(failureOutcome(end.error, connected), "not-observed", "not-observed");
+  }
+}
+function recordWarning(into, warning, offsetBase = 0) {
+  into.push(Object.freeze({ code: warning.code, byteOffset: offsetBase + warning.byteOffset }));
+}
+function classifyFrame(exchange, payload, frameStart, chunks, deviations, finish) {
+  const canonical = encodeFrame(payload, {
+    allowDelimiterBytesInPayload: true,
+    onWarning: (w) => {
+      recordWarning(deviations, w, frameStart + 1);
+    }
+  });
+  const received = Buffer.concat([...chunks]);
+  const parityMatch = deviations.length === 0 && frameStart === 0 && received.length >= canonical.length && received.subarray(0, canonical.length).equals(canonical);
+  const acknowledged = extractMsaControlId(payload);
+  let correlation;
+  if (acknowledged === null) correlation = "absent";
+  else if (acknowledged === exchange.controlId) correlation = "match";
+  else correlation = "mismatch";
+  if (correlation !== "match") {
+    deviations.push(Object.freeze({ code: ACK_CORRELATION_CODE, byteOffset: frameStart }));
+  }
+  return finish("answered", parityMatch ? "match" : "deviation", correlation);
+}
+function deriveResult(exchanges) {
+  const answered = exchanges.filter((e) => e.outcome === "answered");
+  if (answered.length === 0) return "no-observation";
+  const clean = answered.length === exchanges.length && answered.every(
+    (e) => e.byteParity === "match" && e.correlation === "match" && e.deviations.length === 0
+  );
+  return clean ? "parity-observed" : "deviations-observed";
+}
+async function runDifferential(options = {}) {
+  const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const deadlineMs = options.deadlineMs ?? DEFAULT_DEADLINE_MS;
+  const exchanges = options.exchanges ?? canonicalExchanges();
+  const connect = options.connect ?? connectOverTcp;
+  const { signal } = options;
+  throwIfAborted(signal);
+  const peer = resolveDifferentialPeer(options.peer);
+  if (peer === void 0) {
+    return Object.freeze({
+      peer: void 0,
+      result: "skipped",
+      skipReason: "no-peer-configured",
+      exchanges: Object.freeze([]),
+      exchangesAttempted: 0,
+      exchangesAnswered: 0,
+      deadlineMs,
+      startedAt,
+      finishedAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
+  const settings = {
+    peer,
+    connect,
+    deadlineMs,
+    maxFrameSizeBytes: options.maxFrameSizeBytes,
+    signal
+  };
+  const results = [];
+  for (const exchange of exchanges) {
+    throwIfAborted(signal);
+    results.push(await runExchange(exchange, settings));
+  }
+  return Object.freeze({
+    peer: Object.freeze({ host: peer.host, port: peer.port }),
+    result: deriveResult(results),
+    skipReason: void 0,
+    exchanges: Object.freeze([...results]),
+    exchangesAttempted: results.length,
+    exchangesAnswered: results.filter((e) => e.outcome === "answered").length,
+    deadlineMs,
+    startedAt,
+    finishedAt: (/* @__PURE__ */ new Date()).toISOString()
+  });
+}
+
 // src/index.ts
-var VERSION = "0.0.10";
+var VERSION = "0.1.0";
 
-export { Connection, FrameReader, MLLP_BIND_ALL_INTERFACES, MLLP_TLS_VERIFY_DISABLED, MllpAckError, MllpBackpressureError, MllpClient, MllpConnectionError, MllpFramingError, MllpServer, MllpTimeoutError, NetTransport, TlsTransport, VERSION, ackDiagnosticMessage, buildRawAck, createClient, createServer, createStarterClient, createStarterServer, createWarning, encodeFrame, isTlsProtocolError, isTlsVerificationErrorCode, isTransientConnectionError, rawAckUncorrelatable, resolveNackCode };
+export { ATNA_CIPHER_LIST, ATNA_CIPHER_SUITES, Connection, FrameReader, 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, MllpAckError, MllpApplicationAckError, MllpBackpressureError, MllpClient, MllpCommitRejectedError, MllpConnectionError, MllpDifferentialConfigurationError, MllpFramingError, MllpNeverDeliveredError, MllpServer, MllpTimeoutError, MllpTlsConfigurationError, MllpUnknownFateError, NetTransport, TLS13_DEFAULT_CIPHER_SUITES, TlsTransport, VERSION, ackDiagnosticMessage, ackModeDiagnosticMessage, buildRawAck, canonicalAcknowledgement, canonicalExchanges, createClient, createServer, createStarterClient, createStarterServer, createWarning, differentialConfigurationMessage, encodeFrame, isTlsProtocolError, isTlsVerificationErrorCode, isTransientConnectionError, rawAckUncorrelatable, readNegotiatedTlsParameters, resolveDifferentialPeer, resolveNackCode, resolveTlsCipherPolicy, runDifferential, tlsConfigurationMessage };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map