@cosyte/astm 0.0.7 → 0.0.8

package/CHANGELOG.md

@@ -129,6 +129,73 @@ phase 8` passes while `Phase 8` reds). An arm keyed on a following digit was wri
 
 ### Changed
 
+- **BREAKING: a profile may no longer tolerate `ASTM_RECORD_UNKNOWN_TYPE`**
+  (`ASTM-UNKNOWN-RECORD-REMERGE`). The code moves off the profile safety gate's tolerable
+  allow-list and onto the safety-critical set, so `defineAstmProfile({ tolerate: [...] })` naming
+  it now throws `AstmProfileDefinitionError` at definition time instead of building a profile, and
+  the gate is re-checked when a warning would be downgraded, so a profile assembled as a plain
+  object rather than through the factory gets the same answer (it declines to downgrade rather than
+  throwing, so a hand-authored profile still parses, it just cannot quiet a safety-critical code).
+  `TOLERABLE_CODES` goes from four members to three (`ASTM_NONSTANDARD_DELIMITERS`,
+  `ASTM_UNKNOWN_ESCAPE_SEQUENCE`, `ASTM_RECORD_UNINTERPRETED_QUERY_STATUS`) and
+  `SAFETY_CRITICAL_CODES` / `isSafetyCriticalCode()` answer accordingly. No built-in profile
+  tolerated the code, so nothing in this package changes shape; a consumer profile that named it
+  will now fail to define, loudly, at the point of definition.
+
+  **Why, and it is a wrong-patient path.** A message runs from an `H` header to its `L`
+  terminator, and `messages()` decides where one starts by reading each record's **type letter**.
+  A header the reader cannot recognize as a header (one carrying a stray leading byte, for
+  instance) is surfaced as an unsupported record, opens no message, and the two messages either
+  side of it are grouped as one. The merged message pairs a patient with results that arrived
+  under a different header. The `ASTM_RECORD_UNKNOWN_TYPE` warning is the entire report that this
+  happened, so a profile downgrading it to `PROFILE_QUIRK_APPLIED` quieted the whole signal, and a
+  `{ strict: true }` parse then accepted the stream with no objection at all.
+
+  **The type letter turned out to have two load-bearing readers, not one.** `classifyMessage`
+  counts `Q` / `R` / `O` records by the same letter, and the rule that a message carrying a query
+  is never read as a result set is stated on that count. An unrecognized `Q` costs a host-query
+  request that guarantee: the message reads as `kind: "results"`, and the
+  `ASTM_RECORD_AMBIGUOUS_MESSAGE_KIND` warning that flags a query-plus-result contradiction
+  disappears along with the `Q` it was counting. There too `ASTM_RECORD_UNKNOWN_TYPE` is the only
+  warning left on the stream. Both readers are measured in the regression test. The
+  mis-classification itself is not fixed here, for the same reason the merge is not: it is a
+  property of reading the letter, and inferring the intended letter is the guess this package
+  declines to make.
+
+  **The variant that reaches furthest carries no second patient.** When the merged second message
+  has its own `P`, the merged message holds two and the multi-patient guard throws. When the
+  second message is **result-only**, the merged message still holds exactly one `P`, so `patient()`
+  and `results()` both answer confidently and the first patient silently acquires the second
+  message's results. That is the fixture the regression test pins.
+
+  **The parser is deliberately unchanged.** Recognizing a mangled header _as_ a header means
+  guessing at a byte the sender did not send, and that guess would split a stream a different way
+  just as silently. A lenient parse still merges and still warns; a strict parse refuses; and the
+  refusal can no longer be configured away. `messages()`, the warning's own message text, the
+  `UnsupportedRecord` type, the README and the quickstart all now say to read this code as a
+  possible lost message boundary rather than as cosmetic noise.
+
+  **The admission test for the allow-list gained a second clause**, which is the durable part of
+  this change. A code was admitted on one question: can it alter, drop, or fabricate an extracted
+  value? `ASTM_RECORD_UNKNOWN_TYPE` still passes that one, and it was still wrong to tolerate,
+  because the condition it reports had quietly become something the library reads. The rule is now
+  that a code is tolerable only while **nothing else in this package reads the condition the
+  warning reports**, and that second clause is a claim about the whole library which can stop being
+  true without anyone editing `safety.ts`. It is a review obligation, not a mechanical check, and
+  the file says so rather than implying a gate that does not exist. The three surviving codes were
+  each re-derived against both readers of record structure, and each is measured by comparing the
+  same logical stream with the reported condition present and absent. That is deliberately not a
+  comparison of a parse with a profile against one without: the profile transform runs after the
+  records are built, so the second comparison is identical for every code and would have passed for
+  the one just removed. The comparison actually used is exercised on the mangled-header pair as a
+  negative control, where it has to fail.
+
+  **Evidence, labelled.** The `H` … `L` message unit is _verified primary_ and its grounding is
+  recorded on `messages()`, unchanged here. The allow-list itself is **this library's own policy,
+  not the standard's**: no clause governs which of our warning codes a profile may downgrade, and
+  none is claimed for it. The behaviour above (the merge, the accessors answering, the strict
+  acceptance under a tolerating profile) is _measured_, on the tree before and after the change.
+
 - **The em dash (U+2014) is gone from every tracked file, and a CI gate keeps it out**
   (`EMDASH-CONFORMANCE`). The brand rule bans the character outright across every cosyte surface
   and names commit messages explicitly; this package was the last one it had not reached, and the

package/README.md

@@ -42,11 +42,14 @@ reference parser, [`@cosyte/hl7`](https://github.com/cosyte/hl7).
   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
-  value, flag, status, range, or units warning, any patient or comment context, any message-kind
-  ambiguity, and any frame or transport integrity warning. A profile can never make a bad checksum
-  "ok" or a cancelled result read "final." Named per-vendor profiles await a public,
-  vendor-attributed quirk document.
+  ever altering a value, behind a safety gate that refuses to tolerate any result value, flag,
+  status, range, or units warning, any patient or comment context, any message-kind ambiguity, any
+  unrecognized record type, and any frame or transport integrity warning. The gate runs when a
+  profile is defined **and** again when a warning would be downgraded, so a profile assembled as a
+  plain object rather than through `defineAstmProfile()` gets the same answer. A profile can never
+  make a bad checksum "ok", a cancelled result read "final", or quiet the warning that says a
+  message boundary went unrecognized. Named per-vendor profiles await a public, vendor-attributed
+  quirk document.
 - **Terminology, bring your own.** `applyLivd(msg, catalog)` maps an analyzer's local test code to a
   LOINC from a consumer-supplied IICC LIVD catalog as an additive, advisory annotation that never
   mutates the raw code or value and never guesses a LOINC. No LOINC, SNOMED, or LIVD dictionary is
@@ -170,6 +173,18 @@ patient is unchanged, and so is a result-only message with no `P` at all, which
 `undefined`. `commentsFor()` is unchanged on every stream, because the parent record you hand it
 already names the message.
 
+Splitting reads each record's type letter, so check for an `ASTM_RECORD_UNKNOWN_TYPE` warning before
+you trust the split. A header the reader does not recognize as a header, one carrying a stray leading
+byte for instance, opens no message, and the messages either side of it merge back into one, so a
+patient can end up holding results that arrived under a different header. Delimiters are re-read at
+each header too, so if the unrecognized one declared a different set, the records after it are read
+with the previous set and their fields can be lost rather than merely misfiled. The
+parser warns on that record and a `{ strict: true }` parse refuses the stream. That warning is the
+only report the merge produces, so a profile is not allowed to tolerate it: the code is refused when
+a profile is defined, and a warning carrying it is not downgraded whatever profile is in force. Do
+not gate on the warning count, though, because the records that merged in can raise warnings of
+their own.
+
 ## 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

package/dist/index.cjs

@@ -121,7 +121,11 @@ function primaryCode(u) {
 
 // src/common/warnings.ts
 var WARNING_CODES = {
-  /** A record's type letter is not one of the modeled types: surfaced as an unsupported record. */
+  /**
+   * A record's type letter is not one of the modeled types: surfaced as an unsupported record,
+   * never dropped. Treat it as a possible lost message boundary, because a header the reader did
+   * not recognize as one does not open a new message.
+   */
   ASTM_RECORD_UNKNOWN_TYPE: "ASTM_RECORD_UNKNOWN_TYPE",
   /** The header declared delimiters other than the canonical `H|\^&`: tolerated, noted. */
   ASTM_NONSTANDARD_DELIMITERS: "ASTM_NONSTANDARD_DELIMITERS",
@@ -214,7 +218,7 @@ var WARNING_CODES = {
 function unknownRecordType(position) {
   return {
     code: WARNING_CODES.ASTM_RECORD_UNKNOWN_TYPE,
-    message: "Unrecognized record type, surfaced verbatim as an unsupported record.",
+    message: "Unrecognized record type, surfaced verbatim as an unsupported record. If this record was a header, message grouping did not open a new message here.",
     position
   };
 }
@@ -427,6 +431,135 @@ function classifyMessage(records) {
   return { kind, hasQuery, hasResults, hasOrders, isHostQueryRequest: kind === "host-query" };
 }
 
+// src/frames/warnings.ts
+var 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.
+   */
+  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.
+   */
+  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`).
+   */
+  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`).
+   */
+  ASTM_FRAME_OVERSIZE: "ASTM_FRAME_OVERSIZE"
+};
+function frameBadChecksum(position) {
+  return {
+    code: FRAME_WARNING_CODES.ASTM_FRAME_BAD_CHECKSUM,
+    message: "Frame checksum mismatch, surfaced untrusted, never merged into a record.",
+    position
+  };
+}
+function frameSequenceGap(position) {
+  return {
+    code: FRAME_WARNING_CODES.ASTM_FRAME_SEQUENCE_GAP,
+    message: "Frame number out of sequence, possible dropped frame, never silently bridged.",
+    position
+  };
+}
+function frameUnterminated(position) {
+  return {
+    code: FRAME_WARNING_CODES.ASTM_FRAME_UNTERMINATED,
+    message: "Unterminated frame, partial bytes surfaced untrusted, no partial record invented.",
+    position
+  };
+}
+function frameOversize(position) {
+  return {
+    code: FRAME_WARNING_CODES.ASTM_FRAME_OVERSIZE,
+    message: "Frame text exceeded the 240-byte limit without a split, flagged, never dropped.",
+    position
+  };
+}
+
+// src/ltp/warnings.ts
+var 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.)
+   */
+  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.
+   */
+  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.
+   */
+  ASTM_LTP_FRAME_REJECTED: "ASTM_LTP_FRAME_REJECTED"
+};
+function ltpAmbiguousTransport() {
+  return {
+    code: LTP_WARNING_CODES.ASTM_LTP_AMBIGUOUS_TRANSPORT,
+    message: "Leading byte was neither a frame start (STX/ENQ) nor a record letter, defaulted to framed; override with a profile to force raw."
+  };
+}
+function ltpUnexpectedEvent(frameNumber) {
+  return {
+    code: LTP_WARNING_CODES.ASTM_LTP_UNEXPECTED_EVENT,
+    message: "Control event arrived in a state that did not expect it, handled defensively, never read as acceptance.",
+    ...frameNumber !== void 0 ? { frameNumber } : {}
+  };
+}
+function ltpFrameRejected(frameNumber) {
+  return {
+    code: LTP_WARNING_CODES.ASTM_LTP_FRAME_REJECTED,
+    message: "Frame rejected (bad checksum, unterminated, or out of sequence), NAK sent, retransmit expected, never accepted.",
+    ...frameNumber !== void 0 ? { frameNumber } : {}
+  };
+}
+
+// src/profiles/safety.ts
+var TOLERABLE_CODES = Object.freeze(
+  /* @__PURE__ */ new Set([
+    WARNING_CODES.ASTM_NONSTANDARD_DELIMITERS,
+    WARNING_CODES.ASTM_UNKNOWN_ESCAPE_SEQUENCE,
+    WARNING_CODES.ASTM_RECORD_UNINTERPRETED_QUERY_STATUS
+  ])
+);
+var ALL_WARNING_CODES = [
+  ...Object.values(WARNING_CODES),
+  ...Object.values(FRAME_WARNING_CODES),
+  ...Object.values(LTP_WARNING_CODES)
+];
+var ALL_ASTM_WARNING_CODES = Object.freeze(
+  new Set(ALL_WARNING_CODES)
+);
+var SAFETY_CRITICAL_CODES = Object.freeze(
+  new Set(ALL_WARNING_CODES.filter((c) => !TOLERABLE_CODES.has(c)))
+);
+function isSafetyCriticalCode(code) {
+  return SAFETY_CRITICAL_CODES.has(code);
+}
+
 // src/profiles/apply.ts
 function toleranceApplies(tolerance, warning) {
   if (tolerance.code !== warning.code) return false;
@@ -442,6 +575,7 @@ function toleranceApplies(tolerance, warning) {
 }
 function applyAstmProfile(profile, warning) {
   if (warning.expected === true) return warning;
+  if (isSafetyCriticalCode(warning.code)) return warning;
   for (const tolerance of profile.tolerate) {
     if (toleranceApplies(tolerance, warning)) {
       return profileQuirkApplied(warning, profile.name);
@@ -563,136 +697,6 @@ var AstmProfileDefinitionError = class extends Error {
   }
 };
 
-// src/frames/warnings.ts
-var 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.
-   */
-  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.
-   */
-  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`).
-   */
-  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`).
-   */
-  ASTM_FRAME_OVERSIZE: "ASTM_FRAME_OVERSIZE"
-};
-function frameBadChecksum(position) {
-  return {
-    code: FRAME_WARNING_CODES.ASTM_FRAME_BAD_CHECKSUM,
-    message: "Frame checksum mismatch, surfaced untrusted, never merged into a record.",
-    position
-  };
-}
-function frameSequenceGap(position) {
-  return {
-    code: FRAME_WARNING_CODES.ASTM_FRAME_SEQUENCE_GAP,
-    message: "Frame number out of sequence, possible dropped frame, never silently bridged.",
-    position
-  };
-}
-function frameUnterminated(position) {
-  return {
-    code: FRAME_WARNING_CODES.ASTM_FRAME_UNTERMINATED,
-    message: "Unterminated frame, partial bytes surfaced untrusted, no partial record invented.",
-    position
-  };
-}
-function frameOversize(position) {
-  return {
-    code: FRAME_WARNING_CODES.ASTM_FRAME_OVERSIZE,
-    message: "Frame text exceeded the 240-byte limit without a split, flagged, never dropped.",
-    position
-  };
-}
-
-// src/ltp/warnings.ts
-var 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.)
-   */
-  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.
-   */
-  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.
-   */
-  ASTM_LTP_FRAME_REJECTED: "ASTM_LTP_FRAME_REJECTED"
-};
-function ltpAmbiguousTransport() {
-  return {
-    code: LTP_WARNING_CODES.ASTM_LTP_AMBIGUOUS_TRANSPORT,
-    message: "Leading byte was neither a frame start (STX/ENQ) nor a record letter, defaulted to framed; override with a profile to force raw."
-  };
-}
-function ltpUnexpectedEvent(frameNumber) {
-  return {
-    code: LTP_WARNING_CODES.ASTM_LTP_UNEXPECTED_EVENT,
-    message: "Control event arrived in a state that did not expect it, handled defensively, never read as acceptance.",
-    ...frameNumber !== void 0 ? { frameNumber } : {}
-  };
-}
-function ltpFrameRejected(frameNumber) {
-  return {
-    code: LTP_WARNING_CODES.ASTM_LTP_FRAME_REJECTED,
-    message: "Frame rejected (bad checksum, unterminated, or out of sequence), NAK sent, retransmit expected, never accepted.",
-    ...frameNumber !== void 0 ? { frameNumber } : {}
-  };
-}
-
-// src/profiles/safety.ts
-var TOLERABLE_CODES = Object.freeze(
-  /* @__PURE__ */ new Set([
-    WARNING_CODES.ASTM_RECORD_UNKNOWN_TYPE,
-    WARNING_CODES.ASTM_NONSTANDARD_DELIMITERS,
-    WARNING_CODES.ASTM_UNKNOWN_ESCAPE_SEQUENCE,
-    WARNING_CODES.ASTM_RECORD_UNINTERPRETED_QUERY_STATUS
-  ])
-);
-var ALL_WARNING_CODES = [
-  ...Object.values(WARNING_CODES),
-  ...Object.values(FRAME_WARNING_CODES),
-  ...Object.values(LTP_WARNING_CODES)
-];
-var ALL_ASTM_WARNING_CODES = Object.freeze(
-  new Set(ALL_WARNING_CODES)
-);
-var SAFETY_CRITICAL_CODES = Object.freeze(
-  new Set(ALL_WARNING_CODES.filter((c) => !TOLERABLE_CODES.has(c)))
-);
-function isSafetyCriticalCode(code) {
-  return SAFETY_CRITICAL_CODES.has(code);
-}
-
 // src/profiles/validate.ts
 var KNOWN_OPTION_KEYS = [
   "name",
@@ -772,7 +776,7 @@ function validateTolerations(tolerate, profileName) {
     }
     if (isSafetyCriticalCode(t.code)) {
       throw new AstmProfileDefinitionError(
-        `Profile '${profileName}' may not tolerate '${t.code}': it is a safety-critical warning code (a result value / flag / status / range / units, patient or comment context, message-kind ambiguity, code system, or a frame / LTP integrity warning). A profile quiets benign structural noise, never a deviation that could change a clinical reading or corrupt the wire: it can never make a bad checksum "ok" or a cancelled result read "final."`,
+        `Profile '${profileName}' may not tolerate '${t.code}': it is a safety-critical warning code (a result value / flag / status / range / units, patient or comment context, message-kind ambiguity, code system, an unrecognized record type, or a frame / LTP integrity warning). A profile quiets benign structural noise, never a deviation that could change a clinical reading, report a lost message boundary, or corrupt the wire: it can never make a bad checksum "ok", a cancelled result read "final", or quiet the warning that says two messages were read as one.`,
         profileName
       );
     }
@@ -2199,7 +2203,7 @@ function concatBytes3(chunks) {
 }
 
 // src/index.ts
-var VERSION = "0.0.7";
+var VERSION = "0.0.8";
 
 exports.ALL_ASTM_WARNING_CODES = ALL_ASTM_WARNING_CODES;
 exports.AMBIGUOUS_CODES = AMBIGUOUS_CODES;