@cosyte/astm 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,3861 @@
+/**
+ * Positional context shared by warnings and fatal errors in the `@cosyte/astm`
+ * record layer.
+ *
+ * **PHI discipline (the whole point).** A position identifies *where* a
+ * deviation occurred — the record's ordinal index, its type letter, and the
+ * 1-based field / component indices — and **never** carries a field value. A
+ * warning or error may be logged verbatim without leaking a patient name, an
+ * identifier, or a result value.
+ */
+/**
+ * Where in a record stream a warning or fatal originated. Every field is
+ * positional; none is a value.
+ *
+ * @example
+ * ```ts
+ * import type { AstmPosition } from "@cosyte/astm";
+ * const at: AstmPosition = { recordIndex: 3, recordType: "R", fieldIndex: 4 };
+ * ```
+ */
+interface AstmPosition {
+    /** 0-based ordinal of the record within the message. */
+    readonly recordIndex: number;
+    /** The record's type letter (`H`/`P`/`O`/`R`/`L`/…), when known. */
+    readonly recordType?: string;
+    /** 1-based field index within the record (ASTM fields are 1-indexed). */
+    readonly fieldIndex?: number;
+    /** 1-based component index within the field, when the deviation is component-scoped. */
+    readonly componentIndex?: number;
+}
+
+/**
+ * Tier-2 warning registry and factories for the `@cosyte/astm` record parser.
+ *
+ * A warning is the lenient parser's record of a tolerated deviation: it never
+ * throws, never drops data, and never fabricates a value. Consumers compare
+ * `warning.code === WARNING_CODES.<CODE>` to react; renaming a code is a
+ * **breaking change**. Every warning carries a stable code plus a
+ * {@link AstmPosition} and **never** a field value (PHI discipline).
+ */
+
+/**
+ * Stable string codes for every Tier-2 warning the record parser may emit.
+ * `key === value` so `Object.values(...)` yields a stable snapshot set.
+ *
+ * @example
+ * ```ts
+ * import { parseAstmRecords, WARNING_CODES } from "@cosyte/astm";
+ * const msg = parseAstmRecords("H|\\^&\rL|1\r");
+ * msg.warnings.some((w) => w.code === WARNING_CODES.ASTM_RECORD_UNKNOWN_TYPE);
+ * ```
+ */
+declare const WARNING_CODES: {
+    /** A record's type letter is not one of the modeled types — surfaced as an unsupported record. */
+    readonly ASTM_RECORD_UNKNOWN_TYPE: "ASTM_RECORD_UNKNOWN_TYPE";
+    /** The header declared delimiters other than the canonical `H|\^&` — tolerated, noted. */
+    readonly ASTM_NONSTANDARD_DELIMITERS: "ASTM_NONSTANDARD_DELIMITERS";
+    /** An escape sequence body was not one of `&F&`/`&S&`/`&R&`/`&E&` — preserved verbatim. */
+    readonly ASTM_UNKNOWN_ESCAPE_SEQUENCE: "ASTM_UNKNOWN_ESCAPE_SEQUENCE";
+    /**
+     * A result value field carried an *unescaped* component delimiter, so it split into more than one
+     * component. Both the full raw value and the split are surfaced and this warning fires — the
+     * ambiguity is never resolved silently into a truncated value.
+     */
+    readonly ASTM_RECORD_AMBIGUOUS_VALUE_SPLIT: "ASTM_RECORD_AMBIGUOUS_VALUE_SPLIT";
+    /**
+     * A result's abnormal-flag field (`R` field 7) carried a letter outside HL7 Table 0078. The flag is
+     * surfaced as `undefined` — never dropped, and **never coerced to `normal`** (a clinical error).
+     */
+    readonly ASTM_RECORD_UNDEFINED_ABNORMAL_FLAG: "ASTM_RECORD_UNDEFINED_ABNORMAL_FLAG";
+    /**
+     * A result's status field (`R` field 9) carried a letter that is not a recognized status. It is
+     * surfaced as `undefined` and, like every non-`F` status, never reads as active-final.
+     */
+    readonly ASTM_RECORD_UNDEFINED_RESULT_STATUS: "ASTM_RECORD_UNDEFINED_RESULT_STATUS";
+    /**
+     * A result's reference-range field (`R` field 6) did not match a recognized form (`low-high`,
+     * `<high`, `>low`). The text is surfaced verbatim as `unparsed` — a bound is **never fabricated**.
+     */
+    readonly ASTM_RECORD_UNPARSEABLE_REFERENCE_RANGE: "ASTM_RECORD_UNPARSEABLE_REFERENCE_RANGE";
+    /**
+     * A result carried a numeric value but no units (`R` field 5 empty). Units are vendor free text
+     * (not UCUM); a missing unit is flagged here and **never defaulted, guessed, or converted**.
+     */
+    readonly ASTM_RECORD_UNITS_ABSENT: "ASTM_RECORD_UNITS_ABSENT";
+    /**
+     * A `C` (comment) record had no valid preceding `H`/`P`/`O`/`R` parent — an **orphan**. The comment
+     * is attached to the message root (`attachedToRoot: true`) and surfaced, **never dropped**.
+     */
+    readonly ASTM_RECORD_ORPHAN_COMMENT: "ASTM_RECORD_ORPHAN_COMMENT";
+    /**
+     * A `YYYYMMDDHHMMSS` timestamp had an odd digit run that truncates a two-digit component in half
+     * (e.g. a partial day/hour). The raw run is preserved and the structured value stops at the last
+     * **complete** component — the dangling digit is **never zero-filled into a fabricated time**.
+     */
+    readonly ASTM_RECORD_PARTIAL_TIMESTAMP: "ASTM_RECORD_PARTIAL_TIMESTAMP";
+    /**
+     * A `Q` (request-information) record carried a request-information status code (field 13). The code
+     * *set* is `[OSS-derived / paywalled]` with no publicly-groundable enumeration, so the parser
+     * interprets **none** of them: the status is surfaced verbatim and this value-free warning flags that
+     * it was passed through **uninterpreted** — never mapped to a guessed meaning.
+     */
+    readonly ASTM_RECORD_UNINTERPRETED_QUERY_STATUS: "ASTM_RECORD_UNINTERPRETED_QUERY_STATUS";
+    /**
+     * A message carried **both** a `Q` (request) and an `R` (result) record — a contradictory shape. The
+     * message is classified `host-query` (the `Q` **dominates**, so it is never read as a result set) and
+     * this warning flags the anomaly. Positional context only; no field value.
+     */
+    readonly ASTM_RECORD_AMBIGUOUS_MESSAGE_KIND: "ASTM_RECORD_AMBIGUOUS_MESSAGE_KIND";
+    /**
+     * The downgraded form an active vendor {@link AstmProfile} produces from a deviation it *expects*
+     * (see `src/profiles/`). The original warning is **never dropped**: its code moves to
+     * {@link AstmRecordWarning.toleratedCode}, the warning is re-badged `PROFILE_QUIRK_APPLIED` with
+     * `expected: true` and the tolerating profile named, so a consumer can filter known, grounded noise
+     * while the fact of the deviation — and where it was — survives. A profile can only ever reach this
+     * path for a **non-safety-critical** code (enforced at profile-definition time); a safety-critical
+     * deviation (a result value, flag, status, patient identifier, code system, or a frame-integrity
+     * warning) can **never** be tolerated, so it can never be re-badged here.
+     */
+    readonly PROFILE_QUIRK_APPLIED: "PROFILE_QUIRK_APPLIED";
+};
+/**
+ * Discriminant type for {@link AstmRecordWarning.code}. Narrowing by this code
+ * lets consumers write exhaustive `switch` blocks and guarantees a typo-free
+ * comparison against {@link WARNING_CODES}.
+ */
+type WarningCode = (typeof WARNING_CODES)[keyof typeof WARNING_CODES];
+/**
+ * A single Tier-2 warning: a stable code, a value-free human-readable message,
+ * and positional context. Plain data, accumulated onto `AstmMessage.warnings`.
+ *
+ * @example
+ * ```ts
+ * import type { AstmRecordWarning } from "@cosyte/astm";
+ * const w: AstmRecordWarning = {
+ *   code: "ASTM_RECORD_UNKNOWN_TYPE",
+ *   message: "Unknown record type.",
+ *   position: { recordIndex: 2, recordType: "Z" },
+ * };
+ * ```
+ */
+interface AstmRecordWarning {
+    readonly code: WarningCode;
+    /** Human-readable detail for logs. Never contains a field value. */
+    readonly message: string;
+    readonly position: AstmPosition;
+    /**
+     * `true` when an active vendor {@link AstmProfile} *expected* this deviation and re-badged it as a
+     * {@link WARNING_CODES.PROFILE_QUIRK_APPLIED}. An `expected` warning does **not** escalate to a
+     * thrown `AstmStrictError` in strict mode (the whole point of the profile is that this deviation is
+     * known and benign) — it is still recorded, so nothing is hidden. Absent on an untolerated warning.
+     */
+    readonly expected?: boolean;
+    /** The name of the {@link AstmProfile} that tolerated this warning, when `expected`. */
+    readonly profile?: string;
+    /**
+     * When `code` is {@link WARNING_CODES.PROFILE_QUIRK_APPLIED}, the original warning code the profile
+     * tolerated — so a consumer can still see *which* deviation was re-badged as expected.
+     */
+    readonly toleratedCode?: WarningCode;
+}
+/**
+ * Build an `ASTM_RECORD_UNKNOWN_TYPE` warning. The record is still surfaced (as
+ * an unsupported record), never dropped.
+ *
+ * @example
+ * ```ts
+ * import { unknownRecordType } from "@cosyte/astm";
+ * unknownRecordType({ recordIndex: 3, recordType: "Z" });
+ * ```
+ */
+declare function unknownRecordType(position: AstmPosition): AstmRecordWarning;
+/**
+ * Build an `ASTM_NONSTANDARD_DELIMITERS` warning. The declared delimiters are
+ * used as-is; this only flags that they differ from the canonical set.
+ *
+ * @example
+ * ```ts
+ * import { nonStandardDelimiters } from "@cosyte/astm";
+ * nonStandardDelimiters({ recordIndex: 0, recordType: "H" });
+ * ```
+ */
+declare function nonStandardDelimiters(position: AstmPosition): AstmRecordWarning;
+/**
+ * Build an `ASTM_UNKNOWN_ESCAPE_SEQUENCE` warning. The sequence is preserved
+ * verbatim in the decoded value; the warning body carries neither the sequence
+ * nor its surrounding text.
+ *
+ * @example
+ * ```ts
+ * import { unknownEscapeSequence } from "@cosyte/astm";
+ * unknownEscapeSequence({ recordIndex: 4, recordType: "R", fieldIndex: 4 });
+ * ```
+ */
+declare function unknownEscapeSequence(position: AstmPosition): AstmRecordWarning;
+/**
+ * Build an `ASTM_RECORD_AMBIGUOUS_VALUE_SPLIT` warning. Emitted when a result
+ * value field split on an unescaped component delimiter — the full raw value and
+ * the split are both surfaced, never a silent truncation.
+ *
+ * @example
+ * ```ts
+ * import { ambiguousValueSplit } from "@cosyte/astm";
+ * ambiguousValueSplit({ recordIndex: 3, recordType: "R", fieldIndex: 4 });
+ * ```
+ */
+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.
+ *
+ * @example
+ * ```ts
+ * import { undefinedAbnormalFlag } from "@cosyte/astm";
+ * undefinedAbnormalFlag({ recordIndex: 4, recordType: "R", fieldIndex: 7 });
+ * ```
+ */
+declare function undefinedAbnormalFlag(position: AstmPosition): AstmRecordWarning;
+/**
+ * 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.
+ *
+ * @example
+ * ```ts
+ * import { undefinedResultStatus } from "@cosyte/astm";
+ * undefinedResultStatus({ recordIndex: 4, recordType: "R", fieldIndex: 9 });
+ * ```
+ */
+declare function undefinedResultStatus(position: AstmPosition): AstmRecordWarning;
+/**
+ * Build an `ASTM_RECORD_UNPARSEABLE_REFERENCE_RANGE` warning. The range text is
+ * surfaced verbatim as `unparsed`; no bound is fabricated.
+ *
+ * @example
+ * ```ts
+ * import { unparseableReferenceRange } from "@cosyte/astm";
+ * unparseableReferenceRange({ recordIndex: 4, recordType: "R", fieldIndex: 6 });
+ * ```
+ */
+declare function unparseableReferenceRange(position: AstmPosition): AstmRecordWarning;
+/**
+ * Build an `ASTM_RECORD_UNITS_ABSENT` warning. Emitted when a result carries a
+ * numeric value but no units; units are never defaulted, guessed, or converted.
+ *
+ * @example
+ * ```ts
+ * import { unitsAbsent } from "@cosyte/astm";
+ * unitsAbsent({ recordIndex: 4, recordType: "R", fieldIndex: 5 });
+ * ```
+ */
+declare function unitsAbsent(position: AstmPosition): AstmRecordWarning;
+/**
+ * Build an `ASTM_RECORD_ORPHAN_COMMENT` warning. Emitted when a `C` record had no
+ * valid preceding `H`/`P`/`O`/`R` parent; the comment is attached to the message
+ * root and surfaced, never dropped.
+ *
+ * @example
+ * ```ts
+ * import { orphanComment } from "@cosyte/astm";
+ * orphanComment({ recordIndex: 5, recordType: "C" });
+ * ```
+ */
+declare function orphanComment(position: AstmPosition): AstmRecordWarning;
+/**
+ * Build an `ASTM_RECORD_PARTIAL_TIMESTAMP` warning. Emitted when a
+ * `YYYYMMDDHHMMSS` value had an odd digit run that truncates a component; the raw
+ * run is preserved and no time is fabricated.
+ *
+ * @example
+ * ```ts
+ * import { partialTimestamp } from "@cosyte/astm";
+ * partialTimestamp({ recordIndex: 2, recordType: "P", fieldIndex: 8 });
+ * ```
+ */
+declare function partialTimestamp(position: AstmPosition): AstmRecordWarning;
+/**
+ * Build an `ASTM_RECORD_UNINTERPRETED_QUERY_STATUS` warning. Emitted when a `Q`
+ * record carries a request-information status code; the code set is paywalled, so
+ * the status is surfaced verbatim and never mapped to a guessed meaning.
+ *
+ * @example
+ * ```ts
+ * import { uninterpretedQueryStatus } from "@cosyte/astm";
+ * uninterpretedQueryStatus({ recordIndex: 2, recordType: "Q", fieldIndex: 13 });
+ * ```
+ */
+declare function uninterpretedQueryStatus(position: AstmPosition): AstmRecordWarning;
+/**
+ * Build an `ASTM_RECORD_AMBIGUOUS_MESSAGE_KIND` warning. Emitted when a message
+ * carries both a `Q` (request) and an `R` (result) record; the message is
+ * classified as a host-query request (the `Q` dominates) and the anomaly is
+ * flagged.
+ *
+ * @example
+ * ```ts
+ * import { ambiguousMessageKind } from "@cosyte/astm";
+ * ambiguousMessageKind({ recordIndex: 0, recordType: "H" });
+ * ```
+ */
+declare function ambiguousMessageKind(position: AstmPosition): AstmRecordWarning;
+/**
+ * Build a `PROFILE_QUIRK_APPLIED` warning — the downgraded form an active vendor profile produces from
+ * a deviation it *expects*. The original warning is **not dropped**: its `code` moves to
+ * `toleratedCode`, the warning is re-badged `PROFILE_QUIRK_APPLIED`, `expected` is set, and the
+ * tolerating profile is named. The original `position` and `message` are preserved (both PHI-free by
+ * the same construction as every other factory), so a consumer can filter known, grounded noise while
+ * the fact of the deviation, and where it was, survive. A profile can only ever reach this path for a
+ * **non-safety-critical** code (enforced at profile-definition time by the safety gate).
+ *
+ * @param original - The warning the profile tolerated.
+ * @param profileName - The name of the tolerating profile.
+ * @returns The re-badged, still-informative warning.
+ * @example
+ * ```ts
+ * import { profileQuirkApplied, unknownEscapeSequence } from "@cosyte/astm";
+ * const original = unknownEscapeSequence({ recordIndex: 4, recordType: "R", fieldIndex: 5 });
+ * const w = profileQuirkApplied(original, "referenceCorpus");
+ * w.code; // "PROFILE_QUIRK_APPLIED"
+ * w.toleratedCode; // "ASTM_UNKNOWN_ESCAPE_SEQUENCE"
+ * ```
+ */
+declare function profileQuirkApplied(original: AstmRecordWarning, profileName: string): AstmRecordWarning;
+
+/**
+ * The ASTM delimiter model and its self-declaration reader.
+ *
+ * ASTM/CLSI-LIS02 messages are **self-describing**: every `H` (header) record
+ * declares the four delimiters it uses, in the bytes immediately after the `H`.
+ * A parser MUST read them from the record and MUST NOT hardcode them — a vendor
+ * is free to declare non-standard delimiters and a conformant reader follows.
+ *
+ * The canonical declaration is `H|\^&`:
+ *
+ * | position                 | char | role                    |
+ * |--------------------------|------|-------------------------|
+ * | immediately after `H`    | `\|`  | **field** delimiter     |
+ * | delimiter-definition [0] | `\`  | **repeat** delimiter    |
+ * | delimiter-definition [1] | `^`  | **component** delimiter |
+ * | delimiter-definition [2] | `&`  | **escape** delimiter    |
+ *
+ * Note ASTM differs from HL7 v2 here: ASTM's `\` is the **repeat** delimiter and
+ * `&` is the **escape** delimiter, where HL7 uses `\` for escape and `~` for
+ * repetition. Getting this mapping wrong silently mis-reads values, so the roles
+ * are read positionally from the record, never assumed.
+ */
+/**
+ * The four ASTM delimiters resolved from an `H` record. Immutable; carried on
+ * the parsed message as delimiter provenance.
+ *
+ * @example
+ * ```ts
+ * import { readDelimiters } from "@cosyte/astm";
+ * const d = readDelimiters("H|\\^&");
+ * d.field;     // "|"
+ * d.repeat;    // "\\"
+ * d.component; // "^"
+ * d.escape;    // "&"
+ * ```
+ */
+interface Delimiters {
+    /** Field separator — the char immediately after `H` in the header. */
+    readonly field: string;
+    /** Repeat (repetition) separator — ASTM `\` by default. */
+    readonly repeat: string;
+    /** Component separator — ASTM `^` by default. */
+    readonly component: string;
+    /** Escape character — ASTM `&` by default (introduces `&F&`/`&S&`/`&R&`/`&E&`). */
+    readonly escape: string;
+}
+/**
+ * The canonical ASTM delimiter set (`H|\^&`). Used only as documentation and as
+ * a comparison baseline for the non-standard-delimiter warning — never as a
+ * parse-time default (delimiters are always read from the header).
+ *
+ * @example
+ * ```ts
+ * import { CANONICAL_DELIMITERS } from "@cosyte/astm";
+ * CANONICAL_DELIMITERS.repeat; // "\\"
+ * ```
+ */
+declare const CANONICAL_DELIMITERS: Delimiters;
+/**
+ * Read the four delimiters from a header record's raw text (a single `H`
+ * record, its terminator already stripped).
+ *
+ * Returns `{ ok: false }` when the record cannot declare all four delimiters —
+ * it is shorter than `H` + a field separator + a 3-char delimiter definition —
+ * which the caller escalates to the `ASTM_RECORD_UNDECLARED_DELIMITERS` fatal.
+ * This function does not throw; delimiter resolution and the fatal decision are
+ * kept separate so the reader stays pure and testable.
+ *
+ * @param headerRecord - The raw `H` record text (no trailing CR/LF).
+ * @returns The resolved delimiters, or a declared failure.
+ * @example
+ * ```ts
+ * import { readDelimiters } from "@cosyte/astm";
+ * const d = readDelimiters("H|\\^&|||sender");
+ * d.field; // "|"
+ * ```
+ */
+declare function readDelimiters(headerRecord: string): Delimiters | undefined;
+/**
+ * Whether a resolved delimiter set differs from the canonical `H|\^&`. A `true`
+ * result is a tolerated vendor quirk, surfaced as a value-free warning so a
+ * consumer can notice a non-standard stream without the parser refusing it.
+ *
+ * @example
+ * ```ts
+ * import { isNonStandard, readDelimiters } from "@cosyte/astm";
+ * isNonStandard(readDelimiters("H|\\^&")!); // false
+ * ```
+ */
+declare function isNonStandard(d: Delimiters): boolean;
+
+/**
+ * The ASTM date/time value — `YYYYMMDDHHMMSS`, precision-preserving, no timezone.
+ *
+ * ASTM timestamps are a run of digits, most-significant first, truncated at
+ * whatever precision the instrument reports. There is **no timezone field**:
+ * the value is local to the instrument and this parser never assumes UTC. A
+ * date-only value (`YYYYMMDD`) is a normal, complete value at day precision —
+ * **not** an error and never zero-filled into a fake time.
+ */
+/** The precision to which an {@link AstmDate} is populated. */
+type AstmDatePrecision = "year" | "month" | "day" | "hour" | "minute" | "second";
+/**
+ * A parsed ASTM date/time. Immutable plain data; the populated fields extend
+ * exactly as far as {@link AstmDate.precision}. Absent components are left
+ * `undefined` rather than defaulted, so a consumer can tell "midnight" from
+ * "no time given". No timezone is modeled — the value is instrument-local.
+ *
+ * @example
+ * ```ts
+ * import { parseAstmDate } from "@cosyte/astm";
+ * const d = parseAstmDate("20240315");
+ * d?.precision; // "day"
+ * d?.hour;      // undefined  (not 0)
+ * ```
+ */
+interface AstmDate {
+    /** The raw digit string as it appeared on the wire. */
+    readonly raw: string;
+    readonly year: number;
+    readonly month?: number;
+    readonly day?: number;
+    readonly hour?: number;
+    readonly minute?: number;
+    readonly second?: number;
+    /** How far the components are populated. */
+    readonly precision: AstmDatePrecision;
+    /**
+     * `true` when the digit run does **not** align to a whole-component boundary — an odd number of
+     * digits that cuts a two-digit component (month/day/hour/minute/second) in half (lengths 5, 7, 9,
+     * 11, 13). The full run is preserved in {@link AstmDate.raw} and the structured value is truncated
+     * to the last **complete** component — the dangling digit is **never zero-filled into a fabricated
+     * time**. Absent (never `false`) for a clean value. A caller surfaces this as a value-free
+     * `ASTM_RECORD_PARTIAL_TIMESTAMP` warning.
+     */
+    readonly truncated?: true;
+}
+/**
+ * Parse an ASTM `YYYYMMDDHHMMSS` value, preserving whatever precision is
+ * present. Returns `undefined` for a value that is not a usable timestamp (fewer
+ * than four leading digits for the year, or non-digit content) — a caller keeps
+ * the raw field text either way, so nothing is lost. A partial value is parsed,
+ * never rejected.
+ *
+ * Extra trailing digits beyond seconds (fractional seconds some vendors append)
+ * are ignored for the structured value; the full input remains in {@link AstmDate.raw}.
+ *
+ * @param raw - The raw field text.
+ * @returns The parsed date, or `undefined` when it is not a timestamp.
+ * @example
+ * ```ts
+ * import { parseAstmDate } from "@cosyte/astm";
+ * parseAstmDate("20240315093000")?.precision; // "second"
+ * parseAstmDate("202403")?.precision;          // "month"
+ * ```
+ */
+declare function parseAstmDate(raw: string): AstmDate | undefined;
+/**
+ * Render an {@link AstmDate} as an ISO-8601-*like* string truncated to its
+ * precision, with **no** `Z` and **no** offset — because ASTM carries no
+ * timezone and appending one would fabricate information. A consumer that knows
+ * the instrument's zone can attach it; this function never assumes UTC.
+ *
+ * @param d - The date to render.
+ * @returns e.g. `"2024-03-15T09:30"` (minute precision) or `"2024-03"` (month).
+ * @example
+ * ```ts
+ * import { astmDateToLocalISO, parseAstmDate } from "@cosyte/astm";
+ * astmDateToLocalISO(parseAstmDate("20240315")!); // "2024-03-15"
+ * ```
+ */
+declare function astmDateToLocalISO(d: AstmDate): string;
+
+/**
+ * Code-system **provenance recognition** for the ASTM Universal Test ID.
+ *
+ * ASTM carries a test identifier as a caret-component field (`^^^687`): the
+ * 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 4** is the vendor/local code — the identifier that is actually
+ *   present, and therefore the **primary** identifier 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.
+ */
+/** 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"
+/** Only the test name (component 2) is present — no code. */
+ | "name-only"
+/** Nothing usable in the field. */
+ | "empty";
+/**
+ * A recognized ASTM Universal Test ID. All components are surfaced verbatim
+ * (already escape-decoded by the tokenizer); nothing is looked up.
+ *
+ * @example
+ * ```ts
+ * import { recognizeUniversalTestId } from "@cosyte/astm";
+ * const u = recognizeUniversalTestId(["", "", "", "687"]);
+ * u.localCode;   // "687"
+ * u.provenance;  // "local-code"
+ * ```
+ */
+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 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. */
+    readonly localCode?: string;
+    /** Where the primary identifier came from. */
+    readonly provenance: UniversalTestIdProvenance;
+}
+/**
+ * Recognize a Universal Test ID from a field's already-decoded components.
+ *
+ * @param components - The component strings (escape-decoded), in order.
+ * @returns The recognized, provenance-tagged Universal Test ID.
+ * @example
+ * ```ts
+ * import { recognizeUniversalTestId, primaryCode } from "@cosyte/astm";
+ * primaryCode(recognizeUniversalTestId(["", "Glucose", "L", "687"])); // "687"
+ * ```
+ */
+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.
+ *
+ * @param u - A recognized Universal Test ID.
+ * @returns The primary code, or `undefined`.
+ * @example
+ * ```ts
+ * import { primaryCode, recognizeUniversalTestId } from "@cosyte/astm";
+ * primaryCode(recognizeUniversalTestId(["2345-7", "Glucose", "LN", "687"])); // "2345-7"
+ * ```
+ */
+declare function primaryCode(u: UniversalTestId): string | undefined;
+
+/**
+ * Positional context for frame-codec warnings and errors.
+ *
+ * **PHI discipline (the whole point).** A frame deviation is located by **frame
+ * number + byte offset** and nothing else — never the record text a frame
+ * carries. A frame warning or error may be logged verbatim without ever leaking a
+ * result value, a patient identifier, or any other field the reassembled record
+ * bytes contain.
+ */
+/**
+ * Where in a framed byte stream a warning or error originated. Both members are
+ * positional; neither is a value.
+ *
+ * @example
+ * ```ts
+ * import type { AstmFramePosition } from "@cosyte/astm";
+ * const at: AstmFramePosition = { frameNumber: 2, byteOffset: 251 };
+ * ```
+ */
+interface AstmFramePosition {
+    /**
+     * The frame's sequence number (`0`–`7`) when it could be read, or `undefined`
+     * when the frame was so truncated the number was not present.
+     */
+    readonly frameNumber?: number;
+    /** Byte offset of the `STX` that opened the frame, within the decoded stream. */
+    readonly byteOffset: number;
+}
+
+/**
+ * The **frame** warning registry (`ASTM_FRAME_*`) for the ASTM/CLSI-LIS01 codec —
+ * the second of the package's two registries, alongside the record layer's
+ * `ASTM_RECORD_*` (both share only the `EMPTY_INPUT` fatal).
+ *
+ * A frame warning is the lenient codec's record of a tolerated byte-level
+ * deviation: it never crashes, never invents a value, and — critically — never
+ * lets an untrusted frame be silently merged into a record. Every warning carries
+ * a stable code plus an {@link AstmFramePosition} (frame number + byte offset) and
+ * **never** the record bytes a frame carries (PHI discipline). Consumers compare
+ * `warning.code === FRAME_WARNING_CODES.<CODE>`; renaming a code is a **breaking
+ * change**.
+ */
+
+/**
+ * Stable string codes for every frame-codec warning. `key === value` so
+ * `Object.values(...)` yields a stable snapshot set.
+ *
+ * @example
+ * ```ts
+ * import { decodeAstmFrames, FRAME_WARNING_CODES } from "@cosyte/astm";
+ * const bytes = new Uint8Array([]); // ...a framed stream...
+ * void bytes;
+ * FRAME_WARNING_CODES.ASTM_FRAME_BAD_CHECKSUM; // "ASTM_FRAME_BAD_CHECKSUM"
+ * ```
+ */
+declare const FRAME_WARNING_CODES: {
+    /**
+     * A frame's two-hex-char checksum did not match the modulo-256 sum recomputed over its bytes. The
+     * frame is surfaced with `trusted: false` and its text is **never merged** into a reassembled
+     * record (default **warn** in lenient mode, escalated to a thrown error in `strict`). Corruption is
+     * never silently trusted — the "checksums are routinely not validated" claim was refuted; we
+     * validate.
+     */
+    readonly ASTM_FRAME_BAD_CHECKSUM: "ASTM_FRAME_BAD_CHECKSUM";
+    /**
+     * A frame's sequence number was not the expected next value (`1 → … → 7 → 0 → …`) — a frame was
+     * possibly dropped. The stream is **never silently concatenated across the gap** as if contiguous;
+     * the in-progress record is tainted and not emitted as a clean reassembly.
+     */
+    readonly ASTM_FRAME_SEQUENCE_GAP: "ASTM_FRAME_SEQUENCE_GAP";
+    /**
+     * A frame opened with `STX` but no valid terminator + checksum was found before the stream ended
+     * (or before the next `STX`), or a record's frames ended on an intermediate `ETB` with no final
+     * `ETX`. The partial bytes are surfaced flagged untrusted and **no partial record is invented**
+     * (warn in lenient, thrown in `strict`).
+     */
+    readonly ASTM_FRAME_UNTERMINATED: "ASTM_FRAME_UNTERMINATED";
+    /**
+     * A frame's record text exceeded the 240-byte limit without a split. The frame is still surfaced
+     * (and, if its checksum validates, reassembled) — the deviation is flagged, not silently dropped
+     * (warn in lenient, thrown in `strict`).
+     */
+    readonly ASTM_FRAME_OVERSIZE: "ASTM_FRAME_OVERSIZE";
+};
+/**
+ * Discriminant type for {@link AstmFrameWarning.code}. Narrowing by this code lets
+ * consumers write exhaustive `switch` blocks against {@link FRAME_WARNING_CODES}.
+ */
+type FrameWarningCode = (typeof FRAME_WARNING_CODES)[keyof typeof FRAME_WARNING_CODES];
+/**
+ * A single frame-codec warning: a stable code, a value-free human-readable
+ * message, and positional context (frame number + byte offset).
+ *
+ * @example
+ * ```ts
+ * import type { AstmFrameWarning } from "@cosyte/astm";
+ * const w: AstmFrameWarning = {
+ *   code: "ASTM_FRAME_BAD_CHECKSUM",
+ *   message: "Frame checksum mismatch.",
+ *   position: { frameNumber: 2, byteOffset: 251 },
+ * };
+ * ```
+ */
+interface AstmFrameWarning {
+    readonly code: FrameWarningCode;
+    /** Human-readable detail for logs. Never contains the frame's record bytes. */
+    readonly message: string;
+    readonly position: AstmFramePosition;
+}
+/**
+ * Build an `ASTM_FRAME_BAD_CHECKSUM` warning. The frame is surfaced flagged
+ * untrusted and never merged into a record; the warning carries position only.
+ *
+ * @example
+ * ```ts
+ * import { frameBadChecksum } from "@cosyte/astm";
+ * frameBadChecksum({ frameNumber: 2, byteOffset: 251 });
+ * ```
+ */
+declare function frameBadChecksum(position: AstmFramePosition): AstmFrameWarning;
+/**
+ * Build an `ASTM_FRAME_SEQUENCE_GAP` warning. A frame was possibly dropped; the
+ * record is not concatenated across the gap as if contiguous.
+ *
+ * @example
+ * ```ts
+ * import { frameSequenceGap } from "@cosyte/astm";
+ * frameSequenceGap({ frameNumber: 3, byteOffset: 502 });
+ * ```
+ */
+declare function frameSequenceGap(position: AstmFramePosition): AstmFrameWarning;
+/**
+ * Build an `ASTM_FRAME_UNTERMINATED` warning. The partial bytes are surfaced
+ * flagged untrusted; no partial record is invented.
+ *
+ * @example
+ * ```ts
+ * import { frameUnterminated } from "@cosyte/astm";
+ * frameUnterminated({ byteOffset: 730 });
+ * ```
+ */
+declare function frameUnterminated(position: AstmFramePosition): AstmFrameWarning;
+/**
+ * Build an `ASTM_FRAME_OVERSIZE` warning. The 240-byte text limit was exceeded
+ * without a split; the frame is flagged, not silently dropped.
+ *
+ * @example
+ * ```ts
+ * import { frameOversize } from "@cosyte/astm";
+ * frameOversize({ frameNumber: 1, byteOffset: 0 });
+ * ```
+ */
+declare function frameOversize(position: AstmFramePosition): AstmFrameWarning;
+
+/**
+ * The **LTP** warning registry (`ASTM_LTP_*`) for the ASTM/CLSI-LIS01 protocol
+ * layer — the third of the package's registries, alongside the record layer's
+ * `ASTM_RECORD_*` and the frame codec's `ASTM_FRAME_*`.
+ *
+ * An LTP warning is the protocol reducer's (or the transport detector's) record
+ * of a tolerated session-level deviation: an ambiguous framed/raw stream, a
+ * control event that arrived in a state that did not expect it, or a frame the
+ * receiver had to reject (`NAK`) rather than accept. Every warning carries a
+ * stable code plus, at most, a **frame number** — never the record bytes a frame
+ * carries (PHI discipline). Consumers compare `warning.code ===
+ * LTP_WARNING_CODES.<CODE>`; renaming a code is a **breaking change**.
+ */
+/**
+ * Stable string codes for every LTP protocol / transport warning. `key === value`
+ * so `Object.values(...)` yields a stable snapshot set.
+ *
+ * @example
+ * ```ts
+ * import { LTP_WARNING_CODES } from "@cosyte/astm";
+ * LTP_WARNING_CODES.ASTM_LTP_FRAME_REJECTED; // "ASTM_LTP_FRAME_REJECTED"
+ * ```
+ */
+declare const LTP_WARNING_CODES: {
+    /**
+     * The transport detector could not tell a framed stream from a raw (unframed) one from its leading
+     * byte — it was neither `STX`/`ENQ` nor a bare record letter. It **defaults to framed** and warns,
+     * never guessing silently into data loss; a profile override forces the mode. (cobas b121 drops
+     * framing over TCP; cobas 4800 / Iguana retain it — both realities exist, so an unrecognizable lead
+     * is defaulted, not assumed.)
+     */
+    readonly ASTM_LTP_AMBIGUOUS_TRANSPORT: "ASTM_LTP_AMBIGUOUS_TRANSPORT";
+    /**
+     * A control event arrived in a protocol state that did not expect it — e.g. an inbound `ACK`/`NAK`
+     * at a receiver (which sends, never receives, those), or an `ENQ` mid-transfer. The event is
+     * surfaced and handled defensively (an unexpected `ACK`/`NAK` is **never** read as acceptance of
+     * data); it never advances the transfer as if valid.
+     */
+    readonly ASTM_LTP_UNEXPECTED_EVENT: "ASTM_LTP_UNEXPECTED_EVENT";
+    /**
+     * The receiver rejected a received frame with a `NAK` instead of accepting it — because its
+     * checksum failed, it was unterminated, or its frame number was out of sequence. The frame's text
+     * is **never** appended to the record and the transfer does **not** advance; the receiver awaits the
+     * sender's retransmit. This is the protocol-level face of the frame codec's fail-safe: a bad frame
+     * drives retransmit, not acceptance.
+     */
+    readonly ASTM_LTP_FRAME_REJECTED: "ASTM_LTP_FRAME_REJECTED";
+};
+/**
+ * Discriminant type for {@link AstmLtpWarning.code}. Narrowing by this code lets
+ * consumers write exhaustive `switch` blocks against {@link LTP_WARNING_CODES}.
+ */
+type LtpWarningCode = (typeof LTP_WARNING_CODES)[keyof typeof LTP_WARNING_CODES];
+/**
+ * A single LTP protocol / transport warning: a stable code, a value-free
+ * human-readable message, and — for a frame-scoped deviation — the frame number
+ * only. Never carries a frame's record bytes.
+ *
+ * @example
+ * ```ts
+ * import type { AstmLtpWarning } from "@cosyte/astm";
+ * const w: AstmLtpWarning = {
+ *   code: "ASTM_LTP_FRAME_REJECTED",
+ *   message: "Frame rejected — NAK sent, retransmit expected.",
+ *   frameNumber: 2,
+ * };
+ * ```
+ */
+interface AstmLtpWarning {
+    readonly code: LtpWarningCode;
+    /** Human-readable detail for logs. Never contains the frame's record bytes. */
+    readonly message: string;
+    /** The frame's sequence number when the warning is frame-scoped; absent otherwise. */
+    readonly frameNumber?: number;
+}
+/**
+ * Build an `ASTM_LTP_AMBIGUOUS_TRANSPORT` warning. The detector defaulted to
+ * framed; a profile override can force raw.
+ *
+ * @example
+ * ```ts
+ * import { ltpAmbiguousTransport } from "@cosyte/astm";
+ * ltpAmbiguousTransport();
+ * ```
+ */
+declare function ltpAmbiguousTransport(): AstmLtpWarning;
+/**
+ * Build an `ASTM_LTP_UNEXPECTED_EVENT` warning. The event was surfaced and handled
+ * defensively; it never advanced the transfer as if valid.
+ *
+ * @param frameNumber - The frame number, when the unexpected event was a frame; omitted otherwise.
+ * @example
+ * ```ts
+ * import { ltpUnexpectedEvent } from "@cosyte/astm";
+ * ltpUnexpectedEvent();
+ * ```
+ */
+declare function ltpUnexpectedEvent(frameNumber?: number): AstmLtpWarning;
+/**
+ * Build an `ASTM_LTP_FRAME_REJECTED` warning. The receiver sent a `NAK`; the
+ * frame's text was never appended and the transfer did not advance.
+ *
+ * @param frameNumber - The rejected frame's sequence number, when it could be read.
+ * @example
+ * ```ts
+ * import { ltpFrameRejected } from "@cosyte/astm";
+ * ltpFrameRejected(2);
+ * ```
+ */
+declare function ltpFrameRejected(frameNumber?: number): AstmLtpWarning;
+
+/**
+ * Framed-vs-raw transport auto-detection for ASTM/CLSI-LIS01.
+ *
+ * ASTM transport is not uniform, and that is what breaks naive parsers. **Serial**
+ * (RS-232) always uses full E1381 framing. Over **TCP it varies within a single
+ * vendor**: the Roche cobas 4800 and iNTERFACEWARE Iguana retain the full
+ * `ENQ`/`ACK` + `STX`/checksum framing over TCP (**framed-TCP**), while the cobas
+ * b121 drops all low-level framing — "TCP itself ensures correctness" — and streams
+ * de-framed record bytes directly (**raw-TCP**). A reader must handle both and must
+ * not assume the handshake is present.
+ *
+ * {@link detectFraming} decides which it is from the stream's leading byte: `STX`
+ * or `ENQ` ⇒ framed (feed it to the frame codec + {@link ltpReduce}); a bare record
+ * letter ⇒ raw (feed it straight to `parseAstmRecords`). Anything else is
+ * **ambiguous**, and the fail-safe is to **default to framed** and warn — never to
+ * guess silently into data loss — with an explicit override for a profile that
+ * knows better.
+ */
+
+/**
+ * The transport framing of an ASTM byte stream: `"framed"` (E1381 `STX`/checksum
+ * frames, the serial and framed-TCP realities) or `"raw"` (framing dropped,
+ * de-framed record bytes streamed directly — the raw-TCP reality).
+ */
+type AstmFraming = "framed" | "raw";
+/**
+ * Options for {@link detectFraming}.
+ */
+interface DetectFramingOptions {
+    /**
+     * A profile-supplied override. When set, detection is bypassed entirely and this
+     * value is returned with no warning — the way a Phase-8 vendor profile forces
+     * raw for a cobas b121 or framed for a cobas 4800 regardless of the leading byte.
+     */
+    readonly override?: AstmFraming;
+}
+/**
+ * The result of {@link detectFraming}: the decided framing plus any warning
+ * (exactly one `ASTM_LTP_AMBIGUOUS_TRANSPORT` when the lead was unrecognizable and
+ * the mode was defaulted; empty otherwise).
+ */
+interface DetectFramingResult {
+    /** The decided transport framing. */
+    readonly framing: AstmFraming;
+    /** `true` when the lead byte was unrecognizable and `framing` was defaulted (not inferred). */
+    readonly defaulted: boolean;
+    /** The detection warnings (a single ambiguity warning, or none). */
+    readonly warnings: readonly AstmLtpWarning[];
+}
+/**
+ * Detect whether an ASTM byte stream is framed or raw from its leading byte.
+ *
+ * - Leading `STX` (`0x02`) or `ENQ` (`0x05`) ⇒ `"framed"`.
+ * - A leading bare record letter (`H`/`P`/`O`/`R`/`C`/`Q`/`M`/`S`/`L`) ⇒ `"raw"`.
+ * - Anything else (including an empty stream) is **ambiguous** ⇒ defaults to
+ *   `"framed"` and emits one `ASTM_LTP_AMBIGUOUS_TRANSPORT` warning.
+ *
+ * An `override` short-circuits all of the above, returning the forced mode with no
+ * warning.
+ *
+ * @param bytes - The stream to inspect (only the leading byte is read).
+ * @param options - Detection options; an `override` forces the result.
+ * @returns The decided framing, whether it was defaulted, and any warning.
+ * @example
+ * ```ts
+ * import { detectFraming } from "@cosyte/astm";
+ * detectFraming(new Uint8Array([0x02])).framing; // "framed" (STX)
+ * detectFraming(new Uint8Array([0x48])).framing; // "raw"    (leading "H")
+ * detectFraming(new Uint8Array([0x2a])).framing; // "framed" (ambiguous → defaulted, + warning)
+ * detectFraming(new Uint8Array([0x48]), { override: "framed" }).framing; // "framed" (forced)
+ * ```
+ */
+declare function detectFraming(bytes: Uint8Array, options?: DetectFramingOptions): DetectFramingResult;
+
+/**
+ * Public type surface for the `@cosyte/astm` vendor-profile subsystem. An
+ * {@link AstmProfile} bundles a **named, provenance-backed set of expected
+ * deviations** ("quirks") a class of real-world ASTM streams is known to carry,
+ * plus an optional **transport override** (the raw-vs-framed-TCP knob). It mirrors
+ * the sibling `@cosyte/hl7` `defineProfile` and `@cosyte/ccda` `defineCcdaProfile`
+ * shape (`name` / `lineage` / `describe()` / `extends`-merge) but models ASTM's
+ * quirks — a warning code the stream is expected to trip, and its framing reality —
+ * rather than HL7 v2 Z-segments or C-CDA template deviations.
+ *
+ * A profile **never changes an extracted value**. It operates purely at the
+ * warning layer (downgrading an *already-emitted*, non-safety-critical warning to
+ * a {@link WARNING_CODES.PROFILE_QUIRK_APPLIED}) and at the transport-detection
+ * layer (forcing framed/raw before a single byte is parsed). The two load-bearing
+ * safety rules, enforced by `defineAstmProfile`:
+ *
+ * 1. **A profile can never tolerate a safety-critical warning code** — a result
+ *    value, abnormal flag, result status, reference range, units, patient/comment
+ *    context, message-kind ambiguity, code system, or any frame/LTP integrity
+ *    warning (see `src/profiles/safety.ts`). Naming one is a *definition-time
+ *    throw*, not a silent relaxation — so a profile can never make a bad checksum
+ *    "ok" or a cancelled result read "final."
+ * 2. **A tolerated deviation is downgraded, never dropped.** The parser still
+ *    records it (re-coded {@link WARNING_CODES.PROFILE_QUIRK_APPLIED}, flagged
+ *    `expected: true`, carrying the original `toleratedCode`) so nothing is
+ *    silently hidden — Postel's Law with a receipt.
+ */
+
+/**
+ * Any warning code from any of the three registries — the record layer
+ * (`ASTM_RECORD_*` / `ASTM_NONSTANDARD_DELIMITERS` / `ASTM_UNKNOWN_ESCAPE_SEQUENCE`),
+ * the frame codec (`ASTM_FRAME_*`), or the LTP protocol layer (`ASTM_LTP_*`). A
+ * {@link QuirkTolerance} may *name* any of them, but the safety gate refuses all
+ * but the small, benign, record-layer subset — so the union exists mainly to let
+ * the gate reject a frame/LTP code with a precise, typed message.
+ */
+type AnyAstmWarningCode = WarningCode | FrameWarningCode | LtpWarningCode;
+/**
+ * Provenance for an {@link AstmProfile} — the **real, cited public artifact** a
+ * profile's quirks are grounded in. A quirk is encoded only when a real
+ * (de-identified) document or a redistributable reference corpus grounds it; this
+ * record is where that grounding is stated, so a reviewer can trace every
+ * tolerated deviation back to evidence rather than invention.
+ *
+ * @example
+ * ```ts
+ * import type { AstmProfileProvenance } from "@cosyte/astm";
+ * const prov: AstmProfileProvenance = {
+ *   source: "kxepal/python-astm codec.py",
+ *   reference: "https://github.com/kxepal/python-astm/blob/master/astm/codec.py",
+ *   retrieved: "2026-07-21",
+ * };
+ * ```
+ */
+interface AstmProfileProvenance {
+    /** Short human-readable name of the grounding source (corpus, transcript, or spec). */
+    readonly source: string;
+    /** A citation the grounding can be traced to — a URL, DOI, or repo+path. */
+    readonly reference: string;
+    /** When the grounding was last verified (ISO date) or the pinned commit SHA. */
+    readonly retrieved?: string;
+    /** Optional clarifying note about what in the source grounds the quirks. */
+    readonly note?: string;
+}
+/**
+ * Optional structural narrowing for a {@link QuirkTolerance}. When present, the
+ * tolerance applies only to warnings whose PHI-free {@link AstmPosition} matches
+ * every provided field — so a profile can expect a deviation on one record type
+ * (e.g. an unknown escape only inside `R` result values) without blanket-tolerating
+ * it everywhere. Matching is on **structural identifiers only** (record-type
+ * letter, 1-based field index); there is no matching on any field *value*, by
+ * construction.
+ *
+ * @example
+ * ```ts
+ * import type { AstmQuirkMatch } from "@cosyte/astm";
+ * const onlyResultUnits: AstmQuirkMatch = { recordType: "R", fieldIndex: 5 };
+ * ```
+ */
+interface AstmQuirkMatch {
+    /** Match only warnings carrying this record-type letter in their position. */
+    readonly recordType?: string;
+    /** Match only warnings carrying this 1-based field index in their position. */
+    readonly fieldIndex?: number;
+}
+/**
+ * One expected deviation declared by a profile. `code` names an **existing,
+ * non-safety-critical** warning code the profile expects; `rationale` documents
+ * why (grounded in the profile's {@link AstmProfileProvenance}); optional `match`
+ * narrows it to a structural location. `defineAstmProfile` throws if `code` is
+ * safety-critical or is not a real warning code, or if `rationale` is empty.
+ *
+ * @example
+ * ```ts
+ * import type { AstmQuirkTolerance } from "@cosyte/astm";
+ * const t: AstmQuirkTolerance = {
+ *   code: "ASTM_UNKNOWN_ESCAPE_SEQUENCE",
+ *   rationale: "Corpus stacks that treat '&' as literal data emit non-standard escape bodies.",
+ * };
+ * ```
+ */
+interface AstmQuirkTolerance {
+    /** The existing, non-safety-critical warning code this profile expects. */
+    readonly code: AnyAstmWarningCode;
+    /** Why the profile expects this deviation — grounded in its provenance. */
+    readonly rationale: string;
+    /** Optional structural narrowing (record type / field index). */
+    readonly match?: AstmQuirkMatch;
+}
+/**
+ * A frozen, immutable vendor/conformance profile. Produced by
+ * {@link defineAstmProfile}; consumers pass it to `parseAstmRecords(raw, { profile })`
+ * (or register it as the process default), and feed its {@link AstmProfile.transport}
+ * to `detectFraming(bytes, { override })`. Hand-authoring the object literal is
+ * supported but discouraged — the factory validates the safety rules and attaches
+ * `describe()`.
+ *
+ * @example
+ * ```ts
+ * import { parseAstmRecords, astmProfiles } from "@cosyte/astm";
+ * const msg = parseAstmRecords(raw, { profile: astmProfiles.referenceCorpus });
+ * msg.profile?.name; // "referenceCorpus"
+ * ```
+ */
+interface AstmProfile {
+    /** The profile's unique name (registry key / attribution label). */
+    readonly name: string;
+    /** Optional human-readable description. */
+    readonly description?: string;
+    /** Resolved lineage — `[...parents, name]`, first-occurrence deduped. */
+    readonly lineage: readonly string[];
+    /** The expected, non-safety-critical deviations this profile tolerates. */
+    readonly tolerate: readonly AstmQuirkTolerance[];
+    /**
+     * The raw-vs-framed-TCP override. When set, a consumer forces this framing via
+     * `detectFraming(bytes, { override: profile.transport })` — the way a profile
+     * that knows a vendor's transport reality (e.g. framing dropped over raw TCP)
+     * bypasses leading-byte auto-detection. Absent means "let detection decide."
+     */
+    readonly transport?: AstmFraming;
+    /** The cited public grounding for this profile's quirks (absent for `default`). */
+    readonly provenance?: AstmProfileProvenance;
+    /** Multi-line human-readable summary; always present on factory-built profiles. */
+    readonly describe?: () => string;
+}
+/**
+ * Options accepted by {@link defineAstmProfile}. Mirrors the {@link AstmProfile}
+ * shape minus the derived `lineage`/`describe`, plus the `extends` input key. Every
+ * field except `name` is optional.
+ *
+ * @example
+ * ```ts
+ * import { defineAstmProfile, type DefineAstmProfileOptions } from "@cosyte/astm";
+ * const opts: DefineAstmProfileOptions = {
+ *   name: "my-analyzer",
+ *   transport: "raw",
+ *   tolerate: [{ code: "ASTM_RECORD_UNKNOWN_TYPE", rationale: "partial vendor grammar" }],
+ * };
+ * const p = defineAstmProfile(opts);
+ * ```
+ */
+interface DefineAstmProfileOptions {
+    readonly name: string;
+    readonly description?: string;
+    readonly tolerate?: readonly AstmQuirkTolerance[];
+    readonly transport?: AstmFraming;
+    readonly provenance?: AstmProfileProvenance;
+    readonly extends?: AstmProfile | readonly AstmProfile[];
+}
+
+/**
+ * Safety-critical result semantics for the ASTM `R` (result) record — Phase 2.
+ *
+ * Phase 1 surfaced the `R` record's flag, status, units, and reference-range
+ * 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`**.
+ * - 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)**.
+ * - A **reference range** (field 6) is parsed into a low/high (or open-ended)
+ *   pair; an unparseable range is surfaced **verbatim** — a bound is **never
+ *   fabricated**.
+ *
+ * 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, 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.
+ */
+type AbnormalFlagCode = "L" | "H" | "LL" | "HH" | "<" | ">" | "N" | "A" | "AA" | "U" | "D" | "B" | "W" | "S" | "R" | "I";
+/**
+ * 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`.
+ */
+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";
+/**
+ * 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`**.
+ *
+ * @example
+ * ```ts
+ * import { interpretAbnormalFlag } from "@cosyte/astm";
+ * const f = interpretAbnormalFlag("HH");
+ * f.meaning;    // "critically-above-normal"
+ * f.recognized; // true
+ * ```
+ */
+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. */
+    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. */
+    readonly recognized: boolean;
+}
+/**
+ * Interpret an `R`-record abnormal-flag field (field 7) against HL7 Table 0078.
+ *
+ * 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"`**.
+ *
+ * @param raw - The verbatim field-7 text.
+ * @returns The interpreted flag.
+ * @example
+ * ```ts
+ * import { interpretAbnormalFlag } from "@cosyte/astm";
+ * interpretAbnormalFlag("U").meaning;   // "significant-change-up"
+ * interpretAbnormalFlag("ZZ").meaning;  // "undefined" (never "normal")
+ * ```
+ */
+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)**.
+ */
+type ResultStatusCode = "F" | "C" | "P" | "R" | "S" | "I" | "X";
+/**
+ * The modeled meaning of a result status, plus two fail-safe sentinels:
+ * `unspecified` (the field was absent — **never assumed `final`**) and
+ * `undefined` (a letter was present but is not a recognized status).
+ */
+type ResultStatusMeaning = "final" | "correction" | "preliminary" | "previously-transmitted" | "partial" | "pending" | "cancelled" | "unspecified" | "undefined";
+/**
+ * A modeled result status. The three booleans are the safety surface a consumer
+ * reads instead of string-matching the code:
+ *
+ * - **`isActiveFinal`** is `true` **only** for a plain `F` (final). It is `false`
+ *   for a correction (`C`), a cancellation (`X`), a preliminary/partial/pending
+ *   result, an absent status, and an unrecognized one — so a superseded or
+ *   cancelled result can **never** read as current/final.
+ * - **`supersedes`** is `true` for `C` — this value replaces a previously
+ *   transmitted one.
+ * - **`cancelled`** is `true` for `X` — the result cannot be done / was cancelled.
+ *
+ * @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")
+ * ```
+ */
+interface ResultStatus {
+    /** The verbatim field text, present only when field 9 carried a value. */
+    readonly raw?: string;
+    /** The recognized status code, present only when the raw text is a known status. */
+    readonly code?: ResultStatusCode;
+    /** The modeled meaning; `"unspecified"` when absent, `"undefined"` when unrecognized. */
+    readonly meaning: ResultStatusMeaning;
+    /** Whether the raw text matched a recognized status letter. */
+    readonly recognized: boolean;
+    /** `true` **only** for a plain `F` (final) — never for `C`, `X`, absent, or unrecognized. */
+    readonly isActiveFinal: boolean;
+    /** `true` for `C` — this value supersedes a previously transmitted result. */
+    readonly supersedes: boolean;
+    /** `true` for `X` — the result cannot be done / was cancelled. */
+    readonly cancelled: boolean;
+}
+/**
+ * Interpret an `R`-record result-status field (field 9).
+ *
+ * An **absent** status (`undefined` or empty) is typed `unspecified` — **never
+ * assumed `final`**. A **present but unrecognized** letter is `undefined`
+ * (recognized `false`). In every non-`F` case `isActiveFinal` is `false`, so a
+ * correction, a cancellation, or an unknown status can never read as current.
+ *
+ * @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
+ * ```
+ */
+declare function interpretResultStatus(raw: string | undefined): ResultStatus;
+/**
+ * The shape of a parsed reference range.
+ *
+ * - `closed` — both a low and a high bound (`3.5-5.0`).
+ * - `open-low` — an upper bound only (`<5`): everything at or below `high`.
+ * - `open-high` — a lower bound only (`>10`): everything at or above `low`.
+ * - `unparsed` — the text did not match a recognized form; both bounds are
+ *   absent and the raw text is surfaced. **A bound is never fabricated.**
+ */
+type ReferenceRangeKind = "closed" | "open-low" | "open-high" | "unparsed";
+/**
+ * A parsed reference range. Bounds are surfaced as the **verbatim numeric text**
+ * (never coerced to a float, never rounded, never converted) so nothing is lost
+ * or fabricated.
+ *
+ * **`[OSS-derived]` — the exact lower/upper delimiter (`-`) and the open-ended
+ * `<x`/`>x` forms are taken from the permissively-licensed OSS reference parsers
+ * and cross-verified vendor transcripts; they are not confirmed against the
+ * purchased CLSI LIS02-A2 (roadmap §10 Q1). Anything that does not match these
+ * forms is surfaced verbatim as `unparsed`, never guessed into a bound.**
+ *
+ * @example
+ * ```ts
+ * import { parseReferenceRange } from "@cosyte/astm";
+ * const r = parseReferenceRange("3.5-5.0");
+ * r.kind; // "closed"
+ * r.low;  // "3.5"
+ * r.high; // "5.0"
+ * ```
+ */
+interface ReferenceRange {
+    /** The verbatim field text, exactly as received. */
+    readonly raw: string;
+    /** The lower bound, verbatim numeric text (for `closed` and `open-high`). */
+    readonly low?: string;
+    /** The upper bound, verbatim numeric text (for `closed` and `open-low`). */
+    readonly high?: string;
+    /** The recognized shape, or `"unparsed"` when the text matched no known form. */
+    readonly kind: ReferenceRangeKind;
+}
+/**
+ * Parse an `R`-record reference-range field (field 6) into a low/high (or
+ * open-ended) pair.
+ *
+ * Recognized forms are `low-high` (closed), `<high` (open-low), and `>low`
+ * (open-high). Anything else — including an ambiguous multi-dash string or a
+ * bare non-numeric token — is returned as `kind: "unparsed"` with the raw text
+ * preserved and **no bound invented**. Bounds are surfaced as verbatim text, not
+ * coerced to numbers.
+ *
+ * @param raw - The verbatim field-6 text.
+ * @returns The parsed reference range.
+ * @example
+ * ```ts
+ * import { parseReferenceRange } from "@cosyte/astm";
+ * parseReferenceRange("<5").kind;      // "open-low"
+ * parseReferenceRange(">10").low;      // "10"
+ * parseReferenceRange("weird").kind;   // "unparsed" (never a fabricated bound)
+ * ```
+ */
+declare function parseReferenceRange(raw: string): ReferenceRange;
+
+/**
+ * The immutable ASTM record model produced by {@link parseAstmRecords}.
+ *
+ * A message is a header (which carries the resolved delimiters as provenance), an
+ * ordered list of typed records, and the Tier-2 warnings the lenient parser
+ * accumulated. Every record keeps its raw {@link AstmField}s **and** the typed
+ * accessors relevant to its type — the raw tree is always present so nothing the
+ * parser did not model is lost.
+ *
+ * Phase-1 scope: `H`/`P`/`O`/`R`/`L` are modeled; every other type letter is an
+ * {@link UnsupportedRecord} (surfaced, never dropped). Result-flag/status
+ * *semantics*, comments/query/`M`/`S`, framing, and serialization are later
+ * phases — this layer surfaces the safety-critical values **raw**.
+ */
+
+/**
+ * One ASTM field, as split from a record. The tree holds **decoded** component
+ * strings (escape sequences already resolved), while {@link AstmField.raw}
+ * preserves the exact wire text of the field for round-trip and audit.
+ *
+ * `components` is the first repeat's components (the common single-repeat case);
+ * `repeats` holds every repeat when a field uses the repeat delimiter.
+ */
+interface AstmField {
+    /** The exact field text as it appeared on the wire (escapes NOT decoded). */
+    readonly raw: string;
+    /** Components of the first repeat, each escape-decoded. Empty field → `[""]`. */
+    readonly components: readonly string[];
+    /** Every repeat, each an array of decoded components. `repeats[0] === components`. */
+    readonly repeats: readonly (readonly string[])[];
+}
+/** Common shape of every parsed record. */
+interface RecordBase {
+    /** The record's raw type letter. */
+    readonly type: string;
+    /** 0-based ordinal of the record within the message. */
+    readonly recordIndex: number;
+    /** The record's fields. `fields[0]` is the type-letter field; data fields are 1-indexed after it. */
+    readonly fields: readonly AstmField[];
+}
+/**
+ * The `H` (header) record. Carries the delimiters it declared as provenance.
+ */
+interface HeaderRecord extends RecordBase {
+    readonly type: "H";
+    /** The four delimiters resolved from this header. */
+    readonly delimiters: Delimiters;
+    /**
+     * The header's exact wire text (terminator excluded), preserved because the
+     * escape character appears **literally** inside the delimiter-definition field
+     * (`\^&`), which the generic escape-aware tokenizer cannot split cleanly. The
+     * delimiters are read from this raw text (never from {@link RecordBase.fields}),
+     * and the serializer reconstructs the header's data fields from it.
+     */
+    readonly rawLine: string;
+}
+/**
+ * A patient name (`Last^First^Middle`), each component surfaced verbatim.
+ */
+interface PatientName {
+    readonly raw: string;
+    readonly last?: string;
+    readonly first?: string;
+    readonly middle?: string;
+}
+/**
+ * The `P` (patient) record.
+ *
+ * **Safety:** the practice-assigned ID (field 3) and the laboratory-assigned ID
+ * (field 4) are modeled as **distinct** fields and never collapsed — conflating
+ * them is the primary result-misfiling path.
+ */
+interface PatientRecord extends RecordBase {
+    readonly type: "P";
+    /** Field 2 — sequence number. */
+    readonly seq?: string;
+    /** Field 3 — practice-assigned patient ID. Distinct from {@link PatientRecord.laboratoryAssignedId}. */
+    readonly practiceAssignedId?: string;
+    /** Field 4 — laboratory-assigned patient ID. Distinct from {@link PatientRecord.practiceAssignedId}. */
+    readonly laboratoryAssignedId?: string;
+    /**
+     * Field 5 — a third patient identifier (e.g. a national/alternate ID), surfaced verbatim. Kept
+     * separate from the practice- and laboratory-assigned IDs — the three never collapse into one.
+     */
+    readonly patientIdThree?: string;
+    /** Field 6 — patient name (`Last^First^Middle`). */
+    readonly name?: PatientName;
+    /** Field 7 — mother's maiden name, surfaced verbatim (a surname component; PHI). */
+    readonly mothersMaidenName?: string;
+    /** Field 8 — birthdate (`YYYYMMDDHHMMSS`, precision-preserving; a truncated run sets `truncated`). */
+    readonly birthDate?: AstmDate;
+    /** Field 9 — sex, surfaced raw (`M`/`F`/`U`/vendor value). */
+    readonly sex?: string;
+}
+/**
+ * The `O` (order) record — binds a result to a specimen.
+ */
+interface OrderRecord extends RecordBase {
+    readonly type: "O";
+    /** Field 2 — sequence number. */
+    readonly seq?: string;
+    /** Field 3 — specimen / accession ID. */
+    readonly specimenId?: string;
+    /** Field 4 — instrument specimen ID. */
+    readonly instrumentSpecimenId?: string;
+    /** Field 5 — Universal Test ID (same caret structure as a result's). */
+    readonly universalTestId?: UniversalTestId;
+    /**
+     * Field 6 — priority, surfaced raw (e.g. `S` STAT, `R` routine, `A` ASAP). Vendor letters vary;
+     * the code set is `[OSS-derived]` (the exact enumeration is in the paywalled CLSI LIS02-A2), so the
+     * value is surfaced verbatim and **never mapped to a guessed meaning**.
+     */
+    readonly priority?: string;
+    /**
+     * Field 12 — action code, surfaced raw (e.g. `C` cancel, `A` add, `N` new). The exact field index
+     * (`~12`) and the code set are `[OSS-derived]` (paywalled) — surfaced verbatim, never interpreted.
+     */
+    readonly actionCode?: string;
+    /**
+     * Field 26 — report type, surfaced raw (e.g. `F` final, `P` preliminary, `X` cancel). The exact
+     * field index (`~26`) and the code set are `[OSS-derived]` (paywalled) — surfaced verbatim.
+     */
+    readonly reportType?: string;
+}
+/**
+ * The `R` (result) record — the value itself.
+ *
+ * The raw safety-critical fields (value, `units`, `referenceRange`,
+ * `abnormalFlags`, `resultStatus`) are always surfaced exactly as received.
+ * Phase 2 adds the **modeled, fail-safe** semantics alongside them: `flag`
+ * (Table 0078, `undefined` never coerced to normal), `status` (a `C`/`X` never
+ * reads as active-final; an absent status is `unspecified`, never `final`), and
+ * `range` (open/closed bounds surfaced verbatim, never fabricated). The raw
+ * strings and the modeled views coexist — nothing is collapsed or reconciled.
+ */
+interface ResultRecord extends RecordBase {
+    readonly type: "R";
+    /** Field 2 — sequence number. */
+    readonly seq?: string;
+    /** Field 3 — Universal Test ID (local code in component 4 is the primary identifier). */
+    readonly universalTestId?: UniversalTestId;
+    /**
+     * Field 4 — the measured value. In the ordinary single-component case this is the decoded scalar.
+     * When the value field carried an *unescaped* component delimiter (an ambiguity), this is the
+     * **full raw field text** — never a truncated component — and {@link ResultRecord.valueComponents}
+     * plus an `ASTM_RECORD_AMBIGUOUS_VALUE_SPLIT` warning are also present.
+     */
+    readonly value?: string;
+    /**
+     * Field 4 split into components, present only when the value field carried an *unescaped* component
+     * delimiter — i.e. it read as more than one component. Surfaced alongside the full raw value (and a
+     * warning) so an ambiguous split is visible, never resolved silently.
+     */
+    readonly valueComponents?: readonly string[];
+    /** Field 5 — units (vendor free text; a missing unit is not defaulted). */
+    readonly units?: string;
+    /** Field 6 — reference range, surfaced raw. */
+    readonly referenceRange?: string;
+    /**
+     * Field 6 — the reference range parsed into low/high (or open-ended) bounds, present only when the
+     * field carried a value. An unparseable range is `kind: "unparsed"` with the raw text preserved and
+     * **no bound fabricated**. Bounds are verbatim numeric text, never coerced to floats.
+     */
+    readonly range?: ReferenceRange;
+    /** Field 7 — abnormal flags, surfaced raw (HL7 Table 0078 values). */
+    readonly abnormalFlags?: string;
+    /**
+     * Field 7 — the abnormal flag interpreted against HL7 Table 0078, present only when the field
+     * carried a value. An unrecognized flag is `{ recognized: false, meaning: "undefined" }` — surfaced,
+     * never dropped, and **never coerced to `normal`**.
+     */
+    readonly flag?: AbnormalFlag;
+    /** Field 9 — result status, surfaced raw (`F`/`C`/`X`/…). */
+    readonly resultStatus?: string;
+    /**
+     * Field 9 — the modeled result status. **Always present** (an absent field yields a typed
+     * `unspecified`, never assumed `final`), so `status.isActiveFinal` is always a reliable boolean: it
+     * is `true` only for a plain `F`, and `false` for a correction (`C`), a cancellation (`X`), a
+     * partial/preliminary/pending, an absent, or an unrecognized status.
+     */
+    readonly status: ResultStatus;
+    /** Field 11 — operator. */
+    readonly operator?: string;
+    /** Field 12 — test started timestamp. */
+    readonly startedAt?: AstmDate;
+    /** Field 13 — test completed timestamp. */
+    readonly completedAt?: AstmDate;
+    /** Field 14 — instrument identifier. */
+    readonly instrument?: string;
+}
+/**
+ * The `C` (comment) record — free-text context attached to a parent record.
+ *
+ * A comment is **attached by position** to the immediately-preceding `H`/`P`/`O`/`R` record
+ * ({@link CommentRecord.parentIndex}); consecutive comments share that parent. **Fail-safe:** a
+ * comment with no valid preceding parent is an **orphan** — it is attached to the message root
+ * ({@link CommentRecord.attachedToRoot} `true`) and a value-free `ASTM_RECORD_ORPHAN_COMMENT` warning
+ * fires — **never silently dropped**, so a comment carrying (e.g.) "QC / non-compliant" context can
+ * never float away unnoticed.
+ */
+interface CommentRecord extends RecordBase {
+    readonly type: "C";
+    /** Field 2 — sequence number. */
+    readonly seq?: string;
+    /** Field 3 — comment source (who/what produced it), surfaced verbatim. */
+    readonly source?: string;
+    /**
+     * Field 4 — the comment text, surfaced as the **full** field text (all components), never
+     * truncated to the first component. The component structure is in {@link CommentRecord.textComponents}.
+     */
+    readonly text?: string;
+    /**
+     * Field 4 — the comment text split into its decoded components (comment text is component-capable;
+     * multiple components are a normal structured comment, **not** an ambiguity). Present only when the
+     * field carried more than one component.
+     */
+    readonly textComponents?: readonly string[];
+    /**
+     * Field 5 — comment type code, surfaced verbatim. **`[OSS-derived]`:** `I` (instrument) is the only
+     * value seen in the permissively-licensed real transcripts; other values (e.g. `G`/`T`/`P`) are
+     * defined only in the paywalled CLSI LIS02-A2 and are **not** interpreted here — the raw code is
+     * surfaced, never mapped to a guessed meaning.
+     */
+    readonly commentType?: string;
+    /**
+     * The `recordIndex` of the `H`/`P`/`O`/`R` record this comment is attached to, or `undefined` when
+     * the comment is an orphan attached to the message root (see {@link CommentRecord.attachedToRoot}).
+     */
+    readonly parentIndex?: number;
+    /** `true` when no valid parent preceded — the comment is attached to the message root (and warned). */
+    readonly attachedToRoot: boolean;
+}
+/**
+ * The `Q` (Request Information) record — the host-query request.
+ *
+ * A `Q` record asks the LIS for information (e.g. outstanding orders for a
+ * specimen); its **presence classifies the whole message as a request, never a
+ * result set** (see {@link AstmMessage.classification}). Its safety-relevant
+ * fields — the starting/ending range ID and the request-information status — are
+ * surfaced **verbatim**; the field *positions* are the public ASTM E1394 layout,
+ * but their internal structure and code meanings are **`[OSS-derived / paywalled]`**
+ * (roadmap §10 Q3) and are therefore **never interpreted or guessed**.
+ */
+interface QueryRecord extends RecordBase {
+    /** Field 2 — sequence number. */
+    readonly seq?: string;
+    readonly type: "Q";
+    /**
+     * Field 3 — starting range ID number, surfaced as the **full** verbatim field text (never truncated
+     * to a component). Its caret component structure (e.g. patient ID ^ specimen ID) is
+     * **`[OSS-derived / paywalled]`** — the raw split is available via {@link RecordBase.fields}, but the
+     * *meaning* of each component is **never** assigned here.
+     */
+    readonly startingRangeId?: string;
+    /** Field 4 — ending range ID number, surfaced verbatim (same `[OSS-derived]` caveat as field 3). */
+    readonly endingRangeId?: string;
+    /**
+     * Field 5 — Universal Test ID (the same caret structure as an `O`/`R` record's), recognized by
+     * provenance only. When the field is the literal universal-query keyword, {@link QueryRecord.queriesAllTests}
+     * is set instead — see its caveat.
+     */
+    readonly universalTestId?: UniversalTestId;
+    /**
+     * `true` when field 5 is the literal `ALL` universal-query keyword (case-insensitive). **`[OSS-derived
+     * / paywalled]`:** the token is surfaced because it appears in the OSS references, but its exact
+     * host-query *behavior* (which tests a bare `ALL` selects, and whether the vendor answers with a full
+     * `H/P/O/L` or a `P/O`-only response) is paywalled and vendor-specific — **not decided here**.
+     */
+    readonly queriesAllTests: boolean;
+    /**
+     * Field 13 — request-information status code(s), surfaced **verbatim**. The status code *set* is
+     * **`[OSS-derived / paywalled]`** (roadmap §10 Q3): with no publicly-groundable enumeration, this
+     * parser recognizes **none** of them and interprets nothing — every present status is surfaced raw
+     * and flagged with a value-free `ASTM_RECORD_UNINTERPRETED_QUERY_STATUS` warning. Never mapped to a
+     * guessed meaning.
+     */
+    readonly requestInformationStatus?: string;
+}
+/**
+ * The `M` (manufacturer) record — vendor-defined free-form data
+ * (QC / calibration / maintenance), surfaced **VERBATIM** and **never interpreted
+ * into typed clinical fields**.
+ *
+ * Interpreting a vendor `M` record as clinical data would be a fabrication, so
+ * this record carries **no typed accessors at all**: the exact wire text is in
+ * {@link ManufacturerRecord.rawLine} (byte-preserving) and the tokenized tree in
+ * {@link RecordBase.fields}. Nothing is parsed into a value, a code, or a unit.
+ */
+interface ManufacturerRecord extends RecordBase {
+    readonly type: "M";
+    /** The record's exact wire text (terminator excluded), preserved byte-for-byte for round-trip. */
+    readonly rawLine: string;
+}
+/**
+ * The `S` (scientific) record — vendor-defined free-form data, surfaced
+ * **VERBATIM** and **never interpreted into typed clinical fields** (same posture
+ * as {@link ManufacturerRecord}).
+ */
+interface ScientificRecord extends RecordBase {
+    readonly type: "S";
+    /** The record's exact wire text (terminator excluded), preserved byte-for-byte for round-trip. */
+    readonly rawLine: string;
+}
+/**
+ * The `L` (terminator) record — closes a message.
+ */
+interface TerminatorRecord extends RecordBase {
+    readonly type: "L";
+}
+/**
+ * Any record whose type letter is not modeled (a genuinely unknown letter).
+ * `H`/`P`/`O`/`R`/`C`/`L` (Phases 1–3) and `Q`/`M`/`S` (Phase 4) are all modeled;
+ * anything else is surfaced with its raw fields intact and flagged with an
+ * `ASTM_RECORD_UNKNOWN_TYPE` warning — never dropped.
+ */
+interface UnsupportedRecord extends RecordBase {
+    readonly type: "unsupported";
+    /** The raw type letter as it appeared on the wire. */
+    readonly rawType: string;
+}
+/** The discriminated union of every parsed record. */
+type AstmRecord = HeaderRecord | PatientRecord | OrderRecord | ResultRecord | CommentRecord | QueryRecord | ManufacturerRecord | ScientificRecord | TerminatorRecord | UnsupportedRecord;
+/**
+ * How a message is classified by the host-query flow.
+ *
+ * - `host-query` — the message carries at least one `Q` record: it is a **request
+ *   for information**, and **must never be read as a result set** (the load-bearing
+ *   safety distinction of this layer). `Q` **dominates**: a `Q` present classifies
+ *   the message as a request even if a result record is also present (an anomaly,
+ *   separately warned) — so a `Q`-bearing message is never silently treated as a
+ *   result upload.
+ * - `results` — no `Q`, at least one `R` (result) record: a result upload / response.
+ * - `orders` — no `Q`, no `R`, at least one `O` (order) record: an order download,
+ *   or a query response before results are attached.
+ * - `indeterminate` — none of the above (e.g. header + terminator only). Not
+ *   guessed into one of the other kinds.
+ */
+type AstmMessageKind = "host-query" | "results" | "orders" | "indeterminate";
+/**
+ * The message-level classification from the host-query flow. `isHostQueryRequest`
+ * is the single boolean a consumer should gate on before treating records as
+ * results — it is `true` **iff** a `Q` record is present.
+ *
+ * @example
+ * ```ts
+ * import { parseAstmRecords } from "@cosyte/astm";
+ * const req = parseAstmRecords("H|\\^&\rP|1\rQ|1|^SPEC-7||ALL\rL|1\r");
+ * req.classification.kind;               // "host-query"
+ * req.classification.isHostQueryRequest; // true — never read its records as results
+ * ```
+ */
+interface AstmMessageClassification {
+    /** The message kind. */
+    readonly kind: AstmMessageKind;
+    /** At least one `Q` (request-information) record is present. */
+    readonly hasQuery: boolean;
+    /** At least one `R` (result) record is present. */
+    readonly hasResults: boolean;
+    /** At least one `O` (order) record is present. */
+    readonly hasOrders: boolean;
+    /**
+     * `true` **iff** `kind === "host-query"` (a `Q` record is present) — the safety surface: gate on this
+     * before treating records as results, so a query is never misread as a result upload.
+     */
+    readonly isHostQueryRequest: boolean;
+}
+/**
+ * A parsed ASTM message: the header, the ordered records (the header is also
+ * `records[0]`), the resolved delimiters, and the accumulated warnings.
+ *
+ * @example
+ * ```ts
+ * import { parseAstmRecords } from "@cosyte/astm";
+ * const msg = parseAstmRecords("H|\\^&\rL|1\r");
+ * msg.header.delimiters.field; // "|"
+ * msg.records.length;          // 2
+ * ```
+ */
+interface AstmMessage {
+    readonly header: HeaderRecord;
+    readonly records: readonly AstmRecord[];
+    readonly delimiters: Delimiters;
+    /**
+     * The host-query classification of this message — whether it is a request (`Q`
+     * present), a result upload, an order download, or indeterminate. Gate on
+     * {@link AstmMessageClassification.isHostQueryRequest} before reading records as
+     * results.
+     */
+    readonly classification: AstmMessageClassification;
+    readonly warnings: readonly AstmRecordWarning[];
+    /**
+     * The vendor profile that was active for this parse, when one applied — its
+     * `name` and resolved `lineage` (attribution only; the profile object itself is
+     * not embedded). Absent when no profile applied. A profile that tolerated a
+     * deviation shows up as a `PROFILE_QUIRK_APPLIED` entry in {@link warnings}, not
+     * here.
+     */
+    readonly profile?: {
+        readonly name: string;
+        readonly lineage: readonly string[];
+    };
+}
+/**
+ * Options for {@link parseAstmRecords}. Lenient by default (Postel's Law).
+ */
+interface AstmParseOptions {
+    /**
+     * When `true`, escalate any Tier-2 deviation to a thrown {@link AstmStrictError}
+     * instead of accumulating a warning. Off by default. A deviation a profile
+     * *expected* (a `PROFILE_QUIRK_APPLIED`) does **not** escalate — it is known,
+     * benign, and still recorded.
+     */
+    readonly strict?: boolean;
+    /**
+     * An active vendor {@link AstmProfile}. Its quirk tolerances downgrade the
+     * deviations it *expects* to `PROFILE_QUIRK_APPLIED` warnings (values are never
+     * altered). An explicit profile wins over the process-scoped default
+     * ({@link setDefaultAstmProfile}); pass `null` to opt out of the default for a
+     * single call. Omit to use the default, or no profile when none is registered.
+     */
+    readonly profile?: AstmProfile | null;
+}
+
+/**
+ * The record-layer entry point: {@link parseAstmRecords}.
+ *
+ * Phase 1 assumes **already-de-framed** record bytes (the E1381/LIS01 framing
+ * layer is a later phase). It reads the four delimiters from the header, tokenizes
+ * every record escape-aware, and builds the immutable {@link AstmMessage} — lenient
+ * by default: vendor quirks become typed warnings, and only three unrecoverable
+ * structural conditions are fatal.
+ */
+
+/**
+ * Thrown by {@link parseAstmRecords} in `strict` mode when the lenient parser
+ * would otherwise have accumulated one or more Tier-2 warnings. Carries the
+ * warnings (code + position, never a value) so a caller can see every deviation.
+ *
+ * @example
+ * ```ts
+ * import { parseAstmRecords, AstmStrictError } from "@cosyte/astm";
+ * try {
+ *   parseAstmRecords("H|\\^&\rZ|1\r", { strict: true });
+ * } catch (err) {
+ *   if (err instanceof AstmStrictError) err.warnings.length; // >= 1
+ * }
+ * ```
+ */
+declare class AstmStrictError extends Error {
+    readonly warnings: readonly AstmRecordWarning[];
+    /** @internal */
+    constructor(warnings: readonly AstmRecordWarning[]);
+}
+/**
+ * Parse an ASTM/CLSI-LIS02 record stream into an immutable {@link AstmMessage}.
+ *
+ * The stream is a sequence of records separated by `CR` (with `LF`/`CRLF`
+ * tolerated); the first record must be an `H` header, which declares the
+ * delimiters used by the rest. Lenient by default — set `strict` to reject any
+ * tolerated deviation.
+ *
+ * @param raw - The de-framed record bytes, as a string or `Uint8Array` (decoded
+ *   latin1 so byte values survive 1:1).
+ * @param options - Parse options; lenient unless `strict` is set.
+ * @returns The parsed, deeply-frozen message.
+ * @throws {@link AstmParseError} on a Tier-3 fatal (`EMPTY_INPUT`,
+ *   `ASTM_RECORD_NO_HEADER`, `ASTM_RECORD_UNDECLARED_DELIMITERS`).
+ * @throws {@link AstmStrictError} when `strict` is set and a deviation occurs.
+ * @example
+ * ```ts
+ * import { parseAstmRecords, results } from "@cosyte/astm";
+ * const msg = parseAstmRecords("H|\\^&\rP|1\rO|1|ACC\rR|1|^^^687|28.6|U/L||N||F\rL|1|N\r");
+ * results(msg)[0]?.value; // "28.6"
+ * ```
+ */
+declare function parseAstmRecords(raw: string | Uint8Array, options?: AstmParseOptions): AstmMessage;
+/**
+ * Attach every `C` (comment) record to its parent by position — the immediately-preceding
+ * `H`/`P`/`O`/`R` record; consecutive comments share that parent. **Fail-safe:** a comment with no
+ * valid preceding parent is an **orphan** — it is attached to the message root (`attachedToRoot:
+ * true`) with an `ASTM_RECORD_ORPHAN_COMMENT` warning, **never dropped**. Returns a new array; the
+ * non-comment records pass through unchanged.
+ *
+ * @param records - The built records, in wire order.
+ * @param warnings - The accumulator an orphan comment warns onto.
+ * @returns The records with each comment's `parentIndex` / `attachedToRoot` resolved.
+ * @example
+ * ```ts
+ * import { attachComments } from "@cosyte/astm";
+ * // A comment with no preceding H/P/O/R is an orphan attached to the root.
+ * const warnings: import("@cosyte/astm").AstmRecordWarning[] = [];
+ * const out = attachComments(
+ *   [{ type: "C", recordIndex: 0, fields: [], attachedToRoot: false }],
+ *   warnings,
+ * );
+ * (out[0] as { attachedToRoot: boolean }).attachedToRoot; // true
+ * ```
+ */
+declare function attachComments(records: readonly AstmRecord[], warnings: AstmRecordWarning[]): AstmRecord[];
+
+/**
+ * The record-layer **emit** side: {@link serializeAstmRecords} — Phase 7.
+ *
+ * The inverse of `parseAstmRecords`. Where the parser is liberal (vendor quirks
+ * become warnings), the serializer is **conservative**: it always emits a
+ * spec-clean stream with the **canonical** delimiter set (`H|\^&`), re-escapes
+ * every embedded delimiter so an embedded `|`/`^`/`\`/`&` in a value can never
+ * break framing (the exact inverse of the Phase-1 escape codec), and terminates
+ * each record with a `CR`.
+ *
+ * **Round-trip by construction.** Serialization emits from a record's **decoded**
+ * component tree (`AstmField.repeats`) and re-escapes each leaf, so
+ * `parseAstmRecords(serializeAstmRecords(msg))` reproduces the same modelled
+ * fields — the same components, the same typed accessors, and the canonical
+ * delimiter set (a non-canonical source is normalized to `H|\^&`, a documented
+ * Phase-7 behavior; round-tripping a vendor's own delimiters is a Phase-8
+ * profile concern).
+ *
+ * **Never break framing.** A component leaf that contains a record terminator
+ * (`CR`/`LF`) cannot be escaped by the ASTM escape codec (only the four declared
+ * delimiters have mnemonics), so emitting it would silently corrupt the wire.
+ * The serializer refuses: an embedded `CR`/`LF` is a typed {@link AstmSerializeError},
+ * never emitted raw.
+ */
+
+/**
+ * Thrown by the record/frame emit side when a value cannot be serialized into a
+ * spec-clean stream — specifically when a component contains a record terminator
+ * (`CR`/`LF`), which the ASTM escape codec cannot encode and which would break
+ * framing if emitted raw. Carries a stable code + positional context, never the
+ * offending value (PHI discipline).
+ *
+ * @example
+ * ```ts
+ * import { serializeAstmRecord, AstmSerializeError, parseAstmRecords } from "@cosyte/astm";
+ * const rec = parseAstmRecords("H|\\^&\rL|1\r").records[1]!;
+ * try {
+ *   serializeAstmRecord(rec);
+ * } catch (err) {
+ *   if (err instanceof AstmSerializeError) err.code; // "ASTM_EMIT_UNENCODABLE_VALUE"
+ * }
+ * ```
+ */
+declare class AstmSerializeError extends Error {
+    /** Stable discriminant; `ASTM_EMIT_UNENCODABLE_VALUE` for a `CR`/`LF` in a value. */
+    readonly code: "ASTM_EMIT_UNENCODABLE_VALUE";
+    /** 0-based ordinal of the record within the message, when known. */
+    readonly recordIndex?: number;
+    /** @internal */
+    constructor(message: string, recordIndex?: number);
+}
+/**
+ * Escape-encode one component leaf for spec-clean emit — the inverse of
+ * `decodeEscapes`. The **escape character itself is encoded first** (`&` → `&E&`)
+ * so a later delimiter substitution can never double-encode the `&` it just
+ * introduced; then the field / component / repeat delimiters map to their
+ * mnemonics.
+ *
+ * A `CR`/`LF` in the leaf has no escape mnemonic and would break framing, so it
+ * is rejected with an {@link AstmSerializeError} rather than emitted raw.
+ *
+ * @param leaf - One already-decoded component string.
+ * @param d - The delimiters to emit against (canonical for spec-clean output).
+ * @param recordIndex - The enclosing record's index, for error context.
+ * @returns The escaped component text.
+ * @example
+ * ```ts
+ * import { encodeComponent, CANONICAL_DELIMITERS } from "@cosyte/astm";
+ * encodeComponent("1^40", CANONICAL_DELIMITERS); // "1&S&40"
+ * ```
+ */
+declare function encodeComponent(leaf: string, d: Delimiters, recordIndex?: number): string;
+/**
+ * Serialize a single ASTM record to its spec-clean wire text (no trailing
+ * terminator). Emits with the given delimiters, defaulting to the canonical set.
+ *
+ * The header (`H`) is special-cased: its delimiter-definition field is emitted as
+ * the **literal** canonical declaration (`\^&`), never escaped — escaping it would
+ * corrupt the very declaration a reader depends on. Manufacturer (`M`) and
+ * scientific (`S`) records are surfaced **byte-identically** from their preserved
+ * `rawLine` — verbatim in, verbatim out.
+ *
+ * @param record - The record to serialize.
+ * @param d - The delimiters to emit against; defaults to `H|\^&`.
+ * @returns The record's wire text, terminator excluded.
+ * @throws {@link AstmSerializeError} when a component contains an unencodable `CR`/`LF`.
+ * @example
+ * ```ts
+ * import { serializeAstmRecord, parseAstmRecords } from "@cosyte/astm";
+ * const msg = parseAstmRecords("H|\\^&\rR|1|^^^687|28.6|U/L||N||F\rL|1\r");
+ * serializeAstmRecord(msg.records[1]!); // "R|1|^^^687|28.6|U/L||N||F"
+ * ```
+ */
+declare function serializeAstmRecord(record: AstmRecord, d?: Delimiters): string;
+/**
+ * Serialize a whole ASTM message (or a bare record list) to a spec-clean,
+ * `CR`-terminated record stream — the inverse of `parseAstmRecords`.
+ *
+ * Emit is **conservative**: the canonical `H|\^&` delimiters, every embedded
+ * delimiter re-escaped, each record closed with a `CR`. A message parsed with
+ * non-canonical delimiters is **normalized** to the canonical set on emit (a
+ * documented Phase-7 behavior — vendor-delimiter round-tripping is Phase 8).
+ *
+ * @param input - A parsed {@link AstmMessage} or a list of {@link AstmRecord}s.
+ * @returns The serialized record stream (`CR` after every record).
+ * @throws {@link AstmSerializeError} when a component contains an unencodable `CR`/`LF`.
+ * @example
+ * ```ts
+ * import { parseAstmRecords, serializeAstmRecords } from "@cosyte/astm";
+ * const raw = "H|\\^&\rP|1\rR|1|^^^687|28.6|U/L||N||F\rL|1\r";
+ * serializeAstmRecords(parseAstmRecords(raw)); // === raw
+ * ```
+ */
+declare function serializeAstmRecords(input: AstmMessage | readonly AstmRecord[], d?: Delimiters): string;
+/**
+ * Serialize a single {@link AstmField} to its spec-clean wire text, re-escaping
+ * each component. A low-level helper for callers assembling a field outside a
+ * whole record.
+ *
+ * @param field - The field to serialize.
+ * @param d - The delimiters to emit against; defaults to `H|\^&`.
+ * @returns The escaped field text.
+ * @example
+ * ```ts
+ * import { serializeField, tokenizeRecord, CANONICAL_DELIMITERS } from "@cosyte/astm";
+ * const fields = tokenizeRecord("R|1|^^^687|1&S&40", CANONICAL_DELIMITERS);
+ * serializeField(fields[3]!); // "1&S&40"
+ * ```
+ */
+declare function serializeField(field: AstmField, d?: Delimiters): string;
+
+/**
+ * The record-layer **builder**: {@link buildAstmMessage} — Phase 7.
+ *
+ * A builder produces spec-clean E1394 records **by construction** from typed
+ * caller input, under two disciplines:
+ *
+ * - **Never fabricate.** A builder emits **only** the values the caller supplied.
+ *   An unsupplied field is left **empty**, never filled with a default clinical
+ *   value — no defaulted result status, abnormal flag, units, value, or patient
+ *   identifier. (Leaving a field empty is not a guess; inventing an `F` status or
+ *   an `N` flag would be.) A consumer that parses a built result whose status the
+ *   caller omitted reads `status.meaning === "unspecified"`, never `"final"`.
+ * - **Compute, don't guess, the structure.** The record type letters, the
+ *   delimiter declaration (canonical `H|\^&`), the message terminator (`L`), and
+ *   the per-record sequence counters are **structural** — computed by the builder,
+ *   not clinical values. The caller may override any sequence number.
+ *
+ * Every value is escape-encoded on emit (via the serializer), so an embedded
+ * delimiter can never break framing, and a value carrying an unencodable `CR`/`LF`
+ * is a typed {@link AstmSerializeError} rather than a corrupted wire.
+ */
+/** A patient name split into its components; only the supplied parts are emitted. */
+interface PatientNameInput {
+    readonly last?: string;
+    readonly first?: string;
+    readonly middle?: string;
+}
+/** Input for a `P` (patient) record. The three IDs stay distinct — none defaults from another. */
+interface PatientInput {
+    readonly type: "P";
+    /** Structural sequence number; auto-computed when omitted. */
+    readonly seq?: string;
+    /** Field 3 — practice-assigned patient ID. */
+    readonly practiceAssignedId?: string;
+    /** Field 4 — laboratory-assigned patient ID. */
+    readonly laboratoryAssignedId?: string;
+    /** Field 5 — a third patient identifier. */
+    readonly patientIdThree?: string;
+    /** Field 6 — patient name (`Last^First^Middle`). */
+    readonly name?: PatientNameInput;
+    /** Field 7 — mother's maiden name. */
+    readonly mothersMaidenName?: string;
+    /** Field 8 — birthdate (`YYYYMMDDHHMMSS`), emitted verbatim, never reformatted. */
+    readonly birthDate?: string;
+    /** Field 9 — sex, emitted verbatim (never defaulted). */
+    readonly sex?: string;
+}
+/** Input for an `O` (order) record. */
+interface OrderInput {
+    readonly type: "O";
+    readonly seq?: string;
+    /** Field 3 — specimen / accession ID. */
+    readonly specimenId?: string;
+    /** Field 4 — instrument specimen ID. */
+    readonly instrumentSpecimenId?: string;
+    /** Field 5 — Universal Test ID components (verbatim, in order; e.g. `["", "", "", "687"]`). */
+    readonly universalTestId?: readonly string[];
+    /** Field 6 — priority, emitted verbatim. */
+    readonly priority?: string;
+    /** Field 12 — action code, emitted verbatim. */
+    readonly actionCode?: string;
+    /** Field 26 — report type, emitted verbatim. */
+    readonly reportType?: string;
+}
+/** Input for an `R` (result) record. No clinical field is defaulted; unsupplied ⇒ empty. */
+interface ResultInput {
+    readonly type: "R";
+    readonly seq?: string;
+    /** Field 3 — Universal Test ID components (verbatim). */
+    readonly universalTestId?: readonly string[];
+    /** Field 4 — the measured value, emitted verbatim (never defaulted). */
+    readonly value?: string;
+    /** Field 5 — units (vendor free text; never defaulted, guessed, or converted). */
+    readonly units?: string;
+    /** Field 6 — reference range, emitted verbatim. */
+    readonly referenceRange?: string;
+    /** Field 7 — abnormal flags, emitted verbatim (never defaulted to `N`). */
+    readonly abnormalFlags?: string;
+    /** Field 9 — result status, emitted verbatim (never defaulted to `F`). */
+    readonly resultStatus?: string;
+    /** Field 11 — operator. */
+    readonly operator?: string;
+    /** Field 12 — test-started timestamp (`YYYYMMDDHHMMSS`), verbatim. */
+    readonly startedAt?: string;
+    /** Field 13 — test-completed timestamp, verbatim. */
+    readonly completedAt?: string;
+    /** Field 14 — instrument identifier. */
+    readonly instrument?: string;
+}
+/** Input for a `C` (comment) record. */
+interface CommentInput {
+    readonly type: "C";
+    readonly seq?: string;
+    /** Field 3 — comment source. */
+    readonly source?: string;
+    /** Field 4 — comment text (a single component). Use {@link CommentInput.textComponents} for a structured comment. */
+    readonly text?: string;
+    /** Field 4 — comment text as explicit components (takes precedence over `text` when set). */
+    readonly textComponents?: readonly string[];
+    /** Field 5 — comment type code, emitted verbatim. */
+    readonly commentType?: string;
+}
+/** Input for a `Q` (request-information) record. */
+interface QueryInput {
+    readonly type: "Q";
+    readonly seq?: string;
+    /** Field 3 — starting range ID, emitted verbatim. */
+    readonly startingRangeId?: string;
+    /** Field 4 — ending range ID, emitted verbatim. */
+    readonly endingRangeId?: string;
+    /** Field 5 — Universal Test ID components; ignored when {@link QueryInput.queriesAllTests} is set. */
+    readonly universalTestId?: readonly string[];
+    /** Field 5 — emit the literal `ALL` universal-query keyword instead of a Universal Test ID. */
+    readonly queriesAllTests?: boolean;
+    /** Field 13 — request-information status, emitted verbatim. */
+    readonly requestInformationStatus?: string;
+}
+/**
+ * Input for an `M` (manufacturer) or `S` (scientific) record — vendor-defined
+ * free-form data. Emitted verbatim from the caller's fields; never interpreted.
+ */
+interface VerbatimInput {
+    readonly type: "M" | "S";
+    /** Data fields (after the type letter), emitted verbatim in order. */
+    readonly fields: readonly string[];
+}
+/** Any record the message builder can emit (the terminator `L` is appended automatically). */
+type AstmRecordInput = PatientInput | OrderInput | ResultInput | CommentInput | QueryInput | VerbatimInput;
+/** Optional header fields (after the delimiter declaration). */
+interface HeaderInput {
+    /** Extra `H`-record fields (field 3 onward), emitted verbatim in order. Field 2 is always `\^&`. */
+    readonly fields?: readonly string[];
+}
+/** The message to build: an optional header, the body records, and an optional terminator code. */
+interface MessageInput {
+    /** Header fields; the canonical `H|\^&` declaration is always emitted. */
+    readonly header?: HeaderInput;
+    /** The body records, in order. `H` and `L` are supplied by the builder. */
+    readonly records: readonly AstmRecordInput[];
+    /**
+     * Field 3 of the auto-appended `L` (terminator) record — the termination code
+     * (e.g. `N` normal). Omitted by default (not defaulted to a value the caller
+     * did not choose); the `L` seq is always emitted.
+     */
+    readonly terminationCode?: string;
+}
+/**
+ * Build a spec-clean ASTM/CLSI-LIS02 record stream from typed input.
+ *
+ * The builder emits the canonical `H|\^&` header (plus any header fields), then
+ * every body record with each supplied field at its correct 1-based position and
+ * every value escape-encoded, then an `L` terminator. **Nothing clinical is
+ * defaulted** — an unsupplied field is empty, never a guessed value — and the
+ * structural pieces (delimiters, record types, sequence counters, terminator) are
+ * computed. The result parses back to an equal message: build → parse fidelity by
+ * construction.
+ *
+ * @param input - The message to build.
+ * @returns The serialized, `CR`-terminated record stream.
+ * @throws {@link AstmSerializeError} when a value contains an unencodable `CR`/`LF`.
+ * @example
+ * ```ts
+ * import { buildAstmMessage, parseAstmRecords, results } from "@cosyte/astm";
+ * const raw = buildAstmMessage({
+ *   records: [{ type: "R", universalTestId: ["", "", "", "687"], value: "28.6", units: "U/L" }],
+ * });
+ * results(parseAstmRecords(raw))[0]?.value; // "28.6"
+ * ```
+ */
+declare function buildAstmMessage(input: MessageInput): string;
+
+/**
+ * Typed extractors over an {@link AstmMessage} — the one-line "pull the value out"
+ * surface that is the package's north star.
+ *
+ * They are thin, total, and immutable: they read the already-parsed model and
+ * never re-parse, never mutate, and never fabricate. `results()` returns every
+ * `R` record in order; `patient()` returns the first `P` record (the identity a
+ * result files against), or `undefined` when the message carries none.
+ */
+
+/**
+ * Every result (`R`) record in the message, in wire order.
+ *
+ * @param msg - A parsed message.
+ * @returns The result records (possibly empty).
+ * @example
+ * ```ts
+ * import { parseAstmRecords, results } from "@cosyte/astm";
+ * const msg = parseAstmRecords("H|\\^&\rR|1|^^^687|28.6|U/L||N||F\rL|1\r");
+ * results(msg)[0]?.units; // "U/L"
+ * ```
+ */
+declare function results(msg: AstmMessage): readonly ResultRecord[];
+/**
+ * The first patient (`P`) record, or `undefined` when the message has none.
+ *
+ * A message can carry several `P` records (multiple patients in a batch); this
+ * returns the first. Consumers needing all of them can filter `msg.records`.
+ *
+ * @param msg - A parsed message.
+ * @returns The first patient record, or `undefined`.
+ * @example
+ * ```ts
+ * import { parseAstmRecords, patient } from "@cosyte/astm";
+ * const msg = parseAstmRecords("H|\\^&\rP|1|PRAC|LAB\rL|1\r");
+ * patient(msg)?.practiceAssignedId; // "PRAC"
+ * ```
+ */
+declare function patient(msg: AstmMessage): PatientRecord | undefined;
+/**
+ * Every order (`O`) record in the message, in wire order.
+ *
+ * @param msg - A parsed message.
+ * @returns The order records (possibly empty).
+ * @example
+ * ```ts
+ * import { parseAstmRecords, orders } from "@cosyte/astm";
+ * const msg = parseAstmRecords("H|\\^&\rO|1|ACC-42||^^^687|R\rL|1\r");
+ * orders(msg)[0]?.specimenId; // "ACC-42"
+ * ```
+ */
+declare function orders(msg: AstmMessage): readonly OrderRecord[];
+/**
+ * Every comment (`C`) record in the message, in wire order. Each carries the
+ * `parentIndex` of the `H`/`P`/`O`/`R` it attaches to (or `attachedToRoot` when
+ * it is an orphan) — use {@link commentsFor} to get the comments of one record.
+ *
+ * @param msg - A parsed message.
+ * @returns The comment records (possibly empty).
+ * @example
+ * ```ts
+ * import { parseAstmRecords, comments } from "@cosyte/astm";
+ * const msg = parseAstmRecords("H|\\^&\rR|1|^^^687|5|U/L||||F\rC|1|I|checked|G\rL|1\r");
+ * comments(msg)[0]?.text; // "checked"
+ * ```
+ */
+declare function comments(msg: AstmMessage): readonly CommentRecord[];
+/**
+ * The comment (`C`) records attached to a given parent record, in wire order.
+ * Returns the comments whose `parentIndex` is that record's `recordIndex`, so a
+ * comment carrying (e.g.) QC context is read against the record it modifies —
+ * never floated to the wrong one.
+ *
+ * @param msg - A parsed message.
+ * @param parent - The `H`/`P`/`O`/`R` record whose comments to collect.
+ * @returns The attached comment records (possibly empty).
+ * @example
+ * ```ts
+ * import { parseAstmRecords, results, commentsFor } from "@cosyte/astm";
+ * const msg = parseAstmRecords("H|\\^&\rR|1|^^^687|5|U/L||||F\rC|1|I|checked|G\rL|1\r");
+ * commentsFor(msg, results(msg)[0]!)[0]?.text; // "checked"
+ * ```
+ */
+declare function commentsFor(msg: AstmMessage, parent: AstmRecord): readonly CommentRecord[];
+/**
+ * Every request-information (`Q`) record in the message, in wire order. A non-empty
+ * result means the message is a **host-query request**, not a result set — see
+ * {@link AstmMessage.classification} (`isHostQueryRequest`).
+ *
+ * @param msg - A parsed message.
+ * @returns The query records (possibly empty).
+ * @example
+ * ```ts
+ * import { parseAstmRecords, query } from "@cosyte/astm";
+ * const msg = parseAstmRecords("H|\\^&\rP|1\rQ|1|^SPEC-7||ALL\rL|1\r");
+ * query(msg)[0]?.queriesAllTests; // true
+ * ```
+ */
+declare function query(msg: AstmMessage): readonly QueryRecord[];
+
+/**
+ * The **host-query flow**: classify a message as a request, a result upload, an
+ * order download, or indeterminate — Phase 4.
+ *
+ * On real analyzers the host-query mode is first-class and sometimes mandatory
+ * (on the Roche cobas 4800 there is *no* results-sending-only option): the
+ * analyzer sends an `H/P/Q/L` **request** and the LIS answers with an `H/P/O/L`
+ * **response**. Misreading a query as a result upload (or the reverse) breaks the
+ * order flow, so this module makes the distinction **explicit**:
+ *
+ * **The `Q` record dominates.** Any message carrying a `Q` (request-information)
+ * record is classified `host-query` — a request — and is **never** treated as a
+ * result set, even if a result record is also present (an anomaly, which the
+ * parser flags separately with `ASTM_RECORD_AMBIGUOUS_MESSAGE_KIND`). This is the
+ * whole point: a `Q`-bearing message can never silently read as a result upload.
+ */
+
+/**
+ * Classify a record stream by the host-query flow. Pure and total — it only reads
+ * the record type letters, never a field value.
+ *
+ * `Q` dominates: a message with any `Q` record is a `host-query` request even when
+ * a result (`R`) record is also present, so a query is never misread as a result
+ * upload. (The `Q`+`R` anomaly is separately warned at parse time.)
+ *
+ * @param records - The parsed records, in wire order.
+ * @returns The message classification.
+ * @example
+ * ```ts
+ * import { classifyMessage, parseAstmRecords } from "@cosyte/astm";
+ * const msg = parseAstmRecords("H|\\^&\rP|1\rQ|1|^SPEC-7||ALL\rL|1\r");
+ * classifyMessage(msg.records).kind; // "host-query"
+ * ```
+ */
+declare function classifyMessage(records: readonly AstmRecord[]): AstmMessageClassification;
+
+/**
+ * Record tokenizer: split one raw ASTM record into typed {@link AstmField}s.
+ *
+ * The split is **escape-aware first, decode second** (see `../common/escapes.ts`):
+ * a field / repeat / component boundary is only recognized on an *unescaped*
+ * delimiter, and each resulting component leaf is decoded afterwards. That
+ * ordering is the whole reason an embedded escaped component delimiter (`&S&`)
+ * reads as a single component instead of being mis-split.
+ */
+
+/**
+ * Tokenize a single record string (its terminator already stripped) into its
+ * fields. `fields[0]` is the type-letter field; ASTM data fields follow at
+ * 1-based indices.
+ *
+ * @param record - The raw record text.
+ * @param d - The delimiters resolved from the header.
+ * @param onUnknownEscape - Called (with the 1-based field index) for each
+ *   unrecognized escape sequence encountered, so the caller can warn.
+ * @returns The record's fields.
+ * @example
+ * ```ts
+ * import { tokenizeRecord, CANONICAL_DELIMITERS } from "@cosyte/astm";
+ * const fields = tokenizeRecord("R|1|^^^687|28.6|U/L", CANONICAL_DELIMITERS);
+ * fields[3].components[0]; // "28.6"
+ * ```
+ */
+declare function tokenizeRecord(record: string, d: Delimiters, onUnknownEscape?: (fieldIndex: number) => void): AstmField[];
+/**
+ * The primary scalar of a field: its first repeat's first component, decoded.
+ * Returns `undefined` for a truly empty field so callers can distinguish
+ * "absent" from a value — never defaulting a missing value.
+ *
+ * @example
+ * ```ts
+ * import { fieldScalar, tokenizeRecord, CANONICAL_DELIMITERS } from "@cosyte/astm";
+ * const f = tokenizeRecord("R|1|^^^687|28.6", CANONICAL_DELIMITERS);
+ * fieldScalar(f[3]); // "28.6"
+ * ```
+ */
+declare function fieldScalar(field: AstmField | undefined): string | undefined;
+
+/**
+ * Fatal error taxonomy for the `@cosyte/astm` record parser.
+ *
+ * Tier-3 **fatal** codes mark input the parser cannot recover into a structured
+ * `AstmMessage`; anything less severe is a Tier-2 warning (see `./warnings.ts`).
+ * `AstmParseError` is thrown directly and consumers narrow via the `code`
+ * discriminant. The set is additions-only across phases — the record layer
+ * introduces three, one of which (`EMPTY_INPUT`) is shared with every future
+ * layer (the frame codec adds its own `ASTM_FRAME_*` fatals later).
+ */
+
+/**
+ * Stable string codes for every Tier-3 fatal the record parser may throw.
+ * Consumers narrow on `err.code` to react to specific structural failures.
+ * Renaming a code is a **breaking change**.
+ *
+ * @example
+ * ```ts
+ * import { parseAstmRecords, FATAL_CODES, AstmParseError } from "@cosyte/astm";
+ * try {
+ *   parseAstmRecords("");
+ * } catch (err) {
+ *   if (err instanceof AstmParseError && err.code === FATAL_CODES.EMPTY_INPUT) {
+ *     // handle empty input
+ *   }
+ * }
+ * ```
+ */
+declare const FATAL_CODES: {
+    /** Input was empty or whitespace-only — there is nothing to parse. Shared across layers. */
+    readonly EMPTY_INPUT: "EMPTY_INPUT";
+    /** The first record is not an `H` (header) record — an ASTM message must lead with `H`. */
+    readonly ASTM_RECORD_NO_HEADER: "ASTM_RECORD_NO_HEADER";
+    /** The `H` record is too short to declare the four delimiters (field/repeat/component/escape). */
+    readonly ASTM_RECORD_UNDECLARED_DELIMITERS: "ASTM_RECORD_UNDECLARED_DELIMITERS";
+};
+/**
+ * A value from {@link FATAL_CODES} — the type carried by a thrown {@link AstmParseError}.
+ */
+type FatalCode = (typeof FATAL_CODES)[keyof typeof FATAL_CODES];
+/**
+ * Thrown by {@link parseAstmRecords} when the input violates one of the Tier-3
+ * unrecoverable structural rules (empty input, no leading `H`, or an `H` that
+ * cannot declare its delimiters). Carries positional context so consumers can
+ * log an actionable error.
+ *
+ * **PHI:** the error carries a stable code + position only, never a field value.
+ *
+ * @example
+ * ```ts
+ * import { parseAstmRecords, AstmParseError } from "@cosyte/astm";
+ * try {
+ *   parseAstmRecords("P|1");
+ * } catch (err) {
+ *   if (err instanceof AstmParseError && err.code === "ASTM_RECORD_NO_HEADER") {
+ *     // err.position is available; err carries no field value
+ *   }
+ * }
+ * ```
+ */
+declare class AstmParseError extends Error {
+    readonly code: FatalCode;
+    readonly position: AstmPosition;
+    /**
+     * Construct a new `AstmParseError`. Both fields are required so every thrower
+     * populates positional context and no PHI-bearing snippet is ever attached.
+     *
+     * @internal
+     */
+    constructor(code: FatalCode, message: string, position: AstmPosition);
+}
+
+/**
+ * The ASTM escape codec — the Phase-1 fix for a documented silent-misread class.
+ *
+ * ASTM escapes an embedded delimiter with the escape character on both sides of
+ * a single mnemonic letter (the InterSystems mnemonics, cross-verified in the
+ * roadmap's OSS references):
+ *
+ * ```
+ *   &F&  → field delimiter      (default "|")
+ *   &S&  → component delimiter  (default "^")
+ *   &R&  → repeat delimiter     (default "\")
+ *   &E&  → escape character     (default "&")
+ * ```
+ *
+ * **Why this is a requirement, not a nicety.** A result value can legitimately
+ * contain a component delimiter — e.g. a titre written `1^40`. On the wire that
+ * is escaped as `1&S&40`. A parser that splits a field into components on the
+ * raw component delimiter and *never decodes the escape* is safe here (the
+ * escape body `&S&` contains no literal `^`), but a parser that **decodes first
+ * and splits second** turns `1&S&40` into `1^40` and then mis-splits it into two
+ * components — the silent misread `python-astm` / `Chistousov` exhibit. The
+ * correct order, implemented here, is **escape-aware split, then decode each
+ * leaf**: the escape sequence survives the split intact and only then decodes to
+ * a single literal, so `1&S&40` reads as exactly one component.
+ *
+ * Re-escaping (the inverse, for spec-clean emit) belongs to the serialize phase
+ * (P7) and is deliberately not implemented here.
+ */
+
+/**
+ * A callback the codec calls when it encounters an escape sequence whose body is
+ * not one of the four recognized mnemonics. The sequence is preserved verbatim;
+ * the callback lets the parser surface a value-free `ASTM_UNKNOWN_ESCAPE_SEQUENCE`
+ * warning. Optional so the codec can be used purely.
+ */
+type UnknownEscapeSink = () => void;
+/**
+ * Decode the four recognized ASTM escape mnemonics in a single already-split
+ * leaf (a component string), substituting the *active* delimiters read from the
+ * header. Unrecognized `&…&` bodies are preserved verbatim and reported through
+ * `onUnknown` (never dropped, never guessed).
+ *
+ * This runs **after** splitting, so a decoded delimiter becomes ordinary literal
+ * text and can never introduce a new split boundary.
+ *
+ * @param leaf - One component string, escape-aware split already applied.
+ * @param d - The delimiters resolved from the header.
+ * @param onUnknown - Called once per unrecognized escape body encountered.
+ * @returns The decoded string.
+ * @example
+ * ```ts
+ * import { decodeEscapes, CANONICAL_DELIMITERS } from "@cosyte/astm";
+ * decodeEscapes("1&S&40", CANONICAL_DELIMITERS); // "1^40"
+ * ```
+ */
+declare function decodeEscapes(leaf: string, d: Delimiters, onUnknown?: UnknownEscapeSink): string;
+/**
+ * Split `text` on `delimiter`, treating any escape sequence (`escape …
+ * escape`) as an opaque atom so a delimiter that appears *inside* an escape body
+ * never causes a split. Returns the raw (still-encoded) segments — decoding is
+ * the caller's next step, per the escape-aware-split-then-decode contract.
+ *
+ * For the four canonical mnemonics this is belt-and-suspenders (their bodies are
+ * letters, not delimiters), but it makes the "an escaped delimiter is one token"
+ * guarantee hold for any declared delimiter set, including adversarial input.
+ *
+ * @param text - The field or repeat string to split.
+ * @param delimiter - The delimiter to split on.
+ * @param escape - The active escape character.
+ * @returns The raw segments, in order.
+ * @example
+ * ```ts
+ * import { splitEscapeAware } from "@cosyte/astm";
+ * splitEscapeAware("a^b^c", "^", "&"); // ["a", "b", "c"]
+ * splitEscapeAware("1&S&40", "^", "&"); // ["1&S&40"]  (escape body is opaque)
+ * ```
+ */
+declare function splitEscapeAware(text: string, delimiter: string, escape: string): string[];
+
+/**
+ * Deep-freeze helper for the immutable ASTM model.
+ *
+ * The parser returns plain readonly data; `deepFreeze` makes that immutability
+ * enforced at runtime (a stray `msg.records[0].fields[0] = …` throws in strict
+ * mode and is a no-op otherwise), which the shared `immutabilityProperty`
+ * invariant asserts. Zero-dep, Node stdlib only.
+ */
+/**
+ * Recursively freeze an object graph (objects and arrays), returning the same
+ * reference typed as deeply readonly. Cyclic graphs are not produced by the
+ * parser, so a simple recursive walk suffices.
+ *
+ * @param value - The value to freeze in place.
+ * @returns The same value, now deeply frozen.
+ * @example
+ * ```ts
+ * import { deepFreeze } from "@cosyte/astm";
+ * const frozen = deepFreeze({ a: [1, 2] });
+ * Object.isFrozen(frozen.a); // true
+ * ```
+ */
+declare function deepFreeze<T>(value: T): T;
+
+/**
+ * `defineAstmProfile()` — the public factory for building immutable
+ * {@link AstmProfile} objects with the safety rules enforced and `describe()`
+ * attached. Mirrors the sibling `@cosyte/hl7` `defineProfile()` / `@cosyte/ccda`
+ * `defineCcdaProfile()` shape (name / lineage / `extends`-merge / `describe`) while
+ * modelling ASTM quirks — a tolerated warning code with provenance, plus the
+ * optional raw-vs-framed transport override — rather than HL7 v2 Z-segments or
+ * C-CDA template deviations.
+ *
+ * Zero runtime deps. No `any`; immutability at the return boundary via
+ * `Object.freeze` (top-level, matching the sibling's boundary-freeze doctrine).
+ */
+
+/**
+ * Build a frozen {@link AstmProfile} from a validated options object. Throws
+ * {@link AstmProfileDefinitionError} on a bad name, an unknown option key, an
+ * invalid `transport`, or an invalid `tolerate` entry — including the **safety
+ * rule**: a profile may never tolerate a safety-critical warning code (default-deny
+ * across all three registries).
+ *
+ * `extends` composes profiles: lineage, `tolerate`, `transport`, `provenance`, and
+ * `description` merge (parents left-to-right, then self; scalars are child-wins).
+ * The merged `tolerate` set is re-validated so a safety-critical code cannot sneak
+ * in via a hand-crafted parent.
+ *
+ * @param opts - The profile definition; see {@link DefineAstmProfileOptions}.
+ * @returns A frozen, immutable profile with `describe()` attached.
+ * @throws {@link AstmProfileDefinitionError} on any invalid definition.
+ * @example
+ * ```ts
+ * import { defineAstmProfile } from "@cosyte/astm";
+ * const site = defineAstmProfile({
+ *   name: "acme-analyzer",
+ *   description: "Acme's inbound raw-TCP analyzer",
+ *   transport: "raw",
+ *   tolerate: [
+ *     { code: "ASTM_RECORD_UNKNOWN_TYPE", rationale: "emits a vendor QC record letter" },
+ *   ],
+ *   provenance: { source: "Acme host-interface manual", reference: "internal-2026" },
+ * });
+ * site.lineage; // ["acme-analyzer"]
+ * console.log(site.describe?.());
+ * ```
+ */
+declare function defineAstmProfile(opts: DefineAstmProfileOptions): AstmProfile;
+
+/**
+ * The definition-time error for the `@cosyte/astm` vendor-profile subsystem.
+ *
+ * A profile is validated when it is *defined*, not when it is applied — so a
+ * misconfigured profile (a bad name, an unknown option key, a tolerated code that
+ * is unknown or **safety-critical**) fails loudly at construction, long before it
+ * could quiet a real deviation. This is the class that failure throws. It is a
+ * programming error (a bad profile literal), distinct from `AstmParseError` (bad
+ * input) — so consumers narrow on it separately.
+ */
+/**
+ * Thrown by `defineAstmProfile` when a profile definition is invalid: a missing or
+ * empty `name`, an unknown option key, an invalid `transport` value, or a
+ * `tolerate` entry whose code is unknown, whose `rationale` is empty, or — the
+ * load-bearing safety rule — whose code is **safety-critical** (a result value,
+ * abnormal flag, result status, reference range, units, patient/comment context,
+ * message-kind, code system, or any frame/LTP integrity warning). Carries the
+ * offending profile's `name` when it is known, so a multi-profile build names the
+ * culprit.
+ *
+ * @example
+ * ```ts
+ * import { defineAstmProfile, AstmProfileDefinitionError } from "@cosyte/astm";
+ * try {
+ *   defineAstmProfile({
+ *     name: "unsafe",
+ *     tolerate: [{ code: "ASTM_FRAME_BAD_CHECKSUM", rationale: "no" }],
+ *   });
+ * } catch (err) {
+ *   if (err instanceof AstmProfileDefinitionError) err.profileName; // "unsafe"
+ * }
+ * ```
+ */
+declare class AstmProfileDefinitionError extends Error {
+    /** The offending profile's `name`, when it could be read. */
+    readonly profileName?: string;
+    /**
+     * Construct a new `AstmProfileDefinitionError`.
+     *
+     * @param message - A human-readable explanation of what was invalid.
+     * @param profileName - The offending profile's name, when known.
+     * @internal
+     */
+    constructor(message: string, profileName?: string);
+}
+
+/**
+ * The profile **registry**: the named built-in set (with provenance) plus a
+ * process-scoped default. Mirrors the sibling `@cosyte/hl7` / `@cosyte/ccda`
+ * `set/getDefault*Profile` convention. `parseAstmRecords(raw)` with no explicit
+ * `profile` option consults {@link getDefaultAstmProfile}; an explicit `profile`
+ * option always wins, and `profile: null` opts out of the default for a single call.
+ *
+ * The single mutable module-scoped `let` is the only such state in the profile
+ * subsystem — an intentional, documented trade-off (identical to the siblings).
+ * Tests that set a default MUST clear it in teardown (`setDefaultAstmProfile(null)`)
+ * to avoid cross-test bleed.
+ */
+
+/**
+ * Look up a built-in profile by name. Returns `undefined` when no built-in has that
+ * name (a user-defined profile is not in this registry — pass it directly).
+ *
+ * @param name - The built-in profile name.
+ * @returns The profile, or `undefined`.
+ * @example
+ * ```ts
+ * import { getAstmProfile } from "@cosyte/astm";
+ * getAstmProfile("referenceCorpus")?.provenance?.source;
+ * ```
+ */
+declare function getAstmProfile(name: string): AstmProfile | undefined;
+/**
+ * The names of every built-in profile, in registration order.
+ *
+ * @returns The built-in names.
+ * @example
+ * ```ts
+ * import { listAstmProfiles } from "@cosyte/astm";
+ * listAstmProfiles(); // ["default", "referenceCorpus"]
+ * ```
+ */
+declare function listAstmProfiles(): readonly string[];
+/**
+ * Register a process-scoped default profile that `parseAstmRecords(raw)` applies
+ * when no explicit `profile` option is passed. Pass `null` (or `undefined`) to
+ * clear. An explicit `parseAstmRecords(raw, { profile })` always wins;
+ * `{ profile: null }` opts out of the default for a single call.
+ *
+ * **Test hygiene:** the only mutable module-scoped state here — tests that call this
+ * MUST clear it in teardown or default-profile bleed infects later tests.
+ *
+ * @param profile - The profile to register as default, or `null` to clear.
+ * @example
+ * ```ts
+ * import { setDefaultAstmProfile, astmProfiles, parseAstmRecords } from "@cosyte/astm";
+ * setDefaultAstmProfile(astmProfiles.referenceCorpus);
+ * const msg = parseAstmRecords(raw); // uses referenceCorpus
+ * setDefaultAstmProfile(null); // clear
+ * ```
+ */
+declare function setDefaultAstmProfile(profile: AstmProfile | null): void;
+/**
+ * Return the current process-scoped default profile, or `undefined` if none is
+ * registered.
+ *
+ * @returns The default profile, or `undefined`.
+ * @example
+ * ```ts
+ * import { getDefaultAstmProfile } from "@cosyte/astm";
+ * const p = getDefaultAstmProfile();
+ * if (p !== undefined) console.log("default profile:", p.name);
+ * ```
+ */
+declare function getDefaultAstmProfile(): AstmProfile | undefined;
+
+/**
+ * The runtime side of the profile subsystem: turning an active {@link AstmProfile}
+ * into a warning transform the record parser runs over its accumulated warnings,
+ * plus the transport-override accessor the framing detector consumes.
+ *
+ * A profile **never touches an extracted value**. The warning transform operates
+ * purely at the warning layer — downgrading a deviation it *expects* into a
+ * `PROFILE_QUIRK_APPLIED` warning (flagged `expected`, carrying the original
+ * `toleratedCode`) while leaving every un-expected warning untouched. Because the
+ * transform only ever rewrites a warning object (never a record, field, or value),
+ * a profile cannot change how any byte parses: a spec-clean message parses
+ * identically with or without a profile.
+ */
+
+/**
+ * Apply a profile to a single warning. Returns a downgraded `PROFILE_QUIRK_APPLIED`
+ * warning when the profile expects this deviation; otherwise returns the original
+ * warning unchanged (referential identity preserved, so an un-tolerated warning is
+ * never reallocated). A warning that is already `expected` (e.g. re-processed) is
+ * passed through untouched.
+ *
+ * @param profile - The active profile.
+ * @param warning - One accumulated warning.
+ * @returns The re-badged warning when tolerated, else the original.
+ * @example
+ * ```ts
+ * import { applyAstmProfile, astmProfiles, unknownEscapeSequence } from "@cosyte/astm";
+ * const w = unknownEscapeSequence({ recordIndex: 4, recordType: "R", fieldIndex: 5 });
+ * const out = applyAstmProfile(astmProfiles.referenceCorpus, w);
+ * out.code; // "PROFILE_QUIRK_APPLIED"
+ * out.toleratedCode; // "ASTM_UNKNOWN_ESCAPE_SEQUENCE"
+ * ```
+ */
+declare function applyAstmProfile(profile: AstmProfile, warning: AstmRecordWarning): AstmRecordWarning;
+/**
+ * Apply a profile across a whole warning list, returning a NEW array (the input is
+ * never mutated). Returned unchanged (same reference contents, a shallow copy) when
+ * `profile` is `undefined`, so the no-profile path pays only a copy. Every tolerated
+ * warning is re-badged; every other warning passes through by identity — nothing is
+ * dropped, reordered, or reallocated beyond the re-badge.
+ *
+ * @param warnings - The accumulated record warnings.
+ * @param profile - The active profile, or `undefined` for no transform.
+ * @returns A new array with tolerated warnings downgraded.
+ * @example
+ * ```ts
+ * import { applyAstmProfileToWarnings, astmProfiles } from "@cosyte/astm";
+ * const out = applyAstmProfileToWarnings(msgWarnings, astmProfiles.referenceCorpus);
+ * ```
+ */
+declare function applyAstmProfileToWarnings(warnings: readonly AstmRecordWarning[], profile: AstmProfile | undefined): AstmRecordWarning[];
+/**
+ * The profile's transport override, if any — the value a consumer feeds to
+ * `detectFraming(bytes, { override })` to force framed/raw and bypass leading-byte
+ * auto-detection. `undefined` means "let detection decide."
+ *
+ * @param profile - The active profile, or `undefined`.
+ * @returns `"framed"` / `"raw"` when the profile forces one, else `undefined`.
+ * @example
+ * ```ts
+ * import { resolveProfileTransport, detectFraming, astmProfiles } from "@cosyte/astm";
+ * const override = resolveProfileTransport(myRawTcpProfile);
+ * const { framing } = detectFraming(bytes, override !== undefined ? { override } : {});
+ * ```
+ */
+declare function resolveProfileTransport(profile: AstmProfile | undefined): AstmFraming | undefined;
+
+/**
+ * The safety spine of the profile subsystem: the set of warning codes a profile is
+ * **forbidden** to tolerate. A vendor profile exists to quiet known, benign
+ * structural noise — never to hide a deviation that could change a clinical
+ * reading or corrupt the wire.
+ *
+ * **Design: default-deny.** Rather than enumerate the *forbidden* codes (a list you
+ * can forget to extend when a new warning ships — the exact incompleteness a
+ * safety gate must not have), this module enumerates the tiny set of **explicitly
+ * tolerable** codes and treats *every other* code, across all three registries
+ * (record `ASTM_RECORD_*`, frame `ASTM_FRAME_*`, protocol `ASTM_LTP_*`), as
+ * safety-critical. A warning code added in a future phase is therefore
+ * safety-critical **by default** until someone deliberately, reviewably adds it to
+ * the allow-list below. Widening the allow-list can only ever be an explicit,
+ * argued act; forgetting to touch this file can never *weaken* the gate.
+ *
+ * The four tolerable codes are the only deviations that (a) are structural/
+ * syntactic vendor noise and (b) **cannot alter, drop, or fabricate an extracted
+ * value** — because a profile only ever re-badges a *warning*, never re-parses. In
+ * every one, the underlying datum is already surfaced verbatim regardless of the
+ * profile:
+ *
+ * - `ASTM_RECORD_UNKNOWN_TYPE` — an unmodeled record type, surfaced verbatim as an
+ *   `unsupported` record carrying no interpreted clinical field.
+ * - `ASTM_NONSTANDARD_DELIMITERS` — the header's own declared delimiters are read
+ *   and honored either way; this only notes they differ from the canonical set.
+ * - `ASTM_UNKNOWN_ESCAPE_SEQUENCE` — an unrecognized `&…&` body is **preserved
+ *   byte-for-byte** in the decoded value (the escape codec never guesses); the
+ *   warning is a purely syntactic advisory, the value is identical with or without
+ *   the profile.
+ * - `ASTM_RECORD_UNINTERPRETED_QUERY_STATUS` — a `Q`-record request-information
+ *   status surfaced verbatim on a *request* record; the code set is paywalled and
+ *   is never interpreted, profile or not.
+ *
+ * Everything a wrong value could hide from — a result value split ambiguity, an
+ * undefined abnormal flag or result status, an unparseable reference range, absent
+ * units, a mis-attached comment, a partial timestamp, a query-vs-result ambiguity,
+ * a bad frame checksum / sequence gap / unterminated / oversize frame, an
+ * ambiguous transport, an unexpected protocol event, or a rejected frame — is
+ * forbidden.
+ */
+
+/**
+ * The **only** warning codes a profile may list in its `tolerate` set — benign,
+ * structural/syntactic vendor noise that cannot alter, drop, or fabricate an
+ * extracted value. Frozen so it cannot be mutated at runtime to smuggle a code in.
+ * Adding to this set is a deliberate, reviewable act (and each addition must be an
+ * `expected: false` non-safety code by the same reasoning as the four here).
+ *
+ * @example
+ * ```ts
+ * import { TOLERABLE_CODES } from "@cosyte/astm";
+ * TOLERABLE_CODES.has("ASTM_UNKNOWN_ESCAPE_SEQUENCE"); // true
+ * TOLERABLE_CODES.has("ASTM_FRAME_BAD_CHECKSUM"); // false
+ * ```
+ */
+declare const TOLERABLE_CODES: ReadonlySet<AnyAstmWarningCode>;
+/**
+ * The set of every real warning code, for O(1) membership checks (used by the
+ * validator to distinguish "unknown code" from "known but forbidden"). Frozen.
+ *
+ * @example
+ * ```ts
+ * import { ALL_ASTM_WARNING_CODES } from "@cosyte/astm";
+ * ALL_ASTM_WARNING_CODES.has("ASTM_LTP_FRAME_REJECTED"); // true
+ * ```
+ */
+declare const ALL_ASTM_WARNING_CODES: ReadonlySet<AnyAstmWarningCode>;
+/**
+ * The forbidden set — computed as **every known code minus the tolerable
+ * allow-list**, so it is complete by construction. Frozen. A code appears here iff
+ * it is a real warning code that is not in {@link TOLERABLE_CODES}.
+ *
+ * @example
+ * ```ts
+ * import { SAFETY_CRITICAL_CODES } from "@cosyte/astm";
+ * SAFETY_CRITICAL_CODES.has("ASTM_RECORD_UNDEFINED_RESULT_STATUS"); // true
+ * SAFETY_CRITICAL_CODES.has("ASTM_FRAME_BAD_CHECKSUM"); // true
+ * ```
+ */
+declare const SAFETY_CRITICAL_CODES: ReadonlySet<AnyAstmWarningCode>;
+/**
+ * True when `code` is a known warning code that is **not** tolerable — i.e. a
+ * profile may never list it. A code that is not a real warning code at all returns
+ * `false` here (the validator reports "unknown code" separately, a distinct
+ * failure with a distinct message).
+ *
+ * @param code - The warning code to test.
+ * @returns `true` iff the code is a real code outside the tolerable allow-list.
+ * @example
+ * ```ts
+ * import { isSafetyCriticalCode } from "@cosyte/astm";
+ * isSafetyCriticalCode("ASTM_UNKNOWN_ESCAPE_SEQUENCE"); // false (tolerable)
+ * isSafetyCriticalCode("ASTM_RECORD_AMBIGUOUS_VALUE_SPLIT"); // true
+ * ```
+ */
+declare function isSafetyCriticalCode(code: string): boolean;
+
+/**
+ * The `default` conservative baseline profile. Tolerates **nothing** and forces no
+ * transport — every deviation surfaces as its own warning, unmodified, and framing
+ * is auto-detected. It exists so "no profile" and "the default profile" are the
+ * same, explicit behaviour, and so a consumer can name the baseline when composing
+ * (`extends: astmProfiles.default`) without importing a special sentinel. Absence of
+ * a profile means this conservative default applied — not that a stream was fully
+ * understood.
+ *
+ * Authored through the public `defineAstmProfile()` API — zero privileged coupling;
+ * it is exactly what a user would write.
+ */
+
+/**
+ * The conservative baseline profile: no tolerated quirks, no transport override.
+ *
+ * @example
+ * ```ts
+ * import { parseAstmRecords, astmProfiles } from "@cosyte/astm";
+ * const msg = parseAstmRecords(raw, { profile: astmProfiles.default });
+ * // identical to parseAstmRecords(raw) with no profile.
+ * ```
+ */
+declare const defaultProfile: AstmProfile;
+
+/**
+ * The `referenceCorpus` profile — a **non-vendor**, evidence-backed tolerance
+ * grounded firsthand in the **redistributable OSS reference corpus**, not an
+ * invented per-vendor deviation matrix.
+ *
+ * Grounding (firsthand-verified 2026-07-21; the corpus is permissively licensed and
+ * in scope for grounding, per the roadmap):
+ *
+ * - **`kxepal/python-astm` `codec.py`** (BSD) — its `decode_record` /
+ *   `decode_component` / `decode_repeated_component` split fields, components, and
+ *   repeats on the raw delimiters and **never un-escape** ASTM escape sequences: the
+ *   source contains zero handling of `&F&`/`&S&`/`&R&`/`&E&`, and the escape
+ *   character is treated as ordinary data. `senaite.astm` / `senaite.lis2a` inherit
+ *   the same escape-agnostic decode.
+ * - Consequence, and what this profile expects: a stream produced or relayed by a
+ *   toolchain built on that escape-agnostic reference stack routinely carries a bare
+ *   or non-standard `&…&` body inside a free-text field (units, comments, test
+ *   names) that our **escape-aware** tokenizer flags as
+ *   `ASTM_UNKNOWN_ESCAPE_SEQUENCE`. We are deliberately stricter than the OSS
+ *   references here (roadmap §6 differential note), so the warning is *expected*
+ *   noise when talking to that ecosystem — recognizable and non-clinical.
+ *
+ * **Why this is safe.** The escape codec **preserves an unrecognized `&…&` body
+ * byte-for-byte** in the decoded value (`decodeEscapes` never guesses); the value a
+ * consumer reads is identical whether or not this profile is active. The profile
+ * only re-badges the *warning* — no value, flag, status, or identifier is altered
+ * or dropped. And by the safety gate in `defineAstmProfile`, it **cannot** tolerate
+ * a result value / flag / status / range / units, a patient or comment context, a
+ * message-kind ambiguity, or any frame / LTP integrity warning — those always
+ * surface, profile or not.
+ *
+ * **Honesty.** This is a *reference-corpus* profile, not a claim about any named
+ * analyzer vendor. No per-vendor ("cobas does X") behaviour is asserted; a named
+ * vendor profile awaits a firsthand vendor-attributed quirk document and stays
+ * deferred (`REAL-CORPUS`).
+ */
+
+/**
+ * Tolerates the non-standard-escape noise that streams from the escape-agnostic OSS
+ * reference stack (`python-astm` / `senaite`) carry — the value is preserved
+ * verbatim; only the syntactic warning is expected.
+ *
+ * @example
+ * ```ts
+ * import { parseAstmRecords, astmProfiles, WARNING_CODES } from "@cosyte/astm";
+ * const msg = parseAstmRecords(raw, { profile: astmProfiles.referenceCorpus });
+ * // an unknown-escape deviation arrives as PROFILE_QUIRK_APPLIED (expected), not a bare warning:
+ * const quirks = msg.warnings.filter((w) => w.code === WARNING_CODES.PROFILE_QUIRK_APPLIED);
+ * ```
+ */
+declare const referenceCorpus: AstmProfile;
+
+/**
+ * Public barrel for the `@cosyte/astm` vendor-profile subsystem. Assembles the
+ * `astmProfiles` namespace object (the built-ins) and re-exports the public profile
+ * API: `defineAstmProfile`, the registry accessors, the apply helpers, the safety
+ * set, the definition-time error, and the profile types.
+ *
+ * The individual built-ins are reached via `astmProfiles.referenceCorpus` etc., not
+ * as top-level named exports — mirrors the sibling `profiles` namespace convention
+ * ("default" is too generic for a top-level export).
+ */
+
+/**
+ * Namespace object exposing the built-in profiles: the conservative `default`
+ * baseline plus the evidence-backed `referenceCorpus` (grounded firsthand in the
+ * redistributable OSS reference corpus), each authored via the public
+ * `defineAstmProfile()` API and carrying its cited provenance. Named per-vendor
+ * profiles (cobas / Sysmex / …) are **deferred** pending a firsthand
+ * vendor-attributed quirk document — the engine fully supports them; we do not ship
+ * ungrounded ones.
+ *
+ * @example
+ * ```ts
+ * import { parseAstmRecords, astmProfiles } from "@cosyte/astm";
+ * const msg = parseAstmRecords(raw, { profile: astmProfiles.referenceCorpus });
+ * msg.profile?.name; // "referenceCorpus"
+ * ```
+ */
+declare const astmProfiles: {
+    readonly default: typeof defaultProfile;
+    readonly referenceCorpus: typeof referenceCorpus;
+};
+
+/**
+ * The **consumer-supplied** LIVD catalog: a vendor-test-code → LOINC index built
+ * from an IICC LIVD ("LOINC to Vendor IVD") mapping the consumer provides.
+ *
+ * **Bring-your-own, by design (roadmap §5, Phase 9).** `@cosyte/astm` bundles
+ * **no** LOINC, SNOMED, or LIVD data — LOINC is © Regenstrief (redistributable
+ * only with its attribution notice) and the public CDC LIVD publication is a
+ * SARS-CoV-2-specific file that also carries SNOMED CT (separately licensed), not
+ * a general-analyte, public-domain catalog. So the package stays a **structural
+ * recognizer, not a dictionary**: it recognizes the Universal Test ID's LOINC slot
+ * and surfaces vendor codes verbatim (Phase 1), and this module lets a consumer
+ * *supply* their own LIVD file to map those codes — the terminology data, and its
+ * license obligations, are the consumer's.
+ *
+ * **Grounded firsthand on the IICC LIVD digital format / HL7 LIVD IG.** The
+ * mapping key is the **Vendor Analyte Code** — the vendor *transmission code* the
+ * instrument sends for an automated test, which is exactly the local code an ASTM
+ * analyzer puts in the Universal Test ID (`R`/`O` field, component 4). The mapping
+ * target is the **LOINC Code** (with the LOINC Long Common Name as an optional
+ * human-readable label). Manufacturer/Model are optional provenance a consumer can
+ * carry for their own auditing; this catalog keys on the vendor code alone and,
+ * crucially, **refuses to choose** when one code maps to more than one LOINC.
+ *
+ * **Scope the catalog to the source device fleet.** The ASTM Universal Test ID
+ * carries no manufacturer to disambiguate against, so two different instruments that
+ * reuse the same transmission code for different analytes would both match a single
+ * catalog entry. Supply a catalog built for the analyzers you actually receive from;
+ * 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 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
+ * LIVD digital format's data elements.
+ *
+ * @example
+ * ```ts
+ * import type { LivdEntry } from "@cosyte/astm";
+ * const e: LivdEntry = { vendorCode: "687", loinc: "1920-8", loincLongName: "AST" };
+ * ```
+ */
+interface LivdEntry {
+    /**
+     * The **Vendor Analyte Code** — the vendor transmission code the instrument sends (the local code
+     * in an ASTM Universal Test ID, component 4). The mapping key; compared **verbatim** (exact,
+     * case-sensitive) against the reported code — never normalized or fuzzy-matched.
+     */
+    readonly vendorCode: string;
+    /**
+     * The **LOINC Code** this vendor code maps to (e.g. `"1920-8"`). Taken from the consumer's catalog
+     * as-is and **never validated, altered, or invented** — the parser does not ship a LOINC table and
+     * cannot check it; it only carries what the catalog says.
+     */
+    readonly loinc: string;
+    /** The **LOINC Long Common Name**, when the catalog supplies it — an optional human-readable label. */
+    readonly loincLongName?: string;
+    /** The **Vendor Analyte Name** — the vendor's human-readable analyte label, when supplied. */
+    readonly vendorAnalyteName?: string;
+    /** The device **Manufacturer**, when the catalog scopes the mapping to a device (optional provenance). */
+    readonly manufacturer?: string;
+    /** The device **Model**, when the catalog scopes the mapping to a device (optional provenance). */
+    readonly model?: string;
+}
+/**
+ * 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.
+ */
+type LivdLookup = 
+/** Exactly one LOINC (one entry, or several entries that all agree on the same LOINC). */
+{
+    readonly status: "mapped";
+    readonly loinc: string;
+    readonly loincLongName?: string;
+}
+/** 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. */
+ | {
+    readonly status: "ambiguous";
+    readonly candidates: readonly string[];
+};
+/**
+ * An immutable, consumer-supplied LIVD catalog. Look a vendor code up with
+ * {@link LivdCatalog.lookup}; the catalog **never** picks between conflicting
+ * LOINCs and **never** mutates. Build one with {@link defineLivdCatalog}.
+ */
+interface LivdCatalog {
+    /** The number of distinct vendor codes indexed (not the number of input rows). */
+    readonly size: number;
+    /**
+     * 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.
+     *
+     * @param vendorCode - The reported vendor/local test code.
+     * @returns The lookup outcome.
+     */
+    lookup(vendorCode: string): LivdLookup;
+}
+/**
+ * Build a {@link LivdCatalog} from LIVD entries a consumer supplies. Entries are
+ * indexed by their `vendorCode` (verbatim). When several entries share a vendor
+ * 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.
+ *
+ * The returned catalog is deeply frozen; nothing is mutated after construction.
+ *
+ * @param entries - The consumer's LIVD mapping rows.
+ * @returns An immutable catalog.
+ * @example
+ * ```ts
+ * import { defineLivdCatalog } from "@cosyte/astm";
+ * const catalog = defineLivdCatalog([
+ *   { vendorCode: "687", loinc: "1920-8", loincLongName: "AST" },
+ *   { vendorCode: "690", loinc: "1742-6", loincLongName: "ALT" },
+ * ]);
+ * 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 Phase-9
+ * 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" });
+ * ```
+ */
+declare function livdAmbiguousMapping(position: AstmPosition): AstmLivdWarning;
+
+/**
+ * The **additive, advisory** LIVD annotation layer (Phase 9). {@link applyLivd}
+ * reads a parsed {@link AstmMessage} and a consumer-supplied {@link LivdCatalog}
+ * and returns a **separate** layer of per-record LOINC annotations — it **never
+ * mutates, alters, or drops** the raw reported code or value. Recognition is an
+ * 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.
+ */
+
+/**
+ * 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.
+ *
+ * - `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.
+ * - `ambiguous` — a vendor/local code matching more than one distinct LOINC; the
+ *   candidates are surfaced but **none is chosen**.
+ * - `no-code` — the record carried no usable test code at all (name-only/empty), so
+ *   there was nothing to map.
+ */
+type LivdMapping = {
+    readonly status: "mapped";
+    readonly loinc: string;
+    readonly loincLongName?: string;
+    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[];
+} | {
+    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.
+ *
+ * @example
+ * ```ts
+ * import type { LivdAnnotation } from "@cosyte/astm";
+ * const a: LivdAnnotation = {
+ *   recordIndex: 3,
+ *   recordType: "R",
+ *   reportedCode: "687",
+ *   provenance: "local-code",
+ *   mapping: { status: "mapped", loinc: "1920-8", source: "livd", derived: true },
+ * };
+ * ```
+ */
+interface LivdAnnotation {
+    /** The `recordIndex` of the annotated `R`/`O` record. */
+    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. */
+    readonly reportedCode?: string;
+    /** How the reported code was recognized in the Universal Test ID (provenance only, never a lookup). */
+    readonly provenance: UniversalTestIdProvenance;
+    /** The mapping outcome — never a guessed LOINC. */
+    readonly mapping: LivdMapping;
+}
+/**
+ * The result of {@link applyLivd}: the per-record annotations (one per `R`/`O`
+ * record) and the value-free warnings for every unmapped or ambiguous code. Both
+ * arrays are deeply frozen; the source message is untouched.
+ */
+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`. */
+    readonly warnings: readonly AstmLivdWarning[];
+}
+/**
+ * Annotate one `R` or `O` record against a LIVD catalog. The building block of
+ * {@link applyLivd}; useful when a consumer holds a single record. Never mutates
+ * the record and never fabricates a LOINC.
+ *
+ * @param record - The result/order record to annotate.
+ * @param catalog - The consumer-supplied LIVD catalog.
+ * @returns The record's annotation.
+ * @example
+ * ```ts
+ * import { parseAstmRecords, results, defineLivdCatalog, lookupLivdForRecord } from "@cosyte/astm";
+ * const msg = parseAstmRecords("H|\\^&\rR|1|^^^687|28.6|U/L||N||F\rL|1\r");
+ * const catalog = defineLivdCatalog([{ vendorCode: "687", loinc: "1920-8" }]);
+ * lookupLivdForRecord(results(msg)[0]!, catalog).mapping.status; // "mapped"
+ * ```
+ */
+declare function lookupLivdForRecord(record: ResultRecord | OrderRecord, catalog: LivdCatalog): LivdAnnotation;
+/**
+ * Apply a consumer-supplied LIVD catalog to a parsed message, producing an
+ * **additive, advisory** layer of LOINC annotations over its `R` (result) and `O`
+ * (order) records. The source message is never mutated; the raw reported codes and
+ * values stay exactly as parsed.
+ *
+ * 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).
+ *
+ * @param msg - A parsed ASTM message.
+ * @param catalog - The consumer-supplied LIVD catalog (build with {@link defineLivdCatalog}).
+ * @returns The annotations and value-free warnings (deeply frozen).
+ * @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 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 }
+ * ```
+ */
+declare function applyLivd(msg: AstmMessage, catalog: LivdCatalog): LivdResult;
+
+/**
+ * The frame-codec value model produced by {@link decodeAstmFrames}.
+ *
+ * The codec decodes a framed byte stream into a list of {@link AstmFrame}s (every
+ * frame surfaced, trusted or not) plus the **reassembled record bytes** of the
+ * frames that were trusted and contiguous. Nothing is invented: a frame whose
+ * checksum fails, or that arrives out of sequence, or that never terminates, is
+ * surfaced and flagged but is **never merged** into the clean `records` output.
+ */
+
+/** Which terminator closed a frame: `ETB` (record continues) or `ETX` (record complete). */
+type FrameTerminator = "ETB" | "ETX";
+/**
+ * A frame's checksum verdict: the modulo-256 value recomputed from the frame's
+ * bytes, the value declared on the wire (or `undefined` when it was unreadable),
+ * and whether they matched.
+ */
+interface FrameChecksum {
+    /** The modulo-256 checksum recomputed over the frame (frame number through terminator). */
+    readonly computed: number;
+    /**
+     * The checksum declared on the wire (the two hex chars after the terminator), read
+     * case-insensitively; `undefined` when those bytes were missing or not hex.
+     */
+    readonly declared?: number;
+    /** `true` only when a declared checksum was present **and** equal to `computed`. */
+    readonly valid: boolean;
+}
+/**
+ * One decoded ASTM frame. `text` is the frame's record-byte payload (the bytes
+ * between the frame number and the terminator, escapes untouched — this is the
+ * framing layer, not the record layer). `trusted` is the single flag a consumer
+ * gates on: it is `true` only for a fully-terminated frame whose checksum
+ * validated, and such frames are the only ones reassembled into `records`.
+ */
+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
+     * corruption that also trips a sequence-gap warning). `undefined` when the frame
+     * was too truncated to carry a frame number at all.
+     */
+    readonly frameNumber?: number;
+    /** `ETB` (intermediate) or `ETX` (final); `undefined` for an unterminated frame. */
+    readonly terminator?: FrameTerminator;
+    /** The frame's record-byte payload (may be empty). A **copy**, safe for the caller to retain. */
+    readonly text: Uint8Array;
+    /** Byte offset of the `STX` that opened this frame, within the decoded stream. */
+    readonly byteOffset: number;
+    /** The checksum verdict. */
+    readonly checksum: FrameChecksum;
+    /**
+     * `true` only when the frame was fully terminated **and** its checksum validated.
+     * Only trusted frames are reassembled into {@link DecodeAstmFramesResult.records};
+     * an untrusted frame is surfaced here but never merged.
+     */
+    readonly trusted: boolean;
+    /** `true` when no valid terminator + checksum was found for this frame (a truncated/partial frame). */
+    readonly unterminated: boolean;
+    /** `true` when the frame's record text exceeded the 240-byte limit. */
+    readonly oversize: boolean;
+}
+/**
+ * The result of {@link decodeAstmFrames}: the reassembled record bytes, every
+ * decoded frame, and the accumulated frame warnings.
+ */
+interface DecodeAstmFramesResult {
+    /**
+     * The reassembled record byte-strings — one entry per complete record (a run of
+     * frames closed by an `ETX`), in wire order. **Only** clean reassemblies appear:
+     * a record whose frames included a bad checksum, a sequence gap, or an
+     * unterminated frame is **omitted** (its frames are still in {@link DecodeAstmFramesResult.frames},
+     * flagged). Each entry is ready to hand to `parseAstmRecords`.
+     */
+    readonly records: readonly Uint8Array[];
+    /** Every decoded frame, trusted or not, in wire order. */
+    readonly frames: readonly AstmFrame[];
+    /** The frame warnings accumulated during a lenient decode (empty in a clean decode). */
+    readonly warnings: readonly AstmFrameWarning[];
+}
+/**
+ * Options for {@link decodeAstmFrames}. Lenient by default (Postel's Law).
+ */
+interface FrameOptions {
+    /**
+     * When `true`, escalate any tolerated frame deviation (bad checksum, sequence
+     * gap, unterminated, oversize) to a thrown {@link AstmFrameStrictError} instead
+     * of accumulating a warning. Off by default.
+     */
+    readonly strict?: boolean;
+}
+
+/**
+ * The value model for the pure LTP protocol reducer ({@link ltpReduce}).
+ *
+ * The reducer models the **receiver** side of an ASTM/CLSI-LIS01 (LIS01-A2)
+ * session — the host/LIS receiving an upload — because that is where the one
+ * safety decision lives: whether to `ACK` (accept) or `NAK` (reject) a frame that
+ * just arrived. It is a **pure function** of the current {@link LtpState} and one
+ * inbound {@link LtpEvent}, returning an {@link LtpTransition} (the next state plus
+ * the actions the consumer should take and any warnings). No sockets, no timers,
+ * no I/O — the consumer owns the wire and the clock; the reducer owns the logic.
+ */
+
+/**
+ * The protocol phase. The line is either **neutral** (idle — awaiting an `ENQ` to
+ * establish, or reset there after an `EOT`) or in **transfer** (establishment
+ * accepted; frames and their per-frame `ACK`/`NAK` flow until the sender's `EOT`).
+ * The classic three-phase LIS01 model (establishment → transfer → termination)
+ * collapses to these two, since establishment is the `neutral → transfer` edge and
+ * termination is the `transfer → neutral` edge.
+ */
+type LtpPhase = "neutral" | "transfer";
+/**
+ * The reducer's immutable session state. Every {@link ltpReduce} call returns a new,
+ * frozen `LtpState`; the previous one is never mutated.
+ */
+interface LtpState {
+    /** The current protocol phase. */
+    readonly phase: LtpPhase;
+    /**
+     * The next frame number the receiver expects (`1 → … → 7 → 0 → …`), meaningful in
+     * `transfer`. A trusted frame carrying this number is accepted and appended; any
+     * other number is a duplicate retransmit (idempotent re-`ACK`) or an out-of-sequence
+     * frame (rejected with `NAK`), never silently bridged.
+     */
+    readonly expectedFrame: number;
+    /**
+     * The frame number of the last frame accepted into the current record, used to
+     * recognise a duplicate retransmit; `undefined` before the first frame of a
+     * transfer is accepted.
+     */
+    readonly lastAcceptedFrame?: number;
+    /**
+     * The reassembled bytes of every **complete** record delivered so far in the
+     * session (each closed by an `ETX` frame with a clean run). Concatenate these and
+     * hand them to `parseAstmRecords` to get the message. Only trusted, in-sequence
+     * frames contribute; a rejected or partial record never appears.
+     */
+    readonly records: readonly Uint8Array[];
+    /** `true` when a record is mid-reassembly (an `ETB` frame was accepted, awaiting its `ETX`). */
+    readonly recordOpen: boolean;
+    /**
+     * The bytes accumulated so far for the in-progress record — the concatenation of
+     * the `ETB` frames accepted since the last `ETX`. Empty when no record is open.
+     * These bytes are **never** delivered on their own: only an `ETX` completes a
+     * record, at which point they (plus the final frame's text) become one entry in
+     * {@link LtpState.records}. An `EOT` or an `ENQ` restart discards them unread.
+     */
+    readonly openRecord: Uint8Array;
+}
+/**
+ * An inbound protocol event the consumer feeds the reducer: one of the four LTP
+ * control signals (`ENQ`/`ACK`/`NAK`/`EOT`) read off the wire, or a `frame` the
+ * consumer already decoded with `decodeAstmFrames` (the reducer reuses the codec's
+ * `trusted`/`checksum` verdict — it never re-derives it).
+ */
+type LtpEvent = {
+    readonly type: "enq";
+} | {
+    readonly type: "ack";
+} | {
+    readonly type: "nak";
+} | {
+    readonly type: "eot";
+} | {
+    readonly type: "frame";
+    readonly frame: AstmFrame;
+};
+/**
+ * An action the reducer tells the consumer to take. The consumer performs the I/O
+ * (write the byte to the socket, hand the record to the parser); the reducer only
+ * decides. `sendAck`/`sendNak`/`sendEot` are single control bytes; `deliverRecord`
+ * carries the freshly-completed record's reassembled bytes.
+ */
+type LtpAction = {
+    readonly type: "sendAck";
+} | {
+    readonly type: "sendNak";
+} | {
+    readonly type: "sendEot";
+} | {
+    readonly type: "deliverRecord";
+    readonly record: Uint8Array;
+};
+/**
+ * The result of one {@link ltpReduce} step: the next {@link LtpState}, the
+ * {@link LtpAction}s to perform (in order), and any {@link AstmLtpWarning}s raised.
+ */
+interface LtpTransition {
+    /** The next session state (frozen). */
+    readonly state: LtpState;
+    /** The actions the consumer should take, in order. */
+    readonly actions: readonly LtpAction[];
+    /** Warnings raised by this step (empty on a clean, expected event). */
+    readonly warnings: readonly AstmLtpWarning[];
+}
+
+/**
+ * The pure LTP protocol reducer: {@link ltpReduce} and {@link ltpInitialState}.
+ *
+ * A deterministic, socket-free receiver-side state machine for ASTM/CLSI-LIS01
+ * (LIS01-A2). The consumer owns the wire — it reads bytes, decodes frames with
+ * `decodeAstmFrames`, and drives this reducer one {@link LtpEvent} at a time — and
+ * the reducer decides, purely, what happens next: whether to `ACK` or `NAK`, when a
+ * record is complete, and when the session returns to neutral.
+ *
+ * **The one inviolable rule (borrowed from `mllp`'s ACK-failsafe discipline):** a
+ * frame the codec did not vouch for — a bad checksum, an unterminated frame, or one
+ * out of sequence — is answered with `NAK`, **never** a fabricated positive `ACK`,
+ * and its bytes are **never** appended to a record or delivered. A `NAK` drives
+ * retransmit, not acceptance. This is the protocol-level twin of the frame codec's
+ * "a bad-checksum frame is never merged into a record."
+ */
+
+/**
+ * The neutral starting state for a fresh session: line idle, no record in flight,
+ * nothing delivered yet. A consumer creates one of these when a connection opens
+ * and folds inbound events through {@link ltpReduce} from here.
+ *
+ * @returns A frozen neutral {@link LtpState}.
+ * @example
+ * ```ts
+ * import { ltpInitialState, ltpReduce } from "@cosyte/astm";
+ * let state = ltpInitialState();
+ * const step = ltpReduce(state, { type: "enq" });
+ * step.actions; // [{ type: "sendAck" }]
+ * state = step.state;
+ * ```
+ */
+declare function ltpInitialState(): LtpState;
+/**
+ * Advance the LTP session by one inbound event — a pure function, no I/O.
+ *
+ * Behaviour by phase:
+ * - **neutral** — `enq` accepts establishment (`sendAck`, enter transfer); `eot` is
+ *   a benign line reset (no-op); `ack`/`nak` are unexpected at a receiver (surfaced,
+ *   never read as acceptance); a `frame` before establishment is tolerated
+ *   (Postel's Law) — the session auto-establishes and processes it, with a warning.
+ * - **transfer** — a `frame` is accepted (`sendAck`, appended, sequence advanced) only
+ *   when it is trusted *and* carries the expected number; a duplicate of the last
+ *   accepted frame is idempotently re-`ACK`ed without re-appending; a bad or
+ *   out-of-sequence frame is `NAK`ed and dropped. `eot` terminates the transfer and
+ *   returns to neutral (a record left open on an `ETB` is **not** delivered). `enq`
+ *   restarts establishment. `ack`/`nak` are unexpected.
+ *
+ * @param state - The current session state.
+ * @param event - The inbound event.
+ * @returns The next state, the actions to take, and any warnings.
+ * @example
+ * ```ts
+ * import { ltpInitialState, ltpReduce } from "@cosyte/astm";
+ * // A bad-checksum frame is NAKed, never ACKed, and never appended.
+ * const est = ltpReduce(ltpInitialState(), { type: "enq" }).state;
+ * const bad = { trusted: false } as never;
+ * ltpReduce(est, { type: "frame", frame: bad }).actions; // [{ type: "sendNak" }]
+ * ```
+ */
+declare function ltpReduce(state: LtpState, event: LtpEvent): LtpTransition;
+
+/**
+ * The four LTP (low-level transfer protocol) control bytes for ASTM/CLSI-LIS01
+ * (was E1381), plus the bare-record-letter set the transport detector keys on.
+ *
+ * The frame codec (`../frames`) owns the *inside* of a frame (`STX FN text
+ * ETB/ETX CS CRLF`); this module owns the *handshake around* frames — the
+ * establishment/transfer/termination signalling that the {@link ltpReduce}
+ * reducer consumes. These are the raw byte values; the reducer and the transport
+ * detector are the only consumers.
+ */
+/** Enquiry (`0x05`) — the sender's request to establish a transfer. */
+declare const ENQ = 5;
+/** Acknowledge (`0x06`) — the receiver accepted the last establishment or frame. */
+declare const ACK = 6;
+/** Negative acknowledge (`0x15`) — the receiver rejected the last frame; retransmit, do not accept. */
+declare const NAK = 21;
+/** End of transmission (`0x04`) — the sender terminated the transfer; the line returns to neutral. */
+declare const EOT = 4;
+
+/**
+ * The frame-layer entry point: {@link decodeAstmFrames}.
+ *
+ * Decode a framed ASTM/CLSI-LIS01 byte stream (`<STX> FN text <ETB|ETX> CS <CR>
+ * <LF>` frames) into a list of frames plus the reassembled record bytes of the
+ * frames that were trusted and contiguous. Lenient by default: byte-level
+ * deviations become {@link AstmFrameWarning}s, and the only fatal is the shared
+ * `EMPTY_INPUT` (an empty stream). The two safety-critical rules are absolute in
+ * **both** modes: a bad-checksum frame is surfaced flagged untrusted and **never**
+ * merged into a record, and a sequence gap is **never** silently bridged.
+ *
+ * This is the framing layer only — it does not parse record grammar. Hand a
+ * reassembled record to `parseAstmRecords`, or use `parseFramedAstm` to compose
+ * both layers at the edge.
+ */
+
+/**
+ * Decode a framed ASTM byte stream into frames + reassembled record bytes.
+ *
+ * Bytes outside a frame (before the first `STX`, or between a frame's trailing
+ * `LF` and the next `STX`) are skipped: in ASTM they are low-level transfer
+ * control (`ENQ`/`ACK`/`NAK`/`EOT` — the Phase 6 protocol layer), never record
+ * content, so skipping them is not data loss.
+ *
+ * @param bytes - The framed byte stream.
+ * @param options - Decode options; lenient unless `strict` is set.
+ * @returns The decoded frames, the reassembled trusted record bytes, and any warnings.
+ * @throws {@link AstmParseError} with `EMPTY_INPUT` when `bytes` is empty (both modes).
+ * @throws {@link AstmFrameStrictError} when `strict` is set and any deviation occurred.
+ * @example
+ * ```ts
+ * import { decodeAstmFrames } from "@cosyte/astm";
+ * // One final frame carrying the record text "R|1|" — checksum "AF" over FN..ETX (mod 256).
+ * const bytes = new Uint8Array([0x02, 0x31, 0x52, 0x7c, 0x31, 0x7c, 0x03, 0x41, 0x46, 0x0d, 0x0a]);
+ * const { records, frames } = decodeAstmFrames(bytes);
+ * frames[0]?.frameNumber; // 1
+ * records.length;         // 1
+ * ```
+ */
+declare function decodeAstmFrames(bytes: Uint8Array, options?: FrameOptions): DecodeAstmFramesResult;
+
+/**
+ * The frame-layer **emit** side: {@link composeAstmFrames} — Phase 7.
+ *
+ * The exact inverse of {@link decodeAstmFrames}. Given the reassembled record
+ * byte-strings (one entry per complete record — the same shape `decodeAstmFrames`
+ * *produces*), it wraps each into one or more `<STX> FN text <ETB|ETX> CS <CR><LF>`
+ * frames, so `decodeAstmFrames(composeAstmFrames(records)).records` reproduces the
+ * input records exactly.
+ *
+ * Everything structural is **computed, never accepted-as-given**:
+ * - 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`,
+ *   continuous across every frame in the stream (as the decoder's sequence check
+ *   expects);
+ * - the **240-byte text split** — a record longer than 240 bytes is split across
+ *   frames closed by `ETB` (intermediate) with a final `ETX`; the seven framing
+ *   control bytes are never counted toward the 240.
+ *
+ * A record must carry bytes: an empty record (or an empty record list) is a typed
+ * {@link AstmFrameEncodeError}, never an empty frame.
+ */
+/**
+ * Thrown by {@link composeAstmFrames} when the input cannot be framed into a
+ * spec-clean stream — an empty record list, or a record with no bytes (a frame
+ * must carry a record; an empty one is a structural error, never an empty frame).
+ * Carries a stable code + the offending record index, never record bytes.
+ *
+ * @example
+ * ```ts
+ * import { composeAstmFrames, AstmFrameEncodeError } from "@cosyte/astm";
+ * try {
+ *   composeAstmFrames([]);
+ * } catch (err) {
+ *   if (err instanceof AstmFrameEncodeError) err.code; // "ASTM_FRAME_EMPTY_RECORD"
+ * }
+ * ```
+ */
+declare class AstmFrameEncodeError extends Error {
+    /** Stable discriminant. */
+    readonly code: "ASTM_FRAME_EMPTY_RECORD";
+    /** Index of the offending record within the input, when applicable. */
+    readonly recordIndex?: number;
+    /** @internal */
+    constructor(message: string, recordIndex?: number);
+}
+/** Options for {@link composeAstmFrames}. */
+interface ComposeFramesOptions {
+    /**
+     * The frame number to start the sequence at (`0`–`7`). Defaults to
+     * {@link FIRST_FRAME_NUMBER} (`1`) — the ASTM convention.
+     */
+    readonly startFrameNumber?: number;
+}
+/**
+ * Frame reassembled record bytes into a spec-clean ASTM/CLSI-LIS01 byte stream —
+ * the inverse of {@link decodeAstmFrames}.
+ *
+ * Each record is split at 240 text bytes into `ETB`-closed intermediate frames
+ * and a final `ETX` frame; frame numbers run `1, 2, … 7, 0, 1 …` continuously
+ * across the whole stream; every frame's modulo-256 checksum is computed and
+ * emitted uppercase.
+ *
+ * @param records - The reassembled record byte-strings (`Uint8Array` or latin1
+ *   `string`), one entry per complete record.
+ * @param options - Encode options.
+ * @returns The framed byte stream.
+ * @throws {@link AstmFrameEncodeError} when the list is empty or a record has no bytes.
+ * @example
+ * ```ts
+ * import { composeAstmFrames, decodeAstmFrames } from "@cosyte/astm";
+ * const records = [new TextEncoder().encode("H|\\^&\r"), new TextEncoder().encode("L|1\r")];
+ * const bytes = composeAstmFrames(records);
+ * decodeAstmFrames(bytes).records.length; // 2
+ * ```
+ */
+declare function composeAstmFrames(records: readonly (Uint8Array | string)[], options?: ComposeFramesOptions): Uint8Array;
+
+/**
+ * Composing the two layers at the edge: {@link parseFramedAstm}.
+ *
+ * The framing layer ({@link decodeAstmFrames}) and the record layer
+ * (`parseAstmRecords`) share nothing but the payload boundary — a frame carries
+ * record bytes; a record knows nothing about frames. This helper joins them at the
+ * one point they meet: decode a framed stream into trusted, reassembled record
+ * bytes, then parse those bytes into an {@link AstmMessage}. It is deliberately
+ * thin — a consumer that already holds de-framed record bytes calls
+ * `parseAstmRecords` directly, and a consumer that only wants frames calls
+ * `decodeAstmFrames` directly.
+ */
+
+/**
+ * The result of {@link parseFramedAstm}: the parsed message, plus the frame-layer
+ * detail (every decoded frame and the frame warnings) so a consumer keeps full
+ * visibility into the transport below the records.
+ */
+interface FramedAstmResult {
+    /** The message parsed from the trusted, reassembled record bytes. */
+    readonly message: AstmMessage;
+    /** Every decoded frame, trusted or not, in wire order. */
+    readonly frames: readonly AstmFrame[];
+    /** The frame-layer warnings (bad checksum, sequence gap, unterminated, oversize). */
+    readonly frameWarnings: readonly AstmFrameWarning[];
+}
+/**
+ * Decode a framed ASTM byte stream and parse its reassembled records in one call.
+ *
+ * Only **trusted, contiguous** frames are reassembled (a bad-checksum frame, a
+ * sequence gap, or an unterminated frame is surfaced in `frames`/`frameWarnings`
+ * but never fed to the record parser), so the parsed `message` reflects only bytes
+ * the framing layer vouched for.
+ *
+ * @param bytes - The framed byte stream.
+ * @param options - Frame decode options **and** record parse options (both layers
+ *   honor a shared `strict`).
+ * @returns The parsed message plus the frame-layer detail.
+ * @throws {@link AstmParseError} `EMPTY_INPUT` when the stream is empty, or when no
+ *   trusted records could be reassembled (nothing to parse).
+ * @throws {@link AstmFrameStrictError} / {@link AstmStrictError} in `strict` mode on
+ *   a frame or record deviation, respectively.
+ * @example
+ * ```ts
+ * import { parseFramedAstm } from "@cosyte/astm";
+ * // A single final frame carrying "H|\^&\r" — checksum "E5" over FN..ETX (mod 256).
+ * const bytes = new Uint8Array([
+ *   0x02, 0x31, 0x48, 0x7c, 0x5c, 0x5e, 0x26, 0x0d, 0x03, 0x45, 0x35, 0x0d, 0x0a,
+ * ]);
+ * const { message, frames } = parseFramedAstm(bytes);
+ * message.header.delimiters.field; // "|"
+ * frames.length;                   // 1
+ * ```
+ */
+declare function parseFramedAstm(bytes: Uint8Array, options?: FrameOptions & AstmParseOptions): FramedAstmResult;
+/**
+ * Serialize an ASTM message (or a bare record list) and frame it into a spec-clean
+ * byte stream in one call — the inverse of {@link parseFramedAstm}, composing the
+ * two emit layers at the edge.
+ *
+ * Each record is serialized to spec-clean, `CR`-terminated wire text (canonical
+ * delimiters, embedded delimiters re-escaped) and then framed **independently**
+ * (one record per `ETX`-closed frame run), so the framing exactly mirrors what
+ * {@link decodeAstmFrames} reassembles: `parseFramedAstm(serializeFramedAstm(msg))`
+ * yields an equal message.
+ *
+ * @param input - A parsed {@link AstmMessage} or a list of {@link AstmRecord}s.
+ * @param options - Frame-encode options.
+ * @returns The framed byte stream.
+ * @throws {@link AstmSerializeError} when a value contains an unencodable `CR`/`LF`.
+ * @throws {@link AstmFrameEncodeError} when there are no records to frame.
+ * @example
+ * ```ts
+ * import { parseAstmRecords, serializeFramedAstm, parseFramedAstm } from "@cosyte/astm";
+ * const msg = parseAstmRecords("H|\\^&\rR|1|^^^687|28.6|U/L||N||F\rL|1\r");
+ * const bytes = serializeFramedAstm(msg);
+ * parseFramedAstm(bytes).message.records.length; // 3
+ * ```
+ */
+declare function serializeFramedAstm(input: AstmMessage | readonly AstmRecord[], options?: ComposeFramesOptions): Uint8Array;
+
+/**
+ * The ASTM/CLSI-LIS01 modulo-256 frame checksum.
+ *
+ * The checksum is the sum, modulo 256, of every byte **after** the `STX` up to
+ * and **including** the `ETB`/`ETX` terminator — i.e. the frame number, the record
+ * text, and the terminator byte. It is carried on the wire as **two hexadecimal
+ * characters**. This module computes it (`computeChecksum`), formats it for emit
+ * (`toChecksumHex` — always **uppercase**), and reads it back leniently
+ * (`parseChecksumHex` — **accepts lowercase**), matching the real-vendor quirk that
+ * some analyzers emit a lowercase checksum.
+ */
+/**
+ * Sum bytes `[start, endInclusive]` of `bytes` modulo 256 — the ASTM frame
+ * checksum span (frame number through the terminator, inclusive).
+ *
+ * @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`.
+ * @example
+ * ```ts
+ * import { computeChecksum } from "@cosyte/astm";
+ * // bytes: STX '1' 'A' ETX  →  sum '1' + 'A' + ETX, mod 256.
+ * computeChecksum(new Uint8Array([0x02, 0x31, 0x41, 0x03]), 1, 3); // 0x75
+ * ```
+ */
+declare function computeChecksum(bytes: Uint8Array, start: number, endInclusive: number): number;
+/**
+ * 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`.
+ * @returns Two uppercase hex characters, zero-padded (e.g. `"0A"`, `"75"`).
+ * @example
+ * ```ts
+ * import { toChecksumHex } from "@cosyte/astm";
+ * toChecksumHex(0x0a); // "0A"
+ * ```
+ */
+declare function toChecksumHex(checksum: number): string;
+/**
+ * Read the two-hex-char checksum at `bytes[i0]`/`bytes[i1]`, **case-insensitively**
+ * (a lowercase checksum is a tolerated real-vendor quirk). Returns `undefined` when
+ * either position is out of range or not a hex digit — the caller then treats the
+ * frame as having no readable declared checksum, never as a match.
+ *
+ * @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.
+ * @example
+ * ```ts
+ * import { parseChecksumHex } from "@cosyte/astm";
+ * parseChecksumHex(new Uint8Array([0x37, 0x35]), 0, 1); // 0x75 ("75")
+ * parseChecksumHex(new Uint8Array([0x37, 0x35]), 5, 6); // undefined (out of range)
+ * ```
+ */
+declare function parseChecksumHex(bytes: Uint8Array, i0: number, i1: number): number | undefined;
+
+/**
+ * The frame codec's thrown error — the `strict`-mode counterpart to its lenient
+ * warnings.
+ *
+ * The frame layer is lenient by default (byte-level deviations become
+ * {@link AstmFrameWarning}s), and shares the single {@link FATAL_CODES.EMPTY_INPUT}
+ * fatal with the record layer (thrown as an {@link AstmParseError} on an empty
+ * stream, in both modes). In `strict` mode every tolerated deviation is rejected
+ * instead: {@link decodeAstmFrames} throws {@link AstmFrameStrictError} carrying the
+ * warnings it would otherwise have accumulated (code + position, never a value).
+ */
+
+/**
+ * Thrown by {@link decodeAstmFrames} in `strict` mode when the lenient codec would
+ * otherwise have accumulated one or more frame warnings (a bad checksum, a
+ * sequence gap, an unterminated frame, or an oversize frame). Carries every
+ * warning (code + position, never the frame's record bytes) so a caller can see
+ * each deviation.
+ *
+ * @example
+ * ```ts
+ * import { decodeAstmFrames, AstmFrameStrictError } from "@cosyte/astm";
+ * try {
+ *   decodeAstmFrames(someFramedBytes, { strict: true });
+ * } catch (err) {
+ *   if (err instanceof AstmFrameStrictError) err.warnings.length; // >= 1
+ * }
+ * ```
+ */
+declare class AstmFrameStrictError extends Error {
+    readonly warnings: readonly AstmFrameWarning[];
+    /** @internal */
+    constructor(warnings: readonly AstmFrameWarning[]);
+}
+
+/**
+ * Public entry point for the `@cosyte/astm` package — the ASTM/CLSI-LIS02
+ * **record** layer.
+ *
+ * The north star: hand a de-framed ASTM record stream to {@link parseAstmRecords}
+ * and pull a result's value, units, and flag out in one line — lenient on parse
+ * (vendor quirks become typed warnings, never silent loss), and — the whole point
+ * — **never a confident wrong value**. Delimiters are read from each header,
+ * embedded escapes are decoded before a value is split, the practice- and
+ * laboratory-assigned patient IDs stay distinct, and every deviation is a stable,
+ * value-free warning. Result flag/status semantics (P2), patient/order identity
+ * depth + the `C` comment record + partial-timestamp hardening (P3), and the
+ * request-information (`Q`) record + host-query classification + verbatim `M`/`S`
+ * records (P4) are all modeled — the **record-content layer is now feature-complete**.
+ *
+ * The E1381/CLSI-LIS01 **framing** layer (P5) lives alongside the record layer and
+ * shares nothing but the payload boundary: {@link decodeAstmFrames} decodes a framed
+ * byte stream (`<STX> FN text <ETB|ETX> CS <CR><LF>`) into frames + reassembled
+ * record bytes — verifying the modulo-256 checksum (a bad frame is surfaced
+ * untrusted, never merged), tracking frame-number sequencing (a gap is never
+ * silently bridged), and reassembling the 240-byte-limited multi-frame records.
+ * {@link parseFramedAstm} composes the two layers at the edge.
+ *
+ * The LTP **protocol** layer (P6) sits above the frame codec: {@link detectFraming}
+ * auto-detects the transport reality — framed (serial / cobas 4800 / Iguana) vs raw
+ * (cobas b121, framing dropped) — from the stream's leading byte, and
+ * {@link ltpReduce} is a **pure, socket-free** receiver-side state machine over
+ * `ENQ`/`ACK`/`NAK`/`EOT` + frame-received events. The consumer owns the wire; the
+ * reducer decides. Its inviolable rule mirrors `mllp`'s ACK-failsafe: a frame the
+ * codec did not vouch for is answered with `NAK`, **never** a fabricated positive
+ * `ACK`, and never merged into a record — a `NAK` drives retransmit, not acceptance.
+ * Serialize/build (P7) is deferred.
+ */
+/**
+ * Library version string, synced with `package.json#version` at build time.
+ *
+ * @example
+ * ```ts
+ * import { VERSION } from "@cosyte/astm";
+ * console.log(VERSION);
+ * ```
+ */
+declare const VERSION = "0.0.0";
+
+export { ALL_ASTM_WARNING_CODES, ACK as ASTM_ACK, ENQ as ASTM_ENQ, EOT as ASTM_EOT, NAK as ASTM_NAK, type AbnormalFlag, type AbnormalFlagCode, type AbnormalFlagMeaning, type AnyAstmWarningCode, type AstmDate, type AstmDatePrecision, type AstmField, type AstmFrame, AstmFrameEncodeError, 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, AstmStrictError, CANONICAL_DELIMITERS, type CommentInput, type CommentRecord, type ComposeFramesOptions, type DecodeAstmFramesResult, type DefineAstmProfileOptions, 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, TOLERABLE_CODES, type TerminatorRecord, type UniversalTestId, type UniversalTestIdProvenance, type UnknownEscapeSink, type UnsupportedRecord, VERSION, type VerbatimInput, WARNING_CODES, type WarningCode, ambiguousMessageKind, ambiguousValueSplit, applyAstmProfile, applyAstmProfileToWarnings, applyLivd, astmDateToLocalISO, astmProfiles, attachComments, buildAstmMessage, classifyMessage, comments, commentsFor, composeAstmFrames, computeChecksum, decodeAstmFrames, decodeEscapes, deepFreeze, defineAstmProfile, defineLivdCatalog, detectFraming, encodeComponent, fieldScalar, frameBadChecksum, frameOversize, frameSequenceGap, frameUnterminated, getAstmProfile, getDefaultAstmProfile, interpretAbnormalFlag, interpretResultStatus, isNonStandard, isSafetyCriticalCode, listAstmProfiles, livdAmbiguousMapping, livdUnmappedCode, lookupLivdForRecord, ltpAmbiguousTransport, ltpFrameRejected, ltpInitialState, ltpReduce, ltpUnexpectedEvent, nonStandardDelimiters, orders, orphanComment, parseAstmDate, parseAstmRecords, parseChecksumHex, parseFramedAstm, parseReferenceRange, partialTimestamp, patient, primaryCode, profileQuirkApplied, query, readDelimiters, recognizeUniversalTestId, resolveProfileTransport, results, serializeAstmRecord, serializeAstmRecords, serializeField, serializeFramedAstm, setDefaultAstmProfile, splitEscapeAware, toChecksumHex, tokenizeRecord, undefinedAbnormalFlag, undefinedResultStatus, uninterpretedQueryStatus, unitsAbsent, unknownEscapeSequence, unknownRecordType, unparseableReferenceRange };