@cosyte/hl7 0.0.3 → 0.0.5

package/dist/index.d.cts

@@ -248,7 +248,8 @@ declare function missingRequiredField(position: Hl7Position, segmentName: string
  * 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
@@ -2314,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[];
@@ -3602,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[];
@@ -3985,6 +4013,16 @@ declare class Hl7Message {
      */
     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: {
@@ -4646,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

package/dist/index.d.ts

@@ -248,7 +248,8 @@ declare function missingRequiredField(position: Hl7Position, segmentName: string
  * 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
@@ -2314,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[];
@@ -3602,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[];
@@ -3985,6 +4013,16 @@ declare class Hl7Message {
      */
     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: {
@@ -4646,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

package/dist/index.mjs

@@ -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([])
     });
@@ -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;
@@ -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;
@@ -3883,6 +3934,16 @@ var Hl7Message = class {
    */
   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;
@@ -3953,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;
@@ -4791,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)}"`
         )
       );
     }
@@ -6806,7 +6872,7 @@ async function* parseStream(source, optionsOrProfile) {
 }
 
 // src/index.ts
-var VERSION = "0.0.3";
+var VERSION = "0.0.5";
 
 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