@cosyte/hl7 0.0.1 → 0.0.2

package/dist/index.cjs

@@ -3,6 +3,12 @@
 var crypto = require('crypto');
 var buffer = require('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",
@@ -68,7 +74,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
     );
@@ -76,7 +82,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
     );
@@ -85,7 +91,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
     );
@@ -269,7 +275,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 {
@@ -347,7 +354,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
   };
 }
@@ -432,7 +439,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
   };
 }
@@ -588,7 +602,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",
@@ -775,7 +789,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",
@@ -787,7 +801,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",
@@ -797,7 +811,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({
@@ -860,7 +874,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",
@@ -870,7 +884,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",
@@ -880,7 +894,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({
@@ -890,7 +904,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",
@@ -1020,7 +1034,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);
@@ -1146,6 +1160,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;
@@ -1724,13 +1859,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;
@@ -1748,7 +1883,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.
    *
@@ -1769,13 +1904,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.
@@ -1794,7 +1929,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
@@ -1809,12 +1944,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.
    *
@@ -1831,7 +1987,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
@@ -1921,7 +2077,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)`.
@@ -1937,7 +2093,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
@@ -2007,7 +2163,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;
@@ -2023,7 +2179,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
@@ -2046,16 +2202,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
@@ -2082,13 +2238,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
@@ -3136,8 +3292,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++) {
@@ -3456,7 +3612,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()
@@ -3475,7 +3631,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) {
@@ -3516,6 +3672,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) {
@@ -3525,7 +3880,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).
    */
@@ -3535,7 +3890,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.
@@ -3565,14 +3920,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
    */
@@ -3609,9 +3964,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
@@ -3620,7 +3975,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) {
@@ -3629,7 +3984,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
@@ -3695,7 +4050,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).
    *
@@ -3711,10 +4066,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.
    *
@@ -3729,14 +4084,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() {
@@ -3764,7 +4119,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
@@ -3779,7 +4134,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.
    *
@@ -3787,7 +4142,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
    * }
    * ```
    */
@@ -3795,11 +4150,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
@@ -3812,7 +4167,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
@@ -3839,7 +4194,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
@@ -3860,7 +4215,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
@@ -3930,7 +4285,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
@@ -3947,7 +4302,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).
@@ -3967,7 +4322,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).
    *
@@ -3988,7 +4343,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
@@ -4006,7 +4361,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
@@ -4025,16 +4380,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
@@ -4054,13 +4409,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).
@@ -4097,7 +4452,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) {
@@ -4105,7 +4460,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;
@@ -4114,7 +4469,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;
@@ -4123,7 +4478,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;
@@ -4143,9 +4498,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
@@ -4195,14 +4636,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).
    *
@@ -4380,9 +4821,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] ?? "";
@@ -4514,6 +4955,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";
@@ -4629,6 +5088,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",
@@ -4711,7 +5411,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);
@@ -4720,8 +5420,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),
@@ -4732,26 +5432,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)) {
@@ -4791,24 +5491,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) {
@@ -5068,7 +5768,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
       );
     }
@@ -5095,7 +5795,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
       );
     }
@@ -5153,7 +5853,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 } }
@@ -5163,7 +5863,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 } },
@@ -5174,7 +5874,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 } },
@@ -5185,7 +5885,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 } },
@@ -5196,10 +5896,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 } }
   }
 });
 
@@ -5209,7 +6021,10 @@ var profiles = Object.freeze({
   cerner,
   epic,
   genericLab,
-  meditech
+  meditech,
+  philips,
+  va,
+  visage
 });
 
 // src/model/coding-system.ts
@@ -5441,8 +6256,560 @@ 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.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.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";
 
 exports.ACK_CODES = ACK_CODES;
 exports.ACK_CONDITIONS = ACK_CONDITIONS;
@@ -5452,6 +6819,7 @@ exports.ERR_CONDITION_CODES = ERR_CONDITION_CODES;
 exports.ERR_CONDITION_CODE_SYSTEM = ERR_CONDITION_CODE_SYSTEM;
 exports.ERR_SEVERITIES = ERR_SEVERITIES;
 exports.FATAL_CODES = FATAL_CODES;
