@cosyte/hl7 0.0.2 → 0.0.4

package/dist/index.d.cts

@@ -241,14 +241,15 @@ declare function encodingMismatch(position: Hl7Position, detail: string): Hl7Par
  */
 declare function missingRequiredField(position: Hl7Position, segmentName: string, fieldIndex: number): Hl7ParseWarning;
 /**
- * Build a `MISSING_EXPECTED_GROUP` warning (roadmap Phase G). Emitted once per
+ * Build a `MISSING_EXPECTED_GROUP` warning. 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
  * 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),
- * NEVER a field value, so no PHI is exposed. `position` references MSH-9.
+ * never a field value: the message type is shape-checked before it is
+ * interpolated, and withheld if it does not match. `position` references MSH-9.
  *
  * @example
  * ```ts
@@ -292,8 +293,8 @@ 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
- * PHI is exposed.
+ * message carries the charset code only, never a decoded field value: the code
+ * is shape-checked before it is interpolated, and withheld if it does not match.
  *
  * @example
  * ```ts
@@ -315,8 +316,8 @@ declare function unknownCharset(position: Hl7Position, requested: string): Hl7Pa
  * 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
- * exposed.
+ * carries the charset code only, never a decoded field value: the code is
+ * shape-checked before it is interpolated, and withheld if it does not match.
  *
  * @example
  * ```ts
@@ -326,7 +327,7 @@ declare function unknownCharset(position: Hl7Position, requested: string): Hl7Pa
  */
 declare function unsupportedCharset(position: Hl7Position, code: string): Hl7ParseWarning;
 /**
- * Build an `ACK_NO_CORRELATION_ID` warning. Emitted by `buildAck` (Phase C),
+ * Build an `ACK_NO_CORRELATION_ID` warning. Emitted by `buildAck`,
  * not by the parser: the inbound message carried no MSH-10 message control ID,
  * 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
@@ -342,7 +343,7 @@ 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
+ * Build a `MERGE_MISSING_PRIOR_OR_SURVIVOR` warning. Emitted
  * 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
@@ -368,7 +369,7 @@ 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
+ * Build a `BATCH_COUNT_MISMATCH` warning. Emitted by
  * `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
@@ -392,7 +393,7 @@ 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
+ * Build a `BATCH_MISSING_TRAILER` warning. Emitted by
  * `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**
@@ -413,7 +414,7 @@ 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
+ * Build an `UNTERMINATED_STREAM_MESSAGE` warning. 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
@@ -535,9 +536,8 @@ interface ParseOptions {
  * (`defineProfile()`). `fields` maps a caller-visible field NAME to its
  * 1-indexed HL7 position within the segment. Declared here (alongside
  * `Profile`) to keep the parser's type module the single source of truth;
- * `src/profiles/define.ts` re-exports this type so consumers can write
- * `import type { CustomSegmentDefinition } from "@cosyte/hl7"`
- * after Plan 06's barrel-sweep.
+ * `src/profiles/define.ts` re-exports this type, so consumers can write
+ * `import type { CustomSegmentDefinition } from "@cosyte/hl7"`.
  *
  * @example
  * ```ts
@@ -553,11 +553,10 @@ 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
- * and runtime effects land in Phase 6.
+ * callbacks. Profiles are built with the `defineProfile()` factory.
  *
- * Phase 6 Plan 01 tightens `customSegments` to the locked
- * `CustomSegmentDefinition` shape and adds an optional `describe?` method
+ * `customSegments` is narrowed to the locked `CustomSegmentDefinition` shape,
+ * and `Profile` carries 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`
@@ -737,8 +736,8 @@ interface RawSegment {
 
 /**
  * The HL7 default 5-tuple of encoding characters used when a message does
- * not override them via MSH-1 / MSH-2. Re-used by downstream stages (Plan 04
- * escape map, Plan 06 `parseHL7`) as a synthetic-message fallback.
+ * not override them via MSH-1 / MSH-2. Re-used by downstream stages (the
+ * escape map, `parseHL7`) as a synthetic-message fallback.
  *
  * @example
  * ```ts
@@ -754,7 +753,7 @@ declare const DEFAULT_ENCODING_CHARACTERS: EncodingCharacters;
  * 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
+ * `renderText` is a read projection: it 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
@@ -909,9 +908,9 @@ declare function renderText(input: string, enc?: EncodingCharacters, opts?: Rend
 
 /**
  * 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
- * set to `undefined`.
+ * parsed from a `RawRepetition` on demand by `Field.asCe()`. Fields are
+ * OMITTED when absent (exactOptionalPropertyTypes): NEVER set to
+ * `undefined`.
  *
  * CE is the older, simpler sibling of CWE: 6 components, no version ids,
  * no originalText. Still common in OBX.3 and similar observation-identifier
@@ -964,8 +963,8 @@ 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,
- * HL7-VALUE-REDECODE). Absent / empty components are OMITTED
+ * are returned verbatim (already decoded once by the tokenizer: never
+ * re-unescaped). Absent / empty components are OMITTED
  * from the result (exactOptionalPropertyTypes semantics).
  *
  * @example
@@ -984,9 +983,9 @@ declare function parseCe(rep: RawRepetition, enc: EncodingCharacters): CE;
 
 /**
  * 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),
- * NEVER set to `undefined`.
+ * shape parsed from a `RawRepetition` on demand by `Field.asCwe()`. 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
@@ -1046,8 +1045,8 @@ 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,
- * HL7-VALUE-REDECODE). Absent / empty components are OMITTED
+ * are returned verbatim (already decoded once by the tokenizer: never
+ * re-unescaped). Absent / empty components are OMITTED
  * from the result (exactOptionalPropertyTypes semantics).
  *
  * @example
@@ -1097,8 +1096,8 @@ 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,
- * HL7-VALUE-REDECODE). Absent / empty components are OMITTED
+ * are returned verbatim (already decoded once by the tokenizer: never
+ * re-unescaped). Absent / empty components are OMITTED
  * from the result (exactOptionalPropertyTypes semantics).
  *
  * @example
@@ -1119,7 +1118,7 @@ declare function parseHd(rep: RawRepetition, enc: EncodingCharacters): HD;
 /**
  * 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
+ * demand by `Field.asCx()`. Fields are OMITTED when
  * absent (exactOptionalPropertyTypes): NEVER set to `undefined`.
  *
  * Component 4 (`assigningAuthority`) is the ONE nested-composite field in
@@ -1178,8 +1177,8 @@ 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,
- * HL7-VALUE-REDECODE). Absent / empty components are OMITTED
+ * are returned verbatim (already decoded once by the tokenizer: never
+ * re-unescaped). Absent / empty components are OMITTED
  * from the result (exactOptionalPropertyTypes semantics). Component 4
  * (`assigningAuthority`) is parsed as a nested `HD`; see component table in
  * the `CX` interface JSDoc for the v1 simplifications on components 6/9/10.
@@ -1257,7 +1256,7 @@ 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
  * `entityIdentifier` is rarely used; v2 may restore the full shape) parsed
- * from a `RawRepetition` on demand by `Field.asPl()` (wired in Plan 04).
+ * from a `RawRepetition` on demand by `Field.asPl()`.
  * Fields are OMITTED when absent (exactOptionalPropertyTypes): NEVER set
  * to `undefined`.
  *
@@ -1319,8 +1318,8 @@ 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,
- * HL7-VALUE-REDECODE). Absent / empty components are OMITTED
+ * are returned verbatim (already decoded once by the tokenizer: never
+ * re-unescaped). 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`
  * interface JSDoc for the v1 simplifications.
@@ -1421,15 +1420,15 @@ declare function parseSn(rep: RawRepetition, enc: EncodingCharacters): SN | unde
 /**
  * HL7 v2 TS/DTM datetime handling for the `@cosyte/hl7` parser pipeline.
  *
- * Phase N (datetime precision + timezone fidelity) reworked this module from a
- * `Date`-coercing helper into a **fidelity-first** parser. The HL7 v2 Ch. 2A
+ * This module is a **fidelity-first** datetime parser rather than a
+ * `Date`-coercing helper. 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",
  * 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.
+ * assume-UTC on a missing offset, eager `Date`) is an architectural defect:
+ * 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`),
@@ -1639,13 +1638,12 @@ interface DtmToDateOptions {
 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 parser
  * 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
- * {@link DtmParts}: raw string + typed parts + stated precision + timezone
+ * The composite is fidelity-preserving: rather than a `{ raw, date }` shape
+ * that would zero-fill truncations and assume UTC for a missing offset, it is
+ * a {@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
  * for an offset-less value rather than silently defaulting to UTC.
@@ -1699,9 +1697,9 @@ declare function parseTs(rep: RawRepetition, _enc: EncodingCharacters): TS;
 
 /**
  * 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),
- * NEVER set to `undefined`.
+ * shape parsed from a `RawRepetition` on demand by `Field.asXad()`. Fields
+ * are OMITTED when absent (exactOptionalPropertyTypes), NEVER set to
+ * `undefined`.
  *
  * Zero runtime deps: pure function over the raw positional tree + `unescape`.
  */
