@cosyte/hl7 0.0.1 → 0.0.2

package/dist/index.mjs

@@ -1,6 +1,12 @@
 import { randomBytes } from 'crypto';
 import { Buffer } from 'buffer';
 
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
 // src/parser/errors.ts
 var FATAL_CODES = {
   NO_MSH_SEGMENT: "NO_MSH_SEGMENT",
@@ -66,7 +72,7 @@ function readDelimiters(firstSegment) {
   if (firstSegment.length < 3 || firstSegment.slice(0, 3) !== "MSH") {
     throw new Hl7ParseError(
       FATAL_CODES.NO_MSH_SEGMENT,
-      "First segment is not MSH \u2014 HL7 v2 messages must begin with an MSH segment.",
+      "First segment is not MSH: HL7 v2 messages must begin with an MSH segment.",
       fatalPosition,
       snip
     );
@@ -74,7 +80,7 @@ function readDelimiters(firstSegment) {
   if (firstSegment.length < 8) {
     throw new Hl7ParseError(
       FATAL_CODES.MSH_TOO_SHORT,
-      "MSH segment is truncated \u2014 cannot read encoding characters.",
+      "MSH segment is truncated: cannot read encoding characters.",
       fatalPosition,
       snip
     );
@@ -83,7 +89,7 @@ function readDelimiters(firstSegment) {
   if (/\s/u.test(field)) {
     throw new Hl7ParseError(
       FATAL_CODES.INVALID_ENCODING_CHARACTERS,
-      "MSH-1 field separator is whitespace \u2014 refusing to parse.",
+      "MSH-1 field separator is whitespace: refusing to parse.",
       fatalPosition,
       snip
     );
@@ -267,7 +273,8 @@ var WARNING_CODES = {
   ACK_NO_CORRELATION_ID: "ACK_NO_CORRELATION_ID",
   MERGE_MISSING_PRIOR_OR_SURVIVOR: "MERGE_MISSING_PRIOR_OR_SURVIVOR",
   BATCH_COUNT_MISMATCH: "BATCH_COUNT_MISMATCH",
-  BATCH_MISSING_TRAILER: "BATCH_MISSING_TRAILER"
+  BATCH_MISSING_TRAILER: "BATCH_MISSING_TRAILER",
+  UNTERMINATED_STREAM_MESSAGE: "UNTERMINATED_STREAM_MESSAGE"
 };
 function mllpFramingStripped(position) {
   return {
@@ -345,7 +352,7 @@ function extraFields(position, segmentName2, extraCount) {
 function unknownSegment(position, segmentName2) {
   return {
     code: WARNING_CODES.UNKNOWN_SEGMENT,
-    message: `Unknown segment "${segmentName2}" \u2014 not in HL7 spec and no profile claim.`,
+    message: `Unknown segment "${segmentName2}": not in HL7 spec and no profile claim.`,
     position
   };
 }
@@ -430,7 +437,14 @@ function batchCountMismatch(position, unit, declared, actual) {
 function batchMissingTrailer(position, header, expectedTrailer) {
   return {
     code: WARNING_CODES.BATCH_MISSING_TRAILER,
-    message: `Batch envelope header "${header}" has no matching "${expectedTrailer}" trailer; splitBatch surfaces this but does not reject \u2014 a profile that mandates the full envelope may.`,
+    message: `Batch envelope header "${header}" has no matching "${expectedTrailer}" trailer; splitBatch surfaces this but does not reject: a profile that mandates the full envelope may.`,
+    position
+  };
+}
+function unterminatedStreamMessage(position) {
+  return {
+    code: WARNING_CODES.UNTERMINATED_STREAM_MESSAGE,
+    message: "The final message in the stream ended without a segment terminator; it is still yielded in full. If the source terminates every segment, this may indicate a truncated feed.",
     position
   };
 }
@@ -586,7 +600,7 @@ var RECOGNIZED_PRESERVED_SET = /* @__PURE__ */ new Set([
   "H",
   // begin highlighting (§2.7.1)
   "N",
-  // normal text — end highlighting (§2.7.1)
+  // normal text: end highlighting (§2.7.1)
   ".sp",
   // vertical skip (§2.7.6)
   ".in",
@@ -773,7 +787,7 @@ function tokenizeComponent(raw, enc, emit, position) {
 var MESSAGE_STRUCTURE_DEFINITIONS = Object.freeze([
   // ── ADT (Ch. 3): patient identification (PID) + visit (PV1) are Required
   //    for these admit/transfer/discharge/register/update/cancel events.
-  //    EVN is intentionally excluded — real senders omit it freely, making it
+  //    EVN is intentionally excluded: real senders omit it freely, making it
   //    a weak (false-positive-prone) signal.
   Object.freeze({
     messageCode: "ADT",
@@ -785,7 +799,7 @@ var MESSAGE_STRUCTURE_DEFINITIONS = Object.freeze([
   }),
   // ── ORU^R01 (Ch. 7): the OBR/OBX result group is the Required payload.
   //    PID is excluded (the patient-result group's PID is R within the group,
-  //    but a result-only relay can legitimately omit it at the top — keep the
+  //    but a result-only relay can legitimately omit it at the top: keep the
   //    anchor on the result segments themselves, the true truncation signal).
   Object.freeze({
     messageCode: "ORU",
@@ -795,7 +809,7 @@ var MESSAGE_STRUCTURE_DEFINITIONS = Object.freeze([
     ])
   }),
   // ── Orders (Ch. 4): ORC is the Required common-order segment across the
-  //    order message family. OBR is excluded — it is Optional in several of
+  //    order message family. OBR is excluded: it is Optional in several of
   //    these (OML/OMG/OMI carry it inside an optional observation-request
   //    group), so anchoring only on ORC avoids a false positive.
   Object.freeze({
@@ -858,7 +872,7 @@ var MESSAGE_STRUCTURE_DEFINITIONS = Object.freeze([
       Object.freeze({ name: "schedule", anchorSegments: Object.freeze(["SCH"]) })
     ])
   }),
-  // ── MDM (Ch. 9): document management — PID + the TXA document header are
+  // ── MDM (Ch. 9): document management: PID + the TXA document header are
   //    Required for T02 (original document) and T06 (document addendum).
   Object.freeze({
     messageCode: "MDM",
@@ -868,7 +882,7 @@ var MESSAGE_STRUCTURE_DEFINITIONS = Object.freeze([
       Object.freeze({ name: "document", anchorSegments: Object.freeze(["TXA"]) })
     ])
   }),
-  // ── DFT^P03 (Ch. 6): financial transaction — PID + at least one FT1
+  // ── DFT^P03 (Ch. 6): financial transaction: PID + at least one FT1
   //    financial-transaction segment are Required.
   Object.freeze({
     messageCode: "DFT",
@@ -878,7 +892,7 @@ var MESSAGE_STRUCTURE_DEFINITIONS = Object.freeze([
       Object.freeze({ name: "financial", anchorSegments: Object.freeze(["FT1"]) })
     ])
   }),
-  // ── VXU^V04 (CDC IG): immunization update — PID is Required. RXA is
+  // ── VXU^V04 (CDC IG): immunization update: PID is Required. RXA is
   //    excluded: it lives in the Optional order group of the CDC IG, so a
   //    query-shaped VXU with no administered vaccine must not warn.
   Object.freeze({
@@ -888,7 +902,7 @@ var MESSAGE_STRUCTURE_DEFINITIONS = Object.freeze([
       Object.freeze({ name: "patient", anchorSegments: Object.freeze(["PID"]) })
     ])
   }),
-  // ── ACK (Ch. 2): a general acknowledgment — MSA (message acknowledgment) is
+  // ── ACK (Ch. 2): a general acknowledgment: MSA (message acknowledgment) is
   //    Required. Matched on message code alone (no trigger event in MSH-9.2).
   Object.freeze({
     messageCode: "ACK",
@@ -1018,7 +1032,7 @@ function parsePath(path) {
   }
   if (i !== path.length) {
     throw new TypeError(
-      `Invalid HL7 dot-path: "${path}" (trailing content at position ${String(i)} \u2014 too deep or malformed).`
+      `Invalid HL7 dot-path: "${path}" (trailing content at position ${String(i)}: too deep or malformed).`
     );
   }
   return freezeDotPath(out);
@@ -1144,6 +1158,127 @@ function emitSegment(seg, enc) {
   return parts.join(enc.field);
 }
 
+// src/text/render.ts
+var FORMATTING_RE = /^\.(br|sp|in|ti|fi|nf|ce|sk)[ +]?([+-]?\d+)?$/u;
+var DEFAULT_TRUNCATION_CHAR2 = "#";
+var MAX_FORMAT_REPEAT = 100;
+function normalizeBreaks(s, newline) {
+  return s.replace(/\r\n|\r|\n/gu, newline);
+}
+function clampCount(arg) {
+  if (arg === void 0) return 1;
+  const n = Math.trunc(Number(arg));
+  if (!Number.isFinite(n) || n < 1) return 1;
+  return Math.min(n, MAX_FORMAT_REPEAT);
+}
+function renderText(input, enc = DEFAULT_ENCODING_CHARACTERS, opts) {
+  const esc = enc.escape;
+  const newline = opts?.newline ?? "\n";
+  const runs = [];
+  const unrendered = [];
+  let highlighted = false;
+  let current = "";
+  const flush = () => {
+    if (current !== "") {
+      runs.push({ text: current, highlighted });
+      current = "";
+    }
+  };
+  let i = 0;
+  const len = input.length;
+  while (i < len) {
+    const ch = input.charAt(i);
+    if (ch === "\r" || ch === "\n") {
+      current += newline;
+      i += ch === "\r" && input.charAt(i + 1) === "\n" ? 2 : 1;
+      continue;
+    }
+    if (ch !== esc) {
+      current += ch;
+      i++;
+      continue;
+    }
+    const close = input.indexOf(esc, i + 1);
+    if (close === -1) {
+      const tail = input.slice(i);
+      current += tail;
+      unrendered.push(tail);
+      break;
+    }
+    const body = input.slice(i + 1, close);
+    const literal = esc + body + esc;
+    if (body === "H") {
+      flush();
+      highlighted = true;
+    } else if (body === "N") {
+      flush();
+      highlighted = false;
+    } else {
+      const decoded = decodeBody(body, enc, newline);
+      if (decoded !== null) {
+        current += decoded;
+      } else {
+        current += literal;
+        unrendered.push(literal);
+      }
+    }
+    i = close + 1;
+  }
+  flush();
+  const text = runs.reduce((acc, r) => acc + r.text, "");
+  return { text, runs, unrenderedSequences: unrendered };
+}
+function decodeBody(body, enc, newline) {
+  switch (body) {
+    case "F":
+      return enc.field;
+    case "S":
+      return enc.component;
+    case "T":
+      return enc.subcomponent;
+    case "R":
+      return enc.repetition;
+    case "E":
+      return enc.escape;
+    case "P":
+      return enc.truncation ?? DEFAULT_TRUNCATION_CHAR2;
+  }
+  if (body.charAt(0) === ".") {
+    const m = FORMATTING_RE.exec(body);
+    if (m !== null) return renderFormatting(m[1] ?? "", m[2], newline);
+    return null;
+  }
+  if (body.charAt(0) === "X") {
+    const hex = body.slice(1);
+    if (hex.length === 0 || hex.length % 2 !== 0 || !/^[0-9A-Fa-f]+$/u.test(hex)) {
+      return null;
+    }
+    let out = "";
+    for (let j = 0; j < hex.length; j += 2) {
+      out += String.fromCharCode(parseInt(hex.slice(j, j + 2), 16));
+    }
+    return normalizeBreaks(out, newline);
+  }
+  return null;
+}
+function renderFormatting(cmd, arg, newline) {
+  switch (cmd) {
+    case "br":
+    case "ce":
+      return newline;
+    case "sp":
+      return newline.repeat(clampCount(arg));
+    case "sk":
+      return " ".repeat(clampCount(arg));
+    case "in":
+    case "ti":
+    case "fi":
+    case "nf":
+    default:
+      return "";
+  }
+}
+
 // src/model/types/_shared.ts
 function readSubcomponent(component, index, _enc) {
   if (component === void 0) return void 0;
@@ -1722,13 +1857,13 @@ function parseXtn(rep, enc) {
 // src/model/field.ts
 var DEFAULT_POSITION = { segmentIndex: 0 };
 var Field = class {
-  /** HL7 null indicator — `true` iff the underlying field was the two-char literal `""`. */
+  /** HL7 null indicator: `true` iff the underlying field was the two-char literal `""`. */
   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 */
   enc;
-  /** Position of this field in the parent message — used for position-aware error messages. @internal */
+  /** Position of this field in the parent message: used for position-aware error messages. @internal */
   position;
   /** The full `RawField` this wrapper wraps. Exposed for composite parsers (Plan 02/03/04). @internal */
   raw;
@@ -1746,7 +1881,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
+   * string: unescaped ONCE by the tokenizer on parse, returned verbatim here
    * (never re-unescaped, HL7-VALUE-REDECODE). Returns `""` when the field is
    * empty or HL7 null. Equivalent to `msg.get('SEG.N')` for a top-level access.
    *
@@ -1767,13 +1902,13 @@ var Field = class {
     return sub;
   }
   /**
-   * The field's **canonical wire text** — the full field re-serialized with
+   * The field's **canonical wire text**: the full field re-serialized with
    * the active delimiters and re-escaped content (repetitions, components,
    * and subcomponents included). Contrast with {@link value}, which
    * returns only the first subcomponent of the first component of the first
-   * repetition (decoded once at parse — never re-unescaped).
+   * repetition (decoded once at parse: never re-unescaped).
    *
-   * Use this when a field must be compared or echoed as a whole — e.g.
+   * Use this when a field must be compared or echoed as a whole: e.g.
    * correlating an ACK's MSA-2 against the inbound MSH-10, where a
    * vendor-quirk control id containing an unescaped delimiter (`ID^X`) must
    * not be truncated to its first component.
@@ -1792,7 +1927,7 @@ var Field = class {
    *
    * **MSH-1/MSH-2 caveat.** Like {@link value}, calling this on MSH-1 or
    * MSH-2 (the delimiter-definition fields) re-escapes the encoding
-   * characters themselves and produces garbage — those two fields are only
+   * characters themselves and produces garbage: those two fields are only
    * meaningful through `Hl7Message.encodingCharacters`.
    *
    * @example
@@ -1807,12 +1942,33 @@ var Field = class {
     return emitField(this.raw, this.enc);
   }
   /**
-   * Return a synthetic empty `Field` sentinel — used by `Segment.field(n)` to
+   * Render this field's formatted text (HL7 v2 §2.7 highlight + formatting
+   * escapes) into a normalized {@link RenderedText} display model: plain text
+   * plus highlight-aware runs. A **read projection** over the field's
+   * byte-verbatim wire {@link text}: it never mutates the raw value, and it
+   * never fabricates (an unrenderable escape is preserved + flagged). Use this
+   * to surface a clinical narrative (an NTE / OBX-5 note) to a human without
+   * the raw `\.br\` / `\H\` sentinels.
+   *
+   * @param opts - see {@link RenderTextOptions} (e.g. a custom line-break string).
+   * @returns the normalized display model.
+   *
+   * @example
+   * ```ts
+   * const note = msg.segments("OBX")[0]?.field(5);
+   * note?.render().text; // "Specimen received.\nGross exam normal."
+   * ```
+   */
+  render(opts) {
+    return renderText(this.text, this.enc, opts);
+  }
+  /**
+   * Return a synthetic empty `Field` sentinel: used by `Segment.field(n)` to
    * honor MODEL-05's "never throws on missing" contract. The returned Field
    * has `isNull === false`, `repetitions === []`, and `value === ""`.
    * Referentially stable across calls (same instance returned each time).
    *
-   * The `enc` argument is accepted for API symmetry but ignored — the
+   * The `enc` argument is accepted for API symmetry but ignored: the
    * synthetic field carries no content, so unescape would be a no-op
    * regardless of the active encoding characters.
    *
@@ -1829,7 +1985,7 @@ var Field = class {
   /**
    * Coerce this field's first repetition to a typed `XPN` (Extended Person
    * Name). Absent components are OMITTED from the result
-   * (`exactOptionalPropertyTypes`). Not memoized in v1 — each call re-parses
+   * (`exactOptionalPropertyTypes`). Not memoized in v1: each call re-parses
    * (D-09).
    *
    * @example
@@ -1919,7 +2075,7 @@ var Field = class {
     return parsePl(this.repetitions[0] ?? EMPTY_REP, this.enc);
   }
   /**
-   * Coerce this field's first repetition to a typed `TS` (Time Stamp) — the
+   * Coerce this field's first repetition to a typed `TS` (Time Stamp): the
    * fidelity `DtmParts` (raw + parts + precision + timezone). `valid` is
    * `false` on unparseable input (no throw). Build an absolute instant only on
    * explicit request via `dtmToDate(ts)`.
@@ -1935,7 +2091,7 @@ var Field = class {
   }
   /**
    * Coerce this field's first repetition to a typed `NM` (Numeric).
-   * `{ raw, value }` — `value` is `undefined` on non-numeric input.
+   * `{ raw, value }`: `value` is `undefined` on non-numeric input.
    *
    * @example
    * ```ts
@@ -2005,7 +2161,7 @@ var EMPTY_REP = Object.freeze({
 var Segment = class {
   /** Segment name (3 chars, e.g. `"PID"`, `"OBX"`, `"ZPI"`). */
   type;
-  /** Reference to the underlying `RawSegment.fields` — 1-indexed per HL7 convention. */
+  /** Reference to the underlying `RawSegment.fields`: 1-indexed per HL7 convention. */
   fields;
   /** The 5 encoding characters for this message. Exposed for composite parsers. @internal */
   enc;
@@ -2021,7 +2177,7 @@ var Segment = class {
    * @internal
    */
   customFields;
-  /** Lazy cache of Field wrappers — one per fields[] position. @internal */
+  /** Lazy cache of Field wrappers: one per fields[] position. @internal */
   _fieldWrappers;
   /**
    * Construct a new `Segment`. Called internally by `Hl7Message`; user code
@@ -2044,16 +2200,16 @@ var Segment = class {
   }
   /**
    * Return the `Field` wrapper at HL7 position `n`. Indexing follows the HL7
-   * 1-indexed convention — `seg.field(5)` on a PID segment maps to PID-5.
+   * 1-indexed convention: `seg.field(5)` on a PID segment maps to PID-5.
    * MSH segments use the same user-facing convention: `msh.field(1)` returns
    * the field-separator (MSH-1), `msh.field(2)` returns encoding chars
-   * (MSH-2), `msh.field(3)` returns MSH-3, and so on — the internal
+   * (MSH-2), `msh.field(3)` returns MSH-3, and so on: the internal
    * `fields[N-1]` offset for MSH segments is applied here (mirrors the
    * dot-path resolver in `dot-path.ts`, keeping `msg.segments('MSH')[0].field(3)`
    * and `msg.get('MSH.3')` in agreement).
    *
    * Returns a synthetic empty `Field` (`.isNull === false`, `.value === ""`)
-   * when `n` is out of range — never throws (MODEL-05). Successive calls with
+   * when `n` is out of range: never throws (MODEL-05). Successive calls with
    * the same `n` return the same `Field` instance (D-12).
    *
    * @example
@@ -2080,13 +2236,13 @@ var Segment = class {
   /**
    * Return the `Field` at the profile-declared position for `name`, or
    * `undefined` when no custom mapping exists (PROF-07). Unlike `field(n)`,
-   * missing names return `undefined` — NOT a synthetic empty Field — so
+   * missing names return `undefined`, NOT a synthetic empty Field, so
    * typos surface instead of silently resolving to an empty string (D-14).
    *
    * For segments without a profile-declared customSegments slice (most
    * non-Z segments, and any Z-segment whose host message had no profile
    * applied), this method always returns `undefined` (D-15 defense-in-depth
-   * — D-05 already rejects standard-segment overlays at `defineProfile()`
+   *: D-05 already rejects standard-segment overlays at `defineProfile()`
    * time).
    *
    * When the declared position is out of range for the underlying
@@ -3134,8 +3290,8 @@ function buildMeta(msg) {
   const out = {};
   const msh = msg.segments("MSH")[0];
   if (msh !== void 0) {
-    const typeField = msh.field(9);
-    const firstRep = typeField.repetitions[0];
+    const typeField2 = msh.field(9);
+    const firstRep = typeField2.repetitions[0];
     if (firstRep !== void 0) {
       const parts = [];
       for (let i = 0; i < firstRep.components.length; i++) {
@@ -3454,7 +3610,7 @@ function emitJson(msg) {
     name: seg.name,
     fields: seg.fields.map((field) => ({
       // D-17 + Claude's-Discretion: `repetitions` is ALWAYS `[]` when the
-      // field has zero repetitions — shape-stable, no conditional omission.
+      // field has zero repetitions: shape-stable, no conditional omission.
       repetitions: field.repetitions.map((rep) => ({
         components: rep.components.map((comp) => ({
           subcomponents: comp.subcomponents.slice()
@@ -3473,7 +3629,7 @@ function emitJson(msg) {
     },
     segments,
     // D-19: ALWAYS present, even when empty. `msg.warnings` is already frozen
-    // at Hl7Message construction (Phase 2) — pass-through is safe.
+    // at Hl7Message construction (Phase 2): pass-through is safe.
     warnings: msg.warnings
   };
   if (msg.profile !== void 0) {
@@ -3514,6 +3670,205 @@ function emitMshSegment(seg, enc) {
   return "MSH" + enc.field + msh2 + enc.field + tail;
 }
 
+// src/builder/encode-composite.ts
+function sc(value) {
+  return { subcomponents: [value ?? ""] };
+}
+function hdComponent(hd) {
+  if (hd === void 0) return { subcomponents: [] };
+  const subs = [hd.namespaceId ?? "", hd.universalId ?? "", hd.universalIdType ?? ""];
+  while (subs.length > 0 && subs[subs.length - 1] === "") subs.pop();
+  return { subcomponents: subs };
+}
+function isEmptyComponent(c) {
+  return c.subcomponents.every((s) => s === "");
+}
+function toField(components) {
+  const trimmed = components.slice();
+  while (trimmed.length > 0) {
+    const last = trimmed[trimmed.length - 1];
+    if (last !== void 0 && isEmptyComponent(last)) trimmed.pop();
+    else break;
+  }
+  if (trimmed.length === 0) return { repetitions: [], isNull: false };
+  return { repetitions: [{ components: trimmed }], isNull: false };
+}
+function encodeXpn(v) {
+  return toField([
+    sc(v.familyName),
+    sc(v.givenName),
+    sc(v.secondName),
+    sc(v.suffix),
+    sc(v.prefix),
+    sc(v.degree),
+    sc(v.nameTypeCode),
+    sc(v.nameRepresentationCode),
+    sc(v.nameContext),
+    sc(v.nameValidityRange),
+    sc(v.nameAssemblyOrder),
+    sc(v.effectiveDate),
+    sc(v.expirationDate),
+    sc(v.professionalSuffix)
+  ]);
+}
+function encodeXad(v) {
+  return toField([
+    sc(v.street),
+    sc(v.otherDesignation),
+    sc(v.city),
+    sc(v.stateOrProvince),
+    sc(v.zipOrPostalCode),
+    sc(v.country),
+    sc(v.addressType),
+    sc(v.otherGeographicDesignation),
+    sc(v.countyParishCode),
+    sc(v.censusTract),
+    sc(v.addressRepresentationCode),
+    sc(v.addressValidityRange)
+  ]);
+}
+function encodeCx(v) {
+  return toField([
+    sc(v.idNumber),
+    sc(v.checkDigit),
+    sc(v.checkDigitScheme),
+    hdComponent(v.assigningAuthority),
+    sc(v.identifierTypeCode),
+    sc(v.assigningFacility),
+    sc(v.effectiveDate),
+    sc(v.expirationDate),
+    sc(v.assigningJurisdiction),
+    sc(v.assigningAgencyOrDepartment)
+  ]);
+}
+function encodeCwe(v) {
+  const components = [
+    sc(v.identifier),
+    sc(v.text),
+    sc(v.nameOfCodingSystem),
+    sc(v.alternateIdentifier),
+    sc(v.alternateText),
+    sc(v.nameOfAlternateCodingSystem),
+    sc(v.codingSystemVersionId),
+    sc(v.alternateCodingSystemVersionId),
+    sc(v.originalText)
+  ];
+  for (const extra of v.extraComponents ?? []) components.push(sc(extra));
+  return toField(components);
+}
+function encodeCe(v) {
+  const components = [
+    sc(v.identifier),
+    sc(v.text),
+    sc(v.nameOfCodingSystem),
+    sc(v.alternateIdentifier),
+    sc(v.alternateText),
+    sc(v.nameOfAlternateCodingSystem)
+  ];
+  for (const extra of v.extraComponents ?? []) components.push(sc(extra));
+  return toField(components);
+}
+function encodeXtn(v) {
+  return toField([
+    sc(v.telephoneNumber),
+    sc(v.telecommunicationUseCode),
+    sc(v.telecommunicationEquipmentType),
+    sc(v.emailAddress),
+    sc(v.countryCode),
+    sc(v.areaCityCode),
+    sc(v.localNumber),
+    sc(v.extension),
+    sc(v.anyText),
+    sc(v.extensionPrefix),
+    sc(v.speedDialCode),
+    sc(v.unformattedTelephoneNumber)
+  ]);
+}
+function encodePl(v) {
+  return toField([
+    sc(v.pointOfCare),
+    sc(v.room),
+    sc(v.bed),
+    hdComponent(v.facility),
+    sc(v.locationStatus),
+    sc(v.personLocationType),
+    sc(v.building),
+    sc(v.floor),
+    sc(v.locationDescription),
+    sc(v.comprehensiveLocationId),
+    sc(v.assigningAuthorityForLocation)
+  ]);
+}
+function encodeHd(v) {
+  return toField([sc(v.namespaceId), sc(v.universalId), sc(v.universalIdType)]);
+}
+function encodeTs(v) {
+  const raw = typeof v === "string" ? v : v.raw;
+  return toField([sc(raw)]);
+}
+function encodeNm(v) {
+  let raw;
+  if (typeof v === "number") raw = String(v);
+  else if (typeof v === "string") raw = v;
+  else raw = v.raw;
+  return toField([sc(raw)]);
+}
+function encodeXcn(v) {
+  return toField([
+    sc(v.idNumber),
+    sc(v.familyName),
+    sc(v.givenName),
+    sc(v.secondName),
+    sc(v.suffix),
+    sc(v.prefix),
+    sc(v.degree),
+    sc(v.sourceTable),
+    hdComponent(v.assigningAuthority),
+    sc(v.nameTypeCode),
+    sc(v.identifierCheckDigit),
+    sc(v.checkDigitScheme),
+    sc(v.identifierTypeCode)
+  ]);
+}
+function encodeComposite(kind, value) {
+  switch (kind) {
+    case "XPN":
+      return encodeXpn(value);
+    case "XAD":
+      return encodeXad(value);
+    case "CX":
+      return encodeCx(value);
+    case "CWE":
+      return encodeCwe(value);
+    case "CE":
+      return encodeCe(value);
+    case "XTN":
+      return encodeXtn(value);
+    case "PL":
+      return encodePl(value);
+    case "TS":
+      return encodeTs(value);
+    case "NM":
+      return encodeNm(value);
+    case "HD":
+      return encodeHd(value);
+    case "XCN":
+      return encodeXcn(value);
+    default: {
+      const never = kind;
+      throw new TypeError(`encodeComposite: unknown composite kind ${JSON.stringify(never)}.`);
+    }
+  }
+}
+function encodeCompositeReps(kind, values) {
+  const repetitions = [];
+  for (const value of values) {
+    const encoded = encodeComposite(kind, value);
+    for (const rep of encoded.repetitions) repetitions.push(rep);
+  }
+  return { repetitions, isNull: false };
+}
+
 // src/model/message.ts
 var SEGMENT_NAME_RE2 = /^[A-Z][A-Z0-9]{2}$/u;
 function toMutableArray(arr) {
@@ -3523,7 +3878,7 @@ 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
+   * `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).
    */
@@ -3533,7 +3888,7 @@ var Hl7Message = class {
   warnings;
   profile;
   /**
-   * Merged `dateFormats` list — `options.dateFormats ++ profile.dateFormats`
+   * Merged `dateFormats` list: `options.dateFormats ++ profile.dateFormats`
    * deduped first-occurrence per D-21. Empty array when neither source
    * supplied any formats. Exposed publicly so helpers (`msg.meta.timestamp`)
    * and advanced callers can introspect the active cascade.
@@ -3563,14 +3918,14 @@ var Hl7Message = class {
   _allSegments;
   /**
    * Lazily built `Meta` view (Phase 4 D-02 memoization). Dropped wholesale
-   * by `invalidateCaches`. `Meta` is always defined (D-03 — MSH absence
+   * by `invalidateCaches`. `Meta` is always defined (D-03: MSH absence
    * throws `NO_MSH_SEGMENT` at parse time) so no null-sentinel is needed.
    * @internal
    */
   _meta;
   /**
    * Lazily built `MessageStructure` view (Phase G). Dropped wholesale by
-   * `invalidateCaches`. Always defined — `analyzeMessageStructure` returns an
+   * `invalidateCaches`. Always defined: `analyzeMessageStructure` returns an
    * `recognized: false` summary for unmodelled types rather than absence.
    * @internal
    */
@@ -3607,9 +3962,9 @@ 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,
+   * decoded leaf string (unescaped once at parse: never re-unescaped on read,
    * HL7-VALUE-REDECODE). Returns `undefined` when the path doesn't
-   * resolve — never throws on missing path (MODEL-05). Throws `TypeError`
+   * resolve: never throws on missing path (MODEL-05). Throws `TypeError`
    * on malformed path syntax (e.g. `"pid.5"`, empty string).
    *
    * @example
@@ -3618,7 +3973,7 @@ var Hl7Message = class {
    * msg.get("PID.5.1");  // "Smith"
    * msg.get("OBX[2].5"); // third OBX's 5th field
    * msg.get("NOT.9.9");  // undefined
-   * msg.get("MSH.12");   // "2.5" — HL7 version string
+   * msg.get("MSH.12");   // "2.5": HL7 version string
    * ```
    */
   get(path) {
@@ -3627,7 +3982,7 @@ var Hl7Message = class {
   /**
    * Return every `Segment` of `segmentType` in document order. Returns `[]`
    * (empty array, NEVER `undefined`) when no segment of that type exists
-   * (MODEL-02). Alias for `segments(segmentType)` — shares the same cache.
+   * (MODEL-02). Alias for `segments(segmentType)`: shares the same cache.
    *
    * @example
    * ```ts
@@ -3693,7 +4048,7 @@ var Hl7Message = class {
   }
   /**
    * MSH-derived message metadata (type, controlId, timestamp, version, etc.).
-   * D-01: plain object. D-02: memoized — `msg.meta === msg.meta` across
+   * D-01: plain object. D-02: memoized: `msg.meta === msg.meta` across
    * reads until mutation invalidates. D-03: always defined (MSH absence
    * throws `NO_MSH_SEGMENT` at parse time).
    *
@@ -3709,10 +4064,10 @@ var Hl7Message = class {
   }
   /**
    * Structural-conformance summary for the common message types (roadmap
-   * Phase G) — a misroute/truncation safety net, NOT a conformance validator.
+   * Phase G): a misroute/truncation safety net, NOT a conformance validator.
    * Reports, per the message's recognized (MSH-9.1, MSH-9.2) type, which
    * Required segment groups are present and which are entirely absent
-   * (`missingGroups` — the same set the parser flags as
+   * (`missingGroups`: the same set the parser flags as
    * `MISSING_EXPECTED_GROUP` warnings). For an unmodelled type, `recognized`
    * is `false` and `missingGroups` is empty. D-02: memoized.
    *
@@ -3727,14 +4082,14 @@ var Hl7Message = class {
   }
   /**
    * PID-derived patient view, or `undefined` when no PID segment exists
-   * (D-04). D-02: memoized. HELPERS-07: never throws — absent fields
+   * (D-04). D-02: memoized. HELPERS-07: never throws: absent fields
    * surface as `undefined` on the returned `Patient` object.
    *
    * @example
    * ```ts
    * console.log(msg.patient?.mrn);
    * console.log(msg.patient?.fullName);
-   * console.log(msg.patient?.dateOfBirth?.raw); // fidelity TS — e.g. "19800115"
+   * console.log(msg.patient?.dateOfBirth?.raw); // fidelity TS: e.g. "19800115"
    * ```
    */
   get patient() {
@@ -3762,7 +4117,7 @@ var Hl7Message = class {
   }
   /**
    * Every OBX segment as a typed Observation in document order. D-05:
-   * returns `[]` when no OBX present. D-06: NOT memoized — each call
+   * returns `[]` when no OBX present. D-06: NOT memoized: each call
    * re-walks `rawSegments`. Value type is discriminated per D-13.
    *
    * @example
@@ -3777,7 +4132,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` (Phase M: the repeat pattern
    * surfaced verbatim, never resolved to a schedule). D-05: returns `[]` when no
    * OBR present. D-06: not memoized.
    *
@@ -3785,7 +4140,7 @@ var Hl7Message = class {
    * ```ts
    * for (const order of msg.orders()) {
    *   console.log(order.placerOrderNumber, order.observations.length);
-   *   for (const t of order.timings) console.log(t.repeatPattern?.code); // e.g. "Q6H" — verbatim
+   *   for (const t of order.timings) console.log(t.repeatPattern?.code); // e.g. "Q6H": verbatim
    * }
    * ```
    */
@@ -3793,11 +4148,11 @@ var Hl7Message = class {
     return orders(this);
   }
   /**
-   * Message-level NTE notes (Phase P) — every NTE segment with no recognized
+   * Message-level NTE notes (Phase P): every NTE segment with no recognized
    * preceding parent (not immediately following a `PID`, `ORC`, `OBR`, or
    * `OBX`), surfaced verbatim in document order so nothing is dropped. Notes
    * that DO attach to a specific patient / order / result are exposed on those
-   * helper outputs (`msg.patient?.notes`, `order.notes`, `observation.notes`) —
+   * helper outputs (`msg.patient?.notes`, `order.notes`, `observation.notes`),
    * not here. D-05: returns `[]` when there are none. D-06: NOT memoized.
    *
    * @example
@@ -3810,7 +4165,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: roadmap Phase K), with the MRG-sourced
    * `prior` and PID/PV1-sourced `surviving` parties labelled by role and the
    * spec-constant `direction: "MRG_TO_PID"` on merge/move events. Returns
    * `[]` when the trigger event is not in the identity family. D-06: not
@@ -3837,7 +4192,7 @@ var Hl7Message = class {
    * and never reconciled (Phase D §4).
    *
    * Each medication also carries its TQ1 / legacy embedded-TQ (RXE-1) `timings`
-   * (Phase M — repeat pattern verbatim, never resolved to a schedule).
+   * (Phase M: repeat pattern verbatim, never resolved to a schedule).
    *
    * @example
    * ```ts
@@ -3858,7 +4213,7 @@ var Hl7Message = class {
    * returns `[]` when no RXA present. D-06: not memoized. The vaccine code
    * carries its own provenance; the action code (RXA-21) is surfaced verbatim
    * and `recordOrigin` (administered vs historical) is derived only from the
-   * well-known NIP001 RXA-9.1 codes — never guessed.
+   * well-known NIP001 RXA-9.1 codes: never guessed.
    *
    * @example
    * ```ts
@@ -3928,7 +4283,7 @@ var Hl7Message = class {
    * status (Table 0278), SCH-11 start/end timing, and the resource groups
    * (service / general / location / personnel). D-05: returns `[]` when no SCH
    * is present. D-06: not memoized. Never throws (HELPERS-07). Not a
-   * scheduling-workflow state machine — see the package known-limitations.
+   * scheduling-workflow state machine: see the package known-limitations.
    *
    * @example
    * ```ts
@@ -3945,7 +4300,7 @@ var Hl7Message = class {
    * Every TXA of an MDM message as a typed `ClinicalDocument` (roadmap Phase Q),
    * with the OBX narrative body grouped positionally under that TXA. The
    * completion status (TXA-17) and availability status (TXA-19) are surfaced as
-   * **distinct** fields and never conflated — a document can be available before
+   * **distinct** fields and never conflated: a document can be available before
    * it is authenticated, and reading a preliminary document as final is the
    * harm. D-05: returns `[]` when no TXA is present. D-06: not memoized. Never
    * throws (HELPERS-07).
@@ -3965,7 +4320,7 @@ var Hl7Message = class {
    * Every FT1 of a DFT message as a typed `Charge` (roadmap Phase Q), one per
    * FT1 in document order. Surfaces billing-critical fields (FT1-6 transaction
    * type, FT1-7 code, FT1-11/12 extended/unit amount, FT1-19 diagnosis linkage)
-   * with **no billing logic and no money-as-float** — amounts are the verbatim
+   * with **no billing logic and no money-as-float**: amounts are the verbatim
    * CP wire text. D-05: returns `[]` when no FT1 is present. D-06: not memoized.
    * Never throws (HELPERS-07).
    *
@@ -3986,7 +4341,7 @@ var Hl7Message = class {
    * D-05; MSH-1 and MSH-2 are inlined verbatim from
    * `this.encodingCharacters` per D-06; every field string passes through
    * `reescape` per D-04. `RawField.isNull === true` is preserved as the
-   * HL7 literal `""` (D-02). Pure — never warns, never throws (D-07).
+   * HL7 literal `""` (D-02). Pure: never warns, never throws (D-07).
    *
    * @example
    * ```ts
@@ -4004,7 +4359,7 @@ var Hl7Message = class {
    * Re-walks `rawSegments` on every call (D-30 no caching). Mirrors the
    * raw tree one-for-one, preserves `isNull`, always includes
    * `warnings: []`, and includes `profile: { name, lineage }` only when
-   * `this.profile` is truthy (D-19/D-20). Pure — never warns, never throws.
+   * `this.profile` is truthy (D-19/D-20). Pure: never warns, never throws.
    *
    * @example
    * ```ts
@@ -4023,16 +4378,16 @@ var Hl7Message = class {
    * debugging (SER-04). Single opinionated format (D-22 no options):
    * header line with type / controlId / timestamp / segment count, then
    * one line per segment with labeled `[N]=value` fields (D-23). Composite
-   * values render as their raw HL7 string — depth stops at field level
-   * (D-24). Pure — never warns, never throws (D-26).
+   * values render as their raw HL7 string: depth stops at field level
+   * (D-24). Pure: never warns, never throws (D-26).
    *
    * **Field values render as their raw HL7 string representation.**
-   * Embedded delimiters in user data appear as escape sequences — e.g.
+   * Embedded delimiters in user data appear as escape sequences: e.g.
    * a patient family name containing `|` renders as `Smith\F\Jones`
    * (NOT `Smith|Jones`). This preserves round-trip fidelity: copy-pasting
    * prettyPrint output into `parseHL7` yields a structurally equivalent
    * message. For un-escaped human display, parse the composite first via
-   * typed accessors (e.g. `msg.patient?.familyName`) — those return
+   * typed accessors (e.g. `msg.patient?.familyName`): those return
    * already-decoded strings.
    *
    * @example
@@ -4052,13 +4407,13 @@ var Hl7Message = class {
    * Set the string value at a dot-path. Mutates the underlying tree and
    * returns `this` for chaining (D-15). Auto-creates missing repetitions,
    * components, and subcomponents WITHIN an existing field, but does NOT
-   * auto-create segments — callers must `addSegment` first (throws
+   * auto-create segments: callers must `addSegment` first (throws
    * `TypeError` with an actionable message otherwise).
    *
    * The value is accepted verbatim: unescaped delimiter characters are NOT
    * rejected on input (D-18). Re-escaping on serialize is Phase 5's concern.
    *
-   * MSH-1 / MSH-2 follow the user-facing HL7 convention — `setField("MSH.3", ...)`
+   * MSH-1 / MSH-2 follow the user-facing HL7 convention: `setField("MSH.3", ...)`
    * targets MSH-3 (sending application), matching `msg.get("MSH.3")`.
    *
    * Segment/Field wrapper caches are invalidated wholesale on success (D-17).
@@ -4095,7 +4450,7 @@ var Hl7Message = class {
     const mutSegments = toMutableArray(this.rawSegments);
     const seg = mutSegments[segIdx];
     if (seg === void 0) {
-      throw new Error("setField: internal invariant \u2014 segment disappeared after lookup.");
+      throw new Error("setField: internal invariant, segment disappeared after lookup.");
     }
     const mutFields = toMutableArray(seg.fields);
     while (mutFields.length <= rawFieldIndex) {
@@ -4103,7 +4458,7 @@ var Hl7Message = class {
     }
     const field = mutFields[rawFieldIndex];
     if (field === void 0) {
-      throw new Error("setField: internal invariant \u2014 field missing after growth.");
+      throw new Error("setField: internal invariant, field missing after growth.");
     }
     const mutReps = toMutableArray(field.repetitions);
     const repIdx = parsed.repetitionIndex ?? 0;
@@ -4112,7 +4467,7 @@ var Hl7Message = class {
     }
     const rep = mutReps[repIdx];
     if (rep === void 0) {
-      throw new Error("setField: internal invariant \u2014 repetition missing after growth.");
+      throw new Error("setField: internal invariant, repetition missing after growth.");
     }
     const mutComps = toMutableArray(rep.components);
     const compIdx = (parsed.componentIndex ?? 1) - 1;
@@ -4121,7 +4476,7 @@ var Hl7Message = class {
     }
     const comp = mutComps[compIdx];
     if (comp === void 0) {
-      throw new Error("setField: internal invariant \u2014 component missing after growth.");
+      throw new Error("setField: internal invariant, component missing after growth.");
     }
     const mutSubs = toMutableArray(comp.subcomponents);
     const subIdx = (parsed.subcomponentIndex ?? 1) - 1;
@@ -4141,9 +4496,95 @@ var Hl7Message = class {
     this.invalidateCaches();
     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
+   * (`asXpn`/`asCx`/…). The caller passes a structured value (an XPN name, a CX
+   * identifier, a TS timestamp, …) by its {@link CompositeKind}, and the setter
+   * encodes it into a spec-clean field using the HL7-R encode-safe path: any
+   * delimiter embedded in a component value is **escaped, never injected**, so
+   * a `familyName` of `"Smith^Jr"` re-parses to exactly that string rather than
+   * forging a component boundary. No hand-assembly of `^`/`&`/`~`.
+   *
+   * The path must resolve to a **field** (`"PID.5"`) or a specific
+   * **repetition** of a field (`"PID.11[1]"`). A component/subcomponent-level
+   * path (`"PID.5.1"`) is rejected with `TypeError`: a composite occupies a
+   * whole field, not a single component. Like {@link setField}, the target
+   * segment must already exist (`addSegment` first); the repetition defaults to
+   * index 0 and other repetitions of the field are preserved.
+   *
+   * Never fabricates: an omitted optional composite field encodes to an
+   * empty/absent component, never a defaulted value; an all-empty composite
+   * clears the field. Segment/helper caches are invalidated on success; the
+   * frozen `warnings` array is untouched.
+   *
+   * @example
+   * ```ts
+   * const msg = buildMessage({ type: "ADT^A01" }).addSegment("PID", [""]);
+   * msg.setComposite("PID.5", "XPN", { familyName: "Smith", givenName: "Ann" });
+   * msg.setComposite("PID.3", "CX", { idNumber: "MRN001", identifierTypeCode: "MR" });
+   * msg.setComposite("PID.7", "TS", "19880705");
+   * msg.get("PID.5.1"); // "Smith"
+   * ```
+   */
+  setComposite(path, kind, value) {
+    const parsed = parsePath(path);
+    if (parsed.componentIndex !== void 0 || parsed.subcomponentIndex !== void 0) {
+      throw new TypeError(
+        `setComposite: path "${path}" targets a component/subcomponent, but a typed composite occupies a whole field. Use a field path (e.g. "PID.5") or a field-repetition path (e.g. "PID.11[1]").`
+      );
+    }
+    let seen = 0;
+    let segIdx = -1;
+    for (let i = 0; i < this.rawSegments.length; i++) {
+      const s = this.rawSegments[i];
+      if (s === void 0) continue;
+      if (s.name === parsed.segmentType) {
+        if (seen === parsed.segmentIndex) {
+          segIdx = i;
+          break;
+        }
+        seen++;
+      }
+    }
+    if (segIdx === -1) {
+      throw new TypeError(
+        `setComposite: segment "${parsed.segmentType}" (occurrence ${String(parsed.segmentIndex)}) not found. Add it first with addSegment("${parsed.segmentType}", [...]).`
+      );
+    }
+    const encoded = encodeComposite(kind, value);
+    const encodedRep = encoded.repetitions[0] ?? { components: [] };
+    const rawFieldIndex = parsed.segmentType === "MSH" ? parsed.fieldIndex - 1 : parsed.fieldIndex;
+    const mutSegments = toMutableArray(this.rawSegments);
+    const seg = mutSegments[segIdx];
+    if (seg === void 0) {
+      throw new Error("setComposite: internal invariant, segment disappeared after lookup.");
+    }
+    const mutFields = toMutableArray(seg.fields);
+    while (mutFields.length <= rawFieldIndex) {
+      mutFields.push({ repetitions: [], isNull: false });
+    }
+    const field = mutFields[rawFieldIndex];
+    if (field === void 0) {
+      throw new Error("setComposite: internal invariant, field missing after growth.");
+    }
+    const mutReps = toMutableArray(field.repetitions);
+    const repIdx = parsed.repetitionIndex ?? 0;
+    while (mutReps.length <= repIdx) {
+      mutReps.push({ components: [] });
+    }
+    mutReps[repIdx] = encodedRep;
+    const newField = { repetitions: mutReps, isNull: false };
+    mutFields[rawFieldIndex] = newField;
+    const newSeg = { name: seg.name, fields: mutFields };
+    mutSegments[segIdx] = newSeg;
+    this.rawSegments = mutSegments;
+    this.invalidateCaches();
+    return this;
+  }
   /**
    * Append a new segment to the end of the message. `name` must match
-   * `/^(?:[A-Z]{3}|Z[A-Z0-9]{2})$/u` — throws `TypeError` otherwise (D-19).
+   * `/^(?:[A-Z]{3}|Z[A-Z0-9]{2})$/u`: throws `TypeError` otherwise (D-19).
    *
    * `fields` is interpreted in HL7 1-indexed terms: `addSegment("NTE", [a, b, c])`
    * produces a segment whose `NTE-1 = a`, `NTE-2 = b`, `NTE-3 = c`. The
@@ -4193,14 +4634,14 @@ var Hl7Message = class {
   /**
    * Remove segments by type + occurrence or by type + all. Call shapes:
    *
-   * - `removeSegment("NTE")` — remove the FIRST NTE (occurrence 0).
-   * - `removeSegment("OBX", 1)` — remove the SECOND OBX (0-indexed per D-01).
-   * - `removeSegment("OBX", { all: true })` — remove ALL OBX segments.
+   * - `removeSegment("NTE")`: remove the FIRST NTE (occurrence 0).
+   * - `removeSegment("OBX", 1)`: remove the SECOND OBX (0-indexed per D-01).
+   * - `removeSegment("OBX", { all: true })`: remove ALL OBX segments.
    *
-   * `MSH` is protected — `removeSegment("MSH")` throws `TypeError` (every
+   * `MSH` is protected: `removeSegment("MSH")` throws `TypeError` (every
    * HL7 message must retain its MSH segment). Unknown segment types are a
    * no-op (idempotent; no throw). Segment name must match the D-19 shape
-   * regex — invalid shapes throw `TypeError` for symmetry with `addSegment`.
+   * regex: invalid shapes throw `TypeError` for symmetry with `addSegment`.
    *
    * Invalidates caches on return; warnings untouched (D-16).
    *
@@ -4378,9 +4819,9 @@ function extractVersion(msh) {
 }
 function extractMessageType(msh) {
   if (msh === void 0 || msh.name !== "MSH") return { messageCode: "", triggerEvent: "" };
-  const typeField = msh.fields[8];
-  if (typeField === void 0) return { messageCode: "", triggerEvent: "" };
-  const firstRep = typeField.repetitions[0];
+  const typeField2 = msh.fields[8];
+  if (typeField2 === void 0) return { messageCode: "", triggerEvent: "" };
+  const firstRep = typeField2.repetitions[0];
   if (firstRep === void 0) return { messageCode: "", triggerEvent: "" };
   const messageCode = firstRep.components[0]?.subcomponents[0] ?? "";
   const triggerEvent = firstRep.components[1]?.subcomponents[0] ?? "";
@@ -4512,6 +4953,24 @@ function parseHL7(raw, optionsOrProfile) {
   return new Hl7Message(init);
 }
 
+// src/text/codec.ts
+function ignore() {
+}
+function decodeText(input, enc = DEFAULT_ENCODING_CHARACTERS) {
+  return unescape(input, enc, ignore, { segmentIndex: 0 });
+}
+function encodeText(input, enc = DEFAULT_ENCODING_CHARACTERS) {
+  return reescape(input, enc);
+}
+
+// src/text/index.ts
+var text_exports = {};
+__export(text_exports, {
+  decode: () => decodeText,
+  encode: () => encodeText,
+  render: () => renderText
+});
+
 // src/model/types/namespace.ts
 var namespace_exports = {};
 var ALNUM_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
@@ -4627,6 +5086,247 @@ function compositeField(typeString) {
   };
 }
 
+// src/builder/segment-fields.ts
+function scalarField2(value) {
+  if (value === void 0 || value === "") return { repetitions: [], isNull: false };
+  return { repetitions: [{ components: [{ subcomponents: [value] }] }], isNull: false };
+}
+function absentField2() {
+  return { repetitions: [], isNull: false };
+}
+function typeField(typeString) {
+  const components = typeString.split("^").map((p) => ({ subcomponents: [p] }));
+  return { repetitions: [{ components }], isNull: false };
+}
+function resolveTimestamp2(ts) {
+  if (ts === void 0) return formatHl7Timestamp(/* @__PURE__ */ new Date());
+  if (typeof ts === "string") return ts;
+  return formatHl7Timestamp(ts);
+}
+function buildMshSegment(type, envelope) {
+  const enc = DEFAULT_ENCODING_CHARACTERS;
+  const fields = [
+    scalarField2(enc.field),
+    // fields[0] MSH-1 field separator placeholder
+    scalarField2(
+      enc.component + enc.repetition + enc.escape + enc.subcomponent + (enc.truncation ?? "")
+    ),
+    // MSH-2 encoding characters
+    scalarField2(envelope.sendingApp),
+    // MSH-3
+    scalarField2(envelope.sendingFacility),
+    // MSH-4
+    scalarField2(envelope.receivingApp),
+    // MSH-5
+    scalarField2(envelope.receivingFacility),
+    // MSH-6
+    scalarField2(resolveTimestamp2(envelope.timestamp)),
+    // MSH-7
+    absentField2(),
+    // MSH-8
+    typeField(type),
+    // MSH-9
+    scalarField2(envelope.controlId ?? generateControlId()),
+    // MSH-10
+    scalarField2(envelope.processingId ?? "P"),
+    // MSH-11
+    scalarField2(envelope.version ?? "2.5")
+    // MSH-12
+  ];
+  return { name: "MSH", fields };
+}
+function assembleSegment(name, positions) {
+  let max = 0;
+  for (const [pos, field] of positions) {
+    if (field !== void 0 && pos > max) max = pos;
+  }
+  const fields = [absentField2()];
+  for (let i = 1; i <= max; i++) {
+    fields.push(positions.get(i) ?? absentField2());
+  }
+  return { name, fields };
+}
+
+// src/builder/build-adt.ts
+function repField(kind, value) {
+  if (value === void 0) return { repetitions: [], isNull: false };
+  if (Array.isArray(value)) {
+    return encodeCompositeReps(kind, value);
+  }
+  return encodeComposite(kind, value);
+}
+function buildAdt(event, init) {
+  if (typeof event !== "string" || event.trim().length === 0) {
+    throw new TypeError(
+      `buildAdt: \`event\` (the ADT trigger, e.g. "A01") is required and must be a non-empty string. Received: ${JSON.stringify(event)}.`
+    );
+  }
+  if (init === null || init === void 0 || init.patient === void 0) {
+    throw new TypeError(
+      "buildAdt: `patient` is required. An ADT patient event is never emitted with a fabricated patient. Supply at least one identifier or a name."
+    );
+  }
+  const enc = DEFAULT_ENCODING_CHARACTERS;
+  const version = init.version ?? "2.5";
+  const segments = [buildMshSegment(`ADT^${event}`, init)];
+  const evn = init.event;
+  segments.push(
+    assembleSegment(
+      "EVN",
+      /* @__PURE__ */ new Map([
+        [1, scalarField2(event)],
+        [
+          2,
+          evn?.recordedDateTime !== void 0 ? encodeComposite("TS", evn.recordedDateTime) : void 0
+        ],
+        [
+          6,
+          evn?.eventOccurred !== void 0 ? encodeComposite("TS", evn.eventOccurred) : void 0
+        ]
+      ])
+    )
+  );
+  const p = init.patient;
+  segments.push(
+    assembleSegment(
+      "PID",
+      /* @__PURE__ */ new Map([
+        [1, p.setId !== void 0 ? scalarField2(p.setId) : void 0],
+        [3, p.identifiers !== void 0 ? repField("CX", p.identifiers) : void 0],
+        [5, p.name !== void 0 ? repField("XPN", p.name) : void 0],
+        [
+          6,
+          p.mothersMaidenName !== void 0 ? encodeComposite("XPN", p.mothersMaidenName) : void 0
+        ],
+        [7, p.birthDateTime !== void 0 ? encodeComposite("TS", p.birthDateTime) : void 0],
+        [8, p.administrativeSex !== void 0 ? scalarField2(p.administrativeSex) : void 0],
+        [11, p.address !== void 0 ? repField("XAD", p.address) : void 0],
+        [13, p.phoneHome !== void 0 ? repField("XTN", p.phoneHome) : void 0],
+        [18, p.accountNumber !== void 0 ? encodeComposite("CX", p.accountNumber) : void 0]
+      ])
+    )
+  );
+  const v = init.visit;
+  segments.push(
+    assembleSegment(
+      "PV1",
+      /* @__PURE__ */ new Map([
+        [1, v?.setId !== void 0 ? scalarField2(v.setId) : void 0],
+        [2, v?.patientClass !== void 0 ? scalarField2(v.patientClass) : void 0],
+        [
+          3,
+          v?.assignedLocation !== void 0 ? encodeComposite("PL", v.assignedLocation) : void 0
+        ],
+        [7, v?.attendingDoctor !== void 0 ? repField("XCN", v.attendingDoctor) : void 0],
+        [8, v?.referringDoctor !== void 0 ? repField("XCN", v.referringDoctor) : void 0],
+        [19, v?.visitNumber !== void 0 ? encodeComposite("CX", v.visitNumber) : void 0],
+        [44, v?.admitDateTime !== void 0 ? encodeComposite("TS", v.admitDateTime) : void 0]
+      ])
+    )
+  );
+  return new Hl7Message({
+    segments,
+    encodingCharacters: enc,
+    version,
+    warnings: []
+  });
+}
+
+// src/builder/build-oru.ts
+function repField2(kind, value) {
+  if (value === void 0) return { repetitions: [], isNull: false };
+  if (Array.isArray(value)) {
+    return encodeCompositeReps(kind, value);
+  }
+  return encodeComposite(kind, value);
+}
+function buildOru(init) {
+  if (init === null || init === void 0 || init.patient === void 0) {
+    throw new TypeError(
+      "buildOru: `patient` is required. An ORU is never emitted with a fabricated subject."
+    );
+  }
+  if (init.observations === void 0 || init.observations.length === 0) {
+    throw new TypeError(
+      "buildOru: at least one `observations` entry (OBX) is required. An ORU with no result is a typed error, never a fabricated observation."
+    );
+  }
+  const enc = DEFAULT_ENCODING_CHARACTERS;
+  const version = init.version ?? "2.5";
+  const segments = [buildMshSegment("ORU^R01", init)];
+  const p = init.patient;
+  segments.push(
+    assembleSegment(
+      "PID",
+      /* @__PURE__ */ new Map([
+        [1, p.setId !== void 0 ? scalarField2(p.setId) : void 0],
+        [3, p.identifiers !== void 0 ? repField2("CX", p.identifiers) : void 0],
+        [5, p.name !== void 0 ? repField2("XPN", p.name) : void 0],
+        [
+          6,
+          p.mothersMaidenName !== void 0 ? encodeComposite("XPN", p.mothersMaidenName) : void 0
+        ],
+        [7, p.birthDateTime !== void 0 ? encodeComposite("TS", p.birthDateTime) : void 0],
+        [8, p.administrativeSex !== void 0 ? scalarField2(p.administrativeSex) : void 0],
+        [11, p.address !== void 0 ? repField2("XAD", p.address) : void 0],
+        [13, p.phoneHome !== void 0 ? repField2("XTN", p.phoneHome) : void 0],
+        [18, p.accountNumber !== void 0 ? encodeComposite("CX", p.accountNumber) : void 0]
+      ])
+    )
+  );
+  const o = init.order;
+  segments.push(
+    assembleSegment(
+      "OBR",
+      /* @__PURE__ */ new Map([
+        [1, o?.setId !== void 0 ? scalarField2(o.setId) : void 0],
+        [2, o?.placerOrderNumber !== void 0 ? scalarField2(o.placerOrderNumber) : void 0],
+        [3, o?.fillerOrderNumber !== void 0 ? scalarField2(o.fillerOrderNumber) : void 0],
+        [
+          4,
+          o?.universalServiceId !== void 0 ? encodeComposite("CWE", o.universalServiceId) : void 0
+        ],
+        [
+          7,
+          o?.observationDateTime !== void 0 ? encodeComposite("TS", o.observationDateTime) : void 0
+        ],
+        [16, o?.orderingProvider !== void 0 ? repField2("XCN", o.orderingProvider) : void 0],
+        [25, o?.resultStatus !== void 0 ? scalarField2(o.resultStatus) : void 0]
+      ])
+    )
+  );
+  for (const obs of init.observations) {
+    segments.push(
+      assembleSegment(
+        "OBX",
+        /* @__PURE__ */ new Map([
+          [1, obs.setId !== void 0 ? scalarField2(obs.setId) : void 0],
+          [2, obs.valueType !== void 0 ? scalarField2(obs.valueType) : void 0],
+          [3, obs.identifier !== void 0 ? encodeComposite("CWE", obs.identifier) : void 0],
+          [5, obs.value !== void 0 ? scalarField2(obs.value) : void 0],
+          [6, obs.units !== void 0 ? encodeComposite("CWE", obs.units) : void 0],
+          [7, obs.referenceRange !== void 0 ? scalarField2(obs.referenceRange) : void 0],
+          [8, obs.abnormalFlags !== void 0 ? scalarField2(obs.abnormalFlags) : void 0],
+          [
+            11,
+            obs.observationResultStatus !== void 0 ? scalarField2(obs.observationResultStatus) : void 0
+          ],
+          [
+            14,
+            obs.observationDateTime !== void 0 ? encodeComposite("TS", obs.observationDateTime) : void 0
+          ]
+        ])
+      )
+    );
+  }
+  return new Hl7Message({
+    segments,
+    encodingCharacters: enc,
+    version,
+    warnings: []
+  });
+}
+
 // src/builder/ack-tables.ts
 var ACK_CODES = {
   AA: "AA",
@@ -4709,7 +5409,7 @@ function buildAck(inbound, options) {
   const enc = DEFAULT_ENCODING_CHARACTERS;
   const meta = inbound.meta;
   const msh = inbound.segments("MSH")[0];
-  const inboundMsh = (n) => msh?.field(n).raw ?? absentField2();
+  const inboundMsh = (n) => msh?.field(n).raw ?? absentField3();
   const sameEnc = encodingsEqual(inbound.encodingCharacters, enc);
   const rawControlId = sameEnc ? inboundMsh(10) : stripEscapeOverlay(inboundMsh(10));
   const hasCorrelation = rawFieldHasContent(rawControlId);
@@ -4718,8 +5418,8 @@ function buildAck(inbound, options) {
   const version = meta.version ?? "2.5";
   const processingId = meta.processingId ?? "P";
   const mshFields = [
-    scalarField2(enc.field),
-    scalarField2(
+    scalarField3(enc.field),
+    scalarField3(
       enc.component + enc.repetition + enc.escape + enc.subcomponent + (enc.truncation ?? "")
     ),
     inboundMsh(5),
@@ -4730,26 +5430,26 @@ function buildAck(inbound, options) {
     // MSH-5 receivingApp = inbound MSH-3 (sendingApp)
     inboundMsh(4),
     // MSH-6 receivingFacility = inbound MSH-4 (sendingFacility)
-    scalarField2(formatHl7Timestamp(/* @__PURE__ */ new Date())),
+    scalarField3(formatHl7Timestamp(/* @__PURE__ */ new Date())),
     // MSH-7
-    absentField2(),
+    absentField3(),
     // MSH-8
     compositeField2(ackType),
     // MSH-9
-    scalarField2(generateControlId()),
+    scalarField3(generateControlId()),
     // MSH-10
-    scalarField2(processingId),
+    scalarField3(processingId),
     // MSH-11
-    scalarField2(version)
+    scalarField3(version)
     // MSH-12
   ];
   const segments = [{ name: "MSH", fields: mshFields }];
   segments.push({
     name: "MSA",
     fields: [
-      absentField2(),
-      scalarField2(emittedCode),
-      hasCorrelation ? rawControlId : absentField2()
+      absentField3(),
+      scalarField3(emittedCode),
+      hasCorrelation ? rawControlId : absentField3()
     ]
   });
   for (const detail of normalizeErrors(options.error)) {
@@ -4789,24 +5489,24 @@ function buildErrSegment(detail) {
   return {
     name: "ERR",
     fields: [
-      absentField2(),
-      // fields[0] — segment-name/separator placeholder slot
-      absentField2(),
+      absentField3(),
+      // fields[0]: segment-name/separator placeholder slot
+      absentField3(),
       // ERR-1 (deprecated v2.4 / withdrawn v2.7)
-      detail.location !== void 0 ? compositeField2(detail.location) : absentField2(),
+      detail.location !== void 0 ? compositeField2(detail.location) : absentField3(),
       // ERR-2 (ERL)
       err3,
       // ERR-3
-      scalarField2(severity)
+      scalarField3(severity)
       // ERR-4
     ]
   };
 }
-function scalarField2(value) {
+function scalarField3(value) {
   if (value === "") return { repetitions: [], isNull: false };
   return { repetitions: [{ components: [{ subcomponents: [value] }] }], isNull: false };
 }
-function absentField2() {
+function absentField3() {
   return { repetitions: [], isNull: false };
 }
 function encodingsEqual(a, b) {
@@ -5066,7 +5766,7 @@ function validateCustomSegments(map, profileName) {
   for (const key of Object.keys(map)) {
     if (!Z_SEGMENT_RE.test(key)) {
       throw new ProfileDefinitionError(
-        `Profile '${profileName}' declares customSegments for '${key}' \u2014 only Z-segments (Z[A-Z0-9]{2}) are allowed in v1. Typed overlays are a v2 feature.`,
+        `Profile '${profileName}' declares customSegments for '${key}': only Z-segments (Z[A-Z0-9]{2}) are allowed in v1. Typed overlays are a v2 feature.`,
         profileName
       );
     }
@@ -5093,7 +5793,7 @@ function validateDateFormats(formats, profileName) {
     const f = formats[i] ?? "";
     if (!TOKEN_MATCH_RE.test(f)) {
       throw new ProfileDefinitionError(
-        `Profile '${profileName}' dateFormats[${String(i)}] = ${JSON.stringify(f)} is malformed \u2014 must contain at least one of ${SUPPORTED_DATE_TOKENS.join("/")}.`,
+        `Profile '${profileName}' dateFormats[${String(i)}] = ${JSON.stringify(f)} is malformed: must contain at least one of ${SUPPORTED_DATE_TOKENS.join("/")}.`,
         profileName
       );
     }
@@ -5151,7 +5851,7 @@ function defineProfile(opts) {
 // src/profiles/athena.ts
 var athena = defineProfile({
   name: "athena",
-  description: "athenahealth Interop \u2014 US-short-date format and care-team Z-segment",
+  description: "athenahealth Interop: US-short-date format and care-team Z-segment",
   dateFormats: ["MM/DD/YYYY"],
   customSegments: {
     ZCA: { fields: { careTeamRole: 3, providerId: 5, providerName: 6 } }
@@ -5161,7 +5861,7 @@ var athena = defineProfile({
 // src/profiles/cerner.ts
 var cerner = defineProfile({
   name: "cerner",
-  description: "Cerner Millennium \u2014 ISO-style timestamps and common Z-segments",
+  description: "Cerner Millennium: ISO-style timestamps and common Z-segments",
   dateFormats: ["YYYY-MM-DDTHH:mm:ss", "YYYY-MM-DD"],
   customSegments: {
     ZDS: { fields: { summaryText: 3 } },
@@ -5172,7 +5872,7 @@ var cerner = defineProfile({
 // src/profiles/epic.ts
 var epic = defineProfile({
   name: "epic",
-  description: "Epic Bridges Interconnect \u2014 ADT-style date formats and common Z-segments",
+  description: "Epic Bridges Interconnect: ADT-style date formats and common Z-segments",
   dateFormats: ["MM/DD/YYYY HH:mm:ss", "MM/DD/YYYY"],
   customSegments: {
     ZDP: { fields: { departmentCode: 3, departmentName: 4 } },
@@ -5183,7 +5883,7 @@ var epic = defineProfile({
 // src/profiles/genericLab.ts
 var genericLab = defineProfile({
   name: "genericLab",
-  description: "Generic reference-laboratory \u2014 ASTM-era + ISO-date formats + lab Z-segments",
+  description: "Generic reference-laboratory: ASTM-era + ISO-date formats + lab Z-segments",
   dateFormats: ["YYYYMMDD HHmm", "YYYY-MM-DD"],
   customSegments: {
     ZLB: { fields: { specimenOverride: 3, methodOverride: 5 } },
@@ -5194,10 +5894,122 @@ var genericLab = defineProfile({
 // src/profiles/meditech.ts
 var meditech = defineProfile({
   name: "meditech",
-  description: "Meditech MAGIC/Expanse \u2014 minute-precision timestamps and visit-info Z-segment",
+  description: "MEDITECH MAGIC/6.x/Expanse: minute-precision timestamps and DFT charge Z-segments (ZF1/ZF2)",
   dateFormats: ["YYYYMMDDHHmm"],
   customSegments: {
-    ZVI: { fields: { visitReason: 3, admitSource: 5 } }
+    ZF1: {
+      fields: {
+        providerEncounter: 1,
+        misServiceGroup: 2,
+        serviceGroupCopay: 3,
+        visitCopay: 4,
+        copayMinimum: 5,
+        copayMaximum: 6
+      }
+    },
+    ZF2: {
+      fields: {
+        setId: 1,
+        providerEncounter: 2,
+        encounterDate: 3,
+        encounterProcedure: 4,
+        encounterProcedureQuantity: 5,
+        encounterProcedureCharge: 6,
+        prvProcedureAmountPaid: 7,
+        prvProcedureAmountDue: 8
+      }
+    }
+  }
+});
+
+// src/profiles/philips.ts
+var philips = defineProfile({
+  name: "philips",
+  description: "Philips Vue PACS (IS Link) imaging: ZDS/ZLK/ZAO/ZEB/ZAP/ZAV order/patient/visit-filler Z-segments",
+  customSegments: {
+    // §5.11 ZDS: Order Filler: DICOM Study Instance UID (RP, comp 1).
+    ZDS: { fields: { studyInstanceUid: 1 } },
+    // §5.12 ZLK: Order Filler: study/order linking ids.
+    ZLK: { fields: { externalWorkitemId: 1, orderLinkId: 2 } },
+    // §5.13 ZAO: Order Filler: order additional details (note: no field 7).
+    ZAO: {
+      fields: {
+        orderAdditionalDetails: 1,
+        orderWithNoImages: 2,
+        modality: 3,
+        bodyPart: 4,
+        resultTransferStatus: 5,
+        departmentId: 6,
+        device: 8,
+        section: 9,
+        orderCustomString1: 10,
+        orderCustomString2: 11,
+        orderCustomString3: 12,
+        orderCustomString4: 13,
+        orderCustomString5: 14,
+        orderCustomString6: 15,
+        orderCustomString7: 16,
+        orderCustomNumber1: 17,
+        orderCustomNumber2: 18,
+        orderCustomDate1: 19,
+        orderCustomDate2: 20,
+        orderCustomDate3: 21,
+        technicianFamilyName: 22,
+        technicianGivenName: 23,
+        technicianMiddleName: 24,
+        technicianId: 25,
+        radiologistFamilyName: 26,
+        radiologistGivenName: 27,
+        radiologistMiddleName: 28,
+        radiologistId: 29,
+        orderCreatedBy: 30,
+        orderUpdatedBy: 31,
+        acquisitionStatus: 32
+      }
+    },
+    // §5.14 ZEB: Patient Filler: encrypted patient-info blob (PHI-bearing).
+    ZEB: { fields: { encryptedPatientInfo: 1 } },
+    // §5.15 ZAP: Patient Filler: patient additional details (note: no field 2).
+    ZAP: {
+      fields: {
+        patientAdditionalDetails: 1,
+        patientCustomString1: 3,
+        patientCustomString2: 4,
+        patientCustomString3: 5,
+        patientCustomString4: 6,
+        patientCustomString5: 7,
+        patientCustomString6: 8,
+        patientCustomString7: 9,
+        patientCustomNumber1: 10,
+        patientCustomNumber2: 11,
+        patientCustomDate1: 12,
+        patientCustomDate2: 13,
+        patientCustomDate3: 14
+      }
+    },
+    // §5.16 ZAV: Visit Filler: visit additional details.
+    ZAV: { fields: { visitAdditionalDetails: 1 } }
+  }
+});
+
+// src/profiles/va.ts
+var va = defineProfile({
+  name: "va",
+  description: "VA VistA Radiology/Nuclear Medicine imaging: ZDS DICOM Study Instance UID segment (ORM + ORU, IHE RAD)",
+  customSegments: {
+    // ZDS-1 = Study Instance UID (RP), UID in the first component (1.1 Pointer).
+    // VA Radiology/Nuclear Medicine 5.0 HL7 IS v3.6 (June 2024): "ZDS Segment
+    // Fields in ORU and ORM".
+    ZDS: { fields: { studyInstanceUid: 1 } }
+  }
+});
+
+// src/profiles/visage.ts
+var visage = defineProfile({
+  name: "visage",
+  description: "Visage 7 imaging/PACS: ZDS DICOM Study Instance UID segment (IHE RAD)",
+  customSegments: {
+    ZDS: { fields: { studyInstanceUid: 1 } }
   }
 });
 
@@ -5207,7 +6019,10 @@ var profiles = Object.freeze({
   cerner,
   epic,
   genericLab,
-  meditech
+  meditech,
+  philips,
+  va,
+  visage
 });
 
 // src/model/coding-system.ts
@@ -5439,9 +6254,561 @@ function splitBatch(raw, optionsOrProfile) {
   return Object.freeze(result);
 }
 
+// src/conformance/types.ts
+var USAGE_CODES = Object.freeze(["R", "RE", "C", "CE", "O", "X"]);
+var FINDING_CODES = {
+  /** A Required (`R`) segment or field is absent (or present-but-empty). */
+  PROFILE_REQUIRED_ABSENT: "PROFILE_REQUIRED_ABSENT",
+  /** A Not-permitted (`X`) segment or field is present. */
+  PROFILE_NOT_PERMITTED: "PROFILE_NOT_PERMITTED",
+  /** A segment-occurrence or field-repetition count is outside its cardinality. */
+  PROFILE_CARDINALITY: "PROFILE_CARDINALITY",
+  /** A checked component value exceeds the declared maximum length. */
+  PROFILE_LENGTH: "PROFILE_LENGTH",
+  /** A checked component value is not a member of the consumer-supplied value set. */
+  PROFILE_VALUE_NOT_IN_SET: "PROFILE_VALUE_NOT_IN_SET",
+  /** The profile ITSELF is structurally malformed (a diagnostic, not a message finding). */
+  PROFILE_MALFORMED: "PROFILE_MALFORMED"
+};
+
+// src/conformance/findings.ts
+function describeLocus(locus) {
+  let s = locus.segment;
+  if (locus.occurrence !== void 0 && locus.occurrence > 0) {
+    s += `[occurrence ${String(locus.occurrence)}]`;
+  }
+  if (locus.field !== void 0) {
+    s += `-${String(locus.field)}`;
+  }
+  if (locus.repetition !== void 0) {
+    s += ` rep ${String(locus.repetition)}`;
+  }
+  if (locus.component !== void 0) {
+    s += ` component ${String(locus.component)}`;
+  }
+  return s;
+}
+function requiredAbsent(locus, severity) {
+  const kind = locus.field === void 0 ? "segment" : "field";
+  return {
+    code: FINDING_CODES.PROFILE_REQUIRED_ABSENT,
+    severity,
+    locus,
+    message: `Required ${kind} ${describeLocus(locus)} is absent or empty (usage R).`
+  };
+}
+function notPermitted(locus, severity) {
+  const kind = locus.field === void 0 ? "segment" : "field";
+  return {
+    code: FINDING_CODES.PROFILE_NOT_PERMITTED,
+    severity,
+    locus,
+    message: `${kind === "segment" ? "Segment" : "Field"} ${describeLocus(
+      locus
+    )} is present but the profile marks it not-permitted (usage X).`
+  };
+}
+function cardinality(locus, actual, bound, unit, severity) {
+  const parts = [];
+  if (bound.min !== void 0) parts.push(`min ${String(bound.min)}`);
+  if (bound.max !== void 0) parts.push(`max ${String(bound.max)}`);
+  return {
+    code: FINDING_CODES.PROFILE_CARDINALITY,
+    severity,
+    locus,
+    message: `${describeLocus(locus)} has ${String(actual)} ${unit}(s), outside the declared cardinality (${parts.join(
+      ", "
+    )}).`
+  };
+}
+function length(locus, actualLength, maxLength, severity) {
+  return {
+    code: FINDING_CODES.PROFILE_LENGTH,
+    severity,
+    locus,
+    message: `${describeLocus(locus)} value length ${String(
+      actualLength
+    )} exceeds the declared maximum of ${String(maxLength)}.`
+  };
+}
+function valueNotInSet(locus, valueSetSize, severity) {
+  return {
+    code: FINDING_CODES.PROFILE_VALUE_NOT_IN_SET,
+    severity,
+    locus,
+    message: `${describeLocus(
+      locus
+    )} value is not in the profile value set (${String(valueSetSize)} permitted code(s)).`
+  };
+}
+function malformed(locus, detail) {
+  return {
+    code: FINDING_CODES.PROFILE_MALFORMED,
+    severity: "error",
+    locus,
+    message: `Malformed conformance profile: ${detail}`
+  };
+}
+
+// src/conformance/profile-shape.ts
+var SEGMENT_NAME_RE3 = /^[A-Z][A-Z0-9]{2}$/u;
+var SEVERITIES = ["error", "warning", "info"];
+function isObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function checkCardinality(card, locus, out) {
+  if (card === void 0) return;
+  if (!isObject(card)) {
+    out.push({ locus, detail: `${describe(locus)} cardinality must be an object.` });
+    return;
+  }
+  const min = card["min"];
+  const max = card["max"];
+  if (min !== void 0 && (typeof min !== "number" || !Number.isInteger(min) || min < 0)) {
+    out.push({
+      locus,
+      detail: `${describe(locus)} cardinality.min must be a non-negative integer.`
+    });
+  }
+  if (max !== void 0 && max !== "*" && (typeof max !== "number" || !Number.isInteger(max) || max < 0)) {
+    out.push({
+      locus,
+      detail: `${describe(locus)} cardinality.max must be a non-negative integer or "*".`
+    });
+  }
+  if (typeof min === "number" && typeof max === "number" && Number.isInteger(min) && Number.isInteger(max) && max < min) {
+    out.push({
+      locus,
+      detail: `${describe(locus)} cardinality.max (${String(max)}) is less than min (${String(min)}).`
+    });
+  }
+}
+function describe(locus) {
+  if (locus.segment === "(profile)") return "profile";
+  let s = `segment "${locus.segment}"`;
+  if (locus.field !== void 0) s += ` field ${String(locus.field)}`;
+  return s;
+}
+function collectProfileDefects(profile) {
+  const out = [];
+  const root = { segment: "(profile)" };
+  if (!isObject(profile)) {
+    out.push({ locus: root, detail: "profile must be an object with `name` and `segments`." });
+    return out;
+  }
+  if (typeof profile["name"] !== "string" || profile["name"].trim().length === 0) {
+    out.push({ locus: root, detail: "profile.name must be a non-empty string." });
+  }
+  const segments = profile["segments"];
+  if (!Array.isArray(segments)) {
+    out.push({ locus: root, detail: "profile.segments must be an array of segment rules." });
+    return out;
+  }
+  for (let i = 0; i < segments.length; i++) {
+    const seg = segments[i];
+    if (!isObject(seg)) {
+      out.push({ locus: root, detail: `segments[${String(i)}] must be an object.` });
+      continue;
+    }
+    const name = seg["segment"];
+    if (typeof name !== "string" || !SEGMENT_NAME_RE3.test(name)) {
+      out.push({
+        locus: root,
+        detail: `segments[${String(i)}].segment must be a valid segment name ([A-Z][A-Z0-9]{2}).`
+      });
+      continue;
+    }
+    const segLocus = { segment: name };
+    checkUsage(seg["usage"], segLocus, out);
+    checkSeverity(seg["severity"], segLocus, out);
+    checkCardinality(seg["cardinality"], segLocus, out);
+    const fields = seg["fields"];
+    if (fields !== void 0) {
+      if (!Array.isArray(fields)) {
+        out.push({ locus: segLocus, detail: `segment "${name}" fields must be an array.` });
+        continue;
+      }
+      for (let j = 0; j < fields.length; j++) {
+        checkFieldRule(fields[j], name, j, out);
+      }
+    }
+  }
+  return out;
+}
+function checkUsage(usage, locus, out) {
+  if (usage === void 0) return;
+  if (typeof usage !== "string" || !USAGE_CODES.includes(usage)) {
+    out.push({
+      locus,
+      detail: `${describe(locus)} usage must be one of ${USAGE_CODES.join("/")}.`
+    });
+  }
+}
+function checkSeverity(sev, locus, out) {
+  if (sev === void 0) return;
+  if (typeof sev !== "string" || !SEVERITIES.includes(sev)) {
+    out.push({
+      locus,
+      detail: `${describe(locus)} severity must be one of ${SEVERITIES.join("/")}.`
+    });
+  }
+}
+function checkFieldRule(rule, segment, index, out) {
+  const locus = { segment };
+  if (!isObject(rule)) {
+    out.push({ locus, detail: `segment "${segment}" fields[${String(index)}] must be an object.` });
+    return;
+  }
+  const field = rule["field"];
+  if (typeof field !== "number" || !Number.isInteger(field) || field < 1) {
+    out.push({
+      locus,
+      detail: `segment "${segment}" fields[${String(index)}].field must be a positive (1-indexed) integer.`
+    });
+    return;
+  }
+  const fieldLocus = { segment, field };
+  checkUsage(rule["usage"], fieldLocus, out);
+  checkSeverity(rule["severity"], fieldLocus, out);
+  checkCardinality(rule["cardinality"], fieldLocus, out);
+  const len = rule["length"];
+  if (len !== void 0 && (typeof len !== "number" || !Number.isInteger(len) || len < 0)) {
+    out.push({
+      locus: fieldLocus,
+      detail: `${describe(fieldLocus)} length must be a non-negative integer.`
+    });
+  }
+  const comp = rule["component"];
+  if (comp !== void 0 && (typeof comp !== "number" || !Number.isInteger(comp) || comp < 1)) {
+    out.push({
+      locus: fieldLocus,
+      detail: `${describe(fieldLocus)} component must be a positive (1-indexed) integer.`
+    });
+  }
+  const vs = rule["valueSet"];
+  if (vs !== void 0) {
+    if (!Array.isArray(vs)) {
+      out.push({
+        locus: fieldLocus,
+        detail: `${describe(fieldLocus)} valueSet must be an array of strings.`
+      });
+    } else if (!vs.every((c) => typeof c === "string")) {
+      out.push({
+        locus: fieldLocus,
+        detail: `${describe(fieldLocus)} valueSet entries must all be strings.`
+      });
+    }
+  }
+}
+function defineConformanceProfile(profile) {
+  const defects = collectProfileDefects(profile);
+  if (defects.length > 0) {
+    const name = isObject(profile) && typeof profile["name"] === "string" ? profile["name"] : void 0;
+    throw new ProfileDefinitionError(
+      `Conformance profile has ${String(defects.length)} defect(s): ` + defects.map((d) => d.detail).join("; "),
+      name
+    );
+  }
+  return profile;
+}
+
+// src/conformance/validate-against-profile.ts
+function safeName(profile) {
+  if (typeof profile === "object" && profile !== null && !Array.isArray(profile)) {
+    const n = profile["name"];
+    if (typeof n === "string" && n.trim().length > 0) return n;
+  }
+  return "(unnamed profile)";
+}
+function componentValue(rep, component) {
+  return rep.components[component - 1]?.subcomponents[0] ?? "";
+}
+function fieldHasValue(field) {
+  return field.repetitions.some(
+    (rep) => rep.components.some((comp) => comp.subcomponents.some((sub) => sub !== ""))
+  );
+}
+function presenceVerdict(usage, present) {
+  if (usage === "R" && !present) return "required-absent";
+  if (usage === "X" && present) return "not-permitted";
+  return null;
+}
+function checkCardinality2(count, card, locus, unit, severity, out) {
+  if (card === void 0) return;
+  const { min, max } = card;
+  if (typeof max === "number" && count > max) {
+    out.push(cardinality(locus, count, card, unit, severity));
+    return;
+  }
+  if (typeof min === "number" && count > 0 && count < min) {
+    out.push(cardinality(locus, count, card, unit, severity));
+  }
+}
+function checkFields(seg, occurrence, fields, out) {
+  for (const rule of fields) {
+    const severity = rule.severity ?? "error";
+    const field = seg.field(rule.field);
+    const present = fieldHasValue(field);
+    const baseLocus = { segment: seg.type, field: rule.field, occurrence };
+    const verdict = presenceVerdict(rule.usage, present);
+    if (verdict === "required-absent") {
+      out.push(requiredAbsent(baseLocus, severity));
+      continue;
+    }
+    if (verdict === "not-permitted") {
+      out.push(notPermitted(baseLocus, severity));
+      continue;
+    }
+    if (!present) continue;
+    const reps = field.repetitions;
+    checkCardinality2(reps.length, rule.cardinality, baseLocus, "repetition", severity, out);
+    if (rule.length === void 0 && rule.valueSet === void 0) continue;
+    const component = rule.component ?? 1;
+    for (let r = 0; r < reps.length; r++) {
+      const rep = reps[r];
+      if (rep === void 0) continue;
+      const value = componentValue(rep, component);
+      const locus = {
+        segment: seg.type,
+        field: rule.field,
+        component,
+        repetition: r,
+        occurrence
+      };
+      if (rule.length !== void 0 && value.length > rule.length) {
+        out.push(length(locus, value.length, rule.length, severity));
+      }
+      if (rule.valueSet !== void 0 && value !== "" && !rule.valueSet.includes(value)) {
+        out.push(valueNotInSet(locus, rule.valueSet.length, severity));
+      }
+    }
+  }
+}
+function checkSegment(message, rule, out) {
+  const severity = rule.severity ?? "error";
+  const occurrences = message.segments(rule.segment);
+  const count = occurrences.length;
+  const present = count > 0;
+  const segLocus = { segment: rule.segment };
+  const verdict = presenceVerdict(rule.usage, present);
+  if (verdict === "required-absent") {
+    out.push(requiredAbsent(segLocus, severity));
+    return;
+  }
+  if (verdict === "not-permitted") {
+    out.push(notPermitted(segLocus, severity));
+    return;
+  }
+  checkCardinality2(count, rule.cardinality, segLocus, "occurrence", severity, out);
+  if (!present || rule.fields === void 0) return;
+  for (let occ = 0; occ < occurrences.length; occ++) {
+    const seg = occurrences[occ];
+    if (seg === void 0) continue;
+    checkFields(seg, occ, rule.fields, out);
+  }
+}
+function validateAgainstProfile(message, profile) {
+  const defects = collectProfileDefects(profile);
+  if (defects.length > 0) {
+    const findings = defects.map((d) => malformed(d.locus, d.detail));
+    return Object.freeze({ profileName: safeName(profile), findings: Object.freeze(findings) });
+  }
+  const out = [];
+  for (const rule of profile.segments) {
+    checkSegment(message, rule, out);
+  }
+  return Object.freeze({ profileName: profile.name, findings: Object.freeze(out) });
+}
+
+// src/conformance/index.ts
+var conformance_exports = {};
+__export(conformance_exports, {
+  FINDING_CODES: () => FINDING_CODES,
+  USAGE_CODES: () => USAGE_CODES,
+  collectProfileDefects: () => collectProfileDefects,
+  defineConformanceProfile: () => defineConformanceProfile,
+  validateAgainstProfile: () => validateAgainstProfile
+});
+function isEnvelopeName2(name) {
+  return name === "FHS" || name === "BHS" || name === "BTS" || name === "FTS";
+}
+function decodeChunk(chunk) {
+  if (typeof chunk === "string") return { text: chunk, wasBuffer: false };
+  if (chunk instanceof Uint8Array) {
+    return { text: Buffer.from(chunk).toString("latin1"), wasBuffer: true };
+  }
+  throw new TypeError(
+    `parseStream: each chunk must be a string, Buffer, or Uint8Array; received ${chunk === null ? "null" : typeof chunk}.`
+  );
+}
+async function* iterateChunks(source) {
+  if (source === null || source === void 0) {
+    throw new TypeError("parseStream: source must be an async-iterable or iterable of chunks.");
+  }
+  const asAsync = source[Symbol.asyncIterator];
+  if (typeof asAsync === "function") {
+    for await (const chunk of source) yield chunk;
+    return;
+  }
+  const asSync = source[Symbol.iterator];
+  if (typeof asSync === "function") {
+    for (const chunk of source) yield chunk;
+    return;
+  }
+  throw new TypeError(
+    "parseStream: source must be an async-iterable or iterable of chunks (e.g. a Node Readable)."
+  );
+}
+function nextSegment(buf, cursor, final) {
+  if (cursor >= buf.length) return null;
+  const r = buf.indexOf("\r", cursor);
+  const n = buf.indexOf("\n", cursor);
+  let idx;
+  let isCr;
+  if (r === -1 && n === -1) return null;
+  else if (r === -1) {
+    idx = n;
+    isCr = false;
+  } else if (n === -1) {
+    idx = r;
+    isCr = true;
+  } else if (r < n) {
+    idx = r;
+    isCr = true;
+  } else {
+    idx = n;
+    isCr = false;
+  }
+  if (isCr && idx === buf.length - 1 && !final) return null;
+  let termLen = 1;
+  if (isCr && idx + 1 < buf.length && buf.charCodeAt(idx + 1) === 10) termLen = 2;
+  return { seg: buf.slice(cursor, idx), next: idx + termLen };
+}
+function parseStreamEntry(rawMessage, position, wasBuffer, optionsOrProfile, streamWarnings) {
+  const input = wasBuffer ? Buffer.from(rawMessage, "latin1") : rawMessage;
+  try {
+    const message = optionsOrProfile === void 0 ? parseHL7(input) : parseHL7(input, optionsOrProfile);
+    return Object.freeze({ ok: true, message, raw: rawMessage, position, streamWarnings });
+  } catch (error) {
+    if (error instanceof Hl7ParseError) {
+      return Object.freeze({ ok: false, error, raw: rawMessage, position, streamWarnings });
+    }
+    throw error;
+  }
+}
+async function* parseStream(source, optionsOrProfile) {
+  if (typeof source === "string" || source instanceof Uint8Array) {
+    throw new TypeError(
+      "parseStream expects a stream of chunks (a Node Readable, an async-iterable, or an iterable of string/Buffer chunks), not a single string or Buffer. For one message use parseHL7; to stream a whole buffer, wrap it: parseStream([buffer])."
+    );
+  }
+  let pending = "";
+  let currentLines = [];
+  let messageStartIndex = -1;
+  let globalSegmentIndex = 0;
+  let wasBuffer = false;
+  let firstChunkSeen = false;
+  let bomStripped = false;
+  const flush = (finalUnterminated2) => {
+    while (currentLines.length > 0 && currentLines[currentLines.length - 1] === "") {
+      currentLines.pop();
+    }
+    if (currentLines.length === 0) {
+      messageStartIndex = -1;
+      return null;
+    }
+    const position = Object.freeze({ segmentIndex: messageStartIndex });
+    const streamWarnings = finalUnterminated2 ? Object.freeze([unterminatedStreamMessage(position)]) : Object.freeze([]);
+    const entry = parseStreamEntry(
+      currentLines.join("\r"),
+      position,
+      wasBuffer,
+      optionsOrProfile,
+      streamWarnings
+    );
+    currentLines = [];
+    messageStartIndex = -1;
+    return entry;
+  };
+  const processSegment = (seg) => {
+    const thisIndex = globalSegmentIndex;
+    globalSegmentIndex += 1;
+    const name = seg.slice(0, 3);
+    if (isEnvelopeName2(name)) {
+      return flush(false);
+    }
+    if (name === "MSH") {
+      const flushed = flush(false);
+      currentLines = [seg];
+      messageStartIndex = thisIndex;
+      return flushed;
+    }
+    if (currentLines.length === 0) {
+      if (seg.trim() === "") return null;
+      messageStartIndex = thisIndex;
+    }
+    currentLines.push(seg);
+    return null;
+  };
+  const tryStripBom = (final) => {
+    if (bomStripped || pending.length === 0) return;
+    if (pending.charCodeAt(0) === 65279) {
+      pending = pending.slice(1);
+      bomStripped = true;
+    } else if (pending.startsWith("\xEF\xBB\xBF")) {
+      pending = pending.slice(3);
+      bomStripped = true;
+    } else if (final || !"\xEF\xBB\xBF".startsWith(pending)) {
+      bomStripped = true;
+    }
+  };
+  for await (const rawChunk of iterateChunks(source)) {
+    const { text, wasBuffer: chunkWasBuffer } = decodeChunk(rawChunk);
+    if (!firstChunkSeen) {
+      wasBuffer = chunkWasBuffer;
+      firstChunkSeen = true;
+    }
+    if (text.length === 0) continue;
+    pending += text;
+    tryStripBom(false);
+    if (!bomStripped) continue;
+    let cursor = 0;
+    for (; ; ) {
+      const res = nextSegment(pending, cursor, false);
+      if (res === null) break;
+      cursor = res.next;
+      const entry = processSegment(res.seg);
+      if (entry !== null) yield entry;
+    }
+    pending = pending.slice(cursor);
+  }
+  tryStripBom(true);
+  {
+    let cursor = 0;
+    for (; ; ) {
+      const res = nextSegment(pending, cursor, true);
+      if (res === null) break;
+      cursor = res.next;
+      const entry = processSegment(res.seg);
+      if (entry !== null) yield entry;
+    }
+    pending = pending.slice(cursor);
+  }
+  const tail = pending;
+  pending = "";
+  let finalUnterminated = false;
+  if (tail.length > 0) {
+    const flushed = processSegment(tail);
+    if (flushed !== null) yield flushed;
+    finalUnterminated = currentLines.length > 0 && tail.trim() !== "";
+  }
+  const finalEntry = flush(finalUnterminated);
+  if (finalEntry !== null) yield finalEntry;
+}
+
 // src/index.ts
-var VERSION = "0.0.1";
+var VERSION = "0.0.2";
 
-export { ACK_CODES, ACK_CONDITIONS, BUILTIN_DATE_FALLBACKS, DEFAULT_ENCODING_CHARACTERS, ERR_CONDITION_CODES, ERR_CONDITION_CODE_SYSTEM, ERR_SEVERITIES, FATAL_CODES, Field, namespace_exports as HL7, Hl7Message, Hl7ParseError, KNOWN_CODING_SYSTEMS, KNOWN_SEGMENTS, MESSAGE_STRUCTURE_DEFINITIONS, ProfileDefinitionError, SUPPORTED_DATE_TOKENS, Segment, VERSION, WARNING_CODES, ackNoCorrelationId, alternateCodingSystemOf, analyzeMessageStructure, batchCountMismatch, batchMissingTrailer, buildAck, buildMessage, canonicalCharset, codingSystem, codingSystemOf, defineProfile, detectAckMode, downgradePositiveAck, dtmToDate, duplicateRequiredSegment, encodingMismatch, extraFields, fieldWhitespaceTrimmed, formatDtm, getDefaultProfile, interpretAck, isPositiveAck, mergeMissingPriorOrSurvivor, missingExpectedGroup, missingRequiredField, mllpFramingStripped, outOfOrderSegment, parseCe, parseCwe, parseCx, parseDtm, parseHL7, parseHd, parseNm, parsePath, parsePl, parseSn, parseTs, parseXad, parseXcn, parseXpn, parseXtn, pickMrn, profiles, reescape, resolveCharset, resolvePath, segmentCase, setDefaultProfile, splitBatch, timestampFallbackFormat, unescape, unknownCharset, unknownEscapeSequence, unknownSegment, unsupportedCharset, unterminatedEscapeSequence, versionMismatch };
+export { ACK_CODES, ACK_CONDITIONS, 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
 //# sourceMappingURL=index.mjs.map