@cosyte/mllp 0.0.1 → 0.0.2

package/dist/ack-from-hl7/index.d.cts

@@ -2,7 +2,7 @@ import { AckCode, AckErrorDetail, Hl7Message, AckMode, BuildAckOptions, Hl7Parse
 export { AckCode, AckErrorDetail, AckMode } from '@cosyte/hl7';
 
 /**
- * `buildMllpAck` — a THIN transport adapter over `@cosyte/hl7`'s `buildAck`.
+ * `buildMllpAck`, a THIN transport adapter over `@cosyte/hl7`'s `buildAck`.
  *
  * `@cosyte/hl7` owns ACK **content** (MSH/MSA/ERR construction, the fail-safe
  * no-correlation downgrade); this module owns **transport policy**: accepting
@@ -53,7 +53,7 @@ interface MllpAckWarning {
 declare const MLLP_ACK_INBOUND_UNPARSEABLE = "MLLP_ACK_INBOUND_UNPARSEABLE";
 /**
  * Warning code emitted when the built ACK's MSA-2 bytes are **not** byte-identical
- * to the inbound MSH-10 bytes — i.e. the ACK does not echo the message control ID
+ * to the inbound MSH-10 bytes, i.e. the ACK does not echo the message control ID
  * verbatim, as HL7 v2.5.1 §2.9.2.2 requires.
  *
  * This is a **correlation failure**, and the reason it is a loud warning rather
@@ -61,7 +61,7 @@ declare const MLLP_ACK_INBOUND_UNPARSEABLE = "MLLP_ACK_INBOUND_UNPARSEABLE";
  * it put on the wire. An ACK whose MSA-2 differs by even one byte will not match
  * that key, so the send is never settled → ACK timeout → resend → **duplicate
  * clinical message**. Emitting the ACK anyway (rather than throwing) is the
- * fail-safe choice — a mismatched ACK still tells the peer *something* — but the
+ * fail-safe choice, a mismatched ACK still tells the peer *something*, but the
  * mismatch must never pass unremarked.
  *
  * `buildMllpAck` verifies this on every build, against the very same byte-level
@@ -73,7 +73,7 @@ declare const MLLP_ACK_INBOUND_UNPARSEABLE = "MLLP_ACK_INBOUND_UNPARSEABLE";
  * `string`/`Hl7Message` inbound has **already been decoded** before this module sees it:
  * the only thing left to compare against is that same text, encoded with the same codec,
  * so the codec cancels on both sides and a codec-induced mismatch is **structurally
- * invisible** — it warns about nothing. See {@link BuildMllpAckOptions.encoding}. Pass a
+ * invisible**, it warns about nothing. See {@link BuildMllpAckOptions.encoding}. Pass a
  * `Buffer` if you want this guarantee to mean anything.
  *
  * Two known ways to provoke it, both documented in the package limitations:
@@ -84,7 +84,7 @@ declare const MLLP_ACK_INBOUND_UNPARSEABLE = "MLLP_ACK_INBOUND_UNPARSEABLE";
  *   2. An inbound that declares **non-default encoding characters** (MSH-1/MSH-2).
  *      `@cosyte/hl7`'s `buildMessage` always emits the HL7 default `|^~\&`, so an
  *      inbound MSH-10 of `ID#X` under a `#` component separator is re-delimited to
- *      `ID^X` in MSA-2 — different bytes, unmatchable key. Use `buildRawAck` (root
+ *      `ID^X` in MSA-2, different bytes, unmatchable key. Use `buildRawAck` (root
  *      export), which echoes the inbound's own MSH-1/MSH-2, if you must serve such
  *      a peer.
  *
@@ -93,11 +93,63 @@ declare const MLLP_ACK_INBOUND_UNPARSEABLE = "MLLP_ACK_INBOUND_UNPARSEABLE";
  * import { MLLP_ACK_CONTROL_ID_NOT_VERBATIM, buildAckAA } from '@cosyte/mllp/ack-from-hl7';
  * const { warnings } = buildAckAA(inbound, { encoding: "ascii" });
  * if (warnings.some((w) => w.code === MLLP_ACK_CONTROL_ID_NOT_VERBATIM)) {
- *   // this ACK will NOT correlate at the sender — investigate before shipping it
+ *   // this ACK will NOT correlate at the sender, investigate before shipping it
  * }
  * ```
  */
 declare const MLLP_ACK_CONTROL_ID_NOT_VERBATIM = "MLLP_ACK_CONTROL_ID_NOT_VERBATIM";
+/**
+ * Warning code emitted when the inbound was handed in as **text** (a `string` or an
+ * already-parsed `Hl7Message`) rather than as raw `Buffer` bytes, and the ACK's MSA-2
+ * carries a **non-ASCII** control ID, a combination whose byte-verbatim echo
+ * (HL7 v2.5.1 §2.9.2.2) `buildMllpAck` **cannot verify**, and may silently be breaking.
+ *
+ * ## Why a distinct code from {@link MLLP_ACK_CONTROL_ID_NOT_VERBATIM}
+ *
+ * `MLLP_ACK_CONTROL_ID_NOT_VERBATIM` is a *proof of failure*: on a `Buffer` inbound the
+ * wire bytes are in hand, the check compares MSA-2 against them, and it fires only when
+ * they provably differ. This code is the opposite, a *confession that the proof cannot
+ * be run*. A `string`/`Hl7Message` inbound was decoded from its wire bytes **before** this
+ * module ever saw it, so the only thing left to compare the ACK against is that same text
+ * re-encoded with the same codec: the codec cancels on both sides and the verbatim check
+ * becomes a tautology that always passes (see {@link verifyVerbatimEcho}). It would report
+ * clean even for `buildAckAA(payload.toString("latin1"))` on a high-bit control ID, where
+ * a `latin1`-decoded `0x8B` is re-encoded as the two `utf8` bytes `0xC2 0x8B`, a *different*
+ * control ID the sender cannot correlate (timeout → resend → **duplicate clinical message**).
+ *
+ * The guard cannot be grown to catch that; by the time text arrives the bytes are gone.
+ * The API can, and does: rather than let the text path pass a codec-sensitive control ID
+ * off as verified, `buildMllpAck` refuses to stay silent about it. Whenever the ACK's MSA-2
+ * control ID holds a code unit outside `0x00`–`0x7F` on a text inbound, the range where the
+ * codec choice is load-bearing, it emits this warning. An all-ASCII control ID round-trips
+ * identically under every codec, so the common case stays quiet; a non-ASCII one is flagged as
+ * *unverifiable*, not as *known-broken*, because from a decoded string the two are genuinely
+ * indistinguishable.
+ *
+ * The check reads the **pre-encoding code units** of MSA-2, not the emitted bytes, so a lossy
+ * `{ encoding: "ascii" }` override, which truncates a code unit to its low 8 bits (`str -> byte &
+ * 0xFF`) and so masks a code unit above `0xFF` *into* the ASCII byte range on the way out (`U+0153`
+ * -> `0x53`), cannot slip a corrupted control ID past it silently (MLLP-ACK-ASCII-OVERRIDE-BLEED).
+ * The strongly-discouraged text-plus-override path is covered for the same reason the default `utf8`
+ * text path is; the `Buffer` overload remains the answer.
+ *
+ * **The fix the warning points at is the `Buffer`-first API rule.** Pass the raw payload,
+ * the bytes the server handed you, and you get the real byte-level check (and, if it breaks,
+ * the definite {@link MLLP_ACK_CONTROL_ID_NOT_VERBATIM}) instead of this "cannot tell".
+ *
+ * Like its sibling, this warning carries byte **lengths** only, never the field bytes
+ * (MSH-10 is inbound payload content and a warning goes to a log; see {@link verifyVerbatimEcho}).
+ *
+ * @example
+ * ```typescript
+ * import { MLLP_ACK_CONTROL_ID_UNVERIFIABLE, buildAckAA } from '@cosyte/mllp/ack-from-hl7';
+ * const { warnings } = buildAckAA(payload.toString("latin1")); // text inbound, high-bit id
+ * if (warnings.some((w) => w.code === MLLP_ACK_CONTROL_ID_UNVERIFIABLE)) {
+ *   // pass the raw Buffer instead, the echo cannot be verified from decoded text
+ * }
+ * ```
+ */
+declare const MLLP_ACK_CONTROL_ID_UNVERIFIABLE = "MLLP_ACK_CONTROL_ID_UNVERIFIABLE";
 /**
  * Options for {@link buildMllpAck} and its six convenience wrappers.
  *
@@ -113,7 +165,7 @@ interface BuildMllpAckOptions {
     /** Optional error detail; one entry emits one ERR segment. */
     readonly error?: AckErrorDetail | readonly AckErrorDetail[];
     /**
-     * The codec used to move the ACK between bytes and text — **both** directions,
+     * The codec used to move the ACK between bytes and text, **both** directions,
      * as a single symmetric choice. It decodes a raw-`Buffer` `inbound` on the way in
      * and encodes the serialized ACK on the way out, so the ACK is emitted in the same
      * codec the inbound was read in.
@@ -122,13 +174,13 @@ interface BuildMllpAckOptions {
      * **verbatim** (HL7 v2.5.1 §2.9.2.2). Decoding in one codec and encoding in another
      * corrupts every non-ASCII byte it round-trips: a `latin1`-decoded `0x8B` re-encoded
      * as `utf8` goes out as the two bytes `0xC2 0x8B`, which is a *different control ID*
-     * — and the sender, which keyed its in-flight store on `0x8B`, cannot match the ACK.
+     * and the sender, which keyed its in-flight store on `0x8B`, cannot match the ACK.
      *
      * **Defaults, by inbound type:**
      *
      * - `Buffer` → **`"latin1"`**. We own the decode, and `latin1` is the only codec
      *   that round-trips arbitrary bytes losslessly, so MSA-2 is byte-verbatim for any
-     *   charset — including an MSH-18 of `8859/1` with high-bit bytes in the control ID.
+     *   charset, including an MSH-18 of `8859/1` with high-bit bytes in the control ID.
      * - `string` / `Hl7Message` → **`"utf8"`**. The caller already decoded; we re-encode
      *   with the JS-native codec.
      *
@@ -136,33 +188,52 @@ interface BuildMllpAckOptions {
      * raw-`Buffer` inbound gives up the verbatim guarantee for non-ASCII bytes (`"ascii"`
      * masks the high bit; `"utf8"` folds invalid sequences onto `U+FFFD`). On a `Buffer`,
      * `buildMllpAck` **checks** the result and emits {@link MLLP_ACK_CONTROL_ID_NOT_VERBATIM}
-     * if the echo did not survive, so a bad override there is loud rather than silent — but
+     * if the echo did not survive, so a bad override there is loud rather than silent, but
      * it is still a broken ACK. Set this only when the receiving system genuinely demands a
      * specific codec.
      *
-     * **On a `string` / `Hl7Message` inbound the check cannot see a codec problem at all.**
-     * The wire bytes were decoded to text *before* this function saw them, so there is
-     * nothing left to compare the ACK against except that same text — the codec cancels on
-     * both sides and the comparison is a tautology. Concretely,
-     * `buildAckAA(payload.toString("latin1"))` on a high-bit control ID (`0x8B`, legal under
-     * an `MSH-18` of `8859/1`) re-encodes it as the two `utf8` bytes `0xC2 0x8B`, emits a
-     * **different** control ID, and warns about **nothing** — the sender cannot correlate it.
-     * This is not a hole the guard can be grown to cover; the bytes are gone by then.
+     * **On a `string` / `Hl7Message` inbound the verbatim check cannot see a codec problem,
+     * so a *different* warning does the honest thing instead.** The wire bytes were decoded to
+     * text *before* this function saw them, so there is nothing left to compare the ACK against
+     * except that same text: the codec cancels on both sides and {@link MLLP_ACK_CONTROL_ID_NOT_VERBATIM}
+     * can never fire. Concretely, `buildAckAA(payload.toString("latin1"))` on a high-bit control ID
+     * (`0x8B`, legal under an `MSH-18` of `8859/1`) re-encodes it as the two `utf8` bytes `0xC2 0x8B`,
+     * emitting a **different** control ID the sender cannot correlate. The verbatim check is blind to
+     * that, but the byte-safety of a text inbound cannot be *proven*, so `buildMllpAck` refuses to
+     * pass it off as verified: whenever the emitted MSA-2 holds a non-ASCII byte on a text inbound it
+     * emits {@link MLLP_ACK_CONTROL_ID_UNVERIFIABLE}, an explicit "cannot verify, pass a `Buffer`".
+     * The guard is not grown to *catch* the mismatch (the bytes are gone by then); the API stops
+     * being silent about the fact that it can't.
      *
      * **`Buffer` is the byte-safe path.** Pass the raw payload. It is what the server hands
      * you, it is what the `Buffer`-first API rule exists for, and it is the only input for
-     * which the verbatim guarantee — or a warning that it broke — actually means anything.
+     * which the verbatim guarantee, or a proof that it broke, actually means anything.
+     *
+     * **Only a *text* codec is accepted, on every input shape.** This codec serializes the ACK
+     * back to bytes, so it must be one that writes characters as a byte stream the peer can read as
+     * HL7: `"utf8"`, `"ascii"`, `"latin1"`, or `"binary"`. A **non-text** codec,
+     * `"base64"`/`"base64url"`/`"hex"` (which reinterpret the ACK *string* as encoded data) or
+     * `"utf16le"`/`"ucs2"` (which NUL-pad every byte), emits a wholesale-garbage frame the receiver
+     * cannot parse, so `buildMllpAck` **throws a `TypeError`** for it here rather than hand back an
+     * unusable ACK. This applies to a `Buffer` inbound too (MLLP-ACK-NONTEXT-CODEC-BUFFER): a
+     * non-text codec there garbles the *inbound* decode into the unparseable fallback (empty MSA-2,
+     * so the {@link MLLP_ACK_CONTROL_ID_NOT_VERBATIM} check never runs) and then serializes the
+     * fallback ACK to garbage bytes that intermittently trip the strict frame encoder, it is never
+     * the "loud AE" it was once documented to be. The legitimate byte-level escape hatch is
+     * unchanged: a lossy **charset** override on a `Buffer` (`"ascii"` masking a high bit) is still
+     * accepted and still caught loudly by {@link MLLP_ACK_CONTROL_ID_NOT_VERBATIM}; only the
+     * categorically-non-serializing codecs are refused.
      */
     readonly encoding?: BufferEncoding;
     /**
      * Passthrough to `encodeFrame`'s `allowDelimiterBytesInPayload`. Defaults
-     * to `false` (strict — throws if the serialized ACK somehow contains a
+     * to `false` (strict, throws if the serialized ACK somehow contains a
      * VT/FS byte, which a spec-clean `@cosyte/hl7` emit never does).
      */
     readonly allowDelimiterBytesInPayload?: boolean;
 }
 /**
- * Result of {@link buildMllpAck} — a ready-to-write MLLP frame plus the
+ * Result of {@link buildMllpAck}, a ready-to-write MLLP frame plus the
  * metadata needed to log or assert on what was actually emitted. Frozen
  * (including the `warnings` array) so subscribers cannot mutate shared state.
  *
@@ -193,24 +264,28 @@ interface MllpAck {
     readonly warnings: readonly MllpAckWarning[];
 }
 /**
- * Build a framed MLLP ACK from an inbound HL7 v2 message — the core
+ * Build a framed MLLP ACK from an inbound HL7 v2 message, the core
  * `ack-from-hl7` adapter. `inbound` may be an already-parsed `Hl7Message`, or
  * raw bytes/text to parse first.
  *
  * Behavior:
- * - **Fatally unparseable inbound** (`Hl7ParseError`) — never emits a
+ * - **Fatally unparseable inbound** (`Hl7ParseError`), never emits a
  *   positive code: `AA`→`AE`, `CA`→`CE`; other codes pass through. MSA-2 is
  *   empty, `correlationId` and `mode` are `undefined`, and `warnings`
  *   contains one {@link MLLP_ACK_INBOUND_UNPARSEABLE} entry naming the fatal
- *   code — never any inbound payload bytes.
- * - **Normal path** — detects the ack mode from inbound MSH-15/16, delegates
+ *   code, never any inbound payload bytes.
+ * - **Normal path**, detects the ack mode from inbound MSH-15/16, delegates
  *   to `@cosyte/hl7`'s `buildAck` (which applies its own no-correlation
  *   fail-safe), and forwards `buildAck`'s own warnings (mapped to
- *   `{ code, message }`). Inbound parse warnings are NOT forwarded — they are
+ *   `{ code, message }`). Inbound parse warnings are NOT forwarded, they are
  *   the caller's concern if they parsed the inbound themselves.
  *
  * @throws {MllpPeerMissingError} when `@cosyte/hl7` is not installed.
- * @throws {TypeError} when `options.code` is not a known HL7 Table 0008 code.
+ * @throws {TypeError} when `options.code` is not a known HL7 Table 0008 code, or when
+ *   `options.encoding` is a **non-text** codec (`base64`/`base64url`/`hex`/`utf16le`/`ucs2`)
+ *   on **any** inbound, it would serialize a garbage frame the receiver cannot parse
+ *   (MLLP-ACK-NONTEXT-CODEC-FRAME / MLLP-ACK-NONTEXT-CODEC-BUFFER). See
+ *   {@link BuildMllpAckOptions.encoding}.
  *
  * @example
  * ```typescript
@@ -287,14 +362,14 @@ declare function buildAckCR(inbound: Hl7Message | Buffer | string, options?: Omi
  * who import both from `@cosyte/hl7` and `@cosyte/mllp/ack-from-hl7`.
  *
  * `inbound` may be an already-parsed `Hl7Message`, or raw bytes/text to parse
- * first. A fatal parse failure rethrows the `Hl7ParseError` as-is — unlike
+ * first. A fatal parse failure rethrows the `Hl7ParseError` as-is, unlike
  * {@link buildMllpAck}, there is no ACK to build here, so there is no
  * fallback to construct.
  *
  * **Module-realm note:** this adapter loads `@cosyte/hl7` lazily via
  * `createRequire` (see `peer.ts`). If your code ALSO does
  * `import { Hl7ParseError } from "@cosyte/hl7"` directly, Node's module
- * resolution can — depending on your bundler/runtime — hand you a distinct
+ * resolution can, depending on your bundler/runtime, hand you a distinct
  * module instance than the one this adapter loaded, in which case
  * `caught instanceof Hl7ParseError` (your import) may be `false` even though
  * `caught.name === "Hl7ParseError"` and `caught.code` is a valid HL7 fatal
@@ -318,8 +393,8 @@ declare function detectMode(inbound: Hl7Message | Buffer | string): AckMode;
  *
  * `@cosyte/mllp` ships **zero runtime dependencies**; `@cosyte/hl7` is an
  * optional peer dep referenced only from this `/ack-from-hl7` subpath. To keep
- * the rest of the package fully dependency-free, the peer is required lazily —
- * on first call into `ack-from-hl7` — via `createRequire`, not at module load
+ * the rest of the package fully dependency-free, the peer is required lazily,
+ * on first call into `ack-from-hl7`, via `createRequire`, not at module load
  * time. The public API of this subpath stays synchronous throughout.
  *
  * @example
@@ -334,7 +409,7 @@ declare function detectMode(inbound: Hl7Message | Buffer | string): AckMode;
 /**
  * The subset of the `@cosyte/hl7` runtime surface the `ack-from-hl7` adapter
  * consumes. Kept narrow and typed via `import type` (erased at compile time)
- * so the runtime dependency stays fully lazy — only the shape is known
+ * so the runtime dependency stays fully lazy, only the shape is known
  * statically, the values are resolved via `require()` at first call.
  *
  * @example
@@ -354,7 +429,7 @@ interface Hl7Peer {
     }) => Hl7Message;
     /**
      * The peer's own `Hl7Message` class. Exposed (not just used as a type) so
-     * callers can detect a cross-realm instance — see the dual-package-hazard
+     * callers can detect a cross-realm instance, see the dual-package-hazard
      * note on `resolveInbound` in `build.ts`. Typed as `abstract new` (rather
      * than a concrete constructor signature) purely so TypeScript accepts it as
      * an `instanceof` right-hand side without also implying callers can `new`
@@ -366,14 +441,14 @@ interface Hl7Peer {
     readonly ACK_CODES: typeof ACK_CODES;
     /**
      * The peer's fail-safe downgrade primitive (`AA`→`AE`, `CA`→`CE`, everything
-     * else unchanged) — the single upstream source of truth for the pair; this
+     * else unchanged), the single upstream source of truth for the pair; this
      * adapter never carries its own copy of the mapping.
      */
     readonly downgradePositiveAck: (code: AckCode) => AckCode;
 }
 /**
- * Thrown when `@cosyte/hl7` — the optional peer dependency required by
- * `@cosyte/mllp/ack-from-hl7` — cannot be resolved at runtime.
+ * Thrown when `@cosyte/hl7`, the optional peer dependency required by
+ * `@cosyte/mllp/ack-from-hl7`, cannot be resolved at runtime.
  *
  * `@cosyte/hl7` is declared as an optional peer dependency, so a consumer of
  * the root `@cosyte/mllp` entry point is never forced to install it. Only
@@ -405,7 +480,7 @@ declare class MllpPeerMissingError extends Error {
 }
 /**
  * Load the `@cosyte/hl7` peer module, caching the result for subsequent
- * calls. The public adapter functions in `build.ts` call this internally —
+ * calls. The public adapter functions in `build.ts` call this internally,
  * most consumers never call it directly.
  *
  * @param requireFn - Injectable `require`-like function, used by tests to
@@ -422,4 +497,4 @@ declare class MllpPeerMissingError extends Error {
  */
 declare function loadHl7Peer(requireFn?: (id: string) => unknown): Hl7Peer;
 
