@cosyte/terminology 0.1.5 → 0.1.7

package/dist/index.d.cts

@@ -13,7 +13,7 @@
  * 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
+ * `http://loinc.org`), not a mnemonic or OID: use {@link 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.
  *
@@ -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
- * {@link ../conceptmap/translate.translate} operates on a single {@link Coding}.
+ * {@link translate} operates on a single {@link Coding}.
  *
  * @example
  * ```ts
@@ -385,7 +385,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. Thrown by {@link ../crosswalk/gems.invertGem} so the
+     * inverse of the backward map. Thrown by {@link 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";
@@ -558,8 +558,11 @@ interface SystemIdentity {
     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).
+ * The seed identity table. Order is irrelevant; {@link resolveSystem} builds its lookup indexes from
+ * it. Each entry is one system whose URI and OID were grounded firsthand against the FHIR R4
+ * terminology-systems registry (and its ICD page). Its mnemonics are its HL7 Table 0396 mnemonic
+ * and, for some systems, other accepted short aliases (such as `LOINC` or `CPT`) that are not
+ * Table 0396 codes.
  */
 declare const SYSTEM_IDENTITIES: readonly SystemIdentity[];
 /**
@@ -602,10 +605,12 @@ 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.
+ * Accepts, in order of attempt: a canonical URI (case-insensitive), a mnemonic listed in
+ * {@link SYSTEM_IDENTITIES} (an HL7 v2 Table 0396 mnemonic or another accepted alias,
+ * case-insensitive), a bare or `urn:oid:`-prefixed OID, and an HL7 v2 table's OID or
+ * `terminology.hl7.org` URI (resolved structurally from the table number). The `v2-XXXX` mnemonic a
+ * v2 table identity carries is not accepted as input on its own. 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 }`.
@@ -1274,9 +1279,9 @@ type CodeSystemSource = RrfSource | CsvSource | FixedWidthSource | FhirCodeSyste
  * - `"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`.
+ * partial concept). **Conservative on structure:** an unusable *source* (wrong FHIR `resourceType`, a
+ * CSV whose configured columns are absent from the header, or an RRF or fixed-width property entry
+ * that is not an object) throws a typed `TerminologyError` carrying `TERM_CODESYSTEM_MALFORMED`.
  *
  * @param source - The release descriptor (a discriminated {@link CodeSystemSource}).
  * @returns The immutable, deep-frozen {@link CodeSystem}.
@@ -1372,6 +1377,10 @@ declare function validateCode(cs: CodeSystem, code: string): ValidateCodeResult;
  * concept, never a crash. RRF reserves `|` as the delimiter (fields never contain a literal pipe), so
  * a plain split is exact.
  *
+ * **Conservative on structure:** a `columns.properties` entry that is not an object (a hole in a
+ * sparse list, an explicit `undefined`, a `null`) names no column, so it is a typed
+ * `TERM_CODESYSTEM_MALFORMED` fatal, raised before any row is read.
+ *
  * @packageDocumentation
  */
 
@@ -1397,6 +1406,8 @@ declare function parseRrfLine(line: string): readonly string[];
  *
  * @param source - The RRF source.
  * @returns The parsed concepts (by code) and the load warnings.
+ * @throws {TerminologyError} `TERM_CODESYSTEM_MALFORMED` when a `columns.properties` entry is not an
+ *   object (a hole, `undefined`, or `null`). The message is fixed and names no configured value.
  * @example
  * ```ts
  * import { parseRrf } from "@cosyte/terminology";
@@ -1432,8 +1443,8 @@ declare function parseRrf(source: RrfSource): {
  */
 
 /**
- * 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.
+ * Parse RFC-4180 CSV content into rows of fields. 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).
@@ -1483,6 +1494,10 @@ declare function parseCsvSource(source: CsvSource): {
  * **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.
  *
+ * **Conservative on structure:** a `fields.properties` entry that is not an object (a hole in a
+ * sparse list, an explicit `undefined`, a `null`) names no slice, so it is a typed
+ * `TERM_CODESYSTEM_MALFORMED` fatal, raised before any line is read.
+ *
  * @packageDocumentation
  */
 
@@ -1519,6 +1534,8 @@ declare const ICD10CM_ORDER_FILE_FIELDS: FixedWidthFieldMap;
  *
  * @param source - The fixed-width source.
  * @returns The parsed concepts (by code) and the load warnings.
+ * @throws {TerminologyError} `TERM_CODESYSTEM_MALFORMED` when a `fields.properties` entry is not an
+ *   object (a hole, `undefined`, or `null`). The message is fixed and names no configured value.
  * @example
  * ```ts
  * import { parseFixedWidth } from "@cosyte/terminology";