@@ -1747,8 +1745,8 @@ 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,
- * HL7-VALUE-REDECODE). Absent / empty components are OMITTED
+ * are returned verbatim (already decoded once by the tokenizer: never
+ * re-unescaped). Absent / empty components are OMITTED
  * from the result (exactOptionalPropertyTypes semantics).
  *
  * @example
@@ -1829,8 +1827,8 @@ 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,
- * HL7-VALUE-REDECODE). Absent / empty components are OMITTED
+ * are returned verbatim (already decoded once by the tokenizer: never
+ * re-unescaped). Absent / empty components are OMITTED
  * from the result (exactOptionalPropertyTypes semantics). Component 9
  * (`assigningAuthority`) is parsed as a nested `HD`; see component table in
  * the `XCN` interface JSDoc for the v1 trimming.
@@ -1864,9 +1862,9 @@ declare function parseXcn(rep: RawRepetition, enc: EncodingCharacters): XCN;
 
 /**
  * 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),
- * NEVER set to `undefined`.
+ * shape parsed from a `RawRepetition` on demand by `Field.asXpn()`. Fields
+ * are OMITTED when absent (exactOptionalPropertyTypes), NEVER set to
+ * `undefined`.
  *
  * Zero runtime deps: pure function over the raw positional tree + `unescape`.
  */
@@ -1916,8 +1914,8 @@ 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,
- * HL7-VALUE-REDECODE). Absent / empty components are OMITTED
+ * are returned verbatim (already decoded once by the tokenizer: never
+ * re-unescaped). Absent / empty components are OMITTED
  * from the result (exactOptionalPropertyTypes semantics).
  *
  * @example
@@ -1938,9 +1936,9 @@ declare function parseXpn(rep: RawRepetition, enc: EncodingCharacters): XPN;
  * 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
- * shape) parsed from a `RawRepetition` on demand by `Field.asXtn()` (wired
- * in Plan 04). Fields are OMITTED when absent (exactOptionalPropertyTypes)
- *: NEVER set to `undefined`.
+ * shape) parsed from a `RawRepetition` on demand by `Field.asXtn()`. Fields
+ * are OMITTED when absent (exactOptionalPropertyTypes): NEVER set to
+ * `undefined`.
  *
  * Zero runtime deps: pure function over the raw positional tree + `unescape`.
  */
@@ -1993,8 +1991,8 @@ 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,
- * HL7-VALUE-REDECODE). Absent / empty components are OMITTED
+ * are returned verbatim (already decoded once by the tokenizer: never
+ * re-unescaped). Absent / empty components are OMITTED
  * from the result (exactOptionalPropertyTypes semantics). Components past
  * position 12 are silently ignored in v1.
  *
