@cosyte/terminology 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,3466 @@
+/**
+ * The immutable FHIR value types the engine operates over: {@link Coding} and
+ * {@link CodeableConcept}.
+ *
+ * These mirror the FHIR R4 datatypes of the same names (the interchange lingua franca the whole
+ * ecosystem speaks), reduced to the fields the terminology operations need. Every instance the
+ * engine hands back is deep-frozen, so a translated result is safe to share across a pipeline
+ * without defensive copying — the immutability discipline the parsers follow.
+ *
+ * @packageDocumentation
+ */
+/**
+ * A single coded value — a `code` drawn from a code `system`, optionally versioned and displayed.
+ *
+ * Models FHIR R4 `Coding`. `system` is the code system's **canonical URI** (e.g.
+ * `http://loinc.org`), not a mnemonic or OID — use {@link ../systems/resolve.resolveSystem} to
+ * canonicalize before constructing one. `system` is optional because a raw wire code sometimes
+ * arrives without one; the engine surfaces that rather than inventing a system.
+ *
+ * @example
+ * ```ts
+ * import { coding } from "@cosyte/terminology";
+ *
+ * const c = coding({ system: "http://loinc.org", code: "2160-0", display: "Creatinine" });
+ * c.code; // => "2160-0"
+ * ```
+ */
+interface Coding {
+    /** The code system's canonical URI (e.g. `http://snomed.info/sct`). Optional when unknown. */
+    readonly system?: string;
+    /** The symbol in the code system's syntax. Required — a coding without a code is meaningless. */
+    readonly code: string;
+    /** The code system version this code is drawn from, when known (mappings are release-scoped). */
+    readonly version?: string;
+    /** The human-readable label. Carried verbatim from the source; never fabricated by the engine. */
+    readonly display?: string;
+}
+/**
+ * A concept described by one or more {@link Coding}s plus optional free text — FHIR R4
+ * `CodeableConcept`. Included so the value layer is complete for downstream consumers even though
+ * Phase 1's {@link ../conceptmap/translate.translate} operates on a single {@link Coding}.
+ *
+ * @example
+ * ```ts
+ * import { codeableConcept } from "@cosyte/terminology";
+ *
+ * const cc = codeableConcept({
+ *   coding: [{ system: "http://loinc.org", code: "2160-0" }],
+ *   text: "Serum creatinine",
+ * });
+ * cc.coding[0].code; // => "2160-0"
+ * ```
+ */
+interface CodeableConcept {
+    /** The codings for this concept, in order of preference. Frozen and never empty-by-fabrication. */
+    readonly coding: readonly Coding[];
+    /** Plain-text representation of the concept, when supplied. */
+    readonly text?: string;
+}
+/**
+ * Construct a deep-frozen {@link Coding}.
+ *
+ * The returned object is `Object.freeze`d so it cannot be mutated in place — parsed/translated
+ * values are immutable by default. Optional fields are only present when supplied (no `undefined`
+ * keys), so structural equality checks stay clean.
+ *
+ * @param init - The coding fields; `code` is required.
+ * @returns A frozen {@link Coding}.
+ * @example
+ * ```ts
+ * import { coding } from "@cosyte/terminology";
+ *
+ * const frozen = coding({ system: "http://loinc.org", code: "2160-0" });
+ * Object.isFrozen(frozen); // => true
+ * ```
+ */
+declare function coding(init: Coding): Coding;
+/**
+ * Construct a deep-frozen {@link CodeableConcept} (its `coding` array and every member frozen).
+ *
+ * @param init - The concept fields; `coding` is required (may be empty).
+ * @returns A frozen {@link CodeableConcept}.
+ * @example
+ * ```ts
+ * import { codeableConcept } from "@cosyte/terminology";
+ *
+ * const cc = codeableConcept({ coding: [{ code: "2160-0" }] });
+ * Object.isFrozen(cc.coding); // => true
+ * ```
+ */
+declare function codeableConcept(init: CodeableConcept): CodeableConcept;
+
+/**
+ * The engine's **stable diagnostic + fatal code registries** and its typed error.
+ *
+ * `@cosyte/terminology` is an engine, not a lenient wire-format parser, so its stable codes are
+ * **diagnostics** (typed, surfaced outcomes a consumer branches on) and **fatals** (thrown on
+ * structurally unusable input), rather than the parsers' "Tier-2 tolerance warnings". The
+ * discipline is identical: the code strings are part of the public contract — consumers narrow on
+ * them, so renaming or removing one is a **breaking change**, and the full set is snapshotted via
+ * `sortedCodeSet` (`@cosyte/test-utils`) as a reviewable tripwire.
+ *
+ * **Value-free by construction.** A diagnostic carries a stable code plus, at most, a
+ * code + system + version — **never** a surrounding patient identifier or clinical narrative. A
+ * code *in patient context* can be PHI (roadmap §7), so messages describe *structure* (a resource
+ * path, a code system), never echo arbitrary input *values*.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Stable **diagnostic codes** — typed, surfaced, non-throwing outcomes.
+ *
+ * These are not errors: they are first-class results a caller inspects (an unmapped translation,
+ * an unrecognized code system). `key === value` so `Object.values(...)` yields the snapshot set.
+ *
+ * @example
+ * ```ts
+ * import { DIAGNOSTIC_CODES } from "@cosyte/terminology";
+ *
+ * DIAGNOSTIC_CODES.TERM_TRANSLATE_UNMAPPED; // => "TERM_TRANSLATE_UNMAPPED"
+ * ```
+ */
+declare const DIAGNOSTIC_CODES: {
+    /**
+     * A `$translate` found no target for the source code. A **first-class outcome, never an error** —
+     * the source is surfaced as `unmapped`, never replaced with a guessed target (the never-fabricate
+     * invariant).
+     */
+    readonly TERM_TRANSLATE_UNMAPPED: "TERM_TRANSLATE_UNMAPPED";
+    /**
+     * A code-system identifier (URI, OID, or mnemonic) was not recognized by the identity resolver.
+     * Surfaced as a typed `unknown`, never coerced to a guessed canonical URI.
+     */
+    readonly TERM_SYSTEM_UNRECOGNIZED: "TERM_SYSTEM_UNRECOGNIZED";
+    /**
+     * An RRF (pipe-delimited RxNorm/UMLS release) row was structurally unusable — too few columns to
+     * reach a configured field, or a missing code. The row is **skipped and surfaced** as a load
+     * warning (liberal on load), never kept as a partially-parsed concept.
+     */
+    readonly TERM_RRF_MALFORMED_ROW: "TERM_RRF_MALFORMED_ROW";
+    /**
+     * A CSV (RFC-4180, e.g. LOINC `Loinc.csv`) row was structurally unusable — too few fields to reach
+     * a configured column. The row is **skipped and surfaced** as a load warning, never partial.
+     */
+    readonly TERM_CSV_MALFORMED: "TERM_CSV_MALFORMED";
+    /**
+     * A fixed-width (e.g. ICD-10-CM order file) row was structurally unusable — too short to contain
+     * the configured code field, or a missing code. Skipped and surfaced, never partial.
+     */
+    readonly TERM_FIXED_WIDTH_MALFORMED: "TERM_FIXED_WIDTH_MALFORMED";
+    /**
+     * A concept inside a FHIR `CodeSystem` resource was unusable — not an object, or missing its
+     * required `code`. Skipped and surfaced (the whole resource still loads); `line` is `0` since a
+     * JSON concept is not line-addressable.
+     */
+    readonly TERM_FHIR_CONCEPT_MALFORMED: "TERM_FHIR_CONCEPT_MALFORMED";
+    /**
+     * A `$lookup`/`$validate-code` found no concept for the code in the loaded release. A **first-class
+     * typed outcome, never a guess** — the engine returns `unknown`/`valid: false`, never a fabricated
+     * display or a coerced `valid: true` (the never-fabricate invariant, applied to code identity).
+     */
+    readonly TERM_CODE_UNKNOWN: "TERM_CODE_UNKNOWN";
+    /**
+     * A resolved concept is **deprecated / no longer current** (e.g. LOINC `STATUS = DEPRECATED`, or a
+     * FHIR concept flagged `inactive`). Surfaced on the concept's status so a caller never presents a
+     * non-current code as clean; the concept is still *found* (a lookup succeeds), it is just flagged.
+     */
+    readonly TERM_CONCEPT_DEPRECATED: "TERM_CONCEPT_DEPRECATED";
+    /**
+     * A resolved concept is a **classification header, not a billable/valid leaf** (e.g. an ICD-10-CM
+     * order-file row with the position-15 flag `0`). Surfaced on the concept's status: a header code is
+     * found but is **not valid for claim submission**, and must never be presented as billable.
+     */
+    readonly TERM_CONCEPT_HEADER_NOT_BILLABLE: "TERM_CONCEPT_HEADER_NOT_BILLABLE";
+    /**
+     * A ValueSet `compose` part could **not be expanded** — an intensional `include`/`exclude` whose
+     * code system was not supplied, an unresolvable referenced value set, or a `filter` operator the
+     * engine does not implement. Surfaced as a typed outcome that marks the expansion **incomplete**;
+     * the engine **never** fabricates a member and **never** returns a silently-empty "no members"
+     * answer for a part it could not compute (roadmap §4.4 — a false "not a member" is a clinical error).
+     */
+    readonly TERM_VALUESET_CANNOT_EXPAND: "TERM_VALUESET_CANNOT_EXPAND";
+    /**
+     * A **pre-computed** `ValueSet.expansion` is **incomplete** — its `total` exceeds the number of
+     * `contains` entries, or it is flagged too-costly (the VSAC `$expand` >1200-code truncation hazard,
+     * roadmap §4.4). The engine **never treats a truncated expansion as complete membership**: a code
+     * absent from a truncated expansion is `undetermined`, never a confident "not a member".
+     */
+    readonly TERM_VALUESET_EXPANSION_TRUNCATED: "TERM_VALUESET_EXPANSION_TRUNCATED";
+    /**
+     * A UCUM unit expression is **not valid** — it does not parse against the UCUM grammar, or it
+     * names an atom absent from the vendored UCUM table. A **first-class typed outcome, never an
+     * error and never a guess**: {@link validateUcum} returns `{ valid: false, reason }`, never a
+     * coerced or "nearest" unit (the never-fabricate invariant, applied to units — roadmap §4.3). The
+     * `reason` is value-free (a grammar fault or an unknown-atom shape), never PHI.
+     */
+    readonly TERM_UCUM_INVALID: "TERM_UCUM_INVALID";
+    /**
+     * A crosswalk source code has an **authored No-Map** — the steward declares it has no valid target
+     * in the other classification (a GEM `NoDx`/`NoPCS` sentinel, or a SNOMED complex-map `447638001`
+     * "cannot be classified" category). A **first-class typed outcome, never an error and never a
+     * guess** (the never-fabricate invariant, applied to crosswalks — roadmap §4.1). Distinct from
+     * {@link TERM_CROSSWALK_UNMAPPED}: the source *is* in the map, and the map says "no target".
+     */
+    readonly TERM_CROSSWALK_NO_MAP: "TERM_CROSSWALK_NO_MAP";
+    /**
+     * A crosswalk source code is **absent from the map entirely** — not an authored No-Map, simply not
+     * present. Surfaced as a typed outcome (never a fabricated target, never a silent success), and
+     * kept distinct from {@link TERM_CROSSWALK_NO_MAP} so a caller can tell "the steward said no target"
+     * from "this code was not in the file".
+     */
+    readonly TERM_CROSSWALK_UNMAPPED: "TERM_CROSSWALK_UNMAPPED";
+    /**
+     * A SNOMED→ICD-10-CM complex-map group's decision needs **patient context** (an `IFA` age band or
+     * gender) the caller did not supply. The engine surfaces the candidate rules + advice and **refuses
+     * to pick a branch** it lacks the data for (roadmap §4.1) — never a silently-chosen target.
+     */
+    readonly TERM_CROSSWALK_CONTEXT_REQUIRED: "TERM_CROSSWALK_CONTEXT_REQUIRED";
+    /**
+     * A GEM file line was structurally unusable — not three whitespace-delimited fields, or a flag
+     * field that is not a 5-digit code. The row is **skipped and surfaced** as a load warning (liberal
+     * on load), never kept as a partially-parsed entry.
+     */
+    readonly TERM_GEM_MALFORMED_ROW: "TERM_GEM_MALFORMED_ROW";
+    /**
+     * A SNOMED complex-map RF2 refset row was structurally unusable — missing its
+     * `referencedComponentId`/`mapGroup`/`mapPriority`. Skipped and surfaced, never partial.
+     */
+    readonly TERM_COMPLEX_MAP_MALFORMED_ROW: "TERM_COMPLEX_MAP_MALFORMED_ROW";
+    /**
+     * A RxNorm RRF row (`RXNCONSO` / `RXNREL` / `RXNSAT`) was structurally unusable — too few columns to
+     * reach a required field, or a missing `RXCUI`/NDC value. The row is **skipped and surfaced** as a
+     * load warning (liberal on load), never kept as a partial concept/edge. Rows that are simply *not of
+     * interest* (a non-`RXNORM` atom, an atom-level relationship, a non-`NDC` attribute) are skipped
+     * **silently** — they are expected, not faults.
+     */
+    readonly TERM_RXNORM_MALFORMED_ROW: "TERM_RXNORM_MALFORMED_ROW";
+    /**
+     * A RxNorm graph navigation was asked about an `RXCUI` **absent from the loaded release** — a
+     * first-class typed outcome, never a fabricated concept and never an empty "success" (the
+     * never-fabricate invariant, applied to the drug graph — roadmap §4.2). Distinct from a *present*
+     * concept that simply has no edge of the requested relationship (that is a found result with empty
+     * targets).
+     */
+    readonly TERM_RXNORM_UNKNOWN_RXCUI: "TERM_RXNORM_UNKNOWN_RXCUI";
+    /**
+     * An NDC could **not be resolved** to any `RXCUI` in the loaded RxNorm release — a typed, surfaced
+     * absence, never a guessed `RXCUI`. NDC↔RXCUI is many:1 and temporal (roadmap §4.2), so a resolution
+     * is always release-scoped; an NDC not present in the loaded release is this diagnostic.
+     */
+    readonly TERM_RXNORM_NDC_UNMAPPED: "TERM_RXNORM_NDC_UNMAPPED";
+};
+/**
+ * A value from {@link DIAGNOSTIC_CODES} — the type consumers narrow a diagnostic's `code` against.
+ */
+type DiagnosticCode = (typeof DIAGNOSTIC_CODES)[keyof typeof DIAGNOSTIC_CODES];
+/**
+ * Stable **fatal codes** — thrown (as a {@link TerminologyError}) when input cannot be loaded into
+ * a usable model at all. Always thrown, never swallowed. `key === value`, part of the contract.
+ *
+ * @example
+ * ```ts
+ * import { FATAL_CODES } from "@cosyte/terminology";
+ *
+ * FATAL_CODES.TERM_CONCEPTMAP_MALFORMED; // => "TERM_CONCEPTMAP_MALFORMED"
+ * ```
+ */
+declare const FATAL_CODES: {
+    /**
+     * A `ConceptMap` resource was structurally unusable — wrong `resourceType`, or a group/element
+     * missing a required field. Thrown rather than silently loading a partial, misleading map.
+     */
+    readonly TERM_CONCEPTMAP_MALFORMED: "TERM_CONCEPTMAP_MALFORMED";
+    /**
+     * A CodeSystem *source* was structurally unusable — a FHIR resource with the wrong `resourceType`,
+     * or a delimited source whose configured code/display column is absent from the header. Thrown
+     * rather than silently loading an empty or mis-keyed release. (Malformed individual **rows** are
+     * skipped-and-surfaced load warnings, not fatals — only an unusable *source* is fatal.)
+     */
+    readonly TERM_CODESYSTEM_MALFORMED: "TERM_CODESYSTEM_MALFORMED";
+    /**
+     * A `ValueSet` resource was structurally unusable — wrong `resourceType`, or a `compose`/`expansion`
+     * whose required shape (an `include` that is not an object, a `contains` entry missing its `code`)
+     * is corrupt. Thrown rather than silently loading a partial value set that would bind *some* codes
+     * and quietly drop others. (A `filter` operator the engine does not implement is **not** fatal — it
+     * is the surfaced `TERM_VALUESET_CANNOT_EXPAND` diagnostic at expansion time.)
+     */
+    readonly TERM_VALUESET_MALFORMED: "TERM_VALUESET_MALFORMED";
+    /**
+     * A crosswalk map *source* was structurally unusable — e.g. a SNOMED complex-map RF2 refset with
+     * empty content or a header missing a required column. Thrown rather than silently loading an empty
+     * or mis-keyed map. (Malformed individual **rows** are skipped-and-surfaced warnings, not fatals.)
+     */
+    readonly TERM_CROSSWALK_MALFORMED: "TERM_CROSSWALK_MALFORMED";
+    /**
+     * An **inversion** of a directional crosswalk was requested — a forbidden operation. The GEMs and
+     * the SNOMED→ICD-10-CM map are authoritative in **one direction only**; a forward map is not the
+     * inverse of the backward map (roadmap §4.1). Thrown by {@link ../crosswalk/gems.invertGem} so the
+     * never-invert refusal is a first-class, discoverable contract rather than a silent absence.
+     */
+    readonly TERM_MAP_NOT_INVERTIBLE: "TERM_MAP_NOT_INVERTIBLE";
+};
+/**
+ * A value from {@link FATAL_CODES} — the type carried by a thrown {@link TerminologyError}.
+ */
+type FatalCode = (typeof FATAL_CODES)[keyof typeof FATAL_CODES];
+/**
+ * The engine's typed error. Carries a stable {@link FatalCode} so callers branch on `err.code`
+ * without string-matching the message. Thrown only for {@link FATAL_CODES} conditions.
+ *
+ * The `message` is **value-free**: it names the structural fault (a resource path, a missing
+ * field) and never echoes input *values*.
+ *
+ * @example
+ * ```ts
+ * import { loadConceptMap, TerminologyError, FATAL_CODES } from "@cosyte/terminology";
+ *
+ * try {
+ *   loadConceptMap({ resourceType: "Patient" });
+ * } catch (err) {
+ *   (err as TerminologyError).code === FATAL_CODES.TERM_CONCEPTMAP_MALFORMED; // => true
+ * }
+ * ```
+ */
+declare class TerminologyError extends Error {
+    /** The stable fatal code. Branch on this, not on {@link message}. */
+    readonly code: FatalCode;
+    /**
+     * @param code - The stable {@link FatalCode} describing the fault.
+     * @param message - A **value-free** structural description (path + fault; never an input value).
+     */
+    constructor(code: FatalCode, message: string);
+}
+
+/**
+ * Minimal, zero-dependency navigation helpers for **untrusted FHIR JSON** (`unknown` inputs
+ * decoded from a consumer-supplied `ConceptMap`/`CodeSystem`/`ValueSet`).
+ *
+ * The engine never trusts the shape of its inputs: every accessor here narrows an `unknown`
+ * to a concrete type or returns `undefined`, so a malformed resource degrades to a typed
+ * diagnostic (see {@link ../conceptmap/load}) rather than a `TypeError` deep in a getter. This
+ * is the terminology-engine analogue of a parser's lenient tokenizer — liberal on load.
+ *
+ * These helpers are **value-free**: they read structure, never log or echo field *values*, so a
+ * code-in-context (which can be PHI, per the roadmap's PHI posture) never flows into a message.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Narrow an `unknown` to a plain JSON object (a non-null, non-array `object`).
+ *
+ * @param value - The value to test.
+ * @returns `true` when `value` is a non-null, non-array object.
+ * @example
+ * ```ts
+ * import { isJsonObject } from "@cosyte/terminology";
+ *
+ * isJsonObject({ resourceType: "ConceptMap" }); // => true
+ * ```
+ */
+declare function isJsonObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Read a **string** property from an untrusted object, or `undefined` if absent/not a string.
+ *
+ * @param obj - The source object (may be any `unknown`).
+ * @param key - The property name to read.
+ * @returns The string value, or `undefined` when the key is missing or not a string.
+ * @example
+ * ```ts
+ * import { getString } from "@cosyte/terminology";
+ *
+ * getString({ url: "http://loinc.org" }, "url"); // => "http://loinc.org"
+ * ```
+ */
+declare function getString(obj: unknown, key: string): string | undefined;
+/**
+ * Read an **array** property from an untrusted object as a `readonly unknown[]`, or `undefined`.
+ *
+ * The elements are left as `unknown` — callers narrow each one. A non-array (including a missing
+ * key) yields `undefined`, which callers treat as "no entries" rather than an error.
+ *
+ * @param obj - The source object (may be any `unknown`).
+ * @param key - The property name to read.
+ * @returns The array (elements untyped), or `undefined` when the key is missing or not an array.
+ * @example
+ * ```ts
+ * import { getArray } from "@cosyte/terminology";
+ *
+ * getArray({ group: [{ source: "a" }] }, "group")?.length; // => 1
+ * ```
+ */
+declare function getArray(obj: unknown, key: string): readonly unknown[] | undefined;
+/**
+ * Read a **boolean** property from an untrusted object, or `undefined` if absent/not a boolean.
+ *
+ * A non-boolean (including a missing key, or the strings `"true"`/`"false"`) yields `undefined` —
+ * the accessor never coerces, so a caller can distinguish "explicitly `false`" from "absent".
+ *
+ * @param obj - The source object (may be any `unknown`).
+ * @param key - The property name to read.
+ * @returns The boolean value, or `undefined` when the key is missing or not a boolean.
+ * @example
+ * ```ts
+ * import { getBoolean } from "@cosyte/terminology";
+ *
+ * getBoolean({ inactive: true }, "inactive"); // => true
+ * ```
+ */
+declare function getBoolean(obj: unknown, key: string): boolean | undefined;
+/**
+ * Read a **number** property from an untrusted object, or `undefined` if absent/not a finite number.
+ *
+ * @param obj - The source object (may be any `unknown`).
+ * @param key - The property name to read.
+ * @returns The number value, or `undefined` when the key is missing or not a finite number.
+ * @example
+ * ```ts
+ * import { getNumber } from "@cosyte/terminology";
+ *
+ * getNumber({ valueInteger: 3 }, "valueInteger"); // => 3
+ * ```
+ */
+declare function getNumber(obj: unknown, key: string): number | undefined;
+
+/**
+ * The **code-system identity registry** — the grounded OID ↔ canonical-URI ↔ mnemonic facts the
+ * ecosystem uses.
+ *
+ * A code-system *identity* (the triple of canonical URI, OID, and HL7 v2 mnemonic that all name
+ * the same terminology) is a **published fact**, not copyrighted content — so it is encoded here,
+ * cited firsthand. This is the license line the roadmap draws: identities are facts we may encode;
+ * the code *lists themselves* (SNOMED/CPT/LOINC content) are BYO and never bundled.
+ *
+ * **Every identity below is grounded firsthand against a primary source** (verified 2026-07-21):
+ *
+ * - The FHIR R4 terminology-systems registry — `https://hl7.org/fhir/R4/terminologies-systems.html`
+ *   — for LOINC, SNOMED CT, RxNorm, UCUM, CPT, NDC, CVX (canonical URI + OID), and for the HL7 v2
+ *   table URI/OID patterns (`http://terminology.hl7.org/CodeSystem/v2-[X]` ↔
+ *   `2.16.840.1.113883.12.[X]`).
+ * - The FHIR R4 ICD page — `https://hl7.org/fhir/R4/icd.html` — for ICD-10-CM
+ *   (`http://hl7.org/fhir/sid/icd-10-cm` ↔ `2.16.840.1.113883.6.90`).
+ * - HL7 Table 0396 (coding-system mnemonics) — the THO `v2-0396` code system — for the mnemonics
+ *   (`LN`, `SCT`, `I10C`, `RXNORM`, `UCUM`, `C4`, `NDC`, `CVX`).
+ *
+ * Identities that could not be pinned to a primary source firsthand this pass are **omitted**, not
+ * guessed (roadmap: "do not guess an identity") — notably ICD-9-CM and ICD-10-PCS, whose OID
+ * assignments were ambiguous across sources.
+ *
+ * @packageDocumentation
+ */
+/**
+ * A resolved code-system identity — the canonical URI plus the alternate identifiers that name the
+ * same system.
+ */
+interface SystemIdentity {
+    /** The canonical URI — the single value the engine treats as the system's identity. */
+    readonly url: string;
+    /** The registered OID (bare, no `urn:oid:` prefix), when the system has one. */
+    readonly oid?: string;
+    /** A short human-readable name for diagnostics/logs (value-free — a system name, never a value). */
+    readonly name: string;
+    /** HL7 v2 Table 0396 mnemonic(s) and other accepted short aliases for this system. */
+    readonly mnemonics: readonly string[];
+}
+/**
+ * The seed identity table. Order is irrelevant; lookup indexes are built from it in
+ * {@link ../systems/resolve}. Each entry is one firsthand-grounded system (see the module doc).
+ */
+declare const SYSTEM_IDENTITIES: readonly SystemIdentity[];
+/**
+ * The OID root under which every HL7 v2 table code system is registered:
+ * `2.16.840.1.113883.12.[table]` — grounded against the FHIR R4 terminology-systems registry.
+ * The table number is appended with no leading zeros (e.g. table 0203 → `…12.203`).
+ */
+declare const HL7_V2_OID_ROOT = "2.16.840.1.113883.12";
+/**
+ * The canonical URI prefix for HL7 v2 table code systems in HL7 Terminology (THO):
+ * `http://terminology.hl7.org/CodeSystem/v2-[XXXX]`, where `[XXXX]` is the zero-padded 4-digit
+ * table id — grounded against the FHIR R4 terminology-systems registry.
+ */
+declare const HL7_V2_URL_PREFIX = "http://terminology.hl7.org/CodeSystem/v2-";
+
+/**
+ * The **code-system identity / canonical-URI resolver** — `resolveSystem`.
+ *
+ * Given a code system named any of the ways the ecosystem names it — a canonical URI, an OID (bare
+ * or `urn:oid:`-prefixed), or an HL7 v2 mnemonic (`LN`, `SCT`, …) — it returns the one canonical
+ * {@link SystemIdentity}. This is the piece `@cosyte/transform` pins so a `Coding` off any parser
+ * (HL7 v2 CE/CWE, C-CDA, FHIR) can be canonicalized to a single system URI before translation.
+ *
+ * **Never guesses.** An identifier that matches nothing known returns a typed
+ * `{ unknown: true, input }` — never a fabricated URI (the never-fabricate invariant, applied to
+ * system identity).
+ *
+ * @packageDocumentation
+ */
+
+/** The typed "not recognized" outcome from {@link resolveSystem} — surfaced, never a guess. */
+interface UnknownSystem {
+    /** Discriminant: the identifier was not recognized. */
+    readonly unknown: true;
+    /** The identifier as supplied, echoed back so the caller can surface/log it. */
+    readonly input: string;
+}
+/** The result of {@link resolveSystem}: a resolved {@link SystemIdentity} or a typed unknown. */
+type ResolveSystemResult = SystemIdentity | UnknownSystem;
+/**
+ * Resolve a code-system identifier to its canonical {@link SystemIdentity}.
+ *
+ * Accepts, in order of attempt: a canonical URI (case-insensitive), a `v2-XXXX` mnemonic or a
+ * v2 table URI/OID (resolved structurally), a bare or `urn:oid:`-prefixed OID, or an HL7 v2
+ * Table 0396 mnemonic. Whitespace is trimmed. An empty or unrecognized identifier yields a typed
+ * {@link UnknownSystem} — the resolver **never** invents a URI.
+ *
+ * @param id - The identifier (canonical URI, OID, `urn:oid:` OID, or mnemonic).
+ * @returns The resolved {@link SystemIdentity}, or `{ unknown: true, input }`.
+ * @example
+ * ```ts
+ * import { resolveSystem } from "@cosyte/terminology";
+ *
+ * resolveSystem("2.16.840.1.113883.6.1"); // => { url: "http://loinc.org", … }
+ * resolveSystem("SCT"); // => { url: "http://snomed.info/sct", … }
+ * resolveSystem("http://example.com/nope"); // => { unknown: true, input: "http://example.com/nope" }
+ * ```
+ */
+declare function resolveSystem(id: string): ResolveSystemResult;
+/**
+ * Type guard: did {@link resolveSystem} fail to recognize the identifier?
+ *
+ * @param result - A {@link resolveSystem} result.
+ * @returns `true` when the result is a typed {@link UnknownSystem}.
+ * @example
+ * ```ts
+ * import { resolveSystem, isUnknownSystem } from "@cosyte/terminology";
+ *
+ * isUnknownSystem(resolveSystem("nope")); // => true
+ * ```
+ */
+declare function isUnknownSystem(result: ResolveSystemResult): result is UnknownSystem;
+
+/**
+ * The types for the ConceptMap `$translate` engine — the loaded {@link ConceptMap} model, the
+ * normalized {@link Relationship} enum, and the fail-safe {@link TranslateResult}.
+ *
+ * The engine targets **FHIR R4** ConceptMap input (`element.target.equivalence`), but carries an
+ * internal, version-neutral {@link Relationship} model that maps cleanly to **both** R4
+ * `equivalence` and R5 `relationship` (the enum was renamed and re-valued between versions). Each
+ * match surfaces both the normalized relationship and the verbatim R4 token it came from, so no
+ * information is dropped and a consumer can render either vocabulary.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * The verbatim **FHIR R4** `ConceptMap.group.element.target.equivalence` value, carried through
+ * untouched so nothing the map author asserted is lost. (R4 enum:
+ * `relatedto | equivalent | equal | wider | subsumes | narrower | specializes | inexact |
+ * unmatched | disjoint`.)
+ */
+type R4Equivalence = "relatedto" | "equivalent" | "equal" | "wider" | "subsumes" | "narrower" | "specializes" | "inexact" | "unmatched" | "disjoint";
+/**
+ * The engine's **normalized, version-neutral relationship** between a source and a target concept —
+ * the FHIR **R5** vocabulary, which the R4 `equivalence` tokens fold into cleanly. Surfaced on every
+ * match alongside the verbatim R4 token.
+ *
+ * - `equivalent` ← R4 `equivalent` / `equal`
+ * - `source-is-narrower-than-target` ← R4 `wider` / `subsumes` (the source is-a the target)
+ * - `source-is-broader-than-target` ← R4 `narrower` / `specializes` (the target is-a the source)
+ * - `related-to` ← R4 `relatedto` / `inexact`
+ * - `not-related-to` ← R4 `disjoint` / `unmatched`
+ */
+type Relationship = "equivalent" | "source-is-narrower-than-target" | "source-is-broader-than-target" | "related-to" | "not-related-to";
+/**
+ * One target concept a {@link translate} call produced, with its relationship to the source and
+ * the verbatim R4 equivalence token. Never fabricated — every field is drawn from the loaded map.
+ */
+interface TranslateMatch {
+    /** The target {@link Coding} exactly as declared in the map (frozen). */
+    readonly target: Coding;
+    /** The normalized, version-neutral relationship (R5 vocabulary). */
+    readonly relationship: Relationship;
+    /** The verbatim FHIR R4 `equivalence` token this match was declared with. */
+    readonly equivalence: R4Equivalence;
+    /** Author's free-text comment on this mapping, when present (carried verbatim, e.g. map advice). */
+    readonly comment?: string;
+}
+/**
+ * The FHIR R4 `group.unmapped.mode` an unmapped source fell through to — the map author's declared
+ * fallback behavior. Surfaced (never silently acted on): the caller decides whether to trust a
+ * fallback.
+ *
+ * - `provided` — echo the source code as the target (the map declares no real mapping).
+ * - `fixed` — a single fixed fallback code the map declares for *all* unmapped sources.
+ * - `other-map` — consult the referenced ConceptMap (which this engine does not auto-follow).
+ * - `none` — no `group.unmapped` directive applied (plain no-match, or an explicit `unmatched`).
+ */
+type UnmappedMode = "provided" | "fixed" | "other-map" | "none";
+/** Provenance of a translation — which map (and which group's systems) produced it. */
+interface MapProvenance {
+    /** The ConceptMap's canonical `url`, when declared. */
+    readonly conceptMapUrl?: string;
+    /** The ConceptMap's business `version`, when declared (mappings are release-scoped). */
+    readonly conceptMapVersion?: string;
+    /** The source code system of the group that matched (or was consulted), when known. */
+    readonly sourceSystem?: string;
+    /** The target code system of the group that matched, when known. */
+    readonly targetSystem?: string;
+}
+/** A successful translation: one or more matches, never empty (an empty result is `unmapped`). */
+interface TranslateMatched {
+    /** Discriminant: the source mapped. */
+    readonly unmapped: false;
+    /** The target concepts, in declared order. Non-empty and frozen. */
+    readonly matches: readonly TranslateMatch[];
+    /** Where this translation came from. */
+    readonly provenance: MapProvenance;
+}
+/**
+ * A **fail-safe unmapped** translation — the never-fabricate outcome. The source is surfaced as-is;
+ * **no target is ever guessed**. Any `group.unmapped` fallback the author declared is reported via
+ * {@link UnmappedMode} (and `fixedTarget`/`otherMapUrl`) for the caller to accept or reject — the
+ * engine does not silently substitute it.
+ */
+interface TranslateUnmapped {
+    /** Discriminant: the source did not map. */
+    readonly unmapped: true;
+    /** The stable diagnostic code for an unmapped translation. */
+    readonly code: "TERM_TRANSLATE_UNMAPPED";
+    /** The map author's declared fallback mode (or `none`). */
+    readonly mode: UnmappedMode;
+    /** The original source {@link Coding}, surfaced untouched. */
+    readonly source: Coding;
+    /** For `mode: "fixed"`, the author's fixed fallback coding — reported, not auto-applied. */
+    readonly fixedTarget?: Coding;
+    /** For `mode: "other-map"`, the referenced map's URL — reported, not auto-followed. */
+    readonly otherMapUrl?: string;
+    /** Where the (failed) translation was attempted. */
+    readonly provenance: MapProvenance;
+}
+/** The result of {@link translate}: a matched result or a typed {@link TranslateUnmapped}. */
+type TranslateResult = TranslateMatched | TranslateUnmapped;
+/**
+ * A single `group.unmapped` directive from a loaded ConceptMap group (FHIR R4).
+ */
+interface ConceptMapUnmapped {
+    /** The fallback mode. */
+    readonly mode: UnmappedMode;
+    /** For `fixed`, the fixed target code. */
+    readonly code?: string;
+    /** For `fixed`, the fixed target display. */
+    readonly display?: string;
+    /** For `other-map`, the canonical URL of the map to consult. */
+    readonly url?: string;
+}
+/** One `group.element.target` — a candidate target for a source concept (FHIR R4). */
+interface ConceptMapTarget {
+    /** The target code (absent for a pure `unmatched` assertion). */
+    readonly code?: string;
+    /** The target display, carried verbatim when present. */
+    readonly display?: string;
+    /** The verbatim R4 equivalence token. */
+    readonly equivalence: R4Equivalence;
+    /** Author's comment (e.g. steward map advice), carried verbatim. */
+    readonly comment?: string;
+}
+/** One `group.element` — a source concept and its candidate targets (FHIR R4). */
+interface ConceptMapElement {
+    /** The source code. */
+    readonly code?: string;
+    /** The source display. */
+    readonly display?: string;
+    /** The candidate targets. */
+    readonly target: readonly ConceptMapTarget[];
+}
+/** One `group` — a source-system/target-system pair with its element mappings (FHIR R4). */
+interface ConceptMapGroup {
+    /** The group's source code system (canonical URI), when declared. */
+    readonly source?: string;
+    /** The group's source system version, when declared. */
+    readonly sourceVersion?: string;
+    /** The group's target code system (canonical URI), when declared. */
+    readonly target?: string;
+    /** The group's target system version, when declared. */
+    readonly targetVersion?: string;
+    /** The element mappings. */
+    readonly element: readonly ConceptMapElement[];
+    /** The `group.unmapped` fallback directive, when declared. */
+    readonly unmapped?: ConceptMapUnmapped;
+}
+/**
+ * A loaded, immutable ConceptMap — the subset of the FHIR R4 `ConceptMap` resource the
+ * `$translate` engine needs. Produced by {@link loadConceptMap}; every field frozen.
+ */
+interface ConceptMap {
+    /** The resource's canonical `url`, when declared. */
+    readonly url?: string;
+    /** The resource's business `version`, when declared. */
+    readonly version?: string;
+    /** The map's `sourceUri`/`sourceCanonical` scope, when declared. */
+    readonly sourceScope?: string;
+    /** The map's `targetUri`/`targetCanonical` scope, when declared. */
+    readonly targetScope?: string;
+    /** The translation groups. */
+    readonly group: readonly ConceptMapGroup[];
+}
+
+/**
+ * {@link loadConceptMap} — validate and normalize an untrusted FHIR R4 `ConceptMap` JSON resource
+ * into the immutable {@link ConceptMap} model the `$translate` engine runs over.
+ *
+ * **Conservative on load** (unlike a wire parser's lenient posture): a ConceptMap drives a clinical
+ * translation, so a structurally unusable map is a typed **fatal**
+ * ({@link FATAL_CODES.TERM_CONCEPTMAP_MALFORMED}), never a silently partial map that would translate
+ * *some* codes and quietly drop others. Fault messages are **value-free** — they name the resource
+ * *path* and the fault, never echo a code or display *value*.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Load an untrusted FHIR R4 `ConceptMap` JSON value into an immutable {@link ConceptMap}.
+ *
+ * Accepts the standard resource shape: a top-level object with `resourceType: "ConceptMap"` and an
+ * optional `group[]`. `source[x]`/`target[x]` scopes are read from either the `Uri` or `Canonical`
+ * variant. The result is deep-frozen. Anything structurally unusable throws a
+ * {@link TerminologyError} carrying {@link FATAL_CODES.TERM_CONCEPTMAP_MALFORMED}.
+ *
+ * @param json - The untrusted resource (typically `JSON.parse` output — hence `unknown`).
+ * @returns The immutable, validated {@link ConceptMap}.
+ * @throws {TerminologyError} `TERM_CONCEPTMAP_MALFORMED` when the resource is not a usable ConceptMap.
+ * @example
+ * ```ts
+ * import { loadConceptMap } from "@cosyte/terminology";
+ *
+ * const map = loadConceptMap({
+ *   resourceType: "ConceptMap",
+ *   url: "http://example.org/cm/gender",
+ *   group: [
+ *     {
+ *       source: "http://hl7.org/fhir/administrative-gender",
+ *       target: "http://terminology.hl7.org/CodeSystem/v2-0001",
+ *       element: [{ code: "male", target: [{ code: "M", equivalence: "equivalent" }] }],
+ *     },
+ *   ],
+ * });
+ * map.group.length; // => 1
+ * ```
+ */
+declare function loadConceptMap(json: unknown): ConceptMap;
+
+/**
+ * {@link translate} — the ConceptMap `$translate` engine, modeled on the FHIR
+ * `ConceptMap/$translate` operation.
+ *
+ * Given a source {@link Coding} and a loaded {@link ConceptMap}, it returns the declared target
+ * code(s) with their FHIR relationship and the map's provenance — or, when the source does not map,
+ * a **typed {@link TranslateUnmapped}**. This slice births the invariants every later phase
+ * inherits:
+ *
+ * 1. **Never fabricate.** An unmapped source yields a surfaced `unmapped` result — never a guessed
+ *    target. Every target returned is drawn verbatim from the map; the engine invents nothing.
+ * 2. **Never invert.** Translation reads the map in its authored direction only: a source coding is
+ *    matched against `group.element.code` (the source side) and **never** against target codes. A
+ *    directional map therefore cannot be run backwards — reverse translation requires an explicit
+ *    inverse map (a later phase), it is never synthesized here.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Translate a source {@link Coding} through a loaded {@link ConceptMap}.
+ *
+ * Matches the coding's `code` against each applicable group's `element.code` (the **source** side —
+ * never targets, so the map is never inverted) and returns every declared target for it. A target
+ * with an `unmatched` equivalence, or with no `code`, is treated as "no target" — the FHIR way of
+ * asserting a non-mapping — and does not count as a match. When nothing matches, the map author's
+ * `group.unmapped` directive (if any) is *reported* via the result's {@link UnmappedMode} but never
+ * silently applied.
+ *
+ * @param sourceCoding - The source concept to translate.
+ * @param map - A {@link ConceptMap} from {@link loadConceptMap}.
+ * @returns A {@link TranslateResult} — matched targets, or a typed unmapped outcome.
+ * @example
+ * ```ts
+ * import { loadConceptMap, translate } from "@cosyte/terminology";
+ *
+ * const map = loadConceptMap({
+ *   resourceType: "ConceptMap",
+ *   group: [
+ *     {
+ *       source: "http://hl7.org/fhir/administrative-gender",
+ *       target: "http://terminology.hl7.org/CodeSystem/v2-0001",
+ *       element: [{ code: "male", target: [{ code: "M", equivalence: "equivalent" }] }],
+ *     },
+ *   ],
+ * });
+ * const r = translate(
+ *   { system: "http://hl7.org/fhir/administrative-gender", code: "male" },
+ *   map,
+ * );
+ * r.unmapped; // => false
+ * ```
+ */
+declare function translate(sourceCoding: Coding, map: ConceptMap): TranslateResult;
+
+/**
+ * The types for the **CodeSystem load layer** and the FHIR `$lookup` / `$validate-code` operations
+ * (roadmap Phase 2): the immutable {@link CodeSystem} model, the per-concept {@link ConceptStatus},
+ * and the discriminated {@link CodeSystemSource} union the loaders accept.
+ *
+ * The model is **content-agnostic**: it is fed a code system's *release* (a consumer-supplied RRF,
+ * CSV, fixed-width file, or FHIR `CodeSystem` JSON) and answers the two identity questions. It ships
+ * **zero copyrighted content** — every concept comes from the caller's data (roadmap §5, the BYO-data
+ * posture). The FHIR operation shapes are grounded firsthand on the FHIR R4 Terminology Module
+ * (`https://hl7.org/fhir/R4/codesystem-operation-lookup.html`,
+ * `https://hl7.org/fhir/R4/codesystem-operation-validate-code.html`).
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * A concept's normalized activity — whether it is a clean, current, usable code, or carries a
+ * steward status that a caller must not ignore. `active` is the boolean convenience derived from it.
+ *
+ * - `active` — current and usable.
+ * - `deprecated` — no longer current (LOINC `DEPRECATED`; a FHIR `inactive`/`deprecated` concept).
+ * - `discouraged` / `trial` — LOINC lifecycle states (usable, but not settled).
+ * - `obsolete` — withdrawn (RxNorm `SUPPRESS = O`).
+ * - `suppressed` — editor-suppressed (RxNorm/UMLS `SUPPRESS = Y`/`E`).
+ * - `header` — a classification header, **not a billable/valid leaf** (ICD-10-CM flag `0`).
+ * - `unknown` — a status token the mapper did not recognize; carried verbatim, never guessed clean.
+ */
+type ConceptActivity = "active" | "deprecated" | "discouraged" | "trial" | "obsolete" | "suppressed" | "header" | "unknown";
+/**
+ * The status flags a `$lookup`/`$validate-code` carries on a concept — the safety surface that stops
+ * a non-current or non-billable code from being presented as clean (roadmap §4.4). Present only when
+ * the loaded release supplied status information; the engine never fabricates a status.
+ */
+interface ConceptStatus {
+    /** The normalized {@link ConceptActivity}. */
+    readonly activity: ConceptActivity;
+    /** Convenience: `activity === "active"`. A caller can gate on this without a switch. */
+    readonly active: boolean;
+    /** For classification systems (ICD-10-CM): is this a billable/valid leaf? A header is `false`. */
+    readonly billable?: boolean;
+    /** The steward's raw status token, carried verbatim (e.g. `"DEPRECATED"`, `"O"`, `"0"`). */
+    readonly raw?: string;
+    /** A stable {@link DiagnosticCode} naming the concern, when the concept is not clean-active. */
+    readonly code?: DiagnosticCode;
+}
+/**
+ * One property value on a concept — models FHIR R4 `$lookup` `property` ("one or more properties
+ * that contain additional information about the code, including status"). Carried verbatim from the
+ * release; never fabricated.
+ */
+interface Property {
+    /** Identifies the property (FHIR `property.code`), e.g. `"shortDescription"`, `"TTY"`, `"parent"`. */
+    readonly code: string;
+    /** The property value (FHIR `property.value[x]`), reduced to the primitive kinds the readers emit. */
+    readonly value: string | boolean | number;
+    /** Optional human-readable rendering of the value (FHIR `property.description`). */
+    readonly description?: string;
+}
+/**
+ * One loaded, immutable concept — the subset of a `CodeSystem.concept` the operations need.
+ */
+interface Concept {
+    /** The code, exactly as it appears in the release. */
+    readonly code: string;
+    /** The preferred display, carried verbatim. Absent when the release supplied none (never invented). */
+    readonly display?: string;
+    /** The formal definition, when the release supplied one. */
+    readonly definition?: string;
+    /** The concept's status flags, when the release carried status information. */
+    readonly status?: ConceptStatus;
+    /** Additional properties, in load order. Frozen; may be empty, never fabricated. */
+    readonly properties: readonly Property[];
+}
+/**
+ * A surfaced, non-fatal load warning — a malformed row that was **skipped**, reported with its line
+ * number and a **value-free** structural reason (never the row's content). Liberal on load.
+ */
+interface LoadWarning {
+    /** The stable diagnostic code (`TERM_RRF_MALFORMED_ROW` / `_CSV_MALFORMED` / `_FIXED_WIDTH_MALFORMED`). */
+    readonly code: DiagnosticCode;
+    /** The 1-based source line the fault was found on (positional context; value-free). */
+    readonly line: number;
+    /** A value-free description of the structural fault (never echoes a field value). */
+    readonly detail: string;
+}
+/**
+ * A loaded, immutable code-system release — the queryable model {@link loadCodeSystem} produces and
+ * {@link lookup} / {@link validateCode} run over. Concepts are keyed by code for O(1) identity; the
+ * map is exposed `readonly` and every concept is frozen.
+ */
+interface CodeSystem {
+    /** The code system's canonical URI, when supplied by the source. */
+    readonly url?: string;
+    /** The release version, when supplied — mappings and displays are release-scoped. */
+    readonly version?: string;
+    /** A short human-readable name, when supplied. */
+    readonly name?: string;
+    /** The number of loaded concepts. */
+    readonly count: number;
+    /** The concepts, keyed by `code`. Read-only; every value frozen. */
+    readonly concepts: ReadonlyMap<string, Concept>;
+    /** The skipped-row warnings surfaced during load, in line order. Frozen; may be empty. */
+    readonly warnings: readonly LoadWarning[];
+}
+/** A successful {@link lookup}: the concept's details plus its release provenance. */
+interface LookupResult {
+    /** Discriminant: the code was found. */
+    readonly found: true;
+    /** The code, echoed. */
+    readonly code: string;
+    /** The preferred display, when the release carried one (never fabricated). */
+    readonly display?: string;
+    /** The formal definition, when present. */
+    readonly definition?: string;
+    /** The concept's status flags, when present. */
+    readonly status?: ConceptStatus;
+    /** The concept's properties, in load order (frozen, may be empty). */
+    readonly properties: readonly Property[];
+    /** The code system's canonical URI, when known. */
+    readonly system?: string;
+    /** The release version, when known. */
+    readonly version?: string;
+}
+/** A **fail-safe unknown** {@link lookup} — the never-fabricate outcome; no display is ever guessed. */
+interface LookupUnknown {
+    /** Discriminant: the code was not found. */
+    readonly found: false;
+    /** The stable diagnostic code for an unknown code. */
+    readonly code: "TERM_CODE_UNKNOWN";
+    /** The code that was looked up, echoed so the caller can surface it. */
+    readonly input: string;
+}
+/** The result of {@link lookup}: a found concept or a typed {@link LookupUnknown}. */
+type LookupOutcome = LookupResult | LookupUnknown;
+/**
+ * The result of {@link validateCode} — models FHIR R4 `$validate-code`'s `result` boolean. A found
+ * concept is `valid: true` **carrying its status** (a deprecated or header code validates as present
+ * but is flagged, never presented clean); an absent code is `valid: false`, never a guessed `true`.
+ */
+interface ValidateCodeResult {
+    /** FHIR `result`: true if the code is a valid member of the code system. */
+    readonly valid: boolean;
+    /** The concept's status flags, when the code was found and the release carried status. */
+    readonly status?: ConceptStatus;
+    /** For an invalid code, the stable diagnostic (`TERM_CODE_UNKNOWN`); absent when valid. */
+    readonly code?: DiagnosticCode;
+}
+/** A mapper from a raw steward status token to a normalized {@link ConceptActivity}. Overridable. */
+type StatusMapper = (raw: string) => ConceptActivity;
+/** A half-open `[start, end)` slice of a fixed-width line (0-based char indices; `end` optional). */
+interface FieldSlice {
+    /** The 0-based start char index (inclusive). */
+    readonly start: number;
+    /** The 0-based end char index (exclusive). Omit to slice to end of line. */
+    readonly end?: number;
+}
+/** One extra RRF column to capture as a {@link Property}. */
+interface RrfPropertyColumn {
+    /** The property code to emit. */
+    readonly name: string;
+    /** The 0-based column index. */
+    readonly column: number;
+}
+/** The column mapping for an {@link RrfSource} (0-based column indices into the pipe-split row). */
+interface RrfColumnMap {
+    /** The column holding the concept code (e.g. RxNorm `RXCUI` = 0, or `CODE` = 13). */
+    readonly code: number;
+    /** The column holding the display string (e.g. `STR` = 14). */
+    readonly display: number;
+    /** The column holding a status/suppress token (e.g. `SUPPRESS` = 16), when present. */
+    readonly status?: number;
+    /** Extra columns to surface as properties. */
+    readonly properties?: readonly RrfPropertyColumn[];
+}
+/**
+ * An **RRF** (Rich Release Format — pipe-delimited RxNorm/UMLS release) source. One parameterized
+ * reader serves both: RxNorm `RXNCONSO`/`RXNSAT` and UMLS `MRCONSO`/`MRSAT` share the RRF shape
+ * (pipe-delimited, one trailing pipe per line). BYO — the consumer supplies the file.
+ */
+interface RrfSource {
+    /** Discriminant. */
+    readonly format: "rrf";
+    /** The raw RRF file content. */
+    readonly content: string;
+    /** Which columns hold the code/display/status/properties. */
+    readonly columns: RrfColumnMap;
+    /** The code system's canonical URI, attached to the loaded release. */
+    readonly url?: string;
+    /** A human-readable name. */
+    readonly name?: string;
+    /** The release version (RRF carries none inline — supply it so displays stay release-scoped). */
+    readonly version?: string;
+    /** Override the default status interpretation of the `status` column's raw token. */
+    readonly statusMap?: StatusMapper;
+}
+/** The column mapping for a {@link CsvSource} (header names, matched against the header row). */
+interface CsvColumnMap {
+    /** The header name of the code column (e.g. LOINC `LOINC_NUM`). */
+    readonly code: string;
+    /** The header name of the display column (e.g. LOINC `LONG_COMMON_NAME`). */
+    readonly display: string;
+    /** The header name of a status column (e.g. LOINC `STATUS`), when present. */
+    readonly status?: string;
+    /** Header names to surface as properties. */
+    readonly properties?: readonly string[];
+}
+/**
+ * An **RFC-4180 CSV** source (quoted fields, embedded commas/quotes/newlines) — e.g. LOINC's
+ * `Loinc.csv`. The one release format that needs real quote handling; hand-rolled, zero-dep. BYO.
+ */
+interface CsvSource {
+    /** Discriminant. */
+    readonly format: "csv";
+    /** The raw CSV file content. */
+    readonly content: string;
+    /** Which header-named columns hold the code/display/status/properties. */
+    readonly columns: CsvColumnMap;
+    /** The code system's canonical URI. */
+    readonly url?: string;
+    /** A human-readable name. */
+    readonly name?: string;
+    /** The release version. */
+    readonly version?: string;
+    /** Override the default status interpretation of the `status` column's raw token. */
+    readonly statusMap?: StatusMapper;
+}
+/** The billable-flag descriptor for a {@link FixedWidthFieldMap}. */
+interface BillableFlag {
+    /** The 0-based char index of the flag. */
+    readonly at: number;
+    /** The character value that means "billable/valid leaf" (ICD-10-CM: `"1"`; `"0"` is a header). */
+    readonly billableValue: string;
+}
+/** One extra fixed-width field to capture as a {@link Property}. */
+interface FixedWidthPropertyField {
+    /** The property code to emit. */
+    readonly name: string;
+    /** The field slice. */
+    readonly slice: FieldSlice;
+}
+/** The field mapping for a {@link FixedWidthSource} (0-based char slices). */
+interface FixedWidthFieldMap {
+    /** The slice holding the concept code. */
+    readonly code: FieldSlice;
+    /** The slice holding the display string. */
+    readonly display: FieldSlice;
+    /** The billable/header flag (ICD-10-CM position-15), when the format has one. */
+    readonly billable?: BillableFlag;
+    /** A slice holding a status token, when the format has one (alternative to `billable`). */
+    readonly status?: FieldSlice;
+    /** Extra slices to surface as properties. */
+    readonly properties?: readonly FixedWidthPropertyField[];
+}
+/**
+ * A **fixed-width** source (slice by column) — e.g. the ICD-10-CM order file. Fully parameterized:
+ * the consumer supplies the field slices (see {@link ICD10CM_ORDER_FILE_FIELDS} for the documented
+ * ICD-10-CM preset, which they confirm against their release's README — the byte offsets are a
+ * flagged open question in the roadmap). BYO.
+ */
+interface FixedWidthSource {
+    /** Discriminant. */
+    readonly format: "fixed-width";
+    /** The raw fixed-width file content. */
+    readonly content: string;
+    /** Which char slices hold the code/display/billable/status/properties. */
+    readonly fields: FixedWidthFieldMap;
+    /** The code system's canonical URI. */
+    readonly url?: string;
+    /** A human-readable name. */
+    readonly name?: string;
+    /** The release version. */
+    readonly version?: string;
+    /** Override the default status interpretation of the `status` slice's raw token. */
+    readonly statusMap?: StatusMapper;
+}
+/**
+ * A **FHIR R4 `CodeSystem`** JSON source (native, license-clean model). The consumer supplies the
+ * untrusted resource; nested `concept` hierarchies are flattened, and the standard `inactive` /
+ * `deprecated` concept properties are read into {@link ConceptStatus}.
+ */
+interface FhirCodeSystemSource {
+    /** Discriminant. */
+    readonly format: "fhir";
+    /** The untrusted FHIR `CodeSystem` resource (typically `JSON.parse` output — hence `unknown`). */
+    readonly resource: unknown;
+}
+/** The discriminated union {@link loadCodeSystem} accepts. */
+type CodeSystemSource = RrfSource | CsvSource | FixedWidthSource | FhirCodeSystemSource;
+
+/**
+ * {@link loadCodeSystem} — the single entry point that dispatches a {@link CodeSystemSource} to the
+ * right reader (RRF / CSV / fixed-width / FHIR) and assembles the immutable {@link CodeSystem}.
+ *
+ * The engine is **content-agnostic and license-clean**: it loads a *consumer-supplied* release and
+ * ships **zero** copyrighted content (roadmap §5). The loaded model is deep-frozen and keyed by code
+ * for O(1) {@link lookup}/{@link validateCode}.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Load a consumer-supplied code-system release into an immutable, queryable {@link CodeSystem}.
+ *
+ * Dispatches on `source.format`:
+ * - `"rrf"` — pipe-delimited RxNorm/UMLS release (one parameterized reader for both).
+ * - `"csv"` — RFC-4180 CSV (e.g. LOINC `Loinc.csv`), with real quote handling.
+ * - `"fixed-width"` — slice-by-column order files (e.g. ICD-10-CM; see `ICD10CM_ORDER_FILE_FIELDS`).
+ * - `"fhir"` — a native FHIR R4 `CodeSystem` JSON resource.
+ *
+ * **Liberal on load:** a malformed *row* is skipped and surfaced in `warnings` (never a crash, never a
+ * partial concept). **Conservative on structure:** an unusable *source* (wrong FHIR `resourceType`, or
+ * a CSV whose configured columns are absent from the header) throws a typed `TerminologyError`
+ * carrying `TERM_CODESYSTEM_MALFORMED`.
+ *
+ * @param source - The release descriptor (a discriminated {@link CodeSystemSource}).
+ * @returns The immutable, deep-frozen {@link CodeSystem}.
+ * @throws {TerminologyError} `TERM_CODESYSTEM_MALFORMED` when the source is structurally unusable.
+ * @example
+ * ```ts
+ * import { loadCodeSystem } from "@cosyte/terminology";
+ *
+ * const cs = loadCodeSystem({
+ *   format: "fhir",
+ *   resource: {
+ *     resourceType: "CodeSystem",
+ *     url: "http://example.org/cs",
+ *     concept: [{ code: "A", display: "Alpha" }],
+ *   },
+ * });
+ * cs.count; // => 1
+ * ```
+ */
+declare function loadCodeSystem(source: CodeSystemSource): CodeSystem;
+
+/**
+ * {@link lookup} and {@link validateCode} — the FHIR R4 CodeSystem `$lookup` and `$validate-code`
+ * operations over a loaded {@link CodeSystem}.
+ *
+ * Grounded firsthand on FHIR R4 (`https://hl7.org/fhir/R4/codesystem-operation-lookup.html`,
+ * `https://hl7.org/fhir/R4/codesystem-operation-validate-code.html`):
+ *
+ * - `$lookup` returns the concept's `display` (*"The preferred display for this concept"*) and its
+ *   `property` values (*"additional information about the code, including status"*).
+ * - `$validate-code` returns `result` (*"True if the concept details supplied are valid"*).
+ *
+ * Both honor the **never-fabricate invariant** born in Phase 1, now applied to code identity: an
+ * unknown code yields a typed `unknown` / `valid: false` — **never** a fabricated display and
+ * **never** a guessed `valid: true`. A found-but-non-current concept (deprecated, or an ICD-10-CM
+ * header) validates as present **but carries its status flag**, so a caller never treats it as clean.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * `$lookup`: resolve a code to its display, definition, status, and properties in a loaded release.
+ *
+ * @param cs - The loaded {@link CodeSystem}.
+ * @param code - The code to look up.
+ * @returns A {@link LookupResult} when found, or a typed {@link LookupUnknown} — never a guess.
+ * @example
+ * ```ts
+ * import { loadCodeSystem, lookup } from "@cosyte/terminology";
+ *
+ * const cs = loadCodeSystem({
+ *   format: "fhir",
+ *   resource: { resourceType: "CodeSystem", concept: [{ code: "A", display: "Alpha" }] },
+ * });
+ * const r = lookup(cs, "A");
+ * r.found === true && r.display; // => "Alpha"
+ * ```
+ */
+declare function lookup(cs: CodeSystem, code: string): LookupOutcome;
+/**
+ * `$validate-code`: is `code` a valid member of the loaded code system?
+ *
+ * A found code is `valid: true`, **carrying its status** (a deprecated or header code is present but
+ * flagged — never silently clean). An absent code is `valid: false` with `TERM_CODE_UNKNOWN`, never a
+ * guessed `true`.
+ *
+ * @param cs - The loaded {@link CodeSystem}.
+ * @param code - The code to validate.
+ * @returns A {@link ValidateCodeResult}.
+ * @example
+ * ```ts
+ * import { loadCodeSystem, validateCode } from "@cosyte/terminology";
+ *
+ * const cs = loadCodeSystem({
+ *   format: "fhir",
+ *   resource: { resourceType: "CodeSystem", concept: [{ code: "A", display: "Alpha" }] },
+ * });
+ * validateCode(cs, "A").valid; // => true
+ * validateCode(cs, "ZZZ").valid; // => false
+ * ```
+ */
+declare function validateCode(cs: CodeSystem, code: string): ValidateCodeResult;
+
+/**
+ * The **RRF** (Rich Release Format) reader — the pipe-delimited layer shared by RxNorm (`RXNCONSO`/
+ * `RXNSAT`) and UMLS (`MRCONSO`/`MRSAT`). One parameterized reader serves both: they share the RRF
+ * shape — fields separated by `|`, with **one trailing pipe per line** (grounded firsthand on the
+ * UMLS Reference Manual, `https://www.ncbi.nlm.nih.gov/books/NBK9685/`: *"values … are separated by
+ * vertical bars (|)"* and each row ends with *"a vertical bar and line termination"*).
+ *
+ * **Liberal on load** (roadmap §6): a row too short to reach a configured column, or with an empty
+ * code, is **skipped and surfaced** as a `TERM_RRF_MALFORMED_ROW` warning — never kept as a partial
+ * concept, never a crash. RRF reserves `|` as the delimiter (fields never contain a literal pipe), so
+ * a plain split is exact.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Split one RRF line into its fields, dropping the single reserved trailing pipe.
+ *
+ * @param line - One RRF line (no line terminator).
+ * @returns The fields, in column order.
+ * @example
+ * ```ts
+ * import { parseRrfLine } from "@cosyte/terminology";
+ *
+ * parseRrfLine("314076|ENG|lisinopril 10 MG|"); // => ["314076", "ENG", "lisinopril 10 MG"]
+ * ```
+ */
+declare function parseRrfLine(line: string): readonly string[];
+/**
+ * Parse an {@link RrfSource} into concepts (first row per code wins) and skipped-row warnings.
+ *
+ * A code that recurs across rows (RRF repeats a code once per atom/attribute) keeps its **first**
+ * occurrence — a documented v1 limitation: preferred-atom selection (`TS`/`STT`/`ISPREF`) and
+ * attribute merging are later work. The result is data only; {@link loadCodeSystem} freezes it.
+ *
+ * @param source - The RRF source.
+ * @returns The parsed concepts (by code) and the load warnings.
+ * @example
+ * ```ts
+ * import { parseRrf } from "@cosyte/terminology";
+ *
+ * const { concepts } = parseRrf({
+ *   format: "rrf",
+ *   content: "1|Aspirin|",
+ *   columns: { code: 0, display: 1 },
+ * });
+ * concepts.get("1")?.display; // => "Aspirin"
+ * ```
+ */
+declare function parseRrf(source: RrfSource): {
+    concepts: Map<string, Concept>;
+    warnings: LoadWarning[];
+};
+
+/**
+ * The **RFC-4180 CSV** reader — the one release format that needs real quote handling (LOINC's
+ * `Loinc.csv`). Fields may be quoted with `"`; inside a quoted field a literal quote is escaped as
+ * `""`, and commas and newlines are data. Hand-rolled, zero-dep (roadmap §1: the CSV surface is small
+ * and well-specified enough to hand-roll rather than pull a dependency).
+ *
+ * **Liberal on load:** a data row with too few fields to reach a configured column is **skipped and
+ * surfaced** as a `TERM_CSV_MALFORMED` warning; an unterminated final quote is surfaced too — never a
+ * crash. A configured code/display header that is **absent from the header row** is a *fatal*
+ * (`TERM_CODESYSTEM_MALFORMED`): the source config does not match the file, so nothing loads cleanly.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Parse RFC-4180 CSV content into rows of fields (the `.rows` of {@link parseCsvRows}). Lenient: a
+ * stray mid-field quote is literal, so a malformed quote never silently swallows subsequent rows.
+ *
+ * @param content - The raw CSV text.
+ * @returns The rows, each an array of field strings (untrimmed).
+ * @example
+ * ```ts
+ * import { parseCsv } from "@cosyte/terminology";
+ *
+ * parseCsv('a,b\n"x,y","z""q"'); // => [["a", "b"], ["x,y", 'z"q']]
+ * ```
+ */
+declare function parseCsv(content: string): string[][];
+/**
+ * Parse a {@link CsvSource} into concepts and skipped-row warnings.
+ *
+ * @param source - The CSV source.
+ * @returns The parsed concepts (by code) and the load warnings.
+ * @throws {TerminologyError} `TERM_CODESYSTEM_MALFORMED` when the file has no header row, or a
+ *   configured `code`/`display`/`status`/property column is absent from the header.
+ * @example
+ * ```ts
+ * import { parseCsvSource } from "@cosyte/terminology";
+ *
+ * const { concepts } = parseCsvSource({
+ *   format: "csv",
+ *   content: "CODE,NAME\n2160-0,Creatinine",
+ *   columns: { code: "CODE", display: "NAME" },
+ * });
+ * concepts.get("2160-0")?.display; // => "Creatinine"
+ * ```
+ */
+declare function parseCsvSource(source: CsvSource): {
+    concepts: Map<string, Concept>;
+    warnings: LoadWarning[];
+};
+
+/**
+ * The **fixed-width** reader — slice a line by column, for order-file layouts like the ICD-10-CM
+ * order file (`icd10cm_order_YYYY.txt`). Fully parameterized: the consumer supplies the field slices,
+ * so the *engine* is content-agnostic and the byte offsets live in the caller's config, not baked in.
+ *
+ * The documented ICD-10-CM preset is {@link ICD10CM_ORDER_FILE_FIELDS} — the position-15 flag
+ * (0-based char index 14) is `1` for a **billable/valid** code and `0` for a **header** (grounded on
+ * the CMS/CDC order-file layout). Per the roadmap's flagged open question (§10 #4), a consumer should
+ * confirm the exact offsets against their release's README before relying on the preset — which is
+ * exactly why the reader takes the slices as a parameter.
+ *
+ * **Liberal on load:** a line too short to contain the code slice, or with an empty code, is skipped
+ * and surfaced as a `TERM_FIXED_WIDTH_MALFORMED` warning.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Extract and trim a {@link FieldSlice} from a line (`end` omitted slices to end of line).
+ *
+ * @param line - The source line.
+ * @param slice - The half-open `[start, end)` slice.
+ * @returns The trimmed field text (empty when the slice is entirely past the line's end).
+ * @example
+ * ```ts
+ * import { sliceField } from "@cosyte/terminology";
+ *
+ * sliceField("00001 A00     1 Cholera", { start: 6, end: 13 }); // => "A00"
+ * ```
+ */
+declare function sliceField(line: string, slice: FieldSlice): string;
+/**
+ * The documented **ICD-10-CM order file** field layout (0-based char indices).
+ *
+ * - `code` — the ICD-10-CM code (no decimal point).
+ * - `billable` — position-15 flag at index 14: `"1"` = billable/valid leaf, `"0"` = header.
+ * - `display` — the long description (to end of line).
+ * - property `shortDescription` — the 60-char short description.
+ *
+ * Grounded on the CMS/CDC order-file layout; **verify against your release's README** before relying
+ * on the exact offsets (roadmap §10 #4 — the CDC PDF resisted authoritative decode). The reader takes
+ * the layout as a parameter precisely so this preset is a starting point, not a hardcoded assumption.
+ */
+declare const ICD10CM_ORDER_FILE_FIELDS: FixedWidthFieldMap;
+/**
+ * Parse a {@link FixedWidthSource} into concepts and skipped-row warnings.
+ *
+ * @param source - The fixed-width source.
+ * @returns The parsed concepts (by code) and the load warnings.
+ * @example
+ * ```ts
+ * import { parseFixedWidth } from "@cosyte/terminology";
+ *
+ * const { concepts } = parseFixedWidth({
+ *   format: "fixed-width",
+ *   content: "A00 1 Cholera",
+ *   fields: { code: { start: 0, end: 3 }, display: { start: 6 } },
+ * });
+ * concepts.get("A00")?.display; // => "Cholera"
+ * ```
+ */
+declare function parseFixedWidth(source: FixedWidthSource): {
+    concepts: Map<string, Concept>;
+    warnings: LoadWarning[];
+};
+
+/**
+ * The **FHIR R4 `CodeSystem`** JSON loader — the native, license-clean model. Reads the untrusted
+ * resource into the engine's {@link Concept} map, flattening nested `concept` hierarchies and mapping
+ * the standard concept properties to {@link ConceptStatus}.
+ *
+ * Grounded firsthand on FHIR R4 (`https://hl7.org/fhir/R4/codesystem.html` and the concept-properties
+ * code system, `https://hl7.org/fhir/R4/codesystem-concept-properties.html`): a concept has
+ * `code`/`display`/`definition`/`designation`/`property`/nested `concept`; the base property
+ * **`inactive`** (boolean) is *"True if the concept is not considered active — e.g. not a valid
+ * concept any more"*, **`deprecated`** (dateTime) marks a deprecation, and a `status` string property
+ * is common in real systems.
+ *
+ * **Conservative on load:** the wrong `resourceType` is a *fatal* (`TERM_CODESYSTEM_MALFORMED`); a
+ * concept missing its required `code` is skipped and surfaced (a malformed row, not a whole-file
+ * fatal).
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Parse a {@link FhirCodeSystemSource} into concepts, a resolved url/version/name, and warnings.
+ *
+ * @param source - The FHIR CodeSystem source.
+ * @returns The parsed concepts (by code), the load warnings, and the resource metadata.
+ * @throws {TerminologyError} `TERM_CODESYSTEM_MALFORMED` when the resource is not a FHIR `CodeSystem`.
+ * @example
+ * ```ts
+ * import { parseFhirCodeSystem } from "@cosyte/terminology";
+ *
+ * const { concepts } = parseFhirCodeSystem({
+ *   resource: { resourceType: "CodeSystem", concept: [{ code: "A", display: "Alpha" }] },
+ *   format: "fhir",
+ * });
+ * concepts.get("A")?.display; // => "Alpha"
+ * ```
+ */
+declare function parseFhirCodeSystem(source: FhirCodeSystemSource): {
+    concepts: Map<string, Concept>;
+    warnings: LoadWarning[];
+    url?: string;
+    version?: string;
+    name?: string;
+};
+
+/**
+ * Status interpretation shared by the loaders — the {@link defaultStatusMapper} that turns a raw
+ * steward status token into a normalized {@link ConceptActivity}, and {@link makeStatus} which
+ * assembles the frozen {@link ConceptStatus} (attaching the stable diagnostic code for the concerns
+ * the roadmap names: deprecated and header-not-billable).
+ *
+ * The mapper is deliberately **conservative**: it recognizes only the tokens grounded in the format
+ * docs (LOINC `STATUS` lifecycle values, RxNorm/UMLS `SUPPRESS` values — roadmap §4.4/§11), and maps
+ * everything else to `unknown` — a non-active state carrying the raw token, **never** a guessed
+ * clean-active. Every loader lets the consumer override it for a release with bespoke semantics.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * The default raw-token → {@link ConceptActivity} mapping, case-insensitive.
+ *
+ * Recognized (grounded in the format docs): `""`/`N`/`ACTIVE` → active; `DEPRECATED` → deprecated;
+ * `DISCOURAGED`; `TRIAL`; `O`/`OBSOLETE` → obsolete; `Y`/`E`/`SUPPRESSED` → suppressed. Anything else
+ * → `unknown` (surfaced with its raw token, never coerced to active).
+ *
+ * @param raw - The steward's raw status token.
+ * @returns The normalized activity.
+ * @example
+ * ```ts
+ * import { defaultStatusMapper } from "@cosyte/terminology";
+ *
+ * defaultStatusMapper("DEPRECATED"); // => "deprecated"
+ * defaultStatusMapper("N"); // => "active"
+ * ```
+ */
+declare const defaultStatusMapper: StatusMapper;
+/**
+ * Assemble a frozen {@link ConceptStatus} from a normalized activity, carrying the raw token and (for
+ * classification systems) the billable flag, and attaching the stable diagnostic code for the two
+ * concerns the roadmap names — `TERM_CONCEPT_DEPRECATED` and `TERM_CONCEPT_HEADER_NOT_BILLABLE`.
+ *
+ * @param activity - The normalized activity.
+ * @param raw - The verbatim steward token, if any (omitted from the result when empty).
+ * @param billable - The billable flag for a classification system, if applicable.
+ * @returns A frozen {@link ConceptStatus}.
+ * @example
+ * ```ts
+ * import { makeStatus } from "@cosyte/terminology";
+ *
+ * makeStatus("deprecated", "DEPRECATED").code; // => "TERM_CONCEPT_DEPRECATED"
+ * ```
+ */
+declare function makeStatus(activity: ConceptActivity, raw?: string, billable?: boolean): ConceptStatus;
+
+/**
+ * The types for the **ValueSet binding layer** (roadmap Phase 3): the immutable {@link ValueSet}
+ * model, the `compose` component/filter shapes, the {@link ExpansionContext} that supplies the loaded
+ * code systems and referenced value sets, and the fail-safe {@link ExpandResult} /
+ * {@link ValueSetMembership} outcomes.
+ *
+ * The model is **content-agnostic and license-clean**: a `ValueSet` names codes by system URI and is
+ * expanded over **consumer-supplied** {@link CodeSystem} releases — the engine ships **zero** encoded
+ * value-set content (SNOMED/CPT/full-UMLS/VSAC value sets are strictly BYO, roadmap §5). The FHIR
+ * operation shapes are grounded firsthand on the FHIR R4 Terminology Module
+ * (`https://hl7.org/fhir/R4/valueset.html`, `https://hl7.org/fhir/R4/valueset-operation-expand.html`,
+ * `https://hl7.org/fhir/R4/valueset-operation-validate-code.html`).
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * A FHIR R4 `ValueSet.compose.include.filter` operator — the subset the engine implements plus the
+ * ones it explicitly does not. Grounded on the FHIR `filter-operator` code system
+ * (`https://hl7.org/fhir/R4/valueset-filter-operator.html`).
+ *
+ * **Implemented:** `is-a` / `descendent-of` / `is-not-a` (subsumption over the loaded release's
+ * hierarchy), `=` / `in` / `not-in` / `exists` (property predicates). **Not implemented** (surfaced as
+ * a typed {@link DiagnosticCode.TERM_VALUESET_CANNOT_EXPAND}, never silently mis-expanded): `regex`,
+ * `generalizes`. Anything unrecognized is treated as not-implemented — never as "matches nothing".
+ */
+type FilterOperator = "=" | "is-a" | "descendent-of" | "is-not-a" | "regex" | "in" | "not-in" | "generalizes" | "exists";
+/** One `ValueSet.compose.include.filter` — a `property op value` predicate over a code system. */
+interface ConceptSetFilter {
+    /** The concept property the predicate is on (e.g. `"concept"` for the code hierarchy, or a code). */
+    readonly property: string;
+    /** The filter operator. */
+    readonly op: FilterOperator;
+    /** The comparison value (for `in`/`not-in`, a comma-separated list; for `is-a`, an anchor code). */
+    readonly value: string;
+}
+/** One explicit `ValueSet.compose.include.concept` — an enumerated code (extensional). */
+interface ConceptRef {
+    /** The code, drawn verbatim from the value set. */
+    readonly code: string;
+    /** The display, when the value set supplied one (carried verbatim, never fabricated). */
+    readonly display?: string;
+}
+/**
+ * One `ValueSet.compose.include` / `.exclude` component — a `ConceptSet`. Selects codes by an explicit
+ * `concept` list, by `filter`s over a `system`, by referencing other value sets (`valueSet`), or a
+ * combination (the combination is an **intersection**, per FHIR).
+ */
+interface ConceptSetComponent {
+    /** The code system these codes are drawn from (canonical URI), when the component names one. */
+    readonly system?: string;
+    /** The code system version to pin the selection to, when declared. */
+    readonly version?: string;
+    /** An explicit, enumerated code list (extensional). Mutually exclusive with {@link filter} in FHIR. */
+    readonly concept?: readonly ConceptRef[];
+    /** Intensional filters over {@link system}. Each code must satisfy **all** filters. */
+    readonly filter?: readonly ConceptSetFilter[];
+    /** Canonical URLs of other value sets; a code must be a member of **every** one (intersection). */
+    readonly valueSet?: readonly string[];
+}
+/** A `ValueSet.compose` — the intensional/extensional definition of membership. */
+interface ValueSetCompose {
+    /** The `include` components (their union, minus every {@link exclude}, is the membership). */
+    readonly include: readonly ConceptSetComponent[];
+    /** The `exclude` components — codes removed from the include union. */
+    readonly exclude: readonly ConceptSetComponent[];
+}
+/** One `ValueSet.expansion.contains` entry from a **pre-computed** expansion. */
+interface ExpansionContains {
+    /** The code system URI, when the entry names one. */
+    readonly system?: string;
+    /** The code. Required — a `contains` entry without a code is a malformed expansion. */
+    readonly code: string;
+    /** The display, carried verbatim when present. */
+    readonly display?: string;
+    /** The code system version, when the entry pins one. */
+    readonly version?: string;
+}
+/**
+ * A **pre-computed** `ValueSet.expansion` — a cached membership snapshot, used as-is (extensional).
+ * The engine never re-derives it; it only checks whether it is **complete** (roadmap §4.4 — a
+ * truncated expansion must never read as full membership).
+ */
+interface ValueSetExpansion {
+    /** The server-reported total membership, when present (FHIR `expansion.total`). */
+    readonly total?: number;
+    /** The snapshot members, in expansion order (frozen). */
+    readonly contains: readonly ExpansionContains[];
+    /**
+     * Derived at load: the expansion is **incomplete**. True when `total` exceeds `contains.length`, or
+     * the `http://hl7.org/fhir/StructureDefinition/valueset-toocostly` extension flagged it too-costly
+     * (the VSAC >1200-code truncation hazard). A truncated expansion never reads as complete membership.
+     */
+    readonly truncated: boolean;
+}
+/**
+ * A loaded, immutable `ValueSet` — the subset of the FHIR R4 `ValueSet` resource the binding layer
+ * needs. Produced by {@link loadValueSet}; every field deep-frozen.
+ */
+interface ValueSet {
+    /** The resource's canonical `url`, when declared (the key referenced value sets resolve against). */
+    readonly url?: string;
+    /** The resource's business `version`, when declared. */
+    readonly version?: string;
+    /** A short human-readable name, when declared. */
+    readonly name?: string;
+    /** The intensional/extensional `compose`, when the resource defines membership by composition. */
+    readonly compose?: ValueSetCompose;
+    /** A **pre-computed** `expansion`, when the resource carries a cached membership snapshot. */
+    readonly expansion?: ValueSetExpansion;
+}
+/**
+ * The data an {@link expand}/{@link validateCodeInValueSet} call draws on: the loaded
+ * {@link CodeSystem} releases (for intensional `filter`/`system` includes) and any referenced
+ * {@link ValueSet}s (for `compose.include.valueSet`), each keyed by its **canonical URL**.
+ *
+ * The engine makes **no network call** and holds no bundled content: everything intensional resolves
+ * through this map, and a system or value set the caller did not supply becomes a typed
+ * {@link DiagnosticCode.TERM_VALUESET_CANNOT_EXPAND}, never a fabricated member (roadmap §2, §4.4).
+ */
+interface ExpansionContext {
+    /** Loaded code-system releases, keyed by canonical URI (e.g. `"http://loinc.org"`). */
+    readonly codeSystems?: ReadonlyMap<string, CodeSystem>;
+    /** Referenced value sets, keyed by canonical URL, for `compose.include.valueSet`. */
+    readonly valueSets?: ReadonlyMap<string, ValueSet>;
+}
+/** A surfaced expansion concern — a part that could not be expanded, or a truncated snapshot. */
+interface ExpansionDiagnostic {
+    /** The stable code (`TERM_VALUESET_CANNOT_EXPAND` / `TERM_VALUESET_EXPANSION_TRUNCATED`). */
+    readonly code: DiagnosticCode;
+    /** A **value-free** structural description of the concern (never echoes a patient value). */
+    readonly detail: string;
+    /** The code system / value set URI the concern is about (a published identity — not PHI). */
+    readonly system?: string;
+}
+/**
+ * The result of {@link expand}: the flattened membership plus an honest **completeness** signal.
+ *
+ * `complete` is `false` whenever any part could not be fully computed (a missing code system, an
+ * unresolved referenced value set, an unimplemented `filter` op, or a truncated pre-computed
+ * expansion). A `false` here is the never-fabricate contract in action: the `contains` set is a
+ * **lower bound**, so it must never be read as exhaustive membership.
+ */
+interface ExpandResult {
+    /** Whether the expansion is exhaustive. When `false`, `contains` is a lower bound, not the whole set. */
+    readonly complete: boolean;
+    /** The expanded, de-duplicated members, in first-seen order (frozen; every member frozen). */
+    readonly contains: readonly Coding[];
+    /** The server-reported total, when the expansion came from a pre-computed snapshot. */
+    readonly total?: number;
+    /** The surfaced concerns, in encounter order (frozen; may be empty). */
+    readonly diagnostics: readonly ExpansionDiagnostic[];
+}
+/** A definitive membership answer — the code is (or is not) a member of the value set. */
+interface ValueSetMemberDecided {
+    /** Discriminant: membership was decided. */
+    readonly undetermined: false;
+    /** FHIR `$validate-code` `result`: true iff the code is a member of the value set. */
+    readonly result: boolean;
+    /** The coding that was tested, echoed. */
+    readonly coding: Coding;
+}
+/**
+ * A **fail-safe undetermined** membership — the never-fabricate outcome for a value set that could
+ * not be fully evaluated (a missing code system, a truncated expansion). The engine refuses to guess:
+ * it returns neither `true` nor `false`, so a caller can never mistake "we could not check" for "not a
+ * member" (roadmap §4.4 — a false "not a member" is a clinical error).
+ */
+interface ValueSetMemberUndetermined {
+    /** Discriminant: membership could not be decided. */
+    readonly undetermined: true;
+    /** The stable diagnostic code (`TERM_VALUESET_CANNOT_EXPAND`). */
+    readonly code: "TERM_VALUESET_CANNOT_EXPAND";
+    /** The coding that was tested, echoed. */
+    readonly coding: Coding;
+    /** The surfaced reasons the check could not be completed. */
+    readonly diagnostics: readonly ExpansionDiagnostic[];
+}
+/** The result of {@link validateCodeInValueSet}: a decided membership or a typed undetermined. */
+type ValueSetMembership = ValueSetMemberDecided | ValueSetMemberUndetermined;
+
+/**
+ * {@link loadValueSet} — validate and normalize an untrusted FHIR R4 `ValueSet` JSON resource into
+ * the immutable {@link ValueSet} model the `$expand` / `$validate-code` binding operations run over.
+ *
+ * **Conservative on load** (like {@link ../conceptmap/load.loadConceptMap}, unlike a lenient wire
+ * parser): a value set *binds* whether a code is allowed in a clinical slot, so a structurally
+ * unusable resource is a typed **fatal** ({@link FATAL_CODES.TERM_VALUESET_MALFORMED}) rather than a
+ * silently partial value set that would admit *some* codes and quietly drop others. A `filter`
+ * operator the engine does not implement is **not** fatal — the value set loads, and the gap surfaces
+ * at expansion time as a {@link DIAGNOSTIC_CODES.TERM_VALUESET_CANNOT_EXPAND} diagnostic. Fault
+ * messages are **value-free**: they name the resource *path* and the fault, never echo a code value.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Load an untrusted FHIR R4 `ValueSet` JSON value into an immutable {@link ValueSet}.
+ *
+ * Accepts the standard resource shape: `resourceType: "ValueSet"` with an optional intensional
+ * `compose` (`include`/`exclude` of `system`/`concept`/`filter`/`valueSet`) and/or a **pre-computed**
+ * `expansion` (`contains`, with `total` and the `valueset-toocostly` extension read into a derived
+ * `truncated` flag). The result is deep-frozen. Anything structurally unusable throws a
+ * {@link TerminologyError} carrying {@link FATAL_CODES.TERM_VALUESET_MALFORMED}.
+ *
+ * @param json - The untrusted resource (typically `JSON.parse` output — hence `unknown`).
+ * @returns The immutable, validated {@link ValueSet}.
+ * @throws {TerminologyError} `TERM_VALUESET_MALFORMED` when the resource is not a usable ValueSet.
+ * @example
+ * ```ts
+ * import { loadValueSet } from "@cosyte/terminology";
+ *
+ * const vs = loadValueSet({
+ *   resourceType: "ValueSet",
+ *   url: "http://example.org/vs/colors",
+ *   compose: {
+ *     include: [{ system: "http://example.org/cs", concept: [{ code: "red" }, { code: "green" }] }],
+ *   },
+ * });
+ * vs.compose?.include.length; // => 1
+ * ```
+ */
+declare function loadValueSet(json: unknown): ValueSet;
+
+/**
+ * {@link expand} — the FHIR R4 ValueSet `$expand` operation over a loaded {@link ValueSet}.
+ *
+ * Grounded firsthand on FHIR R4 (`https://hl7.org/fhir/R4/valueset-operation-expand.html`,
+ * `https://hl7.org/fhir/R4/valueset.html#compose`):
+ *
+ * - A **pre-computed** `expansion` is used as-is (extensional), and its completeness is checked — a
+ *   truncated snapshot is flagged, never treated as full membership (roadmap §4.4).
+ * - An intensional `compose` is expanded over **consumer-supplied** {@link ../codesystem/types.CodeSystem}
+ *   releases: the union of `include` components minus the union of `exclude` components. Each component
+ *   selects by explicit `concept`, by `filter` (subsumption + property predicates), by the whole
+ *   `system`, and/or by intersecting referenced value sets.
+ *
+ * **Never fabricate.** A part that cannot be computed — a missing code system, an unresolved
+ * referenced value set, an unimplemented `filter` operator — yields a typed
+ * {@link ../common/diagnostics.DIAGNOSTIC_CODES.TERM_VALUESET_CANNOT_EXPAND} and marks the result
+ * `complete: false`, so the `contains` set is an explicit **lower bound**, never a silently-empty or
+ * fabricated membership.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * `$expand`: compute the flattened membership of a {@link ValueSet} over the supplied code systems.
+ *
+ * @param vs - The loaded value set.
+ * @param ctx - The loaded code systems / referenced value sets the intensional parts resolve against.
+ * @returns An {@link ExpandResult} — the `contains` members plus an honest `complete` flag. When
+ *   `complete` is `false`, `contains` is a lower bound (never treat it as exhaustive membership).
+ * @example
+ * ```ts
+ * import { loadValueSet, loadCodeSystem, expand } from "@cosyte/terminology";
+ *
+ * const cs = loadCodeSystem({
+ *   format: "fhir",
+ *   resource: {
+ *     resourceType: "CodeSystem",
+ *     url: "http://example.org/cs",
+ *     concept: [{ code: "a" }, { code: "b" }, { code: "c" }],
+ *   },
+ * });
+ * const vs = loadValueSet({
+ *   resourceType: "ValueSet",
+ *   compose: { include: [{ system: "http://example.org/cs", concept: [{ code: "a" }, { code: "b" }] }] },
+ * });
+ * const result = expand(vs, { codeSystems: new Map([["http://example.org/cs", cs]]) });
+ * result.complete; // => true
+ * result.contains.length; // => 2
+ * ```
+ */
+declare function expand(vs: ValueSet, ctx?: ExpansionContext): ExpandResult;
+
+/**
+ * {@link validateCodeInValueSet} — the FHIR R4 ValueSet `$validate-code` operation (value-set
+ * binding): is a {@link Coding} a member of a {@link ValueSet}?
+ *
+ * Grounded firsthand on FHIR R4 (`https://hl7.org/fhir/R4/valueset-operation-validate-code.html`): a
+ * binding decides whether a code is *allowed* in a slot. The engine returns a **decided** membership
+ * (`result: true`/`false`) **only when it can prove it** — a code found in a computable `include` and
+ * not removed by any computable `exclude` is a definite member; a code absent from a fully-evaluated
+ * value set is a definite non-member. When any relevant part cannot be evaluated (a missing code
+ * system, a truncated pre-computed expansion, an unimplemented `filter`), the answer is a typed
+ * {@link ValueSetMemberUndetermined} — **never** a fabricated `false` (roadmap §4.4: a false "not a
+ * member" is a clinical error).
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * `$validate-code` (ValueSet): is `coding` a member of `valueSet`?
+ *
+ * @param coding - The code to test (system + code).
+ * @param valueSet - The loaded value set.
+ * @param ctx - The loaded code systems / referenced value sets the intensional parts resolve against.
+ * @returns A decided {@link ValueSetMembership} (`result: true`/`false`), or a typed
+ *   {@link ValueSetMemberUndetermined} when membership could not be proven — never a fabricated `false`.
+ * @example
+ * ```ts
+ * import { loadValueSet, validateCodeInValueSet } from "@cosyte/terminology";
+ *
+ * const vs = loadValueSet({
+ *   resourceType: "ValueSet",
+ *   compose: { include: [{ system: "http://example.org/cs", concept: [{ code: "a" }, { code: "b" }] }] },
+ * });
+ * const r = validateCodeInValueSet({ system: "http://example.org/cs", code: "a" }, vs);
+ * r.undetermined === false && r.result; // => true
+ * ```
+ */
+declare function validateCodeInValueSet(coding: Coding, valueSet: ValueSet, ctx?: ExpansionContext): ValueSetMembership;
+
+/**
+ * Subsumption + `compose.include.filter` evaluation — the shared machinery {@link ./expand.expand}
+ * and {@link ./validate.validateCodeInValueSet} both draw on.
+ *
+ * **Subsumption** is read from the loaded {@link CodeSystem}'s **`parent`** concept-properties
+ * (`http://hl7.org/fhir/concept-properties#parent`) — which the FHIR loader synthesizes from a nested
+ * `concept` hierarchy and carries verbatim from an explicit `parent` property. This is deliberately
+ * the release's **own** hierarchy (roadmap: "hierarchy/`$subsumes` minimal; deep subsumption is
+ * Phase 5"); a code system that encodes no parent edges has no descendants beyond identity, and that
+ * is treated as complete — not guessed deeper.
+ *
+ * **Filter support is explicit.** `is-a` / `descendent-of` / `is-not-a` / `=` / `in` / `not-in` /
+ * `exists` are implemented; `regex` / `generalizes` / anything unrecognized report `supported: false`
+ * so the caller surfaces a typed {@link DIAGNOSTIC_CODES.TERM_VALUESET_CANNOT_EXPAND} rather than
+ * silently mis-including or dropping codes.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * The filters whose operator the engine does **not** implement (`regex` / `generalizes` / unknown) —
+ * a non-empty result means the caller must surface a typed cannot-expand, never mis-expand.
+ *
+ * @param filters - The component's filters.
+ * @returns The subset with an unimplemented operator (empty when all are supported).
+ * @example
+ * ```ts
+ * import { unsupportedOps } from "@cosyte/terminology";
+ *
+ * unsupportedOps([{ property: "concept", op: "is-a", value: "x" }]).length; // => 0
+ * ```
+ */
+declare function unsupportedOps(filters: readonly ConceptSetFilter[]): readonly ConceptSetFilter[];
+/** An immutable ancestor index over a {@link CodeSystem}'s `parent` edges. */
+interface Subsumption {
+    /** All (transitive) ancestor codes of `code`, cycle-safe. Excludes `code` itself. */
+    ancestorsOf(code: string): ReadonlySet<string>;
+}
+/**
+ * Build a cycle-safe ancestor index from a loaded {@link CodeSystem}'s `parent` concept-properties.
+ *
+ * @param cs - The loaded code system.
+ * @returns A {@link Subsumption} answering transitive-ancestor queries.
+ * @example
+ * ```ts
+ * import { loadCodeSystem, buildSubsumption } from "@cosyte/terminology";
+ *
+ * const cs = loadCodeSystem({
+ *   format: "fhir",
+ *   resource: { resourceType: "CodeSystem", concept: [{ code: "p", concept: [{ code: "c" }] }] },
+ * });
+ * buildSubsumption(cs).ancestorsOf("c").has("p"); // => true
+ * ```
+ */
+declare function buildSubsumption(cs: CodeSystem): Subsumption;
+/**
+ * True when `code` is-a `anchor` — the same code, or a (transitive) descendant of it.
+ *
+ * @param sub - The subsumption index (from {@link buildSubsumption}).
+ * @param code - The candidate code.
+ * @param anchor - The ancestor code to test against.
+ * @returns Whether `code` is `anchor` or a descendant of it.
+ * @example
+ * ```ts
+ * import { loadCodeSystem, buildSubsumption, isA } from "@cosyte/terminology";
+ *
+ * const cs = loadCodeSystem({
+ *   format: "fhir",
+ *   resource: { resourceType: "CodeSystem", concept: [{ code: "p", concept: [{ code: "c" }] }] },
+ * });
+ * isA(buildSubsumption(cs), "c", "p"); // => true
+ * ```
+ */
+declare function isA(sub: Subsumption, code: string, anchor: string): boolean;
+/** The outcome of evaluating a single filter against a single concept. */
+interface FilterMatch {
+    /** Whether the concept satisfies the filter (meaningful only when {@link supported}). */
+    readonly matched: boolean;
+    /** Whether the engine implements this filter operator; `false` ⇒ the caller must surface it. */
+    readonly supported: boolean;
+}
+/**
+ * Evaluate one {@link ConceptSetFilter} against one {@link Concept}, using the release's hierarchy.
+ *
+ * The `concept` filter property (and the hierarchy operators regardless of property) reads the code
+ * itself / its subsumption; other properties read the concept's `property` values. An unimplemented
+ * operator returns `{ supported: false }` — never a coerced `matched`.
+ *
+ * @param concept - The concept under test.
+ * @param filter - The filter predicate.
+ * @param sub - The subsumption index for the concept's code system.
+ * @returns A {@link FilterMatch}.
+ * @example
+ * ```ts
+ * import { loadCodeSystem, buildSubsumption, matchesFilter } from "@cosyte/terminology";
+ *
+ * const cs = loadCodeSystem({
+ *   format: "fhir",
+ *   resource: { resourceType: "CodeSystem", concept: [{ code: "p", concept: [{ code: "c" }] }] },
+ * });
+ * const dog = cs.concepts.get("c");
+ * dog && matchesFilter(dog, { property: "concept", op: "is-a", value: "p" }, buildSubsumption(cs)).matched; // => true
+ * ```
+ */
+declare function matchesFilter(concept: Concept, filter: ConceptSetFilter, sub: Subsumption): FilterMatch;
+
+/**
+ * Types for the **UCUM unit layer** (roadmap Phase 4): the parsed unit AST, the reduced
+ * (canonical) dimensional form, and the public {@link UcumValidation} result.
+ *
+ * The layer is **recognition + validation + representation canonicalization only** — it answers
+ * "is this a valid UCUM expression" and "are these two expressions the same unit", and it
+ * canonicalizes a unit's *representation*. It performs **no magnitude conversion** (`mg/dL` →
+ * `mmol/L` needs an analyte's molar mass — a clinical computation the engine refuses, roadmap
+ * §2/§4.3). The tables are the vendored, verbatim UCUM `ucum-essence.xml` (roadmap §5), transformed
+ * to an in-memory model at runtime; the engine ships **no derivative** of the UCUM table.
+ *
+ * @packageDocumentation
+ */
+/** A UCUM metric prefix (e.g. `k` = kilo, factor `1e3`), from the essence `<prefix>` table. */
+interface UcumPrefix {
+    /** The case-sensitive prefix symbol (e.g. `"k"`, `"da"`, `"Ki"`). */
+    readonly code: string;
+    /** The multiplicative factor (e.g. `1000` for `k`, `1024` for `Ki`). */
+    readonly factor: number;
+}
+/**
+ * A UCUM unit atom, from the essence `<base-unit>` / `<unit>` table. An atom is a symbol like `m`,
+ * `L`, `[in_i]`, `10*`, or `Cel`, **before** any prefix or exponent is applied.
+ */
+interface UcumAtom {
+    /** The case-sensitive atom symbol (the essence `Code`, e.g. `"m"`, `"[iU]"`, `"m[Hg]"`). */
+    readonly code: string;
+    /** Whether a metric prefix may attach to this atom (essence `isMetric`). Only metric atoms prefix. */
+    readonly metric: boolean;
+    /** A **base** unit (one of the 7: `m s g rad K C cd`) — its own dimension, factor 1. */
+    readonly base: boolean;
+    /** A base unit's dimension key (its own `code`), or `undefined` for derived atoms. */
+    readonly dim?: string;
+    /**
+     * A **special** unit (essence `isSpecial`, e.g. `Cel`, `B`, `[pH]`) — defined by a non-linear
+     * function, so it has **no** linear factor/dimension and is never reduced to one. Compared only by
+     * identity of its normalized representation (never claimed equal to a linear unit).
+     */
+    readonly special: boolean;
+    /**
+     * An **arbitrary** unit (essence `isArbitrary`, e.g. `[IU]`, `[arb'U]`) — not commensurable with
+     * any other unit. Modeled as its own dimension axis keyed by the atom `code`, so `[IU]/[IU]`
+     * reduces to unity but `[IU]` is never equated with a mass or another arbitrary unit.
+     */
+    readonly arbitrary: boolean;
+    /**
+     * The linear definition: `1 <atom> = value × <unit>` (essence `<value value Unit>`), for derived
+     * atoms. `undefined` for base units (they define the dimensions) and for special units (non-linear).
+     */
+    readonly value?: {
+        readonly factor: number;
+        readonly unit: string;
+    };
+}
+/** The parsed UCUM essence table — the engine's in-memory unit model, built lazily and cached. */
+interface UcumEssence {
+    /** Prefix symbols → prefix, longest symbols first (for greedy matching). */
+    readonly prefixes: readonly UcumPrefix[];
+    /** Atom symbols → atom, longest symbols first (for greedy longest-match). */
+    readonly atoms: readonly UcumAtom[];
+    /** Atom lookup by exact `code`. */
+    readonly atomByCode: ReadonlyMap<string, UcumAtom>;
+    /** Prefix lookup by exact `code`. */
+    readonly prefixByCode: ReadonlyMap<string, UcumPrefix>;
+}
+/** One parsed component of a unit term: a simple unit (prefix?+atom) with an optional exponent. */
+interface SimpleUnitNode {
+    readonly kind: "simple";
+    /** The applied prefix, when present. */
+    readonly prefix?: UcumPrefix;
+    /** The resolved atom. */
+    readonly atom: UcumAtom;
+    /** The integer exponent (default 1). Negative for the denominator side. */
+    readonly exponent: number;
+}
+/** A numeric factor component (a bare integer, e.g. the `4` in `4.[pi]`). */
+interface FactorNode {
+    readonly kind: "factor";
+    /** The integer value. */
+    readonly value: number;
+}
+/** A parenthesised sub-term or an annotation-only component. */
+interface GroupNode {
+    readonly kind: "group";
+    /** The parsed inner term. */
+    readonly term: UnitNode;
+}
+/** A component that carries **only** an annotation (e.g. `{cells}`), dimensionless and inert. */
+interface AnnotationNode {
+    readonly kind: "annotation";
+}
+/** A component: a simple unit, a factor, a group, or an annotation — each optionally exponentiated. */
+type ComponentNode = SimpleUnitNode | FactorNode | GroupNode | AnnotationNode;
+/**
+ * A parsed UCUM term: an ordered list of components, each combined into the product with the given
+ * sign (+1 for `.` / the leading operand, -1 for the `/` denominator).
+ */
+interface UnitNode {
+    readonly kind: "term";
+    /** The components and their operator sign, in source order. */
+    readonly factors: ReadonlyArray<{
+        readonly sign: 1 | -1;
+        readonly node: ComponentNode;
+    }>;
+}
+/**
+ * A unit reduced to base dimensions: a scalar `factor` times a map of dimension axis → exponent.
+ * Dimension keys are the seven UCUM base symbols (`m s g rad K C cd`) plus `arb:<code>` axes for
+ * arbitrary units. Two `linear` forms are the **same unit** iff equal dims and equal factor.
+ */
+interface LinearReduction {
+    readonly kind: "linear";
+    /** The accumulated scalar factor in base units. */
+    readonly factor: number;
+    /** Dimension axis → non-zero exponent (zero exponents omitted). */
+    readonly dims: Readonly<Record<string, number>>;
+}
+/**
+ * A **non-linear** (special) reduction — the expression involves a special unit (`Cel`, `B`, …) and
+ * cannot be reduced to a scalar×dimension form. Carried by its normalized representation `form`;
+ * two special reductions are the same unit iff their `form`s are identical (never equated with a
+ * linear unit — the never-fabricate posture applied to units).
+ */
+interface SpecialReduction {
+    readonly kind: "special";
+    /** The normalized expression string (prefixes/atoms/exponents; annotations stripped). */
+    readonly form: string;
+}
+/** The reduced canonical form of a unit expression. */
+type Reduction = LinearReduction | SpecialReduction;
+/**
+ * The result of {@link validateUcum}: a valid unit with its canonical descriptor, or a typed
+ * invalid carrying the stable {@link TERM_UCUM_INVALID} diagnostic and a value-free reason.
+ */
+type UcumValidation = {
+    /** The expression is a well-formed UCUM unit over known atoms. */
+    readonly valid: true;
+    /**
+     * A stable, normalized **descriptor** of the unit's canonical form — equal iff the units are
+     * the same (see {@link ucumEqual}). Note: this is a comparison/debug descriptor, **not**
+     * guaranteed to be a re-parseable UCUM expression (UCUM cannot express arbitrary numeric
+     * factors as literals).
+     */
+    readonly canonical: string;
+} | {
+    /** The expression is not a valid UCUM unit. */
+    readonly valid: false;
+    /** The stable diagnostic code — never a guessed "nearest" unit (the never-fabricate rule). */
+    readonly code: "TERM_UCUM_INVALID";
+    /** A **value-free** structural reason (a grammar fault or an unknown atom; never PHI). */
+    readonly reason: string;
+};
+
+/**
+ * The public **UCUM** surface (roadmap Phase 4): {@link validateUcum} (recognition + a canonical
+ * descriptor) and {@link ucumEqual} (are two expressions the *same unit*).
+ *
+ * Both are **recognition / validation / representation-canonicalization only** — never magnitude
+ * conversion (roadmap §2/§4.3). The never-fabricate posture holds: an unparseable or unknown unit is
+ * a typed {@link TERM_UCUM_INVALID} outcome carrying a value-free reason, **never** a guessed
+ * "nearest" unit; and a special (non-linear) unit is never claimed equal to a linear one.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Validate a UCUM unit expression and, when valid, return its canonical descriptor.
+ *
+ * Validation **is** parsing against the UCUM grammar over the known atom table: an expression is
+ * valid iff it parses completely. An invalid expression returns a typed {@link TERM_UCUM_INVALID}
+ * with a value-free reason — never a coerced or guessed unit.
+ *
+ * @param unit - The UCUM unit expression (e.g. `"mmol/L"`, `"kg.m/s2"`, `"Cel"`).
+ * @returns `{ valid: true, canonical }` or `{ valid: false, code: "TERM_UCUM_INVALID", reason }`.
+ * @example
+ * ```ts
+ * import { validateUcum } from "@cosyte/terminology";
+ *
+ * validateUcum("mmol/L").valid; // => true
+ * const bad = validateUcum("mg/dl/"); // trailing operator
+ * bad.valid; // => false
+ * ```
+ */
+declare function validateUcum(unit: string): UcumValidation;
+/**
+ * Whether two UCUM expressions denote the **same unit** — i.e. they reduce to the same canonical
+ * form (equal base dimensions *and* equal scale). This recognizes representational equivalences
+ * (`N` ≡ `kg.m/s2`, `mmol/L` ≡ `mmol.L-1`, annotations inert) but is **not** magnitude conversion:
+ * `mg` and `g` are different units and compare unequal.
+ *
+ * A unit is never equal to an invalid expression, and a special (non-linear) unit (`Cel`, `[pH]`) is
+ * equal only to a structurally identical special unit — never to a linear unit (the never-fabricate
+ * posture: the engine will not assert an equivalence it cannot prove).
+ *
+ * @param a - The first UCUM unit expression.
+ * @param b - The second UCUM unit expression.
+ * @returns `true` iff both are valid and denote the same unit.
+ * @example
+ * ```ts
+ * import { ucumEqual } from "@cosyte/terminology";
+ *
+ * ucumEqual("N", "kg.m/s2"); // => true
+ * ucumEqual("mmol/L", "mmol.L-1"); // => true
+ * ucumEqual("mg", "g"); // => false
+ * ```
+ */
+declare function ucumEqual(a: string, b: string): boolean;
+
+/**
+ * The **UCUM grammar parser** (roadmap Phase 4): a hand-rolled, zero-dependency recursive-descent
+ * parser from a unit expression string to a {@link UnitNode} AST, grounded firsthand on the UCUM
+ * specification's syntax (base units, metric prefixes attached with no delimiter and resolved by
+ * longest-match, `.` multiply / `/` divide, signed integer exponents, `{…}` inert annotations, and
+ * the `10*` / `10^` powers-of-ten). Validation **is** parsing: an expression is valid iff it parses
+ * completely over **known** atoms — an unknown atom yields no match and fails, never a guessed unit.
+ *
+ * @packageDocumentation
+ */
+
+/** A successful parse (the AST) or a value-free failure reason. */
+type ParseResult = {
+    readonly ok: true;
+    readonly node: UnitNode;
+} | ParseFailure;
+/** A parse failure carrying a value-free structural reason. */
+interface ParseFailure {
+    readonly ok: false;
+    /** A structural description of the fault (never echoes an input *value* beyond the offending token shape). */
+    readonly reason: string;
+}
+/**
+ * Parse a UCUM unit expression into an AST.
+ *
+ * @param unit - The unit expression (e.g. `"mmol/L"`, `"kg.m/s2"`, `"10*3/ul"`).
+ * @returns The parsed {@link UnitNode}, or a typed {@link ParseFailure} with a value-free reason.
+ * @example
+ * ```ts
+ * import { parseUcum } from "@cosyte/terminology";
+ *
+ * parseUcum("mmol/L").ok; // => true
+ * parseUcum("m/").ok; // => false
+ * ```
+ */
+declare function parseUcum(unit: string): ParseResult;
+
+/**
+ * **Dimensional reduction** of a parsed UCUM unit (roadmap Phase 4): reduce an expression to its
+ * canonical base-unit form — a scalar factor times a map of the seven UCUM base dimensions
+ * (`m s g rad K C cd`), recursively substituting each atom's essence definition down to base units.
+ *
+ * This is **representation** canonicalization, not magnitude *conversion*: it answers "are these two
+ * expressions the same unit" (`N` ≡ `kg.m/s2`, `mmol/L` ≡ `mmol.L-1`), never "what is 5 mg/dL in
+ * mmol/L" (that needs an analyte's molar mass — refused, roadmap §2/§4.3). **Special** units (`Cel`,
+ * `B`, `[pH]`) are non-linear and carry no factor/dimension — they reduce to an opaque normalized
+ * form and are never equated with a linear unit. **Arbitrary** units (`[IU]`, `[arb'U]`) are modeled
+ * as their own dimension axis, so they cancel with themselves but convert to nothing else.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Reduce a parsed UCUM unit to its canonical {@link Reduction} — a linear scalar×dimension form, or
+ * an opaque `special` form for expressions involving a non-linear special unit.
+ *
+ * @param node - The AST from {@link parseUcum}.
+ * @returns The reduced form.
+ * @example
+ * ```ts
+ * import { parseUcum, reduce } from "@cosyte/terminology";
+ *
+ * const parsed = parseUcum("N");
+ * if (parsed.ok) {
+ *   const r = reduce(parsed.node);
+ *   r.kind; // => "linear"  (1000 × g·m·s⁻²)
+ * }
+ * ```
+ */
+declare function reduce(node: UnitNode): Reduction;
+
+/**
+ * Parse the vendored, verbatim UCUM `ucum-essence.xml` (embedded as {@link UCUM_ESSENCE_XML}) into
+ * the engine's in-memory unit model — the {@link UcumEssence} table of prefixes and atoms.
+ *
+ * Hand-rolled, **zero-dependency** scanning of a known-well-formed document (not a general XML
+ * parser): the essence file is a flat, regular list of `<prefix>` / `<base-unit>` / `<unit>`
+ * elements. Parsed **once**, lazily, and cached — the engine reads no file at runtime; the table is
+ * a pure transform of the embedded verbatim content (a permitted UCUM use, not a derivative — see
+ * `vendor/ucum/NOTICE.md`).
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Load the UCUM essence table, parsing the embedded verbatim XML on first call and caching it.
+ *
+ * @returns The immutable in-memory {@link UcumEssence} model (7 base units, 24 prefixes, ~305 atoms).
+ * @example
+ * ```ts
+ * import { loadUcumEssence } from "@cosyte/terminology";
+ *
+ * const essence = loadUcumEssence();
+ * essence.atomByCode.has("m"); // => true
+ * ```
+ */
+declare function loadUcumEssence(): UcumEssence;
+
+/**
+ * The types for the **crosswalk resolvers** (roadmap Phase 5) — the CMS ICD-9↔ICD-10 **GEMs**
+ * (General Equivalence Mappings) and the NLM **SNOMED CT → ICD-10-CM complex map**.
+ *
+ * Both are the library's highest-risk surface, and their types are built around the stewards' own
+ * warnings: these maps are **approximate, 1:many, context-dependent, and non-invertible** — *"not
+ * crosswalks… reference mappings"* (CMS on the GEMs), *"semi-automated"* (NLM on the SNOMED map). So
+ * every result type here is a **discriminated, fail-safe outcome** carrying the steward's flags,
+ * never a single collapsed target:
+ *
+ * - a No-Map is a typed {@link CrosswalkNoMap} — the steward said "cannot be classified", surfaced,
+ *   never a guessed code;
+ * - a 1:many source yields the **whole** ordered candidate set, never one confident pick;
+ * - a context-dependent rule with no runtime context is a typed {@link ComplexMapContextRequired} —
+ *   the rule + advice ride through, the engine never picks a branch it wasn't given the data for;
+ * - all Map Advice / GEM flags ride through **verbatim** ("advice flags must not be swallowed",
+ *   roadmap §4.1);
+ * - a directional map is **never inverted** (see {@link ../crosswalk/gems.invertGem}).
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * The **direction** of a loaded GEM file. CMS ships the forward (ICD-9→ICD-10, `…_I9gem.txt`) and
+ * backward (ICD-10→ICD-9, `…_I10gem.txt`) maps as **separate, non-inverse artifacts** — a forward map
+ * composed with a backward map is *"not a mirror image"* (roadmap §4.1). A `GemMap` therefore records
+ * which direction it is and is only ever applied in that direction.
+ */
+type GemDirection = "9-to-10" | "10-to-9";
+/**
+ * The decoded **5-position flag field** of a GEM entry (CMS Dx GEM User's Guide). Each digit is a
+ * steward signal a caller must not ignore; the verbatim field rides through as {@link raw}.
+ *
+ * Positions (left to right): `approximate | no-map | combination | scenario | choice-list`.
+ */
+interface GemFlags {
+    /**
+     * Position 1 — **approximate** flag. `true` when the mapping is approximate (the common case: the
+     * source and target are not identical in meaning); `false` when the entry is an exact identity. A
+     * GEM entry is a *reference* mapping either way — never an assertion of clinical equivalence.
+     */
+    readonly approximate: boolean;
+    /**
+     * Position 2 — **no-map** flag. `true` when the source code has **no valid target** in the other
+     * classification (the target field is the `NoDx`/`NoPCS` sentinel). A first-class typed outcome —
+     * surfaced as a {@link CrosswalkNoMap}, never a fabricated target (roadmap §4.1).
+     */
+    readonly noMap: boolean;
+    /**
+     * Position 3 — **combination** flag. `true` when the source requires a **combination** of target
+     * codes to be fully represented; the entry is one candidate within a scenario/choice-list cluster
+     * (see {@link scenario} / {@link choiceList}), never a standalone 1:1 target.
+     */
+    readonly combination: boolean;
+    /**
+     * Position 4 — **scenario** number (`0` for a non-combination entry). Within a combination, all
+     * entries sharing a scenario describe **one** valid way to represent the source; distinct scenarios
+     * are alternative representations.
+     */
+    readonly scenario: number;
+    /**
+     * Position 5 — **choice-list** number (`0` for a non-combination entry). Within a scenario, a valid
+     * cluster is built by taking **one** target from each distinct choice list.
+     */
+    readonly choiceList: number;
+    /** The verbatim 5-character flag field, carried through untouched. */
+    readonly raw: string;
+}
+/**
+ * One loaded GEM entry — a source code, its (optional) target, and the decoded {@link GemFlags}. A
+ * No-Map entry ({@link GemFlags.noMap}) carries **no** {@link target}: the source has no equivalent,
+ * and the engine never invents one.
+ */
+interface GemEntry {
+    /** The source code (in the map's source classification), verbatim. */
+    readonly source: string;
+    /** The target code (in the map's target classification), verbatim — **absent** for a No-Map entry. */
+    readonly target?: string;
+    /** The decoded steward flags. */
+    readonly flags: GemFlags;
+}
+/**
+ * A loaded, immutable GEM map. Entries are keyed by source code (a source may have many entries — the
+ * maps are 1:many). Applied **only** in its {@link direction}; never inverted.
+ */
+interface GemMap {
+    /** Which direction this file maps. Applied only this way. */
+    readonly direction: GemDirection;
+    /** The GEM version/release (e.g. `"2018"`), when supplied — mappings are release-scoped. */
+    readonly version?: string;
+    /** The number of loaded entries. */
+    readonly count: number;
+    /** Entries keyed by source code, each list in file order. Read-only; frozen. */
+    readonly entries: ReadonlyMap<string, readonly GemEntry[]>;
+    /** The skipped-row warnings surfaced during load, in line order. Frozen; may be empty. */
+    readonly warnings: readonly GemLoadWarning[];
+}
+/**
+ * A surfaced, non-fatal GEM load warning — a malformed line that was **skipped**, reported with its
+ * line number and a value-free structural reason. Liberal on load (roadmap §6, the parsers' posture).
+ */
+interface GemLoadWarning {
+    /** The stable diagnostic code for a skipped GEM row. */
+    readonly code: "TERM_GEM_MALFORMED_ROW";
+    /** The 1-based source line the fault was found on. */
+    readonly line: number;
+    /** A value-free description of the structural fault (never echoes a field value). */
+    readonly detail: string;
+}
+/** One choice list within a combination scenario — pick **one** of its targets to build a cluster. */
+interface GemChoiceList {
+    /** The choice-list number ({@link GemFlags.choiceList}). */
+    readonly choiceList: number;
+    /** The candidate target codes for this choice list, in file order. Frozen; never empty. */
+    readonly targets: readonly string[];
+}
+/**
+ * One combination **scenario** — a single valid way to represent the source as a combination of
+ * target codes. A valid **cluster** is one target taken from each of its {@link choiceLists}.
+ */
+interface GemScenario {
+    /** The scenario number ({@link GemFlags.scenario}). */
+    readonly scenario: number;
+    /** The choice lists composing this scenario, ordered by choice-list number. Frozen. */
+    readonly choiceLists: readonly GemChoiceList[];
+}
+/**
+ * A successful GEM application — one or more candidate targets for the source. The **full** candidate
+ * set is surfaced (never collapsed to one); when the source is a combination, {@link combinations}
+ * carries the scenario/choice-list structure needed to build valid clusters.
+ */
+interface GemMatched {
+    /** Discriminant: the source mapped to at least one target. */
+    readonly mapped: true;
+    /** The source code, echoed. */
+    readonly source: string;
+    /** The direction the map was applied in. */
+    readonly direction: GemDirection;
+    /** Every candidate entry for the source, in file order. Frozen; never empty here. */
+    readonly entries: readonly GemEntry[];
+    /** For a combination source, the scenario→choice-list structure. Absent for a plain 1:many source. */
+    readonly combinations?: readonly GemScenario[];
+}
+/**
+ * One row of the SNOMED CT → ICD-10-CM **complex/extended map** refset — the caller-supplied,
+ * SNOMED-licensed content the resolver runs over (**no SNOMED content is bundled**; roadmap §5). The
+ * field names paraphrase the SNOMED RF2 extended-map refset columns.
+ */
+interface ComplexMapEntry {
+    /** The SNOMED CT source concept id (`referencedComponentId`), verbatim. */
+    readonly source: string;
+    /**
+     * The **map group** (1-based). Distinct groups on one source are an **AND** — the source needs a
+     * target from *each* group (e.g. a manifestation code plus an etiology code). Every group resolves
+     * independently.
+     */
+    readonly group: number;
+    /**
+     * The **map priority** within a group (1-based). Rules are evaluated in ascending priority; the
+     * first whose {@link rule} matches the caller's context wins that group (an if-then-else chain).
+     */
+    readonly priority: number;
+    /**
+     * The **map rule**, verbatim — `"TRUE"` / `"OTHERWISE TRUE"` (unconditional fall-through), or an
+     * `IFA` predicate (e.g. an age-band or gender test) evaluated against caller-supplied context.
+     */
+    readonly rule: string;
+    /**
+     * The **map advice**, verbatim (pipe-delimited in the source) — steward instructions to a human
+     * (`CONSIDER LATERALITY`, `EPISODE OF CARE INFORMATION NEEDED`, `THIS IS A MANIFESTATION CODE…`).
+     * Carried through untouched: advice flags must **never** be swallowed (roadmap §4.1).
+     */
+    readonly advice: string;
+    /** The ICD-10-CM **map target** code, verbatim — **absent** for a No-Map / empty-target row. */
+    readonly target?: string;
+    /** The steward **map category** id (a `MAP_CATEGORIES` value, e.g. `447638001`), when supplied. */
+    readonly category?: string;
+    /** The map **correlation** id (SNOMED map-correlation concept), when supplied. Carried verbatim. */
+    readonly correlation?: string;
+}
+/**
+ * A loaded, immutable SNOMED→ICD-10-CM complex map. Entries are keyed by source concept id; within a
+ * source they are ordered by (group, priority). Applied **only** SNOMED→ICD-10-CM; never inverted.
+ */
+interface ComplexMap {
+    /** The map version/release, when supplied — mappings are release-scoped. */
+    readonly version?: string;
+    /** The number of loaded rows. */
+    readonly count: number;
+    /** Rows keyed by SNOMED source concept id, each ordered by (group, priority). Frozen. */
+    readonly entries: ReadonlyMap<string, readonly ComplexMapEntry[]>;
+    /** The skipped-row warnings surfaced during load, in line order. Frozen; may be empty. */
+    readonly warnings: readonly ComplexMapLoadWarning[];
+}
+/** A surfaced, non-fatal complex-map load warning — a malformed refset row that was skipped. */
+interface ComplexMapLoadWarning {
+    /** The stable diagnostic code for a skipped complex-map row. */
+    readonly code: "TERM_COMPLEX_MAP_MALFORMED_ROW";
+    /** The 1-based source line the fault was found on. */
+    readonly line: number;
+    /** A value-free description of the structural fault. */
+    readonly detail: string;
+}
+/**
+ * The **caller-supplied patient context** an `IFA` rule is evaluated against. The resolver evaluates
+ * only against what it is given: a rule needing context absent here surfaces as a
+ * {@link ComplexMapContextRequired}, never a silently-picked branch (roadmap §4.1).
+ */
+interface PatientContext {
+    /** The patient's age **in years**, when known (for `IFA … Age …` bands). */
+    readonly ageYears?: number;
+    /** The patient's administrative gender, when known (for gender `IFA` rules). */
+    readonly gender?: "male" | "female";
+}
+/**
+ * One map group's resolution — a discriminated outcome. A group resolves to a target, a No-Map, an
+ * ambiguity (candidates surfaced), or a context-required stall; it is **never** a silently-picked
+ * single target when the steward flagged otherwise.
+ */
+type ComplexMapGroupResult = ComplexMapGroupResolved | ComplexMapGroupNoMap | ComplexMapContextRequired;
+/** A group that resolved to a concrete ICD-10-CM target via its winning rule. */
+interface ComplexMapGroupResolved {
+    /** Discriminant. */
+    readonly outcome: "resolved";
+    /** The 1-based map group. */
+    readonly group: number;
+    /** The resolved ICD-10-CM target coding (drawn verbatim from the map). */
+    readonly target: Coding;
+    /** The steward map category, when supplied (e.g. `447637006`). */
+    readonly category?: string;
+    /** The winning rule's advice, verbatim. */
+    readonly advice: string;
+    /** The winning rule text, verbatim (`"TRUE"`, an `IFA` predicate, …). */
+    readonly rule: string;
+}
+/**
+ * A group the steward marked **No-Map** (`447638001` "cannot be classified", or an empty target) — a
+ * typed, surfaced outcome, never a fabricated target.
+ */
+interface ComplexMapGroupNoMap {
+    /** Discriminant. */
+    readonly outcome: "no-map";
+    /** The stable diagnostic code. */
+    readonly code: "TERM_CROSSWALK_NO_MAP";
+    /** The 1-based map group. */
+    readonly group: number;
+    /** The steward map category, when supplied (`447638001`, or absent for an empty-target row). */
+    readonly category?: string;
+    /** The advice on the No-Map row, verbatim. */
+    readonly advice: string;
+}
+/**
+ * A group whose winning path is a **context-dependent** `IFA` rule (or `447639009`/`447640006`
+ * category) for which the caller supplied **no** matching context. The engine surfaces the rules +
+ * advice and refuses to pick a branch (roadmap §4.1) — the never-fabricate rule for runtime context.
+ */
+interface ComplexMapContextRequired {
+    /** Discriminant. */
+    readonly outcome: "context-required";
+    /** The stable diagnostic code. */
+    readonly code: "TERM_CROSSWALK_CONTEXT_REQUIRED";
+    /** The 1-based map group. */
+    readonly group: number;
+    /** The unresolved candidate rules in this group (priority order), each with its target + advice. */
+    readonly rules: readonly ComplexMapEntry[];
+}
+/** A successful complex-map application — one resolution **per map group**, in group order. */
+interface ComplexMapMatched {
+    /** Discriminant: the source concept is present in the map. */
+    readonly mapped: true;
+    /** The SNOMED source concept id, echoed. */
+    readonly source: string;
+    /** One resolution per map group, ordered by group. A source needing N codes has N groups. Frozen. */
+    readonly groups: readonly ComplexMapGroupResult[];
+}
+/**
+ * A **No-Map** outcome — the source is present in the map but the steward declares it has no valid
+ * target ("cannot be classified with available data"). A first-class typed result, **never** a
+ * fabricated target (roadmap §4.1). Distinct from {@link CrosswalkUnmapped} (source absent entirely).
+ */
+interface CrosswalkNoMap {
+    /** Discriminant: the source did not map. */
+    readonly mapped: false;
+    /** Sub-discriminant: this is an authored No-Map, not a plain absence. */
+    readonly noMap: true;
+    /** The stable diagnostic code. */
+    readonly code: "TERM_CROSSWALK_NO_MAP";
+    /** The source code, echoed. */
+    readonly source: string;
+    /** The steward flags/advice that declared the No-Map, carried verbatim. */
+    readonly entries: readonly GemEntry[];
+}
+/**
+ * An **unmapped** outcome — the source code is **not present in the map at all** (distinct from an
+ * authored No-Map). Surfaced as a typed result, never a guessed target and never a silent success.
+ */
+interface CrosswalkUnmapped {
+    /** Discriminant: the source did not map. */
+    readonly mapped: false;
+    /** Sub-discriminant: a plain absence, not an authored No-Map. */
+    readonly noMap: false;
+    /** The stable diagnostic code. */
+    readonly code: "TERM_CROSSWALK_UNMAPPED";
+    /** The source code, echoed. */
+    readonly source: string;
+}
+/** The result of {@link ../crosswalk/gems.applyGem}: a match, an authored No-Map, or an absence. */
+type GemApplyResult = GemMatched | CrosswalkNoMap | CrosswalkUnmapped;
+/**
+ * The result of {@link ../crosswalk/complex-map.applyComplexMap}: a per-group match, or a typed
+ * absence when the source concept is not in the map.
+ */
+type ComplexMapApplyResult = ComplexMapMatched | CrosswalkUnmapped;
+
+/**
+ * The CMS **ICD-9 ↔ ICD-10 GEMs** (General Equivalence Mappings) loader + applier (roadmap Phase 5).
+ *
+ * The GEMs are **CMS/NCHS public-domain** (US-government work) reference mappings between the ICD-9-CM
+ * and ICD-10-CM diagnosis classifications. CMS is emphatic about what they are — *"GEMs are not
+ * crosswalks. They are reference mappings… the raw material from which providers… derive specific
+ * applied mappings"* — so this resolver treats a GEM hit as a **candidate**, never an equivalence:
+ *
+ * - **Approximate by default.** Position-1 flag: most entries are approximate (source and target are
+ *   not identical in meaning). The flag rides through; the engine asserts nothing beyond it.
+ * - **No-Map is first-class.** A source with no valid target carries the `NoDx` sentinel (and the
+ *   position-2 flag); {@link applyGem} returns a typed {@link CrosswalkNoMap}, never a guessed code.
+ * - **1:many, never collapsed.** A source with several targets returns the **whole** candidate set.
+ * - **Combination clusters.** A combination source (position-3 flag) maps to a *combination* of
+ *   targets grouped by scenario (position 4) and choice list (position 5); the result surfaces that
+ *   structure so a caller can build valid clusters, never a single fabricated target.
+ * - **Directional, never inverted.** The forward (9→10) and backward (10→9) files are **separate,
+ *   non-inverse** artifacts; {@link invertGem} refuses to synthesize one from the other.
+ *
+ * The engine ships **no GEM content**: the caller supplies the public-domain GEM file (BYO — roadmap
+ * §2/§5). Bundling the public-domain packs is the separate content-packs phase.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * A raw GEM source file, plus the direction it maps and its release version. BYO — the caller
+ * supplies the public-domain CMS GEM file content.
+ */
+interface GemSource {
+    /** The raw GEM file content (whitespace-delimited: `source target flags`, one entry per line). */
+    readonly content: string;
+    /** Which direction this file maps (`"9-to-10"` for `…_I9gem.txt`, `"10-to-9"` for `…_I10gem.txt`). */
+    readonly direction: GemDirection;
+    /** The GEM release/version (e.g. `"2018"`), when known — mappings are release-scoped. */
+    readonly version?: string;
+}
+/**
+ * Load a CMS GEM file into an immutable {@link GemMap}, keyed by source code.
+ *
+ * Liberal on load: a structurally unusable *line* (not three whitespace-delimited fields, or a
+ * malformed 5-digit flag) is **skipped and surfaced** as a {@link GemLoadWarning}, never a
+ * partially-parsed entry. An unusable *source* is not possible here (an all-malformed file loads to an
+ * empty map with warnings) — there is no fatal for GEM load. Ships **no** GEM content: the entries are
+ * the caller's public-domain file (roadmap §5).
+ *
+ * @param source - The {@link GemSource} (raw content + direction + version).
+ * @returns The immutable {@link GemMap}.
+ * @example
+ * ```ts
+ * import { loadGems, applyGem } from "@cosyte/terminology";
+ *
+ * // Synthetic rows in the CMS GEM format (source target flags): an exact map and a No-Map.
+ * const gems = loadGems({
+ *   direction: "9-to-10",
+ *   version: "2018",
+ *   content: "0010 A000 00000\nV290 NoDx 11000\n",
+ * });
+ * applyGem(gems, "0010").mapped; // => true
+ * ```
+ */
+declare function loadGems(source: GemSource): GemMap;
+/**
+ * Apply a loaded GEM map to a source code, in the map's authored direction only.
+ *
+ * Returns the **full** candidate set (never collapsed to one), with each entry's steward flags; a
+ * combination source additionally surfaces its scenario/choice-list structure. A source the steward
+ * marked No-Map (`NoDx` sentinel) is a typed {@link CrosswalkNoMap}; a source **absent** from the map
+ * is a typed {@link CrosswalkUnmapped} — the two are distinct, and neither is ever a fabricated code.
+ *
+ * @param map - A {@link GemMap} from {@link loadGems}.
+ * @param source - The source code (in the map's source classification).
+ * @returns A {@link GemApplyResult}.
+ * @example
+ * ```ts
+ * import { loadGems, applyGem } from "@cosyte/terminology";
+ *
+ * const gems = loadGems({ direction: "9-to-10", content: "V290 NoDx 11000\n" });
+ * const r = applyGem(gems, "V290");
+ * r.mapped; // => false
+ * ```
+ */
+declare function applyGem(map: GemMap, source: string): GemApplyResult;
+/**
+ * Refuse to invert a directional GEM map. **Always throws** {@link FATAL_CODES.TERM_MAP_NOT_INVERTIBLE}.
+ *
+ * The never-invert invariant made explicit and discoverable: a forward GEM (9→10) is **not** the
+ * inverse of the backward GEM (10→9) — CMS ships them as separate artifacts and *"forward and
+ * backward mappings are not simply the reverse"* (roadmap §4.1). To resolve the other direction, load
+ * the other file with {@link loadGems}; the engine never synthesizes an inverse.
+ *
+ * @param map - The map an inversion was (incorrectly) requested for.
+ * @returns Never — always throws.
+ * @throws {TerminologyError} `TERM_MAP_NOT_INVERTIBLE`, always.
+ * @example
+ * ```ts runnable throws
+ * import { loadGems, invertGem } from "@cosyte/terminology";
+ *
+ * const gems = loadGems({ direction: "9-to-10", content: "0010 A000 00000\n" });
+ * invertGem(gems); // throws TERM_MAP_NOT_INVERTIBLE
+ * ```
+ */
+declare function invertGem(map: GemMap): never;
+
+/**
+ * The **SNOMED CT → ICD-10-CM complex-map** resolver (roadmap Phase 5) — a rule-based, **BYO**
+ * resolver over the caller-supplied complex/extended-map refset. **No SNOMED CT content is bundled**
+ * (roadmap §5): the engine ships the rule machinery; the caller supplies the map rows from their own
+ * SNOMED-licensed release.
+ *
+ * The map is *"semi-automated"* by the steward's own statement — 1:many, context-dependent, with
+ * first-class No-Map states. The resolver honours that:
+ *
+ * - **Map groups are an AND.** A source needing a manifestation *and* an etiology code has two groups;
+ *   {@link applyComplexMap} resolves each independently and returns one result per group.
+ * - **Priorities are an if-then-else.** Within a group, rules run in ascending priority; the first
+ *   whose `IFA` predicate the caller's context satisfies wins.
+ * - **Context it wasn't given, it never guesses.** If deciding a group requires an `IFA` predicate
+ *   (an age band, a gender) the caller left unspecified, the group is a typed
+ *   {@link ComplexMapContextRequired} carrying the candidate rules + advice — never a silently-picked
+ *   branch (roadmap §4.1).
+ * - **No-Map is typed.** A `447638001` "cannot be classified" row (or an empty target) is a typed
+ *   No-Map, never a fabricated code.
+ * - **Advice rides through verbatim.** `CONSIDER LATERALITY`, `EPISODE OF CARE INFORMATION NEEDED`,
+ *   manifestation-code advice — carried untouched to the caller.
+ * - **Never inverted.** The map is applied SNOMED→ICD-10-CM only; the reverse is a separate artifact.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * The discriminated input {@link loadComplexMap} accepts — already-structured refset rows, or a raw
+ * RF2 tab-delimited extended-map refset the caller exported from their SNOMED release.
+ */
+type ComplexMapInput = {
+    readonly format: "rows";
+    readonly rows: readonly ComplexMapEntry[];
+    readonly version?: string;
+} | {
+    readonly format: "rf2";
+    readonly content: string;
+    readonly version?: string;
+};
+/**
+ * Load a SNOMED→ICD-10-CM complex map from **caller-supplied** rows or a raw RF2 refset into an
+ * immutable {@link ComplexMap}, keyed by source concept and ordered by (group, priority).
+ *
+ * Liberal on load: a structurally unusable RF2 *row* is skipped and surfaced as a warning; only an
+ * unusable *source* (empty content, header missing required columns) is a fatal
+ * {@link FATAL_CODES.TERM_CROSSWALK_MALFORMED}. Ships **no** SNOMED content — the rows are the
+ * caller's, under their own licence (roadmap §5).
+ *
+ * @param input - Structured `rows`, or a raw RF2 extended-map refset `content`.
+ * @returns The immutable {@link ComplexMap}.
+ * @throws {TerminologyError} `TERM_CROSSWALK_MALFORMED` when the source is structurally unusable.
+ * @example
+ * ```ts
+ * import { loadComplexMap } from "@cosyte/terminology";
+ *
+ * const map = loadComplexMap({
+ *   format: "rows",
+ *   rows: [
+ *     { source: "195967001", group: 1, priority: 1, rule: "TRUE", advice: "ALWAYS J45.909", target: "J45.909", category: "447637006" },
+ *   ],
+ * });
+ * map.count; // => 1
+ * ```
+ */
+declare function loadComplexMap(input: ComplexMapInput): ComplexMap;
+/**
+ * Apply a loaded SNOMED→ICD-10-CM complex map to a source concept and patient context.
+ *
+ * Resolves **each map group** independently (groups are an AND — a source needing multiple ICD-10-CM
+ * codes has multiple groups) by running its rules in priority order against `context`. A group whose
+ * decision needs `IFA` context the caller did not supply is a typed
+ * {@link ComplexMapContextRequired}; a `447638001` row is a typed No-Map; every result carries the
+ * steward's advice verbatim. **Never** fabricates a target, **never** inverts the map.
+ *
+ * @param map - A {@link ComplexMap} from {@link loadComplexMap}.
+ * @param source - The SNOMED CT source concept id.
+ * @param context - The caller-supplied {@link PatientContext} (age / gender). Optional; a missing
+ *   field that a rule needs yields a `context-required` group, never a guessed branch.
+ * @returns A {@link ComplexMapApplyResult} — per-group resolutions, or a typed absence.
+ * @example
+ * ```ts
+ * import { loadComplexMap, applyComplexMap } from "@cosyte/terminology";
+ *
+ * const map = loadComplexMap({
+ *   format: "rows",
+ *   rows: [
+ *     { source: "72098002", group: 1, priority: 1, rule: "IFA 248152002 | Female (finding) |", advice: "MAP IS CONTEXT DEPENDENT FOR GENDER", target: "O00.9", category: "447639009" },
+ *     { source: "72098002", group: 1, priority: 2, rule: "OTHERWISE TRUE", advice: "CANNOT BE CLASSIFIED", category: "447638001" },
+ *   ],
+ * });
+ * const r = applyComplexMap(map, "72098002", { gender: "female" });
+ * r.mapped; // => true
+ * ```
+ */
+declare function applyComplexMap(map: ComplexMap, source: string, context?: PatientContext): ComplexMapApplyResult;
+/** The SNOMED CT source-system URI a complex-map source concept is drawn from (re-exported for docs). */
+declare const COMPLEX_MAP_SOURCE_SYSTEM = "http://snomed.info/sct";
+
+/**
+ * Steward-defined **map category** and **map-relationship** identifiers the crosswalk resolvers carry
+ * through verbatim — the SNOMED CT complex-map `mapCategoryId` concepts and the map-correlation
+ * concepts. These are **published SNOMED CT metadata identifiers** (concept ids in the SNOMED CT
+ * Model Component module), encoded here as identity facts (like the code-system OID↔URI facts in
+ * {@link ../systems/registry}); **no SNOMED CT content is bundled** — a caller still supplies the map
+ * refset itself under their own SNOMED licence (roadmap §5, the BYO posture).
+ *
+ * The category on a resolved SNOMED→ICD-10-CM map row is the steward telling the caller *how much to
+ * trust the target*: a `447638001` "cannot be classified" row is a **No-Map**, a `447640006`
+ * "ambiguous" row must surface its candidates rather than pick one, and a `447639009`
+ * "context-dependent" row needs runtime patient context. The resolver never collapses these to a
+ * single confident target (roadmap §4.1).
+ *
+ * @packageDocumentation
+ */
+/**
+ * The SNOMED CT complex-map **map category** concept ids — the `mapCategoryId` column of the
+ * SNOMED→ICD-10-CM extended-map refset. Encoded as published identity facts; carried through a
+ * resolution verbatim so a caller sees the steward's own trust signal.
+ *
+ * @example
+ * ```ts
+ * import { MAP_CATEGORIES } from "@cosyte/terminology";
+ *
+ * MAP_CATEGORIES.NO_MAP; // => "447638001"
+ * ```
+ */
+declare const MAP_CATEGORIES: {
+    /** `447637006` — "Map source concept is properly classified" (a normal, usable target). */
+    readonly PROPERLY_CLASSIFIED: "447637006";
+    /** `447638001` — "Map source concept cannot be classified with available data" — a **No-Map**. */
+    readonly NO_MAP: "447638001";
+    /** `447639009` — "Map of source concept is context dependent" (needs runtime patient context). */
+    readonly CONTEXT_DEPENDENT: "447639009";
+    /** `447640006` — "Source concept is ambiguous" — surface candidates, never pick one. */
+    readonly AMBIGUOUS: "447640006";
+};
+/** A value from {@link MAP_CATEGORIES} — the SNOMED map-category id carried on a resolution. */
+type MapCategoryId = (typeof MAP_CATEGORIES)[keyof typeof MAP_CATEGORIES];
+/**
+ * The set of {@link MAP_CATEGORIES} ids the resolver treats as a **No-Map** (a typed, surfaced
+ * "cannot be classified", never a fabricated target).
+ */
+declare const NO_MAP_CATEGORIES: ReadonlySet<string>;
+/**
+ * The canonical code-system URI for **ICD-10-CM** — the target system of both crosswalks. A published
+ * identity fact (mirrors {@link ../systems/registry.SYSTEM_IDENTITIES}); attached to a resolved
+ * target {@link ../common/coding.Coding} so a translation is self-describing.
+ */
+declare const ICD10CM_SYSTEM = "http://hl7.org/fhir/sid/icd-10-cm";
+/**
+ * The canonical code-system URI for **ICD-9-CM** (the legacy diagnosis classification the GEMs bridge
+ * to/from). A published identity fact; attached to a GEM target/source coding.
+ */
+declare const ICD9CM_SYSTEM = "http://hl7.org/fhir/sid/icd-9-cm";
+/**
+ * The canonical code-system URI for **SNOMED CT** — the source system of the SNOMED→ICD-10-CM complex
+ * map. Recognised by URI only; **no SNOMED CT content is bundled** (roadmap §5).
+ */
+declare const SNOMEDCT_SYSTEM = "http://snomed.info/sct";
+
+/**
+ * The types for the **RxNorm drug relationship graph** (roadmap Phase 6) — the ingredient / brand /
+ * clinical-drug / dose-form graph navigated over a **caller-supplied** RxNorm RRF release.
+ *
+ * RxNorm is the US NLM's normalized drug nomenclature. Its concepts (`RXCUI`s) are typed by **term
+ * type** ({@link TermType}: `IN` ingredient, `SCD` semantic clinical drug, `SBD` semantic branded
+ * drug, `BN` brand name, `DF` dose form, …) and wired together by **directed relationships** carried
+ * in `RXNREL.RRF` and labeled by a `RELA` (`has_ingredient`, `tradename_of`, `has_dose_form`,
+ * `consists_of`, …). The graph these form is the whole point of this phase: resolve an `SCD` to its
+ * ingredients, a branded drug to its generic, a drug to its dose form.
+ *
+ * **The direction convention is a documented medication-safety trap** (roadmap §4.2 / §10 Q5), and it
+ * is grounded here firsthand on the NLM RxNorm Technical Documentation (§12.7) and the UMLS Reference
+ * Manual: *"the direction of REL — the relationship which the SECOND concept or atom (with … RXCUI2
+ * …) HAS TO the FIRST concept or atom (with … RXCUI1 …)."* So every `RXNREL` row `(RXCUI1, …, RELA,
+ * RXCUI2, …)` is read **`RXCUI2 ⟶RELA⟶ RXCUI1`** and normalized at load into a
+ * {@link RxNormEdge} with `subject = RXCUI2`, `predicate = RELA`, `object = RXCUI1`. Navigation only
+ * ever follows **authored** edges by their predicate; the engine **never synthesizes an inverse edge**
+ * (RxNorm already ships both directions of an asymmetric relationship as separate rows) and **never
+ * fabricates** an `RXCUI` or a relationship absent from the loaded data — an absent concept is a typed
+ * {@link RxNormUnknown}, an unresolvable NDC a typed {@link NdcUnmapped}, never a guess.
+ *
+ * **No RxNorm content is bundled** (roadmap §5): the engine ships the graph *machinery*; the caller
+ * supplies the RRF release (the public-domain Current Prescribable Content, or the full BYO release).
+ * Bundling the public-domain Prescribable pack is the separate content-packs phase (Phase 7).
+ *
+ * @packageDocumentation
+ */
+/**
+ * A RxNorm **term type** (`TTY`) — the kind of drug concept an `RXCUI` names. These are the
+ * `RXNCONSO.RRF` `TTY` values relevant to the drug graph, grounded on the NLM RxNorm Technical
+ * Documentation (Appendix 5). Carried verbatim on a {@link RxNormConcept}; the engine classifies but
+ * never re-labels a concept.
+ */
+type TermType = "IN" | "PIN" | "MIN" | "BN" | "SCDC" | "SBDC" | "SCD" | "SBD" | "SCDG" | "SBDG" | "GPCK" | "BPCK" | "DF" | "DFG" | "PSN" | "SY" | "TMSY" | "ET";
+/**
+ * One RxNorm concept (`RXCUI`) as loaded from `RXNCONSO.RRF` — its normalized name and term type.
+ * Built from the concept's `SAB=RXNORM` atom (the normalized form); the verbatim `RXCUI`, `TTY`, and
+ * `STR` (name) ride through untouched.
+ */
+interface RxNormConcept {
+    /** The RxNorm concept unique identifier (`RXCUI`), verbatim. */
+    readonly rxcui: string;
+    /** The concept's term type ({@link TermType}), verbatim from `RXNCONSO.TTY`. */
+    readonly tty: TermType;
+    /** The concept's normalized name (`RXNCONSO.STR`), verbatim. */
+    readonly name: string;
+    /** `true` when the source atom is suppressed (`RXNCONSO.SUPPRESS` ≠ `N`) — surfaced, never hidden. */
+    readonly suppressed: boolean;
+}
+/**
+ * One directed relationship edge, normalized from an `RXNREL.RRF` row under the documented direction
+ * convention (see the module doc): the row `(RXCUI1, …, RELA, RXCUI2, …)` becomes
+ * `subject = RXCUI2`, `predicate = RELA`, `object = RXCUI1` — read **`subject ⟶predicate⟶ object`**.
+ */
+interface RxNormEdge {
+    /** The subject `RXCUI` — `RXCUI2` in the source row. The concept the relationship is *from*. */
+    readonly subject: string;
+    /** The relationship label (`RXNREL.RELA`, e.g. `has_ingredient`), verbatim. */
+    readonly predicate: string;
+    /** The object `RXCUI` — `RXCUI1` in the source row. The concept the relationship is *to*. */
+    readonly object: string;
+}
+/**
+ * A resolved **NDC → RXCUI** mapping (from an `RXNSAT.RRF` `ATN=NDC` attribute), carrying the
+ * temporal {@link NdcStatus} and the **as-of release** it is valid for. NDC↔RXCUI is many:1 and
+ * changes across releases (roadmap §4.2), so a resolution is never timeless — the release rides
+ * through on {@link asOf}.
+ */
+interface NdcResolution {
+    /** Discriminant: the NDC resolved to a concept in the loaded release. */
+    readonly resolved: true;
+    /** The 11-digit NDC (as supplied), echoed. */
+    readonly ndc: string;
+    /** The `RXCUI` the NDC attribute is attached to in the loaded release. */
+    readonly rxcui: string;
+    /** The temporal status of the NDC ({@link NdcStatus}). */
+    readonly status: NdcStatus;
+    /** The release version the mapping is valid **as of**, when the graph carries one. */
+    readonly asOf?: string;
+}
+/**
+ * The temporal status of an NDC↔RXCUI mapping (RxNav `getNDCStatus`: `ACTIVE` / `OBSOLETE` / `ALIEN`
+ * / `UNKNOWN`). An NDC found in the loaded release's `RXNSAT` attributes is `active` **as of that
+ * release**; `obsolete` / `alien` come from the RxNav NDC-history data (a differential / BYO source,
+ * not the base RRF concept files) and are surfaced only when the caller supplies them — the engine
+ * **never fabricates** a non-current status (roadmap §4.2).
+ */
+type NdcStatus = "active" | "obsolete" | "alien" | "unknown";
+/** An NDC that could not be resolved to any `RXCUI` in the loaded release — a typed absence. */
+interface NdcUnmapped {
+    /** Discriminant: the NDC is not present in the loaded release. */
+    readonly resolved: false;
+    /** The stable diagnostic code. */
+    readonly code: "TERM_RXNORM_NDC_UNMAPPED";
+    /** The NDC (as supplied), echoed. */
+    readonly ndc: string;
+}
+/** The result of {@link ../rxnorm/navigate.resolveNdc}: a resolution or a typed absence. */
+type NdcResult = NdcResolution | NdcUnmapped;
+/**
+ * A successful graph-navigation result — the concept, the predicate followed, and the **full** set of
+ * related concepts drawn verbatim from the loaded edges. `targets` may be **empty**: that is an
+ * honest, data-grounded "the release has no such edge for this concept", never a fabricated relation.
+ */
+interface RxNormRelated {
+    /** Discriminant: the source `RXCUI` is present in the graph. */
+    readonly found: true;
+    /** The source `RXCUI`, echoed. */
+    readonly rxcui: string;
+    /** The relationship predicate(s) that were followed. */
+    readonly predicates: readonly string[];
+    /** The related concepts, in edge order, each drawn verbatim from the loaded graph. May be empty. */
+    readonly targets: readonly RxNormConcept[];
+}
+/**
+ * A typed **unknown** navigation result — the queried `RXCUI` is **absent from the loaded graph**. A
+ * first-class outcome, never a fabricated concept or an empty success (the never-fabricate invariant,
+ * applied to the drug graph — roadmap §4.2). Distinct from a {@link RxNormRelated} with empty
+ * `targets`, which means "present, but no such relationship".
+ */
+interface RxNormUnknown {
+    /** Discriminant: the source `RXCUI` is not in the graph. */
+    readonly found: false;
+    /** The stable diagnostic code. */
+    readonly code: "TERM_RXNORM_UNKNOWN_RXCUI";
+    /** The queried `RXCUI`, echoed. */
+    readonly rxcui: string;
+}
+/** The result of a graph-navigation query: a match (possibly empty) or a typed unknown source. */
+type RxNormNavResult = RxNormRelated | RxNormUnknown;
+/**
+ * One **approximate**-match candidate (the opt-in, never-default path — roadmap §4.2). Every field is
+ * marked so a caller can never mistake it for an exact identity: {@link approximate} is always `true`
+ * and {@link score} is the labeled, derived similarity. The concept itself is drawn verbatim from the
+ * loaded release.
+ */
+interface RxNormApproximateMatch {
+    /** Always `true` — this is a similarity match, never an exact code resolution. */
+    readonly approximate: true;
+    /** The matched concept, verbatim from the loaded release. */
+    readonly concept: RxNormConcept;
+    /** A derived, labeled similarity score in `[0, 1]` (token overlap). Never a clinical assertion. */
+    readonly score: number;
+}
+/**
+ * A surfaced, non-fatal RxNorm load warning — a malformed `RXNCONSO` / `RXNREL` / `RXNSAT` row that
+ * was **skipped**, reported with its line number and a value-free structural reason (liberal on load,
+ * roadmap §6). Never echoes a field value.
+ */
+interface RxNormLoadWarning {
+    /** The stable diagnostic code for a skipped RxNorm row. */
+    readonly code: "TERM_RXNORM_MALFORMED_ROW";
+    /** Which source file the fault was in. */
+    readonly file: "RXNCONSO" | "RXNREL" | "RXNSAT";
+    /** The 1-based source line the fault was found on. */
+    readonly line: number;
+    /** A value-free description of the structural fault. */
+    readonly detail: string;
+}
+/**
+ * A loaded, immutable RxNorm drug graph: concepts keyed by `RXCUI`, edges indexed by subject, and the
+ * NDC→RXCUI attribute index — all frozen. Applied only in the authored edge direction; never inverted.
+ */
+interface RxNormGraph {
+    /** The release version (e.g. `"RXNORM_2026AA"`), when supplied — mappings are release-scoped. */
+    readonly version?: string;
+    /** Concepts keyed by `RXCUI` (first `SAB=RXNORM` atom per `RXCUI` wins). Frozen. */
+    readonly concepts: ReadonlyMap<string, RxNormConcept>;
+    /** Directed edges indexed by `subject` `RXCUI`, each list in file order. Frozen. */
+    readonly edges: ReadonlyMap<string, readonly RxNormEdge[]>;
+    /** NDC → { rxcui, status } index from `RXNSAT` `ATN=NDC` attributes. Frozen; may be empty. */
+    readonly ndcs: ReadonlyMap<string, {
+        readonly rxcui: string;
+        readonly status: NdcStatus;
+    }>;
+    /** The number of loaded concepts. */
+    readonly conceptCount: number;
+    /** The number of loaded edges. */
+    readonly edgeCount: number;
+    /** The skipped-row warnings surfaced during load, in file/line order. Frozen; may be empty. */
+    readonly warnings: readonly RxNormLoadWarning[];
+}
+
+/**
+ * The **RxNorm drug graph loader** (roadmap Phase 6) — build an immutable {@link RxNormGraph} from a
+ * **caller-supplied** RxNorm RRF release (`RXNCONSO.RRF` + `RXNREL.RRF`, and optionally `RXNSAT.RRF`
+ * for NDC attributes). Reuses the shared, zero-dep {@link ../codesystem/rrf.parseRrfLine} (pipe split,
+ * reserved trailing pipe) — the same RRF reader the CodeSystem layer uses.
+ *
+ * **Column layouts, grounded firsthand** on the NLM RxNorm Technical Documentation (§ file
+ * descriptions):
+ * - `RXNCONSO.RRF` (18 cols): `RXCUI`(0) `LAT`(1) `TS`(2) `LUI`(3) `STT`(4) `SUI`(5) `ISPREF`(6)
+ *   `RXAUI`(7) `SAUI`(8) `SCUI`(9) `SDUI`(10) `SAB`(11) `TTY`(12) `CODE`(13) `STR`(14) `SRL`(15)
+ *   `SUPPRESS`(16) `CVF`(17). Only the **normalized** atoms (`SAB=RXNORM`) with a drug-graph `TTY`
+ *   become graph concepts; the first such atom per `RXCUI` wins.
+ * - `RXNREL.RRF` (16 cols): `RXCUI1`(0) `RXAUI1`(1) `STYPE1`(2) `REL`(3) `RXCUI2`(4) `RXAUI2`(5)
+ *   `STYPE2`(6) `RELA`(7) `RUI`(8) `SRUI`(9) `SAB`(10) `SL`(11) `RG`(12) `DIR`(13) `SUPPRESS`(14)
+ *   `CVF`(15). Read `subject = RXCUI2`, `predicate = RELA`, `object = RXCUI1` (the direction
+ *   convention — see {@link ../rxnorm/rela}). Only concept-level rows (both `RXCUI`s present) with a
+ *   non-empty `RELA` become edges; atom-level (`RXAUI`) rows are not part of the concept graph.
+ * - `RXNSAT.RRF` (13 cols): `RXCUI`(0) … `ATN`(8) `SAB`(9) `ATV`(10) `SUPPRESS`(11) `CVF`(12). Rows
+ *   with `ATN=NDC` index `ATV`(the NDC) → `RXCUI`, marked `active` **as of** the loaded release.
+ *
+ * **Liberal on load** (roadmap §6): a structurally unusable *row* (too few columns, missing a required
+ * value) is **skipped and surfaced** as a `TERM_RXNORM_MALFORMED_ROW` warning, never a partial
+ * concept/edge, never a crash. Rows that are simply *not of interest* (a non-`RXNORM` atom, an
+ * atom-level relationship, a non-`NDC` attribute) are skipped **silently** — they are expected, not
+ * faults. Ships **no** RxNorm content: every concept/edge is the caller's release (roadmap §5).
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * A raw RxNorm RRF release, BYO. The caller supplies the public-domain Current Prescribable Content
+ * subset or the full (licensed) release; the engine bundles **no** RxNorm content (roadmap §5).
+ */
+interface RxNormGraphSource {
+    /** The raw `RXNCONSO.RRF` content (pipe-delimited concept/atom names). */
+    readonly conso: string;
+    /** The raw `RXNREL.RRF` content (pipe-delimited relationships). */
+    readonly rel: string;
+    /** The raw `RXNSAT.RRF` content (pipe-delimited attributes) — supply to resolve NDCs. Optional. */
+    readonly sat?: string;
+    /** The release version (e.g. `"RXNORM_2026AA"`), when known — mappings are release-scoped. */
+    readonly version?: string;
+}
+/**
+ * Load a **caller-supplied** RxNorm RRF release into an immutable {@link RxNormGraph}.
+ *
+ * Parses `RXNCONSO` (concepts), `RXNREL` (directed edges, normalized to the documented direction), and
+ * — when supplied — `RXNSAT` (NDC attributes). Liberal on load: a structurally unusable row is a
+ * skipped, surfaced {@link RxNormLoadWarning}, never partial. Ships **no** RxNorm content — the graph
+ * is entirely the caller's release (roadmap §5).
+ *
+ * @param source - The {@link RxNormGraphSource} (RRF file contents + optional version).
+ * @returns The immutable {@link RxNormGraph}.
+ * @example
+ * ```ts
+ * import { loadRxNormGraph } from "@cosyte/terminology";
+ *
+ * // Synthetic rows in the RxNorm RRF wire format (no real RxNorm content is bundled).
+ * const graph = loadRxNormGraph({
+ *   conso: "1|ENG||||||||||RXNORM|IN||lisinopril||N||\n2|ENG||||||||||RXNORM|SCD||lisinopril 10 MG Oral Tablet||N||",
+ *   // "SCD(2) has_ingredient IN(1)": subject=RXCUI2=2, object=RXCUI1=1.
+ *   rel: "1|||RN|2|||has_ingredient|||RXNORM||||||",
+ * });
+ * graph.conceptCount; // => 2
+ * ```
+ */
+declare function loadRxNormGraph(source: RxNormGraphSource): RxNormGraph;
+
+/**
+ * **RxNorm drug-graph navigation** (roadmap Phase 6) — resolve an `SCD` to its ingredients, a branded
+ * drug to its generic, a drug to its dose form, and an NDC to its `RXCUI`, over a loaded
+ * {@link RxNormGraph}. Every query is **fail-safe and never-fabricate** (roadmap §4.2):
+ *
+ * - a queried `RXCUI` absent from the graph is a typed {@link RxNormUnknown}, never a guessed concept;
+ * - a present concept with no such relationship is a {@link RxNormRelated} with **empty** `targets` —
+ *   an honest, data-grounded "no such edge", distinct from "unknown concept";
+ * - navigation follows only **authored** edges by their predicate; the engine **never synthesizes an
+ *   inverse** (RxNorm ships both directions as separate rows, so brand→generic follows the authored
+ *   `tradename_of` and generic→brand follows the authored `has_tradename`);
+ * - an NDC not in the loaded release is a typed {@link NdcUnmapped}, and a resolution carries the
+ *   **as-of release** and temporal {@link ../rxnorm/types.NdcStatus} (never a timeless assertion);
+ * - approximate matching is an **opt-in, explicitly labeled** path ({@link approximateMatch}), never
+ *   the default and never presented as an exact code resolution.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Look up a single concept by `RXCUI`.
+ *
+ * @param graph - A loaded {@link RxNormGraph}.
+ * @param rxcui - The concept unique identifier.
+ * @returns The {@link RxNormConcept}, or `undefined` when the `RXCUI` is not in the release.
+ * @example
+ * ```ts
+ * import { loadRxNormGraph, getConcept } from "@cosyte/terminology";
+ *
+ * const g = loadRxNormGraph({ conso: "1|ENG||||||||||RXNORM|IN||aspirin||N||", rel: "" });
+ * getConcept(g, "1")?.tty; // => "IN"
+ * ```
+ */
+declare function getConcept(graph: RxNormGraph, rxcui: string): RxNormConcept | undefined;
+/**
+ * Follow one or more `RELA` predicates out of a concept (the generic navigation primitive). Direction
+ * is the **authored** edge direction (`subject ⟶predicate⟶ object`); the engine never inverts.
+ *
+ * @param graph - A loaded {@link RxNormGraph}.
+ * @param rxcui - The source concept.
+ * @param predicate - A `RELA` name, or an array of them (any-of).
+ * @returns A {@link RxNormNavResult}: the related concepts (possibly empty), or a typed unknown source.
+ * @example
+ * ```ts
+ * import { loadRxNormGraph, relatedByRela, RELA } from "@cosyte/terminology";
+ *
+ * // "SCD(2) has_ingredient IN(1)": subject=RXCUI2=2, object=RXCUI1=1.
+ * const g = loadRxNormGraph({
+ *   conso: "1|ENG||||||||||RXNORM|IN||lisinopril||N||\n2|ENG||||||||||RXNORM|SCD||lisinopril 10 MG Oral Tablet||N||",
+ *   rel: "1|||RN|2|||has_ingredient|||RXNORM||||||",
+ * });
+ * const r = relatedByRela(g, "2", RELA.HAS_INGREDIENT);
+ * r.found && r.targets[0]?.name; // => "lisinopril"
+ * ```
+ */
+declare function relatedByRela(graph: RxNormGraph, rxcui: string, predicate: string | readonly string[]): RxNormNavResult;
+/**
+ * The **ingredients** of a concept — the concepts it links to by a **direct** `has_ingredient` /
+ * `has_precise_ingredient` edge in the loaded release.
+ *
+ * This follows the *authored, direct* edge only (never-fabricate, never a synthesized path). Note the
+ * release's own topology: a clinical component (`SCDC`) links directly to its `IN`, whereas some `SCD`
+ * releases route the ingredient through the component (`SCD ⟶consists_of⟶ SCDC ⟶has_ingredient⟶ IN`).
+ * When a drug's ingredient is not a *direct* edge, this honestly returns found-with-empty-targets —
+ * traverse {@link consistsOf} then `ingredientsOf` to reach the ingredient through the component. The
+ * engine never invents the transitive edge.
+ *
+ * @param graph - A loaded {@link RxNormGraph}.
+ * @param rxcui - The concept (a drug or a clinical/branded component).
+ * @returns The directly-linked ingredient concepts (possibly empty), or a typed unknown source.
+ * @example
+ * ```ts
+ * import { loadRxNormGraph, ingredientsOf } from "@cosyte/terminology";
+ *
+ * const g = loadRxNormGraph({
+ *   conso: "1|ENG||||||||||RXNORM|IN||lisinopril||N||\n2|ENG||||||||||RXNORM|SCD||lisinopril 10 MG Oral Tablet||N||",
+ *   rel: "1|||RN|2|||has_ingredient|||RXNORM||||||",
+ * });
+ * ingredientsOf(g, "2").found; // => true
+ * ```
+ */
+declare function ingredientsOf(graph: RxNormGraph, rxcui: string): RxNormNavResult;
+/**
+ * The **generic** form(s) of a branded concept — an `SBD`/`BN`/`BPCK` `tradename_of` its generic. The
+ * authored forward edge; the engine never inverts a `has_tradename` edge to synthesize this.
+ *
+ * @param graph - A loaded {@link RxNormGraph}.
+ * @param rxcui - The branded concept.
+ * @returns The generic concept(s) (possibly empty), or a typed unknown source.
+ * @example
+ * ```ts
+ * import { loadRxNormGraph, genericFor } from "@cosyte/terminology";
+ *
+ * // "SBD(2) tradename_of SCD(1)": subject=RXCUI2=2, object=RXCUI1=1.
+ * const g = loadRxNormGraph({
+ *   conso: "1|ENG||||||||||RXNORM|SCD||lisinopril 10 MG Oral Tablet||N||\n2|ENG||||||||||RXNORM|SBD||Zestril 10 MG Oral Tablet||N||",
+ *   rel: "1|||RN|2|||tradename_of|||RXNORM||||||",
+ * });
+ * genericFor(g, "2").found; // => true
+ * ```
+ */
+declare function genericFor(graph: RxNormGraph, rxcui: string): RxNormNavResult;
+/**
+ * The **branded** form(s) of a generic concept — an `SCD`/`IN`/`GPCK` that `has_tradename` a brand.
+ * The authored forward edge; not a synthesized inverse of `tradename_of`.
+ *
+ * @param graph - A loaded {@link RxNormGraph}.
+ * @param rxcui - The generic concept.
+ * @returns The branded concept(s) (possibly empty), or a typed unknown source.
+ * @example
+ * ```ts
+ * import { loadRxNormGraph, brandsFor } from "@cosyte/terminology";
+ *
+ * const g = loadRxNormGraph({
+ *   conso: "1|ENG||||||||||RXNORM|SCD||lisinopril 10 MG Oral Tablet||N||\n2|ENG||||||||||RXNORM|SBD||Zestril 10 MG Oral Tablet||N||",
+ *   rel: "2|||RN|1|||has_tradename|||RXNORM||||||",
+ * });
+ * brandsFor(g, "1").found; // => true
+ * ```
+ */
+declare function brandsFor(graph: RxNormGraph, rxcui: string): RxNormNavResult;
+/**
+ * The **dose form(s)** of a drug — the `DF`/`DFG` concepts it `has_dose_form` / `has_doseformgroup`.
+ *
+ * @param graph - A loaded {@link RxNormGraph}.
+ * @param rxcui - The drug concept.
+ * @returns The dose-form concept(s) (possibly empty), or a typed unknown source.
+ * @example
+ * ```ts
+ * import { loadRxNormGraph, doseFormsOf } from "@cosyte/terminology";
+ *
+ * const g = loadRxNormGraph({
+ *   conso: "1|ENG||||||||||RXNORM|SCD||lisinopril 10 MG Oral Tablet||N||\n9|ENG||||||||||RXNORM|DF||Oral Tablet||N||",
+ *   rel: "9|||RN|1|||has_dose_form|||RXNORM||||||",
+ * });
+ * doseFormsOf(g, "1").found; // => true
+ * ```
+ */
+declare function doseFormsOf(graph: RxNormGraph, rxcui: string): RxNormNavResult;
+/**
+ * The **components** a drug `consists_of` — an `SCD`/`SBD` → its `SCDC`/`SBDC` dose-form components.
+ *
+ * @param graph - A loaded {@link RxNormGraph}.
+ * @param rxcui - The drug concept.
+ * @returns The component concept(s) (possibly empty), or a typed unknown source.
+ * @example
+ * ```ts
+ * import { loadRxNormGraph, consistsOf } from "@cosyte/terminology";
+ *
+ * const g = loadRxNormGraph({
+ *   conso: "2|ENG||||||||||RXNORM|SCD||lisinopril 10 MG Oral Tablet||N||\n3|ENG||||||||||RXNORM|SCDC||lisinopril 10 MG||N||",
+ *   rel: "3|||RN|2|||consists_of|||RXNORM||||||",
+ * });
+ * consistsOf(g, "2").found; // => true
+ * ```
+ */
+declare function consistsOf(graph: RxNormGraph, rxcui: string): RxNormNavResult;
+/**
+ * Resolve an **NDC** (National Drug Code) to its `RXCUI` in the loaded release, carrying the temporal
+ * status and the as-of release. NDC↔RXCUI is many:1 and changes across releases (roadmap §4.2), so an
+ * NDC present in the release is `active` **as of that release**; an absent NDC is a typed
+ * {@link NdcUnmapped}, never a guessed `RXCUI`.
+ *
+ * @param graph - A loaded {@link RxNormGraph} (load with `sat` supplied to populate NDC attributes).
+ * @param ndc - The NDC (as it appears in the release, e.g. 11-digit).
+ * @returns An {@link NdcResult} — a resolution with status + `asOf`, or a typed absence.
+ * @example
+ * ```ts
+ * import { loadRxNormGraph, resolveNdc } from "@cosyte/terminology";
+ *
+ * const g = loadRxNormGraph({
+ *   conso: "2|ENG||||||||||RXNORM|SCD||lisinopril 10 MG Oral Tablet||N||",
+ *   rel: "",
+ *   sat: "2||||||||NDC|RXNORM|00000000000|N||",
+ *   version: "RXNORM_2026AA",
+ * });
+ * const r = resolveNdc(g, "00000000000");
+ * r.resolved && r.status; // => "active"
+ * ```
+ */
+declare function resolveNdc(graph: RxNormGraph, ndc: string): NdcResult;
+/** Options for {@link approximateMatch}. */
+interface ApproximateMatchOptions {
+    /** Minimum similarity (`0`–`1`) for a candidate to be returned. Default `0.34`. */
+    readonly minScore?: number;
+    /** Maximum number of candidates to return, best-first. Default `20`. */
+    readonly limit?: number;
+}
+/**
+ * **Opt-in, explicitly labeled** approximate name matching (roadmap §4.2) — find loaded concepts whose
+ * names are token-similar to `query`. This is **never** the default resolution path and its results
+ * are **never** an exact code assertion: every candidate is marked `approximate: true` with a derived
+ * {@link RxNormApproximateMatch.score}. A caller opts in by calling this function explicitly.
+ *
+ * Coverage is not correctness (roadmap §4.2): a "no match" is an **empty** array (typed, honest),
+ * distinct from a fabricated nearest guess. The engine never promotes an approximate hit to an exact
+ * one.
+ *
+ * @param graph - A loaded {@link RxNormGraph}.
+ * @param query - A free-text drug name to match against loaded concept names.
+ * @param options - {@link ApproximateMatchOptions} (min score, limit).
+ * @returns The labeled approximate candidates, best-first (possibly empty). Never an exact resolution.
+ * @example
+ * ```ts
+ * import { loadRxNormGraph, approximateMatch } from "@cosyte/terminology";
+ *
+ * const g = loadRxNormGraph({
+ *   conso: "1|ENG||||||||||RXNORM|IN||lisinopril||N||",
+ *   rel: "",
+ * });
+ * approximateMatch(g, "lisinopril")[0]?.approximate; // => true
+ * ```
+ */
+declare function approximateMatch(graph: RxNormGraph, query: string, options?: ApproximateMatchOptions): readonly RxNormApproximateMatch[];
+
+/**
+ * The RxNorm **relationship (`RELA`) vocabulary** and the **direction convention** the drug graph is
+ * built on — encoded here as published identity facts (like the code-system OID↔URI facts in
+ * {@link ../systems/registry}), grounded firsthand on the NLM RxNorm Technical Documentation and the
+ * UMLS Reference Manual. **No RxNorm content is bundled** — only the relationship *names* and the
+ * *rule* for reading a row's direction (roadmap §5).
+ *
+ * **The direction rule (roadmap §4.2 / §10 Q5 — a documented medication-safety trap).** From the
+ * RxNorm Technical Documentation (§12.7) and the UMLS Reference Manual, verbatim: *"the direction of
+ * REL — the relationship which the SECOND concept or atom (with … RXCUI2 …) HAS TO the FIRST concept
+ * or atom (with … RXCUI1 …)."* The doc's worked example — a row with `RXCUI1=1155862`, `RELA=isa`,
+ * `RXCUI2=197589` — reads *"197589 **isa** 1155862"* (the second concept is-a the first).
+ *
+ * So an `RXNREL.RRF` row is read **`RXCUI2 ⟶RELA⟶ RXCUI1`**, and {@link ../rxnorm/load.loadRxNormGraph}
+ * normalizes every row to `subject = RXCUI2`, `predicate = RELA`, `object = RXCUI1`. Concretely, a
+ * `has_ingredient` row places the **drug** in `RXCUI2` and the **ingredient** in `RXCUI1` (the drug
+ * *has* the ingredient); a `tradename_of` row places the **branded** concept in `RXCUI2` and the
+ * **generic** in `RXCUI1` (the brand *is a tradename of* the generic). Getting this backwards is a
+ * wrong-medication bug, so the fixtures pin it against the doc's convention.
+ *
+ * @packageDocumentation
+ */
+/**
+ * The drug-graph `RELA` relationship names, grounded on the NLM RxNorm Technical Documentation
+ * (Appendix 1). Each is directional and read `subject ⟶RELA⟶ object` after normalization (see the
+ * module doc). RxNorm ships both members of an inverse pair as **separate rows**, so the graph
+ * traverses the authored predicate for the direction it wants — it **never synthesizes an inverse**.
+ *
+ * @example
+ * ```ts
+ * import { RELA } from "@cosyte/terminology";
+ *
+ * RELA.HAS_INGREDIENT; // => "has_ingredient"
+ * ```
+ */
+declare const RELA: {
+    /** `has_ingredient` — subject (a drug/component) *has ingredient* object (an `IN`/`PIN`). */
+    readonly HAS_INGREDIENT: "has_ingredient";
+    /** `ingredient_of` — subject (an `IN`/`PIN`) *is an ingredient of* object (a drug/component). */
+    readonly INGREDIENT_OF: "ingredient_of";
+    /** `has_precise_ingredient` — subject *has precise ingredient* object (a `PIN`). */
+    readonly HAS_PRECISE_INGREDIENT: "has_precise_ingredient";
+    /** `precise_ingredient_of` — inverse of `has_precise_ingredient`. */
+    readonly PRECISE_INGREDIENT_OF: "precise_ingredient_of";
+    /** `tradename_of` — subject (a branded concept) *is a tradename of* object (its generic). */
+    readonly TRADENAME_OF: "tradename_of";
+    /** `has_tradename` — subject (a generic concept) *has tradename* object (a branded concept). */
+    readonly HAS_TRADENAME: "has_tradename";
+    /** `has_dose_form` — subject (a drug) *has dose form* object (a `DF`). */
+    readonly HAS_DOSE_FORM: "has_dose_form";
+    /** `dose_form_of` — subject (a `DF`) *is the dose form of* object (a drug). */
+    readonly DOSE_FORM_OF: "dose_form_of";
+    /** `has_doseformgroup` — subject *has dose-form group* object (a `DFG`). */
+    readonly HAS_DOSE_FORM_GROUP: "has_doseformgroup";
+    /** `doseformgroup_of` — inverse of `has_doseformgroup`. */
+    readonly DOSE_FORM_GROUP_OF: "doseformgroup_of";
+    /** `consists_of` — subject (an `SCD`/`SBD`) *consists of* object (its `SCDC`/`SBDC` component(s)). */
+    readonly CONSISTS_OF: "consists_of";
+    /** `constitutes` — subject (a component) *constitutes* object (the drug). Inverse of `consists_of`. */
+    readonly CONSTITUTES: "constitutes";
+    /** `contains` — subject (a pack) *contains* object (a member drug). */
+    readonly CONTAINS: "contains";
+    /** `contained_in` — subject (a drug) *is contained in* object (a pack). Inverse of `contains`. */
+    readonly CONTAINED_IN: "contained_in";
+    /** `has_quantified_form` — subject *has quantified form* object. */
+    readonly HAS_QUANTIFIED_FORM: "has_quantified_form";
+    /** `quantified_form_of` — inverse of `has_quantified_form`. */
+    readonly QUANTIFIED_FORM_OF: "quantified_form_of";
+    /** `isa` — subject *is a* object (hierarchical, e.g. `SCD isa SCDG`). */
+    readonly ISA: "isa";
+    /** `inverse_isa` — subject *is a parent of* object. Inverse of `isa`. */
+    readonly INVERSE_ISA: "inverse_isa";
+};
+/** A value from {@link RELA} — a drug-graph relationship name. */
+type RelaName = (typeof RELA)[keyof typeof RELA];
+/**
+ * The authored **inverse pairs** of the drug-graph `RELA`s — a published fact (RxNorm Appendix 1),
+ * used only to *document* and *validate* that a caller is traversing a real relationship. The graph
+ * **never** uses this to synthesize a missing edge: RxNorm ships both directions, so
+ * {@link ../rxnorm/navigate} follows whichever authored predicate points the way it wants to go.
+ *
+ * @example
+ * ```ts
+ * import { RELA_INVERSE, RELA } from "@cosyte/terminology";
+ *
+ * RELA_INVERSE[RELA.HAS_INGREDIENT]; // => "ingredient_of"
+ * ```
+ */
+declare const RELA_INVERSE: Readonly<Record<string, string>>;
+/** The canonical code-system URI for **RxNorm** — a published identity fact, attached to graph codings. */
+declare const RXNORM_SYSTEM = "http://www.nlm.nih.gov/research/umls/rxnorm";
+
+/**
+ * The RxNorm **term-type (`TTY`) vocabulary** relevant to the drug graph — the normal-form ladder and
+ * the cross-link kinds — encoded as published identity facts (grounded firsthand on the NLM RxNorm
+ * Technical Documentation, Appendix 5). **No RxNorm content is bundled** (roadmap §5): these are the
+ * *labels*, not the drug list.
+ *
+ * The RxNorm normal-form graph runs `IN → SCDC → SCD → SBD` (ingredient → clinical-drug component →
+ * semantic clinical drug → semantic branded drug), with `BN` (brand name) and `DF` (dose form) as
+ * cross-links (roadmap §4.2).
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * The drug-graph term types (`RXNCONSO.TTY`), each mapped to its short gloss. Encoded as an identity
+ * fact; a concept's `TTY` is carried verbatim on its {@link ../rxnorm/types.RxNormConcept}, never
+ * re-labeled.
+ *
+ * @example
+ * ```ts
+ * import { TERM_TYPES } from "@cosyte/terminology";
+ *
+ * TERM_TYPES.SCD; // => "Semantic Clinical Drug"
+ * ```
+ */
+declare const TERM_TYPES: Readonly<Record<TermType, string>>;
+/**
+ * Narrow a raw `RXNCONSO.TTY` string to a known {@link TermType}, or `undefined` when it is not a
+ * drug-graph term type this engine models (the concept is then skipped at load, liberal-on-load —
+ * never coerced to a wrong type).
+ *
+ * @param tty - The raw `TTY` value from an `RXNCONSO` row.
+ * @returns The narrowed {@link TermType}, or `undefined` when unrecognized.
+ * @example
+ * ```ts
+ * import { asTermType } from "@cosyte/terminology";
+ *
+ * asTermType("SCD"); // => "SCD"
+ * asTermType("ZZZ"); // => undefined
+ * ```
+ */
+declare function asTermType(tty: string): TermType | undefined;
+
+/**
+ * Public entry point for **`@cosyte/terminology`** — a zero-dependency, developer-focused
+ * **terminology engine** for US healthcare code systems.
+ *
+ * Unlike its sibling `@cosyte/*` packages, this is **not a wire-format parser**: it mirrors the
+ * **FHIR Terminology Module** (`$translate`, `$lookup`, `$validate-code`, `$expand`, …), operating
+ * over **consumer-supplied** FHIR resources. It ships the *engine*, never copyrighted terminology
+ * *content* (SNOMED/CPT/full-LOINC/UMLS are strictly BYO); code-system *identities* (OID ↔ URI) are
+ * published facts, encoded here and cited firsthand.
+ *
+ * **Phase 1** ships exactly the surface `@cosyte/transform` pins:
+ *
+ * - {@link resolveSystem} — the code-system identity / canonical-URI resolver (mnemonic | OID → URI).
+ * - {@link loadConceptMap} + {@link translate} — the ConceptMap `$translate` engine, with the
+ *   **never-fabricate / never-invert** invariants: an unmapped source is a typed
+ *   {@link TranslateUnmapped}, never a guessed target; a directional map is never run backwards.
+ *
+ * **Phase 2** adds the CodeSystem load layer and the FHIR `$lookup` / `$validate-code` operations:
+ *
+ * - {@link loadCodeSystem} — load a **consumer-supplied** release (RRF / CSV / fixed-width / FHIR
+ *   `CodeSystem` JSON) into an immutable model. Ships the engine, **never** copyrighted content.
+ * - {@link lookup} — code → display + properties, carrying status (deprecated / header-not-billable).
+ * - {@link validateCode} — is a code a valid member of the system, with its status flags.
+ *
+ * The never-fabricate invariant holds here too: an unknown code is a typed `unknown` / `valid: false`,
+ * never a fabricated display or a guessed `valid: true`.
+ *
+ * **Phase 3** adds the ValueSet binding layer — FHIR `$expand` / `$validate-code` over a `compose`:
+ *
+ * - {@link loadValueSet} — load a **consumer-supplied** FHIR `ValueSet` (intensional `compose` and/or
+ *   a pre-computed `expansion`) into an immutable model.
+ * - {@link expand} — flatten membership over the supplied {@link CodeSystem}s (`include`/`exclude`,
+ *   explicit `concept` lists, `is-a`/property `filter`s, referenced value sets), with an honest
+ *   `complete` flag: an unresolvable part is a typed `TERM_VALUESET_CANNOT_EXPAND`, never a guess.
+ * - {@link validateCodeInValueSet} — binding membership, returning a **decided** `result` only when
+ *   proven and a typed `undetermined` otherwise (a truncated expansion never reads as complete).
+ *
+ * **Phase 4** adds the **UCUM** unit layer — a hand-rolled UCUM grammar parser + validation +
+ * representation canonicalization (recognition only, **no** magnitude conversion):
+ *
+ * - {@link validateUcum} — is a string a valid UCUM unit; if so, its canonical descriptor. An
+ *   invalid unit is a typed `TERM_UCUM_INVALID`, never a guessed "nearest" unit.
+ * - {@link ucumEqual} — do two expressions denote the *same unit* (`N` ≡ `kg.m/s2`), by reducing
+ *   both to base dimensions. Not magnitude conversion (`mg/dL` → `mmol/L` is refused).
+ * - {@link parseUcum} / {@link reduce} / {@link loadUcumEssence} — the underlying grammar parser,
+ *   dimensional reducer, and the in-memory model of the vendored, verbatim UCUM table.
+ *
+ * **Phase 5** adds the **crosswalk resolvers** — the never-fabricate/never-invert invariant applied
+ * to the published, directional reference maps (roadmap §4.1, the safety crown):
+ *
+ * - {@link loadGems} + {@link applyGem} — the CMS **ICD-9↔ICD-10 GEMs** (public-domain reference
+ *   mappings), honoring the steward's Approximate / No-Map / Combination (scenario→choice-list) flags.
+ *   A No-Map source is a typed {@link CrosswalkNoMap}; a 1:many source returns the full candidate set.
+ * - {@link loadComplexMap} + {@link applyComplexMap} — the NLM **SNOMED CT → ICD-10-CM complex map**
+ *   (BYO, SNOMED-licensed content — **zero bundled**), evaluating Map Group / Priority / `IFA` Rule /
+ *   Advice / Category against caller-supplied {@link PatientContext}; a rule needing context the
+ *   caller lacks is a typed {@link ComplexMapContextRequired}, never a guessed branch.
+ * - {@link invertGem} — the never-invert refusal made a first-class, thrown contract
+ *   ({@link FATAL_CODES.TERM_MAP_NOT_INVERTIBLE}).
+ *
+ * **Phase 6** adds the **RxNorm drug relationship graph** — ingredient / brand / clinical-drug /
+ * dose-form navigation over a **caller-supplied** RxNorm RRF release (roadmap §4.2):
+ *
+ * - {@link loadRxNormGraph} — load `RXNCONSO` (concepts, typed by `TTY`), `RXNREL` (directed `RELA`
+ *   edges, normalized to the documented `RXCUI2 ⟶RELA⟶ RXCUI1` direction), and optionally `RXNSAT`
+ *   (NDC attributes) into an immutable graph. Ships **no** RxNorm content — BYO release (roadmap §5).
+ * - {@link ingredientsOf} / {@link genericFor} / {@link brandsFor} / {@link doseFormsOf} /
+ *   {@link consistsOf} / {@link relatedByRela} — graph navigation following **authored** edges only
+ *   (the engine never synthesizes an inverse). An absent `RXCUI` is a typed {@link RxNormUnknown}.
+ * - {@link resolveNdc} — NDC → `RXCUI` carrying the temporal status and the as-of release; an absent
+ *   NDC is a typed {@link NdcUnmapped}, never a guess.
+ * - {@link approximateMatch} — the **opt-in, explicitly labeled** similarity path (never the default,
+ *   never an exact code assertion).
+ *
+ * Deferred to later phases: the bundleable public-domain content packs, including the RxNorm Current
+ * Prescribable Content pack and a GEM pack (the content-packs phase, Phase 7). The GEMs and the
+ * Prescribable subset are public-domain, so a caller may supply them today (BYO); SNOMED/CPT/full-UMLS
+ * content stays BYO permanently (a licensing wall — roadmap §5).
+ *
+ * @packageDocumentation
+ */
+/**
+ * Library version string, synced with `package.json#version` at release time.
+ *
+ * @example
+ * ```ts
+ * import { VERSION } from "@cosyte/terminology";
+ * typeof VERSION; // => "string"
+ * ```
+ */
+declare const VERSION = "0.0.0";
+
+export { type AnnotationNode, type ApproximateMatchOptions, type BillableFlag, COMPLEX_MAP_SOURCE_SYSTEM, type CodeSystem, type CodeSystemSource, type CodeableConcept, type Coding, type ComplexMap, type ComplexMapApplyResult, type ComplexMapContextRequired, type ComplexMapEntry, type ComplexMapGroupNoMap, type ComplexMapGroupResolved, type ComplexMapGroupResult, type ComplexMapInput, type ComplexMapLoadWarning, type ComplexMapMatched, type ComponentNode, type Concept, type ConceptActivity, type ConceptMap, type ConceptMapElement, type ConceptMapGroup, type ConceptMapTarget, type ConceptMapUnmapped, type ConceptRef, type ConceptSetComponent, type ConceptSetFilter, type ConceptStatus, type CrosswalkNoMap, type CrosswalkUnmapped, type CsvColumnMap, type CsvSource, DIAGNOSTIC_CODES, type DiagnosticCode, type ExpandResult, type ExpansionContains, type ExpansionContext, type ExpansionDiagnostic, FATAL_CODES, type FactorNode, type FatalCode, type FhirCodeSystemSource, type FieldSlice, type FilterMatch, type FilterOperator, type FixedWidthFieldMap, type FixedWidthPropertyField, type FixedWidthSource, type GemApplyResult, type GemChoiceList, type GemDirection, type GemEntry, type GemFlags, type GemLoadWarning, type GemMap, type GemMatched, type GemScenario, type GemSource, type GroupNode, HL7_V2_OID_ROOT, HL7_V2_URL_PREFIX, ICD10CM_ORDER_FILE_FIELDS, ICD10CM_SYSTEM, ICD9CM_SYSTEM, type LinearReduction, type LoadWarning, type LookupOutcome, type LookupResult, type LookupUnknown, MAP_CATEGORIES, type MapCategoryId, type MapProvenance, NO_MAP_CATEGORIES, type NdcResolution, type NdcResult, type NdcStatus, type NdcUnmapped, type ParseFailure, type ParseResult, type PatientContext, type Property, type R4Equivalence, RELA, RELA_INVERSE, RXNORM_SYSTEM, type Reduction, type RelaName, type Relationship, type ResolveSystemResult, type RrfColumnMap, type RrfPropertyColumn, type RrfSource, type RxNormApproximateMatch, type RxNormConcept, type RxNormEdge, type RxNormGraph, type RxNormGraphSource, type RxNormLoadWarning, type RxNormNavResult, type RxNormRelated, type RxNormUnknown, SNOMEDCT_SYSTEM, SYSTEM_IDENTITIES, type SimpleUnitNode, type SpecialReduction, type StatusMapper, type Subsumption, type SystemIdentity, TERM_TYPES, type TermType, TerminologyError, type TranslateMatch, type TranslateMatched, type TranslateResult, type TranslateUnmapped, type UcumAtom, type UcumEssence, type UcumPrefix, type UcumValidation, type UnitNode, type UnknownSystem, type UnmappedMode, VERSION, type ValidateCodeResult, type ValueSet, type ValueSetCompose, type ValueSetExpansion, type ValueSetMemberDecided, type ValueSetMemberUndetermined, type ValueSetMembership, applyComplexMap, applyGem, approximateMatch, asTermType, brandsFor, buildSubsumption, codeableConcept, coding, consistsOf, defaultStatusMapper, doseFormsOf, expand, genericFor, getArray, getBoolean, getConcept, getNumber, getString, ingredientsOf, invertGem, isA, isJsonObject, isUnknownSystem, loadCodeSystem, loadComplexMap, loadConceptMap, loadGems, loadRxNormGraph, loadUcumEssence, loadValueSet, lookup, makeStatus, matchesFilter, parseCsv, parseCsvSource, parseFhirCodeSystem, parseFixedWidth, parseRrf, parseRrfLine, parseUcum, reduce, relatedByRela, resolveNdc, resolveSystem, sliceField, translate, ucumEqual, unsupportedOps, validateCode, validateCodeInValueSet, validateUcum };