@@ -2506,7 +2523,7 @@ declare function loadUcumEssence(): UcumEssence;
  * - 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);
- * - a directional map is **never inverted** (see {@link ../crosswalk/gems.invertGem}).
+ * - a directional map is **never inverted** (see {@link invertGem}).
  *
  * @packageDocumentation
  */
@@ -2718,8 +2735,8 @@ interface PatientContext {
     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
+ * One map group's resolution: a discriminated outcome. A group resolves to a target, a No-Map, or a
+ * context-required stall carrying the group's candidate rules; it is **never** a silently-picked
  * single target when the steward flagged otherwise.
  */
 type ComplexMapGroupResult = ComplexMapGroupResolved | ComplexMapGroupNoMap | ComplexMapContextRequired;
@@ -2755,8 +2772,9 @@ interface ComplexMapGroupNoMap {
     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 +
+ * A group whose winning path is a **context-dependent** `IFA` rule for which the caller supplied
+ * **no** matching context (or an `IFA` rule the resolver cannot interpret, or a group in which no rule
+ * held). The engine surfaces the rules +
  * advice and refuses to pick a branch: the never-fabricate rule for runtime context.
  */
 interface ComplexMapContextRequired {
@@ -2809,10 +2827,10 @@ interface CrosswalkUnmapped {
     /** The source code, echoed. */
     readonly source: string;
 }
-/** The result of {@link ../crosswalk/gems.applyGem}: a match, an authored No-Map, or an absence. */
+/** The result of {@link 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
+ * The result of {@link applyComplexMap}: a per-group match, or a typed
  * absence when the source concept is not in the map.
  */
 type ComplexMapApplyResult = ComplexMapMatched | CrosswalkUnmapped;
@@ -3058,7 +3076,7 @@ declare const MAP_CATEGORIES: {
     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). */
+    /** `447640006`: "Source concept is ambiguous" (carried through on the result; the rule decides). */
     readonly AMBIGUOUS: "447640006";
 };
 /** A value from {@link MAP_CATEGORIES}: the SNOMED map-category id carried on a resolution. */
@@ -3070,8 +3088,8 @@ type MapCategoryId = (typeof MAP_CATEGORIES)[keyof typeof MAP_CATEGORIES];
 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.
+ * identity fact (mirrors {@link SYSTEM_IDENTITIES}); attached to a resolved
+ * target {@link Coding} so a translation is self-describing.
  */
 declare const ICD10CM_SYSTEM = "http://hl7.org/fhir/sid/icd-10-cm";
 /**
@@ -3096,7 +3114,7 @@ declare const SNOMEDCT_SYSTEM = "http://snomed.info/sct";
  * `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}).
+ * (see {@link ingredientsOf}).
  *
  * **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
@@ -3125,7 +3143,7 @@ declare const SNOMEDCT_SYSTEM = "http://snomed.info/sct";
  * `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}.
+ * {@link isSynonymTermType}.
  */
 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";
 /**
@@ -3180,9 +3198,9 @@ interface NdcResolution {
 /**
  * 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.
+ * release**; `obsolete` / `alien` come from the RxNav NDC-history data (a differential source, not
+ * the base RRF concept files), which {@link loadRxNormGraph} does not read, so every resolution it
+ * returns today is `active`. The engine **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. */
@@ -3194,7 +3212,7 @@ interface NdcUnmapped {
     /** The NDC (as supplied), echoed. */
     readonly ndc: string;
 }
-/** The result of {@link ../rxnorm/navigate.resolveNdc}: a resolution or a typed absence. */
+/** The result of {@link 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
@@ -3250,7 +3268,7 @@ interface RxNormLoadWarning {
     /**
      * 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.
+     * package-wide {@link DIAGNOSTIC_CODES} registry, which documents each.
      */
     readonly code: "TERM_RXNORM_MALFORMED_ROW" | "TERM_RXNORM_UNTYPED_CONCEPT";
     /** Which source file the fault was in. */
@@ -3276,7 +3294,7 @@ interface RxNormLoadWarning {
 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). Each frozen. */
+    /** Concepts keyed by `RXCUI`, each typed by its first **defining** `SAB=RXNORM` atom. Each frozen. */
     readonly concepts: ReadonlyMap<string, RxNormConcept>;
     /** Directed edges indexed by `subject` `RXCUI`, each list in file order. Each list frozen. */
     readonly edges: ReadonlyMap<string, readonly RxNormEdge[]>;
@@ -3629,7 +3647,7 @@ declare function approximateMatch(graph: RxNormGraph, query: string, options?: A
  * 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}
+ * So an `RXNREL.RRF` row is read **`RXCUI2 ⟶RELA⟶ RXCUI1`**, and {@link loadRxNormGraph}
  * normalizes every row to `subject = RXCUI2`, `predicate = RELA`, `object = RXCUI1`. Concretely, a
  * `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
@@ -3645,7 +3663,7 @@ declare function approximateMatch(graph: RxNormGraph, query: string, options?: A
  * 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}.
+ * {@link ingredientsOf}.
  *
  * @packageDocumentation
  */
@@ -3714,7 +3732,7 @@ 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.
+ * the navigation functions follow whichever authored predicate points the way they want to go.
  *
  * @example
  * ```ts
@@ -3744,7 +3762,7 @@ declare const RXNORM_SYSTEM = "http://www.nlm.nih.gov/research/umls/rxnorm";
  * 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}.
+ * {@link isSynonymTermType} and {@link loadRxNormGraph}.
  *
  * @packageDocumentation
  */
@@ -3753,7 +3771,7 @@ declare const RXNORM_SYSTEM = "http://www.nlm.nih.gov/research/umls/rxnorm";
  * 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.
+ * {@link 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}).
@@ -3788,7 +3806,7 @@ declare function asTermType(tty: string): TermType | undefined;
  *
  * 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
