@cosyte/terminology 0.0.4 → 0.0.6

package/CHANGELOG.md

@@ -9,8 +9,237 @@ this file is maintained by hand (Changesets handles the version bump and publish
 
 ## [Unreleased]
 
+### Changed
+
+- **Breaking: `ExpansionDiagnostic.system` is replaced by `ExpansionDiagnostic.path`.** The field
+  used to carry the code system or value set URI the concern was about — consumer-supplied text of
+  unbounded length on a diagnostic surface. It now carries a value-free structural locus into your
+  own resource, built from integers and the engine's own field names: `"compose.include[2]"`,
+  `"compose.include[0].valueSet[1]"`, `"expansion"`. A diagnostic raised while expanding a
+  referenced value set is prefixed with the reference that reached it. This is strictly more precise
+  than the URI, which cannot distinguish two `include` components naming the same system. `expand`
+  and `validateCodeInValueSet` build the path identically, so a locus means the same thing in both;
+  they do **not** always emit the same _set_ of diagnostics, because membership can decide an answer
+  without evaluating a part expansion still has to report. Reading `d.system` is now a type error.
+  The rationale, and the other three sites, are under **Fixed** below.
+
 ### Fixed
 
+- **A `UnitNode` you assembled yourself could change how `reduce` and `ucumEqual` answer for a unit
+  parsed out of the bundled UCUM table, for the rest of the process**
+  (`TERMINOLOGY-ATOMMEMO-POISONING`). `reduce` is exported and takes a caller-built node, and
+  nothing checks that the atoms on it came from the bundled table. Its per-atom memo, and the guard
+  against a definition that leads back to itself, were keyed on `atom.code` — a **string** — so an
+  atom you built wrote under the key of whichever shipped atom happened to share its code, and every
+  later reduction of that shipped atom read what yours had left.
+
+  Measured on `0.0.5`: one `reduce()` over a value-less atom coded `L`, as the first touch of `L` in
+  the process, made `ucumEqual("L", "1")` and `ucumEqual("mg/L", "mg")` both answer `true` where the
+  same calls without it answered `false`, and dropped `mmol/L` from `6.02214076e23 × m-3` to a
+  dimensionless `6.02214076e20` — **a concentration comparing equal to a mass**, from an engine
+  whose contract is never to fabricate. Two further readings on the same build: an atom coded `N`
+  and defined as `N` left the cycle guard armed, so every later `ucumEqual("N", "kg.m/s2")` threw;
+  and the value returned for a term with no factors was the engine's own module-global dimensionless
+  object, so mutating a result you had been handed turned `kg.m/s2` into `999000 × m2.g.s-2` and
+  made `ucumEqual("N", "kg.m/s2")` answer `false`.
+
+  Four changes:
+  - The memo and the cycle guard key on the **atom object**, in a `WeakMap` / `WeakSet`. The atoms
+    `parseUcum` resolves are the unit table's cached singletons, so a parsed expression still gets
+    one memo entry per atom; an atom you built gets its own entry and is collected with it. Measured
+    warm over ten mixed expressions, best of seven trials of 2,000,000 `reduce` calls, on two
+    different machines: identity-keyed came in at or ahead of string-keyed both times. Read that as
+    no measured cost rather than as a speed-up; the absolute figures are machine- and load-dependent
+    and are deliberately not quoted as a pair.
+  - An atom carrying no linear definition, and which is neither a base nor an arbitrary unit, is now
+    **refused** with `UCUM atom has no linear definition` rather than answered — and memoized — as
+    dimensionless. No expression `parseUcum` accepts reaches this, though **not** because every atom
+    in the bundled table has a linear definition: 21 of its 312 atoms, the special units, have none.
+    It is that an expression containing a special unit short-circuits to the opaque `special` form
+    before linear reduction, base and arbitrary units are answered directly, and every remaining atom
+    resolves. A node you assemble can reach it — including by defining an atom in terms of a special
+    unit such as `Cel`, which lands on the table's own `Cel`.
+  - The cycle guard releases its atom in a `finally`, so a throw from inside the recursion no longer
+    wedges that atom for the rest of the process.
+  - `reduce` no longer returns the module-global dimensionless object. What you get back is per-call
+    state, and mutating it cannot reach the engine.
+
+  Keying on identity was chosen over validating that each atom came from the bundled table: it needs
+  no provenance check on the hot path and adds no failure mode for real input, and it is the
+  narrower change. The cost is that an atom you built is answered on its own terms only — the
+  intended contract, not a regression. **No unit obtained from `parseUcum` changes its answer**: the
+  530-case UCUM conformance suite and the rest of the suite are unchanged and green, and the new
+  refusals are reachable only through a node you assembled. **The claim rests on one property, and
+  it is the one this repo asserts: every atom in the bundled table reduces, and none of them reaches
+  a refusal** (`test/ucum/reduce-memo.test.ts`, last case, over all 312). That is enough to cover
+  every expression `parseUcum` accepts rather than sampling them — an expression containing a
+  special unit short-circuits before linear reduction, linear reduction is compositional over atoms,
+  and the table's own definitions close over that same set, so once every atom answers there is
+  nothing left for a bigger corpus to vary. `test/ucum/functional.test.ts` separately drives the
+  vendored UCUM functional-test suite's unit strings through `reduce`.
+  **Do not restate this as more evidence than that.** Three drafts of this paragraph each claimed
+  more than the tree holds — two cited generated-corpus sizes that were not reproducible from their
+  own descriptions, and the third attributed a three-clause sweep to a file that pins one clause of
+  it. A before/after differential is a two-tree measurement and **no in-tree test can pin one**, by
+  construction; do not add a guard to make a sentence here true, shrink the sentence. The three
+  guards are now covered by tests
+  rather than by a `/* v8 ignore */` block, and each message is pinned by whole-message equality
+  rather than by a substring match.
+
+- **Consumer-supplied strings reached `TerminologyError.message`, `err.stack` and an
+  `ExpansionDiagnostic`, contradicting this package's own "value-free by construction" claim**
+  (`PHI-WARNING-MESSAGE-LEAK`). Three sites, found by binding
+  `assertNoDiagnosticPhiLeak` from `@cosyte/test-utils@0.0.2` to a 52-slot table covering the
+  consumer-controlled positions across the readers and loaders that this repo has identified — which
+  is not a proof that none was missed, as the fourth site below shows; **14 of the 52 slots were red on the
+  base commit** — 4 CSV column-config slots, 1 `invertGem` slot, 4 in `expand.ts` and 5 in
+  `validate.ts` — and the table was run there first for exactly that reason. (An earlier draft of
+  this entry said 9. That was the measurement taken before the slot table was extended to the
+  **second copy** of the `src/valueset/` diagnostic factories, and it was never re-taken; the five
+  `validate.ts` slots are the difference. Re-measure after you widen a table.)
+  1. `csv.ts` `requireHeader` interpolated the caller's configured column name into the
+     `TERM_CODESYSTEM_MALFORMED` message. Measured against the published `0.0.5`: a 1,000,000-byte
+     `columns.code` produced a 1,000,063-byte `err.message`, and the same bytes landed in
+     `err.stack`. It now reads the message out of a frozen `MISSING_COLUMN_MESSAGE` table keyed on
+     the column's **role** (`code` / `display` / `status` / `property`) and takes no value
+     parameter. That is the `astm`/`transform` shape the ecosystem audit recorded for the designs
+     that do not leak, and it is what this factory now is — a property of **this** factory, not a
+     rule this package holds everywhere. Several factories here do take `string` parameters and are
+     safe because every argument reaching them is engine-owned; they are named below, and reading
+     the no-value-parameter shape as a package-wide rule is what made three drafts of this entry
+     wrong.
+  2. `invertGem` interpolated `GemMap.direction` into the `TERM_MAP_NOT_INVERTIBLE` message.
+     `GemDirection` is a two-value union, but nothing validates it on load and a JavaScript caller
+     can pass anything, so the echo was unbounded in practice. Now a closed-set `Map` lookup with a
+     direction-free fallback; the direction is kept where it is one of the two authored values,
+     because it tells the caller which file to load instead.
+  3. `ExpansionDiagnostic.system` carried the caller's `include.system`, referenced `valueSet` URL,
+     or `ValueSet.url` verbatim. **This site is not in the 2026-07-30 ecosystem audit, which
+     recorded `terminology` as "one site, a CSV column name".** It is the only one of the three
+     that is _document_-derived rather than caller-configuration. **Breaking:** the field is
+     replaced by `path`, a value-free index locus (`compose.include[2]`,
+     `compose.include[0].valueSet[1]`, `expansion`), built the same way in both `expand.ts` and
+     `validate.ts` so a locus means the same thing in each, and prefixed with the reference that
+     reached it when the diagnostic comes from a referenced value set. The two do **not** always
+     emit the same _set_ of diagnostics and the changeset no longer says they do: membership
+     short-circuits on a system mismatch and on an exclude that cannot change a decided verdict,
+     where expansion still has to report the part it could not compute. Not a truncation: an index path is
+     strictly more precise than the URI, which cannot distinguish two `include`s over one system.
+
+  **Severity is medium-low and stays medium-low.** Sites 1 and 2 echo the caller's own
+  configuration, not a patient's document; site 3 echoes a canonical URI out of reference content.
+  The engine's genuinely patient-derived inputs are its _query_ values (a code off a parsed
+  message, a unit off an observation, an NDC off a prescription, the `PatientContext` age/gender a
+  complex map branches on), and **no query value reaches a message or a stack anywhere**: the
+  engine throws only on an unusable source, never on a query. That is now asserted rather than
+  argued.
+
+  **A misfiled result field, corrected in the same docblock and shipped in `dist/index.d.ts`:
+  `MapProvenance.sourceSystem`.** A draft of the "which result fields carry verbatim text" list put
+  the whole of `MapProvenance` under _your loaded artifact_ — "reference data, not anything a
+  patient supplied". That is true of `.targetSystem`, `.conceptMapUrl` and `.conceptMapVersion`
+  (`group.target`, `map.url`, `map.version`) and **false of `.sourceSystem`**, which `translate`
+  fills from the `system` on the `Coding` **you** passed it, verbatim and unbounded, falling back to
+  the map's `group.source` only when the coding carries none. It is a query echo and is now listed
+  as one, so a reader applies the log-it-only-if-you-would-log-the-code rule to it. This is a
+  classification fix in prose: the value has always been the caller's own, it is not on a
+  diagnostic-message surface, and **nothing about the runtime behaviour changed** — bounding it is
+  not attempted here, and would be the same fabricate-a-miss trade-off as bounding any other echo.
+
+  **The `@param` contract this broke** is `TerminologyError`'s own: _"a **value-free** structural
+  description (path + fault; never an input value)"_. It now also tells a caller why, since the
+  string reaches `err.stack`.
+
+  **The "Value-free by construction" claim in `src/common/diagnostics.ts` was checked before being
+  rewritten, and it was false** on two counts: the two messages above echoed arbitrary input, and
+  "at most a code + system + version" described the leaking `ExpansionDiagnostic.system` as though
+  it were the safety property. The new wording states the mechanical fact — **every string a message
+  is assembled from is owned by the engine**: a literal, a frozen-table entry, or a locus this
+  package built (a `line`, a column count, an index path of integers and FHIR field names) — and, in
+  the same place, scopes it: it covers **diagnostics**, not **results**, which carry the caller's
+  values by design. A first draft of that replacement said instead that "no message is built from a
+  value parameter" and that every message is "a literal or a frozen-table entry". **That was false as
+  written**, of factories it did not touch: `malformed(path, fault)` in `conceptmap/load.ts` and
+  `valueset/load.ts`, and `cannotExpand` / `truncated` / `underPath` in `valueset/` — where
+  `expand.ts` and `validate.ts` each carry their own copy — all of which do interpolate
+  `string` parameters. **An earlier draft of this paragraph said "four", and the tree has seven**;
+  a count in prose is the thing that goes stale, so it is derived now, not written down.
+  The code is fine — every argument reaching them is engine-owned, each `fault`
+  a literal at the call site and each `path` built from indices — but the sentence was stronger than
+  the code, which is precisely the failure this entry exists to end. It now describes the arguments,
+  not the signatures.
+
+  **The mechanism is now stated as a general rule in exactly one place — the
+  `src/common/diagnostics.ts` docblock.** `README.md`, `docs-content/troubleshooting.md` and
+  `docs-content/concepts-archetype.md` carried the old "code + system + version" sentence, and the
+  `test/phi/diagnostic-surface.test.ts` header (new in this slice) carried the same doctrine in a
+  later wording; all four now state only the **consumer-facing property** — nothing you configured
+  and nothing your release or resource contained reaches a `message`, `detail`, `reason` or
+  `err.stack`, at any length — and none restates the general rule. An earlier draft of this slice
+  moved all four to a _restatement_ of the mechanism instead, in the wording already found false of
+  `malformed` / `cannotExpand` / `truncated`, and this entry claimed they had moved with the fix
+  when what they had moved to was the superseded draft. No gate in this repo can grade an English
+  sentence, which is the argument for one copy of the rule rather than four. **Statements scoped to
+  a single factory are not copies of the rule and deliberately stay put** — `csv.ts` still says its
+  own `MISSING_COLUMN_MESSAGE` lookup takes no value parameter, and `TerminologyError`'s `@param`
+  still tells a caller what may go into the string it is handed. The `diagnostics` guidance in
+  `troubleshooting.md`, which told readers to read a diagnostic for "which code system was missing",
+  points at `path`.
+
+  **What the gate proves is narrow, deliberately:** for each declared slot, no verbatim echo of
+  four or more bytes of the planted value on any swept surface, and the slot provably reached the
+  code it names. It does not prove the absence of a re-encoded echo, an echo under four bytes, or a
+  leak through a slot nobody declared. Two limits are written into the file rather than implied
+  away. First, `expectCode` shows the branch ran, not that the _marker_ ran it: about half the slots
+  are **model-only** and pair the marker with a second marker-free malformed element so a diagnostic
+  exists to sweep, and for those it is the sweep of **those diagnostics** that carries the proof. (An
+  earlier draft said "the whole rendered result". The runner sweeps exactly what the two selectors
+  return plus the thrown value, so for the `CodeSystem.url` slot the `url` itself is never swept —
+  correctly, since it is payload, but not swept.) Second, `getModelIdentifiers` returns the model's
+  real loci — a `RxNormLoadWarning.file`
+  token, an `ExpansionDiagnostic.path` — which are also swept as part of their diagnostic, so it is
+  redundant rather than load-bearing; it exists so the classification of every name-like string on
+  every exported model type is executed and reviewable instead of collapsing to a `[]` a reader has
+  to trust. `Property.code` and `RxNormEdge.predicate` are classified as payload on a checkable
+  test: an HL7 v2 `segment.type` is spec-bounded to three characters, so bounding it discards
+  nothing, while a FHIR `code` carries no `maxLength` and RxNorm's `RELA` is an open vocabulary, and
+  both are the keys the engine and the caller match on, so truncating either turns a hit into a
+  miss. The residual is
+  named: that protects the lookup, not a future consumer who builds a locus out of one.
+  `@cosyte/cli` is today the only package in the ecosystem that depends on this one, and it uses
+  `loadConceptMap` + `translate` only.
+
+  **A FOURTH site, found by the refuter after the three above: `reduce` echoed a forged atom's
+  `code` into a plain `Error.message` and `err.stack`** — a second ~1 MB leak. `reduce` is exported
+  and takes a caller-built
+  `UnitNode`, and nothing checks that the atoms on it came from the vendored UCUM table, so a
+  forged atom whose `value.unit` does not parse reaches the throw. Measured on `0.0.5`: a
+  1,000,000-byte atom code produced a **1,000,042-byte** `Error.message`, with the same bytes in
+  `err.stack`. Every `Error` message `reduce` can throw is a literal — two of them at that point,
+  three after the memo fix recorded at the top of this section. The site had been marked `/* v8 ignore */` as
+  "unreachable with the shipped data", and the throw was moved outside that block, with
+  `test/ucum/reduce.test.ts` pinning the message and the stack. **The two branches still inside the
+  block were not unreachable either, and the comment stopped saying they were.** A draft of that slice
+  relabelled them "genuinely unreachable through the public API"; they were not, because `inProgress`
+  and `atomMemo` keyed on the atom's `code` string and nothing checked that an atom came from the
+  vendored table, so a caller-forged atom whose code collided with a shipped one re-entered the
+  cyclic guard (measured: `reduce` over a forged `mol` defined as `mol` threw it) and a forged atom
+  with no `value` fell through the second, which threw nothing — it memoized dimensionless and
+  returned. The "with the shipped data" scope was the defensible one and was restored, stated
+  as a coverage exclusion over a corrupt-table guard rather than as an assertion of unreachability.
+  Neither branch leaked — the one message inside the block was a literal — so nothing was deferred **on
+  the diagnostic surface**. What was deferred is not merely that the branches were reachable: that
+  second branch wrote the forged atom's `code` into the module-global `atomMemo` before returning,
+  so one `reduce()` over a forged, value-less atom whose code collided with a shipped one poisoned
+  every later reduction of that atom in the process — enough to make `ucumEqual("mg/L", "mg")`
+  answer `true`. That is a **never-fabricate defect, not a diagnostic-surface one**, it was
+  byte-identical on `0.0.5`, and it was filed as its own item rather than folded in here. **It is
+  fixed in this same unreleased window — see the memo-poisoning entry at the top of this section —
+  and the `/* v8 ignore */` block is gone with it.** It is **not** in the slot table and
+  cannot be: it throws an un-coded `Error`, so it can carry no `expectCode`, and every slot in
+  that table names one. The 2026-07-30 ecosystem audit recorded this package as "one site"; with
+  `ExpansionDiagnostic.system` and this, it was **three**.
+
 - **`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
@@ -207,6 +436,20 @@ has_ingredient IN`). RxNorm authors no such relationship in any release: the ing
   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.
