@cosyte/terminology 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,249 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+Versions and publishing are managed with [Changesets](https://github.com/changesets/changesets);
+this file is maintained by hand (Changesets handles the version bump and publish only).
+
+## [Unreleased]
+
+The first pre-alpha release (`0.0.1`) will ship the initial public API surface. The package begins
+its public history at `0.0.x`, per the cosyte version ladder (`0.0.x` until first alpha).
+
+### Security
+
+- **Dev-dependency advisory remediation (no runtime impact — `@cosyte/terminology`
+  ships zero runtime dependencies, so the published artifact is unchanged).**
+  Added the shared canonical scoped `pnpm.overrides` block pinning two transitive
+  **dev/build-time** packages to their patched releases: `esbuild`
+  (`>=0.27.3 <0.28.1` → `0.28.1`; GHSA dev-server path-traversal — not reachable
+  here: the library builds via `tsup`/`vitest` and never runs `esbuild serve`) and
+  the `@changesets/parse` copy of `js-yaml` (`>=4.0.0 <4.2.0` → `4.2.0`;
+  GHSA-h67p-54hq-rp68 merge-key DoS). The `js-yaml@3.x` pulled by `read-yaml-file`
+  (via `@manypkg/get-packages` → `@changesets/cli`) is **intentionally left**: it
+  calls `yaml.safeLoad`, removed/throwing in js-yaml 4, so it cannot be
+  force-upgraded without breaking the release tooling, and it only parses trusted
+  local repo YAML at release time. This mirrors `@cosyte/hl7` and is the shared
+  override block enforced suite-wide by the `@cosyte/config` drift check.
+
+### Added
+
+- **Phase 6 — RxNorm drug relationship graph** (`TERMINOLOGY-6`). Ingredient / brand / clinical-drug /
+  dose-form graph navigation over a **caller-supplied** RxNorm RRF release — the never-fabricate
+  invariant applied to the drug graph (roadmap §4.2). Ships the graph **mechanism** over the real RRF
+  wire format; ships **no** RxNorm content.
+  - **`loadRxNormGraph(source)`** — load `RXNCONSO` (concepts, typed by `TTY`: `IN`/`PIN`/`BN`/`SCD`/
+    `SBD`/`SCDC`/`DF`/…), `RXNREL` (directed `RELA` edges), and optionally `RXNSAT` (`ATN=NDC`
+    attributes) into an immutable graph. Reuses the shared zero-dep RRF reader. The **column layouts and
+    the direction convention are grounded firsthand** on the NLM RxNorm Technical Documentation (§ file
+    descriptions; §12.7) and the UMLS Reference Manual: `RELA` is _"the relationship which the second
+    concept (`RXCUI2`) has to the first (`RXCUI1`)"_, so every row is read `RXCUI2 ⟶RELA⟶ RXCUI1` and
+    normalized to `subject = RXCUI2`, `object = RXCUI1` — the documented medication-safety trap
+    (roadmap §10 Q5), **pinned by fixtures** built in the real wire format. Liberal on load: a
+    structurally unusable row is a skipped, surfaced `TERM_RXNORM_MALFORMED_ROW`; rows not of interest
+    (non-`RXNORM` atoms, atom-level relationships, non-`NDC` attributes) are skipped silently.
+  - **`ingredientsOf` / `genericFor` / `brandsFor` / `doseFormsOf` / `consistsOf` / `relatedByRela`** —
+    graph navigation following **authored edges only**. RxNorm ships both directions of an asymmetric
+    relationship as separate rows, so `genericFor` follows the authored `tradename_of` and `brandsFor`
+    the authored `has_tradename` — the engine **never synthesizes an inverse**. An absent `RXCUI` is a
+    typed `TERM_RXNORM_UNKNOWN_RXCUI`; a present concept with no such edge is a found result with an
+    **empty** target set (an honest "no such edge", distinct from "unknown concept").
+  - **`resolveNdc(graph, ndc)`** — NDC → `RXCUI` carrying the temporal status and the **as-of release**
+    (NDC↔RXCUI is many:1 and temporal). An NDC in the loaded release is `active` as of that release;
+    obsolete/alien statuses come from RxNav NDC-history data (a differential/BYO source, not the base
+    RRF), never fabricated. An absent NDC is a typed `TERM_RXNORM_NDC_UNMAPPED`, never a guessed `RXCUI`.
+  - **`approximateMatch(graph, query, options?)`** — the **opt-in, explicitly labeled** similarity path
+    (never the default, never an exact code assertion): every candidate carries `approximate: true` and
+    a derived token-overlap score; a no-match is an empty array, never a nearest guess.
+  - Also exports `getConcept`, the `RELA` / `RELA_INVERSE` / `TERM_TYPES` / `asTermType` /
+    `RXNORM_SYSTEM` identity facts, and the graph types. New stable diagnostic codes:
+    `TERM_RXNORM_MALFORMED_ROW`, `TERM_RXNORM_UNKNOWN_RXCUI`, `TERM_RXNORM_NDC_UNMAPPED`.
+  - **Content posture (honest).** This phase does **not** bundle RxNorm content. RxNorm's Current
+    Prescribable Content is public-domain and _bundleable_ per the licensing matrix, but a genuine
+    verbatim release could not be obtained in the build sandbox (no build-time network for the release
+    archive), and fabricating "real RxNorm content" would breach the never-fabricate / grounding
+    discipline. So Phase 6 ships the **BYO** graph mechanism grounded firsthand on the RxNorm technical
+    documentation, and **actual content-bundling is deferred to the content-packs phase (Phase 7)**.
+    All fixtures are synthetic rows in the real RRF wire format. Zero runtime dependencies.
+
+- **Phase 5 — Crosswalk resolvers: ICD-9↔ICD-10 GEMs + SNOMED CT → ICD-10-CM complex map**
+  (`TERMINOLOGY-5`). The never-fabricate / never-invert invariant applied to the published,
+  **directional** reference maps — the safety crown (roadmap §4.1). Both stewards say these are _not_
+  crosswalks (CMS: _"GEMs are not crosswalks… reference mappings"_; NLM: _"semi-automated"_), so a hit
+  is a **candidate carrying the steward's flags**, never an equivalence and never a fabricated code.
+  - **`loadGems(source)` / `applyGem(map, code)`** — the CMS **public-domain** GEMs, loaded in their
+    authored `direction` (`"9-to-10"` / `"10-to-9"`) and applied only that way. Decodes the 5-position
+    flag field (**approximate | no-map | combination | scenario | choice-list**, grounded firsthand on
+    the CMS Dx GEM User's Guide / Technical Documentation) and carries it through verbatim. A **1:many**
+    source returns the **full** candidate set (never collapsed to one); a **combination** source
+    surfaces its scenario→choice-list structure so a caller can build valid clusters (one target per
+    choice list); a **`NoDx`** No-Map source is the typed `TERM_CROSSWALK_NO_MAP`; a source **absent**
+    from the file is the distinct `TERM_CROSSWALK_UNMAPPED`. Liberal on load (a malformed line is a
+    skipped, surfaced `TERM_GEM_MALFORMED_ROW`, never partial).
+  - **`loadComplexMap(input)` / `applyComplexMap(map, source, context)`** — the NLM SNOMED CT →
+    ICD-10-CM complex map, **BYO** (SNOMED is licensed — **zero** SNOMED content is bundled; the engine
+    ships only the rule machinery, roadmap §5). Accepts structured rows or a raw RF2 extended-map
+    refset. A source's **map groups are an AND** (a manifestation code _and_ an etiology code → two
+    groups, one resolution each); within a group, **priorities are an if-then-else** chain of `IFA`
+    rules evaluated against caller-supplied `PatientContext` (age band, gender). A group whose decision
+    needs context the caller did **not** supply is the typed `TERM_CROSSWALK_CONTEXT_REQUIRED` — the
+    candidate rules + Map Advice ride through, and the engine **refuses to pick a branch** it lacks the
+    data for. Map Categories (`447638001` cannot-classify → No-Map, `447639009` context-dependent,
+    `447640006` ambiguous) and Map Advice are carried verbatim.
+  - **`invertGem(map)`** — the never-invert refusal made a first-class, thrown contract: the forward
+    (9→10) and backward (10→9) GEM files are **separate, non-inverse** artifacts, so an inversion
+    request always throws `TERM_MAP_NOT_INVERTIBLE` rather than fabricate a transpose.
+  - **New stable codes** (additions-only): diagnostics `TERM_CROSSWALK_NO_MAP`,
+    `TERM_CROSSWALK_UNMAPPED`, `TERM_CROSSWALK_CONTEXT_REQUIRED`, `TERM_GEM_MALFORMED_ROW`,
+    `TERM_COMPLEX_MAP_MALFORMED_ROW`; fatals `TERM_CROSSWALK_MALFORMED`, `TERM_MAP_NOT_INVERTIBLE`.
+  - **No map content bundled.** The GEMs are CMS public-domain, so a caller may supply the file today
+    (BYO); bundling a public-domain GEM pack is deferred to the content-packs phase. SNOMED/CPT/UMLS
+    stay BYO permanently (a licensing wall — roadmap §5). Property + unit tests lock the
+    never-fabricate / never-invert / No-Map / context-required invariants. Zero runtime dependencies.
+- **Phase 4 — UCUM: grammar parser + `validateUcum` + `ucumEqual`** (`TERMINOLOGY-4`). Unit
+  recognition, validation, and **representation canonicalization only** — **no** magnitude conversion
+  (`mg/dL` → `mmol/L` needs an analyte's molar mass, a clinical computation the engine refuses;
+  roadmap §2/§4.3). Engine only; the UCUM table is **vendored verbatim**, never a derivative.
+  - **`validateUcum(unit)`** — a hand-rolled, zero-dep UCUM grammar parser (base units, metric
+    prefixes attached with no delimiter and resolved by **longest-match**, `.` multiply / `/` divide,
+    signed integer exponents, `{…}` inert annotations, the `10*` / `10^` powers-of-ten, **case
+    sensitive**) over the known atom table. Returns `{ valid: true, canonical }` for a well-formed
+    unit, or the typed `{ valid: false, code: "TERM_UCUM_INVALID", reason }` — an unparseable or
+    unknown unit is **never** a guessed "nearest" unit (the never-fabricate invariant, applied to
+    units; roadmap §4.3). Total and fail-safe: any string in, a typed result out, never a throw.
+  - **`ucumEqual(a, b)`** — reduces both expressions to base dimensions and reports whether they
+    denote the **same unit** (`N` ≡ `kg.m/s2`, `Pa` ≡ `N/m2`, `mmol/L` ≡ `mmol.L-1`, annotations
+    inert). This is **not** magnitude conversion — `mg` ≠ `g`, `km` ≠ `m`. A **special** (non-linear)
+    unit (`Cel`, `[pH]`, `B`) is never equated with a linear one, and distinct **arbitrary** units
+    (`[IU]` vs `[iU]`) never compare equal (the never-fabricate posture: no unproven equivalence).
+  - **`parseUcum` / `reduce` / `loadUcumEssence`** — the underlying AST parser, dimensional reducer,
+    and the in-memory model of the vendored UCUM table, exported for advanced use.
+  - **Vendored, verbatim UCUM data.** `vendor/ucum/ucum-essence.xml` (official v2.2) is checked in
+    byte-for-byte and embedded verbatim as a string (`src/ucum/essence-data.generated.ts`, via
+    `pnpm gen:ucum`); the engine parses it at runtime into a lookup table (a permitted UCUM use, not a
+    modification/derivative — see `vendor/ucum/NOTICE.md`; UCUM © Regenstrief Institute). No file is
+    read at runtime; a drift test proves the embedded copy is byte-identical to the vendored source.
+  - **Conformance gate.** The official `UcumFunctionalTests.xml` suite (EPL) is vendored and run: all
+    **530 validation cases** pass, and the **31 conversion pairs** are verified commensurable
+    (same reduced dimension). Magnitude-conversion sub-tests are a documented non-goal.
+  - **Scope, flagged.** Case-**sensitive** (c/s) mode only — the normative FHIR/HL7 interchange mode;
+    the case-insensitive (c/i) variant is **not** implemented (a c/i-only string is a typed
+    `TERM_UCUM_INVALID`, never silently reinterpreted). Deeply-nested/pathological input degrades to a
+    typed invalid (nesting is capped), never a crash. No magnitude conversion (documented non-goal).
+  - New value-free stable diagnostic code: **`TERM_UCUM_INVALID`**. Zero runtime dependencies.
+
+- **Phase 3 — ValueSet binding: `compose` / `$expand` / `$validate-code` against a value set**
+  (`TERMINOLOGY-3`). Loads a **consumer-supplied** FHIR `ValueSet` and answers the FHIR R4 ValueSet
+  terminology operations over the CodeSystem loaders — engine only, **zero bundled content** (VSAC
+  value sets and their embedded SNOMED/CPT/RxNorm/LOINC remain BYO by license).
+  - **`loadValueSet(json)`** — validates an untrusted FHIR R4 `ValueSet` into an immutable model
+    (intensional `compose` of `include`/`exclude` over `system`/`concept`/`filter`/`valueSet`, and/or
+    a **pre-computed** `expansion` whose `total`/`valueset-toocostly` extension derive a `truncated`
+    flag). Conservative on load: a structurally unusable resource is the typed fatal
+    `TERM_VALUESET_MALFORMED`; an unimplemented `filter` operator is **not** fatal (it surfaces at
+    expansion time).
+  - **`expand(vs, ctx)`** — FHIR `$expand`: the union of `include` minus `exclude`, over the
+    **consumer-supplied** `CodeSystem`s (and referenced `ValueSet`s) in the `ExpansionContext`.
+    Supports explicit `concept` lists, whole-`system` includes, referenced value sets (intersection,
+    cycle-safe), and `filter`s — `is-a` / `descendent-of` / `is-not-a` subsumption over the release's
+    hierarchy plus `=` / `in` / `not-in` / `exists` property predicates. Returns an honest `complete`
+    flag: a part it could not compute (missing code system, unresolved value set, unimplemented op) is
+    a typed `TERM_VALUESET_CANNOT_EXPAND` and the `contains` set is an explicit **lower bound**, never
+    a silently-empty or fabricated membership.
+  - **`validateCodeInValueSet(coding, vs, ctx)`** — FHIR ValueSet `$validate-code` (binding): a
+    **decided** `result: true`/`false` only when membership is proven (found in a computable include
+    and not removed by any computable exclude / absent from a fully-evaluated value set), otherwise a
+    typed `undetermined` (`TERM_VALUESET_CANNOT_EXPAND`). A **truncated** pre-computed expansion never
+    reads as complete membership — a code absent from it is `undetermined`, never a fabricated "not a
+    member" (roadmap §4.4: a false negative on a binding is a clinical error).
+  - **Subsumption from the release's own hierarchy** — the FHIR `CodeSystem` loader now synthesizes a
+    standard `parent` concept-property from a **nested `concept`** hierarchy (default `is-a`
+    meaning), so `is-a`/`descendent-of` work over nested and explicit-`parent` code systems alike;
+    `buildSubsumption` / `isA` are exposed. Cycle-safe.
+  - **The never-fabricate invariant extends to value-set binding** — locked by property-based tests
+    (every expanded code is one the value set selects; excludes are honored; membership is
+    order-independent; a decided membership agrees with the full expansion; a truncated expansion is
+    never read as complete). Grounded firsthand on the FHIR R4 Terminology Module
+    (`valueset`, `valueset-operation-expand`, `valueset-operation-validate-code`, `valueset-filter-operator`).
+  - New value-free stable codes: `TERM_VALUESET_CANNOT_EXPAND`, `TERM_VALUESET_EXPANSION_TRUNCATED`
+    (diagnostics) and `TERM_VALUESET_MALFORMED` (fatal).
+  - **Zero runtime dependencies** retained.
+
+- **Phase 2 — the CodeSystem load layer + FHIR `$lookup` / `$validate-code`** (`TERMINOLOGY-2`).
+  Loads a **consumer-supplied** code-system release into an immutable, queryable model and answers the
+  two FHIR R4 CodeSystem identity operations. Ships the engine only — **zero bundled copyrighted
+  content** (RxNorm/LOINC/ICD-10-CM/SNOMED/CPT releases are BYO).
+  - **`loadCodeSystem(source)`** — one entry point over four hand-rolled, zero-dep readers, dispatched
+    on `source.format`: **RRF** (pipe-delimited, single trailing pipe; one parameterized reader for
+    RxNorm `RXNCONSO` and UMLS `MRCONSO`), **RFC-4180 CSV** (real quote handling — LOINC `Loinc.csv`),
+    **fixed-width** (slice-by-column order files; `ICD10CM_ORDER_FILE_FIELDS` preset with the
+    position-15 header/billable flag), and native **FHIR R4 `CodeSystem` JSON** (nested-concept
+    flattening, standard `inactive`/`deprecated`/`status` properties). Liberal on load: a malformed
+    row is skipped and surfaced in `warnings` (`TERM_RRF_MALFORMED_ROW` / `TERM_CSV_MALFORMED` /
+    `TERM_FIXED_WIDTH_MALFORMED` / `TERM_FHIR_CONCEPT_MALFORMED`); a structurally unusable _source_ is
+    the typed fatal `TERM_CODESYSTEM_MALFORMED`.
+  - **`lookup(cs, code)`** — FHIR `$lookup`: code → display + definition + properties, carrying a
+    `ConceptStatus` (deprecated / header-not-billable / obsolete / suppressed, with `active` and, for
+    ICD-10-CM, `billable`). An unknown code is a typed `{ found: false }` — never a fabricated display.
+  - **`validateCode(cs, code)`** — FHIR `$validate-code`: `valid: true` for a present code **carrying
+    its status** (a deprecated or header code validates as present but is flagged, never presented
+    clean); an absent code is `valid: false` with `TERM_CODE_UNKNOWN` — never a guessed `true`.
+  - **The never-fabricate invariant extends to code identity** — locked by property-based +
+    fuzz tests (the RRF/CSV/fixed-width readers never crash on hostile input; a lookup display always
+    comes verbatim from the loaded release). Grounded firsthand on FHIR R4
+    (`codesystem-operation-lookup`/`-validate-code`, concept-properties).
+  - New value-free stable codes: `TERM_CODE_UNKNOWN`, `TERM_CONCEPT_DEPRECATED`,
+    `TERM_CONCEPT_HEADER_NOT_BILLABLE`, `TERM_RRF_MALFORMED_ROW`, `TERM_CSV_MALFORMED`,
+    `TERM_FIXED_WIDTH_MALFORMED`, `TERM_FHIR_CONCEPT_MALFORMED` (diagnostics) and
+    `TERM_CODESYSTEM_MALFORMED` (fatal). New JSON helpers `getBoolean` / `getNumber`.
+  - **Zero runtime dependencies** retained.
+
+- **Phase 1 — the ConceptMap `$translate` engine + code-system identity/canonical-URI resolver**
+  (`TERMINOLOGY-1`). This replaces the parser-shaped scaffold stubs: `@cosyte/terminology` is a
+  **terminology engine** modeled on the FHIR Terminology Module, not a wire parser.
+  - **Code-system identity resolver** — `resolveSystem(id)` maps a canonical URI, OID (bare or
+    `urn:oid:`), or HL7 v2 mnemonic to a single `SystemIdentity` (canonical URI + OID + mnemonics), or
+    a typed `{ unknown }` — never a guessed URI. Seeded with identities grounded **firsthand** against
+    the FHIR R4 terminology-systems registry and HL7 Table 0396: LOINC, SNOMED CT, ICD-10-CM, RxNorm,
+    UCUM, CPT, NDC, CVX, and the HL7 v2 table family (`v2-XXXX` URI ↔ `…12.[table]` OID, resolved
+    structurally). Exposed as `SYSTEM_IDENTITIES`, `HL7_V2_OID_ROOT`, `HL7_V2_URL_PREFIX`.
+  - **ConceptMap `$translate` engine** — `loadConceptMap(json)` validates an untrusted FHIR R4
+    `ConceptMap` into an immutable model (malformed → typed fatal `TERM_CONCEPTMAP_MALFORMED`);
+    `translate(coding, map)` returns the declared target(s) with their FHIR relationship (an internal
+    R5-vocabulary `Relationship` plus the verbatim R4 `equivalence`), steward comments, and the map's
+    provenance — or a typed `unmapped` result carrying any `group.unmapped` fallback mode.
+  - **The never-fabricate / never-invert invariants** (the safety crown for every later phase): an
+    unmapped source is surfaced, never a guessed target; a directional map is read source→target only
+    and never inverted. Locked by property-based tests.
+  - **Value types + diagnostics**: immutable `coding()` / `codeableConcept()`; untrusted-JSON
+    navigation helpers (`isJsonObject`/`getString`/`getArray`); the stable, value-free
+    `DIAGNOSTIC_CODES` (`TERM_TRANSLATE_UNMAPPED`, `TERM_SYSTEM_UNRECOGNIZED`) + `FATAL_CODES`
+    (`TERM_CONCEPTMAP_MALFORMED`) registries and the typed `TerminologyError`.
+  - **Zero runtime dependencies** retained; **zero bundled copyrighted terminology content**
+    (SNOMED/CPT/full-LOINC/UMLS/VSAC are BYO by license).
+
+### Changed
+
+- **Docs: README scope corrected to the complete engine.** The status/scope block led with "Ships
+  **Phase 1**" and read as a phase-by-phase build ladder, understating the shipped surface. Rewritten to
+  state plainly that the **engine is complete** (identity resolver + `$translate`, CodeSystem load +
+  `$lookup`/`$validate-code`, ValueSet `compose`/`$expand`/binding, UCUM, the GEMs + SNOMED→ICD-10-CM
+  crosswalks, and the RxNorm drug graph) while keeping the two accurate caveats intact: **pre-alpha
+  `0.0.x`, not yet published to npm**, and **no code-system content is bundled** (BYO data; the
+  public-domain content packs are still to come). Added a "not on npm yet" note beside the `npm install`
+  line so the aspirational command is not mistaken for a live one. Docs-only — no API, version, or
+  runtime change.
+
+### Removed
+
+- The parser-shaped scaffold stubs (`parseTerminology`, `ParsedTerminology`, the placeholder
+  `WARNING_CODES` entry, and the parse-oriented option/warning types). This package is an engine, not
+  a parser; that placeholder surface never shipped.
+
+### Fixed
+
+### Security
+
+[Unreleased]: https://github.com/cosyte/terminology/commits/main

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cosyte
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,168 @@
+# @cosyte/terminology
+
+> A **zero-dependency terminology engine** for US healthcare code systems — FHIR-shaped, BYO-data,
+> and it **never fabricates a code**.
+
+`@cosyte/terminology` is **not a wire parser**. It mirrors the FHIR **Terminology Module**
+(`$translate`, `$lookup`, `$validate-code`, `$expand`, …), operating over **consumer-supplied** FHIR
+resources. It is the sibling engine `@cosyte/transform` and, later, the parsers' code-system
+recognition consume. It ships the **engine, never copyrighted terminology content** — SNOMED CT, CPT,
+full LOINC/UMLS, and VSAC value sets are strictly bring-your-own; code-system _identities_ (OID ↔
+canonical URI) are published facts, grounded firsthand and encoded.
+
+> **Status:** pre-alpha (`0.0.x`), **not yet published to npm.** The **engine is complete** — every
+> operation below ships today. What is still to come is bundled _content_, not capability. The surface:
+>
+> - the code-system **identity resolver** (`resolveSystem`) and the ConceptMap **`$translate`** engine
+>   (`loadConceptMap` / `translate`);
+> - the **CodeSystem load layer** (RRF / CSV / fixed-width / FHIR JSON) with **`$lookup`** and
+>   **`$validate-code`**;
+> - **ValueSet** binding (`compose` / **`$expand`** / **`$validate-code`**), subsumption read from the
+>   release's own hierarchy;
+> - **UCUM** unit validation and canonicalization (`validateUcum` / `ucumEqual`, recognition only, **no
+>   magnitude conversion**) — the official UCUM functional-test suite is the conformance gate;
+> - the **crosswalk resolvers** — the CMS **ICD-9↔ICD-10 GEMs** (`loadGems` / `applyGem`,
+>   public-domain) and the NLM **SNOMED CT → ICD-10-CM complex map** (`loadComplexMap` /
+>   `applyComplexMap`, BYO — zero SNOMED content bundled), never inverted;
+> - the **RxNorm drug graph** (`loadRxNormGraph` + `ingredientsOf` / `genericFor` / `brandsFor` /
+>   `doseFormsOf` / `consistsOf` / `resolveNdc` / `approximateMatch`) over a **BYO** RxNorm RRF release,
+>   edges read in RxNorm's documented direction and never inverted, an absent `RXCUI`/NDC typed, never
+>   fabricated.
+>
+> **Bring your own data.** The engine is whole; **no code-system _content_ is bundled yet.** It runs
+> over the FHIR resources and standard releases _you_ supply. The bundleable public-domain content packs
+> (RxNorm Prescribable, ICD-10-CM, UCUM, LOINC) are still to come — they are blocked on getting a genuine
+> verbatim public-domain release into the build, not on engine work — and the copyrighted content
+> (SNOMED CT / CPT / full LOINC / UMLS / VSAC) is bring-your-own permanently by license.
+
+## Install
+
+> **Not on npm yet.** `@cosyte/terminology` is pre-alpha and **unpublished** — the command below is how
+> you will install it once the first `0.0.x` release lands. Until then the package is source-only.
+
+```bash
+npm install @cosyte/terminology
+```
+
+## Resolve a code system to its canonical URI
+
+```ts
+import { resolveSystem, isUnknownSystem } from "@cosyte/terminology";
+
+const r = resolveSystem("2.16.840.1.113883.6.1"); // OID, mnemonic, or URI
+isUnknownSystem(r) ? "unknown" : r.url; // "http://loinc.org"
+```
+
+## Translate a code through a ConceptMap
+
+```ts
+import { loadConceptMap, translate } from "@cosyte/terminology";
+
+const map = loadConceptMap(myFhirConceptMapJson); // a standard FHIR R4 ConceptMap
+const result = translate({ system: "http://loinc.org", code: "2160-0" }, map);
+
+if (result.unmapped) {
+  // Typed, surfaced outcome — carries any group.unmapped fallback mode. Never a guessed target.
+} else {
+  for (const m of result.matches) {
+    m.target; // a frozen Coding, drawn verbatim from the map
+    m.relationship; // "equivalent" | "source-is-narrower-than-target" | … (R5 vocabulary)
+    m.equivalence; // the verbatim FHIR R4 equivalence token
+    m.comment; // steward map advice, carried through verbatim
+  }
+}
+```
+
+## Look up a code in a code system
+
+```ts
+import { loadCodeSystem, lookup, validateCode } from "@cosyte/terminology";
+
+// Load a consumer-supplied release: RRF (RxNorm/UMLS), CSV (LOINC), fixed-width
+// (ICD-10-CM order file — see ICD10CM_ORDER_FILE_FIELDS), or a FHIR CodeSystem JSON.
+const cs = loadCodeSystem({ format: "fhir", resource: myFhirCodeSystemJson });
+
+const hit = lookup(cs, "2160-0"); // $lookup
+if (hit.found) {
+  hit.display; // the preferred display, verbatim from the release
+  hit.status; // deprecated / header-not-billable / obsolete / … carried, never presented clean
+} else {
+  hit.code; // "TERM_CODE_UNKNOWN" — never a fabricated display
+}
+
+validateCode(cs, "2160-0").valid; // $validate-code — true iff present; never a guessed true
+```
+
+## Validate and compare UCUM units
+
+Recognition and canonicalization only — **no magnitude conversion** (`5 mg/dL` → `mmol/L` needs the
+analyte's molar mass, a clinical computation this engine refuses).
+
+```ts
+import { validateUcum, ucumEqual } from "@cosyte/terminology";
+
+const v = validateUcum("mmol/L");
+v.valid; // true — v.canonical is a stable canonical descriptor
+validateUcum("mg/dl/").valid; // false — code "TERM_UCUM_INVALID", never a guessed "nearest" unit
+
+ucumEqual("N", "kg.m/s2"); // true  — same unit, different spelling
+ucumEqual("mmol/L", "mmol.L-1"); // true  — annotations inert, operators normalized
+ucumEqual("mg", "g"); // false — different units (this is not conversion)
+ucumEqual("Cel", "K"); // false — a special (non-linear) unit is never equated with a linear one
+```
+
+The UCUM table is the official `ucum-essence.xml`, vendored **verbatim** and parsed at runtime; the
+engine ships no derivative of it and passes the official UCUM functional-test suite. See
+`vendor/ucum/NOTICE.md`.
+
+> **Case-sensitive (c/s) mode only.** UCUM's normative interchange mode — the one FHIR/HL7 bind to —
+> is case-sensitive (`m` = metre, `M` = mega, `Pa` = pascal, `pA` = picoampere). The
+> case-**insensitive** (c/i) spelling variant is **not** supported; a c/i-only string returns a typed
+> `TERM_UCUM_INVALID` (fail-safe — never silently reinterpreted). Magnitude conversion is likewise a
+> deliberate non-goal (recognition and canonicalization only).
+
+## Navigate the RxNorm drug graph
+
+Load a **bring-your-own** RxNorm RRF release and walk the ingredient / brand / clinical-drug /
+dose-form graph. Relationships are read in RxNorm's documented direction (`RELA` is the relationship
+the **second** `RXCUI` has to the **first**); navigation follows only authored edges — the engine
+never synthesizes an inverse, and never fabricates a concept, edge, or NDC.
+
+```ts
+import { loadRxNormGraph, ingredientsOf, genericFor, resolveNdc } from "@cosyte/terminology";
+
+const graph = loadRxNormGraph({
+  conso: rxnconsoRrf,
+  rel: rxnrelRrf,
+  sat: rxnsatRrf,
+  version: "RXNORM_2026AA",
+});
+
+ingredientsOf(graph, "314076"); // { found: true, targets: [ { rxcui: "29046", tty: "IN", name: "lisinopril", … } ] }
+genericFor(graph, "311354"); // an SBD → its SCD, via the authored tradename_of edge
+resolveNdc(graph, "00000000001"); // { resolved: true, rxcui: "314076", status: "active", asOf: "RXNORM_2026AA" }
+ingredientsOf(graph, "99999999"); // { found: false, code: "TERM_RXNORM_UNKNOWN_RXCUI" } — never a guess
+```
+
+The engine ships **no** RxNorm content — you supply the release (the public-domain Current Prescribable
+Content subset, or the full BYO release). Bundling the public-domain pack is a later phase.
+
+## The invariants this engine is built on
+
+- **Never fabricate.** An unmapped source is a typed `unmapped`, never a guessed target. Every target
+  returned is drawn verbatim from the supplied map. An unrecognized system resolves to a typed
+  `unknown`, never a guessed URI.
+- **Never invert.** A directional map is read in its authored direction only; reverse translation
+  needs an explicit inverse map, never a mechanical inversion.
+- **BYO data, engine-only.** Zero copyrighted terminology content is bundled (a licensing wall, not a
+  gap); the engine operates over your own FHIR resources.
+- **Liberal load, conservative assertion.** Malformed input degrades to a typed diagnostic; a 1:many
+  mapping returns the full candidate set, never collapsed to one.
+- **Value-free diagnostics.** A diagnostic carries a code + system + version, never patient context —
+  a code _in patient context_ can be PHI.
+- **Zero runtime dependencies. Dual ESM + CJS.** Node stdlib only; built with `tsup`, validated with
+  `attw`. Immutable by construction (every returned value is deep-frozen).
+
+## License
+
+MIT © Cosyte