+ * type, and {@link 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}.

package/dist/index.d.ts

@@ -13,7 +13,7 @@
  * 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
+ * `http://loinc.org`), not a mnemonic or OID: use {@link 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.
  *
@@ -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
- * {@link ../conceptmap/translate.translate} operates on a single {@link Coding}.
+ * {@link translate} operates on a single {@link Coding}.
  *
  * @example
  * ```ts
@@ -385,7 +385,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. Thrown by {@link ../crosswalk/gems.invertGem} so the
+     * inverse of the backward map. Thrown by {@link 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";
@@ -558,8 +558,11 @@ interface SystemIdentity {
     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).
+ * The seed identity table. Order is irrelevant; {@link resolveSystem} builds its lookup indexes from
+ * it. Each entry is one system whose URI and OID were grounded firsthand against the FHIR R4
+ * terminology-systems registry (and its ICD page). Its mnemonics are its HL7 Table 0396 mnemonic
+ * and, for some systems, other accepted short aliases (such as `LOINC` or `CPT`) that are not
+ * Table 0396 codes.
  */
 declare const SYSTEM_IDENTITIES: readonly SystemIdentity[];
 /**
@@ -602,10 +605,12 @@ 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.
+ * Accepts, in order of attempt: a canonical URI (case-insensitive), a mnemonic listed in
+ * {@link SYSTEM_IDENTITIES} (an HL7 v2 Table 0396 mnemonic or another accepted alias,
+ * case-insensitive), a bare or `urn:oid:`-prefixed OID, and an HL7 v2 table's OID or
+ * `terminology.hl7.org` URI (resolved structurally from the table number). The `v2-XXXX` mnemonic a
+ * v2 table identity carries is not accepted as input on its own. 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 }`.
@@ -1274,9 +1279,9 @@ type CodeSystemSource = RrfSource | CsvSource | FixedWidthSource | FhirCodeSyste
  * - `"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`.
+ * partial concept). **Conservative on structure:** an unusable *source* (wrong FHIR `resourceType`, a
+ * CSV whose configured columns are absent from the header, or an RRF or fixed-width property entry
+ * that is not an object) throws a typed `TerminologyError` carrying `TERM_CODESYSTEM_MALFORMED`.
  *
  * @param source - The release descriptor (a discriminated {@link CodeSystemSource}).
  * @returns The immutable, deep-frozen {@link CodeSystem}.