+- **The README opens with the Cosyte mark, which follows the reader's color scheme.** A `<picture>`
+  block above the H1 offers a dark-ground tile behind a `prefers-color-scheme: dark` media query and
+  carries the light-ground tile as the inner `<img>`, so on a renderer that honors the switch the
+  mark sits on a ground that matches the page it is read on. This README carried no image at all
+  before, so the block is purely additive: the `# @cosyte/terminology` heading, the blockquote
+  tagline and every section below are unchanged, and because the lockup reads "Cosyte" while the
+  heading reads `@cosyte/terminology`, nothing is duplicated. The failure mode is safe: a renderer
+  that strips `<source>` renders the inner `<img>`, so the worst case is a light-ground mark on a
+  dark page, never a missing image. On the npm package page the `<img>` is hoisted out of its
+  `<picture>` by the anchor wrapper, so the light cut renders there, which is the correct one
+  because npmjs.com has no dark mode. The alt text describes the artwork rather than the package,
+  since it is what a screen reader reads out and what a reader gets when the image fails. Both tile
+  URLs were rechecked before push and returned `200 image/png`. No behaviour, API surface or bundled
+  content changed.
 
 ### Changed
 

package/README.md

@@ -1,3 +1,8 @@
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://cosyte.com/tile/cosyte-lockup-tile-on-dark-1200x300.png">
+  <img alt="Cosyte: a plus mark set in two overlapping rounded squares, one solid and one outlined, beside the Cosyte wordmark" src="https://cosyte.com/tile/cosyte-lockup-tile-on-light-1200x300.png">
+</picture>
+
 # @cosyte/terminology
 
 > A **zero-dependency terminology engine** for US healthcare code systems — FHIR-shaped, BYO-data,
