@cosyte/astm 0.0.3 → 0.0.4

package/CHANGELOG.md

@@ -9,8 +9,411 @@ this file is maintained by hand (Changesets handles the version bump and publish
 
 ## [Unreleased]
 
+### Added
+
+- **`messages()` — read a stream as the sequence of messages it actually is**
+  (`ASTM-PATIENT-RESULT-MISATTRIBUTION`). A parsed model has always been a whole record
+  **stream**, and a stream may carry several messages back to back: a message runs from an `H`
+  header to its `L` terminator. `messages(msg)` splits the stream into them and returns a
+  readonly array of `AstmStreamMessage`, each carrying only its own records:
+
+  ```ts
+  for (const m of messages(parseAstmRecords(raw))) {
+    m.patient; // the P for THIS message
+    m.results; // the Rs for THIS message
+  }
+  ```
+
+  Each entry carries `index`, `header`, `delimiters`, `records`, `patient`, `patients`,
+  `results`, `orders`, `comments`, and `queries`. It never throws, and a single-message stream
+  yields exactly one entry whose `records` are the whole stream, so it is safe to reach for
+  unconditionally.
+
+  **A message opens at every `H`** and runs to the record before the next one. That is
+  deliberately the _same_ boundary the parser already uses to scope delimiters, so message
+  boundaries and delimiter scope cannot disagree; `m.delimiters` is the set that message's
+  records were actually read with. The `L` terminator closes a message but opens no scope, so
+  records between an `L` and the next `H` stay with the message their header opened rather than
+  being dropped. Grouping is **total**: every record lands in exactly one message, none
+  duplicated and none lost, which is asserted directly.
+
+  **Evidence, labelled.** The message unit is `H` … `L` — _verified primary_: CLSI LIS02-A2 §2 is
+  definitional about the unit itself, bounding a message by the `H` record at one end and the `L`
+  record at the other. Read directly in CLSI's own free sample, and stated here in our own words
+  on purpose: we may read and cite the standard but never reproduce its prose, and this file ships
+  inside the npm tarball. That clause is the whole of what is claimed from the standard here, and
+  it does **not** settle which record _opens_ a new scope partway through a stream. So treating a
+  second `H` as the start of the next message is recorded as a **reasoned choice, not a citation**
+  — no clause number is claimed for it, and we do not assert the standard is silent either. It is
+  chosen to agree with the delimiter scoping this parser already enforces, and because it drops no
+  record. **The OSS corpus was checked rather than dismissed**, and unlike for delimiter questions
+  it is informative here — but only negatively: neither commonly-cited reference implementation
+  models the message unit at all. One dispatches records to per-type callbacks one at a time with
+  no carried state, leaving the association to the integrator; the other merges every message of a
+  transport session into a single envelope of flat per-record-type buckets, from which the
+  association cannot be recovered at all. A flat model is the incumbent shape, and this entry is
+  what it costs.
+
+  **`patient` is answered only when the message determines one.** It is the single `P` when the
+  message carries exactly one, and `undefined` when it carries none **or** several;
+  `patients.length` distinguishes those two, and there is no third meaning. A message carrying
+  several patients is not answered with the first one, because that is the guess this release
+  exists to remove. Within-message record hierarchy (which `P` a given `R` files against when a
+  message carries several) is **not** modeled: the clauses that would ground it (the
+  message-level structure diagram, and the `P` sequence-number rule) are withheld from the free
+  sample and paywalled, so the layer declines rather than inventing a rule. Multi-patient
+  messages are real — at least one openly-published vendor interface grammar makes the patient
+  group repeatable on the download direction — so this is a deferral with a known shape, not a
+  claim that the case does not arise, and not a claim that the standard is silent about it.
+
+- **`pnpm check:no-internal-refs` + a `no-internal-refs` CI job** (`PUBLIC-SURFACE-HYGIENE`,
+  founder directive 2026-07-27). Internal only; no change to the published package surface. `astm` was
+  the last parser with no gate on this rule at all, which is why the class had regrown. The script is
+  ported from `ncpdp`'s copy (which carries three fixes `hl7`'s reference lacks: the `src/`
+  string-literal pass, the plural `phases?` stem, and `/` in the ADR separator class) plus `cli`'s
+  seventh rule, the prose roadmap citation, which neither `hl7` nor `ncpdp` has and which found the
+  second-largest class here. Four surfaces are scanned against seven rules: public markdown +
+  the npm `description`/`keywords`, `src/` doc comments, and `src/` string literals. The two prose
+  surfaces are scanned line by line **and** paragraph-reflowed, so a violation that straddles a wrap
+  is still caught; the npm metadata and the string-literal pass are line-scanned only. A multi-line
+  template literal is not scanned at all, split or not, because the extractor needs both delimiters
+  on one line. `//` comments, `CHANGELOG.md` and `.changeset/` are deliberately out of scope:
+  the convention names them as where identifiers belong.
+
+  Re-derived for this repo rather than copied: rule 2 now excludes E1381/CLSI-LIS01's own
+  **protocol phases** (`protocol`, `three-`, `establishment`, `transfer`, `termination`, `neutral`,
+  `idle`), because "phase" is the standard's word for the state of the line and `LtpState.phase` is an
+  exported field. The cost is disclosed rather than papered over: because a lookbehind exempts the
+  whole match, one of our own phases sitting behind one of those words is not caught (`the transfer
+phase 8` passes while `Phase 8` reds). An arm keyed on a following digit was written, measured and
+  removed, because the justification did not survive the corpus: the digit is usually the next
+  clause's first token, so it red on `In the transfer phase 240 bytes is the maximum frame text` and
+  on `a three-phase 400 V supply`, which are reference prose. Where a rule cannot be guarded, it is
+  cut rather than hardened. And the `SPEC-7` /
+  `ACC-42` synthetic example ids in every runnable sample are
+  `WORD-N` exactly, so a shape-keyed rule would rewrite the sample a consumer copy-pastes. Both are
+  asserted in negative self-tests, alongside `ASTM-E1394`, `CLSI-LIS01`, `LIS02-A2`, `POCT1-A`,
+  `E1394-97` and `ICD-10-CM`. A further negative self-test pins **bare `§` section citations as
+  deliberately unruled**, so closing that hole has to be a decision rather than a widening that lands
+  by accident.
+
+  The script also **refuses to run under a `grep` that cannot see its subject.** A scanner-visibility
+  probe seeds a violation into a file containing a NUL byte and requires it to come back as either a
+  hit or a stderr diagnostic; silence at exit 0 is a hard refusal, because a tool that skips a file
+  produces output identical to a tool that read it and found it clean. This is not theoretical: the
+  development container interposes a `grep` with `-I` forced, which drops such input without a word.
+  An interposed shell function is also `unset` rather than assumed absent. Both directions are
+  proven — an `-I`-forcing `grep` ahead of it on `PATH` makes the gate refuse, and an exported `grep`
+  function is neutralised. The companion `-G` (basic-regex) hazard needs no separate guard: every
+  positive self-test uses alternation, so a BRE-forced `grep` fails them and refuses.
+
+  Known gaps, stated rather than discovered later: a bare `P\d+` label (`(P7)`) is not caught, because
+  a general `P\d+` rule has corrupted ICD-10-CM codes in a sibling; `phase` at the end of a clause is
+  not caught; bare `§` section citations are deliberately unruled; and `dist/` is build output this
+  script cannot read, so it gates dist's source, not dist. Fourteen `P\d+` lines and the falsehoods
+  below were found by hand, not by a rule.
+
+### Changed
+
+- **BREAKING: `patient()`, `results()`, `orders()`, `comments()`, and `query()` now throw on a
+  stream they cannot answer for, instead of answering across patients**
+  (`ASTM-PATIENT-RESULT-MISATTRIBUTION`; shipped `0.0.1` through `0.0.3`).
+
+  **The defect.** These accessors read the whole stream. On a stream carrying more than one
+  message, `patient()` answered with the **first** `P` in the stream while `results()` answered
+  with **every** `R` in it, so pairing them — which is exactly what this package's one-line north
+  star does — attributed one patient's results to another. It needed no delimiter redeclaration
+  and no unusual delimiters: an ordinary two-message stream in one canonical set reproduced it,
+  with **zero** warnings, and `strict` mode raised no objection either. On an analyzer-to-LIS
+  path that is a result filed against the wrong patient. Nothing was mis-_read_ — every `P` and
+  every `R` was correct in `records` — but there was no way to ask which belonged together.
+
+  **The change.** Those five accessors now throw `AstmAmbiguousStreamError` with code
+  `ASTM_AMBIGUOUS_MULTI_MESSAGE` when the stream carries more than one message. `patient()` also
+  throws `ASTM_AMBIGUOUS_MULTI_PATIENT` when the single message it is reading carries more than
+  one `P`, which is the same harm one level down: "the first `P`" is a guess about whose result
+  it is. The error carries a stable code, a value-free position, and the two counts; never an
+  identifier and never a value.
+
+  **Why the break is the fix, not a cost of it.** The callers this breaks are exactly the
+  population that is being silently corrupted today. A caller who now gets an exception is
+  strictly better off than one who quietly received another patient's results: the failure is
+  loud, immediate, positioned, and correctable, where before it was invisible at every layer.
+  There is no version of this where the old behaviour is safe to keep, and no warning strong
+  enough to substitute for refusing to answer, because the wrong answer was already being used.
+
+  **Which callers are affected, stated exactly.** A stream that is one message carrying at most one
+  `P` is **unchanged**, and so is a result-only message with no `P` at all: `patient()` still answers
+  `undefined` there, which is an ordinary shape and not an error. But `ASTM_AMBIGUOUS_MULTI_PATIENT`
+  **does reach single-message callers** — a lone message carrying several patients used to answer
+  with the first of them and now refuses — so "single-message streams are unaffected" would be false
+  and is not claimed. That second break is the same wrong-patient guess as the first, one level down,
+  and it is disclosed on the README and in the docs for the same reason the first one is.
+  `commentsFor()` is unchanged and works on any stream, single- or multi-message, because the parent
+  record it is handed already names the message.
+
+  **Migrating** is mechanical: replace `results(msg)` and `patient(msg)` with a walk over
+  `messages(msg)`, reading each message's own `patient` and `results`. Where a caller genuinely
+  wants every result in a stream regardless of who they belong to, that is
+  `messages(msg).flatMap((m) => m.results)` — written out, so it is a choice rather than a
+  default.
+
 ### Fixed
 
