@cosyte/transform 0.0.9 → 0.1.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { FhirComplex } from '@cosyte/fhir';
-import { HD, TS, CX, CWE, XPN, XAD, NM, Hl7Message } from '@cosyte/hl7';
+import { FhirComplex, FhirNode } from '@cosyte/fhir';
+import { HD, TS, CX, CWE, XPN, XAD, NM, Hl7Message, Segment, Field, BuildMessageInit } from '@cosyte/hl7';
 
 /**
  * The stable code registries for the `@cosyte/transform` diagnostic channel.
@@ -17,6 +17,16 @@ import { HD, TS, CX, CWE, XPN, XAD, NM, Hl7Message } from '@cosyte/hl7';
  *   entry points. **Nothing in this library throws one today**: the datatype converters and
  *   `toFhir` alike fail safe to a value-free issue instead.
  *
+ * **The line between the two registries is structural, and it decides where a new code goes.** A
+ * `FatalCode` is the type carried by a *thrown* error; a `TransformIssue.code` is typed `IssueCode`
+ * and {@link ISSUE_REGISTRY} is exhaustive over {@link ISSUE_CODES} alone. So a condition that is
+ * *returned* on the non-throwing `{ value, issues }` channel is an {@link ISSUE_CODES} entry by
+ * construction, however severe it is: the missing-trigger refusal on the reverse
+ * (FHIR to v2) entry points is returned, never thrown, so it is
+ * {@link ISSUE_CODES.TRANSFORM_MISSING_TRIGGER} rather than a fatal code. Adding it to
+ * {@link FATAL_CODES} instead would have required widening `TransformIssue.code` to
+ * `IssueCode | FatalCode` and blurring exactly that split.
+ *
  * @packageDocumentation
  */
 /**
@@ -80,6 +90,62 @@ declare const ISSUE_CODES: {
      * 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 reverse (FHIR to v2) conversion was called without the explicit message trigger it requires.
+     * No FHIR resource carries a v2 trigger, so it is never inferred from resource content and never
+     * defaulted: no message is built and no builder is called. */
+    readonly TRANSFORM_MISSING_TRIGGER: "TRANSFORM_MISSING_TRIGGER";
+    /** A reverse (FHIR to v2) conversion was handed a resource outside the narrow set of shapes it
+     * supports. No v2 message is emitted and no segment layout is guessed. */
+    readonly TRANSFORM_UNSUPPORTED_RESOURCE: "TRANSFORM_UNSUPPORTED_RESOURCE";
+    /** A resource handed to a reverse (FHIR to v2) conversion is not structurally a FHIR resource of
+     * its expected type (not an object, no `resourceType`, or an element carrying the wrong node
+     * kind). Nothing is emitted and nothing is thrown. */
+    readonly TRANSFORM_RESOURCE_MALFORMED: "TRANSFORM_RESOURCE_MALFORMED";
+    /** A populated FHIR element has no v2 field in the narrow reverse map that covers this shape
+     * (the IG map defines no source for it, or its inverse is not implemented here). The element is
+     * surfaced and left out, never approximated into a neighbouring v2 field. */
+    readonly TRANSFORM_NO_V2_TARGET: "TRANSFORM_NO_V2_TARGET";
+    /** A FHIR value cannot be carried into its v2 target without altering it (a lexical form v2 has
+     * no representation for, or content that exceeds the target's component structure). The v2 field
+     * is left absent rather than truncated, rounded, or coerced. */
+    readonly TRANSFORM_VALUE_NOT_REPRESENTABLE: "TRANSFORM_VALUE_NOT_REPRESENTABLE";
+    /** A FHIR code has no usable inverse in the IG ConceptMap that governs its field: either several
+     * v2 source codes map onto it (so the inverse is ambiguous) or the map has no row for it at all.
+     * The v2 field is left absent, never resolved to one arbitrary member of the ambiguous set. */
+    readonly TRANSFORM_CODE_NOT_INVERTIBLE: "TRANSFORM_CODE_NOT_INVERTIBLE";
+    /** A `Coding.system` is not a system this library can name with a v2 coding-system mnemonic, so
+     * the coding cannot be written into a v2 coded field. It is flagged rather than emitted with no
+     * table context or with a code from an unrelated table. */
+    readonly TRANSFORM_CODE_SYSTEM_NOT_V2: "TRANSFORM_CODE_SYSTEM_NOT_V2";
+    /** A v2 field the segment's own attribute table marks **required** (usage `R`) is absent from an
+     * emitted segment, because the FHIR resource carried no source this reverse map could ground it
+     * from, or the source it carried had no faithful v2 form. The field is left absent per v2
+     * optionality rules and **declared here**: a placeholder is never written to satisfy v2 structure,
+     * and the receiver is never left to discover the gap. Distinct from
+     * {@link ISSUE_CODES.TRANSFORM_REQUIRED_ELEMENT_UNKNOWN}, which is the forward direction's
+     * FHIR-required element. */
+    readonly TRANSFORM_V2_REQUIRED_FIELD_ABSENT: "TRANSFORM_V2_REQUIRED_FIELD_ABSENT";
+    /** A reverse (FHIR to v2) conversion produced **no message at all**: nothing in the resource
+     * grounded a single field of the target segment, and an empty segment is never emitted. Raised so
+     * that an empty-handed conversion is never indistinguishable from a successful one, and separate
+     * from the refusals that name their own cause (an absent trigger, an unsupported resource type, a
+     * structurally malformed resource). */
+    readonly TRANSFORM_NO_V2_MESSAGE_EMITTED: "TRANSFORM_NO_V2_MESSAGE_EMITTED";
+    /** A segment the message carried did **not** reach any resource in the returned bundle, and the IG
+     * *does* publish a segment map for its name: a **library gap**, fixable here. Raised once per
+     * occurrence, located `NAME[k]` with `k` counted 1-based among the occurrences of that name
+     * (`DG1[1]`, `DG1[2]`), so a consumer can tell how much of the message the bundle represents
+     * without diffing the two by hand. The occurrence may have been read and refused rather than never
+     * read: being counted, or already named by another issue, is not the same as reaching a resource. */
+    readonly TRANSFORM_SEGMENT_NOT_EMITTED: "TRANSFORM_SEGMENT_NOT_EMITTED";
+    /** A segment the message carried did **not** reach any resource in the returned bundle, and its
+     * name is **not** one the IG publishes a segment map for: a **standard gap**, not fixable here.
+     * Custom Z-segments and `RXE` land on this code, and so does a name this library could not
+     * classify at all, because a damaged segment identifier is never re-derived from the line: an
+     * `AL1` whose identifier arrived as `AL11` reads as unclassifiable, not as an IG omission. Such an
+     * occurrence is located `[#n]` by its 1-based position among the segments of the message, with no
+     * name part at all. */
+    readonly TRANSFORM_SEGMENT_NO_IG_MAP: "TRANSFORM_SEGMENT_NO_IG_MAP";
 };
 /** A value from {@link ISSUE_CODES}: the type consumers narrow `issue.code` against. */
 type IssueCode = (typeof ISSUE_CODES)[keyof typeof ISSUE_CODES];
