@cosyte/astm 0.0.22 → 0.1.1

package/dist/index.d.ts

@@ -858,7 +858,9 @@ declare function unpairedEscapeCharacter(position: AstmPosition): AstmRecordWarn
 declare function ambiguousValueSplit(position: AstmPosition): AstmRecordWarning;
 /**
  * Build an `ASTM_RECORD_UNDEFINED_ABNORMAL_FLAG` warning. The flag is surfaced as
- * `undefined` (never coerced to `normal`); the warning carries only the position.
+ * `undefined` (never coerced to `normal`); the warning carries only the position
+ * and fixed prose naming the **same** vocabulary the interpreted flag reports,
+ * read from the one shared constant so the two cannot drift apart.
  *
  * @example
  * ```ts
@@ -870,6 +872,8 @@ declare function undefinedAbnormalFlag(position: AstmPosition): AstmRecordWarnin
 /**
  * Build an `ASTM_RECORD_UNDEFINED_RESULT_STATUS` warning. The status is surfaced
  * as `undefined` and, like every non-final status, never reads as active-final.
+ * The message carries the **same** attribution the interpreted status reports
+ * (there is no citable source for this letter set), from the one shared constant.
  *
  * @example
  * ```ts
@@ -1254,22 +1258,30 @@ declare function astmDateToLocalISO(d: AstmDate): string;
  * spec's component order is LOINC-slot / test-name / coding-scheme / local-code.
  * In the field the way real analyzers emit it:
  *
- * - **component 1** is a LOINC slot: *almost always empty*; a few vendors place
- *   an inline LOINC when one exists;
+ * - **component 1** is a LOINC slot: *almost always empty*, and the governing
+ *   mapping guide puts LOINC on the instrument wire explicitly out of scope, so
+ *   whatever arrives there is a wire value this library **does not vouch for**
+ *   and never treats as an identifier;
  * - **component 4** is the vendor/local code: the identifier that is actually
- *   present, and therefore the **primary** identifier here.
+ *   present, and therefore the **only** identifier a result is keyed on here.
  *
  * Following the sibling parsers' conservative posture, this module is a
  * **structural recognizer, not a dictionary**: it tags where a code came from
  * (its provenance) and surfaces every code verbatim. It does not look codes up,
- * does not validate them, and bundles no LOINC/SNOMED tables.
+ * does not validate them, and bundles no LOINC/SNOMED tables. In particular it
+ * performs **no LOINC validation of any kind** and never decides what a
+ * first-component value "looks like": `2345-7` and `Glucose` in component 1 are
+ * treated identically, and the routing is positional throughout.
  */
 /** Where a Universal Test ID's usable identifier came from. */
 type UniversalTestIdProvenance = 
-/** Component 1 (the LOINC slot) is populated: a candidate LOINC, recognized not validated. */
-"inline-loinc-candidate"
 /** Component 4 (the vendor/local code) carries the identifier. */
- | "local-code"
+"local-code"
+/**
+ * Component 1 is populated and there is no vendor/local code, so there is **no**
+ * identifier: the value is surfaced unvalidated and is never keyed on.
+ */
+ | "unvalidated-wire-value-only"
 /** Only the test name (component 2) is present: no code. */
  | "name-only"
 /** Nothing usable in the field. */
