@cosyte/hl7 0.0.1 → 0.0.2

package/dist/index.d.cts

@@ -11,7 +11,7 @@ import { Buffer } from 'node:buffer';
 /**
  * Stable string codes for every Tier-2 warning the parser may emit. The
  * registry is frozen via `as const` so TypeScript infers the exact string
- * literal union for `WarningCode` — there is zero runtime cost and no
+ * literal union for `WarningCode`: there is zero runtime cost and no
  * magic-string comparisons for consumers.
  *
  * @example
@@ -43,6 +43,7 @@ declare const WARNING_CODES: {
     readonly MERGE_MISSING_PRIOR_OR_SURVIVOR: "MERGE_MISSING_PRIOR_OR_SURVIVOR";
     readonly BATCH_COUNT_MISMATCH: "BATCH_COUNT_MISMATCH";
     readonly BATCH_MISSING_TRAILER: "BATCH_MISSING_TRAILER";
+    readonly UNTERMINATED_STREAM_MESSAGE: "UNTERMINATED_STREAM_MESSAGE";
 };
 /**
  * Discriminant type for `Hl7ParseWarning.code`. Narrowing a warning by this
@@ -102,8 +103,8 @@ declare function mllpFramingStripped(position: Hl7Position): Hl7ParseWarning;
  * Build a `FIELD_WHITESPACE_TRIMMED` warning. Emitted when the parser trims
  * leading or trailing whitespace from a field value (the `trimFields`
  * option, on by default). The message carries only the leading/trailing
- * character **counts** — NEVER the field value itself (before or after
- * trimming) — so no PHI is exposed; the trimmed value is still preserved
+ * character **counts**: NEVER the field value itself (before or after
+ * trimming): so no PHI is exposed; the trimmed value is still preserved
  * verbatim in the parsed output.
  *
  * @example
@@ -116,12 +117,12 @@ declare function fieldWhitespaceTrimmed(position: Hl7Position, leadingCount: num
 /**
  * Build an `UNKNOWN_ESCAPE_SEQUENCE` warning for a **terminated** escape
  * sequence (`\..\`) whose body is not a recognized HL7 escape. The message
- * NEVER embeds the escape body — only its length and, when the body's first
+ * NEVER embeds the escape body: only its length and, when the body's first
  * character is a recognized HL7 escape-identifier letter (structural HL7
- * grammar, not PHI — e.g. `Z` for a vendor escape, `.` for a formatting
+ * grammar, not PHI: e.g. `Z` for a vendor escape, `.` for a formatting
  * escape), that single letter. A body that doesn't start with a known escape
  * letter is untrusted field text and names no character at all. The sequence
- * itself is still preserved verbatim in the parsed output — only the WARNING
+ * itself is still preserved verbatim in the parsed output: only the WARNING
  * message is PHI-safe.
  *
  * @example
@@ -137,7 +138,7 @@ declare function unknownEscapeSequence(position: Hl7Position, body: string): Hl7
  * (an escape character with no closing partner before end-of-input). The
  * "body" in this case is the entire remainder of the field, so the message
  * carries NEITHER the body NOR its length (the length of a truncated tail is
- * itself derivable field-shape information) — just the fact that an
+ * itself derivable field-shape information): just the fact that an
  * unterminated escape was found, and the position. The remainder is still
  * preserved verbatim in the parsed output.
  *
@@ -179,7 +180,7 @@ declare function timestampFallbackFormat(position: Hl7Position, matchedFormat: s
 declare function segmentCase(position: Hl7Position, observed: string): Hl7ParseWarning;
 /**
  * Build an `EXTRA_FIELDS` warning. Emitted when a segment contains more
- * fields than the profile definition (or HL7 spec) declares — the extras
+ * fields than the profile definition (or HL7 spec) declares: the extras
  * are preserved on `RawSegment.fields` but flagged for consumers.
  *
  * @example
@@ -243,10 +244,10 @@ declare function missingRequiredField(position: Hl7Position, segmentName: string
  * Build a `MISSING_EXPECTED_GROUP` warning (roadmap Phase G). Emitted once per
  * absent Required segment group when the message's (MSH-9.1, MSH-9.2) type is
  * one the structure safety net recognizes and an expected group is entirely
- * missing — e.g. an `ORU^R01` carrying no `OBR`/`OBX` result group, the
+ * missing: e.g. an `ORU^R01` carrying no `OBR`/`OBX` result group, the
  * signature of a truncated or misrouted feed. Tier-2 and additive: lenient
  * parse never throws on it, `strict` mode may promote it. The message carries
- * only the structural fact (message type, group name, anchor segment names) —
+ * only the structural fact (message type, group name, anchor segment names),
  * NEVER a field value, so no PHI is exposed. `position` references MSH-9.
  *
  * @example
@@ -291,7 +292,7 @@ declare function versionMismatch(position: Hl7Position, declared: string, expect
  * Table-0211 character set**. The parser never guesses an encoding: it reads the
  * raw bytes as `latin1` (a 1:1 byte mapping) so single-byte content stays
  * recoverable, rather than corrupting it with replacement characters. The
- * message carries the charset code only — never a decoded field value — so no
+ * message carries the charset code only, never a decoded field value, so no
  * PHI is exposed.
  *
  * @example
@@ -303,18 +304,18 @@ declare function versionMismatch(position: Hl7Position, declared: string, expect
 declare function unknownCharset(position: Hl7Position, requested: string): Hl7ParseWarning;
 /**
  * Build an `UNSUPPORTED_CHARSET` warning. Emitted when a **recognized**
- * Table-0211 character set is not decoded into text — either because this parser
- * does not decode it (the multibyte / ISO-2022-switched East-Asian sets — JIS,
- * GB 18030, KS X 1001, CNS 11643, BIG-5 — and the wide Unicode transforms
+ * Table-0211 character set is not decoded into text: either because this parser
+ * does not decode it (the multibyte / ISO-2022-switched East-Asian sets: JIS,
+ * GB 18030, KS X 1001, CNS 11643, BIG-5: and the wide Unicode transforms
  * UTF-16 / UTF-32), or because a strict decode of a decodable set **failed** (a
  * byte invalid / undefined for the declared set, or an ICU build lacking the
  * label). In every case the raw bytes are read as `latin1`, never guessed at, so
  * the parser does not emit replacement-char-corrupted text. Single-byte content
  * stays byte-recoverable; multibyte content is best-effort (a content byte can
- * coincide with a structural delimiter — see the parser's known-limitations).
+ * coincide with a structural delimiter: see the parser's known-limitations).
  * The switch escapes (`\Cxxyy\` / `\Mxxyyzz\`) are recognized and preserved by
  * the escape layer; full stateful decoding is a documented non-goal. The message
- * carries the charset code only — never a decoded field value — so no PHI is
+ * carries the charset code only, never a decoded field value, so no PHI is
  * exposed.
  *
  * @example
@@ -330,7 +331,7 @@ declare function unsupportedCharset(position: Hl7Position, code: string): Hl7Par
  * so the generated ACK leaves MSA-2 empty and, when a positive accept was
  * requested, downgrades it to an error code rather than fabricating an
  * unverifiable `AA`/`CA`. The `position` references the inbound MSH segment.
- * The message NEVER echoes a PHI value — only the structural fact.
+ * The message NEVER echoes a PHI value: only the structural fact.
  *
  * @example
  * ```ts
@@ -342,20 +343,20 @@ declare function unsupportedCharset(position: Hl7Position, code: string): Hl7Par
 declare function ackNoCorrelationId(position: Hl7Position): Hl7ParseWarning;
 /**
  * Build a `MERGE_MISSING_PRIOR_OR_SURVIVOR` warning (roadmap Phase K). Emitted
- * by `identityEvents()` (a read-side helper — it attaches to the returned
+ * by `identityEvents()` (a read-side helper: it attaches to the returned
  * `IdentityEvent.warnings`, never to `Hl7Message.warnings`) when a merge/move
  * trigger event (A18/A34/A35/A36/A39/A40/A41/A42/A43/A44) is missing one side
- * of the spec-mandated MRG (prior) → PID (surviving) pair — or when that side
+ * of the spec-mandated MRG (prior) → PID (surviving) pair: or when that side
  * carries no usable identity field: no MRG segment in the patient group, no
  * PID for an orphaned MRG, or a PID/MRG whose identifier, account, and visit
  * fields are all empty or version-gated (a v2.7+ MRG whose only content was
  * the withdrawn MRG-4 must not read as "nothing to retire"). The helper
  * surfaces whatever IS present and never
- * guesses the merge direction — this warning is the signal that the pair is
+ * guesses the merge direction: this warning is the signal that the pair is
  * incomplete.
  *
  * The message carries only the structural facts (trigger event code + which
- * role is missing) — NEVER an identifier, name, or any other field value, so
+ * role is missing): NEVER an identifier, name, or any other field value, so
  * no PHI is exposed (HL7 v2 Ch. 3: the PID carries surviving and the MRG
  * carries non-surviving identity information).
  *
@@ -368,18 +369,18 @@ declare function ackNoCorrelationId(position: Hl7Position): Hl7ParseWarning;
 declare function mergeMissingPriorOrSurvivor(position: Hl7Position, eventType: string, missing: "prior" | "survivor"): Hl7ParseWarning;
 /**
  * Build a `BATCH_COUNT_MISMATCH` warning (roadmap Phase L). Emitted by
- * `splitBatch()` — attached to the returned `BatchSplitResult.warnings`, never
- * to `Hl7Message.warnings` — when a declared envelope count does not equal the
+ * `splitBatch()`: attached to the returned `BatchSplitResult.warnings`, never
+ * to `Hl7Message.warnings`: when a declared envelope count does not equal the
  * count actually split out: a **BTS-1** batch message count that differs from
  * the messages found in that batch, or an **FTS-1** file batch count that
  * differs from the batches found in the file (HL7 v2 Ch. 2 §2.10.3; BTS-1 / FTS-1
  * per the BTS / FTS segment definitions in §2.15).
- * The splitter **never drops the tail** to make the numbers agree — the
+ * The splitter **never drops the tail** to make the numbers agree: the
  * mismatch is surfaced and every message is still returned; the caller decides
  * whether to reject.
  *
  * The message carries only the declared-vs-actual **integers** and the unit
- * (`message` for BTS-1, `batch` for FTS-1) — NEVER a field value, facility
+ * (`message` for BTS-1, `batch` for FTS-1): NEVER a field value, facility
  * identifier, or any other content, so no PHI is exposed. `position` references
  * the trailer segment (`BTS`/`FTS`) that declared the count.
  *
@@ -392,15 +393,15 @@ declare function mergeMissingPriorOrSurvivor(position: Hl7Position, eventType: s
 declare function batchCountMismatch(position: Hl7Position, unit: "message" | "batch", declared: number, actual: number): Hl7ParseWarning;
 /**
  * Build a `BATCH_MISSING_TRAILER` warning (roadmap Phase L). Emitted by
- * `splitBatch()` — attached to `BatchSplitResult.warnings` — when an envelope
+ * `splitBatch()` (attached to `BatchSplitResult.warnings`) when an envelope
  * header opens a scope that is never closed: a **BHS** batch header with no
  * matching **BTS** trailer, or an **FHS** file header with no matching **FTS**
- * trailer (HL7 v2 Ch. 2 §2.10.3 — each envelope segment is optional, but a
+ * trailer (HL7 v2 Ch. 2 §2.10.3: each envelope segment is optional, but a
  * profile such as an IIS file-submission spec may mandate the full frame).
- * `splitBatch` **does not enforce** such a rule — it splits, warns, and leaves
+ * `splitBatch` **does not enforce** such a rule: it splits, warns, and leaves
  * the accept/reject decision to the caller; the parse never throws for this.
  *
- * The message carries only the header/trailer segment names — NEVER a field
+ * The message carries only the header/trailer segment names: NEVER a field
  * value, so no PHI is exposed. `position` references the unmatched header
  * segment (`FHS`/`BHS`).
  *
@@ -411,13 +412,34 @@ declare function batchCountMismatch(position: Hl7Position, unit: "message" | "ba
  * ```
  */
 declare function batchMissingTrailer(position: Hl7Position, header: "FHS" | "BHS", expectedTrailer: "FTS" | "BTS"): Hl7ParseWarning;
