@cosyte/terminology 0.0.1 → 0.0.4

package/dist/index.d.ts

@@ -38,7 +38,7 @@ interface Coding {
 /**
  * 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}.
+ * {@link ../conceptmap/translate.translate} operates on a single {@link Coding}.
  *
  * @example
  * ```ts
@@ -102,7 +102,7 @@ declare function codeableConcept(init: CodeableConcept): CodeableConcept;
  *
  * **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
+ * code *in patient context* can be PHI, so messages describe *structure* (a resource
  * path, a code system), never echo arbitrary input *values*.
  *
  * @packageDocumentation
@@ -177,13 +177,13 @@ declare const DIAGNOSTIC_CODES: {
      * 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).
+     * answer for a part it could not compute (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
+     * `contains` entries, or it is flagged too-costly (the VSAC `$expand` >1200-code truncation
+     * hazard). 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";
@@ -191,7 +191,7 @@ declare const DIAGNOSTIC_CODES: {
      * 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
+     * coerced or "nearest" unit (the never-fabricate invariant, applied to units). The
      * `reason` is value-free (a grammar fault or an unknown-atom shape), never PHI.
      */
     readonly TERM_UCUM_INVALID: "TERM_UCUM_INVALID";
@@ -199,7 +199,7 @@ declare const DIAGNOSTIC_CODES: {
      * 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
+     * guess** (the never-fabricate invariant, applied to crosswalks). 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";
@@ -213,7 +213,7 @@ declare const DIAGNOSTIC_CODES: {
     /**
      * 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.
+     * to pick a branch** it lacks the data for — never a silently-chosen target.
      */
     readonly TERM_CROSSWALK_CONTEXT_REQUIRED: "TERM_CROSSWALK_CONTEXT_REQUIRED";
     /**
@@ -235,17 +235,27 @@ declare const DIAGNOSTIC_CODES: {
      * **silently** — they are expected, not faults.
      */
     readonly TERM_RXNORM_MALFORMED_ROW: "TERM_RXNORM_MALFORMED_ROW";
+    /**
+     * An `RXCUI` appeared in the release's `SAB=RXNORM` atoms but **none of them could establish its
+     * term type**, so it is **not** in the graph. Either every atom carried a synonym-class `TTY`
+     * (`PSN`/`SY`/`TMSY`, which Appendix 5 defines as a "synonym of another TTY" and which therefore
+     * types a *name* rather than a concept) or every atom carried a `TTY` this engine does not model.
+     * The concept is skipped rather than typed from a synonym atom: an absent concept is already a
+     * first-class typed answer (`TERM_RXNORM_UNKNOWN_RXCUI`), while a concept whose term type reads
+     * `TMSY` is a fabricated claim about what a drug *is* that a caller cannot detect.
+     */
+    readonly TERM_RXNORM_UNTYPED_CONCEPT: "TERM_RXNORM_UNTYPED_CONCEPT";
     /**
      * 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*
+     * never-fabricate invariant, applied to the drug graph). 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
+     * absence, never a guessed `RXCUI`. NDC↔RXCUI is many:1 and temporal, 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";
@@ -295,7 +305,7 @@ declare const FATAL_CODES: {
     /**
      * 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
+     * inverse of the backward map. 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";
@@ -342,7 +352,7 @@ declare class TerminologyError extends Error {
  * 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.
+ * code-in-context (which can be PHI) never flows into a message.
  *
  * @packageDocumentation
  */
@@ -427,9 +437,9 @@ declare function getNumber(obj: unknown, key: string): number | undefined;
  * 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.
+ * the same terminology) is a **published identifier** for the system, not the system's code list — so
+ * it is encoded here, cited firsthand. That is where the line falls: identities are encoded; the code
+ * *lists themselves* (SNOMED CT / CPT / LOINC content) are BYO and never bundled.
  *
  * **Every identity below is grounded firsthand against a primary source** (verified 2026-07-21):
  *
@@ -442,8 +452,8 @@ declare function getNumber(obj: unknown, key: string): number | undefined;
  * - 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
+ * Identities that could not be pinned to a primary source firsthand are **omitted**, not
+ * guessed — notably ICD-9-CM and ICD-10-PCS, whose OID
  * assignments were ambiguous across sources.
  *
  * @packageDocumentation
@@ -754,15 +764,14 @@ declare function loadConceptMap(json: unknown): ConceptMap;
  *
  * 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:
+ * a **typed {@link TranslateUnmapped}**. Two invariants govern it:
  *
  * 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.
+ *    inverse map; it is never synthesized here.
  *
  * @packageDocumentation
  */
@@ -804,14 +813,14 @@ declare function loadConceptMap(json: unknown): ConceptMap;
 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},
+ * The types for the **CodeSystem load layer** and the FHIR `$lookup` / `$validate-code`
+ * operations: 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
+ * **no code-system release** — every concept comes from the caller's data (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`).
  *
@@ -833,7 +842,7 @@ declare function translate(sourceCoding: Coding, map: ConceptMap): TranslateResu
 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
+ * a non-current or non-billable code from being presented as clean. Present only when
  * the loaded release supplied status information; the engine never fabricates a status.
  */
 interface ConceptStatus {
@@ -1059,8 +1068,8 @@ interface FixedWidthFieldMap {
 /**
  * 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.
+ * ICD-10-CM preset, which they confirm against their release's README, since the byte offsets are
+ * not confirmed against an authoritative machine-readable source). BYO.
  */
 interface FixedWidthSource {
     /** Discriminant. */
@@ -1079,7 +1088,7 @@ interface FixedWidthSource {
     readonly statusMap?: StatusMapper;
 }
 /**
- * A **FHIR R4 `CodeSystem`** JSON source (native, license-clean model). The consumer supplies the
+ * A **FHIR R4 `CodeSystem`** JSON source (native, consumer-supplied model). The consumer supplies the
  * untrusted resource; nested `concept` hierarchies are flattened, and the standard `inactive` /
  * `deprecated` concept properties are read into {@link ConceptStatus}.
  */
@@ -1096,8 +1105,8 @@ type CodeSystemSource = RrfSource | CsvSource | FixedWidthSource | FhirCodeSyste
  * {@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
+ * The engine is **content-agnostic**: it loads a *consumer-supplied* release and ships
+ * **no code-system release** of its own. The loaded model is deep-frozen and keyed by code
  * for O(1) {@link lookup}/{@link validateCode}.
  *
  * @packageDocumentation
@@ -1148,7 +1157,7 @@ declare function loadCodeSystem(source: CodeSystemSource): CodeSystem;
  *   `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
+ * Both honor the **never-fabricate invariant**, applied here 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.
@@ -1206,7 +1215,7 @@ declare function validateCode(cs: CodeSystem, code: string): ValidateCodeResult;
  * 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
+ * **Liberal on load**: 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.
@@ -1223,7 +1232,7 @@ declare function validateCode(cs: CodeSystem, code: string): ValidateCodeResult;
  * ```ts
  * import { parseRrfLine } from "@cosyte/terminology";
  *
- * parseRrfLine("314076|ENG|lisinopril 10 MG|"); // => ["314076", "ENG", "lisinopril 10 MG"]
+ * parseRrfLine("316151|ENG|lisinopril 10 MG|"); // => ["316151", "ENG", "lisinopril 10 MG"]
  * ```
  */
 declare function parseRrfLine(line: string): readonly string[];
@@ -1256,8 +1265,8 @@ declare function parseRrf(source: RrfSource): {
 /**
  * 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).
+ * `""`, and commas and newlines are data. Hand-rolled, zero-dep (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
@@ -1312,9 +1321,8 @@ declare function parseCsvSource(source: CsvSource): {
  *
  * 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.
+ * the CMS/CDC order-file layout). Confirm the exact offsets against your 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.
@@ -1345,8 +1353,9 @@ declare function sliceField(line: string, slice: FieldSlice): string;
  * - 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.
+ * on the exact offsets, which are not confirmed against an authoritative machine-readable source.
+ * 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;
 /**
@@ -1372,7 +1381,7 @@ declare function parseFixedWidth(source: FixedWidthSource): {
 };
 
 /**
- * The **FHIR R4 `CodeSystem`** JSON loader — the native, license-clean model. Reads the untrusted
+ * The **FHIR R4 `CodeSystem`** JSON loader — the native, consumer-supplied 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}.
  *
@@ -1418,11 +1427,11 @@ declare function parseFhirCodeSystem(source: FhirCodeSystemSource): {
 /**
  * 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).
+ * assembles the frozen {@link ConceptStatus} (attaching the stable diagnostic code for the two
+ * concerns it distinguishes: 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
+ * docs (LOINC `STATUS` lifecycle values and RxNorm/UMLS `SUPPRESS` values), 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.
  *
@@ -1450,7 +1459,7 @@ 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`.
+ * concerns it distinguishes — `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).
@@ -1466,14 +1475,14 @@ declare const defaultStatusMapper: StatusMapper;
 declare function makeStatus(activity: ConceptActivity, raw?: string, billable?: boolean): ConceptStatus;
 
 /**
- * The types for the **ValueSet binding layer** (roadmap Phase 3): the immutable {@link ValueSet}
+ * The types for the **ValueSet binding layer**: 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
+ * The model is **content-agnostic**: 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 CT / CPT / LOINC / UMLS / VSAC value sets are strictly BYO). 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`).
@@ -1545,8 +1554,8 @@ interface ExpansionContains {
 }
 /**
  * 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).
+ * The engine never re-derives it; it only checks whether it is **complete** (a truncated
+ * expansion must never read as full membership).
  */
 interface ValueSetExpansion {
     /** The server-reported total membership, when present (FHIR `expansion.total`). */
@@ -1581,9 +1590,10 @@ interface ValueSet {
  * {@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
+ * The engine makes **no network call** and holds no bundled code-system release: 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).
+ * {@link DiagnosticCode.TERM_VALUESET_CANNOT_EXPAND}, never a fabricated member.
  */
 interface ExpansionContext {
     /** Loaded code-system releases, keyed by canonical URI (e.g. `"http://loinc.org"`). */
@@ -1631,7 +1641,7 @@ interface ValueSetMemberDecided {
  * 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).
+ * member" (a false "not a member" is a clinical error).
  */
 interface ValueSetMemberUndetermined {
     /** Discriminant: membership could not be decided. */
@@ -1696,7 +1706,7 @@ declare function loadValueSet(json: unknown): ValueSet;
  * `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).
+ *   truncated snapshot is flagged, never treated as full membership.
  * - 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
@@ -1751,8 +1761,8 @@ declare function expand(vs: ValueSet, ctx?: ExpansionContext): ExpandResult;
  * 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).
+ * {@link ValueSetMemberUndetermined} — **never** a fabricated `false` (a false "not a member" is a
+ * clinical error).
  *
  * @packageDocumentation
  */
@@ -1786,9 +1796,9 @@ declare function validateCodeInValueSet(coding: Coding, valueSet: ValueSet, ctx?
  * **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.
+ * the release's **own** hierarchy: subsumption across two separate releases is not computed, and a
+ * code system that encodes no parent edges has no descendants beyond identity, which 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`
@@ -1886,15 +1896,16 @@ interface FilterMatch {
 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
+ * Types for the **UCUM unit layer**: 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.
+ * `mmol/L` needs an analyte's molar mass — a clinical computation the engine refuses). The tables
+ * are the UCUM `ucum-essence.xml`, **bundled verbatim** in this package (copyright © Regenstrief
+ * Institute, Inc. — see `vendor/ucum/NOTICE.md`) and transformed to an in-memory model at runtime;
+ * the engine ships **no derivative** of the UCUM table.
  *
  * @packageDocumentation
  */
@@ -2039,11 +2050,11 @@ type UcumValidation = {
 };
 
 /**
- * The public **UCUM** surface (roadmap Phase 4): {@link validateUcum} (recognition + a canonical
+ * The public **UCUM** surface: {@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
+ * conversion. 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.
  *
@@ -2094,7 +2105,7 @@ declare function validateUcum(unit: string): UcumValidation;
 declare function ucumEqual(a: string, b: string): boolean;
 
 /**
- * The **UCUM grammar parser** (roadmap Phase 4): a hand-rolled, zero-dependency recursive-descent
+ * The **UCUM grammar parser**: 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
@@ -2131,13 +2142,13 @@ interface ParseFailure {
 declare function parseUcum(unit: string): ParseResult;
 
 /**
- * **Dimensional reduction** of a parsed UCUM unit (roadmap Phase 4): reduce an expression to its
+ * **Dimensional reduction** of a parsed UCUM unit: 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`,
+ * mmol/L" (that needs an analyte's molar mass, which the engine refuses). **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.
@@ -2171,8 +2182,9 @@ declare function reduce(node: UnitNode): Reduction;
  * 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`).
+ * a pure in-process transform of the embedded verbatim content, never serialized or distributed. The
+ * UCUM table is copyright © Regenstrief Institute, Inc. and is bundled verbatim — see
+ * `vendor/ucum/NOTICE.md`, which ships with this package.
  *
  * @packageDocumentation
  */
@@ -2192,7 +2204,7 @@ declare function reduce(node: UnitNode): Reduction;
 declare function loadUcumEssence(): UcumEssence;
 
 /**
- * The types for the **crosswalk resolvers** (roadmap Phase 5) — the CMS ICD-9↔ICD-10 **GEMs**
+ * The types for the **crosswalk resolvers** — 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
@@ -2206,8 +2218,7 @@ declare function loadUcumEssence(): UcumEssence;
  * - 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);
+ * - all Map Advice / GEM flags ride through **verbatim** (advice flags must not be swallowed);
  * - a directional map is **never inverted** (see {@link ../crosswalk/gems.invertGem}).
  *
  * @packageDocumentation
@@ -2216,7 +2227,7 @@ declare function loadUcumEssence(): UcumEssence;
 /**
  * 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
+ * composed with a backward map is *"not a mirror image"*. A `GemMap` therefore records
  * which direction it is and is only ever applied in that direction.
  */
 type GemDirection = "9-to-10" | "10-to-9";
@@ -2236,7 +2247,7 @@ interface GemFlags {
     /**
      * 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).
+     * surfaced as a {@link CrosswalkNoMap}, never a fabricated target.
      */
     readonly noMap: boolean;
     /**
@@ -2290,7 +2301,7 @@ interface GemMap {
 }
 /**
  * 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).
+ * line number and a value-free structural reason. Liberal on load (the parsers' posture).
  */
 interface GemLoadWarning {
     /** The stable diagnostic code for a skipped GEM row. */
@@ -2336,8 +2347,8 @@ interface GemMatched {
 }
 /**
  * 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.
+ * SNOMED-licensed content the resolver runs over (**no SNOMED CT refset is bundled**). The field
+ * names paraphrase the SNOMED RF2 extended-map refset columns.
  */
 interface ComplexMapEntry {
     /** The SNOMED CT source concept id (`referencedComponentId`), verbatim. */
@@ -2361,7 +2372,7 @@ interface ComplexMapEntry {
     /**
      * 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).
+     * Carried through untouched: advice flags must **never** be swallowed.
      */
     readonly advice: string;
     /** The ICD-10-CM **map target** code, verbatim — **absent** for a No-Map / empty-target row. */
@@ -2397,7 +2408,7 @@ interface ComplexMapLoadWarning {
 /**
  * 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).
+ * {@link ComplexMapContextRequired}, never a silently-picked branch.
  */
 interface PatientContext {
     /** The patient's age **in years**, when known (for `IFA … Age …` bands). */
@@ -2445,7 +2456,7 @@ interface ComplexMapGroupNoMap {
 /**
  * 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.
+ * advice and refuses to pick a branch — the never-fabricate rule for runtime context.
  */
 interface ComplexMapContextRequired {
     /** Discriminant. */
@@ -2469,7 +2480,7 @@ interface ComplexMapMatched {
 /**
  * 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).
+ * fabricated target. Distinct from {@link CrosswalkUnmapped} (source absent entirely).
  */
 interface CrosswalkNoMap {
     /** Discriminant: the source did not map. */
@@ -2506,7 +2517,7 @@ type GemApplyResult = GemMatched | CrosswalkNoMap | CrosswalkUnmapped;
 type ComplexMapApplyResult = ComplexMapMatched | CrosswalkUnmapped;
 
 /**
- * The CMS **ICD-9 ↔ ICD-10 GEMs** (General Equivalence Mappings) loader + applier (roadmap Phase 5).
+ * The CMS **ICD-9 ↔ ICD-10 GEMs** (General Equivalence Mappings) loader + applier.
  *
  * 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
@@ -2524,8 +2535,7 @@ type ComplexMapApplyResult = ComplexMapMatched | CrosswalkUnmapped;
  * - **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.
+ * The engine ships **no GEM content**: the caller supplies the public-domain GEM file (BYO).
  *
  * @packageDocumentation
  */
@@ -2549,7 +2559,7 @@ interface GemSource {
  * 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).
+ * the caller's public-domain file.
  *
  * @param source - The {@link GemSource} (raw content + direction + version).
  * @returns The immutable {@link GemMap}.
@@ -2593,7 +2603,7 @@ declare function applyGem(map: GemMap, source: string): GemApplyResult;
  *
  * 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
+ * backward mappings are not simply the reverse"*. 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.
@@ -2610,10 +2620,13 @@ declare function applyGem(map: GemMap, source: string): GemApplyResult;
 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 **SNOMED CT → ICD-10-CM complex-map** resolver — a rule-based, **BYO**
+ * resolver over the caller-supplied complex/extended-map refset. **No SNOMED CT refset or release is
+ * bundled**: the engine ships the rule machinery; the caller supplies the map rows from their own
+ * SNOMED CT release. (Individual SNOMED CT concepts this resolver *names* are bundled: the
+ * map-category concepts a row's `mapCategoryId` refers to — see
+ * {@link ../crosswalk/categories.MAP_CATEGORIES} — and the two gender findings a gender `IFA` rule
+ * is written against.)
  *
  * 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:
@@ -2625,7 +2638,7 @@ declare function invertGem(map: GemMap): never;
  * - **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).
+ *   branch.
  * - **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`,
@@ -2654,8 +2667,8 @@ type ComplexMapInput = {
  *
  * 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).
+ * {@link FATAL_CODES.TERM_CROSSWALK_MALFORMED}. Ships **no** SNOMED CT release or refset — the rows
+ * are the caller's, under their own licence.
  *
  * @param input - Structured `rows`, or a raw RF2 extended-map refset `content`.
  * @returns The immutable {@link ComplexMap}.
@@ -2710,23 +2723,25 @@ 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).
+ * concepts. These are SNOMED CT metadata concepts, and **they are bundled**: the four ids below and
+ * their steward descriptions ship inside this package. SNOMED CT is copyright © International Health
+ * Terminology Standards Development Organisation. **No SNOMED CT refset or release is bundled** — a
+ * caller still supplies the map refset itself under their own SNOMED CT licence (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).
+ * single confident target.
  *
  * @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.
+ * SNOMED→ICD-10-CM extended-map refset. These four SNOMED CT concepts — id and steward description —
+ * are **bundled** in this package (SNOMED CT is copyright © International Health Terminology
+ * Standards Development Organisation); carried through a resolution verbatim so a caller sees the
+ * steward's own trust signal.
  *
  * @example
  * ```ts
@@ -2765,22 +2780,24 @@ declare const ICD10CM_SYSTEM = "http://hl7.org/fhir/sid/icd-10-cm";
 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).
+ * map. Recognised by URI only; **no SNOMED CT refset or release is bundled**.
  */
 declare const SNOMEDCT_SYSTEM = "http://snomed.info/sct";
 
 /**
- * The types for the **RxNorm drug relationship graph** (roadmap Phase 6) — the ingredient / brand /
+ * The types for the **RxNorm drug relationship graph** — 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.
+ * `consists_of`, …). The graph these form is the whole point: resolve a drug to its
+ * components and through them to its ingredient, a branded drug to its generic, a drug to its dose
+ * form. Note that the ingredient edge is authored on the component rather than on the `SCD` itself
+ * (see {@link ../rxnorm/navigate.ingredientsOf}).
  *
- * **The direction convention is a documented medication-safety trap** (roadmap §4.2 / §10 Q5), and it
+ * **The direction convention is a documented medication-safety trap**, 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,
@@ -2791,9 +2808,10 @@ declare const SNOMEDCT_SYSTEM = "http://snomed.info/sct";
  * 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).
+ * **No RxNorm release is bundled**: the engine ships the graph *machinery*, and RxNorm's
+ * relationship and term-type *names* (`RELA`, `TERM_TYPES`); the caller
+ * supplies the RRF release (the public-domain Current Prescribable Content, or the full BYO
+ * release).
  *
  * @packageDocumentation
  */
@@ -2802,8 +2820,13 @@ declare const SNOMEDCT_SYSTEM = "http://snomed.info/sct";
  * `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.
+ *
+ * `PSN` / `SY` / `TMSY` are Appendix 5's **synonym** term types: each labels an alternate *name* on
+ * some other concept rather than a concept of its own, so they are part of this vocabulary but can
+ * never appear as a loaded {@link RxNormConcept.tty}. See
+ * {@link ../rxnorm/tty.isSynonymTermType}.
  */
-type TermType = "IN" | "PIN" | "MIN" | "BN" | "SCDC" | "SBDC" | "SCD" | "SBD" | "SCDG" | "SBDG" | "GPCK" | "BPCK" | "DF" | "DFG" | "PSN" | "SY" | "TMSY" | "ET";
+type TermType = "IN" | "PIN" | "MIN" | "BN" | "SCDC" | "SBDC" | "SCDF" | "SBDF" | "SCDFP" | "SBDFP" | "SCD" | "SBD" | "SCDG" | "SBDG" | "SCDGP" | "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
@@ -2812,7 +2835,10 @@ type TermType = "IN" | "PIN" | "MIN" | "BN" | "SCDC" | "SBDC" | "SCD" | "SBD" |
 interface RxNormConcept {
     /** The RxNorm concept unique identifier (`RXCUI`), verbatim. */
     readonly rxcui: string;
-    /** The concept's term type ({@link TermType}), verbatim from `RXNCONSO.TTY`. */
+    /**
+     * The concept's term type ({@link TermType}), verbatim from the `RXNCONSO.TTY` of a **defining**
+     * atom. Never a synonym-class `TTY` (`PSN`/`SY`/`TMSY`), which types a name rather than a concept.
+     */
     readonly tty: TermType;
     /** The concept's normalized name (`RXNCONSO.STR`), verbatim. */
     readonly name: string;
@@ -2835,7 +2861,7 @@ interface RxNormEdge {
 /**
  * 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
+ * changes across releases, so a resolution is never timeless — the release rides
  * through on {@link asOf}.
  */
 interface NdcResolution {
@@ -2855,7 +2881,7 @@ interface NdcResolution {
  * / `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).
+ * **never fabricates** a non-current status.
  */
 type NdcStatus = "active" | "obsolete" | "alien" | "unknown";
 /** An NDC that could not be resolved to any `RXCUI` in the loaded release — a typed absence. */
@@ -2886,8 +2912,8 @@ interface RxNormRelated {
 }
 /**
  * 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
+ * first-class outcome, never a fabricated concept or an empty success (the never-fabricate
+ * invariant, applied to the drug graph). Distinct from a {@link RxNormRelated} with empty
  * `targets`, which means "present, but no such relationship".
  */
 interface RxNormUnknown {
@@ -2901,7 +2927,7 @@ interface RxNormUnknown {
 /** 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
+ * One **approximate**-match candidate (the opt-in, never-default path). 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.
@@ -2915,13 +2941,17 @@ interface RxNormApproximateMatch {
     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.
+ * A surfaced, non-fatal RxNorm load warning: an `RXNCONSO` / `RXNREL` / `RXNSAT` row (or, for
+ * `TERM_RXNORM_UNTYPED_CONCEPT`, an `RXCUI`) that was **skipped**, reported with its line number and
+ * a value-free structural reason (liberal on load). Never echoes a field value.
  */
 interface RxNormLoadWarning {
-    /** The stable diagnostic code for a skipped RxNorm row. */
-    readonly code: "TERM_RXNORM_MALFORMED_ROW";
+    /**
+     * The stable diagnostic code for the skip. `TERM_RXNORM_MALFORMED_ROW` is a structurally unusable
+     * row; `TERM_RXNORM_UNTYPED_CONCEPT` is an `RXCUI` no defining atom could type. Both are in the
+     * package-wide {@link ../common/diagnostics.DIAGNOSTIC_CODES} registry, which documents each.
+     */
+    readonly code: "TERM_RXNORM_MALFORMED_ROW" | "TERM_RXNORM_UNTYPED_CONCEPT";
     /** Which source file the fault was in. */
     readonly file: "RXNCONSO" | "RXNREL" | "RXNSAT";
     /** The 1-based source line the fault was found on. */
@@ -2954,7 +2984,7 @@ interface RxNormGraph {
 }
 
 /**
- * The **RxNorm drug graph loader** (roadmap Phase 6) — build an immutable {@link RxNormGraph} from a
+ * The **RxNorm drug graph loader** — 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.
@@ -2963,8 +2993,8 @@ interface RxNormGraph {
  * 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.
+ *   `SUPPRESS`(16) `CVF`(17). Only the **normalized** atoms (`SAB=RXNORM`) become graph concepts, and
+ *   only through a **defining** `TTY` (see "Typing a concept" below).
  * - `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
@@ -2973,18 +3003,30 @@ interface RxNormGraph {
  * - `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
+ * **Typing a concept (`RXNCONSO`).** An `RXCUI` carries one **defining** atom (its normalized
+ * name, a `TTY` from Appendix 5's "Normalized Names" table) plus any number of **synonym** atoms, whose
+ * `TTY` (`PSN`/`SY`/`TMSY`) Appendix 5 defines as a *"synonym of another TTY"*: it types a **name**,
+ * not a concept. RxNorm documents no ordering between an `RXCUI`'s atoms, so the loader takes the
+ * **defining** atom wherever it sits in the file (first-wins among defining atoms) and **never** falls
+ * back to a synonym atom. An `RXCUI` that no defining atom could type, because every atom is
+ * synonym-class or carries a `TTY` this engine does not model, is **skipped and surfaced** as a
+ * `TERM_RXNORM_UNTYPED_CONCEPT` warning naming the line. Skipping is the deliberate choice: an absent
+ * concept is already a first-class typed outcome (`TERM_RXNORM_UNKNOWN_RXCUI`), whereas a concept
+ * whose `tty` reads `"TMSY"` is a fabricated claim about what the drug *is*, indistinguishable from a
+ * real one.
+ *
+ * **Liberal on load**: 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).
+ * faults. Ships **no** RxNorm release: every concept/edge is the caller's.
  *
  * @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).
+ * subset or the full (licensed) release; the engine bundles **no** RxNorm release.
  */
 interface RxNormGraphSource {
     /** The raw `RXNCONSO.RRF` content (pipe-delimited concept/atom names). */
@@ -3001,8 +3043,12 @@ interface RxNormGraphSource {
  *
  * 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).
+ * skipped, surfaced {@link RxNormLoadWarning}, never partial. Ships **no** RxNorm release — the graph
+ * is entirely the caller's release.
+ *
+ * A concept is typed only by a **defining** atom, never by a synonym-class one and never by file
+ * order; an `RXCUI` no defining atom could type is skipped and surfaced as
+ * `TERM_RXNORM_UNTYPED_CONCEPT`. See the module documentation.
  *
  * @param source - The {@link RxNormGraphSource} (RRF file contents + optional version).
  * @returns The immutable {@link RxNormGraph}.
@@ -3010,10 +3056,10 @@ interface RxNormGraphSource {
  * ```ts
  * import { loadRxNormGraph } from "@cosyte/terminology";
  *
- * // Synthetic rows in the RxNorm RRF wire format (no real RxNorm content is bundled).
+ * // Synthetic rows in the RxNorm RRF wire format (no RxNorm release 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.
+ *   conso: "1|ENG||||||||||RXNORM|IN||lisinopril||N||\n2|ENG||||||||||RXNORM|SCDC||lisinopril 10 MG||N||",
+ *   // "SCDC(2) has_ingredient IN(1)": subject=RXCUI2=2, object=RXCUI1=1.
  *   rel: "1|||RN|2|||has_ingredient|||RXNORM||||||",
  * });
  * graph.conceptCount; // => 2
@@ -3022,9 +3068,9 @@ interface RxNormGraphSource {
 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):
+ * **RxNorm drug-graph navigation**: resolve a drug to its components and its
+ * ingredient, 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**:
  *
  * - 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` —
@@ -3067,9 +3113,9 @@ declare function getConcept(graph: RxNormGraph, rxcui: string): RxNormConcept |
  * ```ts
  * import { loadRxNormGraph, relatedByRela, RELA } from "@cosyte/terminology";
  *
- * // "SCD(2) has_ingredient IN(1)": subject=RXCUI2=2, object=RXCUI1=1.
+ * // "SCDC(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||",
+ *   conso: "1|ENG||||||||||RXNORM|IN||lisinopril||N||\n2|ENG||||||||||RXNORM|SCDC||lisinopril 10 MG||N||",
  *   rel: "1|||RN|2|||has_ingredient|||RXNORM||||||",
  * });
  * const r = relatedByRela(g, "2", RELA.HAS_INGREDIENT);
@@ -3081,12 +3127,35 @@ declare function relatedByRela(graph: RxNormGraph, rxcui: string, predicate: str
  * 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.
+ * This follows the *authored, direct* edge only (never-fabricate, never a synthesized path), and
+ * **RxNorm's ingredient topology is not the obvious one**. Always read the `TTY` of what comes back:
+ *
+ * - concepts on the **clinical** side (`SCDC`, `SCDF`, `SCDG`) link to the ingredient itself, an
+ *   `IN`;
+ * - concepts on the **branded** side (`SBD`, `SBDC`, `SBDF`, `SBDG`) link to their **brand name**, a
+ *   `BN`. That is what the release says and what is echoed back, term type included. It is *not* the
+ *   active ingredient. (`has_precise_ingredient`, which this function also follows, likewise reaches
+ *   a `PIN`.)
+ * - a **clinical drug** (`SCD`) carries **no** `has_ingredient` edge at all. RxNorm authors none, in
+ *   any release, so this honestly returns found-with-empty-targets rather than walking a path on the
+ *   caller's behalf.
+ * - the **precise** forms (`SCDFP`, `SBDFP`, `SCDGP`) carry **neither** edge, so this returns
+ *   found-with-empty-targets for them too. They do **not** behave like their non-precise siblings:
+ *   an `SCDFP` reaches its basis-of-strength substance(s) by `has_boss`, a one-to-many relation with
+ *   a different meaning whose targets can be a `PIN` or a plain `IN`, and which this function
+ *   deliberately does not follow; an `SBDFP` and an
+ *   `SCDGP` author no ingredient-bearing edge at all and are reached instead through `form_of` /
+ *   `tradename_of` / `isa`.
+ *
+ * Those pairings are the ones RxNorm authors, not a closed set a caller may rely on: check the
+ * returned `TTY` rather than assuming it from the one you queried.
+ *
+ * **To reach an active ingredient, walk to the CLINICAL component and take its edge.** From an `SCD`
+ * that is `SCD ⟶consists_of⟶ SCDC ⟶has_ingredient⟶ IN`, i.e. {@link consistsOf} then
+ * `ingredientsOf`. From an `SBD` it needs one more decision, because `consists_of` returns **both**
+ * its branded component (`SBDC`, whose own ingredient edge is the `BN` again) and the clinical
+ * `SCDC`: it is the `SCDC` that leads to the `IN`. The engine never invents the transitive edge and
+ * never picks that branch for you.
  *
  * @param graph - A loaded {@link RxNormGraph}.
  * @param rxcui - The concept (a drug or a clinical/branded component).
@@ -3095,8 +3164,9 @@ declare function relatedByRela(graph: RxNormGraph, rxcui: string, predicate: str
  * ```ts
  * import { loadRxNormGraph, ingredientsOf } from "@cosyte/terminology";
  *
+ * // The ingredient edge is authored on the COMPONENT, not on the clinical drug.
  * const g = loadRxNormGraph({
- *   conso: "1|ENG||||||||||RXNORM|IN||lisinopril||N||\n2|ENG||||||||||RXNORM|SCD||lisinopril 10 MG Oral Tablet||N||",
+ *   conso: "1|ENG||||||||||RXNORM|IN||lisinopril||N||\n2|ENG||||||||||RXNORM|SCDC||lisinopril 10 MG||N||",
  *   rel: "1|||RN|2|||has_ingredient|||RXNORM||||||",
  * });
  * ingredientsOf(g, "2").found; // => true
@@ -3116,7 +3186,7 @@ declare function ingredientsOf(graph: RxNormGraph, rxcui: string): RxNormNavResu
  *
  * // "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||",
+ *   conso: "1|ENG||||||||||RXNORM|SCD||lisinopril 10 MG Oral Tablet||N||\n2|ENG||||||||||RXNORM|SBD||lisinopril 10 MG Oral Tablet [Zestril]||N||",
  *   rel: "1|||RN|2|||tradename_of|||RXNORM||||||",
  * });
  * genericFor(g, "2").found; // => true
@@ -3135,7 +3205,7 @@ declare function genericFor(graph: RxNormGraph, rxcui: string): RxNormNavResult;
  * 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||",
+ *   conso: "1|ENG||||||||||RXNORM|SCD||lisinopril 10 MG Oral Tablet||N||\n2|ENG||||||||||RXNORM|SBD||lisinopril 10 MG Oral Tablet [Zestril]||N||",
  *   rel: "2|||RN|1|||has_tradename|||RXNORM||||||",
  * });
  * brandsFor(g, "1").found; // => true
@@ -3180,7 +3250,7 @@ declare function doseFormsOf(graph: RxNormGraph, rxcui: string): RxNormNavResult
 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
+ * status and the as-of release. NDC↔RXCUI is many:1 and changes across releases, 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`.
  *
@@ -3210,12 +3280,12 @@ interface ApproximateMatchOptions {
     readonly limit?: number;
 }
 /**
- * **Opt-in, explicitly labeled** approximate name matching (roadmap §4.2) — find loaded concepts whose
+ * **Opt-in, explicitly labeled** approximate name matching — 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),
+ * Coverage is not correctness: 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.
  *
@@ -3240,10 +3310,10 @@ declare function approximateMatch(graph: RxNormGraph, query: string, options?: A
  * 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).
+ * UMLS Reference Manual. **No RxNorm release is bundled** — what ships is the relationship *names*
+ * and the *rule* for reading a row's direction.
  *
- * **The direction rule (roadmap §4.2 / §10 Q5 — a documented medication-safety trap).** From the
+ * **The direction rule (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`,
@@ -3251,10 +3321,21 @@ declare function approximateMatch(graph: RxNormGraph, query: string, options?: A
  *
  * 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.
+ * `has_ingredient` row places the **having** concept in `RXCUI2` and what it *has* in `RXCUI1`; 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.
+ *
+ * **Direction is not topology, and the topology is not the obvious one.** Knowing how to read a row
+ * does not tell you which rows exist. RxNorm authors `has_ingredient` from the **clinical** side
+ * (`SCDC`/`SCDF`/`SCDG`) to an `IN`, and from the **branded** side (`SBD`/`SBDC`/`SBDF`/`SBDG`) to a
+ * `BN` rather than to the active ingredient; it authors **no** `SCD ⟶ IN` ingredient edge at all, so
+ * a clinical drug reaches its ingredient only through `consists_of`. The **precise** forms
+ * (`SCDFP`/`SBDFP`/`SCDGP`) carry no `has_ingredient` row either: an `SCDFP` instead reaches its
+ * basis-of-strength substances by `has_boss` (one-to-many, and its targets can be a `PIN` or a plain
+ * `IN`), and the other two author no ingredient-bearing edge at all. Treat those pairings as the
+ * ones RxNorm authors, not as a closed set, and read the `TTY` of what a traversal returns. See
+ * {@link ../rxnorm/navigate.ingredientsOf}.
  *
  * @packageDocumentation
  */
@@ -3272,9 +3353,17 @@ declare function approximateMatch(graph: RxNormGraph, query: string, options?: A
  * ```
  */
 declare const RELA: {
-    /** `has_ingredient` — subject (a drug/component) *has ingredient* object (an `IN`/`PIN`). */
+    /**
+     * `has_ingredient`: subject *has ingredient* object. Authored from the clinical side
+     * (`SCDC`/`SCDF`/`SCDG`) to an `IN` and from the branded side (`SBD`/`SBDC`/`SBDF`/`SBDG`) to a
+     * `BN`; RxNorm authors no `SCD ⟶ IN` row.
+     */
     readonly HAS_INGREDIENT: "has_ingredient";
-    /** `ingredient_of` — subject (an `IN`/`PIN`) *is an ingredient of* object (a drug/component). */
+    /**
+     * `ingredient_of`: subject *is an ingredient of* object. The authored inverse, so an `IN` reaches
+     * clinical components and dose forms and a `BN` reaches branded concepts (the `SBD` included).
+     * Neither reaches an `SCD`.
+     */
     readonly INGREDIENT_OF: "ingredient_of";
     /** `has_precise_ingredient` — subject *has precise ingredient* object (a `PIN`). */
     readonly HAS_PRECISE_INGREDIENT: "has_precise_ingredient";
@@ -3331,33 +3420,47 @@ 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
+ * Technical Documentation, Appendix 5). **No RxNorm release is bundled**: what ships is these
  * *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).
+ * cross-links.
+ *
+ * **Appendix 5 splits these into two kinds, and the split is load-bearing.** A **defining** term type
+ * (its "Normalized Names" table, `IN` … `DFG`) says what an `RXCUI` *is*. A **synonym** term type
+ * (its "Synonyms" table, `PSN` / `SY` / `TMSY`) is Appendix 5's own word for an atom that is a
+ * *"synonym of another TTY"*: it types a **name**, not a concept, so it can never be a concept's term
+ * type. `ET` is in neither table; the appendix describes it only in prose, as "a small number of
+ * concepts with TTY=ET, a term type reserved for entry terms for dose forms". Those are concepts in
+ * their own right rather than synonyms carried on another, so `ET` counts as defining here. See
+ * {@link isSynonymTermType} and {@link ../rxnorm/load.loadRxNormGraph}.
  *
  * @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.
+ * The drug-graph term types (`RXNCONSO.TTY`), each mapped to its **verbatim Appendix 5 name** (`ET`
+ * excepted: the appendix publishes no Name for it, so the UMLS expansion "Entry Term" is used).
+ * Encoded as an identity fact; a concept's `TTY` is carried verbatim on its
+ * {@link ../rxnorm/types.RxNormConcept}, never re-labeled.
+ *
+ * The keys are the full Appendix 5 vocabulary, defining and synonym alike. Only the **defining** ones
+ * can appear on a loaded concept (see {@link isSynonymTermType}).
  *
  * @example
  * ```ts
  * import { TERM_TYPES } from "@cosyte/terminology";
  *
  * TERM_TYPES.SCD; // => "Semantic Clinical Drug"
+ * TERM_TYPES.SCDF; // => "Semantic Clinical Drug Form"
  * ```
  */
 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).
+ * drug-graph term type this engine models (the atom 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.
@@ -3370,6 +3473,25 @@ declare const TERM_TYPES: Readonly<Record<TermType, string>>;
  * ```
  */
 declare function asTermType(tty: string): TermType | undefined;
+/**
+ * Is this term type a **synonym-class** one (`PSN` / `SY` / `TMSY`)?
+ *
+ * Appendix 5 defines each as a *"synonym of another TTY"*: it labels an alternate **name** for a
+ * concept, never the concept's own kind. So a synonym atom can never establish an `RXCUI`'s term
+ * type, and {@link ../rxnorm/load.loadRxNormGraph} will not let one: an `RXCUI` whose release
+ * supplies only synonym atoms is skipped and surfaced, never typed `"TMSY"`.
+ *
+ * @param tty - A {@link TermType}.
+ * @returns `true` for `PSN` / `SY` / `TMSY`; `false` for every defining term type.
+ * @example
+ * ```ts
+ * import { isSynonymTermType } from "@cosyte/terminology";
+ *
+ * isSynonymTermType("TMSY"); // => true
+ * isSynonymTermType("SCDF"); // => false
+ * ```
+ */
+declare function isSynonymTermType(tty: TermType): boolean;
 
 /**
  * Public entry point for **`@cosyte/terminology`** — a zero-dependency, developer-focused
@@ -3377,28 +3499,30 @@ declare function asTermType(tty: string): TermType | undefined;
  *
  * 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.
+ * over **consumer-supplied** FHIR resources. It ships the *engine* and **no code-system release**
+ * (SNOMED CT / CPT / LOINC / UMLS / RxNorm are strictly BYO). It is not content-free: see
+ * **What is bundled** at the end of this note, which includes the UCUM unit table, the code-system
+ * *identities* (OID ↔ URI), the SNOMED CT concepts the crosswalk resolver names and RxNorm's
+ * relationship and term-type names, each with its copyright.
  *
- * **Phase 1** ships exactly the surface `@cosyte/transform` pins:
+ * **Code-system identity and ConceptMap translation:**
  *
  * - {@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:
+ * **The CodeSystem load layer**, with 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.
+ *   `CodeSystem` JSON) into an immutable model. Ships the loader; **no code-system release**.
  * - {@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`:
+ * **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.
@@ -3408,8 +3532,8 @@ declare function asTermType(tty: string): TermType | undefined;
  * - {@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):
+ * **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.
@@ -3418,25 +3542,25 @@ declare function asTermType(tty: string): TermType | undefined;
  * - {@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):
+ * **The crosswalk resolvers** — the never-fabricate/never-invert invariant applied to the
+ * published, directional reference maps:
  *
  * - {@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 /
+ *   (BYO — **no SNOMED CT refset 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):
+ * **The RxNorm drug relationship graph** — ingredient / brand / clinical-drug / dose-form
+ * navigation over a **caller-supplied** RxNorm RRF release:
  *
  * - {@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).
+ *   (NDC attributes) into an immutable graph. Ships **no** RxNorm release — BYO.
  * - {@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}.
@@ -3445,15 +3569,51 @@ declare function asTermType(tty: string): TermType | undefined;
  * - {@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).
+ * **What is bundled.** No code-system release is. What is bundled includes the following, named with
+ * its copyright:
+ *
+ * - the **UCUM unit table** (`ucum-essence.xml`, version 2.2, revision-date 2024-06-17) — copyright
+ *   ©1999–2024 Regenstrief Institute, Inc., all rights reserved, reproduced **verbatim** under the
+ *   UCUM Copyright Notice and License (https://ucum.org/license), embedded byte-for-byte in the
+ *   published build and parsed at runtime; no modified or derivative copy is distributed. The UCUM
+ *   Specification is provided "as is" **without warranty of any kind** — see the License for the
+ *   full disclaimer. The complete notice ships with this package at `vendor/ucum/NOTICE.md`.
+ * - the **code-system identity facts** ({@link SYSTEM_IDENTITIES}) — OID ↔ canonical-URI pairings,
+ *   which identify the systems rather than listing any system's codes.
+ * - the **SNOMED CT concepts the crosswalk resolver names**, each with its description: the four
+ *   map-category concepts ({@link MAP_CATEGORIES}) a complex-map row's `mapCategoryId` refers to, and
+ *   the two gender findings (`248152002` Female, `248153007` Male) a gender `IFA` rule is written
+ *   against. Further SNOMED CT identifiers, and ICD-10-CM codes, appear in the API documentation
+ *   examples, which are distributed in the compiled declaration files and in the build's
+ *   sourcemaps. SNOMED CT is copyright © International Health Terminology Standards
+ *   Development Organisation.
+ * - the **RxNorm relationship and term-type names** the drug-graph API is written against: the
+ *   relationship names in {@link RELA} / {@link RELA_INVERSE} (`has_ingredient`, `tradename_of`, …),
+ *   and the term-type codes in {@link TERM_TYPES}, each with its name as published by the U.S.
+ *   National Library of Medicine (`SCD` reads "Semantic Clinical Drug"). Individual RxNorm
+ *   identifiers also appear in the API documentation examples, with their RxNorm names and term
+ *   types (for instance `RXCUI` `316151`, "lisinopril 10 MG"), and in `README.md` as well as the
+ *   places named above. RxNorm is produced by the National Library of Medicine; no RxNorm release
+ *   is bundled.
+ *
+ * The `LICENSE` file that ships with this package carries the MIT text for the package's own code
+ * and a third-party notices section naming each of the above.
+ *
+ * The content packs that would change this (the CMS GEM files, the RxNorm Current Prescribable
+ * subset) are not bundled; a caller supplies them, as they do a SNOMED CT, CPT, LOINC, UMLS or VSAC
+ * release, under whatever terms its steward sets. This states what is distributed and under whose
+ * copyright; it is not legal advice, and makes no claim about whether a particular use is permitted
+ * to you.
  *
  * @packageDocumentation
  */
 /**
- * Library version string, synced with `package.json#version` at release time.
+ * Library version string, kept in lockstep with `package.json#version`.
+ *
+ * Changesets owns the bump and rewrites `package.json` only, so the release `version` script runs
+ * `scripts/sync-version.mjs` to rewrite this declaration in the same commit, and
+ * `test/sanity.test.ts` compares the two so a skipped sync goes red instead of shipping a version
+ * string that lies. That is not hypothetical: `0.0.1` went to the registry exporting `"0.0.0"`.
  *
  * @example
  * ```ts
@@ -3461,6 +3621,6 @@ declare function asTermType(tty: string): TermType | undefined;
  * typeof VERSION; // => "string"
  * ```
  */
-declare const VERSION = "0.0.0";
+declare const VERSION: string;
 
-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 };
+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, isSynonymTermType, 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 };