@cosyte/astm 0.0.13 → 0.0.15

package/CHANGELOG.md

@@ -11,6 +11,123 @@ this file is maintained by hand (Changesets handles the version bump and publish
 
 ### Fixed
 
+- **The escape encoder protected the escape character it introduced but not the `E`/`F`/`S`/`R`
+  mnemonics, so a delimiter set naming one of those letters in another role altered the values it
+  emitted** (`ASTM-FRAME-RESIDUALS` follow-up, defect 12). `PRE-EXISTING`, byte-identical on
+  `4bb62f1`. `encodeLeaf` ran as four chained whole-string substitutions (escape, then field,
+  component, repeat), and each pass could see what the previous ones had written. Going first
+  protected the escape character; nothing protected the mnemonic letters. Under
+  `{ field: "E", escape: "R" }` a leaf of `R` went out as `RRFRR` and read back as `RER`.
+
+  **Re-measured here rather than carried over, because the recorded figures came from a sweep whose
+  parameters were not written down.** Over the whole four-role space drawn from the 18-character
+  alphabet `|` `\` `^` `&` `E` `F` `S` `R` `*` `~` `:` `#` `+` `@` `!` `$` `%` `/` (the four
+  canonical delimiters, the four mnemonic letters, a common vendor set, neutral punctuation), that is
+  P(18,4) = 73,440 sets, against **exactly the `STREAM` constant in
+  `test/records/escape-mnemonic-roles.test.ts`**, a synthetic ten-record
+  `H`/`P`/`O`/`R`/`R`/`R`/`C`/`M`/`S`/`L` message that parses with `warnings: []`, the serializer
+  refused 23,040 and accepted **50,400**. Of those, **10,450** emitted
+  a stream this library re-read with a **different field tree**, and **9,287** reported nothing
+  outside `TOLERABLE_CODES`, so a gate-legal profile plus `{ strict: true }` accepted an altered
+  value.
+
+  **The "0 silent" reading is confirmed and is weaker than it looks, which is worth more than the
+  number.** Zero of the 10,450 re-parsed with `warnings: []`, but a non-canonical set always reports
+  `ASTM_NONSTANDARD_DELIMITERS`, and that code is itself tolerable, so `warnings: []` was never
+  reachable for any set that could exhibit this defect. Silence was not available as a measure here.
+  The tier that does discriminate is the strict-accepted one above.
+
+  **The fix is one left-to-right pass.** Each character is read once and written either as itself or
+  as a whole `escape` + mnemonic + `escape` triple, and nothing the encoder writes is examined again,
+  which makes it the **exact** inverse of `decodeEscapes` rather than approximately so. No accepted
+  set in that sweep diverges after it. Bytes change for **exactly** the 10,450 sets that were
+  diverging and for no others (measured both directions: 0 sets diverged with unchanged bytes, 0 sets
+  changed bytes without having diverged), so a canonical stream and any set naming none of the four
+  mnemonic letters is byte-identical. The accept/refuse partition is unchanged over all 73,440 sets:
+  `ASTM_EMIT_TYPE_LETTER_COLLISION` reads the first character actually written, so it needed no
+  change when the encoder underneath it did, which is the argument for testing bytes rather than
+  enumerating dangerous roles. **No clause is claimed**: the grounding is this package's own decoder.
+
+  Pinned in `test/records/escape-mnemonic-roles.test.ts`, which transcribes the four chained
+  substitutions (nothing shipped still reproduces them) and **checks that transcription against the
+  shipped encoder on all 1,680 sets where the two must agree**, so it cannot decay into a strawman.
+  8 of its assertions are red against a `git archive` of `4bb62f1`. Five of them pin the **emitted bytes as literals**, each derived in a comment rather than snapshotted, because every other assertion here reads the stream back through this package's own parser and so cannot see an encoder and decoder that agree with each other and are both wrong. The committed test pins a
+  12-character subspace (P(12,4) = 11,880) rather than the 18, because the full space costs about a
+  minute of suite time and the extra six characters are neutral punctuation already represented. The
+  corpus is the same in both: the 73,440-set figures above differ from the test's only by alphabet. The claim in
+  `test/records/type-letter-collision.test.ts` that a type letter equal to the escape character
+  "does not always encode as letter + E + letter" was pinned to `RRFRR`/`RRSRR` and is now false:
+  it encodes that way for every set, and the assertion was updated to say so rather than deleted.
+
+- **`composeAstmFrames` wrote an out-of-range `startFrameNumber` straight into the frame-number
+  position, so a value that was not a frame number produced a stream whose records the decoder
+  refused to emit** (`ASTM-FRAME-RESIDUALS`, defect 13). `PRE-EXISTING`, byte-identical on `64c2fd5`.
+  The option is now checked before `composeAstmFrames` reads a record, and refused with the new code
+  `ASTM_FRAME_INVALID_START_FRAME_NUMBER` (a fourth member of `AstmFrameEncodeErrorCode`) unless it is
+  a whole number from `0` to `7`.
+
+  **What went out instead, measured on this package's own round trip.** A frame's number is one ASCII
+  digit, written as `FN_ZERO + n`, and nothing checked `n`. `-1` put a `/` in the frame-number
+  position, and `NaN`, `Infinity` and `-Infinity` each put a `NUL` there in **every** frame of the
+  stream, after which `decodeAstmFrames` recognised no frame number at all, warned
+  `ASTM_FRAME_SEQUENCE_GAP` on every frame, and emitted **none** of the records: a whole four-record
+  message in, zero out, and `parseFramedAstm` throwing on empty input. **The recorded defect said an
+  out-of-range value writes a non-digit byte and named a space for `NaN`. It is a `NUL`**, which is
+  the difference between an ordinary inter-frame byte the decoder skips and a byte that costs the
+  stream every one of its records.
+
+  **The quieter half is why the check covers the whole domain rather than the ends.** Values that
+  truncated back onto a digit were accepted silently and behaved as some other start value: `1.5` and
+  `257` each produced the byte-for-byte stream a `startFrameNumber` of `1` produces. The option
+  documented `0`-`7` and enforced neither bound nor integrality in either direction.
+
+  **The domain is derived from what a frame can carry, and the refusal is not a clamp.** The writable
+  numbers are exactly the whole numbers `0`-`7`, the modulo-8 sequence `decodeAstmFrames` reads and
+  rolls over. Clamping or taking a modulo would pick a frame number the caller did not ask for, and
+  the frame number is the decoder's only evidence that no frame was dropped, so a stream numbered from
+  a value nobody chose is a stream whose sequence check certifies the wrong thing. The refusal is
+  raised before `composeAstmFrames` reads a record, so on that entry point it never depends on the
+  caller's data (`serializeFramedAstm` serializes every record first, so a record that cannot be
+  serialized at all is refused ahead of it on that route). Its message names the value received: that
+  value is the caller's own option, not stream content, and nothing from the records reaches it.
+
+  **The whole `0`-`7` range is still accepted, because a non-default start has a real use that was
+  measured rather than assumed.** It composes a **continuation** of a transfer already in progress:
+  `composeAstmFrames(head)` joined with `composeAstmFrames(tail, { startFrameNumber: n })`, where `n`
+  is the number after the last frame `head` used, is **byte-identical** to composing the whole list in
+  one call and decodes with an empty warnings array, across the `7 → 0` rollover included. Narrowing
+  the option to `1` would have removed that.
+
+  **What a continuation is not, now stated on the option rather than guarded against.** Read on its
+  own, a stream that starts anywhere but `1` opens on a sequence gap; the decoder never bridges a gap
+  silently, so it warns and does not emit that first record. **What `parseFramedAstm` does after that
+  varies with the message shape, and no rule is offered for it:** it may throw, under more than one
+  code (`ASTM_RECORD_NO_HEADER`, `EMPTY_INPUT` and `ASTM_RECORD_UNDECLARED_DELIMITERS` were each
+  measured), and it may return a message one record short. **The one statement that generalizes is
+  that the record layer never reports the loss**, because `parseFramedAstm` hands the record parser
+  only the frames the codec vouched for, so `message.warnings` carries what the surviving records
+  warrant and nothing about the record that did not survive. Read `frameWarnings`. Nothing returns the number to continue a sequence from either, and the frame count
+  is not it once a record splits, so the supported computation is named on the option. The
+  documented-valid `0` has always behaved that way. It is the cost of the option, not a defect in the
+  caller's records, and it is why `1` is the default.
+
+  **This is a narrowing on a published package, in a small population.** `1.5` and `257` used to
+  produce a working stream, the byte-for-byte start-at-`1` one, and now throw. Every value the check
+  turns away was already outside what the option documented: a frame number, a whole number `0`-`7`.
+
+  Both the old bytes and the new refusal are pinned in `test/frames/start-frame-number.test.ts`,
+  asserted on what the old encoder produced (rebuilt with the test-only `frame()` builder, so nothing
+  is transcribed twice), with a biconditional property: a value is refused **if and only if** it is
+  not a whole number in `0`-`7`. 14 of the 32 new tests are red against `64c2fd5`.
+
+- **Three `{@link}` targets in the published `.d.ts` did not name a symbol declared there**
+  (`ASTM-FRAME-RESIDUALS`, the sibling minors). `QuirkTolerance` is `AstmQuirkTolerance` (twice, in
+  `src/profiles/types.ts`); the `startFrameNumber` doc linked `FIRST_FRAME_NUMBER`, which this
+  package does not export, and that sentence was rewritten and no longer links it; and
+  `AstmMessage.profile` linked a bare `warnings`, meaning its sibling member, which resolves only for
+  a tool that resolves against the enclosing declaration. Every `{@link}` target in
+  `dist/index.d.ts` now names a symbol declared in that file.
+
 - **A delimiter set colliding with a record's type letter emitted a stream that read back as
   DIFFERENT records, and in its silent branch it fabricated a final lab result out of patient
   identifiers** (`ASTM-FRAME-RESIDUALS`, defect 5). `PRE-EXISTING`, byte-identical on `7253098`,
