@cosyte/terminology 0.0.1 → 0.0.4

package/CHANGELOG.md

@@ -9,8 +9,284 @@ 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
+
+- **`LICENSE` was unqualified MIT over a tree that also distributes third-party material**
+  (`TERMINOLOGY-LICENSE-THIRD-PARTY`, residuals 1 and 2 of `TERMINOLOGY-RESIDUALS`). The README had
+  already grown a "What is bundled" carve-out; the licence file had not, so the two consumer-facing
+  licence statements disagreed. The MIT text is unchanged and still covers this package's own code.
+  A `THIRD-PARTY MATERIALS` section is appended, stating for each item what is distributed and under
+  whose copyright: the **UCUM unit table** (`ucum-essence.xml` v2.2, revision-date 2024-06-17,
+  copyright 1999-2024 Regenstrief Institute, Inc., verbatim under the UCUM Copyright Notice and
+  License, embedded byte-for-byte in the build) with its grant recorded as **revocable**, its
+  no-different-standard and no-derivative-works restrictions, its warranty disclaimer and a pointer
+  to `vendor/ucum/NOTICE.md`, which ships in the tarball and remains the notice of record; the
+  **UCUM functional-test suite** (EPL v1.0, repository-only, not distributed on npm);
+  **`SYSTEM_IDENTITIES`**; the **SNOMED CT identifiers the crosswalk resolver names**; and
+  **RxNorm's relationship and term-type names**. The notice itself is deliberately untouched: it was
+  verified against `ucum.org/license` on 2026-07-30 and already carries all four things the licence
+  requires of a distributor.
+  The last of those closes the second residual. "The engine ships no RxNorm **content**" was
+  unscoped in the way the UCUM claim once was, because `RELA` / `RELA_INVERSE` / `TERM_TYPES` do
+  ship RxNorm's relationship and term-type names; every site now reads "no RxNorm **release**", the
+  same narrowing already applied to the code-system claim, and the names that do ship are named.
+  `Ships no SNOMED content` on the complex-map loader is narrowed to "no SNOMED CT release or
+  refset" for the same reason. **No engine behaviour, API surface or bundled content changes.**
+  Both surfaces that carry the claim move together, as they must: `README.md` and the package JSDoc
+  compiled into `dist/index.d.ts` / `dist/index.d.cts`, plus four `docs-content/` pages, two of
+  which carried a grammatically **closed** bundled-list that the new `LICENSE` would otherwise have
+  contradicted. The enumerated items are derived from the build, not from prose, and every list
+  reads "includes the following" rather than closing the set. Beyond the named constants,
+  individual SNOMED CT, ICD-10-CM and **RxNorm** identifiers ship inside the API documentation
+  examples, with their real names and term types, and those examples reach a consumer in three
+  places rather than one: `README.md`, the compiled declaration files, and the build's sourcemaps,
+  whose `sourcesContent` carries every source comment verbatim. No absolute negative is written
+  over those files: a draft said "no RxNorm release, drug concept or NDC is distributed", which the
+  build falsifies (`RXCUI` `316151` ships as "lisinopril 10 MG"), so the claim is scoped to the
+  release rather than reworded around it.
+  Gated by `test/license-third-party.test.ts` (bytes read with `node:fs`, never a `grep` pipeline):
+  the MIT grant is intact; the third-party section names the UCUM copyright holder, licence URL,
+  revocability, no-derivative-works restriction, warranty disclaimer and `NOTICE.md` pointer;
+  `LICENSE`, `README.md`, the package JSDoc and the four `docs-content/` pages all name the same
+  distributed items, so one surface cannot be updated while another is left contradicting it; no
+  prose file in `LICENSE`, `README.md`, `docs-content/` or **all** of `src/` contains the phrase
+  "RxNorm content" or "SNOMED content"; and every checked-in path in `package.json`'s `files`
+  exists, which is the check `0.0.1` lacked when it pointed consumers at a `NOTICE.md` the tarball
+  did not contain. The anchor list is explicit rather than inferred, so a sixth bundled item still
+  needs the anchors updated by hand.
+  That guard bans the **phrase**, not a determiner pattern, and the reason is recorded because it
+  was got wrong first: a version matching `no\s+(\*\*)?RxNorm(\*\*)?\s+content` put the optional
+  bold markers after the space, so it matched `no **RxNorm content` and missed `**no** RxNorm
+content` — the form every historical instance actually took — and read green over the whole
+  pre-fix tree, 0 of 6 real forms firing. A self-test now asserts the matcher fires on all eight
+  historical spellings and stays quiet on the correct wording. The file list also **walks** `src/`
+  rather than naming files, because a hand-written list omitted `src/rxnorm/rela.ts` and
+  `src/rxnorm/tty.ts`, whose doc comments compile into the declaration files.
+
+- **Three published documentation pages carried a link form that MDX cannot compile, and it stopped
+  docs.cosyte.com building for every package** (`TERMINOLOGY-MDX-AUTOLINK`). `docs-content/intro.md`,
+  `troubleshooting.md` and `concepts-archetype.md` linked the UCUM licence as the CommonMark autolink
+  `<https://ucum.org/license>`. `cosyte/docs` compiles fetched content as **MDX**, which is stricter:
+  it reads the `<` as the start of an element, `https` as a tag name and `:` as a namespace separator,
+  then fails on the `/` with `Unexpected character '/' (U+002F) before local name`. Docusaurus SSG
+  failure is **global**, so three lines in this package's tarball did not degrade one page, they
+  stopped the whole documentation site deploying, for all nine packages it hosts. It went live when
+  `0.0.2` published (2026-07-29T19:20Z) and broke the next push to that repository's `main`.
+  Rewritten as `[https://ucum.org/license](https://ucum.org/license)`, which renders identically and
+  is the form MDX's own error message recommends. **No engine behaviour, API surface or bundled
+  content changes.**
+  `README.md`, `vendor/ucum/NOTICE.md` and `scripts/generate-ucum-essence-data.ts` use the same
+  autolink form and are **deliberately untouched**: verified against the published `0.0.2` assets,
+  `docs-content.tar.gz` ships only the narrative pages plus `sidebars.json` and `source.tar.gz` ships
+  only `package.json` + `src/`, so nothing outside `docs-content/` reaches MDX, and the form renders
+  correctly on GitHub and the registry where those files are actually read.
+
+- **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.)
+
+### Added
+
+- **A gate over `docs-content/` that fails on an MDX-hostile link form**
+  (`test/docs-content-mdx-safety.test.ts`). A published release is immutable and the documentation
+  site re-fetches it indefinitely, so a bad link in a tarball cannot be recalled: fixing this
+  repository's `main` does nothing for the version that shipped it. The gate reports the offending
+  file and line with the replacement form, runs inside the required `ci / verify` context (so it
+  cannot be silently un-required by being split into its own job), and carries a **self-test** proving
+  the matcher can see a real autolink, so a green result cannot come from a pattern that matches
+  nothing. It reads bytes directly rather than shelling out to `grep`, which this repository has
+  already been burned by. Scoped to `docs-content/` only, for the reason above.
+
+### 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 +518,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/LICENSE