+- **Emit no longer writes a stream it cannot read back** (`ASTM-EMIT-RESIDUALS`; both gaps shipped
+  `0.0.1` through `0.0.3`, `PRE-EXISTING`, neither a regression). Two residual emit-side holes, both
+  recorded and deliberately deferred by `ASTM-MIXED-DELIMITER-EMIT` (#21) and again by
+  `ASTM-SECOND-HEADER-COLLAPSE` (#22) because each turned on a question those slices did not answer.
+  Both were reproduced by **executing** the shipped code before anything was changed, and re-verified
+  the same way after; neither was half-fixed by the two earlier slices.
+
+  **1. A delimiter declaration longer than three characters lost its extra bytes.** Three characters
+  of a header's declaration carry a role — repeat, component, escape, by position — and the reader
+  ignores any beyond them rather than refusing the stream. Emit regenerated the declaration from the
+  three roles alone, so a header that arrived as `H|\^&#` went back out as `H|\^&`, with no warning
+  and no way for a caller to notice. Measured before the fix: `serializeAstmRecords(msg, msg.delimiters)`
+  on `H|\^&#|||SENDER^SYS|||||||P|1` returned a header short of its `#` and a round-trip that was not
+  byte-exact.
+
+  The surplus is now carried through from the modeled declaration field. Of the three available
+  dispositions — preserve, refuse, report — **preserve** was chosen. Refusing would reject a stream
+  the parser reads without complaint, on a published package, over bytes it has already decided are
+  inert. Reporting is not available at all: emit returns a bare string and has no warning channel, so
+  a warning could only be ignored while the truncated stream still shipped, which is the same reason
+  #21 chose re-encoding. Preserving costs nothing and is the only one of the three that makes the
+  round-trip byte-exact. What the surplus _means_ remains unresolved — the clauses that would settle
+  it are not in the freely published material and were not read, so no clause is cited here in either
+  direction — but carrying bytes through unread is a strictly smaller claim than deleting them, and it
+  stays coherent with a reader that now scopes delimiters forward from every header: the re-read
+  declaration resolves to the same four roles either way. This lands on the **default** canonical
+  path too, not only when a set is passed explicitly — normalizing a message replaces the four
+  delimiter roles, and the surplus holds none of them — so a caller who was relying on emit to strip
+  those bytes will find it no longer does.
+
+  The surplus is dropped in exactly the two cases where it could not be read back as surplus — the
+  header is being transcoded into a different delimiter set, so the surplus belonged to the
+  declaration being replaced; or the surplus is not inert on the wire, meaning it contains the field
+  separator or **any control character**. The control rule is deliberately wider than the record
+  layer alone needs. A `CR`/`LF` would end the record and shift every data field along, but this text
+  also reaches the **frame** layer through `serializeFramedAstm`, where `STX`, `ETX` and `ETB` are
+  structural: a surplus carrying one of those truncated the frame body, and re-reading the framed
+  stream then dropped the **entire header record** — its sender, its receiver, its control ID —
+  behind nothing but an `ASTM_FRAME_BAD_CHECKSUM`. Rather than enumerate the bytes each layer happens
+  to reserve, and re-derive that list whenever a layer is added, no control character is carried at
+  all. Two things that rule does **not** do, said here rather than left to be found: it is keyed on
+  the character while the frame layer's structure is keyed on the low byte (`charCodeAt(i) & 0xff`),
+  so a non-control character truncating onto `STX`/`ETX`/`ETB` still breaks framing — loudly, with a
+  typed error or an unknown-record-type warning, never silently; and refusing a control character in
+  a _surplus_ does not mean one cannot be a _delimiter role_, since only `CR`/`LF` are refused
+  there. Those are
+  structural losses; dropping inert bytes is not.
+
+  **2. A caller-supplied delimiter set was never validated.** `serializeAstmRecords(msg, d)` and its
+  three siblings took `d` on trust. Measured before the fix, across six malformed sets: a
+  multi-character field separator, an empty escape character, a `field`/`escape` collision and a `CR`
+  separator each emitted a stream `parseAstmRecords` then **threw** on; a `repeat`/`component`
+  collision and a `component`/`escape` collision each emitted one it **re-read with a different field
+  tree and zero warnings**. An empty escape additionally garbled the values themselves — `28.6` went
+  out as `2E8E.E6`. On the analyzer-to-LIS path a field tree that changes under a re-read is a lost
+  result or a lost specimen identifier, and the caller had no signal either way.
+
+  `d` is now checked before any bytes are written, on all four public emit entry points
+  (`serializeAstmRecords`, `serializeAstmRecord`, `serializeField`, `encodeComponent`): each separator
+  exactly one character, none a `CR`/`LF`, no two the same character. A failing set is an
+  `AstmSerializeError` with the new code `ASTM_EMIT_INVALID_DELIMITERS` — including a set that omits a
+  member or holds a non-string, which the types forbid but a JavaScript caller can still pass, and
+  which previously surfaced as a raw `TypeError` from inside the serializer.
+
+  **The three rules are necessary, not sufficient, and the docs say so rather than implying a
+  guarantee.** A set can satisfy all three and still emit a stream that reads back wrong: a separator
+  equal to a record's type letter (`field` of `R`) makes the type letter itself get escaped away, and
+  the record re-reads as unsupported with its result lost. That corruption is unchanged by this slice
+  — it reproduces byte-identically before it — and is recorded as a known defect rather than fixed
+  here, because the rule that would catch it has to be derived rather than guessed. **A typed error rather than a
+  warning, and the house rule from #21 is why**: with no warning channel on a `string` return, refusing
+  at the call is the only disposition that reaches the caller at all. The counter-argument was weighed
+  and is real — `@cosyte/astm` is published, and refusing rejects input previously accepted. It is
+  accepted deliberately, because the input turned away is exactly the input that was being corrupted,
+  and because the three rules are not stylistic: each names a case where the emitted bytes provably do
+  not read back as the records that produced them. The narrowing has one consequence worth stating
+  plainly: the **reader** tolerates a header declaring, say, the same character for `repeat` and
+  `component`, so `serializeAstmRecords(msg, msg.delimiters)` on such a message now throws where it
+  previously returned bytes that read back wrong. The canonical default is untouched, and so is every
+  well-formed set. The error names the role at fault and never echoes the offending characters, since
+  a value failing the one-character rule can be arbitrary caller text and the message reaches logs.
+
+  The invariant both halves are held against is the one #21 and #22 established: **a round-trip never
+  silently loses a field, in either direction.** The property is asserted by round-tripping through the
+  real parser, not by inspecting the serializer.
+
+  `AstmSerializeError.code` widens from a single string literal to a two-member union, exported as the
+  new `AstmSerializeErrorCode` type. `ASTM_EMIT_UNENCODABLE_VALUE` is unchanged.
+
+- **`parseAstmRecords` now reads the delimiters from every `H` record, not only the first, so a
+  stream carrying more than one message no longer silently loses fields** (`ASTM-SECOND-HEADER-COLLAPSE`;
+  shipped `0.0.1` through `0.0.3`, `PRE-EXISTING`, not a regression). This is the same silent field
+  collapse as `ASTM-MIXED-DELIMITER-EMIT` one layer over, on the **parse** side, which is why #21 did
+  not narrow it: #21 fixed what we write, and a stream arriving with two headers is mis-read on the
+  way **in**, before any of that runs.
+
+  A message runs `H` … `L`, so one stream may carry several back to back and each header declares the
+  delimiters for the records that follow it. Delimiters were read only from `records[0]` and applied
+  to the whole stream, so every record after a redeclaring header **collapsed into a single field,
+  with zero warnings**, and `{ strict: true }` accepted it. Measured by execution on `dc09a3a` before
+  the fix: in a two-message stream whose second header declared `*~:#`, the second result — value
+  `99.9`, units `mmol/L`, abnormal flag `H`, status `F` — came back with `value`, `units`, `flag` and
+  `resultStatus` **all absent** and `status` reading `unspecified`. On the analyzer↔LIS path that is a
+  lost result with no signal to the caller.
+
+  **The decision, and its grounding.** Delimiters are now scoped **forward from each header**: a later
+  `H` governs itself and the records after it, until the next `H`. The asymmetry with the emit bug is
+  real — on emit the library was corrupting its own output, so re-encoding was unambiguously safe,
+  whereas on parse the bytes are the sender's and a second `H` is legal. What settles it is that
+  forward scoping is the **only** reading that never reinterprets bytes already consumed: records
+  before a redeclaration keep the set they were read with, so the two sets never disagree about the
+  same bytes. "First header wins forever" is the collapse itself; "last header wins retroactively"
+  would require re-reading records already delivered.
+
+  **Evidence, labelled.** The message unit is `H` … `L` — _verified primary_: LIS02-A2 §2 makes the
+  message a **bounded unit**, one record type opening it and another closing it, which is why a second
+  `H` begins a new message rather than corrupting the current one. Read directly in CLSI's own free
+  sample of the document. (Stated in our own words on purpose. We may read and cite the standard but
+  never reproduce its prose, and `CHANGELOG.md` ships inside the npm tarball — an earlier draft of
+  this entry quoted the clause verbatim and was caught in review.) That a header may follow a
+  terminator to start another message — _verified secondary_, two independent restatements of the
+  terminator clause (Roche cobas b 121 ASTM interface description; Genaux, _Introduction to ASTM
+  Message Formats_, 2024).
+  That a header's delimiters govern "the message" — _verified secondary_ (Genaux; Stratford Software
+  interface spec), which leans per-message but **does not address a redeclaration that changes the
+  set**. **We could not reach the normative text on that specific question**: LIS02-A2 §5.4
+  (Delimiters) and §6.2 (Delimiter Definition) are precisely the clauses withheld from the free
+  sample, and E1394-97 and LIS01-A2 stayed paywalled. So the forward-scoping rule is recorded as a
+  **reasoned choice, not a citation** — no clause number is claimed for it, and we do not assert the
+  standard is silent either, because that would need the same evidence.
+
+  The OSS reference corpus cannot ground this one and is reported as a negative result rather than
+  dressed up: `kxepal/python-astm` and `senaite.astm` both hardcode `|\^&` as module constants, never
+  read the header's declaration at all, and neither tracks `H` … `L` boundaries — so differential
+  testing against them is uninformative here.
+
+  **Behaviour.** A redeclaration that **changes** the set is honored and raises
+  `ASTM_RECORD_DELIMITERS_REDECLARED`. A header that merely **restates** the set in force is a no-op
+  and raises nothing — several messages in one delimiter set is an ordinary shape, and warning on it
+  would be noise. A later header whose declaration is **unusable** (too short, or a field separator
+  that also names another role) keeps the set already in force and raises
+  `ASTM_RECORD_UNREADABLE_REDECLARATION`; a set is never guessed and no record is dropped. The same
+  condition on the _first_ header remains the `ASTM_RECORD_UNDECLARED_DELIMITERS` fatal — there is no
+  earlier set to fall back to, and that is pinned by a test so it cannot be softened by accident.
+
+  **Surface.** Two new stable warning codes (`ASTM_RECORD_DELIMITERS_REDECLARED`,
+  `ASTM_RECORD_UNREADABLE_REDECLARATION`) with `delimitersRedeclared` / `unreadableRedeclaration`
+  factories, both **safety-critical** by the profile gate's default-deny rule, so no profile can quiet
+  them (asserted). `HeaderRecord.delimiters` now reports the set **that** header put into force rather
+  than always the first header's; `AstmMessage.delimiters` is unchanged and stays the first header's.
+  The sites that _stated_ the old single-header rule were swept — the `parseAstmRecords` JSDoc, the
+  module header, `HeaderRecord`/`AstmMessage` type docs, `readDelimiters` (whose doc comment said the
+  caller escalates an unusable declaration to the fatal, true only of the first header now), and
+  `docs-content/quickstart.md` — because on #21 the refuter's first pass was refused for exactly the
+  opposite failure: correct code shipped behind documentation that steered consumers the wrong way.
+  The `readDelimiters` comment also said it returns `{ ok: false }` when it has always returned
+  `undefined`; that was already wrong before this slice and is corrected in the same paragraph.
+
+  **Deliberately left for their own slices** (both recorded with this item, both **emit**-side, and
+  both turning on questions this one does not answer): a delimiter declaration **longer than three
+  characters** still loses its extra bytes on emit — what a fourth declaration byte even means is
+  unresolved by the same withheld clauses — and `serializeAstmRecords(msg, d)` still does **not
+  validate a caller-supplied `d`**, so a malformed set emits a stream this library's own parser then
+  rejects or mis-reads, with no typed error. Neither is touched here; folding an emit-side change into
+  a parse-side fix would have widened the diff without answering either question.
+
+  **Strict-mode boundary, disclosed as a sample and not a census.** Measured base-build vs head-build
+  over 216,699 synthetic streams (the 11 repo fixtures, 464 single-header streams, and multi-header
+  pairs across a sampled sweep of delimiter sets): **394 moved accepted→rejected, 0 the other way.**
+  All 11 fixtures and all 464 single-header streams were **unchanged**, in strict mode and in their
+  lenient warning lists — which matches the code path, since the new warnings can only be raised at an
+  `H` record that is not `records[0]`.
+
+- **`serializeAstmRecords` no longer emits a mixed-delimiter stream that silently loses fields on the
+  next read** (`ASTM-MIXED-DELIMITER-EMIT`; shipped since `0.0.1`, `PRE-EXISTING`, not a regression).
+  Emit normalized the header to the canonical `H|\^&` set but re-emitted `M` (manufacturer) and `S`
+  (scientific) records byte-for-byte from `rawLine`. For a message that arrived under a vendor
+  delimiter set the output was therefore **non-conformant**: a canonical header above `M`/`S` rows
+  still written in the original delimiters. Re-parsing that output **collapsed every field of those
+  rows into one, with zero warnings** — on the analyzer↔LIS path, a lost result or a lost
+  patient/specimen identifier with no signal to the caller. Verified by execution before and after,
+  not by inspection: a five-field `M` row round-tripped to one field.
+
+  **The semantics chosen, and why.** The two candidates were to re-encode every record to the
+  delimiters the header declares, or to refuse/warn on a message whose records disagree.
+  **Re-encoding was chosen.** It is what the serializer already promises — one spec-clean stream in
+  the declared set — and a mixed-delimiter stream is not spec-clean. Emit returns a `string` and has
+  no warning channel, so a warning could only have been ignored while the corrupt stream still
+  shipped, and a refusal would have rejected messages this library successfully parsed, a harder
+  break on a published package. The invariant that had to hold either way is that **a round-trip
+  never silently loses a field, in either direction**; it is now pinned by a property over arbitrary
+  declared delimiter sets, which fails against the old code. `M`/`S` are reproduced byte-for-byte
+  **only when a reader using the emit delimiters would recover exactly the fields the record models**,
+  so bytes change for exactly the streams that were being corrupted and for no others. The reasoning
+  is recorded at the site in `src/records/serialize.ts`.
+
+- **Editing a modeled `H` field and re-serializing no longer silently keeps the original value**
+  (`PRE-EXISTING`, found in the same pass). The header was emitted by re-tokenizing its preserved
+  `rawLine`, so the model was bypassed on emit. It is now emitted from `HeaderRecord.fields` like
+  every other record type. The delimiter declaration itself is still never taken from the model — it
+  always states the delimiters actually being emitted with, because a declaration that disagrees with
+  the records around it is the very corruption above.
+
+- **`HeaderRecord.fields` now holds the header's real fields.** The generic escape-aware tokenizer
+  reads the escape character sitting _literally_ inside the delimiter declaration as an unterminated
+  escape and swallows the remainder of the record, so a canonical header modeled as **two** fields
+  (`H` and everything else merged) instead of one per field. A header-aware `tokenizeHeader` takes the
+  declaration verbatim as one opaque field and tokenizes the data portion normally; it is exported
+  alongside `tokenizeRecord`. This is what made emitting the header from its model possible.
+
+  **A `strict` consumer will observe one side effect, stated rather than left to be discovered.**
+  The old tokenizer read the declaration's literal escape char as an unterminated escape and raised a
+  spurious `ASTM_UNKNOWN_ESCAPE_SEQUENCE` on some headers, which `{ strict: true }` rejected. Those
+  warnings are gone, so a few messages that previously threw now parse. Measured over ~40,000
+  differential messages: 1,176 moved from rejected to accepted, **0** moved the other way, and every
+  warning delta is confined to `recordIndex 0` — no warning on any other record is added or dropped.
+
+  Three `PRE-EXISTING` neighbours were found while grading this and are deliberately **not** fixed
+  here, to keep the slice the size of its item: `parseAstmRecords` reads delimiters only from the
+  first header, so a **second `H` mid-stream that redeclares them** still yields the same silent
+  field collapse (parse-side, not emit-side — the emitter faithfully reproduces what parse modeled)
+  — **since fixed, see the parse-side entry above**;
+  a delimiter declaration longer than three characters silently loses its extra bytes on emit; and
+  `serializeAstmRecords(msg, d)` does not validate a caller-supplied `d`, so a malformed set (a
+  multi-char delimiter, an empty escape, a `field`/`escape` collision) emits a stream this library's
+  own parser then rejects or mis-reads, with no typed error.
+
+- **The type documentation shipped in `dist/index.d.ts` no longer understates the library.** The
+  entry-point module documentation ended by calling serialize and build deferred, on a tree that exports
+  `serializeAstmRecords`, `buildAstmMessage`, `composeAstmFrames` and `serializeFramedAstm`, and the
+  record-types module documentation described only `H`/`P`/`O`/`R`/`L` as modeled, naming
+  result-flag/status semantics, comment, query, `M`/`S`, framing and serialization as still to come,
+  when all of them are modeled. Both
+  blocks are carried verbatim in `dist/index.d.ts` and `dist/index.d.cts`, which is what an installer
+  receives. (They are module-level blocks that bind to no exported symbol, so they sit in the
+  declaration text rather than in any symbol's editor tooltip.) Every affected block now describes
+  what the code does. 18 source files changed; no runtime behaviour, export, type or warning code is
+  affected.
+- **The fatal-error taxonomy is now accurate about what `err.code` can hold.** `FATAL_CODES`
+  documented itself as later growing the frame codec's own `ASTM_FRAME_*` fatals. `FatalCode` is a
+  closed three-value union and the frame codec does not widen it: it reuses `EMPTY_INPUT` for an
+  empty stream, and its own thrown errors are separate types with their own discriminants
+  (`AstmFrameEncodeError` carries `ASTM_FRAME_EMPTY_RECORD`; `AstmFrameStrictError` carries the
+  rejected warnings rather than a `code`). Narrowing an `AstmParseError` on `code` will only ever
+  see one of the three.
+- **The serializer's round-trip note now names the cases that do not round-trip.** It claimed
+  serialization emits from the decoded component tree. Three record types do not: `H`, `M` and `S`
+  are emitted from their preserved `rawLine`, so an edit to their modeled `fields` is silently not
+  reflected on emit -- editing a header field and re-serializing keeps the original value, with no
+  warning. `M`/`S` additionally keep whatever delimiters they arrived with, so a non-canonical
+  `M`/`S` row does not come back as separate fields. Normalization to `H|\^&` is also skipped when a
+  delimiter set is passed explicitly. All of it is now stated next to the round-trip claim it
+  bounds, and `serializeAstmRecords` gained the `@param d` its siblings already had.
+
 - **The published documentation sidebar now follows the shared section order.** The shipped
   `docs-content/sidebars.json` carried a category named "About" holding the "what it does and does not
   do" page. That label is not one of the sections the documentation site recognises (Overview,

package/README.md

@@ -32,7 +32,9 @@ reference parser, [`@cosyte/hl7`](https://github.com/cosyte/hl7).
 - **Emit.** `serializeAstmRecords` and `buildAstmMessage` emit canonical `H|\^&` records with embedded
   delimiters re-escaped and nothing clinical fabricated; `composeAstmFrames` and `serializeFramedAstm`
   frame them with computed checksums, frame numbers, and the 240-byte split. Both layers round-trip by
-  construction.
+  construction, and a delimiter set that fails any of the three conditions readback requires — one
+  character per separator, no `CR`/`LF`, no two the same — is a typed error rather than bytes written
+  and lost.
 - **Vendor profiles.** `defineAstmProfile()` builds a provenance-backed profile whose tolerances
   downgrade _expected_, non-safety-critical deviations to a `PROFILE_QUIRK_APPLIED` warning without
   ever altering a value, behind a definition-time safety gate that refuses to tolerate any result
@@ -133,6 +135,36 @@ produce a confident wrong value: an embedded escaped delimiter reads as one comp
 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.
 
+### Several messages in one stream
+
+A message runs from its `H` header to its `L` terminator, so a stream can carry several. `messages()`
+splits a parsed stream into them, and each entry carries only its own records — so a patient is only
+ever paired with the results that message actually carried:
+
+```ts
+import { parseAstmRecords, messages } from "@cosyte/astm";
+
+for (const m of messages(parseAstmRecords(raw))) {
+  m.patient?.practiceAssignedId; // the P for THIS message
+  m.results; // the Rs for THIS message
+  m.delimiters; // the set THIS message's records were read with
+}
+```
+
+The flat accessors above (`patient`, `results`, `orders`, `comments`, `query`) read the whole stream,
+so they **throw** `AstmAmbiguousStreamError` on a stream they cannot answer for rather than answering
+across patients:
+
+- `ASTM_AMBIGUOUS_MULTI_MESSAGE` from any of the five, when the stream carries more than one message.
+- `ASTM_AMBIGUOUS_MULTI_PATIENT` from `patient()` only, when a **single** message carries more than
+  one `P` record. "The first `P`" is a guess about whose result it is, so it is refused there too.
+
+**Both are breaking**, and the second one reaches single-message callers: a lone message carrying
+several patients used to answer with the first of them. A stream that is one message with at most one
+patient is unchanged, and so is a result-only message with no `P` at all, which still answers
+`undefined`. `commentsFor()` is unchanged on every stream, because the parent record you hand it
+already names the message.
+
 ## 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