@@ -323,6 +440,34 @@ this file is maintained by hand (Changesets handles the version bump and publish
   that only ever fails is not a gate and one that swallows the status is not one either. **No
   runtime code changed and the built output is identical.**
 
+### Documented
+
+- **A header delimiter-declaration surplus loses all 31 of the C0/`DEL` characters that can reach
+  it, and the published surfaces stated the preservation rule without that exception.**
+  `PRE-EXISTING`; the
+  behaviour is unchanged and argued at `declarationResidual`. What changed is that it is measured,
+  pinned and stated, and that **one of the recorded reasons for it is now known to be false**:
+  "carrying the byte through would turn a spec-clean header into a stream the frame layer refuses"
+  holds for `STX`, `ETX` and `ETB` only. Measured, the other **28 of the 31** round-trip byte-exactly
+  through `composeAstmFrames` into `decodeAstmFrames` with `warnings: []`, and all 31 round-trip at
+  the record layer. The disposition still stands, on the reason the code site actually gives: rather
+  than enumerate the bytes each layer happens to reserve and re-derive that list every time a layer
+  is added, no control character is carried at all. Do not restate the frame-layer reason. Probing one character at a time in the surplus of an otherwise spec-clean
+  `H|\^&` header: **31 of the 33** C0/`DEL` characters reach the rule and are dropped, each with
+  `warnings: []` and no error; the other two are `CR` and `LF`, which end the record while it is being
+  read, so no surplus ever holds them. The drop is **all-or-nothing**, so a surplus of `#` + `US` + `$`
+  loses the `#` and the `$` as well, and that is deliberate: a subsequence of an opaque run whose
+  meaning is unresolved is a different run, not a shorter version of the same one, and choosing which
+  characters to keep is the guess this library declines everywhere else. `docs-content/quickstart.md`
+  attached the control-character drop to the transcoding case alone, which is wrong: it fires on the
+  **default canonical path** too. The `serializeAstmRecords` and `serializeAstmRecord` doc comments
+  and this module's own doc block, all of which compile into the published declarations, stated the
+  preservation rule unqualified. All are
+  widened rather than rewritten, and `docs-content/limitations.md`, which already disclosed the drop,
+  gains the all-or-nothing shape and the count. Pinned in
+  `test/records/declaration-surplus-residual.test.ts`, which passes on `4bb62f1` by design: it
+  measures behaviour this entry does not change.
+
 ### Added
 
 - **`ASTM_RECORD_FIELDS_UNSEPARATED`: a record that lost its fields no longer loses them in

package/README.md

@@ -53,7 +53,13 @@ reference parser, [`@cosyte/hl7`](https://github.com/cosyte/hl7).
   of a frame, framing has no escape sequence for them, and writing one through truncated the frame at
   that byte, silently losing a whole record whenever the two bytes after it happened to be the short
   frame's checksum. The **record** layer still carries them, because a returned string is not yet on a
-  wire and a raw-transport consumer round-trips such a value exactly.
+  wire and a raw-transport consumer round-trips such a value exactly. `startFrameNumber` lets you
+  compose one transfer across several calls, and `composeAstmFrames` checks it before it reads a
+  record: a frame's number is a single ASCII digit, so a value that is not a whole number from `0` to
+  `7` is a typed error rather than whatever byte the arithmetic truncated to. The round trip above is
+  the **default** start; a non-default one writes a continuation of a sequence already in progress,
+  and a continuation read on its own opens on a frame-sequence gap, so its first record is warned
+  about and not emitted.
 - **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 safety gate that refuses to tolerate any result value, flag,

package/dist/index.cjs

@@ -1435,6 +1435,13 @@ function encodeComponent(leaf, d, recordIndex) {
   assertEmittableDelimiters(d, recordIndex);
   return encodeLeaf(leaf, d, recordIndex);
 }
+function escapeMnemonic(ch, d) {
+  if (ch === d.escape) return "E";
+  if (ch === d.field) return "F";
+  if (ch === d.component) return "S";
+  if (ch === d.repeat) return "R";
+  return void 0;
+}
 function encodeLeaf(leaf, d, recordIndex) {
   if (leaf.includes("\r") || leaf.includes("\n")) {
     throw new AstmSerializeError(
@@ -1442,7 +1449,13 @@ function encodeLeaf(leaf, d, recordIndex) {
       recordIndex
     );
   }
-  return leaf.split(d.escape).join(d.escape + "E" + d.escape).split(d.field).join(d.escape + "F" + d.escape).split(d.component).join(d.escape + "S" + d.escape).split(d.repeat).join(d.escape + "R" + d.escape);
+  let out = "";
+  for (let i = 0; i < leaf.length; i += 1) {
+    const ch = leaf.charAt(i);
+    const mnemonic = escapeMnemonic(ch, d);
+    out += mnemonic === void 0 ? ch : d.escape + mnemonic + d.escape;
+  }
+  return out;
 }
 function encodeField(repeats, d, recordIndex) {
   return repeats.map((rep) => rep.map((c) => encodeLeaf(c, d, recordIndex)).join(d.component)).join(d.repeat);
@@ -2290,6 +2303,15 @@ function assertFramable(bytes, recordIndex) {
     }
   }
 }
+function assertStartFrameNumber(value) {
+  if (!Number.isInteger(value) || value < 0 || value > FRAME_NUMBER_MODULUS - 1) {
+    throw new AstmFrameEncodeError(
+      `startFrameNumber must be a whole number from 0 to 7: a frame's number is one ASCII digit and the sequence is modulo 8. Received: ${String(value)}.`,
+      void 0,
+      "ASTM_FRAME_INVALID_START_FRAME_NUMBER"
+    );
+  }
+}
 function encodeFrame(text, frameNumber, isFinal) {
   const term = isFinal ? ETX : ETB;
   const bytes = [STX, FN_ZERO + frameNumber, ...text, term];
@@ -2298,11 +2320,13 @@ function encodeFrame(text, frameNumber, isFinal) {
   return [...bytes, hex.charCodeAt(0), hex.charCodeAt(1), CR, LF];
 }
 function composeAstmFrames(records, options = {}) {
+  const start = options.startFrameNumber ?? FIRST_FRAME_NUMBER;
+  assertStartFrameNumber(start);
   if (records.length === 0) {
     throw new AstmFrameEncodeError("Cannot frame an empty record list: nothing to transmit.");
   }
   const out = [];
-  let frameNumber = options.startFrameNumber ?? FIRST_FRAME_NUMBER;
+  let frameNumber = start;
   records.forEach((record, recordIndex) => {
     const bytes = toBytes(record, recordIndex);
     if (bytes.length === 0) {
@@ -2347,7 +2371,7 @@ function concatBytes3(chunks) {
 }
 
 // src/index.ts
-var VERSION = "0.0.13";
+var VERSION = "0.0.15";
 
 exports.ALL_ASTM_WARNING_CODES = ALL_ASTM_WARNING_CODES;
 exports.AMBIGUOUS_CODES = AMBIGUOUS_CODES;