@@ -1289,13 +1301,17 @@ type UniversalTestIdProvenance =
 interface UniversalTestId {
     /** The field's components, verbatim and in order. */
     readonly components: readonly string[];
-    /** Component 1 when populated: a *candidate* LOINC (provenance only, never validated). */
-    readonly loincCandidate?: string;
+    /**
+     * Component 1 when populated, verbatim: a wire value this library **does not
+     * vouch for**. It is not validated, is not reported as a LOINC or a LOINC
+     * candidate, and is never the code a result is keyed on.
+     */
+    readonly unvalidatedWireValue?: string;
     /** Component 2: the test / battery name, when present. */
     readonly testName?: string;
     /** Component 3: the coding-scheme selector, when present. */
     readonly codingScheme?: string;
-    /** Component 4, the vendor/local code: the primary identifier when no inline LOINC is given. */
+    /** Component 4, the vendor/local code: the only identifier a result is keyed on. */
     readonly localCode?: string;
     /** Where the primary identifier came from. */
     readonly provenance: UniversalTestIdProvenance;
@@ -1303,6 +1319,9 @@ interface UniversalTestId {
 /**
  * Recognize a Universal Test ID from a field's already-decoded components.
  *
+ * The provenance is decided **positionally**, by which components are populated,
+ * and never by what a value looks like.
+ *
  * @param components - The component strings (escape-decoded), in order.
  * @returns The recognized, provenance-tagged Universal Test ID.
  * @example
@@ -1313,16 +1332,18 @@ interface UniversalTestId {
  */
 declare function recognizeUniversalTestId(components: readonly string[]): UniversalTestId;
 /**
- * The primary code to key a result on: the inline LOINC candidate when a vendor
- * supplied one, otherwise the local (vendor) code. Returns `undefined` when the
- * field carries no code at all (name-only or empty): never a guess.
+ * The primary code to key a result on: the local (vendor) code, and nothing else.
+ * Returns `undefined` when the field carries no vendor/local code, **including**
+ * when component 1 is populated: never a guess, and never a value this library
+ * does not vouch for. Read `unvalidatedWireValue` for that value.
  *
  * @param u - A recognized Universal Test ID.
- * @returns The primary code, or `undefined`.
+ * @returns The vendor/local code, or `undefined`.
  * @example
  * ```ts
  * import { primaryCode, recognizeUniversalTestId } from "@cosyte/astm";
- * primaryCode(recognizeUniversalTestId(["2345-7", "Glucose", "LN", "687"])); // "2345-7"
+ * primaryCode(recognizeUniversalTestId(["2345-7", "Glucose", "LN", "687"])); // "687"
+ * primaryCode(recognizeUniversalTestId(["Glucose", "", "", ""]));            // undefined
  * ```
  */
 declare function primaryCode(u: UniversalTestId): string | undefined;
@@ -1348,7 +1369,7 @@ declare function primaryCode(u: UniversalTestId): string | undefined;
  */
 interface AstmFramePosition {
     /**
-     * The frame's sequence number (`0`–`7`) when it could be read, or `undefined`
+     * The frame's sequence number (`0` to `7`) when it could be read, or `undefined`
      * when the frame was so truncated the number was not present.
      */
     readonly frameNumber?: number;
@@ -1837,6 +1858,127 @@ interface DefineAstmProfileOptions {
     readonly extends?: AstmProfile | readonly AstmProfile[];
 }
 
+/**
+ * Vocabulary attribution for the code sets this library grades wire letters
+ * against.
+ *
+ * An `R` record carries single letters whose meaning comes from a published
+ * vocabulary, and the ASTM record grammar itself is frozen while those
+ * vocabularies keep moving. Reporting a letter as "unrecognized" without saying
+ * what it was compared against therefore hides a staleness: a consumer cannot
+ * tell a code no published vocabulary defines from a code this library has
+ * simply not caught up to.
+ *
+ * So every interpreted value carries an attribution, and the attribution has
+ * exactly two shapes:
+ *
+ * - {@link NamedVocabulary}: a published code system, named by identifier and
+ *   version. **The version says what this library compared against; it is not a
+ *   claim about which version the sender meant.**
+ * - {@link UnattributedVocabulary}: no citable published source. This is a
+ *   positive statement, deliberately distinguishable from an attribution that is
+ *   simply absent, and it never carries a code-system identifier.
+ *
+ * These constants are the single source of truth: the interpreted value and the
+ * warning raised beside it both read them, so the two can never drift apart.
+ */
+/**
+ * A published code system this library graded a value against, named by
+ * identifier and version.
+ *
+ * @example
+ * ```ts
+ * import { ABNORMAL_FLAG_VOCABULARY } from "@cosyte/astm";
+ * ABNORMAL_FLAG_VOCABULARY.attributed; // true
+ * ABNORMAL_FLAG_VOCABULARY.version;    // the version compared against
+ * ```
+ */
+interface NamedVocabulary {
+    /** Always `true`: a published source is cited. */
+    readonly attributed: true;
+    /** The code system's canonical identifier, verbatim from the published source. */
+    readonly system: string;
+    /**
+     * The code system version this library compared against, verbatim from the
+     * published source. **Not** a claim about the version the sender used.
+     */
+    readonly version: string;
+}
+/**
+ * The explicit statement that a code set is bound by **no citable published
+ * source**. It carries no identifier and no version, because inventing either
+ * would be the guess this library exists to refuse.
+ *
+ * @example
+ * ```ts
+ * import { RESULT_STATUS_VOCABULARY } from "@cosyte/astm";
+ * RESULT_STATUS_VOCABULARY.attributed; // false
+ * RESULT_STATUS_VOCABULARY.reason;     // fixed prose: why nothing is cited
+ * ```
+ */
+interface UnattributedVocabulary {
+    /** Always `false`: no published source can be cited for this code set. */
+    readonly attributed: false;
+    /** Fixed prose saying why nothing is cited. Never a code-system identifier. */
+    readonly reason: string;
+}
+/**
+ * What an interpreted wire letter was graded against: either a named published
+ * code system or an explicit "no citable source". Discriminate on
+ * {@link NamedVocabulary.attributed}.
+ */
+type VocabularyAttribution = NamedVocabulary | UnattributedVocabulary;
+/**
+ * The vocabulary the `R` record's abnormal-flag letters (field 7) are graded
+ * against: the HL7 v3 ObservationInterpretation code system, which carries the
+ * concepts kept aligned with the HL7 v2 Table 0078 interpretation codes this
+ * library has always recognized.
+ *
+ * The identifier and version are transcribed character for character from that
+ * code system's published source of truth. **The version records what this
+ * library compared against, not what the sender meant.**
+ *
+ * @example
+ * ```ts
+ * import { ABNORMAL_FLAG_VOCABULARY, interpretAbnormalFlag } from "@cosyte/astm";
+ * interpretAbnormalFlag("HU").vocabulary === ABNORMAL_FLAG_VOCABULARY; // true
+ * ```
+ */
+declare const ABNORMAL_FLAG_VOCABULARY: NamedVocabulary;
+/**
+ * The attribution for the `R` record's result-status letters (field 9): **none**.
+ *
+ * The letters this library models are the ones real analyzers send, but the
+ * normative text that would bind them to a published code set is purchase-gated
+ * and has not been read here. A neighbouring HL7 table exists whose letters
+ * partly agree, and adopting it would be an assertion nothing in the public
+ * record supports. So this library says the set is unattributed rather than
+ * citing a source it cannot stand behind.
+ *
+ * @example
+ * ```ts
+ * import { interpretResultStatus } from "@cosyte/astm";
+ * interpretResultStatus("F").vocabulary.attributed; // false
+ * ```
+ */
+declare const RESULT_STATUS_VOCABULARY: UnattributedVocabulary;
+/**
+ * Render a vocabulary attribution as fixed prose for a warning message.
+ *
+ * The result is a function of the attribution constants alone: it embeds no
+ * field text, no value, and no position, so a warning built with it stays
+ * value-free.
+ *
+ * @param vocabulary - The attribution to describe.
+ * @returns Fixed prose naming the code system and version, or the unattributed reason.
+ * @example
+ * ```ts
+ * import { describeVocabulary, ABNORMAL_FLAG_VOCABULARY } from "@cosyte/astm";
+ * describeVocabulary(ABNORMAL_FLAG_VOCABULARY); // "graded against <system> version <version>"
+ * ```
+ */
+declare function describeVocabulary(vocabulary: VocabularyAttribution): string;
+
 /**
  * Safety-critical result semantics for the ASTM `R` (result) record.
  *
@@ -1844,9 +1986,9 @@ interface DefineAstmProfileOptions {
  * fields **raw**. This module turns those raw letters into modeled, **fail-safe**
  * semantics, under one rule: **never a confident wrong value.**
  *
- * - An **abnormal flag** (field 7) is recognized against HL7 Table 0078; an
- *   unrecognized flag is surfaced as `undefined` (with a warning) and is **never
- *   coerced to `normal`**.
+ * - An **abnormal flag** (field 7) is recognized against a **named** published
+ *   vocabulary; an unrecognized flag is surfaced as `undefined` (with a warning)
+ *   and is **never coerced to `normal`**.
  * - A **result status** (field 9) is modeled so a **correction (`C`)** or a
  *   **cancellation (`X`)** can never read as an active-final result, and an
  *   **absent** status is a typed `unspecified`: **never assumed `F` (final)**.
@@ -1854,54 +1996,91 @@ interface DefineAstmProfileOptions {
  *   pair; an unparseable range is surfaced **verbatim**, a bound is **never
  *   fabricated**.
  *
+ * Every interpreted flag and status also carries the **vocabulary it was graded
+ * against**, recognized or not, so an unknown code is distinguishable from one
+ * this library has not caught up to. The status set's attribution is the
+ * explicit "no citable published source": see `../common/vocabulary.js`.
+ *
  * Every bound and code is surfaced verbatim; nothing is collapsed, reconciled,
  * or converted. Units are handled at the record layer (a numeric value without
  * units warns; units are never defaulted, guessed, or converted, see
  * `./parse.ts`).
  */
+
+/**
+ * The recognized abnormal-flag letters, graded against
+ * {@link ABNORMAL_FLAG_VOCABULARY} (the flag *value* set, a published fact set,
+ * not CLSI prose). That code system carries the concepts kept aligned with the
+ * HL7 v2 Table 0078 interpretation codes. Read in the context of an `R` record's
+ * field 7: here `S`/`R`/`I` are the microbiology susceptibility codes and `R` is
+ * **not** the repeat delimiter.
+ *
+ * Recognition is **exact match** after the surrounding whitespace is trimmed:
+ * letter case is never folded, so `hu` is unrecognized and stays that way.
+ */
+type AbnormalFlagCode = "L" | "H" | "LL" | "HH" | "<" | ">" | "N" | "A" | "AA" | "U" | "D" | "B" | "W" | "S" | "R" | "I" | "HU" | "LU";
 /**
- * The recognized abnormal-flag letters, from **HL7 v2.2 Table 0078** (the flag
- * *value* set, a published fact set, not CLSI prose). Read in the context of an
- * `R` record's field 7: here `S`/`R`/`I` are the microbiology susceptibility
- * codes and `R` is **not** the repeat delimiter.
+ * The modeled meaning of a recognized {@link AbnormalFlagCode}, plus the
+ * fail-safe sentinel `undefined` (a flag was present but is not in the graded
+ * vocabulary), which is **never** collapsed to `normal`.
  */
-type AbnormalFlagCode = "L" | "H" | "LL" | "HH" | "<" | ">" | "N" | "A" | "AA" | "U" | "D" | "B" | "W" | "S" | "R" | "I";
+type AbnormalFlagMeaning = "below-normal" | "above-normal" | "critically-below-normal" | "critically-above-normal" | "below-scale" | "above-scale" | "normal" | "abnormal" | "very-abnormal" | "significant-change-up" | "significant-change-down" | "better" | "worse" | "susceptible" | "resistant" | "intermediate" | "significantly-high" | "significantly-low" | "undefined";
 /**
- * The modeled meaning of a recognized {@link AbnormalFlagCode}, plus the two
- * fail-safe sentinels: `undefined` (a flag was present but is not in Table 0078),
- * which is **never** collapsed to `normal`.
+ * Every abnormal-flag letter this library recognizes, in declaration order. A
+ * letter outside this list is surfaced verbatim as unrecognized, never guessed
+ * into a meaning.
+ *
+ * @example
+ * ```ts
+ * import { ABNORMAL_FLAG_CODES } from "@cosyte/astm";
+ * ABNORMAL_FLAG_CODES.includes("HU"); // true
+ * ```
  */
-type AbnormalFlagMeaning = "below-normal" | "above-normal" | "critically-below-normal" | "critically-above-normal" | "below-scale" | "above-scale" | "normal" | "abnormal" | "very-abnormal" | "significant-change-up" | "significant-change-down" | "better" | "worse" | "susceptible" | "resistant" | "intermediate" | "undefined";
+declare const ABNORMAL_FLAG_CODES: readonly AbnormalFlagCode[];
 /**
  * A recognized (or explicitly *un*recognized) abnormal flag. The raw field text
  * is always preserved; `recognized` is `false` and `meaning` is `"undefined"`
- * for any letter outside Table 0078, the flag is surfaced, never dropped, and
- * **never coerced to `normal`**.
+ * for any letter outside the graded vocabulary, the flag is surfaced, never
+ * dropped, and **never coerced to `normal`**.
+ *
+ * `vocabulary` is present either way, so a consumer holding an unrecognized flag
+ * can tell a code no published vocabulary defines from one this library has not
+ * caught up to.
  *
  * @example
  * ```ts
  * import { interpretAbnormalFlag } from "@cosyte/astm";
  * const f = interpretAbnormalFlag("HH");
- * f.meaning;    // "critically-above-normal"
- * f.recognized; // true
+ * f.meaning;            // "critically-above-normal"
+ * f.recognized;         // true
+ * f.vocabulary.version; // the code system version compared against
  * ```
  */
 interface AbnormalFlag {
     /** The verbatim field text, exactly as received. */
     readonly raw: string;
-    /** The Table 0078 code, present only when the raw text is a recognized flag. */
+    /** The recognized code, present only when the raw text is a recognized flag. */
     readonly code?: AbnormalFlagCode;
     /** The modeled meaning; `"undefined"` (never `"normal"`) for an unrecognized flag. */
     readonly meaning: AbnormalFlagMeaning;
-    /** Whether the raw text matched a Table 0078 flag. */
+    /** Whether the raw text matched a flag in the graded vocabulary. */
     readonly recognized: boolean;
+    /**
+     * The published code system this flag was graded against, named by identifier
+     * and version. Always present, recognized or not. The version says what this
+     * library compared against, **not** what the sender meant.
+     */
+    readonly vocabulary: NamedVocabulary;
 }
 /**
- * Interpret an `R`-record abnormal-flag field (field 7) against HL7 Table 0078.
+ * Interpret an `R`-record abnormal-flag field (field 7) against
+ * {@link ABNORMAL_FLAG_VOCABULARY}.
  *
  * Leading/trailing whitespace is ignored for the lookup but the `raw` text is
- * preserved verbatim. An unrecognized flag yields `{ recognized: false, meaning:
- * "undefined" }`, surfaced, never dropped, and **never `"normal"`**.
+ * preserved verbatim. Matching is otherwise **exact**: letter case is never
+ * folded. An unrecognized flag yields `{ recognized: false, meaning:
+ * "undefined" }`, surfaced, never dropped, and **never `"normal"`**, and still
+ * carries the vocabulary it was graded against.
  *
  * @param raw - The verbatim field-7 text.
  * @returns The interpreted flag.
@@ -1909,6 +2088,7 @@ interface AbnormalFlag {
  * ```ts
  * import { interpretAbnormalFlag } from "@cosyte/astm";
  * interpretAbnormalFlag("U").meaning;   // "significant-change-up"
+ * interpretAbnormalFlag("HU").meaning;  // "significantly-high"
  * interpretAbnormalFlag("ZZ").meaning;  // "undefined" (never "normal")
  * ```
  */
@@ -1917,6 +2097,10 @@ declare function interpretAbnormalFlag(raw: string): AbnormalFlag;
  * The recognized result-status letters (`R`-record field 9). The clinically
  * load-bearing members are **`C` (correction, supersedes a previously
  * transmitted value)** and **`X` (cannot be done / cancelled)**.
+ *
+ * This set is bound by **no citable published source**: see
+ * {@link RESULT_STATUS_VOCABULARY}, which every interpreted status carries. As
+ * with the flags, matching is exact after trimming; letter case is never folded.
  */
 type ResultStatusCode = "F" | "C" | "P" | "R" | "S" | "I" | "X";
 /**
@@ -1937,12 +2121,17 @@ type ResultStatusMeaning = "final" | "correction" | "preliminary" | "previously-
  *   transmitted one.
  * - **`cancelled`** is `true` for `X`: the result cannot be done / was cancelled.
  *
+ * `vocabulary` is always the explicit "no citable published source": this letter
+ * set is modeled from what analyzers send, not from a vocabulary this library
+ * can name.
+ *
  * @example
  * ```ts
  * import { interpretResultStatus } from "@cosyte/astm";
- * interpretResultStatus("C").isActiveFinal; // false (a correction is not active-final)
- * interpretResultStatus("X").cancelled;     // true
- * interpretResultStatus(undefined).meaning; // "unspecified" (never "final")
+ * interpretResultStatus("C").isActiveFinal;      // false (a correction is not active-final)
+ * interpretResultStatus("X").cancelled;          // true
+ * interpretResultStatus(undefined).meaning;      // "unspecified" (never "final")
+ * interpretResultStatus("F").vocabulary.attributed; // false: nothing is cited
  * ```
  */
 interface ResultStatus {
@@ -1960,6 +2149,12 @@ interface ResultStatus {
     readonly supersedes: boolean;
     /** `true` for `X`: the result cannot be done / was cancelled. */
     readonly cancelled: boolean;
+    /**
+     * The explicit statement that this letter set is bound by **no citable
+     * published source**. Always present and always unattributed, so an absent
+     * attribution and an unattributable one never look alike.
+     */
+    readonly vocabulary: UnattributedVocabulary;
 }
 /**
  * Interpret an `R`-record result-status field (field 9).
@@ -1969,14 +2164,18 @@ interface ResultStatus {
  * (recognized `false`). In every non-`F` case `isActiveFinal` is `false`, so a
  * correction, a cancellation, or an unknown status can never read as current.
  *
+ * Every returned status carries {@link RESULT_STATUS_VOCABULARY}: the explicit
+ * statement that no published source binding this letter set can be cited.
+ *
  * @param raw - The verbatim field-9 text, or `undefined`/empty when absent.
  * @returns The modeled status.
  * @example
  * ```ts
  * import { interpretResultStatus } from "@cosyte/astm";
  * const s = interpretResultStatus("F");
- * s.isActiveFinal; // true
- * s.supersedes;    // false
+ * s.isActiveFinal;          // true
+ * s.supersedes;             // false
+ * s.vocabulary.attributed;  // false: nothing is cited for this set
  * ```
  */
 declare function interpretResultStatus(raw: string | undefined): ResultStatus;
@@ -4285,6 +4484,183 @@ declare function decodeEscapes(leaf: string, d: Delimiters, onUnknown?: UnknownE
  */
 declare function splitEscapeAware(text: string, delimiter: string, escape: string, onAmbiguousAlignment?: AmbiguousAlignmentSink, onShiftedFields?: ShiftedFieldsSink, onTruncatedField?: TruncatedFieldSink, onShiftedComponents?: ShiftedComponentsSink): string[];
 
+/**
+ * The shared `@cosyte/*` date conversion surface, over {@link AstmDate}.
+ *
+ * `toObject`, `toISO` and `toDate` carry the same names, the same return shapes
+ * and the same timezone rule in every `@cosyte` parser, so moving between two of
+ * them costs nothing to relearn. They are **additive**: {@link astmDateToLocalISO}
+ * and {@link parseAstmDate} are untouched, and `toISO` renders exactly the string
+ * `astmDateToLocalISO` renders for every value `parseAstmDate` produces.
+ *
+ * **ASTM is the strictest case for the rule these functions exist for.** An ASTM
+ * timestamp models **no timezone at all**: the value is local to the instrument
+ * that wrote it. So an ASTM value is never an absolute instant on its own, and
+ * {@link toDate} answers `undefined` until the caller says which zone the
+ * instrument was in (`assumeOffsetMinutes`). The host machine's zone is never
+ * read and UTC is never assumed: either guess shifts a date of birth by a day in
+ * every negative-offset zone, silently, and nothing throws to say so.
+ *
+ * Nothing here fabricates a component either. A value stated to day precision
+ * converts to a day, never to a fabricated midnight, and the components a value
+ * did not state are **absent** from {@link DateParts} rather than zero-filled.
+ *
+ * **Nor does anything here normalise a component that is out of calendar range.**
+ * `parseAstmDate` is lenient by design and reads `19881301` into month 13, so the
+ * conversions are where that has to be answered. All three refuse such a value
+ * (`undefined`, never a throw), because the alternative is what a JS `Date` does
+ * with it: month 13 rolls into January of the following year and comes back as a
+ * confident, wrong instant that no warning marks. A date of birth is the case
+ * that decided it.
+ */
+
+/**
+ * The calendar components a parsed value actually stated: the shared return
+ * shape of {@link toObject} across every `@cosyte` parser.
+ *
+ * Every value is a `number` and `month` is **spec-native 1 to 12**, never the JS
+ * `Date` 0 to 11. A component the value did not state is **absent**: the key is
+ * not present at all, rather than present and `undefined`, so `Object.keys()` of
+ * the result is exactly the set of stated components and the value's precision is
+ * recoverable from it. There is no `precision`, `raw`, `valid` or `truncated` key:
+ * this is the calendar reading, not the parse record.
+ *
+ * Deleting `offsetMinutes` leaves an object `Temporal.PlainDateTime.from` and
+ * luxon's `DateTime.fromObject` accept with no key rename and no value
+ * adjustment, which is why the keys are singular and the month is 1-based.
+ * Neither library is a dependency of this package: the shape is the interop, not
+ * an import.
+ *
+ * `millisecond` and `offsetMinutes` belong to the shared shape and are **never
+ * populated by this package**: an ASTM timestamp carries no timezone, and this
+ * parser retains no fractional-second component (the digits stay in
+ * {@link AstmDate.raw}). They are declared so that code written over two
+ * `@cosyte` parsers reads one shape rather than two.
+ */
+interface DateParts {
+    /** Four-digit calendar year, exactly as stated (`50` is the year 50, not 1950). */
+    readonly year?: number;
+    /** Calendar month, **1 to 12**, as the standard states it. */
+    readonly month?: number;
+    /** Day of month, 1 to 31. */
+    readonly day?: number;
+    /** Hour of day, 0 to 23. */
+    readonly hour?: number;
+    /** Minute of hour, 0 to 59. */
+    readonly minute?: number;
+    /** Second of minute, 0 to 59. */
+    readonly second?: number;
+    /** Millisecond. Never populated here: this parser retains no fractional second. */
+    readonly millisecond?: number;
+    /** Signed minutes east of UTC. Never populated here: ASTM states no offset. */
+    readonly offsetMinutes?: number;
+}
+/** The options {@link toDate} accepts. Carries `assumeOffsetMinutes` and nothing else. */
+interface ToDateOptions {
+    /**
+     * The zone to read an offset-less value in, as signed minutes east of UTC
+     * (`-300` is UTC-05:00). Supplying `0` means "treat this value as UTC", which
+     * is a decision only the caller can make: an ASTM value states no offset, so
+     * without this option {@link toDate} returns `undefined` rather than guessing.
+     */
+    readonly assumeOffsetMinutes?: number;
+}
+/**
+ * Read a parsed ASTM date as the shared {@link DateParts} object: only the
+ * components the value stated, frozen, with a spec-native 1-to-12 month.
+ *
+ * Returns `undefined` for `undefined`, for `null`, for a value that stated no
+ * component at all, and for one whose stated components are not a real calendar
+ * date (a month outside 1 to 12, a day past the end of that month, an hour past
+ * 23, a minute or second past 59). Never throws, whatever it is handed. The
+ * truncation flag, the precision and the raw digit run are deliberately not
+ * carried over: a dangling half-component was never a complete component, so it
+ * appears in no field here.
+ *
+ * The out-of-range refusal is total, not per component: `"19881301"` answers
+ * `undefined`, not `{ year: 1988 }`, because a year-precision date of birth is
+ * not what that instrument sent either.
+ *
+ * @param value - A parsed date, or the `undefined` {@link parseAstmDate} returns.
+ * @returns The stated components, frozen, or `undefined`.
+ * @example
+ * ```ts
+ * import { parseAstmDate, toObject } from "@cosyte/astm";
+ * toObject(parseAstmDate("20240315")); // { year: 2024, month: 3, day: 15 }
+ * Object.keys(toObject(parseAstmDate("2024")) ?? {}); // ["year"]
+ * toObject(parseAstmDate("19881301")); // undefined: there is no month 13
+ * ```
+ */
+declare function toObject(value: AstmDate | null | undefined): DateParts | undefined;
+/**
+ * Render a parsed ASTM date as ISO-8601, truncated to the precision it stated
+ * and **never** padded out to a precision it did not.
+ *
+ * No `Z` and no offset is ever appended, because ASTM states none and appending
+ * one would fabricate the instrument's zone. The string is deliberately
+ * zone-less. It is identical to what {@link astmDateToLocalISO} returns for every
+ * value {@link parseAstmDate} produces **whose components are a real calendar
+ * date**; the shared name is the portable route and the repo-native name is
+ * unchanged. On a run that is not, the two differ on purpose and only in one
+ * direction: `astmDateToLocalISO` still renders the digits it was given
+ * (`"1988-13-01"`), because that is its pinned behaviour, and `toISO` answers
+ * `undefined` rather than emit a string no ISO-8601 reader accepts.
+ *
+ * Returns `undefined` for `undefined`, for `null`, for a value stating no
+ * component, for one whose components are not a real calendar date, and for one
+ * stating no year: an ASTM timestamp opens with a mandatory four-digit year, so a
+ * yearless value is not one this parser reads. Never throws.
+ *
+ * @param value - A parsed date, or the `undefined` {@link parseAstmDate} returns.
+ * @returns e.g. `"2024-03-15T09:30"` (minute precision) or `"2024-03"` (month).
+ * @example
+ * ```ts
+ * import { parseAstmDate, toISO } from "@cosyte/astm";
+ * toISO(parseAstmDate("202403150930")); // "2024-03-15T09:30"
+ * toISO(parseAstmDate("not a date"));   // undefined
+ * toISO(parseAstmDate("20240230"));     // undefined: February has no 30th
+ * ```
+ */
+declare function toISO(value: AstmDate | null | undefined): string | undefined;
+/**
+ * Convert a parsed ASTM date to an absolute-instant JS `Date`, **only** when the
+ * caller has made the zone determinate.
+ *
+ * ASTM carries no timezone, so `toDate` returns `undefined` unless
+ * `options.assumeOffsetMinutes` says which zone the instrument was in. The host
+ * machine's zone is never read and UTC is never assumed. A value stating no year
+ * is never an instant either, and neither is one whose components are not a real
+ * calendar date: month 13 becomes January of the next year in a JS `Date`, and
+ * that silent roll-over is the reason the range is checked before the instant is
+ * built rather than after.
+ *
+ * An `assumeOffsetMinutes` that names no usable zone is refused the same way,
+ * with `undefined`: one that is not a finite number (`NaN`, either infinity),
+ * and one so large that applying it puts the result outside the range a JS
+ * `Date` represents. **The answer is never an `Invalid Date`.** Such a `Date`
+ * satisfies this signature and defeats it, because a caller cannot tell it from
+ * a real instant without testing `getTime()` for `NaN`, and `toISOString()` on
+ * it throws.
+ *
+ * Components below the stated precision fill to their lowest legal value (month
+ * and day to 1, time to 0) **for instant construction only**: the value itself is
+ * unchanged, and {@link toObject} and {@link toISO} report exactly what they
+ * reported before the call.
+ *
+ * @param value - A parsed date, or the `undefined` {@link parseAstmDate} returns.
+ * @param options - The zone assumption to apply, as signed minutes east of UTC.
+ * @returns The instant, or `undefined` when the zone or the year is unstated.
+ * @example
+ * ```ts
+ * import { parseAstmDate, toDate } from "@cosyte/astm";
+ * const d = parseAstmDate("20240315");
+ * toDate(d);                              // undefined: no zone was stated
+ * toDate(d, { assumeOffsetMinutes: -300 }); // 2024-03-15T05:00:00.000Z
+ * toDate(parseAstmDate("19881301"), { assumeOffsetMinutes: 0 }); // undefined, not 1989
+ * ```
+ */
+declare function toDate(value: AstmDate | null | undefined, options?: ToDateOptions): Date | undefined;
+
 /**
  * Deep-freeze helper for the immutable ASTM model.
  *
@@ -5092,6 +5468,207 @@ declare const astmProfiles: {
     readonly referenceCorpus: typeof referenceCorpus;
 };
 
+/**
+ * The **terminology** warning registry (`ASTM_LIVD_*`) for the LIVD-aware LOINC
+ * recognition layer: the fourth of the package's registries,
+ * alongside the record layer's `ASTM_RECORD_*`, the frame codec's `ASTM_FRAME_*`,
+ * and the protocol reducer's `ASTM_LTP_*`.
+ *
+ * A terminology warning is the record of a **safe non-mapping**: a reported
+ * vendor test code that a consumer-supplied LIVD catalog did not map to a single
+ * LOINC. It never carries a LOINC the catalog did not vouch for: the whole point
+ * of the layer is that an unmapped or ambiguous code is surfaced as *unmapped*,
+ * **never a guessed LOINC** (mis-identifying a test is safety-critical). Every
+ * warning carries a stable code and a message that is a **constant**, and
+ * **never** a field value, a reported code or any text the consumer stored in
+ * their catalog. Consumers compare `warning.code ===
+ * LIVD_WARNING_CODES.<CODE>`; renaming a code is a **breaking change**.
+ *
+ * **Two shapes, by what the warning is about.** A warning about a RECORD carries
+ * positional context ({@link AstmPosition}) and is an {@link AstmLivdWarning}: one
+ * per unmapped or ambiguous code, produced while a message is annotated. A warning
+ * about the CATALOG ITSELF carries no position, because no record is implicated: it
+ * is an {@link AstmLivdCatalogWarning}, raised once where the catalog is defined,
+ * and it names the catalog through a structured field
+ * ({@link LivdCatalogIdentity}) rather than through its message text, so a consumer
+ * who logs only the message can never emit text they stored in their catalog.
+ *
+ * These codes live in their own registry and are deliberately **not** part of the
+ * profile safety gate's universe (`ALL_ASTM_WARNING_CODES`): a LIVD non-mapping is
+ * a post-parse advisory produced by the opt-in {@link applyLivd} helper, not a
+ * parse-time deviation a vendor profile could ever "tolerate". A profile referencing
+ * one is rejected as an unknown code: correctly, since there is nothing here to
+ * quiet.
+ */
+
+/**
+ * Stable string codes for every terminology (LIVD) warning. `key === value` so
+ * `Object.values(...)` yields a stable snapshot set.
+ *
+ * @example
+ * ```ts
+ * import { LIVD_WARNING_CODES } from "@cosyte/astm";
+ * LIVD_WARNING_CODES.ASTM_LIVD_UNMAPPED_CODE; // "ASTM_LIVD_UNMAPPED_CODE"
+ * ```
+ */
+declare const LIVD_WARNING_CODES: {
+    /**
+     * A record carried a vendor/local test code, but the consumer-supplied LIVD catalog held **no**
+     * entry for it. The code stays surfaced verbatim and the mapping is `unmapped`: a LOINC is
+     * **never** guessed. Purely advisory: the raw code and value are untouched.
+     */
+    readonly ASTM_LIVD_UNMAPPED_CODE: "ASTM_LIVD_UNMAPPED_CODE";
+    /**
+     * A vendor/local test code matched **more than one distinct LOINC** in the catalog (e.g. the same
+     * transmission code used by two devices for different analytes). The mapping is `ambiguous` and the
+     * candidate LOINCs are surfaced for inspection, but **none is chosen**: refusing to pick is the
+     * fail-safe, since guessing wrong mis-identifies the test.
+     */
+    readonly ASTM_LIVD_AMBIGUOUS_MAPPING: "ASTM_LIVD_AMBIGUOUS_MAPPING";
+    /**
+     * A consumer-supplied LIVD catalog was defined **without a LOINC version**, so a mapping it
+     * produces cannot say which version of LOINC it was made against. Advisory and **never a
+     * refusal**: the catalog is still built, still indexed and still answers exactly as it would
+     * have. Raised **once, where the catalog is defined**, and never per record: it is a fact about
+     * the catalog rather than about any message, so it never joins the per-record warning stream.
+     */
+    readonly ASTM_LIVD_CATALOG_NO_LOINC_VERSION: "ASTM_LIVD_CATALOG_NO_LOINC_VERSION";
+};
+/**
+ * Discriminant type for every code in {@link LIVD_WARNING_CODES}, the per-record
+ * codes and the catalog-level one alike. Narrowing by this code lets consumers
+ * write exhaustive `switch` blocks against the registry. It tracks the registry
+ * exactly, so `Object.values(LIVD_WARNING_CODES)` stays a snapshot of this type.
+ */
+type LivdWarningCode = (typeof LIVD_WARNING_CODES)[keyof typeof LIVD_WARNING_CODES];
+/**
+ * A single terminology (LIVD) warning: a stable code, a value-free human-readable
+ * message, and positional context. Never carries a test code, a value, or a LOINC.
+ *
+ * @example
+ * ```ts
+ * import type { AstmLivdWarning } from "@cosyte/astm";
+ * const w: AstmLivdWarning = {
+ *   code: "ASTM_LIVD_UNMAPPED_CODE",
+ *   message: "Reported test code had no LIVD mapping, surfaced unmapped, never a guessed LOINC.",
+ *   position: { recordIndex: 3, recordType: "R" },
+ * };
+ * ```
+ */
+interface AstmLivdWarning {
+    readonly code: LivdWarningCode;
+    /** Human-readable detail for logs. Never contains a test code, a value, or a LOINC. */
+    readonly message: string;
+    readonly position: AstmPosition;
+}
+/**
+ * Build an `ASTM_LIVD_UNMAPPED_CODE` warning. The reported code stays verbatim and
+ * the mapping is `unmapped`; no LOINC is fabricated.
+ *
+ * @param position - Where the unmapped code was seen (record ordinal + type; never the code).
+ * @returns The warning.
+ * @example
+ * ```ts
+ * import { livdUnmappedCode } from "@cosyte/astm";
+ * livdUnmappedCode({ recordIndex: 3, recordType: "R" });
+ * ```
+ */
+declare function livdUnmappedCode(position: AstmPosition): AstmLivdWarning;
+/**
+ * Build an `ASTM_LIVD_AMBIGUOUS_MAPPING` warning. The code matched multiple distinct
+ * LOINCs; none is chosen (refusing to pick is the fail-safe).
+ *
+ * @param position - Where the ambiguous code was seen (record ordinal + type; never the code).
+ * @returns The warning.
+ * @example
+ * ```ts
+ * import { livdAmbiguousMapping } from "@cosyte/astm";
+ * livdAmbiguousMapping({ recordIndex: 4, recordType: "O" });
+ * ```
+ */
+declare function livdAmbiguousMapping(position: AstmPosition): AstmLivdWarning;
+/**
+ * What a LIVD catalog declared about its own identity: the two publication elements
+ * that name a publication, or the explicit statement that it declared neither.
+ *
+ * The same two shapes the rest of this package uses for attribution: a named source,
+ * or a positive "nothing citable", never an absent field and never an invented name.
+ * Discriminate on `declared`.
+ *
+ * @example
+ * ```ts
+ * import type { LivdCatalogIdentity } from "@cosyte/astm";
+ * const named: LivdCatalogIdentity = { declared: true, publisher: "Example Diagnostics" };
+ * ```
+ */
+type LivdCatalogIdentity = {
+    /** Always `true`: the catalog declared at least one of the two elements below. */
+    readonly declared: true;
+    /** The **Publisher** the catalog declared, verbatim, when it declared one. */
+    readonly publisher?: string;
+    /** The **Publication Version ID** the catalog declared, verbatim, when it declared one. */
+    readonly publicationVersion?: string;
+} | {
+    /** Always `false`: the catalog declared neither a publisher nor a publication version. */
+    readonly declared: false;
+    /** Fixed prose saying that no identity was declared. Never an invented or indexed name. */
+    readonly reason: string;
+};
+/**
+ * The identity reported for a catalog that declared neither a publisher nor a
+ * publication version: a positive statement that it declared none.
+ *
+ * It exists so that case is said rather than left to an absent field, and so nothing
+ * has to invent a name, an ordinal or a position to stand in for one. Frozen.
+ *
+ * @example
+ * ```ts
+ * import { LIVD_CATALOG_IDENTITY_UNDECLARED } from "@cosyte/astm";
+ * LIVD_CATALOG_IDENTITY_UNDECLARED.declared; // false
+ * ```
+ */
+declare const LIVD_CATALOG_IDENTITY_UNDECLARED: LivdCatalogIdentity;
+/**
+ * A catalog-level terminology warning: a stable code, a value-free constant message,
+ * and the catalog's own declared identity. It carries no position, because no record
+ * is implicated, and it is never produced while a message is annotated.
+ *
+ * @example
+ * ```ts
+ * import type { AstmLivdCatalogWarning } from "@cosyte/astm";
+ * const w: AstmLivdCatalogWarning = {
+ *   code: "ASTM_LIVD_CATALOG_NO_LOINC_VERSION",
+ *   message: "...",
+ *   catalog: { declared: true, publisher: "Example Diagnostics", publicationVersion: "2026-01" },
+ * };
+ * ```
+ */
+interface AstmLivdCatalogWarning {
+    /** Always `ASTM_LIVD_CATALOG_NO_LOINC_VERSION`. */
+    readonly code: typeof LIVD_WARNING_CODES.ASTM_LIVD_CATALOG_NO_LOINC_VERSION;
+    /**
+     * Human-readable detail for logs. A **constant**: never a test code, a value, a LOINC, or any
+     * text the consumer supplied. The catalog is named by the `catalog` field, not by this string.
+     */
+    readonly message: string;
+    /** What the catalog declared about itself, or the positive statement that it declared none. */
+    readonly catalog: LivdCatalogIdentity;
+}
+/**
+ * Build an `ASTM_LIVD_CATALOG_NO_LOINC_VERSION` warning. Advisory: the catalog it
+ * describes is still built and still answers every lookup exactly as it would have.
+ *
+ * @param catalog - What the catalog declared about its identity; pass
+ *   {@link LIVD_CATALOG_IDENTITY_UNDECLARED} where it declared none.
+ * @returns The warning.
+ * @example
+ * ```ts
+ * import { livdCatalogMissingLoincVersion, LIVD_CATALOG_IDENTITY_UNDECLARED } from "@cosyte/astm";
+ * livdCatalogMissingLoincVersion(LIVD_CATALOG_IDENTITY_UNDECLARED);
+ * ```
+ */
+declare function livdCatalogMissingLoincVersion(catalog: LivdCatalogIdentity): AstmLivdCatalogWarning;
+
 /**
  * The **consumer-supplied** LIVD catalog: a vendor-test-code → LOINC index built
  * from an IICC LIVD ("LOINC to Vendor IVD") mapping the consumer provides.
@@ -5122,7 +5699,55 @@ declare const astmProfiles: {
  * conflicting entries *within* one catalog are caught and surfaced as `ambiguous`
  * (never resolved to a guess), but cross-device code reuse the catalog cannot see is
  * a catalog-hygiene concern the consumer owns.
+ *
+ * **One vendor analyte code to many LOINCs is the ORDINARY case, and the units are
+ * what tell them apart.** The mapping guide this catalog format comes from describes
+ * the relationship as many-to-many by design, and its own worked examples are the
+ * commonest chemistry analytes: a serum glucose maps to one LOINC as a mass
+ * concentration and to another as a substance concentration, and a urine analyte maps
+ * to one LOINC at `mmol/L` (a spot specimen) and to another at `mmol/(24.h)` (a 24
+ * hour collection). The guide's remedy is to define a mapping per unit, so
+ * {@link LivdEntry.representativeUnit} carries that unit and
+ * {@link LivdCatalog.lookup} compares it with the units the `R` record reported.
+ *
+ * **That comparison is VERBATIM and CASE SENSITIVE, and it is not UCUM.** Nothing is
+ * normalized, converted, case folded or scaled on either side: a catalog saying
+ * `mg/dL` does not match a feed saying `MG/DL`, and a catalog saying `mg/L` never
+ * matches `ug/dL` however convertible the two are. UCUM defines a case-insensitive
+ * variant of every terminal symbol and requires a program claiming full conformance
+ * to compare unit expressions by their SEMANTICS, so a verbatim string comparison is
+ * a deliberately limited choice rather than UCUM conformance. It is the only
+ * comparison that cannot invent an equivalence, and because a consumer could
+ * otherwise read a matched unit as a conformance claim this package does not make,
+ * every unit-selected answer states what the comparison was
+ * ({@link LivdUnitComparison}).
+ *
+ * **A catalog can also say where the mapping came from, and none of it is checked.**
+ * The mapping guide defines four elements about the PUBLICATION rather than about any
+ * row: who published it, which publication version it is, which LOINC version the
+ * mapping was made against, and the attribution statement the LOINC license requires.
+ * {@link LivdPublication} carries all four, every one optional, every one preserved
+ * verbatim, and **not one of them validated**: this package performs no LOINC
+ * validation of any kind, so a LOINC version is stored and surfaced exactly as
+ * supplied and is never parsed, ranged, formatted or compared. Carrying an
+ * attribution statement is not discharging the obligation to make it: the terminology
+ * data, and its license, stay the consumer's.
+ *
+ * **A catalog with no LOINC version is built, and says so.** A mapping whose LOINC
+ * version is unrecorded cannot be reproduced later, so defining a catalog without one
+ * surfaces a value-free `ASTM_LIVD_CATALOG_NO_LOINC_VERSION` warning on
+ * {@link LivdCatalog.warnings}. It is a nudge and never a refusal: the catalog is
+ * built, every lookup answers exactly as it would have, and no per-record warning
+ * moves.
+ *
+ * **The three LIVD attributes are carried verbatim and only one of them is matched
+ * on.** {@link LivdEntry.vendorSpecimenDescription} and
+ * {@link LivdEntry.vendorResultDescription} are free text the guide says is there to
+ * help a laboratory choose by hand and is "not intended to be parsed by an IVD
+ * Software System that automates the mapping": they are stored and surfaced, never
+ * matched on, never normalized. Only the representative unit ever selects.
  */
+
 /**
  * One LIVD mapping row a consumer supplies: a vendor test code and the LOINC it
  * maps to, plus optional human-readable / provenance fields. Modeled on the IICC
@@ -5155,29 +5780,232 @@ interface LivdEntry {
     readonly manufacturer?: string;
     /** The device **Model**, when the catalog scopes the mapping to a device (optional provenance). */
     readonly model?: string;
+    /**
+     * The **Vendor Specimen Description**: the vendor's own human-readable text for the specimen this
+     * mapping is for, such as `"Serum or Plasma"`. Carried **verbatim** (never trimmed, case folded or
+     * normalized) and surfaced for a human to read. **Never matched on**: the mapping guide states this
+     * text is not intended to be parsed by software that automates the mapping, so choosing on it would
+     * be a string guess. Optional, so an existing catalog keeps working unchanged.
+     */
+    readonly vendorSpecimenDescription?: string;
+    /**
+     * The **Vendor Result Description**: the vendor's own human-readable text for the result this
+     * mapping produces (binary, ordinal, nominal, or a numeric result with its unit). Carried
+     * **verbatim** and surfaced for a human to read; **never matched on**, for the same reason as
+     * {@link LivdEntry.vendorSpecimenDescription}. Optional.
+     */
+    readonly vendorResultDescription?: string;
+    /**
+     * The **representative unit of measure** for this mapping, preferably a UCUM unit (e.g. `"mg/dL"`,
+     * `"mmol/L"`, `"mmol/(24.h)"`). This is the **one** attribute a lookup ever selects on: when a
+     * vendor analyte code carries several candidate LOINCs, the candidate whose representative unit is
+     * **exactly equal** to the units the `R` record reported is chosen, compared verbatim and case
+     * sensitively with no normalization, conversion or scale factor on either side.
+     *
+     * Absent, empty or whitespace only means **not unit qualified**: such a candidate is never selected
+     * by a unit comparison, though it is still surfaced among an ambiguous answer's candidates.
+     * Optional, so an existing catalog keeps working unchanged.
+     */
+    readonly representativeUnit?: string;
+}
+/**
+ * How a candidate was selected on its unit, stated on the answer so a consumer cannot
+ * read a matched unit as a UCUM conformance claim this package does not make.
+ *
+ * Present on a {@link LivdLookup} **only** when a unit comparison actually chose
+ * between candidate LOINCs. Its whole content is a disclosure: the comparison was a
+ * verbatim, case-sensitive string equality, and **not** a UCUM semantic comparison.
+ * Nothing was normalized, case folded, scaled or converted on either side.
+ *
+ * @example
+ * ```ts
+ * import type { LivdUnitComparison } from "@cosyte/astm";
+ * const c: LivdUnitComparison = {
+ *   comparison: "verbatim-case-sensitive",
+ *   ucumSemantic: false,
+ *   reportedUnits: "mg/dL",
+ *   representativeUnit: "mg/dL",
+ *   note: "...",
+ * };
+ * ```
+ */
+interface LivdUnitComparison {
+    /** Always `"verbatim-case-sensitive"`: an exact string equality, nothing normalized. */
+    readonly comparison: "verbatim-case-sensitive";
+    /** Always `false`. This package does not compare unit expressions by their semantics. */
+    readonly ucumSemantic: false;
+    /** The units the record reported, verbatim. */
+    readonly reportedUnits: string;
+    /** The chosen candidate's representative unit, verbatim. Byte-identical to `reportedUnits`. */
+    readonly representativeUnit: string;
+    /** A human-readable restatement of the two facts above, for a log or a review screen. */
+    readonly note: string;
+}
+/**
+ * One candidate mapping behind an `ambiguous` answer: the LOINC plus the LIVD
+ * attributes that tell candidates apart, so a human can choose what this package
+ * refuses to guess.
+ *
+ * One per catalog row for the vendor code, in catalog order, so a LOINC appearing in
+ * two rows appears twice. Every candidate is surfaced, including one that is not unit
+ * qualified: it can never be selected on a unit, but hiding it would hide a mapping
+ * the consumer's own catalog holds.
+ *
+ * @example
+ * ```ts
+ * import type { LivdCandidate } from "@cosyte/astm";
+ * const c: LivdCandidate = {
+ *   loinc: "2345-7",
+ *   vendorSpecimenDescription: "Serum or Plasma",
+ *   representativeUnit: "mg/dL",
+ *   unitQualified: true,
+ * };
+ * ```
+ */
+interface LivdCandidate {
+    /** The candidate LOINC, verbatim from the catalog row. Never validated. */
+    readonly loinc: string;
+    /** The row's LOINC Long Common Name, when supplied. */
+    readonly loincLongName?: string;
+    /** The row's Vendor Specimen Description, verbatim, when supplied. Never matched on. */
+    readonly vendorSpecimenDescription?: string;
+    /** The row's Vendor Result Description, verbatim, when supplied. Never matched on. */
+    readonly vendorResultDescription?: string;
+    /** The row's representative unit, verbatim, when supplied. */
+    readonly representativeUnit?: string;
+    /**
+     * `false` when the representative unit is absent, empty or whitespace only. Such a candidate is
+     * **never** selected by a unit comparison against any reported units, and is surfaced here anyway.
+     */
+    readonly unitQualified: boolean;
 }
+/**
+ * Why a code carrying several candidate LOINCs stayed `ambiguous` after the unit
+ * comparison ran, or why the comparison could not run at all.
+ *
+ * - `no-reported-units`: the record reported no usable units (absent, empty or whitespace only), so
+ *   nothing could be compared. A unit-qualified candidate is never chosen in this case.
+ * - `no-candidate-matched-units`: units were reported and **no** unit-qualified candidate's
+ *   representative unit was exactly equal to them.
+ * - `multiple-candidates-matched-units`: units were reported and **more than one distinct** candidate
+ *   LOINC matched them exactly. Picking one would be a guess.
+ *
+ * Every one of them surfaces every candidate and chooses no LOINC.
+ */
+type LivdAmbiguityReason = "no-reported-units" | "no-candidate-matched-units" | "multiple-candidates-matched-units";
 /**
  * The outcome of looking a vendor code up in a {@link LivdCatalog}. A distinct
  * value per safe disposition: a hit is `mapped`; a miss is `unmapped`; a code that
- * matched more than one **distinct** LOINC is `ambiguous` with the candidates
- * surfaced but **none chosen**. There is deliberately no "guessed" case.
+ * matched more than one **distinct** LOINC and that the reported units did not
+ * settle is `ambiguous` with the candidates surfaced but **none chosen**. There is
+ * deliberately no "guessed" case.
+ *
+ * **The added fields are all optional, and a catalog carrying none of the three LIVD
+ * attributes answers byte-identically to how it answered before they existed.** They
+ * appear only where the consumer's own catalog rows supply something to put in them.
  */
 type LivdLookup = 
-/** Exactly one LOINC (one entry, or several entries that all agree on the same LOINC). */
+/**
+ * Exactly one LOINC: one entry, several entries that all agree on the same LOINC, or several
+ * candidates of which exactly one had a representative unit equal to the units the record
+ * reported (and then, and only then, `unitComparison` says how that comparison was made).
+ */
 {
     readonly status: "mapped";
     readonly loinc: string;
     readonly loincLongName?: string;
+    /** The chosen row's Vendor Specimen Description, verbatim, when supplied. Never matched on. */
+    readonly vendorSpecimenDescription?: string;
+    /** The chosen row's Vendor Result Description, verbatim, when supplied. Never matched on. */
+    readonly vendorResultDescription?: string;
+    /**
+     * The chosen row's representative unit, verbatim, when supplied.
+     *
+     * **This is provenance about the CATALOG ROW, not a restatement of what the record
+     * reported.** Where a vendor code carried a single candidate LOINC across several rows
+     * that spell the unit differently, the answer takes the FIRST row's attributes (exactly
+     * as it has always taken the first row's `loincLongName`), so this can name a unit the
+     * record did not report. Only {@link LivdUnitComparison} asserts the two were equal, and
+     * it is present only where a unit actually chose between candidates.
+     */
+    readonly representativeUnit?: string;
+    /**
+     * Present **if and only if** a unit comparison chose this LOINC from more than one candidate.
+     * Absent where the code carried a single candidate LOINC, which is answered whether or not the
+     * units agree: nothing was selected on a unit there, so claiming it was would be false.
+     */
+    readonly unitComparison?: LivdUnitComparison;
 }
 /** No entry for this code: a miss. The code stays verbatim; no LOINC is invented. */
  | {
     readonly status: "unmapped";
 }
-/** More than one distinct LOINC: surfaced for inspection, never resolved to one. */
+/** More than one distinct LOINC, unsettled: surfaced for inspection, never resolved to one. */
  | {
     readonly status: "ambiguous";
+    /** Every distinct candidate LOINC, deduplicated, in first-seen catalog order. */
     readonly candidates: readonly string[];
+    /**
+     * Every candidate row with its LIVD attributes, one per catalog row (so a LOINC held by two
+     * rows appears twice), including rows that are not unit qualified. Present only where at least
+     * one row for this vendor code carries one of the three LIVD attributes.
+     */
+    readonly candidateDetails?: readonly LivdCandidate[];
+    /**
+     * Why the unit comparison did not settle it. Present under the same condition as
+     * `candidateDetails`: a catalog carrying none of the LIVD attributes answers exactly as it did
+     * before this field existed.
+     */
+    readonly reason?: LivdAmbiguityReason;
 };
+/**
+ * The publication-level metadata a consumer declares about the LIVD publication
+ * their catalog was built from: what the mapping guide defines about the publication
+ * rather than about any one row.
+ *
+ * Every field is **optional** and every declared value is preserved **verbatim**:
+ * nothing is trimmed, case folded, reordered, reformatted, defaulted or validated,
+ * and no value is ever rejected, corrected or warned about on account of its content
+ * or its shape. A value that is absent, empty or whitespace only is one case, **no
+ * value declared**, which is the only inspection any of these strings gets.
+ *
+ * **None of it is checked, and none of it is a claim by this package.** This library
+ * is not the LOINC licensee and performs no LOINC validation of any kind, so it
+ * cannot tell a real LOINC version from a typed one and does not try.
+ *
+ * @example
+ * ```ts
+ * import type { LivdPublication } from "@cosyte/astm";
+ * const p: LivdPublication = { publisher: "Example Diagnostics", loincVersion: "2.78" };
+ * ```
+ */
+interface LivdPublication {
+    /** The **Publisher**: the entity publishing the mapping information. Verbatim, never checked. */
+    readonly publisher?: string;
+    /**
+     * The **Publication Version ID**: human-readable information the vendor provides that tells one
+     * LIVD publication version from another. Verbatim, never parsed and never ordered against another.
+     */
+    readonly publicationVersion?: string;
+    /**
+     * The **LOINC Version ID**: the version of LOINC the mapping was made against. Carried verbatim
+     * onto every annotation this catalog produces ({@link LivdAnnotation.catalogLoincVersion}), so a
+     * mapping can be reproduced later. It is **provenance the consumer declared**, never a statement
+     * that any LOINC was checked against it: nothing here validates a LOINC or a LOINC version.
+     *
+     * Declaring none is allowed and surfaces a value-free warning on {@link LivdCatalog.warnings};
+     * the catalog is still built and every answer is unchanged.
+     */
+    readonly loincVersion?: string;
+    /**
+     * The **LOINCCopyright**: the attribution statement the LOINC license requires beside content
+     * that carries LOINC codes. Stored verbatim so it travels with the mapping it applies to.
+     *
+     * **Carrying it is not discharging it.** The obligation is the consumer's, this package supplies
+     * no statement on anyone's behalf, and it checks neither the presence nor the wording of one.
+     */
+    readonly loincCopyright?: string;
+}
 /**
  * An immutable, consumer-supplied LIVD catalog. Look a vendor code up with
  * {@link LivdCatalog.lookup}; the catalog **never** picks between conflicting
@@ -5186,15 +6014,45 @@ type LivdLookup =
 interface LivdCatalog {
     /** The number of distinct vendor codes indexed (not the number of input rows). */
     readonly size: number;
+    /**
+     * The publication-level metadata the consumer declared, each value **verbatim**. Absent where
+     * the catalog declared none, and each field inside it absent where that value was not declared:
+     * a blank is never stored as a blank, and nothing is ever defaulted.
+     *
+     * Optional on the interface, so a catalog a consumer implements by hand needs no metadata and
+     * stays source compatible.
+     */
+    readonly publication?: LivdPublication;
+    /**
+     * The value-free warnings raised where this catalog was **defined**, in the order they were
+     * raised. {@link defineLivdCatalog} always sets it, empty where it had nothing to say.
+     *
+     * These are facts about the CATALOG, so they never join the per-record warning stream
+     * {@link applyLivd} returns and they implicate no record. Optional on the interface, so a
+     * hand-implemented catalog that offers none stays source compatible.
+     */
+    readonly warnings?: readonly AstmLivdCatalogWarning[];
     /**
      * Look a vendor code up, verbatim (exact, case-sensitive). Returns `mapped` on a
      * single-LOINC hit, `unmapped` on a miss, and `ambiguous` when the code carries
-     * more than one distinct LOINC: never a guess.
+     * more than one distinct LOINC that the reported units did not settle: never a
+     * guess.
+     *
+     * `reportedUnits` are the units the `R` record carried, verbatim. They are compared
+     * with each candidate's {@link LivdEntry.representativeUnit} by exact,
+     * case-sensitive string equality and by nothing else. Omitting them, or passing an
+     * empty or whitespace-only string, means **no units were reported**: no
+     * unit-qualified candidate is chosen and a code carrying several candidates stays
+     * `ambiguous`. A code carrying exactly one candidate LOINC is answered either way.
+     *
+     * Implementing this interface by hand stays source compatible: a `lookup` declared
+     * with the vendor code alone simply ignores the units, and answers as it always did.
      *
      * @param vendorCode - The reported vendor/local test code.
+     * @param reportedUnits - The units the record reported, verbatim, when it reported any.
      * @returns The lookup outcome.
      */
-    lookup(vendorCode: string): LivdLookup;
+    lookup(vendorCode: string, reportedUnits?: string): LivdLookup;
 }
 /**
  * Build a {@link LivdCatalog} from LIVD entries a consumer supplies. Entries are
@@ -5202,13 +6060,26 @@ interface LivdCatalog {
  * code:
  *
  * - all agreeing on the same `loinc` → a single `mapped` result (the first entry's
- *   optional `loincLongName` is kept);
- * - disagreeing (two distinct LOINCs) → an `ambiguous` result carrying every
- *   distinct candidate, and **no** choice between them.
+ *   optional `loincLongName` and LIVD attributes are kept), whether or not the
+ *   reported units equal that entry's representative unit;
+ * - disagreeing (two distinct LOINCs) → the reported units decide, by exact
+ *   case-sensitive equality against each row's
+ *   {@link LivdEntry.representativeUnit}. Exactly one distinct LOINC matching is
+ *   `mapped`, and the answer states that the comparison was verbatim. None matching,
+ *   more than one matching, or no units reported is an `ambiguous` result carrying
+ *   every distinct candidate and **no** choice between them.
+ *
+ * Publication-level metadata is supplied beside the rows, and every element of it is
+ * optional, so the single-argument call keeps working exactly as it did. Each declared
+ * value is preserved verbatim and readable back off {@link LivdCatalog.publication};
+ * none of it is validated. Declaring no LOINC version is allowed and puts a value-free
+ * {@link AstmLivdCatalogWarning} on {@link LivdCatalog.warnings}: a nudge, never a
+ * refusal, and no lookup answers differently because of it.
  *
  * The returned catalog is deeply frozen; nothing is mutated after construction.
  *
  * @param entries - The consumer's LIVD mapping rows.
+ * @param publication - The consumer's publication-level metadata, when they declare any.
  * @returns An immutable catalog.
  * @example
  * ```ts
@@ -5220,108 +6091,20 @@ interface LivdCatalog {
  * catalog.lookup("687"); // { status: "mapped", loinc: "1920-8", loincLongName: "AST" }
  * catalog.lookup("999"); // { status: "unmapped" }
  * ```
- */
-declare function defineLivdCatalog(entries: readonly LivdEntry[]): LivdCatalog;
-
-/**
- * The **terminology** warning registry (`ASTM_LIVD_*`) for the LIVD-aware LOINC
- * recognition layer: the fourth of the package's registries,
- * alongside the record layer's `ASTM_RECORD_*`, the frame codec's `ASTM_FRAME_*`,
- * and the protocol reducer's `ASTM_LTP_*`.
- *
- * A terminology warning is the record of a **safe non-mapping**: a reported
- * vendor test code that a consumer-supplied LIVD catalog did not map to a single
- * LOINC. It never carries a LOINC the catalog did not vouch for: the whole point
- * of the layer is that an unmapped or ambiguous code is surfaced as *unmapped*,
- * **never a guessed LOINC** (mis-identifying a test is safety-critical). Every
- * warning carries a stable code plus positional context ({@link AstmPosition}) and
- * **never** a field value. Consumers compare `warning.code ===
- * LIVD_WARNING_CODES.<CODE>`; renaming a code is a **breaking change**.
- *
- * These codes live in their own registry and are deliberately **not** part of the
- * profile safety gate's universe (`ALL_ASTM_WARNING_CODES`): a LIVD non-mapping is
- * a post-parse advisory produced by the opt-in {@link applyLivd} helper, not a
- * parse-time deviation a vendor profile could ever "tolerate". A profile referencing
- * one is rejected as an unknown code: correctly, since there is nothing here to
- * quiet.
- */
-
-/**
- * Stable string codes for every terminology (LIVD) warning. `key === value` so
- * `Object.values(...)` yields a stable snapshot set.
- *
- * @example
- * ```ts
- * import { LIVD_WARNING_CODES } from "@cosyte/astm";
- * LIVD_WARNING_CODES.ASTM_LIVD_UNMAPPED_CODE; // "ASTM_LIVD_UNMAPPED_CODE"
- * ```
- */
-declare const LIVD_WARNING_CODES: {
-    /**
-     * A record carried a vendor/local test code, but the consumer-supplied LIVD catalog held **no**
-     * entry for it. The code stays surfaced verbatim and the mapping is `unmapped`: a LOINC is
-     * **never** guessed. Purely advisory: the raw code and value are untouched.
-     */
-    readonly ASTM_LIVD_UNMAPPED_CODE: "ASTM_LIVD_UNMAPPED_CODE";
-    /**
-     * A vendor/local test code matched **more than one distinct LOINC** in the catalog (e.g. the same
-     * transmission code used by two devices for different analytes). The mapping is `ambiguous` and the
-     * candidate LOINCs are surfaced for inspection, but **none is chosen**: refusing to pick is the
-     * fail-safe, since guessing wrong mis-identifies the test.
-     */
-    readonly ASTM_LIVD_AMBIGUOUS_MAPPING: "ASTM_LIVD_AMBIGUOUS_MAPPING";
-};
-/**
- * Discriminant type for {@link AstmLivdWarning.code}. Narrowing by this code lets
- * consumers write exhaustive `switch` blocks against {@link LIVD_WARNING_CODES}.
- */
-type LivdWarningCode = (typeof LIVD_WARNING_CODES)[keyof typeof LIVD_WARNING_CODES];
-/**
- * A single terminology (LIVD) warning: a stable code, a value-free human-readable
- * message, and positional context. Never carries a test code, a value, or a LOINC.
- *
  * @example
  * ```ts
- * import type { AstmLivdWarning } from "@cosyte/astm";
- * const w: AstmLivdWarning = {
- *   code: "ASTM_LIVD_UNMAPPED_CODE",
- *   message: "Reported test code had no LIVD mapping, surfaced unmapped, never a guessed LOINC.",
- *   position: { recordIndex: 3, recordType: "R" },
- * };
- * ```
- */
-interface AstmLivdWarning {
-    readonly code: LivdWarningCode;
-    /** Human-readable detail for logs. Never contains a test code, a value, or a LOINC. */
-    readonly message: string;
-    readonly position: AstmPosition;
-}
-/**
- * Build an `ASTM_LIVD_UNMAPPED_CODE` warning. The reported code stays verbatim and
- * the mapping is `unmapped`; no LOINC is fabricated.
- *
- * @param position - Where the unmapped code was seen (record ordinal + type; never the code).
- * @returns The warning.
- * @example
- * ```ts
- * import { livdUnmappedCode } from "@cosyte/astm";
- * livdUnmappedCode({ recordIndex: 3, recordType: "R" });
- * ```
- */
-declare function livdUnmappedCode(position: AstmPosition): AstmLivdWarning;
-/**
- * Build an `ASTM_LIVD_AMBIGUOUS_MAPPING` warning. The code matched multiple distinct
- * LOINCs; none is chosen (refusing to pick is the fail-safe).
- *
- * @param position - Where the ambiguous code was seen (record ordinal + type; never the code).
- * @returns The warning.
- * @example
- * ```ts
- * import { livdAmbiguousMapping } from "@cosyte/astm";
- * livdAmbiguousMapping({ recordIndex: 4, recordType: "O" });
+ * import { defineLivdCatalog } from "@cosyte/astm";
+ * // One vendor analyte code, two LOINCs, told apart by their representative unit.
+ * const glucose = defineLivdCatalog([
+ *   { vendorCode: "GLU", loinc: "2345-7", representativeUnit: "mg/dL" },
+ *   { vendorCode: "GLU", loinc: "15074-8", representativeUnit: "mmol/L" },
+ * ]);
+ * glucose.lookup("GLU", "mmol/L").status; // "mapped": 15074-8, on a verbatim unit match
+ * glucose.lookup("GLU", "MMOL/L").status; // "ambiguous": the comparison is case sensitive
+ * glucose.lookup("GLU").status; // "ambiguous": no units reported, so nothing to compare
  * ```
  */
-declare function livdAmbiguousMapping(position: AstmPosition): AstmLivdWarning;
+declare function defineLivdCatalog(entries: readonly LivdEntry[], publication?: LivdPublication): LivdCatalog;
 
 /**
  * The **additive, advisory** LIVD annotation layer. {@link applyLivd}
@@ -5331,24 +6114,52 @@ declare function livdAmbiguousMapping(position: AstmPosition): AstmLivdWarning;
  * annotation, not a rewrite: the wire stays exactly as parsed.
  *
  * **The never-fabricate rule (the safety-critical point).** A vendor code with no
- * single LIVD mapping surfaces as a typed `unmapped`/`ambiguous`/`no-code`
- * annotation: **never** a guessed LOINC. A wrong LOINC mis-identifies a test, so
- * the layer only ever reports a LOINC the wire itself carried (an inline LOINC
- * candidate) or one the consumer's catalog vouched for (labeled `derived`), and
- * otherwise reports nothing but the miss.
+ * single LIVD mapping surfaces as a typed `unmapped`/`ambiguous`/`no-vendor-code`/
+ * `no-code` annotation: **never** a guessed LOINC. A wrong LOINC mis-identifies a
+ * test, so the only LOINC this layer ever reports is one the consumer's catalog
+ * vouched for (labeled `derived`), and otherwise it reports nothing but the miss.
+ *
+ * **The wire never answers the analyte-identity question.** The catalog is
+ * consulted whenever a vendor/local code is present, and it is consulted with that
+ * code alone. A populated component 1 rides along verbatim as
+ * {@link LivdAnnotation.unvalidatedWireValue}, is never validated, and is never
+ * reported as a LOINC. Where it differs from what the catalog vouched for, the
+ * difference is reported as its own fact
+ * ({@link LivdAnnotation.wireValueDisagreesWithCatalog}) and is **never resolved**:
+ * both values are surfaced, and nothing here picks between them.
+ *
+ * **The units DO answer, and only for choosing between the catalog's own
+ * candidates.** One vendor analyte code legitimately maps to several LOINCs that
+ * differ by reporting unit, so the catalog is consulted with the vendor code AND with
+ * the units field 5 of the `R` record carried, verbatim. That comparison is exact and
+ * case sensitive, never a UCUM semantic comparison, and a unit-selected answer says
+ * so on its output. It only ever narrows the candidate list the consumer's own
+ * catalog produced: it can never introduce a LOINC, never overrides the catalog, and
+ * a record with no readable units simply leaves the ambiguity standing.
+ *
+ * **The catalog's declared LOINC version rides on every annotation.** Where the
+ * consumer declared one, {@link LivdAnnotation.catalogLoincVersion} carries it
+ * verbatim on every annotation that catalog produced, whatever the outcome of the
+ * lookup, so a mapping says which version of LOINC it was made against and can be
+ * reproduced. It is provenance the CONSUMER declared and nothing else: no LOINC is
+ * validated against it, or against anything, here or anywhere in this package.
  */
 
 /**
- * The outcome of annotating one record's Universal Test ID against a LIVD catalog.
- * A distinct case per disposition; there is no case in which a LOINC is guessed.
+ * The outcome of looking one record's Universal Test ID up in a LIVD catalog: a
+ * closed, mutually exclusive discriminant. There is no case in which a LOINC is
+ * guessed, and no case in which a value the wire carried is reported as a LOINC.
  *
  * - `mapped`, the vendor/local code resolved to a single LOINC **via the catalog**
  *   (labeled `derived: true`, `source: "livd"`).
- * - `inline-loinc`, the wire itself carried a LOINC in the Universal Test ID's slot
- *   (component 1); surfaced `source: "wire"`, **not** derived and **not** validated.
- * - `unmapped`: a vendor/local code with no catalog entry.
+ * - `unmapped`: a vendor/local code was looked up and the catalog held no entry
+ *   for it (a hit whose LOINC is a zero-length string is reported here too: an
+ *   empty LOINC is not an answer).
  * - `ambiguous`: a vendor/local code matching more than one distinct LOINC; the
  *   candidates are surfaced but **none is chosen**.
+ * - `no-vendor-code`: component 1 is populated and there is no vendor/local code,
+ *   so nothing was looked up. The wire value is surfaced unvalidated, and is never
+ *   used as a lookup key: the catalog is keyed on the vendor transmission code.
  * - `no-code`: the record carried no usable test code at all (name-only/empty), so
  *   there was nothing to map.
  */
@@ -5356,24 +6167,38 @@ type LivdMapping = {
     readonly status: "mapped";
     readonly loinc: string;
     readonly loincLongName?: string;
+    /** The chosen catalog row's Vendor Specimen Description, verbatim, when supplied. */
+    readonly vendorSpecimenDescription?: string;
+    /** The chosen catalog row's Vendor Result Description, verbatim, when supplied. */
+    readonly vendorResultDescription?: string;
+    /** The chosen catalog row's representative unit, verbatim, when supplied. */
+    readonly representativeUnit?: string;
+    /**
+     * Present **if and only if** the record's units chose this LOINC from more than one candidate,
+     * and it states what that comparison was: verbatim and case sensitive, not UCUM semantic.
+     */
+    readonly unitComparison?: LivdUnitComparison;
     readonly source: "livd";
     readonly derived: true;
-} | {
-    readonly status: "inline-loinc";
-    readonly loinc: string;
-    readonly source: "wire";
 } | {
     readonly status: "unmapped";
 } | {
     readonly status: "ambiguous";
     readonly candidates: readonly string[];
+    /** Every candidate row with its LIVD attributes, when the catalog supplied any. */
+    readonly candidateDetails?: readonly LivdCandidate[];
+    /** Why the units did not settle it, when the catalog supplied the attributes to say. */
+    readonly reason?: LivdAmbiguityReason;
+} | {
+    readonly status: "no-vendor-code";
 } | {
     readonly status: "no-code";
 };
 /**
- * One record's LIVD annotation, which record, the code that was looked up
- * (verbatim), how it was recognized, and the mapping outcome. Additive: it points
- * at the record by index and never replaces it.
+ * One record's LIVD annotation: which record, the code the catalog was consulted
+ * with (verbatim), how it was recognized, the lookup outcome, and the two facts
+ * about a populated component 1 that ride alongside **any** outcome. Additive: it
+ * points at the record by index and never replaces it.
  *
  * @example
  * ```ts
@@ -5382,6 +6207,8 @@ type LivdMapping = {
  *   recordIndex: 3,
  *   recordType: "R",
  *   reportedCode: "687",
+ *   unvalidatedWireValue: "Glucose",
+ *   wireValueDisagreesWithCatalog: true,
  *   provenance: "local-code",
  *   mapping: { status: "mapped", loinc: "1920-8", source: "livd", derived: true },
  * };
@@ -5392,12 +6219,47 @@ interface LivdAnnotation {
     readonly recordIndex: number;
     /** The annotated record's type. */
     readonly recordType: "R" | "O";
-    /** The reported primary code that was looked up, verbatim; absent when the record carried no code. */
+    /**
+     * The vendor/local code the catalog was consulted with, verbatim. Absent when no
+     * vendor/local code was present, because then nothing was looked up. It is never
+     * a component 1 value.
+     */
     readonly reportedCode?: string;
-    /** How the reported code was recognized in the Universal Test ID (provenance only, never a lookup). */
+    /**
+     * Component 1 when populated, verbatim: a wire value this library **does not
+     * vouch for**, carried on every outcome and never validated, never promoted to a
+     * LOINC, and never used as a lookup key. Absent when component 1 is empty.
+     */
+    readonly unvalidatedWireValue?: string;
+    /**
+     * `true` if and only if the catalog vouched for exactly one LOINC for the
+     * vendor/local code, component 1 is populated, and that value is not
+     * byte-identical to that LOINC. `false` in **every** other case, including where
+     * the catalog vouched for no single LOINC (a miss, an ambiguity, no vendor code,
+     * no code at all): asserting a disagreement there would claim the catalog spoke
+     * about a code it never spoke about.
+     *
+     * It reports the difference and **nothing else**. Neither value is marked
+     * correct, neither is suppressed, and no field says the difference was settled.
+     */
+    readonly wireValueDisagreesWithCatalog: boolean;
+    /** How the identifier was recognized in the Universal Test ID (provenance only, never a lookup). */
     readonly provenance: UniversalTestIdProvenance;
-    /** The mapping outcome: never a guessed LOINC. */
+    /** The lookup outcome: never a guessed LOINC. */
     readonly mapping: LivdMapping;
+    /**
+     * The **LOINC version the catalog declared**, verbatim, carried on **every** annotation that
+     * catalog produced, whatever the outcome of the lookup. It is what makes a mapping reproducible:
+     * the reader can see which version of LOINC the consumer's catalog says it was built against.
+     *
+     * **It asserts nothing about this LOINC.** It is provenance about the CATALOG, not a claim that
+     * any LOINC was checked, found, or validated against that version: this package performs no
+     * LOINC validation of any kind, and nothing here reads the string beyond carrying it.
+     *
+     * Absent when the catalog declared no LOINC version (including a catalog a consumer implemented
+     * by hand, which declares none), never a default, a placeholder or an empty string.
+     */
+    readonly catalogLoincVersion?: string;
 }
 /**
  * The result of {@link applyLivd}: the per-record annotations (one per `R`/`O`
@@ -5407,7 +6269,15 @@ interface LivdAnnotation {
 interface LivdResult {
     /** One annotation per `R`/`O` record, in wire order. */
     readonly annotations: readonly LivdAnnotation[];
-    /** A value-free warning per `unmapped`/`ambiguous` code: never per `mapped`/`inline-loinc`/`no-code`. */
+    /**
+     * A value-free warning per `unmapped`/`ambiguous` code: never per `mapped`, and
+     * never per `no-vendor-code`/`no-code`, where no lookup happened at all.
+     *
+     * Per-record only. A warning about the CATALOG, such as one declaring no LOINC
+     * version, is raised where the catalog is defined and stays on
+     * {@link LivdCatalog.warnings}: it implicates no record, so it never joins this
+     * stream and never changes its codes, its order or its length.
+     */
     readonly warnings: readonly AstmLivdWarning[];
 }
 /**
@@ -5435,9 +6305,14 @@ declare function lookupLivdForRecord(record: ResultRecord | OrderRecord, catalog
  *
  * Fail-safe: with no matching entry a code is `unmapped` (+ an
  * `ASTM_LIVD_UNMAPPED_CODE` warning); with a conflicting mapping it is `ambiguous`
- * (+ an `ASTM_LIVD_AMBIGUOUS_MAPPING` warning); a LOINC is **never** guessed. When
- * the wire already carried an inline LOINC candidate, it is surfaced from the wire
- * (never overwritten by the catalog).
+ * (+ an `ASTM_LIVD_AMBIGUOUS_MAPPING` warning); a LOINC is **never** guessed. A
+ * populated component 1 never short-circuits the lookup and is never reported as a
+ * LOINC: it is carried verbatim as an unvalidated wire value, and where it differs
+ * from the catalog's answer the difference is reported and left unresolved.
+ *
+ * A catalog is code a consumer supplies, so a lookup that throws propagates to the
+ * caller unchanged: a consumer's own failure is never reported as a catalog miss,
+ * and no partially annotated result is returned.
  *
  * @param msg - A parsed ASTM message.
  * @param catalog - The consumer-supplied LIVD catalog (build with {@link defineLivdCatalog}).
@@ -5445,10 +6320,12 @@ declare function lookupLivdForRecord(record: ResultRecord | OrderRecord, catalog
  * @example
  * ```ts
  * import { parseAstmRecords, defineLivdCatalog, applyLivd } from "@cosyte/astm";
- * const msg = parseAstmRecords("H|\\^&\rR|1|^^^687|28.6|U/L||N||F\rL|1\r");
+ * const msg = parseAstmRecords("H|\\^&\rR|1|Glucose^^^687|28.6|U/L||N||F\rL|1\r");
  * const catalog = defineLivdCatalog([{ vendorCode: "687", loinc: "1920-8", loincLongName: "AST" }]);
- * const { annotations } = applyLivd(msg, catalog);
- * annotations[0]?.mapping; // { status: "mapped", loinc: "1920-8", loincLongName: "AST", source: "livd", derived: true }
+ * const [a] = applyLivd(msg, catalog).annotations;
+ * a?.mapping; // { status: "mapped", loinc: "1920-8", loincLongName: "AST", source: "livd", derived: true }
+ * a?.unvalidatedWireValue; // "Glucose": carried verbatim, vouched for by nothing
+ * a?.wireValueDisagreesWithCatalog; // true: reported, never resolved
  * ```
  */
 declare function applyLivd(msg: AstmMessage, catalog: LivdCatalog): LivdResult;
@@ -5490,8 +6367,8 @@ interface FrameChecksum {
  */
 interface AstmFrame {
     /**
-     * The frame's sequence number as read from the `FN` byte. Normally `0`–`7`; a
-     * value outside that range means the `FN` byte was not a `0`–`7` digit (a
+     * The frame's sequence number as read from the `FN` byte. Normally `0` to `7`; a
+     * value outside that range means the `FN` byte was not a `0` to `7` digit (a
      * corruption that also trips a sequence-gap warning). `undefined` when the frame
      * was too truncated to carry a frame number at all.
      */
@@ -5786,7 +6663,7 @@ declare function decodeAstmFrames(bytes: Uint8Array, options?: FrameOptions): De
  * - the **modulo-256 checksum** over `FN … terminator` (inclusive), emitted as two
  *   **uppercase** hex chars (the conservative-emit form the decoder accepts either
  *   case of);
- * - the **frame number** `0`–`7`, starting at `1` and rolling over `7 → 0 → 1`,
+ * - the **frame number** `0` to `7`, starting at `1` and rolling over `7 → 0 → 1`,
  *   continuous across every frame in the stream (as the decoder's sequence check
  *   expects); a caller may start the sequence elsewhere to compose one transfer
  *   across several calls, but only at a number a frame can actually carry;
@@ -6128,7 +7005,7 @@ declare function serializeFramedAstm(input: AstmMessage | readonly AstmRecord[],
  * @param bytes - The full decoded byte stream.
  * @param start - First index to include (the frame-number byte, one past `STX`).
  * @param endInclusive - Last index to include (the `ETB`/`ETX` terminator byte).
- * @returns The checksum in `0`–`255`.
+ * @returns The checksum in `0` to `255`.
  * @example
  * ```ts
  * import { computeChecksum } from "@cosyte/astm";
@@ -6141,7 +7018,7 @@ declare function computeChecksum(bytes: Uint8Array, start: number, endInclusive:
  * Format a checksum byte as the two **uppercase** hex characters ASTM puts on the
  * wire (the conservative-emit form). Decode accepts lowercase; emit is uppercase.
  *
- * @param checksum - A value in `0`–`255`.
+ * @param checksum - A value in `0` to `255`.
  * @returns Two uppercase hex characters, zero-padded (e.g. `"0A"`, `"75"`).
  * @example
  * ```ts
@@ -6159,7 +7036,7 @@ declare function toChecksumHex(checksum: number): string;
  * @param bytes - The full decoded byte stream.
  * @param i0 - Index of the high hex nibble (immediately after the terminator).
  * @param i1 - Index of the low hex nibble.
- * @returns The declared checksum in `0`–`255`, or `undefined` if unreadable.
+ * @returns The declared checksum in `0` to `255`, or `undefined` if unreadable.
  * @example
  * ```ts
  * import { parseChecksumHex } from "@cosyte/astm";
@@ -6271,4 +7148,4 @@ declare class AstmFrameStrictError extends Error {
  */
 declare const VERSION: string;
 
-export { ALL_ASTM_WARNING_CODES, AMBIGUOUS_CODES, ACK as ASTM_ACK, ENQ as ASTM_ENQ, EOT as ASTM_EOT, NAK as ASTM_NAK, type AbnormalFlag, type AbnormalFlagCode, type AbnormalFlagMeaning, type AmbiguousAlignmentSink, type AmbiguousCode, type AnyAstmWarningCode, AstmAmbiguousStreamError, type AstmDate, type AstmDatePrecision, type AstmField, type AstmFrame, AstmFrameEncodeError, type AstmFrameEncodeErrorCode, type AstmFramePosition, AstmFrameStrictError, type AstmFrameWarning, type AstmFraming, type AstmLivdWarning, type AstmLtpWarning, type AstmMessage, type AstmMessageClassification, type AstmMessageKind, AstmParseError, type AstmParseOptions, type AstmPosition, type AstmProfile, AstmProfileDefinitionError, type AstmProfileProvenance, type AstmQuirkMatch, type AstmQuirkTolerance, type AstmRecord, type AstmRecordInput, type AstmRecordWarning, AstmSerializeError, type AstmSerializeErrorCode, type AstmStreamMessage, AstmStrictError, CANONICAL_DELIMITERS, type CommentInput, type CommentRecord, type ComposeFramesOptions, type DecodeAstmFramesResult, type DefineAstmProfileOptions, type DelimiterDeclarationFault, type DelimiterReadResult, type Delimiters, type DetectFramingOptions, type DetectFramingResult, FATAL_CODES, FRAME_WARNING_CODES, type FatalCode, type FrameChecksum, type FrameOptions, type FrameTerminator, type FrameWarningCode, type FramedAstmResult, type HeaderInput, type HeaderRecord, LIVD_WARNING_CODES, LTP_WARNING_CODES, type LivdAnnotation, type LivdCatalog, type LivdEntry, type LivdLookup, type LivdMapping, type LivdResult, type LivdWarningCode, type LtpAction, type LtpEvent, type LtpPhase, type LtpState, type LtpTransition, type LtpWarningCode, type ManufacturerRecord, type MessageInput, type OrderInput, type OrderRecord, type PatientInput, type PatientName, type PatientNameInput, type PatientRecord, type QueryInput, type QueryRecord, type ReferenceRange, type ReferenceRangeKind, type ResultInput, type ResultRecord, type ResultStatus, type ResultStatusCode, type ResultStatusMeaning, SAFETY_CRITICAL_CODES, type ScientificRecord, type ShiftedComponentsSink, type ShiftedFieldsSink, type SwallowedDelimiterSink, TOLERABLE_CODES, type TerminatorRecord, type TruncatedFieldSink, type UniversalTestId, type UniversalTestIdProvenance, type UnknownEscapeSink, type UnpairedEscapeSink, type UnsupportedRecord, VERSION, type VerbatimInput, WARNING_CODES, type WarningCode, alignmentShiftedComponents, alignmentShiftedFields, alignmentTruncatedField, ambiguousEscapeAlignment, ambiguousMessageKind, ambiguousValueSplit, applyAstmProfile, applyAstmProfileToWarnings, applyLivd, astmDateToLocalISO, astmProfiles, attachComments, buildAstmMessage, classifyMessage, comments, commentsFor, composeAstmFrames, computeChecksum, decodeAstmFrames, decodeEscapes, deepFreeze, defineAstmProfile, defineLivdCatalog, delimiterRoleCollision, delimiterSwallowedByEscape, delimitersRedeclared, detectFraming, encodeComponent, fieldScalar, fieldsUnseparated, frameBadChecksum, frameOversize, frameSequenceGap, frameUnterminated, getAstmProfile, getDefaultAstmProfile, hasCollidingRoles, interpretAbnormalFlag, interpretResultStatus, isNonStandard, isSafetyCriticalCode, listAstmProfiles, livdAmbiguousMapping, livdUnmappedCode, lookupLivdForRecord, ltpAmbiguousTransport, ltpFrameRejected, ltpInitialState, ltpReduce, ltpUnexpectedEvent, messages, nonStandardDelimiters, orders, orphanComment, parseAstmDate, parseAstmRecords, parseChecksumHex, parseFramedAstm, parseReferenceRange, partialTimestamp, patient, primaryCode, profileQuirkApplied, query, readDelimiterDeclaration, readDelimiters, recognizeUniversalTestId, resolveProfileTransport, results, serializeAstmRecord, serializeAstmRecords, serializeField, serializeFramedAstm, setDefaultAstmProfile, splitEscapeAware, toChecksumHex, tokenizeHeader, tokenizeRecord, undefinedAbnormalFlag, undefinedResultStatus, uninterpretedQueryStatus, unitsAbsent, unknownEscapeSequence, unknownRecordType, unpairedEscapeCharacter, unparseableReferenceRange, unreadableRedeclaration };
+export { ABNORMAL_FLAG_CODES, ABNORMAL_FLAG_VOCABULARY, ALL_ASTM_WARNING_CODES, AMBIGUOUS_CODES, ACK as ASTM_ACK, ENQ as ASTM_ENQ, EOT as ASTM_EOT, NAK as ASTM_NAK, type AbnormalFlag, type AbnormalFlagCode, type AbnormalFlagMeaning, type AmbiguousAlignmentSink, type AmbiguousCode, type AnyAstmWarningCode, AstmAmbiguousStreamError, type AstmDate, type AstmDatePrecision, type AstmField, type AstmFrame, AstmFrameEncodeError, type AstmFrameEncodeErrorCode, type AstmFramePosition, AstmFrameStrictError, type AstmFrameWarning, type AstmFraming, type AstmLivdCatalogWarning, type AstmLivdWarning, type AstmLtpWarning, type AstmMessage, type AstmMessageClassification, type AstmMessageKind, AstmParseError, type AstmParseOptions, type AstmPosition, type AstmProfile, AstmProfileDefinitionError, type AstmProfileProvenance, type AstmQuirkMatch, type AstmQuirkTolerance, type AstmRecord, type AstmRecordInput, type AstmRecordWarning, AstmSerializeError, type AstmSerializeErrorCode, type AstmStreamMessage, AstmStrictError, CANONICAL_DELIMITERS, type CommentInput, type CommentRecord, type ComposeFramesOptions, type DateParts, type DecodeAstmFramesResult, type DefineAstmProfileOptions, type DelimiterDeclarationFault, type DelimiterReadResult, type Delimiters, type DetectFramingOptions, type DetectFramingResult, FATAL_CODES, FRAME_WARNING_CODES, type FatalCode, type FrameChecksum, type FrameOptions, type FrameTerminator, type FrameWarningCode, type FramedAstmResult, type HeaderInput, type HeaderRecord, LIVD_CATALOG_IDENTITY_UNDECLARED, LIVD_WARNING_CODES, LTP_WARNING_CODES, type LivdAmbiguityReason, type LivdAnnotation, type LivdCandidate, type LivdCatalog, type LivdCatalogIdentity, type LivdEntry, type LivdLookup, type LivdMapping, type LivdPublication, type LivdResult, type LivdUnitComparison, type LivdWarningCode, type LtpAction, type LtpEvent, type LtpPhase, type LtpState, type LtpTransition, type LtpWarningCode, type ManufacturerRecord, type MessageInput, type NamedVocabulary, type OrderInput, type OrderRecord, type PatientInput, type PatientName, type PatientNameInput, type PatientRecord, type QueryInput, type QueryRecord, RESULT_STATUS_VOCABULARY, type ReferenceRange, type ReferenceRangeKind, type ResultInput, type ResultRecord, type ResultStatus, type ResultStatusCode, type ResultStatusMeaning, SAFETY_CRITICAL_CODES, type ScientificRecord, type ShiftedComponentsSink, type ShiftedFieldsSink, type SwallowedDelimiterSink, TOLERABLE_CODES, type TerminatorRecord, type ToDateOptions, type TruncatedFieldSink, type UnattributedVocabulary, type UniversalTestId, type UniversalTestIdProvenance, type UnknownEscapeSink, type UnpairedEscapeSink, type UnsupportedRecord, VERSION, type VerbatimInput, type VocabularyAttribution, WARNING_CODES, type WarningCode, alignmentShiftedComponents, alignmentShiftedFields, alignmentTruncatedField, ambiguousEscapeAlignment, ambiguousMessageKind, ambiguousValueSplit, applyAstmProfile, applyAstmProfileToWarnings, applyLivd, astmDateToLocalISO, astmProfiles, attachComments, buildAstmMessage, classifyMessage, comments, commentsFor, composeAstmFrames, computeChecksum, decodeAstmFrames, decodeEscapes, deepFreeze, defineAstmProfile, defineLivdCatalog, delimiterRoleCollision, delimiterSwallowedByEscape, delimitersRedeclared, describeVocabulary, detectFraming, encodeComponent, fieldScalar, fieldsUnseparated, frameBadChecksum, frameOversize, frameSequenceGap, frameUnterminated, getAstmProfile, getDefaultAstmProfile, hasCollidingRoles, interpretAbnormalFlag, interpretResultStatus, isNonStandard, isSafetyCriticalCode, listAstmProfiles, livdAmbiguousMapping, livdCatalogMissingLoincVersion, livdUnmappedCode, lookupLivdForRecord, ltpAmbiguousTransport, ltpFrameRejected, ltpInitialState, ltpReduce, ltpUnexpectedEvent, messages, nonStandardDelimiters, orders, orphanComment, parseAstmDate, parseAstmRecords, parseChecksumHex, parseFramedAstm, parseReferenceRange, partialTimestamp, patient, primaryCode, profileQuirkApplied, query, readDelimiterDeclaration, readDelimiters, recognizeUniversalTestId, resolveProfileTransport, results, serializeAstmRecord, serializeAstmRecords, serializeField, serializeFramedAstm, setDefaultAstmProfile, splitEscapeAware, toChecksumHex, toDate, toISO, toObject, tokenizeHeader, tokenizeRecord, undefinedAbnormalFlag, undefinedResultStatus, uninterpretedQueryStatus, unitsAbsent, unknownEscapeSequence, unknownRecordType, unpairedEscapeCharacter, unparseableReferenceRange, unreadableRedeclaration };