@cosyte/astm 0.0.19 → 0.0.21

package/dist/index.d.ts

@@ -182,9 +182,12 @@ declare const WARNING_CODES: {
      * Two escape alignments of the same bytes disagreed about a **field** boundary, the reading taken
      * kept it, and the escape character that reading resumes on **heads no sequence this codec can
      * interpret**, so the boundary was bought with bytes this reading cannot read while the competing
-     * alignment is exactly the reading that can. Every field after that point sits one place further
-     * right than the competing alignment puts it, **except on the one class named at the end of this
-     * entry**, where the two readings instead read the same number of fields in different places.
+     * alignment is exactly the reading that can. Every field after that point sits further
+     * right than the competing alignment puts it, by a displacement that is **not fixed**: one place
+     * on a record carrying a single contested construct, one more for each additional one, and none
+     * at all **on the one class named at the end of this entry**, where the two readings instead read
+     * the same number of fields in different places. Counting these warnings does not give it; see
+     * {@link ShiftedFieldsSink}.
      *
      * **The shift is the harm, and on a result record it reaches the status slot.** Measured on the
      * canonical set, `R|1|^^^687|28.6&F&|&U/L||||F` reads **9** fields under the reading taken and
@@ -229,7 +232,8 @@ declare const WARNING_CODES: {
      *   taken interprets a construct and leaves nothing unread: under a set naming the field separator
      *   `F`, `28.6&F&F&F&U/L` is that separator escaped, written, and escaped again, entirely well
      *   formed, and refusing it would be an over-refusal. That is the only tail on which a stream's
-     *   escaping can be clean, which is why it is the only exclusion. Where the tail heads a sequence
+     *   escaping can be clean, on the declarations {@link ShiftedFieldsSink} scopes that to, which is
+     *   why it is the only exclusion. Where the tail heads a sequence
      *   whose body is *unrecognized*, the reading taken consumes a triple it cannot read, preserved
      *   verbatim and never guessed at, the field shift is the same shift, and **this reports it**.
      *   Consuming a triple is not interpreting one.
@@ -307,8 +311,8 @@ declare const WARNING_CODES: {
      *
      * **Two further deliberate bounds, both stated rather than left to be found.**
      * - **Only the repeat role.** The **component** role reaches a modeled slot too, and differently:
-     *   there the components stay in the record and move one slot along, so a local code reads as a
-     *   coding scheme and a given name as a middle name. That is measured and is now reported by
+     *   there the components stay in the record and move along the component list, so a local code
+     *   reads as a coding scheme and a given name as a middle name. That is measured and is now reported by
      *   {@link WARNING_CODES.ASTM_RECORD_ALIGNMENT_SHIFTED_COMPONENTS}, a third code on the same tail
      *   test wired to the component split. It is still not covered **here**, because wiring a sink to
      *   another split is another criterion, which is why it took its own population measurement.
@@ -317,8 +321,8 @@ declare const WARNING_CODES: {
      *   this codec *recognizes*, it interprets a construct and the repeats are the ones the sender
      *   wrote: under a set naming the repeat separator `F`, `28.6&F&F&F&U/L` is that separator
      *   escaped, written, and escaped again, entirely well formed, and refusing it would be an
-     *   over-refusal. That is the only tail on which a stream's escaping can be clean, which is why it
-     *   is the only exclusion. Where the tail heads a sequence whose body is *unrecognized*, the
+     *   over-refusal. That is the only tail on which a stream's escaping can be clean, on the
+     *   declarations {@link ShiftedFieldsSink} scopes that to, which is why it is the only exclusion. Where the tail heads a sequence whose body is *unrecognized*, the
      *   reading taken consumes a triple it cannot read, preserved verbatim and never guessed at, the
      *   truncation is the same truncation, and **this reports it**.
      * - **That remaining silence is a TRADE, not a claim that nothing was lost.** On the excluded tail
@@ -353,10 +357,11 @@ declare const WARNING_CODES: {
      * {@link WARNING_CODES.ASTM_RECORD_ALIGNMENT_TRUNCATED_FIELD}, on the third and last splitting
      * role, and what it costs is a third thing again, which is why it is a third code.
      *
-     * **The components are neither shifted out of the record nor dropped from it: they MOVE one slot
-     * along.** A field's components are modeled *inside* it, so a gained component boundary shifts
-     * every component after it exactly as a gained field boundary shifts every later field, **except
-     * on the one class named at the end of this entry**, where the two readings instead read the same
+     * **The components are neither shifted out of the record nor dropped from it: they MOVE along the
+     * component list.** A field's components are modeled *inside* it, so a gained component boundary shifts
+     * every component after it exactly as a gained field boundary shifts every later field, by the
+     * displacement {@link ShiftedFieldsSink} states, **except on the one class named at the end of
+     * this entry**, where the two readings instead read the same
      * number of components in different places. Nothing leaves the record and nothing changes field
      * number; what changes is which modeled slot each component lands in, and those slots are named
      * things:
@@ -408,7 +413,8 @@ declare const WARNING_CODES: {
      * *recognizes*, it interprets a construct and the components are the ones the sender wrote: under
      * a set naming the component separator `F`, `GLU&F&F&F&L` is that separator escaped, written, and
      * escaped again, entirely well formed, and refusing it would be an over-refusal. That is the only
-     * tail on which a stream's escaping can be clean, which is why it is the only exclusion. Where the
+     * tail on which a stream's escaping can be clean, on the declarations
+     * {@link ShiftedFieldsSink} scopes that to, which is why it is the only exclusion. Where the
      * tail heads a sequence whose body is *unrecognized*, the reading taken consumes a triple it
      * cannot read, preserved verbatim and never guessed at, the slots move exactly as far, and **this
      * reports it**.
@@ -694,21 +700,19 @@ declare function ambiguousEscapeAlignment(position: AstmPosition): AstmRecordWar
 /**
  * Build an `ASTM_RECORD_ALIGNMENT_SHIFTED_FIELDS` warning. Emitted when a competing escape
  * alignment decided a **field** boundary and the escape character the reading taken resumes on
- * heads no sequence this codec can interpret, so every field after that point sits one place further
- * right than
- * the competing alignment puts it. On a result record that reaches the units and the **result
+ * heads no sequence this codec can interpret, so every field after that point sits further right
+ * than the competing alignment puts it. On a result record that reaches the units and the **result
  * status**: a trailing status letter lands in field 9 under the reading taken and in no field at
- * all under the competing one. **Except where the sequence past the boundary carries the field
- * separator itself**, where the two readings read the same number of fields in different places and
- * no field index moves; see {@link WARNING_CODES.ASTM_RECORD_ALIGNMENT_SHIFTED_FIELDS}.
+ * all under the competing one. **How far the fields are displaced, and why counting these warnings
+ * does not give it, is stated once on {@link ShiftedFieldsSink}**; it is not fixed.
  *
  * A profile may **not** tolerate this code. **Which tolerable escape report accompanies it depends
  * on the tail**: {@link WARNING_CODES.ASTM_UNPAIRED_ESCAPE_CHARACTER} where the tail heads no
  * sequence at all, and {@link WARNING_CODES.ASTM_UNKNOWN_ESCAPE_SEQUENCE} where it heads one whose
- * body is unrecognized. Both report strictly weaker facts, and wherever the escape role is a
- * character distinct from the three splitting roles one of them always fires beside this code. It
- * fires alongside {@link WARNING_CODES.ASTM_RECORD_AMBIGUOUS_ESCAPE_ALIGNMENT} where that also
- * applies. The reading
+ * body is unrecognized. Both report strictly weaker facts. **Which of them accompanies this code,
+ * and the declaration under which neither does, is stated once on the tail test itself**; see
+ * {@link ShiftedFieldsSink}. It fires alongside
+ * {@link WARNING_CODES.ASTM_RECORD_AMBIGUOUS_ESCAPE_ALIGNMENT} where that also applies. The reading
  * is unchanged: this reports the shift, it does not repair it.
  *
  * @example
@@ -729,18 +733,17 @@ declare function alignmentShiftedFields(position: AstmPosition): AstmRecordWarni
  * repeat alone: everything past the boundary stays in `repeats` and leaves every modeled slot, so a
  * result value truncates and a Universal Test ID or a patient name loses the components that sat
  * after it. At a **later** boundary nothing modeled moves and this still fires, which is
- * over-reporting relative to those slots and never under-reporting, and **where the sequence past
- * the boundary carries the repeat separator itself** the two readings read the same number of
- * repeats in different places, so the field is not read as more repeats at all; see
- * {@link WARNING_CODES.ASTM_RECORD_ALIGNMENT_TRUNCATED_FIELD}.
+ * over-reporting relative to those slots and never under-reporting. **By how many repeats the two
+ * readings differ, including the tie class where they do not differ at all, is stated once on
+ * {@link ShiftedFieldsSink}.**
  *
  * A profile may **not** tolerate this code. **Which tolerable escape report accompanies it depends
  * on the tail**: {@link WARNING_CODES.ASTM_UNPAIRED_ESCAPE_CHARACTER} where the tail heads no
  * sequence at all, and {@link WARNING_CODES.ASTM_UNKNOWN_ESCAPE_SEQUENCE} where it heads one whose
- * body is unrecognized. Both report strictly weaker facts, and wherever the escape role is a
- * character distinct from the three splitting roles one of them always fires beside this code. It
- * fires alongside {@link WARNING_CODES.ASTM_RECORD_AMBIGUOUS_ESCAPE_ALIGNMENT} where that also
- * applies. The reading
+ * body is unrecognized. Both report strictly weaker facts. **Which of them accompanies this code,
+ * and the declaration under which neither does, is stated once on the tail test itself**; see
+ * {@link ShiftedFieldsSink}. It fires alongside
+ * {@link WARNING_CODES.ASTM_RECORD_AMBIGUOUS_ESCAPE_ALIGNMENT} where that also applies. The reading
  * is unchanged: this reports the gained boundary, it does not repair it.
  *
  * @example
@@ -753,26 +756,24 @@ declare function alignmentTruncatedField(position: AstmPosition): AstmRecordWarn
 /**
  * Build an `ASTM_RECORD_ALIGNMENT_SHIFTED_COMPONENTS` warning. Emitted when a competing escape
  * alignment decided a **component** boundary and the escape character the reading taken resumes on
- * heads no sequence this codec can interpret, so every component after that point sits one place
- * further right
+ * heads no sequence this codec can interpret, so every component after that point sits further right
  * than the competing alignment puts it. No field number changes and nothing leaves the record, and
  * that is the difference from {@link alignmentShiftedFields} and {@link alignmentTruncatedField}:
  * what moves is which modeled slot each component lands in, so a Universal Test ID's coding scheme
  * and local code, or a patient's given and middle names, are read out of positions the competing
  * alignment does not put them in. **Every gained boundary at or before the last modeled component
  * index moves those slots, not only the first**; past that index, and inside a **later repeat**,
- * nothing named moves and this still fires, which is over-reporting and never under-reporting, and
- * **where the sequence past the boundary carries the component separator itself** the two readings
- * read the same number of components in different places, so no component index moves at all. See
- * {@link WARNING_CODES.ASTM_RECORD_ALIGNMENT_SHIFTED_COMPONENTS}.
+ * nothing named moves and this still fires, which is over-reporting and never under-reporting.
+ * **How far the components are displaced, including the tie class where they do not move at all, is
+ * stated once on {@link ShiftedFieldsSink}**; it is not fixed.
  *
  * A profile may **not** tolerate this code. **Which tolerable escape report accompanies it depends
  * on the tail**: {@link WARNING_CODES.ASTM_UNPAIRED_ESCAPE_CHARACTER} where the tail heads no
  * sequence at all, and {@link WARNING_CODES.ASTM_UNKNOWN_ESCAPE_SEQUENCE} where it heads one whose
- * body is unrecognized. Both report strictly weaker facts, and wherever the escape role is a
- * character distinct from the three splitting roles one of them always fires beside this code. It
- * fires alongside {@link WARNING_CODES.ASTM_RECORD_AMBIGUOUS_ESCAPE_ALIGNMENT} where that also
- * applies. The reading
+ * body is unrecognized. Both report strictly weaker facts. **Which of them accompanies this code,
+ * and the declaration under which neither does, is stated once on the tail test itself**; see
+ * {@link ShiftedFieldsSink}. It fires alongside
+ * {@link WARNING_CODES.ASTM_RECORD_AMBIGUOUS_ESCAPE_ALIGNMENT} where that also applies. The reading
  * is unchanged: this reports the moved components, it does not repair them.
  *
  * @example
@@ -3768,7 +3769,7 @@ declare class AstmParseError extends Error {
  * mnemonic and is therefore preserved verbatim rather than read), the boundary was
  * bought with bytes this reading cannot read, while the competing alignment is
  * precisely the reading that can. On the **field** separator that gained boundary
- * shifts every later field one place, so a result record's units and **result
+ * shifts every later field, so a result record's units and **result
  * status** are read out of slots the competing alignment does not put them in, and
  * a status of `final` can be a consequence of the alignment rather than something
  * the sender wrote there. That is `ASTM_RECORD_ALIGNMENT_SHIFTED_FIELDS`; see
@@ -3787,7 +3788,7 @@ declare class AstmParseError extends Error {
  *
  * **The same question asked on the component separator has a third answer again, and
  * so a third code.** There the components neither leave the record nor change field
- * number: they move one slot along, because components are modeled *inside* a field.
+ * number: they move along the component list, because components are modeled *inside* a field.
  * A Universal Test ID's coding scheme and local code, and a patient's given and middle
  * names, are then read out of positions the competing alignment does not put them in.
  * That is `ASTM_RECORD_ALIGNMENT_SHIFTED_COMPONENTS`; see {@link ShiftedComponentsSink},
@@ -3892,7 +3893,7 @@ type AmbiguousAlignmentSink = (segmentIndex: number) => void;
  *   and the boundary is bought with bytes this reading cannot read either way.
  *
  * Wired **only to the split taken on the field separator**, because that is the
- * whole of its claim: a gained *field* boundary shifts every later field one place,
+ * whole of its claim: a gained *field* boundary shifts every later field,
  * so a record's modeled slots after it are decided by the alignment rather than by
  * the sender's own positions. On a result record that is the units slot and the
  * **result status** slot: the sender's trailing letter lands in field 9 under the
@@ -3907,8 +3908,8 @@ type AmbiguousAlignmentSink = (segmentIndex: number) => void;
  * reported by {@link TruncatedFieldSink}, on the same tail test and under its own
  * code, because what it costs is a different thing. The **component** half is
  * reported by {@link ShiftedComponentsSink}, on that same tail test and under a code of
- * its own again, because what it costs is a third thing: there the components move one
- * slot along rather than leaving the record. The
+ * its own again, because what it costs is a third thing: there the components move along the
+ * component list rather than leaving the record. The
  * callback lets the parser surface a value-free
  * `ASTM_RECORD_ALIGNMENT_SHIFTED_FIELDS` warning. Optional so the split can be used
  * purely.
@@ -3935,9 +3936,10 @@ type AmbiguousAlignmentSink = (segmentIndex: number) => void;
  * for this family.
  *
  * **That exclusion is not a matter of degree, which is why it is the only one.** It
- * is the sole tail on which a stream's escaping can be clean at all: on the other
- * two the package already reports a deviation, so this report can never be the
- * reason a well-formed stream is refused. A tail comparison that instead weighs
+ * is the sole tail on which a stream's escaping can be clean at all, wherever the
+ * escape role is a character distinct from the three splitting roles: on the other two
+ * the package already reports a deviation. **Where the escape role is NOT distinct that
+ * reasoning does not hold**; see the companion paragraph on {@link ShiftedFieldsSink}. A tail comparison that instead weighs
  * which alignment the bytes *prefer* would exclude the unrecognized body too (the
  * competing alignment leaves two escape characters bare there against the reading
  * taken's one unreadable body) and it is the wrong question: these codes report a
@@ -3952,25 +3954,68 @@ type AmbiguousAlignmentSink = (segmentIndex: number) => void;
  * this bound makes. **Read the raw line when an escape character sits next to a
  * delimiter, whether or not anything fired.**
  *
- * **⚠️ THE SHIFT IS NOT UNIVERSAL OVER THE FIRING POPULATION, AND THE EXCEPTION IS
- * NAMED RATHER THAN LEFT TO BE FOUND.** Where the sequence past the boundary carries
- * the **field separator itself** as its body, the reading taken holds that character
- * inside an opaque atom while the competing alignment splits on it, so the two
- * readings return the **same number** of fields in **different places**: no field
- * index moves, and what differs is the **contents** of the fields at and after the
- * boundary. Under the canonical set `R|1|^^^687|28.6&F&|&|&U/L||||F` reads nine
- * fields under both, with the status `F` in field 9 under both, and units of `&|&U/L`
- * against `&U/L`. That class is bounded and costs no stream its disposition: the tail
- * body is then a splitting delimiter in force, so
- * `ASTM_RECORD_DELIMITER_SWALLOWED_BY_ESCAPE` has already refused the record. What
- * holds on **every** firing tuple is that the two readings disagree and that both
- * consume every byte, so neither is forced.
+ * **⚠️ HOW FAR THE DISPLACEMENT RUNS. Every other surface names the KIND of cost and
+ * leaves the magnitude to this paragraph**, because a restatement is a separate claim
+ * that goes stale on its own, and on this family they have.
+ *
+ * **The displacement is not fixed, and "one place" describes only the single-construct
+ * case the three codes were first measured on.** It takes three values, and two of them
+ * were left out of every surface that quoted a figure:
+ *
+ * - **Zero, on the tie class.** Where the sequence past the boundary carries the
+ *   **field separator itself** as its body, the reading taken holds that character
+ *   inside an opaque atom while the competing alignment splits on it, so the two
+ *   readings return the **same number** of fields in **different places**: no field
+ *   index moves and what differs is the **contents**. `R|1|^^^687|28.6&F&|&|&U/L||||F`
+ *   reads nine fields under both, status `F` in field 9 under both, units `&|&U/L`
+ *   against `&U/L`. That class costs no stream its disposition: the tail body is a
+ *   splitting delimiter in force, so `ASTM_RECORD_DELIMITER_SWALLOWED_BY_ESCAPE` has
+ *   already refused the record.
+ * - **One, on a record carrying exactly one contested construct.** This is the case
+ *   every corpus in this family was built on, and the only one "one place" was ever
+ *   true of.
+ * - **One more for each additional contested construct.** The competing reading resumes
+ *   a character further on at each contested position, so it falls further out of step
+ *   with the reading taken and the gap widens once per construct.
+ *   `A&Z&|&BX&Z&|&F&C` reads **three** fields against **one**.
+ *
+ * **The number of these warnings is not the displacement either, in either
+ * direction.** A gained boundary whose tail is a recognized mnemonic is excluded from
+ * the report and still displaces, so one warning can sit on a displacement of two; and
+ * where one of several constructs is a tie, two warnings can sit on a displacement of
+ * one. A consumer cannot recover the offset by counting. **Read the raw line.**
+ *
+ * What holds on **every** firing tuple is that the two readings disagree, that both
+ * consume every byte so neither is forced, and that the reading taken never reads
+ * **fewer** segments than the competing one. Measured in
+ * `test/records/alignment-offset-rephasing.test.ts`.
+ *
+ * **⚠️ WHICH REPORTS ACCOMPANY THIS ONE, AND THE DECLARATION ON WHICH NONE DOES.** The
+ * exclusion above rests on a defence against over-refusal: firing requires an escape
+ * character heading no sequence this codec can interpret, and the package reports each
+ * of those in its own right, so a stream whose escaping raises nothing is never refused
+ * because of these codes. **That defence is true wherever the escape role is a
+ * character distinct from the three splitting roles, and it is FALSE where it is not.**
+ * On a set naming the escape character in a splitting role too, one byte both opens a
+ * sequence and ends a segment, the split claims it first, and neither
+ * `ASTM_UNPAIRED_ESCAPE_CHARACTER` nor `ASTM_UNKNOWN_ESCAPE_SEQUENCE` ever sees a
+ * sequence to raise: this fires with **neither** companion. What refuses the stream
+ * there is the declaration itself, as `ASTM_RECORD_DELIMITER_ROLE_COLLISION`, which no
+ * profile may tolerate. So the defence survives only in the form **no stream whose
+ * escaping AND whose declaration are both clean is refused by one of these codes.**
+ *
+ * **That replacement is scoped to the STREAM and does not hold per message**: the
+ * collision is reported once per set change rather than once per record, so a second
+ * header re-declaring the same colliding set raises nothing while these codes fire
+ * again in its message. A consumer scoping warnings to a message can therefore see one
+ * of them standing entirely alone. The **field** role cannot collide with the escape
+ * role at all: the declaration is the three characters after the field separator and
+ * stops at the next one, so such a header terminates itself one character short and is
+ * refused. Measured in `test/records/alignment-companion-universal.test.ts`.
  *
  * @param segmentIndex - The 0-based index of the field being accumulated when the
- *   contested boundary was taken. Every field after it is one place further right
- *   than the competing alignment puts it, **except** where the sequence past the
- *   boundary carries the field separator as its body, where the two readings return
- *   the same number of fields with different contents instead.
+ *   contested boundary was taken. For how far the fields after it are displaced, see
+ *   the displacement paragraph above: it is not a fixed one place.
  */
 type ShiftedFieldsSink = (segmentIndex: number) => void;
 /**
@@ -4025,7 +4070,8 @@ type ShiftedFieldsSink = (segmentIndex: number) => void;
  * the repeat separator `F`, `28.6&F&F&F&U/L` is that separator escaped, written, and
  * escaped again, with nothing reported at all. Refusing that is the over-refusal that
  * sank an earlier candidate criterion for this family, and that tail is the only one
- * on which a stream's escaping can be clean. Where the tail heads a sequence whose
+ * on which a stream's escaping can be clean, on the declarations the companion
+ * paragraph on {@link ShiftedFieldsSink} scopes that to. Where the tail heads a sequence whose
  * body is *unrecognized*, the reading taken consumes a triple it cannot read, the
  * truncation is the same truncation, and this reports it.
  *
@@ -4052,7 +4098,9 @@ type ShiftedFieldsSink = (segmentIndex: number) => void;
  *   contested boundary was taken, so `0` is the boundary that ends the first repeat
  *   and is the one that reaches a modeled slot. It is **not** a field index: the
  *   caller splitting one field into repeats already knows which field it is in, and
- *   reports that.
+ *   reports that. For how many repeats the two readings differ by, and why the count
+ *   of these warnings does not give it, see the displacement paragraph on
+ *   {@link ShiftedFieldsSink}.
  */
 type TruncatedFieldSink = (segmentIndex: number) => void;
 /**
@@ -4067,8 +4115,8 @@ type TruncatedFieldSink = (segmentIndex: number) => void;
  * **What a gained component boundary costs, and it is neither of the other two.** No
  * field number changes, so nothing shifts between field-indexed slots, and nothing
  * leaves the record, so nothing truncates. Components are modeled **inside** a field,
- * so what happens is that every component after the gained boundary is one place
- * further right than the competing alignment puts it, and the slots that indexes into
+ * so what happens is that every component after the gained boundary sits further right
+ * than the competing alignment puts it, and the slots that indexes into
  * are named things: a Universal Test ID's LOINC-candidate slot, test name, **coding
  * scheme** and **local code**; a patient name's last, first and middle. Under the
  * canonical set `&F&^&GLU^L^687` reads four components, so `L` is the coding scheme
@@ -4115,7 +4163,8 @@ type TruncatedFieldSink = (segmentIndex: number) => void;
  * separator `F`, `GLU&F&F&F&L` is that separator escaped, written, and escaped again,
  * with nothing reported at all. Refusing that is the over-refusal that sank an earlier
  * candidate criterion for this family, and that tail is the only one on which a
- * stream's escaping can be clean. Where the tail heads a sequence whose body is
+ * stream's escaping can be clean, on the declarations the companion paragraph on
+ * {@link ShiftedFieldsSink} scopes that to. Where the tail heads a sequence whose body is
  * *unrecognized*, the reading taken consumes a triple it cannot read, the slots move
  * exactly as far, and this reports it.
  *
@@ -4126,28 +4175,24 @@ type TruncatedFieldSink = (segmentIndex: number) => void;
  * still sit where an alignment guess put them. Reporting it would refuse a stream whose
  * escaping is working.
  *
- * **⚠️ THE MOVE IS NOT UNIVERSAL OVER THE FIRING POPULATION, AND THE EXCEPTION IS NAMED
- * RATHER THAN LEFT TO BE FOUND.** It is a **third** bound running the other way, and it
- * differs from the two above: those two fire where nothing named moves because of where
- * the boundary sits, while this one is about the bytes past it. Where the sequence past
- * the boundary carries the **component separator itself** as its body, the reading taken
- * holds that character inside an opaque atom while the competing alignment splits on it,
- * so the two readings return the **same number** of components in **different places**:
- * no component index moves, and what differs is the **contents**. Under the canonical
- * set `DOE&F&^&^&JANE^A` reads three components under both, with `A` the middle name
- * under both. That class is bounded and costs no stream its disposition: the tail body
- * is then a splitting delimiter in force, so
- * `ASTM_RECORD_DELIMITER_SWALLOWED_BY_ESCAPE` has already refused the record. What holds
- * on **every** firing tuple is that the two readings disagree and that both consume
- * every byte, so neither is forced.
+ * **⚠️ HOW FAR THE COMPONENTS MOVE IS THE DISPLACEMENT {@link ShiftedFieldsSink}
+ * STATES, READ ON THE COMPONENT SEPARATOR.** It is not fixed, and it takes three values
+ * and not one: zero on the tie class (`DOE&F&^&^&JANE^A` reads three
+ * components under both, with `A` the middle name under both, and
+ * `ASTM_RECORD_DELIMITER_SWALLOWED_BY_ESCAPE` has already refused that record), and
+ * more than one once a field carries more than one contested construct. That paragraph
+ * is not repeated here on purpose: it is one claim, stated where the link points.
+ *
+ * This third bound differs from the two above in what it is about: those two fire where
+ * nothing named moves because of where the boundary **sits**, while the tie class is
+ * about the bytes **past** it. What holds on **every** firing tuple is that the two
+ * readings disagree and that both consume every byte, so neither is forced.
  *
  * @param segmentIndex - The 0-based index of the component being accumulated when the
- *   contested boundary was taken. Every component after it is one place further right
- *   than the competing alignment puts it, **except** where the sequence past the
- *   boundary carries the component separator as its body, where the two readings return
- *   the same number of components with different contents instead. It is **not** a field
- *   index, and it is **not** a repeat index: the caller splitting one repeat into
- *   components already knows both, and reports the field.
+ *   contested boundary was taken. It is **not** a field index, and it is **not** a
+ *   repeat index: the caller splitting one repeat into components already knows both,
+ *   and reports the field. For how far the components after it move, see the
+ *   displacement paragraph on {@link ShiftedFieldsSink}.
  */
 type ShiftedComponentsSink = (segmentIndex: number) => void;
 /**
@@ -4606,10 +4651,12 @@ declare function resolveProfileTransport(profile: AstmProfile | undefined): Astm
  * the first one that reaches a MODELED SLOT rather than a boundary.** It reports
  * that a contested alignment decided a **field** boundary while the reading taken
  * resumes on an escape character heading no sequence this codec can interpret, so
- * every later field sits one place further right than the competing alignment puts
- * it (**except where the sequence past the boundary carries the field separator
- * itself**, where the two readings read the same number of fields in different
- * places). On a result record that
+ * every later field sits further right than the competing alignment puts it, by a
+ * displacement that is not fixed (**except where the sequence past the boundary carries
+ * the field separator itself**, where the two readings read the same number of fields in
+ * different places, and further still where the record carries a second contested
+ * construct).
+ * On a result record that
  * moves the units and the **result status**: the sender's trailing letter is read out
  * of field 9 under the reading taken and out of no field at all under the other, so a
  * status of `final` can be a consequence of the alignment rather than something the
@@ -4651,10 +4698,11 @@ declare function resolveProfileTransport(profile: AstmProfile | undefined): Astm
  * role.** It reports a contested alignment deciding a **component** boundary. Nothing
  * shifts between fields and nothing leaves the record, which is why neither of the two
  * above could cover it: components are modeled **inside** a field, so every component
- * after the gained boundary is one place further right than the competing alignment
- * puts it (**except where the sequence past the boundary carries the component
- * separator itself**, where the two readings read the same number of components in
- * different places). That indexes into named slots. A Universal Test ID's four components are the
+ * after the gained boundary sits further right than the competing alignment puts it, by
+ * a displacement that is not fixed (**except where the sequence past the boundary carries
+ * the component separator itself**, where the two readings read the same number of
+ * components in different places, and further still where the field carries a second
+ * contested construct). That indexes into named slots. A Universal Test ID's four components are the
  * LOINC-candidate slot, the test name, the **coding scheme** and the **local code**, so
  * `&F&^&GLU^L^687` reads `687` as the vendor's local code under the reading taken and
  * as the **coding scheme** under the competing one; a patient name's three are last,
@@ -4873,7 +4921,7 @@ declare function resolveProfileTransport(profile: AstmProfile | undefined): Astm
  * `ASTM_RECORD_ALIGNMENT_SHIFTED_COMPONENTS` is not on this list and must not be added
  * to it either. It reports the same contested alignment deciding a **component**
  * boundary, where nothing leaves the record and no field number changes, and every
- * component after it moves one slot along instead: a Universal Test ID's coding scheme
+ * component after it moves along the component list instead: a Universal Test ID's coding scheme
  * and local code, and a patient's given and middle names, are read out of positions the
  * competing alignment does not put them in. Reporting a code system, a vendor's local
  * code or a given name that the bytes do not unambiguously carry fails the first half of

package/dist/index.mjs

@@ -271,9 +271,12 @@ var WARNING_CODES = {
    * Two escape alignments of the same bytes disagreed about a **field** boundary, the reading taken
    * kept it, and the escape character that reading resumes on **heads no sequence this codec can
    * interpret**, so the boundary was bought with bytes this reading cannot read while the competing
-   * alignment is exactly the reading that can. Every field after that point sits one place further
-   * right than the competing alignment puts it, **except on the one class named at the end of this
-   * entry**, where the two readings instead read the same number of fields in different places.
+   * alignment is exactly the reading that can. Every field after that point sits further
+   * right than the competing alignment puts it, by a displacement that is **not fixed**: one place
+   * on a record carrying a single contested construct, one more for each additional one, and none
+   * at all **on the one class named at the end of this entry**, where the two readings instead read
+   * the same number of fields in different places. Counting these warnings does not give it; see
+   * {@link ShiftedFieldsSink}.
    *
    * **The shift is the harm, and on a result record it reaches the status slot.** Measured on the
    * canonical set, `R|1|^^^687|28.6&F&|&U/L||||F` reads **9** fields under the reading taken and
@@ -318,7 +321,8 @@ var WARNING_CODES = {
    *   taken interprets a construct and leaves nothing unread: under a set naming the field separator
    *   `F`, `28.6&F&F&F&U/L` is that separator escaped, written, and escaped again, entirely well
    *   formed, and refusing it would be an over-refusal. That is the only tail on which a stream's
-   *   escaping can be clean, which is why it is the only exclusion. Where the tail heads a sequence
+   *   escaping can be clean, on the declarations {@link ShiftedFieldsSink} scopes that to, which is
+   *   why it is the only exclusion. Where the tail heads a sequence
    *   whose body is *unrecognized*, the reading taken consumes a triple it cannot read, preserved
    *   verbatim and never guessed at, the field shift is the same shift, and **this reports it**.
    *   Consuming a triple is not interpreting one.
@@ -396,8 +400,8 @@ var WARNING_CODES = {
    *
    * **Two further deliberate bounds, both stated rather than left to be found.**
    * - **Only the repeat role.** The **component** role reaches a modeled slot too, and differently:
-   *   there the components stay in the record and move one slot along, so a local code reads as a
-   *   coding scheme and a given name as a middle name. That is measured and is now reported by
+   *   there the components stay in the record and move along the component list, so a local code
+   *   reads as a coding scheme and a given name as a middle name. That is measured and is now reported by
    *   {@link WARNING_CODES.ASTM_RECORD_ALIGNMENT_SHIFTED_COMPONENTS}, a third code on the same tail
    *   test wired to the component split. It is still not covered **here**, because wiring a sink to
    *   another split is another criterion, which is why it took its own population measurement.
@@ -406,8 +410,8 @@ var WARNING_CODES = {
    *   this codec *recognizes*, it interprets a construct and the repeats are the ones the sender
    *   wrote: under a set naming the repeat separator `F`, `28.6&F&F&F&U/L` is that separator
    *   escaped, written, and escaped again, entirely well formed, and refusing it would be an
-   *   over-refusal. That is the only tail on which a stream's escaping can be clean, which is why it
-   *   is the only exclusion. Where the tail heads a sequence whose body is *unrecognized*, the
+   *   over-refusal. That is the only tail on which a stream's escaping can be clean, on the
+   *   declarations {@link ShiftedFieldsSink} scopes that to, which is why it is the only exclusion. Where the tail heads a sequence whose body is *unrecognized*, the
    *   reading taken consumes a triple it cannot read, preserved verbatim and never guessed at, the
    *   truncation is the same truncation, and **this reports it**.
    * - **That remaining silence is a TRADE, not a claim that nothing was lost.** On the excluded tail
@@ -442,10 +446,11 @@ var WARNING_CODES = {
    * {@link WARNING_CODES.ASTM_RECORD_ALIGNMENT_TRUNCATED_FIELD}, on the third and last splitting
    * role, and what it costs is a third thing again, which is why it is a third code.
    *
-   * **The components are neither shifted out of the record nor dropped from it: they MOVE one slot
-   * along.** A field's components are modeled *inside* it, so a gained component boundary shifts
-   * every component after it exactly as a gained field boundary shifts every later field, **except
-   * on the one class named at the end of this entry**, where the two readings instead read the same
+   * **The components are neither shifted out of the record nor dropped from it: they MOVE along the
+   * component list.** A field's components are modeled *inside* it, so a gained component boundary shifts
+   * every component after it exactly as a gained field boundary shifts every later field, by the
+   * displacement {@link ShiftedFieldsSink} states, **except on the one class named at the end of
+   * this entry**, where the two readings instead read the same
    * number of components in different places. Nothing leaves the record and nothing changes field
    * number; what changes is which modeled slot each component lands in, and those slots are named
    * things:
@@ -497,7 +502,8 @@ var WARNING_CODES = {
    * *recognizes*, it interprets a construct and the components are the ones the sender wrote: under
    * a set naming the component separator `F`, `GLU&F&F&F&L` is that separator escaped, written, and
    * escaped again, entirely well formed, and refusing it would be an over-refusal. That is the only
-   * tail on which a stream's escaping can be clean, which is why it is the only exclusion. Where the
+   * tail on which a stream's escaping can be clean, on the declarations
+   * {@link ShiftedFieldsSink} scopes that to, which is why it is the only exclusion. Where the
    * tail heads a sequence whose body is *unrecognized*, the reading taken consumes a triple it
    * cannot read, preserved verbatim and never guessed at, the slots move exactly as far, and **this
    * reports it**.
@@ -683,21 +689,21 @@ function ambiguousEscapeAlignment(position) {
 function alignmentShiftedFields(position) {
   return {
     code: WARNING_CODES.ASTM_RECORD_ALIGNMENT_SHIFTED_FIELDS,
-    message: "A field boundary here is one of two escape alignments the bytes carry, and the reading that took it resumes on an escape character heading no sequence this reader can interpret, which the other alignment uses to close one. The two readings disagree, and both consume every byte, so neither is forced. Usually every later field is one place further right than the other reading puts it, so a result's units and status may be read out of slots the sender did not put them in; one measured class does not shift at all, where the sequence past the boundary carries the field separator itself and the two readings read the same number of fields with different contents. The reading was kept and every byte is preserved.",
+    message: "A field boundary here is one of two escape alignments the bytes carry, and the reading that took it resumes on an escape character heading no sequence this reader can interpret, which the other alignment uses to close one. The two readings disagree, and both consume every byte, so neither is forced. How far the later fields are displaced is NOT fixed: one place where the record carries a single contested construct, one more for each additional one, and none at all on one measured class, where the sequence past the boundary carries the field separator itself and the two readings read the same number of fields with different contents. So a result's units and status may be read out of slots the sender did not put them in. Counting these warnings does not give the displacement. Read the raw line. The reading was kept and every byte is preserved.",
     position
   };
 }
 function alignmentTruncatedField(position) {
   return {
     code: WARNING_CODES.ASTM_RECORD_ALIGNMENT_TRUNCATED_FIELD,
-    message: "A repeat boundary here is one of two escape alignments the bytes carry, and the reading that took it resumes on an escape character heading no sequence this reader can interpret, which the other alignment uses to close one. The two readings disagree, and both consume every byte, so neither is forced. Usually this field is read as more repeats than the other reading gives it, and its modeled value and components are taken from the first repeat alone, so where that boundary is the first one the rest of the field leaves every modeled slot; one measured class reads the same number of repeats, where the sequence past the boundary carries the repeat separator itself. The reading was kept and every byte is preserved.",
+    message: "A repeat boundary here is one of two escape alignments the bytes carry, and the reading that took it resumes on an escape character heading no sequence this reader can interpret, which the other alignment uses to close one. The two readings disagree, and both consume every byte, so neither is forced. How many more repeats this field is read as is NOT fixed: one where the record carries a single contested construct, one more for each additional one, and none at all on one measured class, where the sequence past the boundary carries the repeat separator itself. Its modeled value and components are taken from the first repeat alone, so where that boundary is the first one the rest of the field leaves every modeled slot. Counting these warnings does not give the difference. Read the raw line. The reading was kept and every byte is preserved.",
     position
   };
 }
 function alignmentShiftedComponents(position) {
   return {
     code: WARNING_CODES.ASTM_RECORD_ALIGNMENT_SHIFTED_COMPONENTS,
-    message: "A component boundary here is one of two escape alignments the bytes carry, and the reading that took it resumes on an escape character heading no sequence this reader can interpret, which the other alignment uses to close one. The two readings disagree, and both consume every byte, so neither is forced. Usually every later component of this field sits one place further right than the other reading puts it, so a test identity's coding scheme and local code, or a patient's given and middle names, may be read out of slots the sender did not put them in; one measured class does not move at all, where the sequence past the boundary carries the component separator itself and the two readings read the same number of components with different contents. The reading was kept and every byte is preserved.",
+    message: "A component boundary here is one of two escape alignments the bytes carry, and the reading that took it resumes on an escape character heading no sequence this reader can interpret, which the other alignment uses to close one. The two readings disagree, and both consume every byte, so neither is forced. How far the later components of this field are displaced is NOT fixed: one place where the field carries a single contested construct, one more for each additional one, and none at all on one measured class, where the sequence past the boundary carries the component separator itself and the two readings read the same number of components with different contents. So a test identity's coding scheme and local code, or a patient's given and middle names, may be read out of slots the sender did not put them in. Counting these warnings does not give the displacement. Read the raw line. The reading was kept and every byte is preserved.",
     position
   };
 }
@@ -1326,7 +1332,7 @@ var referenceCorpus = defineAstmProfile({
   tolerate: [
     {
       code: "ASTM_UNKNOWN_ESCAPE_SEQUENCE",
-      rationale: "The OSS reference stack (python-astm codec.py, firsthand-verified) treats '&' as literal data and never decodes escape sequences, so streams from that ecosystem carry non-standard '&\u2026&' bodies our escape-aware tokenizer flags. The body is preserved byte-for-byte in the value. NOT always non-clinical, and this is measured rather than assumed: where the body is a delimiter, that delimiter never became a field boundary, so `28.6&|&U/L` reads as one value with no units and no final status. That subset now also raises ASTM_RECORD_DELIMITER_SWALLOWED_BY_ESCAPE, which this profile cannot tolerate, so tolerating this code no longer hides it. The same holds for the mirror case, where a sequence ends where another could have begun and a delimiter splits that the other alignment would have held: that raises ASTM_RECORD_AMBIGUOUS_ESCAPE_ALIGNMENT, which this profile cannot tolerate either. Where that gained boundary is a field boundary and the reading taken resumes on an escape character heading no sequence this reader can interpret, every later field shifts and a result's units and status move with it, which raises ASTM_RECORD_ALIGNMENT_SHIFTED_FIELDS, untolerable here as well. Where that same gained boundary is a repeat boundary, nothing shifts but the field is read out of its first repeat alone, so a value truncates and a test identity empties, which raises ASTM_RECORD_ALIGNMENT_TRUNCATED_FIELD, untolerable here too. Where it is a component boundary, nothing leaves the record and no field number changes, and every component after it moves one slot along, so a test identity's coding scheme and local code and a patient's given and middle names are read out of positions the other alignment does not put them in, which raises ASTM_RECORD_ALIGNMENT_SHIFTED_COMPONENTS, untolerable here as well. Each of those three shift claims has one measured exception, where the sequence past the boundary carries the splitting delimiter itself: the two readings then read the same number of segments in different places, nothing moves index, and the record was already refused by ASTM_RECORD_DELIMITER_SWALLOWED_BY_ESCAPE. All three carry the same tail bound and stay silent in exactly one case, where the escape character past the boundary heads a sequence this reader RECOGNIZES, which is the escape mechanism working. How often that happens on this corpus is NOT measured and must not be guessed at: the firsthand grounding above is of the DECODE path only, and a relayed stream can still carry a device-written mnemonic. Tolerating this code does not quiet those three, and their absence is not a statement that nothing was lost."
+      rationale: "The OSS reference stack (python-astm codec.py, firsthand-verified) treats '&' as literal data and never decodes escape sequences, so streams from that ecosystem carry non-standard '&\u2026&' bodies our escape-aware tokenizer flags. The body is preserved byte-for-byte in the value. NOT always non-clinical, and this is measured rather than assumed: where the body is a delimiter, that delimiter never became a field boundary, so `28.6&|&U/L` reads as one value with no units and no final status. That subset now also raises ASTM_RECORD_DELIMITER_SWALLOWED_BY_ESCAPE, which this profile cannot tolerate, so tolerating this code no longer hides it. The same holds for the mirror case, where a sequence ends where another could have begun and a delimiter splits that the other alignment would have held: that raises ASTM_RECORD_AMBIGUOUS_ESCAPE_ALIGNMENT, which this profile cannot tolerate either. Where that gained boundary is a field boundary and the reading taken resumes on an escape character heading no sequence this reader can interpret, every later field shifts and a result's units and status move with it, which raises ASTM_RECORD_ALIGNMENT_SHIFTED_FIELDS, untolerable here as well. Where that same gained boundary is a repeat boundary, nothing shifts but the field is read out of its first repeat alone, so a value truncates and a test identity empties, which raises ASTM_RECORD_ALIGNMENT_TRUNCATED_FIELD, untolerable here too. Where it is a component boundary, nothing leaves the record and no field number changes, and every component after it moves along the component list, so a test identity's coding scheme and local code and a patient's given and middle names are read out of positions the other alignment does not put them in, which raises ASTM_RECORD_ALIGNMENT_SHIFTED_COMPONENTS, untolerable here as well. Each of those three shift claims has one measured exception, where the sequence past the boundary carries the splitting delimiter itself: the two readings then read the same number of segments in different places, nothing moves index, and the record was already refused by ASTM_RECORD_DELIMITER_SWALLOWED_BY_ESCAPE. All three carry the same tail bound and stay silent in exactly one case, where the escape character past the boundary heads a sequence this reader RECOGNIZES, which is the escape mechanism working. How often that happens on this corpus is NOT measured and must not be guessed at: the firsthand grounding above is of the DECODE path only, and a relayed stream can still carry a device-written mnemonic. Tolerating this code does not quiet those three, and their absence is not a statement that nothing was lost."
     }
   ]
 });
@@ -2900,7 +2906,7 @@ function concatBytes3(chunks) {
 }
 
 // src/index.ts
-var VERSION = "0.0.19";
+var VERSION = "0.0.21";
 
 export { ALL_ASTM_WARNING_CODES, AMBIGUOUS_CODES, ACK as ASTM_ACK, ENQ as ASTM_ENQ, EOT as ASTM_EOT, NAK as ASTM_NAK, AstmAmbiguousStreamError, AstmFrameEncodeError, AstmFrameStrictError, AstmParseError, AstmProfileDefinitionError, AstmSerializeError, AstmStrictError, CANONICAL_DELIMITERS, FATAL_CODES, FRAME_WARNING_CODES, LIVD_WARNING_CODES, LTP_WARNING_CODES, SAFETY_CRITICAL_CODES, TOLERABLE_CODES, VERSION, WARNING_CODES, alignmentShiftedComponents, alignmentShiftedFields, alignmentTruncatedField, ambiguousEscapeAlignment, ambiguousMessageKind, ambiguousValueSplit, applyAstmProfile, applyAstmProfileToWarnings, applyLivd, astmDateToLocalISO, astmProfiles, attachComments, buildAstmMessage, classifyMessage, comments, commentsFor, composeAstmFrames, computeChecksum, decodeAstmFrames, decodeEscapes, deepFreeze, defineAstmProfile, defineLivdCatalog, delimiterRoleCollision, delimiterSwallowedByEscape, delimitersRedeclared, detectFraming, encodeComponent, fieldScalar, fieldsUnseparated, frameBadChecksum, frameOversize, frameSequenceGap, frameUnterminated, getAstmProfile, getDefaultAstmProfile, hasCollidingRoles, interpretAbnormalFlag, interpretResultStatus, isNonStandard, isSafetyCriticalCode, listAstmProfiles, livdAmbiguousMapping, livdUnmappedCode, lookupLivdForRecord, ltpAmbiguousTransport, ltpFrameRejected, ltpInitialState, ltpReduce, ltpUnexpectedEvent, messages, nonStandardDelimiters, orders, orphanComment, parseAstmDate, parseAstmRecords, parseChecksumHex, parseFramedAstm, parseReferenceRange, partialTimestamp, patient, primaryCode, profileQuirkApplied, query, readDelimiterDeclaration, readDelimiters, recognizeUniversalTestId, resolveProfileTransport, results, serializeAstmRecord, serializeAstmRecords, serializeField, serializeFramedAstm, setDefaultAstmProfile, splitEscapeAware, toChecksumHex, tokenizeHeader, tokenizeRecord, undefinedAbnormalFlag, undefinedResultStatus, uninterpretedQueryStatus, unitsAbsent, unknownEscapeSequence, unknownRecordType, unpairedEscapeCharacter, unparseableReferenceRange, unreadableRedeclaration };
 //# sourceMappingURL=index.mjs.map