@cosyte/astm 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,358 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+Versions and publishing are managed with [Changesets](https://github.com/changesets/changesets);
+this file is maintained by hand (Changesets handles the version bump and publish only).
+
+## [Unreleased]
+
+The first pre-alpha release (`0.0.1`) will ship the initial public API surface. The package begins
+its public history at `0.0.x`, per the cosyte version ladder (`0.0.x` until first alpha).
+
+### Added
+
+- Project scaffold from the shared `@cosyte/*` parser template: the canonical toolchain (TypeScript
+  ES2023 + strict rigor via `@cosyte/tsconfig`, ESLint 10 + type-checked `typescript-eslint` via
+  `@cosyte/eslint-config`, Prettier via `@cosyte/prettier-config`, Vitest 4 + v8 coverage via
+  `@cosyte/vitest-config`, dual ESM + CJS build via `tsup` + `@cosyte/tsup-config`, `attw` publish
+  gate), thin callers of the reusable `cosyte/.github` CI/release workflows, Changesets on the
+  `0.0.x` ladder, and the property-based conformance harness from `@cosyte/test-utils`.
+- **Record foundation (ASTM-1, roadmap Phase 1).** The record-content layer: parse an ASTM/CLSI-LIS02
+  record stream and pull result value + units + flag in one line.
+  - `parseAstmRecords(raw, opts?)` → an immutable, deeply-frozen `AstmMessage`; `results(msg)` /
+    `patient(msg)` typed extractors.
+  - **Delimiter self-declaration** — the four delimiters (field / repeat / component / escape) are
+    read from each `H` record, never hardcoded, with ASTM's `\`=repeat and `&`=escape mapping.
+  - **Escape codec** — `&F&`/`&S&`/`&R&`/`&E&` are decoded via escape-aware split-then-decode, so a
+    value containing an escaped component delimiter reads as **one** component (the documented
+    silent-misread class the OSS references exhibit). Re-escaping is deferred to the emit phase (P7).
+  - Modeled records: `H` (delimiter provenance), `P` (identity — practice-assigned ID and
+    laboratory-assigned ID kept **distinct**), `O` (accession + Universal Test ID), `R` (all 14
+    fields; value / units / flags / status surfaced **raw**), `L`. Unknown record types surface as
+    `unsupported` records with a warning, never dropped.
+  - `/common` value layer: delimiter model, escape codec, precision-preserving `YYYYMMDDHHMMSS` date
+    value (no-UTC, partial dates are not errors), Universal Test ID code-system provenance
+    recognition (`[OSS-derived]` field order), the deep-freeze base, and the warning/fatal registry.
+  - Fatal codes: `EMPTY_INPUT` (shared), `ASTM_RECORD_NO_HEADER`, `ASTM_RECORD_UNDECLARED_DELIMITERS`.
+    Warning codes: `ASTM_RECORD_UNKNOWN_TYPE`, `ASTM_NONSTANDARD_DELIMITERS`,
+    `ASTM_UNKNOWN_ESCAPE_SEQUENCE`, `ASTM_RECORD_AMBIGUOUS_VALUE_SPLIT` — all carry stable code +
+    value-free positional context.
+  - **Fail-safe on an unescaped component delimiter in a result value:** the full raw value and the
+    component split are both surfaced and an `ASTM_RECORD_AMBIGUOUS_VALUE_SPLIT` warning fires — the
+    primary `value` is never silently truncated to the first component.
+  - `scripts/phi-scan.ts` extended toward the P-record loci (name + DOB, delimiter-aware); synthetic
+    fixtures declared in `scripts/phi-allow-list.txt`.
+- Public exports replace the scaffold stubs: `parseAstmRecords`, `results`, `patient`,
+  `AstmParseError`, `AstmStrictError`, the record/value model types, and the `WARNING_CODES` /
+  `FATAL_CODES` registries.
+- **Safety-critical result semantics (ASTM-2, roadmap Phase 2).** The raw `R`-record letters that
+  Phase 1 surfaced are now modeled into fail-safe semantics, under one rule — _never a confident wrong
+  value_. The raw strings (`abnormalFlags`, `resultStatus`, `referenceRange`, `units`) still coexist
+  with the modeled views; nothing is collapsed or reconciled.
+  - **Abnormal flags (field 7) → HL7 Table 0078.** `interpretAbnormalFlag()` and the `flag` field on
+    `ResultRecord` model the full value set: `L`/`H`, panic `LL`/`HH`, off-scale `<`/`>`, `N`, `A`/`AA`,
+    the **directional** significant-change `U` (up) / `D` (down) — _not_ units/delta — `B`/`W`, and
+    microbiology `S`/`R`/`I`. An **unrecognized** flag is surfaced as `meaning: "undefined"` with an
+    `ASTM_RECORD_UNDEFINED_ABNORMAL_FLAG` warning — **never dropped, never coerced to `normal`**.
+  - **Result status (field 9).** `interpretResultStatus()` and the always-present `status` field model
+    `F`/`C`/`P`/`R`/`S`/`I`/`X`, with **`C` correction** (`supersedes: true`) and **`X` cancel**
+    (`cancelled: true`) so a superseded/cancelled result can **never** read as current — `isActiveFinal`
+    is `true` only for a plain `F`. An **absent** status is typed `unspecified` (never assumed `final`);
+    an unrecognized one is `undefined` + `ASTM_RECORD_UNDEFINED_RESULT_STATUS`.
+  - **Reference range (field 6).** `parseReferenceRange()` and the `range` field parse `low-high`
+    (closed), `<high` (open-low), and `>low` (open-high); bounds are surfaced as **verbatim numeric
+    text** (never coerced to floats). The range is read from the **full field text**, so a
+    component-delimited value (`low^high`) is preserved verbatim and read as `unparsed` — never
+    truncated to a single bound. An unparseable range is `kind: "unparsed"` +
+    `ASTM_RECORD_UNPARSEABLE_REFERENCE_RANGE` — **no bound is fabricated**. The exact delimiter is
+    `[OSS-derived]` pending the purchased CLSI LIS02-A2 (roadmap §10 Q1).
+  - **Units discipline (field 5).** A _numeric_ result value with no units raises
+    `ASTM_RECORD_UNITS_ABSENT`; units are vendor free text (not UCUM) and are **never defaulted,
+    guessed, or converted**.
+  - New warning codes (registry extended, snapshot locked): `ASTM_RECORD_UNDEFINED_ABNORMAL_FLAG`,
+    `ASTM_RECORD_UNDEFINED_RESULT_STATUS`, `ASTM_RECORD_UNPARSEABLE_REFERENCE_RANGE`,
+    `ASTM_RECORD_UNITS_ABSENT` — all value-free (code + record/field index only).
+- **Patient/order identity depth, comments, and partial-timestamp hardening (ASTM-3, roadmap Phase 3).**
+  The misfiling-prevention slice: model the identity that a result files against, and the context that
+  qualifies it.
+  - **Full patient (`P`) identity.** The **practice-assigned ID (field 3)**, the **laboratory-assigned
+    ID (field 4)**, and a **third patient ID (field 5)** are modeled as **distinct** fields that never
+    collapse into one — conflating them is the primary result-misfiling path. Adds mother's maiden name
+    (field 7) alongside the existing name components (field 6), birthdate (field 8), and sex (field 9).
+  - **Full order (`O`).** `priority` (field 6), `actionCode` (field ~12), and `reportType` (field ~26)
+    are surfaced **verbatim** on top of the existing specimen/accession + Universal Test ID. The `~`
+    field indices and the code sets are `[OSS-derived]` (paywalled) — never mapped to a guessed meaning.
+  - **The `C` (comment) record.** Modeled as `source` (field 3), `text` (field 4, component-capable —
+    the full text is surfaced plus the component split, never truncated), and `commentType` (field 5).
+    Each comment is **attached by position** to the immediately-preceding `H`/`P`/`O`/`R` parent
+    (`parentIndex`); consecutive comments share that parent. **Fail-safe:** an **orphan** comment with no
+    valid parent is attached to the message root (`attachedToRoot: true`) with an
+    `ASTM_RECORD_ORPHAN_COMMENT` warning — **never silently dropped**. New extractors `comments(msg)` /
+    `commentsFor(msg, record)` / `orders(msg)`, and the pure `attachComments()` attachment pass.
+  - **Comment-type codes are `[OSS-derived]`.** `I` (instrument) is the only value seen in the
+    permissively-licensed real transcripts; `G`/`T`/`P` are defined only in the paywalled CLSI LIS02-A2
+    and are **not** interpreted — `commentType` is surfaced raw, never mapped to a guessed meaning.
+  - **Partial-timestamp hardening.** A `YYYYMMDDHHMMSS` value with an odd digit run that truncates a
+    two-digit component (lengths 5/7/9/11/13) sets `AstmDate.truncated`, is preserved verbatim in `raw`,
+    and stops at the last **complete** component — the dangling digit is **never zero-filled into a
+    fabricated time**. A caller surfaces this as a value-free `ASTM_RECORD_PARTIAL_TIMESTAMP` warning
+    (P field 8, R fields 12/13). No timezone is modeled — times stay instrument-local, never assumed UTC.
+  - New warning codes (registry extended, snapshot locked): `ASTM_RECORD_ORPHAN_COMMENT`,
+    `ASTM_RECORD_PARTIAL_TIMESTAMP` — value-free (code + record/field index only).
+  - `scripts/phi-scan.ts` extended toward the mother's-maiden locus (P field 7), on top of the existing
+    name (field 6) + DOB (field 8) detection; synthetic fixtures declared in `scripts/phi-allow-list.txt`.
+- **Query (`Q`) + host-query flow + `M`/`S` surfaced verbatim (ASTM-4, roadmap Phase 4).** Completes the
+  record grammar — **the record-content layer is now feature-complete.**
+  - **The `Q` (Request Information) record.** Modeled at the public ASTM E1394 field positions:
+    `startingRangeId` (field 3) and `endingRangeId` (field 4) surfaced as the **full verbatim field**
+    (never truncated to a component), the Universal Test ID (field 5, same caret structure as `O`/`R`),
+    and `requestInformationStatus` (field 13) surfaced **verbatim**. The range component structure, the
+    `ALL` universal-query keyword (`queriesAllTests`), and the request-information status code set are
+    all **`[OSS-derived / paywalled]`** (roadmap §10 Q3) — surfaced, flagged, and **never interpreted or
+    guessed**. New `query(msg)` extractor.
+  - **The host-query flow.** Every message is classified up front (`msg.classification`): an `H/P/Q/L`
+    **request** is `host-query`, an `R`-bearing message is `results`, an `O`-only message is `orders`,
+    else `indeterminate`. **Fail-safe:** the `Q` **dominates** — a `Q`-bearing message is a request and
+    is **never** read as a result set, even when a result record is also present (a contradiction flagged
+    with `ASTM_RECORD_AMBIGUOUS_MESSAGE_KIND`). Gate on `classification.isHostQueryRequest`. Pure
+    `classifyMessage(records)` exported.
+  - **`M` (manufacturer) + `S` (scientific) records surfaced verbatim.** Vendor-defined free-form
+    QC / calibration / maintenance data, preserved byte-for-byte on `record.rawLine` and **never**
+    interpreted into typed clinical fields — a QC value can never be read as a patient result. Round-trip
+    byte-identical.
+  - New warning codes (registry extended, snapshot locked): `ASTM_RECORD_UNINTERPRETED_QUERY_STATUS`
+    (a Q request-information status surfaced verbatim; the code set is paywalled, so it is passed through
+    uninterpreted) and `ASTM_RECORD_AMBIGUOUS_MESSAGE_KIND` — both value-free (code + position only).
+  - `AstmMessage` gains a `classification` field; `AstmRecord` gains `QueryRecord` / `ManufacturerRecord`
+    / `ScientificRecord` members (an unknown type letter is still an `UnsupportedRecord`, never dropped).
+- **E1381/CLSI-LIS01 frame codec (ASTM-5, roadmap Phase 5).** The **low-level framing layer** begins —
+  a separate, independent layer from the record layer, sharing only the payload boundary. `src/frames/`
+  decodes a framed byte stream into frames + reassembled record bytes; `src/common/` and `src/records/`
+  are untouched.
+  - `decodeAstmFrames(bytes, opts?)` → `{ records: readonly Uint8Array[]; frames: readonly AstmFrame[];
+warnings: readonly AstmFrameWarning[] }`. A frame is `<STX> FN text <ETB|ETX> CS <CR><LF>`.
+  - **Modulo-256 checksum** over the bytes after `STX` up to and **including** the `ETB`/`ETX`
+    terminator, two hex chars — **verified on decode, emitted uppercase, accepted lowercase** (a real
+    vendor quirk). `computeChecksum` / `toChecksumHex` / `parseChecksumHex` exported.
+  - **Frame-number `0`–`7` sequencing** (rolls over `7 → 0 → 1`, starts at `1`) and **multi-frame record
+    reassembly** — text is capped at **240 bytes** (the seven control bytes are **not** counted), `ETB`
+    is intermediate / `ETX` final. `parseFramedAstm(bytes, opts?)` composes the framing and record layers
+    at the edge (decode → reassemble trusted records → `parseAstmRecords`).
+  - **Fail-safe (byte-level, safety-critical):** a **checksum mismatch** surfaces the frame flagged
+    `trusted: false` and **never merges** it into a record (default warn in lenient / thrown in strict —
+    the "checksums are routinely not validated" claim was _refuted_: we validate); a **frame-number gap**
+    warns and is **never silently bridged**; an **unterminated** frame surfaces the partial bytes
+    untrusted and **invents no partial record**; an **oversize** (>240) frame is flagged, never dropped.
+  - New `ASTM_FRAME_*` warning registry (a **second** registry alongside `ASTM_RECORD_*`, sharing only
+    the `EMPTY_INPUT` fatal; snapshot locked): `ASTM_FRAME_BAD_CHECKSUM`, `ASTM_FRAME_SEQUENCE_GAP`,
+    `ASTM_FRAME_UNTERMINATED`, `ASTM_FRAME_OVERSIZE` — every warning **value-free**, carrying a **frame
+    number + byte offset** only, never the record bytes a frame holds. `{ strict: true }` throws
+    `AstmFrameStrictError`.
+  - **Fuzz gate (required, part of `verify`):** a `fast-check` target over the codec — arbitrary /
+    truncated / mixed / control-char-laden bytes never crash, hang, or OOM; they degrade to a typed
+    error or a value-free warning. Plus property tests: N-frame reassembly equals the single-frame form,
+    and every trusted frame's recomputed checksum matches its declared value.
+  - New types/exports: `AstmFrame`, `FrameChecksum`, `FrameTerminator`, `FrameOptions`,
+    `DecodeAstmFramesResult`, `FramedAstmResult`, `AstmFramePosition`, `AstmFrameWarning`,
+    `FrameWarningCode`, `FRAME_WARNING_CODES`.
+- **Transport variants + pure LTP protocol reducer (ASTM-6, roadmap Phase 6).** The **LTP protocol
+  layer** — `src/ltp/` — sits above the frame codec: transport auto-detection plus a deterministic,
+  socket-free session state machine. No live I/O: the consumer owns the wire and clock; this layer
+  decides.
+  - **Transport auto-detection.** `detectFraming(bytes, opts?)` → `{ framing: "framed" | "raw";
+defaulted: boolean; warnings }`. A leading `STX`/`ENQ` ⇒ **framed** (serial, and the cobas 4800 /
+    iNTERFACEWARE Iguana framed-over-TCP reality); a leading bare record letter (`H`/`P`/`O`/`R`/`C`/
+    `Q`/`M`/`S`/`L`) ⇒ **raw** (the cobas b121 raw-TCP reality — framing dropped, records streamed
+    directly). An unrecognizable lead **defaults to framed and warns**
+    (`ASTM_LTP_AMBIGUOUS_TRANSPORT`), never guessing silently into data loss; an `override` forces the
+    mode (the Phase-8 profile hook).
+  - **Pure receiver-side reducer.** `ltpReduce(state, event)` → `{ state, actions, warnings }`, seeded
+    by `ltpInitialState()`. Events are the four LTP control signals (`enq`/`ack`/`nak`/`eot`) plus a
+    codec-decoded `frame`; actions are `sendAck` / `sendNak` / `sendEot` / `deliverRecord`. It models
+    the LIS01-A2 establishment → transfer → termination phases as `neutral ⇄ transfer`, reassembling
+    `ETB…ETX` runs into delivered records and tracking the `0`–`7` frame sequence.
+  - **ACK-failsafe (safety-critical, borrowed from `mllp`).** 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** (`ASTM_LTP_FRAME_REJECTED`). A duplicate
+    of the last-accepted frame is idempotently re-`ACK`ed without re-appending; a partial record open
+    on an `EOT` or `ENQ` restart is discarded, never delivered as if whole.
+  - New `ASTM_LTP_*` warning registry (a **third** registry alongside `ASTM_RECORD_*` / `ASTM_FRAME_*`;
+    value-free, carrying at most a frame number): `ASTM_LTP_AMBIGUOUS_TRANSPORT`,
+    `ASTM_LTP_UNEXPECTED_EVENT`, `ASTM_LTP_FRAME_REJECTED`.
+  - Property tests: the reducer **never emits `ACK` after an untrusted frame**; a full `ENQ → frames →
+EOT` session **reassembles exactly the source records**; a **raw-TCP stream equals its framed
+    twin**. Plus the transport-control control bytes `ASTM_ENQ` / `ASTM_ACK` / `ASTM_NAK` / `ASTM_EOT`.
+  - New types/exports: `detectFraming`, `AstmFraming`, `DetectFramingOptions`, `DetectFramingResult`,
+    `ltpInitialState`, `ltpReduce`, `LtpPhase`, `LtpState`, `LtpEvent`, `LtpAction`, `LtpTransition`,
+    `AstmLtpWarning`, `LtpWarningCode`, `LTP_WARNING_CODES`, `ltpAmbiguousTransport`,
+    `ltpUnexpectedEvent`, `ltpFrameRejected`.
+- **Spec-clean serializers + builders — both layers (ASTM-7, roadmap Phase 7).** The **emit** side: the
+  conservative inverse of the parser and the frame codec, so **round-trip fidelity holds by
+  construction**. Postel's Law's second half — liberal on parse, strict on emit.
+  - **Record serializer.** `serializeAstmRecords(msg | records)` and `serializeAstmRecord(record)` emit a
+    `CR`-terminated stream with the **canonical** `H|\^&` delimiters and every embedded delimiter
+    re-escaped. `encodeComponent()` is the exact inverse of the Phase-1 escape codec — the escape char is
+    encoded **first** (`&` → `&E&`), then the field / component / repeat delimiters (`&F&`/`&S&`/`&R&`) —
+    so a value containing a delimiter (a titre `1^40` → `1&S&40`) can never break framing and reads back
+    as **one** component. A source parsed with **non-canonical** delimiters is **normalized** to the
+    canonical set on emit (vendor-delimiter round-tripping is a Phase-8 profile concern). The header's
+    delimiter declaration is emitted **literally** (never escaped); `M`/`S` records are re-emitted
+    **byte-identically** from `rawLine`.
+  - **Message builder.** `buildAstmMessage(input)` constructs a spec-clean stream from typed input under
+    the **never-fabricate** discipline: it emits **only** the values the caller supplied — an omitted
+    field is left empty, **never a defaulted clinical value** (an unset result status reads back as
+    `unspecified`, never `final`; units / abnormal flags / patient IDs are never defaulted). The
+    **structure** — record type letters, the canonical delimiter declaration, per-record-type sequence
+    counters, the `L` terminator — is **computed, not guessed** (a sequence number may be overridden).
+  - **Frame encoder.** `composeAstmFrames(records, opts?)` is the exact inverse of `decodeAstmFrames`:
+    it wraps reassembled record bytes into `<STX> FN text <ETB|ETX> CS <CR><LF>` frames with the
+    modulo-256 **checksum** and the `0`–`7` **frame number** **computed** (never accepted-as-given or
+    faked; emitted uppercase), numbered continuously across the stream (start `1`, roll over `7 → 0`),
+    and every record over **240** text bytes **split** `ETB…ETX` (the seven control bytes never counted).
+    `serializeFramedAstm(msg | records)` composes both emit layers at the edge — the mirror of
+    `parseFramedAstm`.
+  - **Framing-integrity guards (typed errors, conservative emit).** A value carrying a `CR`/`LF` — which
+    no ASTM escape can encode — is refused with an `AstmSerializeError` (`ASTM_EMIT_UNENCODABLE_VALUE`)
+    rather than emitted into a corrupted wire; an empty record or empty record list is an
+    `AstmFrameEncodeError` (`ASTM_FRAME_EMPTY_RECORD`), never an empty frame.
+  - **Round-trip proven.** The shared archetype `roundTripProperty` is now **live** (serialize is the
+    idempotent inverse of parse); Tier-3 golden files round-trip every synthetic fixture through both the
+    record and framing layers (structural equality of the decoded field tree, zero frame warnings); and
+    `decodeAstmFrames(composeAstmFrames(x)).records ≡ x`.
+  - `HeaderRecord` gains an additive `rawLine` field (the escape char living inside the `\^&` definition
+    defeats the generic escape-aware tokenizer, so the raw header is the reliable source for both
+    delimiter reading and re-serialization). New exports: `serializeAstmRecords`, `serializeAstmRecord`,
+    `serializeField`, `encodeComponent`, `AstmSerializeError`, `buildAstmMessage` (+ `AstmRecordInput`,
+    `MessageInput`, `HeaderInput`, `PatientInput`, `PatientNameInput`, `OrderInput`, `ResultInput`,
+    `CommentInput`, `QueryInput`, `VerbatimInput`), `composeAstmFrames`, `AstmFrameEncodeError`,
+    `ComposeFramesOptions`, `serializeFramedAstm`.
+- **Vendor profile system — engine + registry + quirk tolerance + definition-time safety gate
+  (ASTM-8, roadmap Phase 8).** `src/profiles/` mirrors the sibling `@cosyte/hl7` `defineProfile` /
+  `@cosyte/ccda` `defineCcdaProfile` shape: `name` / `lineage` / `describe()` / `extends`-merge, a
+  provenance-backed built-in registry, a runtime tolerance transform, and a definition-time safety gate.
+  - `defineAstmProfile(opts)` builds a frozen, immutable profile declaring the **non-safety-critical**
+    warning codes a class of streams is expected to trip (each with a grounded `rationale`), plus an
+    optional `transport` override (`"framed"`/`"raw"`) — the raw-vs-framed-TCP knob a consumer feeds to
+    `detectFraming(bytes, { override })` for a stream whose leading byte would auto-detect the wrong way.
+  - **A profile never alters an extracted value.** The transform (`applyAstmProfileToWarnings`, run last
+    in `parseAstmRecords`) only ever re-badges a warning it _expects_ to the new `PROFILE_QUIRK_APPLIED`
+    code (flagged `expected: true`, carrying the original `toleratedCode` and position) — Postel's Law
+    with a receipt: nothing is dropped, and a spec-clean message parses byte-identically with or without
+    a profile.
+  - **The safety gate is default-deny and total.** Only four benign, value-preserving record codes are
+    tolerable (`ASTM_RECORD_UNKNOWN_TYPE`, `ASTM_NONSTANDARD_DELIMITERS`, `ASTM_UNKNOWN_ESCAPE_SEQUENCE`,
+    `ASTM_RECORD_UNINTERPRETED_QUERY_STATUS`); **every other code across all three registries — record,
+    frame (`ASTM_FRAME_*`), and LTP (`ASTM_LTP_*`) — is safety-critical and refused at definition time**
+    with an `AstmProfileDefinitionError`. A profile therefore can never make a bad checksum "ok," a
+    cancelled result read "final," or quiet a wrong value / flag / status / range / units / patient or
+    comment context / message-kind ambiguity. Any warning code added in a future phase is
+    safety-critical **by default** until deliberately added to the allow-list.
+  - `parseAstmRecords(raw, { profile })` accepts an explicit profile; `{ profile: null }` opts out of
+    the process-scoped default (`setDefaultAstmProfile`); an `expected` quirk does **not** escalate in
+    `strict` mode. `AstmMessage` gains an additive `profile?: { name, lineage }` attribution.
+  - **Built-ins:** `astmProfiles.default` (tolerates nothing) + `astmProfiles.referenceCorpus` — a
+    **non-vendor**, evidence-backed profile grounded firsthand in the redistributable OSS reference
+    corpus (`kxepal/python-astm` `codec.py` (BSD) + `senaite.astm`, which split on raw delimiters and
+    never un-escape `&F&`/`&S&`/`&R&`/`&E&`), tolerating only the resulting non-standard-escape
+    _syntactic_ noise (the value is preserved byte-for-byte). **Named per-vendor profiles**
+    (cobas / Sysmex / …) are **deferred** (`REAL-CORPUS`): the engine fully supports them, but no public
+    vendor-attributed quirk document grounds a named one.
+  - New warning code `PROFILE_QUIRK_APPLIED` (record registry). New exports: `defineAstmProfile`,
+    `AstmProfileDefinitionError`, `astmProfiles`, `getAstmProfile`, `listAstmProfiles`,
+    `setDefaultAstmProfile`, `getDefaultAstmProfile`, `applyAstmProfile`, `applyAstmProfileToWarnings`,
+    `resolveProfileTransport`, `profileQuirkApplied`, `SAFETY_CRITICAL_CODES`, `TOLERABLE_CODES`,
+    `ALL_ASTM_WARNING_CODES`, `isSafetyCriticalCode`, and the `AstmProfile`, `DefineAstmProfileOptions`,
+    `AstmQuirkTolerance`, `AstmQuirkMatch`, `AstmProfileProvenance`, `AnyAstmWarningCode` types.
+- **LIVD-aware LOINC recognition — bring-your-own catalog, zero bundled terminology data (ASTM-9,
+  roadmap Phase 9).** The `src/terminology/` layer maps an analyzer's local test code (the Universal
+  Test ID's vendor/local code on `R`/`O` records) to a standard LOINC via a **consumer-supplied** IICC
+  LIVD ("LOINC to Vendor IVD") catalog — **additive, advisory, and never a guessed LOINC** (a wrong
+  LOINC mis-identifies a test).
+  - `defineLivdCatalog(entries)` builds an immutable, frozen catalog indexed by the **Vendor Analyte
+    Code** (the vendor transmission code the instrument sends), grounded firsthand on the IICC LIVD
+    digital format / HL7 LIVD IG; `catalog.lookup(code)` returns `mapped` (one LOINC), `unmapped` (a
+    miss), or `ambiguous` (a code matching more than one distinct LOINC — surfaced, **never resolved**).
+  - `applyLivd(msg, catalog)` produces a **separate** layer of per-`R`/`O` `LivdAnnotation`s and never
+    mutates, alters, or drops the raw reported code/value; a catalog hit is labeled `derived: true`
+    (`source: "livd"`), an inline LOINC already on the wire is surfaced `source: "wire"` (never
+    overwritten by the catalog), and a miss/conflict is `unmapped`/`ambiguous` with a **value-free**
+    warning — a LOINC is **never** fabricated. `lookupLivdForRecord(record, catalog)` annotates one
+    record.
+  - **No LOINC / SNOMED / LIVD data is bundled** (roadmap §5). Firsthand: LOINC is © Regenstrief —
+    redistributable only _with its attribution notice_, not public-domain; and the public CDC LIVD file
+    is a **SARS-CoV-2-specific** publication that also carries separately-licensed SNOMED CT, not a
+    general-analyte, public-domain catalog. The package stays a structural recognizer, not a dictionary:
+    the consumer supplies the LIVD data (and owns its license obligations).
+  - New `ASTM_LIVD_*` warning registry (`ASTM_LIVD_UNMAPPED_CODE`, `ASTM_LIVD_AMBIGUOUS_MAPPING`) — a
+    fourth, self-contained registry, deliberately outside the profile safety gate's universe (a LIVD
+    non-mapping is a post-parse advisory, not a parse-time deviation a profile could tolerate). New
+    exports: `defineLivdCatalog`, `applyLivd`, `lookupLivdForRecord`, `LIVD_WARNING_CODES`,
+    `livdUnmappedCode`, `livdAmbiguousMapping`, and the `LivdCatalog`, `LivdEntry`, `LivdLookup`,
+    `LivdAnnotation`, `LivdMapping`, `LivdResult`, `AstmLivdWarning`, `LivdWarningCode` types.
+- **Release hardening (ASTM-10, roadmap Phase 10 — the final phase).** Publish-readiness for the now
+  feature-complete parser: coverage, fuzz, firsthand differential testing, the full docs spine, and a
+  proven release shape. No new runtime API.
+  - **Differential conformance vs [python-astm][pa]** (BSD-3-Clause reference codec, commit
+    `4170ce0c`), grounded **firsthand** in `test/differential/`: outputs captured once from the
+    reference (`generate-reference-vectors.py` → `reference-vectors.json`; **no reference code
+    vendored**), then asserted against `@cosyte/astm` on three shared paths — the **modulo-256
+    checksum**, the **record field/component split** (escape-free, non-header), and a
+    **cross-implementation frame decode** (python encodes + splits → our decoder verifies every
+    checksum and reassembles the exact record bytes). The **deliberate divergences** are asserted on
+    purpose: we un-escape `&F&`/`&S&`/`&R&`/`&E&` (python leaves them literal), we validate the frame
+    checksum (python does not verify on decode), and we classify the `Q` host-query (python has no
+    model). CI needs no Python — only the captured JSON.
+  - **Per-directory ≥ 90 coverage gating extended to the whole `src/` surface** — `frames`, `ltp`,
+    and `terminology` now gate per-dir alongside `common`/`records`/`profiles` (on top of the global
+    gate), so the release bar holds directory by directory, not just in aggregate.
+  - **Record-tokenizer fuzz** (`test/property/records-fuzz.property.test.ts`) — the companion to the
+    frame-codec fuzz: arbitrary / truncated / delimiter- and escape-laden input into
+    `parseAstmRecords` never crashes, hangs, or OOMs; lenient mode only ever throws a sanctioned
+    Tier-3 fatal, strict only `AstmStrictError`, and every warning carries a registered code. Both
+    fuzz suites scale via `ASTM_FUZZ_RUNS`, driven up nightly by a scheduled **Fuzz** workflow
+    (`.github/workflows/fuzz.yml`) and runnable on demand via `pnpm test:fuzz`.
+  - **Publish dry-run proven release-shaped:** `attw` all-green (per-condition ESM/CJS types), a new
+    `smoke` gate (`scripts/smoke.mjs`) that imports the **built** ESM and requires the **built** CJS
+    entry and parses a result through each (now wired into `verify.sh`), and an `npm publish
+--dry-run` pack inspection (10 files — `dist/` + `README`/`LICENSE`/`CHANGELOG`/`package.json`,
+    no `src` or tests). Zero runtime dependencies; MIT.
+  - **Full Diátaxis docs spine + honesty docs.** New `docs-content/limitations.md` (**What it does —
+    and does not do**: no live I/O, units are verbatim free text not UCUM, no bundled terminology
+    dictionary, `M`/`S` verbatim, the archived-standard status, and the MIT-vs-CLSI license posture)
+    and `docs-content/architecture.md` (the two independent layers and their payload boundary); the
+    **Guides** page is now real how-to recipes (was a placeholder), and the intro / troubleshooting /
+    concepts status blocks are refreshed to the feature-complete state. Every ` ```ts runnable `
+    example is executed by the doc/code-agreement gate.
+
+[pa]: https://github.com/kxepal/python-astm
+
+### Changed
+
+- **Breaking (pre-alpha):** the archetype stub `parseAstm` / `ParsedAstm` is replaced by
+  `parseAstmRecords` / `AstmMessage`; the placeholder `WARNING_CODES` / `FATAL_CODES` entries are
+  replaced by the real Phase-1 registries.
+
+### Deferred (later phases)
+
+- **Named per-vendor profiles** (cobas / Sysmex / ADVIA / Mindray / Snibe) stay `REAL-CORPUS`-gated —
+  the Phase-8 engine supports them (tolerate + transport override), but no public vendor-attributed
+  quirk document grounds a named one. **No bundled terminology
+  dictionary** — LIVD-aware LOINC recognition is bring-your-own by design (Phase 9); the package ships
+  no LOINC / SNOMED / LIVD data and mapping quality is the consumer's catalog. The LTP reducer remains
+  a pure state machine — no live I/O: wiring it to a real `SerialPort`/`net.Socket` (and the
+  interactive contention/timeout/retransmit **timing**) is a thin consumer adapter, and the standard's
+  exact numeric timeouts / retry counts are deferred (we model transitions, not timers).
+
+### Deprecated
+
+### Removed
+
+### Fixed
+
+### Security
+
+[Unreleased]: https://github.com/cosyte/astm/commits/main

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cosyte
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,185 @@
+# @cosyte/astm
+
+> ASTM parser, serializer, and builder for Node.js and TypeScript — **lenient on parse,
+> spec-clean on emit**.
+
+`@cosyte/astm` is a zero-dependency TypeScript toolkit that follows the cosyte parser archetype: a lenient
+parser that turns real-world, vendor-quirky input into **warnings** rather than failures, paired with
+a serializer that always emits spec-clean output (Postel's Law). It mirrors the API shape of the
+reference parser, [`@cosyte/hl7`](https://github.com/cosyte/hl7).
+
+> **Status:** pre-alpha (`0.0.x`), not yet published to npm. Phase 1 ships the **record** layer
+> (`H`/`P`/`O`/`R`/`L` read, delimiter self-declaration, escape decode); Phase 2 adds **safety-critical
+> result semantics** — HL7 Table 0078 abnormal flags, result status (with correction `C` / cancel `X`),
+> reference-range parsing, and the units-absent discipline; Phase 3 adds **identity depth, comments, and
+> timestamp hardening** — the three distinct patient IDs, mother's maiden name, full order fields, the
+> `C` comment record attached by position (orphans surfaced, never dropped), and partial timestamps
+> preserved and flagged, never zero-filled. Phase 4 adds the **`Q` request-information record + the
+> host-query flow** (a `Q`-bearing message is classified a request, **never** read as a result set) and
+> the **`M`/`S` records surfaced verbatim** (vendor QC/calibration data, never interpreted into clinical
+> fields) — the **record-content layer is now feature-complete**. Phase 5 adds the **E1381/CLSI-LIS01
+> frame codec**: `decodeAstmFrames` decodes a framed byte stream into frames + reassembled record
+> bytes, **verifies the modulo-256 checksum** (a bad frame is surfaced untrusted and never merged),
+> tracks **frame-number sequencing** (a gap is never silently bridged), and **reassembles** the
+> 240-byte-limited multi-frame records; `parseFramedAstm` composes the framing and record layers at the
+> edge. Phase 6 adds the **transport layer**: `detectFraming` auto-detects framed (serial / cobas 4800 /
+> Iguana) vs raw (cobas b121, framing dropped) streams, and `ltpReduce` is a **pure, socket-free**
+> receiver-side `ENQ`/`ACK`/`NAK`/`EOT` state machine whose one rule mirrors `mllp`'s ACK-failsafe — a
+> bad-checksum frame is **NAK**ed, never falsely **ACK**ed. Phase 7 adds the **spec-clean serializers +
+> builders** — `serializeAstmRecords` / `buildAstmMessage` emit canonical `H|\^&` records (embedded
+> delimiters re-escaped, nothing clinical fabricated) and `composeAstmFrames` / `serializeFramedAstm`
+> frame them with **computed** checksums + frame numbers and the 240-byte split, so both layers
+> round-trip by construction. Phase 8 adds the vendor **profile** system — `defineAstmProfile()` builds
+> a provenance-backed profile whose quirk tolerances downgrade _expected_, non-safety-critical
+> deviations to a `PROFILE_QUIRK_APPLIED` warning (values are never altered), guarded by a
+> definition-time safety gate that refuses to tolerate any result value / flag / status / range /
+> units, patient or comment context, message-kind, or frame / LTP integrity warning — a profile can
+> never make a bad checksum "ok" or a cancelled result read "final." Named per-vendor profiles are
+> deferred pending a public vendor-attributed quirk document. Phase 9 adds **LIVD-aware LOINC
+> recognition** — `applyLivd(msg, catalog)` maps an analyzer's local test code to a standard **LOINC**
+> from a **consumer-supplied** IICC LIVD catalog (`defineLivdCatalog`), as an **additive, advisory**
+> annotation that never mutates the raw code/value and **never guesses a LOINC** (an unmapped or
+> ambiguous code surfaces as such). No LOINC / SNOMED / LIVD dictionary is bundled — the package stays a
+> structural recognizer, and the consumer brings their own catalog.
+
+## Decode a framed byte stream
+
+```ts
+import { decodeAstmFrames, parseFramedAstm, results } from "@cosyte/astm";
+
+// A raw ASTM byte stream off a serial line or socket.
+const { records, frames, warnings } = decodeAstmFrames(framedBytes);
+frames[0]?.checksum.valid; // the modulo-256 checksum verdict (emitted uppercase, accepted lowercase)
+warnings; // ASTM_FRAME_* deviations, each with a frame number + byte offset (never the record bytes)
+
+// Or compose both layers: decode frames → parse the trusted, reassembled records.
+const { message } = parseFramedAstm(framedBytes);
+results(message)[0]?.value; // only checksum-verified frames ever reach the record parser
+```
+
+A checksum mismatch, a sequence gap, an unterminated frame, and an oversize (>240) frame are each a
+**warning** in the default lenient mode (surfaced, flagged, never silently trusted) and a thrown
+`AstmFrameStrictError` under `{ strict: true }`.
+
+## Drive the transport (framed vs raw) + the LTP protocol
+
+ASTM transport is not uniform: **serial** always frames, but over **TCP it varies within a single
+vendor** — the cobas 4800 and Iguana keep the full `ENQ`/`ACK` + `STX`/checksum framing, while the
+cobas b121 drops it and streams de-framed record bytes directly. Detect which you have, then drive the
+pure protocol reducer with your own socket I/O.
+
+```ts
+import {
+  detectFraming,
+  decodeAstmFrames,
+  parseAstmRecords,
+  ltpInitialState,
+  ltpReduce,
+} from "@cosyte/astm";
+
+// 1. Route by the stream's leading byte (STX/ENQ ⇒ framed; a bare record letter ⇒ raw).
+const { framing } = detectFraming(leadingBytes); // "framed" | "raw"  (override: { override: "raw" })
+if (framing === "raw") {
+  // cobas b121 raw-TCP: no handshake, no frames — parse the record bytes directly.
+  parseAstmRecords(rawBytes);
+}
+
+// 2. Framed transport: drive the pure receiver-side state machine. YOU own the socket + clock.
+let state = ltpInitialState();
+function onControlOrFrame(event) {
+  const { state: next, actions, warnings } = ltpReduce(state, event);
+  state = next;
+  for (const a of actions) {
+    if (a.type === "sendAck") socket.write(Uint8Array.of(0x06)); // ACK  — only ever for a good frame
+    if (a.type === "sendNak") socket.write(Uint8Array.of(0x15)); // NAK  — bad checksum ⇒ retransmit
+    if (a.type === "deliverRecord") parseAstmRecords(a.record); // a complete, trusted record
+  }
+  void warnings; // ASTM_LTP_* — value-free (a code + at most a frame number)
+}
+// Feed events as you read them: { type: "enq" }, { type: "frame", frame: decodeAstmFrames(b).frames[0] }, …
+```
+
+The reducer is deterministic and fully testable without a socket. Its inviolable rule: a frame the
+codec did not vouch for — bad checksum, unterminated, or out of sequence — yields `sendNak`, **never** a
+fabricated `sendAck`, and is **never** appended to a record. A `NAK` drives retransmit, not acceptance.
+The interactive contention/timeout/retransmit **timing** is the consumer's — this layer models the
+state transitions, not the wall-clock timers.
+
+## Install
+
+```bash
+npm install @cosyte/astm
+```
+
+## Parse
+
+```ts
+import { parseAstmRecords, results, patient } from "@cosyte/astm";
+
+// A de-framed ASTM record stream (CR-delimited records; the header declares the delimiters).
+const msg = parseAstmRecords(raw);
+
+results(msg)[0]?.value; // the measured value, surfaced raw
+results(msg)[0]?.units; // vendor free-text units (a missing unit is a warning, never a default)
+patient(msg)?.practiceAssignedId; // kept distinct from laboratoryAssignedId (the misfiling guard)
+msg.warnings; // stable, value-free positional tolerance warnings (never throws on quirks)
+```
+
+The parser is **lenient by default** — vendor quirks become warnings, not failures — and refuses to
+produce a confident wrong value: an embedded escaped delimiter reads as one component, an unknown
+record type is surfaced (never dropped), and a missing unit is flagged (never defaulted). A
+`{ strict: true }` mode escalates every tolerated deviation to a thrown error.
+
+## Map local codes to LOINC (LIVD, bring-your-own)
+
+An analyzer sends a proprietary local test code in the Universal Test ID; a standard LOINC is mapped
+downstream. Supply your own IICC LIVD ("LOINC to Vendor IVD") catalog and annotate a message — the
+mapping is **additive and advisory**: it never touches the raw code or value, and an unmapped or
+ambiguous code is surfaced as such, **never a guessed LOINC**.
+
+```ts
+import { parseAstmRecords, defineLivdCatalog, applyLivd } from "@cosyte/astm";
+
+// Your LIVD catalog: the vendor transmission code (Vendor Analyte Code) → LOINC.
+const catalog = defineLivdCatalog([{ vendorCode: "687", loinc: "1920-8", loincLongName: "AST" }]);
+
+const msg = parseAstmRecords("H|\\^&\rR|1|^^^687|28.6|U/L||N||F\rL|1\r");
+const { annotations, warnings } = applyLivd(msg, catalog);
+
+annotations[0]?.mapping; // { status: "mapped", loinc: "1920-8", loincLongName: "AST", source: "livd", derived: true }
+warnings; // ASTM_LIVD_UNMAPPED_CODE / ASTM_LIVD_AMBIGUOUS_MAPPING (value-free) for codes with no single LOINC
+```
+
+**No LOINC / SNOMED / LIVD dictionary is bundled.** LOINC is © Regenstrief (redistributable only with
+its attribution notice) and the public CDC LIVD file is SARS-CoV-2-specific and carries
+separately-licensed SNOMED CT — so the package ships no terminology data and you bring the catalog (and
+its license obligations).
+
+> **Scope your catalog to the source device fleet.** The ASTM Universal Test ID carries no manufacturer
+> to disambiguate against, so the catalog keys on the vendor transmission code alone. Two different
+> instruments that reuse the same code for different analytes would both match — 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.)
+
+## The cosyte parser archetype
+
+- **Postel's Law** — liberal parser (lenient default + warnings), conservative serializer (always
+  spec-clean), so quirks don't propagate downstream on round-trip.
+- **Tiered tolerance** — Tier 0/1 silent, Tier 2 warning + recovery (escalates in strict mode),
+  Tier 3 fatal always.
+- **Stable warning codes** — warnings carry stable string codes + positional context; consumers
+  branch on `w.code`, so renaming a code is a breaking change.
+- **Zero runtime dependencies** — Node stdlib only (healthcare integrations vet every dependency).
+- **Dual ESM + CJS** — built with `tsup`, validated with `attw`.
+- **Immutability** — parsed models are immutable; mutation is via explicit methods.
+- **Profile system** — a `defineAstmProfile()` API for vendor quirks, with built-in profiles authored
+  through the same public API. A profile only ever downgrades an _expected_, non-safety-critical warning
+  to `PROFILE_QUIRK_APPLIED` (it never alters a value) and may force the raw-vs-framed transport; a
+  default-deny safety gate refuses to tolerate any safety-critical deviation at definition time.
+- **Terminology recognizer, not a dictionary** — LIVD-aware LOINC recognition is bring-your-own
+  (`applyLivd` over a consumer-supplied catalog): additive, advisory, and never a guessed LOINC. No
+  LOINC / SNOMED / LIVD data is bundled.
+
+## License
+
+MIT © Cosyte