@cosyte/transform 0.0.7 → 0.0.9

package/dist/index.d.cts

@@ -9,39 +9,39 @@ import { HD, TS, CX, CWE, XPN, XAD, NM, Hl7Message } from '@cosyte/hl7';
  * or removing one is a **breaking change** (mirrors the parser archetype's stable-warning-code rule).
  * New codes are **additions only**.
  *
- * - {@link ISSUE_CODES} — non-fatal, typed diagnostics carried on a {@link TransformResult}. Every
+ * - {@link ISSUE_CODES}: non-fatal, typed diagnostics carried on a {@link TransformResult}. Every
  *   fail-safe decision the transform makes (a naked timestamp, an unresolvable assigning authority,
- *   an unmapped code, a non-UCUM unit, a dropped element) surfaces as one of these — **never** a
+ *   an unmapped code, a non-UCUM unit, a dropped element) surfaces as one of these, **never** a
  *   silently-defaulted or fabricated FHIR value.
- * - {@link FATAL_CODES} — the small set of unrecoverable conditions reserved for message-level
+ * - {@link FATAL_CODES}: the small set of unrecoverable conditions reserved for message-level
  *   entry points. **Nothing in this library throws one today**: the datatype converters and
  *   `toFhir` alike fail safe to a value-free issue instead.
  *
  * @packageDocumentation
  */
 /**
- * Stable **non-fatal issue codes** — the typed diagnostics the fail-safe rule emits.
+ * Stable **non-fatal issue codes**: the typed diagnostics the fail-safe rule emits.
  *
  * @example
  * ```ts
  * import { ISSUE_CODES } from "@cosyte/transform";
  * if (issue.code === ISSUE_CODES.TRANSFORM_TIMESTAMP_NO_TIMEZONE) {
- *   // a v2 timestamp had a time-of-day but no timezone offset — reduced to date precision
+ *   // a v2 timestamp had a time-of-day but no timezone offset: reduced to date precision
  * }
  * ```
  */
 declare const ISSUE_CODES: {
     /** A v2 DTM/TS carried a time-of-day but no timezone offset. FHIR forbids time-without-zone, so
-     * the value was reduced to date precision (or an explicit sender offset applied via options) —
+     * the value was reduced to date precision (or an explicit sender offset applied via options),
      * **never** a guessed UTC. */
     readonly TRANSFORM_TIMESTAMP_NO_TIMEZONE: "TRANSFORM_TIMESTAMP_NO_TIMEZONE";
     /** A v2 DTM/TS could not be parsed into a valid FHIR date/time; no value was emitted. */
     readonly TRANSFORM_TIMESTAMP_INVALID: "TRANSFORM_TIMESTAMP_INVALID";
     /** The assigning authority (HD) could not be resolved to a FHIR `Identifier.system` URI via the
-     * NamingSystem registry. The identifier is emitted with its value and **no** system — a system URI
+     * NamingSystem registry. The identifier is emitted with its value and **no** system: a system URI
      * is **never** synthesized from HD.1 alone. */
     readonly TRANSFORM_IDENTIFIER_SYSTEM_UNRESOLVED: "TRANSFORM_IDENTIFIER_SYSTEM_UNRESOLVED";
-    /** A coded value could not be mapped to a FHIR concept — either it carried no coding-system context
+    /** A coded value could not be mapped to a FHIR concept: either it carried no coding-system context
      * (CWE.3 absent), or it is a table code the IG ConceptMap has **no target** for (e.g. an OBX-11/
      * OBR-25 result status the HL70085/HL70123 map does not carry, or an OBX-8 abnormal flag absent from
      * HL70078). The original code is preserved / the FHIR value left absent; **never** coerced to a
@@ -51,14 +51,14 @@ declare const ISSUE_CODES: {
      * be emitted. The code is preserved; a URI is **never** invented. */
     readonly TRANSFORM_CODE_SYSTEM_UNRESOLVED: "TRANSFORM_CODE_SYSTEM_UNRESOLVED";
     /** A unit was not a valid UCUM code (or was not declared UCUM). It is preserved verbatim in
-     * `Quantity.unit`; `Quantity.code`/`.system` are left absent — a UCUM code is **never** fabricated
+     * `Quantity.unit`; `Quantity.code`/`.system` are left absent: a UCUM code is **never** fabricated
      * and a magnitude is **never** converted. */
     readonly TRANSFORM_UNIT_NOT_UCUM: "TRANSFORM_UNIT_NOT_UCUM";
-    /** A v2 numeric value (NM) could not be represented as a FHIR `decimal` without altering it — e.g.
+    /** A v2 numeric value (NM) could not be represented as a FHIR `decimal` without altering it, e.g.
      * a leading `+`, a leading zero, or a trailing dot, which FHIR's `decimal` lexical form forbids. No
      * `Quantity` value is emitted rather than a canonicalized (and therefore altered) magnitude. */
     readonly TRANSFORM_QUANTITY_VALUE_INVALID: "TRANSFORM_QUANTITY_VALUE_INVALID";
-    /** A populated source element was not carried to its FHIR target and was dropped — either because
+    /** A populated source element was not carried to its FHIR target and was dropped, either because
      * the IG map defines no target, or because that target's conversion is **not implemented**
      * (e.g. XTN→ContactPoint telecom, PV1 participants). Surfaced here rather than silently discarded,
      * never a fabricated value. */
@@ -71,20 +71,20 @@ declare const ISSUE_CODES: {
     readonly TRANSFORM_ADDRESS_USE_UNMAPPED: "TRANSFORM_ADDRESS_USE_UNMAPPED";
     /** The message's trigger event has no IG *message* map, so its resource graph was assembled from
      * the reusable IG *segment* maps rather than a message map. The graph is best-effort and flagged
-     * as such — never a fabricated message map. */
+     * as such, never a fabricated message map. */
     readonly TRANSFORM_SEGMENT_ASSEMBLED: "TRANSFORM_SEGMENT_ASSEMBLED";
     /** A produced FHIR resource failed `@cosyte/fhir` R4 structural validation and was **withheld**
-     * from the bundle rather than emitted as a silently-invalid resource — the conservative-emit gate. */
+     * from the bundle rather than emitted as a silently-invalid resource: the conservative-emit gate. */
     readonly TRANSFORM_RESOURCE_INVALID: "TRANSFORM_RESOURCE_INVALID";
     /** A FHIR-required element's value could not be faithfully derived from the source, so it was
-     * emitted with a `data-absent-reason` extension (value `unknown`) rather than fabricated — e.g.
+     * emitted with a `data-absent-reason` extension (value `unknown`) rather than fabricated, e.g.
      * `MessageHeader.source.endpoint` from an MSH-3 application namespace that is not a URL. */
     readonly TRANSFORM_REQUIRED_ELEMENT_UNKNOWN: "TRANSFORM_REQUIRED_ELEMENT_UNKNOWN";
 };
-/** A value from {@link ISSUE_CODES} — the type consumers narrow `issue.code` against. */
+/** A value from {@link ISSUE_CODES}: the type consumers narrow `issue.code` against. */
 type IssueCode = (typeof ISSUE_CODES)[keyof typeof ISSUE_CODES];
 /**
- * Stable **fatal codes** — the reserved names for unrecoverable input conditions. **Nothing in this
+ * Stable **fatal codes**: the reserved names for unrecoverable input conditions. **Nothing in this
  * library throws one today**; every path, datatype and message level alike, fails safe to a
  * value-free issue instead. They are declared so that a future one is an addition rather than a
  * rename.
@@ -101,23 +101,23 @@ declare const FATAL_CODES: {
     /** The input was not a shape this transform accepts. */
     readonly TRANSFORM_UNSUPPORTED_INPUT: "TRANSFORM_UNSUPPORTED_INPUT";
 };
-/** A value from {@link FATAL_CODES} — the type carried by a thrown fatal error. */
+/** A value from {@link FATAL_CODES}: the type carried by a thrown fatal error. */
 type FatalCode = (typeof FATAL_CODES)[keyof typeof FATAL_CODES];
 
 /**
- * The value-free {@link TransformIssue} — the single diagnostic shape the whole library emits.
+ * The value-free {@link TransformIssue}: the single diagnostic shape the whole library emits.
  *
  * Every issue is **`OperationOutcome`-shaped and PHI-safe by construction**: it carries the *v2
- * location* (segment / field / component index — never a value) and the *FHIR path* it concerns,
+ * location* (segment / field / component index, never a value) and the *FHIR path* it concerns,
  * plus a **static, per-code** severity and human-readable message drawn from {@link ISSUE_REGISTRY}.
- * Nothing in an issue is interpolated from patient data — the factory takes only positional metadata,
+ * Nothing in an issue is interpolated from patient data: the factory takes only positional metadata,
  * so there is no code path by which a name, DOB, MRN, or result value can reach a log line (the
  * discipline `@cosyte/fhir` already proved with its value-free `OperationOutcome`).
  *
  * @packageDocumentation
  */
 
