@cosyte/transform 0.0.2

package/dist/index.d.ts

@@ -0,0 +1,1271 @@
+import { FhirComplex } from '@cosyte/fhir';
+import { HD, TS, CX, CWE, XPN, XAD, NM, Hl7Message } from '@cosyte/hl7';
+
+/**
+ * The stable code registries for the `@cosyte/transform` diagnostic channel.
+ *
+ * Two registries, both `key === value` so they survive `Object.values(...)` into a snapshot
+ * tripwire, and both **part of the public contract**: consumers branch on these codes, so renaming
+ * or removing one is a **breaking change** (mirrors the parser archetype's stable-warning-code rule).
+ * New codes are **additions only**.
+ *
+ * - {@link ISSUE_CODES} — non-fatal, typed diagnostics carried on a {@link TransformResult}. Every
+ *   fail-safe decision the transform makes (a naked timestamp, an unresolvable assigning authority,
+ *   an unmapped code, a non-UCUM unit, a dropped element) surfaces as one of these — **never** a
+ *   silently-defaulted or fabricated FHIR value.
+ * - {@link FATAL_CODES} — the small set of unrecoverable conditions reserved for message-level
+ *   entry points. **Nothing in this library throws one today**: the datatype converters and
+ *   `toFhir` alike fail safe to a value-free issue instead.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Stable **non-fatal issue codes** — the typed diagnostics the fail-safe rule emits.
+ *
+ * @example
+ * ```ts
+ * import { ISSUE_CODES } from "@cosyte/transform";
+ * if (issue.code === ISSUE_CODES.TRANSFORM_TIMESTAMP_NO_TIMEZONE) {
+ *   // a v2 timestamp had a time-of-day but no timezone offset — reduced to date precision
+ * }
+ * ```
+ */
+declare const ISSUE_CODES: {
+    /** A v2 DTM/TS carried a time-of-day but no timezone offset. FHIR forbids time-without-zone, so
+     * the value was reduced to date precision (or an explicit sender offset applied via options) —
+     * **never** a guessed UTC. */
+    readonly TRANSFORM_TIMESTAMP_NO_TIMEZONE: "TRANSFORM_TIMESTAMP_NO_TIMEZONE";
+    /** A v2 DTM/TS could not be parsed into a valid FHIR date/time; no value was emitted. */
+    readonly TRANSFORM_TIMESTAMP_INVALID: "TRANSFORM_TIMESTAMP_INVALID";
+    /** The assigning authority (HD) could not be resolved to a FHIR `Identifier.system` URI via the
+     * NamingSystem registry. The identifier is emitted with its value and **no** system — a system URI
+     * is **never** synthesized from HD.1 alone. */
+    readonly TRANSFORM_IDENTIFIER_SYSTEM_UNRESOLVED: "TRANSFORM_IDENTIFIER_SYSTEM_UNRESOLVED";
+    /** A coded value could not be mapped to a FHIR concept — either it carried no coding-system context
+     * (CWE.3 absent), or it is a table code the IG ConceptMap has **no target** for (e.g. an OBX-11/
+     * OBR-25 result status the HL70085/HL70123 map does not carry, or an OBX-8 abnormal flag absent from
+     * HL70078). The original code is preserved / the FHIR value left absent; **never** coerced to a
+     * neighbor and **never** guessed to `final`/`normal`. */
+    readonly TRANSFORM_CODE_UNMAPPED: "TRANSFORM_CODE_UNMAPPED";
+    /** A coding-system mnemonic (CWE.3 / CWE.6) was not recognized, so no canonical system URI could
+     * be emitted. The code is preserved; a URI is **never** invented. */
+    readonly TRANSFORM_CODE_SYSTEM_UNRESOLVED: "TRANSFORM_CODE_SYSTEM_UNRESOLVED";
+    /** A unit was not a valid UCUM code (or was not declared UCUM). It is preserved verbatim in
+     * `Quantity.unit`; `Quantity.code`/`.system` are left absent — a UCUM code is **never** fabricated
+     * and a magnitude is **never** converted. */
+    readonly TRANSFORM_UNIT_NOT_UCUM: "TRANSFORM_UNIT_NOT_UCUM";
+    /** A v2 numeric value (NM) could not be represented as a FHIR `decimal` without altering it — e.g.
+     * a leading `+`, a leading zero, or a trailing dot, which FHIR's `decimal` lexical form forbids. No
+     * `Quantity` value is emitted rather than a canonicalized (and therefore altered) magnitude. */
+    readonly TRANSFORM_QUANTITY_VALUE_INVALID: "TRANSFORM_QUANTITY_VALUE_INVALID";
+    /** A populated source element was not carried to its FHIR target and was dropped — either because
+     * the IG map defines no target, or because that target's conversion is **not implemented**
+     * (e.g. XTN→ContactPoint telecom, PV1 participants). Surfaced here rather than silently discarded,
+     * never a fabricated value. */
+    readonly TRANSFORM_ELEMENT_DROPPED: "TRANSFORM_ELEMENT_DROPPED";
+    /** An XPN.7 name-type code has no equivalent in the IG's HL70200 → name-use ConceptMap;
+     * `HumanName.use` is left absent rather than guessed. */
+    readonly TRANSFORM_NAME_USE_UNMAPPED: "TRANSFORM_NAME_USE_UNMAPPED";
+    /** An XAD.7 address-type code has no equivalent in the IG's HL70190 → address-use/type
+     * ConceptMaps; `Address.use`/`.type` are left absent rather than guessed. */
+    readonly TRANSFORM_ADDRESS_USE_UNMAPPED: "TRANSFORM_ADDRESS_USE_UNMAPPED";
+    /** The message's trigger event has no IG *message* map, so its resource graph was assembled from
+     * the reusable IG *segment* maps rather than a message map. The graph is best-effort and flagged
+     * as such — never a fabricated message map. */
+    readonly TRANSFORM_SEGMENT_ASSEMBLED: "TRANSFORM_SEGMENT_ASSEMBLED";
+    /** A produced FHIR resource failed `@cosyte/fhir` R4 structural validation and was **withheld**
+     * from the bundle rather than emitted as a silently-invalid resource — the conservative-emit gate. */
+    readonly TRANSFORM_RESOURCE_INVALID: "TRANSFORM_RESOURCE_INVALID";
+    /** A FHIR-required element's value could not be faithfully derived from the source, so it was
+     * emitted with a `data-absent-reason` extension (value `unknown`) rather than fabricated — e.g.
+     * `MessageHeader.source.endpoint` from an MSH-3 application namespace that is not a URL. */
+    readonly TRANSFORM_REQUIRED_ELEMENT_UNKNOWN: "TRANSFORM_REQUIRED_ELEMENT_UNKNOWN";
+};
+/** A value from {@link ISSUE_CODES} — the type consumers narrow `issue.code` against. */
+type IssueCode = (typeof ISSUE_CODES)[keyof typeof ISSUE_CODES];
+/**
+ * Stable **fatal codes** — the reserved names for unrecoverable input conditions. **Nothing in this
+ * library throws one today**; every path, datatype and message level alike, fails safe to a
+ * value-free issue instead. They are declared so that a future one is an addition rather than a
+ * rename.
+ *
+ * @example
+ * ```ts
+ * import { FATAL_CODES } from "@cosyte/transform";
+ * void FATAL_CODES.EMPTY_INPUT;
+ * ```
+ */
+declare const FATAL_CODES: {
+    /** The input carried nothing to transform. */
+    readonly EMPTY_INPUT: "EMPTY_INPUT";
+    /** The input was not a shape this transform accepts. */
+    readonly TRANSFORM_UNSUPPORTED_INPUT: "TRANSFORM_UNSUPPORTED_INPUT";
+};
+/** A value from {@link FATAL_CODES} — the type carried by a thrown fatal error. */
+type FatalCode = (typeof FATAL_CODES)[keyof typeof FATAL_CODES];
+
+/**
+ * The value-free {@link TransformIssue} — the single diagnostic shape the whole library emits.
+ *
+ * Every issue is **`OperationOutcome`-shaped and PHI-safe by construction**: it carries the *v2
+ * location* (segment / field / component index — never a value) and the *FHIR path* it concerns,
+ * plus a **static, per-code** severity and human-readable message drawn from {@link ISSUE_REGISTRY}.
+ * Nothing in an issue is interpolated from patient data — the factory takes only positional metadata,
+ * so there is no code path by which a name, DOB, MRN, or result value can reach a log line (the
+ * discipline `@cosyte/fhir` already proved with its value-free `OperationOutcome`).
+ *
+ * @packageDocumentation
+ */
+
+/** The severity a {@link TransformIssue} carries — an `OperationOutcome.issue.severity` value. */
+type TransformSeverity = "error" | "warning" | "information";
+/**
+ * A single value-free diagnostic.
+ *
+ * @example
+ * ```ts
+ * import { ISSUE_CODES } from "@cosyte/transform";
+ * // issue.code === ISSUE_CODES.TRANSFORM_TIMESTAMP_NO_TIMEZONE
+ * // issue.v2Location === "TS.1"; issue.fhirPath === "dateTime"
+ * ```
+ */
+interface TransformIssue {
+    /** The stable code. One of {@link ISSUE_CODES}. */
+    readonly code: IssueCode;
+    /** The `OperationOutcome`-style severity, fixed per code. */
+    readonly severity: TransformSeverity;
+    /** The v2 source location — a segment / field / component **index**, never a value. */
+    readonly v2Location: string;
+    /** The FHIR path this issue concerns (e.g. `Identifier.system`), when applicable. */
+    readonly fhirPath?: string;
+    /** A static, value-free description drawn from {@link ISSUE_REGISTRY}. */
+    readonly message: string;
+}
+/** The fixed metadata for a code: its severity, its FHIR `issue-type` code, and a static message. */
+interface IssueMeta {
+    readonly severity: TransformSeverity;
+    /** The FHIR `OperationOutcome.issue.code` (R4 `issue-type` value set) this maps to. */
+    readonly fhirIssueType: string;
+    /** A static, value-free message. Contains no interpolated data — safe to log verbatim. */
+    readonly message: string;
+}
+/**
+ * The per-code registry: severity, FHIR `issue-type`, and a static message. Frozen and exhaustive
+ * over {@link ISSUE_CODES} (enforced by the `Record<IssueCode, …>` type — a new code will not
+ * compile until it has an entry).
+ */
+declare const ISSUE_REGISTRY: Readonly<Record<IssueCode, IssueMeta>>;
+/**
+ * Construct a value-free {@link TransformIssue}. The severity and message come from
+ * {@link ISSUE_REGISTRY}; the caller supplies only positional metadata, so an issue can carry no PHI.
+ *
+ * @param code - The stable {@link IssueCode}.
+ * @param v2Location - The v2 source location (segment / field / component index) — never a value.
+ * @param fhirPath - The FHIR path the issue concerns, when applicable.
+ * @example
+ * ```ts
+ * import { issue, ISSUE_CODES } from "@cosyte/transform";
+ * const i = issue(ISSUE_CODES.TRANSFORM_TIMESTAMP_NO_TIMEZONE, "TS.1", "dateTime");
+ * void i.severity; // "warning"
+ * ```
+ */
+declare function issue(code: IssueCode, v2Location: string, fhirPath?: string): TransformIssue;
+/**
+ * The FHIR `issue-type` code for an {@link IssueCode} — used by the `OperationOutcome` renderer.
+ *
+ * @param code - The stable {@link IssueCode}.
+ * @example
+ * ```ts
+ * import { fhirIssueTypeFor, ISSUE_CODES } from "@cosyte/transform";
+ * fhirIssueTypeFor(ISSUE_CODES.TRANSFORM_IDENTIFIER_SYSTEM_UNRESOLVED); // "not-found"
+ * ```
+ */
+declare function fhirIssueTypeFor(code: IssueCode): string;
+
+/**
+ * The {@link ConvertResult} envelope every datatype converter returns.
+ *
+ * A converter never throws on ambiguity and never returns a "confident wrong" value: it returns the
+ * FHIR value it could faithfully produce (or `undefined` when nothing can be safely emitted) together
+ * with the value-free {@link TransformIssue}s it raised. This is the fail-safe rule as a type.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * The result of one datatype conversion: the produced FHIR value (or `undefined` when the input was
+ * empty or un-emittable) plus the diagnostics raised.
+ *
+ * @template T - The produced FHIR value's type (a `FhirComplex` datatype node, or a lexical string
+ *   for `dateTime`).
+ *
+ * @example
+ * ```ts
+ * import { toFhirHumanName } from "@cosyte/transform";
+ * const { value, issues } = toFhirHumanName({ familyName: "Public" });
+ * // value is a FHIR HumanName node; issues is [] here
+ * void value;
+ * void issues;
+ * ```
+ */
+interface ConvertResult<T> {
+    /** The produced FHIR value, or `undefined` when nothing could be safely emitted. */
+    readonly value: T | undefined;
+    /** The value-free diagnostics raised during the conversion, in emission order. */
+    readonly issues: readonly TransformIssue[];
+}
+
+/**
+ * Render a list of {@link TransformIssue}s as a FHIR `OperationOutcome` resource model.
+ *
+ * The transform's diagnostic channel is `OperationOutcome`-shaped by design; this is the adapter that
+ * materializes it as an actual `@cosyte/fhir` resource node a consumer can serialize, validate, or
+ * return alongside a bundle. It is **value-free**: every field is drawn from the issue's static
+ * metadata (code, severity, message) and its positional locations (v2 location → `diagnostics`, FHIR
+ * path → `expression`) — no patient data is reachable here.
+ *
+ * @packageDocumentation
+ */
+
+/** The code system under which the transform's stable issue codes are carried in `details.coding`. */
+declare const TRANSFORM_ISSUE_SYSTEM = "https://cosyte.com/fhir/CodeSystem/transform-issue-codes";
+/**
+ * Build a FHIR `OperationOutcome` {@link FhirComplex} from the given issues. An empty list still
+ * produces a structurally-valid `OperationOutcome` with a single `information` "all clear" issue
+ * (FHIR requires `OperationOutcome.issue` to be non-empty).
+ *
+ * @param issues - The value-free diagnostics to render.
+ * @example
+ * ```ts
+ * import { toOperationOutcome } from "@cosyte/transform";
+ * const oo = toOperationOutcome([]);
+ * // oo is a FhirComplex resource node with resourceType "OperationOutcome"
+ * void oo;
+ * ```
+ */
+declare function toOperationOutcome(issues: readonly TransformIssue[]): FhirComplex;
+
+/**
+ * The NamingSystem registry — how an HL7 v2 identity/coding namespace becomes a FHIR canonical URI.
+ *
+ * Two resolutions live here, and both are **fail-safe by refusal**:
+ *
+ * 1. **Assigning authority (HD) → `Identifier.system`.** The IG's CX→Identifier map says CX.4 maps to
+ *    `Identifier.system` *only when the authority is in an identifier registry* — the URI comes from a
+ *    NamingSystem lookup, **not** string concatenation. There is no deterministic algorithm from an
+ *    HD to a URI, so this resolver **never synthesizes a system from HD.1 (the bare namespace
+ *    mnemonic) alone** — doing so would let two hospitals reusing "MR"/"HOSPMRN" collide and merge two
+ *    patients. The *only* auto-derivations are the unambiguous ones: `urn:oid:<oid>` when HD.2 is a
+ *    valid OID with HD.3 = `ISO`, and `urn:uuid:<uuid>` when HD.3 = `UUID`. Everything else must be an
+ *    explicit, caller-seeded registry entry, or it resolves to `undefined` and the caller emits a
+ *    typed issue.
+ *
+ * 2. **v2 coding-system mnemonic → canonical URI.** CWE.3/CWE.6 carry a v2 Table 0396 mnemonic
+ *    (`LN`, `SCT`, …); FHIR needs the canonical URI (`http://loinc.org`, …). {@link DEFAULT_V2_CODE_SYSTEMS}
+ *    seeds a small, license-clean set of the universally-fixed FHIR-core systems; an unrecognized
+ *    mnemonic resolves to `undefined` (the caller preserves the raw code and flags it — a URI is
+ *    never invented). The full HL7 THO crosswalk is not bundled.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * The HL7 v2 Table 0203 identifier-type code system canonical URI — used to build `Identifier.type`.
+ * (FHIR R4 terminologies-systems.html)
+ */
+declare const V2_0203_SYSTEM = "http://terminology.hl7.org/CodeSystem/v2-0203";
+/**
+ * A small, license-clean seed of v2 Table 0396 coding-system mnemonic → canonical URI, for the
+ * FHIR-core-fixed systems whose URIs are universally cited (FHIR R4 terminologies-systems.html).
+ * The full HL7 THO NamingSystem crosswalk is not bundled; callers extend this via
+ * {@link createNamingSystem}. **No terminology *content* is bundled — only identity URIs.**
+ */
+declare const DEFAULT_V2_CODE_SYSTEMS: Readonly<Record<string, string>>;
+/** A seed for {@link createNamingSystem}: extra coding systems and explicit assigning authorities. */
+interface NamingSystemSeed {
+    /** Extra v2 coding-system mnemonic → canonical URI entries (merged over the defaults). */
+    readonly codeSystems?: Readonly<Record<string, string>>;
+    /**
+     * Explicit assigning-authority entries, keyed by **HD.1 namespace mnemonic** and/or **HD.2
+     * universal ID (OID)** → the `Identifier.system` URI. This is the safe, caller-vetted path the IG
+     * calls for; the registry never derives a system from a mnemonic on its own.
+     */
+    readonly authorities?: Readonly<Record<string, string>>;
+}
+/** The resolver consulted by the identity- and code-conversion paths. */
+interface NamingSystemRegistry {
+    /**
+     * Resolve an assigning authority (HD) to a FHIR `Identifier.system` URI, or `undefined` when it
+     * cannot be resolved safely. **Never** synthesizes a URI from HD.1 alone.
+     */
+    readonly resolveAssigningAuthority: (hd: HD) => string | undefined;
+    /** Resolve a v2 coding-system mnemonic to a canonical URI, or `undefined` when unrecognized. */
+    readonly resolveCodeSystem: (mnemonic: string) => string | undefined;
+}
+/**
+ * Create a {@link NamingSystemRegistry}. With no seed it resolves the built-in FHIR-core code systems
+ * and the two unambiguous HD auto-derivations (OID/UUID); a seed adds caller-vetted code systems and
+ * explicit assigning-authority URIs.
+ *
+ * @example
+ * ```ts
+ * import { createNamingSystem } from "@cosyte/transform";
+ * const registry = createNamingSystem({
+ *   authorities: { HOSPMRN: "urn:oid:1.2.840.114350.1.13.1" },
+ * });
+ * registry.resolveCodeSystem("LN"); // => "http://loinc.org"
+ * ```
+ */
+declare function createNamingSystem(seed?: NamingSystemSeed): NamingSystemRegistry;
+
+/**
+ * The options and context threaded through the datatype converters.
+ *
+ * These are **types only** — no runtime behavior. {@link TransformOptions} carries the policy knobs a
+ * caller can set; {@link TransformContext} additionally carries the
+ * {@link NamingSystemRegistry} the identity- and code-resolution paths consult.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Caller/profile policy for a conversion.
+ *
+ * @remarks
+ * `assumeTimezoneOffsetMinutes` is the **only** way a naked v2 timestamp acquires a time-of-day in
+ * FHIR: the caller asserts the sender's offset (in minutes east of UTC — e.g. `-300` for US Eastern
+ * standard time). It is a *sender-asserted* value, flagged as such; absent it, a naked timestamp is
+ * reduced to date precision, **never** assumed to be UTC.
+ */
+interface TransformOptions {
+    /** The sender's UTC offset in minutes, asserted by the caller to resolve naked timestamps. */
+    readonly assumeTimezoneOffsetMinutes?: number;
+    /**
+     * The {@link NamingSystemRegistry} the message-level transform threads into every datatype
+     * conversion (HD → `Identifier.system`, v2 mnemonic → canonical URI). When omitted, a default
+     * registry (`createNamingSystem()`) is used — it resolves only the FHIR-core-fixed systems and the
+     * two unambiguous HD auto-derivations, so an un-seeded assigning authority surfaces a typed issue
+     * rather than a guessed system.
+     */
+    readonly namingSystem?: NamingSystemRegistry;
+    /**
+     * Allocator for the `urn:uuid:` `Bundle.entry.fullUrl` / reference identities the assembler mints.
+     * Defaults to `crypto.randomUUID`. Inject a deterministic generator to make bundle output
+     * reproducible (e.g. for golden fixtures). It must return a fresh, unique value per call — the
+     * assembler relies on uniqueness for intra-bundle reference integrity.
+     */
+    readonly generateId?: () => string;
+}
+/**
+ * The context a converter consults. Carries the {@link NamingSystemRegistry} used to resolve an
+ * assigning authority (HD) to an `Identifier.system` and a v2 coding-system mnemonic to a canonical
+ * URI, plus the {@link TransformOptions}.
+ */
+interface TransformContext {
+    /** The registry used to resolve HD → system and v2 mnemonic → canonical URI. */
+    readonly namingSystem?: NamingSystemRegistry;
+    /** Conversion policy. */
+    readonly options?: TransformOptions;
+}
+
+/**
+ * DTM / TS → FHIR `dateTime` — the single most dangerous conversion.
+ *
+ * Grounded on the IG datatype ConceptMap **DTM → dateTime** (`DTM.1` *is equivalent to* the FHIR
+ * `dateTime.$value`, with the instruction to "convert v2 date time format to FHIR date time format")
+ * and the **FHIR core datatype rule** it defers to: *"if hours and minutes are specified, a timezone
+ * offset SHALL be populated"*, and the R4 `dateTime` grammar requires **full `hh:mm:ss` with an
+ * offset** whenever a time is present. Two fail-safe consequences follow:
+ *
+ * - **Naked timestamp (no offset).** A `20260721143000` cannot become a valid zoned FHIR `dateTime`
+ *   without inventing an offset — assuming UTC would silently shift the clinical instant by hours. So
+ *   the value is **reduced to date precision** (`2026-07-21`) and {@link ISSUE_CODES.TRANSFORM_TIMESTAMP_NO_TIMEZONE}
+ *   is raised — unless the caller asserts the sender's offset via `options.assumeTimezoneOffsetMinutes`.
+ * - **Partial-precision time (hour/minute only).** FHIR cannot represent `hh` or `hh:mm` without
+ *   seconds, and padding `:00` would fabricate precision, so such a value is likewise reduced to date
+ *   precision and flagged — never padded.
+ *
+ * Date-only precisions (`2026`, `2026-07`, `2026-07-21`) are preserved exactly — never zero-filled —
+ * and need no offset (FHIR permits a bare date).
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Convert a parsed HL7 v2 timestamp to a FHIR `dateTime` lexical string, fail-safe on timezone and
+ * precision. Returns `{ value: undefined }` only when the timestamp is unparseable.
+ *
+ * @param ts - A parsed `@cosyte/hl7` `TS` (`DtmParts`).
+ * @param options - Conversion policy; `assumeTimezoneOffsetMinutes` supplies a sender-asserted offset.
+ * @example
+ * ```ts
+ * import { parseDtm } from "@cosyte/hl7";
+ * import { toFhirDateTime } from "@cosyte/transform";
+ * const { value } = toFhirDateTime(parseDtm("20260721"));
+ * // value === "2026-07-21"
+ * void value;
+ * ```
+ */
+declare function toFhirDateTime(ts: TS, options?: TransformOptions): ConvertResult<string>;
+
+/**
+ * CX → FHIR `Identifier` — the patient-identity-integrity path.
+ *
+ * Grounded on the IG datatype ConceptMap **CX → Identifier**: `CX.1` → `Identifier.value`, `CX.4`
+ * (assigning authority HD) → `Identifier.system` *when the authority resolves in a registry* (else
+ * the IG maps it to `Identifier.assigner` — a message-level Organization reference this library does
+ * not build), and `CX.5` (Table 0203) → `Identifier.type`.
+ *
+ * The load-bearing fail-safe: the assigning authority is resolved through the
+ * {@link NamingSystemRegistry}, which **never synthesizes a system URI from HD.1 (the bare namespace)
+ * alone** — two hospitals reusing "MR"/"HOSPMRN" would otherwise collide and merge two patients. On
+ * an unresolved authority the identifier is emitted with its **value and no system**, plus a typed
+ * {@link ISSUE_CODES.TRANSFORM_IDENTIFIER_SYSTEM_UNRESOLVED} issue — never a guessed system.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Convert a parsed HL7 v2 CX to a FHIR `Identifier` node, fail-safe on the assigning authority.
+ * Returns `{ value: undefined }` when the CX carries no identifier value at all.
+ *
+ * @param cx - A parsed `@cosyte/hl7` `CX`.
+ * @param ctx - The transform context; `ctx.namingSystem` resolves the assigning authority (HD).
+ * @example
+ * ```ts
+ * import { toFhirIdentifier, createNamingSystem } from "@cosyte/transform";
+ * const { value, issues } = toFhirIdentifier(
+ *   { idNumber: "12345", assigningAuthority: { namespaceId: "HOSPMRN" } },
+ *   { namingSystem: createNamingSystem() },
+ * );
+ * // no registry entry for a bare "HOSPMRN" namespace → value emitted, system absent, one issue
+ * void value;
+ * void issues;
+ * ```
+ */
+declare function toFhirIdentifier(cx: CX, ctx?: TransformContext): ConvertResult<FhirComplex>;
+
+/**
+ * CWE / CE → FHIR `CodeableConcept` — the code-fidelity path.
+ *
+ * Grounded on the IG datatype ConceptMap **CWE → CodeableConcept**: `CWE.1`→`coding[0].code`,
+ * `CWE.2`→`coding[0].display`, `CWE.3`→`coding[0].system` **(indirect — the vocabulary table gives
+ * the actual URI)**, `CWE.7`→`coding[0].version`, the alternate triplet `CWE.4/5/6`→`coding[1]` (+
+ * `CWE.8`→`coding[1].version`), and `CWE.9`→`text`. `CE` is the 6-component subset of `CWE` and maps
+ * through the same shape.
+ *
+ * Two fail-safes, neither of which ever fabricates a code:
+ * - **Unrecognized coding-system mnemonic** (CWE.3/CWE.6) → the code is preserved with **no system**,
+ *   flagged {@link ISSUE_CODES.TRANSFORM_CODE_SYSTEM_UNRESOLVED}. A canonical URI is never invented.
+ * - **A bare code with no coding system at all** (CWE.1 present, CWE.3 absent) → preserved verbatim,
+ *   flagged {@link ISSUE_CODES.TRANSFORM_CODE_UNMAPPED}. Never coerced to a plausible neighbor.
+ *
+ * This converter does **no ConceptMap value translation** (that is
+ * `toFhirCodeableConceptVia`); it recognizes systems and preserves codes.
+ *
+ * @packageDocumentation
+ */
+
+/** The subset of CWE fields a CE also provides — so `toFhirCodeableConcept` accepts both. */
+type CodedElement = Pick<CWE, "identifier" | "text" | "nameOfCodingSystem" | "alternateIdentifier" | "alternateText" | "nameOfAlternateCodingSystem" | "codingSystemVersionId" | "alternateCodingSystemVersionId" | "originalText">;
+/**
+ * Convert a parsed HL7 v2 CWE (or CE) to a FHIR `CodeableConcept` node, fail-safe on the coding
+ * system and on unmapped codes. Returns `{ value: undefined }` when the element is empty.
+ *
+ * @param cwe - A parsed `@cosyte/hl7` `CWE` (a `CE` is accepted as its subset).
+ * @param ctx - The transform context; `ctx.namingSystem` resolves the coding-system mnemonic.
+ * @example
+ * ```ts
+ * import { toFhirCodeableConcept, createNamingSystem } from "@cosyte/transform";
+ * const { value } = toFhirCodeableConcept(
+ *   { identifier: "789-8", text: "Hemoglobin", nameOfCodingSystem: "LN" },
+ *   { namingSystem: createNamingSystem() },
+ * );
+ * // coding[0] === { system: "http://loinc.org", code: "789-8", display: "Hemoglobin" }
+ * void value;
+ * ```
+ */
+declare function toFhirCodeableConcept(cwe: CodedElement, ctx?: TransformContext): ConvertResult<FhirComplex>;
+
+/**
+ * XPN → FHIR `HumanName`.
+ *
+ * Grounded on the IG datatype ConceptMap **XPN → HumanName**: `XPN.1`→`family`, `XPN.2`→`given[0]`,
+ * `XPN.3`→`given[1]`, `XPN.4`→`suffix`, `XPN.5`→`prefix`, `XPN.6` (degree)→`suffix`,
+ * `XPN.7`→`use` (via the IG **HL70200 → name-use** ConceptMap), `XPN.14` (professional suffix)→`suffix`.
+ *
+ * `XPN.7`→`use` is a **lossy code translation**: only the codes the IG's HL70200→name-use map covers
+ * are translated; any other name-type code leaves `use` **absent** and raises
+ * {@link ISSUE_CODES.TRANSFORM_NAME_USE_UNMAPPED} — never guessed. Not converted, and flagged:
+ * the name-validity period (`XPN.12`/`XPN.13`), whose FHIR `period` needs the timezone policy of the
+ * dateTime path.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * HL7 v2 Table 0200 name-type code → FHIR `name-use`, exactly per the IG **HL70200 → name-use**
+ * ConceptMap (every row is "is equivalent to"). Codes absent here (A, B, C, F, I, K, NB, NOUSE, P,
+ * REL, S, T, U, …) have **no FHIR equivalent** and are surfaced, never guessed.
+ */
+declare const NAME_USE_MAP: Readonly<Record<string, string>>;
+/**
+ * Convert a parsed HL7 v2 XPN to a FHIR `HumanName` node. Returns `{ value: undefined }` when the
+ * name carries no emittable part.
+ *
+ * @param xpn - A parsed `@cosyte/hl7` `XPN`.
+ * @example
+ * ```ts
+ * import { toFhirHumanName } from "@cosyte/transform";
+ * const { value } = toFhirHumanName({ familyName: "Public", givenName: "Jane", nameTypeCode: "L" });
+ * // value === HumanName { use: "official", family: "Public", given: ["Jane"] }
+ * void value;
+ * ```
+ */
+declare function toFhirHumanName(xpn: XPN): ConvertResult<FhirComplex>;
+
+/**
+ * XAD → FHIR `Address`.
+ *
+ * Grounded on the IG datatype ConceptMap **XAD → Address**: `XAD.1`/`XAD.2`→`line`, `XAD.3`→`city`,
+ * `XAD.4`→`state`, `XAD.5`→`postalCode`, `XAD.6`→`country`, `XAD.9` (county/parish)→`district`, and
+ * the **value-conditional `XAD.7`** split across two independent FHIR axes:
+ * - `XAD.7 IN {BA, BI, C, B, H, O}` → `Address.use` (via the IG **HL70190 → address-use** map);
+ * - `XAD.7 IN {M, SH}` → `Address.type` (via the IG **HL70190 → address-type** map);
+ * - a vacation address (`V` in Table 0190; the datatype map references `HV`) → an ISO-21090 extension
+ *   the IG defines — **not emitted**, and flagged rather than invented;
+ * - any other code → `use`/`type` left absent, flagged {@link ISSUE_CODES.TRANSFORM_ADDRESS_USE_UNMAPPED}.
+ *
+ * FHIR deliberately separates `use` (home/work/temp) from `type` (postal/physical), so one v2 code
+ * cannot always populate both axes — round-trip is not stable, and the drop is surfaced, never hidden.
+ * `XAD.8` (other geographic designation) has no FHIR target and is flagged dropped.
+ *
+ * @packageDocumentation
+ */
+
+/** HL7 v2 Table 0190 address-type code → FHIR `address-use`, exactly per the IG HL70190→address-use map. */
+declare const ADDRESS_USE_MAP: Readonly<Record<string, string>>;
+/** HL7 v2 Table 0190 address-type code → FHIR `address-type`, exactly per the IG HL70190→address-type map. */
+declare const ADDRESS_TYPE_MAP: Readonly<Record<string, string>>;
+/**
+ * Convert a parsed HL7 v2 XAD to a FHIR `Address` node. Returns `{ value: undefined }` when the
+ * address carries no emittable part.
+ *
+ * @param xad - A parsed `@cosyte/hl7` `XAD`.
+ * @example
+ * ```ts
+ * import { toFhirAddress } from "@cosyte/transform";
+ * const { value } = toFhirAddress({ street: "1 Main St", city: "Boston", stateOrProvince: "MA", addressType: "H" });
+ * // value === Address { use: "home", line: ["1 Main St"], city: "Boston", state: "MA" }
+ * void value;
+ * ```
+ */
+declare function toFhirAddress(xad: XAD): ConvertResult<FhirComplex>;
+
+/**
+ * NM + units (CWE) → FHIR `Quantity`.
+ *
+ * Grounded on the IG datatype maps for OBX-5 (NM)→`Quantity.value` and OBX-6 (CWE units)→
+ * `Quantity.unit`/`.code`/`.system`. Two hard fail-safes:
+ *
+ * - **Never convert magnitudes.** The numeric value is carried through **precision-exact** via
+ *   `@cosyte/fhir`'s string-backed `decimal` (a dose or lab value is never routed through a JS
+ *   `number`). UCUM magnitude conversion (mg/dL ↔ mmol/L) is analyte-dependent and a
+ *   clinical-safety footgun — an explicit non-goal, never a transform side effect.
+ * - **Never fabricate a UCUM code.** A unit is emitted into `Quantity.code`/`.system` **only** when
+ *   it is declared UCUM and passes `@cosyte/fhir`'s UCUM shape check. Any other unit is preserved
+ *   verbatim in `Quantity.unit` with `code`/`system` absent, flagged
+ *   {@link ISSUE_CODES.TRANSFORM_UNIT_NOT_UCUM}.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Convert a parsed HL7 v2 numeric value plus its units to a FHIR `Quantity` node, fail-safe on the
+ * unit. Returns `{ value: undefined }` when the numeric magnitude is absent or non-numeric (a
+ * Quantity without a value cannot be safely emitted).
+ *
+ * @param value - A parsed `@cosyte/hl7` `NM` (its `.raw` carries the exact lexical value).
+ * @param units - The units component (an OBX-6 `CWE`); its CWE.1 is the candidate UCUM code.
+ * @param ctx - The transform context; used to recognize the UCUM coding system.
+ * @example
+ * ```ts
+ * import { toFhirQuantity } from "@cosyte/transform";
+ * const { value } = toFhirQuantity(
+ *   { raw: "5.4", value: 5.4 },
+ *   { identifier: "mg/dL", nameOfCodingSystem: "UCUM" },
+ * );
+ * // value === Quantity { value: 5.4, unit: "mg/dL", system: "http://unitsofmeasure.org", code: "mg/dL" }
+ * void value;
+ * ```
+ */
+declare function toFhirQuantity(value: NM, units: CWE, ctx?: TransformContext): ConvertResult<FhirComplex>;
+
+/**
+ * `toFhir` — the message-level entry point: assemble a parsed HL7 v2 message into a FHIR R4
+ * **message Bundle** (a `MessageHeader` first, then the focal resources), grounded on the IG message
+ * and segment maps. The **ADT** family becomes **Patient + Encounter** (+ `RelatedPerson`
+ * from NK1); the **ORU^R01** results graph becomes `DiagnosticReport` + `Observation`; the
+ * order-entry graph — **ORM_O01 / OML_O21** ORC/OBR → `ServiceRequest` and **RXO** (+ RXR) →
+ * `MedicationRequest`; and the thin IG singles — **VXU_V04** RXA/RXR/ORC → `Immunization`,
+ * **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:
+ *
+ * - **Segment-assembled, not fabricated.** For an ADT trigger the IG maps ({@link IG_MAPPED_ADT_TRIGGERS}),
+ *   the graph is message-map-grounded. For any other trigger there is no IG *message* map, so the
+ *   graph is assembled from the reusable IG *segment* maps and flagged
+ *   {@link ISSUE_CODES.TRANSFORM_SEGMENT_ASSEMBLED} — never a fabricated message map.
+ * - **Conservative emit gate.** Every produced resource is run through `@cosyte/fhir.validateResource`
+ *   before it can join the bundle — `Patient` against the built-in schema in `strict` mode, and the
+ *   other types against the minimal required-cardinality {@link EMIT_SCHEMAS} in `lenient` mode (so a
+ *   missing required element errors and withholds, while unmodeled sibling elements do not
+ *   false-reject). A resource with any structural error is **withheld** from the bundle and flagged
+ *   {@link ISSUE_CODES.TRANSFORM_RESOURCE_INVALID} rather than shipped as silently-invalid FHIR. When
+ *   the Patient is withheld, the Encounter's `subject` and any RelatedPerson are dropped rather than
+ *   left dangling — references always resolve within the bundle.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * The immutable result of a message-level transform: the FHIR `Bundle` model and the value-free
+ * diagnostics raised assembling it.
+ */
+interface TransformResult {
+    /** The FHIR R4 `Bundle` resource node (a message Bundle: MessageHeader first, then focal resources). */
+    readonly bundle: FhirComplex;
+    /** The value-free diagnostics raised during assembly, in emission order. */
+    readonly issues: readonly TransformIssue[];
+}
+/**
+ * The ADT trigger events the IG ships a **message** map for. Other triggers still transform — from the
+ * reusable segment maps — but are flagged {@link ISSUE_CODES.TRANSFORM_SEGMENT_ASSEMBLED}.
+ */
+declare const IG_MAPPED_ADT_TRIGGERS: ReadonlySet<string>;
+/**
+ * The ORU trigger events the IG ships a **message** map for. The IG maps only `R01`; other ORU triggers
+ * still assemble their results graph from the reusable OBR/OBX segment maps but are flagged
+ * {@link ISSUE_CODES.TRANSFORM_SEGMENT_ASSEMBLED}.
+ */
+declare const IG_MAPPED_ORU_TRIGGERS: ReadonlySet<string>;
+/**
+ * The order-message trigger events the IG ships a **message** map for, keyed `CODE^TRIGGER`. Only
+ * `ORM^O01` and `OML^O21` are message-map-grounded; other order families (`OMP`, `OMG`, `RDE`, …)
+ * still assemble their request graph from the reusable ORC/OBR/RXO/RXR segment maps but are flagged
+ * {@link ISSUE_CODES.TRANSFORM_SEGMENT_ASSEMBLED}.
+ */
+declare const IG_MAPPED_ORDER_TRIGGERS: ReadonlySet<string>;
+/**
+ * The immunization trigger the IG ships a **message** map for. The IG maps only `VXU^V04`; other VXU
+ * triggers still assemble their Immunization graph from the reusable RXA/RXR/ORC segment maps but are
+ * flagged {@link ISSUE_CODES.TRANSFORM_SEGMENT_ASSEMBLED}.
+ */
+declare const IG_MAPPED_IMMUNIZATION_TRIGGERS: ReadonlySet<string>;
+/**
+ * The scheduling trigger the IG ships a **message** map for. The IG maps only `SIU^S12`; other SIU
+ * triggers still assemble their Appointment from the reusable SCH/AIS/PID segment maps but are flagged
+ * {@link ISSUE_CODES.TRANSFORM_SEGMENT_ASSEMBLED}.
+ */
+declare const IG_MAPPED_APPOINTMENT_TRIGGERS: ReadonlySet<string>;
+/**
+ * The medical-document trigger the IG ships a **message** map for. The IG maps only `MDM^T02`; other MDM
+ * triggers still assemble their DocumentReference from the reusable TXA/OBX segment maps but are flagged
+ * {@link ISSUE_CODES.TRANSFORM_SEGMENT_ASSEMBLED}.
+ */
+declare const IG_MAPPED_DOCUMENT_TRIGGERS: ReadonlySet<string>;
+/**
+ * Transform a parsed HL7 v2 message into a FHIR R4 message `Bundle`. Never throws for a well-formed
+ * {@link Hl7Message}; every ambiguity, unmapped code, dropped element, or withheld resource surfaces
+ * as a value-free {@link TransformIssue}.
+ *
+ * @param msg - A parsed `@cosyte/hl7` message.
+ * @param opts - Transform options: the {@link TransformOptions.namingSystem} registry, the naked-
+ *   timestamp {@link TransformOptions.assumeTimezoneOffsetMinutes} policy, and a
+ *   {@link TransformOptions.generateId} allocator for reproducible fullUrls.
+ * @example
+ * ```ts
+ * import { parseHL7 } from "@cosyte/hl7";
+ * import { toFhir, createNamingSystem } from "@cosyte/transform";
+ * const { bundle, issues } = toFhir(parseHL7(raw), { namingSystem: createNamingSystem() });
+ * void bundle;
+ * void issues;
+ * ```
+ */
+declare function toFhir(msg: Hl7Message, opts?: TransformOptions): TransformResult;
+
+/**
+ * PID → FHIR `Patient` — grounded on the IG **Segment PID to Patient** ConceptMap
+ * (`hl7.fhir.uv.v2mappings`, STU1). The field→element rows used here, verified firsthand against the
+ * published map:
+ *
+ * | PID field | FHIR target | via |
+ * |---|---|---|
+ * | PID-3 Patient Identifier List (CX) | `Patient.identifier` | {@link toFhirIdentifier} |
+ * | PID-5 Patient Name (XPN) | `Patient.name` | {@link toFhirHumanName} |
+ * | PID-7 Date/Time of Birth (DTM) | `Patient.birthDate` | {@link toFhirDateTime} reduced to a `date` |
+ * | PID-8 Administrative Sex (CWE) | `Patient.gender` | {@link ADMINISTRATIVE_GENDER_MAP} (Table 0001) |
+ * | PID-11 Patient Address (XAD) | `Patient.address` | {@link toFhirAddress} |
+ *
+ * Fail-safe throughout: each datatype conversion carries its own value-free issues, an unmapped
+ * administrative-sex code leaves `gender` absent (never guessed), and a birth *time* (PID-7 with a
+ * time-of-day) is dropped to `date` precision with a flag — the US Core `patient-birthTime` extension
+ * is a profile concern this library does not cover. Deferred and flagged, not silently mapped:
+ * PID-13/14 telecom (no XTN→ContactPoint converter), and PID-10/15/22/29/30 (US Core race/ethnicity
+ * extensions, communication language, deceased).
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * HL7 v2 Table 0001 (Administrative Sex) → FHIR `administrative-gender`, exactly per the IG
+ * **Table HL70001 to Administrative Gender** ConceptMap (every row "is equivalent to"). `A`
+ * (Ambiguous) and `N` (Not applicable) both narrow to `other` — the map's stated equivalence, carried
+ * as-is. A code absent here (the map defines no `unmapped` default) leaves `gender` absent and is
+ * flagged {@link ISSUE_CODES.TRANSFORM_CODE_UNMAPPED} — never coerced to `unknown`.
+ */
+declare const ADMINISTRATIVE_GENDER_MAP: Readonly<Record<string, string>>;
+
+/**
+ * PV1 → FHIR `Encounter` — grounded on the IG **Segment PV1 to Encounter** ConceptMap plus the two
+ * **Table HL70004** ConceptMaps (to V3 ActCode, and to Encounter Status), all verified firsthand
+ * against the published `hl7.fhir.uv.v2mappings` STU1 maps:
+ *
+ * | PV1 field | FHIR target | condition / via |
+ * |---|---|---|
+ * | PV1-2 Patient Class | `Encounter.class` (Coding) | Table 0004 → V3 ActCode ({@link ENCOUNTER_CLASS_V3_MAP}); the self-mapped classes stay in v2-0004 |
+ * | PV1-2 Patient Class | `Encounter.status` (code) | Table 0004 → Encounter Status ({@link ENCOUNTER_STATUS_MAP}), *only IF PV1-45 not valued* |
+ * | PV1-19 Visit Number | `Encounter.identifier` (type `VN`) | v2-0203 identifier-type system |
+ * | PV1-44 Admit Date/Time | `Encounter.period.start` | {@link toFhirDateTime} |
+ * | PV1-45 Discharge Date/Time | `Encounter.period.end` + `status = finished` | {@link toFhirDateTime} |
+ *
+ * Fail-safe: an unmapped patient class leaves `Encounter.class` absent and flags
+ * {@link ISSUE_CODES.TRANSFORM_CODE_UNMAPPED} (never coerced); `Encounter.subject` is wired to the
+ * bundle's Patient (the identity anchor) and omitted only when no valid Patient was produced.
+ * Deferred and flagged, not silently mapped: PV1-3 location (Reference(Location), no Location resource
+ * is built), PV1-7/8 attending/referring doctor (Reference(Practitioner), no Practitioner resource
+ * is built).
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * HL7 v2 Table 0004 (Patient Class) → FHIR v3 ActCode (`Encounter.class`), per the IG **Table HL70004
+ * to V3 ActCode** ConceptMap (each "is equivalent to"). Only these four v2 classes have a v3 ActCode
+ * equivalent; the remaining classes (R/B/C/N/U) map to themselves and stay in the v2-0004 system
+ * ({@link V2_0004_SYSTEM}) per the same map's V2→V2 rows.
+ */
+declare const ENCOUNTER_CLASS_V3_MAP: Readonly<Record<string, {
+    code: string;
+    display: string;
+}>>;
+/**
+ * HL7 v2 Table 0004 (Patient Class) → FHIR `Encounter.status`, per the IG **Table HL70004 to
+ * Encounter Status** ConceptMap. Applied only when PV1-45 (discharge date) is *not* valued — a valued
+ * discharge sets `status = finished` per the PV1→Encounter map.
+ */
+declare const ENCOUNTER_STATUS_MAP: Readonly<Record<string, string>>;
+
+/**
+ * OBX → FHIR `Observation` — the highest-clinical-stakes segment map,
+ * grounded firsthand on the IG **Segment OBX to Observation** ConceptMap plus its two governing table
+ * ConceptMaps (`hl7.fhir.uv.v2mappings`, STU1). The rows used here, verified against the published maps
+ * (`ConceptMap-segment-obx-to-observation.html`, `-table-hl70078-to-v3-observationinterpretation.html`,
+ * `-table-hl70085-to-observation-status.html`):
+ *
+ * | OBX field | FHIR target | via |
+ * |---|---|---|
+ * | OBX-2 Value Type | discriminates OBX-5 → `value[x]` | {@link buildValue} — never assume `Quantity` |
+ * | OBX-3 Observation Identifier (CWE) | `Observation.code` | {@link toFhirCodeableConcept} |
+ * | OBX-5 Observation Value | `Observation.value[x]` | per OBX-2 |
+ * | OBX-6 Units (CWE) | `valueQuantity.unit`/`.code`/`.system` | {@link quantityFromRawMagnitude} |
+ * | OBX-7 Reference Range | `Observation.referenceRange.text` | mapped to `.text` (never decomposed) |
+ * | 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} |
+ *
+ * **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`.
+ * - **A corrected/cancelled result never emits as `final`.** OBX-11 `C`→`corrected`, `X`→`cancelled`,
+ *   `D`/`W`→`entered-in-error` (HL70085). A status code with **no** HL70085 target leaves
+ *   `Observation.status` absent (flagged {@link ISSUE_CODES.TRANSFORM_CODE_UNMAPPED}); the required-`status`
+ *   emit gate then **withholds** the Observation rather than shipping it — never coerced to `final`.
+ * - **An unrecognized abnormal flag is surfaced, never coerced to normal.** Each OBX-8 flag in
+ *   {@link HL70078_INTERPRETATION_CODES} becomes an `interpretation` coding (the map is code-preserving);
+ *   a flag absent from the table is flagged and dropped, never emitted as `N`/normal.
+ *
+ * Numeric magnitudes (NM, SN) are read from the **raw OBX-5 field** — not the `@cosyte/hl7`
+ * `Observation` view's JS `number` — so a reported lab value's exact lexical precision (`120.50`) is
+ * carried through the string-backed FHIR `decimal`, never routed through a lossy `number`.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * HL7 v2 Table 0078 (Abnormal Flags) → FHIR v3 ObservationInterpretation (`Observation.interpretation`),
+ * per the IG **Table HL70078 to v3 ObservationInterpretation** ConceptMap. Every mapped row is
+ * `is equivalent to` an **identically-spelled** v3 code (the map is code-preserving), so this is the set
+ * of codes that carry a target — a flag **absent** from this set has no equivalent and is flagged
+ * {@link ISSUE_CODES.TRANSFORM_CODE_UNMAPPED}, never coerced (the IG leaves `AC`/`HM`/`OBX`/`QCF`/`TOX`
+ * and any local flag unmapped, and declares no `unmapped` default).
+ */
+declare const HL70078_INTERPRETATION_CODES: ReadonlySet<string>;
+/**
+ * HL7 v2 Table 0085 (Observation Result Status) → FHIR `observation-status` (`Observation.status`),
+ * per the IG **Table HL70085 to Observation Status** ConceptMap (each `is equivalent to`). Only these
+ * seven source codes carry a target; the codes the IG leaves unmapped (`B`, `I`, `N`, `O`, `R`, `S`,
+ * `U`, `V`) are **absent here on purpose** — an OBX-11 with one of them (or any local code) leaves
+ * `Observation.status` absent + flagged, and the required-`status` emit gate withholds the Observation.
+ * **`C`→`corrected` and `X`→`cancelled` guarantee a corrected/cancelled result never emits as `final`.**
+ */
+declare const OBSERVATION_STATUS_MAP: Readonly<Record<string, string>>;
+
+/**
+ * OBR → FHIR `DiagnosticReport` — the ORU results-report anchor, grounded firsthand
+ * on the IG **Segment OBR to DiagnosticReport** ConceptMap and its **Table HL70123 to Diagnostic Report
+ * Status** ConceptMap (`hl7.fhir.uv.v2mappings`, STU1;
+ * `ConceptMap-segment-obr-to-diagnosticreport.html`,
+ * `ConceptMap-table-hl70123-queries-to-diagnostic-report-status.html`):
+ *
+ * | OBR field | FHIR target | via |
+ * |---|---|---|
+ * | OBR-2 Placer Order Number | `identifier` (type `PLAC`) | EI.1 → `Identifier.value`, v2-0203 type |
+ * | OBR-3 Filler Order Number | `identifier` (type `FILL`) | EI.1 → `Identifier.value`, v2-0203 type |
+ * | OBR-4 Universal Service Identifier (CWE) | `DiagnosticReport.code` | {@link toFhirCodeableConcept} |
+ * | OBR-7 Observation Date/Time | `effectiveDateTime` / `effectivePeriod.start` | {@link toFhirDateTime} |
+ * | OBR-8 Observation End Date/Time | `effectivePeriod.end` (start moves to the period when valued) | — |
+ * | OBR-22 Results Rpt/Status Chng Date/Time | `DiagnosticReport.issued` (an `instant`) | {@link toFhirDateTime} |
+ * | OBR-24 Diagnostic Serv Sect ID | `DiagnosticReport.category` | v2-0074 coding |
+ * | OBR-25 Result Status | `DiagnosticReport.status` | {@link DIAGNOSTIC_REPORT_STATUS_MAP} (HL70123) |
+ * | (OBX children) | `DiagnosticReport.result` | reference wiring from the assembler |
+ *
+ * **Fail-safes.** `DiagnosticReport.status` is required (R4 1..1) and the IG itself notes an unvalued
+ * OBR-25 is an error; so an absent OBR-25 — or an OBR-25 code the HL70123 map does not carry (`A`, `M`,
+ * `N`, `Y`, `Z`) — leaves `status` absent + flagged {@link ISSUE_CODES.TRANSFORM_CODE_UNMAPPED}, and the
+ * 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.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * HL7 v2 Table 0123 (Result Status) → FHIR `diagnostic-report-status` (`DiagnosticReport.status`), per
+ * the IG **Table HL70123 [Queries] to Diagnostic Report Status** ConceptMap (each `is equivalent to`).
+ * Only these **eight** source codes carry a target; the IG leaves `A`, `M`, `N`, `Y`, `Z` unmapped
+ * (verified firsthand against the published v1.0.0 ConceptMap — `N` "Procedure completed, results
+ * pending" is in the `(not mapped)` group, and the map declares no `unmapped` default), so an OBR-25
+ * with one of them leaves `status` absent + flagged and the report is withheld. In particular a
+ * results-**pending** `N` is **never** emitted as the post-final `appended`. **`C`→`corrected` and
+ * `X`→`cancelled` guarantee a corrected/cancelled report never emits as `final`.**
+ */
+declare const DIAGNOSTIC_REPORT_STATUS_MAP: Readonly<Record<string, string>>;
+
+/**
+ * ORC + OBR → FHIR `ServiceRequest` — the order-entry request, grounded firsthand
+ * on the IG **Segment ORC to ServiceRequest** and **Segment OBR to ServiceRequest** ConceptMaps and
+ * the **Table HL70119 to Request Status** ConceptMap (`hl7.fhir.uv.v2mappings`, STU1;
+ * `ConceptMap-segment-orc-to-servicerequest.html`, `ConceptMap-segment-obr-to-servicerequest.html`,
+ * `ConceptMap-table-hl70119-to-request-status.html`). Per the **ORM_O01 / OML_O21 message maps**,
+ * `ORC` *creates* the `ServiceRequest` and `OBR` is *incorporated into that same* request, so one
+ * builder consumes both:
+ *
+ * | v2 field | FHIR target | via |
+ * |---|---|---|
+ * | ORC-1 Order Control | `ServiceRequest.status` | {@link REQUEST_STATUS_MAP} (HL70119), *only IF ORC-5 not valued* |
+ * | ORC-2 / OBR-2 Placer Order Number | `identifier` (type `PLAC`) | {@link orderIdentifier} (EI.1, v2-0203) |
+ * | ORC-3 / OBR-3 Filler Order Number | `identifier` (type `FILL`) | {@link orderIdentifier} |
+ * | 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-31 Reason for Study (CWE) | `reasonCode` | {@link toFhirCodeableConcept} |
+ * | (order message context) | `intent` = `order` | see below |
+ * | (message-map wiring) | `subject` / `encounter` | the bundle's Patient / Encounter |
+ *
+ * **Fail-safes (never a confident wrong request).**
+ * - **`status` (required 1..1).** ORC-1 → HL70119 carries a target for only the 19 codes in
+ *   {@link REQUEST_STATUS_MAP}; the many codes the IG leaves in its `(unmapped)` group (CH, CP, PA,
+ *   RE, RF, RP, SC, the U* "unable to …" family, …) have **no** target and leave `status` absent +
+ *   flagged {@link ISSUE_CODES.TRANSFORM_CODE_UNMAPPED}. When **ORC-5** (Order Status) is valued the
+ *   IG routes status through ORC-5 via an *unspecified* mapping (no code table) — so we cannot derive
+ *   it, flag ORC-5 unmapped, and leave `status` absent rather than mis-applying the ORC-1 table
+ *   against the IG's own condition. The required-`status` emit gate then **withholds** the request —
+ *   never guessed, never coerced.
+ * - **`intent` (required 1..1) = `order`.** The IG maps ORC-1/OBR → `intent` as `equivalent` but ships
+ *   **no value ConceptMap** for it; the ORM_O01/OML_O21 families are, by definition, *order* messages
+ *   (their message maps create a `ServiceRequest`/`MedicationRequest` per order), so `intent` is fixed
+ *   to the `request-intent` code `order` from that message context. This is a resource-level constant
+ *   grounded in the message family — **not** a fabricated per-code translation row. The finer
+ *   OBR-11-conditioned intent refinement is deferred.
+ * - **`subject` (required 1..1).** Wired to the bundle's Patient; a request with no resolvable Patient
+ *   is withheld rather than emitted with a dangling/absent subject.
+ *
+ * - **`priority` (0..1) — value-translated.** OBR-5 → `ServiceRequest.priority` via the IG
+ *   **Table HL70485 to Request Priority** ConceptMap ({@link SERVICE_REQUEST_PRIORITY_MAP}): only
+ *   `S→stat`, `A→asap`, `R→routine` carry a target (each `equivalent`, and all three are valid
+ *   `request-priority` members). Every other v2-0485 code — `P`, `C`, `T`, the `T{S,M,H,D,W,L}<integer>`
+ *   timing-critical family, `PRN` — sits in the IG map's `(unmapped)` group, so a valued OBR-5 the map
+ *   has no target for leaves `priority` absent + flagged {@link ISSUE_CODES.TRANSFORM_CODE_UNMAPPED},
+ *   never guessed. (`priority` is 0..1, so an unmapped value simply omits it — the request still emits.)
+ *
+ * Deferred and flagged elsewhere, not silently mapped: ORC-7/OBR-27 timing (`$this`), ORC-12/OBR-16
+ * requester + ORC-21..24 ordering facility/provider (need Practitioner/PractitionerRole/Organization
+ * resources), OBR-29 basedOn, specimen, and the ORC-1/ORC-9/OBR-13 order-control/supporting-info
+ * extensions.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * HL7 v2 Table 0119 (Order Control Codes) → FHIR `request-status` (`ServiceRequest.status`), per the
+ * IG **Table HL70119 to Request Status** ConceptMap (each `is equivalent to`). Only these **19** source
+ * codes carry a target; every other v2-0119 code sits in the IG's explicit `(unmapped)` group
+ * (verified firsthand against the published v1.0.0 ConceptMap — CH/CN/CP/DE/LI/NA/OE/OF/OP/OR/PA/RE/
+ * RF/RP/RR/RU/SC/SN/SR/SS/UA/UC/UD/UF/UH/UM/UN/UR/UX/XO/XR/XX/MC are all `unmatched`, and the map
+ * declares no `unmapped` default), so an ORC-1 with one of them leaves `status` absent + flagged and
+ * the request is withheld. `request-status` has no `cancelled`; the cancel/discontinue codes map to
+ * `revoked` and the hold codes to `on-hold`, exactly as the IG table specifies.
+ */
+declare const REQUEST_STATUS_MAP: Readonly<Record<string, string>>;
+/**
+ * HL7 v2 Table 0485 (Extended Priority Codes) → FHIR `request-priority` (`ServiceRequest.priority`),
+ * per the IG **Table HL70485 to Request Priority** ConceptMap (each `is equivalent to`; verified
+ * firsthand against the published v1.0.0 ConceptMap). Only these **three** source codes carry a
+ * target; every other v2-0485 code — `P` (Preop), `C` (Callback), `T` (Timing critical), the
+ * `T{S,M,H,D,W,L}<integer>` timing-critical family, and `PRN` (As needed) — sits in the IG's
+ * `(unmapped)` group with no target, so an OBR-5 carrying one leaves `priority` absent + flagged.
+ * All three targets (`stat`/`asap`/`routine`) are valid `request-priority` members.
+ */
+declare const SERVICE_REQUEST_PRIORITY_MAP: Readonly<Record<string, string>>;
+
+/**
+ * VXU_V04 → FHIR `Immunization` — the thin IG single for immunization administration,
+ * grounded firsthand on the IG **VXU_V04 message map** and the **RXA/RXR/ORC → Immunization**
+ * segment maps (`hl7.fhir.uv.v2mappings`, STU1; `ConceptMap-message-vxu-v04-to-bundle.json`,
+ * `ConceptMap-segment-rxa-to-immunization.json`, `ConceptMap-segment-rxr-to-immunization.json`,
+ * `ConceptMap-segment-orc-to-immunization.json`). Per the VXU message map, **each `ORC` creates an
+ * `Immunization`** and the `RXA` (+ `RXR` route) in the same order group are *incorporated into it*, so
+ * one builder consumes all three; the order-group `OBX`s become standalone patient `Observation`s
+ * (`Observation[2]` in the IG bundle), handled by the assembler.
+ *
+ * | v2 field | FHIR target | via |
+ * |---|---|---|
+ * | RXA-5 Administered Code (CE) | `vaccineCode` (required 1..1) | {@link toFhirCodeableConcept} (structural — no IG value map) |
+ * | RXA-3 Date/Time Start of Administration (DTM) | `occurrenceDateTime` (required, occurrence[x]) | {@link toFhirDateTime} |
+ * | RXA-20 Completion Status + RXA-21 Action Code | `status` (required 1..1) | {@link buildStatus} (HL70322 + IG assignments) |
+ * | RXA-6 Administered Amount + RXA-7 Units | `doseQuantity` | {@link quantityFromRawMagnitude} |
+ * | RXA-15 Substance Lot Number (ST) | `lotNumber` | verbatim |
+ * | RXA-16 Substance Expiration Date (DT) | `expirationDate` (a `date`) | {@link toFhirDateTime}, date-only |
+ * | RXA-18 Substance/Treatment Refusal Reason (CWE) | `statusReason` | {@link toFhirCodeableConcept} |
+ * | RXA-19 Indication (CWE) | `reasonCode` | {@link toFhirCodeableConcept} |
+ * | RXA-22 System Entry Date/Time (DTM) | `recorded` | {@link toFhirDateTime} (ORC-9 fallback) |
+ * | RXR-1 Route (CWE) | `route` | {@link ROUTE_VALUE_MAP} (HL70162, value-translated) |
+ * | RXR-2 Administration Site (CWE) | `site` | {@link SITE_VALUE_MAP} (HL70550, value-translated) |
+ * | ORC-2 / ORC-3 Placer/Filler Order Number | `identifier` (PLAC / FILL) | {@link orderIdentifier} |
+ * | ORC-9 Date/Time of Order Event | `recorded` (fallback) | {@link toFhirDateTime} |
+ * | (message-map wiring) | `patient` (required 1..1) / `encounter` | the bundle's Patient / Encounter |
+ *
+ * **Fail-safes (never a confident wrong immunization record).**
+ * - **`status` (required 1..1).** The IG ships **three conditioned status rows** (verified firsthand
+ *   against `ConceptMap-segment-rxa-to-immunization.json`): **RXA-21 = "D"** (delete) → the IG-assigned
+ *   `entered-in-error`; **RXA-20 not valued and RXA-21 ≠ "D"** → the IG-assigned `completed`; **RXA-20
+ *   valued and RXA-21 ≠ "D"** → translated via {@link IMMUNIZATION_STATUS_MAP} (the HL70322 →
+ *   event-status ConceptMap, whose targets `completed`/`not-done` are all valid `immunization-status`
+ *   members). A **valued** RXA-20 the HL70322 map has no target for is flagged
+ *   {@link ISSUE_CODES.TRANSFORM_CODE_UNMAPPED}, `status` left absent, and the required-`status` emit gate
+ *   **withholds** the Immunization — never guessed, never coerced.
+ * - **`vaccineCode` (required 1..1) + `occurrence[x]` (required 1..1) + `patient` (required 1..1).** An
+ *   absent RXA-5, RXA-3, or bundle Patient leaves the resource missing a required element, so it is
+ *   withheld by the emit gate rather than emitted incomplete.
+ * - **Dose.** RXA-6/RXA-7 → `doseQuantity` via {@link quantityFromRawMagnitude}: precision-exact magnitude,
+ *   non-UCUM unit preserved verbatim with `.code`/`.system` absent + flagged — never a fabricated UCUM code.
+ * - **Route/site value translation.** RXR-1 route → {@link ROUTE_VALUE_MAP} (HL70162) and
+ *   RXR-2 site → {@link SITE_VALUE_MAP} (HL70550) are value-translated additively (derived target coding
+ *   added, raw coding preserved); a code outside the table is preserved + flagged, never coerced.
+ * - **`vaccineCode` is NOT value-translated — by grounding, not omission.** RXA-5 has **no** `mappedVia`
+ *   value ConceptMap in the IG's RXA→Immunization segment map (verified firsthand), so the code (typically
+ *   CVX) is carried **structurally** (system recognized, value preserved) — a translation is never
+ *   invented for it.
+ *
+ * Deferred and flagged elsewhere, not silently mapped: RXA-10 performer, RXA-17 manufacturer, RXA-27/28
+ * location, ORC-12 performer (all need Practitioner/Organization/Location resources this library does not
+ * build).
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * HL7 v2 Table 0322 (Completion Status) → FHIR `Immunization.status`, per the IG **Table HL70322 to
+ * Event Status** ConceptMap (each `is equivalent to`). Table 0322 has exactly these **four** source
+ * codes and every one carries a target; the two distinct targets (`completed`, `not-done`) are both
+ * valid members of the `immunization-status` required binding, so applying this map to
+ * `Immunization.status` is faithful. Consulted only for a **valued** RXA-20 when **RXA-21 ≠ "D"** (the
+ * IG's `mappedVia` condition on that row); the two other IG status rows assign fixed values directly (a
+ * delete → `entered-in-error`, an unvalued RXA-20 → `completed`) and do not consult this map. See
+ * {@link buildStatus}.
+ */
+declare const IMMUNIZATION_STATUS_MAP: Readonly<Record<string, string>>;
+
+/**
+ * SIU_S12 → FHIR `Appointment` — the thin IG single for scheduling, grounded
+ * firsthand on the IG **SIU_S12 message map**, the **SCH/AIS/PID → Appointment** segment maps, the
+ * **Table HL70278 → AppointmentStatus** ConceptMap, and the **TQ → Appointment** datatype map
+ * (`hl7.fhir.uv.v2mappings`, STU1; `ConceptMap-message-siu-s12-to-bundle.json`,
+ * `ConceptMap-segment-sch-to-appointment.json`, `ConceptMap-segment-ais-to-appointment.json`,
+ * `ConceptMap-segment-pid-to-appointment.json`, `ConceptMap-table-hl70278-to-appointmentstatus.json`,
+ * `ConceptMap-datatype-tq-to-appointment.json`). Per the message map an SIU message yields **one**
+ * `Appointment` created from the `SCH` segment; `PID` contributes the patient participant and `AIS`
+ * the service type.
+ *
+ * | v2 field | FHIR target | via |
+ * |---|---|---|
+ * | SCH-25 Filler Status Code | `status` (required 1..1) | {@link APPOINTMENT_STATUS_MAP} (HL70278) |
+ * | SCH-1 Placer / SCH-2 Filler Appointment ID | `identifier` | EI.1 → `Identifier.value` |
+ * | SCH-7 Appointment Reason (CWE) | `reasonCode` | {@link toFhirCodeableConcept} (structural — SNOMED target, BYO) |
+ * | SCH-8 Appointment Type (CWE) | `appointmentType` | {@link APPOINTMENT_TYPE_VALUE_MAP} (HL70277, value-translated) |
+ * | SCH-9 Duration + SCH-10 Units | `minutesDuration` | integer, only when SCH-10 is minutes |
+ * | SCH-11 Appointment Timing Quantity (TQ) | `start` / `end` (instant) | TQ.4/TQ.5 → {@link toFhirDateTime} |
+ * | AIS-3 Universal Service Identifier (CWE) | `serviceType` | {@link toFhirCodeableConcept} |
+ * | PID (bundle Patient) | `participant.actor` (required 1..*) | reference wiring |
+ *
+ * **Fail-safes (never a confident wrong appointment).**
+ * - **`status` (required 1..1).** SCH-25 → {@link APPOINTMENT_STATUS_MAP} (HL70278). The three HL70278
+ *   codes the IG leaves unmatched (`Discontinued`, `Blocked`, `Overbook`) and an absent SCH-25 leave
+ *   `status` absent + flagged {@link ISSUE_CODES.TRANSFORM_CODE_UNMAPPED}; the required-`status` emit gate
+ *   then **withholds** the Appointment — never guessed.
+ * - **`participant` (required 1..*).** The bundle Patient is emitted as the required participant. Its
+ *   `participant.status` (a required-bound `code` the IG supplies no source for) is emitted as a
+ *   `data-absent-reason` primitive (value `unknown`) + flagged {@link ISSUE_CODES.TRANSFORM_REQUIRED_ELEMENT_UNKNOWN}
+ *   — the spec-clean way to satisfy a required code whose value is genuinely unknown, never fabricated. An
+ *   Appointment with no resolvable Patient (and no other groundable actor this library builds) has no
+ *   participant and is withheld.
+ * - **`start`/`end` (instant).** SCH-11's TQ.4/TQ.5 become `start`/`end` only when they are fully-zoned
+ *   instants; a naked (unzoned) timing is dropped + flagged rather than assigned a fabricated UTC offset,
+ *   mirroring `Bundle.timestamp`.
+ * - **`appointmentType` value translation.** SCH-8 → {@link APPOINTMENT_TYPE_VALUE_MAP}
+ *   (HL70277 `Normal`/`Tentative`/`Complete` identity into `v2-0277`); a code outside the table is
+ *   preserved + flagged, never coerced. **`reasonCode` is NOT value-translated:** SCH-7's IG map target
+ *   is SNOMED CT (`table-hl70276-to-sct`) — encumbered, **not bundled** — so the reason is carried
+ *   structurally (BYO ConceptMap), never SNOMED-translated here. (The IG's SCH→Appointment map *also*
+ *   carries a redundant SCH-7 → `appointmentType[1]` row via `table-hl70277-to-v2-0277`; it is not
+ *   applied — SCH-7 carries HL70276 *reason* codes, not HL70277 *type* codes, so translating them through
+ *   the type table would only ever produce spurious unmapped flags. `appointmentType` comes from SCH-8,
+ *   the appointment-*type* field, per that same map's SCH-8 → `appointmentType[1]` row.)
+ *
+ * Deferred and flagged elsewhere, not silently mapped: SCH-12/16/20 contact participants and AIP/AIL/AIG
+ * actors (need Practitioner/Location resources), SCH-26/27 `basedOn` ServiceRequest, AIS participant periods.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * HL7 v2 Table 0278 (Filler Status Code) → FHIR `appointmentstatus` (`Appointment.status`), per the IG
+ * **Table HL70278 to AppointmentStatus** ConceptMap (each `is equivalent to`). The three source codes
+ * the IG leaves **unmatched** (`Discontinued`, `Blocked`, `Overbook`) are absent here on purpose — an
+ * SCH-25 carrying one of them (or any local code) leaves `Appointment.status` absent + flagged and the
+ * required-`status` emit gate withholds the Appointment.
+ */
+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**.
+ *
+ * **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 — 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";
+/** 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:
+ * a 41-code **identity** group (source `v2-0162` → target `v2-0162`, each `equivalent`) and a 6-code
+ * **remap** group into `v3-RouteOfAdministration` (`ID→IDINJ`, `IM→IM`, `IV→IVINJ`, `PO→PO`, `SC→SQ`,
+ * `TD→TRNSDERM`, each `equivalent`, with the IG target displays). The two source-code sets are
+ * disjoint. Any other v2-0162 code (or a non-table code) is unmapped → the raw coding is preserved
+ * and flagged, never coerced.
+ */
+declare const ROUTE_VALUE_MAP: CodedValueMap;
+/**
+ * **RXR-2 Administration Site** — IG `ConceptMap/table-hl70550-to-v2-0550`. A single **identity**
+ * group of 443 body-part codes (source `v2-0550` → target `v2-0550`, each `equivalent`), transcribed
+ * verbatim from the published STU1 ConceptMap — **including** its as-published data-quality artifacts
+ * (`CHESTÂ`, a lone `Â`, `KIDNÂ`, where a stray U+00C2 leaked from the IG's source
+ * encoding). They are preserved for source-fidelity; they are inert (a clean `CHEST`/`KIDN` simply
+ * falls through to unmapped). A code not in the table is unmapped → raw coding preserved + flagged.
+ */
+declare const SITE_VALUE_MAP: CodedValueMap;
+/**
+ * **SCH-8 Appointment Type** — IG `ConceptMap/table-hl70277-to-v2-0277`. A single **identity** group
+ * of the three v2-0277 codes (`Normal`, `Tentative`, `Complete` → themselves, each `equivalent`,
+ * source and target both `v2-0277`). Any other code is unmapped → raw coding preserved + flagged.
+ */
+declare const APPOINTMENT_TYPE_VALUE_MAP: CodedValueMap;
+/**
+ * **RXO-9 Allow Substitutions** — IG `ConceptMap/table-hl70161-to-v2-0161`. A single **identity**
+ * group of the three v2-0161 codes (`N` NOT authorized, `G` generic, `T` therapeutic → themselves,
+ * each `equivalent`, source and target both `v2-0161`), the target for
+ * `MedicationRequest.substitution.allowedCodeableConcept`. Any other code is unmapped → the
+ * substitution is withheld + flagged, never a fabricated substitution permission.
+ */
+declare const SUBSTITUTION_VALUE_MAP: CodedValueMap;
+/**
+ * The bound-table target for a coded element's **primary** coding, or `undefined` when the map does
+ * not faithfully apply — i.e. the primary declares a coding system that is **not** this map's bound
+ * table (CWE.3 present and not in {@link CodedValueMap.sourceMnemonics}), the primary code is empty, or
+ * the code is in the IG map's `(unmapped)` group. Never asserts a standard translation for a foreign
+ * coding system, and never fabricates a target.
+ *
+ * @param cwe - The parsed coded element (its `identifier` is the candidate source-table code).
+ * @param map - The license-clean value map to consider applying.
+ * @example
+ * ```ts
+ * import { translateBound, ROUTE_VALUE_MAP } from "@cosyte/transform";
+ * translateBound({ identifier: "IM" }, ROUTE_VALUE_MAP)?.code; // "IM" (v3 route)
+ * translateBound({ identifier: "IM", nameOfCodingSystem: "99LOCAL" }, ROUTE_VALUE_MAP); // undefined
+ * ```
+ */
+declare function translateBound(cwe: CodedElement, map: CodedValueMap): CodedTarget | undefined;
+/**
+ * Build a FHIR `CodeableConcept` node for a {@link CodedTarget} — the single translated coding, with
+ * an optional free-`text`. Used by translate-or-withhold callers (e.g. substitution) that build the
+ * CodeableConcept only on a successful translation.
+ *
+ * @param target - The translated target coding.
+ * @param text - The original free text (`CWE.9`) to carry as `CodeableConcept.text`, if any.
+ * @example
+ * ```ts
+ * import { codeableConceptFromTarget, V2_0161_SYSTEM } from "@cosyte/transform";
+ * const cc = codeableConceptFromTarget({ system: V2_0161_SYSTEM, code: "G" });
+ * void cc;
+ * ```
+ */
+declare function codeableConceptFromTarget(target: CodedTarget, text?: string): FhirComplex;
+/**
+ * Value-translate a coded v2 element to a FHIR `CodeableConcept` **via** a license-clean
+ * {@link CodedValueMap}, **additively** and fail-safe — never mutating or discarding what the message
+ * said:
+ *
+ * - **Primary code recognized as a bound-table code** ({@link translateBound} — CWE.3 absent or names
+ *   the bound table, and the code is in the IG map's mapped group) → the **primary** coding is emitted
+ *   in the recognized source-table system (`map.sourceSystem`, carrying `CWE.7` version) and the
+ *   **derived** target coding is *appended* when it differs (a remap such as `SC→SQ`); the **alternate
+ *   triplet** (`CWE.4/5/6`, via {@link buildCoding}, with its own system resolution + flags) and the
+ *   original `CWE.9` text are preserved. No primary unmapped flag — the value was faithfully recognized.
+ * - **Otherwise** — the primary declares a **foreign** coding system (not the bound table), the code is
+ *   empty, or it is in the IG's `(unmapped)` group → this defers entirely to the **structural**
+ *   {@link toFhirCodeableConcept}, which preserves the raw coding (and its `CWE.4/5/6` alternate and
+ *   `CWE.7` version) and flags it ({@link ISSUE_CODES.TRANSFORM_CODE_UNMAPPED} /
+ *   `TRANSFORM_CODE_SYSTEM_UNRESOLVED`). A target is **never** fabricated, and a code that declares a
+ *   foreign system is **never** asserted to be the standard concept.
+ *
+ * @param cwe - The parsed `@cosyte/hl7` coded element (its `identifier` is the candidate table code).
+ * @param map - The license-clean value map to apply (e.g. {@link ROUTE_VALUE_MAP}).
+ * @param ctx - The transform context (threaded to the structural path + the alternate-triplet resolver).
+ * @example
+ * ```ts
+ * import { toFhirCodeableConceptVia, ROUTE_VALUE_MAP } from "@cosyte/transform";
+ * const { value } = toFhirCodeableConceptVia({ identifier: "IM" }, ROUTE_VALUE_MAP);
+ * // coding === [{ system: ".../v2-0162", code: "IM" },
+ * //            { system: ".../v3-RouteOfAdministration", code: "IM", display: "Injection, intramuscular" }]
+ * void value;
+ * ```
+ */
+declare function toFhirCodeableConceptVia(cwe: CodedElement, map: CodedValueMap, ctx?: TransformContext): ConvertResult<FhirComplex>;
+
+/**
+ * Public entry point for `@cosyte/transform` — the HL7 v2 → FHIR R4 transformation library.
+ *
+ * `@cosyte/transform` is **not** a parser; it is a **consumer** one tier above the parser suite. It
+ * takes already-parsed `@cosyte/hl7` composites and produces validated `@cosyte/fhir` model nodes,
+ * grounded on the official **HL7 Version 2 to FHIR** Implementation Guide (`hl7.fhir.uv.v2mappings`,
+ * STU Edition 1). Its whole promise is narrow and honest: **IG-grounded, fail-safe transformation
+ * with typed, value-free diagnostics — never a confident wrong FHIR value.**
+ *
+ * This module ships the six safety-critical datatype converters, the immutable
+ * `OperationOutcome`-shaped diagnostic channel and the NamingSystem resolver they consult,
+ * the message-level assembly — HL7 v2 **ADT → FHIR Patient + Encounter**, the
+ * **ORU^R01 → DiagnosticReport + Observation** results graph, the order-entry graph
+ * (**ORM_O01 / OML_O21 → ServiceRequest** and **RXO → MedicationRequest**), and the thin IG
+ * singles (**VXU_V04 → Immunization**, **SIU_S12 → Appointment**, **MDM_T02 → DocumentReference**),
+ * all through `toFhir(msg)` — and the **terminology value-translation** layer: a
+ * `$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.
+ *
+ * @packageDocumentation
+ */
+/** The library version string, synced with `package.json#version` by the release tooling. */
+declare const VERSION = "0.0.0";
+
+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 };