+/**
+ * Build an `UNTERMINATED_STREAM_MESSAGE` warning (roadmap Phase S). Emitted by
+ * `parseStream()`: attached to a {@link StreamMessageEntry}'s `streamWarnings`,
+ * NOT to `Hl7Message.warnings`: when the **final** message in a stream ends
+ * without a segment terminator (its last segment ran to end-of-stream with no
+ * trailing `\r`/`\r\n`/`\n`). The message is still parsed and yielded **in
+ * full**; this is the fail-safe signal that the tail may have been truncated
+ * mid-message (a cut-off feed), never a reason to drop it and never a throw.
+ * Only the last message can be unterminated: every earlier message is closed by
+ * the terminator that precedes the next `MSH`/envelope boundary.
+ *
+ * The message carries only the structural fact, NEVER a field value, so no PHI
+ * is exposed. `position` references the message's `MSH` segment index.
+ *
+ * @example
+ * ```ts
+ * import { unterminatedStreamMessage } from "@cosyte/hl7";
+ * const w = unterminatedStreamMessage({ segmentIndex: 6 });
+ * ```
+ */
+declare function unterminatedStreamMessage(position: Hl7Position): Hl7ParseWarning;
 
 /**
  * Shared type definitions consumed across the `@cosyte/hl7` parser
  * pipeline. These types are contracts between parser stages (normalize,
  * mllp, segments, delimiters, tokenize) and the `Hl7Message` model shell.
  *
- * Every type here is deliberately readonly — the parser produces immutable
+ * Every type here is deliberately readonly: the parser produces immutable
  * data structures and consumers must not mutate them. Narrowing is done via
  * the `Hl7ParseWarning.code` and `Hl7ParseError.code` discriminants defined
  * in sibling files.
@@ -426,14 +448,14 @@ declare function batchMissingTrailer(position: Hl7Position, header: "FHS" | "BHS
 /**
  * Positional context attached to every warning and fatal error. Fields are
  * 1-indexed against the HL7 spec convention (see `RawSegment.fields` for the
- * index 0 slot convention). All fields past `segmentIndex` are optional —
+ * index 0 slot convention). All fields past `segmentIndex` are optional,
  * for a top-level fatal like `EMPTY_INPUT` only `segmentIndex: 0` is
  * populated; for a tokenizer warning deep inside a subcomponent all five
  * indices may be set.
  *
  * @remarks
  * With `exactOptionalPropertyTypes: true`, do not pass `fieldIndex: undefined`
- * explicitly — omit the key instead.
+ * explicitly: omit the key instead.
  *
  * @example
  * ```ts
@@ -470,7 +492,7 @@ type OnWarningCallback = (warning: Hl7ParseWarning) => void;
  *
  * @remarks
  * With `exactOptionalPropertyTypes: true`, callers cannot pass
- * `{ strict: undefined }` — either omit the key or pass a boolean. The
+ * `{ strict: undefined }`: either omit the key or pass a boolean. The
  * `profile: null` form is the explicit opt-out from the process-scoped
  * default profile (PROF-08 semantics); `profile` omitted means "use the
  * default if one is registered".
@@ -531,14 +553,14 @@ interface CustomSegmentDefinition {
 /**
  * Structural placeholder for HL7 profiles. A profile bundles vendor-specific
  * tolerances, date formats, custom segment definitions, and optional
- * callbacks. Phase 2 ships only the type — the `defineProfile()` builder
+ * callbacks. Phase 2 ships only the type: the `defineProfile()` builder
  * and runtime effects land in Phase 6.
  *
  * Phase 6 Plan 01 tightens `customSegments` to the locked
  * `CustomSegmentDefinition` shape and adds an optional `describe?` method
  * so `defineProfile()`-produced profiles can be introspected without
  * consumers needing to narrow away from the `Profile` type. The `describe`
- * method is only populated by `defineProfile()` — hand-authored `Profile`
+ * method is only populated by `defineProfile()`: hand-authored `Profile`
  * objects may omit it.
  *
  * @example
@@ -565,8 +587,8 @@ interface Profile {
 }
 /**
  * The HL7 delimiter characters discovered from MSH-1 (field separator) and
- * MSH-2 (encoding characters). The first four — component, repetition,
- * escape, subcomponent — are mandatory across all HL7 v2 versions. The fifth,
+ * MSH-2 (encoding characters). The first four: component, repetition,
+ * escape, subcomponent: are mandatory across all HL7 v2 versions. The fifth,
  * `truncation`, is the v2.7+ truncation character (default `#` per spec
  * §2.5.5.2): only present when MSH-2 actually carries 5 encoding characters,
  * so messages that pre-date v2.7 round-trip with a 4-char MSH-2 unchanged.
@@ -593,7 +615,7 @@ interface EncodingCharacters {
     readonly truncation?: string;
 }
 /**
- * A single component inside a repetition — the most deeply nested data
+ * A single component inside a repetition: the most deeply nested data
  * layer in the HL7 positional tree. A component is an ordered list of
  * subcomponent strings (subcomponent separator `&` by default).
  *
@@ -605,7 +627,7 @@ interface EncodingCharacters {
  */
 interface RawComponent {
     /**
-     * The component's subcomponents, **HL7-decoded** — the tokenizer expands
+     * The component's subcomponents, **HL7-decoded**: the tokenizer expands
      * escape sequences on parse so consumers read literal values (`Smith|Jones`,
      * not `Smith\F\Jones`). This is the value surface every reader uses
      * (`Field.value`, the composite parsers, dot-path, `toJSON`).
@@ -616,7 +638,7 @@ interface RawComponent {
      * for each index, the subcomponent's **original wire bytes** to emit
      * verbatim instead of re-escaping the decoded form. An entry is present
      * (non-`undefined`) only when a subcomponent carried an escape whose decoded
-     * form does not re-escape back to the exact wire bytes — i.e. a recognize-
+     * form does not re-escape back to the exact wire bytes: i.e. a recognize-
      * and-preserve escape (`\H\`, `\Z..\`, charset/formatting) or a hex escape
      * (`\X41\`, or non-canonical hex casing). Delimiter escapes (`\F\`→`|`) round-
      * trip through `reescape` unchanged and get no overlay. The whole field is
@@ -632,7 +654,7 @@ interface RawComponent {
     readonly rawSubcomponents?: readonly (string | undefined)[];
 }
 /**
- * A single repetition inside a field — HL7 fields may repeat using the
+ * A single repetition inside a field: HL7 fields may repeat using the
  * repetition separator (`~` by default). Each repetition is an ordered list
  * of components.
  *
@@ -663,7 +685,7 @@ interface RawField {
     readonly isNull: boolean;
 }
 /**
- * A parsed HL7 segment — the top level of the positional tree. The `name`
+ * A parsed HL7 segment: the top level of the positional tree. The `name`
  * is the three-character segment identifier (`MSH`, `PID`, `ZPI`, ...) and
  * `fields` is the 1-indexed positional field array (see the JSDoc on
  * `fields` for the index 0 slot convention).
@@ -708,7 +730,7 @@ interface RawSegment {
  * them, which keeps custom-delimiter behaviour (PARSE-02) consistent across
  * the pipeline.
  *
- * Only three of the four Tier-3 fatal codes originate here —
+ * Only three of the four Tier-3 fatal codes originate here,
  * `NO_MSH_SEGMENT`, `MSH_TOO_SHORT`, `INVALID_ENCODING_CHARACTERS`. The
  * fourth, `EMPTY_INPUT`, is owned by the `normalize.ts` preprocessing stage.
  */
@@ -727,23 +749,182 @@ interface RawSegment {
 declare const DEFAULT_ENCODING_CHARACTERS: EncodingCharacters;
 
 /**
- * CE — HL7 v2 Coded Element composite. 6-component coded-element shape
+ * Formatted-text rendering for `@cosyte/hl7`: turns HL7 v2 §2.7
+ * escape/formatting-bearing field content into a **normalized display model**
+ * a human (or a downstream display / FHIR `.text`) can read, instead of the
+ * raw `\H\`/`\.br\` sentinels the lenient parser preserves.
+ *
+ * This is the read-projection half of Phase R: `renderText` never mutates the
+ * raw field value (rendering is opt-in on top of the tolerant parse), and it
+ * **never fabricates**: an escape it cannot render is preserved as its literal
+ * characters AND flagged in {@link RenderedText.unrenderedSequences}, never
+ * dropped and never replaced with a guessed glyph.
+ *
+ * **Clinical-safety angle.** A lab/clinical narrative surfaced with raw
+ * `\.br\` / `\H\` sentinels is *misread* by a human; that is the harm this
+ * prevents. Formatting commands become real whitespace/line-breaks and
+ * highlight boundaries are dropped from the plain text (and exposed as
+ * `highlighted` runs for consumers that want emphasis), so what a reader sees
+ * is the intended text: never a sentinel and never an invented character.
+ *
+ * ## Spec traceability (HL7 v2 Chapter 2, §2.7: confirmed firsthand
+ * 2026-07-21 against the v2.5.1 and v2.8.2 chapter text; section numbers shift
+ * by version)
+ *
+ * - **§2.7.1 formatting codes**: the delimiter/escape substitutions
+ *   `\F\ \S\ \T\ \R\ \E\` (→ the message's own field/component/subcomponent/
+ *   repetition/escape characters), the highlight pair `\H\` (start) / `\N\`
+ *   (normal, i.e. end), and (v2.7+) `\P\` (the truncation character).
+ * - **§2.7.2/2.7.3 charset switch**: `\Cxxyy\` (single-byte) / `\Mxxyyzz\`
+ *   (multi-byte, `zz` optional): selects an alternate MSH-18 character set for
+ *   the following run. Decoding requires stateful charset context this module
+ *   does not have, so a switch is **preserved + flagged**, never guessed.
+ * - **§2.7.5/2.7.6 hex**: `\Xdddd…\`: consecutive **pairs** of hex digits,
+ *   each pair one 8-bit byte.
+ * - **§2.7.6/2.7.7 formatting commands** (FT data type): `\.br\` `\.sp\`
+ *   `\.in\` `\.ti\` `\.fi\` `\.nf\` `\.ce\` `\.sk\`; `.sp` takes an optional
+ *   positive count, `.in`/`.ti` a signed indent, `.sk` a space count. Rendered
+ *   to a conservative plain-text normalization (see the table below).
+ * - **§2.7.7/2.7.8 locally-defined**: `\Zdddd…\`: opaque, meaning is a
+ *   sender/receiver agreement, so **preserved + flagged**, never interpreted.
+ *
+ * ## Normalization policy (conservative, documented: not a page-layout engine)
+ *
+ * | Escape                      | Rendered as                                   |
+ * | --------------------------- | --------------------------------------------- |
+ * | `\F\ \S\ \T\ \R\ \E\ \P\`   | the literal delimiter / escape / trunc char   |
+ * | `\Xdddd…\`                  | the decoded byte(s)                           |
+ * | `\H\` / `\N\`               | dropped from text; toggles a `highlighted` run |
+ * | `\.br\`                     | one line break                                |
+ * | `\.sp\` / `\.sp <n>\`       | `n` line breaks (default 1, clamped to 100)    |
+ * | `\.ce\`                     | one line break (centering dropped)            |
+ * | `\.in <n>\` / `\.ti <n>\`   | dropped (indentation: exact column math is a defer) |
+ * | `\.fi\` / `\.nf\`           | dropped (word-wrap mode: no content)         |
+ * | `\.sk <n>\`                 | `n` spaces (default 1, clamped to 100)         |
+ * | `\Cxxyy\` `\Mxxyyzz\` `\Zdddd…\`, malformed / unterminated | literal chars, **preserved + flagged** |
+ *
+ * A raw CR / LF / CRLF already present in the input (e.g. a `\.br\` the parser
+ * already decoded to `\n`, or a hex-encoded `\X0D\`/`\X0A\`) is normalized to
+ * one line break too, so rendering a pre-decoded `Field.value` and rendering
+ * the wire text agree. A `\.sp <n>\`/`\.sk <n>\` count is clamped to a small
+ * maximum (a conservative renderer need not honor a pathological skip, and an
+ * unbounded count is a memory / `RangeError` foot-gun on a hostile feed).
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * One contiguous run of rendered display text, tagged with whether it fell
+ * inside a `\H\`…\`\N\` highlight span. Runs preserve emphasis boundaries that
+ * the flat {@link RenderedText.text} intentionally drops.
+ */
+interface TextRun {
+    /**
+     * The literal display text of this run: escape sentinels already resolved
+     * (delimiter/hex decoded, formatting → whitespace/line breaks). Never
+     * contains a formatting sentinel; may contain the newline used for breaks.
+     */
+    readonly text: string;
+    /** `true` when this run is inside a `\H\`…`\N\` highlight span. */
+    readonly highlighted: boolean;
+}
+/**
+ * The normalized display model produced by {@link renderText}: a flat
+ * plain-text string plus the structured highlight-aware runs, plus an
+ * honesty list of the escape sequences that were preserved rather than
+ * rendered.
+ */
+interface RenderedText {
+    /**
+     * The full plain-text normalization: formatting commands become
+     * whitespace / line breaks and highlight boundaries are dropped. This is
+     * the string to show a human or feed a downstream `.text`. Equal to the
+     * concatenation of every {@link runs} entry's `text`.
+     */
+    readonly text: string;
+    /**
+     * The structured, highlight-aware form: `{ text, highlighted }` runs in
+     * document order. Empty runs are elided. Use this to preserve emphasis
+     * (bold / reverse-video / etc.) that the flat {@link text} drops.
+     */
+    readonly runs: readonly TextRun[];
+    /**
+     * The escape sequences `renderText` **preserved verbatim instead of
+     * rendering**: vendor `\Zdddd…\`, charset switches `\Cxxyy\`/`\Mxxyyzz\`,
+     * and any malformed / unterminated sequence. Their literal characters ALSO
+     * appear in {@link text}/{@link runs} (never silently dropped); this list
+     * exists so a consumer can detect that a non-render decision was made and
+     * surface or route those sequences deliberately. Empty when everything
+     * rendered cleanly.
+     */
+    readonly unrenderedSequences: readonly string[];
+}
+/** Options for {@link renderText}. */
+interface RenderTextOptions {
+    /**
+     * The string emitted for each line break (`\.br\`, `\.sp\`, `\.ce\`, and a
+     * raw CR/LF/CRLF in the input). Defaults to `"\n"`. Set `"\r\n"` for
+     * Windows-style display, or `" "` to flatten a note to a single line.
+     */
+    readonly newline?: string;
+}
+/**
+ * Render an HL7 v2 escape/formatting-bearing string into a normalized display
+ * model (plain text + highlight-aware runs). A **read projection**: it never
+ * mutates the underlying field, and it never fabricates: an escape it cannot
+ * render is preserved as literal characters and flagged in
+ * {@link RenderedText.unrenderedSequences}.
+ *
+ * `input` is the field's escape-bearing text. Pass the **wire form** (e.g.
+ * `Field.text`, byte-verbatim for parsed content) for the most faithful
+ * result: a wire `\E\H\E\` (an escaped literal backslash-H-backslash) then
+ * renders as the three literal characters `\H\`, never as a highlight. Passing
+ * an already-decoded `Field.value` also works: its `\.br\` is already a
+ * newline (rendered as one line break) and its `\H\`/formatting sentinels are
+ * still recognized.
+ *
+ * Never throws for any input.
+ *
+ * @param input - the escape-bearing field text to render.
+ * @param enc - the message's encoding characters (for `\F\`/`\S\`/… targets);
+ *   defaults to the HL7 standard `|^~\&`.
+ * @param opts - see {@link RenderTextOptions}.
+ * @returns the normalized {@link RenderedText}.
+ *
+ * @example
+ * ```ts
+ * import { renderText } from "@cosyte/hl7";
+ *
+ * const r = renderText("Specimen received.\\.br\\Gross exam \\H\\normal\\N\\.");
+ * r.text;
+ * // "Specimen received.\nGross exam normal."
+ * r.runs;
+ * // [ { text: "Specimen received.\nGross exam ", highlighted: false },
+ * //   { text: "normal",                          highlighted: true  },
+ * //   { text: ".",                               highlighted: false } ]
+ * r.unrenderedSequences; // []
+ * ```
+ */
+declare function renderText(input: string, enc?: EncodingCharacters, opts?: RenderTextOptions): RenderedText;
+
+/**
+ * CE: HL7 v2 Coded Element composite. 6-component coded-element shape
  * parsed from a `RawRepetition` on demand by `Field.asCe()` (wired in Plan
- * 04). Fields are OMITTED when absent (exactOptionalPropertyTypes) — NEVER
+ * 04). Fields are OMITTED when absent (exactOptionalPropertyTypes): NEVER
  * set to `undefined`.
  *
- * CE is the older, simpler sibling of CWE — 6 components, no version ids,
+ * CE is the older, simpler sibling of CWE: 6 components, no version ids,
  * no originalText. Still common in OBX.3 and similar observation-identifier
  * slots on older messages. CE was deprecated at HL7 v2.5 and withdrawn at
- * v2.6 in favor of CWE; the two are read uniformly here — reading a
+ * v2.6 in favor of CWE; the two are read uniformly here: reading a
  * CWE-shaped value through `asCe()` preserves components 7+ on
  * `extraComponents` rather than dropping them, so neither accessor is lossy.
  *
- * Zero runtime deps — pure function over the raw positional tree + `unescape`.
+ * Zero runtime deps: pure function over the raw positional tree + `unescape`.
  */
 
 /**
- * HL7 v2 Coded Element (CE) — coded element per HL7 Chapter 2. All 6
+ * HL7 v2 Coded Element (CE): coded element per HL7 Chapter 2. All 6
  * components are optional. Fields are OMITTED when the underlying component
  * is absent (exactOptionalPropertyTypes).
  *
@@ -756,7 +937,7 @@ declare const DEFAULT_ENCODING_CHARACTERS: EncodingCharacters;
  * 6. nameOfAlternateCodingSystem
  *
  * Components 7+ (present when a CWE-shaped value is read through the CE
- * accessor — e.g. version ids, originalText) are surfaced verbatim on
+ * accessor: e.g. version ids, originalText) are surfaced verbatim on
  * `extraComponents` rather than dropped.
  *
  * @example
@@ -783,7 +964,7 @@ interface CE {
 }
 /**
  * Parse an HL7 v2 CE repetition into a structured `CE` object. Components
- * are returned verbatim (already decoded once by the tokenizer — never re-unescaped,
+ * are returned verbatim (already decoded once by the tokenizer: never re-unescaped,
  * HL7-VALUE-REDECODE). Absent / empty components are OMITTED
  * from the result (exactOptionalPropertyTypes semantics).
  *
@@ -802,24 +983,24 @@ interface CE {
 declare function parseCe(rep: RawRepetition, enc: EncodingCharacters): CE;
 
 /**
- * CWE — HL7 v2 Coded with Exceptions composite. 9-component coded-element
+ * CWE: HL7 v2 Coded with Exceptions composite. 9-component coded-element
  * shape parsed from a `RawRepetition` on demand by `Field.asCwe()` (wired in
- * Plan 04). Fields are OMITTED when absent (exactOptionalPropertyTypes) —
+ * Plan 04). Fields are OMITTED when absent (exactOptionalPropertyTypes),
  * NEVER set to `undefined`.
  *
  * Note: full HL7 v2.6+ CWE has 22 components. v1 of this library ships the 9
- * core components — identifier, text, coding-system trio + version ids, and
- * originalText — which cover the common HL7 v2.5 use cases. v2 may restore
- * the full shape. Components 10+ that a newer (v2.7+) sender supplies — the
- * second-alternate triplet and the coding-system / value-set OIDs — are NOT
+ * core components: identifier, text, coding-system trio + version ids, and
+ * originalText: which cover the common HL7 v2.5 use cases. v2 may restore
+ * the full shape. Components 10+ that a newer (v2.7+) sender supplies: the
+ * second-alternate triplet and the coding-system / value-set OIDs: are NOT
  * dropped: they are preserved verbatim on `extraComponents` so the typed view
  * is lossless across versions.
  *
- * Zero runtime deps — pure function over the raw positional tree + `unescape`.
+ * Zero runtime deps: pure function over the raw positional tree + `unescape`.
  */
 
 /**
- * HL7 v2 Coded with Exceptions (CWE) — coded element per HL7 Chapter 2. All
+ * HL7 v2 Coded with Exceptions (CWE): coded element per HL7 Chapter 2. All
  * 9 components are optional. Fields are OMITTED when the underlying
  * component is absent (exactOptionalPropertyTypes).
  *
@@ -835,7 +1016,7 @@ declare function parseCe(rep: RawRepetition, enc: EncodingCharacters): CE;
  * 9. originalText
  *
  * Components 10+ (present only on v2.7+ senders) are surfaced verbatim, in
- * order, on `extraComponents` — never silently truncated.
+ * order, on `extraComponents`: never silently truncated.
  *
  * @example
  * ```ts
@@ -865,7 +1046,7 @@ interface CWE {
 }
 /**
  * Parse an HL7 v2 CWE repetition into a structured `CWE` object. Components
- * are returned verbatim (already decoded once by the tokenizer — never re-unescaped,
+ * are returned verbatim (already decoded once by the tokenizer: never re-unescaped,
  * HL7-VALUE-REDECODE). Absent / empty components are OMITTED
  * from the result (exactOptionalPropertyTypes semantics).
  *
@@ -884,23 +1065,23 @@ interface CWE {
 declare function parseCwe(rep: RawRepetition, enc: EncodingCharacters): CWE;
 
 /**
- * HD — HL7 v2 Hierarchic Designator composite. 3-component structured
+ * HD: HL7 v2 Hierarchic Designator composite. 3-component structured
  * identifier (namespace + universal id + universal id type) parsed from a
  * `RawRepetition` on demand. Fields are OMITTED when absent
- * (exactOptionalPropertyTypes) — NEVER set to `undefined`.
+ * (exactOptionalPropertyTypes): NEVER set to `undefined`.
  *
- * Zero runtime deps — pure function over the raw positional tree + `unescape`.
+ * Zero runtime deps: pure function over the raw positional tree + `unescape`.
  */
 
 /**
- * HL7 v2 Hierarchic Designator (HD) — per HL7 Chapter 2 data type. All 3
+ * HL7 v2 Hierarchic Designator (HD): per HL7 Chapter 2 data type. All 3
  * components are optional. Fields are OMITTED when the underlying component
  * is absent (exactOptionalPropertyTypes).
  *
  * Component positions (HL7 1-indexed; this interface is 0-indexed by key):
- * 1. namespaceId — application- or facility-scoped identifier (e.g. "EPIC").
- * 2. universalId — globally-unique id (e.g. an OID or UUID string).
- * 3. universalIdType — classifier for `universalId` (ISO, GUID, UUID, DNS,
+ * 1. namespaceId: application- or facility-scoped identifier (e.g. "EPIC").
+ * 2. universalId: globally-unique id (e.g. an OID or UUID string).
+ * 3. universalIdType: classifier for `universalId` (ISO, GUID, UUID, DNS,
  *    URI, HL7, HCD, Random, etc.).
  *
  * @example
@@ -916,7 +1097,7 @@ interface HD {
 }
 /**
  * Parse an HL7 v2 HD repetition into a structured `HD` object. Components
- * are returned verbatim (already decoded once by the tokenizer — never re-unescaped,
+ * are returned verbatim (already decoded once by the tokenizer: never re-unescaped,
  * HL7-VALUE-REDECODE). Absent / empty components are OMITTED
  * from the result (exactOptionalPropertyTypes semantics).
  *
@@ -936,10 +1117,10 @@ interface HD {
 declare function parseHd(rep: RawRepetition, enc: EncodingCharacters): HD;
 
 /**
- * CX — HL7 v2 Extended Composite ID (with check digit) composite.
+ * CX: HL7 v2 Extended Composite ID (with check digit) composite.
  * 10-component structured-identifier shape parsed from a `RawRepetition` on
  * demand by `Field.asCx()` (wired in Plan 04). Fields are OMITTED when
- * absent (exactOptionalPropertyTypes) — NEVER set to `undefined`.
+ * absent (exactOptionalPropertyTypes): NEVER set to `undefined`.
  *
  * Component 4 (`assigningAuthority`) is the ONE nested-composite field in
  * this plan: its subcomponents form a 3-field HD (namespaceId, universalId,
@@ -948,14 +1129,14 @@ declare function parseHd(rep: RawRepetition, enc: EncodingCharacters): HD;
  * CX component 4.
  *
  * Component 6 (`assigningFacility`) is simplified to a flat `string` in v1
- * — the HL7 spec treats it as HD-shaped, but v1 favours simplicity. Callers
+ *: the HL7 spec treats it as HD-shaped, but v1 favours simplicity. Callers
  * who need the full HD can parse the raw string separately.
  *
- * Zero runtime deps — pure function over the raw positional tree + `unescape`.
+ * Zero runtime deps: pure function over the raw positional tree + `unescape`.
  */
 
 /**
- * HL7 v2 Extended Composite ID (CX) — structured identifier per HL7 Chapter
+ * HL7 v2 Extended Composite ID (CX): structured identifier per HL7 Chapter
  * 2. All 10 components are optional. Fields are OMITTED when the underlying
  * component is absent (exactOptionalPropertyTypes). `assigningAuthority`
  * uses the nested `HD` shape; `assigningFacility` is flattened to a plain
@@ -965,7 +1146,7 @@ declare function parseHd(rep: RawRepetition, enc: EncodingCharacters): HD;
  * 1. idNumber
  * 2. checkDigit
  * 3. checkDigitScheme (ISO 7064, M10, M11, NPI)
- * 4. assigningAuthority (nested HD — 3 subcomponents form a HD composite)
+ * 4. assigningAuthority (nested HD: 3 subcomponents form a HD composite)
  * 5. identifierTypeCode (MR, SSN, DL, MC, ...)
  * 6. assigningFacility (v1: flattened to string; spec is HD-shaped)
  * 7. effectiveDate (raw HL7 TS string)
@@ -997,7 +1178,7 @@ interface CX {
 }
 /**
  * Parse an HL7 v2 CX repetition into a structured `CX` object. Components
- * are returned verbatim (already decoded once by the tokenizer — never re-unescaped,
+ * are returned verbatim (already decoded once by the tokenizer: never re-unescaped,
  * HL7-VALUE-REDECODE). Absent / empty components are OMITTED
  * from the result (exactOptionalPropertyTypes semantics). Component 4
  * (`assigningAuthority`) is parsed as a nested `HD`; see component table in
@@ -1021,7 +1202,7 @@ interface CX {
 declare function parseCx(rep: RawRepetition, enc: EncodingCharacters): CX;
 
 /**
- * NM — HL7 v2 Numeric composite. Parses the raw HL7 numeric string into a
+ * NM: HL7 v2 Numeric composite. Parses the raw HL7 numeric string into a
  * `number` via the stricter `Number(raw)` (not `parseFloat`, which tolerates
  * trailing garbage like "12abc" → 12). `NaN` is normalized to `undefined`
  * per the same no-throw discipline as TS/DTM (D-24 analogous).
@@ -1029,17 +1210,17 @@ declare function parseCx(rep: RawRepetition, enc: EncodingCharacters): CX;
  * The raw string is preserved verbatim on the composite so callers needing
  * to round-trip or render with the original precision/formatting can.
  *
- * Zero runtime deps — pure function over the raw tree + `unescape` + stdlib
+ * Zero runtime deps: pure function over the raw tree + `unescape` + stdlib
  * `Number`.
  */
 
 /**
  * HL7 v2 Numeric (NM) composite. Carries both the raw HL7 numeric string
  * and the parsed JS `number`. `.value` is `undefined` when the raw string
- * is empty or not fully numeric — NEVER throws.
+ * is empty or not fully numeric: NEVER throws.
  *
  * Unlike most composites in this phase, both `raw` and `value` are
- * ALWAYS-PRESENT keys (not optional) — `value` is explicitly typed as
+ * ALWAYS-PRESENT keys (not optional): `value` is explicitly typed as
  * `number | undefined` so callers can destructure uniformly.
  *
  * @example
@@ -1055,10 +1236,10 @@ interface NM {
 }
 /**
  * Parse an HL7 v2 NM repetition into `{ raw, value }`. Uses `Number(raw)`
- * for strict numeric parsing — trailing non-numeric characters produce
+ * for strict numeric parsing: trailing non-numeric characters produce
  * `NaN`, normalized to `undefined`. Empty raw also produces `undefined`.
  *
- * `Number("")` is `0` in JS — which is the wrong answer for an empty HL7
+ * `Number("")` is `0` in JS: which is the wrong answer for an empty HL7
  * numeric field. The explicit empty-string check below returns
  * `{ raw: "", value: undefined }` so empty inputs match missing inputs.
  *
@@ -1073,42 +1254,42 @@ interface NM {
 declare function parseNm(rep: RawRepetition, _enc: EncodingCharacters): NM;
 
 /**
- * PL — HL7 v2 Person Location composite. 11-component structured-location
- * shape (v1 trimmed from the HL7 v2.5 full 12-component PL — slot 12
+ * PL: HL7 v2 Person Location composite. 11-component structured-location
+ * shape (v1 trimmed from the HL7 v2.5 full 12-component PL: slot 12
  * `entityIdentifier` is rarely used; v2 may restore the full shape) parsed
  * from a `RawRepetition` on demand by `Field.asPl()` (wired in Plan 04).
- * Fields are OMITTED when absent (exactOptionalPropertyTypes) — NEVER set
+ * Fields are OMITTED when absent (exactOptionalPropertyTypes): NEVER set
  * to `undefined`.
  *
  * Component 4 (`facility`) is the ONE nested-composite field in this
  * parser: its subcomponents form a 3-field HD (namespaceId, universalId,
- * universalIdType) — same synthesis pattern used in `parseCx` for
+ * universalIdType): same synthesis pattern used in `parseCx` for
  * `assigningAuthority`. To reuse `parseHd` without duplicating logic, the
  * parser synthesises a `RawRepetition` whose components wrap the
  * subcomponents of PL component 4.
  *
- * Zero runtime deps — pure function over the raw positional tree + `unescape`.
+ * Zero runtime deps: pure function over the raw positional tree + `unescape`.
  */
 
 /**
- * HL7 v2 Person Location (PL) — structured location per HL7 Chapter 2. All
+ * HL7 v2 Person Location (PL): structured location per HL7 Chapter 2. All
  * 11 v1 components are optional. Fields are OMITTED when the underlying
  * component is absent (exactOptionalPropertyTypes). `facility` uses the
  * nested `HD` shape; `assigningAuthorityForLocation` is flattened to a
  * plain string in v1 (HL7 spec treats it as HD-shaped).
  *
  * Component positions (HL7 1-indexed; this interface is 0-indexed by key):
- * 1. pointOfCare — e.g. "ICU", "ED"
+ * 1. pointOfCare: e.g. "ICU", "ED"
  * 2. room
  * 3. bed
- * 4. facility — nested HD (3 subcomponents form an HD composite)
- * 5. locationStatus — O=Occupied, U=Unoccupied, K=Contaminated, C=Closed,
+ * 4. facility: nested HD (3 subcomponents form an HD composite)
+ * 5. locationStatus: O=Occupied, U=Unoccupied, K=Contaminated, C=Closed,
  *    H=Housekeeping, I=Isolated
- * 6. personLocationType — C=Clinic, D=Department, H=Home, N=Nursing Unit,
+ * 6. personLocationType: C=Clinic, D=Department, H=Home, N=Nursing Unit,
  *    O=Office, R=Revenue Location
  * 7. building
  * 8. floor
- * 9. locationDescription — free-text
+ * 9. locationDescription: free-text
  * 10. comprehensiveLocationId
  * 11. assigningAuthorityForLocation (v1: flattened to string)
  *
@@ -1138,7 +1319,7 @@ interface PL {
 }
 /**
  * Parse an HL7 v2 PL repetition into a structured `PL` object. Components
- * are returned verbatim (already decoded once by the tokenizer — never re-unescaped,
+ * are returned verbatim (already decoded once by the tokenizer: never re-unescaped,
  * HL7-VALUE-REDECODE). Absent / empty components are OMITTED
  * from the result (exactOptionalPropertyTypes semantics). Component 4
  * (`facility`) is parsed as a nested `HD`; see component table in the `PL`
@@ -1161,15 +1342,15 @@ interface PL {
 declare function parsePl(rep: RawRepetition, enc: EncodingCharacters): PL;
 
 /**
- * SN — HL7 v2 Structured Numeric composite (HL7 Chapter 2A). Parses an OBX-5
+ * SN: HL7 v2 Structured Numeric composite (HL7 Chapter 2A). Parses an OBX-5
  * value declared as `OBX-2 = SN` into its four positional components so a
  * comparator or a range/ratio is preserved as TYPED data instead of being
  * flattened to a string (where everything past the first component is lost).
  *
  * Component positions (HL7 1-indexed; this interface is 0-indexed by key):
- *   1. comparator (ST)         — `>` `<` `>=` `<=` `=` `<>`; absent ⇒ `=`
+ *   1. comparator (ST): `>` `<` `>=` `<=` `=` `<>`; absent ⇒ `=`
  *   2. num1 (NM)
- *   3. separatorOrSuffix (ST)  — `-` (range), `:` / `/` (ratio), `+` (suffix), `.`
+ *   3. separatorOrSuffix (ST): `-` (range), `:` / `/` (ratio), `+` (suffix), `.`
  *   4. num2 (NM)
  *
  * Usage examples (the literal OBX-5 string ⇒ what this parses):
@@ -1179,12 +1360,12 @@ declare function parsePl(rep: RawRepetition, enc: EncodingCharacters): PL;
  *   `^1^:^128`     ⇒ titer/ratio 1:128      → { num1: 1, separatorOrSuffix: ":", num2: 128 }
  *
  * Safety: `num1`/`num2` are parsed with the same strict `Number()` discipline
- * as NM — non-numeric input becomes `undefined`, NEVER `NaN` and never a
+ * as NM: non-numeric input becomes `undefined`, NEVER `NaN` and never a
  * silently wrong number. The comparator is surfaced ONLY when SN.1 is a
  * recognized operator, so a non-operator value in the comparator slot is never
  * passed off as a real relation.
  *
- * Zero runtime deps — pure function over the raw positional tree + `unescape`.
+ * Zero runtime deps: pure function over the raw positional tree + `unescape`.
  */
 
 /**
@@ -1194,7 +1375,7 @@ declare function parsePl(rep: RawRepetition, enc: EncodingCharacters): PL;
  * when absent (`exactOptionalPropertyTypes`).
  *
  * An absent `comparator` means the default `=` relation per HL7 Chapter 2A.
- * This library surfaces the structure only — it does not evaluate the
+ * This library surfaces the structure only: it does not evaluate the
  * inequality, validate the unit, or convert values.
  *
  * @example
@@ -1205,11 +1386,11 @@ declare function parsePl(rep: RawRepetition, enc: EncodingCharacters): PL;
  * ```
  */
 interface SN {
-    /** SN.1 comparator — one of `>` `<` `>=` `<=` `=` `<>`. Omitted ⇒ default `=`. */
+    /** SN.1 comparator: one of `>` `<` `>=` `<=` `=` `<>`. Omitted ⇒ default `=`. */
     readonly comparator?: string;
     /** SN.2 first numeric value. `undefined` when absent or non-numeric (never `NaN`). */
     readonly num1: number | undefined;
-    /** SN.3 separator/suffix — `-` (range), `:`/`/` (ratio), `+` (suffix), `.`. Omitted when absent. */
+    /** SN.3 separator/suffix: `-` (range), `:`/`/` (ratio), `+` (suffix), `.`. Omitted when absent. */
     readonly separatorOrSuffix?: string;
     /** SN.4 second numeric value. `undefined` when absent or non-numeric (never `NaN`). */
     readonly num2: number | undefined;
@@ -1222,7 +1403,7 @@ interface SN {
  *
  * Fail-safe: a non-operator value in the comparator slot (SN.1) is dropped
  * rather than surfaced as a relation, and a non-numeric SN.2/SN.4 becomes
- * `undefined` — the parser never emits a confident wrong comparator or number.
+ * `undefined`: the parser never emits a confident wrong comparator or number.
  *
  * @example
  * ```ts
@@ -1244,14 +1425,14 @@ declare function parseSn(rep: RawRepetition, enc: EncodingCharacters): SN | unde
  * `Date`-coercing helper into a **fidelity-first** parser. The HL7 v2 Ch. 2A
  * DTM datatype is `YYYY[MM[DD[HH[MM[SS[.S[S[S[S]]]]]]]]][+/-ZZZZ]`, where the
  * number of populated characters (excluding the offset) sets the precision and
- * a missing offset "defaults to that of the local time zone of the sender" —
+ * a missing offset "defaults to that of the local time zone of the sender",
  * NOT UTC and NOT the parser's zone. The old behavior (zero-fill truncations,
  * assume-UTC on a missing offset, eager `Date`) is an architectural defect
  * [S-DTM-IMPL]: it silently shifts a day-only birth date (`|19880705|`) by a
  * day in any negative-offset zone.
  *
  * This module therefore:
- *  - `parseDtm(raw)` decodes the DTM into typed **parts** (`DtmParts`) —
+ *  - `parseDtm(raw)` decodes the DTM into typed **parts** (`DtmParts`),
  *    precision preserved, no zero-fill, no `Date`, no UTC assumption.
  *  - `formatDtm(parts)` reconstructs the DTM string from parts (round-trip).
  *  - `dtmToDate(parts, opts)` materializes an absolute `Date` **only on
@@ -1261,12 +1442,12 @@ declare function parseSn(rep: RawRepetition, enc: EncodingCharacters): SN | unde
  *    formats → built-in fallbacks) used by non-composite callers such as
  *    `msg.meta.timestamp`; it emits `TIMESTAMP_FALLBACK_FORMAT` on a fallback.
  *
- * Zero runtime deps — only the JS stdlib `Date` / `Date.UTC` APIs and
+ * Zero runtime deps: only the JS stdlib `Date` / `Date.UTC` APIs and
  * hand-rolled regex / token matchers. No date-fns, no luxon, no moment.
  */
 
 /**
- * Stated precision of a parsed HL7 DTM value — the number of populated
+ * Stated precision of a parsed HL7 DTM value: the number of populated
  * characters (excluding the timezone offset) determines which level applies.
  * A value's precision is preserved verbatim: `|1970|` is `"year"`, never
  * silently promoted to a full timestamp.
@@ -1280,7 +1461,7 @@ declare function parseSn(rep: RawRepetition, enc: EncodingCharacters): SN | unde
  */
 type DtmPrecision = "year" | "month" | "day" | "hour" | "minute" | "second" | "fraction";
 /**
- * Parsed HL7 v2 TS/DTM value — the raw string plus its structural parts, with
+ * Parsed HL7 v2 TS/DTM value: the raw string plus its structural parts, with
  * the stated **precision** and **timezone fidelity** preserved. This is the
  * shape of the `TS` composite (`field.asTs()`) and every helper datetime.
  *
@@ -1288,7 +1469,7 @@ type DtmPrecision = "year" | "month" | "day" | "hour" | "minute" | "second" | "f
  * **spec-native** (`month` is 1–12, NOT the JS `Date` 0–11). `offsetMinutes`
  * is present iff `hasTimezone` is `true` and is signed minutes east of UTC
  * (`+0500` → `300`, `-0430` → `-270`). A missing offset is **flagged**
- * (`hasTimezone: false`), never resolved to UTC — the consumer decides how to
+ * (`hasTimezone: false`), never resolved to UTC: the consumer decides how to
  * localize with {@link dtmToDate}.
  *
  * @example
@@ -1306,7 +1487,7 @@ interface DtmParts {
     /**
      * `true` when `raw` is a well-formed, in-range HL7 DTM (or a matched
      * fallback format). `false` for empty, malformed, or calendar-out-of-range
-     * input — in which case only `raw` and `hasTimezone: false` are meaningful.
+     * input: in which case only `raw` and `hasTimezone: false` are meaningful.
      */
     readonly valid: boolean;
     /** Stated precision; absent when `valid` is `false`. */
@@ -1325,7 +1506,7 @@ interface DtmParts {
     readonly second?: number;
     /**
      * Fractional-second digits exactly as populated (no leading dot), e.g.
-     * `"5"` (0.5 s), `"0500"` (0.05 s). Preserved verbatim — never rounded.
+     * `"5"` (0.5 s), `"0500"` (0.05 s). Preserved verbatim: never rounded.
      */
     readonly fractionalSeconds?: string;
     /** `true` iff an explicit `+/-ZZZZ` offset was present. */
@@ -1372,7 +1553,7 @@ declare const SUPPORTED_DATE_TOKENS: readonly string[];
  * never coerces to a `Date`, and never assumes UTC for a missing offset.
  *
  * Returns `{ raw, valid: false, hasTimezone: false }` (no parts) for empty,
- * malformed, or calendar-out-of-range input — never throws. A fractional
+ * malformed, or calendar-out-of-range input: never throws. A fractional
  * component is only accepted at full second precision.
  *
  * @example
@@ -1392,12 +1573,12 @@ declare const SUPPORTED_DATE_TOKENS: readonly string[];
 declare function parseDtm(raw: string): DtmParts;
 /**
  * Reconstruct the HL7 DTM string from {@link DtmParts}. The inverse of
- * {@link parseDtm} for a strict HL7 parse — `formatDtm(parseDtm(s)) === s` for
+ * {@link parseDtm} for a strict HL7 parse: `formatDtm(parseDtm(s)) === s` for
  * any well-formed `s`, including the byte-preserving `-0000` (which HL7, unlike
  * RFC 3339, treats as UTC but whose sign we retain for exact round-trip).
  * Returns the raw string unchanged when `parts.valid` is `false`.
  *
- * Emits exactly the populated precision — no zero-fill — so a year-only value
+ * Emits exactly the populated precision, no zero-fill, so a year-only value
  * re-serializes to four characters, never `YYYY0101`.
  *
  * @example
@@ -1423,14 +1604,14 @@ declare function formatDtm(parts: DtmParts): string;
 interface DtmToDateOptions {
     /**
      * Offset (signed minutes east of UTC) to assume when the value carries **no**
-     * timezone. Without it, an offset-less value resolves to `undefined` —
+     * timezone. Without it, an offset-less value resolves to `undefined`,
      * {@link dtmToDate} never guesses a zone. Ignored when the value already has
      * an offset. Pass `0` to explicitly treat a naive value as UTC.
      */
     readonly assumeOffsetMinutes?: number;
 }
 /**
- * Materialize an absolute-instant JS `Date` from {@link DtmParts} — **only on
+ * Materialize an absolute-instant JS `Date` from {@link DtmParts}: **only on
  * explicit caller request**. Truncated fields fill to their lowest legal value
  * (month → January, day → 1, time → 0) *for instant construction only*; the
  * value's stated `precision` still tells the truth.
@@ -1448,35 +1629,35 @@ interface DtmToDateOptions {
  * import { parseDtm, dtmToDate } from "@cosyte/hl7";
  *
  * dtmToDate(parseDtm("20250102153045-0500"))?.toISOString();
- * // "2025-01-02T20:30:45.000Z" — exact, offset-derived
+ * // "2025-01-02T20:30:45.000Z": exact, offset-derived
  *
- * dtmToDate(parseDtm("20250102"));                       // undefined — refuses to guess the zone
+ * dtmToDate(parseDtm("20250102"));                       // undefined: refuses to guess the zone
  * dtmToDate(parseDtm("20250102"), { assumeOffsetMinutes: 0 })?.toISOString();
- * // "2025-01-02T00:00:00.000Z" — caller explicitly assumed UTC
+ * // "2025-01-02T00:00:00.000Z": caller explicitly assumed UTC
  * ```
  */
 declare function dtmToDate(parts: DtmParts, options?: DtmToDateOptions): Date | undefined;
 
 /**
- * TS/DTM — HL7 v2 Time Stamp composite. Delegates parsing to the Phase 2
+ * TS/DTM: HL7 v2 Time Stamp composite. Delegates parsing to the Phase 2
  * helper `src/parser/dates.ts::parseDtm` (D-10 "zero duplicate date logic").
  *
  * Phase N (datetime precision + timezone fidelity) reshaped this composite from
  * the old `{ raw, date }` (which zero-filled truncations and assumed UTC for a
- * missing offset — an architectural defect) to the fidelity-preserving
+ * missing offset: an architectural defect) to the fidelity-preserving
  * {@link DtmParts}: raw string + typed parts + stated precision + timezone
  * presence, with **no eager `Date`**. Callers that need an absolute instant
- * opt in explicitly via `dtmToDate(ts, opts)` — which refuses to guess a zone
+ * opt in explicitly via `dtmToDate(ts, opts)`: which refuses to guess a zone
  * for an offset-less value rather than silently defaulting to UTC.
  *
- * Zero runtime deps — delegates to `parseDtm` + `unescape`.
+ * Zero runtime deps: delegates to `parseDtm` + `unescape`.
  */
 
 /**
- * HL7 v2 Time Stamp (TS) / Date Time (DTM) composite — the raw HL7 string plus
+ * HL7 v2 Time Stamp (TS) / Date Time (DTM) composite: the raw HL7 string plus
  * its parsed parts, preserving the **stated precision** and **timezone
  * fidelity**. This is a {@link DtmParts}: `valid` is `false` (with no parts)
- * for unparseable input — NEVER throws (TYPES-04 no-throw guarantee).
+ * for unparseable input: NEVER throws (TYPES-04 no-throw guarantee).
  *
  * There is deliberately **no `date` field**: a day-only value coerced to a JS
  * `Date` at UTC midnight silently shifts the calendar day in negative-offset
@@ -1489,14 +1670,14 @@ declare function dtmToDate(parts: DtmParts, options?: DtmToDateOptions): Date |
  * import { dtmToDate } from "@cosyte/hl7";
  * const dob: TS = { raw: "19880705", valid: true, precision: "day",
  *   year: 1988, month: 7, day: 5, hasTimezone: false };
- * console.log(dob.precision);          // "day" — not a full timestamp
- * console.log(dtmToDate(dob));         // undefined — refuses to guess the zone
+ * console.log(dob.precision);          // "day": not a full timestamp
+ * console.log(dtmToDate(dob));         // undefined: refuses to guess the zone
  * ```
  */
 type TS = DtmParts;
 /**
  * Parse an HL7 v2 TS/DTM repetition into fidelity {@link TS} parts. Delegates
- * to `parseDtm` — the same structural parser that backs every timestamp in the
+ * to `parseDtm`: the same structural parser that backs every timestamp in the
  * library. No user `dateFormats` at this layer; non-composite callers (e.g.
  * `msg.meta.timestamp`) that know `ParseOptions.dateFormats` use
  * `parseDtmCascade` directly.
@@ -1517,22 +1698,22 @@ type TS = DtmParts;
 declare function parseTs(rep: RawRepetition, _enc: EncodingCharacters): TS;
 
 /**
- * XAD — HL7 v2 Extended Address composite. 12-component structured address
+ * XAD: HL7 v2 Extended Address composite. 12-component structured address
  * shape parsed from a `RawRepetition` on demand by `Field.asXad()` (wired in
- * Plan 04). Fields are OMITTED when absent (exactOptionalPropertyTypes) —
+ * Plan 04). Fields are OMITTED when absent (exactOptionalPropertyTypes),
  * NEVER set to `undefined`.
  *
- * Zero runtime deps — pure function over the raw positional tree + `unescape`.
+ * Zero runtime deps: pure function over the raw positional tree + `unescape`.
  */
 
 /**
- * HL7 v2 Extended Address (XAD) — structured postal address per HL7 Chapter
+ * HL7 v2 Extended Address (XAD): structured postal address per HL7 Chapter
  * 2. All 12 components are optional. Fields are OMITTED when the underlying
  * component is absent (exactOptionalPropertyTypes).
  *
  * Component positions (HL7 1-indexed; this interface is 0-indexed by key):
- * 1. street — street address (house number + street name).
- * 2. otherDesignation — apartment number, suite, floor, etc.
+ * 1. street: street address (house number + street name).
+ * 2. otherDesignation: apartment number, suite, floor, etc.
  * 3. city
  * 4. stateOrProvince
  * 5. zipOrPostalCode
@@ -1566,7 +1747,7 @@ interface XAD {
 }
 /**
  * Parse an HL7 v2 XAD repetition into a structured `XAD` object. Components
- * are returned verbatim (already decoded once by the tokenizer — never re-unescaped,
+ * are returned verbatim (already decoded once by the tokenizer: never re-unescaped,
  * HL7-VALUE-REDECODE). Absent / empty components are OMITTED
  * from the result (exactOptionalPropertyTypes semantics).
  *
@@ -1587,7 +1768,7 @@ interface XAD {
 declare function parseXad(rep: RawRepetition, enc: EncodingCharacters): XAD;
 
 /**
- * XCN — HL7 v2 Extended Composite ID Number and Name for Persons. Common in
+ * XCN: HL7 v2 Extended Composite ID Number and Name for Persons. Common in
  * OBR-16 (ordering provider), PV1-7 (attending doctor), PV1-8 (referring
  * doctor), and other fields that identify a human clinician.
  *
@@ -1596,29 +1777,29 @@ declare function parseXad(rep: RawRepetition, enc: EncodingCharacters): XAD;
  * most-used components (HL7 v2.5 defines 23); additional components may be
  * restored in v2 if vendor-quirk fixtures require them.
  *
- * Zero runtime deps — pure function over the raw positional tree + `unescape`.
+ * Zero runtime deps: pure function over the raw positional tree + `unescape`.
  * Parser is silent (D-09 composite-parser silence).
  */
 
 /**
- * HL7 v2 Extended Composite ID Number and Name for Persons (XCN) — per HL7
+ * HL7 v2 Extended Composite ID Number and Name for Persons (XCN): per HL7
  * Chapter 2.A.88. All 13 v1 components are optional. Fields are OMITTED when
  * the underlying component is absent (exactOptionalPropertyTypes).
  *
  * Component positions (HL7 1-indexed; this interface is 0-indexed by key):
- * 1. idNumber — e.g. employee ID, NPI digits, DEA number (CX-1 analogue)
+ * 1. idNumber: e.g. employee ID, NPI digits, DEA number (CX-1 analogue)
  * 2. familyName (XPN-1)
  * 3. givenName (XPN-2)
- * 4. secondName — second and further given names (XPN-3)
- * 5. suffix — Jr., III, etc. (XPN-4)
- * 6. prefix — Dr., Mrs., etc. (XPN-5)
- * 7. degree — MD, PhD, etc. (XPN-6)
+ * 4. secondName: second and further given names (XPN-3)
+ * 5. suffix: Jr., III, etc. (XPN-4)
+ * 6. prefix: Dr., Mrs., etc. (XPN-5)
+ * 7. degree: MD, PhD, etc. (XPN-6)
  * 8. sourceTable
- * 9. assigningAuthority — nested HD (CX-4 analogue)
- * 10. nameTypeCode — L=Legal, M=Maiden, N=Nickname, ... (XPN-7)
+ * 9. assigningAuthority: nested HD (CX-4 analogue)
+ * 10. nameTypeCode: L=Legal, M=Maiden, N=Nickname, ... (XPN-7)
  * 11. identifierCheckDigit
- * 12. checkDigitScheme — ISO 7064, M10, M11, NPI
- * 13. identifierTypeCode — "NPI", "DN" (DEA number), ... (CX-5 analogue)
+ * 12. checkDigitScheme: ISO 7064, M10, M11, NPI
+ * 13. identifierTypeCode: "NPI", "DN" (DEA number), ... (CX-5 analogue)
  *
  * @example
  * ```ts
@@ -1648,7 +1829,7 @@ interface XCN {
 }
 /**
  * Parse an HL7 v2 XCN repetition into a structured `XCN` object. Components
- * are returned verbatim (already decoded once by the tokenizer — never re-unescaped,
+ * are returned verbatim (already decoded once by the tokenizer: never re-unescaped,
  * HL7-VALUE-REDECODE). Absent / empty components are OMITTED
  * from the result (exactOptionalPropertyTypes semantics). Component 9
  * (`assigningAuthority`) is parsed as a nested `HD`; see component table in
@@ -1682,16 +1863,16 @@ interface XCN {
 declare function parseXcn(rep: RawRepetition, enc: EncodingCharacters): XCN;
 
 /**
- * XPN — HL7 v2 Extended Person Name composite. 14-component structured-name
+ * XPN: HL7 v2 Extended Person Name composite. 14-component structured-name
  * shape parsed from a `RawRepetition` on demand by `Field.asXpn()` (wired in
- * Plan 04). Fields are OMITTED when absent (exactOptionalPropertyTypes) —
+ * Plan 04). Fields are OMITTED when absent (exactOptionalPropertyTypes),
  * NEVER set to `undefined`.
  *
- * Zero runtime deps — pure function over the raw positional tree + `unescape`.
+ * Zero runtime deps: pure function over the raw positional tree + `unescape`.
  */
 
 /**
- * HL7 v2 Extended Person Name (XPN) — structured name per HL7 Chapter 2. All
+ * HL7 v2 Extended Person Name (XPN): structured name per HL7 Chapter 2. All
  * 14 components are optional. Fields are OMITTED when the underlying
  * component is absent (exactOptionalPropertyTypes).
  *
@@ -1704,10 +1885,10 @@ declare function parseXcn(rep: RawRepetition, enc: EncodingCharacters): XCN;
  * 6. degree (e.g. MD, PhD)
  * 7. nameTypeCode (L=Legal, M=Maiden, N=Nickname, S=Coded Pseudo-Name, ...)
  * 8. nameRepresentationCode
- * 9. nameContext (flattened to string in v1 — CWE nesting is out of scope)
+ * 9. nameContext (flattened to string in v1: CWE nesting is out of scope)
  * 10. nameValidityRange
  * 11. nameAssemblyOrder (F=family first, G=given first)
- * 12. effectiveDate (raw HL7 TS string — caller may parse via parseDtm)
+ * 12. effectiveDate (raw HL7 TS string: caller may parse via parseDtm)
  * 13. expirationDate
  * 14. professionalSuffix
  *
@@ -1735,7 +1916,7 @@ interface XPN {
 }
 /**
  * Parse an HL7 v2 XPN repetition into a structured `XPN` object. Components
- * are returned verbatim (already decoded once by the tokenizer — never re-unescaped,
+ * are returned verbatim (already decoded once by the tokenizer: never re-unescaped,
  * HL7-VALUE-REDECODE). Absent / empty components are OMITTED
  * from the result (exactOptionalPropertyTypes semantics).
  *
@@ -1754,34 +1935,34 @@ interface XPN {
 declare function parseXpn(rep: RawRepetition, enc: EncodingCharacters): XPN;
 
 /**
- * XTN — HL7 v2 Extended Telecommunication Number composite. 12-component
+ * XTN: HL7 v2 Extended Telecommunication Number composite. 12-component
  * structured telecom shape (v1 trimmed from the HL7 v2.5 full 14-component
- * XTN — slots 13/14 are rarely-used legacy fields; v2 may restore the full
+ * XTN: slots 13/14 are rarely-used legacy fields; v2 may restore the full
  * shape) parsed from a `RawRepetition` on demand by `Field.asXtn()` (wired
  * in Plan 04). Fields are OMITTED when absent (exactOptionalPropertyTypes)
- * — NEVER set to `undefined`.
+ *: NEVER set to `undefined`.
  *
- * Zero runtime deps — pure function over the raw positional tree + `unescape`.
+ * Zero runtime deps: pure function over the raw positional tree + `unescape`.
  */
 
 /**
- * HL7 v2 Extended Telecommunication Number (XTN) — structured telecom per
+ * HL7 v2 Extended Telecommunication Number (XTN): structured telecom per
  * HL7 Chapter 2. All 12 v1 components are optional. Fields are OMITTED when
  * the underlying component is absent (exactOptionalPropertyTypes).
  *
  * Component positions (HL7 1-indexed; this interface is 0-indexed by key):
- * 1. telephoneNumber — formatted or unformatted phone number
- * 2. telecommunicationUseCode — PRN=Primary Residence, WPN=Work, NET=Internet,
+ * 1. telephoneNumber: formatted or unformatted phone number
+ * 2. telecommunicationUseCode: PRN=Primary Residence, WPN=Work, NET=Internet,
  *    ORN=Other Residence, BPN=Beeper, VHN=Vacation Home, ASN=Answering
  *    Service, EMR=Emergency, ...
- * 3. telecommunicationEquipmentType — PH=Phone, FX=Fax, MD=Modem,
+ * 3. telecommunicationEquipmentType: PH=Phone, FX=Fax, MD=Modem,
  *    CP=Cellular Phone, BP=Beeper, Internet, X.400, TDD, TTY
  * 4. emailAddress
  * 5. countryCode (e.g. "+1")
  * 6. areaCityCode
  * 7. localNumber
  * 8. extension
- * 9. anyText — free-text note
+ * 9. anyText: free-text note
  * 10. extensionPrefix (e.g. "x")
  * 11. speedDialCode
  * 12. unformattedTelephoneNumber
@@ -1812,7 +1993,7 @@ interface XTN {
 }
 /**
  * Parse an HL7 v2 XTN repetition into a structured `XTN` object. Components
- * are returned verbatim (already decoded once by the tokenizer — never re-unescaped,
+ * are returned verbatim (already decoded once by the tokenizer: never re-unescaped,
  * HL7-VALUE-REDECODE). Absent / empty components are OMITTED
  * from the result (exactOptionalPropertyTypes semantics). Components past
  * position 12 are silently ignored in v1.
@@ -1832,7 +2013,7 @@ interface XTN {
 declare function parseXtn(rep: RawRepetition, enc: EncodingCharacters): XTN;
 
 /**
- * `Field` — wrapper over a `RawField` exposing HL7 null/empty discrimination
+ * `Field`: wrapper over a `RawField` exposing HL7 null/empty discrimination
  * (`isNull`), the raw repetitions tree, and a convenience `value` getter that
  * reads the first subcomponent of the first component of the first
  * repetition. Constructed internally by `Segment.field(n)`; user code never
@@ -1841,7 +2022,7 @@ declare function parseXtn(rep: RawRepetition, enc: EncodingCharacters): XTN;
  * Typed composite coercions (`asXpn`, `asXad`, `asCx`, `asCwe`, `asCe`,
  * `asXtn`, `asPl`, `asTs`, `asNm`, `asHd`) delegate to the corresponding
  * composite parsers from `./types/*`. Coercions are lazy and NOT memoized
- * in v1 (D-09) — each call re-parses the first repetition. Empty fields
+ * in v1 (D-09): each call re-parses the first repetition. Empty fields
  * return empty typed objects (`{}` for optional-field composites,
  * `{ raw: "", date: undefined }` / `{ raw: "", value: undefined }` for
  * the TS/NM scalar composites).
@@ -1850,7 +2031,7 @@ declare function parseXtn(rep: RawRepetition, enc: EncodingCharacters): XTN;
 /**
  * Wrapper over a `RawField` exposing HL7 null/empty discrimination
  * (`isNull`), the repetitions tree, and a decoded `value` getter.
- * `seg.field(3) === seg.field(3)` — Field instances are referentially stable
+ * `seg.field(3) === seg.field(3)`: Field instances are referentially stable
  * per segment position (D-12).
  *
  * @example
@@ -1858,19 +2039,19 @@ declare function parseXtn(rep: RawRepetition, enc: EncodingCharacters): XTN;
  * import { parseHL7 } from "@cosyte/hl7";
  * const msg = parseHL7(raw);
  * const pid5 = msg.segments("PID")[0]?.field(5);
- * console.log(pid5?.value);              // "Smith" — decoded at parse
- * console.log(pid5?.isNull);             // false — HL7 explicit null is "", absent is not
+ * console.log(pid5?.value);              // "Smith": decoded at parse
+ * console.log(pid5?.isNull);             // false: HL7 explicit null is "", absent is not
  * console.log(pid5?.repetitions.length); // 1
  * ```
  */
 declare class Field {
-    /** HL7 null indicator — `true` iff the underlying field was the two-char literal `""`. */
+    /** HL7 null indicator: `true` iff the underlying field was the two-char literal `""`. */
     readonly isNull: boolean;
     /** Reference to the underlying `RawField.repetitions` (no defensive copy). */
     readonly repetitions: readonly RawRepetition[];
     /** The 5 encoding characters for this message. Exposed for composite parsers (Plan 04). @internal */
     readonly enc: EncodingCharacters;
-    /** Position of this field in the parent message — used for position-aware error messages. @internal */
+    /** Position of this field in the parent message: used for position-aware error messages. @internal */
     readonly position: Hl7Position;
     /** The full `RawField` this wrapper wraps. Exposed for composite parsers (Plan 02/03/04). @internal */
     readonly raw: RawField;
@@ -1882,7 +2063,7 @@ declare class Field {
     constructor(raw: RawField, enc: EncodingCharacters, position: Hl7Position);
     /**
      * First-repetition, first-component, first-subcomponent value as a decoded
-     * string — unescaped ONCE by the tokenizer on parse, returned verbatim here
+     * string: unescaped ONCE by the tokenizer on parse, returned verbatim here
      * (never re-unescaped, HL7-VALUE-REDECODE). Returns `""` when the field is
      * empty or HL7 null. Equivalent to `msg.get('SEG.N')` for a top-level access.
      *
@@ -1895,13 +2076,13 @@ declare class Field {
      */
     get value(): string;
     /**
-     * The field's **canonical wire text** — the full field re-serialized with
+     * The field's **canonical wire text**: the full field re-serialized with
      * the active delimiters and re-escaped content (repetitions, components,
      * and subcomponents included). Contrast with {@link value}, which
      * returns only the first subcomponent of the first component of the first
-     * repetition (decoded once at parse — never re-unescaped).
+     * repetition (decoded once at parse: never re-unescaped).
      *
-     * Use this when a field must be compared or echoed as a whole — e.g.
+     * Use this when a field must be compared or echoed as a whole: e.g.
      * correlating an ACK's MSA-2 against the inbound MSH-10, where a
      * vendor-quirk control id containing an unescaped delimiter (`ID^X`) must
      * not be truncated to its first component.
@@ -1920,7 +2101,7 @@ declare class Field {
      *
      * **MSH-1/MSH-2 caveat.** Like {@link value}, calling this on MSH-1 or
      * MSH-2 (the delimiter-definition fields) re-escapes the encoding
-     * characters themselves and produces garbage — those two fields are only
+     * characters themselves and produces garbage: those two fields are only
      * meaningful through `Hl7Message.encodingCharacters`.
      *
      * @example
@@ -1933,12 +2114,31 @@ declare class Field {
      */
     get text(): string;
     /**
-     * Return a synthetic empty `Field` sentinel — used by `Segment.field(n)` to
+     * Render this field's formatted text (HL7 v2 §2.7 highlight + formatting
+     * escapes) into a normalized {@link RenderedText} display model: plain text
+     * plus highlight-aware runs. A **read projection** over the field's
+     * byte-verbatim wire {@link text}: it never mutates the raw value, and it
+     * never fabricates (an unrenderable escape is preserved + flagged). Use this
+     * to surface a clinical narrative (an NTE / OBX-5 note) to a human without
+     * the raw `\.br\` / `\H\` sentinels.
+     *
+     * @param opts - see {@link RenderTextOptions} (e.g. a custom line-break string).
+     * @returns the normalized display model.
+     *
+     * @example
+     * ```ts
+     * const note = msg.segments("OBX")[0]?.field(5);
+     * note?.render().text; // "Specimen received.\nGross exam normal."
+     * ```
+     */
+    render(opts?: RenderTextOptions): RenderedText;
+    /**
+     * Return a synthetic empty `Field` sentinel: used by `Segment.field(n)` to
      * honor MODEL-05's "never throws on missing" contract. The returned Field
      * has `isNull === false`, `repetitions === []`, and `value === ""`.
      * Referentially stable across calls (same instance returned each time).
      *
-     * The `enc` argument is accepted for API symmetry but ignored — the
+     * The `enc` argument is accepted for API symmetry but ignored: the
      * synthetic field carries no content, so unescape would be a no-op
      * regardless of the active encoding characters.
      *
@@ -1953,7 +2153,7 @@ declare class Field {
     /**
      * Coerce this field's first repetition to a typed `XPN` (Extended Person
      * Name). Absent components are OMITTED from the result
-     * (`exactOptionalPropertyTypes`). Not memoized in v1 — each call re-parses
+     * (`exactOptionalPropertyTypes`). Not memoized in v1: each call re-parses
      * (D-09).
      *
      * @example
@@ -2029,7 +2229,7 @@ declare class Field {
      */
     asPl(): PL;
     /**
-     * Coerce this field's first repetition to a typed `TS` (Time Stamp) — the
+     * Coerce this field's first repetition to a typed `TS` (Time Stamp): the
      * fidelity `DtmParts` (raw + parts + precision + timezone). `valid` is
      * `false` on unparseable input (no throw). Build an absolute instant only on
      * explicit request via `dtmToDate(ts)`.
@@ -2043,7 +2243,7 @@ declare class Field {
     asTs(): TS;
     /**
      * Coerce this field's first repetition to a typed `NM` (Numeric).
-     * `{ raw, value }` — `value` is `undefined` on non-numeric input.
+     * `{ raw, value }`: `value` is `undefined` on non-numeric input.
      *
      * @example
      * ```ts
@@ -2094,18 +2294,18 @@ declare class Field {
 }
 
 /**
- * `Segment` — wrapper class over a `RawSegment` that exposes `field(n)` with
+ * `Segment`: wrapper class over a `RawSegment` that exposes `field(n)` with
  * referentially stable `Field` instances (D-12). Constructed internally by
  * `Hl7Message.segments(type)` / `Hl7Message.allSegments()`; user code never
  * calls `new Segment(...)` directly.
  *
- * The wrapper does NOT copy `raw.fields` — it holds a reference so mutations
+ * The wrapper does NOT copy `raw.fields`: it holds a reference so mutations
  * through Plan 04's `setField` / `addSegment` / `removeSegment` stay visible.
  */
 
 /**
  * Wrapper over a `RawSegment` exposing typed per-position `Field` instances.
- * `seg.field(3) === seg.field(3)` — referential stability is guaranteed per
+ * `seg.field(3) === seg.field(3)`: referential stability is guaranteed per
  * segment instance.
  *
  * @example
@@ -2119,7 +2319,7 @@ declare class Field {
 declare class Segment {
     /** Segment name (3 chars, e.g. `"PID"`, `"OBX"`, `"ZPI"`). */
     readonly type: string;
-    /** Reference to the underlying `RawSegment.fields` — 1-indexed per HL7 convention. */
+    /** Reference to the underlying `RawSegment.fields`: 1-indexed per HL7 convention. */
     readonly fields: readonly RawField[];
     /** The 5 encoding characters for this message. Exposed for composite parsers. @internal */
     readonly enc: EncodingCharacters;
@@ -2135,7 +2335,7 @@ declare class Segment {
      * @internal
      */
     readonly customFields: Readonly<Record<string, number>> | undefined;
-    /** Lazy cache of Field wrappers — one per fields[] position. @internal */
+    /** Lazy cache of Field wrappers: one per fields[] position. @internal */
     private _fieldWrappers;
     /**
      * Construct a new `Segment`. Called internally by `Hl7Message`; user code
@@ -2151,16 +2351,16 @@ declare class Segment {
     constructor(raw: RawSegment, enc: EncodingCharacters, absoluteIndex: number, customFields?: Readonly<Record<string, number>>);
     /**
      * Return the `Field` wrapper at HL7 position `n`. Indexing follows the HL7
-     * 1-indexed convention — `seg.field(5)` on a PID segment maps to PID-5.
+     * 1-indexed convention: `seg.field(5)` on a PID segment maps to PID-5.
      * MSH segments use the same user-facing convention: `msh.field(1)` returns
      * the field-separator (MSH-1), `msh.field(2)` returns encoding chars
-     * (MSH-2), `msh.field(3)` returns MSH-3, and so on — the internal
+     * (MSH-2), `msh.field(3)` returns MSH-3, and so on: the internal
      * `fields[N-1]` offset for MSH segments is applied here (mirrors the
      * dot-path resolver in `dot-path.ts`, keeping `msg.segments('MSH')[0].field(3)`
      * and `msg.get('MSH.3')` in agreement).
      *
      * Returns a synthetic empty `Field` (`.isNull === false`, `.value === ""`)
-     * when `n` is out of range — never throws (MODEL-05). Successive calls with
+     * when `n` is out of range: never throws (MODEL-05). Successive calls with
      * the same `n` return the same `Field` instance (D-12).
      *
      * @example
@@ -2175,13 +2375,13 @@ declare class Segment {
     /**
      * Return the `Field` at the profile-declared position for `name`, or
      * `undefined` when no custom mapping exists (PROF-07). Unlike `field(n)`,
-     * missing names return `undefined` — NOT a synthetic empty Field — so
+     * missing names return `undefined`, NOT a synthetic empty Field, so
      * typos surface instead of silently resolving to an empty string (D-14).
      *
      * For segments without a profile-declared customSegments slice (most
      * non-Z segments, and any Z-segment whose host message had no profile
      * applied), this method always returns `undefined` (D-15 defense-in-depth
-     * — D-05 already rejects standard-segment overlays at `defineProfile()`
+     *: D-05 already rejects standard-segment overlays at `defineProfile()`
      * time).
      *
      * When the declared position is out of range for the underlying
@@ -2200,7 +2400,7 @@ declare class Segment {
 }
 
 /**
- * `identityEvents` — roadmap Phase K read-side helper that recognizes the ADT
+ * `identityEvents`: roadmap Phase K read-side helper that recognizes the ADT
  * patient-identity management trigger events and surfaces the MRG segment's
  * *prior* (non-surviving) identifiers alongside the PID/PV1 *surviving*
  * identifiers, each labelled by role.
@@ -2208,7 +2408,7 @@ declare class Segment {
  * Spec traceability (HL7 v2 Ch. 3, Patient Administration):
  * - A18 "The PID segment contains the surviving patient ID information. The
  *   MRG segment contains the non-surviving information." The merge direction
- *   is spec-explicit and constant: **MRG (prior) → PID (surviving)** — this
+ *   is spec-explicit and constant: **MRG (prior) → PID (surviving)**: this
  *   helper NEVER infers it from content and never reverses it.
  * - Merge family (§3.3.34–§3.3.42): A34/A35/A36 (v2.3-era merges), A39 merge
  *   person, A40 merge patient identifier list, A41 merge account, A42 merge
@@ -2217,33 +2417,33 @@ declare class Segment {
  *   A28 / A31 (PID only, no MRG).
  * - MRG field map is **version-scoped** (v2.5.1 §3.4.10): MRG-1 prior patient
  *   identifier list (CX, repeating), MRG-3 prior patient account number (CX),
- *   MRG-4 prior patient ID (CX, backward-compat only — **withdrawn as of
+ *   MRG-4 prior patient ID (CX, backward-compat only: **withdrawn as of
  *   v2.7** in favour of MRG-1), MRG-5 prior visit number (CX), MRG-7 prior
  *   patient name (XPN). MRG-2 / MRG-6 (prior *alternate* patient/visit IDs,
  *   also withdrawn v2.7) are deliberately not surfaced. On a v2.7+ message
- *   (MSH-12) the withdrawn MRG-4 — and the symmetric withdrawn PID-2 — are
+ *   (MSH-12) the withdrawn MRG-4 (and the symmetric withdrawn PID-2) are
  *   NOT read as identity fields.
  *
  * Fail-safe: a merge/move event missing either side of the MRG→PID pair
  * surfaces what is present plus a `MERGE_MISSING_PRIOR_OR_SURVIVOR` warning on
- * the event — the MRG is **never dropped** (an orphaned MRG yields its own
+ * the event: the MRG is **never dropped** (an orphaned MRG yields its own
  * event) and the direction is **never guessed**. The helper never throws.
  *
  * PHI note: identifiers and names are the *payload* of the typed view (by
- * design — the consumer needs them to apply the merge), but warning messages
+ * design: the consumer needs them to apply the merge), but warning messages
  * carry only structural facts (event code + missing role), never a value.
  *
  * Applying the merge (re-pointing stored data to the survivor) is the
- * consumer's / integration engine's job — this helper only surfaces it.
+ * consumer's / integration engine's job: this helper only surfaces it.
  */
 
 /**
  * Classification of a recognized identity trigger event.
  *
- * - `merge` — A18 / A34 / A35 / A36 / A39 / A40 / A41 / A42 (MRG expected)
- * - `move` — A43 / A44 (MRG expected)
- * - `link` / `unlink` — A24 / A37 (two PID groups, no MRG)
- * - `add` / `update` — A28 / A31 (person add/update, no MRG)
+ * - `merge`: A18 / A34 / A35 / A36 / A39 / A40 / A41 / A42 (MRG expected)
+ * - `move`: A43 / A44 (MRG expected)
+ * - `link` / `unlink`: A24 / A37 (two PID groups, no MRG)
+ * - `add` / `update`: A28 / A31 (person add/update, no MRG)
  *
  * @example
  * ```ts
@@ -2255,7 +2455,7 @@ type IdentityEventKind = "merge" | "move" | "link" | "unlink" | "add" | "update"
 /**
  * Role of one party in an identity event. `surviving` / `subject` / `linked`
  * parties are ONLY ever sourced from PID (+ PV1); `prior` parties are ONLY
- * ever sourced from MRG — the role-labelling invariant Phase K exists for.
+ * ever sourced from MRG: the role-labelling invariant Phase K exists for.
  *
  * @example
  * ```ts
@@ -2289,15 +2489,15 @@ type IdentityRole = "surviving" | "prior" | "linked" | "subject";
  * ```
  */
 interface IdentityParty {
-    /** Role of this party in the event — the safety-critical label. */
+    /** Role of this party in the event: the safety-critical label. */
     readonly role: IdentityRole;
-    /** Segment this party was sourced from — provenance for the role label. */
+    /** Segment this party was sourced from: provenance for the role label. */
     readonly sourceSegment: "PID" | "MRG";
     /** Identifier list (PID-3 / MRG-1), every non-empty CX repetition. */
     readonly identifiers: readonly CX[];
     /**
      * Legacy single patient ID (PID-2 / MRG-4). Backward-compat only; withdrawn
-     * as of HL7 v2.7 — OMITTED (not read) when MSH-12 declares v2.7 or later.
+     * as of HL7 v2.7: OMITTED (not read) when MSH-12 declares v2.7 or later.
      */
     readonly legacyPatientId?: CX;
     /** Patient account number (PID-18 / MRG-3). */
@@ -2310,11 +2510,11 @@ interface IdentityParty {
 /**
  * One recognized patient-identity event. For `merge` / `move` kinds the
  * `surviving` (PID/PV1-sourced) and `prior` (MRG-sourced) parties are also
- * exposed directly, with the spec-constant `direction: "MRG_TO_PID"` — the
+ * exposed directly, with the spec-constant `direction: "MRG_TO_PID"`: the
  * prior identifiers are the ones being retired in favour of the surviving
  * ones, never the reverse (HL7 v2 Ch. 3, A18/A39/A40).
  *
- * `parties` is the complete role-labelled surface in document order — nothing
+ * `parties` is the complete role-labelled surface in document order: nothing
  * present in the message is dropped, including a nonconforming MRG in a
  * link/add message (surfaced as a `prior`-role party).
  *
@@ -2330,7 +2530,7 @@ interface IdentityParty {
  *   if (ev.kind === "merge" && ev.prior && ev.surviving) {
  *     // retire ev.prior.identifiers in favour of ev.surviving.identifiers
  *   } else if (ev.warnings.length > 0) {
- *     // incomplete pair — do NOT apply; route for review
+ *     // incomplete pair: do NOT apply; route for review
  *   }
  * }
  * ```
@@ -2340,11 +2540,11 @@ interface IdentityEvent {
     readonly eventType: string;
     /** Classification of the trigger event. */
     readonly kind: IdentityEventKind;
-    /** Every party in document order, role-labelled — the complete surface. */
+    /** Every party in document order, role-labelled: the complete surface. */
     readonly parties: readonly IdentityParty[];
-    /** The surviving party (merge/move) — ONLY ever sourced from PID/PV1. */
+    /** The surviving party (merge/move): ONLY ever sourced from PID/PV1. */
     readonly surviving?: IdentityParty;
-    /** The prior (non-surviving) party (merge/move) — ONLY ever sourced from MRG. */
+    /** The prior (non-surviving) party (merge/move): ONLY ever sourced from MRG. */
     readonly prior?: IdentityParty;
     /**
      * Spec-constant merge/move direction: the MRG (prior) identifiers merge
@@ -2357,14 +2557,14 @@ interface IdentityEvent {
 }
 
 /**
- * Phase 4 helper type declarations — the 9 typed shapes returned by
+ * Phase 4 helper type declarations: the 9 typed shapes returned by
  * `Hl7Message.meta`/`.patient`/`.visit` getters and the 6 collection methods
  * (`observations()`, `orders()`, `nextOfKin()`, `allergies()`, `diagnoses()`,
  * `insurance()`). Every field is `readonly`; every optional key is
  * `exactOptionalPropertyTypes`-safe (never `| undefined` on the declaration).
  *
  * Types compose on the 11 v1 composites from `src/model/types/*.ts` (XPN, XAD,
- * CX, CWE, CE, XTN, PL, XCN) — helpers are pure views on top of Phase 3's
+ * CX, CWE, CE, XTN, PL, XCN): helpers are pure views on top of Phase 3's
  * composite coercions, never re-parsing the raw tree.
  *
  * Field lists locked by Phase 4 CONTEXT.md decisions D-01..D-24. Nine interfaces:
@@ -2401,7 +2601,7 @@ interface Meta {
     readonly triggerEvent?: string;
     /** MSH-9.3 message structure (e.g. "ADT_A01"). */
     readonly messageStructure?: string;
-    /** MSH-10 message control ID — unique per message per sender. */
+    /** MSH-10 message control ID: unique per message per sender. */
     readonly controlId?: string;
     /** MSH-7 message date/time as the fidelity `TS` (Phase N). */
     readonly timestamp?: TS;
@@ -2422,7 +2622,7 @@ interface Meta {
  * PID-derived patient view (HELPERS-02). `msg.patient` is `undefined` (D-04)
  * when no PID segment exists; this interface describes the shape when
  * present. `identifiers` and `phoneNumbers` are ALWAYS present as arrays
- * (D-09 / D-20) — empty when the underlying field is absent. `name` is
+ * (D-09 / D-20): empty when the underlying field is absent. `name` is
  * ALWAYS present (D-19) even if `{}` when PID-5 is empty.
  *
  * @example
@@ -2457,7 +2657,7 @@ interface Patient {
     readonly fullName?: string;
     /**
      * PID-7 date of birth as the fidelity `TS` (Phase N). A day-only DOB keeps
-     * `precision: "day"` — never coerced to a UTC-midnight instant that would
+     * `precision: "day"`: never coerced to a UTC-midnight instant that would
      * read as the previous day in a negative-offset zone.
      */
     readonly dateOfBirth?: TS;
@@ -2474,7 +2674,7 @@ interface Patient {
     /** PID-15 primary language. */
     readonly language?: CE;
     /**
-     * NTE note lines positionally attached to the (first) PID (Phase P) — notes
+     * NTE note lines positionally attached to the (first) PID (Phase P): notes
      * immediately following the patient's PID segment, HL7-unescaped, in
      * document order. OMITTED when the patient carries no notes. High-PHI-risk
      * clinical narrative.
@@ -2530,7 +2730,7 @@ interface Visit {
  * ```
  */
 interface ObservationBase {
-    /** OBX-1 set id (string — typically sequential "1", "2", ...). */
+    /** OBX-1 set id (string: typically sequential "1", "2", ...). */
     readonly setId?: string;
     /** OBX-3 observation identifier. Always present (may be `{}` if OBX-3 absent). */
     readonly identifier: CWE;
@@ -2538,11 +2738,11 @@ interface ObservationBase {
     readonly units?: CWE;
     /**
      * `true` iff OBX-6's coding system (CWE.3, "name of coding system") is
-     * exactly `UCUM` (HL7 Table 0396) — i.e. the unit is declared UCUM and is
+     * exactly `UCUM` (HL7 Table 0396): i.e. the unit is declared UCUM and is
      * safe to interpret as a computable unit. `false` means a unit IS present
      * but is NOT declared UCUM (e.g. a local code or free text) and is surfaced
      * as-is, never coerced. OMITTED when OBX-6 is absent. This is a *claim* check
-     * only — the library does not validate UCUM grammar or check the alternate
+     * only: the library does not validate UCUM grammar or check the alternate
      * coding system (CWE.6).
      */
     readonly unitsAreUcum?: boolean;
@@ -2555,7 +2755,7 @@ interface ObservationBase {
     /** OBX-14 date/time of observation as the fidelity `TS` (Phase N). */
     readonly observedDateTime?: TS;
     /**
-     * NTE note lines positionally attached to this OBX (Phase P) — each
+     * NTE note lines positionally attached to this OBX (Phase P): each
      * non-empty NTE-3 (Comment, FT) repetition of every NTE immediately
      * following this observation, HL7-unescaped, in document order. OMITTED when
      * the observation carries no notes. High-PHI-risk clinical narrative.
@@ -2608,30 +2808,30 @@ type Observation = ObservationBase & ({
     readonly value: string | undefined;
 });
 /**
- * How an order/medication `RepeatPattern` code (HL7 Table 0335) is classified —
+ * How an order/medication `RepeatPattern` code (HL7 Table 0335) is classified,
  * **provenance only, never used to resolve a schedule** (Phase M). The `code`
  * is always authoritative and surfaced verbatim; this flag only tells a
  * consumer *what kind* of pattern it is looking at so it can decide whether a
  * load-bearing integer is present.
  *
- * - `"parametric"` — a `Q<integer><unit>` template (`Q6H`, `Q30M`, `Q2D`,
+ * - `"parametric"`: a `Q<integer><unit>` template (`Q6H`, `Q30M`, `Q2D`,
  *   `Q1W`, `Q3J5`) whose **integer is load-bearing**: `Q6H` (every 6 hours) is
  *   a different dose count from `Q8H`. The parsed integer + unit ride on
  *   {@link RepeatPattern.interval}.
- * - `"named"` — a recognized fixed Table-0335 mnemonic scheduled at
+ * - `"named"`: a recognized fixed Table-0335 mnemonic scheduled at
  *   institution-specified times (`BID`, `TID`, `QID`, `QOD`, `QHS`, `QAM`,
  *   `QPM`, `QSHIFT`, `PRN`, `AC`, `PC`, `HS`, `C`). No numeric interval.
- * - `"unknown"` — anything else (a local code, free text, an unrecognized
+ * - `"unknown"`: anything else (a local code, free text, an unrecognized
  *   mnemonic). Surfaced **verbatim**, never mapped to a frequency.
  */
 type RepeatPatternKind = "parametric" | "named" | "unknown";
 /**
- * An order/medication timing **repeat pattern** (HL7 Table 0335) — the
+ * An order/medication timing **repeat pattern** (HL7 Table 0335): the
  * frequency/SIG field (TQ1-3, or the legacy embedded TQ interval RI.1), Phase M.
  *
  * **Safety contract.** `code` is the **decoded field value** (HL7 escapes are
  * unescaped as with every field read) and is **never resolved to clock times,
- * normalized, or mapped to a different frequency** — reading `Q6H` as "daily"
+ * normalized, or mapped to a different frequency**: reading `Q6H` as "daily"
  * or silently dropping a `BID` changes the administered dose count, a
  * transcription-class harm. `kind`/`interval` are convenience provenance ONLY;
  * `code` is the authoritative value.
@@ -2646,12 +2846,12 @@ type RepeatPatternKind = "parametric" | "named" | "unknown";
 interface RepeatPattern {
     /** The Table-0335 repeat-pattern code exactly as authored (e.g. `"Q6H"`, `"BID"`). Never normalized. */
     readonly code: string;
-    /** Provenance classification of `code` — never used to resolve a schedule. See {@link RepeatPatternKind}. */
+    /** Provenance classification of `code`: never used to resolve a schedule. See {@link RepeatPatternKind}. */
     readonly kind: RepeatPatternKind;
     /**
      * For a `"parametric"` `Q<integer><unit>` template only: the load-bearing
      * integer and its unit letter (`S`/`M`/`H`/`D`/`W`/`L`, or `J` for
-     * day-of-week). OMITTED for `"named"`/`"unknown"` patterns. Informational —
+     * day-of-week). OMITTED for `"named"`/`"unknown"` patterns. Informational,
      * `code` remains authoritative.
      */
     readonly interval?: {
@@ -2660,7 +2860,7 @@ interface RepeatPattern {
     };
 }
 /**
- * A composite-quantity (CQ) value on an order/medication timing — the TQ1-2
+ * A composite-quantity (CQ) value on an order/medication timing: the TQ1-2
  * service quantity, Phase M. `value` is strict-`Number()` parsed (`undefined`,
  * never `NaN`); `units` carries any CQ.2 units. Both keys OMITTED when absent.
  *
@@ -2677,7 +2877,7 @@ interface TimingQuantity {
     readonly units?: CWE;
 }
 /**
- * The order/medication **timing** structure — one TQ1 segment (v2.5+) or the
+ * The order/medication **timing** structure: one TQ1 segment (v2.5+) or the
  * legacy embedded TQ in ORC-7 / RXE-1 (pre-v2.5), Phase M. Attached to
  * {@link Order.timings} and {@link Medication.timings}.
  *
@@ -2686,7 +2886,7 @@ interface TimingQuantity {
  * clock times, or interpret sig. The load-bearing {@link repeatPattern} and
  * {@link totalOccurrences} are preserved verbatim (see {@link RepeatPattern});
  * `startDateTime`/`endDateTime` keep the Phase N `TS` precision + timezone
- * fidelity. A malformed timing never throws — absent pieces are omitted keys.
+ * fidelity. A malformed timing never throws: absent pieces are omitted keys.
  *
  * @example
  * ```ts
@@ -2704,18 +2904,18 @@ interface OrderTiming {
      * Which structure this timing was read from: the dedicated **TQ1** segment
      * (v2.5+) or the **legacy** embedded TQ data type in ORC-7 (orders) / RXE-1
      * (encoded medications, pre-v2.5). The library treats the presence of a TQ1
-     * segment as the v2.5+ signal — the legacy embedded TQ is surfaced only when
+     * segment as the v2.5+ signal: the legacy embedded TQ is surfaced only when
      * no TQ1 accompanies the order, so the same timing is never double-counted
      * and a legacy-only timing is never dropped.
      */
     readonly source: "TQ1" | "legacy";
     /** TQ1-2 / legacy TQ.1 service quantity (CQ). */
     readonly quantity?: TimingQuantity;
-    /** TQ1-3 / legacy TQ.2 interval RI.1 repeat pattern (Table 0335) — verbatim. See {@link RepeatPattern}. */
+    /** TQ1-3 / legacy TQ.2 interval RI.1 repeat pattern (Table 0335): verbatim. See {@link RepeatPattern}. */
     readonly repeatPattern?: RepeatPattern;
-    /** TQ1-4 / legacy TQ.2 interval RI.2 explicit time(s) — surfaced verbatim (first repetition/value). */
+    /** TQ1-4 / legacy TQ.2 interval RI.2 explicit time(s): surfaced verbatim (first repetition/value). */
     readonly explicitTime?: string;
-    /** TQ1-6 / legacy TQ.3 service duration — surfaced verbatim. */
+    /** TQ1-6 / legacy TQ.3 service duration: surfaced verbatim. */
     readonly serviceDuration?: string;
     /** TQ1-7 / legacy TQ.4 start date/time as the fidelity `TS` (Phase N). */
     readonly startDateTime?: TS;
@@ -2724,7 +2924,7 @@ interface OrderTiming {
     /** TQ1-9 priority (CWE) / legacy TQ.6 priority (surfaced as a CWE `{ identifier }`). */
     readonly priority?: CWE;
     /**
-     * TQ1-14 / legacy TQ.12 total occurrences (NM) — how many times the service
+     * TQ1-14 / legacy TQ.12 total occurrences (NM): how many times the service
      * is to be performed (strict-parsed; never `NaN`). **TQ1-14, not TQ1-11**
      * (TQ1-11 is Text Instruction). Load-bearing: losing it drops the total
      * administered count.
@@ -2733,8 +2933,8 @@ interface OrderTiming {
 }
 /**
  * OBR-derived order (HELPERS-05, D-16) with positionally-grouped OBX children
- * (D-12). `observations` is ALWAYS present — empty when no OBX follows this
- * OBR before the next OBR or end-of-message. Phase M adds `timings` — ALWAYS
+ * (D-12). `observations` is ALWAYS present: empty when no OBX follows this
+ * OBR before the next OBR or end-of-message. Phase M adds `timings`: ALWAYS
  * present, empty when the order carries no TQ1 / legacy embedded TQ.
  *
  * @example
@@ -2757,7 +2957,7 @@ interface Order {
     readonly fillerOrderNumber?: string;
     /** OBR-4 universal service identifier (test code + description). */
     readonly universalServiceId?: CWE;
-    /** OBR-5 order status (v1 — Phase 7 may reconcile with OBR-25). */
+    /** OBR-5 order status (v1: Phase 7 may reconcile with OBR-25). */
     readonly orderStatus?: string;
     /** ORC-1 order control when an ORC precedes this OBR. */
     readonly orderControl?: string;
@@ -2767,23 +2967,23 @@ interface Order {
     readonly observations: readonly Observation[];
     /**
      * TQ1 / legacy embedded-TQ timing(s) grouped under this order (Phase M).
-     * Always present — empty when the order carries no timing. See
+     * Always present: empty when the order carries no timing. See
      * {@link OrderTiming}.
      */
     readonly timings: readonly OrderTiming[];
     /**
-     * NTE note lines positionally attached to this order (Phase P) — the
+     * NTE note lines positionally attached to this order (Phase P): the
      * ORC-region notes (before the OBR) followed by the OBR-region notes, in
      * document order. Several ORCs before one OBR all contribute here; nothing is
      * dropped. OMITTED when the order carries no notes. A note on a trailing or
      * dangling ORC that never opens an order is surfaced at message level
-     * (`msg.notes()`), not here — still never dropped. High-PHI-risk clinical
+     * (`msg.notes()`), not here: still never dropped. High-PHI-risk clinical
      * narrative.
      */
     readonly notes?: readonly string[];
 }
 /**
- * NK1-derived next-of-kin entry (HELPERS-06). Lean subset — callers can
+ * NK1-derived next-of-kin entry (HELPERS-06). Lean subset: callers can
  * reach for `msg.segments("NK1")` when they need the full NK1 surface.
  *
  * @example
@@ -2857,21 +3057,21 @@ interface Diagnosis {
     readonly type?: string;
 }
 /**
- * Which pharmacy/treatment segment a `Medication` was extracted from — the
+ * Which pharmacy/treatment segment a `Medication` was extracted from: the
  * clinical "phase" of the medication. Each value maps 1:1 to one RX* parent
  * segment (Phase D, Ch. 4A):
- * - `"order"` — **RXO** (Pharmacy/Treatment Order): the originally *requested*
+ * - `"order"`: **RXO** (Pharmacy/Treatment Order): the originally *requested*
  *   give code/amount/dosage-form, before pharmacy encoding.
- * - `"encoded"` — **RXE** (Encoded Order): the pharmacy-encoded give
- *   code/amount, plus the give *strength* (RXE-25/26) — the only context that
+ * - `"encoded"`: **RXE** (Encoded Order): the pharmacy-encoded give
+ *   code/amount, plus the give *strength* (RXE-25/26): the only context that
  *   carries a separate strength.
- * - `"dispense"` — **RXD** (Dispense): what was actually dispensed.
- * - `"administration"` — **RXA** (Administration): what was actually given to
+ * - `"dispense"`: **RXD** (Dispense): what was actually dispensed.
+ * - `"administration"`: **RXA** (Administration): what was actually given to
  *   the patient.
  *
  * The context is preserved verbatim and never collapsed: an RDE order that
  * carries both an RXO request and an RXE encoded line surfaces as TWO
- * `Medication` entries with distinct contexts — the helper never reconciles
+ * `Medication` entries with distinct contexts: the helper never reconciles
  * one against the other.
  */
 type MedicationContext = "order" | "encoded" | "dispense" | "administration";
@@ -2880,10 +3080,10 @@ type MedicationContext = "order" | "encoded" | "dispense" | "administration";
  * Carries the HL7 min/max amount pair and its units.
  *
  * - For an **order** (RXO-2/3) or **encoded** order (RXE-3/4) the amount is a
- *   genuine min..max range — both keys may be present.
+ *   genuine min..max range: both keys may be present.
  * - For a **dispense** (RXD-4) or **administration** (RXA-6) there is a SINGLE
  *   amount; it is surfaced as `minimum` with `maximum` OMITTED. This is a
- *   single value, not a range — do not read the absent `maximum` as "no upper
+ *   single value, not a range: do not read the absent `maximum` as "no upper
  *   bound on a range".
  *
  * `minimum`/`maximum` are strict-`Number()` parsed (`undefined`, never `NaN`).
@@ -2906,7 +3106,7 @@ interface MedicationAmount {
 }
 /**
  * The give *strength* of an **encoded** `Medication` (RXE-25 value + RXE-26
- * units) — Phase D. Strength is the concentration of active ingredient (e.g.
+ * units): Phase D. Strength is the concentration of active ingredient (e.g.
  * "250 mg"), distinct from the give *amount* (how much is administered, e.g.
  * "2 tablets"). Only the `"encoded"` (RXE) context carries strength.
  *
@@ -2914,7 +3114,7 @@ interface MedicationAmount {
  * RXE-25/26 fields declare it, and is NEVER reconciled against any strength
  * *implied* by the give code (e.g. an NDC that encodes "250 mg"). A consumer
  * that sees both an explicit strength here and a coded drug in `giveCode` must
- * treat a disagreement as a real signal — the library does not silently pick a
+ * treat a disagreement as a real signal: the library does not silently pick a
  * winner. `value` is strict-`Number()` parsed (`undefined`, never `NaN`).
  *
  * @example
@@ -2932,7 +3132,7 @@ interface MedicationStrength {
 /**
  * One RXR (Pharmacy/Treatment Route) grouped under its parent RX* segment
  * (Phase D). `route` is HL7 Table 0162 (CWE); `site` is Table 0163 (CWE).
- * Provenance travels on the CWE (`route.nameOfCodingSystem`) — a "PO" route is
+ * Provenance travels on the CWE (`route.nameOfCodingSystem`): a "PO" route is
  * only safe to act on when you know the system it was coded against.
  *
  * @example
@@ -2949,7 +3149,7 @@ interface MedicationRoute {
 }
 /**
  * One RXC (Pharmacy/Treatment Component Order) grouped under its parent RX*
- * segment (Phase D) — a component of a compound/IV. Surfaced STRUCTURALLY
+ * segment (Phase D): a component of a compound/IV. Surfaced STRUCTURALLY
  * (the component list as authored), NOT pharmacologically resolved.
  *
  * @example
@@ -2959,7 +3159,7 @@ interface MedicationRoute {
  * ```
  */
 interface MedicationComponent {
-    /** RXC-1 component type (e.g. "B"=base, "A"=additive — HL7 Table 0166). */
+    /** RXC-1 component type (e.g. "B"=base, "A"=additive: HL7 Table 0166). */
     readonly type?: string;
     /** RXC-2 component code. */
     readonly code?: CWE;
@@ -2977,15 +3177,15 @@ interface MedicationComponent {
  * **Safety contract.** A wrong drug, strength, or route can harm a real
  * patient, so this view is deliberately conservative:
  * - `giveCode` carries its own coding-system provenance via the CWE
- *   (`giveCode.nameOfCodingSystem` — e.g. `RXN` RxNorm, `NDC`). The helper
+ *   (`giveCode.nameOfCodingSystem`: e.g. `RXN` RxNorm, `NDC`). The helper
  *   surfaces the *claim*; it never validates or looks the code up.
  * - `amount` (how much) and `strength` (concentration) are SEPARATE fields and
- *   are never reconciled — including against any strength a coded drug implies
+ *   are never reconciled: including against any strength a coded drug implies
  *   (Phase D §4). A disagreement is preserved for the consumer to see.
- * - Malformed RX* segments never throw — absent fields are omitted keys.
+ * - Malformed RX* segments never throw: absent fields are omitted keys.
  *
  * `routes` and `components` are ALWAYS present (possibly empty). Phase M adds
- * `timings` — ALWAYS present, empty when no TQ1 / legacy embedded TQ (RXE-1)
+ * `timings`: ALWAYS present, empty when no TQ1 / legacy embedded TQ (RXE-1)
  * accompanies the medication; the repeat pattern is surfaced **verbatim, never
  * normalized to a schedule**. Deferred (not v1): sig/frequency *interpretation*,
  * dose-range or interaction checking, pharmacologic resolution of compounds.
@@ -3011,7 +3211,7 @@ interface Medication {
     readonly giveCode?: CWE;
     /** Give/dispense/administered amount (+ units). See {@link MedicationAmount}. */
     readonly amount?: MedicationAmount;
-    /** RXE-25/26 give strength — ENCODED context only; never reconciled with `giveCode`. */
+    /** RXE-25/26 give strength: ENCODED context only; never reconciled with `giveCode`. */
     readonly strength?: MedicationStrength;
     /** RXO-5 requested dosage form (order context). */
     readonly dosageForm?: CWE;
@@ -3021,7 +3221,7 @@ interface Medication {
     readonly components: readonly MedicationComponent[];
     /**
      * TQ1 / legacy embedded-TQ (RXE-1) timing(s) grouped under this medication
-     * (Phase M). Always present — empty when the medication carries no timing.
+     * (Phase M). Always present: empty when the medication carries no timing.
      * See {@link OrderTiming}.
      */
     readonly timings: readonly OrderTiming[];
@@ -3067,11 +3267,11 @@ interface Insurance {
 }
 /**
  * Whether an `Immunization` records a dose that was **administered** by the
- * reporting system or is **historical** information sourced from elsewhere —
+ * reporting system or is **historical** information sourced from elsewhere,
  * derived conservatively from RXA-9.1 against HL7 Table NIP001 (Immunization
  * Information Source, CDC v2.5.1 Immunization Messaging IG):
- * - `"administered"` — RXA-9.1 is exactly `"00"` (New immunization record).
- * - `"historical"` — RXA-9.1 is `"01".."08"` (any "Historical information …"
+ * - `"administered"`: RXA-9.1 is exactly `"00"` (New immunization record).
+ * - `"historical"`: RXA-9.1 is `"01".."08"` (any "Historical information …"
  *   source).
  *
  * **Fail-safe:** this is OMITTED (never guessed) when RXA-9 is absent or carries
@@ -3079,7 +3279,7 @@ interface Insurance {
  * always preserved verbatim on `Immunization.informationSource`, so a consumer
  * can inspect the original code even when `recordOrigin` is undefined. The
  * distinction matters because an IIS de-duplicates a *historical* report
- * differently from a dose it believes was *administered* — guessing corrupts
+ * differently from a dose it believes was *administered*: guessing corrupts
  * the registry.
  */
 type ImmunizationRecordOrigin = "administered" | "historical";
@@ -3094,18 +3294,18 @@ type ImmunizationRecordOrigin = "administered" | "historical";
  * a patient or corrupt an IIS (Immunization Information System) registry, so
  * this view is deliberately conservative:
  * - `vaccineCode` carries its own coding-system provenance via the CWE
- *   (`vaccineCode.nameOfCodingSystem` — `CVX` HL7 Table 0292; live IIS feeds
+ *   (`vaccineCode.nameOfCodingSystem`: `CVX` HL7 Table 0292; live IIS feeds
  *   frequently *dual-code* RXA-5 with an alternate CVX/NDC in CWE.4-6, surfaced
  *   as `vaccineCode.alternateIdentifier`/`alternateText`/`nameOfAlternateCodingSystem`).
  *   The helper reports the *claim*; it never validates or looks the code up.
  * - `actionCode` (RXA-21, `A`/`D`/`U`) is surfaced **verbatim** and never
- *   defaulted — mis-keying it corrupts a registry's add/delete/update dedup.
+ *   defaulted: mis-keying it corrupts a registry's add/delete/update dedup.
  * - `doseAmount` is strict-`Number()` parsed; the IIS "unknown dose" sentinel
  *   `999` is surfaced **as the number `999`**, never specially coerced.
  * - `recordOrigin` (administered vs historical) is derived only from the
- *   well-known NIP001 RXA-9.1 codes and OMITTED otherwise — see
+ *   well-known NIP001 RXA-9.1 codes and OMITTED otherwise: see
  *   {@link ImmunizationRecordOrigin}.
- * - Malformed RXA segments never throw — absent fields are omitted keys.
+ * - Malformed RXA segments never throw: absent fields are omitted keys.
  *
  * `routes` and `observations` are ALWAYS present (possibly empty). Deferred (not
  * v1): IIS-specific state profile constraints; CVX/MVX validity checks; the 2nd+
@@ -3140,9 +3340,9 @@ interface Immunization {
     readonly doseUnits?: CWE;
     /**
      * `true` iff RXA-7's coding system (CWE.3) is exactly `UCUM` (HL7 Table 0396)
-     * — i.e. the dose unit is declared UCUM and safe to interpret as computable.
+     *: i.e. the dose unit is declared UCUM and safe to interpret as computable.
      * `false` means a unit IS present but is NOT declared UCUM (surfaced as-is,
-     * never coerced). OMITTED when RXA-7 is absent. A *claim* check only — UCUM
+     * never coerced). OMITTED when RXA-7 is absent. A *claim* check only: UCUM
      * grammar is not validated here.
      */
     readonly doseUnitsAreUcum?: boolean;
@@ -3162,7 +3362,7 @@ interface Immunization {
     readonly refusalReason?: CWE;
     /** RXA-20 completion status (`CP`=complete, `RE`=refused, `NA`=not administered, `PA`=partially administered). */
     readonly completionStatus?: string;
-    /** RXA-21 action code (`A`=add, `D`=delete, `U`=update) — preserved verbatim, NEVER defaulted. */
+    /** RXA-21 action code (`A`=add, `D`=delete, `U`=update): preserved verbatim, NEVER defaulted. */
     readonly actionCode?: string;
     /** RXR children grouped under this RXA (Table 0162 route / Table 0163 site). Always present (possibly empty). */
     readonly routes: readonly MedicationRoute[];
@@ -3170,7 +3370,7 @@ interface Immunization {
     readonly observations: readonly Observation[];
 }
 /**
- * One appointment resource grouped under a `SCH` (Phase Q) — an AIS (service),
+ * One appointment resource grouped under a `SCH` (Phase Q): an AIS (service),
  * AIG (general resource), AIL (location), or AIP (personnel / provider) segment.
  * The resource identifier lives at position 3 of every AI* segment; for the
  * personnel resource (AIP) it is additionally surfaced as a typed `person`
@@ -3186,7 +3386,7 @@ interface AppointmentResource {
     /** Which AI* segment sourced this resource: AIS→service, AIG→general, AIL→location, AIP→personnel. */
     readonly kind: "service" | "general" | "location" | "personnel";
     /**
-     * The AI*-3 resource identifier surfaced as a coded element — `code.identifier`
+     * The AI*-3 resource identifier surfaced as a coded element: `code.identifier`
      * is the resource id (first component, verbatim). AIS-3 / AIG-3 are coded
      * elements, so `code.text` / `code.nameOfCodingSystem` are meaningful there;
      * AIL-3 is a **PL** (location) rather than a coded element, so only
@@ -3194,11 +3394,11 @@ interface AppointmentResource {
      * fields are positional provenance, not a coding system. Provenance-only.
      */
     readonly code?: CWE;
-    /** AIP-3 personnel resource as a typed `XCN` (personnel resources only) — the appointment provider. */
+    /** AIP-3 personnel resource as a typed `XCN` (personnel resources only): the appointment provider. */
     readonly person?: XCN;
 }
 /**
- * SCH-derived appointment entry (Phase Q — SIU scheduling breadth). Surfaces the
+ * SCH-derived appointment entry (Phase Q: SIU scheduling breadth). Surfaces the
  * appointment identifiers, filler status (SCH-25, Table 0278), SCH-11 start/end
  * timing, and the AI* resource groups. NOT a scheduling-workflow state machine.
  *
@@ -3217,19 +3417,19 @@ interface Appointment {
     readonly placerAppointmentId?: string;
     /** SCH-2 filler appointment ID (EI first component, verbatim). */
     readonly fillerAppointmentId?: string;
-    /** SCH-25 filler status code (HL7 Table 0278) — the appointment status, verbatim/provenance-only. */
+    /** SCH-25 filler status code (HL7 Table 0278): the appointment status, verbatim/provenance-only. */
     readonly fillerStatusCode?: CWE;
-    /** Appointment start date/time — SCH-11 TQ.4 (fidelity `TS`, Phase N). */
+    /** Appointment start date/time: SCH-11 TQ.4 (fidelity `TS`, Phase N). */
     readonly startDateTime?: TS;
-    /** Appointment end date/time — SCH-11 TQ.5 (fidelity `TS`, Phase N). */
+    /** Appointment end date/time: SCH-11 TQ.5 (fidelity `TS`, Phase N). */
     readonly endDateTime?: TS;
     /** AIS/AIG/AIL/AIP resources grouped under this SCH. Always present (possibly empty). */
     readonly resources: readonly AppointmentResource[];
 }
 /**
- * TXA-derived clinical-document entry (Phase Q — MDM document breadth). The
+ * TXA-derived clinical-document entry (Phase Q: MDM document breadth). The
  * load-bearing safety property: **completion status (TXA-17) and availability
- * status (TXA-19) are DISTINCT fields and are never conflated** — a document can
+ * status (TXA-19) are DISTINCT fields and are never conflated**: a document can
  * be *available* before it is *authenticated*, and reading a preliminary
  * document as final is the clinical harm. Both are verbatim / provenance-only.
  *
@@ -3238,8 +3438,8 @@ interface Appointment {
  * import type { ClinicalDocument } from "@cosyte/hl7";
  * const doc: ClinicalDocument = {
  *   documentType: "DS",
- *   completionStatus: "IP", // in progress — NOT yet authenticated
- *   availabilityStatus: "AV", // available — a different axis
+ *   completionStatus: "IP", // in progress: NOT yet authenticated
+ *   availabilityStatus: "AV", // available: a different axis
  *   observations: [],
  * };
  * ```
@@ -3248,14 +3448,14 @@ interface ClinicalDocument {
     /** TXA-2 document type (HL7 Table 0270), verbatim. */
     readonly documentType?: string;
     /**
-     * TXA-17 document **completion** status (HL7 Table 0271 — e.g. `DO` documented,
+     * TXA-17 document **completion** status (HL7 Table 0271: e.g. `DO` documented,
      * `IP` in progress, `AU` authenticated, `LA` legally authenticated, `IN`
      * incomplete). Surfaced DISTINCT from {@link availabilityStatus}; verbatim,
      * never validated, never merged.
      */
     readonly completionStatus?: string;
     /**
-     * TXA-19 document **availability** status (HL7 Table 0273 — `AV` available,
+     * TXA-19 document **availability** status (HL7 Table 0273: `AV` available,
      * `CA` cancelled, `OB` obsolete, `UN` unavailable). Surfaced DISTINCT from
      * {@link completionStatus}; verbatim, never validated, never merged.
      */
@@ -3264,14 +3464,14 @@ interface ClinicalDocument {
     readonly activityDateTime?: TS;
     /** TXA-12 unique document number (EI first component, verbatim). */
     readonly uniqueDocumentNumber?: string;
-    /** TXA-13 parent document number (EI first component) — addendum / replacement link. */
+    /** TXA-13 parent document number (EI first component): addendum / replacement link. */
     readonly parentDocumentNumber?: string;
     /** OBX narrative body grouped under this TXA. Always present (possibly empty). */
     readonly observations: readonly Observation[];
 }
 /**
- * FT1-derived charge entry (Phase Q — DFT financial breadth). Billing-critical
- * fields surfaced with **no billing logic and no money-as-float** — the
+ * FT1-derived charge entry (Phase Q: DFT financial breadth). Billing-critical
+ * fields surfaced with **no billing logic and no money-as-float**: the
  * extended/unit amounts are the verbatim CP wire text, never parsed to a number.
  *
  * @example
@@ -3288,29 +3488,29 @@ interface ClinicalDocument {
 interface Charge {
     /** FT1-4 transaction date (fidelity `TS`, Phase N). */
     readonly transactionDate?: TS;
-    /** FT1-6 transaction type (HL7 Table 0017 — `CG` charge, `CD` credit, `PY` payment, `AJ` adjustment). Verbatim. */
+    /** FT1-6 transaction type (HL7 Table 0017: `CG` charge, `CD` credit, `PY` payment, `AJ` adjustment). Verbatim. */
     readonly transactionType?: string;
-    /** FT1-7 transaction code — the institution charge/procedure code (CWE, provenance-only, never validated). */
+    /** FT1-7 transaction code: the institution charge/procedure code (CWE, provenance-only, never validated). */
     readonly transactionCode?: CWE;
     /** FT1-10 transaction quantity (NM; strict-parsed, never `NaN`). */
     readonly quantity?: number;
-    /** FT1-11 transaction amount, extended (CP) — canonical wire text (e.g. `150.00^USD`, byte-exact for a plain amount); never parsed to a number. */
+    /** FT1-11 transaction amount, extended (CP): canonical wire text (e.g. `150.00^USD`, byte-exact for a plain amount); never parsed to a number. */
     readonly amountExtended?: string;
-    /** FT1-12 transaction amount, unit (CP) — canonical wire text; never parsed to a number. */
+    /** FT1-12 transaction amount, unit (CP): canonical wire text; never parsed to a number. */
     readonly amountUnit?: string;
-    /** FT1-19 diagnosis code(s) linked to this charge (CE, repeating) — billing diagnosis linkage. Always present (possibly empty). */
+    /** FT1-19 diagnosis code(s) linked to this charge (CE, repeating): billing diagnosis linkage. Always present (possibly empty). */
     readonly diagnoses: readonly CWE[];
 }
 
 /**
- * Message-type & structure awareness (roadmap Phase G) — a conservative
+ * Message-type & structure awareness (roadmap Phase G): a conservative
  * **misroute / truncation safety net**, NOT an abstract-message-syntax
  * validator.
  *
  * It answers one question per message: **"for this trigger event, are the
  * core segment groups the spec marks Required actually present?"** When an
  * expected group is entirely absent (e.g. an `ORU^R01` carrying no `OBR`/`OBX`
- * result group — the classic signature of a truncated or misrouted feed), the
+ * result group: the classic signature of a truncated or misrouted feed), the
  * parser emits a single additive Tier-2 `MISSING_EXPECTED_GROUP` warning. It
  * never throws, never refuses, never rewrites the message.
  *
@@ -3318,24 +3518,24 @@ interface Charge {
  * false-positives):
  *
  *   - **Per trigger event, never per family.** The claim that an ADT family
- *     shares one shape is false — events diverge by version and trigger. Every
+ *     shares one shape is false: events diverge by version and trigger. Every
  *     definition keys on the (messageCode, triggerEvent) pair.
  *   - **Required (R) anchors only.** A group is modelled only when its anchor
  *     segment is genuinely Required by the v2.5.1 abstract syntax for that
  *     event. Optional groups (e.g. PID in ORU, RXA in VXU, OBR in OML) are
  *     deliberately excluded so a conformant-but-sparse message never warns.
  *   - **Presence is liberal.** A group counts as present if ANY of its anchor
- *     segments appears — the conservative direction (it suppresses a warning
+ *     segments appears: the conservative direction (it suppresses a warning
  *     rather than inventing one).
  *   - **Unrecognized = silent.** A message whose type has no definition here
  *     produces an unrecognized structure summary and zero structural warnings.
  *
- * Spec traceability: HL7 v2.5.1 — Ch. 3 (ADT), Ch. 4 (orders), Ch. 6
- * (financial — DFT), Ch. 7 (observation — ORU), Ch. 9 (MDM), Ch. 10
- * (scheduling — SIU), Ch. 2 (ACK), CDC IG (VXU). Per-entry sourcing lives in
+ * Spec traceability: HL7 v2.5.1: Ch. 3 (ADT), Ch. 4 (orders), Ch. 6
+ * (financial: DFT), Ch. 7 (observation: ORU), Ch. 9 (MDM), Ch. 10
+ * (scheduling: SIU), Ch. 2 (ACK), CDC IG (VXU). Per-entry sourcing lives in
  * `docs-content/spec-notes-structure.md`.
  *
- * Zero runtime deps — pure data + pure functions.
+ * Zero runtime deps: pure data + pure functions.
  */
 /**
  * One expected segment group for a recognized trigger event. The group is
@@ -3397,7 +3597,7 @@ interface StructureGroup {
     readonly present: boolean;
 }
 /**
- * The structure summary for a parsed message — the data behind
+ * The structure summary for a parsed message: the data behind
  * `Hl7Message.structure`. For an unrecognized type, `recognized` is `false`,
  * `expectedGroups` is empty, and `missingGroups` is empty (the safety net is
  * deliberately silent on types it does not model).
@@ -3418,7 +3618,7 @@ interface MessageStructure {
  * Analyze a parsed message's structure against the conservative expected-group
  * registry. Pure: it takes the message code, trigger event, and the set of
  * segment names actually present, and returns a `MessageStructure` summary. It
- * decides nothing about whether to warn — the caller (parser) emits one
+ * decides nothing about whether to warn: the caller (parser) emits one
  * `MISSING_EXPECTED_GROUP` warning per name in `missingGroups`.
  *
  * @param messageCode - MSH-9.1 (e.g. `"ORU"`); empty string if absent.
@@ -3436,7 +3636,7 @@ interface MessageStructure {
 declare function analyzeMessageStructure(messageCode: string, triggerEvent: string, presentSegmentNames: ReadonlySet<string>): MessageStructure;
 
 /**
- * `emitJson` + `SerializedMessage` — snapshot-stable JSON projection of an
+ * `emitJson` + `SerializedMessage`: snapshot-stable JSON projection of an
  * `Hl7Message`. Mirrors `rawSegments` one-for-one; preserves `isNull`;
  * always includes `warnings: []`; omits `profile` when absent.
  *
@@ -3449,15 +3649,15 @@ declare function analyzeMessageStructure(messageCode: string, triggerEvent: stri
  *   warnings + optional profile).
  * - D-18: `Hl7Message.toJSON` delegates here so `JSON.stringify(msg)` Just Works.
  * - D-19: warnings array is ALWAYS present (`warnings: []` when empty).
- * - D-20: `profile` field appears only when `msg.profile` is truthy — then
+ * - D-20: `profile` field appears only when `msg.profile` is truthy: then
  *   contains only `name` + `lineage`.
  * - D-21: `SerializedMessage` is exported from `src/index.ts` (not nested
  *   under HL7 namespace).
  *
  * Note on runtime freeze scope: `emitJson` returns an object that is
- * boundary-frozen (top level only — `Object.isFrozen(msg.toJSON()) === true`).
+ * boundary-frozen (top level only: `Object.isFrozen(msg.toJSON()) === true`).
  * Inner arrays are readonly at the TypeScript type level but MUTABLE at
- * runtime — consumers should treat the returned structure as immutable
+ * runtime: consumers should treat the returned structure as immutable
  * and not mutate nested arrays. Deep-freeze is explicitly rejected per
  * D-30 (emit is hot-path; runtime deep-freeze would add cost with no
  * observable benefit given the type-level readonly contract).
@@ -3469,7 +3669,7 @@ declare function analyzeMessageStructure(messageCode: string, triggerEvent: stri
  *
  * Runtime immutability: the top-level object is `Object.freeze`d
  * (boundary-frozen). Inner arrays are readonly at the TypeScript type
- * level but mutable at runtime — treat as immutable, do not mutate.
+ * level but mutable at runtime: treat as immutable, do not mutate.
  *
  * @example
  * ```ts
@@ -3503,11 +3703,214 @@ interface SerializedMessage {
 }
 
 /**
- * `Hl7Message` — the immutable parsed-message model produced by `parseHL7`.
+ * Typed-composite **encoders** for the `@cosyte/hl7` emit path (roadmap Phase
+ * T): the conservative-emit mirror of the `src/model/types/*` read parsers.
+ *
+ * Each encoder takes one typed composite (an {@link XPN} name, a {@link CX}
+ * identifier, a {@link TS} timestamp, …) and produces a `RawField` whose
+ * positional structure matches exactly what the corresponding `parseXxx`
+ * reads back. The load-bearing guarantees:
+ *
+ * - **No delimiter injection.** Component values are stored **decoded** (the
+ *   same surface `parseXxx` returns), and the serializer (`emit-field.ts`)
+ *   runs every subcomponent through `reescape` (the HL7-R encode-safe codec)
+ *   on the way out. A `familyName` of `"Smith^Jr"` is therefore emitted as
+ *   `Smith\S\Jr` (one component) and re-parses to the exact string `"Smith^Jr"`,
+ *   never forging a component boundary. The caller never hand-assembles
+ *   `^`/`&`/`~`.
+ * - **`emit ∘ parse` identity on the modelled fields.** Interior empty
+ *   components are preserved (so component positions stay aligned) and only
+ *   trailing empties are trimmed (matching the serializer's D-02 strip and the
+ *   parser's omit-on-absent), so `parseXxx(encodeXxx(v)) ` reproduces `v` on
+ *   every modelled field.
+ * - **Never fabricate.** An omitted optional field encodes to an empty /
+ *   absent component: never a defaulted value. An all-empty composite encodes
+ *   to an absent field (`repetitions: []`).
+ *
+ * Zero runtime deps: pure functions over the raw positional tree.
+ */
+
+/**
+ * The 11 typed composite kinds this module can encode. Mirrors the read-side
+ * composite set (`XPN`, `XAD`, `CX`, `CWE`, `CE`, `XTN`, `PL`, `TS`, `NM`,
+ * `HD`, `XCN`).
+ */
+type CompositeKind = "XPN" | "XAD" | "CX" | "CWE" | "CE" | "XTN" | "PL" | "TS" | "NM" | "HD" | "XCN";
+/**
+ * Maps each {@link CompositeKind} to the typed value {@link encodeComposite}
+ * (and `setComposite`) accept for it. `TS` also accepts a pre-formatted HL7
+ * timestamp string; `NM` also accepts a `number` or a raw numeric string,
+ * both are emitted verbatim (the serializer never re-formats a claimed value).
+ */
+interface CompositeValueByKind {
+    readonly XPN: XPN;
+    readonly XAD: XAD;
+    readonly CX: CX;
+    readonly CWE: CWE;
+    readonly CE: CE;
+    readonly XTN: XTN;
+    readonly PL: PL;
+    readonly TS: TS | string;
+    readonly NM: NM | number | string;
+    readonly HD: HD;
+    readonly XCN: XCN;
+}
+/**
+ * Encode an XPN (14 components) to a spec-clean field.
+ *
+ * @example
+ * ```ts
+ * import { encodeXpn } from "@cosyte/hl7";
+ * encodeXpn({ familyName: "Doe", givenName: "Jane", prefix: "Dr" });
+ * ```
+ */
+declare function encodeXpn(v: XPN): RawField;
+/**
+ * Encode an XAD (12 components) to a spec-clean field.
+ *
+ * @example
+ * ```ts
+ * import { encodeXad } from "@cosyte/hl7";
+ * encodeXad({ street: "123 Main St", city: "Boston", stateOrProvince: "MA" });
+ * ```
+ */
+declare function encodeXad(v: XAD): RawField;
+/**
+ * Encode a CX (identifier): component 4 is a nested HD (assigningAuthority).
+ *
+ * @example
+ * ```ts
+ * import { encodeCx } from "@cosyte/hl7";
+ * encodeCx({ idNumber: "MRN001", assigningAuthority: { namespaceId: "HOSP" }, identifierTypeCode: "MR" });
+ * ```
+ */
+declare function encodeCx(v: CX): RawField;
+/**
+ * Encode a CWE (coded element, 9 modelled + preserved `extraComponents`).
+ *
+ * @example
+ * ```ts
+ * import { encodeCwe } from "@cosyte/hl7";
+ * encodeCwe({ identifier: "GLU", text: "Glucose", nameOfCodingSystem: "LN" });
+ * ```
+ */
+declare function encodeCwe(v: CWE): RawField;
+/**
+ * Encode a CE (coded element, 6 modelled + preserved `extraComponents`).
+ *
+ * @example
+ * ```ts
+ * import { encodeCe } from "@cosyte/hl7";
+ * encodeCe({ identifier: "GLU", text: "Glucose", nameOfCodingSystem: "L" });
+ * ```
+ */
+declare function encodeCe(v: CE): RawField;
+/**
+ * Encode an XTN (telecom, 12 components) to a spec-clean field.
+ *
+ * @example
+ * ```ts
+ * import { encodeXtn } from "@cosyte/hl7";
+ * encodeXtn({ telephoneNumber: "555-1234", telecommunicationUseCode: "PRN" });
+ * ```
+ */
+declare function encodeXtn(v: XTN): RawField;
+/**
+ * Encode a PL (person location): component 4 is a nested HD (facility).
+ *
+ * @example
+ * ```ts
+ * import { encodePl } from "@cosyte/hl7";
+ * encodePl({ pointOfCare: "ICU", room: "101", bed: "A" });
+ * ```
+ */
+declare function encodePl(v: PL): RawField;
+/**
+ * Encode an HD (hierarchic designator, 3 components) to a spec-clean field.
+ *
+ * @example
+ * ```ts
+ * import { encodeHd } from "@cosyte/hl7";
+ * encodeHd({ namespaceId: "EPIC", universalId: "1.2.840", universalIdType: "ISO" });
+ * ```
+ */
+declare function encodeHd(v: HD): RawField;
+/**
+ * Encode a TS/DTM timestamp. Accepts either the typed {@link TS} (its `raw`
+ * string is emitted verbatim: the serializer never re-derives a timestamp
+ * from parts) or a pre-formatted HL7 timestamp string.
+ *
+ * @example
+ * ```ts
+ * import { encodeTs } from "@cosyte/hl7";
+ * encodeTs("20260721101500");
+ * ```
+ */
+declare function encodeTs(v: TS | string): RawField;
+/**
+ * Encode an NM numeric. Accepts the typed {@link NM} (its `raw` string emitted
+ * verbatim, preserving the sender's precision/formatting), a `number`, or a raw
+ * string. A `number` is stringified with `String(n)`; the value is never
+ * reconciled or rounded.
+ *
+ * @example
+ * ```ts
+ * import { encodeNm } from "@cosyte/hl7";
+ * encodeNm("120.50"); // precision preserved verbatim
+ * ```
+ */
+declare function encodeNm(v: NM | number | string): RawField;
+/**
+ * Encode an XCN: component 9 is a nested HD (assigningAuthority).
+ *
+ * @example
+ * ```ts
+ * import { encodeXcn } from "@cosyte/hl7";
+ * encodeXcn({ idNumber: "1234567890", familyName: "Welby", identifierTypeCode: "NPI" });
+ * ```
+ */
+declare function encodeXcn(v: XCN): RawField;
+/**
+ * Encode any typed composite into a spec-clean `RawField` by its
+ * {@link CompositeKind}. The single dispatcher `setComposite` and the typed
+ * builders (`buildAdt`/`buildOru`) route through.
+ *
+ * Encoding takes **no** encoding-characters argument on purpose: the field it
+ * produces carries the **decoded** component values, and the actual
+ * delimiter-escaping happens later in the serializer against the message's own
+ * encoding characters: so a composite is delimiter-independent to encode.
+ *
+ * @example
+ * ```ts
+ * import { encodeComposite } from "@cosyte/hl7";
+ * // A hostile family name cannot break framing on emit:
+ * const f = encodeComposite("XPN", { familyName: "Smith^Jr", givenName: "Ann" });
+ * ```
+ */
+declare function encodeComposite<K extends CompositeKind>(kind: K, value: CompositeValueByKind[K]): RawField;
+/**
+ * Encode an array of typed composites into a single repeating `RawField`: one
+ * HL7 repetition (`~`-joined on emit) per array element. Used for repeating
+ * fields such as PID-3 (patient identifier list) and PID-11 (addresses). An
+ * empty array yields an absent field.
+ *
+ * @example
+ * ```ts
+ * import { encodeCompositeReps } from "@cosyte/hl7";
+ * const ids = encodeCompositeReps("CX", [
+ *   { idNumber: "MRN001", identifierTypeCode: "MR" },
+ *   { idNumber: "9990", identifierTypeCode: "SS" },
+ * ]);
+ * ```
+ */
+declare function encodeCompositeReps<K extends CompositeKind>(kind: K, values: readonly CompositeValueByKind[K][]): RawField;
+
+/**
+ * `Hl7Message`: the immutable parsed-message model produced by `parseHL7`.
  * Phase 2 shipped the read-only shell; Phase 3 extends the same class with
  * the read-path traversal methods (`get`, `getAll`, `segments`,
  * `allSegments`) on top of lazy, referentially stable Segment/Field caches
- * (D-11/D-12). The constructor surface is unchanged (Phase 2 D-05 lock) —
+ * (D-11/D-12). The constructor surface is unchanged (Phase 2 D-05 lock),
  * `init.segments` is still the parser-side key, but the public raw-tree
  * field is now exposed as `rawSegments` to free up the name `segments` for
  * the typed `segments(type)` method.
@@ -3521,7 +3924,7 @@ interface SerializedMessage {
  *
  * @remarks
  * With `exactOptionalPropertyTypes: true`, callers cannot pass
- * `{ profile: undefined }` — either omit the key or pass a real profile
+ * `{ profile: undefined }`: either omit the key or pass a real profile
  * descriptor. This matches the `Hl7Message.profile` public field shape
  * (`... | undefined`).
  *
@@ -3547,7 +3950,7 @@ interface Hl7MessageInit {
      */
     readonly customSegments?: Readonly<Record<string, CustomSegmentDefinition>>;
     /**
-     * Merged `dateFormats` list — `options.dateFormats ++ profile.dateFormats`
+     * Merged `dateFormats` list: `options.dateFormats ++ profile.dateFormats`
      * deduped first-occurrence per D-21. Consumed by `msg.meta.timestamp` and
      * any future helper that calls `parseDtmCascade` directly. Absent when
      * neither `options.dateFormats` nor `profile.dateFormats` was supplied.
@@ -3557,7 +3960,7 @@ interface Hl7MessageInit {
 /**
  * Parsed HL7 v2 message. Produced by `parseHL7`. Exposes the raw positional
  * tree (`rawSegments`), delimiter metadata, warnings, and a typed traversal
- * surface — `get(path)` for dot-paths, `getAll(type)` / `segments(type)` /
+ * surface: `get(path)` for dot-paths, `getAll(type)` / `segments(type)` /
  * `allSegments()` for wrapper-level iteration.
  *
  * @remarks
@@ -3582,7 +3985,7 @@ declare class Hl7Message {
     /**
      * Raw positional tree produced by the parser. 1-indexed per HL7 convention
      * (`fields[0]` is the segment-name / MSH separator placeholder slot). Use
-     * `segments(type)` / `allSegments()` for typed wrapper access — this field
+     * `segments(type)` / `allSegments()` for typed wrapper access: this field
      * is exposed for advanced callers that need the raw tree directly (e.g.
      * future serialization phase 5).
      */
@@ -3595,7 +3998,7 @@ declare class Hl7Message {
         readonly lineage: readonly string[];
     } | undefined;
     /**
-     * Merged `dateFormats` list — `options.dateFormats ++ profile.dateFormats`
+     * Merged `dateFormats` list: `options.dateFormats ++ profile.dateFormats`
      * deduped first-occurrence per D-21. Empty array when neither source
      * supplied any formats. Exposed publicly so helpers (`msg.meta.timestamp`)
      * and advanced callers can introspect the active cascade.
@@ -3625,14 +4028,14 @@ declare class Hl7Message {
     private _allSegments;
     /**
      * Lazily built `Meta` view (Phase 4 D-02 memoization). Dropped wholesale
-     * by `invalidateCaches`. `Meta` is always defined (D-03 — MSH absence
+     * by `invalidateCaches`. `Meta` is always defined (D-03: MSH absence
      * throws `NO_MSH_SEGMENT` at parse time) so no null-sentinel is needed.
      * @internal
      */
     private _meta;
     /**
      * Lazily built `MessageStructure` view (Phase G). Dropped wholesale by
-     * `invalidateCaches`. Always defined — `analyzeMessageStructure` returns an
+     * `invalidateCaches`. Always defined: `analyzeMessageStructure` returns an
      * `recognized: false` summary for unmodelled types rather than absence.
      * @internal
      */
@@ -3661,9 +4064,9 @@ declare class Hl7Message {
     constructor(init: Hl7MessageInit);
     /**
      * Resolve a dot-path (e.g. `PID.5.1`, `OBX[2].5`, `PID.3[0].1`) to its
-     * decoded leaf string (unescaped once at parse — never re-unescaped on read,
+     * decoded leaf string (unescaped once at parse: never re-unescaped on read,
      * HL7-VALUE-REDECODE). Returns `undefined` when the path doesn't
-     * resolve — never throws on missing path (MODEL-05). Throws `TypeError`
+     * resolve: never throws on missing path (MODEL-05). Throws `TypeError`
      * on malformed path syntax (e.g. `"pid.5"`, empty string).
      *
      * @example
@@ -3672,14 +4075,14 @@ declare class Hl7Message {
      * msg.get("PID.5.1");  // "Smith"
      * msg.get("OBX[2].5"); // third OBX's 5th field
      * msg.get("NOT.9.9");  // undefined
-     * msg.get("MSH.12");   // "2.5" — HL7 version string
+     * msg.get("MSH.12");   // "2.5": HL7 version string
      * ```
      */
     get(path: string): string | undefined;
     /**
      * Return every `Segment` of `segmentType` in document order. Returns `[]`
      * (empty array, NEVER `undefined`) when no segment of that type exists
-     * (MODEL-02). Alias for `segments(segmentType)` — shares the same cache.
+     * (MODEL-02). Alias for `segments(segmentType)`: shares the same cache.
      *
      * @example
      * ```ts
@@ -3718,7 +4121,7 @@ declare class Hl7Message {
     allSegments(): readonly Segment[];
     /**
      * MSH-derived message metadata (type, controlId, timestamp, version, etc.).
-     * D-01: plain object. D-02: memoized — `msg.meta === msg.meta` across
+     * D-01: plain object. D-02: memoized: `msg.meta === msg.meta` across
      * reads until mutation invalidates. D-03: always defined (MSH absence
      * throws `NO_MSH_SEGMENT` at parse time).
      *
@@ -3732,10 +4135,10 @@ declare class Hl7Message {
     get meta(): Meta;
     /**
      * Structural-conformance summary for the common message types (roadmap
-     * Phase G) — a misroute/truncation safety net, NOT a conformance validator.
+     * Phase G): a misroute/truncation safety net, NOT a conformance validator.
      * Reports, per the message's recognized (MSH-9.1, MSH-9.2) type, which
      * Required segment groups are present and which are entirely absent
-     * (`missingGroups` — the same set the parser flags as
+     * (`missingGroups`: the same set the parser flags as
      * `MISSING_EXPECTED_GROUP` warnings). For an unmodelled type, `recognized`
      * is `false` and `missingGroups` is empty. D-02: memoized.
      *
@@ -3748,14 +4151,14 @@ declare class Hl7Message {
     get structure(): MessageStructure;
     /**
      * PID-derived patient view, or `undefined` when no PID segment exists
-     * (D-04). D-02: memoized. HELPERS-07: never throws — absent fields
+     * (D-04). D-02: memoized. HELPERS-07: never throws: absent fields
      * surface as `undefined` on the returned `Patient` object.
      *
      * @example
      * ```ts
      * console.log(msg.patient?.mrn);
      * console.log(msg.patient?.fullName);
-     * console.log(msg.patient?.dateOfBirth?.raw); // fidelity TS — e.g. "19800115"
+     * console.log(msg.patient?.dateOfBirth?.raw); // fidelity TS: e.g. "19800115"
      * ```
      */
     get patient(): Patient | undefined;
@@ -3773,7 +4176,7 @@ declare class Hl7Message {
     get visit(): Visit | undefined;
     /**
      * Every OBX segment as a typed Observation in document order. D-05:
-     * returns `[]` when no OBX present. D-06: NOT memoized — each call
+     * returns `[]` when no OBX present. D-06: NOT memoized: each call
      * re-walks `rawSegments`. Value type is discriminated per D-13.
      *
      * @example
@@ -3786,7 +4189,7 @@ declare class Hl7Message {
     observations(): readonly Observation[];
     /**
      * Every OBR as an Order with its OBX children grouped positionally (D-12) and
-     * its TQ1 / legacy embedded-TQ (ORC-7) `timings` (Phase M — the repeat pattern
+     * its TQ1 / legacy embedded-TQ (ORC-7) `timings` (Phase M: the repeat pattern
      * surfaced verbatim, never resolved to a schedule). D-05: returns `[]` when no
      * OBR present. D-06: not memoized.
      *
@@ -3794,17 +4197,17 @@ declare class Hl7Message {
      * ```ts
      * for (const order of msg.orders()) {
      *   console.log(order.placerOrderNumber, order.observations.length);
-     *   for (const t of order.timings) console.log(t.repeatPattern?.code); // e.g. "Q6H" — verbatim
+     *   for (const t of order.timings) console.log(t.repeatPattern?.code); // e.g. "Q6H": verbatim
      * }
      * ```
      */
     orders(): readonly Order[];
     /**
-     * Message-level NTE notes (Phase P) — every NTE segment with no recognized
+     * Message-level NTE notes (Phase P): every NTE segment with no recognized
      * preceding parent (not immediately following a `PID`, `ORC`, `OBR`, or
      * `OBX`), surfaced verbatim in document order so nothing is dropped. Notes
      * that DO attach to a specific patient / order / result are exposed on those
-     * helper outputs (`msg.patient?.notes`, `order.notes`, `observation.notes`) —
+     * helper outputs (`msg.patient?.notes`, `order.notes`, `observation.notes`),
      * not here. D-05: returns `[]` when there are none. D-06: NOT memoized.
      *
      * @example
@@ -3815,7 +4218,7 @@ declare class Hl7Message {
     notes(): readonly string[];
     /**
      * Every recognized ADT patient-identity event (merge / move / link /
-     * unlink / person add/update — roadmap Phase K), with the MRG-sourced
+     * unlink / person add/update: roadmap Phase K), with the MRG-sourced
      * `prior` and PID/PV1-sourced `surviving` parties labelled by role and the
      * spec-constant `direction: "MRG_TO_PID"` on merge/move events. Returns
      * `[]` when the trigger event is not in the identity family. D-06: not
@@ -3840,7 +4243,7 @@ declare class Hl7Message {
      * and never reconciled (Phase D §4).
      *
      * Each medication also carries its TQ1 / legacy embedded-TQ (RXE-1) `timings`
-     * (Phase M — repeat pattern verbatim, never resolved to a schedule).
+     * (Phase M: repeat pattern verbatim, never resolved to a schedule).
      *
      * @example
      * ```ts
@@ -3859,7 +4262,7 @@ declare class Hl7Message {
      * returns `[]` when no RXA present. D-06: not memoized. The vaccine code
      * carries its own provenance; the action code (RXA-21) is surfaced verbatim
      * and `recordOrigin` (administered vs historical) is derived only from the
-     * well-known NIP001 RXA-9.1 codes — never guessed.
+     * well-known NIP001 RXA-9.1 codes: never guessed.
      *
      * @example
      * ```ts
@@ -3919,7 +4322,7 @@ declare class Hl7Message {
      * status (Table 0278), SCH-11 start/end timing, and the resource groups
      * (service / general / location / personnel). D-05: returns `[]` when no SCH
      * is present. D-06: not memoized. Never throws (HELPERS-07). Not a
-     * scheduling-workflow state machine — see the package known-limitations.
+     * scheduling-workflow state machine: see the package known-limitations.
      *
      * @example
      * ```ts
@@ -3934,7 +4337,7 @@ declare class Hl7Message {
      * Every TXA of an MDM message as a typed `ClinicalDocument` (roadmap Phase Q),
      * with the OBX narrative body grouped positionally under that TXA. The
      * completion status (TXA-17) and availability status (TXA-19) are surfaced as
-     * **distinct** fields and never conflated — a document can be available before
+     * **distinct** fields and never conflated: a document can be available before
      * it is authenticated, and reading a preliminary document as final is the
      * harm. D-05: returns `[]` when no TXA is present. D-06: not memoized. Never
      * throws (HELPERS-07).
@@ -3952,7 +4355,7 @@ declare class Hl7Message {
      * Every FT1 of a DFT message as a typed `Charge` (roadmap Phase Q), one per
      * FT1 in document order. Surfaces billing-critical fields (FT1-6 transaction
      * type, FT1-7 code, FT1-11/12 extended/unit amount, FT1-19 diagnosis linkage)
-     * with **no billing logic and no money-as-float** — amounts are the verbatim
+     * with **no billing logic and no money-as-float**: amounts are the verbatim
      * CP wire text. D-05: returns `[]` when no FT1 is present. D-06: not memoized.
      * Never throws (HELPERS-07).
      *
@@ -3971,7 +4374,7 @@ declare class Hl7Message {
      * D-05; MSH-1 and MSH-2 are inlined verbatim from
      * `this.encodingCharacters` per D-06; every field string passes through
      * `reescape` per D-04. `RawField.isNull === true` is preserved as the
-     * HL7 literal `""` (D-02). Pure — never warns, never throws (D-07).
+     * HL7 literal `""` (D-02). Pure: never warns, never throws (D-07).
      *
      * @example
      * ```ts
@@ -3987,7 +4390,7 @@ declare class Hl7Message {
      * Re-walks `rawSegments` on every call (D-30 no caching). Mirrors the
      * raw tree one-for-one, preserves `isNull`, always includes
      * `warnings: []`, and includes `profile: { name, lineage }` only when
-     * `this.profile` is truthy (D-19/D-20). Pure — never warns, never throws.
+     * `this.profile` is truthy (D-19/D-20). Pure: never warns, never throws.
      *
      * @example
      * ```ts
@@ -4004,16 +4407,16 @@ declare class Hl7Message {
      * debugging (SER-04). Single opinionated format (D-22 no options):
      * header line with type / controlId / timestamp / segment count, then
      * one line per segment with labeled `[N]=value` fields (D-23). Composite
-     * values render as their raw HL7 string — depth stops at field level
-     * (D-24). Pure — never warns, never throws (D-26).
+     * values render as their raw HL7 string: depth stops at field level
+     * (D-24). Pure: never warns, never throws (D-26).
      *
      * **Field values render as their raw HL7 string representation.**
-     * Embedded delimiters in user data appear as escape sequences — e.g.
+     * Embedded delimiters in user data appear as escape sequences: e.g.
      * a patient family name containing `|` renders as `Smith\F\Jones`
      * (NOT `Smith|Jones`). This preserves round-trip fidelity: copy-pasting
      * prettyPrint output into `parseHL7` yields a structurally equivalent
      * message. For un-escaped human display, parse the composite first via
-     * typed accessors (e.g. `msg.patient?.familyName`) — those return
+     * typed accessors (e.g. `msg.patient?.familyName`): those return
      * already-decoded strings.
      *
      * @example
@@ -4031,13 +4434,13 @@ declare class Hl7Message {
      * Set the string value at a dot-path. Mutates the underlying tree and
      * returns `this` for chaining (D-15). Auto-creates missing repetitions,
      * components, and subcomponents WITHIN an existing field, but does NOT
-     * auto-create segments — callers must `addSegment` first (throws
+     * auto-create segments: callers must `addSegment` first (throws
      * `TypeError` with an actionable message otherwise).
      *
      * The value is accepted verbatim: unescaped delimiter characters are NOT
      * rejected on input (D-18). Re-escaping on serialize is Phase 5's concern.
      *
-     * MSH-1 / MSH-2 follow the user-facing HL7 convention — `setField("MSH.3", ...)`
+     * MSH-1 / MSH-2 follow the user-facing HL7 convention: `setField("MSH.3", ...)`
      * targets MSH-3 (sending application), matching `msg.get("MSH.3")`.
      *
      * Segment/Field wrapper caches are invalidated wholesale on success (D-17).
@@ -4051,9 +4454,41 @@ declare class Hl7Message {
      * ```
      */
     setField(path: string, value: string): this;
+    /**
+     * Set a **typed composite** at a field (or field-repetition) dot-path,
+     * roadmap Phase T, the conservative-emit mirror of the typed read accessors
+     * (`asXpn`/`asCx`/…). The caller passes a structured value (an XPN name, a CX
+     * identifier, a TS timestamp, …) by its {@link CompositeKind}, and the setter
+     * encodes it into a spec-clean field using the HL7-R encode-safe path: any
+     * delimiter embedded in a component value is **escaped, never injected**, so
+     * a `familyName` of `"Smith^Jr"` re-parses to exactly that string rather than
+     * forging a component boundary. No hand-assembly of `^`/`&`/`~`.
+     *
+     * The path must resolve to a **field** (`"PID.5"`) or a specific
+     * **repetition** of a field (`"PID.11[1]"`). A component/subcomponent-level
+     * path (`"PID.5.1"`) is rejected with `TypeError`: a composite occupies a
+     * whole field, not a single component. Like {@link setField}, the target
+     * segment must already exist (`addSegment` first); the repetition defaults to
+     * index 0 and other repetitions of the field are preserved.
+     *
+     * Never fabricates: an omitted optional composite field encodes to an
+     * empty/absent component, never a defaulted value; an all-empty composite
+     * clears the field. Segment/helper caches are invalidated on success; the
+     * frozen `warnings` array is untouched.
+     *
+     * @example
+     * ```ts
+     * const msg = buildMessage({ type: "ADT^A01" }).addSegment("PID", [""]);
+     * msg.setComposite("PID.5", "XPN", { familyName: "Smith", givenName: "Ann" });
+     * msg.setComposite("PID.3", "CX", { idNumber: "MRN001", identifierTypeCode: "MR" });
+     * msg.setComposite("PID.7", "TS", "19880705");
+     * msg.get("PID.5.1"); // "Smith"
+     * ```
+     */
+    setComposite<K extends CompositeKind>(path: string, kind: K, value: CompositeValueByKind[K]): this;
     /**
      * Append a new segment to the end of the message. `name` must match
-     * `/^(?:[A-Z]{3}|Z[A-Z0-9]{2})$/u` — throws `TypeError` otherwise (D-19).
+     * `/^(?:[A-Z]{3}|Z[A-Z0-9]{2})$/u`: throws `TypeError` otherwise (D-19).
      *
      * `fields` is interpreted in HL7 1-indexed terms: `addSegment("NTE", [a, b, c])`
      * produces a segment whose `NTE-1 = a`, `NTE-2 = b`, `NTE-3 = c`. The
@@ -4076,14 +4511,14 @@ declare class Hl7Message {
     /**
      * Remove segments by type + occurrence or by type + all. Call shapes:
      *
-     * - `removeSegment("NTE")` — remove the FIRST NTE (occurrence 0).
-     * - `removeSegment("OBX", 1)` — remove the SECOND OBX (0-indexed per D-01).
-     * - `removeSegment("OBX", { all: true })` — remove ALL OBX segments.
+     * - `removeSegment("NTE")`: remove the FIRST NTE (occurrence 0).
+     * - `removeSegment("OBX", 1)`: remove the SECOND OBX (0-indexed per D-01).
+     * - `removeSegment("OBX", { all: true })`: remove ALL OBX segments.
      *
-     * `MSH` is protected — `removeSegment("MSH")` throws `TypeError` (every
+     * `MSH` is protected: `removeSegment("MSH")` throws `TypeError` (every
      * HL7 message must retain its MSH segment). Unknown segment types are a
      * no-op (idempotent; no throw). Segment name must match the D-19 shape
-     * regex — invalid shapes throw `TypeError` for symmetry with `addSegment`.
+     * regex: invalid shapes throw `TypeError` for symmetry with `addSegment`.
      *
      * Invalidates caches on return; warnings untouched (D-16).
      *
@@ -4108,7 +4543,7 @@ declare class Hl7Message {
 }
 
 /**
- * Public entry point for the `@cosyte/hl7` parser — composes every
+ * Public entry point for the `@cosyte/hl7` parser: composes every
  * parser stage built across Plans 01–05 (normalize, strip MLLP, split
  * segments, read delimiters, tokenize) and routes every Tier-2 warning
  * through a single `emitWarning` chokepoint. The four Tier-3 fatal codes
@@ -4160,7 +4595,7 @@ declare function parseHL7(raw: string | Buffer, options: ParseOptions): Hl7Messa
  * thrown directly; consumers narrow via the `code` discriminant.
  *
  * `ProfileDefinitionError` is declared here so the error taxonomy is locked
- * before Phase 6 wires profile validation — keeping file ownership clean
+ * before Phase 6 wires profile validation: keeping file ownership clean
  * across phases.
  */
 
@@ -4218,7 +4653,7 @@ type FatalCode = (typeof FATAL_CODES)[keyof typeof FATAL_CODES];
  * snippet of the offending input so consumers can log actionable errors.
  *
  * @remarks
- * Snippets may contain PHI when parsing real clinical messages — redact at
+ * Snippets may contain PHI when parsing real clinical messages: redact at
  * the call site if required by your compliance posture. The library does
  * not redact snippets itself.
  *
@@ -4229,7 +4664,7 @@ type FatalCode = (typeof FATAL_CODES)[keyof typeof FATAL_CODES];
  *   parseHL7("");
  * } catch (err) {
  *   if (err instanceof Hl7ParseError && err.code === "EMPTY_INPUT") {
- *     // handle empty input — err.position, err.snippet available
+ *     // handle empty input: err.position, err.snippet available
  *   }
  * }
  * ```
@@ -4248,7 +4683,7 @@ declare class Hl7ParseError extends Error {
 }
 /**
  * Thrown by `defineProfile()` and profile-validation code (Phase 6) when a
- * profile definition is structurally invalid — e.g. references an undefined
+ * profile definition is structurally invalid: e.g. references an undefined
  * parent, declares a malformed custom segment, or includes an unsupported
  * date format. Declared in Phase 2 so the error taxonomy is locked before
  * Phase 6 lands; callers may optionally supply the offending profile name
@@ -4279,13 +4714,13 @@ declare class ProfileDefinitionError extends Error {
  * HL7 v2 **Table 0211 (Alternate Character Sets)** resolution for the parser's
  * `Buffer`-decode stage (Phase O). Mirrors the frozen read-only registries
  * `KNOWN_SEGMENTS` / `KNOWN_CODING_SYSTEMS`: a single source of truth mapping an
- * MSH-18 character-set code to how the parser treats it — **decode** (single-byte
+ * MSH-18 character-set code to how the parser treats it: **decode** (single-byte
  * ISO-8859 family + Unicode UTF-8) or **preserve-verbatim** (the multibyte /
  * ISO-2022-switched East-Asian sets and UTF-16/32, which HL7 renders through
  * stateful `\Mxxyyzz\` escapes this phase deliberately does not fully decode).
  *
  * Spec traceability: HL7 v2 Chapter 2, **MSH-18** (item 00692) + **Table 0211**
- * (OID 2.16.840.1.113883.18.116). MSH-18 is **repeating** — the first occurrence
+ * (OID 2.16.840.1.113883.18.116). MSH-18 is **repeating**: the first occurrence
  * is the message's default encoding, later occurrences are alternates activated
  * mid-message by the §2.7.4 charset-switch escapes (`\Cxxyy\` single-byte,
  * `\Mxxyyzz\` multi-byte). A **blank** MSH-18 means 7-bit ASCII (the default).
@@ -4299,18 +4734,18 @@ declare class ProfileDefinitionError extends Error {
  * be re-decoded downstream via `Buffer.from(value, "latin1")`. For a **multibyte**
  * set (UTF-16/32, the East-Asian DBCS/ISO-2022 sets) a content byte can coincide
  * with a structural byte, so tokenization runs on raw bytes and framing is
- * best-effort, not byte-recoverable — which is exactly why decoding those sets is
+ * best-effort, not byte-recoverable: which is exactly why decoding those sets is
  * deferred (see the parser's known-limitations). Because a recognized-but-undecoded
  * set and an unrecognized label both preserve bytes, the exact Table-0211 spelling
- * of the multibyte codes is not load-bearing for safety — only for which warning
+ * of the multibyte codes is not load-bearing for safety: only for which warning
  * (`UNSUPPORTED_CHARSET` vs `UNKNOWN_CHARSET`) fires.
  */
 /**
  * How the parser treats a resolved MSH-18 character set.
  *
- * - `decode` — decode the byte stream to text with {@link CharsetResolution.decoder}.
- * - `verbatim` — read the raw bytes as a 1:1 `latin1` mapping; do not decode
- *   (byte-recoverable for single-byte content — see the module header).
+ * - `decode`: decode the byte stream to text with {@link CharsetResolution.decoder}.
+ * - `verbatim`: read the raw bytes as a 1:1 `latin1` mapping; do not decode
+ *   (byte-recoverable for single-byte content: see the module header).
  */
 type CharsetTreatment = "decode" | "verbatim";
 /**
@@ -4372,7 +4807,7 @@ declare function canonicalCharset(raw: string): string;
 
 /**
  * HL7 escape-sequence handling for the `@cosyte/hl7` parser pipeline
- * — expands reserved-delimiter escapes on parse (`unescape`) and re-escapes
+ *: expands reserved-delimiter escapes on parse (`unescape`) and re-escapes
  * them back when emitting spec-clean HL7 on serialize (`reescape`).
  *
  * The HL7 v2 spec reserves the delimiter characters (field, component,
@@ -4385,7 +4820,7 @@ declare function canonicalCharset(raw: string): string;
  * sequences. We **decode** sequences whose meaning is byte-exact (delimiter
  * back-substitution, hex, newline, truncation char). We **recognize and
  * preserve verbatim** sequences whose intent is presentational or sender-
- * specific — decoding them would either lose information (formatting/charset)
+ * specific: decoding them would either lose information (formatting/charset)
  * or invent a rendering policy the spec leaves to the consumer. Either way,
  * a recognized standard sequence never emits `UNKNOWN_ESCAPE_SEQUENCE`;
  * that warning is reserved for genuinely-unknown bodies (`\Z..\`, garbage).
@@ -4405,7 +4840,7 @@ declare function canonicalCharset(raw: string): string;
  *   \.sp\, \.in\, \.ti\, \.fi\,       formatting commands (§2.7.6, kept as
  *   \.nf\, \.ce\                       semantic sentinels for a renderer)
  *   \Cxxyy\, \Mxxyyzz\                single- / multi-byte charset switch
- *                                       (§2.7.4 — sender-local byte sequences;
+ *                                       (§2.7.4: sender-local byte sequences;
  *                                       decoding requires charset context
  *                                       this module does not have)
  *
@@ -4424,7 +4859,7 @@ declare function canonicalCharset(raw: string): string;
  * Unknown or malformed sequences are preserved VERBATIM in the output and
  * emit an `UNKNOWN_ESCAPE_SEQUENCE` warning via `emit`. Unterminated escapes
  * (an escape character with no closing partner before end-of-input) are also
- * preserved in full and warn once — the scan is strictly O(n) and cannot
+ * preserved in full and warn once: the scan is strictly O(n) and cannot
  * infinite-loop on malformed input.
  *
  * @example
@@ -4458,10 +4893,10 @@ declare function unescape(input: string, enc: EncodingCharacters, emit: (w: Hl7P
  *   "\n" (LF)         → \.br\
  *   "\r" (CR)         → \X0D\  (a decoded CR is the HL7 segment separator;
  *                               emitting it raw would corrupt wire framing, so
- *                               it re-encodes to its hex escape — see below)
+ *                               it re-encodes to its hex escape: see below)
  *
  * **Lossy by construction for the non-delimiter escape families.** `reescape`
- * only knows about the reserved characters above — it cannot reconstruct a
+ * only knows about the reserved characters above: it cannot reconstruct a
  * recognize-and-preserve escape (`\H\`, formatting, charset, `\Z..\`) or the
  * original bytes of a hex escape (`\X41\` decoded to `A`; casing of `\X0d\`),
  * because those decode to ordinary characters that carry no "I was an escape"
@@ -4483,17 +4918,120 @@ declare function unescape(input: string, enc: EncodingCharacters, emit: (w: Hl7P
  */
 declare function reescape(input: string, enc: EncodingCharacters): string;
 
+/**
+ * First-class HL7 v2 text codec for `@cosyte/hl7`: the ergonomic
+ * decode / encode pair that sits on top of the parser-internal
+ * `unescape` / `reescape` primitives.
+ *
+ * - {@link decodeText} turns a field's escape-bearing wire text into its
+ *   decoded value (delimiter + hex + `\.br\` escapes resolved; presentational
+ *   escapes preserved verbatim), with no warning plumbing to wire up.
+ * - {@link encodeText} is the **encode-safe** direction: an arbitrary string in,
+ *   a spec-clean field body out that can **never inject a delimiter or forge a
+ *   component boundary**. This is the primitive Phase T (typed emit) builds on.
+ *
+ * For a human-readable rendering (formatting commands → whitespace, highlight
+ * dropped), use {@link renderText} instead of {@link decodeText}.
+ */
+
+/**
+ * Decode a field's escape-bearing HL7 text to its human value: the five
+ * delimiter escapes (`\F\ \S\ \T\ \R\ \E\`), the truncation escape (`\P\`),
+ * `\.br\` (→ newline), and hex (`\Xdddd…\`) are resolved; presentational
+ * escapes (`\H\`/`\N\`, formatting, charset, vendor `\Z..\`) are **preserved
+ * verbatim** so nothing is lost. Never throws.
+ *
+ * This is the one-call inverse of {@link encodeText} for delimiter-bearing
+ * content. It does **not** interpret formatting/highlight: for a normalized
+ * display string use {@link renderText}.
+ *
+ * @param input - the field's escape-bearing text.
+ * @param enc - encoding characters; defaults to the HL7 standard `|^~\&`.
+ * @returns the decoded value string.
+ *
+ * @example
+ * ```ts
+ * import { decodeText } from "@cosyte/hl7";
+ * decodeText("Doe\\S\\John");   // "Doe^John": \S\ → component separator
+ * decodeText("line1\\.br\\line2"); // "line1\nline2"
+ * ```
+ */
+declare function decodeText(input: string, enc?: EncodingCharacters): string;
+/**
+ * **Encode-safe** direction: escape an arbitrary string so it can be placed in
+ * an HL7 field as data without ever breaking framing. Every reserved character
+ *: the escape char (escaped **first**, so decoding is unambiguous), the field,
+ * component, subcomponent, and repetition separators, the declared truncation
+ * char, and the framing-critical `\n`/`\r`: is replaced by its escape
+ * sequence, so the value **cannot inject a delimiter or forge a component /
+ * subcomponent / repetition boundary**.
+ *
+ * The hard invariant, property-tested over arbitrary strings:
+ * `decodeText(encodeText(s, enc), enc) === s`, and a message field carrying
+ * `encodeText(s)` **cannot forge a component / subcomponent / repetition
+ * boundary or break framing**: the value never escapes its field.
+ *
+ * Two caveats are inherent to HL7 field encoding, not to this codec, and apply
+ * to *whole-field* re-parse (they do not weaken the no-injection guarantee):
+ * the two-character string `""` is HL7's explicit-null token, so a field whose
+ * entire value is `""` re-parses as null; and the default parser trims field
+ * whitespace, so a value with leading/trailing spaces re-parses trimmed. Encode
+ * such values into a component/subcomponent position, or parse with trimming
+ * off, to preserve them exactly.
+ *
+ * @param input - the arbitrary string to encode.
+ * @param enc - encoding characters; defaults to the HL7 standard `|^~\&`.
+ * @returns the spec-clean, delimiter-safe field body.
+ *
+ * @example
+ * ```ts
+ * import { encodeText, parseHL7 } from "@cosyte/hl7";
+ * // A value full of delimiters cannot break out of its field:
+ * const hostile = "a|b^c~d\\e&f";
+ * const body = encodeText(hostile); // "a\\F\\b\\S\\c\\R\\d\\E\\e\\T\\f"
+ * const msg = parseHL7(`MSH|^~\\&|A|B|C|D|20260101||ADT^A01|1|P|2.5\rNTE|1||${body}`);
+ * msg.segments("NTE")[0]?.field(3).value === hostile; // true: round-trips exactly
+ * ```
+ */
+declare function encodeText(input: string, enc?: EncodingCharacters): string;
+
+/**
+ * The `@cosyte/hl7` **text codec**: a first-class, documented namespace for
+ * getting the human string out of a field and safely encoding an arbitrary
+ * string in.
+ *
+ * Exposed on the package as the `text` namespace object so a consumer can, in
+ * one call:
+ *
+ * - `text.decode(field.text)`: resolve delimiter/hex/`\.br\` escapes to a value;
+ * - `text.render(field.text)`: normalize formatting + highlight to a display model;
+ * - `text.encode(anyString)`: encode-safe: no delimiter injection (Phase T's primitive).
+ *
+ * ```ts
+ * import { text } from "@cosyte/hl7";
+ * text.render("Result \\H\\HIGH\\N\\\\.br\\see note").text; // "Result HIGH\nsee note"
+ * text.encode("a|b^c").length > 0;                          // delimiter-safe
+ * ```
+ *
+ * The same functions are also available as top-level named exports
+ * (`decodeText`, `encodeText`, `renderText`) for tree-shaking-friendly imports.
+ */
+
+declare namespace index$1 {
+  export { decodeText as decode, encodeText as encode, renderText as render };
+}
+
 /**
  * Dot-path tokenizer and resolver for the `@cosyte/hl7` structural
  * model. Parses strings like `PID.5.1`, `OBX[2].5`, `PID.3[0].1` into a
  * discriminated-token descriptor, then resolves that descriptor against a
  * `readonly RawSegment[]` tree to produce the decoded leaf string (or
- * `undefined` on missing path). Zero runtime deps — a hand-rolled linear scan
+ * `undefined` on missing path). Zero runtime deps: a hand-rolled linear scan
  * (analog: `src/parser/dates.ts::matchTokenFormat`).
  *
  * Indexing conventions (locked in Phase 3 CONTEXT.md):
- * - `[N]` is ALWAYS 0-indexed — applies to segment repeats AND field repeats (D-01).
- * - Dot-numbers are ALWAYS 1-indexed — matches HL7 spec and Phase 2's 1-indexed
+ * - `[N]` is ALWAYS 0-indexed: applies to segment repeats AND field repeats (D-01).
+ * - Dot-numbers are ALWAYS 1-indexed: matches HL7 spec and Phase 2's 1-indexed
  *   `RawSegment.fields` (D-02). `PID.5` → `fields[5]`.
  * - MSH.1 / MSH.2 are the separator char and encoding-chars string, both
  *   stored at `fields[0]` / `fields[1]` by Phase 2 tokenize.ts (D-05).
@@ -4553,7 +5091,7 @@ declare function parsePath(path: string): DotPath;
  * leaf value. Returns `undefined` whenever the path does not resolve (missing
  * segment, out-of-range field/component/subcomponent/repetition), and never
  * throws on a missing value. Throws `TypeError` only when `path` itself is
- * malformed — callers relying on "never throws" should pre-validate or wrap
+ * malformed: callers relying on "never throws" should pre-validate or wrap
  * in try/catch.
  *
  * @example
@@ -4567,14 +5105,14 @@ declare function parsePath(path: string): DotPath;
 declare function resolvePath(path: string, segments: readonly RawSegment[], _enc: EncodingCharacters): string | undefined;
 
 /**
- * `HL7` namespace — type-only re-exports of the 10 composite interfaces
+ * `HL7` namespace: type-only re-exports of the 10 composite interfaces
  * (XPN, XAD, CX, CWE, CE, XTN, PL, TS, NM, HD). Consumed via
  * `export * as HL7 from "./model/types/namespace.js";` in the top-level barrel
  * (`src/index.ts`). Named exports of the same interfaces live in the public
  * barrel alongside this namespace for developers who prefer the direct
  * `import type { XPN } ...` style (D-13).
  *
- * The namespace is TYPES-ONLY — parser functions (`parseXpn`, `parseXad`, ...)
+ * The namespace is TYPES-ONLY: parser functions (`parseXpn`, `parseXad`, ...)
  * are exported as value exports from the main barrel, not under `HL7`.
  */
 
@@ -4595,7 +5133,7 @@ declare namespace namespace {
 }
 
 /**
- * `pickMrn` — pick the Medical Record Number string from a PID-3 identifier
+ * `pickMrn`: pick the Medical Record Number string from a PID-3 identifier
  * list. Isolated from `patient.ts` so Phase 6 profile hooks can substitute
  * a profile-aware variant without patching the helper that calls it.
  *
@@ -4606,12 +5144,12 @@ declare namespace namespace {
  * Pick the Medical Record Number string from a list of PID-3 CX identifiers.
  *
  * D-07: prefer the first CX whose `identifierTypeCode === "MR"` (HL7 v2.5+
- * canonical MRN marker). D-10: the match is case-SENSITIVE — lowercase
+ * canonical MRN marker). D-10: the match is case-SENSITIVE: lowercase
  * `"mr"` does NOT match; spec mandates uppercase.
  *
  * D-08: when no MR-typed identifier is found, fall back to the first CX's
  * `idNumber`. Returns `undefined` when the first CX has no `idNumber` (even
- * if later CXs do — the fallback is strictly "first CX", not "first CX with
+ * if later CXs do: the fallback is strictly "first CX", not "first CX with
  * idNumber", because we need a deterministic answer).
  *
  * D-21: no warning emitted. Callers who need strict MR resolution can walk
@@ -4627,7 +5165,7 @@ declare namespace namespace {
  * // → "MRN001"
  *
  * pickMrn([{ idNumber: "X1" }]);
- * // → "X1"  (fallback — no MR entry)
+ * // → "X1"  (fallback: no MR entry)
  *
  * pickMrn([]);
  * // → undefined
@@ -4636,7 +5174,7 @@ declare namespace namespace {
 declare function pickMrn(identifiers: readonly CX[]): string | undefined;
 
 /**
- * `buildMessage` — top-level outbound factory for the `@cosyte/hl7`
+ * `buildMessage`: top-level outbound factory for the `@cosyte/hl7`
  * package. Synthesizes a complete MSH `RawSegment` from `BuildMessageInit`
  * and returns a real `Hl7Message` (not a builder subtype). Callers chain
  * `.addSegment(...)` (Phase 3 mutation method, unchanged) to append PID,
@@ -4651,7 +5189,7 @@ declare function pickMrn(identifiers: readonly CX[]): string | undefined;
  * - D-10: `BuildMessageInit` shape below.
  * - D-11: internally synthesises a complete MSH `RawSegment` and hands to
  *   `new Hl7Message({...})`.
- * - D-12: controlId auto-gen — YYYYMMDDHHmmssSSS + 6 alnum = 23 chars.
+ * - D-12: controlId auto-gen: YYYYMMDDHHmmssSSS + 6 alnum = 23 chars.
  * - D-13: `timestamp` accepts `Date | string`; `Date` formats to
  *   `YYYYMMDDHHmmss` UTC.
  * - D-14: encoding chars always `DEFAULT_ENCODING_CHARACTERS`.
@@ -4661,9 +5199,9 @@ declare function pickMrn(identifiers: readonly CX[]): string | undefined;
  *
  * **Absent vs. explicit null at the wire level:** at the HL7 wire level,
  * an empty-string field and an omitted field produce IDENTICAL output
- * (both emit as absent — `||` in the line). If you need to distinguish
+ * (both emit as absent: `||` in the line). If you need to distinguish
  * "explicitly null" (HL7 `""`) from "absent" in an outbound message, use
- * `buildMessage({...}).setField(path, '""')` after construction — the
+ * `buildMessage({...}).setField(path, '""')` after construction: the
  * Phase 3 `setField` mutation method sets `RawField.isNull = true`, which
  * the emitter preserves as the literal two-char string `""` per D-02.
  */
@@ -4678,7 +5216,7 @@ declare function pickMrn(identifiers: readonly CX[]): string | undefined;
  * empty string produce IDENTICAL wire output (both emit as an absent
  * positional field). To emit an HL7 explicit null (`""`) at a specific
  * position in an outbound message, build the message first and then call
- * `.setField(path, '""')` — the Phase 3 mutation method sets `isNull=true`
+ * `.setField(path, '""')`: the Phase 3 mutation method sets `isNull=true`
  * on the underlying `RawField`, and the emitter preserves that as the
  * literal two-char output per D-02.
  *
@@ -4707,7 +5245,7 @@ interface BuildMessageInit {
      *
      * The string is split on `^` into MSH-9 components; each component is
      * emitted verbatim. Literal `^` characters in a component are NOT
-     * representable via this field — splitting is unconditional. Callers
+     * representable via this field: splitting is unconditional. Callers
      * needing that edge case should build the message and then use
      * `.setField("MSH.9.1", ...)` etc. after construction.
      *
@@ -4752,7 +5290,7 @@ interface BuildMessageInit {
  *
  * **Empty string vs. omitted field (W1):** at the HL7 wire level, passing
  * `sendingApp: ""` and omitting `sendingApp` produce IDENTICAL output
- * (both emit as absent — `||` at the MSH-3 position). If you need to
+ * (both emit as absent: `||` at the MSH-3 position). If you need to
  * emit an HL7 explicit null (`""`, the two-char literal) at a specific
  * position, build the message first, then use `setField`:
  *
@@ -4784,23 +5322,273 @@ interface BuildMessageInit {
  */
 declare function buildMessage(init: BuildMessageInit): Hl7Message;
 
+/**
+ * Shared field/segment assembly primitives for the typed builders
+ * (`buildAdt`/`buildOru`: roadmap Phase T). Centralises the MSH synthesis and
+ * the sparse positional-segment assembly so each builder stays declarative and
+ * every builder emits an identical, spec-clean MSH.
+ *
+ * Zero runtime deps: pure functions over the raw positional tree.
+ */
+
+/**
+ * The MSH envelope shared by every typed builder: the addressing + control
+ * metadata that is independent of the message body. Mirrors `BuildMessageInit`
+ * minus `type` (each builder derives MSH-9 from its own trigger).
+ */
+interface MessageEnvelope {
+    readonly sendingApp?: string;
+    readonly sendingFacility?: string;
+    readonly receivingApp?: string;
+    readonly receivingFacility?: string;
+    /** Auto-generated via `generateControlId()` when omitted. */
+    readonly controlId?: string;
+    /**
+     * `Date` → HL7 `YYYYMMDDHHmmss` (UTC, seconds); a pre-formatted HL7 TS string
+     * passes through verbatim. Defaults to `new Date()`.
+     */
+    readonly timestamp?: Date | string;
+    /** Defaults to `"2.5"`. */
+    readonly version?: string;
+    /** Defaults to `"P"` (production). */
+    readonly processingId?: string;
+}
+
+/**
+ * `buildAdt`: author a spec-clean HL7 v2 **ADT** (admit/discharge/transfer)
+ * message from typed inputs (roadmap Phase T). The conservative-emit mirror of
+ * the read helpers (`msg.patient`, `msg.visit`): a caller supplies structured
+ * values (an {@link XPN} name, {@link CX} identifiers, a {@link TS} birth date,
+ * a {@link PL} location, …) and `buildAdt` assembles `MSH + EVN + PID + PV1`
+ * with correct `^`/`&`/`~` structure via the HL7-R encode-safe path: never
+ * hand-assembling delimiters, never injecting one.
+ *
+ * **Structurally complete + zero-warning.** The emitted message carries the
+ * segment groups the parser's own structure net marks Required for the ADT
+ * events it recognises (patient = PID, visit = PV1), so it re-parses with
+ * **zero warnings** and `msg.structure.missingGroups` empty.
+ *
+ * **Never fabricate.** Only values the caller supplies are emitted; an omitted
+ * optional field becomes an empty/absent field, never a defaulted clinical
+ * value. `patient` is **required**: an ADT patient event with no patient is a
+ * typed `TypeError`, not a guessed PID.
+ *
+ * Spec traceability: HL7 v2 Ch. 3 (ADT: MSH/EVN/PID/PV1), Ch. 2 datatypes.
+ * Zero runtime deps.
+ */
+
+/** Typed PID (patient identification) content for {@link buildAdt}. */
+interface AdtPatient {
+    /** PID-1 Set ID. */
+    readonly setId?: string;
+    /** PID-3 Patient Identifier List: one or more CX identifiers (MRN, SSN, …). */
+    readonly identifiers?: CX | readonly CX[];
+    /** PID-5 Patient Name. */
+    readonly name?: XPN | readonly XPN[];
+    /** PID-6 Mother's Maiden Name. */
+    readonly mothersMaidenName?: XPN;
+    /** PID-7 Date/Time of Birth. */
+    readonly birthDateTime?: TS | string;
+    /** PID-8 Administrative Sex (e.g. `"F"`, `"M"`, `"U"`). */
+    readonly administrativeSex?: string;
+    /** PID-11 Patient Address: one or more XAD addresses. */
+    readonly address?: XAD | readonly XAD[];
+    /** PID-13 Phone Number - Home: one or more XTN telecoms. */
+    readonly phoneHome?: XTN | readonly XTN[];
+    /** PID-18 Patient Account Number. */
+    readonly accountNumber?: CX;
+}
+/** Typed PV1 (patient visit) content for {@link buildAdt}. */
+interface AdtVisit {
+    /** PV1-1 Set ID. */
+    readonly setId?: string;
+    /** PV1-2 Patient Class (e.g. `"I"` inpatient, `"O"` outpatient, `"E"` emergency). */
+    readonly patientClass?: string;
+    /** PV1-3 Assigned Patient Location. */
+    readonly assignedLocation?: PL;
+    /** PV1-7 Attending Doctor. */
+    readonly attendingDoctor?: XCN | readonly XCN[];
+    /** PV1-8 Referring Doctor. */
+    readonly referringDoctor?: XCN | readonly XCN[];
+    /** PV1-19 Visit Number. */
+    readonly visitNumber?: CX;
+    /** PV1-44 Admit Date/Time. */
+    readonly admitDateTime?: TS | string;
+}
+/** Typed EVN (event type) content for {@link buildAdt}. */
+interface AdtEvent {
+    /** EVN-2 Recorded Date/Time. */
+    readonly recordedDateTime?: TS | string;
+    /** EVN-6 Event Occurred. */
+    readonly eventOccurred?: TS | string;
+}
+/** Input for {@link buildAdt}: the MSH envelope plus the typed segment bodies. */
+interface BuildAdtInit extends MessageEnvelope {
+    /** PID content. **Required**: never fabricated. */
+    readonly patient: AdtPatient;
+    /** PV1 content. Optional; an (empty) PV1 is emitted regardless so the visit group is present. */
+    readonly visit?: AdtVisit;
+    /** EVN content (EVN-1 is the trigger event; EVN-2/6 optional). */
+    readonly event?: AdtEvent;
+}
+/**
+ * Build a spec-clean ADT message for `event` (the MSH-9.2 trigger, e.g.
+ * `"A01"`, `"A04"`, `"A08"`) from typed inputs.
+ *
+ * The result is a real {@link Hl7Message}: `msg.toString()` serialises it,
+ * `parseHL7(msg.toString())` round-trips with zero warnings, and
+ * `msg.patient` / `msg.visit` read back the values supplied.
+ *
+ * @param event - the ADT trigger event (MSH-9.2). Required, non-empty.
+ * @param init - the MSH envelope + typed PID/PV1/EVN content (`patient` required).
+ * @throws TypeError when `event` is empty or `init.patient` is absent.
+ *
+ * @example
+ * ```ts
+ * import { buildAdt, parseHL7 } from "@cosyte/hl7";
+ * const msg = buildAdt("A01", {
+ *   sendingApp: "CLINIC",
+ *   receivingApp: "LAB",
+ *   patient: {
+ *     identifiers: { idNumber: "MRN001", identifierTypeCode: "MR" },
+ *     name: { familyName: "Test", givenName: "Ann" },
+ *     birthDateTime: "19880705",
+ *     administrativeSex: "F",
+ *   },
+ *   visit: { patientClass: "I", assignedLocation: { pointOfCare: "ICU", room: "1", bed: "A" } },
+ * });
+ * const round = parseHL7(msg.toString());
+ * round.warnings.length;          // 0
+ * round.patient?.familyName;      // "Test"
+ * round.structure.missingGroups;  // []
+ * ```
+ */
+declare function buildAdt(event: string, init: BuildAdtInit): Hl7Message;
+
+/**
+ * `buildOru`: author a spec-clean HL7 v2 **ORU^R01** (observation result)
+ * message from typed inputs (roadmap Phase T). The conservative-emit mirror of
+ * the read helpers (`msg.orders`, `msg.observations`): a caller supplies a
+ * typed patient, an optional order (OBR), and one or more typed observations
+ * (OBX), and `buildOru` assembles `MSH + PID + OBR + OBX…` with correct
+ * `^`/`&`/`~` structure via the HL7-R encode-safe path.
+ *
+ * **Structurally complete + zero-warning.** The emitted message carries the
+ * ORU^R01 result group the parser's structure net marks Required (OBR/OBX), so
+ * it re-parses with **zero warnings** and `msg.structure.missingGroups` empty.
+ *
+ * **Never fabricate.** Only supplied values are emitted; omitted fields become
+ * empty/absent. `patient` and at least one `observations` entry are
+ * **required**: an ORU with no subject or no result is a typed `TypeError`,
+ * not a guessed PID or a fabricated OBX.
+ *
+ * Spec traceability: HL7 v2 Ch. 7 (ORU: MSH/PID/OBR/OBX), Ch. 2 datatypes.
+ * Zero runtime deps.
+ */
+
+/**
+ * Typed PID content for {@link buildOru}. Reuses {@link AdtPatient}: the
+ * patient-identification shape is identical across message families.
+ */
+type OruPatient = AdtPatient;
+/** Typed OBR (observation request / order) content for {@link buildOru}. */
+interface OruOrder {
+    /** OBR-1 Set ID. */
+    readonly setId?: string;
+    /** OBR-2 Placer Order Number. */
+    readonly placerOrderNumber?: string;
+    /** OBR-3 Filler Order Number. */
+    readonly fillerOrderNumber?: string;
+    /** OBR-4 Universal Service Identifier. */
+    readonly universalServiceId?: CWE;
+    /** OBR-7 Observation Date/Time. */
+    readonly observationDateTime?: TS | string;
+    /** OBR-16 Ordering Provider. */
+    readonly orderingProvider?: XCN | readonly XCN[];
+    /** OBR-25 Result Status (e.g. `"F"` final, `"P"` preliminary, `"C"` corrected). */
+    readonly resultStatus?: string;
+}
+/** Typed OBX (observation / result) content for {@link buildOru}. */
+interface OruObservation {
+    /** OBX-1 Set ID. */
+    readonly setId?: string;
+    /** OBX-2 Value Type (e.g. `"NM"`, `"ST"`, `"CE"`, `"TX"`). */
+    readonly valueType?: string;
+    /** OBX-3 Observation Identifier. */
+    readonly identifier?: CWE;
+    /** OBX-5 Observation Value (emitted verbatim: the caller owns its formatting). */
+    readonly value?: string;
+    /** OBX-6 Units. */
+    readonly units?: CWE;
+    /** OBX-7 References Range. */
+    readonly referenceRange?: string;
+    /** OBX-8 Abnormal Flags (e.g. `"H"`, `"L"`, `"N"`). */
+    readonly abnormalFlags?: string;
+    /** OBX-11 Observation Result Status (e.g. `"F"` final, `"P"` preliminary). */
+    readonly observationResultStatus?: string;
+    /** OBX-14 Date/Time of the Observation. */
+    readonly observationDateTime?: TS | string;
+}
+/** Input for {@link buildOru}: the MSH envelope plus the typed segment bodies. */
+interface BuildOruInit extends MessageEnvelope {
+    /** PID content. **Required**: never fabricated. */
+    readonly patient: OruPatient;
+    /** OBR content. Optional; an (empty) OBR is emitted regardless so the result group is well-formed. */
+    readonly order?: OruOrder;
+    /** OBX content. **Required, non-empty**: an ORU with no result is a typed error. */
+    readonly observations: readonly OruObservation[];
+}
+/**
+ * Build a spec-clean ORU^R01 observation-result message from typed inputs.
+ *
+ * The result is a real {@link Hl7Message}: `msg.toString()` serialises it,
+ * `parseHL7(msg.toString())` round-trips with zero warnings, and
+ * `msg.observations()` reads back the results supplied.
+ *
+ * @param init - the MSH envelope + typed PID/OBR/OBX content. `patient` and a
+ *   non-empty `observations` list are required.
+ * @throws TypeError when `patient` is absent or `observations` is empty.
+ *
+ * @example
+ * ```ts
+ * import { buildOru, parseHL7 } from "@cosyte/hl7";
+ * const msg = buildOru({
+ *   sendingApp: "LAB",
+ *   receivingApp: "EHR",
+ *   patient: { identifiers: { idNumber: "MRN001", identifierTypeCode: "MR" },
+ *              name: { familyName: "Test", givenName: "Ann" } },
+ *   order: { universalServiceId: { identifier: "CBC", text: "Complete Blood Count", nameOfCodingSystem: "L" },
+ *            resultStatus: "F" },
+ *   observations: [
+ *     { setId: "1", valueType: "NM",
+ *       identifier: { identifier: "WBC", text: "White Blood Cells", nameOfCodingSystem: "LN" },
+ *       value: "7.2", units: { identifier: "10*3/uL" }, observationResultStatus: "F" },
+ *   ],
+ * });
+ * const round = parseHL7(msg.toString());
+ * round.warnings.length;                  // 0
+ * round.observations()[0]?.value;         // "7.2"
+ * ```
+ */
+declare function buildOru(init: BuildOruInit): Hl7Message;
+
 /**
  * Frozen HL7 control-vocabulary tables for ACK generation (Phase C). These
- * are read-only enums sourced from the HL7 v2 standard — `@cosyte/hl7` is the
+ * are read-only enums sourced from the HL7 v2 standard: `@cosyte/hl7` is the
  * single owner of this vocabulary; siblings (notably `@cosyte/mllp`) consume
  * `buildAck` rather than re-declaring these codes.
  *
- * Provenance (re-verify before editing — HL7 tables move):
- * - **Table 0008** Acknowledgment code — https://terminology.hl7.org/CodeSystem-v2-0008.html
- * - **Table 0357** Message error condition codes — https://terminology.hl7.org/CodeSystem-v2-0357.html
- * - **Table 0516** Error severity — HL7 v2 Chapter 2 §2.14.5 (ERR-4)
- * - **Table 0155** Accept/application acknowledgment conditions (MSH-15/16) —
+ * Provenance (re-verify before editing: HL7 tables move):
+ * - **Table 0008** Acknowledgment code: https://terminology.hl7.org/CodeSystem-v2-0008.html
+ * - **Table 0357** Message error condition codes: https://terminology.hl7.org/CodeSystem-v2-0357.html
+ * - **Table 0516** Error severity: HL7 v2 Chapter 2 §2.14.5 (ERR-4)
+ * - **Table 0155** Accept/application acknowledgment conditions (MSH-15/16),
  *   HL7 v2 Chapter 2 §2.14.9.15–16
  *
  * Zero runtime deps.
  */
 /**
- * HL7 Table 0008 — Acknowledgment code (MSA-1). The two acknowledgment
+ * HL7 Table 0008: Acknowledgment code (MSA-1). The two acknowledgment
  * **vocabularies**:
  * - **original** mode: `AA` Application Accept · `AE` Application Error ·
  *   `AR` Application Reject.
@@ -4838,14 +5626,14 @@ type AckCode = (typeof ACK_CODES)[keyof typeof ACK_CODES];
  */
 declare function isPositiveAck(code: string | undefined): boolean;
 /**
- * Downgrade a positive acknowledgment code to its matching error code —
+ * Downgrade a positive acknowledgment code to its matching error code,
  * `AA` → `AE` (original mode), `CA` → `CE` (enhanced mode). Every other code
  * passes through unchanged.
  *
  * This is the **single upstream source of truth** for the fail-safe downgrade
  * pair: `buildAck` applies it when the inbound carries no MSH-10 correlation
  * id, and `@cosyte/mllp`'s `ack-from-hl7` adapter applies it when the inbound
- * cannot be parsed at all — neither ever fabricates an unverifiable positive
+ * cannot be parsed at all: neither ever fabricates an unverifiable positive
  * acknowledgment, and neither carries its own copy of the mapping.
  *
  * @example
@@ -4858,7 +5646,7 @@ declare function isPositiveAck(code: string | undefined): boolean;
  */
 declare function downgradePositiveAck(code: AckCode): AckCode;
 /**
- * HL7 Table 0516 — Error severity (ERR-4). A v2.5+ construct (ERR was
+ * HL7 Table 0516: Error severity (ERR-4). A v2.5+ construct (ERR was
  * structured differently in v2.3.1).
  *
  * @example
@@ -4878,13 +5666,13 @@ declare const ERR_SEVERITIES: {
 /** Error-severity union (HL7 Table 0516, ERR-4). */
 type ErrSeverity = (typeof ERR_SEVERITIES)[keyof typeof ERR_SEVERITIES];
 /**
- * HL7 Table 0357 — Message error condition codes (ERR-3.1 → ERR-3.2 text).
+ * HL7 Table 0357: Message error condition codes (ERR-3.1 → ERR-3.2 text).
  * Frozen read-only map of `code → standard display text`. The code system
  * name emitted in ERR-3.3 is {@link ERR_CONDITION_CODE_SYSTEM}.
  *
  * Codes `104` (value too long) and `105` (table value not found) are v2.7+
  * additions; the rest are present from v2.5. `buildAck` emits whatever code it
- * is told — it never invents a condition — and looks up the display text here.
+ * is told (it never invents a condition) and looks up the display text here.
  *
  * @example
  * ```ts
@@ -4896,7 +5684,7 @@ declare const ERR_CONDITION_CODES: Readonly<Record<string, string>>;
 /** Code-system name emitted in ERR-3.3 for Table 0357 condition codes. */
 declare const ERR_CONDITION_CODE_SYSTEM = "HL70357";
 /**
- * HL7 Table 0155 — Accept/application acknowledgment conditions (MSH-15 /
+ * HL7 Table 0155: Accept/application acknowledgment conditions (MSH-15 /
  * MSH-16): `AL` Always · `NE` Never · `ER` Error/reject conditions only ·
  * `SU` Successful completion only. Exposed read-only for adapters that
  * surface the inbound sender's stated acknowledgment expectations.
@@ -4922,12 +5710,12 @@ type AckCondition = (typeof ACK_CONDITIONS)[keyof typeof ACK_CONDITIONS];
 type AckMode = "original" | "enhanced";
 
 /**
- * `buildAck` — generate a spec-clean HL7 v2 acknowledgment (ACK) message from
+ * `buildAck`: generate a spec-clean HL7 v2 acknowledgment (ACK) message from
  * an inbound message (Phase C). The boundary with `@cosyte/mllp` is resolved
  * (hl7 roadmap §10.1): **hl7 owns ACK *content*** (this file + the control
  * tables); mllp owns *policy/timing* (the commit contract) and *framing*.
  *
- * `buildAck` is **mechanical** — it builds the disposition it is *told* via
+ * `buildAck` is **mechanical**: it builds the disposition it is *told* via
  * `options.code`; it never decides accept-vs-reject. The one safety override is
  * the fail-safe below: it refuses to fabricate a positive `AA`/`CA` for an
  * inbound message that carries no MSH-10 correlation id.
@@ -4941,7 +5729,7 @@ type AckMode = "original" | "enhanced";
 
 /**
  * One ERR segment's worth of error detail for `buildAck`. Carries **codes and
- * locations only — never echoed PHI values** (the phi-redaction-review gate
+ * locations only: never echoed PHI values** (the phi-redaction-review gate
  * binds this contract).
  *
  * @example
@@ -4958,7 +5746,7 @@ interface AckErrorDetail {
      * HL7 Table 0357 message error condition code (ERR-3.1). Defaults to `"207"`
      * (Application internal error). The standard display text is looked up from
      * Table 0357 and emitted in ERR-3.2; unknown codes emit with empty text
-     * (the code is preserved verbatim — never dropped).
+     * (the code is preserved verbatim: never dropped).
      */
     readonly conditionCode?: string;
     /** HL7 Table 0516 severity (ERR-4). Defaults to `"E"` (Error). */
@@ -4966,7 +5754,7 @@ interface AckErrorDetail {
     /**
      * Error location (ERR-2, an HL7 ERL). A structural path such as `"PID^1^5"`
      * (segment id ^ segment sequence ^ field position). **Must not contain a
-     * patient data value** — locations point at *where*, never *what*.
+     * patient data value**: locations point at *where*, never *what*.
      */
     readonly location?: string;
 }
@@ -4983,7 +5771,7 @@ interface BuildAckOptions {
     /**
      * The acknowledgment disposition to emit in MSA-1 (HL7 Table 0008). One of
      * `AA`/`AE`/`AR` (original) or `CA`/`CE`/`CR` (enhanced accept-level).
-     * Required — `buildAck` builds the disposition it is told. An unknown code
+     * Required: `buildAck` builds the disposition it is told. An unknown code
      * is a programming error and throws `TypeError`.
      */
     readonly code: AckCode;
@@ -4995,7 +5783,7 @@ interface BuildAckOptions {
     /**
      * Optional explicit acknowledgment mode. When omitted it is derived from the
      * inbound MSH-15/16 via {@link detectAckMode}. `buildAck` emits `code`
-     * verbatim regardless of mode — this field is advisory metadata for adapters
+     * verbatim regardless of mode: this field is advisory metadata for adapters
      * (e.g. `@cosyte/mllp`'s commit-policy layer) that need the detected mode.
      */
     readonly mode?: AckMode;
@@ -5005,7 +5793,7 @@ interface BuildAckOptions {
  * acknowledgment type) and MSH-16 (application acknowledgment type), per HL7 v2
  * Chapter 2 §2.9: **original** when *both* are absent/empty; **enhanced** when
  * *either* is present. This split is spec-exact (unlike the disposition mapping,
- * which has no single correct model — see the package README).
+ * which has no single correct model: see the package README).
  *
  * @example
  * ```ts
@@ -5018,33 +5806,33 @@ declare function detectAckMode(inbound: Hl7Message): AckMode;
  * Build a spec-clean ACK (`MSH` + `MSA` [+ `ERR`…]) responding to `inbound`.
  *
  * Behavior:
- * - **MSH** — sender/receiver are swapped (inbound MSH-5/6 → ACK MSH-3/4;
+ * - **MSH**: sender/receiver are swapped (inbound MSH-5/6 → ACK MSH-3/4;
  *   inbound MSH-3/4 → ACK MSH-5/6); MSH-7 is the current UTC time; MSH-9 is
  *   `ACK` (with the inbound trigger event echoed as `ACK^<trigger>^ACK` when
  *   present); MSH-10 is a freshly generated control id; MSH-11 (processing id)
  *   and MSH-12 (version) echo the inbound values.
- * - **MSA** — MSA-1 = `code`; **MSA-2 echoes the full inbound MSH-10 field**
- *   (the raw field structure is carried over whole — a vendor-quirk id like
+ * - **MSA**: MSA-1 = `code`; **MSA-2 echoes the full inbound MSH-10 field**
+ *   (the raw field structure is carried over whole: a vendor-quirk id like
  *   `ID^X` is never truncated to its first component). The echo carries the
  *   inbound field's escape-fidelity overlay (HL7-ESC), so an id bearing a hex
  *   escape (`ID\X41\Q`) or a preserved escape (`\H\`) echoes **byte-verbatim**,
- *   not canonicalized — exactly the bytes the sender put on the wire, which is
+ *   not canonicalized: exactly the bytes the sender put on the wire, which is
  *   what MSA-2 correlation compares. The only structural transform is
  *   trailing-empty canonicalization (D-02). (A sender that used *custom*
  *   encoding characters is **re-delimited spec-cleanly**: the overlay carries
  *   the sender's raw bytes in the sender's alphabet, so echoing them verbatim
  *   under the ACK's default alphabet would corrupt the field's structure and
- *   break correlation — the overlay is therefore bypassed and the decoded id is
+ *   break correlation: the overlay is therefore bypassed and the decoded id is
  *   re-escaped under default, which re-parses back to the same control id.
  *   Default-delimiter senders, the norm, keep the byte-exact overlay echo.)
- * - **ERR** — one segment per supplied {@link AckErrorDetail}: ERR-2 location
+ * - **ERR**: one segment per supplied {@link AckErrorDetail}: ERR-2 location
  *   (when given), ERR-3 the Table 0357 condition code as a CWE
  *   (`code^text^HL70357`), ERR-4 the Table 0516 severity.
  *
  * **Fail-safe (roadmap §Phase C).** If the inbound message has no MSH-10, the
  * ACK cannot be correlated. `buildAck` then leaves MSA-2 empty and, if a
  * positive accept (`AA`/`CA`) was requested, **downgrades it** to the matching
- * error code (`AE`/`CE`) — it never fabricates an unverifiable positive ACK.
+ * error code (`AE`/`CE`): it never fabricates an unverifiable positive ACK.
  * The returned message carries an `ACK_NO_CORRELATION_ID` warning. (This is the
  * inbound-side complement to `@cosyte/mllp`'s "no commit ⇒ never AA".)
  *
@@ -5063,16 +5851,16 @@ declare function detectAckMode(inbound: Hl7Message): AckMode;
 declare function buildAck(inbound: Hl7Message, options: BuildAckOptions): Hl7Message;
 
 /**
- * `interpretAck` — read-side helper that interprets an inbound HL7 v2
+ * `interpretAck`: read-side helper that interprets an inbound HL7 v2
  * acknowledgment (ACK) message into a typed {@link Acknowledgment} view
  * (Phase C). The mechanical inverse of `buildAck`: it reads MSA-1 (code),
  * MSA-2 (the correlated control id), and every ERR segment.
  *
- * Fail-safe: an absent or unrecognized MSA-1 yields `accepted: false` — the
+ * Fail-safe: an absent or unrecognized MSA-1 yields `accepted: false`: the
  * interpreter NEVER reports an acknowledgment as accepted on ambiguous input.
  *
  * Spec traceability: HL7 v2 Chapter 2 §2.14.8 (MSA), §2.14.5 (ERR). Codes are
- * surfaced verbatim (Table 0008 / 0357 / 0516) — no validation or lookup.
+ * surfaced verbatim (Table 0008 / 0357 / 0516): no validation or lookup.
  *
  * Zero runtime deps.
  */
@@ -5080,18 +5868,18 @@ declare function buildAck(inbound: Hl7Message, options: BuildAckOptions): Hl7Mes
 /**
  * One ERR segment interpreted from an ACK. All fields are surfaced verbatim
  * (no table lookup) and OMITTED when the underlying component is absent
- * (exactOptionalPropertyTypes). Codes/locations only — never PHI.
+ * (exactOptionalPropertyTypes). Codes/locations only: never PHI.
  */
 interface AckErrorEntry {
-    /** ERR-3.1 — HL7 Table 0357 condition code. */
+    /** ERR-3.1: HL7 Table 0357 condition code. */
     readonly conditionCode?: string;
-    /** ERR-3.2 — condition code display text. */
+    /** ERR-3.2: condition code display text. */
     readonly conditionText?: string;
-    /** ERR-3.3 — condition code system name (e.g. `HL70357`). */
+    /** ERR-3.3: condition code system name (e.g. `HL70357`). */
     readonly conditionCodeSystem?: string;
-    /** ERR-4 — HL7 Table 0516 severity (`I`/`W`/`E`). */
+    /** ERR-4: HL7 Table 0516 severity (`I`/`W`/`E`). */
     readonly severity?: string;
-    /** ERR-2 — error location (an HL7 ERL), surfaced verbatim. */
+    /** ERR-2: error location (an HL7 ERL), surfaced verbatim. */
     readonly location?: string;
 }
 /**
@@ -5115,7 +5903,7 @@ interface Acknowledgment {
     readonly code?: string;
     /**
      * MSA-2 message control id (the correlated inbound MSH-10), surfaced as the
-     * field's **canonical wire text** (`Field.text`) — the whole field,
+     * field's **canonical wire text** (`Field.text`): the whole field,
      * delimiters included, never truncated to the first component. Note this is
      * the *re-escaped* form: a properly-escaped id arrives as its wire bytes
      * (`ID\S\X`), and an HL7 explicit-null MSA-2 surfaces as the literal
@@ -5147,7 +5935,7 @@ interface Acknowledgment {
 declare function interpretAck(msg: Hl7Message): Acknowledgment;
 
 /**
- * `defineProfile()` — public factory for building `Profile` objects with
+ * `defineProfile()`: public factory for building `Profile` objects with
  * validation + `describe()` attached (PROF-01, PROF-04, PROF-05).
  *
  * Wave 1 (Plan 06-01) ships the single-profile (no-extends) path;
@@ -5197,7 +5985,7 @@ interface DefineProfileOptions {
  * unknown top-level keys with typo hints (D-07), and missing/empty
  * name.
  *
- * Wave 1 (Plan 06-01) ships the no-extends path — `opts.extends` is
+ * Wave 1 (Plan 06-01) ships the no-extends path: `opts.extends` is
  * ACCEPTED but IGNORED, resulting in `lineage === [opts.name]`
  * regardless. Wave 2 (Plan 06-02) adds full lineage computation + merge
  * semantics.
@@ -5223,7 +6011,7 @@ declare function defineProfile(opts: DefineProfileOptions): Profile;
 
 /**
  * Process-scoped default profile management (PROF-08 / D-18). This module
- * holds the first mutable module-scoped state in the codebase — an
+ * holds the first mutable module-scoped state in the codebase: an
  * intentional trade-off documented in PROJECT.md Key Decisions:
  * `setDefaultProfile` EXISTS but is DISCOURAGED. It is scoped to the
  * current Node process, NOT shared across workers, NOT a symbol-keyed
@@ -5245,7 +6033,7 @@ declare function defineProfile(opts: DefineProfileOptions): Profile;
  * arg of `parseHL7` (D-20): customSegments, dateFormats, onWarning chain,
  * and profile attribution all apply the same way.
  *
- * Explicit args ALWAYS win — `parseHL7(raw, myProfile)` uses `myProfile`
+ * Explicit args ALWAYS win: `parseHL7(raw, myProfile)` uses `myProfile`
  * regardless of the default; `parseHL7(raw, { profile: null })` opts out
  * of the default for a single call without changing the registered
  * default.
@@ -5274,7 +6062,7 @@ declare function defineProfile(opts: DefineProfileOptions): Profile;
 declare function setDefaultProfile(profile: Profile | null): void;
 /**
  * Return the current default profile, or `undefined` if none is
- * registered. Consistent with `msg.profile` convention — `undefined`
+ * registered. Consistent with `msg.profile` convention: `undefined`
  * rather than `null`.
  *
  * @example
@@ -5292,7 +6080,7 @@ declare function getDefaultProfile(): Profile | undefined;
  * `ZCA` (care team membership). BIP-04.
  *
  * The AM/PM meridian variant (`MM/DD/YYYY HH:mm AM/PM`) is intentionally
- * NOT shipped — the library's format-token set does not include AM/PM
+ * NOT shipped: the library's format-token set does not include AM/PM
  * (`SUPPORTED_DATE_TOKENS` = YYYY/MM/DD/HH/mm/ss/SSSS). Consumers needing
  * meridian support can extend this profile or supply their own format
  * handler.
@@ -5350,7 +6138,7 @@ declare const cerner: Profile;
  * feeds, plus two Z-segments: `ZDP` (department context) and `ZRS`
  * (result status). BIP-01.
  *
- * Authored from the public `defineProfile()` API — zero privileged
+ * Authored from the public `defineProfile()` API: zero privileged
  * internal coupling. Consumers extend this profile via
  * `defineProfile({ name: '...', extends: profiles.epic, ... })`.
  *
@@ -5380,7 +6168,7 @@ declare const epic: Profile;
  * `YYYY-MM-DD` (ISO date-only). Two Z-segments: `ZLB` (lab-override
  * flags) and `ZNT` (lab note). BIP-05.
  *
- * The canonical HL7 format `YYYYMMDDHHmmss` is NOT shipped here — it's
+ * The canonical HL7 format `YYYYMMDDHHmmss` is NOT shipped here: it's
  * already the parser's primary (zero-warning) match for TS/DTM.
  *
  * @example
@@ -5404,22 +6192,54 @@ declare const epic: Profile;
 declare const genericLab: Profile;
 
 /**
- * Meditech MAGIC / Expanse HL7 quirks. Ships minute-precision timestamps
- * (`YYYYMMDDHHmm`) — a non-HL7 format Meditech commonly uses in ADT and
- * scheduling feeds (HL7 spec is `YYYYMMDDHHmmss` with seconds). One
- * Z-segment: `ZVI` (visit info). BIP-03.
+ * MEDITECH (MAGIC / 6.x / Expanse) HL7 quirks. Ships minute-precision
+ * timestamps (`YYYYMMDDHHMM`, no seconds) and two DFT charge-capture
+ * Z-segments: `ZF1` (provider-encounter copay data) and `ZF2`
+ * (encounter-procedure data). BIP-03.
+ *
+ * Grounded in **publicly downloadable** MEDITECH interface specifications
+ * (ADR 0018: public specs count as real artifacts), not invented:
+ *
+ * - The **minute-precision** date/time format is confirmed by *two*
+ *   public MEDITECH specs: "MEDITECH Admissions and Registration to Other
+ *   Vendor Ancillary" (Version 2.4, © 2021 Medical Information Technology,
+ *   Inc.) ("Date and Time in Admissions. Format is YYYYMMDDHHMM") and
+ *   "MEDITECH Ancillary Charges (LAB/PHA/ITS/IDM)" (Version 2.1, © 2021),
+ *   whose MSH-7 is length **12** (= `YYYYMMDDHHMM`) and whose EVN-2/PID-7
+ *   are documented "Format is YYYYMMDDHHMM". Minute precision is
+ *   HL7-conformant (TS/DTM permit variable precision), so declaring it here
+ *   is not about accepting an illegal value: it records MEDITECH's
+ *   characteristic no-seconds convention so date resolution across a
+ *   MEDITECH feed is explicit rather than incidental.
+ * - `ZF1` and `ZF2` are the DFT (charge) Z-segments defined verbatim in
+ *   the Ancillary Charges spec (Version 2.1): `ZF1` = "PROVIDER ENCOUNTER
+ *   COPAY DATA" (ZF1-1 PROVIDER ENCOUNTER, ZF1-2 MIS SERVICE GROUP, ZF1-3
+ *   SERVICE GROUP COPAY, ZF1-4 VISIT COPAY, ZF1-5 COPAY MINIMUM, ZF1-6
+ *   COPAY MAXIMUM); `ZF2` = "ENCOUNTER PROCEDURE DATA" (ZF2-1 SET ID, ZF2-2
+ *   PROVIDER ENCOUNTER, ZF2-3 ENCOUNTER DATE, ZF2-4 ENCOUNTER PROCEDURE,
+ *   ZF2-5 ENCOUNTER PROCEDURE QUANTITY, ZF2-6 ENCOUNTER PROCEDURE CHARGE,
+ *   ZF2-7 PRV PROCEDURE AMOUNT PAID, ZF2-8 PRV PROCEDURE AMOUNT DUE).
+ *
+ * (This replaced an earlier `ZVI` "visit info" segment that was a
+ * community-sourced prior with no citable public grounding: HL7-I
+ * re-grounding, ADR 0018. Field positions here are transcribed directly
+ * from the spec's segment tables.)
+ *
+ * Authored from the public `defineProfile()` API: zero privileged
+ * internal coupling. Consumers extend this profile via
+ * `defineProfile({ name: '...', extends: profiles.meditech, ... })`.
  *
  * @example
  * ```ts
  * import { parseHL7, profiles } from "@cosyte/hl7";
  * const msg = parseHL7(raw, profiles.meditech);
- * const zvi = msg.allSegments().find((s) => s.type === "ZVI");
- * console.log(zvi?.get("visitReason")?.value);
+ * const zf1 = msg.allSegments().find((s) => s.type === "ZF1");
+ * console.log(zf1?.get("visitCopay")?.value);
  * ```
  */
 /**
- * Built-in Meditech MAGIC/Expanse profile (BIP-03). See file header for
- * rationale; use via `parseHL7(raw, profiles.meditech)`.
+ * Built-in MEDITECH MAGIC/6.x/Expanse profile (BIP-03). See file header for
+ * rationale and spec citations; use via `parseHL7(raw, profiles.meditech)`.
  *
  * @example
  * ```ts
@@ -5429,22 +6249,173 @@ declare const genericLab: Profile;
  */
 declare const meditech: Profile;
 
+/**
+ * Philips Vue PACS ("IS Link") imaging HL7 interface quirks. The Vue PACS
+ * IS Link component receives RIS-side ORM/ADT feeds and carries its
+ * PACS-specific data in six custom Z-segments the HL7 standard does not
+ * define: one per *filler role*:
+ *
+ * - **`ZDS`**: Order Filler: the DICOM **Study Instance UID** (field 1,
+ *   first component), the RIS↔PACS bridge (as in the IHE Radiology TF and
+ *   the `visage` profile); IS Link uses it to update the accession number.
+ * - **`ZLK`**: Order Filler: study/order **linking** ids (external
+ *   workitem id, order link id) that group studies and orders.
+ * - **`ZAO`**: Order Filler: order **additional details** (a base64 XML
+ *   key/value blob) plus modality, body part, transfer/acquisition status,
+ *   technician + radiologist names/ids, and vendor "custom" string/number/
+ *   date slots.
+ * - **`ZEB`**: Patient Filler: an **encrypted** patient-info blob (base64).
+ * - **`ZAP`**: Patient Filler: patient **additional details** (base64 XML)
+ *   plus patient "custom" string/number/date slots.
+ * - **`ZAV`**: Visit Filler: visit **additional details** (base64 XML).
+ *
+ * Grounded in the public **Vue PACS 12.2.8 HL7 Interface Specifications**
+ * (Philips, document HA1669 Rev A), §§5.11–5.16: a publicly downloadable
+ * vendor interface spec, not an invented quirk (ADR 0018). The spec's
+ * `TS` timestamps are the HL7-native `YYYYMMDDHHMMSS` form (§2.6), so this
+ * profile declares **no** custom `dateFormats`: only the Z-segments.
+ *
+ * Field positions are transcribed verbatim from the spec's segment tables,
+ * including two of its own gaps/quirks: `ZAO` has **no field 7** (the table
+ * jumps 6 → 8) and `ZAP` has **no field 2** (jumps 1 → 3); the three
+ * `ZAO`/`ZAP` "Custom Date" rows are all printed "…Date 1" in the spec (a
+ * transcription slip) but sit at consecutive positions, so they are named
+ * `…CustomDate1/2/3` here to keep each field name unique.
+ *
+ * `ZEB` holds *encrypted* patient information and `ZAP`/`ZAV` carry
+ * patient/visit blobs: naming the field is exactly how a consumer learns
+ * that segment is PHI-bearing and must not be logged. This profile only
+ * *names* the fields; it never decodes, decrypts, or rewrites them.
+ *
+ * Authored from the public `defineProfile()` API: zero privileged internal
+ * coupling. Consumers extend this profile via
+ * `defineProfile({ name: '...', extends: profiles.philips, ... })`.
+ *
+ * @example
+ * ```ts
+ * import { parseHL7, profiles } from "@cosyte/hl7";
+ * const msg = parseHL7(raw, profiles.philips);
+ * const zds = msg.allSegments().find((s) => s.type === "ZDS");
+ * console.log(zds?.get("studyInstanceUid")?.value); // "1.2.826.0.1.3680043.10.99999.20250326.7"
+ * ```
+ */
+/**
+ * Built-in Philips Vue PACS ("IS Link") imaging profile (BIP-08). See file
+ * header for rationale; use via `parseHL7(raw, profiles.philips)`.
+ *
+ * @example
+ * ```ts
+ * import { parseHL7, profiles } from "@cosyte/hl7";
+ * const msg = parseHL7(raw, profiles.philips);
+ * ```
+ */
+declare const philips: Profile;
+
+/**
+ * VA VistA Radiology / Nuclear Medicine imaging HL7 interface quirks. The
+ * Veterans Affairs VistA Radiology package exchanges HL7 **v2.4** messages
+ * with commercial RIS/PACS systems and carries the DICOM **Study Instance
+ * UID** in a `ZDS` Z-segment (field 1, `RP` "Reference Pointer" composite,
+ * the UID sits in the first component, ZDS-1.1 "Pointer"), so the receiving
+ * image manager can correlate the HL7 order/result with the DICOM study.
+ * This is the same IHE Radiology cross-vendor bridge segment declared by the
+ * `visage` and `philips` profiles: `ZDS` is an IHE extension, not a
+ * VA-proprietary quirk; the value this profile adds is a **named federal
+ * source** grounded in a distinct public spec, plus coverage of the shape the
+ * VA spec documents that the imaging-vendor specs do not: `ZDS` on **ORU**
+ * result messages (VistA sends `ZDS` in **both ORM and ORU**), not just on
+ * the ORM order.
+ *
+ * Grounded in the public **Radiology/Nuclear Medicine 5.0 HL7 Interface
+ * Specification** (Version 3.6, revised for Patch RA*5.0*203, June 2024, U.S.
+ * Department of Veterans Affairs), which documents "ZDS Segment Fields in ORU
+ * and ORM" with `ZDS-1` = Study Instance UID (`RP`: 1.1 Pointer, 1.2
+ * Application ID, 1.3 Type of Data, 1.4 Subtype). It is a publicly
+ * downloadable federal interface spec on the VA VistA Documentation Library
+ * (`va.gov/vdl`), not an invented quirk (ADR 0018). The spec's messaging is
+ * HL7-native v2.4, so its `TS` timestamps use the `YYYYMMDDHHMMSS` form: this
+ * profile therefore declares **no** custom `dateFormats`, only the ZDS
+ * segment.
+ *
+ * Authored from the public `defineProfile()` API: zero privileged internal
+ * coupling. Consumers extend this profile via
+ * `defineProfile({ name: '...', extends: profiles.va, ... })`.
+ *
+ * @example
+ * ```ts
+ * import { parseHL7, profiles } from "@cosyte/hl7";
+ * const msg = parseHL7(raw, profiles.va);
+ * const zds = msg.allSegments().find((s) => s.type === "ZDS");
+ * console.log(zds?.get("studyInstanceUid")?.value); // "1.2.826.0.1.3680043.10.99999.20250326.9"
+ * ```
+ */
+/**
+ * Built-in VA VistA Radiology / Nuclear Medicine imaging profile (BIP-09).
+ * See file header for rationale; use via `parseHL7(raw, profiles.va)`.
+ *
+ * @example
+ * ```ts
+ * import { parseHL7, profiles } from "@cosyte/hl7";
+ * const msg = parseHL7(raw, profiles.va);
+ * ```
+ */
+declare const va: Profile;
+
+/**
+ * Visage 7 imaging/PACS HL7 interface quirks. Radiology/PACS order feeds
+ * carry the DICOM **Study Instance UID** in a `ZDS` Z-segment (field 1,
+ * first component) so the receiving image manager can correlate the HL7
+ * order with the DICOM study: the classic RIS/PACS ↔ HL7 bridge segment
+ * defined by the IHE Radiology Technical Framework. BIP-07.
+ *
+ * Grounded in the public **Visage 7 – HL7 Interface Specification**
+ * (V23.00, Jun 2026, Visage Imaging GmbH), §4.4 "ORM Messages" + the ZDS
+ * segment table ("Study Instance UID … contained in the first component of
+ * the first field of the ZDS Segment"): a publicly downloadable vendor
+ * interface spec, not an invented quirk (ADR 0018). Dates in that spec use
+ * the HL7-native `YYYYMMDDHHMMSS` form, so this profile declares **no**
+ * custom `dateFormats`: only the ZDS segment.
+ *
+ * Authored from the public `defineProfile()` API: zero privileged internal
+ * coupling. Consumers extend this profile via
+ * `defineProfile({ name: '...', extends: profiles.visage, ... })`.
+ *
+ * @example
+ * ```ts
+ * import { parseHL7, profiles } from "@cosyte/hl7";
+ * const msg = parseHL7(raw, profiles.visage);
+ * const zds = msg.allSegments().find((s) => s.type === "ZDS");
+ * console.log(zds?.get("studyInstanceUid")?.value); // "1.2.826.0.1.3680043.10.99999.20250326.1"
+ * ```
+ */
+/**
+ * Built-in Visage 7 imaging/PACS profile (BIP-07). See file header for
+ * rationale; use via `parseHL7(raw, profiles.visage)`.
+ *
+ * @example
+ * ```ts
+ * import { parseHL7, profiles } from "@cosyte/hl7";
+ * const msg = parseHL7(raw, profiles.visage);
+ * ```
+ */
+declare const visage: Profile;
+
 /**
  * Public barrel for the `@cosyte/hl7` profile subsystem. Assembles
- * the `profiles` namespace object (5 built-ins) and re-exports the public
+ * the `profiles` namespace object (8 built-ins) and re-exports the public
  * profile API: `defineProfile`, `setDefaultProfile`, `getDefaultProfile`,
  * plus the two type exports `DefineProfileOptions` and
  * `CustomSegmentDefinition`.
  *
- * D-26 contract: individual built-ins are NOT top-level named exports —
+ * D-26 contract: individual built-ins are NOT top-level named exports,
  * consumers access them via `profiles.epic`, `profiles.cerner`, etc.
  * ("epic" is too generic a name for a top-level export.)
  */
 
 /**
- * Namespace object exposing the 5 shipped built-in vendor profiles (epic,
- * cerner, meditech, athena, genericLab). Each is authored via the public
- * `defineProfile()` API (BIP-01..05).
+ * Namespace object exposing the 8 shipped built-in vendor profiles (epic,
+ * cerner, meditech, athena, genericLab, visage, philips, va). Each is authored
+ * via the public `defineProfile()` API (BIP-01..09).
  *
  * @example
  * ```ts
@@ -5459,6 +6430,9 @@ declare const profiles: {
     readonly epic: typeof epic;
     readonly genericLab: typeof genericLab;
     readonly meditech: typeof meditech;
+    readonly philips: typeof philips;
+    readonly va: typeof va;
+    readonly visage: typeof visage;
 };
 
 /**
@@ -5468,7 +6442,7 @@ declare const profiles: {
  *
  * Derived from HL7 v2.5.1 chapters 3-7 (core message segments, order/result
  * tree, financial tree, scheduling, master files). Z-segments
- * (`/^Z[A-Z0-9]{2}$/`) are NOT in this set — they're always user-defined
+ * (`/^Z[A-Z0-9]{2}$/`) are NOT in this set: they're always user-defined
  * and must be declared in a profile to avoid the warning.
  *
  * Frozen as `ReadonlySet<string>` for O(1) lookup without mutation risk.
@@ -5489,7 +6463,7 @@ declare const profiles: {
 declare const KNOWN_SEGMENTS: ReadonlySet<string>;
 
 /**
- * Coding-system provenance (HL7 Table 0396, READ-ONLY) — roadmap Phase F.
+ * Coding-system provenance (HL7 Table 0396, READ-ONLY): roadmap Phase F.
  *
  * Answers one question about a coded element: **"what coding system does this
  * code CLAIM?"** It surfaces the sender's CWE.3 / CE.3 "Name of Coding System"
@@ -5502,20 +6476,20 @@ declare const KNOWN_SEGMENTS: ReadonlySet<string>;
  *   - **No lookup, no network, no bundled codeset.** Zero runtime deps; this is
  *     a frozen acronym→name map, nothing more.
  *   - **Fail-safe.** An unregistered / local / mistyped system id is surfaced
- *     **verbatim** with `known: false` — never dropped, never guessed.
+ *     **verbatim** with `known: false`: never dropped, never guessed.
  *
  * Because provenance is the *sender's claim*, not a verified fact, a consumer
  * MUST still treat the code per its own trust policy. The value of this module
- * is letting that consumer ask "which system?" before interpreting a code — a
+ * is letting that consumer ask "which system?" before interpreting a code: a
  * "PCN" allergen or an "I10" diagnosis is only safe to read once you know the
  * system it belongs to.
  *
- * Spec traceability: HL7 Table 0396 (Coding System) — the registry of
+ * Spec traceability: HL7 Table 0396 (Coding System): the registry of
  * coding-system acronyms carried in the CWE.3 / CE.3 component. v2.7+ expects
  * the registered acronym. See `docs-content/spec-notes-coding-system.md` for
  * the per-entry source and the `I10` (ICD-10 vs ICD-10-CM) nuance.
  *
- * Zero runtime deps — pure data + pure functions.
+ * Zero runtime deps: pure data + pure functions.
  */
 /**
  * One recognized HL7 Table 0396 coding system: its registered acronym (the
@@ -5536,14 +6510,14 @@ interface KnownCodingSystem {
 }
 /**
  * The safety-relevant subset of HL7 Table 0396 this library recognizes for
- * provenance. Deliberately small and frozen — it is NOT the full Table 0396
+ * provenance. Deliberately small and frozen: it is NOT the full Table 0396
  * registry. Each entry's source is recorded in
  * `docs-content/spec-notes-coding-system.md`.
  *
  * Note on `I10`: Table 0396 registers `I10` as **ICD-10** (the WHO base
  * classification). US v2 feeds frequently send `I10` when they mean
  * ICD-10-**CM**, but that clinical-modification specificity is the sender's
- * convention, not what the acronym registers — so this map reports the
+ * convention, not what the acronym registers: so this map reports the
  * registered claim (`"ICD-10"`) and does not silently upgrade it to CM.
  *
  * @example
@@ -5554,14 +6528,14 @@ interface KnownCodingSystem {
  */
 declare const KNOWN_CODING_SYSTEMS: readonly KnownCodingSystem[];
 /**
- * A coding-system provenance answer — the system a code CLAIMS, never
+ * A coding-system provenance answer: the system a code CLAIMS, never
  * validated. `claimed` is always present and verbatim (never dropped); the
  * resolved `id` / `name` are present only when the claim maps to a registered
  * Table 0396 entry.
  */
 interface CodingSystemInfo {
     /**
-     * The coding-system id exactly as it appeared in CWE.3 / CE.3 — preserved
+     * The coding-system id exactly as it appeared in CWE.3 / CE.3: preserved
      * verbatim (original case and spelling), never altered, never dropped.
      */
     readonly claimed: string;
@@ -5575,12 +6549,12 @@ interface CodingSystemInfo {
 /**
  * Resolve a raw coding-system id (a CWE.3 / CE.3 "Name of Coding System"
  * value) to its provenance. Returns `undefined` when there is no claim to
- * resolve — `id` is `undefined`, empty, or whitespace-only.
+ * resolve: `id` is `undefined`, empty, or whitespace-only.
  *
  * Matching is case-insensitive and tolerant of surrounding whitespace, and
  * normalizes the well-known aliases in {@link KNOWN_CODING_SYSTEMS} (e.g.
  * `"LOINC"` → `LN`, `"SNOMED"` → `SCT`, `"RxNorm"` → `RXN`). An unrecognized
- * id is returned verbatim with `known: false` — never guessed.
+ * id is returned verbatim with `known: false`: never guessed.
  *
  * @example
  * ```ts
@@ -5594,7 +6568,7 @@ interface CodingSystemInfo {
 declare function codingSystem(id: string | undefined): CodingSystemInfo | undefined;
 /**
  * Structural shape of any coded element that carries a primary + alternate
- * coding system — both {@link CWE} and {@link CE} satisfy it. Kept structural
+ * coding system: both {@link CWE} and {@link CE} satisfy it. Kept structural
  * (not a union) so callers can pass a `dg.code` / `obs.code` directly.
  */
 interface CodedSystemFields {
@@ -5646,10 +6620,10 @@ declare function alternateCodingSystemOf(coded: CodedSystemFields): CodingSystem
  *
  * `splitBatch()` demarcates the individual `MSH`-led messages by **MSH
  * boundaries**, parses each one with {@link parseHL7} (so every message is
- * returned either as a parsed `Hl7Message` **or** as a typed failure entry —
+ * returned either as a parsed `Hl7Message` **or** as a typed failure entry,
  * a malformed message mid-stream is isolated, never suppresses its siblings),
  * and reconciles the declared envelope counts (BTS-1 batch message count,
- * FTS-1 file batch count) against the actual counts — surfacing a
+ * FTS-1 file batch count) against the actual counts: surfacing a
  * {@link batchCountMismatch} warning on any mismatch **without ever dropping
  * the tail**. A bare single message with no envelope passes straight through
  * as a one-message result.
@@ -5657,7 +6631,7 @@ declare function alternateCodingSystemOf(coded: CodedSystemFields): CodingSystem
  * This is a **separate surface** from `parseHL7` on purpose: `parseHL7` rejects
  * non-`MSH`-first input outright (that is correct for a single-message
  * parser), so batch demarcation lives here. `splitBatch` is a **splitter**, not
- * an enforcer — it does not send batch ACKs, does not enforce any profile's
+ * an enforcer: it does not send batch ACKs, does not enforce any profile's
  * mandatory-envelope rule (it warns via {@link batchMissingTrailer}; the caller
  * decides to reject), and does not de-batch across transport framing (that is
  * `@cosyte/mllp`). See `docs-content/spec-notes-batch.md`.
@@ -5676,7 +6650,7 @@ type BatchEnvelopeName = "FHS" | "BHS" | "BTS" | "FTS";
 /**
  * A raw batch-envelope segment (`FHS`/`BHS`/`BTS`/`FTS`) surfaced by
  * {@link splitBatch}. `fields` is the segment split on its own field separator
- * with `fields[0]` holding the segment name — deliberately the raw token
+ * with `fields[0]` holding the segment name: deliberately the raw token
  * array, not a typed model: first-class FHS/BHS field helpers are deferred
  * (roadmap Phase L defers "typed FHS/BHS helpers beyond raw fields"). Note the
  * HL7 MSH-family indexing quirk: for `FHS`/`BHS`, `fields[1]` is the
@@ -5704,7 +6678,7 @@ interface BatchEnvelopeSegment {
  * One message extracted from a batch stream. Discriminated on `ok`: a
  * successful parse carries the `Hl7Message` (whose own `.warnings` hold any
  * per-message Tier-2 deviations); a message that hit one of the four Tier-3
- * fatal conditions carries the `Hl7ParseError` instead — **isolated**, so the
+ * fatal conditions carries the `Hl7ParseError` instead: **isolated**, so the
  * rest of the batch still yields. `raw` is the message's verbatim source
  * (re-parseable by {@link parseHL7}); `position` is the message's `MSH` (or,
  * for pre-`MSH` stray content, its first) segment index in the stream.
@@ -5733,7 +6707,7 @@ type BatchMessageEntry = {
  * One batch within a stream: a run of messages delimited by a `BHS` header
  * and/or a `BTS` trailer (both optional in §2.10.3, so a `BTS` closes a
  * preceding run into a batch even with no `BHS`). A run of messages with
- * **neither** a header nor a trailer is *not* a batch — those messages live in
+ * **neither** a header nor a trailer is *not* a batch: those messages live in
  * {@link BatchSplitResult.messages} only, so they never inflate a batch count.
  * `declaredMessageCount` is BTS-1 when the trailer declared a usable
  * non-negative integer (it is **optional [0..1]** in the spec, so it may be
@@ -5761,7 +6735,7 @@ interface Batch {
 }
 /**
  * The result of {@link splitBatch}: the flattened `messages` (every message
- * across every batch, in stream order — the primary surface), the nested
+ * across every batch, in stream order: the primary surface), the nested
  * `batches`, the raw file envelope segments, and the batch-level `warnings`
  * (count-mismatch / missing-trailer). `hadEnvelope` is `false` for a bare
  * passthrough (no FHS/BHS/BTS/FTS seen).
@@ -5777,7 +6751,7 @@ interface Batch {
  */
 interface BatchSplitResult {
     /**
-     * Every message split out of the stream, in order — the primary surface. This
+     * Every message split out of the stream, in order: the primary surface. This
      * includes messages that belong to no explicit batch (a bare stream, or
      * content outside any `BHS`/`BTS`), so it is a superset of the messages
      * reachable via `batches`.
@@ -5806,16 +6780,16 @@ interface BatchSplitResult {
  * - handles a file with **multiple batches** and a batch with multiple messages;
  * - a **bare single message** (no envelope) passes straight through as one entry;
  * - a **malformed message mid-batch is isolated** (returned as a typed failure
- *   entry) — its siblings are still returned, the tail is never dropped;
+ *   entry): its siblings are still returned, the tail is never dropped;
  * - reconciles BTS-1 (batch message count) and FTS-1 (file batch count) and
- *   emits {@link batchCountMismatch} on a mismatch — counts only, never PHI;
+ *   emits {@link batchCountMismatch} on a mismatch: counts only, never PHI;
  * - emits {@link batchMissingTrailer} when a `BHS`/`FHS` header opens a scope no
- *   `BTS`/`FTS` closes — a warning, never a throw (the caller decides to reject).
+ *   `BTS`/`FTS` closes: a warning, never a throw (the caller decides to reject).
  *
  * The second argument, when given, is forwarded verbatim to {@link parseHL7}
  * for **each** message (profile, `strict`, `charset`, `dateFormats`, …). Under
  * `strict`, a message that would warn surfaces as a failure entry (still
- * isolated). `splitBatch` itself never throws — an empty stream yields an empty
+ * isolated). `splitBatch` itself never throws: an empty stream yields an empty
  * result.
  *
  * @example
@@ -5833,13 +6807,622 @@ interface BatchSplitResult {
  * for (const entry of messages) {
  *   if (entry.ok) console.log(entry.message.version); // "2.5"
  * }
- * console.log(warnings.length); // 0 — declared counts match
+ * console.log(warnings.length); // 0: declared counts match
  * ```
  */
 declare function splitBatch(raw: string | Buffer): BatchSplitResult;
 declare function splitBatch(raw: string | Buffer, profile: Profile): BatchSplitResult;
 declare function splitBatch(raw: string | Buffer, options: ParseOptions): BatchSplitResult;
 
+/**
+ * Public types for the conformance-profile engine (roadmap Phase U). A
+ * **consumer authors** a declarative {@link ConformanceProfile}: a bounded
+ * subset of the HL7 v2 Message-Profile / NIST-IGAMT model (usage codes,
+ * cardinality, length, value-set binding against a consumer-supplied code
+ * list): and {@link validateAgainstProfile} runs it against a parsed message,
+ * returning typed {@link ConformanceFinding}s.
+ *
+ * This is the **sanctioned functionality-plane replacement for the retired
+ * vendor-corpus arc**: instead of hl7 shipping vendor/IHE/regulatory profiles
+ * or code sets, the consumer brings their own interface spec and hl7 validates
+ * against it. hl7 ships **no** profile, **no** code set, and makes **no**
+ * network call: the profile and every value set are supplied by the caller.
+ *
+ * Two invariants govern the whole surface:
+ *
+ * 1. **"No findings" is NOT a conformance attestation.** An empty
+ *    {@link ConformanceResult.findings} means "nothing THIS profile checked was
+ *    violated": never "this message is conformant." The profile only covers
+ *    what the author declared; everything undeclared is unchecked.
+ * 2. **No PHI in findings.** A finding names the structural **locus** (segment
+ *    name, field / component index, repetition, occurrence) and the rule that
+ *    fired: **never** the offending field value. A "value not in set" finding
+ *    says *where* and *which value set*, never *what the value was*.
+ *
+ * @see validateAgainstProfile
+ */
+/**
+ * The six HL7 v2 conformance **usage codes** (HL7 Conformance Methodology,
+ * Message Profiles; IHE ITI TF Vol.2 Appendix C). They constrain whether an
+ * element must, may, or must not appear:
+ *
+ * - **`R`**: Required. The element SHALL be present (with a value). Absent →
+ *   {@link FINDING_CODES.PROFILE_REQUIRED_ABSENT}.
+ * - **`RE`**: Required but may be Empty. The element is supported and SHALL be
+ *   sent when the sender has the data; its **absence is never a violation**
+ *   (this engine cannot know whether the sender had the data).
+ * - **`C`**: Conditional. Presence depends on a predicate. This bounded engine
+ *   ships **no predicate language** (a documented defer: roadmap §5), so a
+ *   `C` element's **presence is not evaluated** (treated as optional); its
+ *   length / value-set / cardinality rules still apply when it IS present.
+ * - **`CE`**: Conditional but may be Empty. Same non-evaluation as `C`.
+ * - **`O`**: Optional. No presence constraint.
+ * - **`X`**: Not supported / not permitted. The element SHALL NOT be present.
+ *   Present → {@link FINDING_CODES.PROFILE_NOT_PERMITTED}.
+ *
+ * @example
+ * ```ts
+ * import type { UsageCode } from "@cosyte/hl7";
+ * const usage: UsageCode = "R";
+ * ```
+ */
+type UsageCode = "R" | "RE" | "C" | "CE" | "O" | "X";
+/**
+ * The frozen set of valid {@link UsageCode}s, for runtime validation and
+ * introspection. `USAGE_CODES.R === "R"`.
+ *
+ * @example
+ * ```ts
+ * import { USAGE_CODES } from "@cosyte/hl7";
+ * USAGE_CODES.includes("R" as const); // true
+ * ```
+ */
+declare const USAGE_CODES: readonly UsageCode[];
+/**
+ * A repetition-count constraint. `min` / `max` are inclusive bounds on the
+ * number of repetitions (for a field rule) or occurrences (for a segment
+ * rule). `max` may be the literal `"*"` for "unbounded". Omitted bounds are
+ * unconstrained on that side.
+ *
+ * **Cardinality `min` is checked only when the element is present.** An absent
+ * **Required** element is reported as {@link FINDING_CODES.PROFILE_REQUIRED_ABSENT}
+ * (a usage finding), not a cardinality finding: so a missing `R` field with
+ * `cardinality.min = 1` yields exactly one finding, never two.
+ *
+ * @example
+ * ```ts
+ * import type { Cardinality } from "@cosyte/hl7";
+ * const once: Cardinality = { min: 1, max: 1 };
+ * const many: Cardinality = { min: 1, max: "*" };
+ * ```
+ */
+interface Cardinality {
+    readonly min?: number;
+    readonly max?: number | "*";
+}
+/**
+ * A rule for one **field position** within a segment (roadmap Phase U). Every
+ * constraint is optional; a rule with only a `field` index is a no-op.
+ *
+ * @remarks
+ * `field` is the 1-indexed HL7 position (MSH offset handled internally, exactly
+ * like `Segment.field(n)`: `{ field: 9 }` on `MSH` targets MSH-9). Length and
+ * value-set checks read the value at `component` (default **1**), so a coded
+ * field's code (`CWE.1` / `CE.1`) is checked by default; set `component` to
+ * check a different component. Both are applied **per present repetition**.
+ */
+interface FieldRule {
+    /** 1-indexed HL7 field position (e.g. `3` for PID-3, `9` for MSH-9). */
+    readonly field: number;
+    /**
+     * Optional human label for the field (e.g. `"Patient Identifier List"`).
+     * Structural documentation for the profile author only: findings identify a
+     * field by its PHI-free structural locus (segment + index), never by this
+     * label, so the label is never echoed into a finding message.
+     */
+    readonly name?: string;
+    /** Usage constraint (see {@link UsageCode}). Omitted ⇒ Optional. */
+    readonly usage?: UsageCode;
+    /** Repetition-count constraint for this field. */
+    readonly cardinality?: Cardinality;
+    /** Maximum character length of the checked component value (inclusive). */
+    readonly length?: number;
+    /**
+     * Consumer-supplied permitted-value list. The checked component value must be
+     * a member (case-sensitive exact match). **hl7 ships no code set**: this is
+     * BYO terminology; membership is a literal string check, never a LOINC /
+     * SNOMED / ICD / RxNorm lookup and never a network call.
+     */
+    readonly valueSet?: readonly string[];
+    /**
+     * 1-indexed component whose value the `length` / `valueSet` checks read.
+     * Defaults to `1` (the first component: a coded element's code).
+     */
+    readonly component?: number;
+    /**
+     * Severity for findings this rule produces. Defaults to `"error"`. A profile
+     * author can downgrade a data-quality rule (e.g. a length or value-set check)
+     * to `"warning"` or `"info"` without changing the check itself.
+     */
+    readonly severity?: FindingSeverity;
+}
+/**
+ * A rule for one **segment type** (roadmap Phase U). `usage` constrains whether
+ * the segment must / must not appear; `cardinality` constrains how many times;
+ * `fields` are the per-field rules, applied to **every** occurrence of the
+ * segment.
+ */
+interface SegmentRule {
+    /** Segment name: 3 chars, `[A-Z][A-Z0-9]{2}` (standard or `Z…` segment). */
+    readonly segment: string;
+    /**
+     * Usage for the segment as a whole. `R` ⇒ at least one occurrence required;
+     * `X` ⇒ none permitted; `RE` / `O` ⇒ no presence constraint; `C` / `CE` ⇒
+     * presence not evaluated (no predicate language). Omitted ⇒ Optional.
+     */
+    readonly usage?: UsageCode;
+    /** Occurrence-count constraint for this segment across the message. */
+    readonly cardinality?: Cardinality;
+    /** Per-field rules, applied to each occurrence of this segment. */
+    readonly fields?: readonly FieldRule[];
+    /** Severity for the segment-level presence / cardinality findings. Default `"error"`. */
+    readonly severity?: FindingSeverity;
+}
+/**
+ * A **user-authored, declarative** conformance profile (roadmap Phase U). The
+ * consumer supplies this; hl7 ships none. It is a bounded subset of the HL7 v2
+ * Message-Profile model: usage / cardinality / length / consumer-supplied
+ * value set: with **no** conditional-predicate language, **no** bundled code
+ * set, and **no** network binding (all deliberate scope boundaries).
+ *
+ * @example
+ * ```ts
+ * import type { ConformanceProfile } from "@cosyte/hl7";
+ *
+ * // A minimal ADT profile the CONSUMER authors: example, NOT an attestation.
+ * const profile: ConformanceProfile = {
+ *   name: "example-adt-min",
+ *   segments: [
+ *     { segment: "MSH", usage: "R", fields: [{ field: 10, name: "Control ID", usage: "R" }] },
+ *     { segment: "PID", usage: "R", cardinality: { min: 1, max: 1 }, fields: [
+ *       { field: 3, name: "Patient Identifiers", usage: "R", cardinality: { min: 1, max: 1 } },
+ *       { field: 8, name: "Administrative Sex", usage: "RE", valueSet: ["M", "F", "U"] },
+ *     ] },
+ *     { segment: "ZZZ", usage: "X" },
+ *   ],
+ * };
+ * ```
+ */
+interface ConformanceProfile {
+    /** A name for provenance: echoed into {@link ConformanceResult.profileName}. */
+    readonly name: string;
+    /** The segment rules, evaluated in array order (stable finding order). */
+    readonly segments: readonly SegmentRule[];
+}
+/**
+ * Severity of a {@link ConformanceFinding}. `error` is a constraint violation;
+ * `warning` / `info` are author-downgraded advisories (via a rule's
+ * `severity`). {@link FINDING_CODES.PROFILE_MALFORMED} is always `error`.
+ */
+type FindingSeverity = "error" | "warning" | "info";
+/**
+ * The frozen registry of finding codes. Stable, additive string codes: a
+ * consumer compares `finding.code === FINDING_CODES.PROFILE_REQUIRED_ABSENT`.
+ * Segment-level vs field-level is disambiguated by whether the finding's
+ * {@link FindingLocus.field} is present, not by separate codes.
+ *
+ * @example
+ * ```ts
+ * import { validateAgainstProfile, FINDING_CODES } from "@cosyte/hl7";
+ * const { findings } = validateAgainstProfile(msg, profile);
+ * const missing = findings.filter((f) => f.code === FINDING_CODES.PROFILE_REQUIRED_ABSENT);
+ * ```
+ */
+declare const FINDING_CODES: {
+    /** A Required (`R`) segment or field is absent (or present-but-empty). */
+    readonly PROFILE_REQUIRED_ABSENT: "PROFILE_REQUIRED_ABSENT";
+    /** A Not-permitted (`X`) segment or field is present. */
+    readonly PROFILE_NOT_PERMITTED: "PROFILE_NOT_PERMITTED";
+    /** A segment-occurrence or field-repetition count is outside its cardinality. */
+    readonly PROFILE_CARDINALITY: "PROFILE_CARDINALITY";
+    /** A checked component value exceeds the declared maximum length. */
+    readonly PROFILE_LENGTH: "PROFILE_LENGTH";
+    /** A checked component value is not a member of the consumer-supplied value set. */
+    readonly PROFILE_VALUE_NOT_IN_SET: "PROFILE_VALUE_NOT_IN_SET";
+    /** The profile ITSELF is structurally malformed (a diagnostic, not a message finding). */
+    readonly PROFILE_MALFORMED: "PROFILE_MALFORMED";
+};
+/**
+ * Discriminant union of every {@link ConformanceFinding} code. Enables
+ * exhaustive `switch` narrowing (the `switch-exhaustiveness-check` lint rule).
+ */
+type FindingCode = (typeof FINDING_CODES)[keyof typeof FINDING_CODES];
+/**
+ * The **structural** locus a finding refers to: segment name plus, where
+ * applicable, the field position, component, repetition, and segment
+ * occurrence. Every member is a name or an index: a locus is **inherently
+ * PHI-free** and never carries a field value.
+ *
+ * A finding with no {@link field} is **segment-level** (presence / cardinality
+ * of the segment itself); a finding with a `field` is **field-level**. For a
+ * {@link FINDING_CODES.PROFILE_MALFORMED} diagnostic (a defect in the profile,
+ * not the message) `segment` may be the sentinel `"(profile)"`.
+ */
+interface FindingLocus {
+    /** Segment name (e.g. `"PID"`), or `"(profile)"` for a profile-shape defect. */
+    readonly segment: string;
+    /** 1-indexed field position, when the finding is field-level. */
+    readonly field?: number;
+    /** 1-indexed component, when a component-scoped check (length / value-set) fired. */
+    readonly component?: number;
+    /** 0-indexed field repetition, when the finding is repetition-scoped. */
+    readonly repetition?: number;
+    /** 0-indexed segment occurrence, when the segment type repeats. */
+    readonly occurrence?: number;
+}
+/**
+ * One typed conformance finding. Carries the {@link FindingCode}, a
+ * {@link FindingSeverity}, the structural {@link FindingLocus}, and a
+ * human-readable `message` describing the rule that fired.
+ *
+ * **The `message` is PHI-safe by construction**: it names the locus, the rule,
+ * and (for a value-set miss) the SIZE of the value set, but **never** the
+ * offending field value.
+ *
+ * @example
+ * ```ts
+ * import type { ConformanceFinding } from "@cosyte/hl7";
+ * const f: ConformanceFinding = {
+ *   code: "PROFILE_VALUE_NOT_IN_SET",
+ *   severity: "error",
+ *   locus: { segment: "PID", field: 8, component: 1 },
+ *   message: 'PID-8 component 1 value is not in the profile value set (3 permitted codes).',
+ * };
+ * ```
+ */
+interface ConformanceFinding {
+    readonly code: FindingCode;
+    readonly severity: FindingSeverity;
+    readonly locus: FindingLocus;
+    readonly message: string;
+}
+/**
+ * The result of {@link validateAgainstProfile}: the profile's `name` and the
+ * ordered list of `findings`.
+ *
+ * **`findings.length === 0` is NOT a conformance attestation.** It means every
+ * rule the profile declared was satisfied: nothing about the parts of the
+ * message the profile did not cover, and nothing about clinical correctness.
+ * Read it as "no declared rule was violated," never as "conformant."
+ */
+interface ConformanceResult {
+    readonly profileName: string;
+    readonly findings: readonly ConformanceFinding[];
+}
+
+/**
+ * The conformance-profile engine (roadmap Phase U): `validateAgainstProfile`.
+ * Runs a **consumer-authored** declarative {@link ConformanceProfile} against a
+ * parsed {@link Hl7Message} and returns typed {@link ConformanceFinding}s.
+ *
+ * The sanctioned functionality-plane replacement for the retired vendor-corpus
+ * arc: the consumer brings the profile and every value set; hl7 ships **no**
+ * profile, **no** code set, and makes **no** network call. Four invariants the
+ * engine holds absolutely:
+ *
+ * 1. **Never throws.** Any message × any profile (even a malformed profile, or a
+ *    value cast through `any`) yields a {@link ConformanceResult}, never an
+ *    exception. A malformed profile becomes `PROFILE_MALFORMED` findings.
+ * 2. **Valid ⇒ zero findings**, and **zero findings is NOT an attestation**,
+ *    it means no *declared* rule was violated, nothing more (see
+ *    {@link ConformanceResult}).
+ * 3. **No PHI in findings.** Findings name the structural locus and the rule,
+ *    never the offending value (see `src/conformance/findings.ts`).
+ * 4. **Read-only.** Validation never mutates the message.
+ */
+
+/**
+ * Validate a parsed HL7 v2 message against a **user-authored** declarative
+ * conformance profile (roadmap Phase U) and return typed findings.
+ *
+ * **Never throws.** A well-formed profile is evaluated rule by rule; a
+ * malformed profile is reported as `PROFILE_MALFORMED` findings (the engine
+ * does not validate against a profile it cannot trust: never a silent pass).
+ * Either way you get a {@link ConformanceResult}. For fail-fast authoring, run
+ * {@link defineConformanceProfile} first: it throws on a malformed profile.
+ *
+ * **`findings.length === 0` is NOT a conformance attestation.** It means every
+ * rule the profile declared was satisfied: nothing about the parts of the
+ * message the profile did not cover, and nothing about clinical correctness.
+ *
+ * **No PHI in findings**: each finding names the structural locus (segment /
+ * field / component / repetition) and the rule, never the offending value.
+ *
+ * **Read-only**: the message is never mutated.
+ *
+ * @param message - a parsed message from {@link parseHL7}.
+ * @param profile - the consumer's declarative {@link ConformanceProfile}.
+ * @returns the profile name and the ordered findings (empty ⇒ no declared rule violated).
+ *
+ * @example
+ * ```ts
+ * import { parseHL7, validateAgainstProfile, type ConformanceProfile } from "@cosyte/hl7";
+ *
+ * const profile: ConformanceProfile = {
+ *   name: "example-adt-min",
+ *   segments: [
+ *     { segment: "PID", usage: "R", fields: [
+ *       { field: 3, name: "Patient Identifiers", usage: "R" },
+ *       { field: 8, name: "Administrative Sex", usage: "RE", valueSet: ["M", "F", "U"] },
+ *     ] },
+ *   ],
+ * };
+ *
+ * const msg = parseHL7(raw);
+ * const { findings } = validateAgainstProfile(msg, profile);
+ * for (const f of findings) console.log(f.severity, f.code, f.message);
+ * // findings.length === 0 ⇒ no declared rule violated (NOT an attestation)
+ * ```
+ */
+declare function validateAgainstProfile(message: Hl7Message, profile: ConformanceProfile): ConformanceResult;
+
+/**
+ * Profile-shape validation for the conformance engine (roadmap Phase U). A
+ * conformance profile is **consumer-authored configuration**, so it can be
+ * malformed. Two entry points share one total defect collector:
+ *
+ * - {@link collectProfileDefects}: **total over `unknown`, never throws.** It
+ *   returns a list of structural {@link ProfileDefect}s (empty ⇒ well-formed).
+ *   {@link validateAgainstProfile} calls it first and, on any defect, returns
+ *   `PROFILE_MALFORMED` findings instead of validating a profile it cannot
+ *   trust (never a silent pass).
+ * - {@link defineConformanceProfile}: the **fail-fast authoring** helper. It
+ *   runs the same collector and **throws {@link ProfileDefinitionError}** on the
+ *   first-through-all defects, returning the profile typed on success. Use it at
+ *   profile-authoring time; the engine itself never throws (task invariant).
+ *
+ * A defect `detail` describes the profile's SHAPE (`segments[2].fields[0].field
+ * must be a positive integer`): profile structure only, never PHI.
+ *
+ * @internal (the two functions are re-exported from the package root)
+ */
+
+/**
+ * One structural defect in a profile: the PHI-free `detail` plus a best-effort
+ * {@link FindingLocus} (so the engine can attach it to a `PROFILE_MALFORMED`
+ * finding). When the defect is above segment level, `locus.segment` is the
+ * sentinel `"(profile)"`.
+ *
+ * @internal
+ */
+interface ProfileDefect {
+    readonly locus: FindingLocus;
+    readonly detail: string;
+}
+/**
+ * Collect every structural defect in a candidate conformance profile. **Total
+ * over `unknown` and never throws**: a caller may pass any value (even one
+ * cast through `any`) and get back a defect list rather than an exception. An
+ * empty result means the profile is well-formed enough to validate against.
+ *
+ * @internal
+ */
+declare function collectProfileDefects(profile: unknown): readonly ProfileDefect[];
+/**
+ * The **fail-fast authoring** gate for a conformance profile (roadmap Phase U's
+ * "malformed profile → typed `ProfileDefinitionError`, build-time, before
+ * validation"). Runs {@link collectProfileDefects}; on any defect, throws a
+ * single {@link ProfileDefinitionError} listing every defect. On success,
+ * returns the profile typed as {@link ConformanceProfile}.
+ *
+ * This is **optional**: {@link validateAgainstProfile} tolerates a raw profile
+ * object and never throws: but it lets an author catch a typo when the profile
+ * is written rather than when it is run.
+ *
+ * @throws {ProfileDefinitionError} when the profile is structurally malformed.
+ *
+ * @example
+ * ```ts
+ * import { defineConformanceProfile } from "@cosyte/hl7";
+ * const profile = defineConformanceProfile({
+ *   name: "example-adt-min",
+ *   segments: [{ segment: "PID", usage: "R" }],
+ * });
+ * // A typo throws at authoring time:
+ * // defineConformanceProfile({ name: "x", segments: [{ segment: "pid" }] });
+ * //   → ProfileDefinitionError: segments[0].segment must be a valid segment name…
+ * ```
+ */
+declare function defineConformanceProfile(profile: unknown): ConformanceProfile;
+
+/**
+ * Barrel for the conformance-profile engine (roadmap Phase U). Re-exports the
+ * engine, the fail-fast profile-authoring gate, and the public types. Also
+ * available as the `conformance` namespace object from the package root.
+ *
+ * @see validateAgainstProfile: run a user-authored profile against a message.
+ * @see defineConformanceProfile: optional fail-fast profile-authoring gate.
+ */
+
+type index_Cardinality = Cardinality;
+type index_ConformanceFinding = ConformanceFinding;
+type index_ConformanceProfile = ConformanceProfile;
+type index_ConformanceResult = ConformanceResult;
+declare const index_FINDING_CODES: typeof FINDING_CODES;
+type index_FieldRule = FieldRule;
+type index_FindingCode = FindingCode;
+type index_FindingLocus = FindingLocus;
+type index_FindingSeverity = FindingSeverity;
+type index_ProfileDefect = ProfileDefect;
+type index_SegmentRule = SegmentRule;
+declare const index_USAGE_CODES: typeof USAGE_CODES;
+type index_UsageCode = UsageCode;
+declare const index_collectProfileDefects: typeof collectProfileDefects;
+declare const index_defineConformanceProfile: typeof defineConformanceProfile;
+declare const index_validateAgainstProfile: typeof validateAgainstProfile;
+declare namespace index {
+  export { type index_Cardinality as Cardinality, type index_ConformanceFinding as ConformanceFinding, type index_ConformanceProfile as ConformanceProfile, type index_ConformanceResult as ConformanceResult, index_FINDING_CODES as FINDING_CODES, type index_FieldRule as FieldRule, type index_FindingCode as FindingCode, type index_FindingLocus as FindingLocus, type index_FindingSeverity as FindingSeverity, type index_ProfileDefect as ProfileDefect, type index_SegmentRule as SegmentRule, index_USAGE_CODES as USAGE_CODES, type index_UsageCode as UsageCode, index_collectProfileDefects as collectProfileDefects, index_defineConformanceProfile as defineConformanceProfile, index_validateAgainstProfile as validateAgainstProfile };
+}
+
+/**
+ * Streaming / incremental parse for the `@cosyte/hl7` parser (roadmap
+ * Phase S). Real ELR / IIS / lab feeds and files ship many messages and can be
+ * far too large to buffer whole; a live source (an already-de-framed MLLP feed,
+ * a growing file) has no "whole" to buffer at all. `parseStream()` consumes a
+ * **chunked** byte/string source: a Node `Readable`, an async-iterable, or a
+ * plain iterable of chunks: and **yields one {@link StreamMessageEntry} per
+ * `MSH`-delimited message** as each boundary completes, holding only
+ * **O(one message)** of state (the in-flight message's lines plus the current
+ * partial-segment buffer): never the whole stream.
+ *
+ * Design (HL7 v2 Ch. 2; note this is engineering guidance, not a spec-mandated
+ * streaming grammar: the base standard prescribes no incremental parse):
+ *
+ * - **`MSH` at segment start is the message boundary.** A message runs from an
+ *   `MSH` segment up to (but not including) the next `MSH` (or a batch-envelope
+ *   segment, or end of stream). This mirrors {@link splitBatch}'s in-memory
+ *   demarcation exactly, so the streamed decomposition of a buffer is identical
+ *   to the whole-buffer one.
+ * - **Batch-aware.** The four batch-envelope segments (`FHS`/`BHS`/`BTS`/`FTS`,
+ *   §2.10.3) act as message boundaries (they flush the current message) and are
+ *   **never yielded as messages**, so `yielded count == MSH count`. Envelope
+ *   **count reconciliation** (BTS-1 / FTS-1) is {@link splitBatch}'s job, not this
+ *   surface's: `parseStream` streams *messages*, not a batch report.
+ * - **Chunk-boundary invariant.** Segments (including the `MSH|^~\&` header) are
+ *   only demarcated once their terminator arrives, so a message split across two
+ *   chunks (mid-segment, mid-field, even mid-`MSH`) is reassembled correctly.
+ *   Feeding the same bytes in 1-byte chunks vs. one big chunk yields **identical**
+ *   messages. A `\r\n` terminator split across a chunk boundary is not mistaken
+ *   for a bare `\r` + empty segment (a trailing `\r` waits for the next chunk).
+ * - **Terminator tolerance.** `\r`, `\r\n`, and `\n` are all accepted as segment
+ *   terminators (Postel's Law: real feeds mix them), matching the core parser's
+ *   `normalize`.
+ * - **Isolation, never dropped tails.** Each message is parsed by the shipped
+ *   {@link parseHL7} (no second grammar; raw extraction semantics unchanged) and
+ *   surfaced as either an `ok` entry (its own `.warnings` hold per-message
+ *   deviations) or a typed **failure** entry carrying the `Hl7ParseError`. A
+ *   corrupt message mid-stream is isolated: it **never suppresses** the messages
+ *   after it. A final message that ends without a segment terminator is still
+ *   yielded in full, flagged via a stream-level {@link unterminatedStreamMessage}
+ *   warning (never a throw), so a truncated feed is surfaced, never silently
+ *   dropped.
+ *
+ * Transport framing (MLLP `<SB>…<EB><CR>`) is **out of scope**: this consumes an
+ * already-de-framed stream; `@cosyte/mllp` owns the wire. See
+ * `docs-content/spec-notes-stream.md`.
+ */
+
+/**
+ * A chunked source `parseStream` can consume: a Node `Readable`, any
+ * async-iterable, or any plain iterable of chunks. Chunks are `string`
+ * (text stream) or `Buffer`/`Uint8Array` (binary stream). A real Node stream in
+ * binary mode yields `Buffer`s; in text mode it yields `string`s: a source is
+ * expected to be **homogeneous** (all-text or all-binary), which every real
+ * `Readable` is. A binary chunk is decoded 1:1 via `latin1` (a lossless
+ * byte↔codepoint mapping) so each message's own MSH-18 charset resolution runs
+ * on its original bytes, exactly as {@link splitBatch} does.
+ *
+ * @example
+ * ```ts
+ * import { createReadStream } from "node:fs";
+ * import { parseStream } from "@cosyte/hl7";
+ *
+ * const src: Hl7StreamSource = createReadStream("feed.hl7");
+ * for await (const entry of parseStream(src)) {
+ *   if (entry.ok) handle(entry.message);
+ *   else quarantine(entry.raw, entry.error.code);
+ * }
+ * ```
+ */
+type Hl7StreamSource = AsyncIterable<string | Buffer | Uint8Array> | Iterable<string | Buffer | Uint8Array>;
+/**
+ * One message yielded by {@link parseStream}. Discriminated on `ok`, mirroring
+ * {@link splitBatch}'s per-message entry: a successful parse carries the
+ * `Hl7Message` (whose own `.warnings` hold per-message Tier-2 deviations); a
+ * message that hit one of the four Tier-3 fatals carries the `Hl7ParseError`
+ * instead: **isolated**, so the rest of the stream still yields.
+ *
+ * `raw` is the message's verbatim source (re-parseable by {@link parseHL7});
+ * `position.segmentIndex` is the message's `MSH` (or, for stray pre-`MSH`
+ * content, its first) segment index in the overall stream: the streaming
+ * analogue of {@link splitBatch}'s message position. `streamWarnings` holds
+ * **stream-level** diagnostics that are not per-message parse warnings: today
+ * only {@link unterminatedStreamMessage} on a final message that lacked a
+ * terminator. It is kept separate from `message.warnings` (which stays exactly
+ * what a whole-buffer `parseHL7` of the same bytes would produce) and is
+ * **empty** for every message but a possibly-truncated final one. Both the entry
+ * and `streamWarnings` are frozen.
+ *
+ * @example
+ * ```ts
+ * import { parseStream, WARNING_CODES } from "@cosyte/hl7";
+ * for await (const entry of parseStream(source)) {
+ *   for (const w of entry.streamWarnings) {
+ *     if (w.code === WARNING_CODES.UNTERMINATED_STREAM_MESSAGE) {
+ *       // the feed may have been cut off mid-message
+ *     }
+ *   }
+ * }
+ * ```
+ */
+type StreamMessageEntry = {
+    readonly ok: true;
+    readonly message: Hl7Message;
+    readonly raw: string;
+    readonly position: Hl7Position;
+    readonly streamWarnings: readonly Hl7ParseWarning[];
+} | {
+    readonly ok: false;
+    readonly error: Hl7ParseError;
+    readonly raw: string;
+    readonly position: Hl7Position;
+    readonly streamWarnings: readonly Hl7ParseWarning[];
+};
+/**
+ * Incrementally parse a chunked HL7 v2 byte / text stream, yielding one
+ * {@link StreamMessageEntry} per `MSH`-delimited message as its boundary
+ * completes, with **O(one-message)** memory: the whole stream is never
+ * retained. Demarcates by `MSH` boundaries inside the optional
+ * `[FHS] { [BHS] { MSH… } [BTS] } [FTS]` batch frame (HL7 v2 Ch. 2 §2.10.3):
+ *
+ * - a message split across chunk boundaries (mid-segment, mid-field, even
+ *   mid-`MSH|^~\&`) is reassembled correctly: feeding the same bytes in 1-byte
+ *   chunks vs. one chunk yields **identical** messages;
+ * - `\r`, `\r\n`, and `\n` segment terminators are all tolerated (a `\r\n` split
+ *   across a chunk boundary is not mistaken for a bare `\r`);
+ * - each message is parsed by the shipped {@link parseHL7} (no second grammar),
+ *   `ok` entries carry the `Hl7Message`, a Tier-3 fatal is an isolated failure
+ *   entry; a **malformed message never suppresses later messages**;
+ * - batch-envelope segments (`FHS`/`BHS`/`BTS`/`FTS`) are treated as boundaries
+ *   and never yielded as messages, so `yielded count == MSH count` (envelope
+ *   count reconciliation is {@link splitBatch}'s job);
+ * - a final message with no trailing terminator is still yielded, flagged with a
+ *   stream-level {@link unterminatedStreamMessage} warning: **never a throw, the
+ *   tail is never dropped**.
+ *
+ * The second argument, when given, is forwarded verbatim to {@link parseHL7} for
+ * **each** message (profile, `strict`, `charset`, `dateFormats`, …), exactly as
+ * {@link splitBatch} forwards it.
+ *
+ * @example
+ * ```ts
+ * import { parseStream } from "@cosyte/hl7";
+ *
+ * async function* chunks() {
+ *   yield "MSH|^~\\&|A|F|B|G|20260101||ADT^A01|1|P|2.5\rPID|||1\r";
+ *   yield "MSH|^~\\&|A|F|B|G|20260101||ADT^A01|2|P|2.5\rPID|||2\r";
+ * }
+ *
+ * let count = 0;
+ * for await (const entry of parseStream(chunks())) {
+ *   if (entry.ok) count += 1; // 2: one per MSH, streamed, released each time
+ * }
+ * ```
+ */
+declare function parseStream(source: Hl7StreamSource): AsyncGenerator<StreamMessageEntry, void, void>;
+declare function parseStream(source: Hl7StreamSource, profile: Profile): AsyncGenerator<StreamMessageEntry, void, void>;
+declare function parseStream(source: Hl7StreamSource, options: ParseOptions): AsyncGenerator<StreamMessageEntry, void, void>;
+
 /**
  * Public entry point for the `@cosyte/hl7` package.
  *
@@ -5861,4 +7444,4 @@ declare function splitBatch(raw: string | Buffer, options: ParseOptions): BatchS
  */
 declare const VERSION: string;
 
-export { ACK_CODES, ACK_CONDITIONS, type AckCode, type AckCondition, type AckErrorDetail, type AckErrorEntry, type AckMode, type Acknowledgment, type Allergy, type Appointment, type AppointmentResource, BUILTIN_DATE_FALLBACKS, type Batch, type BatchEnvelopeName, type BatchEnvelopeSegment, type BatchMessageEntry, type BatchSplitResult, type BuildAckOptions, type BuildMessageInit, type CE, type CWE, type CX, type Charge, type CharsetResolution, type CharsetTreatment, type ClinicalDocument, type CodedSystemFields, type CodingSystemInfo, type CustomSegmentDefinition, DEFAULT_ENCODING_CHARACTERS, type DefineProfileOptions, type Diagnosis, type DotPath, type DtmParts, type DtmPrecision, type DtmToDateOptions, ERR_CONDITION_CODES, ERR_CONDITION_CODE_SYSTEM, ERR_SEVERITIES, type EncodingCharacters, type ErrSeverity, type ExpectedSegmentGroup, FATAL_CODES, type FatalCode, Field, type HD, namespace as HL7, Hl7Message, Hl7ParseError, type Hl7ParseWarning, type Hl7Position, type IdentityEvent, type IdentityEventKind, type IdentityParty, type IdentityRole, type Immunization, type ImmunizationRecordOrigin, type Insurance, KNOWN_CODING_SYSTEMS, KNOWN_SEGMENTS, type KnownCodingSystem, MESSAGE_STRUCTURE_DEFINITIONS, type Medication, type MedicationAmount, type MedicationComponent, type MedicationContext, type MedicationRoute, type MedicationStrength, type MessageStructure, type MessageStructureDefinition, type Meta, type NM, type NextOfKin, type Observation, type ObservationBase, type OnWarningCallback, type Order, type OrderTiming, type PL, type ParseOptions, type Patient, type Profile, ProfileDefinitionError, type RawComponent, type RawField, type RawRepetition, type RawSegment, type RepeatPattern, type RepeatPatternKind, type SN, SUPPORTED_DATE_TOKENS, Segment, type SerializedMessage, type StructureGroup, type TS, type TimingQuantity, VERSION, type Visit, WARNING_CODES, type WarningCode, type XAD, type XCN, type XPN, type XTN, ackNoCorrelationId, alternateCodingSystemOf, analyzeMessageStructure, batchCountMismatch, batchMissingTrailer, buildAck, buildMessage, canonicalCharset, codingSystem, codingSystemOf, defineProfile, detectAckMode, downgradePositiveAck, dtmToDate, duplicateRequiredSegment, encodingMismatch, extraFields, fieldWhitespaceTrimmed, formatDtm, getDefaultProfile, interpretAck, isPositiveAck, mergeMissingPriorOrSurvivor, missingExpectedGroup, missingRequiredField, mllpFramingStripped, outOfOrderSegment, parseCe, parseCwe, parseCx, parseDtm, parseHL7, parseHd, parseNm, parsePath, parsePl, parseSn, parseTs, parseXad, parseXcn, parseXpn, parseXtn, pickMrn, profiles, reescape, resolveCharset, resolvePath, segmentCase, setDefaultProfile, splitBatch, timestampFallbackFormat, unescape, unknownCharset, unknownEscapeSequence, unknownSegment, unsupportedCharset, unterminatedEscapeSequence, versionMismatch };
+export { ACK_CODES, ACK_CONDITIONS, type AckCode, type AckCondition, type AckErrorDetail, type AckErrorEntry, type AckMode, type Acknowledgment, type AdtEvent, type AdtPatient, type AdtVisit, type Allergy, type Appointment, type AppointmentResource, BUILTIN_DATE_FALLBACKS, type Batch, type BatchEnvelopeName, type BatchEnvelopeSegment, type BatchMessageEntry, type BatchSplitResult, type BuildAckOptions, type BuildAdtInit, type BuildMessageInit, type BuildOruInit, type CE, type CWE, type CX, type Cardinality, type Charge, type CharsetResolution, type CharsetTreatment, type ClinicalDocument, type CodedSystemFields, type CodingSystemInfo, type CompositeKind, type CompositeValueByKind, type ConformanceFinding, type ConformanceProfile, type ConformanceResult, type CustomSegmentDefinition, DEFAULT_ENCODING_CHARACTERS, type DefineProfileOptions, type Diagnosis, type DotPath, type DtmParts, type DtmPrecision, type DtmToDateOptions, ERR_CONDITION_CODES, ERR_CONDITION_CODE_SYSTEM, ERR_SEVERITIES, type EncodingCharacters, type ErrSeverity, type ExpectedSegmentGroup, FATAL_CODES, FINDING_CODES, type FatalCode, Field, type FieldRule, type FindingCode, type FindingLocus, type FindingSeverity, type HD, namespace as HL7, Hl7Message, Hl7ParseError, type Hl7ParseWarning, type Hl7Position, type Hl7StreamSource, type IdentityEvent, type IdentityEventKind, type IdentityParty, type IdentityRole, type Immunization, type ImmunizationRecordOrigin, type Insurance, KNOWN_CODING_SYSTEMS, KNOWN_SEGMENTS, type KnownCodingSystem, MESSAGE_STRUCTURE_DEFINITIONS, type Medication, type MedicationAmount, type MedicationComponent, type MedicationContext, type MedicationRoute, type MedicationStrength, type MessageStructure, type MessageStructureDefinition, type Meta, type NM, type NextOfKin, type Observation, type ObservationBase, type OnWarningCallback, type Order, type OrderTiming, type OruObservation, type OruOrder, type OruPatient, type PL, type ParseOptions, type Patient, type Profile, ProfileDefinitionError, type RawComponent, type RawField, type RawRepetition, type RawSegment, type RenderTextOptions, type RenderedText, type RepeatPattern, type RepeatPatternKind, type SN, SUPPORTED_DATE_TOKENS, Segment, type SegmentRule, type SerializedMessage, type StreamMessageEntry, type StructureGroup, type TS, type TextRun, type TimingQuantity, USAGE_CODES, type UsageCode, VERSION, type Visit, WARNING_CODES, type WarningCode, type XAD, type XCN, type XPN, type XTN, ackNoCorrelationId, alternateCodingSystemOf, analyzeMessageStructure, batchCountMismatch, batchMissingTrailer, buildAck, buildAdt, buildMessage, buildOru, canonicalCharset, codingSystem, codingSystemOf, index as conformance, decodeText, defineConformanceProfile, defineProfile, detectAckMode, downgradePositiveAck, dtmToDate, duplicateRequiredSegment, encodeCe, encodeComposite, encodeCompositeReps, encodeCwe, encodeCx, encodeHd, encodeNm, encodePl, encodeText, encodeTs, encodeXad, encodeXcn, encodeXpn, encodeXtn, encodingMismatch, extraFields, fieldWhitespaceTrimmed, formatDtm, getDefaultProfile, interpretAck, isPositiveAck, mergeMissingPriorOrSurvivor, missingExpectedGroup, missingRequiredField, mllpFramingStripped, outOfOrderSegment, parseCe, parseCwe, parseCx, parseDtm, parseHL7, parseHd, parseNm, parsePath, parsePl, parseSn, parseStream, parseTs, parseXad, parseXcn, parseXpn, parseXtn, pickMrn, profiles, reescape, renderText, resolveCharset, resolvePath, segmentCase, setDefaultProfile, splitBatch, index$1 as text, timestampFallbackFormat, unescape, unknownCharset, unknownEscapeSequence, unknownSegment, unsupportedCharset, unterminatedEscapeSequence, unterminatedStreamMessage, validateAgainstProfile, versionMismatch };