-/** The severity a {@link TransformIssue} carries — an `OperationOutcome.issue.severity` value. */
+/** The severity a {@link TransformIssue} carries: an `OperationOutcome.issue.severity` value. */
 type TransformSeverity = "error" | "warning" | "information";
 /**
  * A single value-free diagnostic.
@@ -134,7 +134,7 @@ interface TransformIssue {
     readonly code: IssueCode;
     /** The `OperationOutcome`-style severity, fixed per code. */
     readonly severity: TransformSeverity;
-    /** The v2 source location — a segment / field / component **index**, never a value. */
+    /** The v2 source location: a segment / field / component **index**, never a value. */
     readonly v2Location: string;
     /** The FHIR path this issue concerns (e.g. `Identifier.system`), when applicable. */
     readonly fhirPath?: string;
@@ -146,12 +146,12 @@ interface IssueMeta {
     readonly severity: TransformSeverity;
     /** The FHIR `OperationOutcome.issue.code` (R4 `issue-type` value set) this maps to. */
     readonly fhirIssueType: string;
-    /** A static, value-free message. Contains no interpolated data — safe to log verbatim. */
+    /** A static, value-free message. Contains no interpolated data: safe to log verbatim. */
     readonly message: string;
 }
 /**
  * The per-code registry: severity, FHIR `issue-type`, and a static message. Frozen and exhaustive
- * over {@link ISSUE_CODES} (enforced by the `Record<IssueCode, …>` type — a new code will not
+ * over {@link ISSUE_CODES} (enforced by the `Record<IssueCode, …>` type: a new code will not
  * compile until it has an entry).
  */
 declare const ISSUE_REGISTRY: Readonly<Record<IssueCode, IssueMeta>>;
@@ -160,7 +160,7 @@ declare const ISSUE_REGISTRY: Readonly<Record<IssueCode, IssueMeta>>;
  * {@link ISSUE_REGISTRY}; the caller supplies only positional metadata, so an issue can carry no PHI.
  *
  * @param code - The stable {@link IssueCode}.
- * @param v2Location - The v2 source location (segment / field / component index) — never a value.
+ * @param v2Location - The v2 source location (segment / field / component index), never a value.
  * @param fhirPath - The FHIR path the issue concerns, when applicable.
  * @example
  * ```ts
@@ -171,7 +171,7 @@ declare const ISSUE_REGISTRY: Readonly<Record<IssueCode, IssueMeta>>;
  */
 declare function issue(code: IssueCode, v2Location: string, fhirPath?: string): TransformIssue;
 /**
- * The FHIR `issue-type` code for an {@link IssueCode} — used by the `OperationOutcome` renderer.
+ * The FHIR `issue-type` code for an {@link IssueCode}: used by the `OperationOutcome` renderer.
  *
  * @param code - The stable {@link IssueCode}.
  * @example
@@ -222,7 +222,7 @@ interface ConvertResult<T> {
  * materializes it as an actual `@cosyte/fhir` resource node a consumer can serialize, validate, or
  * return alongside a bundle. It is **value-free**: every field is drawn from the issue's static
  * metadata (code, severity, message) and its positional locations (v2 location → `diagnostics`, FHIR
- * path → `expression`) — no patient data is reachable here.
+ * path → `expression`). No patient data is reachable here.
  *
  * @packageDocumentation
  */
@@ -246,15 +246,15 @@ declare const TRANSFORM_ISSUE_SYSTEM = "https://cosyte.com/fhir/CodeSystem/trans
 declare function toOperationOutcome(issues: readonly TransformIssue[]): FhirComplex;
 
 /**
- * The NamingSystem registry — how an HL7 v2 identity/coding namespace becomes a FHIR canonical URI.
+ * The NamingSystem registry: how an HL7 v2 identity/coding namespace becomes a FHIR canonical URI.
  *
  * Two resolutions live here, and both are **fail-safe by refusal**:
  *
  * 1. **Assigning authority (HD) → `Identifier.system`.** The IG's CX→Identifier map says CX.4 maps to
- *    `Identifier.system` *only when the authority is in an identifier registry* — the URI comes from a
+ *    `Identifier.system` *only when the authority is in an identifier registry*: the URI comes from a
  *    NamingSystem lookup, **not** string concatenation. There is no deterministic algorithm from an
  *    HD to a URI, so this resolver **never synthesizes a system from HD.1 (the bare namespace
- *    mnemonic) alone** — doing so would let two hospitals reusing "MR"/"HOSPMRN" collide and merge two
+ *    mnemonic) alone**: doing so would let two hospitals reusing "MR"/"HOSPMRN" collide and merge two
  *    patients. The *only* auto-derivations are the unambiguous ones: `urn:oid:<oid>` when HD.2 is a
  *    valid OID with HD.3 = `ISO`, and `urn:uuid:<uuid>` when HD.3 = `UUID`. Everything else must be an
  *    explicit, caller-seeded registry entry, or it resolves to `undefined` and the caller emits a
@@ -263,14 +263,14 @@ declare function toOperationOutcome(issues: readonly TransformIssue[]): FhirComp
  * 2. **v2 coding-system mnemonic → canonical URI.** CWE.3/CWE.6 carry a v2 Table 0396 mnemonic
  *    (`LN`, `SCT`, …); FHIR needs the canonical URI (`http://loinc.org`, …). {@link DEFAULT_V2_CODE_SYSTEMS}
  *    seeds a small, license-clean set of the universally-fixed FHIR-core systems; an unrecognized
