@cosyte/hl7 0.0.2 → 0.0.4

package/dist/index.mjs

@@ -36,7 +36,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
@@ -253,7 +253,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",
@@ -338,28 +435,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
   };
 }
@@ -373,42 +470,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
   };
 }
@@ -423,7 +520,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
   };
 }
@@ -469,69 +566,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) {
@@ -926,8 +960,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([])
     });
@@ -1861,11 +1895,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
@@ -1882,7 +1916,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
@@ -1913,7 +1947,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
@@ -2159,7 +2193,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;
@@ -2167,7 +2218,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.
@@ -2184,7 +2235,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`.
@@ -2192,7 +2243,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;
@@ -3879,11 +3930,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;
@@ -3896,7 +3956,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
    */
@@ -3905,40 +3965,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
@@ -3954,7 +4014,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;
@@ -3962,8 +4022,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).
    *
@@ -3998,7 +4058,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
@@ -4021,7 +4081,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
@@ -4055,7 +4115,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"
    * ```
    */
@@ -4063,8 +4123,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
@@ -4132,7 +4192,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.
    *
@@ -4148,7 +4208,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
@@ -4165,7 +4225,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
@@ -4186,13 +4246,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
@@ -4209,7 +4269,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
@@ -4277,7 +4337,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
@@ -4297,7 +4357,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
@@ -4317,7 +4377,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
@@ -4411,7 +4471,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")`.
@@ -4497,11 +4557,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 `^`/`&`/`~`.
@@ -4692,8 +4752,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
@@ -4792,7 +4852,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)}"`
         )
       );
     }
@@ -6807,7 +6872,7 @@ async function* parseStream(source, optionsOrProfile) {
 }
 
 // src/index.ts
-var VERSION = "0.0.2";
+var VERSION = "0.0.4";
 
 export { ACK_CODES, ACK_CONDITIONS, BUILTIN_DATE_FALLBACKS, DEFAULT_ENCODING_CHARACTERS, ERR_CONDITION_CODES, ERR_CONDITION_CODE_SYSTEM, ERR_SEVERITIES, FATAL_CODES, FINDING_CODES, Field, namespace_exports as HL7, Hl7Message, Hl7ParseError, KNOWN_CODING_SYSTEMS, KNOWN_SEGMENTS, MESSAGE_STRUCTURE_DEFINITIONS, ProfileDefinitionError, SUPPORTED_DATE_TOKENS, Segment, USAGE_CODES, VERSION, WARNING_CODES, ackNoCorrelationId, alternateCodingSystemOf, analyzeMessageStructure, batchCountMismatch, batchMissingTrailer, buildAck, buildAdt, buildMessage, buildOru, canonicalCharset, codingSystem, codingSystemOf, conformance_exports as conformance, decodeText, defineConformanceProfile, defineProfile, detectAckMode, downgradePositiveAck, dtmToDate, duplicateRequiredSegment, encodeCe, encodeComposite, encodeCompositeReps, encodeCwe, encodeCx, encodeHd, encodeNm, encodePl, encodeText, encodeTs, encodeXad, encodeXcn, encodeXpn, encodeXtn, encodingMismatch, extraFields, fieldWhitespaceTrimmed, formatDtm, getDefaultProfile, interpretAck, isPositiveAck, mergeMissingPriorOrSurvivor, missingExpectedGroup, missingRequiredField, mllpFramingStripped, outOfOrderSegment, parseCe, parseCwe, parseCx, parseDtm, parseHL7, parseHd, parseNm, parsePath, parsePl, parseSn, parseStream, parseTs, parseXad, parseXcn, parseXpn, parseXtn, pickMrn, profiles, reescape, renderText, resolveCharset, resolvePath, segmentCase, setDefaultProfile, splitBatch, text_exports as text, timestampFallbackFormat, unescape, unknownCharset, unknownEscapeSequence, unknownSegment, unsupportedCharset, unterminatedEscapeSequence, unterminatedStreamMessage, validateAgainstProfile, versionMismatch };
 //# sourceMappingURL=index.mjs.map