@cosyte/hl7 0.0.2 → 0.0.4

package/dist/index.cjs

@@ -38,7 +38,7 @@ var ProfileDefinitionError = class extends Error {
   profileName;
   /**
    * 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
@@ -255,7 +255,104 @@ var KNOWN_SEGMENTS = /* @__PURE__ */ new Set([
   "CSS"
 ]);
 
+// src/parser/charset.ts
+function normalizeLabel(raw) {
+  return raw.trim().replace(/\s+/gu, " ").toUpperCase();
+}
+function decodeEntry(canonical, decoder) {
+  return { canonical, treatment: "decode", decoder };
+}
+function verbatimEntry(canonical) {
+  return { canonical, treatment: "verbatim", decoder: "" };
+}
+function buildTable() {
+  const table = /* @__PURE__ */ new Map();
+  const add = (aliases, entry) => {
+    for (const alias of aliases) table.set(normalizeLabel(alias), entry);
+  };
+  add(["ASCII", "US-ASCII", "ISO IR6"], decodeEntry("ASCII", "utf-8"));
+  add(["UTF-8", "UTF8", "UNICODE UTF-8", "UNICODE"], decodeEntry("UTF-8", "utf-8"));
+  add(["8859/1", "ISO-8859-1", "ISO 8859-1", "ISO8859-1"], decodeEntry("8859/1", "latin1"));
+  for (const n of [2, 3, 4, 5, 6, 7, 8, 10, 13, 14, 15, 16]) {
+    add(
+      [`8859/${n}`, `ISO-8859-${n}`, `ISO 8859-${n}`, `ISO8859-${n}`],
+      decodeEntry(`8859/${n}`, `iso-8859-${n}`)
+    );
+  }
+  add(["8859/9", "ISO-8859-9", "ISO 8859-9", "ISO8859-9"], verbatimEntry("8859/9"));
+  add(["8859/11", "ISO-8859-11", "ISO 8859-11", "ISO8859-11"], verbatimEntry("8859/11"));
+  add(["ISO IR14", "JIS X 0201"], verbatimEntry("ISO IR14"));
+  add(["ISO IR87", "JIS X 0208"], verbatimEntry("ISO IR87"));
+  add(["ISO IR159", "JIS X 0212"], verbatimEntry("ISO IR159"));
+  add(["GB 18030-2000", "GB18030", "GB 18030"], verbatimEntry("GB 18030-2000"));
+  add(["KS X 1001", "KSX1001", "KS C 5601"], verbatimEntry("KS X 1001"));
+  add(["CNS 11643-1992", "CNS 11643"], verbatimEntry("CNS 11643-1992"));
+  add(["BIG-5", "BIG5"], verbatimEntry("BIG-5"));
+  add(["UNICODE UTF-16", "UTF-16"], verbatimEntry("UNICODE UTF-16"));
+  add(["UNICODE UTF-32", "UTF-32"], verbatimEntry("UNICODE UTF-32"));
+  return table;
+}
+var CHARSET_TABLE = buildTable();
+var DEFAULT_RESOLUTION = Object.freeze({
+  canonical: "ASCII",
+  treatment: "decode",
+  decoder: "utf-8",
+  recognized: true
+});
+function resolveCharset(raw) {
+  if (raw === void 0) return DEFAULT_RESOLUTION;
+  const key = normalizeLabel(raw);
+  if (key === "") return DEFAULT_RESOLUTION;
+  const entry = CHARSET_TABLE.get(key);
+  if (entry !== void 0) {
+    return {
+      canonical: entry.canonical,
+      treatment: entry.treatment,
+      decoder: entry.decoder,
+      recognized: true
+    };
+  }
+  return { canonical: key, treatment: "verbatim", decoder: "", recognized: false };
+}
+function canonicalCharset(raw) {
+  return resolveCharset(raw).canonical;
+}
+
+// src/parser/tokens.ts
+var DERIVED_TOKEN_SHAPES = {
+  /**
+   * HL7 v2 Ch. 2 §2.5 segment identifier: three characters, the first
+   * alphabetic.
+   *
+   * Two deliberate tightenings, each measured rather than assumed. The first
+   * version allowed four characters as "vendor tolerance", which was invented
+   * rather than grounded: all 91 `KNOWN_SEGMENTS` are exactly three, and
+   * `defineProfile` independently validates custom Z-segments to
+   * `/^Z[A-Z0-9]{2}$/`, so nothing legitimate is longer. The second requires a
+   * leading letter, which every known segment and every legal Z-segment
+   * satisfies, and which excludes a **bare numeric** residue. That matters out
+   * of proportion to its size: a forged line reading `120` is a glucose, a
+   * blood pressure or a dose, which is the most clinical meaning three
+   * characters can carry.
+   */
+  segmentId: /^[A-Za-z][A-Za-z0-9]{2}$/,
+  /** MSH-9 message type / trigger, e.g. `ADT^A01` or `A40`. */
+  messageType: /^[A-Za-z0-9]{1,8}(?:\^[A-Za-z0-9]{1,8}){0,2}$/,
+  /** MSH-12 version ID, e.g. `2.5` or `2.5.1`. */
+  version: /^[0-9]{1,2}(?:\.[0-9]{1,3}){0,3}$/
+};
+function safeDerivedToken(value, kind) {
+  return DERIVED_TOKEN_SHAPES[kind].test(value) ? value : WITHHELD;
+}
+var WITHHELD = "<withheld>";
+function boundedIdentifier(value, kind) {
+  return value === "" ? "" : safeDerivedToken(value, kind);
+}
+
 // src/parser/warnings.ts
+function safeCharsetLabel(value) {
+  return resolveCharset(value).recognized ? value : WITHHELD;
+}
 var WARNING_CODES = {
   MLLP_FRAMING_STRIPPED: "MLLP_FRAMING_STRIPPED",
   FIELD_WHITESPACE_TRIMMED: "FIELD_WHITESPACE_TRIMMED",
@@ -340,28 +437,28 @@ function timestampFallbackFormat(position, matchedFormat) {
 function segmentCase(position, observed) {
   return {
     code: WARNING_CODES.SEGMENT_CASE,
-    message: `Segment identifier "${observed}" is not uppercase; normalized to "${observed.toUpperCase()}".`,
+    message: `Segment identifier "${safeDerivedToken(observed, "segmentId")}" is not uppercase; normalized to "${safeDerivedToken(observed.toUpperCase(), "segmentId")}".`,
     position
   };
 }
 function extraFields(position, segmentName2, extraCount) {
   return {
     code: WARNING_CODES.EXTRA_FIELDS,
-    message: `Segment "${segmentName2}" has ${String(extraCount)} more field(s) than the profile declares.`,
+    message: `Segment "${safeDerivedToken(segmentName2, "segmentId")}" has ${String(extraCount)} more field(s) than the profile declares.`,
     position
   };
 }
 function unknownSegment(position, segmentName2) {
   return {
     code: WARNING_CODES.UNKNOWN_SEGMENT,
-    message: `Unknown segment "${segmentName2}": not in HL7 spec and no profile claim.`,
+    message: `Unknown segment "${safeDerivedToken(segmentName2, "segmentId")}": not in HL7 spec and no profile claim.`,
     position
   };
 }
 function duplicateRequiredSegment(position, segmentName2) {
   return {
     code: WARNING_CODES.DUPLICATE_REQUIRED_SEGMENT,
-    message: `Required singleton segment "${segmentName2}" appears more than once.`,
+    message: `Required singleton segment "${safeDerivedToken(segmentName2, "segmentId")}" appears more than once.`,
     position
   };
 }
@@ -375,42 +472,42 @@ function encodingMismatch(position, detail) {
 function missingRequiredField(position, segmentName2, fieldIndex) {
   return {
     code: WARNING_CODES.MISSING_REQUIRED_FIELD,
-    message: `Required field ${segmentName2}-${String(fieldIndex)} is missing or empty.`,
+    message: `Required field ${safeDerivedToken(segmentName2, "segmentId")}-${String(fieldIndex)} is missing or empty.`,
     position
   };
 }
 function missingExpectedGroup(position, messageType, groupName, anchorSegments) {
   return {
     code: WARNING_CODES.MISSING_EXPECTED_GROUP,
-    message: `Message type "${messageType}" is missing its expected "${groupName}" segment group (no ${anchorSegments.join("/")}); message may be truncated or misrouted.`,
+    message: `Message type "${safeDerivedToken(messageType, "messageType")}" is missing its expected "${groupName}" segment group (no ${anchorSegments.join("/")}); message may be truncated or misrouted.`,
     position
   };
 }
 function outOfOrderSegment(position, segmentName2) {
   return {
     code: WARNING_CODES.OUT_OF_ORDER_SEGMENT,
-    message: `Segment "${segmentName2}" appears out of the order declared by the active profile.`,
+    message: `Segment "${safeDerivedToken(segmentName2, "segmentId")}" appears out of the order declared by the active profile.`,
     position
   };
 }
 function versionMismatch(position, declared, expected) {
   return {
     code: WARNING_CODES.VERSION_MISMATCH,
-    message: `HL7 version mismatch: message declares "${declared}", expected "${expected}".`,
+    message: `HL7 version mismatch: message declares "${safeDerivedToken(declared, "version")}", expected "${expected}".`,
     position
   };
 }
 function unknownCharset(position, requested) {
   return {
     code: WARNING_CODES.UNKNOWN_CHARSET,
-    message: `Unrecognized character set "${requested}"; not decoded, bytes read as latin1.`,
+    message: `Unrecognized character set "${safeCharsetLabel(requested)}"; not decoded, bytes read as latin1.`,
     position
   };
 }
 function unsupportedCharset(position, code) {
   return {
     code: WARNING_CODES.UNSUPPORTED_CHARSET,
-    message: `Character set "${code}" was not decoded; bytes read as latin1.`,
+    message: `Character set "${safeCharsetLabel(code)}" was not decoded; bytes read as latin1.`,
     position
   };
 }
@@ -425,7 +522,7 @@ function mergeMissingPriorOrSurvivor(position, eventType, missing) {
   const detail = missing === "prior" ? "no MRG segment carries a usable prior (non-surviving) identifier" : "no PID segment carries a usable surviving identifier";
   return {
     code: WARNING_CODES.MERGE_MISSING_PRIOR_OR_SURVIVOR,
-    message: `Identity event "${eventType}" is missing its ${missing} role: ${detail}. Surfacing what is present; the MRG->PID merge direction is not guessed.`,
+    message: `Identity event "${safeDerivedToken(eventType, "messageType")}" is missing its ${missing} role: ${detail}. Surfacing what is present; the MRG->PID merge direction is not guessed.`,
     position
   };
 }
@@ -471,69 +568,6 @@ function emitIfFramed(result, emit, position) {
   }
 }
 
-// src/parser/charset.ts
-function normalizeLabel(raw) {
-  return raw.trim().replace(/\s+/gu, " ").toUpperCase();
-}
-function decodeEntry(canonical, decoder) {
-  return { canonical, treatment: "decode", decoder };
-}
-function verbatimEntry(canonical) {
-  return { canonical, treatment: "verbatim", decoder: "" };
-}
-function buildTable() {
-  const table = /* @__PURE__ */ new Map();
-  const add = (aliases, entry) => {
-    for (const alias of aliases) table.set(normalizeLabel(alias), entry);
-  };
-  add(["ASCII", "US-ASCII", "ISO IR6"], decodeEntry("ASCII", "utf-8"));
-  add(["UTF-8", "UTF8", "UNICODE UTF-8", "UNICODE"], decodeEntry("UTF-8", "utf-8"));
-  add(["8859/1", "ISO-8859-1", "ISO 8859-1", "ISO8859-1"], decodeEntry("8859/1", "latin1"));
-  for (const n of [2, 3, 4, 5, 6, 7, 8, 10, 13, 14, 15, 16]) {
-    add(
-      [`8859/${n}`, `ISO-8859-${n}`, `ISO 8859-${n}`, `ISO8859-${n}`],
-      decodeEntry(`8859/${n}`, `iso-8859-${n}`)
-    );
-  }
-  add(["8859/9", "ISO-8859-9", "ISO 8859-9", "ISO8859-9"], verbatimEntry("8859/9"));
-  add(["8859/11", "ISO-8859-11", "ISO 8859-11", "ISO8859-11"], verbatimEntry("8859/11"));
-  add(["ISO IR14", "JIS X 0201"], verbatimEntry("ISO IR14"));
-  add(["ISO IR87", "JIS X 0208"], verbatimEntry("ISO IR87"));
-  add(["ISO IR159", "JIS X 0212"], verbatimEntry("ISO IR159"));
-  add(["GB 18030-2000", "GB18030", "GB 18030"], verbatimEntry("GB 18030-2000"));
-  add(["KS X 1001", "KSX1001", "KS C 5601"], verbatimEntry("KS X 1001"));
-  add(["CNS 11643-1992", "CNS 11643"], verbatimEntry("CNS 11643-1992"));
-  add(["BIG-5", "BIG5"], verbatimEntry("BIG-5"));
-  add(["UNICODE UTF-16", "UTF-16"], verbatimEntry("UNICODE UTF-16"));
-  add(["UNICODE UTF-32", "UTF-32"], verbatimEntry("UNICODE UTF-32"));
-  return table;
-}
-var CHARSET_TABLE = buildTable();
-var DEFAULT_RESOLUTION = Object.freeze({
-  canonical: "ASCII",
-  treatment: "decode",
-  decoder: "utf-8",
-  recognized: true
-});
-function resolveCharset(raw) {
-  if (raw === void 0) return DEFAULT_RESOLUTION;
-  const key = normalizeLabel(raw);
-  if (key === "") return DEFAULT_RESOLUTION;
-  const entry = CHARSET_TABLE.get(key);
-  if (entry !== void 0) {
-    return {
-      canonical: entry.canonical,
-      treatment: entry.treatment,
-      decoder: entry.decoder,
-      recognized: true
-    };
-  }
-  return { canonical: key, treatment: "verbatim", decoder: "", recognized: false };
-}
-function canonicalCharset(raw) {
-  return resolveCharset(raw).canonical;
-}
-
 // src/parser/normalize.ts
 var CHARSET_POSITION = { segmentIndex: 0, fieldIndex: 18 };
 function preserveVerbatim(input) {
@@ -928,8 +962,8 @@ function analyzeMessageStructure(messageCode, triggerEvent, presentSegmentNames)
   if (def === void 0) {
     return Object.freeze({
       recognized: false,
-      messageCode,
-      triggerEvent,
+      messageCode: boundedIdentifier(messageCode, "segmentId"),
+      triggerEvent: boundedIdentifier(triggerEvent, "segmentId"),
       expectedGroups: Object.freeze([]),
       missingGroups: Object.freeze([])
     });
@@ -1863,11 +1897,11 @@ var Field = class {
   isNull;
   /** Reference to the underlying `RawField.repetitions` (no defensive copy). */
   repetitions;
-  /** 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 */
   enc;
   /** Position of this field in the parent message: used for position-aware error messages. @internal */
   position;
-  /** 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 */
   raw;
   /**
    * Construct a new `Field`. Called internally by `Segment.field(n)`; user
@@ -1884,7 +1918,7 @@ var Field = class {
   /**
    * 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
@@ -1915,7 +1949,7 @@ var Field = class {
    * 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
@@ -2161,7 +2195,24 @@ var EMPTY_REP = Object.freeze({
 
 // src/model/segment.ts
 var Segment = class {
-  /** 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)`.
+   */
   type;
   /** Reference to the underlying `RawSegment.fields`: 1-indexed per HL7 convention. */
   fields;
@@ -2169,7 +2220,7 @@ var Segment = class {
   enc;
   /** Absolute index of this segment in `Hl7Message.rawSegments[]`. Used for position tracking. @internal */
   absoluteIndex;
-  /** The full `RawSegment` this wrapper wraps. Exposed for mutation methods (Plan 04). @internal */
+  /** The full `RawSegment` this wrapper wraps. Exposed for mutation methods. @internal */
   raw;
   /**
    * Lookup map from profile-declared field name → 1-indexed HL7 position.
@@ -2186,7 +2237,7 @@ var Segment = class {
    * 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`.
@@ -2194,7 +2245,7 @@ var Segment = class {
    */
   constructor(raw, enc, absoluteIndex, customFields) {
     this.raw = raw;
-    this.type = raw.name;
+    this.type = boundedIdentifier(raw.name, "segmentId");
     this.fields = raw.fields;
     this.enc = enc;
     this.absoluteIndex = absoluteIndex;
@@ -3881,11 +3932,20 @@ var Hl7Message = class {
    * 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.
    */
   rawSegments;
   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.
+   */
   version;
   warnings;
   profile;
@@ -3898,7 +3958,7 @@ var Hl7Message = class {
   dateFormats;
   /**
    * 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
    */
@@ -3907,40 +3967,40 @@ var Hl7Message = class {
    * 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
    */
   _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
    */
   _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
    */
   _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
    */
   _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
    */
   _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
@@ -3956,7 +4016,7 @@ var Hl7Message = class {
   constructor(init) {
     this.rawSegments = init.segments;
     this.encodingCharacters = init.encodingCharacters;
-    this.version = init.version;
+    this.version = boundedIdentifier(init.version, "version");
     this.warnings = Object.freeze(init.warnings.slice());
     this.profile = init.profile;
     if (init.customSegments !== void 0) this._customSegments = init.customSegments;
@@ -3964,8 +4024,8 @@ var Hl7Message = class {
   }
   /**
    * 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).
    *
@@ -4000,7 +4060,7 @@ var Hl7Message = class {
    * 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
@@ -4023,7 +4083,7 @@ var Hl7Message = class {
    * 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
@@ -4057,7 +4117,7 @@ var Hl7Message = class {
    * @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"
    * ```
    */
@@ -4065,8 +4125,8 @@ var Hl7Message = class {
     return this._meta ??= buildMeta(this);
   }
   /**
-   * 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
@@ -4134,7 +4194,7 @@ var Hl7Message = class {
   }
   /**
    * 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.
    *
@@ -4150,7 +4210,7 @@ var Hl7Message = class {
     return orders(this);
   }
   /**
-   * 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
@@ -4167,7 +4227,7 @@ var Hl7Message = class {
   }
   /**
    * 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
@@ -4188,13 +4248,13 @@ var Hl7Message = class {
   }
   /**
    * 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
@@ -4211,7 +4271,7 @@ var Hl7Message = class {
   /**
    * 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
@@ -4279,7 +4339,7 @@ var Hl7Message = class {
     return insurance(this);
   }
   /**
-   * 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
@@ -4299,7 +4359,7 @@ var Hl7Message = class {
     return appointments(this);
   }
   /**
-   * 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
@@ -4319,7 +4379,7 @@ var Hl7Message = class {
     return documents(this);
   }
   /**
-   * 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
@@ -4413,7 +4473,7 @@ var Hl7Message = class {
    * `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")`.
@@ -4499,11 +4559,11 @@ var Hl7Message = class {
     return 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 `^`/`&`/`~`.
@@ -4694,8 +4754,8 @@ var Hl7Message = class {
     return 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
@@ -4794,7 +4854,12 @@ function resolveBufferCharset(raw, options, emit) {
       emit(
         encodingMismatch(
           { segmentIndex: 0 },
-          `options.charset="${override}" disagrees with MSH-18="${declared}"`
+          // `declared` is MSH-18 read off the wire. On a message with no
+          // segment terminators it is not MSH-18 at all but the 18th
+          // `|`-token of the flattened message, commonly a data field, so it
+          // is shape-checked before it reaches a log surface. `override` is
+          // the caller's own `options.charset`, not input, and is left alone.
+          `options.charset="${override}" disagrees with MSH-18="${safeCharsetLabel(declared)}"`
         )
       );
     }
@@ -6809,7 +6874,7 @@ async function* parseStream(source, optionsOrProfile) {
 }
 
 // src/index.ts
-var VERSION = "0.0.2";
+var VERSION = "0.0.4";
 
 exports.ACK_CODES = ACK_CODES;
 exports.ACK_CONDITIONS = ACK_CONDITIONS;