@@ -1372,6 +1377,10 @@ declare function validateCode(cs: CodeSystem, code: string): ValidateCodeResult;
  * concept, never a crash. RRF reserves `|` as the delimiter (fields never contain a literal pipe), so
  * a plain split is exact.
  *
+ * **Conservative on structure:** a `columns.properties` entry that is not an object (a hole in a
+ * sparse list, an explicit `undefined`, a `null`) names no column, so it is a typed
+ * `TERM_CODESYSTEM_MALFORMED` fatal, raised before any row is read.
+ *
  * @packageDocumentation
  */
 
@@ -1397,6 +1406,8 @@ declare function parseRrfLine(line: string): readonly string[];
  *
  * @param source - The RRF source.
  * @returns The parsed concepts (by code) and the load warnings.
+ * @throws {TerminologyError} `TERM_CODESYSTEM_MALFORMED` when a `columns.properties` entry is not an
+ *   object (a hole, `undefined`, or `null`). The message is fixed and names no configured value.
  * @example
  * ```ts
  * import { parseRrf } from "@cosyte/terminology";
@@ -1432,8 +1443,8 @@ declare function parseRrf(source: RrfSource): {
  */
 
 /**
- * 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.
+ * Parse RFC-4180 CSV content into rows of fields. 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).
@@ -1483,6 +1494,10 @@ declare function parseCsvSource(source: CsvSource): {
  * **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.
  *
+ * **Conservative on structure:** a `fields.properties` entry that is not an object (a hole in a
+ * sparse list, an explicit `undefined`, a `null`) names no slice, so it is a typed
+ * `TERM_CODESYSTEM_MALFORMED` fatal, raised before any line is read.
+ *
  * @packageDocumentation
  */
 
@@ -1519,6 +1534,8 @@ declare const ICD10CM_ORDER_FILE_FIELDS: FixedWidthFieldMap;
  *
  * @param source - The fixed-width source.
  * @returns The parsed concepts (by code) and the load warnings.
+ * @throws {TerminologyError} `TERM_CODESYSTEM_MALFORMED` when a `fields.properties` entry is not an
+ *   object (a hole, `undefined`, or `null`). The message is fixed and names no configured value.
  * @example
  * ```ts
  * import { parseFixedWidth } from "@cosyte/terminology";
@@ -2506,7 +2523,7 @@ declare function loadUcumEssence(): UcumEssence;
  * - 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);
- * - a directional map is **never inverted** (see {@link ../crosswalk/gems.invertGem}).
+ * - a directional map is **never inverted** (see {@link invertGem}).
  *
  * @packageDocumentation
  */