+exports.FINDING_CODES = FINDING_CODES;
 exports.Field = Field;
 exports.HL7 = namespace_exports;
 exports.Hl7Message = Hl7Message;
@@ -5462,6 +6830,7 @@ exports.MESSAGE_STRUCTURE_DEFINITIONS = MESSAGE_STRUCTURE_DEFINITIONS;
 exports.ProfileDefinitionError = ProfileDefinitionError;
 exports.SUPPORTED_DATE_TOKENS = SUPPORTED_DATE_TOKENS;
 exports.Segment = Segment;
+exports.USAGE_CODES = USAGE_CODES;
 exports.VERSION = VERSION;
 exports.WARNING_CODES = WARNING_CODES;
 exports.ackNoCorrelationId = ackNoCorrelationId;
@@ -5470,15 +6839,34 @@ exports.analyzeMessageStructure = analyzeMessageStructure;
 exports.batchCountMismatch = batchCountMismatch;
 exports.batchMissingTrailer = batchMissingTrailer;
 exports.buildAck = buildAck;
+exports.buildAdt = buildAdt;
 exports.buildMessage = buildMessage;
+exports.buildOru = buildOru;
 exports.canonicalCharset = canonicalCharset;
 exports.codingSystem = codingSystem;
 exports.codingSystemOf = codingSystemOf;
+exports.conformance = conformance_exports;
+exports.decodeText = decodeText;
+exports.defineConformanceProfile = defineConformanceProfile;
 exports.defineProfile = defineProfile;
 exports.detectAckMode = detectAckMode;
 exports.downgradePositiveAck = downgradePositiveAck;
 exports.dtmToDate = dtmToDate;
 exports.duplicateRequiredSegment = duplicateRequiredSegment;
+exports.encodeCe = encodeCe;
+exports.encodeComposite = encodeComposite;
+exports.encodeCompositeReps = encodeCompositeReps;
+exports.encodeCwe = encodeCwe;
+exports.encodeCx = encodeCx;
+exports.encodeHd = encodeHd;
+exports.encodeNm = encodeNm;
+exports.encodePl = encodePl;
+exports.encodeText = encodeText;
+exports.encodeTs = encodeTs;
+exports.encodeXad = encodeXad;
+exports.encodeXcn = encodeXcn;
+exports.encodeXpn = encodeXpn;
+exports.encodeXtn = encodeXtn;
 exports.encodingMismatch = encodingMismatch;
 exports.extraFields = extraFields;
 exports.fieldWhitespaceTrimmed = fieldWhitespaceTrimmed;
@@ -5501,6 +6889,7 @@ exports.parseNm = parseNm;
 exports.parsePath = parsePath;
 exports.parsePl = parsePl;
 exports.parseSn = parseSn;
+exports.parseStream = parseStream;
 exports.parseTs = parseTs;
 exports.parseXad = parseXad;
 exports.parseXcn = parseXcn;
@@ -5509,11 +6898,13 @@ exports.parseXtn = parseXtn;
 exports.pickMrn = pickMrn;
 exports.profiles = profiles;
 exports.reescape = reescape;
+exports.renderText = renderText;
 exports.resolveCharset = resolveCharset;
 exports.resolvePath = resolvePath;
 exports.segmentCase = segmentCase;
 exports.setDefaultProfile = setDefaultProfile;
 exports.splitBatch = splitBatch;
+exports.text = text_exports;
 exports.timestampFallbackFormat = timestampFallbackFormat;
 exports.unescape = unescape;
 exports.unknownCharset = unknownCharset;
@@ -5521,6 +6912,8 @@ exports.unknownEscapeSequence = unknownEscapeSequence;
 exports.unknownSegment = unknownSegment;
 exports.unsupportedCharset = unsupportedCharset;
 exports.unterminatedEscapeSequence = unterminatedEscapeSequence;
+exports.unterminatedStreamMessage = unterminatedStreamMessage;
+exports.validateAgainstProfile = validateAgainstProfile;
 exports.versionMismatch = versionMismatch;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map