- *    mnemonic resolves to `undefined` (the caller preserves the raw code and flags it — a URI is
+ *    mnemonic resolves to `undefined` (the caller preserves the raw code and flags it: a URI is
  *    never invented). The full HL7 THO crosswalk is not bundled.
  *
  * @packageDocumentation
  */
 
 /**
- * The HL7 v2 Table 0203 identifier-type code system canonical URI — used to build `Identifier.type`.
+ * The HL7 v2 Table 0203 identifier-type code system canonical URI: used to build `Identifier.type`.
  * (FHIR R4 terminologies-systems.html)
  */
 declare const V2_0203_SYSTEM = "http://terminology.hl7.org/CodeSystem/v2-0203";
@@ -278,7 +278,7 @@ declare const V2_0203_SYSTEM = "http://terminology.hl7.org/CodeSystem/v2-0203";
  * A small, license-clean seed of v2 Table 0396 coding-system mnemonic → canonical URI, for the
  * FHIR-core-fixed systems whose URIs are universally cited (FHIR R4 terminologies-systems.html).
  * The full HL7 THO NamingSystem crosswalk is not bundled; callers extend this via
- * {@link createNamingSystem}. **No terminology *content* is bundled — only identity URIs.**
+ * {@link createNamingSystem}. **No terminology *content* is bundled: only identity URIs.**
  */
 declare const DEFAULT_V2_CODE_SYSTEMS: Readonly<Record<string, string>>;
 /** A seed for {@link createNamingSystem}: extra coding systems and explicit assigning authorities. */
@@ -321,7 +321,7 @@ declare function createNamingSystem(seed?: NamingSystemSeed): NamingSystemRegist
 /**
  * The options and context threaded through the datatype converters.
  *
- * These are **types only** — no runtime behavior. {@link TransformOptions} carries the policy knobs a
+ * These are **types only**, no runtime behavior. {@link TransformOptions} carries the policy knobs a
  * caller can set; {@link TransformContext} additionally carries the
  * {@link NamingSystemRegistry} the identity- and code-resolution paths consult.
  *
@@ -333,7 +333,7 @@ declare function createNamingSystem(seed?: NamingSystemSeed): NamingSystemRegist
  *
  * @remarks
  * `assumeTimezoneOffsetMinutes` is the **only** way a naked v2 timestamp acquires a time-of-day in
- * FHIR: the caller asserts the sender's offset (in minutes east of UTC — e.g. `-300` for US Eastern
+ * FHIR: the caller asserts the sender's offset (in minutes east of UTC, e.g. `-300` for US Eastern
  * standard time). It is a *sender-asserted* value, flagged as such; absent it, a naked timestamp is
  * reduced to date precision, **never** assumed to be UTC.
  */
@@ -343,7 +343,7 @@ interface TransformOptions {
     /**
      * The {@link NamingSystemRegistry} the message-level transform threads into every datatype
      * conversion (HD → `Identifier.system`, v2 mnemonic → canonical URI). When omitted, a default
-     * registry (`createNamingSystem()`) is used — it resolves only the FHIR-core-fixed systems and the
+     * registry (`createNamingSystem()`) is used: it resolves only the FHIR-core-fixed systems and the
      * two unambiguous HD auto-derivations, so an un-seeded assigning authority surfaces a typed issue
      * rather than a guessed system.
      */
@@ -351,7 +351,7 @@ interface TransformOptions {
     /**
      * Allocator for the `urn:uuid:` `Bundle.entry.fullUrl` / reference identities the assembler mints.
      * Defaults to `crypto.randomUUID`. Inject a deterministic generator to make bundle output
-     * reproducible (e.g. for golden fixtures). It must return a fresh, unique value per call — the
+     * reproducible (e.g. for golden fixtures). It must return a fresh, unique value per call: the
      * assembler relies on uniqueness for intra-bundle reference integrity.
      */
     readonly generateId?: () => string;
@@ -369,7 +369,7 @@ interface TransformContext {
 }
 
 /**
- * DTM / TS → FHIR `dateTime` — the single most dangerous conversion.
+ * DTM / TS → FHIR `dateTime`: the single most dangerous conversion.
  *
  * Grounded on the IG datatype ConceptMap **DTM → dateTime** (`DTM.1` *is equivalent to* the FHIR
  * `dateTime.$value`, with the instruction to "convert v2 date time format to FHIR date time format")
@@ -378,14 +378,14 @@ interface TransformContext {
  * offset** whenever a time is present. Two fail-safe consequences follow:
  *
  * - **Naked timestamp (no offset).** A `20260721143000` cannot become a valid zoned FHIR `dateTime`
- *   without inventing an offset — assuming UTC would silently shift the clinical instant by hours. So
+ *   without inventing an offset: assuming UTC would silently shift the clinical instant by hours. So
  *   the value is **reduced to date precision** (`2026-07-21`) and {@link ISSUE_CODES.TRANSFORM_TIMESTAMP_NO_TIMEZONE}
- *   is raised — unless the caller asserts the sender's offset via `options.assumeTimezoneOffsetMinutes`.
+ *   is raised, unless the caller asserts the sender's offset via `options.assumeTimezoneOffsetMinutes`.
  * - **Partial-precision time (hour/minute only).** FHIR cannot represent `hh` or `hh:mm` without
  *   seconds, and padding `:00` would fabricate precision, so such a value is likewise reduced to date
- *   precision and flagged — never padded.
+ *   precision and flagged, never padded.
  *
- * Date-only precisions (`2026`, `2026-07`, `2026-07-21`) are preserved exactly — never zero-filled —
+ * Date-only precisions (`2026`, `2026-07`, `2026-07-21`) are preserved exactly, never zero-filled,
  * and need no offset (FHIR permits a bare date).
  *
  * @packageDocumentation
@@ -409,18 +409,18 @@ interface TransformContext {
 declare function toFhirDateTime(ts: TS, options?: TransformOptions): ConvertResult<string>;
 
 /**
- * CX → FHIR `Identifier` — the patient-identity-integrity path.
+ * CX → FHIR `Identifier`: the patient-identity-integrity path.
  *
  * Grounded on the IG datatype ConceptMap **CX → Identifier**: `CX.1` → `Identifier.value`, `CX.4`
  * (assigning authority HD) → `Identifier.system` *when the authority resolves in a registry* (else
- * the IG maps it to `Identifier.assigner` — a message-level Organization reference this library does
+ * the IG maps it to `Identifier.assigner`: a message-level Organization reference this library does
  * not build), and `CX.5` (Table 0203) → `Identifier.type`.
  *
  * The load-bearing fail-safe: the assigning authority is resolved through the
  * {@link NamingSystemRegistry}, which **never synthesizes a system URI from HD.1 (the bare namespace)
- * alone** — two hospitals reusing "MR"/"HOSPMRN" would otherwise collide and merge two patients. On
+ * alone**. Two hospitals reusing "MR"/"HOSPMRN" would otherwise collide and merge two patients. On
  * an unresolved authority the identifier is emitted with its **value and no system**, plus a typed
- * {@link ISSUE_CODES.TRANSFORM_IDENTIFIER_SYSTEM_UNRESOLVED} issue — never a guessed system.
+ * {@link ISSUE_CODES.TRANSFORM_IDENTIFIER_SYSTEM_UNRESOLVED} issue, never a guessed system.
  *
  * @packageDocumentation
  */
@@ -446,10 +446,10 @@ declare function toFhirDateTime(ts: TS, options?: TransformOptions): ConvertResu
 declare function toFhirIdentifier(cx: CX, ctx?: TransformContext): ConvertResult<FhirComplex>;
 
 /**
- * CWE / CE → FHIR `CodeableConcept` — the code-fidelity path.
+ * CWE / CE → FHIR `CodeableConcept`: the code-fidelity path.
  *
  * Grounded on the IG datatype ConceptMap **CWE → CodeableConcept**: `CWE.1`→`coding[0].code`,
- * `CWE.2`→`coding[0].display`, `CWE.3`→`coding[0].system` **(indirect — the vocabulary table gives
+ * `CWE.2`→`coding[0].display`, `CWE.3`→`coding[0].system` **(indirect: the vocabulary table gives
  * the actual URI)**, `CWE.7`→`coding[0].version`, the alternate triplet `CWE.4/5/6`→`coding[1]` (+
  * `CWE.8`→`coding[1].version`), and `CWE.9`→`text`. `CE` is the 6-component subset of `CWE` and maps
  * through the same shape.
@@ -466,7 +466,7 @@ declare function toFhirIdentifier(cx: CX, ctx?: TransformContext): ConvertResult
  * @packageDocumentation
  */
 
-/** The subset of CWE fields a CE also provides — so `toFhirCodeableConcept` accepts both. */
+/** The subset of CWE fields a CE also provides, so `toFhirCodeableConcept` accepts both. */
 type CodedElement = Pick<CWE, "identifier" | "text" | "nameOfCodingSystem" | "alternateIdentifier" | "alternateText" | "nameOfAlternateCodingSystem" | "codingSystemVersionId" | "alternateCodingSystemVersionId" | "originalText">;
 /**
  * Convert a parsed HL7 v2 CWE (or CE) to a FHIR `CodeableConcept` node, fail-safe on the coding
@@ -496,7 +496,7 @@ declare function toFhirCodeableConcept(cwe: CodedElement, ctx?: TransformContext
  *
  * `XPN.7`→`use` is a **lossy code translation**: only the codes the IG's HL70200→name-use map covers
  * are translated; any other name-type code leaves `use` **absent** and raises
- * {@link ISSUE_CODES.TRANSFORM_NAME_USE_UNMAPPED} — never guessed. Not converted, and flagged:
+ * {@link ISSUE_CODES.TRANSFORM_NAME_USE_UNMAPPED}, never guessed. Not converted, and flagged:
  * the name-validity period (`XPN.12`/`XPN.13`), whose FHIR `period` needs the timezone policy of the
  * dateTime path.
  *
@@ -533,11 +533,11 @@ declare function toFhirHumanName(xpn: XPN): ConvertResult<FhirComplex>;
  * - `XAD.7 IN {BA, BI, C, B, H, O}` → `Address.use` (via the IG **HL70190 → address-use** map);
  * - `XAD.7 IN {M, SH}` → `Address.type` (via the IG **HL70190 → address-type** map);
  * - a vacation address (`V` in Table 0190; the datatype map references `HV`) → an ISO-21090 extension
- *   the IG defines — **not emitted**, and flagged rather than invented;
+ *   the IG defines, **not emitted**, and flagged rather than invented;
  * - any other code → `use`/`type` left absent, flagged {@link ISSUE_CODES.TRANSFORM_ADDRESS_USE_UNMAPPED}.
  *
  * FHIR deliberately separates `use` (home/work/temp) from `type` (postal/physical), so one v2 code
- * cannot always populate both axes — round-trip is not stable, and the drop is surfaced, never hidden.
+ * cannot always populate both axes: round-trip is not stable, and the drop is surfaced, never hidden.
  * `XAD.8` (other geographic designation) has no FHIR target and is flagged dropped.
  *
  * @packageDocumentation
@@ -571,7 +571,7 @@ declare function toFhirAddress(xad: XAD): ConvertResult<FhirComplex>;
  * - **Never convert magnitudes.** The numeric value is carried through **precision-exact** via
  *   `@cosyte/fhir`'s string-backed `decimal` (a dose or lab value is never routed through a JS
  *   `number`). UCUM magnitude conversion (mg/dL ↔ mmol/L) is analyte-dependent and a
- *   clinical-safety footgun — an explicit non-goal, never a transform side effect.
+ *   clinical-safety footgun: an explicit non-goal, never a transform side effect.
  * - **Never fabricate a UCUM code.** A unit is emitted into `Quantity.code`/`.system` **only** when
  *   it is declared UCUM and passes `@cosyte/fhir`'s UCUM shape check. Any other unit is preserved
  *   verbatim in `Quantity.unit` with `code`/`system` absent, flagged
@@ -602,12 +602,12 @@ declare function toFhirAddress(xad: XAD): ConvertResult<FhirComplex>;
 declare function toFhirQuantity(value: NM, units: CWE, ctx?: TransformContext): ConvertResult<FhirComplex>;
 
 /**
- * `toFhir` — the message-level entry point: assemble a parsed HL7 v2 message into a FHIR R4
+ * `toFhir`, the message-level entry point: assemble a parsed HL7 v2 message into a FHIR R4
  * **message Bundle** (a `MessageHeader` first, then the focal resources), grounded on the IG message
  * and segment maps. The **ADT** family becomes **Patient + Encounter** (+ `RelatedPerson`
  * from NK1); the **ORU^R01** results graph becomes `DiagnosticReport` + `Observation`; the
- * order-entry graph — **ORM_O01 / OML_O21** ORC/OBR → `ServiceRequest` and **RXO** (+ RXR) →
- * `MedicationRequest`; and the thin IG singles — **VXU_V04** RXA/RXR/ORC → `Immunization`,
+ * order-entry graph gives **ORM_O01 / OML_O21** ORC/OBR → `ServiceRequest` and **RXO** (+ RXR) →
+ * `MedicationRequest`; and the thin IG singles give **VXU_V04** RXA/RXR/ORC → `Immunization`,
  * **SIU_S12** SCH/AIS/PID → `Appointment`, and **MDM_T02** TXA/OBX → `DocumentReference`.
  *
  * The fail-safe rule holds at the message level. Two message-level fail-safes join the datatype ones:
@@ -615,15 +615,15 @@ declare function toFhirQuantity(value: NM, units: CWE, ctx?: TransformContext):
  * - **Segment-assembled, not fabricated.** For an ADT trigger the IG maps ({@link IG_MAPPED_ADT_TRIGGERS}),
  *   the graph is message-map-grounded. For any other trigger there is no IG *message* map, so the
  *   graph is assembled from the reusable IG *segment* maps and flagged
- *   {@link ISSUE_CODES.TRANSFORM_SEGMENT_ASSEMBLED} — never a fabricated message map.
+ *   {@link ISSUE_CODES.TRANSFORM_SEGMENT_ASSEMBLED}, never a fabricated message map.
  * - **Conservative emit gate.** Every produced resource is run through `@cosyte/fhir.validateResource`
- *   before it can join the bundle — `Patient` against the built-in schema in `strict` mode, and the
+ *   before it can join the bundle: `Patient` against the built-in schema in `strict` mode, and the
  *   other types against the minimal required-cardinality {@link EMIT_SCHEMAS} in `lenient` mode (so a
  *   missing required element errors and withholds, while unmodeled sibling elements do not
  *   false-reject). A resource with any structural error is **withheld** from the bundle and flagged
  *   {@link ISSUE_CODES.TRANSFORM_RESOURCE_INVALID} rather than shipped as silently-invalid FHIR. When
  *   the Patient is withheld, the Encounter's `subject` and any RelatedPerson are dropped rather than
- *   left dangling — references always resolve within the bundle.
+ *   left dangling: references always resolve within the bundle.
  *
  * @packageDocumentation
  */
@@ -639,8 +639,8 @@ interface TransformResult {
     readonly issues: readonly TransformIssue[];
 }
 /**
- * The ADT trigger events the IG ships a **message** map for. Other triggers still transform — from the
- * reusable segment maps — but are flagged {@link ISSUE_CODES.TRANSFORM_SEGMENT_ASSEMBLED}.
+ * The ADT trigger events the IG ships a **message** map for. Other triggers still transform, from the
+ * reusable segment maps, but are flagged {@link ISSUE_CODES.TRANSFORM_SEGMENT_ASSEMBLED}.
  */
 declare const IG_MAPPED_ADT_TRIGGERS: ReadonlySet<string>;
 /**
@@ -695,7 +695,7 @@ declare const IG_MAPPED_DOCUMENT_TRIGGERS: ReadonlySet<string>;
 declare function toFhir(msg: Hl7Message, opts?: TransformOptions): TransformResult;
 
 /**
- * PID → FHIR `Patient` — grounded on the IG **Segment PID to Patient** ConceptMap
+ * PID → FHIR `Patient`, grounded on the IG **Segment PID to Patient** ConceptMap
  * (`hl7.fhir.uv.v2mappings`, STU1). The field→element rows used here, verified firsthand against the
  * published map:
  *
@@ -709,8 +709,8 @@ declare function toFhir(msg: Hl7Message, opts?: TransformOptions): TransformResu
  *
  * Fail-safe throughout: each datatype conversion carries its own value-free issues, an unmapped
  * administrative-sex code leaves `gender` absent (never guessed), and a birth *time* (PID-7 with a
- * time-of-day) is dropped to `date` precision with a flag — the US Core `patient-birthTime` extension
- * is a profile concern this library does not cover. Deferred and flagged, not silently mapped:
+ * time-of-day) is dropped to `date` precision with a flag, because the US Core `patient-birthTime`
+ * extension is a profile concern this library does not cover. Deferred and flagged, not silently mapped:
  * PID-13/14 telecom (no XTN→ContactPoint converter), and PID-10/15/22/29/30 (US Core race/ethnicity
  * extensions, communication language, deceased).
  *
@@ -720,14 +720,14 @@ declare function toFhir(msg: Hl7Message, opts?: TransformOptions): TransformResu
 /**
  * HL7 v2 Table 0001 (Administrative Sex) → FHIR `administrative-gender`, exactly per the IG
  * **Table HL70001 to Administrative Gender** ConceptMap (every row "is equivalent to"). `A`
- * (Ambiguous) and `N` (Not applicable) both narrow to `other` — the map's stated equivalence, carried
+ * (Ambiguous) and `N` (Not applicable) both narrow to `other`: the map's stated equivalence, carried
  * as-is. A code absent here (the map defines no `unmapped` default) leaves `gender` absent and is
- * flagged {@link ISSUE_CODES.TRANSFORM_CODE_UNMAPPED} — never coerced to `unknown`.
+ * flagged {@link ISSUE_CODES.TRANSFORM_CODE_UNMAPPED}, never coerced to `unknown`.
  */
 declare const ADMINISTRATIVE_GENDER_MAP: Readonly<Record<string, string>>;
 
 /**
- * PV1 → FHIR `Encounter` — grounded on the IG **Segment PV1 to Encounter** ConceptMap plus the two
+ * PV1 → FHIR `Encounter`, grounded on the IG **Segment PV1 to Encounter** ConceptMap plus the two
  * **Table HL70004** ConceptMaps (to V3 ActCode, and to Encounter Status), all verified firsthand
  * against the published `hl7.fhir.uv.v2mappings` STU1 maps:
  *
@@ -761,13 +761,13 @@ declare const ENCOUNTER_CLASS_V3_MAP: Readonly<Record<string, {
 }>>;
 /**
  * HL7 v2 Table 0004 (Patient Class) → FHIR `Encounter.status`, per the IG **Table HL70004 to
- * Encounter Status** ConceptMap. Applied only when PV1-45 (discharge date) is *not* valued — a valued
+ * Encounter Status** ConceptMap. Applied only when PV1-45 (discharge date) is *not* valued: a valued
  * discharge sets `status = finished` per the PV1→Encounter map.
  */
 declare const ENCOUNTER_STATUS_MAP: Readonly<Record<string, string>>;
 
 /**
- * OBX → FHIR `Observation` — the highest-clinical-stakes segment map,
+ * OBX → FHIR `Observation`: the highest-clinical-stakes segment map,
  * grounded firsthand on the IG **Segment OBX to Observation** ConceptMap plus its two governing table
  * ConceptMaps (`hl7.fhir.uv.v2mappings`, STU1). The rows used here, verified against the published maps
  * (`ConceptMap-segment-obx-to-observation.html`, `-table-hl70078-to-v3-observationinterpretation.html`,
@@ -775,7 +775,7 @@ declare const ENCOUNTER_STATUS_MAP: Readonly<Record<string, string>>;
  *
  * | OBX field | FHIR target | via |
  * |---|---|---|
- * | OBX-2 Value Type | discriminates OBX-5 → `value[x]` | {@link buildValue} — never assume `Quantity` |
+ * | OBX-2 Value Type | discriminates OBX-5 → `value[x]` | {@link buildValue}, never assume `Quantity` |
  * | OBX-3 Observation Identifier (CWE) | `Observation.code` | {@link toFhirCodeableConcept} |
  * | OBX-5 Observation Value | `Observation.value[x]` | per OBX-2 |
  * | OBX-6 Units (CWE) | `valueQuantity.unit`/`.code`/`.system` | {@link quantityFromRawMagnitude} |
@@ -789,17 +789,17 @@ declare const ENCOUNTER_STATUS_MAP: Readonly<Record<string, string>>;
  *   `SN`→structured (`valueQuantity` with a comparator / `valueRange` / `valueRatio`), `ST`/`TX`/`FT`→
  *   `valueString`. A value type with no first-class target here (`NA`, `ED`, `DR`, `TM`, `NR`, unknown)
  *   preserves the raw value as `valueString` and flags {@link ISSUE_CODES.TRANSFORM_ELEMENT_DROPPED}
- *   (the richer FHIR type is deferred) — never a fabricated `Quantity`.
+ *   (the richer FHIR type is deferred), never a fabricated `Quantity`.
  * - **A corrected/cancelled result never emits as `final`.** OBX-11 `C`→`corrected`, `X`→`cancelled`,
  *   `D`/`W`→`entered-in-error` (HL70085). A status code with **no** HL70085 target leaves
  *   `Observation.status` absent (flagged {@link ISSUE_CODES.TRANSFORM_CODE_UNMAPPED}); the required-`status`
- *   emit gate then **withholds** the Observation rather than shipping it — never coerced to `final`.
+ *   emit gate then **withholds** the Observation rather than shipping it, never coerced to `final`.
  * - **An unrecognized abnormal flag is surfaced, never coerced to normal.** Each OBX-8 flag in
  *   {@link HL70078_INTERPRETATION_CODES} becomes an `interpretation` coding (the map is code-preserving);
  *   a flag absent from the table is flagged and dropped, never emitted as `N`/normal.
  *
- * Numeric magnitudes (NM, SN) are read from the **raw OBX-5 field** — not the `@cosyte/hl7`
- * `Observation` view's JS `number` — so a reported lab value's exact lexical precision (`120.50`) is
+ * Numeric magnitudes (NM, SN) are read from the **raw OBX-5 field**, not the `@cosyte/hl7`
+ * `Observation` view's JS `number`, so a reported lab value's exact lexical precision (`120.50`) is
  * carried through the string-backed FHIR `decimal`, never routed through a lossy `number`.
  *
  * @packageDocumentation
@@ -809,7 +809,7 @@ declare const ENCOUNTER_STATUS_MAP: Readonly<Record<string, string>>;
  * HL7 v2 Table 0078 (Abnormal Flags) → FHIR v3 ObservationInterpretation (`Observation.interpretation`),
  * per the IG **Table HL70078 to v3 ObservationInterpretation** ConceptMap. Every mapped row is
  * `is equivalent to` an **identically-spelled** v3 code (the map is code-preserving), so this is the set
- * of codes that carry a target — a flag **absent** from this set has no equivalent and is flagged
+ * of codes that carry a target: a flag **absent** from this set has no equivalent and is flagged
  * {@link ISSUE_CODES.TRANSFORM_CODE_UNMAPPED}, never coerced (the IG leaves `AC`/`HM`/`OBX`/`QCF`/`TOX`
  * and any local flag unmapped, and declares no `unmapped` default).
  */
@@ -818,14 +818,14 @@ declare const HL70078_INTERPRETATION_CODES: ReadonlySet<string>;
  * HL7 v2 Table 0085 (Observation Result Status) → FHIR `observation-status` (`Observation.status`),
  * per the IG **Table HL70085 to Observation Status** ConceptMap (each `is equivalent to`). Only these
  * seven source codes carry a target; the codes the IG leaves unmapped (`B`, `I`, `N`, `O`, `R`, `S`,
- * `U`, `V`) are **absent here on purpose** — an OBX-11 with one of them (or any local code) leaves
+ * `U`, `V`) are **absent here on purpose**: an OBX-11 with one of them (or any local code) leaves
  * `Observation.status` absent + flagged, and the required-`status` emit gate withholds the Observation.
  * **`C`→`corrected` and `X`→`cancelled` guarantee a corrected/cancelled result never emits as `final`.**
  */
 declare const OBSERVATION_STATUS_MAP: Readonly<Record<string, string>>;
 
 /**
- * OBR → FHIR `DiagnosticReport` — the ORU results-report anchor, grounded firsthand
+ * OBR → FHIR `DiagnosticReport`, the ORU results-report anchor, grounded firsthand
  * on the IG **Segment OBR to DiagnosticReport** ConceptMap and its **Table HL70123 to Diagnostic Report
  * Status** ConceptMap (`hl7.fhir.uv.v2mappings`, STU1;
  * `ConceptMap-segment-obr-to-diagnosticreport.html`,
@@ -837,15 +837,15 @@ declare const OBSERVATION_STATUS_MAP: Readonly<Record<string, string>>;
  * | OBR-3 Filler Order Number | `identifier` (type `FILL`) | EI.1 → `Identifier.value`, v2-0203 type |
  * | OBR-4 Universal Service Identifier (CWE) | `DiagnosticReport.code` | {@link toFhirCodeableConcept} |
  * | OBR-7 Observation Date/Time | `effectiveDateTime` / `effectivePeriod.start` | {@link toFhirDateTime} |
- * | OBR-8 Observation End Date/Time | `effectivePeriod.end` (start moves to the period when valued) | — |
+ * | OBR-8 Observation End Date/Time | `effectivePeriod.end` (start moves to the period when valued) | {@link toFhirDateTime} |
  * | OBR-22 Results Rpt/Status Chng Date/Time | `DiagnosticReport.issued` (an `instant`) | {@link toFhirDateTime} |
  * | OBR-24 Diagnostic Serv Sect ID | `DiagnosticReport.category` | v2-0074 coding |
  * | OBR-25 Result Status | `DiagnosticReport.status` | {@link DIAGNOSTIC_REPORT_STATUS_MAP} (HL70123) |
  * | (OBX children) | `DiagnosticReport.result` | reference wiring from the assembler |
  *
  * **Fail-safes.** `DiagnosticReport.status` is required (R4 1..1) and the IG itself notes an unvalued
- * OBR-25 is an error; so an absent OBR-25 — or an OBR-25 code the HL70123 map does not carry (`A`, `M`,
- * `N`, `Y`, `Z`) — leaves `status` absent + flagged {@link ISSUE_CODES.TRANSFORM_CODE_UNMAPPED}, and the
+ * OBR-25 is an error; so an absent OBR-25, or an OBR-25 code the HL70123 map does not carry (`A`, `M`,
+ * `N`, `Y`, `Z`), leaves `status` absent + flagged {@link ISSUE_CODES.TRANSFORM_CODE_UNMAPPED}, and the
  * required-`status` emit gate withholds the report rather than emitting an invalid one or guessing
  * `final`. `OBR-25 = C`→`corrected` / `X`→`cancelled` are modelled exactly. OBR-22 becomes `issued`
  * only when it is a fully-zoned instant; a date-only/naked OBR-22 is dropped + flagged (never a
@@ -859,7 +859,7 @@ declare const OBSERVATION_STATUS_MAP: Readonly<Record<string, string>>;
  * HL7 v2 Table 0123 (Result Status) → FHIR `diagnostic-report-status` (`DiagnosticReport.status`), per
  * the IG **Table HL70123 [Queries] to Diagnostic Report Status** ConceptMap (each `is equivalent to`).
  * Only these **eight** source codes carry a target; the IG leaves `A`, `M`, `N`, `Y`, `Z` unmapped
- * (verified firsthand against the published v1.0.0 ConceptMap — `N` "Procedure completed, results
+ * (verified firsthand against the published v1.0.0 ConceptMap: `N` "Procedure completed, results
  * pending" is in the `(not mapped)` group, and the map declares no `unmapped` default), so an OBR-25
  * with one of them leaves `status` absent + flagged and the report is withheld. In particular a
  * results-**pending** `N` is **never** emitted as the post-final `appended`. **`C`→`corrected` and
@@ -868,7 +868,7 @@ declare const OBSERVATION_STATUS_MAP: Readonly<Record<string, string>>;
 declare const DIAGNOSTIC_REPORT_STATUS_MAP: Readonly<Record<string, string>>;
 
 /**
- * ORC + OBR → FHIR `ServiceRequest` — the order-entry request, grounded firsthand
+ * ORC + OBR → FHIR `ServiceRequest`: the order-entry request, grounded firsthand
  * on the IG **Segment ORC to ServiceRequest** and **Segment OBR to ServiceRequest** ConceptMaps and
  * the **Table HL70119 to Request Status** ConceptMap (`hl7.fhir.uv.v2mappings`, STU1;
  * `ConceptMap-segment-orc-to-servicerequest.html`, `ConceptMap-segment-obr-to-servicerequest.html`,
@@ -894,26 +894,26 @@ declare const DIAGNOSTIC_REPORT_STATUS_MAP: Readonly<Record<string, string>>;
  *   {@link REQUEST_STATUS_MAP}; the many codes the IG leaves in its `(unmapped)` group (CH, CP, PA,
  *   RE, RF, RP, SC, the U* "unable to …" family, …) have **no** target and leave `status` absent +
  *   flagged {@link ISSUE_CODES.TRANSFORM_CODE_UNMAPPED}. When **ORC-5** (Order Status) is valued the
- *   IG routes status through ORC-5 via an *unspecified* mapping (no code table) — so we cannot derive
+ *   IG routes status through ORC-5 via an *unspecified* mapping (no code table), so we cannot derive
  *   it, flag ORC-5 unmapped, and leave `status` absent rather than mis-applying the ORC-1 table
- *   against the IG's own condition. The required-`status` emit gate then **withholds** the request —
+ *   against the IG's own condition. The required-`status` emit gate then **withholds** the request,
  *   never guessed, never coerced.
  * - **`intent` (required 1..1) = `order`.** The IG maps ORC-1/OBR → `intent` as `equivalent` but ships
  *   **no value ConceptMap** for it; the ORM_O01/OML_O21 families are, by definition, *order* messages
  *   (their message maps create a `ServiceRequest`/`MedicationRequest` per order), so `intent` is fixed
  *   to the `request-intent` code `order` from that message context. This is a resource-level constant
- *   grounded in the message family — **not** a fabricated per-code translation row. The finer
+ *   grounded in the message family, **not** a fabricated per-code translation row. The finer
  *   OBR-11-conditioned intent refinement is deferred.
  * - **`subject` (required 1..1).** Wired to the bundle's Patient; a request with no resolvable Patient
  *   is withheld rather than emitted with a dangling/absent subject.
  *
- * - **`priority` (0..1) — value-translated.** OBR-5 → `ServiceRequest.priority` via the IG
+ * - **`priority` (0..1), value-translated.** OBR-5 → `ServiceRequest.priority` via the IG
  *   **Table HL70485 to Request Priority** ConceptMap ({@link SERVICE_REQUEST_PRIORITY_MAP}): only
  *   `S→stat`, `A→asap`, `R→routine` carry a target (each `equivalent`, and all three are valid
- *   `request-priority` members). Every other v2-0485 code — `P`, `C`, `T`, the `T{S,M,H,D,W,L}<integer>`
- *   timing-critical family, `PRN` — sits in the IG map's `(unmapped)` group, so a valued OBR-5 the map
+ *   `request-priority` members). Every other v2-0485 code (`P`, `C`, `T`, the
+ *   `T{S,M,H,D,W,L}<integer>` timing-critical family, `PRN`) sits in the IG map's `(unmapped)` group, so a valued OBR-5 the map
  *   has no target for leaves `priority` absent + flagged {@link ISSUE_CODES.TRANSFORM_CODE_UNMAPPED},
- *   never guessed. (`priority` is 0..1, so an unmapped value simply omits it — the request still emits.)
+ *   never guessed. (`priority` is 0..1, so an unmapped value simply omits it: the request still emits.)
  *
  * Deferred and flagged elsewhere, not silently mapped: ORC-7/OBR-27 timing (`$this`), ORC-12/OBR-16
  * requester + ORC-21..24 ordering facility/provider (need Practitioner/PractitionerRole/Organization
@@ -927,7 +927,7 @@ declare const DIAGNOSTIC_REPORT_STATUS_MAP: Readonly<Record<string, string>>;
  * HL7 v2 Table 0119 (Order Control Codes) → FHIR `request-status` (`ServiceRequest.status`), per the
  * IG **Table HL70119 to Request Status** ConceptMap (each `is equivalent to`). Only these **19** source
  * codes carry a target; every other v2-0119 code sits in the IG's explicit `(unmapped)` group
- * (verified firsthand against the published v1.0.0 ConceptMap — CH/CN/CP/DE/LI/NA/OE/OF/OP/OR/PA/RE/
+ * (verified firsthand against the published v1.0.0 ConceptMap: CH/CN/CP/DE/LI/NA/OE/OF/OP/OR/PA/RE/
  * RF/RP/RR/RU/SC/SN/SR/SS/UA/UC/UD/UF/UH/UM/UN/UR/UX/XO/XR/XX/MC are all `unmatched`, and the map
  * declares no `unmapped` default), so an ORC-1 with one of them leaves `status` absent + flagged and
  * the request is withheld. `request-status` has no `cancelled`; the cancel/discontinue codes map to
@@ -938,15 +938,15 @@ declare const REQUEST_STATUS_MAP: Readonly<Record<string, string>>;
  * HL7 v2 Table 0485 (Extended Priority Codes) → FHIR `request-priority` (`ServiceRequest.priority`),
  * per the IG **Table HL70485 to Request Priority** ConceptMap (each `is equivalent to`; verified
  * firsthand against the published v1.0.0 ConceptMap). Only these **three** source codes carry a
- * target; every other v2-0485 code — `P` (Preop), `C` (Callback), `T` (Timing critical), the
- * `T{S,M,H,D,W,L}<integer>` timing-critical family, and `PRN` (As needed) — sits in the IG's
+ * target; every other v2-0485 code, namely `P` (Preop), `C` (Callback), `T` (Timing critical), the
+ * `T{S,M,H,D,W,L}<integer>` timing-critical family, and `PRN` (As needed), sits in the IG's
  * `(unmapped)` group with no target, so an OBR-5 carrying one leaves `priority` absent + flagged.
  * All three targets (`stat`/`asap`/`routine`) are valid `request-priority` members.
  */
 declare const SERVICE_REQUEST_PRIORITY_MAP: Readonly<Record<string, string>>;
 
 /**
- * VXU_V04 → FHIR `Immunization` — the thin IG single for immunization administration,
+ * VXU_V04 → FHIR `Immunization`: the thin IG single for immunization administration,
  * grounded firsthand on the IG **VXU_V04 message map** and the **RXA/RXR/ORC → Immunization**
  * segment maps (`hl7.fhir.uv.v2mappings`, STU1; `ConceptMap-message-vxu-v04-to-bundle.json`,
  * `ConceptMap-segment-rxa-to-immunization.json`, `ConceptMap-segment-rxr-to-immunization.json`,
@@ -957,7 +957,7 @@ declare const SERVICE_REQUEST_PRIORITY_MAP: Readonly<Record<string, string>>;
  *
  * | v2 field | FHIR target | via |
  * |---|---|---|
- * | RXA-5 Administered Code (CE) | `vaccineCode` (required 1..1) | {@link toFhirCodeableConcept} (structural — no IG value map) |
+ * | RXA-5 Administered Code (CE) | `vaccineCode` (required 1..1) | {@link toFhirCodeableConcept} (structural, no IG value map) |
  * | RXA-3 Date/Time Start of Administration (DTM) | `occurrenceDateTime` (required, occurrence[x]) | {@link toFhirDateTime} |
  * | RXA-20 Completion Status + RXA-21 Action Code | `status` (required 1..1) | {@link buildStatus} (HL70322 + IG assignments) |
  * | RXA-6 Administered Amount + RXA-7 Units | `doseQuantity` | {@link quantityFromRawMagnitude} |
@@ -980,18 +980,18 @@ declare const SERVICE_REQUEST_PRIORITY_MAP: Readonly<Record<string, string>>;
  *   event-status ConceptMap, whose targets `completed`/`not-done` are all valid `immunization-status`
  *   members). A **valued** RXA-20 the HL70322 map has no target for is flagged
  *   {@link ISSUE_CODES.TRANSFORM_CODE_UNMAPPED}, `status` left absent, and the required-`status` emit gate
- *   **withholds** the Immunization — never guessed, never coerced.
+ *   **withholds** the Immunization, never guessed, never coerced.
  * - **`vaccineCode` (required 1..1) + `occurrence[x]` (required 1..1) + `patient` (required 1..1).** An
  *   absent RXA-5, RXA-3, or bundle Patient leaves the resource missing a required element, so it is
  *   withheld by the emit gate rather than emitted incomplete.
  * - **Dose.** RXA-6/RXA-7 → `doseQuantity` via {@link quantityFromRawMagnitude}: precision-exact magnitude,
- *   non-UCUM unit preserved verbatim with `.code`/`.system` absent + flagged — never a fabricated UCUM code.
+ *   non-UCUM unit preserved verbatim with `.code`/`.system` absent + flagged, never a fabricated UCUM code.
  * - **Route/site value translation.** RXR-1 route → {@link ROUTE_VALUE_MAP} (HL70162) and
  *   RXR-2 site → {@link SITE_VALUE_MAP} (HL70550) are value-translated additively (derived target coding
  *   added, raw coding preserved); a code outside the table is preserved + flagged, never coerced.
- * - **`vaccineCode` is NOT value-translated — by grounding, not omission.** RXA-5 has **no** `mappedVia`
+ * - **`vaccineCode` is NOT value-translated: by grounding, not omission.** RXA-5 has **no** `mappedVia`
  *   value ConceptMap in the IG's RXA→Immunization segment map (verified firsthand), so the code (typically
- *   CVX) is carried **structurally** (system recognized, value preserved) — a translation is never
+ *   CVX) is carried **structurally** (system recognized, value preserved): a translation is never
  *   invented for it.
  *
  * Deferred and flagged elsewhere, not silently mapped: RXA-10 performer, RXA-17 manufacturer, RXA-27/28
@@ -1014,7 +1014,7 @@ declare const SERVICE_REQUEST_PRIORITY_MAP: Readonly<Record<string, string>>;
 declare const IMMUNIZATION_STATUS_MAP: Readonly<Record<string, string>>;
 
 /**
- * SIU_S12 → FHIR `Appointment` — the thin IG single for scheduling, grounded
+ * SIU_S12 → FHIR `Appointment`: the thin IG single for scheduling, grounded
  * firsthand on the IG **SIU_S12 message map**, the **SCH/AIS/PID → Appointment** segment maps, the
  * **Table HL70278 → AppointmentStatus** ConceptMap, and the **TQ → Appointment** datatype map
  * (`hl7.fhir.uv.v2mappings`, STU1; `ConceptMap-message-siu-s12-to-bundle.json`,
@@ -1028,7 +1028,7 @@ declare const IMMUNIZATION_STATUS_MAP: Readonly<Record<string, string>>;
  * |---|---|---|
  * | SCH-25 Filler Status Code | `status` (required 1..1) | {@link APPOINTMENT_STATUS_MAP} (HL70278) |
  * | SCH-1 Placer / SCH-2 Filler Appointment ID | `identifier` | EI.1 → `Identifier.value` |
- * | SCH-7 Appointment Reason (CWE) | `reasonCode` | {@link toFhirCodeableConcept} (structural — SNOMED target, BYO) |
+ * | SCH-7 Appointment Reason (CWE) | `reasonCode` | {@link toFhirCodeableConcept} (structural: SNOMED target, BYO) |
  * | SCH-8 Appointment Type (CWE) | `appointmentType` | {@link APPOINTMENT_TYPE_VALUE_MAP} (HL70277, value-translated) |
  * | SCH-9 Duration + SCH-10 Units | `minutesDuration` | integer, only when SCH-10 is minutes |
  * | SCH-11 Appointment Timing Quantity (TQ) | `start` / `end` (instant) | TQ.4/TQ.5 → {@link toFhirDateTime} |
@@ -1039,11 +1039,11 @@ declare const IMMUNIZATION_STATUS_MAP: Readonly<Record<string, string>>;
  * - **`status` (required 1..1).** SCH-25 → {@link APPOINTMENT_STATUS_MAP} (HL70278). The three HL70278
  *   codes the IG leaves unmatched (`Discontinued`, `Blocked`, `Overbook`) and an absent SCH-25 leave
  *   `status` absent + flagged {@link ISSUE_CODES.TRANSFORM_CODE_UNMAPPED}; the required-`status` emit gate
- *   then **withholds** the Appointment — never guessed.
+ *   then **withholds** the Appointment, never guessed.
  * - **`participant` (required 1..*).** The bundle Patient is emitted as the required participant. Its
  *   `participant.status` (a required-bound `code` the IG supplies no source for) is emitted as a
- *   `data-absent-reason` primitive (value `unknown`) + flagged {@link ISSUE_CODES.TRANSFORM_REQUIRED_ELEMENT_UNKNOWN}
- *   — the spec-clean way to satisfy a required code whose value is genuinely unknown, never fabricated. An
+ *   `data-absent-reason` primitive (value `unknown`) + flagged {@link ISSUE_CODES.TRANSFORM_REQUIRED_ELEMENT_UNKNOWN},
+ *   the spec-clean way to satisfy a required code whose value is genuinely unknown, never fabricated. An
  *   Appointment with no resolvable Patient (and no other groundable actor this library builds) has no
  *   participant and is withheld.
  * - **`start`/`end` (instant).** SCH-11's TQ.4/TQ.5 become `start`/`end` only when they are fully-zoned
@@ -1052,10 +1052,10 @@ declare const IMMUNIZATION_STATUS_MAP: Readonly<Record<string, string>>;
  * - **`appointmentType` value translation.** SCH-8 → {@link APPOINTMENT_TYPE_VALUE_MAP}
  *   (HL70277 `Normal`/`Tentative`/`Complete` identity into `v2-0277`); a code outside the table is
  *   preserved + flagged, never coerced. **`reasonCode` is NOT value-translated:** SCH-7's IG map target
- *   is SNOMED CT (`table-hl70276-to-sct`) — encumbered, **not bundled** — so the reason is carried
+ *   is SNOMED CT (`table-hl70276-to-sct`), which is encumbered and **not bundled**, so the reason is carried
  *   structurally (BYO ConceptMap), never SNOMED-translated here. (The IG's SCH→Appointment map *also*
  *   carries a redundant SCH-7 → `appointmentType[1]` row via `table-hl70277-to-v2-0277`; it is not
- *   applied — SCH-7 carries HL70276 *reason* codes, not HL70277 *type* codes, so translating them through
+ *   applied: SCH-7 carries HL70276 *reason* codes, not HL70277 *type* codes, so translating them through
  *   the type table would only ever produce spurious unmapped flags. `appointmentType` comes from SCH-8,
  *   the appointment-*type* field, per that same map's SCH-8 → `appointmentType[1]` row.)
  *
@@ -1068,7 +1068,7 @@ declare const IMMUNIZATION_STATUS_MAP: Readonly<Record<string, string>>;
 /**
  * HL7 v2 Table 0278 (Filler Status Code) → FHIR `appointmentstatus` (`Appointment.status`), per the IG
  * **Table HL70278 to AppointmentStatus** ConceptMap (each `is equivalent to`). The three source codes
- * the IG leaves **unmatched** (`Discontinued`, `Blocked`, `Overbook`) are absent here on purpose — an
+ * the IG leaves **unmatched** (`Discontinued`, `Blocked`, `Overbook`) are absent here on purpose: an
  * SCH-25 carrying one of them (or any local code) leaves `Appointment.status` absent + flagged and the
  * required-`status` emit gate withholds the Appointment.
  */
@@ -1077,29 +1077,29 @@ declare const APPOINTMENT_STATUS_MAP: Readonly<Record<string, string>>;
 /**
  * The `$translate`-shaped ConceptMap-application engine + the **license-clean** v2-table → FHIR
  * value maps it applies. This is the layer that value-**translates** a coded v2
- * field — not merely carrying its code structurally, but mapping the source table code to the FHIR
+ * field, not merely carrying its code structurally, but mapping the source table code to the FHIR
  * target coding the IG's segment-map `mappedVia` ConceptMap prescribes.
  *
- * **Grounded firsthand on the raw published IG ConceptMaps** (`hl7.fhir.uv.v2mappings`, STU1 —
+ * **Grounded firsthand on the raw published IG ConceptMaps** (`hl7.fhir.uv.v2mappings`, STU1;
  * `ConceptMap-table-*.json`). Each shipped map below cites the exact IG ConceptMap it transcribes and
  * was verified against that resource's JSON (its `group.element[].target[]` rows and its `unmatched`
  * `(unmapped)` group). The engine is **fail-safe by refusal**: a source code the IG map has **no
- * target** for (its `(unmapped)` group) is never coerced to a plausible neighbor — the caller flags it
+ * target** for (its `(unmapped)` group) is never coerced to a plausible neighbor. The caller flags it
  * and preserves the raw coding, or withholds the value, but a target is **never fabricated**.
  *
  * **License posture.** Only maps whose target CodeSystem is **freely redistributable** are
  * shipped here: the HL7 THO v2 tables (`v2-0162`, `v2-0550`, `v2-0277`, `v2-0161`) and HL7 v3
- * (`v3-RouteOfAdministration`) are HL7's own, license-clean. The IG's `*-to-sct` value maps —
- * **RXR-4 method** (`table-hl70165-to-sct`) and **SCH-7 reason** (`table-hl70276-to-sct`) — translate
+ * (`v3-RouteOfAdministration`) are HL7's own, license-clean. The IG's `*-to-sct` value maps,
+ * **RXR-4 method** (`table-hl70165-to-sct`) and **SCH-7 reason** (`table-hl70276-to-sct`), translate
  * **into SNOMED CT**, which is **license-encumbered and is NOT bundled**; those fields stay
  * structurally carried (BYO ConceptMap), never value-translated here (see their message modules).
  *
  * **Additive, never mutating.** A successful translation preserves the raw source coding
  * (its code, display, version, and any `CWE.4/5/6` alternate triplet) and *adds* the derived target
- * coding — recognition never overwrites or discards what the message said; it augments it with the
+ * coding: recognition never overwrites or discards what the message said; it augments it with the
  * IG-mapped equivalent. And it only fires when the field's primary coding is genuinely from the map's
  * **bound source table** (CWE.3 absent, or naming that table): a field that declares a *foreign*
- * coding system (a local `99…`, SNOMED, …) is carried structurally and flagged — its code is **never**
+ * coding system (a local `99…`, SNOMED, …) is carried structurally and flagged, and its code is **never**
  * asserted to be the standard concept just because the string happens to collide with a table code.
  *
  * @packageDocumentation
@@ -1135,11 +1135,11 @@ interface CodedValueMap {
     /** The source table's canonical CodeSystem URI (what the raw v2 code is a member of when mapped). */
     readonly sourceSystem: string;
     /**
-     * The CWE.3 (`nameOfCodingSystem`) mnemonics that denote this map's **bound source table** — the
+     * The CWE.3 (`nameOfCodingSystem`) mnemonics that denote this map's **bound source table**: the
      * HL7 forms (`"HL70162"`, `"0162"`, …). Translation applies **only** when the field's primary
      * coding is from the bound table: CWE.3 absent/empty (a positionally-bound bare code) **or** CWE.3 ∈
      * this set. A CWE that declares a **different** coding system (a local `99…`, or SNOMED) is not a
-     * source-table code, so the map is not applied to it — the raw coding is carried structurally + its
+     * source-table code, so the map is not applied to it: the raw coding is carried structurally + its
      * system flagged, never asserted as the standard concept.
      */
     readonly sourceMnemonics: ReadonlySet<string>;
@@ -1147,7 +1147,7 @@ interface CodedValueMap {
     readonly translate: (code: string) => CodedTarget | undefined;
 }
 /**
- * **RXR-1 Route** — IG `ConceptMap/table-hl70162-to-v2-0162`. Two IG groups, transcribed verbatim:
+ * **RXR-1 Route**: IG `ConceptMap/table-hl70162-to-v2-0162`. Two IG groups, transcribed verbatim:
  * a 41-code **identity** group (source `v2-0162` → target `v2-0162`, each `equivalent`) and a 6-code
  * **remap** group into `v3-RouteOfAdministration` (`ID→IDINJ`, `IM→IM`, `IV→IVINJ`, `PO→PO`, `SC→SQ`,
  * `TD→TRNSDERM`, each `equivalent`, with the IG target displays). The two source-code sets are
@@ -1156,22 +1156,22 @@ interface CodedValueMap {
  */
 declare const ROUTE_VALUE_MAP: CodedValueMap;
 /**
- * **RXR-2 Administration Site** — IG `ConceptMap/table-hl70550-to-v2-0550`. A single **identity**
+ * **RXR-2 Administration Site**: IG `ConceptMap/table-hl70550-to-v2-0550`. A single **identity**
  * group of 443 body-part codes (source `v2-0550` → target `v2-0550`, each `equivalent`), transcribed
- * verbatim from the published STU1 ConceptMap — **including** its as-published data-quality artifacts
+ * verbatim from the published STU1 ConceptMap, **including** its as-published data-quality artifacts
  * (`CHESTÂ`, a lone `Â`, `KIDNÂ`, where a stray U+00C2 leaked from the IG's source
  * encoding). They are preserved for source-fidelity; they are inert (a clean `CHEST`/`KIDN` simply
  * falls through to unmapped). A code not in the table is unmapped → raw coding preserved + flagged.
  */
 declare const SITE_VALUE_MAP: CodedValueMap;
 /**
- * **SCH-8 Appointment Type** — IG `ConceptMap/table-hl70277-to-v2-0277`. A single **identity** group
+ * **SCH-8 Appointment Type**: IG `ConceptMap/table-hl70277-to-v2-0277`. A single **identity** group
  * of the three v2-0277 codes (`Normal`, `Tentative`, `Complete` → themselves, each `equivalent`,
  * source and target both `v2-0277`). Any other code is unmapped → raw coding preserved + flagged.
  */
 declare const APPOINTMENT_TYPE_VALUE_MAP: CodedValueMap;
 /**
- * **RXO-9 Allow Substitutions** — IG `ConceptMap/table-hl70161-to-v2-0161`. A single **identity**
+ * **RXO-9 Allow Substitutions**: IG `ConceptMap/table-hl70161-to-v2-0161`. A single **identity**
  * group of the three v2-0161 codes (`N` NOT authorized, `G` generic, `T` therapeutic → themselves,
  * each `equivalent`, source and target both `v2-0161`), the target for
  * `MedicationRequest.substitution.allowedCodeableConcept`. Any other code is unmapped → the
@@ -1180,7 +1180,7 @@ declare const APPOINTMENT_TYPE_VALUE_MAP: CodedValueMap;
 declare const SUBSTITUTION_VALUE_MAP: CodedValueMap;
 /**
  * The bound-table target for a coded element's **primary** coding, or `undefined` when the map does
- * not faithfully apply — i.e. the primary declares a coding system that is **not** this map's bound
+ * not faithfully apply, i.e. the primary declares a coding system that is **not** this map's bound
  * table (CWE.3 present and not in {@link CodedValueMap.sourceMnemonics}), the primary code is empty, or
  * the code is in the IG map's `(unmapped)` group. Never asserts a standard translation for a foreign
  * coding system, and never fabricates a target.
@@ -1196,7 +1196,7 @@ declare const SUBSTITUTION_VALUE_MAP: CodedValueMap;
  */
 declare function translateBound(cwe: CodedElement, map: CodedValueMap): CodedTarget | undefined;
 /**
- * Build a FHIR `CodeableConcept` node for a {@link CodedTarget} — the single translated coding, with
+ * Build a FHIR `CodeableConcept` node for a {@link CodedTarget}: the single translated coding, with
  * an optional free-`text`. Used by translate-or-withhold callers (e.g. substitution) that build the
  * CodeableConcept only on a successful translation.
  *
@@ -1212,16 +1212,16 @@ declare function translateBound(cwe: CodedElement, map: CodedValueMap): CodedTar
 declare function codeableConceptFromTarget(target: CodedTarget, text?: string): FhirComplex;
 /**
  * Value-translate a coded v2 element to a FHIR `CodeableConcept` **via** a license-clean
- * {@link CodedValueMap}, **additively** and fail-safe — never mutating or discarding what the message
+ * {@link CodedValueMap}, **additively** and fail-safe, never mutating or discarding what the message
  * said:
  *
- * - **Primary code recognized as a bound-table code** ({@link translateBound} — CWE.3 absent or names
+ * - **Primary code recognized as a bound-table code** ({@link translateBound}: CWE.3 absent or names
  *   the bound table, and the code is in the IG map's mapped group) → the **primary** coding is emitted
  *   in the recognized source-table system (`map.sourceSystem`, carrying `CWE.7` version) and the
  *   **derived** target coding is *appended* when it differs (a remap such as `SC→SQ`); the **alternate
  *   triplet** (`CWE.4/5/6`, via {@link buildCoding}, with its own system resolution + flags) and the
- *   original `CWE.9` text are preserved. No primary unmapped flag — the value was faithfully recognized.
- * - **Otherwise** — the primary declares a **foreign** coding system (not the bound table), the code is
+ *   original `CWE.9` text are preserved. No primary unmapped flag: the value was faithfully recognized.
+ * - **Otherwise**: the primary declares a **foreign** coding system (not the bound table), the code is
  *   empty, or it is in the IG's `(unmapped)` group → this defers entirely to the **structural**
  *   {@link toFhirCodeableConcept}, which preserves the raw coding (and its `CWE.4/5/6` alternate and
  *   `CWE.7` version) and flags it ({@link ISSUE_CODES.TRANSFORM_CODE_UNMAPPED} /
@@ -1243,21 +1243,21 @@ declare function codeableConceptFromTarget(target: CodedTarget, text?: string):
 declare function toFhirCodeableConceptVia(cwe: CodedElement, map: CodedValueMap, ctx?: TransformContext): ConvertResult<FhirComplex>;
 
 /**
- * Public entry point for `@cosyte/transform` — the HL7 v2 → FHIR R4 transformation library.
+ * Public entry point for `@cosyte/transform`: the HL7 v2 → FHIR R4 transformation library.
  *
  * `@cosyte/transform` is **not** a parser; it is a **consumer** one tier above the parser suite. It
  * takes already-parsed `@cosyte/hl7` composites and produces validated `@cosyte/fhir` model nodes,
  * grounded on the official **HL7 Version 2 to FHIR** Implementation Guide (`hl7.fhir.uv.v2mappings`,
  * STU Edition 1). Its whole promise is narrow and honest: **IG-grounded, fail-safe transformation
- * with typed, value-free diagnostics — never a confident wrong FHIR value.**
+ * with typed, value-free diagnostics, never a confident wrong FHIR value.**
  *
  * This module ships the six safety-critical datatype converters, the immutable
  * `OperationOutcome`-shaped diagnostic channel and the NamingSystem resolver they consult,
- * the message-level assembly — HL7 v2 **ADT → FHIR Patient + Encounter**, the
+ * the message-level assembly (HL7 v2 **ADT → FHIR Patient + Encounter**, the
  * **ORU^R01 → DiagnosticReport + Observation** results graph, the order-entry graph
  * (**ORM_O01 / OML_O21 → ServiceRequest** and **RXO → MedicationRequest**), and the thin IG
  * singles (**VXU_V04 → Immunization**, **SIU_S12 → Appointment**, **MDM_T02 → DocumentReference**),
- * all through `toFhir(msg)` — and the **terminology value-translation** layer: a
+ * all through `toFhir(msg)`), and the **terminology value-translation** layer: a
  * `$translate`-shaped {@link toFhirCodeableConceptVia} engine applying the license-clean IG value
  * ConceptMaps to the previously structural-only coded fields (route/site, appointment type, order
  * priority, substitution). Terminology **depth beyond these maps**, profiles, and the reverse