@@ -2718,8 +2735,8 @@ interface PatientContext {
     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
+ * One map group's resolution: a discriminated outcome. A group resolves to a target, a No-Map, or a
+ * context-required stall carrying the group's candidate rules; it is **never** a silently-picked
  * single target when the steward flagged otherwise.
  */
 type ComplexMapGroupResult = ComplexMapGroupResolved | ComplexMapGroupNoMap | ComplexMapContextRequired;
@@ -2755,8 +2772,9 @@ interface ComplexMapGroupNoMap {
     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 +
+ * A group whose winning path is a **context-dependent** `IFA` rule for which the caller supplied
+ * **no** matching context (or an `IFA` rule the resolver cannot interpret, or a group in which no rule
+ * held). The engine surfaces the rules +
  * advice and refuses to pick a branch: the never-fabricate rule for runtime context.
  */
 interface ComplexMapContextRequired {
@@ -2809,10 +2827,10 @@ interface CrosswalkUnmapped {
     /** The source code, echoed. */
     readonly source: string;
 }
-/** The result of {@link ../crosswalk/gems.applyGem}: a match, an authored No-Map, or an absence. */
+/** The result of {@link 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
+ * The result of {@link applyComplexMap}: a per-group match, or a typed
  * absence when the source concept is not in the map.
  */
 type ComplexMapApplyResult = ComplexMapMatched | CrosswalkUnmapped;
@@ -3058,7 +3076,7 @@ declare const MAP_CATEGORIES: {
     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). */
+    /** `447640006`: "Source concept is ambiguous" (carried through on the result; the rule decides). */
     readonly AMBIGUOUS: "447640006";
 };
 /** A value from {@link MAP_CATEGORIES}: the SNOMED map-category id carried on a resolution. */
@@ -3070,8 +3088,8 @@ type MapCategoryId = (typeof MAP_CATEGORIES)[keyof typeof MAP_CATEGORIES];
 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.
+ * identity fact (mirrors {@link SYSTEM_IDENTITIES}); attached to a resolved
+ * target {@link Coding} so a translation is self-describing.
  */
 declare const ICD10CM_SYSTEM = "http://hl7.org/fhir/sid/icd-10-cm";
 /**
@@ -3096,7 +3114,7 @@ declare const SNOMEDCT_SYSTEM = "http://snomed.info/sct";
  * `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}).
+ * (see {@link ingredientsOf}).
  *
  * **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
@@ -3125,7 +3143,7 @@ declare const SNOMEDCT_SYSTEM = "http://snomed.info/sct";
  * `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}.
+ * {@link isSynonymTermType}.
  */
 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";
 /**
@@ -3180,9 +3198,9 @@ interface NdcResolution {
 /**
  * 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.
+ * release**; `obsolete` / `alien` come from the RxNav NDC-history data (a differential source, not
+ * the base RRF concept files), which {@link loadRxNormGraph} does not read, so every resolution it
+ * returns today is `active`. The engine **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. */
@@ -3194,7 +3212,7 @@ interface NdcUnmapped {
     /** The NDC (as supplied), echoed. */
     readonly ndc: string;
 }
-/** The result of {@link ../rxnorm/navigate.resolveNdc}: a resolution or a typed absence. */
+/** The result of {@link 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
@@ -3250,7 +3268,7 @@ interface RxNormLoadWarning {
     /**
      * 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.
+     * package-wide {@link DIAGNOSTIC_CODES} registry, which documents each.
      */
     readonly code: "TERM_RXNORM_MALFORMED_ROW" | "TERM_RXNORM_UNTYPED_CONCEPT";
     /** Which source file the fault was in. */
@@ -3276,7 +3294,7 @@ interface RxNormLoadWarning {
 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). Each frozen. */
+    /** Concepts keyed by `RXCUI`, each typed by its first **defining** `SAB=RXNORM` atom. Each frozen. */
     readonly concepts: ReadonlyMap<string, RxNormConcept>;
     /** Directed edges indexed by `subject` `RXCUI`, each list in file order. Each list frozen. */
     readonly edges: ReadonlyMap<string, readonly RxNormEdge[]>;
@@ -3629,7 +3647,7 @@ declare function approximateMatch(graph: RxNormGraph, query: string, options?: A
  * 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}
+ * So an `RXNREL.RRF` row is read **`RXCUI2 ⟶RELA⟶ RXCUI1`**, and {@link loadRxNormGraph}
  * normalizes every row to `subject = RXCUI2`, `predicate = RELA`, `object = RXCUI1`. Concretely, a
  * `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
@@ -3645,7 +3663,7 @@ declare function approximateMatch(graph: RxNormGraph, query: string, options?: A
  * 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}.
+ * {@link ingredientsOf}.
  *
  * @packageDocumentation
  */
@@ -3714,7 +3732,7 @@ 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.
+ * the navigation functions follow whichever authored predicate points the way they want to go.
  *
  * @example
  * ```ts
@@ -3744,7 +3762,7 @@ declare const RXNORM_SYSTEM = "http://www.nlm.nih.gov/research/umls/rxnorm";
  * 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}.
+ * {@link isSynonymTermType} and {@link loadRxNormGraph}.
  *
  * @packageDocumentation
  */
@@ -3753,7 +3771,7 @@ declare const RXNORM_SYSTEM = "http://www.nlm.nih.gov/research/umls/rxnorm";
  * 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.
+ * {@link 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}).
@@ -3788,7 +3806,7 @@ declare function asTermType(tty: string): TermType | undefined;
  *
  * 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
+ * type, and {@link 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}.