@cosyte/terminology 0.0.1 → 0.0.2

package/CHANGELOG.md

@@ -9,8 +9,202 @@ this file is maintained by hand (Changesets handles the version bump and publish
 
 ## [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).
+### Fixed
+
+- **The package claimed to bundle no copyrighted content while bundling the UCUM table, and its
+  attribution never reached the tarball** (`TERMINOLOGY-LICENSING-ACCURACY`). Four statements shipped
+  in `0.0.1`, live on the registry and on docs.cosyte.com, that the tree falsifies:
+  1. the unscoped "**zero copyrighted terminology content is bundled**" claim (README, the JSDoc
+     compiled into `dist/index.d.ts` / `dist/index.d.cts`, and four `docs-content/` pages) is
+     falsified by `ucum-essence.xml` — copyright Regenstrief Institute, Inc. — being embedded
+     byte-for-byte in `dist/index.mjs` and `dist/index.cjs`. The vendored XML carries no copyright
+     line of its own, so the shipped copy asserted nothing;
+  2. `vendor/ucum/NOTICE.md` was **absent from `package.json`'s `files`**, so the attribution never
+     reached a consumer and the README pointed at a file the package did not contain. Measured by
+     packing the base tree: 10 files, no `NOTICE.md`;
+  3. `src/crosswalk/categories.ts` bundles four SNOMED CT map-category concepts — id **and** steward
+     description — in the same doc comment that said "no SNOMED CT content is bundled";
+  4. the README listed **LOINC** among "public-domain content packs" one line before listing it as
+     copyrighted, and listed **UCUM** among packs that "are not bundled" while bundling it.
+
+  Founder call 2026-07-29: keep the bundled table, make the claim true. Every consumer surface now
+  says **"no code-system release is bundled"** and then names what is: the UCUM unit table
+  (`ucum-essence.xml` v2.2, copyright ©1999–2024 Regenstrief Institute, Inc., verbatim under the UCUM
+  Copyright Notice and License, with its warranty disclaimer), the code-system identity pairings, and
+  the SNOMED CT concepts the crosswalk resolver names — the four map-category concepts **and** the two
+  gender findings (`248152002` / `248153007`) a gender `IFA` rule is written against, each with its
+  description (copyright © International Health Terminology Standards Development Organisation).
+  `vendor/ucum/NOTICE.md` is now in `files` and the packed tarball carries it, which also repairs the
+  dangling README pointer. On the README, the declaration files and the docs intro the list is written
+  as **open** ("includes the following"); a draft instead called it "three things … exact rather than
+  approximate", and that self-certification was falsified from `dist` in one grep by the gender
+  findings it had missed.
+
+  The README and the `src/` doc comments were corrected **together** and the built declaration files
+  read back, because fixing one and not the other is what made the previous attempt contradict itself
+  and forced a revert to base. Legal conclusions were **cut** rather than reworded, measured on the
+  base across `README.md`, `docs-content/`, `src/` and `vendor/`: **"license-clean" ×5**
+  (`src/codesystem/fhir.ts`, `src/codesystem/load.ts`, `src/codesystem/types.ts`,
+  `src/valueset/types.ts`, `vendor/ucum/NOTICE.md`) and a **permitted-use assertion ×2**
+  (`src/ucum/essence.ts`, `vendor/ucum/NOTICE.md`). All seven are now zero. The docs state what is
+  distributed and under whose copyright, and say plainly that this is not legal advice. The gate's own
+  tarball
+  drift tripwire caught the new public surface: `vendor/ucum/NOTICE.md` is now scanned by
+  `check:no-internal-refs`, and the internal roadmap citation it carried was removed before it shipped.
+
+  No runtime behaviour changes.
+
+- **A RxNorm concept could load under a term type it does not have.** `loadRxNormGraph` recognized 18
+  of RxNorm's term types and typed each concept from whichever recognized `RXNCONSO` atom appeared
+  first in the file. Five real term types were not among the 18 (`SCDF`, `SBDF`, `SCDFP`, `SBDFP`,
+  `SCDGP`, two of which this package's own documentation already named as subjects of authored
+  `has_ingredient` rows), and `PSN` / `SY` / `TMSY` were, so a drug of an unrecognized type that also
+  carried a synonym atom loaded under the **synonym's** term type instead of being skipped. `RXCUI`
+  370659, the `SCDF` "hydroxyzine Oral Tablet", loaded as a Tall Man Lettering synonym with no
+  warning, and then answered navigation queries under that type. The failure did not need an
+  unrecognized type: any concept whose synonym atom preceded its defining one was mislabelled the
+  same way, including an ordinary `SCD`.
+
+  Both halves are fixed together, because either alone leaves the class open. The term-type
+  vocabulary now carries all of RxNorm's, each under its published name, and `BPCK` reads "Brand Name
+  Pack" as the NLM writes it. And a concept is now typed by a **defining** atom wherever that sits in
+  the file: the NLM defines `PSN` / `SY` / `TMSY` as a "synonym of another TTY", so they type a name
+  rather than a concept and can no longer establish one. An `RXCUI` that no defining atom could type
+  is left out of the graph and reported as a new `TERM_RXNORM_UNTYPED_CONCEPT` warning, which also
+  covers concepts that were previously dropped in silence. Refusing is the safer direction: an absent
+  concept is already a first-class typed answer, while a concept whose term type reads `TMSY` is a
+  fabricated claim about what a drug is, and a caller cannot tell it from a real one.
+
+  `ingredientsOf` keeps its contract exactly: it follows authored edges only and synthesizes nothing.
+  Concepts of the five restored types now load, so they answer with the `has_ingredient` rows their
+  release really carries, and the reference now records what those are, verified per relation rather
+  than inferred from a sibling: an `SCDF` reaches the ingredient `IN`, an `SBDF` reaches the **brand
+  name** rather than the active ingredient, and the precise forms carry no ingredient edge at all.
+  An `SCDFP` instead reaches its basis-of-strength substances by `has_boss`, a one-to-many relation
+  whose targets can be precise ingredients or plain ingredients, and which `ingredientsOf`
+  deliberately does not follow. Also exports `isSynonymTermType`.
+
+- **The documented RxNorm ingredient topology now matches the one RxNorm authors.** The package's
+  own documentation taught an edge that does not exist. The API reference for `ingredientsOf`, the
+  RxNorm type and guide overviews, the quickstart, the concepts guide, the README and the loader's
+  worked example all modelled a clinical drug linking straight to its ingredient (`SCD
+has_ingredient IN`). RxNorm authors no such relationship in any release: the ingredient edge is
+  authored on the components and dose-form concepts around the clinical drug rather than on the drug
+  itself, a branded concept's own ingredient edge lands on its **brand name** rather than on the
+  active ingredient, and `IN ingredient_of` reaches those components rather than the drug. Because
+  the reference text ships inside the type declarations, an installed copy of the package was
+  teaching it too, and `ingredientsOf` on a clinical drug returning nothing read as a gap in the
+  engine rather than as the honest answer it is. Those places now state the authored topology, and
+  it is stated as the pairings RxNorm authors rather than as a closed set: the clinical side
+  (`SCDC`/`SCDF`/`SCDG`) reaches the `IN`, the branded side (`SBD`/`SBDC`/`SBDF`/`SBDG`) reaches the
+  `BN`, and the reader is told to check the term type that comes back. They also spell out how to
+  reach an _active_ ingredient, which is not the same walk from a clinical drug as from a branded
+  one: an `SBD`'s `consists_of` returns its branded component as well as the clinical one, and only
+  the clinical one leads to the `IN`. The quickstart carries new executable examples of both
+  traversals, so the guidance is checked against the shipped code rather than asserted in prose.
+  Behaviour is unchanged: no loader, navigation or resolution result differs.
+- **The npm description described a different package.** `@cosyte/terminology` shipped to the
+  registry describing itself as a "Terminology parser, serializer, and builder ... lenient on parse,
+  spec-clean on emit" - unmodified scaffold boilerplate, still in use by the packages that really
+  are parsers. This one is explicitly **not** a parser, mirrors the FHIR Terminology Module rather
+  than a parser API, and has neither a serializer nor a builder. The most-read line of a published
+  package therefore named three things it does not have and omitted what it does. The description
+  and the `parser` / `serializer` keywords now say what the engine is and what it operates over.
+
+- **`VERSION` now reports the version you actually installed.** `@cosyte/terminology@0.0.1` shipped
+  exporting `VERSION === "0.0.0"`: `package.json` was bumped by Changesets, the constant in the source
+  was not. `docs-content/installation.md` documents printing exactly that constant as the install smoke
+  test, so the one check an installer is told to run was the one that lied. The constant now reads
+  `0.0.1`, and it can no longer drift: the release `version` script rewrites it from `package.json`, and
+  a test compares the two, so a skipped sync fails the build instead of publishing.
+- **Docs stated the wrong publish status in five places.** The README status block, the README install
+  note, `docs-content/intro.md`, `docs-content/installation.md`, and the project guide all said
+  `@cosyte/terminology` was "not yet published to npm" and told readers to consume it from source or a
+  workspace link. It has been on npm since `0.0.1`. All five now say the package is published, and
+  deliberately do not name a version: a version literal in prose is the same drift this release just
+  built a machine guard against, and the registry is the authority. (The historical `[0.0.1]` entry
+  below is left as written: it records what the docs said at the time, hours before the release
+  landed.)
+
+### Changed
+
+- **Internal project bookkeeping is gone from every surface a consumer reads, and a gate now keeps
+  it out.** Per the founder directive of 2026-07-27, what a consumer reads says what the software
+  does and what changed; item identifiers, phase and roadmap-section language, ADR numbers and
+  meta-repo paths belong in this file, the changeset, the commit and the roadmap. Measured on
+  `1158f96` with the final rule set: the public markdown carried 10 lines across four
+  `docs-content/` pages, `src/` doc comments produced 154 gate hits across 28 of the 38 source
+  files (91 from the line pass and 63 from the paragraph-reflow pass, which re-reports all but one
+  of the same places), and the npm `description`/`keywords` and `src/` string literals carried
+  none. The doc comments are the
+  surface that matters most and the one no docs review looks at: they compile verbatim into
+  `dist/index.d.ts` and `dist/index.d.cts`, so **89 lines of the published declaration files**
+  carried this text into every consumer's editor. All are now zero.
+
+  Two shapes no rule catches were cleared by hand, and they are recorded as places rather than as a
+  count: clause-terminal uses of "phase" (in the README, the troubleshooting page, and the
+  concept-map, crosswalk, module and RxNorm reference docs), and two bare roadmap-section citations
+  written without the word "roadmap" next to them. **A zero from a rule set is not a zero**, which
+  is why the by-hand half is stated at all.
+
+  Two statements were **restated rather than deleted**, because removing the planning pointer alone
+  would have widened each into a capability the code does not provide: subsumption is documented as
+  not computed across two separate releases (it reads the loaded system's own `parent` edges), and
+  the `ICD10CM_ORDER_FILE_FIELDS` preset is documented as not confirmed against an authoritative
+  machine-readable source. The NLM RxNorm Technical Documentation citations were
+  deliberately left standing: they are the normative grounding for the `RXNREL` edge-direction
+  convention, and a rule keyed on `§` alone would have deleted the reference a consumer needs in
+  order to check that direction. A self-test now asserts that no rule matches them, so closing that
+  gap has to be a decision.
+
+- **`pnpm check:no-internal-refs` is a new repository gate, and it runs in its own CI job.** It
+  scans `README.md`, `LICENSE`, `docs-content/`, the npm `description` and `keywords`, `src/` doc
+  comments and `src/` string literals, line by line and paragraph-joined, and refuses to report
+  green from a scan that did not read all of its input. It deliberately does **not** scan
+  `CHANGELOG.md`, `.changeset/`, `CLAUDE.md` or `//` comments, which is where the identifiers
+  belong. Its rules key on known project prefixes and never on the `WORD-N` shape: measured here, a
+  shape rule matches 89 hyphenated uppercase tokens on this tree and **all 89 are the consumer's
+  reference material** (`ICD-10-CM`, `ICD-9`, `RFC-4180`, and the UCUM expressions `OHM-1`, `CM-1`
+  and `KG-1.S-2`, which are units with negative exponents), while the prefix-keyed rule matches
+  none. Negative self-tests pin that, so a later simplification reds instead of silently deleting a
+  code system's identifier from a terminology engine's documentation. One rule diverges from the
+  sibling copies on the same reasoning: the "unit of work" rule no longer keys on "the", because a
+  fixed-width order file's **field slice** is this package's public API and the sibling pattern was
+  wrong eight times out of nine here.
+
+- **The RxNorm drug graph's edge direction is now pinned by tests in both directions.** RxNorm
+  relationships are directional, and reading one backwards is a wrong-medication defect rather than a
+  cosmetic one: the ingredient of a tablet would come back as a tablet that is an "ingredient of" its
+  own ingredient, and the generic behind a brand would come back as the brand behind a generic. The
+  convention is now pinned per relation family (ingredient, tradename, dose form, components and
+  packs), forward and reverse, against the sample relationship rows published in the RxNorm technical
+  documentation, so an inverted reading cannot pass by trading one assertion for another. The pinned
+  fixtures follow the topology RxNorm actually authors, including the two places it surprises people:
+  a clinical drug carries no direct ingredient edge (the ingredient is reached through its
+  component), and a branded drug's direct ingredient edge points at its brand name. Behaviour is
+  unchanged: the loader and the navigation surface answer exactly as they did before.
+- **`VERSION` is declared `string` rather than the version literal.** Its emitted type was previously
+  narrowed to the exact release string, so every version bump was a `.d.ts` change and code comparing
+  `VERSION` against another string could be rejected by the type checker. Widening it makes the
+  declared type stable across releases. Runtime value is unchanged.
+
+### Security
+
+- **The CI checks that run on a pull request now block the merge.** Until now `@cosyte/terminology`
+  had no branch-protection ruleset at all, so `ci` (typecheck, lint, format, PHI scan, tests, coverage
+  gate, build, `attw`, dual ESM/CJS smoke) and CodeQL could all go red and the merge would still land
+  on `main`, and `main` publishes. A repository ruleset now requires those checks, restricted to the
+  GitHub Actions app so a status of the same name cannot be posted by anything else, and blocks branch
+  deletion and force-push on `main`. Scope of the claim: this makes a red check binding, it does not
+  make a check correct, and nothing inside this repository can observe the ruleset. See the note in
+  `.github/workflows/ci.yml` before splitting a required job.
+- **Dependency updates are now watched.** The repository had no Dependabot configuration, so its zero
+  open update PRs meant nothing was looking, not that nothing was stale.
+
+## [0.0.1] - 2026-07-21
+
+The first pre-alpha release. The package begins its public history at `0.0.x`, per the cosyte version
+ladder (`0.0.x` until first alpha).
 
 ### Security
 
@@ -242,8 +436,5 @@ its public history at `0.0.x`, per the cosyte version ladder (`0.0.x` until firs
   `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
+[Unreleased]: https://github.com/cosyte/terminology/compare/v0.0.1...HEAD
+[0.0.1]: https://github.com/cosyte/terminology/releases/tag/v0.0.1

package/README.md

@@ -6,12 +6,14 @@
 `@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:
+recognition consume. It ships the **engine, and no code-system release** — SNOMED CT, CPT, LOINC,
+UMLS/RxNorm, and VSAC value sets are strictly bring-your-own. It is not content-free, though: what it
+_does_ bundle — the UCUM unit table, the code-system _identities_ (OID ↔ canonical URI), and the
+SNOMED CT concepts the crosswalk resolver names — is listed with its copyright under
+[What is bundled](#what-is-bundled).
+
+> **Status:** pre-alpha (`0.0.x`), **published on npm.** The **engine is complete** — every
+> operation below ships today. The surface:
 >
 > - the code-system **identity resolver** (`resolveSystem`) and the ConceptMap **`$translate`** engine
 >   (`loadConceptMap` / `translate`);
@@ -23,22 +25,23 @@ canonical URI) are published facts, grounded firsthand and encoded.
 >   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;
+>   `applyComplexMap`, BYO — no SNOMED CT refset 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.
+> **Bring your own data.** The engine is whole; **no code-system release is bundled.** It runs over
+> the FHIR resources and standard releases _you_ supply — SNOMED CT, CPT, LOINC, UMLS/RxNorm, the CMS
+> GEM files, the NLM complex-map refset and VSAC value sets are all bring-your-own, under whatever
+> terms their steward sets. The content packs that would change that (RxNorm Prescribable, ICD-10-CM)
+> are not bundled either. For the things that **are** bundled, and under whose copyright, see
+> [What is bundled](#what-is-bundled).
 
 ## 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.
+> **On npm.** `@cosyte/terminology` is **published**, on the pre-alpha `0.0.x` ladder. The command
+> below installs the real package; the registry, not this page, is the authority on the exact version.
 
 ```bash
 npm install @cosyte/terminology
@@ -111,9 +114,12 @@ 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`.
+The UCUM table is the official `ucum-essence.xml` (version 2.2), and it **is bundled with this
+package** — embedded verbatim in the published build and parsed at runtime. It is copyright
+©1999–2024 Regenstrief Institute, Inc., reproduced under the UCUM Copyright Notice and License
+(<https://ucum.org/license>); the engine ships no derivative of it and passes the official UCUM
+functional-test suite. The full notice ships in the package at `vendor/ucum/NOTICE.md` — see
+[What is bundled](#what-is-bundled).
 
 > **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
@@ -128,8 +134,34 @@ dose-form graph. Relationships are read in RxNorm's documented direction (`RELA`
 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.
 
+Authored edges only means the graph you get is RxNorm's, including where its shape surprises you.
+`has_ingredient` is authored from the **clinical** side (`SCDC`/`SCDF`/`SCDG`) to the ingredient
+`IN`, and from the **branded** side (`SBD`/`SBDC`/`SBDF`/`SBDG`) to the **brand name** `BN` rather
+than to the active ingredient. RxNorm authors no ingredient edge on a clinical drug (`SCD`) at all,
+so that query answers with an honest empty set rather than a guess. To reach an active ingredient,
+walk to the **clinical** component and take its edge: `consistsOf` then `ingredientsOf`. From an
+`SBD`, `consistsOf` returns both its branded component (`SBDC`, whose ingredient edge is the brand
+name again) and the clinical `SCDC`; it is the `SCDC` that leads to the `IN`. The **precise** forms
+(`SCDFP`, `SBDFP`, `SCDGP`) carry no ingredient edge at all: an `SCDFP` instead reaches its
+basis-of-strength substances by `has_boss`, a one-to-many relation with a different meaning whose
+targets can be a `PIN` or a plain `IN`, and which `ingredientsOf` does not follow. Read the `tty` of
+what comes back rather than assuming it.
+
+A concept is typed by its **defining** atom, whichever line of `RXNCONSO` that sits on. `PSN`, `SY`
+and `TMSY` type a _name_ rather than a concept, so they never establish an `RXCUI`'s term type. An
+`RXCUI` no defining atom could type is left out of the graph and reported as
+`TERM_RXNORM_UNTYPED_CONCEPT` on `graph.warnings`, rather than loaded under a synonym's term type:
+a concept that answers with a term type it does not have is a fabricated claim about a drug, and
+this engine refuses instead.
+
 ```ts
-import { loadRxNormGraph, ingredientsOf, genericFor, resolveNdc } from "@cosyte/terminology";
+import {
+  loadRxNormGraph,
+  ingredientsOf,
+  consistsOf,
+  genericFor,
+  resolveNdc,
+} from "@cosyte/terminology";
 
 const graph = loadRxNormGraph({
   conso: rxnconsoRrf,
@@ -138,14 +170,16 @@ const graph = loadRxNormGraph({
   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
+ingredientsOf(graph, "316151"); // an SCDC → { found: true, targets: [ { rxcui: "29046", tty: "IN", name: "lisinopril", … } ] }
+ingredientsOf(graph, "314076"); // an SCD → { found: true, targets: [] }, because no such edge is authored
+consistsOf(graph, "314076"); // → the SCDC, the first of the two hops to the ingredient
+genericFor(graph, "104377"); // 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.
+Content subset, or the full BYO release).
 
 ## The invariants this engine is built on
 
@@ -154,8 +188,9 @@ Content subset, or the full BYO release). Bundling the public-domain pack is a l
   `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.
+- **BYO data, engine-only.** No code-system release is bundled (a licensing wall, not a gap); the
+  engine operates over your own FHIR resources. The UCUM unit table and the two identity sets that
+  **are** bundled are named, with their copyright, under [What is bundled](#what-is-bundled).
 - **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 —
@@ -163,6 +198,31 @@ Content subset, or the full BYO release). Bundling the public-domain pack is a l
 - **Zero runtime dependencies. Dual ESM + CJS.** Node stdlib only; built with `tsup`, validated with
   `attw`. Immutable by construction (every returned value is deep-frozen).
 
+## What is bundled
+
+The engine bundles **no code-system release**. What it _does_ bundle includes the following, named
+with its copyright:
+
+- **The UCUM unit table** — `ucum-essence.xml`, version 2.2, revision-date 2024-06-17. The Unified
+  Code for Units of Measure (UCUM) is copyright ©1999–2024 Regenstrief Institute, Inc., all rights
+  reserved, and is reproduced **verbatim** under the UCUM Copyright Notice and License
+  (<https://ucum.org/license>). It is 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`.
+- **Code-system identity facts** — the OID ↔ canonical-URI pairings (`SYSTEM_IDENTITIES`). These
+  identify the systems; they are not any system's code list.
+- **The SNOMED CT concepts the crosswalk resolver names**, each with its description: the four
+  map-category concepts in `MAP_CATEGORIES` (`447637006`, `447638001`, `447639009`, `447640006`) that
+  a complex-map row's `mapCategoryId` refers to, and the two gender findings (`248152002` Female,
+  `248153007` Male) that a gender `IFA` rule is written against. SNOMED CT is copyright
+  © International Health Terminology Standards Development Organisation. **No SNOMED CT release or
+  refset is bundled** — you supply the map rows under your own SNOMED CT licence.
+
+This section states what is distributed and under whose copyright. It is not legal advice, and makes
+no claim about whether any particular use of these materials is permitted to you.
+
 ## License
 
-MIT © Cosyte
+MIT © Cosyte — this package's own code. The bundled third-party materials above stay under their own
+copyright and licences.

package/dist/index.cjs

@@ -75,13 +75,13 @@ var 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).
    */
   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".
    */
   TERM_VALUESET_EXPANSION_TRUNCATED: "TERM_VALUESET_EXPANSION_TRUNCATED",
@@ -89,7 +89,7 @@ var 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.
    */
   TERM_UCUM_INVALID: "TERM_UCUM_INVALID",
@@ -97,7 +97,7 @@ var 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".
    */
   TERM_CROSSWALK_NO_MAP: "TERM_CROSSWALK_NO_MAP",
@@ -111,7 +111,7 @@ var 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.
    */
   TERM_CROSSWALK_CONTEXT_REQUIRED: "TERM_CROSSWALK_CONTEXT_REQUIRED",
   /**
@@ -133,17 +133,27 @@ var DIAGNOSTIC_CODES = {
    * **silently** — they are expected, not faults.
    */
   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.
+   */
+  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).
    */
   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.
    */
   TERM_RXNORM_NDC_UNMAPPED: "TERM_RXNORM_NDC_UNMAPPED"
@@ -178,7 +188,7 @@ var 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.
    */
   TERM_MAP_NOT_INVERTIBLE: "TERM_MAP_NOT_INVERTIBLE"
@@ -4360,12 +4370,17 @@ var TERM_TYPES = Object.freeze({
   BN: "Brand Name",
   SCDC: "Semantic Clinical Drug Component",
   SBDC: "Semantic Branded Drug Component",
+  SCDF: "Semantic Clinical Drug Form",
+  SBDF: "Semantic Branded Drug Form",
+  SCDFP: "Semantic Clinical Drug Form Precise",
+  SBDFP: "Semantic Branded Drug Form Precise",
   SCD: "Semantic Clinical Drug",
   SBD: "Semantic Branded Drug",
   SCDG: "Semantic Clinical Drug Group",
   SBDG: "Semantic Branded Drug Group",
+  SCDGP: "Semantic Clinical Drug Form Group Precise",
   GPCK: "Generic Pack",
-  BPCK: "Branded Pack",
+  BPCK: "Brand Name Pack",
   DF: "Dose Form",
   DFG: "Dose Form Group",
   PSN: "Prescribable Name",
@@ -4374,9 +4389,13 @@ var TERM_TYPES = Object.freeze({
   ET: "Entry Term"
 });
 var KNOWN = new Set(Object.keys(TERM_TYPES));
+var SYNONYM = /* @__PURE__ */ new Set(["PSN", "SY", "TMSY"]);
 function asTermType(tty) {
   return KNOWN.has(tty) ? tty : void 0;
 }
+function isSynonymTermType(tty) {
+  return SYNONYM.has(tty);
+}
 
 // src/rxnorm/load.ts
 var SAB_RXNORM = "RXNORM";
@@ -4390,13 +4409,13 @@ function cell2(cells, index) {
 }
 function parseConso(content, warnings) {
   const concepts = /* @__PURE__ */ new Map();
-  const lines = content.split(/\r?\n/);
-  for (let i = 0; i < lines.length; i++) {
-    const raw = lines[i] ?? "";
+  const conso = [];
+  const untyped = /* @__PURE__ */ new Map();
+  for (const [i, raw] of content.split(/\r?\n/).entries()) {
     if (raw === "") continue;
     const cells = parseRrfLine(raw);
     if (cells.length <= CONSO.STR) {
-      warnings.push(
+      conso.push(
         Object.freeze({
           code: "TERM_RXNORM_MALFORMED_ROW",
           file: "RXNCONSO",
@@ -4407,11 +4426,9 @@ function parseConso(content, warnings) {
       continue;
     }
     if (cell2(cells, CONSO.SAB) !== SAB_RXNORM) continue;
-    const tty = asTermType(cell2(cells, CONSO.TTY) ?? "");
-    if (tty === void 0) continue;
     const rxcui = cell2(cells, CONSO.RXCUI);
     if (rxcui === void 0 || rxcui === "") {
-      warnings.push(
+      conso.push(
         Object.freeze({
           code: "TERM_RXNORM_MALFORMED_ROW",
           file: "RXNCONSO",
@@ -4421,7 +4438,13 @@ function parseConso(content, warnings) {
       );
       continue;
     }
+    const tty = asTermType(cell2(cells, CONSO.TTY) ?? "");
+    if (tty === void 0 || isSynonymTermType(tty)) {
+      if (!concepts.has(rxcui) && !untyped.has(rxcui)) untyped.set(rxcui, i + 1);
+      continue;
+    }
     if (concepts.has(rxcui)) continue;
+    untyped.delete(rxcui);
     const name = cell2(cells, CONSO.STR) ?? "";
     const suppress = cell2(cells, CONSO.SUPPRESS) ?? "N";
     concepts.set(
@@ -4429,14 +4452,24 @@ function parseConso(content, warnings) {
       Object.freeze({ rxcui, tty, name, suppressed: suppress !== "" && suppress !== "N" })
     );
   }
+  for (const line of untyped.values()) {
+    conso.push(
+      Object.freeze({
+        code: "TERM_RXNORM_UNTYPED_CONCEPT",
+        file: "RXNCONSO",
+        line,
+        detail: "no RXNORM atom established this RXCUI's term type (every atom was synonym-class or an unmodelled TTY); skipped rather than typed from a synonym"
+      })
+    );
+  }
+  conso.sort((a, b) => a.line - b.line);
+  for (const w of conso) warnings.push(w);
   return concepts;
 }
 function parseRel(content, warnings) {
   const edges = /* @__PURE__ */ new Map();
   let edgeCount = 0;
-  const lines = content.split(/\r?\n/);
-  for (let i = 0; i < lines.length; i++) {
-    const raw = lines[i] ?? "";
+  for (const [i, raw] of content.split(/\r?\n/).entries()) {
     if (raw === "") continue;
     const cells = parseRrfLine(raw);
     if (cells.length <= REL.RELA) {
@@ -4465,9 +4498,7 @@ function parseRel(content, warnings) {
 }
 function parseNdcs(content, warnings) {
   const ndcs = /* @__PURE__ */ new Map();
-  const lines = content.split(/\r?\n/);
-  for (let i = 0; i < lines.length; i++) {
-    const raw = lines[i] ?? "";
+  for (const [i, raw] of content.split(/\r?\n/).entries()) {
     if (raw === "") continue;
     const cells = parseRrfLine(raw);
     if (cells.length <= SAT.ATV) {
@@ -4519,9 +4550,17 @@ function loadRxNormGraph(source) {
 
 // src/rxnorm/rela.ts
 var 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.
+   */
   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`.
+   */
   INGREDIENT_OF: "ingredient_of",
   /** `has_precise_ingredient` — subject *has precise ingredient* object (a `PIN`). */
   HAS_PRECISE_INGREDIENT: "has_precise_ingredient",
@@ -4664,7 +4703,7 @@ function approximateMatch(graph, query, options = {}) {
 }
 
 // src/index.ts
-var VERSION = "0.0.0";
+var VERSION = "0.0.2";
 
 exports.COMPLEX_MAP_SOURCE_SYSTEM = COMPLEX_MAP_SOURCE_SYSTEM;
 exports.DIAGNOSTIC_CODES = DIAGNOSTIC_CODES;
@@ -4706,6 +4745,7 @@ exports.ingredientsOf = ingredientsOf;
 exports.invertGem = invertGem;
 exports.isA = isA;
 exports.isJsonObject = isJsonObject;
+exports.isSynonymTermType = isSynonymTermType;
 exports.isUnknownSystem = isUnknownSystem;
 exports.loadCodeSystem = loadCodeSystem;
 exports.loadComplexMap = loadComplexMap;