-export { type BuildMllpAckOptions, type Hl7Peer, MLLP_ACK_CONTROL_ID_NOT_VERBATIM, MLLP_ACK_INBOUND_UNPARSEABLE, type MllpAck, type MllpAckWarning, MllpPeerMissingError, buildAckAA, buildAckAE, buildAckAR, buildAckCA, buildAckCE, buildAckCR, buildMllpAck, detectMode, loadHl7Peer };
+export { type BuildMllpAckOptions, type Hl7Peer, MLLP_ACK_CONTROL_ID_NOT_VERBATIM, MLLP_ACK_CONTROL_ID_UNVERIFIABLE, MLLP_ACK_INBOUND_UNPARSEABLE, type MllpAck, type MllpAckWarning, MllpPeerMissingError, buildAckAA, buildAckAE, buildAckAR, buildAckCA, buildAckCE, buildAckCR, buildMllpAck, detectMode, loadHl7Peer };

package/dist/ack-from-hl7/index.d.ts

@@ -2,7 +2,7 @@ import { AckCode, AckErrorDetail, Hl7Message, AckMode, BuildAckOptions, Hl7Parse
 export { AckCode, AckErrorDetail, AckMode } from '@cosyte/hl7';
 
 /**
- * `buildMllpAck` — a THIN transport adapter over `@cosyte/hl7`'s `buildAck`.
+ * `buildMllpAck`, a THIN transport adapter over `@cosyte/hl7`'s `buildAck`.
  *
  * `@cosyte/hl7` owns ACK **content** (MSH/MSA/ERR construction, the fail-safe
  * no-correlation downgrade); this module owns **transport policy**: accepting
@@ -53,7 +53,7 @@ interface MllpAckWarning {
 declare const MLLP_ACK_INBOUND_UNPARSEABLE = "MLLP_ACK_INBOUND_UNPARSEABLE";
 /**
  * Warning code emitted when the built ACK's MSA-2 bytes are **not** byte-identical
- * to the inbound MSH-10 bytes — i.e. the ACK does not echo the message control ID
+ * to the inbound MSH-10 bytes, i.e. the ACK does not echo the message control ID
  * verbatim, as HL7 v2.5.1 §2.9.2.2 requires.
  *
  * This is a **correlation failure**, and the reason it is a loud warning rather
@@ -61,7 +61,7 @@ declare const MLLP_ACK_INBOUND_UNPARSEABLE = "MLLP_ACK_INBOUND_UNPARSEABLE";
  * it put on the wire. An ACK whose MSA-2 differs by even one byte will not match
  * that key, so the send is never settled → ACK timeout → resend → **duplicate
  * clinical message**. Emitting the ACK anyway (rather than throwing) is the
- * fail-safe choice — a mismatched ACK still tells the peer *something* — but the
+ * fail-safe choice, a mismatched ACK still tells the peer *something*, but the
  * mismatch must never pass unremarked.
  *
  * `buildMllpAck` verifies this on every build, against the very same byte-level
@@ -73,7 +73,7 @@ declare const MLLP_ACK_INBOUND_UNPARSEABLE = "MLLP_ACK_INBOUND_UNPARSEABLE";
  * `string`/`Hl7Message` inbound has **already been decoded** before this module sees it:
  * the only thing left to compare against is that same text, encoded with the same codec,
  * so the codec cancels on both sides and a codec-induced mismatch is **structurally
- * invisible** — it warns about nothing. See {@link BuildMllpAckOptions.encoding}. Pass a
+ * invisible**, it warns about nothing. See {@link BuildMllpAckOptions.encoding}. Pass a
  * `Buffer` if you want this guarantee to mean anything.
  *
  * Two known ways to provoke it, both documented in the package limitations:
@@ -84,7 +84,7 @@ declare const MLLP_ACK_INBOUND_UNPARSEABLE = "MLLP_ACK_INBOUND_UNPARSEABLE";
  *   2. An inbound that declares **non-default encoding characters** (MSH-1/MSH-2).
  *      `@cosyte/hl7`'s `buildMessage` always emits the HL7 default `|^~\&`, so an
  *      inbound MSH-10 of `ID#X` under a `#` component separator is re-delimited to
- *      `ID^X` in MSA-2 — different bytes, unmatchable key. Use `buildRawAck` (root
+ *      `ID^X` in MSA-2, different bytes, unmatchable key. Use `buildRawAck` (root
  *      export), which echoes the inbound's own MSH-1/MSH-2, if you must serve such
  *      a peer.
  *
@@ -93,11 +93,63 @@ declare const MLLP_ACK_INBOUND_UNPARSEABLE = "MLLP_ACK_INBOUND_UNPARSEABLE";
  * import { MLLP_ACK_CONTROL_ID_NOT_VERBATIM, buildAckAA } from '@cosyte/mllp/ack-from-hl7';
  * const { warnings } = buildAckAA(inbound, { encoding: "ascii" });
  * if (warnings.some((w) => w.code === MLLP_ACK_CONTROL_ID_NOT_VERBATIM)) {
- *   // this ACK will NOT correlate at the sender — investigate before shipping it
+ *   // this ACK will NOT correlate at the sender, investigate before shipping it
  * }
  * ```
  */
 declare const MLLP_ACK_CONTROL_ID_NOT_VERBATIM = "MLLP_ACK_CONTROL_ID_NOT_VERBATIM";
+/**
+ * Warning code emitted when the inbound was handed in as **text** (a `string` or an
+ * already-parsed `Hl7Message`) rather than as raw `Buffer` bytes, and the ACK's MSA-2
+ * carries a **non-ASCII** control ID, a combination whose byte-verbatim echo
+ * (HL7 v2.5.1 §2.9.2.2) `buildMllpAck` **cannot verify**, and may silently be breaking.
+ *
+ * ## Why a distinct code from {@link MLLP_ACK_CONTROL_ID_NOT_VERBATIM}
+ *
+ * `MLLP_ACK_CONTROL_ID_NOT_VERBATIM` is a *proof of failure*: on a `Buffer` inbound the
+ * wire bytes are in hand, the check compares MSA-2 against them, and it fires only when
+ * they provably differ. This code is the opposite, a *confession that the proof cannot
+ * be run*. A `string`/`Hl7Message` inbound was decoded from its wire bytes **before** this
+ * module ever saw it, so the only thing left to compare the ACK against is that same text
+ * re-encoded with the same codec: the codec cancels on both sides and the verbatim check
+ * becomes a tautology that always passes (see {@link verifyVerbatimEcho}). It would report
+ * clean even for `buildAckAA(payload.toString("latin1"))` on a high-bit control ID, where
+ * a `latin1`-decoded `0x8B` is re-encoded as the two `utf8` bytes `0xC2 0x8B`, a *different*
+ * control ID the sender cannot correlate (timeout → resend → **duplicate clinical message**).
+ *
+ * The guard cannot be grown to catch that; by the time text arrives the bytes are gone.
+ * The API can, and does: rather than let the text path pass a codec-sensitive control ID
+ * off as verified, `buildMllpAck` refuses to stay silent about it. Whenever the ACK's MSA-2
+ * control ID holds a code unit outside `0x00`–`0x7F` on a text inbound, the range where the
+ * codec choice is load-bearing, it emits this warning. An all-ASCII control ID round-trips
+ * identically under every codec, so the common case stays quiet; a non-ASCII one is flagged as
+ * *unverifiable*, not as *known-broken*, because from a decoded string the two are genuinely
+ * indistinguishable.
+ *
+ * The check reads the **pre-encoding code units** of MSA-2, not the emitted bytes, so a lossy
+ * `{ encoding: "ascii" }` override, which truncates a code unit to its low 8 bits (`str -> byte &
+ * 0xFF`) and so masks a code unit above `0xFF` *into* the ASCII byte range on the way out (`U+0153`
+ * -> `0x53`), cannot slip a corrupted control ID past it silently (MLLP-ACK-ASCII-OVERRIDE-BLEED).
+ * The strongly-discouraged text-plus-override path is covered for the same reason the default `utf8`
+ * text path is; the `Buffer` overload remains the answer.
+ *
+ * **The fix the warning points at is the `Buffer`-first API rule.** Pass the raw payload,
+ * the bytes the server handed you, and you get the real byte-level check (and, if it breaks,
+ * the definite {@link MLLP_ACK_CONTROL_ID_NOT_VERBATIM}) instead of this "cannot tell".
+ *
+ * Like its sibling, this warning carries byte **lengths** only, never the field bytes
+ * (MSH-10 is inbound payload content and a warning goes to a log; see {@link verifyVerbatimEcho}).
+ *
+ * @example
+ * ```typescript
+ * import { MLLP_ACK_CONTROL_ID_UNVERIFIABLE, buildAckAA } from '@cosyte/mllp/ack-from-hl7';
+ * const { warnings } = buildAckAA(payload.toString("latin1")); // text inbound, high-bit id
+ * if (warnings.some((w) => w.code === MLLP_ACK_CONTROL_ID_UNVERIFIABLE)) {
+ *   // pass the raw Buffer instead, the echo cannot be verified from decoded text
+ * }
+ * ```
+ */
+declare const MLLP_ACK_CONTROL_ID_UNVERIFIABLE = "MLLP_ACK_CONTROL_ID_UNVERIFIABLE";
 /**
  * Options for {@link buildMllpAck} and its six convenience wrappers.
  *
@@ -113,7 +165,7 @@ interface BuildMllpAckOptions {
     /** Optional error detail; one entry emits one ERR segment. */
     readonly error?: AckErrorDetail | readonly AckErrorDetail[];
     /**
-     * The codec used to move the ACK between bytes and text — **both** directions,
+     * The codec used to move the ACK between bytes and text, **both** directions,
      * as a single symmetric choice. It decodes a raw-`Buffer` `inbound` on the way in
      * and encodes the serialized ACK on the way out, so the ACK is emitted in the same
      * codec the inbound was read in.
@@ -122,13 +174,13 @@ interface BuildMllpAckOptions {
      * **verbatim** (HL7 v2.5.1 §2.9.2.2). Decoding in one codec and encoding in another
      * corrupts every non-ASCII byte it round-trips: a `latin1`-decoded `0x8B` re-encoded
      * as `utf8` goes out as the two bytes `0xC2 0x8B`, which is a *different control ID*
-     * — and the sender, which keyed its in-flight store on `0x8B`, cannot match the ACK.
+     * and the sender, which keyed its in-flight store on `0x8B`, cannot match the ACK.
      *
      * **Defaults, by inbound type:**
      *
      * - `Buffer` → **`"latin1"`**. We own the decode, and `latin1` is the only codec
      *   that round-trips arbitrary bytes losslessly, so MSA-2 is byte-verbatim for any
-     *   charset — including an MSH-18 of `8859/1` with high-bit bytes in the control ID.
+     *   charset, including an MSH-18 of `8859/1` with high-bit bytes in the control ID.
      * - `string` / `Hl7Message` → **`"utf8"`**. The caller already decoded; we re-encode
      *   with the JS-native codec.
      *
@@ -136,33 +188,52 @@ interface BuildMllpAckOptions {
      * raw-`Buffer` inbound gives up the verbatim guarantee for non-ASCII bytes (`"ascii"`
      * masks the high bit; `"utf8"` folds invalid sequences onto `U+FFFD`). On a `Buffer`,
      * `buildMllpAck` **checks** the result and emits {@link MLLP_ACK_CONTROL_ID_NOT_VERBATIM}
-     * if the echo did not survive, so a bad override there is loud rather than silent — but
+     * if the echo did not survive, so a bad override there is loud rather than silent, but
      * it is still a broken ACK. Set this only when the receiving system genuinely demands a
      * specific codec.
      *
-     * **On a `string` / `Hl7Message` inbound the check cannot see a codec problem at all.**
-     * The wire bytes were decoded to text *before* this function saw them, so there is
-     * nothing left to compare the ACK against except that same text — the codec cancels on
-     * both sides and the comparison is a tautology. Concretely,
-     * `buildAckAA(payload.toString("latin1"))` on a high-bit control ID (`0x8B`, legal under
-     * an `MSH-18` of `8859/1`) re-encodes it as the two `utf8` bytes `0xC2 0x8B`, emits a
-     * **different** control ID, and warns about **nothing** — the sender cannot correlate it.
-     * This is not a hole the guard can be grown to cover; the bytes are gone by then.
+     * **On a `string` / `Hl7Message` inbound the verbatim check cannot see a codec problem,
+     * so a *different* warning does the honest thing instead.** The wire bytes were decoded to
+     * text *before* this function saw them, so there is nothing left to compare the ACK against
+     * except that same text: the codec cancels on both sides and {@link MLLP_ACK_CONTROL_ID_NOT_VERBATIM}
+     * can never fire. Concretely, `buildAckAA(payload.toString("latin1"))` on a high-bit control ID
+     * (`0x8B`, legal under an `MSH-18` of `8859/1`) re-encodes it as the two `utf8` bytes `0xC2 0x8B`,
+     * emitting a **different** control ID the sender cannot correlate. The verbatim check is blind to
+     * that, but the byte-safety of a text inbound cannot be *proven*, so `buildMllpAck` refuses to
+     * pass it off as verified: whenever the emitted MSA-2 holds a non-ASCII byte on a text inbound it
+     * emits {@link MLLP_ACK_CONTROL_ID_UNVERIFIABLE}, an explicit "cannot verify, pass a `Buffer`".
+     * The guard is not grown to *catch* the mismatch (the bytes are gone by then); the API stops
+     * being silent about the fact that it can't.
      *
      * **`Buffer` is the byte-safe path.** Pass the raw payload. It is what the server hands
      * you, it is what the `Buffer`-first API rule exists for, and it is the only input for
-     * which the verbatim guarantee — or a warning that it broke — actually means anything.
+     * which the verbatim guarantee, or a proof that it broke, actually means anything.
+     *
+     * **Only a *text* codec is accepted, on every input shape.** This codec serializes the ACK
+     * back to bytes, so it must be one that writes characters as a byte stream the peer can read as
+     * HL7: `"utf8"`, `"ascii"`, `"latin1"`, or `"binary"`. A **non-text** codec,
+     * `"base64"`/`"base64url"`/`"hex"` (which reinterpret the ACK *string* as encoded data) or
+     * `"utf16le"`/`"ucs2"` (which NUL-pad every byte), emits a wholesale-garbage frame the receiver
+     * cannot parse, so `buildMllpAck` **throws a `TypeError`** for it here rather than hand back an
+     * unusable ACK. This applies to a `Buffer` inbound too (MLLP-ACK-NONTEXT-CODEC-BUFFER): a
+     * non-text codec there garbles the *inbound* decode into the unparseable fallback (empty MSA-2,
+     * so the {@link MLLP_ACK_CONTROL_ID_NOT_VERBATIM} check never runs) and then serializes the
+     * fallback ACK to garbage bytes that intermittently trip the strict frame encoder, it is never
+     * the "loud AE" it was once documented to be. The legitimate byte-level escape hatch is
+     * unchanged: a lossy **charset** override on a `Buffer` (`"ascii"` masking a high bit) is still
+     * accepted and still caught loudly by {@link MLLP_ACK_CONTROL_ID_NOT_VERBATIM}; only the
+     * categorically-non-serializing codecs are refused.
      */
     readonly encoding?: BufferEncoding;
     /**
      * Passthrough to `encodeFrame`'s `allowDelimiterBytesInPayload`. Defaults
-     * to `false` (strict — throws if the serialized ACK somehow contains a
+     * to `false` (strict, throws if the serialized ACK somehow contains a
      * VT/FS byte, which a spec-clean `@cosyte/hl7` emit never does).
      */
     readonly allowDelimiterBytesInPayload?: boolean;
 }
 /**
- * Result of {@link buildMllpAck} — a ready-to-write MLLP frame plus the
+ * Result of {@link buildMllpAck}, a ready-to-write MLLP frame plus the
  * metadata needed to log or assert on what was actually emitted. Frozen
  * (including the `warnings` array) so subscribers cannot mutate shared state.
  *
@@ -193,24 +264,28 @@ interface MllpAck {
     readonly warnings: readonly MllpAckWarning[];
 }
 /**
- * Build a framed MLLP ACK from an inbound HL7 v2 message — the core
+ * Build a framed MLLP ACK from an inbound HL7 v2 message, the core
  * `ack-from-hl7` adapter. `inbound` may be an already-parsed `Hl7Message`, or
  * raw bytes/text to parse first.
  *
  * Behavior:
- * - **Fatally unparseable inbound** (`Hl7ParseError`) — never emits a
+ * - **Fatally unparseable inbound** (`Hl7ParseError`), never emits a
  *   positive code: `AA`→`AE`, `CA`→`CE`; other codes pass through. MSA-2 is
  *   empty, `correlationId` and `mode` are `undefined`, and `warnings`
  *   contains one {@link MLLP_ACK_INBOUND_UNPARSEABLE} entry naming the fatal
- *   code — never any inbound payload bytes.
- * - **Normal path** — detects the ack mode from inbound MSH-15/16, delegates
+ *   code, never any inbound payload bytes.
+ * - **Normal path**, detects the ack mode from inbound MSH-15/16, delegates
  *   to `@cosyte/hl7`'s `buildAck` (which applies its own no-correlation
  *   fail-safe), and forwards `buildAck`'s own warnings (mapped to
- *   `{ code, message }`). Inbound parse warnings are NOT forwarded — they are
+ *   `{ code, message }`). Inbound parse warnings are NOT forwarded, they are
  *   the caller's concern if they parsed the inbound themselves.
  *
  * @throws {MllpPeerMissingError} when `@cosyte/hl7` is not installed.
- * @throws {TypeError} when `options.code` is not a known HL7 Table 0008 code.
+ * @throws {TypeError} when `options.code` is not a known HL7 Table 0008 code, or when
+ *   `options.encoding` is a **non-text** codec (`base64`/`base64url`/`hex`/`utf16le`/`ucs2`)
+ *   on **any** inbound, it would serialize a garbage frame the receiver cannot parse
+ *   (MLLP-ACK-NONTEXT-CODEC-FRAME / MLLP-ACK-NONTEXT-CODEC-BUFFER). See
+ *   {@link BuildMllpAckOptions.encoding}.
  *
  * @example
  * ```typescript
@@ -287,14 +362,14 @@ declare function buildAckCR(inbound: Hl7Message | Buffer | string, options?: Omi
  * who import both from `@cosyte/hl7` and `@cosyte/mllp/ack-from-hl7`.
  *
  * `inbound` may be an already-parsed `Hl7Message`, or raw bytes/text to parse
- * first. A fatal parse failure rethrows the `Hl7ParseError` as-is — unlike
+ * first. A fatal parse failure rethrows the `Hl7ParseError` as-is, unlike
  * {@link buildMllpAck}, there is no ACK to build here, so there is no
  * fallback to construct.
  *
  * **Module-realm note:** this adapter loads `@cosyte/hl7` lazily via
  * `createRequire` (see `peer.ts`). If your code ALSO does
  * `import { Hl7ParseError } from "@cosyte/hl7"` directly, Node's module
- * resolution can — depending on your bundler/runtime — hand you a distinct
+ * resolution can, depending on your bundler/runtime, hand you a distinct
  * module instance than the one this adapter loaded, in which case
  * `caught instanceof Hl7ParseError` (your import) may be `false` even though
  * `caught.name === "Hl7ParseError"` and `caught.code` is a valid HL7 fatal
@@ -318,8 +393,8 @@ declare function detectMode(inbound: Hl7Message | Buffer | string): AckMode;
  *
  * `@cosyte/mllp` ships **zero runtime dependencies**; `@cosyte/hl7` is an
  * optional peer dep referenced only from this `/ack-from-hl7` subpath. To keep
- * the rest of the package fully dependency-free, the peer is required lazily —
- * on first call into `ack-from-hl7` — via `createRequire`, not at module load
+ * the rest of the package fully dependency-free, the peer is required lazily,
+ * on first call into `ack-from-hl7`, via `createRequire`, not at module load
  * time. The public API of this subpath stays synchronous throughout.
  *
  * @example
@@ -334,7 +409,7 @@ declare function detectMode(inbound: Hl7Message | Buffer | string): AckMode;
 /**
  * The subset of the `@cosyte/hl7` runtime surface the `ack-from-hl7` adapter
  * consumes. Kept narrow and typed via `import type` (erased at compile time)
- * so the runtime dependency stays fully lazy — only the shape is known
+ * so the runtime dependency stays fully lazy, only the shape is known
  * statically, the values are resolved via `require()` at first call.
  *
  * @example
@@ -354,7 +429,7 @@ interface Hl7Peer {
     }) => Hl7Message;
     /**
      * The peer's own `Hl7Message` class. Exposed (not just used as a type) so
-     * callers can detect a cross-realm instance — see the dual-package-hazard
+     * callers can detect a cross-realm instance, see the dual-package-hazard
      * note on `resolveInbound` in `build.ts`. Typed as `abstract new` (rather
      * than a concrete constructor signature) purely so TypeScript accepts it as
      * an `instanceof` right-hand side without also implying callers can `new`
@@ -366,14 +441,14 @@ interface Hl7Peer {
     readonly ACK_CODES: typeof ACK_CODES;
     /**
      * The peer's fail-safe downgrade primitive (`AA`→`AE`, `CA`→`CE`, everything
-     * else unchanged) — the single upstream source of truth for the pair; this
+     * else unchanged), the single upstream source of truth for the pair; this
      * adapter never carries its own copy of the mapping.
      */
     readonly downgradePositiveAck: (code: AckCode) => AckCode;
 }
 /**
- * Thrown when `@cosyte/hl7` — the optional peer dependency required by
- * `@cosyte/mllp/ack-from-hl7` — cannot be resolved at runtime.
+ * Thrown when `@cosyte/hl7`, the optional peer dependency required by
+ * `@cosyte/mllp/ack-from-hl7`, cannot be resolved at runtime.
  *
  * `@cosyte/hl7` is declared as an optional peer dependency, so a consumer of
  * the root `@cosyte/mllp` entry point is never forced to install it. Only
@@ -405,7 +480,7 @@ declare class MllpPeerMissingError extends Error {
 }
 /**
  * Load the `@cosyte/hl7` peer module, caching the result for subsequent
- * calls. The public adapter functions in `build.ts` call this internally —
+ * calls. The public adapter functions in `build.ts` call this internally,
  * most consumers never call it directly.
  *
  * @param requireFn - Injectable `require`-like function, used by tests to
@@ -422,4 +497,4 @@ declare class MllpPeerMissingError extends Error {
  */
 declare function loadHl7Peer(requireFn?: (id: string) => unknown): Hl7Peer;
 
-export { type BuildMllpAckOptions, type Hl7Peer, MLLP_ACK_CONTROL_ID_NOT_VERBATIM, MLLP_ACK_INBOUND_UNPARSEABLE, type MllpAck, type MllpAckWarning, MllpPeerMissingError, buildAckAA, buildAckAE, buildAckAR, buildAckCA, buildAckCE, buildAckCR, buildMllpAck, detectMode, loadHl7Peer };
+export { type BuildMllpAckOptions, type Hl7Peer, MLLP_ACK_CONTROL_ID_NOT_VERBATIM, MLLP_ACK_CONTROL_ID_UNVERIFIABLE, MLLP_ACK_INBOUND_UNPARSEABLE, type MllpAck, type MllpAckWarning, MllpPeerMissingError, buildAckAA, buildAckAE, buildAckAR, buildAckCA, buildAckCE, buildAckCR, buildMllpAck, detectMode, loadHl7Peer };