@@ -194,8 +199,14 @@ _names_, listed under [What is bundled](#what-is-bundled).
   **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 —
-  a code _in patient context_ can be PHI.
+- **Value-free diagnostic messages.** Nothing you configured and nothing your release or resource
+  contained reaches a `message`, `detail`, `reason` or `err.stack` — not a column name, not a
+  canonical URI, not a unit atom — at any length. What sits beside a message is a locus: a line
+  number, a column count, an index path into your own resource (`compose.include[2]`), or a fixed
+  token naming which file of a release it came from. The
+  **objects** are a different matter: a typed `unknown`/`unmapped` outcome names the code, unit or
+  NDC you asked about, so log the `code` and the locus rather than the whole result — 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).
 

package/dist/index.cjs

@@ -199,6 +199,9 @@ var TerminologyError = class _TerminologyError extends Error {
   /**
    * @param code - The stable {@link FatalCode} describing the fault.
    * @param message - A **value-free** structural description (path + fault; never an input value).
+   *   Every piece of it must be engine-owned — a literal, a frozen-table entry, or a locus this
+   *   package built. This string reaches `err.stack`, so interpolating a caller-supplied or
+   *   document-derived value into it is how a diagnostic becomes a leak.
    */
   constructor(code, message) {
     super(message);
@@ -652,13 +655,16 @@ function parseCsvRows(content) {
 function parseCsv(content) {
   return parseCsvRows(content).rows;
 }
-function requireHeader(header, name) {
+var MISSING_COLUMN_MESSAGE = Object.freeze({
+  code: "CSV source: the configured 'code' column is not present in the header row",
+  display: "CSV source: the configured 'display' column is not present in the header row",
+  status: "CSV source: the configured 'status' column is not present in the header row",
+  property: "CSV source: a configured property column is not present in the header row"
+});
+function requireHeader(header, name, role) {
   const idx = header.indexOf(name);
   if (idx < 0) {
-    throw new TerminologyError(
-      FATAL_CODES.TERM_CODESYSTEM_MALFORMED,
-      `CSV source: required column '${name}' is not present in the header row`
-    );
+    throw new TerminologyError(FATAL_CODES.TERM_CODESYSTEM_MALFORMED, MISSING_COLUMN_MESSAGE[role]);
   }
   return idx;
 }
@@ -682,12 +688,12 @@ function parseCsvSource(source) {
       })
     );
   }
-  const codeIdx = requireHeader(header, source.columns.code);
-  const displayIdx = requireHeader(header, source.columns.display);
-  const statusIdx = source.columns.status !== void 0 ? requireHeader(header, source.columns.status) : void 0;
+  const codeIdx = requireHeader(header, source.columns.code, "code");
+  const displayIdx = requireHeader(header, source.columns.display, "display");
+  const statusIdx = source.columns.status !== void 0 ? requireHeader(header, source.columns.status, "status") : void 0;
   const propIdx = (source.columns.properties ?? []).map((n) => ({
     name: n,
-    index: requireHeader(header, n)
+    index: requireHeader(header, n, "property")
   }));
   const needCols = Math.max(codeIdx, displayIdx, statusIdx ?? 0, ...propIdx.map((p) => p.index)) + 1;
   const concepts = /* @__PURE__ */ new Map();
@@ -1291,48 +1297,54 @@ function makeCoding(system, code, display, version) {
   if (display !== void 0) init.display = display;
   return coding(init);
 }
-function cannotExpand(detail, system) {
+function cannotExpand(detail, path) {
   const d = { code: "TERM_VALUESET_CANNOT_EXPAND", detail };
-  if (system !== void 0) d.system = system;
+  if (path !== void 0) d.path = path;
   return Object.freeze(d);
 }
-function truncated(detail, system) {
+function truncated(detail, path) {
   const d = { code: "TERM_VALUESET_EXPANSION_TRUNCATED", detail };
-  if (system !== void 0) d.system = system;
+  d.path = path;
   return Object.freeze(d);
 }
+function underPath(d, prefix) {
+  const out = { code: d.code, detail: d.detail };
+  out.path = d.path === void 0 ? prefix : `${prefix}/${d.path}`;
+  return Object.freeze(out);
+}
 function intersectInto(into, other) {
   for (const k of into.keys()) if (!other.has(k)) into.delete(k);
   return into;
 }
-function expandReferencedValueSets(urls, ctx, visited) {
+function expandReferencedValueSets(urls, ctx, visited, path) {
   const diagnostics = [];
   let complete = true;
   let acc = null;
-  for (const url of urls) {
+  for (const [i, url] of urls.entries()) {
+    const refPath = `${path}.valueSet[${String(i)}]`;
     if (visited.has(url)) {
-      diagnostics.push(cannotExpand("cyclic value set reference", url));
+      diagnostics.push(cannotExpand("cyclic value set reference", refPath));
       complete = false;
       acc = /* @__PURE__ */ new Map();
       continue;
     }
     const vs = ctx.valueSets?.get(url);
     if (vs === void 0) {
-      diagnostics.push(cannotExpand("referenced value set not supplied", url));
+      diagnostics.push(cannotExpand("referenced value set not supplied", refPath));
       complete = false;
       acc = /* @__PURE__ */ new Map();
       continue;
     }
     const exp = expandInternal(vs, ctx, /* @__PURE__ */ new Set([...visited, url]));
     if (!exp.complete) complete = false;
-    for (const d of exp.diagnostics) diagnostics.push(d);
+    for (const d of exp.diagnostics) diagnostics.push(underPath(d, refPath));
     const members = /* @__PURE__ */ new Map();
     for (const c of exp.contains) members.set(codingKey(c.system, c.code), c);
     acc = acc === null ? members : intersectInto(acc, members);
   }
   return { members: acc ?? /* @__PURE__ */ new Map(), complete, diagnostics };
 }
-function expandComponent(component, ctx, visited) {
+function expandComponent(component, ctx, visited, path) {
   const diagnostics = [];
   let complete = true;
   const { system, version, concept, filter, valueSet: valueSet2 } = component;
@@ -1347,18 +1359,18 @@ function expandComponent(component, ctx, visited) {
     }
   } else if (hasFilter || system !== void 0 && !hasVs) {
     if (system === void 0) {
-      diagnostics.push(cannotExpand("intensional filter without a code system 'system'"));
+      diagnostics.push(cannotExpand("intensional filter without a code system 'system'", path));
       return { members: /* @__PURE__ */ new Map(), complete: false, diagnostics };
     }
     const cs = ctx.codeSystems?.get(system);
     if (cs === void 0) {
-      diagnostics.push(cannotExpand("code system not supplied for intensional include", system));
+      diagnostics.push(cannotExpand("code system not supplied for intensional include", path));
       return { members: /* @__PURE__ */ new Map(), complete: false, diagnostics };
     }
     if (hasFilter) {
       const unsupported = unsupportedOps(filter);
       if (unsupported.length > 0) {
-        diagnostics.push(cannotExpand("unsupported filter operator", system));
+        diagnostics.push(cannotExpand("unsupported filter operator", path));
         return { members: /* @__PURE__ */ new Map(), complete: false, diagnostics };
       }
       const sub = buildSubsumption(cs);
@@ -1382,7 +1394,7 @@ function expandComponent(component, ctx, visited) {
     }
   }
   if (hasVs) {
-    const refs = expandReferencedValueSets(valueSet2, ctx, visited);
+    const refs = expandReferencedValueSets(valueSet2, ctx, visited, path);
     for (const d of refs.diagnostics) diagnostics.push(d);
     if (!refs.complete) complete = false;
     base = base === null ? refs.members : intersectInto(base, refs.members);
@@ -1407,7 +1419,7 @@ function expandInternal(vs, ctx, visited) {
     if (vs.expansion.truncated) {
       complete = false;
       diagnostics.push(
-        truncated("pre-computed expansion is incomplete (truncated or too-costly)", vs.url)
+        truncated("pre-computed expansion is incomplete (truncated or too-costly)", "expansion")
       );
     }
     const out = {
@@ -1422,14 +1434,14 @@ function expandInternal(vs, ctx, visited) {
     const included = /* @__PURE__ */ new Map();
     const diagnostics = [];
     let complete = true;
-    for (const inc of vs.compose.include) {
-      const r = expandComponent(inc, ctx, visited);
+    for (const [i, inc] of vs.compose.include.entries()) {
+      const r = expandComponent(inc, ctx, visited, `compose.include[${String(i)}]`);
       if (!r.complete) complete = false;
       for (const d of r.diagnostics) diagnostics.push(d);
       for (const [k, c] of r.members) if (!included.has(k)) included.set(k, c);
     }
-    for (const exc of vs.compose.exclude) {
-      const r = expandComponent(exc, ctx, visited);
+    for (const [i, exc] of vs.compose.exclude.entries()) {
+      const r = expandComponent(exc, ctx, visited, `compose.exclude[${String(i)}]`);
       for (const d of r.diagnostics) diagnostics.push(d);
       for (const k of r.members.keys()) included.delete(k);
       if (!r.complete) {
@@ -1456,12 +1468,17 @@ function expand(vs, ctx = {}) {
 }
 
 // src/valueset/validate.ts
-function cannotExpand2(detail, system) {
+function cannotExpand2(detail, path) {
   const d = { code: "TERM_VALUESET_CANNOT_EXPAND", detail };
-  if (system !== void 0) d.system = system;
+  if (path !== void 0) d.path = path;
   return Object.freeze(d);
 }
-function matchComponent(target, component, ctx, visited) {
+function underPath2(d, prefix) {
+  const out = { code: d.code, detail: d.detail };
+  out.path = d.path === void 0 ? prefix : `${prefix}/${d.path}`;
+  return Object.freeze(out);
+}
+function matchComponent(target, component, ctx, visited, path) {
   const diagnostics = [];
   const { system, concept, filter, valueSet: valueSet2 } = component;
   const hasConcept = concept !== void 0;
@@ -1475,18 +1492,18 @@ function matchComponent(target, component, ctx, visited) {
     baseMatched = concept.some((c) => c.code === target.code);
   } else if (hasFilter || system !== void 0 && !hasVs) {
     if (system === void 0) {
-      diagnostics.push(cannotExpand2("intensional filter without a code system 'system'"));
+      diagnostics.push(cannotExpand2("intensional filter without a code system 'system'", path));
       baseMatched = false;
       baseComplete = false;
     } else {
       const cs = ctx.codeSystems?.get(system);
       if (cs === void 0) {
-        diagnostics.push(cannotExpand2("code system not supplied for intensional include", system));
+        diagnostics.push(cannotExpand2("code system not supplied for intensional include", path));
         baseMatched = false;
         baseComplete = false;
       } else if (hasFilter) {
         if (unsupportedOps(filter).length > 0) {
-          diagnostics.push(cannotExpand2("unsupported filter operator", system));
+          diagnostics.push(cannotExpand2("unsupported filter operator", path));
           baseMatched = false;
           baseComplete = false;
         } else {
@@ -1501,21 +1518,22 @@ function matchComponent(target, component, ctx, visited) {
   let refDefiniteFalse = false;
   let refUndetermined = false;
   if (hasVs) {
-    for (const url of valueSet2) {
+    for (const [i, url] of valueSet2.entries()) {
+      const refPath = `${path}.valueSet[${String(i)}]`;
       if (visited.has(url)) {
-        diagnostics.push(cannotExpand2("cyclic value set reference", url));
+        diagnostics.push(cannotExpand2("cyclic value set reference", refPath));
         refUndetermined = true;
         continue;
       }
       const vs = ctx.valueSets?.get(url);
       if (vs === void 0) {
-        diagnostics.push(cannotExpand2("referenced value set not supplied", url));
+        diagnostics.push(cannotExpand2("referenced value set not supplied", refPath));
         refUndetermined = true;
         continue;
       }
       const m = validateInternal(target, vs, ctx, /* @__PURE__ */ new Set([...visited, url]));
       if (m.undetermined) {
-        for (const d of m.diagnostics) diagnostics.push(d);
+        for (const d of m.diagnostics) diagnostics.push(underPath2(d, refPath));
         refUndetermined = true;
       } else if (!m.result) {
         refDefiniteFalse = true;
@@ -1552,7 +1570,7 @@ function validateInternal(target, vs, ctx, visited) {
     if (found) return decided(true, target);
     if (vs.expansion.truncated) {
       return undetermined(target, [
-        cannotExpand2("pre-computed expansion is incomplete (truncated or too-costly)", vs.url)
+        cannotExpand2("pre-computed expansion is incomplete (truncated or too-costly)", "expansion")
       ]);
     }
     return decided(false, target);
@@ -1561,16 +1579,16 @@ function validateInternal(target, vs, ctx, visited) {
     const diagnostics = [];
     let includedDefinite = false;
     let anyIncludeUndetermined = false;
-    for (const inc of vs.compose.include) {
-      const m = matchComponent(target, inc, ctx, visited);
+    for (const [i, inc] of vs.compose.include.entries()) {
+      const m = matchComponent(target, inc, ctx, visited, `compose.include[${String(i)}]`);
       for (const d of m.diagnostics) diagnostics.push(d);
       if (m.complete && m.matched) includedDefinite = true;
       if (!m.complete) anyIncludeUndetermined = true;
     }
     let excludedDefinite = false;
     let anyExcludeUndetermined = false;
-    for (const exc of vs.compose.exclude) {
-      const m = matchComponent(target, exc, ctx, visited);
+    for (const [i, exc] of vs.compose.exclude.entries()) {
+      const m = matchComponent(target, exc, ctx, visited, `compose.exclude[${String(i)}]`);
       for (const d of m.diagnostics) diagnostics.push(d);
       if (m.complete && m.matched) excludedDefinite = true;
       if (!m.complete) anyExcludeUndetermined = true;
@@ -3893,32 +3911,37 @@ function power(r, p) {
   }
   return { kind: "linear", factor: Math.pow(r.factor, p), dims };
 }
-var DIMENSIONLESS = { kind: "linear", factor: 1, dims: {} };
-var atomMemo = /* @__PURE__ */ new Map();
-var inProgress = /* @__PURE__ */ new Set();
+var DIMENSIONLESS = Object.freeze({
+  kind: "linear",
+  factor: 1,
+  dims: Object.freeze({})
+});
+var atomMemo = /* @__PURE__ */ new WeakMap();
+var inProgress = /* @__PURE__ */ new WeakSet();
 function reduceAtomLinear(atom) {
   if (atom.base) return { kind: "linear", factor: 1, dims: { [atom.dim ?? atom.code]: 1 } };
   if (atom.arbitrary) return { kind: "linear", factor: 1, dims: { [`arb:${atom.code}`]: 1 } };
-  const cached2 = atomMemo.get(atom.code);
+  const cached2 = atomMemo.get(atom);
   if (cached2) return cached2;
-  if (inProgress.has(atom.code)) {
-    throw new Error(`cyclic UCUM atom definition for '${atom.code}'`);
+  if (inProgress.has(atom)) {
+    throw new Error("cyclic UCUM atom definition in the unit table");
   }
   if (!atom.value) {
-    atomMemo.set(atom.code, DIMENSIONLESS);
-    return DIMENSIONLESS;
+    throw new Error("UCUM atom has no linear definition");
   }
-  inProgress.add(atom.code);
-  const parsed = parseUcum(atom.value.unit);
-  if (!parsed.ok) {
-    inProgress.delete(atom.code);
-    throw new Error(`unparseable UCUM essence definition for '${atom.code}'`);
+  inProgress.add(atom);
+  try {
+    const parsed = parseUcum(atom.value.unit);
+    if (!parsed.ok) {
+      throw new Error("unparseable UCUM essence definition in the unit table");
+    }
+    const reduced = linearReduceTerm(parsed.node);
+    const result = multiply({ kind: "linear", factor: atom.value.factor, dims: {} }, reduced);
+    atomMemo.set(atom, result);
+    return result;
+  } finally {
+    inProgress.delete(atom);
   }
-  const reduced = linearReduceTerm(parsed.node);
-  const result = multiply({ factor: atom.value.factor, dims: {} }, reduced);
-  inProgress.delete(atom.code);
-  atomMemo.set(atom.code, result);
-  return result;
 }
 function reduceSimpleLinear(node) {
   const base = reduceAtomLinear(node.atom);
@@ -3938,7 +3961,7 @@ function linearReduceComponent(comp) {
   }
 }
 function linearReduceTerm(node) {
-  let acc = DIMENSIONLESS;
+  let acc = { kind: "linear", factor: 1, dims: {} };
   for (const { sign, node: comp } of node.factors) {
     acc = multiply(acc, power(linearReduceComponent(comp), sign));
   }
@@ -4120,10 +4143,15 @@ function applyGem(map, source) {
   if (combinations !== void 0) matched.combinations = combinations;
   return Object.freeze(matched);
 }
+var NOT_INVERTIBLE_MESSAGE = /* @__PURE__ */ new Map([
+  ["9-to-10", "GEM map (direction 9-to-10) cannot be inverted \u2014 load the 10-to-9 GEM file instead"],
+  ["10-to-9", "GEM map (direction 10-to-9) cannot be inverted \u2014 load the 9-to-10 GEM file instead"]
+]);
+var NOT_INVERTIBLE_UNKNOWN_DIRECTION = "GEM map cannot be inverted \u2014 load the reverse GEM file instead";
 function invertGem(map) {
   throw new TerminologyError(
     FATAL_CODES.TERM_MAP_NOT_INVERTIBLE,
-    `GEM map (direction ${map.direction}) cannot be inverted \u2014 load the reverse GEM file instead`
+    NOT_INVERTIBLE_MESSAGE.get(map.direction) ?? NOT_INVERTIBLE_UNKNOWN_DIRECTION
   );
 }
 
@@ -4703,7 +4731,7 @@ function approximateMatch(graph, query, options = {}) {
 }
 
 // src/index.ts
-var VERSION = "0.0.4";
+var VERSION = "0.0.6";
 
 exports.COMPLEX_MAP_SOURCE_SYSTEM = COMPLEX_MAP_SOURCE_SYSTEM;
 exports.DIAGNOSTIC_CODES = DIAGNOSTIC_CODES;