@@ -605,9 +671,13 @@ declare function toFhirQuantity(value: NM, units: CWE, ctx?: TransformContext):
  * `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 gives **ORM_O01 / OML_O21** ORC/OBR → `ServiceRequest` and **RXO** (+ RXR) →
- * `MedicationRequest`; and the thin IG singles give **VXU_V04** RXA/RXR/ORC → `Immunization`,
+ * from NK1, + one `AllergyIntolerance` per AL1, + one `Condition` per DG1, one `Procedure` per PR1
+ * and one `Coverage` per IN1); the **ORU^R01** results graph becomes
+ * `DiagnosticReport` + `Observation` (+ one `Specimen` per SPM of the report's SPECIMEN group,
+ * referenced from the report that scopes it); the
+ * order-entry graph gives **ORM_O01 / OML_O21** ORC/OBR → `ServiceRequest` and **RXO** (+ RXR, + the
+ * order's **TQ1** schedule) → `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:
@@ -624,6 +694,12 @@ declare function toFhirQuantity(value: NM, units: CWE, ctx?: TransformContext):
  *   {@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.
+ * - **Segment-level completeness.** Every segment occurrence that contributed nothing to a resource
+ *   the returned bundle contains raises one value-free issue naming it
+ *   ({@link SegmentReachLedger}), so silence over an omitted segment can no longer read as
+ *   completeness. The diagnostic OBSERVES this assembly and never steers it: the occurrences are
+ *   marked where a resource clears the gate above, the issues are appended after every issue the
+ *   assembly raised, and no resource, value or existing issue changes because of it.
  *
  * @packageDocumentation
  */
@@ -765,6 +841,41 @@ declare const ENCOUNTER_CLASS_V3_MAP: Readonly<Record<string, {
  * discharge sets `status = finished` per the PV1→Encounter map.
  */
 declare const ENCOUNTER_STATUS_MAP: Readonly<Record<string, string>>;
+/**
+ * The same Encounter carrying one `diagnosis` entry per Condition the bundle holds, per the ADT_A01
+ * message map's `Encounter[1].diagnosis.reference = Condition[1].id` row. Each entry's `condition`
+ * points at that Condition's `fullUrl`, so the link resolves inside the bundle.
+ *
+ * Applied after the diagnoses are built, because the Encounter joins the bundle before them and the
+ * produced nodes are immutable: this returns a new node rather than mutating the emitted one.
+ *
+ * @param encounter - The Encounter node already in the bundle.
+ * @param conditionFullUrls - The fullUrls of the Conditions emitted for the same message, in order.
+ * @example
+ * ```ts
+ * // withEncounterDiagnosis(encounter, ["urn:uuid:cond-1"]); // adds one diagnosis entry
+ * ```
+ */
+declare function withEncounterDiagnosis(encounter: FhirComplex, conditionFullUrls: readonly string[]): FhirComplex;
+/**
+ * The Encounter that should replace the emitted one once the message's diagnoses exist: the same
+ * resource carrying the back-references, put through the conservative-emit gate first. When the
+ * gate refuses the linked draft the ORIGINAL Encounter is returned unchanged and the link is
+ * declared {@link ISSUE_CODES.TRANSFORM_ELEMENT_DROPPED}, so a detail never costs the visit.
+ *
+ * The gate is a parameter rather than a call into the assembler, so what "the gate refuses this"
+ * means stays in one place and the refusal branch is reachable from a test without a hand-built
+ * invalid resource: the same shape the allergy emit path uses.
+ *
+ * @param encounter - The Encounter node already in the bundle.
+ * @param conditionFullUrls - The fullUrls of the Conditions emitted for the same message, in order.
+ * @param gate - The conservative-emit predicate: `true` when the linked Encounter may replace it.
+ * @example
+ * ```ts
+ * // emitEncounterDiagnosis(encounter, ["urn:uuid:cond-1"], () => true).value; // the linked one
+ * ```
+ */
+declare function emitEncounterDiagnosis(encounter: FhirComplex, conditionFullUrls: readonly string[], gate: (resource: FhirComplex) => boolean): ConvertResult<FhirComplex>;
 
 /**
  * OBX → FHIR `Observation`: the highest-clinical-stakes segment map,
@@ -783,13 +894,40 @@ declare const ENCOUNTER_STATUS_MAP: Readonly<Record<string, string>>;
  * | OBX-8 Abnormal Flags | `Observation.interpretation` | {@link HL70078_INTERPRETATION_CODES} |
  * | OBX-11 Result Status | `Observation.status` | {@link OBSERVATION_STATUS_MAP} (HL70085) |
  * | OBX-14 Date/Time of Observation | `Observation.effectiveDateTime` | {@link toFhirDateTime} |
+ * | (OBSERVATION-group NTE) | `Observation.note` | {@link buildAnnotations} (`NTE[ServiceRequest]`) |
+ *
+ * **What OBX-2 selects, row by row** (`ConceptMap-segment-obx-to-observation.html`, the OBX-5 rows):
+ *
+ * | OBX-2 | FHIR target | datatype map |
+ * |---|---|---|
+ * | `NM` | `valueQuantity` | `NM[Quantity]` |
+ * | `SN` | `valueQuantity` (with a comparator) / `valueRange` / `valueRatio` | the row's own conditions |
+ * | `CWE`/`CE`/`CF`/`CNE`/`IS` | `valueCodeableConcept` | `CWE[CodeableConcept]` |
+ * | `DT`/`DTM`/`TS` | `valueDateTime` | `DTM[DateTime]` |
+ * | `ST`/`TX`/`FT` | `valueString` | (direct) |
+ * | `DR` | `valuePeriod` | `DR[Period]` |
+ * | `NR` | `valueRange` | `NR[Range]` |
+ * | `TM` | `valueTime` | (direct, an R4 `time`) |
+ * | `NA` | `valueSampledData` | `NA[SampledData]` |
+ * | `ED` **and** OBX-5.4 = `Base64` | the {@link OBSERVATION_VALUE_ATTACHMENT_EXTENSION_URL} extension | `ED[Attachment]` |
+ * | `RP`, `ID`, anything else | `valueString` + flagged | (no settled target) |
  *
  * **The "never a confident wrong result" fail-safes:**
- * - **OBX-2 drives `value[x]`.** `NM`→`valueQuantity`, `CWE`/`CE`/`CF`/`CNE`/`IS`→`valueCodeableConcept`,
- *   `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`.
+ * - **OBX-2 drives `value[x]`**, per the table above, and every row of it degrades to the raw OBX-5
+ *   text as `valueString` + {@link ISSUE_CODES.TRANSFORM_ELEMENT_DROPPED} rather than emit a value
+ *   the map cannot ground: a `DR` neither of whose bounds is a dateTime this library will emit, an
+ *   `NR` neither of whose bounds is a faithful `decimal`, a `TM` carrying a UTC offset (an R4 `time`
+ *   admits none, and discarding one would move the instant), an `NA` carrying a magnitude `decimal`
+ *   cannot hold unaltered, an `ED` whose OBX-5.4 is not `Base64` (both ED rows are conditioned on
+ *   it), and `RP`, whose extension target the guide's own comment marks unsettled.
+ * - **The published NA row spells its attribute `Observation.valueSampedData`.** That is a typo in
+ *   the guide; the R4 element is `valueSampledData` and that is what is emitted.
+ * - **A SampledData asserts no origin and no period.** R4 makes both `1..1` and the NA map has no
+ *   source row for either, so they ship value-absent with a `data-absent-reason` and
+ *   {@link ISSUE_CODES.TRANSFORM_REQUIRED_ELEMENT_UNKNOWN}: an `origin` of 0 or a `period` of 1
+ *   would be a magnitude this message never sent, on a waveform.
+ * - **An ED payload is carried, never read.** OBX-5.5 reaches `Attachment.data` byte-for-byte: no
+ *   decode, no re-encode, no normalization, no validation, no truncation.
  * - **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`
@@ -805,6 +943,16 @@ declare const ENCOUNTER_STATUS_MAP: Readonly<Record<string, string>>;
  * @packageDocumentation
  */
 
+/**
+ * The v3 ObservationInterpretation canonical system (FHIR `Observation.interpretation` binding).
+ *
+ * @example
+ * ```ts
+ * import { V3_OBSERVATION_INTERPRETATION_SYSTEM } from "@cosyte/transform";
+ * V3_OBSERVATION_INTERPRETATION_SYSTEM.endsWith("v3-ObservationInterpretation"); // => true
+ * ```
+ */
+declare const V3_OBSERVATION_INTERPRETATION_SYSTEM = "http://terminology.hl7.org/CodeSystem/v3-ObservationInterpretation";
 /**
  * HL7 v2 Table 0078 (Abnormal Flags) → FHIR v3 ObservationInterpretation (`Observation.interpretation`),
  * per the IG **Table HL70078 to v3 ObservationInterpretation** ConceptMap. Every mapped row is
@@ -823,6 +971,54 @@ declare const HL70078_INTERPRETATION_CODES: ReadonlySet<string>;
  * **`C`→`corrected` and `X`→`cancelled` guarantee a corrected/cancelled result never emits as `final`.**
  */
 declare const OBSERVATION_STATUS_MAP: Readonly<Record<string, string>>;
+/**
+ * The extension URL the OBX map **fixes** on the `IF OBX-2 EQUALS "ED" AND IF OBX-5.4 EQUALS
+ * "Base64"` rows, transcribed from the map's own `Observation.extension.url` assignment. R4 has no
+ * `Observation.valueAttachment`, so the guide carries the R5 element as this named extension.
+ *
+ * @example
+ * ```ts
+ * import { OBSERVATION_VALUE_ATTACHMENT_EXTENSION_URL } from "@cosyte/transform";
+ * OBSERVATION_VALUE_ATTACHMENT_EXTENSION_URL.endsWith("extension-Observation.valueAttachment"); // true
+ * ```
+ */
+declare const OBSERVATION_VALUE_ATTACHMENT_EXTENSION_URL = "https://hl7.org/fhir/5.0/StructureDefinition/extension-Observation.valueAttachment";
+/**
+ * The OBX-5.4 encoding the OBX map conditions **both** of its `ED` rows on. Any other encoding
+ * (`A`, `Hex`, `Ascii`, a local token) leaves those rows unapplied, so no attachment is built.
+ *
+ * @example
+ * ```ts
+ * import { ED_BASE64_ENCODING } from "@cosyte/transform";
+ * ED_BASE64_ENCODING; // "Base64"
+ * ```
+ */
+declare const ED_BASE64_ENCODING = "Base64";
+/**
+ * The `SampledData.data` token the Implementation Considerations chapter's own worked example
+ * directs for a data point a repetition did not carry (`"set .dimensions to 4 and use E for the
+ * data points not present"`). It is the FHIR-defined "error" token, and it is written **only** for
+ * an absent position, never for a value that arrived and could not be converted.
+ *
+ * @example
+ * ```ts
+ * import { SAMPLED_DATA_ABSENT_POINT } from "@cosyte/transform";
+ * SAMPLED_DATA_ABSENT_POINT; // "E"
+ * ```
+ */
+declare const SAMPLED_DATA_ABSENT_POINT = "E";
+/**
+ * The `data-absent-reason` code carried by `SampledData.origin` and `SampledData.period`, the two
+ * R4-required elements of that datatype that **no row of the IG's NA map, and no line of the
+ * Implementation Considerations chapter it points at, supplies a source for**.
+ *
+ * @example
+ * ```ts
+ * import { SAMPLED_DATA_UNGROUNDED } from "@cosyte/transform";
+ * SAMPLED_DATA_UNGROUNDED; // "unknown"
+ * ```
+ */
+declare const SAMPLED_DATA_UNGROUNDED = "unknown";
 
 /**
  * OBR → FHIR `DiagnosticReport`, the ORU results-report anchor, grounded firsthand
@@ -841,6 +1037,7 @@ declare const OBSERVATION_STATUS_MAP: Readonly<Record<string, string>>;
  * | 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) |
+ * | (SPM children) | `DiagnosticReport.specimen` | reference wiring from the assembler |
  * | (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
@@ -849,8 +1046,11 @@ declare const OBSERVATION_STATUS_MAP: Readonly<Record<string, string>>;
  * 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
- * fabricated UTC), mirroring `Bundle.timestamp`. Deferred and flagged elsewhere, not silently mapped:
- * OBR-32/34/35 performers (need PractitionerRole resources), specimen, and `basedOn` ServiceRequest.
+ * fabricated UTC), mirroring `Bundle.timestamp`. `.specimen` carries only the Specimens the
+ * assembler has already emitted into this bundle, so the reference never resolves to nothing.
+ * Deferred and flagged elsewhere, not silently mapped: OBR-32/34/35 performers (need
+ * PractitionerRole resources), the ORU map's own OBR-to-Specimen row (4.2.2, distinct from the SPM
+ * one), and `basedOn` ServiceRequest.
  *
  * @packageDocumentation
  */
@@ -867,6 +1067,125 @@ declare const OBSERVATION_STATUS_MAP: Readonly<Record<string, string>>;
  */
 declare const DIAGNOSTIC_REPORT_STATUS_MAP: Readonly<Record<string, string>>;
 
+/**
+ * SPM → FHIR `Specimen`: the sample a result was taken from, carried into the bundle instead of
+ * lost between the lab feed and the FHIR record. Grounded firsthand on the IG **Segment SPM to
+ * Specimen** ConceptMap and the **ORU_R01 to Bundle** message map (`hl7.fhir.uv.v2mappings`, STU1;
+ * `ConceptMap-segment-spm-to-specimen.html`, `ConceptMap-message-oru-r01-to-bundle.html`), whose
+ * row 4.2.7.1 creates one Specimen per SPM of an ORDER_OBSERVATION's SPECIMEN group and wires
+ * `DiagnosticReport[1].specimen.reference` to it.
+ *
+ * | SPM field | FHIR target | via |
+ * |---|---|---|
+ * | SPM-2 Specimen ID (EIP) | `identifier` (placer, then filler) | EI.1 → `Identifier.value` |
+ * | SPM-4 Specimen Type (CWE) | `Specimen.type` | {@link toFhirCodeableConcept} |
+ * | SPM-6 Specimen Additives (CWE) | `container.additiveCodeableConcept` | {@link toFhirCodeableConcept} |
+ * | SPM-7 Collection Method (CWE) | `collection.method` | {@link toFhirCodeableConcept} |
+ * | SPM-8 Source Site (CWE) | `collection.bodySite` | {@link toFhirCodeableConcept} |
+ * | SPM-14 Specimen Description (ST) | `note` (`Annotation.text`) | one annotation per repetition |
+ * | SPM-17 Collection Date/Time (DR) | `collection.collectedPeriod` / `collectedDateTime` | `IF SPM-17.2 VALUED` |
+ * | SPM-18 Received Date/Time (DTM) | `Specimen.receivedTime` | {@link toFhirDateTime} |
+ * | SPM-24 Specimen Condition (CWE) | `Specimen.condition` | {@link toFhirCodeableConcept} |
+ * | SPM-27 Container Type (CWE) | `container.type` | {@link toFhirCodeableConcept} |
+ * | SPM-30 Accession ID (CX) | `Specimen.accessionIdentifier` | {@link toFhirIdentifier} |
+ * | SPM-31 Other Specimen ID (CX) | `identifier` | {@link toFhirIdentifier} |
+ * | SPM-32 Shipment ID (EI) | `identifier` (type `SHIP`, v2-0203) | the row's own fixed assignment |
+ * | (message-map wiring) | referenced from `DiagnosticReport.specimen` | the assembler |
+ *
+ * **Fail-safes (never a confident wrong specimen).**
+ * - **The status is never asserted.** `SPM-20` is the only row that targets `Specimen.status`, and
+ *   it reaches it through a **Table 0136 to specimen-status** value ConceptMap this library does not
+ *   carry. R4 binds that element `required`, and every member of the binding is a positive claim
+ *   about a sample a clinician may act on, so the element stays absent and the row is declared
+ *   {@link ISSUE_CODES.TRANSFORM_ELEMENT_DROPPED}. Unlike `Coverage.status`, `Specimen.status` is
+ *   `0..1`, so absence is the spec-clean shape and no `data-absent-reason` is needed to hold a slot.
+ * - **A specimen never points at a specimen that is not there.** `SPM-3 Specimen Parent IDs` targets
+ *   `Specimen.parent`, a reference to another Specimen resource; none is built for a parent, so the
+ *   row is declared rather than emitted as a link that resolves to nothing.
+ * - **A collection amount is not rebuilt from parts.** `SPM-12` reaches `collection.quantity`
+ *   through the `CQ[Quantity]` datatype map, which this library does not carry; assembling one from
+ *   CQ.1 and CQ.2 by hand would be a unit gate written twice, so the row is declared instead.
+ * - **An unresolvable coding system costs the system URI, never the code**, and every date/time goes
+ *   through the one timezone-safe converter: the datatype converters own both rules and this module
+ *   only routes fields to them.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * The Table 0203 identifier-type code the SPM-32 row **assigns** to the shipment identifier
+ * (`Specimen.identifier[3].type.coding.code = "SHIP"`, with the v2-0203 system beside it).
+ *
+ * @example
+ * ```ts
+ * import { SPM_SHIPMENT_IDENTIFIER_TYPE } from "@cosyte/transform";
+ * SPM_SHIPMENT_IDENTIFIER_TYPE; // "SHIP"
+ * ```
+ */
+declare const SPM_SHIPMENT_IDENTIFIER_TYPE = "SHIP";
+/**
+ * Build a FHIR `Specimen` resource node from one parsed HL7 v2 SPM segment. Returns
+ * `{ value: undefined }` when the segment grounds no element of the map at all, because an empty
+ * `Specimen` in a bundle is a claim that a sample was described when nothing about it was sent.
+ *
+ * @param spm - The SPM `@cosyte/hl7` `Segment`.
+ * @param subjectFullUrl - The `urn:uuid:` fullUrl of the bundle's Patient → `Specimen.subject`.
+ * @param ctx - The transform context (naming-system registry + timezone policy).
+ * @example
+ * ```ts
+ * import { parseHL7 } from "@cosyte/hl7";
+ * // const spm = parseHL7(raw).segments("SPM")[0];
+ * // const { value } = buildSpecimen(spm!, "urn:uuid:pat", {});
+ * ```
+ */
+declare function buildSpecimen(spm: Segment, subjectFullUrl: string | undefined, ctx: TransformContext): ConvertResult<FhirComplex>;
+
+/**
+ * NTE → a FHIR `Annotation`, grounded firsthand on the IG **Segment NTE to ServiceRequest**
+ * ConceptMap (`hl7.fhir.uv.v2mappings`, STU1; `ConceptMap-segment-nte-to-servicerequest.html`),
+ * which is the map the ORU_R01 message map files its `Observation.note` row against.
+ *
+ * | NTE field | FHIR target | via |
+ * |---|---|---|
+ * | NTE-3 Comment (FT, `0..-1`) | `Annotation.text` (`markdown`) | one annotation per repetition |
+ * | NTE-6 Entered Date/Time (DTM) | `Annotation.time` | {@link toFhirDateTime} |
+ *
+ * `NTE-1`, `NTE-2`, `NTE-7`, `NTE-8` and `NTE-9` carry no target in the map at all. Two rows do
+ * carry one and are deliberately **declared rather than built**: `NTE-5 Entered By` targets
+ * `note.authorReference(Practitioner)`, and this library builds no Practitioner, so an author would
+ * be a reference resolving to nothing; and `NTE-4 Comment Type` targets a **proposed** extension
+ * the guide has not named yet (its own cell reads `extension??-noteType`), so there is no canonical
+ * URL to write and one is never invented.
+ *
+ * **A note is text the sender wrote, so it is read as text.** `NTE-3` is `FT`: a v2 primitive with
+ * no component structure, where a raw `^` or `&` is content. Each repetition is rendered through
+ * the parser's own display projection, which resolves the v2 escape sequences (`\T\` to `&`,
+ * `\.br\` to a line break) and preserves verbatim any sequence it cannot render. The repetitions
+ * are **not** joined: a separator between them would be a character the wire never carried, and
+ * `Observation.note` is `0..*` precisely so each can stand on its own.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Every FHIR `Annotation` a run of `NTE` segments contributes, in message order: one per valued
+ * `NTE-3` repetition, each carrying that repetition's rendered text and the segment's `NTE-6` time.
+ *
+ * Returns `undefined` when the segments carry no comment text at all, so a caller adds no empty
+ * `note` element. The diagnostics raised are value-free: no byte of a note ever reaches one.
+ *
+ * @param notes - The `NTE` segments to read, in message order.
+ * @param ctx - The transform context (naming-system registry + timezone policy).
+ * @param issues - The issue sink for the deferred-row and timestamp diagnostics.
+ * @example
+ * ```ts
+ * import { parseHL7 } from "@cosyte/hl7";
+ * // const nte = parseHL7(raw).segments("NTE");
+ * // buildAnnotations(nte, {}, []); // a FHIR list of Annotation nodes, or undefined
+ * ```
+ */
+declare function buildAnnotations(notes: readonly Segment[], ctx: TransformContext, issues: TransformIssue[]): FhirNode | undefined;
+
 /**
  * ORC + OBR → FHIR `ServiceRequest`: the order-entry request, grounded firsthand
  * on the IG **Segment ORC to ServiceRequest** and **Segment OBR to ServiceRequest** ConceptMaps and
@@ -884,8 +1203,10 @@ declare const DIAGNOSTIC_REPORT_STATUS_MAP: Readonly<Record<string, string>>;
  * | ORC-9 Date/Time of Order Event | `authoredOn` | {@link toFhirDateTime}, *IF ORC-1 = `NW`* |
  * | OBR-4 Universal Service Identifier (CWE) | `ServiceRequest.code` | {@link toFhirCodeableConcept} |
  * | OBR-5 Priority (v2-0485) | `ServiceRequest.priority` | {@link SERVICE_REQUEST_PRIORITY_MAP} (HL70485) |
- * | OBR-6 Requested Date/Time | `occurrenceDateTime` | {@link toFhirDateTime} |
+ * | OBR-6 Requested Date/Time | `occurrenceDateTime` | {@link toFhirDateTime}, *IF no TQ1 timing* |
  * | OBR-31 Reason for Study (CWE) | `reasonCode` | {@link toFhirCodeableConcept} |
+ * | TQ1-3 Repeat Pattern (RPT) | `occurrenceTiming` | {@link readTq1} (RPT[Timing], all-or-nothing) |
+ * | TQ1-7 / TQ1-8 Start / End date-time | `occurrenceTiming.repeat.boundsPeriod.start`/`.end` | {@link readTq1} |
  * | (order message context) | `intent` = `order` | see below |
  * | (message-map wiring) | `subject` / `encounter` | the bundle's Patient / Encounter |
  *
@@ -906,6 +1227,13 @@ declare const DIAGNOSTIC_REPORT_STATUS_MAP: Readonly<Record<string, string>>;
  *   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.
+ * - **`occurrence[x]` is a choice, so exactly one member is ever emitted.** OBR-6 grounds an
+ *   `occurrenceDateTime` and a TQ1 grounds an `occurrenceTiming`; a group that would yield both
+ *   emits the **timing** (the richer statement, and the one the sender wrote a whole segment for)
+ *   and flags the dropped OBR-6. Emitting both would be structurally invalid FHIR, and silently
+ *   preferring the single instant would throw away the schedule. The timing itself is
+ *   all-or-nothing: see {@link readTq1}, whose every refusal leaves `occurrenceTiming` absent and
+ *   therefore hands the choice back to OBR-6 with no issue raised about it.
  *
  * - **`priority` (0..1), value-translated.** OBR-5 → `ServiceRequest.priority` via the IG
  *   **Table HL70485 to Request Priority** ConceptMap ({@link SERVICE_REQUEST_PRIORITY_MAP}): only
@@ -945,6 +1273,290 @@ declare const REQUEST_STATUS_MAP: Readonly<Record<string, string>>;
  */
 declare const SERVICE_REQUEST_PRIORITY_MAP: Readonly<Record<string, string>>;
 
+/**
+ * The message-level completeness diagnostic: which segment occurrences a message carried, which of
+ * them contributed to a resource the returned bundle actually contains, and one value-free issue for
+ * each one that did not.
+ *
+ * The library already refuses to produce a confident wrong FHIR value at the datatype and resource
+ * levels. This is the same rule one level up. A message can carry an `IAM`, a `DG1` or an `IN1` that
+ * nothing here reads, and until now the consumer got a bundle with nothing in it about the allergy
+ * and an issues list with nothing in it about the omission: silence read as completeness, which is a
+ * claim this library cannot make. After this, a consumer reads the issues list and learns which
+ * segments did not reach the bundle, and whether each one is a **library gap**
+ * ({@link ISSUE_CODES.TRANSFORM_SEGMENT_NOT_EMITTED}, the IG publishes a map and this library has
+ * not built it) or a **standard gap** ({@link ISSUE_CODES.TRANSFORM_SEGMENT_NO_IG_MAP}, the IG
+ * publishes no map, or the name could not be classified at all).
+ *
+ * Four rules carry the safety of this, and each one is enforced here rather than assumed upstream:
+ *
+ * - **Contribution, never inspection.** An occurrence "reached" a resource only if the assembly took
+ *   at least one of its values, or its identity, into a resource that is present in the returned
+ *   bundle. An occurrence that was counted, walked past, or already named by another issue did not
+ *   reach anything: the `RXE` and the orphan `OBX` this library counts and refuses are exactly the
+ *   omissions a consumer most needs told, so a "the walker touched it" reading would silence the
+ *   two cases the diagnostic exists for.
+ * - **A name is rendered only if it passes the segment-identifier shape**
+ *   ({@link SEGMENT_IDENTIFIER_SHAPE}), applied by this library to the value the parser published,
+ *   as a positive test the value must pass. Not by excluding known markers, not by importing a
+ *   constant from the parser package, not by anything that depends on which parser version a
+ *   consumer resolved: this library declares a peer range that admits any of them, so a rule keyed
+ *   on a marker literal fails OPEN the moment that literal changes, promoting an unvouched value
+ *   into a rendering. A shape test fails CLOSED: whatever it does not recognize is located
+ *   positionally, and no byte of it is reproduced.
+ * - **A position that carries no segment is not an occurrence.** The parser materializes an empty
+ *   position for a blank line so that ordinals stay stable. It carries no name AND no field content,
+ *   nothing was sent there, and reporting it would be a false claim of clinical omission at a
+ *   position the sender left empty. It is excluded wherever it sits, and it still counts toward the
+ *   `[#n]` ordinal of later occurrences so those keep matching the wire. A line that kept its field
+ *   separator still carries content and IS reported: the exclusion is for the absence of a segment,
+ *   never for the absence of a name.
+ * - **One issue per occurrence, numbered among all occurrences of its name.** Never collapsed,
+ *   capped or deduplicated, and `[k]` is the occurrence's position among all occurrences of that
+ *   name, never among the reported ones: a message with two `NK1` of which only the second is
+ *   reported yields `NK1[2]`.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * The HL7 v2 Chapter 2 segment-identifier shape: three characters, a leading letter, applied to the
+ * name value ITSELF as a positive membership test that must pass before any name is rendered.
+ *
+ * Everything else is a malformed name without exception: the empty string, a withheld marker, a raw
+ * pre-delimiter token, a bare numeric like `202`, a four-character `AL11`. A malformed occurrence has
+ * no name in this library's vocabulary and is identified by position instead.
+ *
+ * @example
+ * ```ts
+ * import { SEGMENT_IDENTIFIER_SHAPE } from "@cosyte/transform";
+ * SEGMENT_IDENTIFIER_SHAPE.test("ZAL"); // true
+ * SEGMENT_IDENTIFIER_SHAPE.test("202"); // false
+ * ```
+ */
+declare const SEGMENT_IDENTIFIER_SHAPE: RegExp;
+/**
+ * Whether a segment name may be rendered: the shape test of {@link SEGMENT_IDENTIFIER_SHAPE} applied
+ * to the value itself.
+ *
+ * Deliberately NOT an exclusion of known-bad literals. An exclusion test admits any value it has not
+ * heard of, which is the wrong direction for a rule whose whole job is to keep message bytes out of
+ * a diagnostic, and it would silently couple this library to one release of the parser package.
+ *
+ * @param name - The value the parser published as the occurrence's segment type.
+ * @example
+ * ```ts
+ * import { isWellFormedSegmentName } from "@cosyte/transform";
+ * isWellFormedSegmentName("ZAL");  // true
+ * isWellFormedSegmentName("AL11"); // false
+ * ```
+ */
+declare function isWellFormedSegmentName(name: string): boolean;
+/**
+ * One segment occurrence of a parsed message: a segment as it appears in the message, in message
+ * order, with everything needed to locate it in a value-free way and nothing else.
+ */
+interface SegmentOccurrence {
+    /** The parsed segment this occurrence wraps. */
+    readonly segment: Segment;
+    /** 1-based position among **all** parsed positions, empty ones included, so it matches the wire. */
+    readonly ordinal: number;
+    /** The renderable segment name, present only when it passed the shape test. */
+    readonly name: string | undefined;
+    /** 1-based position among the occurrences of {@link SegmentOccurrence.name}, when there is one. */
+    readonly nameIndex: number | undefined;
+}
+/**
+ * Every segment occurrence of a parsed message, in message order.
+ *
+ * A position that carries neither a name nor any field content is the parser's ordinal placeholder
+ * for a blank line: it is not a segment occurrence, it is left out, and it still advances the
+ * ordinal of everything after it. A position that carries field content is an occurrence even when
+ * its name is empty.
+ *
+ * @param msg - The parsed message.
+ * @example
+ * ```ts
+ * import { parseHL7 } from "@cosyte/hl7";
+ * import { enumerateSegmentOccurrences } from "@cosyte/transform";
+ * // enumerateSegmentOccurrences(parseHL7(raw))[0]?.name; // "MSH"
+ * ```
+ */
+declare function enumerateSegmentOccurrences(msg: Hl7Message): readonly SegmentOccurrence[];
+/**
+ * The v2 location of an occurrence: `NAME[k]` for a name that passed the shape test, `[#n]` for one
+ * that did not. Those are the only two shapes, and neither carries a field or component index.
+ *
+ * @param occurrence - The occurrence to locate.
+ * @example
+ * ```ts
+ * import { segmentOccurrenceLocation } from "@cosyte/transform";
+ * // segmentOccurrenceLocation(occ); // "DG1[2]" or "[#4]"
+ * ```
+ */
+declare function segmentOccurrenceLocation(occurrence: SegmentOccurrence): string;
+/**
+ * Tracks, across one message-level assembly, which segment occurrences CONTRIBUTED to a resource the
+ * returned bundle contains, and turns the rest into one value-free issue each.
+ *
+ * The assembly marks an occurrence only where a resource has just cleared the emit gate and joined
+ * the bundle, so "reached" means contributed-and-present by construction: an occurrence that was
+ * read and refused, or that built a resource the gate withheld, is never marked and is therefore
+ * reported.
+ *
+ * @example
+ * ```ts
+ * import { parseHL7 } from "@cosyte/hl7";
+ * import { SegmentReachLedger } from "@cosyte/transform";
+ * // const ledger = new SegmentReachLedger(parseHL7(raw));
+ * // ledger.markFirstOfType("MSH");
+ * // ledger.issues(); // one issue per occurrence that reached nothing
+ * ```
+ */
+declare class SegmentReachLedger {
+    private readonly occurrences;
+    private readonly reached;
+    /**
+     * @param msg - The parsed message whose occurrences are being tracked.
+     */
+    constructor(msg: Hl7Message);
+    /**
+     * Record that each given segment contributed to a resource now present in the bundle. `undefined`
+     * entries are ignored, so a call site can pass an optional part of a group without branching.
+     */
+    mark(...segments: readonly (Segment | undefined)[]): void;
+    /**
+     * Record that the FIRST occurrence of `type` contributed. The parser's derived views (`patient`,
+     * `visit`, `meta`) are built from the first segment of their type, so this is how a resource built
+     * from a view marks the occurrence it came from.
+     */
+    markFirstOfType(type: string): void;
+    /**
+     * Record that the `index`-th (0-based) occurrence of `type` contributed: the counterpart of
+     * {@link SegmentReachLedger.markFirstOfType} for the repeating views (`nextOfKin()`), whose
+     * entries are in document order.
+     */
+    markNthOfType(type: string, index: number): void;
+    /** The occurrences that contributed to no resource present in the bundle, in message order. */
+    reportable(): readonly SegmentOccurrence[];
+    /**
+     * One value-free issue per reportable occurrence, in message order: the library-gap code when the
+     * IG publishes a segment map for the name, the standard-gap code otherwise, and the standard-gap
+     * code for every name that could not be classified at all.
+     */
+    issues(): readonly TransformIssue[];
+}
+
+/**
+ * The set of HL7 v2 segment names the **HL7 Version 2 to FHIR** Implementation Guide publishes a
+ * segment-to-resource map for, transcribed by hand from the guide's own Segment Maps index.
+ *
+ * This is the one fact the completeness diagnostic cannot derive from the message or from this
+ * library's own code: whether a segment the transform did not carry into the Bundle is missing
+ * because this library has not built the mapping yet, or because the standard publishes no mapping
+ * to build. The two answers are different news for a consumer, so the set is recorded here with the
+ * guide version and the retrieval date it was read at, and every entry is auditable against the
+ * published index a reader can open themselves.
+ *
+ * **The set is the guide's, not this library's.** It says nothing about which of these segments the
+ * transform actually reads: `IAM` is on it and is not transformed, `RXE` is off it and is read and
+ * refused. Whether an occurrence is reported at all is decided elsewhere, by whether it reached an
+ * emitted resource; this set only chooses which of the two codes the report carries.
+ *
+ * **Qualified rows collapse onto their segment name.** The index publishes several maps per name and
+ * some of them carry a use qualifier (`MSH[Source]`, `PID[Patient]`, `PV1[EncounterHistory]`,
+ * `OBX[Component]`, `NTE[Comment]`, `PD1[LivingWill]`, `PRT[Location]`, `ROL[GeneralPractitioner]`
+ * and the rest). A qualifier selects a use of the same segment, so every one of them contributes its
+ * base name and nothing else: what a message carries is an `MSH`, never an `MSH[Source]`.
+ *
+ * @packageDocumentation
+ */
+/**
+ * The published version of the HL7 Version 2 to FHIR Implementation Guide this set was read from.
+ *
+ * @example
+ * ```ts
+ * import { IG_SEGMENT_MAPS_VERSION } from "@cosyte/transform";
+ * IG_SEGMENT_MAPS_VERSION; // "1.0.0"
+ * ```
+ */
+declare const IG_SEGMENT_MAPS_VERSION = "1.0.0";
+/**
+ * The publication date of {@link IG_SEGMENT_MAPS_VERSION}, so a later release of the guide can be
+ * told apart from a defect in this library.
+ *
+ * @example
+ * ```ts
+ * import { IG_SEGMENT_MAPS_PUBLISHED } from "@cosyte/transform";
+ * IG_SEGMENT_MAPS_PUBLISHED; // "2025-10-07"
+ * ```
+ */
+declare const IG_SEGMENT_MAPS_PUBLISHED = "2025-10-07";
+/**
+ * The date the Segment Maps index was retrieved and transcribed into {@link IG_MAPPED_SEGMENT_NAMES}.
+ *
+ * A classification that surprises a reader is answered by re-reading the index at this date: the set
+ * is a transcription of a published document at a moment, not a live query.
+ *
+ * @example
+ * ```ts
+ * import { IG_SEGMENT_MAPS_RETRIEVED } from "@cosyte/transform";
+ * IG_SEGMENT_MAPS_RETRIEVED; // "2026-08-22"
+ * ```
+ */
+declare const IG_SEGMENT_MAPS_RETRIEVED = "2026-08-22";
+/**
+ * The Segment Maps index this set was transcribed from, so a reader can audit any entry.
+ *
+ * @example
+ * ```ts
+ * import { IG_SEGMENT_MAPS_SOURCE } from "@cosyte/transform";
+ * IG_SEGMENT_MAPS_SOURCE.startsWith("https://"); // true
+ * ```
+ */
+declare const IG_SEGMENT_MAPS_SOURCE = "https://hl7.org/fhir/uv/v2mappings/segment_maps.html";
+/**
+ * Every v2 segment name the guide publishes at least one segment-to-resource map for, at
+ * {@link IG_SEGMENT_MAPS_VERSION}, as of {@link IG_SEGMENT_MAPS_RETRIEVED}.
+ *
+ * Thirty-three names, transcribed chapter by chapter from {@link IG_SEGMENT_MAPS_SOURCE}: Control
+ * (`MSA`, `MSH`, `NTE`, `SFT`), Patient Administration (`AL1`, `EVN`, `IAM`, `MRG`, `NK1`, `PD1`,
+ * `PID`, `PV1`, `PV2`), Order Entry (`OBR`, `ORC`, `TQ1`), Pharmacy and Vaccination (`RXA`, `RXO`,
+ * `RXR`), Financial Management (`DG1`, `IN1`, `IN3`, `PR1`), Observation Reporting (`OBX`, `PRT`,
+ * `SPM`), Medical Records (`TXA`), Scheduling (`AIG`, `AIL`, `AIP`, `AIS`, `SCH`) and Personnel
+ * Management (`ROL`).
+ *
+ * Two absences a reader is most likely to check, because they look like oversights and are not:
+ * **`RXE` is not on this set** (the guide publishes no map for it, which is why this library counts
+ * an `RXE` and refuses to assemble one), and neither is **`GT1`**.
+ *
+ * @example
+ * ```ts
+ * import { IG_MAPPED_SEGMENT_NAMES } from "@cosyte/transform";
+ * IG_MAPPED_SEGMENT_NAMES.has("IAM"); // true
+ * IG_MAPPED_SEGMENT_NAMES.has("RXE"); // false
+ * ```
+ */
+declare const IG_MAPPED_SEGMENT_NAMES: ReadonlySet<string>;
+/**
+ * Whether the guide publishes a segment map for `name`, decided against
+ * {@link IG_MAPPED_SEGMENT_NAMES} and against nothing else.
+ *
+ * The comparison is exact: a name this library could not classify is not in the set, and is reported
+ * as a standard gap for that reason rather than because the guide was consulted and published
+ * nothing. That conflation is deliberate and is documented on the code itself; the alternative would
+ * be re-deriving a name the parser refused to vouch for.
+ *
+ * @param name - A v2 segment name, exactly as the parser published it.
+ * @example
+ * ```ts
+ * import { isIgMappedSegmentName } from "@cosyte/transform";
+ * isIgMappedSegmentName("DG1"); // true
+ * isIgMappedSegmentName("ZAL"); // false
+ * ```
+ */
+declare function isIgMappedSegmentName(name: string): boolean;
+
 /**
  * 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**
@@ -1075,76 +1687,655 @@ declare const IMMUNIZATION_STATUS_MAP: Readonly<Record<string, string>>;
 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
- * target coding the IG's segment-map `mappedVia` ConceptMap prescribes.
- *
- * **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
- * and preserves the raw coding, or withholds the value, but a target is **never fabricated**.
+ * AL1 to FHIR `AllergyIntolerance`: the allergy an ADT states, carried into the bundle instead of
+ * lost between the v2 feed and the FHIR record. Grounded firsthand on the IG **AL1 to
+ * AllergyIntolerance** segment map and the **ADT_A01 to Bundle** message map
+ * (`hl7.fhir.uv.v2mappings`, STU1; `ConceptMap-segment-al1-to-allergyintolerance.html`,
+ * `ConceptMap-message-adt-a01-to-bundle.html`), which wires
+ * `AllergyIntolerance.patient.reference` to the bundle's Patient and creates one resource per AL1.
  *
- * **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
- * **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
- * 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, and its code is **never**
- * asserted to be the standard concept just because the string happens to collide with a table code.
+ * | v2 field | FHIR target | via |
+ * |---|---|---|
+ * | AL1 (fixed) | `clinicalStatus` (`active`) | the IG's own assignment for constraint ait-1 |
+ * | AL1-2 Allergen Type Code (CWE) | `category` (0..*) | {@link ALLERGY_CATEGORY_VALUE_MAP} (HL70127) |
+ * | AL1-2 Allergen Type Code (CWE) | `category.extension` alternate-codes | {@link ALLERGY_ORIGINAL_CATEGORY_VALUE_MAP} (v2-0127 identity) |
+ * | AL1-2 Allergen Type Code (CWE) | `type` (0..1) | {@link ALLERGY_TYPE_VALUE_MAP} (HL70127) |
+ * | AL1-3 Allergen Code (CWE) | `code` | {@link toFhirCodeableConcept} (structural, no IG value map) |
+ * | AL1-4 Allergy Severity Code (CWE) | `criticality` (0..1) | {@link ALLERGY_CRITICALITY_VALUE_MAP} (HL70128) |
+ * | AL1-4 Allergy Severity Code (CWE) | `criticality.extension` alternate-codes | {@link ALLERGY_ORIGINAL_CRITICALITY_VALUE_MAP} (v2-0128 identity) |
+ * | AL1-5 Allergy Reaction Code (ST) | `reaction.manifestation.text` | verbatim, one manifestation per repetition |
+ * | AL1-6 Identification Date (DT) | `onsetDateTime` | {@link toFhirDateTime}, legacy versions only |
+ * | (message-map wiring) | `patient` (required 1..1) | the bundle's Patient |
+ *
+ * **Fail-safes (never a confident wrong allergy).**
+ * - **Two maps over one component, resolved independently.** The guide publishes a separate Table
+ *   0127 map for `category` and for `type`, with different unmapped sets, so `MA` yields a type and
+ *   **no category**. Neither answer is ever borrowed from the other map or from a neighbouring code:
+ *   the element the map has no target for is omitted and flagged
+ *   {@link ISSUE_CODES.TRANSFORM_CODE_UNMAPPED}.
+ * - **The original code survives whatever the map does.** The IG makes the `alternate-codes`
+ *   extension `1..1` wherever AL1-2 or AL1-4 is valued, so the code the sender wrote is carried in
+ *   its own v2 code system even when the translating map had no target for it. An unmapped category
+ *   is therefore a `category` element with the extension and no code value, not an absent one.
+ * - **`criticality` is the only severity target.** `AllergyIntolerance.reaction.severity` is a LOCAL
+ *   VARIATION in the guide, conditioned on a severity that was not used equivalently to criticality,
+ *   which no message states. It is never populated here, so a `MO` or `U` severity leaves criticality
+ *   absent and flagged rather than reappearing as a reaction grading the source never asserted.
+ * - **An allergy names what it is to.** AL1-3 is the allergen. An AL1 that grounds no allergen code
+ *   and no allergen text asserts an allergy without saying to what, so the resource is withheld and
+ *   flagged {@link ISSUE_CODES.TRANSFORM_ELEMENT_DROPPED} rather than emitted naming nothing.
+ * - **AL1-6 is legacy input, never a live element.** The IG's own comment on that row reads
+ *   "Withdrawn as of 2.7", so `onsetDateTime` is carried only for a message whose MSH-12 is readable
+ *   and earlier than 2.7. A valued AL1-6 on any later, absent or unreadable version is dropped and
+ *   flagged, never read as an onset the sender may not have meant.
+ * - **A rejected extension costs the extension, not the allergy.** If the alternate-codes extension
+ *   would make the resource fail the conservative-emit gate, the same resource is emitted without it
+ *   and the drop is flagged, so a consumer keeps the allergy rather than losing it to a detail.
+ *
+ * Deferred and flagged elsewhere, not silently mapped: `IAM` (the guide's other allergy segment),
+ * AL1-1 (the guide states it does not warrant mapping), and `verificationStatus`, which no AL1
+ * component grounds.
  *
  * @packageDocumentation
  */
 
-/** HL7 v2 Table 0162 (Route of Administration) THO CodeSystem URI. */
-declare const V2_0162_SYSTEM = "http://terminology.hl7.org/CodeSystem/v2-0162";
-/** HL7 v3 RouteOfAdministration CodeSystem URI (the IG's remap target for the six common routes). */
-declare const V3_ROUTE_OF_ADMINISTRATION_SYSTEM = "http://terminology.hl7.org/CodeSystem/v3-RouteOfAdministration";
-/** HL7 v2 Table 0550 (Body Parts) THO CodeSystem URI. */
-declare const V2_0550_SYSTEM = "http://terminology.hl7.org/CodeSystem/v2-0550";
-/** HL7 v2 Table 0277 (Appointment Type Codes) THO CodeSystem URI. */
-declare const V2_0277_SYSTEM = "http://terminology.hl7.org/CodeSystem/v2-0277";
-/** HL7 v2 Table 0161 (Allow Substitution) THO CodeSystem URI. */
-declare const V2_0161_SYSTEM = "http://terminology.hl7.org/CodeSystem/v2-0161";
-/** A translated FHIR target coding: the target CodeSystem URI + code, and the IG's target display. */
-interface CodedTarget {
-    /** The FHIR target CodeSystem canonical URI. */
-    readonly system: string;
-    /** The FHIR target code. */
-    readonly code: string;
-    /** The IG map's target display, when it carries one (absent for the identity table maps). */
-    readonly display?: string;
-}
 /**
- * A license-clean v2-table → FHIR value ConceptMap: it translates a **source table code** to its
- * {@link CodedTarget}, or `undefined` when the code is not in the map's *mapped* group (the IG's
- * `(unmapped)` group). Never fabricates a target.
+ * The code system of the fixed `clinicalStatus` the IG assigns to every AllergyIntolerance built
+ * from an AL1, transcribed from the segment map's own sort-order 0 row.
+ *
+ * @example
+ * ```ts
+ * import { ALLERGY_CLINICAL_STATUS_SYSTEM } from "@cosyte/transform";
+ * ALLERGY_CLINICAL_STATUS_SYSTEM.endsWith("allergyintolerance-clinical"); // true
+ * ```
  */
-interface CodedValueMap {
-    /** The IG ConceptMap id this map transcribes (its citation). */
-    readonly name: string;
-    /** 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
-     * 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
-     * system flagged, never asserted as the standard concept.
-     */
-    readonly sourceMnemonics: ReadonlySet<string>;
-    /** Translate a source table code to its FHIR target, or `undefined` when the IG map has no target. */
-    readonly translate: (code: string) => CodedTarget | undefined;
+declare const ALLERGY_CLINICAL_STATUS_SYSTEM = "http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical";
+/**
+ * The fixed `clinicalStatus` code the IG assigns. The guide's own note explains why it is fixed
+ * rather than derived: constraint ait-1 requires a clinicalStatus unless the verificationStatus is
+ * `entered-in-error`, and no AL1 component can ground that retraction.
+ *
+ * @example
+ * ```ts
+ * import { ALLERGY_CLINICAL_STATUS_CODE } from "@cosyte/transform";
+ * ALLERGY_CLINICAL_STATUS_CODE; // "active"
+ * ```
+ */
+declare const ALLERGY_CLINICAL_STATUS_CODE = "active";
+/**
+ * The canonical URL of the FHIR `alternate-codes` extension, the IG's fixed assignment for the
+ * `category.extension.url` and `criticality.extension.url` rows.
+ *
+ * @example
+ * ```ts
+ * import { ALTERNATE_CODES_EXTENSION_URL } from "@cosyte/transform";
+ * ALTERNATE_CODES_EXTENSION_URL; // "http://hl7.org/fhir/StructureDefinition/alternate-codes"
+ * ```
+ */
+declare const ALTERNATE_CODES_EXTENSION_URL = "http://hl7.org/fhir/StructureDefinition/alternate-codes";
+/**
+ * The HL7 v2 version at which AL1-6 Identification Date was withdrawn, per the IG map's own comment
+ * on that row ("Withdrawn as of 2.7, Refer to IAM-11 Onset or IAM-13 Reported Date"). A message at
+ * this version or later carries no AL1-6 that this library will read as an onset.
+ *
+ * @example
+ * ```ts
+ * import { AL1_ONSET_WITHDRAWN_AT } from "@cosyte/transform";
+ * AL1_ONSET_WITHDRAWN_AT; // [2, 7]
+ * ```
+ */
+declare const AL1_ONSET_WITHDRAWN_AT: readonly number[];
+/**
+ * Whether a message's MSH-12 version identifier is readable **and** earlier than the version at
+ * which AL1-6 was withdrawn ({@link AL1_ONSET_WITHDRAWN_AT}).
+ *
+ * Fails closed in both directions a version can be unusable: an absent MSH-12 and one this library
+ * cannot compare (a vendor string, an empty component, anything outside the dotted-numeric shape)
+ * both answer `false`, so a valued AL1-6 is dropped and flagged rather than read as an onset on a
+ * message that may never have meant one.
+ *
+ * @param version - The MSH-12 version identifier exactly as the parser published it.
+ * @example
+ * ```ts
+ * import { carriesLegacyOnsetDate } from "@cosyte/transform";
+ * carriesLegacyOnsetDate("2.5.1"); // true
+ * carriesLegacyOnsetDate("2.7"); // false
+ * carriesLegacyOnsetDate(undefined); // false
+ * ```
+ */
+declare function carriesLegacyOnsetDate(version: string | undefined): boolean;
+/**
+ * Every `AL1` occurrence a message carries, in message order. One AllergyIntolerance is created per
+ * occurrence, per the IG message map's `0..-1` cardinality on the AL1 row.
+ *
+ * @param msg - The parsed `@cosyte/hl7` message.
+ * @example
+ * ```ts
+ * import { parseHL7 } from "@cosyte/hl7";
+ * // collectAllergies(parseHL7(raw)).length; // one entry per AL1 in the message
+ * ```
+ */
+declare function collectAllergies(msg: Hl7Message): readonly Segment[];
+/** How much of the IG's AL1 mapping to carry: the alternate-codes extension is the one variable. */
+interface AllergyBuildOptions {
+    /**
+     * Whether to carry the IG's `alternate-codes` extension on `category` / `criticality`. Defaults to
+     * `true`; the emit path builds a second draft with it off only when the first draft fails the
+     * conservative-emit gate.
+     */
+    readonly carryAlternateCodes?: boolean;
+}
+
+/**
+ * DG1 to FHIR `Condition`: the diagnoses an admit states, carried into the bundle instead of lost
+ * between the v2 feed and the FHIR record. Grounded firsthand on the IG **DG1 to Condition** segment
+ * map and the **ADT_A01 to Bundle** message map (`hl7.fhir.uv.v2mappings`, STU1;
+ * `ConceptMap-segment-dg1-to-condition.html`, `ConceptMap-message-adt-a01-to-bundle.html`), which
+ * wires `Condition[1].subject.reference` to the bundle's Patient, creates one Condition per DG1, and
+ * references it back from `Encounter[1].diagnosis`.
+ *
+ * | v2 field | FHIR target | via |
+ * |---|---|---|
+ * | DG1-3 Diagnosis Code (CWE) | `code` | {@link toFhirCodeableConcept} (structural, no IG value map) |
+ * | DG1-4 Diagnosis Description (ST) | `code.text` | verbatim, overriding the coded field's own text |
+ * | DG1-5 Diagnosis Date/Time (DTM) | `onsetDateTime` | {@link toFhirDateTime} |
+ * | DG1-19 Attestation Date/Time (DTM) | `recordedDate` | {@link toFhirDateTime} |
+ * | DG1-20 Diagnosis Identifier (EI) | `identifier` | {@link toFhirEntityIdentifier} |
+ * | DG1-21 Diagnosis Action Code (ID) | `verificationStatus` | the map's fixed assignment for `D` |
+ * | (message-map wiring) | `subject` (required 1..1) | the bundle's Patient |
+ *
+ * **Fail-safes (never a confident wrong diagnosis).**
+ * - **One action code is mapped, and only one.** The DG1-21 row assigns the fixed value
+ *   `entered-in-error` and names no source code; its own comment reads "Other values (A and U) don't
+ *   map to anything", and Table 0206 publishes `A`, `D`, `S`, `U` and `X`. `D` (Delete) is therefore
+ *   the code the assignment covers: every other published action code leaves `verificationStatus`
+ *   absent and raises {@link ISSUE_CODES.TRANSFORM_CODE_UNMAPPED}, never a neighbouring status.
+ * - **A diagnosis with no code and no text is visible, not silent.** Such a DG1 still becomes a
+ *   Condition (the message stated a diagnosis), and the empty `code` is declared
+ *   {@link ISSUE_CODES.TRANSFORM_ELEMENT_DROPPED} rather than read as an intentionally empty one.
+ * - **`clinicalStatus` is absent because no row grounds it.** The map has no `Condition.clinicalStatus`
+ *   row and no DG1 component states one, so it is never filled. R4's `con-3` invariant expects it
+ *   wherever `verificationStatus` is not `entered-in-error`, so a Condition built here can fail that
+ *   invariant under a full profile validator: that is a declared gap, and filling the element from
+ *   nothing is the fabrication this library refuses.
+ *
+ * Deferred and flagged, never silently mapped: `DG1-16` (`asserter`, a Practitioner resource this
+ * library does not build), `DG1-22` (the `condition-dueTo` extension, whose reference resolves by
+ * identifier rather than by bundle position) and the map's `EpisodeOfCare` target, so a diagnosis
+ * ties to an Encounter or to nothing.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * The code system of the `verificationStatus` the DG1-21 row assigns, transcribed from the segment
+ * map's own `Condition.verificationStatus.coding.system` assignment.
+ *
+ * @example
+ * ```ts
+ * import { CONDITION_VERIFICATION_STATUS_SYSTEM } from "@cosyte/transform";
+ * CONDITION_VERIFICATION_STATUS_SYSTEM.endsWith("condition-ver-status"); // true
+ * ```
+ */
+declare const CONDITION_VERIFICATION_STATUS_SYSTEM = "http://terminology.hl7.org/CodeSystem/condition-ver-status";
+/**
+ * The `verificationStatus` code the DG1-21 row assigns, transcribed from the segment map's own
+ * `Condition.verificationStatus.coding.code` assignment.
+ *
+ * @example
+ * ```ts
+ * import { CONDITION_ENTERED_IN_ERROR } from "@cosyte/transform";
+ * CONDITION_ENTERED_IN_ERROR; // "entered-in-error"
+ * ```
+ */
+declare const CONDITION_ENTERED_IN_ERROR = "entered-in-error";
+/**
+ * The Table 0206 (Segment Action Code) code the DG1-21 assignment covers. The row assigns a
+ * retraction and names no source code; `D` is Delete, and the row's own comment excludes the rest.
+ *
+ * @example
+ * ```ts
+ * import { DG1_RETRACTION_ACTION_CODE } from "@cosyte/transform";
+ * DG1_RETRACTION_ACTION_CODE; // "D"
+ * ```
+ */
+declare const DG1_RETRACTION_ACTION_CODE = "D";
+/**
+ * Every `DG1` occurrence a message carries, in message order. One Condition is created per
+ * occurrence, per the IG message map's `0..-1` cardinality on the DG1 row.
+ *
+ * @param msg - The parsed `@cosyte/hl7` message.
+ * @example
+ * ```ts
+ * import { parseHL7 } from "@cosyte/hl7";
+ * // collectDiagnoses(parseHL7(raw)).length; // one entry per DG1 in the message
+ * ```
+ */
+declare function collectDiagnoses(msg: Hl7Message): readonly Segment[];
+/**
+ * The value-free diagnostics for the DG1 rows this library reads and deliberately does not build:
+ * the diagnosing clinician (a Practitioner resource), and the parent diagnosis (a reference resolved
+ * by identifier rather than by bundle position).
+ *
+ * Raised for the occurrence whether or not the Condition itself is emitted, so a deferred row a
+ * message actually valued is in the issues list rather than silently absent.
+ *
+ * @param dg1 - The `DG1` `@cosyte/hl7` `Segment`.
+ * @example
+ * ```ts
+ * // deferredDiagnosisIssues(dg1).length; // one per valued deferred row
+ * ```
+ */
+declare function deferredDiagnosisIssues(dg1: Segment): readonly TransformIssue[];
+/**
+ * Build a FHIR `Condition` resource node from one `DG1` occurrence, wired to the bundle's Patient.
+ * Always produces a Condition: a DG1 states a diagnosis, so an occurrence that grounds neither a
+ * code nor a description is emitted with its empty `code` declared rather than withheld.
+ *
+ * @param dg1 - The `DG1` `@cosyte/hl7` `Segment`.
+ * @param patientFullUrl - The bundle's Patient fullUrl, for `subject` (required 1..1).
+ * @param ctx - The transform context (naming-system registry + timezone policy).
+ * @param v2Location - The occurrence's v2 location, for the codeless diagnostic (e.g. `DG1[0]`).
+ * @example
+ * ```ts
+ * import { parseHL7 } from "@cosyte/hl7";
+ * // const dg1 = parseHL7(raw).segments("DG1")[0];
+ * // const { value } = buildCondition(dg1!, "urn:uuid:pat", {}, "DG1[0]");
+ * ```
+ */
+declare function buildCondition(dg1: Segment, patientFullUrl: string, ctx: TransformContext, v2Location: string): ConvertResult<FhirComplex>;
+
+/**
+ * PR1 to FHIR `Procedure`: the procedures an admit states, carried into the bundle instead of lost
+ * between the v2 feed and the FHIR record. Grounded firsthand on the IG **PR1 to Procedure** segment
+ * map and the **ADT_A01 to Bundle** message map (`hl7.fhir.uv.v2mappings`, STU1;
+ * `ConceptMap-segment-pr1-to-procedure.html`, `ConceptMap-message-adt-a01-to-bundle.html`), which
+ * wires `Procedure.subject.reference` to the bundle's Patient and creates one Procedure per PR1.
+ *
+ * | v2 field | FHIR target | via |
+ * |---|---|---|
+ * | PR1 (narrative row) | `status` (required 1..1) | the row's own `unknown`, the value it directs when the message context does not determine one |
+ * | PR1-3 Procedure Code (CNE) | `code` | {@link toFhirCodeableConcept} (structural, no IG value map) |
+ * | PR1-4 Procedure Description (ST) | `code.text` | verbatim, only `IF PR1-3.9 NOT VALUED` |
+ * | PR1-5 Procedure Date/Time (DTM) | `performedDateTime` / `performedPeriod.start` | {@link toFhirDateTime}, branched on PR1-7 |
+ * | PR1-6 Procedure Functional Type (CWE) | `category` | {@link toFhirCodeableConcept} |
+ * | PR1-7 Procedure Minutes (NM) | `performedPeriod.end` | the period start plus that many minutes |
+ * | PR1-15 Associated Diagnosis Code (CWE) | `reasonCode` | {@link toFhirCodeableConcept} |
+ * | PR1-19 Procedure Identifier (EI) | `identifier` | {@link toFhirEntityIdentifier} |
+ * | (message-map wiring) | `subject` (required 1..1) | the bundle's Patient |
+ *
+ * **Fail-safes (never a confident wrong procedure).**
+ * - **The status is the one the map directs, never one the message did not state.** The map's own
+ *   sort-order 0 row reads "The value mapping depends on the message context where the PR1 is used
+ *   and to be determined by the implementer. If not clear, use `unknown`". No PR1 component states a
+ *   procedure status, so `unknown` is the answer, and `completed` or `in-progress` is never selected
+ *   from a message that did not say so.
+ * - **A period needs a start precise enough to add minutes to.** PR1-7 is minutes, and the map's own
+ *   comment requires PR1-5 to reach at least minute granularity before a `performedPeriod` is built
+ *   from the pair. This library goes by what the conversion could actually carry: a PR1-5 that
+ *   reduces to date precision (a naked or partial-precision timestamp, per {@link toFhirDateTime})
+ *   is not a start a duration can be added to, so the value stays `performedDateTime` and the end is
+ *   declared {@link ISSUE_CODES.TRANSFORM_ELEMENT_DROPPED} rather than computed from a date.
+ * - **The description defers to the coded field's own text.** The PR1-4 row is conditioned
+ *   `IF PR1-3.9 NOT VALUED`, so an original text the sender put in the coded field wins and PR1-4 is
+ *   dropped and declared rather than overwriting it.
+ *
+ * Deferred and flagged, never silently mapped: `PR1-8`, `PR1-11` and `PR1-12` (`performer.actor`, a
+ * Practitioner resource this library does not build), `PR1-23` (`location`, likewise a Location),
+ * `PR1-25` (`partOf`, a reference resolved by identifier rather than by bundle position) and
+ * `PR1-16`, whose target `Procedure.code.value` is not an element of R4's `Procedure.code`.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * The `Procedure.status` the PR1 map's own narrative row directs when the message context does not
+ * determine one. No PR1 component carries a procedure status, so this is the value every Procedure
+ * built from a PR1 carries.
+ *
+ * @example
+ * ```ts
+ * import { PROCEDURE_STATUS_UNKNOWN } from "@cosyte/transform";
+ * PROCEDURE_STATUS_UNKNOWN; // "unknown"
+ * ```
+ */
+declare const PROCEDURE_STATUS_UNKNOWN = "unknown";
+/**
+ * Every `PR1` occurrence a message carries, in message order. One Procedure is created per
+ * occurrence, per the IG message map's `0..-1` cardinality on the PROCEDURE group.
+ *
+ * @param msg - The parsed `@cosyte/hl7` message.
+ * @example
+ * ```ts
+ * import { parseHL7 } from "@cosyte/hl7";
+ * // collectProcedures(parseHL7(raw)).length; // one entry per PR1 in the message
+ * ```
+ */
+declare function collectProcedures(msg: Hl7Message): readonly Segment[];
+/**
+ * Add whole minutes to a FHIR `dateTime` that carries a time of day, preserving its stated offset and
+ * its fractional seconds exactly. Returns `undefined` when the value is not a full zoned timestamp,
+ * because a date is not a start a duration can be added to.
+ *
+ * @param start - The FHIR `dateTime` lexical value the conversion produced.
+ * @param minutes - The number of minutes to add.
+ * @example
+ * ```ts
+ * import { addMinutes } from "@cosyte/transform";
+ * addMinutes("2026-01-15T10:30:00-05:00", 45); // "2026-01-15T11:15:00-05:00"
+ * addMinutes("2026-01-15", 45); // undefined
+ * ```
+ */
+declare function addMinutes(start: string, minutes: number): string | undefined;
+/**
+ * The value-free diagnostics for the PR1 rows this library reads and deliberately does not build:
+ * the three practitioner roles, the treating organizational unit, the parent procedure, and the code
+ * modifier whose target is not an R4 element.
+ *
+ * Raised for the occurrence whether or not the Procedure itself is emitted, so a deferred row a
+ * message actually valued is in the issues list rather than silently absent.
+ *
+ * @param pr1 - The `PR1` `@cosyte/hl7` `Segment`.
+ * @example
+ * ```ts
+ * // deferredProcedureIssues(pr1).length; // one per valued deferred row
+ * ```
+ */
+declare function deferredProcedureIssues(pr1: Segment): readonly TransformIssue[];
+/**
+ * Build a FHIR `Procedure` resource node from one `PR1` occurrence, wired to the bundle's Patient.
+ * Always produces a Procedure: a PR1 states that a procedure happened, and `status` is grounded on
+ * the map's own row rather than on the message, so nothing here can fail to be groundable.
+ *
+ * @param pr1 - The `PR1` `@cosyte/hl7` `Segment`.
+ * @param patientFullUrl - The bundle's Patient fullUrl, for `subject` (required 1..1).
+ * @param ctx - The transform context (naming-system registry + timezone policy).
+ * @example
+ * ```ts
+ * import { parseHL7 } from "@cosyte/hl7";
+ * // const pr1 = parseHL7(raw).segments("PR1")[0];
+ * // const { value } = buildProcedure(pr1!, "urn:uuid:pat", {});
+ * ```
+ */
+declare function buildProcedure(pr1: Segment, patientFullUrl: string, ctx: TransformContext): ConvertResult<FhirComplex>;
+
+/**
+ * IN1 to FHIR `Coverage`: the insurance an admit states, carried into the bundle instead of lost
+ * between the v2 feed and the FHIR record. Grounded firsthand on the IG **IN1 to Coverage** segment
+ * map and the **ADT_A01 to Bundle** message map (`hl7.fhir.uv.v2mappings`, STU1;
+ * `ConceptMap-segment-in1-to-coverage.html`, `ConceptMap-message-adt-a01-to-bundle.html`), which
+ * wires `Coverage.beneficiary.reference` to the bundle's Patient and creates one Coverage per IN1.
+ *
+ * | v2 field | FHIR target | via |
+ * |---|---|---|
+ * | IN1-2 Health Plan ID (CWE) | `identifier` | CWE.1 as the identifier value |
+ * | IN1-4 Insurance Company Name (XON) | `payor` (required 1..*) | a reference carrying the name as `display` only |
+ * | IN1-10 Insured's Group Emp ID (CX) | the subscriber-id extension, `IF CX.5 IS "SN"` | {@link toFhirIdentifier} |
+ * | IN1-12 Plan Effective Date (DT) | `period.start` | {@link toFhirDateTime} |
+ * | IN1-13 Plan Expiration Date (DT) | `period.end` | {@link toFhirDateTime} |
+ * | IN1-15 Plan Type (CWE) | `type` | {@link toFhirCodeableConcept} |
+ * | IN1-49 Insured's ID Number (CX) | the subscriber-id extension | {@link toFhirIdentifier} |
+ * | (no row at all) | `status` (required 1..1) | a value-absent element, `data-absent-reason` `unknown` |
+ * | (message-map wiring) | `beneficiary` (required 1..1) | the bundle's Patient |
+ *
+ * **Fail-safes (never a confident wrong coverage).**
+ * - **The status is never asserted.** `Coverage.status` occurs nowhere in the segment map, and R4
+ *   makes the element required under a required binding whose members are all positive claims about
+ *   a policy. So it ships as a value-absent element carrying `data-absent-reason` `unknown`, plus
+ *   {@link ISSUE_CODES.TRANSFORM_REQUIRED_ELEMENT_UNKNOWN}: a consumer must read the status as
+ *   unknown, and `active` is never the answer this library gives to a message that did not say so.
+ * - **A coverage names who pays.** `payor` is required 1..1 and IN1-4 is the only row that grounds
+ *   it, so an IN1 whose insurance company name is absent is **withheld** and declared
+ *   {@link ISSUE_CODES.TRANSFORM_ELEMENT_DROPPED} rather than emitted naming no payer.
+ * - **The payer is named, not resolved.** No Organization resource is built here, so `payor` carries
+ *   the company name as a `display` and no literal reference, and the missing resource is declared
+ *   rather than left to look like a resolvable link.
+ * - **A health plan id keeps its value, never a synthesized system.** IN1-2 is a coded element whose
+ *   coding system is a table mnemonic, not an identifier namespace, so only CWE.1 is carried as
+ *   `Identifier.value`; a valued CWE.3 is declared dropped rather than turned into an
+ *   `Identifier.system` this library would be inventing.
+ *
+ * Deferred and flagged, never silently mapped: `IN1-5` (the payer address, an Organization this
+ * library does not build), `IN1-10` and `IN1-11` (`policyHolder`, likewise an Organization),
+ * `IN1-16` (`subscriber`, a Patient or RelatedPerson reference the guide conditions on IN1-17) and
+ * `IN1-17` (`relationship`, whose value translation needs a Table 0063 to v3 RoleCode ConceptMap
+ * this library does not carry).
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * The canonical URL of the subscriber-id extension the IN1-10 and IN1-49 rows assign, transcribed
+ * from the segment map's own `Coverage.extension.url` assignment.
+ *
+ * @example
+ * ```ts
+ * import { COVERAGE_SUBSCRIBER_ID_EXTENSION_URL } from "@cosyte/transform";
+ * COVERAGE_SUBSCRIBER_ID_EXTENSION_URL.endsWith("extension-subscriberId"); // true
+ * ```
+ */
+declare const COVERAGE_SUBSCRIBER_ID_EXTENSION_URL = "http://hl7.org/fhir/5.0/StructureDefinition/extension-subscriberId";
+/**
+ * The `data-absent-reason` code carried by `Coverage.status`, the one FHIR-required element of this
+ * resource that no published row of the segment map grounds.
+ *
+ * @example
+ * ```ts
+ * import { COVERAGE_STATUS_UNKNOWN } from "@cosyte/transform";
+ * COVERAGE_STATUS_UNKNOWN; // "unknown"
+ * ```
+ */
+declare const COVERAGE_STATUS_UNKNOWN = "unknown";
+/**
+ * The Table 0203 identifier-type code the IN1-10 row conditions its subscriber-id assignment on
+ * (`IF CX.5 IS "SN"`, Subscriber Number). Any other identifier type leaves that row unapplied.
+ *
+ * @example
+ * ```ts
+ * import { IN1_SUBSCRIBER_NUMBER_TYPE } from "@cosyte/transform";
+ * IN1_SUBSCRIBER_NUMBER_TYPE; // "SN"
+ * ```
+ */
+declare const IN1_SUBSCRIBER_NUMBER_TYPE = "SN";
+/**
+ * Every `IN1` occurrence a message carries, in message order. One Coverage is created per
+ * occurrence, per the IG message map's INSURANCE group.
+ *
+ * @param msg - The parsed `@cosyte/hl7` message.
+ * @example
+ * ```ts
+ * import { parseHL7 } from "@cosyte/hl7";
+ * // collectCoverages(parseHL7(raw)).length; // one entry per IN1 in the message
+ * ```
+ */
+declare function collectCoverages(msg: Hl7Message): readonly Segment[];
+/**
+ * The insurance company name an IN1 carries, read from XON.1 of IN1-4, or `""` when that component
+ * carries nothing. The only row of the segment map that grounds the required `payor`.
+ *
+ * @param in1 - The `IN1` `@cosyte/hl7` `Segment`.
+ * @example
+ * ```ts
+ * // insuranceCompanyName(in1); // the XON.1 organization name, verbatim
+ * ```
+ */
+declare function insuranceCompanyName(in1: Segment): string;
+/**
+ * The value-free diagnostics for the IN1 rows this library reads and deliberately does not build:
+ * the payer address and the two policy-holder rows (each an Organization resource), the subscriber
+ * (a Patient or RelatedPerson reference), and the relationship, whose value translation needs a
+ * table this library does not carry.
+ *
+ * Raised for the occurrence whether or not the Coverage itself is emitted, so a deferred row a
+ * message actually valued is in the issues list rather than silently absent.
+ *
+ * @param in1 - The `IN1` `@cosyte/hl7` `Segment`.
+ * @example
+ * ```ts
+ * // deferredCoverageIssues(in1).length; // one per valued deferred row
+ * ```
+ */
+declare function deferredCoverageIssues(in1: Segment): readonly TransformIssue[];
+/**
+ * Build a FHIR `Coverage` resource node from one `IN1` occurrence, wired to the bundle's Patient.
+ * Returns `{ value: undefined }` when IN1-4 names no insurance company, because `payor` is required
+ * by R4 and no other row of the segment map grounds it.
+ *
+ * @param in1 - The `IN1` `@cosyte/hl7` `Segment`.
+ * @param patientFullUrl - The bundle's Patient fullUrl, for `beneficiary` (required 1..1).
+ * @param ctx - The transform context (naming-system registry + timezone policy).
+ * @param v2Location - The occurrence's v2 location, for the withholding diagnostic (e.g. `IN1[0]`).
+ * @example
+ * ```ts
+ * import { parseHL7 } from "@cosyte/hl7";
+ * // const in1 = parseHL7(raw).segments("IN1")[0];
+ * // const { value } = buildCoverage(in1!, "urn:uuid:pat", {}, "IN1[0]");
+ * ```
+ */
+declare function buildCoverage(in1: Segment, patientFullUrl: string, ctx: TransformContext, v2Location: string): ConvertResult<FhirComplex>;
+
+/**
+ * Bundle-assembly primitives shared by the segment→resource builders: fresh `urn:uuid:` identities,
+ * FHIR `Reference` nodes, and the small coding/data-absent helpers the message maps need.
+ *
+ * The identities are the wiring of the resource graph: a produced resource is registered under a
+ * `urn:uuid:` `fullUrl`, and every intra-bundle reference (Encounter→subject→Patient,
+ * RelatedPerson→patient→Patient, MessageHeader→focus→…) points at that same `fullUrl` so references
+ * always resolve **within** the bundle. Identities come from {@link TransformOptions.generateId}
+ * (default `crypto.randomUUID`) so output can be made reproducible for golden fixtures.
+ *
+ * @packageDocumentation
+ */
+
+/** One EI field read as a FHIR `Identifier`: the value, and whether an authority went unused. */
+interface EntityIdentifier {
+    /** The `Identifier` node built from EI.1, or `undefined` when EI.1 carries nothing. */
+    readonly identifier: FhirComplex | undefined;
+    /** Whether EI.2, EI.3 or EI.4 carried an assigning authority this library did not resolve. */
+    readonly authorityValued: boolean;
+}
+/**
+ * Read one EI (Entity Identifier) field as a FHIR `Identifier`, carrying EI.1 as
+ * `Identifier.value` and nothing else. The same reading {@link orderIdentifier} applies to the
+ * placer/filler order numbers, without the v2-0203 identifier type those rows assign.
+ *
+ * `Identifier.system` is deliberately left absent even when EI.2 to EI.4 name an assigning
+ * authority: a system URI is never synthesized from a bare namespace, because two senders reusing
+ * one namespace would otherwise collide. The caller is told the authority went unused through
+ * {@link EntityIdentifier.authorityValued} so it can raise its own value-free diagnostic.
+ *
+ * @param field - The `EI` field, exactly as the parser published it.
+ * @example
+ * ```ts
+ * import { parseHL7 } from "@cosyte/hl7";
+ * // const dg1 = parseHL7(raw).segments("DG1")[0];
+ * // toFhirEntityIdentifier(dg1!.field(20)).identifier; // { value: "<EI.1>" } or undefined
+ * ```
+ */
+declare function toFhirEntityIdentifier(field: Field): EntityIdentifier;
+/**
+ * The same `CodeableConcept` with its `text` replaced by `textValue`, so a segment row that targets
+ * `code.text` directly can override the original text the datatype map read out of the coded field.
+ *
+ * @param concept - The `CodeableConcept` node the datatype converter produced.
+ * @param textValue - The text the segment map's own row assigns.
+ * @example
+ * ```ts
+ * // withCodeableText(concept, "Diabetes mellitus") -> the same codings, that text
+ * ```
+ */
+declare function withCodeableText(concept: FhirComplex, textValue: string): FhirComplex;
+
+/**
+ * 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
+ * target coding the IG's segment-map `mappedVia` ConceptMap prescribes.
+ *
+ * **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
+ * and preserves the raw coding, or withholds the value, but a target is **never fabricated**.
+ *
+ * Two of the maps below are consumed as **recognizers** rather than as translations, because their
+ * IG rows are identity in the source code: {@link isRepeatPatternCode} (RPT.1 → `Timing.code`) and
+ * {@link TIMING_EVENT_VALUE_MAP} (RPT.8 → `Timing.repeat.when`). What they decide is whether the
+ * published map has a row at all, so the caller can carry the message's own code verbatim or
+ * withhold the element; neither one ever rewrites a code into a different one.
+ *
+ * **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`, `v2-0127`,
+ * `v2-0128`, `v2-0335`, `v2-0528`), the FHIR R4 core code systems (`allergy-intolerance-category`,
+ * `allergy-intolerance-type`, `allergy-intolerance-criticality`) and HL7 v3
+ * (`v3-RouteOfAdministration`, `v3-TimingEvent`) 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
+ * 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, and its code is **never**
+ * asserted to be the standard concept just because the string happens to collide with a table code.
+ *
+ * @packageDocumentation
+ */
+
+/** HL7 v2 Table 0162 (Route of Administration) THO CodeSystem URI. */
+declare const V2_0162_SYSTEM = "http://terminology.hl7.org/CodeSystem/v2-0162";
+/** HL7 v3 RouteOfAdministration CodeSystem URI (the IG's remap target for the six common routes). */
+declare const V3_ROUTE_OF_ADMINISTRATION_SYSTEM = "http://terminology.hl7.org/CodeSystem/v3-RouteOfAdministration";
+/** HL7 v2 Table 0550 (Body Parts) THO CodeSystem URI. */
+declare const V2_0550_SYSTEM = "http://terminology.hl7.org/CodeSystem/v2-0550";
+/** HL7 v2 Table 0277 (Appointment Type Codes) THO CodeSystem URI. */
+declare const V2_0277_SYSTEM = "http://terminology.hl7.org/CodeSystem/v2-0277";
+/** HL7 v2 Table 0161 (Allow Substitution) THO CodeSystem URI. */
+declare const V2_0161_SYSTEM = "http://terminology.hl7.org/CodeSystem/v2-0161";
+/** HL7 v2 Table 0127 (Allergen Type) THO CodeSystem URI. */
+declare const V2_0127_SYSTEM = "http://terminology.hl7.org/CodeSystem/v2-0127";
+/** HL7 v2 Table 0128 (Allergy Severity) THO CodeSystem URI. */
+declare const V2_0128_SYSTEM = "http://terminology.hl7.org/CodeSystem/v2-0128";
+/** FHIR R4 `AllergyIntoleranceCategory` CodeSystem URI (the IG's AL1-2 category target). */
+declare const ALLERGY_INTOLERANCE_CATEGORY_SYSTEM = "http://hl7.org/fhir/allergy-intolerance-category";
+/** FHIR R4 `AllergyIntoleranceType` CodeSystem URI (the IG's AL1-2 type target). */
+declare const ALLERGY_INTOLERANCE_TYPE_SYSTEM = "http://hl7.org/fhir/allergy-intolerance-type";
+/** FHIR R4 `AllergyIntoleranceCriticality` CodeSystem URI (the IG's AL1-4 criticality target). */
+declare const ALLERGY_INTOLERANCE_CRITICALITY_SYSTEM = "http://hl7.org/fhir/allergy-intolerance-criticality";
+/** A translated FHIR target coding: the target CodeSystem URI + code, and the IG's target display. */
+interface CodedTarget {
+    /** The FHIR target CodeSystem canonical URI. */
+    readonly system: string;
+    /** The FHIR target code. */
+    readonly code: string;
+    /** The IG map's target display, when it carries one (absent for the identity table maps). */
+    readonly display?: string;
+}
+/**
+ * A license-clean v2-table → FHIR value ConceptMap: it translates a **source table code** to its
+ * {@link CodedTarget}, or `undefined` when the code is not in the map's *mapped* group (the IG's
+ * `(unmapped)` group). Never fabricates a target.
+ */
+interface CodedValueMap {
+    /** The IG ConceptMap id this map transcribes (its citation). */
+    readonly name: string;
+    /** 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
+     * 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
+     * system flagged, never asserted as the standard concept.
+     */
+    readonly sourceMnemonics: ReadonlySet<string>;
+    /** Translate a source table code to its FHIR target, or `undefined` when the IG map has no target. */
+    readonly translate: (code: string) => CodedTarget | undefined;
 }
 /**
  * **RXR-1 Route**: IG `ConceptMap/table-hl70162-to-v2-0162`. Two IG groups, transcribed verbatim:
@@ -1178,6 +2369,111 @@ declare const APPOINTMENT_TYPE_VALUE_MAP: CodedValueMap;
  * substitution is withheld + flagged, never a fabricated substitution permission.
  */
 declare const SUBSTITUTION_VALUE_MAP: CodedValueMap;
+/**
+ * The published version of the HL7 Version 2 to FHIR Implementation Guide the five **AL1 allergy**
+ * value maps below were transcribed from.
+ *
+ * Recorded per map family rather than once for the file, because the earlier value maps here were
+ * transcribed on their own date and this constant must not backdate or forward-date them.
+ *
+ * @example
+ * ```ts
+ * import { IG_ALLERGY_VALUE_MAPS_VERSION } from "@cosyte/transform";
+ * IG_ALLERGY_VALUE_MAPS_VERSION; // "1.0.0"
+ * ```
+ */
+declare const IG_ALLERGY_VALUE_MAPS_VERSION = "1.0.0";
+/**
+ * The publication date of {@link IG_ALLERGY_VALUE_MAPS_VERSION}, so a later release of the guide can
+ * be told apart from a defect in this library.
+ *
+ * @example
+ * ```ts
+ * import { IG_ALLERGY_VALUE_MAPS_PUBLISHED } from "@cosyte/transform";
+ * IG_ALLERGY_VALUE_MAPS_PUBLISHED; // "2025-10-07"
+ * ```
+ */
+declare const IG_ALLERGY_VALUE_MAPS_PUBLISHED = "2025-10-07";
+/**
+ * The date the five AL1 allergy ConceptMaps were retrieved and transcribed into the maps below. A
+ * target that surprises a reader is answered by re-reading the guide at this date: each map is a
+ * transcription of a published document at a moment, not a live query.
+ *
+ * @example
+ * ```ts
+ * import { IG_ALLERGY_VALUE_MAPS_RETRIEVED } from "@cosyte/transform";
+ * IG_ALLERGY_VALUE_MAPS_RETRIEVED; // "2026-08-28"
+ * ```
+ */
+declare const IG_ALLERGY_VALUE_MAPS_RETRIEVED = "2026-08-28";
+/**
+ * The IG segment map the five AL1 allergy value maps hang off, so a reader can audit any row: it is
+ * the page that names which vocabulary map applies to which AL1 field.
+ *
+ * @example
+ * ```ts
+ * import { IG_ALLERGY_VALUE_MAPS_SOURCE } from "@cosyte/transform";
+ * IG_ALLERGY_VALUE_MAPS_SOURCE.startsWith("https://"); // true
+ * ```
+ */
+declare const IG_ALLERGY_VALUE_MAPS_SOURCE = "https://hl7.org/fhir/uv/v2mappings/ConceptMap-segment-al1-to-allergyintolerance.html";
+/**
+ * **AL1-2 Allergen Type to category**: IG `ConceptMap/table-hl70127-to-allergy-intolerance-category`.
+ * One **mapped** group of six rows into the FHIR R4 `AllergyIntoleranceCategory` code system (`DA`
+ * drug to `medication`, `FA` food to `food`, `EA` environmental to `environment`, `AA` animal to
+ * `biologic`, `PA` plant to `environment`, `LA` pollen to `environment`, each `equivalent`, with the
+ * IG target displays), and an `(unmapped)` group of two: **`MA` and `MC` have no category target**.
+ *
+ * The IG applies this map to `AllergyIntolerance.category` **only**; `AllergyIntolerance.type` has
+ * its own map ({@link ALLERGY_TYPE_VALUE_MAP}) over the same source table, and the two are resolved
+ * independently. `MA` therefore yields a type and no category, which is the guide's answer and not a
+ * gap to be filled: a category is never borrowed from the type map or from a neighbouring code.
+ */
+declare const ALLERGY_CATEGORY_VALUE_MAP: CodedValueMap;
+/**
+ * **AL1-2 Allergen Type to type**: IG `ConceptMap/table-hl70127-to-allergy-intolerance-type`. One
+ * **mapped** group of seven rows into the FHIR R4 `AllergyIntoleranceType` code system (`DA`, `FA`,
+ * `MA`, `EA`, `AA`, `PA`, `LA` all to `allergy`, each `equivalent`, display `Allergy`), and an
+ * `(unmapped)` group of one: **`MC` miscellaneous contraindication has no type target**.
+ *
+ * Read beside {@link ALLERGY_CATEGORY_VALUE_MAP}: the guide publishes two maps over Table 0127 with
+ * different unmapped sets, so a code can be mapped by one and not the other. `MC` is the only code
+ * neither map carries.
+ */
+declare const ALLERGY_TYPE_VALUE_MAP: CodedValueMap;
+/**
+ * **AL1-4 Allergy Severity to criticality**: IG
+ * `ConceptMap/table-hl70128-to-allergy-intolerance-criticality`. One **mapped** group of two rows
+ * into the FHIR R4 `AllergyIntoleranceCriticality` code system (`SV` severe to `high`, `MI` mild to
+ * `low`, both `equivalent`, with the IG target displays), and an `(unmapped)` group of two: **`MO`
+ * moderate and `U` unknown have no criticality target**.
+ *
+ * The unmapped pair is the whole reason this field fails safe. `criticality` is an overall risk
+ * assessment a prescriber acts on, so a moderate severity is left absent and flagged rather than
+ * rounded to `low` or `high`, and `AllergyIntolerance.reaction.severity` is never populated from the
+ * same component instead: the IG offers that only as a local variation, conditioned on a severity
+ * that was **not** used equivalently to criticality, which no v2 message states.
+ */
+declare const ALLERGY_CRITICALITY_VALUE_MAP: CodedValueMap;
+/**
+ * **AL1-2 original code**: IG `ConceptMap/table-hl70127-to-v2-0127`. A single **identity** group of
+ * all eight Table 0127 codes (`DA`, `FA`, `MA`, `MC`, `EA`, `AA`, `PA`, `LA` to themselves, each
+ * `equivalent`, source and target both `v2-0127`).
+ *
+ * This is the map behind the `alternate-codes` extension the IG puts on `category`: whatever the
+ * category map does or does not translate, the code the sender actually wrote survives on the
+ * resource in its own code system, so a consumer can always see what the message said.
+ */
+declare const ALLERGY_ORIGINAL_CATEGORY_VALUE_MAP: CodedValueMap;
+/**
+ * **AL1-4 original code**: IG `ConceptMap/table-hl70128-original-to-v2-0128`. A single **identity**
+ * group of all four Table 0128 codes (`SV`, `MO`, `MI`, `U` to themselves, each `equivalent`, source
+ * and target both `v2-0128`), the map behind the `alternate-codes` extension on `criticality`.
+ *
+ * Its four codes are a superset of the two {@link ALLERGY_CRITICALITY_VALUE_MAP} translates, which
+ * is the point: a `MO` that yields no criticality still yields the original severity code here.
+ */
+declare const ALLERGY_ORIGINAL_CRITICALITY_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
@@ -1242,6 +2538,308 @@ declare function codeableConceptFromTarget(target: CodedTarget, text?: string):
  */
 declare function toFhirCodeableConceptVia(cwe: CodedElement, map: CodedValueMap, ctx?: TransformContext): ConvertResult<FhirComplex>;
 
+/**
+ * Writing HL7 v2 field content: the small, safe primitives the reverse (FHIR to v2) maps build on.
+ *
+ * Two disciplines live here.
+ *
+ * **Composite content is structured, never concatenated.** A typed composite (XPN, CX, CWE, XAD) is
+ * handed to `@cosyte/hl7` as a `RawField` of components, so the serializer owns delimiter escaping:
+ * a family name of `Do^e` emits as `Do\S\e` and reads back as `Do^e`, where a hand-built `"Do^e"`
+ * string would have silently become two components. Nothing in this module writes a `^` or a `~`.
+ *
+ * **A lexical form v2 cannot carry is refused, never trimmed to fit.** {@link v2Timestamp} and
+ * {@link v2Number} return `undefined` rather than an approximation, and their callers flag the value
+ * and leave the v2 field absent.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Invert a forward v2-to-FHIR code map, keeping **only** the targets exactly one v2 code maps to.
+ *
+ * This is the bijective-subset rule as code. Where several v2 codes are "equivalent to" one FHIR
+ * concept (Table 0001 `O`/`A`/`N` all map to `other`), the inverse is ambiguous: the target is
+ * dropped here, and its caller flags `TRANSFORM_CODE_NOT_INVERTIBLE` rather than picking one member
+ * of the set.
+ *
+ * @param forward - A v2 code to FHIR code map, as published by the IG ConceptMap.
+ * @example
+ * ```ts
+ * import { invertCodeMap } from "@cosyte/transform";
+ * invertCodeMap({ F: "female", O: "other", A: "other" }); // => { female: "F" }
+ * ```
+ */
+declare function invertCodeMap(forward: Readonly<Record<string, string>>): Readonly<Record<string, string>>;
+
+/**
+ * Codes and coding systems on the way out to v2, and the caller-supplied context that resolution
+ * needs.
+ *
+ * A v2 coded field names its vocabulary with a Table 0396 mnemonic (`LN`, `SCT`, `UCUM`), so writing
+ * a FHIR `Coding` into one means turning a canonical system URI back into that mnemonic. There is no
+ * algorithm for that, only a registry, so this module inverts the same seed the forward direction
+ * resolves through ({@link DEFAULT_V2_CODE_SYSTEMS} plus whatever the caller adds) and **refuses
+ * everything else**: an unrecognized system is flagged, never written into a coded field with no
+ * table context and never re-coded into a neighbouring table.
+ *
+ * The inversion keeps only URIs exactly one mnemonic names, for the same reason the code-map
+ * inversion does: two mnemonics for one URI is an ambiguity, not a choice to make silently.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Caller context for a reverse (FHIR to v2) conversion. Every entry is **caller-vetted**: nothing
+ * here is derived from resource content, and omitting all of it is safe (the conversion then flags
+ * what it cannot resolve rather than guessing it).
+ *
+ * @example
+ * ```ts
+ * import { toV2Patient } from "@cosyte/transform";
+ * const options = {
+ *   assigningAuthorities: { "urn:oid:1.2.840.114350": "HOSP" },
+ *   envelope: { sendingApp: "EHR", sendingFacility: "MAIN" },
+ * };
+ * void options;
+ * void toV2Patient;
+ * ```
+ */
+interface ReverseOptions {
+    /**
+     * Extra v2 coding-system mnemonic to canonical URI entries, merged over
+     * {@link DEFAULT_V2_CODE_SYSTEMS} and then inverted. Same shape and direction as the forward
+     * registry's seed, so one declaration serves both directions.
+     */
+    readonly codeSystems?: Readonly<Record<string, string>>;
+    /**
+     * `Identifier.system` URI to the v2 assigning-authority namespace (HD.1) that stands for it. There
+     * is no derivation from a URI to a namespace, so an identifier whose system is absent here is
+     * emitted with its value and **no** assigning authority, flagged rather than invented.
+     */
+    readonly assigningAuthorities?: Readonly<Record<string, string>>;
+    /**
+     * MSH envelope fields for the emitted message (sending/receiving application and facility, control
+     * id, timestamp, version, processing id). The message type is never taken from here: it is fixed
+     * by the shape plus the caller's trigger argument.
+     */
+    readonly envelope?: Omit<BuildMessageInit, "type">;
+}
+
+/**
+ * The scaffolding every reverse (FHIR to v2) entry point shares: the required trigger, the resource
+ * gate, and the message the mapped segment is carried in.
+ *
+ * **The trigger is always the caller's.** No FHIR resource carries an HL7 v2 message trigger: not
+ * `Patient`, not `Observation`, not `Encounter`. So it is a required argument, and a missing, empty
+ * or non-string one stops the conversion **before** any builder call, with
+ * {@link ISSUE_CODES.TRANSFORM_MISSING_TRIGGER} on the ordinary `{ value, issues }` channel. It is
+ * never defaulted, never derived from resource content, and never substituted with a placeholder.
+ *
+ * **What is emitted is a message, never a bare segment.** A segment on its own is not parseable HL7
+ * (a v2 parser fatally rejects any input whose first segment is not `MSH`), so each shape builds a
+ * complete message through `buildMessage` and appends its mapped segment to it. The trigger is used
+ * verbatim as the trailing component of the fixed message code the shape itself owns.
+ *
+ * **What is missing is declared, not merely missing.** A FHIR resource carrying no source for a v2
+ * field the segment's own attribute table marks *required* leaves that field absent, because the
+ * alternative is inventing content for a clinical reader. Absent is the right wire; **silent** is
+ * not, so each shape names its required fields ({@link ReverseShape.required}) and every one of them
+ * that ends up unsourced raises {@link ISSUE_CODES.TRANSFORM_V2_REQUIRED_FIELD_ABSENT}. When nothing
+ * at all grounded a field, there is no segment to be missing from and no message is built:
+ * {@link ISSUE_CODES.TRANSFORM_NO_V2_MESSAGE_EMITTED} declares that outcome on its own, so an
+ * empty-handed conversion never looks like a successful one.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * What a reverse conversion returns: the complete `@cosyte/hl7` message it could faithfully build
+ * (or `undefined` when it could not), plus the value-free diagnostics it raised. The same fail-safe
+ * envelope the forward converters return, in the other direction.
+ *
+ * @example
+ * ```ts
+ * import { toV2Patient } from "@cosyte/transform";
+ * // const { value, issues } = toV2Patient(patientNode, "A28");
+ * // value?.toString() -> "MSH|^~\\&|...|ADT^A28|...\rPID|||MRN1\r"
+ * void toV2Patient;
+ * ```
+ */
+type ReverseResult = ConvertResult<Hl7Message>;
+
+/**
+ * FHIR `Patient` to a v2 message carrying a `PID` segment: the inverse of the IG **Segment PID to
+ * Patient** ConceptMap, over the rows whose inverse is defensible.
+ *
+ * | FHIR element | PID field | inverse |
+ * |---|---|---|
+ * | `Patient.identifier` | PID-3 (CX) | value to CX.1, caller-vetted authority to CX.4, Table 0203 type to CX.5 |
+ * | `Patient.name` | PID-5 (XPN) | family/given/prefix/suffix to XPN.1-XPN.5, `use` to XPN.7 where the HL70200 map inverts |
+ * | `Patient.birthDate` | PID-7 (DTM) | lexical date, precision preserved |
+ * | `Patient.gender` | PID-8 | Table 0001 where the map inverts (`female`/`male`/`unknown`) |
+ * | `Patient.address` | PID-11 (XAD) | line/city/state/postalCode/country/district, `use` to XAD.7 where HL70190 inverts |
+ *
+ * **This is the lossy direction, and it says so rather than papering over it.** The published map is
+ * v2 to FHIR; several of its rows are many-to-one, so the inverse is ambiguous and is refused:
+ * `gender` `other` (Table 0001 `O`, `A` and `N` all mean it), name use `official` (`L` and `R`) and
+ * `temp` (`NAV` and `TEMP`), address use `work` (`B` and `O`), and every `Address.type`
+ * (`M` and `SH` both mean `postal`). Each leaves its v2 field absent and raises
+ * {@link ISSUE_CODES.TRANSFORM_CODE_NOT_INVERTIBLE}. Nothing here reconstructs a v2 message that was
+ * transformed to FHIR: it writes what the FHIR resource itself supports, and flags the rest.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * FHIR `administrative-gender` to HL7 v2 Table 0001, the invertible rows of the IG's **HL70001 to
+ * Administrative Gender** map. `other` is absent on purpose: three source codes carry it.
+ *
+ * @example
+ * ```ts
+ * import { GENDER_TO_V2 } from "@cosyte/transform";
+ * GENDER_TO_V2["female"]; // => "F"
+ * GENDER_TO_V2["other"]; // => undefined (ambiguous inverse, flagged instead)
+ * ```
+ */
+declare const GENDER_TO_V2: Readonly<Record<string, string>>;
+/**
+ * FHIR `name-use` to HL7 v2 Table 0200, the invertible rows of the IG's **HL70200 to name-use** map.
+ * `official` and `temp` are absent on purpose: two source codes each.
+ *
+ * @example
+ * ```ts
+ * import { NAME_USE_TO_V2 } from "@cosyte/transform";
+ * NAME_USE_TO_V2["maiden"]; // => "M"
+ * ```
+ */
+declare const NAME_USE_TO_V2: Readonly<Record<string, string>>;
+/**
+ * FHIR `address-use` to HL7 v2 Table 0190, the invertible rows of the IG's **HL70190 to
+ * address-use** map. `work` is absent on purpose (`B` and `O`), as is every `Address.type` row.
+ *
+ * @example
+ * ```ts
+ * import { ADDRESS_USE_TO_V2 } from "@cosyte/transform";
+ * ADDRESS_USE_TO_V2["home"]; // => "H"
+ * ```
+ */
+declare const ADDRESS_USE_TO_V2: Readonly<Record<string, string>>;
+/**
+ * Convert a FHIR R4 `Patient` into a **complete** v2 message carrying a `PID` segment, for the
+ * demographics-only trigger events (`A28`, `A31`, `A29`, ...) that carry a patient with no visit.
+ *
+ * The `trigger` argument is **required and never inferred**: no `Patient` element maps to a v2
+ * message trigger, so the caller supplies it, and a missing, empty or non-string one returns
+ * `{ value: undefined }` plus {@link ISSUE_CODES.TRANSFORM_MISSING_TRIGGER} without calling the
+ * message builder at all. It is used verbatim as MSH-9.2 under the `ADT` message code this shape
+ * fixes; the caller never supplies the code and it never varies per call.
+ *
+ * Lossy by design and never round-trip-safe: a value the inverse of the IG map cannot ground is
+ * flagged and left absent, never guessed, and a resource of another type is refused outright.
+ *
+ * A `PID` field v2 requires (PID-3 Patient Identifier List, PID-5 Patient Name) that this resource
+ * gives no source for stays absent and is declared with
+ * {@link ISSUE_CODES.TRANSFORM_V2_REQUIRED_FIELD_ABSENT}: the emitted message is honest about what
+ * it lacks rather than padded to look conformant. A `Patient` that grounds no `PID` field at all
+ * yields no message and {@link ISSUE_CODES.TRANSFORM_NO_V2_MESSAGE_EMITTED}.
+ *
+ * @param resource - The FHIR `Patient` node (build one with `@cosyte/fhir`'s `parseResource`).
+ * @param trigger - The bare v2 trigger, e.g. `"A28"`. Required; never derived from the resource.
+ * @param options - Caller-vetted reverse context: assigning authorities, code systems, MSH envelope.
+ * @example
+ * ```ts
+ * import { parseResource } from "@cosyte/fhir";
+ * import { toV2Patient } from "@cosyte/transform";
+ *
+ * const { resource } = parseResource('{"resourceType":"Patient","gender":"female"}');
+ * const { value, issues } = toV2Patient(resource, "A28");
+ * // value.toString() starts "MSH|^~\\&|" and carries "ADT^A28" in MSH-9, then a PID segment
+ * void value;
+ * void issues;
+ * ```
+ */
+declare function toV2Patient(resource: FhirNode, trigger: string, options?: ReverseOptions): ReverseResult;
+
+/**
+ * FHIR `Observation` to a v2 message carrying an `OBX` segment: the inverse of the IG **Segment OBX
+ * to Observation** ConceptMap, over the rows whose inverse is defensible.
+ *
+ * | FHIR element | OBX field | inverse |
+ * |---|---|---|
+ * | `Observation.code` | OBX-3 (CWE) | coding to CWE.1/2/3 (+ one alternate triplet), `text` to CWE.9 |
+ * | `Observation.value[x]` | OBX-2 + OBX-5 | the value type OBX-2 declares is derived from which `value[x]` is present |
+ * | `Observation.valueQuantity` units | OBX-6 (CWE) | UCUM code/display, other systems flagged |
+ * | `Observation.referenceRange.text` | OBX-7 | carried verbatim, never composed from `low`/`high` |
+ * | `Observation.interpretation` | OBX-8 | v3 ObservationInterpretation codes the HL70078 map carries |
+ * | `Observation.status` | OBX-11 | Table 0085 where the map inverts |
+ * | `Observation.effectiveDateTime` | OBX-14 | lexical timestamp, precision preserved |
+ *
+ * **OBX-2 is derived, never assumed.** `valueQuantity` writes `NM` (or `SN` when the quantity
+ * carries a comparator, which is the only OBX-2 type that can hold one), `valueCodeableConcept`
+ * writes `CWE`, `valueString` writes `ST`, `valueDateTime` writes `DTM`. A `value[x]` with no
+ * faithful OBX-5 form (`valueRange`, `valueRatio`, `valueBoolean`, ...) writes **nothing** and is
+ * flagged: emitting the magnitude of a comparator-bearing or ranged value as a bare number would be
+ * a confidently wrong result, which is the one thing this library never does.
+ *
+ * `Observation.subject` and `.encounter` are flagged rather than emitted: this shape's input is an
+ * `Observation` alone, and a PID or PV1 assembled from a bare reference would be fabricated.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * FHIR `observation-status` to HL7 v2 Table 0085, the invertible rows of the IG's **HL70085 to
+ * Observation Status** map. `entered-in-error` is absent on purpose (`D` and `W` both carry it), as
+ * are the FHIR statuses the map never targets (`registered`, `unknown`).
+ *
+ * @example
+ * ```ts
+ * import { OBSERVATION_STATUS_TO_V2 } from "@cosyte/transform";
+ * OBSERVATION_STATUS_TO_V2["corrected"]; // => "C"
+ * OBSERVATION_STATUS_TO_V2["entered-in-error"]; // => undefined (ambiguous inverse, flagged instead)
+ * ```
+ */
+declare const OBSERVATION_STATUS_TO_V2: Readonly<Record<string, string>>;
+/**
+ * Convert a FHIR R4 `Observation` into a **complete** v2 message carrying an `OBX` segment, in the
+ * result-report (`ORU`) shape.
+ *
+ * The `trigger` argument is **required and never inferred**: no `Observation` element maps to a v2
+ * message trigger, so the caller supplies it, and a missing, empty or non-string one returns
+ * `{ value: undefined }` plus {@link ISSUE_CODES.TRANSFORM_MISSING_TRIGGER} without calling the
+ * message builder at all. It is used verbatim as MSH-9.2 under the `ORU` message code this shape
+ * fixes.
+ *
+ * The message carries the `OBX` alone: this shape's input is an `Observation`, which names no
+ * patient, and a subject segment assembled from a reference would be fabricated. Lossy by design and
+ * never round-trip-safe.
+ *
+ * An `OBX` field v2 requires (OBX-11 Observation Result Status) that this resource gives no source
+ * for stays absent and is declared with {@link ISSUE_CODES.TRANSFORM_V2_REQUIRED_FIELD_ABSENT},
+ * rather than defaulted to `F`: a result reported as final that the sender never called final is the
+ * confidently wrong value this library exists to refuse. An `Observation` that grounds no `OBX`
+ * field at all yields no message and {@link ISSUE_CODES.TRANSFORM_NO_V2_MESSAGE_EMITTED}.
+ *
+ * @param resource - The FHIR `Observation` node.
+ * @param trigger - The bare v2 trigger, e.g. `"R01"`. Required; never derived from the resource.
+ * @param options - Caller-vetted reverse context: code systems and the MSH envelope.
+ * @example
+ * ```ts
+ * import { parseResource } from "@cosyte/fhir";
+ * import { toV2Observation } from "@cosyte/transform";
+ *
+ * const { resource } = parseResource(
+ *   '{"resourceType":"Observation","status":"final","code":{"coding":[{"system":"http://loinc.org","code":"789-8"}]}}',
+ * );
+ * const { value, issues } = toV2Observation(resource, "R01");
+ * // value.toString() carries "ORU^R01" in MSH-9, then an OBX whose OBX-3 is "789-8^^LN"
+ * void value;
+ * void issues;
+ * ```
+ */
+declare function toV2Observation(resource: FhirNode, trigger: string, options?: ReverseOptions): ReverseResult;
+
 /**
  * Public entry point for `@cosyte/transform`: the HL7 v2 → FHIR R4 transformation library.
  *
@@ -1260,8 +2858,15 @@ declare function toFhirCodeableConceptVia(cwe: CodedElement, map: CodedValueMap,
  * 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
- * FHIR → v2 direction are not implemented.
+ * priority, substitution).
+ *
+ * It also ships a **narrow reverse path**, FHIR → v2: {@link toV2Patient} and
+ * {@link toV2Observation} emit a complete v2 message carrying a `PID` or an `OBX` built from the
+ * subset of the IG segment maps whose inverse is defensible. Each requires the caller to supply the
+ * v2 trigger, because no FHIR resource carries one. It is **lossy by design and not a round-trip**:
+ * a value the inverse of the IG map cannot ground is flagged and left absent, never guessed.
+ * Terminology **depth beyond these maps**, profiles, and any wider FHIR → v2 conversion are not
+ * implemented.
  *
  * @packageDocumentation
  */
@@ -1282,4 +2887,4 @@ declare function toFhirCodeableConceptVia(cwe: CodedElement, map: CodedValueMap,
  */
 declare const VERSION: string;
 
-export { ADDRESS_TYPE_MAP, ADDRESS_USE_MAP, ADMINISTRATIVE_GENDER_MAP, APPOINTMENT_STATUS_MAP, APPOINTMENT_TYPE_VALUE_MAP, type CodedElement, type CodedTarget, type CodedValueMap, type ConvertResult, DEFAULT_V2_CODE_SYSTEMS, DIAGNOSTIC_REPORT_STATUS_MAP, ENCOUNTER_CLASS_V3_MAP, ENCOUNTER_STATUS_MAP, FATAL_CODES, type FatalCode, HL70078_INTERPRETATION_CODES, IG_MAPPED_ADT_TRIGGERS, IG_MAPPED_APPOINTMENT_TRIGGERS, IG_MAPPED_DOCUMENT_TRIGGERS, IG_MAPPED_IMMUNIZATION_TRIGGERS, IG_MAPPED_ORDER_TRIGGERS, IG_MAPPED_ORU_TRIGGERS, IMMUNIZATION_STATUS_MAP, ISSUE_CODES, ISSUE_REGISTRY, type IssueCode, NAME_USE_MAP, type NamingSystemRegistry, type NamingSystemSeed, OBSERVATION_STATUS_MAP, REQUEST_STATUS_MAP, ROUTE_VALUE_MAP, SERVICE_REQUEST_PRIORITY_MAP, SITE_VALUE_MAP, SUBSTITUTION_VALUE_MAP, TRANSFORM_ISSUE_SYSTEM, type TransformContext, type TransformIssue, type TransformOptions, type TransformResult, type TransformSeverity, V2_0161_SYSTEM, V2_0162_SYSTEM, V2_0203_SYSTEM, V2_0277_SYSTEM, V2_0550_SYSTEM, V3_ROUTE_OF_ADMINISTRATION_SYSTEM, VERSION, codeableConceptFromTarget, createNamingSystem, fhirIssueTypeFor, issue, toFhir, toFhirAddress, toFhirCodeableConcept, toFhirCodeableConceptVia, toFhirDateTime, toFhirHumanName, toFhirIdentifier, toFhirQuantity, toOperationOutcome, translateBound };
+export { ADDRESS_TYPE_MAP, ADDRESS_USE_MAP, ADDRESS_USE_TO_V2, ADMINISTRATIVE_GENDER_MAP, AL1_ONSET_WITHDRAWN_AT, ALLERGY_CATEGORY_VALUE_MAP, ALLERGY_CLINICAL_STATUS_CODE, ALLERGY_CLINICAL_STATUS_SYSTEM, ALLERGY_CRITICALITY_VALUE_MAP, ALLERGY_INTOLERANCE_CATEGORY_SYSTEM, ALLERGY_INTOLERANCE_CRITICALITY_SYSTEM, ALLERGY_INTOLERANCE_TYPE_SYSTEM, ALLERGY_ORIGINAL_CATEGORY_VALUE_MAP, ALLERGY_ORIGINAL_CRITICALITY_VALUE_MAP, ALLERGY_TYPE_VALUE_MAP, ALTERNATE_CODES_EXTENSION_URL, APPOINTMENT_STATUS_MAP, APPOINTMENT_TYPE_VALUE_MAP, type AllergyBuildOptions, CONDITION_ENTERED_IN_ERROR, CONDITION_VERIFICATION_STATUS_SYSTEM, COVERAGE_STATUS_UNKNOWN, COVERAGE_SUBSCRIBER_ID_EXTENSION_URL, type CodedElement, type CodedTarget, type CodedValueMap, type ConvertResult, DEFAULT_V2_CODE_SYSTEMS, DG1_RETRACTION_ACTION_CODE, DIAGNOSTIC_REPORT_STATUS_MAP, ED_BASE64_ENCODING, ENCOUNTER_CLASS_V3_MAP, ENCOUNTER_STATUS_MAP, type EntityIdentifier, FATAL_CODES, type FatalCode, GENDER_TO_V2, HL70078_INTERPRETATION_CODES, IG_ALLERGY_VALUE_MAPS_PUBLISHED, IG_ALLERGY_VALUE_MAPS_RETRIEVED, IG_ALLERGY_VALUE_MAPS_SOURCE, IG_ALLERGY_VALUE_MAPS_VERSION, IG_MAPPED_ADT_TRIGGERS, IG_MAPPED_APPOINTMENT_TRIGGERS, IG_MAPPED_DOCUMENT_TRIGGERS, IG_MAPPED_IMMUNIZATION_TRIGGERS, IG_MAPPED_ORDER_TRIGGERS, IG_MAPPED_ORU_TRIGGERS, IG_MAPPED_SEGMENT_NAMES, IG_SEGMENT_MAPS_PUBLISHED, IG_SEGMENT_MAPS_RETRIEVED, IG_SEGMENT_MAPS_SOURCE, IG_SEGMENT_MAPS_VERSION, IMMUNIZATION_STATUS_MAP, IN1_SUBSCRIBER_NUMBER_TYPE, ISSUE_CODES, ISSUE_REGISTRY, type IssueCode, NAME_USE_MAP, NAME_USE_TO_V2, type NamingSystemRegistry, type NamingSystemSeed, OBSERVATION_STATUS_MAP, OBSERVATION_STATUS_TO_V2, OBSERVATION_VALUE_ATTACHMENT_EXTENSION_URL, PROCEDURE_STATUS_UNKNOWN, REQUEST_STATUS_MAP, ROUTE_VALUE_MAP, type ReverseOptions, type ReverseResult, SAMPLED_DATA_ABSENT_POINT, SAMPLED_DATA_UNGROUNDED, SEGMENT_IDENTIFIER_SHAPE, SERVICE_REQUEST_PRIORITY_MAP, SITE_VALUE_MAP, SPM_SHIPMENT_IDENTIFIER_TYPE, SUBSTITUTION_VALUE_MAP, type SegmentOccurrence, SegmentReachLedger, TRANSFORM_ISSUE_SYSTEM, type TransformContext, type TransformIssue, type TransformOptions, type TransformResult, type TransformSeverity, V2_0127_SYSTEM, V2_0128_SYSTEM, V2_0161_SYSTEM, V2_0162_SYSTEM, V2_0203_SYSTEM, V2_0277_SYSTEM, V2_0550_SYSTEM, V3_OBSERVATION_INTERPRETATION_SYSTEM, V3_ROUTE_OF_ADMINISTRATION_SYSTEM, VERSION, addMinutes, buildAnnotations, buildCondition, buildCoverage, buildProcedure, buildSpecimen, carriesLegacyOnsetDate, codeableConceptFromTarget, collectAllergies, collectCoverages, collectDiagnoses, collectProcedures, createNamingSystem, deferredCoverageIssues, deferredDiagnosisIssues, deferredProcedureIssues, emitEncounterDiagnosis, enumerateSegmentOccurrences, fhirIssueTypeFor, insuranceCompanyName, invertCodeMap, isIgMappedSegmentName, isWellFormedSegmentName, issue, segmentOccurrenceLocation, toFhir, toFhirAddress, toFhirCodeableConcept, toFhirCodeableConceptVia, toFhirDateTime, toFhirEntityIdentifier, toFhirHumanName, toFhirIdentifier, toFhirQuantity, toOperationOutcome, toV2Observation, toV2Patient, translateBound, withCodeableText, withEncounterDiagnosis };