@cosyte/mllp 0.0.3 → 0.0.5

package/dist/index.d.cts

@@ -46,7 +46,21 @@ type WarningCode = "MLLP_MISSING_LEADING_VT" | "MLLP_FS_WITHOUT_CR" | "MLLP_LF_A
  */
 interface MllpWarning {
     readonly code: WarningCode;
-    /** Stable human-readable description. Never contains payload bytes or secrets. */
+    /**
+     * Stable human-readable description. It carries structural facts (a byte
+     * offset, an accumulated size) and **never a run of payload content**.
+     *
+     * Two codes carry exactly one input byte, and it is worth knowing which:
+     * `MLLP_MISSING_LEADING_VT` and `MLLP_FS_WITHOUT_CR` render the hex of the
+     * single byte found where a framing byte was expected, and on a stream that
+     * omits its leading `VT` that byte is the first byte of the unframed content.
+     * One byte, never a run, the same bound `MllpFramingError.snippet` carries. If
+     * that is more than your threat model allows, log `code` and `byteOffset`
+     * rather than `message`.
+     *
+     * The ACK-correlation codes are stricter: their text comes from a frozen
+     * registry and does not vary with the wire at all.
+     */
     readonly message: string;
     /** Absolute stream byte offset where the anomaly was detected. */
     readonly byteOffset: number;
@@ -1704,7 +1718,9 @@ interface ServerOptions {
  *
  * const server = await createStarterServer({
  *   port: 2575,
- *   onMessage: (buf) => buildAckBuffer(buf),
+ *   onMessage: async (payload) => {
+ *     await db.commit(payload); // the durable-commit step; a throw answers a negative ACK
+ *   },
  * });
  * // server is listening, auto-ACK enabled, Symbol.asyncDispose wired
  * await using _ = server; // closes on scope exit
@@ -2029,12 +2045,77 @@ declare function createServer(opts?: ServerOptions): MllpServer;
  *
  * const server = await createStarterServer({
  *   port: 2575,
- *   onMessage: (payload) => buildAck(payload),
+ *   onMessage: async (payload) => {
+ *     await db.commit(payload); // the durable-commit step; a throw answers a negative ACK
+ *   },
  * });
  * ```
  */
 declare function createStarterServer(opts: StarterServerOptions): Promise<MllpServer>;
 
+/**
+ * The frozen diagnostic registry for ACK correlation.
+ *
+ * Every message an ACK-correlation diagnostic can carry lives here as a
+ * literal, and the lookup takes **only a code**. There is no value parameter
+ * anywhere in this module, which is the whole point: a factory that cannot be
+ * handed a value cannot interpolate one, regardless of what arrives on the
+ * wire.
+ *
+ * ## What this replaces, and why the shape matters more than the wording
+ *
+ * The `correlateByControlId` path used to build its diagnostics by
+ * interpolation, and both ends of it were consumer-controlled and unbounded.
+ * The unmatched-ACK error read the **peer's** MSA-2 straight out of an inbound
+ * frame and put it on an `Error.message`; measured against a peer sending a
+ * one-megabyte MSA-2, that produced a 1,000,026-byte `message` and an
+ * equally large field on the frozen error payload. The late-ACK warning did
+ * the same with the control id of the send being reported on. Both go to a
+ * log, and in this domain a log is a place a patient identifier must not
+ * reach. That is not a hypothetical about control ids either: this package has
+ * already shipped one scanner that ran past a segment terminator and returned
+ * PID-3, a patient's medical record number, as the "control ID" of a truncated
+ * MSH. Withholding the bytes is the defence that survives the next such bug.
+ *
+ * ## What a correlation diagnostic says instead
+ *
+ * That a control id did not match, plus **numbers**: a byte length, a stream
+ * offset, an elapsed time. A number is a shape, not content. A truncated id is
+ * not an acceptable middle ground, and neither is a hex or base64 rendering:
+ * both still grow the diagnostic with the input and both still disclose the
+ * bytes. Nothing is lost by withholding them, because the caller already holds
+ * them: the outbound payload is the caller's own argument to `send()`, and the
+ * inbound frame is on the `'message'` event.
+ *
+ * Mirrors the same answer this package already reached for the ACK adapter's
+ * verbatim-echo warning, which reports byte lengths and withholds MSH-10 and
+ * MSA-2 themselves.
+ *
+ * @packageDocumentation
+ */
+/**
+ * The two warning codes emitted by ACK correlation rather than by framing.
+ *
+ * A subset of the framing `WarningCode` union; named separately so the
+ * registry below is exhaustive over exactly the codes it owns and a new
+ * correlation code cannot be added without a message for it.
+ */
+type AckCorrelationCode = "MLLP_ACK_UNMATCHED_CONTROL_ID" | "MLLP_ACK_AFTER_TIMEOUT";
+/**
+ * Look up the frozen diagnostic text for an ACK-correlation code.
+ *
+ * A pure table read. It takes no value, so no caller can widen it into an
+ * interpolation site.
+ *
+ * @param code - The correlation code being reported.
+ * @returns The registered message for that code, byte-for-byte.
+ * @example
+ * ```typescript
+ * const message = ackDiagnosticMessage('MLLP_ACK_AFTER_TIMEOUT');
+ * ```
+ */
+declare function ackDiagnosticMessage(code: AckCorrelationCode): string;
+
 /**
  * MLLP Client, `createClient()` factory and `MllpClient` class.
  *
@@ -2059,6 +2140,37 @@ declare function createStarterServer(opts: StarterServerOptions): Promise<MllpSe
  * @packageDocumentation
  */
 
+/**
+ * The `'warning'` payload the client emits for an ACK-correlation deviation
+ * (`MLLP_ACK_UNMATCHED_CONTROL_ID`, `MLLP_ACK_AFTER_TIMEOUT`).
+ *
+ * A `MllpWarning` with two extra numeric fields. `message` is a **frozen
+ * registry entry**, byte-for-byte identical for a given code no matter what
+ * arrived on the wire, and everything input-derived is a number: the control
+ * ID's byte length and the elapsed time. A warning is a log line, so it carries
+ * no field content.
+ *
+ * @example
+ * ```typescript
+ * client.on('warning', (w: AckCorrelationWarning) => {
+ *   logger.warn({ code: w.code, idBytes: w.controlIdBytes, elapsedMs: w.elapsedSinceSendMs });
+ * });
+ * ```
+ */
+interface AckCorrelationWarning extends MllpWarning {
+    /** The correlation code this warning reports. */
+    readonly code: AckCorrelationCode;
+    /**
+     * Byte length of the control ID involved, or `null` when there was none to
+     * read. Control IDs are decoded `latin1`, so a code-unit count is a byte count.
+     */
+    readonly controlIdBytes: number | null;
+    /**
+     * Milliseconds between the send's write-flush (or its timeout, for a late
+     * ACK) and this warning.
+     */
+    readonly elapsedSinceSendMs: number;
+}
 /**
  * Context passed to a custom `retryStrategy` hook on each reconnect attempt.
  *
@@ -2311,7 +2423,10 @@ interface ClientStats {
  * - `'reconnecting'`, `{ connectionId, attempt?, delayMs? }`
  * - `'close'`, `{ connectionId }` once the FSM enters terminal `CLOSED`
  * - `'message'`, `{ payload, connectionId, byteOffset, warnings }` for every inbound frame
- * - `'warning'`, `MllpWarning` enriched with `connectionId` from the Connection layer
+ * - `'warning'`, `MllpWarning | AckCorrelationWarning`. A framing deviation arrives as a
+ *   `MllpWarning` enriched with `connectionId` from the Connection layer; the two
+ *   ACK-correlation codes arrive as {@link AckCorrelationWarning}, which adds
+ *   `controlIdBytes` and `elapsedSinceSendMs`. Narrow on `code` before reading either.
  * - `'securityWarning'`, `SecurityWarning`. Emitted on every successful
  *   `secureConnect` (initial + every reconnect) when `tls.allowUnverified` is `true`
  *   with code `MLLP_TLS_VERIFY_DISABLED`. Also mirrored to `process.emitWarning`.
@@ -2866,15 +2981,27 @@ declare function createStarterClient(opts: StarterClientOptions): Promise<MllpCl
  *   await client.send(payload);
  * } catch (err) {
  *   if (err instanceof MllpTimeoutError) {
- *     logger.warn({ elapsedMs: err.elapsedMs, controlId: err.messageControlId });
+ *     logger.warn({ elapsedMs: err.elapsedMs, idBytes: err.messageControlIdBytes });
  *   }
  * }
  * ```
  */
 declare class MllpTimeoutError extends Error {
     readonly name: "MllpTimeoutError";
-    /** MSH-10 control ID of the timed-out send (FIFO mode: `undefined`). */
-    readonly messageControlId: string | undefined;
+    /**
+     * Byte length of the timed-out send's MSH-10 control ID, or `undefined` when
+     * there was none to read (FIFO mode, or a payload with no MSH-10).
+     *
+     * **The control ID itself is deliberately not here.** An `Error` is a
+     * diagnostic surface: it is logged, and its `stack` is what an error reporter
+     * ships off the box. MSH-10 is payload content, and a scanner that returns
+     * the wrong field returns payload content of some other kind, which is how a
+     * patient identifier reaches a log line. Nothing is lost by withholding it,
+     * because this error rejects the very `send()` whose payload the caller
+     * passed in, so the caller already holds the bytes. Control IDs are decoded
+     * `latin1`, a 1:1 byte to code-unit map, so this count is a byte count.
+     */
+    readonly messageControlIdBytes: number | undefined;
     /** Milliseconds elapsed between write-flush and timeout fire. */
     readonly elapsedMs: number;
     /** Epoch ms timestamp recorded at write-flush callback. */
@@ -2882,11 +3009,11 @@ declare class MllpTimeoutError extends Error {
     /**
      * Construct an MLLP timeout error.
      *
-     * @param message - Human-readable error message.
-     * @param opts - Timeout context (originating message control id, elapsed time, flush timestamp).
+     * @param message - Human-readable error message. Structural facts only, never field content.
+     * @param opts - Timeout context (control-id byte length, elapsed time, flush timestamp).
      */
     constructor(message: string, opts: {
-        messageControlId: string | undefined;
+        messageControlIdBytes: number | undefined;
         elapsedMs: number;
         sentAt: number;
     });
@@ -3087,4 +3214,4 @@ declare class MllpBackpressureError extends Error {
  */
 declare const VERSION: string;
 
-export { type AckCode, type ClientAuth, type ClientOptions, type ClientStats, Connection, type ConnectionErrorCause, type ConnectionErrorPhase, type ConnectionOptions, type ConnectionState, type ConnectionStats, type EncoderOptions, FrameReader, type FrameReaderOptions, MLLP_BIND_ALL_INTERFACES, MLLP_TLS_VERIFY_DISABLED, type MessageMeta, MllpAckError, MllpBackpressureError, MllpClient, MllpConnectionError, MllpFramingError, MllpServer, MllpTimeoutError, type MllpWarning, type NackEvent, type NackReason, type NegativeAckCode, NetTransport, type PemInput, type ReconnectingEvent, type RetryContext, type RetryStrategy, type SecurityWarning, type SecurityWarningCode, type ServerOptions, type ServerStats, type ServerTlsOptions, type StarterClientOptions, type StarterServerOptions, type StateChangeEvent, type TlsOptions, TlsTransport, Transport, VERSION, type WarningCode, buildRawAck, createClient, createServer, createStarterClient, createStarterServer, createWarning, encodeFrame, isTlsProtocolError, isTlsVerificationErrorCode, isTransientConnectionError, rawAckUncorrelatable, resolveNackCode };
+export { type AckCode, type AckCorrelationCode, type AckCorrelationWarning, type ClientAuth, type ClientOptions, type ClientStats, Connection, type ConnectionErrorCause, type ConnectionErrorPhase, type ConnectionOptions, type ConnectionState, type ConnectionStats, type EncoderOptions, FrameReader, type FrameReaderOptions, MLLP_BIND_ALL_INTERFACES, MLLP_TLS_VERIFY_DISABLED, type MessageMeta, MllpAckError, MllpBackpressureError, MllpClient, MllpConnectionError, MllpFramingError, MllpServer, MllpTimeoutError, type MllpWarning, type NackEvent, type NackReason, type NegativeAckCode, NetTransport, type PemInput, type ReconnectingEvent, type RetryContext, type RetryStrategy, type SecurityWarning, type SecurityWarningCode, type ServerOptions, type ServerStats, type ServerTlsOptions, type StarterClientOptions, type StarterServerOptions, type StateChangeEvent, type TlsOptions, TlsTransport, Transport, VERSION, type WarningCode, ackDiagnosticMessage, buildRawAck, createClient, createServer, createStarterClient, createStarterServer, createWarning, encodeFrame, isTlsProtocolError, isTlsVerificationErrorCode, isTransientConnectionError, rawAckUncorrelatable, resolveNackCode };

package/dist/index.d.ts

@@ -46,7 +46,21 @@ type WarningCode = "MLLP_MISSING_LEADING_VT" | "MLLP_FS_WITHOUT_CR" | "MLLP_LF_A
  */
 interface MllpWarning {
     readonly code: WarningCode;
-    /** Stable human-readable description. Never contains payload bytes or secrets. */
+    /**
+     * Stable human-readable description. It carries structural facts (a byte
+     * offset, an accumulated size) and **never a run of payload content**.
+     *
+     * Two codes carry exactly one input byte, and it is worth knowing which:
+     * `MLLP_MISSING_LEADING_VT` and `MLLP_FS_WITHOUT_CR` render the hex of the
+     * single byte found where a framing byte was expected, and on a stream that
+     * omits its leading `VT` that byte is the first byte of the unframed content.
+     * One byte, never a run, the same bound `MllpFramingError.snippet` carries. If
+     * that is more than your threat model allows, log `code` and `byteOffset`
+     * rather than `message`.
+     *
+     * The ACK-correlation codes are stricter: their text comes from a frozen
+     * registry and does not vary with the wire at all.
+     */
     readonly message: string;
     /** Absolute stream byte offset where the anomaly was detected. */
     readonly byteOffset: number;
@@ -1704,7 +1718,9 @@ interface ServerOptions {
  *
  * const server = await createStarterServer({
  *   port: 2575,
- *   onMessage: (buf) => buildAckBuffer(buf),
+ *   onMessage: async (payload) => {
+ *     await db.commit(payload); // the durable-commit step; a throw answers a negative ACK
+ *   },
  * });
  * // server is listening, auto-ACK enabled, Symbol.asyncDispose wired
  * await using _ = server; // closes on scope exit
@@ -2029,12 +2045,77 @@ declare function createServer(opts?: ServerOptions): MllpServer;
  *
  * const server = await createStarterServer({
  *   port: 2575,
- *   onMessage: (payload) => buildAck(payload),
+ *   onMessage: async (payload) => {
+ *     await db.commit(payload); // the durable-commit step; a throw answers a negative ACK
+ *   },
  * });
  * ```
  */
 declare function createStarterServer(opts: StarterServerOptions): Promise<MllpServer>;
 
+/**
+ * The frozen diagnostic registry for ACK correlation.
+ *
+ * Every message an ACK-correlation diagnostic can carry lives here as a
+ * literal, and the lookup takes **only a code**. There is no value parameter
+ * anywhere in this module, which is the whole point: a factory that cannot be
+ * handed a value cannot interpolate one, regardless of what arrives on the
+ * wire.
+ *
+ * ## What this replaces, and why the shape matters more than the wording
+ *
+ * The `correlateByControlId` path used to build its diagnostics by
+ * interpolation, and both ends of it were consumer-controlled and unbounded.
+ * The unmatched-ACK error read the **peer's** MSA-2 straight out of an inbound
+ * frame and put it on an `Error.message`; measured against a peer sending a
+ * one-megabyte MSA-2, that produced a 1,000,026-byte `message` and an
+ * equally large field on the frozen error payload. The late-ACK warning did
+ * the same with the control id of the send being reported on. Both go to a
+ * log, and in this domain a log is a place a patient identifier must not
+ * reach. That is not a hypothetical about control ids either: this package has
+ * already shipped one scanner that ran past a segment terminator and returned
+ * PID-3, a patient's medical record number, as the "control ID" of a truncated
+ * MSH. Withholding the bytes is the defence that survives the next such bug.
+ *
+ * ## What a correlation diagnostic says instead
+ *
+ * That a control id did not match, plus **numbers**: a byte length, a stream
+ * offset, an elapsed time. A number is a shape, not content. A truncated id is
+ * not an acceptable middle ground, and neither is a hex or base64 rendering:
+ * both still grow the diagnostic with the input and both still disclose the
+ * bytes. Nothing is lost by withholding them, because the caller already holds
+ * them: the outbound payload is the caller's own argument to `send()`, and the
+ * inbound frame is on the `'message'` event.
+ *
+ * Mirrors the same answer this package already reached for the ACK adapter's
+ * verbatim-echo warning, which reports byte lengths and withholds MSH-10 and
+ * MSA-2 themselves.
+ *
+ * @packageDocumentation
+ */
+/**
+ * The two warning codes emitted by ACK correlation rather than by framing.
+ *
+ * A subset of the framing `WarningCode` union; named separately so the
+ * registry below is exhaustive over exactly the codes it owns and a new
+ * correlation code cannot be added without a message for it.
+ */
+type AckCorrelationCode = "MLLP_ACK_UNMATCHED_CONTROL_ID" | "MLLP_ACK_AFTER_TIMEOUT";
+/**
+ * Look up the frozen diagnostic text for an ACK-correlation code.
+ *
+ * A pure table read. It takes no value, so no caller can widen it into an
+ * interpolation site.
+ *
+ * @param code - The correlation code being reported.
+ * @returns The registered message for that code, byte-for-byte.
+ * @example
+ * ```typescript
+ * const message = ackDiagnosticMessage('MLLP_ACK_AFTER_TIMEOUT');
+ * ```
+ */
+declare function ackDiagnosticMessage(code: AckCorrelationCode): string;
+
 /**
  * MLLP Client, `createClient()` factory and `MllpClient` class.
  *
@@ -2059,6 +2140,37 @@ declare function createStarterServer(opts: StarterServerOptions): Promise<MllpSe
  * @packageDocumentation
  */
 
+/**
+ * The `'warning'` payload the client emits for an ACK-correlation deviation
+ * (`MLLP_ACK_UNMATCHED_CONTROL_ID`, `MLLP_ACK_AFTER_TIMEOUT`).
+ *
+ * A `MllpWarning` with two extra numeric fields. `message` is a **frozen
+ * registry entry**, byte-for-byte identical for a given code no matter what
+ * arrived on the wire, and everything input-derived is a number: the control
+ * ID's byte length and the elapsed time. A warning is a log line, so it carries
+ * no field content.
+ *
+ * @example
+ * ```typescript
+ * client.on('warning', (w: AckCorrelationWarning) => {
+ *   logger.warn({ code: w.code, idBytes: w.controlIdBytes, elapsedMs: w.elapsedSinceSendMs });
+ * });
+ * ```
+ */
+interface AckCorrelationWarning extends MllpWarning {
+    /** The correlation code this warning reports. */
+    readonly code: AckCorrelationCode;
+    /**
+     * Byte length of the control ID involved, or `null` when there was none to
+     * read. Control IDs are decoded `latin1`, so a code-unit count is a byte count.
+     */
+    readonly controlIdBytes: number | null;
+    /**
+     * Milliseconds between the send's write-flush (or its timeout, for a late
+     * ACK) and this warning.
+     */
+    readonly elapsedSinceSendMs: number;
+}
 /**
  * Context passed to a custom `retryStrategy` hook on each reconnect attempt.
  *
@@ -2311,7 +2423,10 @@ interface ClientStats {
  * - `'reconnecting'`, `{ connectionId, attempt?, delayMs? }`
  * - `'close'`, `{ connectionId }` once the FSM enters terminal `CLOSED`
  * - `'message'`, `{ payload, connectionId, byteOffset, warnings }` for every inbound frame
- * - `'warning'`, `MllpWarning` enriched with `connectionId` from the Connection layer
+ * - `'warning'`, `MllpWarning | AckCorrelationWarning`. A framing deviation arrives as a
+ *   `MllpWarning` enriched with `connectionId` from the Connection layer; the two
+ *   ACK-correlation codes arrive as {@link AckCorrelationWarning}, which adds
+ *   `controlIdBytes` and `elapsedSinceSendMs`. Narrow on `code` before reading either.
  * - `'securityWarning'`, `SecurityWarning`. Emitted on every successful
  *   `secureConnect` (initial + every reconnect) when `tls.allowUnverified` is `true`
  *   with code `MLLP_TLS_VERIFY_DISABLED`. Also mirrored to `process.emitWarning`.
@@ -2866,15 +2981,27 @@ declare function createStarterClient(opts: StarterClientOptions): Promise<MllpCl
  *   await client.send(payload);
  * } catch (err) {
  *   if (err instanceof MllpTimeoutError) {
- *     logger.warn({ elapsedMs: err.elapsedMs, controlId: err.messageControlId });
+ *     logger.warn({ elapsedMs: err.elapsedMs, idBytes: err.messageControlIdBytes });
  *   }
  * }
  * ```
  */
 declare class MllpTimeoutError extends Error {
     readonly name: "MllpTimeoutError";
-    /** MSH-10 control ID of the timed-out send (FIFO mode: `undefined`). */
-    readonly messageControlId: string | undefined;
+    /**
+     * Byte length of the timed-out send's MSH-10 control ID, or `undefined` when
+     * there was none to read (FIFO mode, or a payload with no MSH-10).
+     *
+     * **The control ID itself is deliberately not here.** An `Error` is a
+     * diagnostic surface: it is logged, and its `stack` is what an error reporter
+     * ships off the box. MSH-10 is payload content, and a scanner that returns
+     * the wrong field returns payload content of some other kind, which is how a
+     * patient identifier reaches a log line. Nothing is lost by withholding it,
+     * because this error rejects the very `send()` whose payload the caller
+     * passed in, so the caller already holds the bytes. Control IDs are decoded
+     * `latin1`, a 1:1 byte to code-unit map, so this count is a byte count.
+     */
+    readonly messageControlIdBytes: number | undefined;
     /** Milliseconds elapsed between write-flush and timeout fire. */
     readonly elapsedMs: number;
     /** Epoch ms timestamp recorded at write-flush callback. */
@@ -2882,11 +3009,11 @@ declare class MllpTimeoutError extends Error {
     /**
      * Construct an MLLP timeout error.
      *
-     * @param message - Human-readable error message.
-     * @param opts - Timeout context (originating message control id, elapsed time, flush timestamp).
+     * @param message - Human-readable error message. Structural facts only, never field content.
+     * @param opts - Timeout context (control-id byte length, elapsed time, flush timestamp).
      */
     constructor(message: string, opts: {
-        messageControlId: string | undefined;
+        messageControlIdBytes: number | undefined;
         elapsedMs: number;
         sentAt: number;
     });
@@ -3087,4 +3214,4 @@ declare class MllpBackpressureError extends Error {
  */
 declare const VERSION: string;
 
-export { type AckCode, type ClientAuth, type ClientOptions, type ClientStats, Connection, type ConnectionErrorCause, type ConnectionErrorPhase, type ConnectionOptions, type ConnectionState, type ConnectionStats, type EncoderOptions, FrameReader, type FrameReaderOptions, MLLP_BIND_ALL_INTERFACES, MLLP_TLS_VERIFY_DISABLED, type MessageMeta, MllpAckError, MllpBackpressureError, MllpClient, MllpConnectionError, MllpFramingError, MllpServer, MllpTimeoutError, type MllpWarning, type NackEvent, type NackReason, type NegativeAckCode, NetTransport, type PemInput, type ReconnectingEvent, type RetryContext, type RetryStrategy, type SecurityWarning, type SecurityWarningCode, type ServerOptions, type ServerStats, type ServerTlsOptions, type StarterClientOptions, type StarterServerOptions, type StateChangeEvent, type TlsOptions, TlsTransport, Transport, VERSION, type WarningCode, buildRawAck, createClient, createServer, createStarterClient, createStarterServer, createWarning, encodeFrame, isTlsProtocolError, isTlsVerificationErrorCode, isTransientConnectionError, rawAckUncorrelatable, resolveNackCode };
+export { type AckCode, type AckCorrelationCode, type AckCorrelationWarning, type ClientAuth, type ClientOptions, type ClientStats, Connection, type ConnectionErrorCause, type ConnectionErrorPhase, type ConnectionOptions, type ConnectionState, type ConnectionStats, type EncoderOptions, FrameReader, type FrameReaderOptions, MLLP_BIND_ALL_INTERFACES, MLLP_TLS_VERIFY_DISABLED, type MessageMeta, MllpAckError, MllpBackpressureError, MllpClient, MllpConnectionError, MllpFramingError, MllpServer, MllpTimeoutError, type MllpWarning, type NackEvent, type NackReason, type NegativeAckCode, NetTransport, type PemInput, type ReconnectingEvent, type RetryContext, type RetryStrategy, type SecurityWarning, type SecurityWarningCode, type ServerOptions, type ServerStats, type ServerTlsOptions, type StarterClientOptions, type StarterServerOptions, type StateChangeEvent, type TlsOptions, TlsTransport, Transport, VERSION, type WarningCode, ackDiagnosticMessage, buildRawAck, createClient, createServer, createStarterClient, createStarterServer, createWarning, encodeFrame, isTlsProtocolError, isTlsVerificationErrorCode, isTransientConnectionError, rawAckUncorrelatable, resolveNackCode };

package/dist/index.mjs

@@ -2005,8 +2005,8 @@ var Correlator = class {
    *   removed from live store. Caller calls `entry.resolve(ackPayload)`.
    * - controlId: keyed lookup by `controlIdFromAck`. Live-store hit returns
    *   the entry; graveyard hit fires `MLLP_ACK_AFTER_TIMEOUT` warning
-   *   and returns `null`; otherwise fires
-   *   `onUnmatchedAck(controlIdFromAck)` and returns `null`.
+   *   and returns `null`; otherwise fires `onUnmatchedAck` with the id's
+   *   **byte length** and returns `null`.
    *
    * Triggers lazy graveyard eviction.
    *
@@ -2029,7 +2029,7 @@ var Correlator = class {
     }
     if (controlIdFromAck === null) {
       if (this._opts.onUnmatchedAck !== void 0) {
-        this._opts.onUnmatchedAck("");
+        this._opts.onUnmatchedAck(null);
       }
       return null;
     }
@@ -2044,7 +2044,9 @@ var Correlator = class {
     if (grave !== void 0) {
       const elapsedSinceSendMs = this._opts.now() - grave.timedOutAt;
       this._opts.onWarning("MLLP_ACK_AFTER_TIMEOUT", {
-        controlId: grave.controlId,
+        // The LENGTH, never the id. Control IDs are decoded `latin1`, a 1:1
+        // byte to code-unit map, so `.length` is a byte count.
+        controlIdBytes: grave.controlId === null ? null : grave.controlId.length,
         elapsedSinceSendMs,
         byteOffset: byteOffsetFromAck
       });
@@ -2052,7 +2054,7 @@ var Correlator = class {
       return null;
     }
     if (this._opts.onUnmatchedAck !== void 0) {
-      this._opts.onUnmatchedAck(controlIdFromAck);
+      this._opts.onUnmatchedAck(controlIdFromAck.length);
     }
     return null;
   }
@@ -2127,11 +2129,32 @@ var Correlator = class {
   }
 };
 
+// src/client/ack-diagnostics.ts
+var ACK_DIAGNOSTIC_MESSAGES = Object.freeze({
+  MLLP_ACK_UNMATCHED_CONTROL_ID: "Inbound ACK control ID matched no in-flight send and no timed-out send; the ACK was dropped. Field values are withheld: MSA-2 is inbound payload content and this diagnostic goes to a log. The inbound bytes are on the 'message' event; controlIdBytes gives the length.",
+  MLLP_ACK_AFTER_TIMEOUT: "ACK arrived after its send had already timed out; the ACK was dropped. Field values are withheld: a control ID is payload content and this diagnostic goes to a log. The outbound bytes are the payload you passed to send(); controlIdBytes gives the length."
+});
+function ackDiagnosticMessage(code) {
+  return ACK_DIAGNOSTIC_MESSAGES[code];
+}
+
 // src/client/error.ts
 var MllpTimeoutError = class _MllpTimeoutError extends Error {
   name = "MllpTimeoutError";
-  /** MSH-10 control ID of the timed-out send (FIFO mode: `undefined`). */
-  messageControlId;
+  /**
+   * Byte length of the timed-out send's MSH-10 control ID, or `undefined` when
+   * there was none to read (FIFO mode, or a payload with no MSH-10).
+   *
+   * **The control ID itself is deliberately not here.** An `Error` is a
+   * diagnostic surface: it is logged, and its `stack` is what an error reporter
+   * ships off the box. MSH-10 is payload content, and a scanner that returns
+   * the wrong field returns payload content of some other kind, which is how a
+   * patient identifier reaches a log line. Nothing is lost by withholding it,
+   * because this error rejects the very `send()` whose payload the caller
+   * passed in, so the caller already holds the bytes. Control IDs are decoded
+   * `latin1`, a 1:1 byte to code-unit map, so this count is a byte count.
+   */
+  messageControlIdBytes;
   /** Milliseconds elapsed between write-flush and timeout fire. */
   elapsedMs;
   /** Epoch ms timestamp recorded at write-flush callback. */
@@ -2139,12 +2162,12 @@ var MllpTimeoutError = class _MllpTimeoutError extends Error {
   /**
    * Construct an MLLP timeout error.
    *
-   * @param message - Human-readable error message.
-   * @param opts - Timeout context (originating message control id, elapsed time, flush timestamp).
+   * @param message - Human-readable error message. Structural facts only, never field content.
+   * @param opts - Timeout context (control-id byte length, elapsed time, flush timestamp).
    */
   constructor(message, opts) {
     super(message);
-    this.messageControlId = opts.messageControlId;
+    this.messageControlIdBytes = opts.messageControlIdBytes;
     this.elapsedMs = opts.elapsedMs;
     this.sentAt = opts.sentAt;
     if (Error.captureStackTrace) {
@@ -2587,31 +2610,34 @@ var MllpClient = class extends EventEmitter {
         maxInFlight: this._pipeline ? Number.POSITIVE_INFINITY : 1,
         onWarning: (code, ctx) => {
           this._aggregatedWarningsByCode[code] = (this._aggregatedWarningsByCode[code] ?? 0) + 1;
-          this._emitContained(
-            "warning",
-            Object.freeze({
-              code,
-              byteOffset: ctx.byteOffset,
-              message: `${code}: controlId=${ctx.controlId} elapsed=${ctx.elapsedSinceSendMs}ms`,
-              connectionId: this._connection?.connectionId ?? conn.connectionId,
-              timestamp: /* @__PURE__ */ new Date()
-            })
-          );
+          const warning = Object.freeze({
+            code,
+            byteOffset: ctx.byteOffset,
+            message: ackDiagnosticMessage(code),
+            controlIdBytes: ctx.controlIdBytes,
+            elapsedSinceSendMs: ctx.elapsedSinceSendMs,
+            connectionId: this._connection?.connectionId ?? conn.connectionId,
+            timestamp: /* @__PURE__ */ new Date()
+          });
+          this._emitContained("warning", warning);
         },
-        onUnmatchedAck: (controlId) => {
+        onUnmatchedAck: (controlIdBytes) => {
           if (this.listenerCount("error") === 0) return;
           const err = new MllpFramingError(
             "MLLP_ACK_UNMATCHED_CONTROL_ID",
             0,
             Buffer.alloc(0),
-            `Unmatched ACK control ID${controlId === "" ? "" : `: ${controlId}`}`
+            ackDiagnosticMessage("MLLP_ACK_UNMATCHED_CONTROL_ID")
           );
           safeEmitError(
             this,
             Object.freeze({
               connectionId: this._connection?.connectionId ?? conn.connectionId,
               error: err,
-              controlId
+              // The peer's MSA-2 byte LENGTH. The bytes themselves used to be
+              // here and on the message above; a peer sending a one-megabyte
+              // MSA-2 produced a one-megabyte Error.message, straight into a log.
+              controlIdBytes
             })
           );
         },
@@ -2619,7 +2645,7 @@ var MllpClient = class extends EventEmitter {
           this._timedOutTotal += 1;
           entry.reject(
             new MllpTimeoutError(`ACK timeout after ${elapsedMs}ms`, {
-              messageControlId: entry.controlId ?? void 0,
+              messageControlIdBytes: entry.controlId?.length,
               elapsedMs,
               sentAt: entry.sentAt ?? 0
             })
@@ -3172,7 +3198,7 @@ var MllpClient = class extends EventEmitter {
         cleanup();
         reject(
           new MllpTimeoutError(`waiting for drain timed out after ${ackTimeoutMs}ms`, {
-            messageControlId: void 0,
+            messageControlIdBytes: void 0,
             elapsedMs: ackTimeoutMs,
             sentAt: Date.now()
           })
@@ -3410,8 +3436,8 @@ async function createStarterClient(opts) {
 }
 
 // src/index.ts
-var VERSION = "0.0.3";
+var VERSION = "0.0.5";
 
-export { Connection, FrameReader, MLLP_BIND_ALL_INTERFACES, MLLP_TLS_VERIFY_DISABLED, MllpAckError, MllpBackpressureError, MllpClient, MllpConnectionError, MllpFramingError, MllpServer, MllpTimeoutError, NetTransport, TlsTransport, VERSION, buildRawAck, createClient, createServer, createStarterClient, createStarterServer, createWarning, encodeFrame, isTlsProtocolError, isTlsVerificationErrorCode, isTransientConnectionError, rawAckUncorrelatable, resolveNackCode };
+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 };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map