@cosyte/astm 0.0.14 → 0.0.17

package/dist/index.cjs

@@ -6,7 +6,19 @@ var FATAL_CODES = {
   EMPTY_INPUT: "EMPTY_INPUT",
   /** The first record is not an `H` (header) record: an ASTM message must lead with `H`. */
   ASTM_RECORD_NO_HEADER: "ASTM_RECORD_NO_HEADER",
-  /** The `H` record is too short to declare the four delimiters (field/repeat/component/escape). */
+  /**
+   * The first `H` record could not declare all four delimiters (field/repeat/component/escape).
+   * One code, four reasons, and the message says which: the record is not a header, it is shorter
+   * than a header plus a three-character definition, its definition field holds fewer than three
+   * characters before the next field separator, or its field separator is also one of the other
+   * three. Only the second of those is "too short", so read the message rather than assuming it.
+   *
+   * **Two of the four cannot be reached on this fatal, and are not dead code.** A first record that
+   * is not an `H` raises `ASTM_RECORD_NO_HEADER` before the declaration is ever read, and a field
+   * separator reused among the other three ends the delimiter definition where it appears, so the
+   * truncation reason answers first. The reader names all four because it is also called directly
+   * and on later headers, where the same conditions are a warning rather than this fatal.
+   */
   ASTM_RECORD_UNDECLARED_DELIMITERS: "ASTM_RECORD_UNDECLARED_DELIMITERS"
 };
 var AstmParseError = class extends Error {
@@ -45,17 +57,26 @@ var CANONICAL_DELIMITERS = {
   escape: "&"
 };
 function readDelimiters(headerRecord) {
-  if (headerRecord.length < 5) return void 0;
-  if (headerRecord.charAt(0) !== "H") return void 0;
+  const result = readDelimiterDeclaration(headerRecord);
+  return result.ok ? result.delimiters : void 0;
+}
+function readDelimiterDeclaration(headerRecord) {
+  if (headerRecord.charAt(0) !== "H") return { ok: false, fault: "not-a-header" };
+  if (headerRecord.length < 5) return { ok: false, fault: "record-too-short" };
   const field = headerRecord.charAt(1);
   const defEnd = headerRecord.indexOf(field, 2);
   const definition = headerRecord.slice(2, defEnd === -1 ? headerRecord.length : defEnd);
-  if (definition.length < 3) return void 0;
+  if (definition.length < 3) return { ok: false, fault: "definition-truncated" };
   const repeat = definition.charAt(0);
   const component = definition.charAt(1);
   const escape = definition.charAt(2);
-  if (field === repeat || field === component || field === escape) return void 0;
-  return { field, repeat, component, escape };
+  if (field === repeat || field === component || field === escape) {
+    return { ok: false, fault: "field-separator-reused" };
+  }
+  return { ok: true, delimiters: { field, repeat, component, escape } };
+}
+function hasCollidingRoles(d) {
+  return d.repeat === d.component || d.repeat === d.escape || d.component === d.escape;
 }
 function isNonStandard(d) {
   return d.field !== CANONICAL_DELIMITERS.field || d.repeat !== CANONICAL_DELIMITERS.repeat || d.component !== CANONICAL_DELIMITERS.component || d.escape !== CANONICAL_DELIMITERS.escape;
@@ -144,18 +165,170 @@ var WARNING_CODES = {
    * boundaries, silently, and this can happen to one record inside a run of these warnings); and a
    * set differing in the repeat, component or escape role usually splits into fields normally,
    * where a mis-split component can cost a test identity while the value survives, and where an
-   * `&X&` sequence whose body is a delimiter is an opaque atom, so that delimiter does not split
+   * `&X&` sequence whose body is an unrecognized character that is itself a delimiter in force is an
+   * opaque atom, so that delimiter does not split
    * and every field after it shifts. The escape role's worst case has narrowed and not
    * disappeared: an escape character heading no sequence is now read as a literal and reported
    * under {@link WARNING_CODES.ASTM_UNPAIRED_ESCAPE_CHARACTER} rather than merging the rest of the
-   * record, but a delimiter swallowed inside an `&X&` body is reported only by
-   * {@link WARNING_CODES.ASTM_UNKNOWN_ESCAPE_SEQUENCE}, which is tolerable. Treat this code as a
+   * record, and a delimiter swallowed inside an `&X&` body now raises
+   * {@link WARNING_CODES.ASTM_RECORD_DELIMITER_SWALLOWED_BY_ESCAPE} as well as the tolerable
+   * {@link WARNING_CODES.ASTM_UNKNOWN_ESCAPE_SEQUENCE}, though it still splits the same way. The
+   * mirror of that case, where the leftmost alignment lets a delimiter split that a competing
+   * alignment would have held, gains a boundary rather than losing one, so the record splits into
+   * more fields than another reading gives and this code cannot see it either
+   * ({@link WARNING_CODES.ASTM_RECORD_AMBIGUOUS_ESCAPE_ALIGNMENT} reports that). Treat this code as a
    * report that one record definitely lost its fields, never as a sweep that would have fired if
    * any had.
    */
   ASTM_RECORD_FIELDS_UNSEPARATED: "ASTM_RECORD_FIELDS_UNSEPARATED",
   /** The header declared delimiters other than the canonical `H|\^&`: tolerated, noted. */
   ASTM_NONSTANDARD_DELIMITERS: "ASTM_NONSTANDARD_DELIMITERS",
+  /**
+   * A header declared **one character in two roles**, so the boundary between those two roles is
+   * not recoverable from the bytes. The declaration is still read and honored and no record is
+   * dropped: what is gone is a distinction the sender's own bytes no longer carry.
+   *
+   * The field separator is not part of this: a declaration naming it in another role is refused
+   * earlier (the `ASTM_RECORD_UNDECLARED_DELIMITERS` fatal on the first header,
+   * {@link WARNING_CODES.ASTM_RECORD_UNREADABLE_REDECLARATION} on a later one). What this code
+   * covers is the three unordered pairs among the rest: **repeat/component, repeat/escape,
+   * component/escape**.
+   *
+   * Measured on `H|^^&` (repeat and component both `^`): the field `A^B^C^D` reads back as four
+   * repeats of one component each, so `components` holds only `A` and a two-repeats-of-two-components
+   * reading cannot be recovered. Measured on `H|\&&` (component and escape both `&`): `A&B` splits
+   * into two components while `A&F&B` reads as the single component `A|B`, so the same character
+   * means two different things depending on what follows it.
+   *
+   * **It is not tolerable**, and the reason is the pair it travels with: such a set is always
+   * non-canonical, so before this code existed the only warning on the stream was
+   * {@link WARNING_CODES.ASTM_NONSTANDARD_DELIMITERS}, which a profile may tolerate. That made a
+   * structurally unreadable declaration indistinguishable, to a strict consumer, from an ordinary
+   * vendor set. Emit refuses the same sets outright (`ASTM_EMIT_INVALID_DELIMITERS`).
+   *
+   * One warning per header that **changes** the set in force into such a set, not one per colliding
+   * pair. A later header restating the colliding set already in force is a no-op and warns nothing,
+   * on the same rule as {@link WARNING_CODES.ASTM_NONSTANDARD_DELIMITERS}: the set it names was
+   * already reported when it came into force.
+   */
+  ASTM_RECORD_DELIMITER_ROLE_COLLISION: "ASTM_RECORD_DELIMITER_ROLE_COLLISION",
+  /**
+   * An escape sequence whose body was **not** a recognized mnemonic held a character that is one of
+   * the three splitting delimiters in force, and the atom rule (an `&X&` triple is opaque) kept it
+   * out of the split, so a boundary the bytes carried never became one. The sequence is preserved
+   * verbatim in the value; nothing is dropped and nothing is re-split.
+   *
+   * Measured on the canonical set: `R|1|^^^687|28.6&|&U/L||||F` reads `value` = `28.6&|&U/L`, with
+   * **no units** and status `unspecified` rather than `final`.
+   *
+   * **This is the code that says a boundary was lost.** The same condition also raises
+   * {@link WARNING_CODES.ASTM_UNKNOWN_ESCAPE_SEQUENCE}, which stays and stays tolerable: that code
+   * reports only that a body was not recognized, which is true of bodies that cost nothing. This one
+   * is the narrower, safety-critical half, and no profile may tolerate it.
+   *
+   * **What it does not do is repair anything.** The atom rule is unchanged (it is what keeps `&F&`
+   * one token under a set that names `F` as a delimiter), so the value is byte-identical to what it
+   * was before this code existed. It also cannot see the condition through a re-emit: emit rewrites
+   * the preserved sequence into recognized mnemonics, and the resulting stream says that value
+   * unambiguously, so a second-generation read is silent and correct about its own bytes. The place
+   * to catch this is the first read of the wire bytes, which is where it now refuses a strict parse.
+   */
+  ASTM_RECORD_DELIMITER_SWALLOWED_BY_ESCAPE: "ASTM_RECORD_DELIMITER_SWALLOWED_BY_ESCAPE",
+  /**
+   * Escape sequences are matched greedily and leftmost, so the escape character that **closed** an
+   * unrecognized sequence could not also **open** the next one. Where it could have, and where the
+   * body it would have held is the delimiter that was split on, the same bytes carry two alignments
+   * that disagree by one boundary: under the reading taken that delimiter ends a field, repeat or
+   * component, and under the other it sits inside an opaque atom and ends nothing. The leftmost
+   * reading is kept, every byte is preserved, and nothing is re-split.
+   *
+   * **This is the mirror of {@link WARNING_CODES.ASTM_RECORD_DELIMITER_SWALLOWED_BY_ESCAPE}, and
+   * the direction is the reason it needs its own code.** That one reports a boundary the reading
+   * **lost**; this one reports a boundary the reading may have **gained**, which is the more
+   * dangerous direction, because a gained boundary hands back a value the sender's bytes do not
+   * unambiguously carry. Measured on the canonical set: `R|1|^^^687|28.6&Z&|&U/L||||F` reads
+   * `value` = `28.6&Z&` and `units` = `&U/L` under the leftmost alignment, and reads as a single
+   * unsplit field carrying both under the other.
+   *
+   * **Two exclusions, both deliberate, and the first is wider than its own argument.** Where the
+   * earlier sequence's body is a **recognized** mnemonic nothing is reported, because the reading
+   * taken interprets a construct (`&F&` is the sender escaping a field separator, which is what the
+   * mechanism is for) while the competing alignment's body is a delimiter character it usually
+   * cannot interpret at all, so this codec's own vocabulary prefers the reading taken. That is not
+   * the same as the reading taken being conformant, and where the declared set names a mnemonic
+   * letter as a splitting delimiter both alignments interpret one construct and neither is
+   * preferred, yet this stays silent. Both residues are measured and recorded rather than closed by
+   * widening the test. And where the escape
+   * character after the delimiter does not itself close a sequence there is no competing alignment
+   * at all, so an ordinary escaped value followed by an ordinary boundary is silent.
+   *
+   * **It is a report, not a repair, and not a round-trip guard.** The reading is unchanged: picking
+   * the other alignment would be a different guess with no more evidence behind it. Emit then
+   * rewrites the preserved sequences into recognized mnemonics, and those bytes carry the reading
+   * that was taken unambiguously, so a second-generation read is silent and is correct about its own
+   * bytes. The first read of the wire bytes is the only place the ambiguity exists to be caught.
+   */
+  ASTM_RECORD_AMBIGUOUS_ESCAPE_ALIGNMENT: "ASTM_RECORD_AMBIGUOUS_ESCAPE_ALIGNMENT",
+  /**
+   * 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 at all**, so the
+   * boundary was bought with a byte 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.
+   *
+   * **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
+   * **8** under the competing one, so the sender's trailing `F` lands in field 9 (the result status)
+   * under the first and in no field at all under the second. The parse hands back units `&U/L` and a
+   * status of **`final`**, and both are consequences of the alignment rather than values the sender
+   * placed in those slots. A downstream system reading `final` would act on a result the bytes do
+   * not say was finalised. Before this code the only warning on that stream was the **tolerable**
+   * {@link WARNING_CODES.ASTM_UNPAIRED_ESCAPE_CHARACTER}, so the widest gate-legal profile plus
+   * `{ strict: true }` accepted it.
+   *
+   * **It is a report, not a repair.** The split is unchanged, every decoded byte is identical, and
+   * the units and status read are the ones that were always read. Picking the other alignment would
+   * be a different guess with no more evidence behind it, and it would change values on a published
+   * package. What is new is that the shift is reported by a code no profile may tolerate.
+   *
+   * **It fires alongside {@link WARNING_CODES.ASTM_RECORD_AMBIGUOUS_ESCAPE_ALIGNMENT}, not instead
+   * of it, and neither test is a widening of the other.** That code asks whether this codec's
+   * vocabulary prefers the reading taken *at* the contested position, and is silent where the
+   * earlier body is a recognized mnemonic. This one asks what the reading taken makes of the bytes
+   * *after* the boundary, and does not consult the earlier body at all.
+   *
+   * **Two deliberate bounds, both stated rather than left to be found.**
+   * - **Only the field role, and that bound is a CHOICE rather than a consequence.** A gained repeat
+   *   or component boundary divides one field and reaches nothing outside it, so it moves no
+   *   **field-indexed** slot: the units and the status stay where they were. **It does not follow
+   *   that it moves no modeled slot at all, and writing that down would be false.** Components are
+   *   modeled *inside* a field: a Universal Test ID's four components are the LOINC-candidate slot,
+   *   the test name, the **coding scheme** and the **local code**, and a patient name's three are
+   *   last, first and middle. A gained component boundary shifts those, so a local code can be read
+   *   as a coding scheme and a given name as a middle name. Measured, and **where the earlier body is
+   *   a recognized mnemonic, reported by nothing** (only the tolerable
+   *   {@link WARNING_CODES.ASTM_UNPAIRED_ESCAPE_CHARACTER} fires, so a gate-legal profile accepts it).
+   *   An **unrecognized** earlier body raises
+   *   {@link WARNING_CODES.ASTM_RECORD_AMBIGUOUS_ESCAPE_ALIGNMENT} there and is refused, which is the
+   *   same split this code's own exclusion takes. It is a separate, open condition rather than something this
+   *   code covers, because wiring this sink to another split is a different criterion needing its own
+   *   population measurement. The repeat role costs the **value**, which this code does not report
+   *   either.
+   * - **The tail is weighed one construct deep.** Where the escape character the reading taken
+   *   resumes on heads a sequence this codec *recognizes*, the reading taken interprets it and the
+   *   competing alignment would leave it bare, so the bytes prefer the reading taken: under a set
+   *   naming the field separator `F`, `28.6&F&F&F&U/L` is that separator escaped, written, and
+   *   escaped again, and refusing it would be an over-refusal of a well-formed stream. Where it
+   *   heads a sequence whose body is *unrecognized*, the reading taken still consumes it while the
+   *   competing alignment would leave **two** escape characters bare, so the preference is stronger
+   *   again, and this stays silent there even though the field shift is real. That last case is the
+   *   named residue: measured, not overlooked.
+   *
+   * **Catch it on the first read.** Emit rewrites the preserved sequences into recognized mnemonics,
+   * and those bytes carry the reading that was taken unambiguously, so a second-generation read is
+   * silent and is correct about its own bytes. A clean re-read is not evidence.
+   */
+  ASTM_RECORD_ALIGNMENT_SHIFTED_FIELDS: "ASTM_RECORD_ALIGNMENT_SHIFTED_FIELDS",
   /** An escape sequence body was not one of `&F&`/`&S&`/`&R&`/`&E&`: preserved verbatim. */
   ASTM_UNKNOWN_ESCAPE_SEQUENCE: "ASTM_UNKNOWN_ESCAPE_SEQUENCE",
   /**
@@ -177,7 +350,8 @@ var WARNING_CODES = {
    * *different* escape character in the same record may still head a real three-character sequence,
    * and if that sequence's body happens to be a delimiter (`&|&` under the canonical set) the atom
    * rule means that delimiter does not split. That case is reported separately, under
-   * {@link WARNING_CODES.ASTM_UNKNOWN_ESCAPE_SEQUENCE}, and it can still cost a field boundary.
+   * {@link WARNING_CODES.ASTM_RECORD_DELIMITER_SWALLOWED_BY_ESCAPE}, and it still costs a field
+   * boundary.
    */
   ASTM_UNPAIRED_ESCAPE_CHARACTER: "ASTM_UNPAIRED_ESCAPE_CHARACTER",
   /**
@@ -243,7 +417,8 @@ var WARNING_CODES = {
    */
   ASTM_RECORD_DELIMITERS_REDECLARED: "ASTM_RECORD_DELIMITERS_REDECLARED",
   /**
-   * A later `H` (header) record could not declare a usable delimiter set: it was too short, or the
+   * A later `H` (header) record could not declare a usable delimiter set: it was not a header, it
+   * was too short, its delimiter definition held fewer than three characters, or the
    * field separator it named also appeared among the other three, leaving the four roles
    * indistinguishable. The delimiters **already in force are kept** and every record is still surfaced;
    * a set is never guessed and no record is dropped.
@@ -285,6 +460,34 @@ function nonStandardDelimiters(position) {
     position
   };
 }
+function delimiterRoleCollision(position) {
+  return {
+    code: WARNING_CODES.ASTM_RECORD_DELIMITER_ROLE_COLLISION,
+    message: "Header declared one character in two delimiter roles, honored as declared; the boundary between those two roles cannot be recovered from the bytes, and emit refuses such a set.",
+    position
+  };
+}
+function delimiterSwallowedByEscape(position) {
+  return {
+    code: WARNING_CODES.ASTM_RECORD_DELIMITER_SWALLOWED_BY_ESCAPE,
+    message: "An unrecognized escape sequence held a delimiter in force, so that delimiter did not end a field, repeat or component. The sequence is preserved verbatim and nothing is re-split.",
+    position
+  };
+}
+function ambiguousEscapeAlignment(position) {
+  return {
+    code: WARNING_CODES.ASTM_RECORD_AMBIGUOUS_ESCAPE_ALIGNMENT,
+    message: "An unrecognized escape sequence ended where another one could have begun, so a delimiter that ended a field, repeat or component here sits inside a sequence under the other alignment. The leftmost alignment was kept, every byte is preserved, and nothing is re-split.",
+    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, which the other alignment uses to close one. 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. The reading was kept and every byte is preserved.",
+    position
+  };
+}
 function delimitersRedeclared(position) {
   return {
     code: WARNING_CODES.ASTM_RECORD_DELIMITERS_REDECLARED,
@@ -900,7 +1103,7 @@ var defaultProfile = defineAstmProfile({
 // src/profiles/reference-corpus.ts
 var referenceCorpus = defineAstmProfile({
   name: "referenceCorpus",
-  description: "Non-standard-escape tolerance grounded firsthand in the escape-agnostic OSS reference corpus (python-astm / senaite). Mostly syntactic encoding noise, with one measured exception: an escape sequence whose body is itself a delimiter is an opaque atom, so that delimiter does not split and a result can lose its units and its status. Read the values; do not rely on this profile leaving only cosmetic deviations behind.",
+  description: "Non-standard-escape tolerance grounded firsthand in the escape-agnostic OSS reference corpus (python-astm / senaite). Mostly syntactic encoding noise, with one measured exception: an escape sequence whose body is an unrecognized character that is itself a delimiter in force is an opaque atom, so that delimiter does not split and a result can lose its units and its status. The mirror case is measured too: sequences are matched leftmost, so one can end where another could have begun and a delimiter splits that the other alignment would have held. Read the values; do not rely on this profile leaving only cosmetic deviations behind.",
   provenance: {
     source: "kxepal/python-astm codec.py (BSD) + senaite.astm / senaite.lis2a",
     reference: "https://github.com/kxepal/python-astm/blob/master/astm/codec.py ; https://github.com/senaite/senaite.astm",
@@ -910,7 +1113,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. Tolerating this code hides that too."
+      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, 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."
     }
   ]
 });
@@ -938,7 +1141,7 @@ function getDefaultAstmProfile() {
 function isEscapeSequenceAt(text, i, escape) {
   return text.charAt(i) === escape && text.charAt(i + 2) === escape;
 }
-function decodeEscapes(leaf, d, onUnknown, onUnpaired) {
+function decodeEscapes(leaf, d, onUnknown, onUnpaired, onSwallowedDelimiter) {
   const esc = d.escape;
   if (!leaf.includes(esc)) return leaf;
   let out = "";
@@ -961,6 +1164,7 @@ function decodeEscapes(leaf, d, onUnknown, onUnpaired) {
     if (replacement === void 0) {
       out += esc + body + esc;
       onUnknown?.();
+      if (isSplittingDelimiter(body, d)) onSwallowedDelimiter?.();
     } else {
       out += replacement;
     }
@@ -968,21 +1172,22 @@ function decodeEscapes(leaf, d, onUnknown, onUnpaired) {
   }
   return out;
 }
+function isSplittingDelimiter(body, d) {
+  return body === d.field || body === d.repeat || body === d.component;
+}
+var MNEMONIC_ROLES = {
+  F: "field",
+  S: "component",
+  R: "repeat",
+  E: "escape"
+};
+function isMnemonicBody(body) {
+  return Object.hasOwn(MNEMONIC_ROLES, body);
+}
 function escapeBody(body, d) {
-  switch (body) {
-    case "F":
-      return d.field;
-    case "S":
-      return d.component;
-    case "R":
-      return d.repeat;
-    case "E":
-      return d.escape;
-    default:
-      return void 0;
-  }
+  return isMnemonicBody(body) ? d[MNEMONIC_ROLES[body]] : void 0;
 }
-function splitEscapeAware(text, delimiter, escape) {
+function splitEscapeAware(text, delimiter, escape, onAmbiguousAlignment, onShiftedFields) {
   if (text.length === 0) return [""];
   const out = [];
   let current = "";
@@ -990,6 +1195,13 @@ function splitEscapeAware(text, delimiter, escape) {
   while (i < text.length) {
     const ch = text.charAt(i);
     if (ch === escape && isEscapeSequenceAt(text, i, escape)) {
+      const contested = text.charAt(i + 3) === delimiter && text.charAt(i + 4) === escape;
+      if (contested && !isMnemonicBody(text.charAt(i + 1))) {
+        onAmbiguousAlignment?.(out.length);
+      }
+      if (contested && !isEscapeSequenceAt(text, i + 4, escape)) {
+        onShiftedFields?.(out.length);
+      }
       current += text.slice(i, i + 3);
       i += 3;
       continue;
@@ -1008,18 +1220,26 @@ function splitEscapeAware(text, delimiter, escape) {
 }
 
 // src/records/tokenize.ts
-function tokenizeRecord(record, d, onUnknownEscape, onUnpairedEscape) {
-  const rawFields = splitEscapeAware(record, d.field, d.escape);
+function tokenizeRecord(record, d, onUnknownEscape, onUnpairedEscape, onSwallowedDelimiter, onAmbiguousAlignment, onAlignmentShiftedFields) {
+  const rawFields = splitEscapeAware(
+    record,
+    d.field,
+    d.escape,
+    (fieldIndex) => onAmbiguousAlignment?.(fieldIndex),
+    (fieldIndex) => onAlignmentShiftedFields?.(fieldIndex)
+  );
   return rawFields.map(
     (raw, fieldIndex) => toField(
       raw,
       d,
       () => onUnknownEscape?.(fieldIndex),
-      () => onUnpairedEscape?.(fieldIndex)
+      () => onUnpairedEscape?.(fieldIndex),
+      () => onSwallowedDelimiter?.(fieldIndex),
+      () => onAmbiguousAlignment?.(fieldIndex)
     )
   );
 }
-function tokenizeHeader(record, d, onUnknownEscape, onUnpairedEscape) {
+function tokenizeHeader(record, d, onUnknownEscape, onUnpairedEscape, onSwallowedDelimiter, onAmbiguousAlignment, onAlignmentShiftedFields) {
   const defEnd = record.indexOf(d.field, 2);
   const definition = defEnd === -1 ? record.slice(2) : record.slice(2, defEnd);
   const head = [opaqueField(record.slice(0, Math.min(1, record.length))), opaqueField(definition)];
@@ -1028,18 +1248,25 @@ function tokenizeHeader(record, d, onUnknownEscape, onUnpairedEscape) {
     record.slice(defEnd + 1),
     d,
     (i) => onUnknownEscape?.(i + 2),
-    (i) => onUnpairedEscape?.(i + 2)
+    (i) => onUnpairedEscape?.(i + 2),
+    (i) => onSwallowedDelimiter?.(i + 2),
+    (i) => onAmbiguousAlignment?.(i + 2),
+    (i) => onAlignmentShiftedFields?.(i + 2)
   );
   return [...head, ...data];
 }
 function opaqueField(raw) {
   return { raw, components: [raw], repeats: [[raw]] };
 }
-function toField(raw, d, onUnknownEscape, onUnpairedEscape) {
-  const rawRepeats = splitEscapeAware(raw, d.repeat, d.escape);
+function toField(raw, d, onUnknownEscape, onUnpairedEscape, onSwallowedDelimiter, onAmbiguousAlignment) {
+  const rawRepeats = splitEscapeAware(raw, d.repeat, d.escape, () => {
+    onAmbiguousAlignment();
+  });
   const repeats = rawRepeats.map(
-    (rep) => splitEscapeAware(rep, d.component, d.escape).map(
-      (comp) => decodeEscapes(comp, d, onUnknownEscape, onUnpairedEscape)
+    (rep) => splitEscapeAware(rep, d.component, d.escape, () => {
+      onAmbiguousAlignment();
+    }).map(
+      (comp) => decodeEscapes(comp, d, onUnknownEscape, onUnpairedEscape, onSwallowedDelimiter)
     )
   );
   const components = repeats[0] ?? [""];
@@ -1076,18 +1303,22 @@ function parseAstmRecords(raw, options = {}) {
       leadType !== void 0 && leadType.length > 0 ? { recordIndex: 0, recordType: leadType } : { recordIndex: 0 }
     );
   }
-  const delimiters = readDelimiters(first);
-  if (delimiters === void 0) {
+  const declaration = readDelimiterDeclaration(first);
+  if (!declaration.ok) {
     throw new AstmParseError(
       FATAL_CODES.ASTM_RECORD_UNDECLARED_DELIMITERS,
-      "Header record is too short to declare the four delimiters.",
+      UNDECLARED_DELIMITER_MESSAGES[declaration.fault],
       { recordIndex: 0, recordType: "H" }
     );
   }
+  const delimiters = declaration.delimiters;
   const warnings = [];
   if (isNonStandard(delimiters)) {
     warnings.push(nonStandardDelimiters({ recordIndex: 0, recordType: "H" }));
   }
+  if (hasCollidingRoles(delimiters)) {
+    warnings.push(delimiterRoleCollision({ recordIndex: 0, recordType: "H" }));
+  }
   let active = delimiters;
   const built = lines.map((line2, recordIndex) => {
     if (recordIndex > 0 && line2.charAt(0) === "H") {
@@ -1119,6 +1350,12 @@ function parseAstmRecords(raw, options = {}) {
   } : { header, records, delimiters, classification, warnings: finalWarnings };
   return deepFreeze(message);
 }
+var UNDECLARED_DELIMITER_MESSAGES = {
+  "not-a-header": "Header record does not begin with an H type letter.",
+  "record-too-short": "Header record is too short to declare the four delimiters.",
+  "definition-truncated": "Header record declares fewer than three delimiter-definition characters before its next field separator, so the repeat, component and escape roles are not all named.",
+  "field-separator-reused": "Header record names its field separator in one of the other three delimiter roles, so the four roles are not distinguishable."
+};
 function resolveProfile(options) {
   if (options.profile === null) return void 0;
   if (options.profile !== void 0) return options.profile;
@@ -1134,6 +1371,7 @@ function adoptRedeclaredDelimiters(line2, active, recordIndex, warnings) {
   if (sameDelimiters(declared, active)) return active;
   warnings.push(delimitersRedeclared(position));
   if (isNonStandard(declared)) warnings.push(nonStandardDelimiters(position));
+  if (hasCollidingRoles(declared)) warnings.push(delimiterRoleCollision(position));
   return declared;
 }
 function sameDelimiters(a, b) {
@@ -1159,7 +1397,38 @@ function buildRecord(line2, recordIndex, d, warnings) {
       unpairedEscapeCharacter({ recordIndex, recordType: rawType, fieldIndex: fieldIndex + 1 })
     );
   };
-  const fields = rawType === "H" ? tokenizeHeader(line2, d, onUnknownEscape, onUnpairedEscape) : tokenizeRecord(line2, d, onUnknownEscape, onUnpairedEscape);
+  const onSwallowedDelimiter = (fieldIndex) => {
+    warnings.push(
+      delimiterSwallowedByEscape({ recordIndex, recordType: rawType, fieldIndex: fieldIndex + 1 })
+    );
+  };
+  const onAmbiguousAlignment = (fieldIndex) => {
+    warnings.push(
+      ambiguousEscapeAlignment({ recordIndex, recordType: rawType, fieldIndex: fieldIndex + 1 })
+    );
+  };
+  const onAlignmentShiftedFields = (fieldIndex) => {
+    warnings.push(
+      alignmentShiftedFields({ recordIndex, recordType: rawType, fieldIndex: fieldIndex + 1 })
+    );
+  };
+  const fields = rawType === "H" ? tokenizeHeader(
+    line2,
+    d,
+    onUnknownEscape,
+    onUnpairedEscape,
+    onSwallowedDelimiter,
+    onAmbiguousAlignment,
+    onAlignmentShiftedFields
+  ) : tokenizeRecord(
+    line2,
+    d,
+    onUnknownEscape,
+    onUnpairedEscape,
+    onSwallowedDelimiter,
+    onAmbiguousAlignment,
+    onAlignmentShiftedFields
+  );
   if (fields.length === 1 && line2.slice(1).trim().length > 0) {
     warnings.push(fieldsUnseparated({ recordIndex, recordType: rawType }));
   }
@@ -1435,6 +1704,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 +1718,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);
@@ -2358,7 +2640,7 @@ function concatBytes3(chunks) {
 }
 
 // src/index.ts
-var VERSION = "0.0.14";
+var VERSION = "0.0.17";
 
 exports.ALL_ASTM_WARNING_CODES = ALL_ASTM_WARNING_CODES;
 exports.AMBIGUOUS_CODES = AMBIGUOUS_CODES;
@@ -2382,6 +2664,8 @@ exports.SAFETY_CRITICAL_CODES = SAFETY_CRITICAL_CODES;
 exports.TOLERABLE_CODES = TOLERABLE_CODES;
 exports.VERSION = VERSION;
 exports.WARNING_CODES = WARNING_CODES;
+exports.alignmentShiftedFields = alignmentShiftedFields;
+exports.ambiguousEscapeAlignment = ambiguousEscapeAlignment;
 exports.ambiguousMessageKind = ambiguousMessageKind;
 exports.ambiguousValueSplit = ambiguousValueSplit;
 exports.applyAstmProfile = applyAstmProfile;
@@ -2401,6 +2685,8 @@ exports.decodeEscapes = decodeEscapes;
 exports.deepFreeze = deepFreeze;
 exports.defineAstmProfile = defineAstmProfile;
 exports.defineLivdCatalog = defineLivdCatalog;
+exports.delimiterRoleCollision = delimiterRoleCollision;
+exports.delimiterSwallowedByEscape = delimiterSwallowedByEscape;
 exports.delimitersRedeclared = delimitersRedeclared;
 exports.detectFraming = detectFraming;
 exports.encodeComponent = encodeComponent;
@@ -2412,6 +2698,7 @@ exports.frameSequenceGap = frameSequenceGap;
 exports.frameUnterminated = frameUnterminated;
 exports.getAstmProfile = getAstmProfile;
 exports.getDefaultAstmProfile = getDefaultAstmProfile;
+exports.hasCollidingRoles = hasCollidingRoles;
 exports.interpretAbnormalFlag = interpretAbnormalFlag;
 exports.interpretResultStatus = interpretResultStatus;
 exports.isNonStandard = isNonStandard;
@@ -2439,6 +2726,7 @@ exports.patient = patient;
 exports.primaryCode = primaryCode;
 exports.profileQuirkApplied = profileQuirkApplied;
 exports.query = query;
+exports.readDelimiterDeclaration = readDelimiterDeclaration;
 exports.readDelimiters = readDelimiters;
 exports.recognizeUniversalTestId = recognizeUniversalTestId;
 exports.resolveProfileTransport = resolveProfileTransport;