@@ -19,3 +19,86 @@ 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.
+
+
+================================================================================
+THIRD-PARTY MATERIALS
+================================================================================
+
+The MIT license above covers Cosyte's own code. This repository and the published
+npm package also distribute third-party materials. Those materials stay under
+their own copyright and license terms, and the MIT grant above does not extend to
+them. What is distributed includes the following.
+
+1. The UCUM unit table (vendor/ucum/ucum-essence.xml)
+
+   The Unified Code for Units of Measure (UCUM), also known as the "UCUM
+   Specification," is copyright (c) 1999-2024, Regenstrief Institute, Inc. All
+   rights reserved.
+
+   Version 2.2, revision-date 2024-06-17, is reproduced verbatim under the UCUM
+   Copyright Notice and License, https://ucum.org/license, and is embedded
+   byte-for-byte in the published build. That License grants a worldwide,
+   non-exclusive, no-charge, royalty-free, revocable license to reproduce,
+   publicly display, publicly perform and distribute the Work, and it permits
+   developing and commercializing software that interoperates with UCUM. It does
+   not permit using the Work to develop or promulgate a different standard, and it
+   does not permit derivative works: the content may not be modified and its
+   meaning must remain unchanged. This copy is unmodified, and no derivative of it
+   is distributed.
+
+   Disclaimer of warranties: the UCUM Specification is provided "as is" without
+   warranty of any kind. See the License at the URL above for the full disclaimer.
+
+   The complete notice ships inside this package at vendor/ucum/NOTICE.md. That
+   file, not this summary, is the notice, and it is the copy to read.
+
+2. The UCUM functional-test suite (vendor/ucum/UcumFunctionalTests.xml)
+
+   Copyright (c) 2008-2009 Grahame Grieve and other contributors (Gunther Schadow,
+   Lloyd Mackenzie, Vladimir Alexiev), reproduced verbatim under the Eclipse
+   Public License v1.0, https://www.eclipse.org/legal/epl-v10.html. It is used
+   only as a test fixture in this repository: package.json's "files" does not name
+   it, so it is not distributed in the npm package.
+
+3. Code-system identity facts (SYSTEM_IDENTITIES)
+
+   The OID and canonical-URI pairings, names and mnemonics for the code systems
+   the resolver recognizes. These identify the systems; no system's code list is
+   distributed.
+
+4. SNOMED CT concept identifiers named by the crosswalk resolver
+
+   SNOMED CT identifiers are distributed with their descriptions: the complex-map
+   category concepts in MAP_CATEGORIES (447637006, 447638001, 447639009,
+   447640006) that a map row's mapCategoryId refers to, and the gender findings
+   248152002 (Female) and 248153007 (Male) that a gender IFA rule is written
+   against. Further SNOMED CT identifiers, and ICD-10-CM codes, appear in the API
+   documentation examples, which are distributed in the compiled declaration
+   files (dist/index.d.ts, dist/index.d.cts) and in the build's sourcemaps, whose
+   sourcesContent carries every source comment verbatim.
+   SNOMED CT is copyright (c) International Health Terminology Standards
+   Development Organisation. No SNOMED CT release or refset is distributed; you
+   supply the map rows under your own SNOMED CT licence.
+
+5. RxNorm relationship and term-type names (RELA, RELA_INVERSE, TERM_TYPES)
+
+   The drug-graph API is written against RxNorm's own vocabulary, and those names
+   are distributed: the relationship names in RELA and RELA_INVERSE
+   (has_ingredient, ingredient_of, tradename_of, and the rest), and the term-type
+   codes in TERM_TYPES, each with its name as published by the U.S. National
+   Library of Medicine ("SCD" reads "Semantic Clinical Drug"). Individual RxNorm
+   identifiers also appear in the API documentation examples, with their RxNorm
+   names and term types (for instance RXCUI 316151, "lisinopril 10 MG"), and in
+   README.md as well as the declaration files and sourcemaps named above. RxNorm
+   is produced by the National Library of Medicine. No RxNorm release is
+   distributed; you supply it.
+
+Beyond what is named above, no code-system release is distributed with this
+package. SNOMED CT, CPT, LOINC, UMLS and RxNorm releases, the CMS GEM files, the
+NLM complex-map refset and VSAC value sets are all supplied by the caller, under
+whatever terms their steward sets.
+
+This section states what is distributed and under whose copyright. It is not legal
+advice, and it makes no claim about whether any particular use of these materials
+is permitted to you.

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, including the UCUM unit table, the code-system _identities_ (OID ↔ canonical URI), the
+SNOMED CT concepts the crosswalk resolver names and RxNorm's relationship and term-type 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,17 @@ 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.
+The engine ships **no** RxNorm release; you supply it (the public-domain Current Prescribable
+Content subset, or the full BYO release). What it does ship is RxNorm's relationship and term-type
+_names_, listed under [What is bundled](#what-is-bundled).
 
 ## The invariants this engine is built on
 
@@ -154,8 +189,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 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 +199,41 @@ 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. Further SNOMED CT identifiers, and
+  ICD-10-CM codes, appear in the API documentation examples, which are distributed in the compiled
+  declaration files and in the build's sourcemaps. SNOMED CT is copyright
+  © International Health Terminology Standards Development Organisation. **No SNOMED CT release or
+  refset is bundled** — you supply the map rows under your own SNOMED CT licence.
+- **The RxNorm relationship and term-type names** the drug-graph API is written against: the
+  relationship names in `RELA` / `RELA_INVERSE` (`has_ingredient`, `tradename_of`, …), and the
+  term-type codes in `TERM_TYPES`, each with its name as published by the U.S. National Library of
+  Medicine (`SCD` reads "Semantic Clinical Drug"). Individual RxNorm identifiers also appear in the
+  API documentation examples, with their RxNorm names and term types (for instance `RXCUI` `316151`,
+  "lisinopril 10 MG"), and in this README as well as the places named above. RxNorm is produced by the
+  National Library of Medicine. **No RxNorm release is bundled**; you supply it.
+
+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; the `LICENSE` file that ships with this package carries the MIT text and a
+third-party notices section naming each of them.