@@ -2049,11 +2047,11 @@ declare class Field {
     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 */
+    /** The 5 encoding characters for this message. Exposed for composite parsers. @internal */
     readonly enc: EncodingCharacters;
     /** 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 */
+    /** The full `RawField` this wrapper wraps. Exposed for composite parsers. @internal */
     readonly raw: RawField;
     /**
      * Construct a new `Field`. Called internally by `Segment.field(n)`; user
@@ -2064,7 +2062,7 @@ declare class Field {
     /**
      * First-repetition, first-component, first-subcomponent value as a decoded
      * string: unescaped ONCE by the tokenizer on parse, returned verbatim here
-     * (never re-unescaped, HL7-VALUE-REDECODE). Returns `""` when the field is
+     * (never re-unescaped). Returns `""` when the field is
      * empty or HL7 null. Equivalent to `msg.get('SEG.N')` for a top-level access.
      *
      * @example
@@ -2087,7 +2085,7 @@ declare class Field {
      * vendor-quirk control id containing an unescaped delimiter (`ID^X`) must
      * not be truncated to its first component.
      *
-     * **Byte-verbatim for parsed content (HL7-ESC).** The parse pipeline stores
+     * **Byte-verbatim for parsed content.** The parse pipeline stores
      * *decoded* content, but also records the original wire bytes of any escape
      * whose decode is not byte-faithful (`RawComponent.rawSubcomponents`), so
      * re-serialization preserves the sender's exact escape bytes: hex escapes
@@ -2300,7 +2298,7 @@ declare class Field {
  * calls `new Segment(...)` directly.
  *
  * The wrapper does NOT copy `raw.fields`: it holds a reference so mutations
- * through Plan 04's `setField` / `addSegment` / `removeSegment` stay visible.
+ * through `setField` / `addSegment` / `removeSegment` stay visible.
  */
 
 /**
@@ -2317,7 +2315,24 @@ declare class Field {
  * ```
  */
 declare class Segment {
-    /** Segment name (3 chars, e.g. `"PID"`, `"OBX"`, `"ZPI"`). */
+    /**
+     * Segment identifier: three characters with a leading letter, e.g. `"PID"`,
+     * `"OBX"`, `"ZPI"`.
+     *
+     * **Bounded, and it is `"<withheld>"` when the raw name is not that shape.**
+     * A line with no field separator has its whole content read as a segment
+     * name, so an unescaped line break inside a narrative field forges a
+     * "segment" whose name is clinical text. This field presents itself as a
+     * structural identifier and consumers interpolate it into labels, loci and
+     * reports, so it never carries that text. `""` still means absent, which is
+     * a different fact from withheld.
+     *
+     * Use {@link Segment.raw}`.name` when you need the verbatim text: it is the
+     * unbounded value, and it is what serialization emits, so the byte-verbatim
+     * round-trip is unaffected. One consequence worth knowing: a segment whose
+     * raw name fails the shape (a 4-character vendor Z-segment, which HL7 v2
+     * Ch. 2 §2.5 does not permit) is not matched by `msg.segments(name)`.
+     */
     readonly type: string;
     /** Reference to the underlying `RawSegment.fields`: 1-indexed per HL7 convention. */
     readonly fields: readonly RawField[];
@@ -2325,7 +2340,7 @@ declare class Segment {
     readonly enc: EncodingCharacters;
     /** Absolute index of this segment in `Hl7Message.rawSegments[]`. Used for position tracking. @internal */
     readonly absoluteIndex: number;
-    /** The full `RawSegment` this wrapper wraps. Exposed for mutation methods (Plan 04). @internal */
+    /** The full `RawSegment` this wrapper wraps. Exposed for mutation methods. @internal */
     readonly raw: RawSegment;
     /**
      * Lookup map from profile-declared field name → 1-indexed HL7 position.
@@ -2342,7 +2357,7 @@ declare class Segment {
      * should obtain `Segment` instances via `msg.segments(type)` or
      * `msg.allSegments()`.
      *
-     * The optional `customFields` parameter is the per-segment slice of the
+     * The optional `customFields` parameter is the per-segment portion of the
      * applied profile's merged `customSegments` map (PROF-07 / D-16). When
      * supplied, `get(name)` resolves names against it; otherwise `get(name)`
      * always returns `undefined`.
@@ -2400,7 +2415,7 @@ declare class Segment {
 }
 
 /**
- * `identityEvents`: roadmap Phase K read-side helper that recognizes the ADT
+ * `identityEvents`: 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.
@@ -2455,7 +2470,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. That is the role-labelling invariant.
  *
  * @example
  * ```ts
@@ -2557,17 +2572,17 @@ interface IdentityEvent {
 }
 
 /**
- * Phase 4 helper type declarations: the 9 typed shapes returned by
+ * 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 the model layer's
  * composite coercions, never re-parsing the raw tree.
  *
- * Field lists locked by Phase 4 CONTEXT.md decisions D-01..D-24. Nine interfaces:
+ * Field lists are locked by decisions D-01..D-24. Nine interfaces:
  * `Meta`, `Patient`, `Visit`, `Observation` (discriminated union + `ObservationBase`),
  * `Order`, `NextOfKin`, `Allergy`, `Diagnosis`, `Insurance`.
  */
@@ -2576,7 +2591,7 @@ interface IdentityEvent {
  * MSH-derived message metadata (HELPERS-01). D-03: always defined on
  * `Hl7Message.meta` (MSH absence throws `NO_MSH_SEGMENT` at parse time);
  * individual fields are optional because vendor-quirky messages routinely
- * omit pieces of MSH. Phase N: `timestamp` is the fidelity `TS` (precision +
+ * omit pieces of MSH. `timestamp` is the fidelity `TS` (precision +
  * timezone preserved), not an eager UTC-assuming `Date`.
  *
  * @example
@@ -2603,7 +2618,7 @@ interface Meta {
     readonly messageStructure?: string;
     /** MSH-10 message control ID: unique per message per sender. */
     readonly controlId?: string;
-    /** MSH-7 message date/time as the fidelity `TS` (Phase N). */
+    /** MSH-7 message date/time as the fidelity `TS`. */
     readonly timestamp?: TS;
     /** MSH-12 HL7 version string (e.g. "2.5", "2.5.1"). */
     readonly version?: string;
@@ -2656,7 +2671,7 @@ interface Patient {
     /** Composed Western-order name "Given Middle Family, Suffix" (D-17). */
     readonly fullName?: string;
     /**
-     * PID-7 date of birth as the fidelity `TS` (Phase N). A day-only DOB keeps
+     * PID-7 date of birth as the fidelity `TS`. A day-only DOB keeps
      * `precision: "day"`: never coerced to a UTC-midnight instant that would
      * read as the previous day in a negative-offset zone.
      */
@@ -2674,7 +2689,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: 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.
@@ -2684,7 +2699,7 @@ interface Patient {
 /**
  * PV1-derived visit view (HELPERS-03). `msg.visit` is `undefined` when no PV1
  * segment exists; this interface describes the shape when present. D-24a:
- * doctor fields use XCN (not flat strings). Phase N: date/time fields are the
+ * doctor fields use XCN (not flat strings). Date/time fields are the
  * fidelity `TS` (precision + timezone preserved).
  *
  * @example
@@ -2704,9 +2719,9 @@ interface Visit {
     readonly patientClass?: string;
     /** PV1-3 assigned patient location (ward / room / bed) as PL. */
     readonly location?: PL;
-    /** PV1-44 admit date/time as the fidelity `TS` (Phase N). */
+    /** PV1-44 admit date/time as the fidelity `TS`. */
     readonly admitDateTime?: TS;
-    /** PV1-45 discharge date/time as the fidelity `TS` (Phase N). */
+    /** PV1-45 discharge date/time as the fidelity `TS`. */
     readonly dischargeDateTime?: TS;
     /** PV1-7 attending doctor (D-24a XCN). */
     readonly attendingDoctor?: XCN;
@@ -2752,10 +2767,10 @@ interface ObservationBase {
     readonly abnormalFlags?: string;
     /** OBX-11 observation result status (e.g. "F"=final, "P"=preliminary). */
     readonly status?: string;
-    /** OBX-14 date/time of observation as the fidelity `TS` (Phase N). */
+    /** OBX-14 date/time of observation as the fidelity `TS`. */
     readonly observedDateTime?: TS;
     /**
-     * NTE note lines positionally attached to this OBX (Phase P): each
+     * NTE note lines positionally attached to this OBX: 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.
@@ -2767,7 +2782,7 @@ interface ObservationBase {
  * `valueType` (OBX-2) per D-13:
  * - `"NM"` → `number | undefined`
  * - `"SN"` → `SN | undefined` (structured numeric: comparator / range / ratio)
- * - `"TS" | "DT"` → `TS | undefined` (fidelity parts per Phase N)
+ * - `"TS" | "DT"` → `TS | undefined` (fidelity parts preserved)
  * - `"CWE" | "CE"` → `CWE | CE | undefined` (full composite per D-14)
  * - other (`"ST"`, `"TX"`, `"FT"`, `"ID"`, `"IS"`, `"NA"`, unknown) →
  *   `string | undefined` (decoded, D-23)
@@ -2809,7 +2824,7 @@ type Observation = ObservationBase & ({
 });
 /**
  * How an order/medication `RepeatPattern` code (HL7 Table 0335) is classified,
- * **provenance only, never used to resolve a schedule** (Phase M). The `code`
+ * **provenance only, never used to resolve a schedule**. 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.
@@ -2827,7 +2842,7 @@ type Observation = ObservationBase & ({
 type RepeatPatternKind = "parametric" | "named" | "unknown";
 /**
  * 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.
+ * frequency/SIG field (TQ1-3, or the legacy embedded TQ interval RI.1).
  *
  * **Safety contract.** `code` is the **decoded field value** (HL7 escapes are
  * unescaped as with every field read) and is **never resolved to clock times,
@@ -2861,7 +2876,7 @@ interface RepeatPattern {
 }
 /**
  * A composite-quantity (CQ) value on an order/medication timing: the TQ1-2
- * service quantity, Phase M. `value` is strict-`Number()` parsed (`undefined`,
+ * service quantity. `value` is strict-`Number()` parsed (`undefined`,
  * never `NaN`); `units` carries any CQ.2 units. Both keys OMITTED when absent.
  *
  * @example
@@ -2878,14 +2893,14 @@ interface TimingQuantity {
 }
 /**
  * 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
+ * legacy embedded TQ in ORC-7 / RXE-1 (pre-v2.5). Attached to
  * {@link Order.timings} and {@link Medication.timings}.
  *
  * **Safety contract.** hl7 surfaces the timing **structure**; it does **not**
  * compute administration schedules, resolve "institution-specified times" to
  * 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
+ * `startDateTime`/`endDateTime` keep the `TS` precision + timezone
  * fidelity. A malformed timing never throws: absent pieces are omitted keys.
  *
  * @example
@@ -2917,9 +2932,9 @@ interface OrderTiming {
     readonly explicitTime?: string;
     /** 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). */
+    /** TQ1-7 / legacy TQ.4 start date/time as the fidelity `TS`. */
     readonly startDateTime?: TS;
-    /** TQ1-8 / legacy TQ.5 end date/time as the fidelity `TS` (Phase N). */
+    /** TQ1-8 / legacy TQ.5 end date/time as the fidelity `TS`. */
     readonly endDateTime?: TS;
     /** TQ1-9 priority (CWE) / legacy TQ.6 priority (surfaced as a CWE `{ identifier }`). */
     readonly priority?: CWE;
@@ -2934,8 +2949,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
- * present, empty when the order carries no TQ1 / legacy embedded TQ.
+ * OBR before the next OBR or end-of-message. `timings` is ALWAYS present,
+ * empty when the order carries no TQ1 / legacy embedded TQ.
  *
  * @example
  * ```ts
@@ -2957,7 +2972,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-25 result status (HL7 Table 0123, e.g. `"F"` final, `"P"` preliminary). */
     readonly orderStatus?: string;
     /** ORC-1 order control when an ORC precedes this OBR. */
     readonly orderControl?: string;
@@ -2966,13 +2981,13 @@ interface Order {
     /** OBX children grouped under this OBR (D-12 positional grouping). Always present. */
     readonly observations: readonly Observation[];
     /**
-     * TQ1 / legacy embedded-TQ timing(s) grouped under this order (Phase M).
+     * TQ1 / legacy embedded-TQ timing(s) grouped under this order.
      * 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: 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
@@ -3008,7 +3023,7 @@ interface NextOfKin {
     readonly contactRole?: CWE;
 }
 /**
- * AL1-derived allergy entry (HELPERS-06). Phase N: `onsetDate` is the fidelity `TS`.
+ * AL1-derived allergy entry (HELPERS-06). `onsetDate` is the fidelity `TS`.
  *
  * @example
  * ```ts
@@ -3030,11 +3045,11 @@ interface Allergy {
     readonly severity?: string;
     /** AL1-5 allergy reaction description (first value). */
     readonly reaction?: string;
-    /** AL1-6 onset date as the fidelity `TS` (Phase N). */
+    /** AL1-6 onset date as the fidelity `TS`. */
     readonly onsetDate?: TS;
 }
 /**
- * DG1-derived diagnosis entry (HELPERS-06). Phase N: `dateTime` is the fidelity `TS`.
+ * DG1-derived diagnosis entry (HELPERS-06). `dateTime` is the fidelity `TS`.
  *
  * @example
  * ```ts
@@ -3051,7 +3066,7 @@ interface Diagnosis {
     readonly code?: CWE;
     /** DG1-4 diagnosis description. */
     readonly description?: string;
-    /** DG1-5 diagnosis date/time as the fidelity `TS` (Phase N). */
+    /** DG1-5 diagnosis date/time as the fidelity `TS`. */
     readonly dateTime?: TS;
     /** DG1-6 diagnosis type (A=admitting, W=working, F=final). */
     readonly type?: string;
@@ -3059,7 +3074,7 @@ interface Diagnosis {
 /**
  * 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):
+ * segment (Ch. 4A):
  * - `"order"`: **RXO** (Pharmacy/Treatment Order): the originally *requested*
  *   give code/amount/dosage-form, before pharmacy encoding.
  * - `"encoded"`: **RXE** (Encoded Order): the pharmacy-encoded give
@@ -3076,7 +3091,7 @@ interface Diagnosis {
  */
 type MedicationContext = "order" | "encoded" | "dispense" | "administration";
 /**
- * The give / dispense / administered amount of a `Medication` (Phase D).
+ * The give / dispense / administered amount of a `Medication`.
  * 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
@@ -3106,11 +3121,11 @@ 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). 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.
  *
- * **Fail-safe (Phase D §4):** strength is surfaced exactly as the explicit
+ * **Fail-safe:** strength is surfaced exactly as the explicit
  * 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
@@ -3130,8 +3145,8 @@ interface MedicationStrength {
     readonly units?: CWE;
 }
 /**
- * One RXR (Pharmacy/Treatment Route) grouped under its parent RX* segment
- * (Phase D). `route` is HL7 Table 0162 (CWE); `site` is Table 0163 (CWE).
+ * One RXR (Pharmacy/Treatment Route) grouped under its parent RX* segment.
+ * `route` is HL7 Table 0162 (CWE); `site` is Table 0163 (CWE).
  * 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.
  *
@@ -3149,7 +3164,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: a component of a compound/IV. Surfaced STRUCTURALLY
  * (the component list as authored), NOT pharmacologically resolved.
  *
  * @example
@@ -3169,8 +3184,8 @@ interface MedicationComponent {
     readonly units?: CWE;
 }
 /**
- * A medication extracted from one RXO/RXE/RXD/RXA segment (Phase D, P0
- * safety), with its RXR (route) and RXC (component) children grouped
+ * A medication extracted from one RXO/RXE/RXD/RXA segment, with its RXR
+ * (route) and RXC (component) children grouped
  * positionally. `context` records which RX* segment this came from (give
  * vs dispense vs administered).
  *
@@ -3180,12 +3195,12 @@ interface MedicationComponent {
  *   (`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
- *   (Phase D §4). A disagreement is preserved for the consumer to see.
+ *   are never reconciled: including against any strength a coded drug
+ *   implies. A disagreement is preserved for the consumer to see.
  * - 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)
+ * `routes` and `components` are ALWAYS present (possibly empty). So is
+ * `timings`: 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.
@@ -3220,8 +3235,8 @@ interface Medication {
     /** RXC children grouped under this RX* (compound components). Always present (possibly empty). */
     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.
+     * TQ1 / legacy embedded-TQ (RXE-1) timing(s) grouped under this medication.
+     * Always present: empty when the medication carries no timing.
      * See {@link OrderTiming}.
      */
     readonly timings: readonly OrderTiming[];
@@ -3256,9 +3271,9 @@ interface Insurance {
     readonly groupNumber?: string;
     /** IN1-16 insured's name. */
     readonly insuredName?: XPN;
-    /** IN1-12 plan effective date as the fidelity `TS` (Phase N). */
+    /** IN1-12 plan effective date as the fidelity `TS`. */
     readonly effectiveDate?: TS;
-    /** IN1-13 plan expiration date as the fidelity `TS` (Phase N). */
+    /** IN1-13 plan expiration date as the fidelity `TS`. */
     readonly expirationDate?: TS;
     /** `true` iff an IN2 segment follows this IN1 before the next IN1. */
     readonly hasIn2: boolean;
@@ -3285,7 +3300,7 @@ interface Insurance {
 type ImmunizationRecordOrigin = "administered" | "historical";
 /**
  * A vaccine dose extracted from one RXA (Pharmacy/Treatment Administration)
- * segment of a VXU^V04 immunization message (Phase E, P0 safety), with its RXR
+ * segment of a VXU^V04 immunization message, with its RXR
  * (route/site) and OBX (e.g. VFC eligibility / funding source) children grouped
  * positionally under the RXA, and `orderControl` from the preceding ORC of the
  * VXU order group (`ORC`→`RXA`→`[RXR]`→`[{OBX}]`).
@@ -3350,11 +3365,11 @@ interface Immunization {
     readonly informationSource?: CWE;
     /** Derived administered-vs-historical classification from RXA-9.1. See {@link ImmunizationRecordOrigin}. */
     readonly recordOrigin?: ImmunizationRecordOrigin;
-    /** RXA-3 date/time start of administration as the fidelity `TS` (Phase N). */
+    /** RXA-3 date/time start of administration as the fidelity `TS`. */
     readonly administeredDateTime?: TS;
     /** RXA-15 substance lot number (first repetition). */
     readonly lotNumber?: string;
-    /** RXA-16 substance expiration date (first repetition) as the fidelity `TS` (Phase N). */
+    /** RXA-16 substance expiration date (first repetition) as the fidelity `TS`. */
     readonly expirationDate?: TS;
     /** RXA-17 substance manufacturer (MVX, HL7 Table 0227; first repetition). */
     readonly manufacturer?: CWE;
@@ -3370,7 +3385,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`: 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`
@@ -3398,7 +3413,7 @@ interface AppointmentResource {
     readonly person?: XCN;
 }
 /**
- * SCH-derived appointment entry (Phase Q: SIU scheduling breadth). Surfaces the
+ * SCH-derived appointment entry (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.
  *
@@ -3419,15 +3434,15 @@ interface Appointment {
     readonly fillerAppointmentId?: string;
     /** 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`). */
     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`). */
     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 (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
  * be *available* before it is *authenticated*, and reading a preliminary
@@ -3460,7 +3475,7 @@ interface ClinicalDocument {
      * {@link completionStatus}; verbatim, never validated, never merged.
      */
     readonly availabilityStatus?: string;
-    /** TXA-4 activity date/time (fidelity `TS`, Phase N). */
+    /** TXA-4 activity date/time (fidelity `TS`). */
     readonly activityDateTime?: TS;
     /** TXA-12 unique document number (EI first component, verbatim). */
     readonly uniqueDocumentNumber?: string;
@@ -3470,7 +3485,7 @@ interface ClinicalDocument {
     readonly observations: readonly Observation[];
 }
 /**
- * FT1-derived charge entry (Phase Q: DFT financial breadth). Billing-critical
+ * FT1-derived charge entry (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.
  *
@@ -3486,7 +3501,7 @@ interface ClinicalDocument {
  * ```
  */
 interface Charge {
-    /** FT1-4 transaction date (fidelity `TS`, Phase N). */
+    /** FT1-4 transaction date (fidelity `TS`). */
     readonly transactionDate?: TS;
     /** FT1-6 transaction type (HL7 Table 0017: `CG` charge, `CD` credit, `PY` payment, `AJ` adjustment). Verbatim. */
     readonly transactionType?: string;
@@ -3503,7 +3518,7 @@ interface Charge {
 }
 
 /**
- * Message-type & structure awareness (roadmap Phase G): a conservative
+ * Message-type & structure awareness: a conservative
  * **misroute / truncation safety net**, NOT an abstract-message-syntax
  * validator.
  *
@@ -3605,9 +3620,19 @@ interface StructureGroup {
 interface MessageStructure {
     /** `true` when a `MESSAGE_STRUCTURE_DEFINITIONS` entry matched the type. */
     readonly recognized: boolean;
-    /** MSH-9.1 message code observed on the message (empty string if absent). */
+    /**
+     * MSH-9.1 message code observed on the message. `""` when absent, and
+     * `"<withheld>"` when `recognized` is `false` and the observed value is not
+     * identifier-shaped (MSH-9 can hold a data field on a malformed message).
+     */
     readonly messageCode: string;
-    /** MSH-9.2 trigger event observed on the message (empty string if absent). */
+    /**
+     * MSH-9.2 trigger event observed on the message. `""` when absent, and
+     * `"<withheld>"` when `recognized` is `false` and the observed value is not
+     * identifier-shaped. Note that on the `recognized` branch this is echoed
+     * verbatim, which for a definition matching on message code alone (`ACK`)
+     * means an arbitrary MSH-9.2.
+     */
     readonly triggerEvent: string;
     /** Per-expected-group presence verdicts (empty when unrecognized). */
     readonly expectedGroups: readonly StructureGroup[];
@@ -3640,9 +3665,8 @@ declare function analyzeMessageStructure(messageCode: string, triggerEvent: stri
  * `Hl7Message`. Mirrors `rawSegments` one-for-one; preserves `isNull`;
  * always includes `warnings: []`; omits `profile` when absent.
  *
- * The `SerializedMessage` interface is exported in Plan 01 (this file) so
- * consumers + `src/index.ts` can reference the type immediately. The
- * `emitJson` function body is filled in Phase 5 Plan 03 (to-json).
+ * `SerializedMessage` is exported from this module and re-exported from
+ * `src/index.ts`, so consumers can reference the type directly.
  *
  * Decisions:
  * - D-17: shape is a raw-tree mirror (encodingCharacters + segments +
@@ -3703,8 +3727,8 @@ interface SerializedMessage {
 }
 
 /**
- * Typed-composite **encoders** for the `@cosyte/hl7` emit path (roadmap Phase
- * T): the conservative-emit mirror of the `src/model/types/*` read parsers.
+ * Typed-composite **encoders** for the `@cosyte/hl7` emit path: 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
@@ -3713,7 +3737,7 @@ interface SerializedMessage {
  *
  * - **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)
+ *   runs every subcomponent through `reescape` (the 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
@@ -3907,13 +3931,12 @@ declare function encodeCompositeReps<K extends CompositeKind>(kind: K, values: r
 
 /**
  * `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),
- * `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.
+ * A read-only shell over the raw segment tree, plus the read-path traversal
+ * methods (`get`, `getAll`, `segments`, `allSegments`) on top of lazy,
+ * referentially stable Segment/Field caches. `init.segments` is the
+ * parser-side constructor key; the public raw-tree field is exposed as
+ * `rawSegments`, which frees the name `segments` for the typed
+ * `segments(type)` method.
  */
 
 /**
@@ -3928,8 +3951,8 @@ declare function encodeCompositeReps<K extends CompositeKind>(kind: K, values: r
  * descriptor. This matches the `Hl7Message.profile` public field shape
  * (`... | undefined`).
  *
- * The init key is still named `segments` (not `rawSegments`) so Phase 2
- * parser code that constructs `Hl7Message` does not need to change. Inside
+ * The init key is named `segments` (not `rawSegments`) so parser code that
+ * constructs `Hl7Message` does not need to change. Inside
  * the class body the raw tree is stored on `this.rawSegments`.
  *
  * @internal
@@ -3965,10 +3988,10 @@ interface Hl7MessageInit {
  *
  * @remarks
  * The `warnings` array is frozen at the model boundary so downstream
- * traversal and helper phases cannot mutate parser output. The `profile`
- * field is populated by Phase 6 when a profile is passed; Phase 2 leaves
- * it `undefined` by default. Segment/Field wrappers are cached per-message
- * and invalidated wholesale by Plan 04 mutation methods.
+ * traversal and helpers cannot mutate parser output. The `profile`
+ * field is populated when a profile is passed, and is `undefined`
+ * otherwise. Segment/Field wrappers are cached per-message and
+ * invalidated wholesale by the mutation methods.
  *
  * @example
  * ```ts
@@ -3986,11 +4009,20 @@ 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
-     * is exposed for advanced callers that need the raw tree directly (e.g.
-     * future serialization phase 5).
+     * is exposed for advanced callers that need the raw tree directly.
      */
     readonly rawSegments: readonly RawSegment[];
     readonly encodingCharacters: EncodingCharacters;
+    /**
+     * HL7 version the model asserts for this message, from MSH-12.1.1, e.g.
+     * `"2.5"` or `"2.5.1"`.
+     *
+     * **Bounded, and it is `"<withheld>"` when MSH-12 does not hold a version.**
+     * Same reasoning as {@link Segment.type}: it presents as an identifier and
+     * consumers label with it. `meta.version` keeps MSH-12 exactly as it
+     * arrived, and is what version-scoped field selection reads, so this bound
+     * changes no parsing behaviour.
+     */
     readonly version: string;
     readonly warnings: readonly Hl7ParseWarning[];
     readonly profile: {
@@ -4006,7 +4038,7 @@ declare class Hl7Message {
     readonly dateFormats: readonly string[];
     /**
      * Merged `customSegments` map from the applied profile, stored so
-     * `allSegments()` can hand per-segment slices to `Segment` constructors
+     * `allSegments()` can hand per-segment portions to `Segment` constructors
      * (D-16). Undefined when no profile was applied.
      * @internal
      */
@@ -4015,40 +4047,40 @@ declare class Hl7Message {
      * Lazily built cache of Segment wrappers keyed by segment type. Built on
      * first `segments(type)` call and filtered from `_allSegments` so
      * individual Segment instances are identical across both caches (D-11).
-     * Plan 04 mutation methods drop this cache wholesale.
+     * The mutation methods drop this cache wholesale.
      * @internal
      */
     private _segmentsByType;
     /**
      * Lazily built cache of every Segment wrapper in document order. Built on
-     * first `segments(type)` / `allSegments()` call. Plan 04 mutation methods
+     * first `segments(type)` / `allSegments()` call. The mutation methods
      * drop this cache wholesale.
      * @internal
      */
     private _allSegments;
     /**
-     * Lazily built `Meta` view (Phase 4 D-02 memoization). Dropped wholesale
+     * Lazily built `Meta` view (memoized). Dropped wholesale
      * 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
+     * Lazily built `MessageStructure` view. Dropped wholesale by
      * `invalidateCaches`. Always defined: `analyzeMessageStructure` returns an
      * `recognized: false` summary for unmodelled types rather than absence.
      * @internal
      */
     private _structure;
     /**
-     * Lazily built `Patient | undefined` view (Phase 4 D-02 memoization). Uses
+     * Lazily built `Patient | undefined` view (memoized). Uses
      * a null-sentinel cache because `undefined` means "not yet computed" while
      * `null` means "computed, absent". D-04: no PID → public value `undefined`.
      * @internal
      */
     private _patient;
     /**
-     * Lazily built `Visit | undefined` view (Phase 4 D-02 memoization). Same
+     * Lazily built `Visit | undefined` view (memoized). Same
      * null-sentinel convention as `_patient`. HELPERS-03: no PV1 → public
      * value `undefined`.
      * @internal
@@ -4064,8 +4096,8 @@ 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,
-     * HL7-VALUE-REDECODE). Returns `undefined` when the path doesn't
+     * decoded leaf string (unescaped once at parse: never re-unescaped on
+     * read). Returns `undefined` when the path doesn't
      * resolve: never throws on missing path (MODEL-05). Throws `TypeError`
      * on malformed path syntax (e.g. `"pid.5"`, empty string).
      *
@@ -4096,7 +4128,7 @@ declare class Hl7Message {
      * Return the cached array of `Segment` wrappers for `segmentType` in
      * document order. The returned array identity and the individual Segment
      * instances are both stable across calls (D-11). Invalidated wholesale
-     * by Plan 04 mutation methods.
+     * by the mutation methods.
      *
      * @example
      * ```ts
@@ -4109,7 +4141,7 @@ declare class Hl7Message {
      * Iterate every `Segment` in document order (MSH first, then every
      * subsequent segment). Cached per-message; same array reference and same
      * Segment instances on repeat calls (D-11). Invalidated wholesale by
-     * Plan 04 mutation methods.
+     * the mutation methods.
      *
      * @example
      * ```ts
@@ -4128,14 +4160,14 @@ declare class Hl7Message {
      * @example
      * ```ts
      * console.log(msg.meta.type);                     // "ADT^A01"
-     * console.log(msg.meta.timestamp?.raw);           // fidelity TS (Phase N)
+     * console.log(msg.meta.timestamp?.raw);           // fidelity TS
      * console.log(msg.meta.controlId);                // "MSG001"
      * ```
      */
     get meta(): Meta;
     /**
-     * Structural-conformance summary for the common message types (roadmap
-     * Phase G): a misroute/truncation safety net, NOT a conformance validator.
+     * Structural-conformance summary for the common message types: 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
@@ -4189,7 +4221,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` (the repeat pattern is
      * surfaced verbatim, never resolved to a schedule). D-05: returns `[]` when no
      * OBR present. D-06: not memoized.
      *
@@ -4203,7 +4235,7 @@ declare class Hl7Message {
      */
     orders(): readonly Order[];
     /**
-     * Message-level NTE notes (Phase P): every NTE segment with no recognized
+     * Message-level NTE notes: 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
@@ -4218,7 +4250,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), 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
@@ -4237,13 +4269,13 @@ declare class Hl7Message {
     identityEvents(): readonly IdentityEvent[];
     /**
      * Every RXO/RXE/RXD/RXA as a typed `Medication`, with RXR (route) and RXC
-     * (component) segments grouped positionally under their parent (Phase D,
-     * P0 safety). D-05: returns `[]` when no RX* parent present. D-06: not
-     * memoized. The give *amount* and give *strength* are surfaced separately
-     * and never reconciled (Phase D §4).
+     * (component) segments grouped positionally under their parent. D-05:
+     * returns `[]` when no RX* parent present. D-06: not memoized. The give
+     * *amount* and give *strength* are surfaced separately and never
+     * reconciled.
      *
      * Each medication also carries its TQ1 / legacy embedded-TQ (RXE-1) `timings`
-     * (Phase M: repeat pattern verbatim, never resolved to a schedule).
+     * (repeat pattern verbatim, never resolved to a schedule).
      *
      * @example
      * ```ts
@@ -4258,7 +4290,7 @@ declare class Hl7Message {
     /**
      * Every RXA of a VXU^V04 as a typed `Immunization`, with RXR (route/site)
      * and OBX children grouped positionally under the RXA and `orderControl`
-     * from the preceding ORC of the VXU order group (Phase E, P0 safety). D-05:
+     * from the preceding ORC of the VXU order group. D-05:
      * 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
@@ -4316,7 +4348,7 @@ declare class Hl7Message {
      */
     insurance(): readonly Insurance[];
     /**
-     * Every SCH of an SIU message as a typed `Appointment` (roadmap Phase Q), with
+     * Every SCH of an SIU message as a typed `Appointment`, with
      * the AIS/AIG/AIL/AIP resource segments that follow it grouped positionally
      * under that SCH. Surfaces the placer/filler appointment ids, SCH-25 filler
      * status (Table 0278), SCH-11 start/end timing, and the resource groups
@@ -4334,7 +4366,7 @@ declare class Hl7Message {
      */
     appointments(): readonly Appointment[];
     /**
-     * Every TXA of an MDM message as a typed `ClinicalDocument` (roadmap Phase Q),
+     * Every TXA of an MDM message as a typed `ClinicalDocument`,
      * 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
@@ -4352,7 +4384,7 @@ declare class Hl7Message {
      */
     documents(): readonly ClinicalDocument[];
     /**
-     * Every FT1 of a DFT message as a typed `Charge` (roadmap Phase Q), one per
+     * Every FT1 of a DFT message as a typed `Charge`, 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
@@ -4438,7 +4470,7 @@ declare class Hl7Message {
      * `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.
+     * rejected on input (D-18). Re-escaping is the serializer's concern.
      *
      * MSH-1 / MSH-2 follow the user-facing HL7 convention: `setField("MSH.3", ...)`
      * targets MSH-3 (sending application), matching `msg.get("MSH.3")`.
@@ -4455,11 +4487,11 @@ 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
+     * Set a **typed composite** at a field (or field-repetition) dot-path:
+     * 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
+     * encodes it into a spec-clean field using the 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 `^`/`&`/`~`.
@@ -4533,8 +4565,8 @@ declare class Hl7Message {
         readonly all?: boolean;
     }): this;
     /**
-     * Drop every wrapper AND helper cache wholesale (Phase 3 D-17 + Phase 4
-     * D-02). Called by every mutation method so subsequent `segments(type)` /
+     * Drop every wrapper AND helper cache wholesale (D-17 + D-02). Called by
+     * every mutation method so subsequent `segments(type)` /
      * `allSegments()` / `meta` / `patient` / `visit` reads rebuild from the
      * mutated `rawSegments` tree.
      * @internal
@@ -4594,9 +4626,8 @@ declare function parseHL7(raw: string | Buffer, options: ParseOptions): Hl7Messa
  * severe is a Tier-2 warning (see `./warnings.ts`). `Hl7ParseError` is
  * 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
- * across phases.
+ * `ProfileDefinitionError` is declared here so the whole error taxonomy
+ * lives in one module.
  */
 
 /**
@@ -4653,9 +4684,31 @@ 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
- * the call site if required by your compliance posture. The library does
- * not redact snippets itself.
+ * `snippet` may contain PHI when parsing real clinical messages, and the
+ * library does not redact it: redact at the call site if required by your
+ * compliance posture. **It is the only field carrying input verbatim and
+ * unfiltered** (capped at 40 characters plus an ellipsis, but not shape-checked
+ * in any way), so it is the one to redact first.
+ *
+ * `message` is bounded but not absolutely content-free, and the difference is
+ * worth stating because `message` is what a logger prints by default and what
+ * `stack` embeds. A token lifted from the input is echoed only when it matches
+ * the form the spec defines for it: a three-character segment identifier, an
+ * MSH-9 type, an MSH-12 version, or a charset label the closed Table 0211
+ * actually contains. Anything else becomes `<withheld>`. So a message cannot
+ * carry a field's value, but it can carry a residue of up to three characters
+ * when a malformed line happens to look like a segment identifier. The other
+ * shapes are narrower in practice than their patterns allow, because the
+ * library only ever feeds them registry-matched values, but the patterns
+ * themselves admit more (a message type up to 26 characters, a version up to
+ * 14), which matters if you construct warnings yourself.
+ *
+ * Under `{ strict: true }` an escalated Tier-2 warning is thrown as this
+ * error, carrying the warning's own bounded message and a `snippet` of the
+ * **first 40 characters of the input**. That snippet is the head of the
+ * message rather than the deviation's own segment, so it is usually the MSH
+ * header; it is deliberately not re-pointed at the offending segment, since
+ * doing so would move more clinical content into the unredacted field.
  *
  * @example
  * ```ts
@@ -4682,12 +4735,11 @@ declare class Hl7ParseError extends Error {
     constructor(code: FatalCode, message: string, position: Hl7Position, snippet: string);
 }
 /**
- * Thrown by `defineProfile()` and profile-validation code (Phase 6) when a
+ * Thrown by `defineProfile()` and profile-validation code when a
  * 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
- * for better diagnostics.
+ * date format. Callers may optionally supply the offending profile name for
+ * better diagnostics.
  *
  * @example
  * ```ts
@@ -4702,7 +4754,7 @@ declare class ProfileDefinitionError extends Error {
     readonly profileName: string | undefined;
     /**
      * Construct a new `ProfileDefinitionError`. `profileName` is optional so
-     * Phase 6 callers may omit it when the offending profile cannot be named
+     * callers may omit it when the offending profile cannot be named
      * (e.g. during initial validation before a name is parsed).
      *
      * @internal
@@ -4712,12 +4764,12 @@ 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
+ * `Buffer`-decode stage. 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
  * 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).
+ * stateful `\Mxxyyzz\` escapes the parser 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
@@ -4928,7 +4980,7 @@ declare function reescape(input: string, enc: EncodingCharacters): string;
  *   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.
+ *   component boundary**. This is the primitive the typed emit path builds on.
  *
  * For a human-readable rendering (formatting commands → whitespace, highlight
  * dropped), use {@link renderText} instead of {@link decodeText}.
@@ -5005,7 +5057,7 @@ declare function encodeText(input: string, enc?: EncodingCharacters): string;
  *
  * - `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).
+ * - `text.encode(anyString)`: encode-safe: no delimiter injection.
  *
  * ```ts
  * import { text } from "@cosyte/hl7";
@@ -5029,17 +5081,17 @@ declare namespace index$1 {
  * `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):
+ * Indexing conventions:
  * - `[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
+ * - Dot-numbers are ALWAYS 1-indexed: matches HL7 spec and the 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).
+ *   stored at `fields[0]` / `fields[1]` by tokenize.ts (D-05).
  * - Missing subcomponent on a single-sub component returns the component
  *   string (depth-collapse, D-04).
  * - Leaf reads return the subcomponent verbatim: the tokenizer (parser-02)
  *   already unescaped it once on parse, so the stored value is decoded and a
- *   second `unescape` here would double-decode it (HL7-VALUE-REDECODE).
+ *   second `unescape` here would double-decode it.
  */
 
 /**
@@ -5134,7 +5186,7 @@ declare namespace namespace {
 
 /**
  * `pickMrn`: pick the Medical Record Number string from a PID-3 identifier
- * list. Isolated from `patient.ts` so Phase 6 profile hooks can substitute
+ * list. Isolated from `patient.ts` so a profile hook can substitute
  * a profile-aware variant without patching the helper that calls it.
  *
  * Silent (D-21: helpers emit no warnings). Never throws (D-22).
@@ -5177,12 +5229,11 @@ declare function pickMrn(identifiers: readonly CX[]): string | undefined;
  * `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,
+ * `.addSegment(...)` (mutation method) to append PID,
  * OBX, etc. Symmetric with `parseHL7` (D-09).
  *
- * The `BuildMessageInit` interface is exported in Plan 01 (this file) so
- * consumers + `src/index.ts` can reference the type immediately. The
- * `buildMessage` function body is filled in Phase 5 Plan 05 (build-message).
+ * `BuildMessageInit` is exported from this module and re-exported from
+ * `src/index.ts`, so consumers can reference the type directly.
  *
  * Decisions:
  * - D-09: top-level named export from `src/index.ts`.
@@ -5193,8 +5244,8 @@ declare function pickMrn(identifiers: readonly CX[]): string | undefined;
  * - D-13: `timestamp` accepts `Date | string`; `Date` formats to
  *   `YYYYMMDDHHmmss` UTC.
  * - D-14: encoding chars always `DEFAULT_ENCODING_CHARACTERS`.
- * - D-15: subsequent `.addSegment(name, fields)` uses Phase 3 unchanged
- *   (`readonly string[]` field input).
+ * - D-15: subsequent `.addSegment(name, fields)` takes `readonly string[]`
+ *   field input.
  * - D-16: missing/empty `type` throws `TypeError`.
  *
  * **Absent vs. explicit null at the wire level:** at the HL7 wire level,
@@ -5202,7 +5253,7 @@ declare function pickMrn(identifiers: readonly CX[]): string | undefined;
  * (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
- * Phase 3 `setField` mutation method sets `RawField.isNull = true`, which
+ * `setField` mutation method sets `RawField.isNull = true`, which
  * the emitter preserves as the literal two-char string `""` per D-02.
  */
 
@@ -5216,7 +5267,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 mutation method sets `isNull=true`
  * on the underlying `RawField`, and the emitter preserves that as the
  * literal two-char output per D-02.
  *
@@ -5276,7 +5327,7 @@ interface BuildMessageInit {
  * Construct an outbound `Hl7Message` from semantic MSH fields (SER-06).
  * Synthesises a complete MSH `RawSegment` per D-10/D-11 and hands to
  * `new Hl7Message({...})`. Callers chain `.addSegment(name, fields)`
- * (Phase 3 mutation method, unchanged) to append PID, OBX, etc.
+ * (mutation method) to append PID, OBX, etc.
  *
  * Defaults applied when fields are omitted (D-10):
  * - `controlId` → `generateControlId()` (D-12)
@@ -5300,9 +5351,7 @@ interface BuildMessageInit {
  * // msg.toString() now emits MSH-3 as `""` (2 chars), not as absent.
  * ```
  *
- * The `BuildMessageInit` interface JSDoc (Plan 01) has the same note on
- * the input shape; this function-level doc reinforces it for developers
- * who land on the impl.
+ * `BuildMessageInit` carries the same note on the input shape.
  *
  * @example
  * ```ts
@@ -5324,7 +5373,7 @@ 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
+ * (`buildAdt`/`buildOru`). Centralises the MSH synthesis and
  * the sparse positional-segment assembly so each builder stays declarative and
  * every builder emits an identical, spec-clean MSH.
  *
@@ -5356,11 +5405,11 @@ interface MessageEnvelope {
 
 /**
  * `buildAdt`: author a spec-clean HL7 v2 **ADT** (admit/discharge/transfer)
- * message from typed inputs (roadmap Phase T). The conservative-emit mirror of
+ * message from typed inputs. 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
+ * with correct `^`/`&`/`~` structure via the encode-safe path: never
  * hand-assembling delimiters, never injecting one.
  *
  * **Structurally complete + zero-warning.** The emitted message carries the
@@ -5467,11 +5516,11 @@ 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
+ * message from typed inputs. 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.
+ * `^`/`&`/`~` structure via the 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
@@ -5573,7 +5622,7 @@ interface BuildOruInit extends MessageEnvelope {
 declare function buildOru(init: BuildOruInit): Hl7Message;
 
 /**
- * Frozen HL7 control-vocabulary tables for ACK generation (Phase C). These
+ * Frozen HL7 control-vocabulary tables for ACK generation. These
  * 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.
@@ -5711,7 +5760,7 @@ type AckMode = "original" | "enhanced";
 
 /**
  * `buildAck`: generate a spec-clean HL7 v2 acknowledgment (ACK) message from
- * an inbound message (Phase C). The boundary with `@cosyte/mllp` is resolved
+ * an inbound message. 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*.
  *
@@ -5814,7 +5863,7 @@ declare function detectAckMode(inbound: Hl7Message): AckMode;
  * - **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
+ *   inbound field's escape-fidelity overlay, 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
  *   what MSA-2 correlation compares. The only structural transform is
@@ -5829,7 +5878,7 @@ declare function detectAckMode(inbound: Hl7Message): AckMode;
  *   (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
+ * **Fail-safe.** 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.
@@ -5852,8 +5901,8 @@ declare function buildAck(inbound: Hl7Message, options: BuildAckOptions): Hl7Mes
 
 /**
  * `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),
+ * acknowledgment (ACK) message into a typed {@link Acknowledgment} view.
+ * 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
@@ -5938,10 +5987,9 @@ declare function interpretAck(msg: Hl7Message): Acknowledgment;
  * `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;
- * Wave 2 (Plan 06-02) fills in `extends` + merge semantics by extending
- * this factory's body. For Wave 1, `opts.extends` is ACCEPTED but
- * IGNORED, resulting in `lineage === [opts.name]` regardless.
+ * `opts.extends` is honoured: parents are merged into the returned
+ * profile (lineage, `dateFormats`, `customSegments`, `description` and
+ * `onWarning`), and the merged result is re-validated before it is frozen.
  *
  * Zero runtime deps. Matches CLAUDE.md engineering guardrails: no `any`,
  * JSDoc `@example` on every public export, immutability at the return
@@ -5985,10 +6033,11 @@ 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
- * ACCEPTED but IGNORED, resulting in `lineage === [opts.name]`
- * regardless. Wave 2 (Plan 06-02) adds full lineage computation + merge
- * semantics.
+ * `opts.extends` accepts a single parent `Profile` or an array of them.
+ * Parents are merged into the result: `lineage` is the parents' lineages
+ * followed by this profile's own name, `dateFormats` and `customSegments`
+ * are merged, `description` inherits when not supplied, and `onWarning`
+ * handlers are composed. With no parent, `lineage === [opts.name]`.
  *
  * @example
  * ```ts
@@ -6197,8 +6246,8 @@ declare const genericLab: Profile;
  * 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:
+ * Grounded in **publicly downloadable** MEDITECH interface specifications,
+ * not invented:
  *
  * - The **minute-precision** date/time format is confirmed by *two*
  *   public MEDITECH specs: "MEDITECH Admissions and Registration to Other
@@ -6220,10 +6269,8 @@ declare const genericLab: Profile;
  *   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.)
+ * (Field positions above are transcribed directly from the spec's segment
+ * tables.)
  *
  * Authored from the public `defineProfile()` API: zero privileged
  * internal coupling. Consumers extend this profile via
@@ -6271,7 +6318,7 @@ declare const meditech: Profile;
  *
  * 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
+ * vendor interface spec, not an invented quirk. The spec's
  * `TS` timestamps are the HL7-native `YYYYMMDDHHMMSS` form (§2.6), so this
  * profile declares **no** custom `dateFormats`: only the Z-segments.
  *
@@ -6332,7 +6379,7 @@ declare const philips: Profile;
  * 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
+ * (`va.gov/vdl`), not an invented quirk. 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.
@@ -6372,7 +6419,7 @@ declare const va: Profile;
  * (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
+ * interface spec, not an invented quirk. Dates in that spec use
  * the HL7-native `YYYYMMDDHHMMSS` form, so this profile declares **no**
  * custom `dateFormats`: only the ZDS segment.
  *
@@ -6463,7 +6510,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).
  *
  * 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"
@@ -6606,8 +6653,8 @@ declare function codingSystemOf(coded: CodedSystemFields): CodingSystemInfo | un
 declare function alternateCodingSystemOf(coded: CodedSystemFields): CodingSystemInfo | undefined;
 
 /**
- * Batch / file envelope splitting for the `@cosyte/hl7` parser (roadmap
- * Phase L). Real lab / ELR / IIS feeds ship many messages wrapped in the HL7
+ * Batch / file envelope splitting for the `@cosyte/hl7` parser. Real lab /
+ * ELR / IIS feeds ship many messages wrapped in the HL7
  * v2 batch protocol envelope (Ch. 2 §2.10.3):
  *
  * ```
@@ -6651,8 +6698,8 @@ 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
- * 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
+ * array, not a typed model: typed FHS/BHS field helpers beyond the raw
+ * fields are not part of this surface. Note the
  * HL7 MSH-family indexing quirk: for `FHS`/`BHS`, `fields[1]` is the
  * encoding-characters field (FHS-2/BHS-2); for `BTS`/`FTS`, `fields[1]` is
  * field 1 (BTS-1 batch message count / FTS-1 file batch count).
@@ -6815,7 +6862,7 @@ declare function splitBatch(raw: string | Buffer, profile: Profile): BatchSplitR
 declare function splitBatch(raw: string | Buffer, options: ParseOptions): BatchSplitResult;
 
 /**
- * Public types for the conformance-profile engine (roadmap Phase U). A
+ * Public types for the conformance-profile engine. 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
@@ -6901,7 +6948,7 @@ interface Cardinality {
     readonly max?: number | "*";
 }
 /**
- * A rule for one **field position** within a segment (roadmap Phase U). Every
+ * A rule for one **field position** within a segment. Every
  * constraint is optional; a rule with only a `field` index is a no-op.
  *
  * @remarks
@@ -6947,7 +6994,7 @@ interface FieldRule {
     readonly severity?: FindingSeverity;
 }
 /**
- * A rule for one **segment type** (roadmap Phase U). `usage` constrains whether
+ * A rule for one **segment type**. `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.
@@ -6969,7 +7016,7 @@ interface SegmentRule {
     readonly severity?: FindingSeverity;
 }
 /**
- * A **user-authored, declarative** conformance profile (roadmap Phase U). The
+ * A **user-authored, declarative** conformance profile. 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
@@ -7101,7 +7148,7 @@ interface ConformanceResult {
 }
 
 /**
- * The conformance-profile engine (roadmap Phase U): `validateAgainstProfile`.
+ * The conformance-profile engine: `validateAgainstProfile`.
  * Runs a **consumer-authored** declarative {@link ConformanceProfile} against a
  * parsed {@link Hl7Message} and returns typed {@link ConformanceFinding}s.
  *
@@ -7123,7 +7170,7 @@ interface ConformanceResult {
 
 /**
  * Validate a parsed HL7 v2 message against a **user-authored** declarative
- * conformance profile (roadmap Phase U) and return typed findings.
+ * conformance profile 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
@@ -7167,7 +7214,7 @@ interface ConformanceResult {
 declare function validateAgainstProfile(message: Hl7Message, profile: ConformanceProfile): ConformanceResult;
 
 /**
- * Profile-shape validation for the conformance engine (roadmap Phase U). A
+ * Profile-shape validation for the conformance engine. A
  * conformance profile is **consumer-authored configuration**, so it can be
  * malformed. Two entry points share one total defect collector:
  *
@@ -7209,9 +7256,9 @@ interface ProfileDefect {
  */
 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
+ * The **fail-fast authoring** gate for a conformance profile: a malformed
+ * profile raises a typed `ProfileDefinitionError` at build time, before any
+ * validation runs. Runs {@link collectProfileDefects}; on any defect, throws a
  * single {@link ProfileDefinitionError} listing every defect. On success,
  * returns the profile typed as {@link ConformanceProfile}.
  *
@@ -7236,7 +7283,7 @@ declare function collectProfileDefects(profile: unknown): readonly ProfileDefect
 declare function defineConformanceProfile(profile: unknown): ConformanceProfile;
 
 /**
- * Barrel for the conformance-profile engine (roadmap Phase U). Re-exports the
+ * Barrel for the conformance-profile engine. 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.
  *
@@ -7265,8 +7312,8 @@ declare namespace index {
 }
 
 /**
- * Streaming / incremental parse for the `@cosyte/hl7` parser (roadmap
- * Phase S). Real ELR / IIS / lab feeds and files ship many messages and can be
+ * Streaming / incremental parse for the `@cosyte/hl7` parser. 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