@cosyte/terminology 0.0.5 → 0.0.7

package/dist/index.d.cts

@@ -100,10 +100,63 @@ declare function codeableConcept(init: CodeableConcept): CodeableConcept;
  * them, so renaming or removing one is a **breaking change**, and the full set is snapshotted via
  * `sortedCodeSet` (`@cosyte/test-utils`) as a reviewable tripwire.
  *
- * **Value-free by construction.** A diagnostic carries a stable code plus, at most, a
- * code + system + version — **never** a surrounding patient identifier or clinical narrative. A
- * code *in patient context* can be PHI, so messages describe *structure* (a resource
- * path, a code system), never echo arbitrary input *values*.
+ * **Value-free by construction**, and the property is stated as what it actually is: every string a
+ * diagnostic or fatal message is assembled from is **owned by the engine**. Three kinds, and no
+ * fourth: a string literal; an entry in a frozen table keyed on the engine's own vocabulary; and a
+ * **locus this package built** — a 1-based `line`, a column count, or an index path over the
+ * caller's own resource made of integers and FHIR field names (`ConceptMap group[0].element[0].target[0]`,
+ * `compose.include[2]`). Nothing a caller configured and nothing their release or resource contained
+ * is ever one of them, so no such string reaches a `message`, a `stack`, or a `detail`, at any
+ * length.
+ *
+ * Read that as the rule, and note what it does **not** say. It does not say no factory takes a
+ * `string` parameter. Several do: `malformed(path, fault)` in `conceptmap/load.ts` and
+ * `valueset/load.ts`, and `cannotExpand(detail, path)`, `truncated(detail, path)` and
+ * `underPath(d, prefix)` in `valueset/` — where `expand.ts` and `validate.ts` each carry their own
+ * copy. It says every **argument** reaching them is engine-owned: each `fault` and `detail` is a
+ * literal at the call site, each `path` and `prefix` is built from indices by the loader that
+ * raises it. That distinction is the thing to preserve — an absolute "no factory takes a value
+ * parameter" reads as a stronger guarantee than the one the code makes, and those factories are the
+ * counter-example to it. Do not write the count down; derive it.
+ *
+ * Positional context is value-free the same way: a `line` integer, an `ExpansionDiagnostic.path`
+ * index path into the caller's own resource (`compose.include[2]`), or a closed-set token
+ * (`RXNCONSO` / `RXNREL` / `RXNSAT`) — never a URI, a column name, or a field the file supplied.
+ * This matters because a code *in patient context* can be PHI, and a thrown error is the one surface
+ * that reaches a log or an error reporter without the consumer choosing to put it there.
+ *
+ * **▶ THE CLAIM IS ABOUT THE MESSAGE FIELDS, NOT ABOUT THE OBJECTS. DO NOT SHORTEN IT TO "A
+ * DIAGNOSTIC IS SAFE TO LOG".** The safe strings are the *message* fields:
+ * `TerminologyError.message` / `.stack`, `LoadWarning.detail`, `GemLoadWarning.detail`,
+ * `ComplexMapLoadWarning.detail`, `RxNormLoadWarning.detail`, `ExpansionDiagnostic.detail`,
+ * `ParseFailure.reason` and `UcumValidation.reason`, plus the loci beside them.
+ *
+ * The **objects** these codes appear on are a different matter, and they carry verbatim text from
+ * two *different* provenances, which decide differently:
+ *
+ * - **Your query, echoed back** — `LookupUnknown.input`, `LookupResult.code`, `UnknownSystem.input`,
+ *   `TranslateUnmapped.source`, `CrosswalkUnmapped.source`, `CrosswalkNoMap.source`,
+ *   `RxNormUnknown.rxcui`, `RxNormRelated.predicates`, `NdcUnmapped.ndc`,
+ *   `ValueSetMembership.coding`, and **`MapProvenance.sourceSystem`** — which is the `system` off
+ *   the `Coding` you passed to `translate`, verbatim and unbounded, whenever that coding
+ *   carries one; the map's own `group.source` is only the fallback for a coding that does not. The
+ *   query is the one genuinely **patient-derived** input this engine takes (a code off a parsed
+ *   message, a unit off an observation, an NDC off a prescription), so this is the class that
+ *   decides a PHI question.
+ * - **Your loaded artifact, carried through** — `ComplexMapContextRequired.rules` (the map
+ *   document's own `rule` / `advice` text) and `MapProvenance.targetSystem` / `.conceptMapUrl` /
+ *   `.conceptMapVersion`, which are read off the loaded map (`group.target`, `map.url`,
+ *   `map.version`). These are *reference data*, bounded by the map or release you loaded, not by
+ *   anything a patient supplied. **`MapProvenance` straddles the two lists** — do not read the whole
+ *   record as reference data on the strength of the fields that are.
+ *
+ * Read both lists as illustrative, not closed: **assume any result field may hold what you passed
+ * in.** So `JSON.stringify(lookupResult)` into a log is a PHI decision, and `String(err)` is not.
+ * Log the `code` and the locus; log a value only if you would log the code you passed in.
+ *
+ * Those echoes are deliberate and are not going away: they are how a never-fabricate outcome says
+ * *which* thing it refused to guess, they are the caller's own data returned to the caller, and
+ * bounding them would mean fabricating a miss.
  *
  * @packageDocumentation
  */
@@ -318,8 +371,10 @@ type FatalCode = (typeof FATAL_CODES)[keyof typeof FATAL_CODES];
  * The engine's typed error. Carries a stable {@link FatalCode} so callers branch on `err.code`
  * without string-matching the message. Thrown only for {@link FATAL_CODES} conditions.
  *
- * The `message` is **value-free**: it names the structural fault (a resource path, a missing
- * field) and never echoes input *values*.
+ * The `message` is **value-free**: it names the structural fault (a resource path, a missing field,
+ * the *role* of a configured column) and never echoes an input value — so it is safe to log, and
+ * safe in an `err.stack` that reaches an error reporter. The rule the strings are built by is in
+ * this module's docblock above.
  *
  * @example
  * ```ts
@@ -338,6 +393,9 @@ declare 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: FatalCode, message: string);
 }
@@ -611,7 +669,13 @@ interface MapProvenance {
     readonly conceptMapUrl?: string;
     /** The ConceptMap's business `version`, when declared (mappings are release-scoped). */
     readonly conceptMapVersion?: string;
-    /** The source code system of the group that matched (or was consulted), when known. */
+    /**
+     * The source code system for this translation. **This is an echo of your query, not reference
+     * data off the map**: it is the `system` on the `Coding` you passed to `translate`, verbatim and
+     * unbounded, whenever that coding carries one; the matched (or consulted) group's own `source` is
+     * only the fallback for a coding that does not. Log it only if you would log the code you passed
+     * in.
+     */
     readonly sourceSystem?: string;
     /** The target code system of the group that matched, when known. */
     readonly targetSystem?: string;
@@ -1272,6 +1336,9 @@ declare function parseRrf(source: RrfSource): {
  * surfaced** as a `TERM_CSV_MALFORMED` warning; an unterminated final quote is surfaced too — never a
  * crash. A configured code/display header that is **absent from the header row** is a *fatal*
  * (`TERM_CODESYSTEM_MALFORMED`): the source config does not match the file, so nothing loads cleanly.
+ * That fatal names the missing column's **role** (`code`, `display`, `status`, a property column)
+ * from a frozen table, never the column name you configured — the message reaches `err.stack`, and a
+ * column name is consumer-supplied text of unbounded length.
  *
  * @packageDocumentation
  */
@@ -1296,7 +1363,8 @@ declare function parseCsv(content: string): string[][];
  * @param source - The CSV source.
  * @returns The parsed concepts (by code) and the load warnings.
  * @throws {TerminologyError} `TERM_CODESYSTEM_MALFORMED` when the file has no header row, or a
- *   configured `code`/`display`/`status`/property column is absent from the header.
+ *   configured `code`/`display`/`status`/property column is absent from the header. The message
+ *   names the missing column's **role**, never the name you configured.
  * @example
  * ```ts
  * import { parseCsvSource } from "@cosyte/terminology";
@@ -1607,8 +1675,18 @@ interface ExpansionDiagnostic {
     readonly code: DiagnosticCode;
     /** A **value-free** structural description of the concern (never echoes a patient value). */
     readonly detail: string;
-    /** The code system / value set URI the concern is about (a published identity — not PHI). */
-    readonly system?: string;
+    /**
+     * A **value-free structural locus** into the caller's own resource — `"expansion"`, or a
+     * `compose`-relative index path such as `"compose.include[2]"` or
+     * `"compose.include[0].valueSet[1]"`. A diagnostic raised while expanding a *referenced* value set
+     * is prefixed with the reference that reached it (`"compose.include[0].valueSet[1]/compose.include[3]"`).
+     *
+     * Built entirely from integers and the engine's own field names, so nothing the caller or their
+     * resource supplied can reach it, at any length. It replaces the URI this field used to carry:
+     * a canonical URI is unbounded consumer-supplied text on a diagnostic surface, and an index path
+     * is strictly more precise anyway (two `include`s may name the same system).
+     */
+    readonly path?: string;
 }
 /**
  * The result of {@link expand}: the flattened membership plus an honest **completeness** signal.
@@ -2160,8 +2238,20 @@ declare function parseUcum(unit: string): ParseResult;
  * Reduce a parsed UCUM unit to its canonical {@link Reduction} — a linear scalar×dimension form, or
  * an opaque `special` form for expressions involving a non-linear special unit.
  *
+ * The reduction of one atom is cached against **that atom object**, so a `UnitNode` you assembled
+ * yourself is answered from its own atoms and cannot change how a unit off {@link parseUcum} reduces,
+ * in this call or any later one.
+ *
  * @param node - The AST from {@link parseUcum}.
  * @returns The reduced form.
+ * @throws {Error} If reducing `node` reaches an atom with no linear definition, or one whose
+ *   definition does not parse. **No expression {@link parseUcum} accepts reaches either**; a node
+ *   you assemble yourself can, including by defining an atom in terms of a special unit such as
+ *   `Cel`, which lands on the table's own `Cel`. A third guard catches a definition that leads back
+ *   to itself. Naming a table atom does not reach it — a definition is resolved against the loaded
+ *   table, so your atom can name one but never be one — and neither does the table itself, which is
+ *   frozen; what reaches it is a `value` accessor that re-enters `reduce` for the same atom while
+ *   that atom is still being reduced. The message names the fault, never the atom.
  * @example
  * ```ts
  * import { parseUcum, reduce } from "@cosyte/terminology";
@@ -2192,7 +2282,13 @@ declare function reduce(node: UnitNode): Reduction;
 /**
  * Load the UCUM essence table, parsing the embedded verbatim XML on first call and caching it.
  *
- * @returns The immutable in-memory {@link UcumEssence} model (7 base units, 24 prefixes, ~305 atoms).
+ * One table is shared by every caller and by the engine itself, so it is handed out **frozen**: an
+ * atom's definition cannot be rewritten in place, and neither can the `atoms` array the parser
+ * scans. It used to be, and doing so before that atom's first reduction poisoned the
+ * reduction memo for the life of the process — a fabricated unit equivalence that survived putting
+ * the table back. A write is refused, which in strict mode means a `TypeError`.
+ *
+ * @returns The shared, frozen in-memory {@link UcumEssence} model.
  * @example
  * ```ts
  * import { loadUcumEssence } from "@cosyte/terminology";

package/dist/index.d.ts

@@ -100,10 +100,63 @@ declare function codeableConcept(init: CodeableConcept): CodeableConcept;
  * them, so renaming or removing one is a **breaking change**, and the full set is snapshotted via
  * `sortedCodeSet` (`@cosyte/test-utils`) as a reviewable tripwire.
  *
- * **Value-free by construction.** A diagnostic carries a stable code plus, at most, a
- * code + system + version — **never** a surrounding patient identifier or clinical narrative. A
- * code *in patient context* can be PHI, so messages describe *structure* (a resource
- * path, a code system), never echo arbitrary input *values*.
+ * **Value-free by construction**, and the property is stated as what it actually is: every string a
+ * diagnostic or fatal message is assembled from is **owned by the engine**. Three kinds, and no
+ * fourth: a string literal; an entry in a frozen table keyed on the engine's own vocabulary; and a
+ * **locus this package built** — a 1-based `line`, a column count, or an index path over the
+ * caller's own resource made of integers and FHIR field names (`ConceptMap group[0].element[0].target[0]`,
+ * `compose.include[2]`). Nothing a caller configured and nothing their release or resource contained
+ * is ever one of them, so no such string reaches a `message`, a `stack`, or a `detail`, at any
+ * length.
+ *
+ * Read that as the rule, and note what it does **not** say. It does not say no factory takes a
+ * `string` parameter. Several do: `malformed(path, fault)` in `conceptmap/load.ts` and
+ * `valueset/load.ts`, and `cannotExpand(detail, path)`, `truncated(detail, path)` and
+ * `underPath(d, prefix)` in `valueset/` — where `expand.ts` and `validate.ts` each carry their own
+ * copy. It says every **argument** reaching them is engine-owned: each `fault` and `detail` is a
+ * literal at the call site, each `path` and `prefix` is built from indices by the loader that
+ * raises it. That distinction is the thing to preserve — an absolute "no factory takes a value
+ * parameter" reads as a stronger guarantee than the one the code makes, and those factories are the
+ * counter-example to it. Do not write the count down; derive it.
+ *
+ * Positional context is value-free the same way: a `line` integer, an `ExpansionDiagnostic.path`
+ * index path into the caller's own resource (`compose.include[2]`), or a closed-set token
+ * (`RXNCONSO` / `RXNREL` / `RXNSAT`) — never a URI, a column name, or a field the file supplied.
+ * This matters because a code *in patient context* can be PHI, and a thrown error is the one surface
+ * that reaches a log or an error reporter without the consumer choosing to put it there.
+ *
+ * **▶ THE CLAIM IS ABOUT THE MESSAGE FIELDS, NOT ABOUT THE OBJECTS. DO NOT SHORTEN IT TO "A
+ * DIAGNOSTIC IS SAFE TO LOG".** The safe strings are the *message* fields:
+ * `TerminologyError.message` / `.stack`, `LoadWarning.detail`, `GemLoadWarning.detail`,
+ * `ComplexMapLoadWarning.detail`, `RxNormLoadWarning.detail`, `ExpansionDiagnostic.detail`,
+ * `ParseFailure.reason` and `UcumValidation.reason`, plus the loci beside them.
+ *
+ * The **objects** these codes appear on are a different matter, and they carry verbatim text from
+ * two *different* provenances, which decide differently:
+ *
+ * - **Your query, echoed back** — `LookupUnknown.input`, `LookupResult.code`, `UnknownSystem.input`,
+ *   `TranslateUnmapped.source`, `CrosswalkUnmapped.source`, `CrosswalkNoMap.source`,
+ *   `RxNormUnknown.rxcui`, `RxNormRelated.predicates`, `NdcUnmapped.ndc`,
+ *   `ValueSetMembership.coding`, and **`MapProvenance.sourceSystem`** — which is the `system` off
+ *   the `Coding` you passed to `translate`, verbatim and unbounded, whenever that coding
+ *   carries one; the map's own `group.source` is only the fallback for a coding that does not. The
+ *   query is the one genuinely **patient-derived** input this engine takes (a code off a parsed
+ *   message, a unit off an observation, an NDC off a prescription), so this is the class that
+ *   decides a PHI question.
+ * - **Your loaded artifact, carried through** — `ComplexMapContextRequired.rules` (the map
+ *   document's own `rule` / `advice` text) and `MapProvenance.targetSystem` / `.conceptMapUrl` /
+ *   `.conceptMapVersion`, which are read off the loaded map (`group.target`, `map.url`,
+ *   `map.version`). These are *reference data*, bounded by the map or release you loaded, not by
+ *   anything a patient supplied. **`MapProvenance` straddles the two lists** — do not read the whole
+ *   record as reference data on the strength of the fields that are.
+ *
+ * Read both lists as illustrative, not closed: **assume any result field may hold what you passed
+ * in.** So `JSON.stringify(lookupResult)` into a log is a PHI decision, and `String(err)` is not.
+ * Log the `code` and the locus; log a value only if you would log the code you passed in.
+ *
+ * Those echoes are deliberate and are not going away: they are how a never-fabricate outcome says
+ * *which* thing it refused to guess, they are the caller's own data returned to the caller, and
+ * bounding them would mean fabricating a miss.
  *
  * @packageDocumentation
  */
@@ -318,8 +371,10 @@ type FatalCode = (typeof FATAL_CODES)[keyof typeof FATAL_CODES];
  * The engine's typed error. Carries a stable {@link FatalCode} so callers branch on `err.code`
  * without string-matching the message. Thrown only for {@link FATAL_CODES} conditions.
  *
- * The `message` is **value-free**: it names the structural fault (a resource path, a missing
- * field) and never echoes input *values*.
+ * The `message` is **value-free**: it names the structural fault (a resource path, a missing field,
+ * the *role* of a configured column) and never echoes an input value — so it is safe to log, and
+ * safe in an `err.stack` that reaches an error reporter. The rule the strings are built by is in
+ * this module's docblock above.
  *
  * @example
  * ```ts
@@ -338,6 +393,9 @@ declare 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: FatalCode, message: string);
 }
@@ -611,7 +669,13 @@ interface MapProvenance {
     readonly conceptMapUrl?: string;
     /** The ConceptMap's business `version`, when declared (mappings are release-scoped). */
     readonly conceptMapVersion?: string;
-    /** The source code system of the group that matched (or was consulted), when known. */
+    /**
+     * The source code system for this translation. **This is an echo of your query, not reference
+     * data off the map**: it is the `system` on the `Coding` you passed to `translate`, verbatim and
+     * unbounded, whenever that coding carries one; the matched (or consulted) group's own `source` is
+     * only the fallback for a coding that does not. Log it only if you would log the code you passed
+     * in.
+     */
     readonly sourceSystem?: string;
     /** The target code system of the group that matched, when known. */
     readonly targetSystem?: string;
@@ -1272,6 +1336,9 @@ declare function parseRrf(source: RrfSource): {
  * surfaced** as a `TERM_CSV_MALFORMED` warning; an unterminated final quote is surfaced too — never a
  * crash. A configured code/display header that is **absent from the header row** is a *fatal*
  * (`TERM_CODESYSTEM_MALFORMED`): the source config does not match the file, so nothing loads cleanly.
+ * That fatal names the missing column's **role** (`code`, `display`, `status`, a property column)
+ * from a frozen table, never the column name you configured — the message reaches `err.stack`, and a
+ * column name is consumer-supplied text of unbounded length.
  *
  * @packageDocumentation
  */
@@ -1296,7 +1363,8 @@ declare function parseCsv(content: string): string[][];
  * @param source - The CSV source.
  * @returns The parsed concepts (by code) and the load warnings.
  * @throws {TerminologyError} `TERM_CODESYSTEM_MALFORMED` when the file has no header row, or a
- *   configured `code`/`display`/`status`/property column is absent from the header.
+ *   configured `code`/`display`/`status`/property column is absent from the header. The message
+ *   names the missing column's **role**, never the name you configured.
  * @example
  * ```ts
  * import { parseCsvSource } from "@cosyte/terminology";
@@ -1607,8 +1675,18 @@ interface ExpansionDiagnostic {
     readonly code: DiagnosticCode;
     /** A **value-free** structural description of the concern (never echoes a patient value). */
     readonly detail: string;
-    /** The code system / value set URI the concern is about (a published identity — not PHI). */
-    readonly system?: string;
+    /**
+     * A **value-free structural locus** into the caller's own resource — `"expansion"`, or a
+     * `compose`-relative index path such as `"compose.include[2]"` or
+     * `"compose.include[0].valueSet[1]"`. A diagnostic raised while expanding a *referenced* value set
+     * is prefixed with the reference that reached it (`"compose.include[0].valueSet[1]/compose.include[3]"`).
+     *
+     * Built entirely from integers and the engine's own field names, so nothing the caller or their
+     * resource supplied can reach it, at any length. It replaces the URI this field used to carry:
+     * a canonical URI is unbounded consumer-supplied text on a diagnostic surface, and an index path
+     * is strictly more precise anyway (two `include`s may name the same system).
+     */
+    readonly path?: string;
 }
 /**
  * The result of {@link expand}: the flattened membership plus an honest **completeness** signal.
@@ -2160,8 +2238,20 @@ declare function parseUcum(unit: string): ParseResult;
  * Reduce a parsed UCUM unit to its canonical {@link Reduction} — a linear scalar×dimension form, or
  * an opaque `special` form for expressions involving a non-linear special unit.
  *
+ * The reduction of one atom is cached against **that atom object**, so a `UnitNode` you assembled
+ * yourself is answered from its own atoms and cannot change how a unit off {@link parseUcum} reduces,
+ * in this call or any later one.
+ *
  * @param node - The AST from {@link parseUcum}.
  * @returns The reduced form.
+ * @throws {Error} If reducing `node` reaches an atom with no linear definition, or one whose
+ *   definition does not parse. **No expression {@link parseUcum} accepts reaches either**; a node
+ *   you assemble yourself can, including by defining an atom in terms of a special unit such as
+ *   `Cel`, which lands on the table's own `Cel`. A third guard catches a definition that leads back
+ *   to itself. Naming a table atom does not reach it — a definition is resolved against the loaded
+ *   table, so your atom can name one but never be one — and neither does the table itself, which is
+ *   frozen; what reaches it is a `value` accessor that re-enters `reduce` for the same atom while
+ *   that atom is still being reduced. The message names the fault, never the atom.
  * @example
  * ```ts
  * import { parseUcum, reduce } from "@cosyte/terminology";
@@ -2192,7 +2282,13 @@ declare function reduce(node: UnitNode): Reduction;
 /**
  * Load the UCUM essence table, parsing the embedded verbatim XML on first call and caching it.
  *
- * @returns The immutable in-memory {@link UcumEssence} model (7 base units, 24 prefixes, ~305 atoms).
+ * One table is shared by every caller and by the engine itself, so it is handed out **frozen**: an
+ * atom's definition cannot be rewritten in place, and neither can the `atoms` array the parser
+ * scans. It used to be, and doing so before that atom's first reduction poisoned the
+ * reduction memo for the life of the process — a fabricated unit equivalence that survived putting
+ * the table back. A write is refused, which in strict mode means a `TypeError`.
+ *
+ * @returns The shared, frozen in-memory {@link UcumEssence} model.
  * @example
  * ```ts
  * import { loadUcumEssence } from "@cosyte/terminology";