@cosyte/astm 0.0.8 → 0.0.10

package/dist/index.d.ts

@@ -57,10 +57,59 @@ declare const WARNING_CODES: {
      * not recognize as one does not open a new message.
      */
     readonly ASTM_RECORD_UNKNOWN_TYPE: "ASTM_RECORD_UNKNOWN_TYPE";
+    /**
+     * The delimiters in force found **no field separator at all** in a record that carries content
+     * beyond its type letter, so the whole record read back as a single field and none of its modeled
+     * fields could be recovered. The raw line is surfaced intact and nothing is dropped, but on a
+     * result record it means the value, the units and the status are all absent from the parsed model.
+     *
+     * This is one signature of a record being read with a delimiter set that does not belong to it,
+     * which is how a delimiter-scoping mistake turns into lost values. It is reported rather than
+     * repaired, because recovering the fields would mean guessing which set the sender meant.
+     *
+     * **Its absence is not evidence that a record was read in its own set.** This tests one of the
+     * four delimiter roles, the field separator, and only in its total form, where that separator
+     * occurs in the line (unescaped). Two whole classes of the same loss are outside it: a foreign set
+     * whose field separator happens to occur somewhere in the line still splits (on the wrong
+     * 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
+     * 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
+     * report that one record definitely lost its fields, never as a sweep that would have fired if
+     * any had.
+     */
+    readonly ASTM_RECORD_FIELDS_UNSEPARATED: "ASTM_RECORD_FIELDS_UNSEPARATED";
     /** The header declared delimiters other than the canonical `H|\^&`: tolerated, noted. */
     readonly ASTM_NONSTANDARD_DELIMITERS: "ASTM_NONSTANDARD_DELIMITERS";
     /** An escape sequence body was not one of `&F&`/`&S&`/`&R&`/`&E&`: preserved verbatim. */
     readonly ASTM_UNKNOWN_ESCAPE_SEQUENCE: "ASTM_UNKNOWN_ESCAPE_SEQUENCE";
+    /**
+     * An escape character appeared where no escape sequence starts (an escape sequence is the escape
+     * character, one body character, and the escape character again). It is read as the **literal
+     * character it is** and kept byte-for-byte in the decoded value. Nothing is dropped and no byte is
+     * invented: this flags that the sender did not write the character the spec-clean way, which
+     * is `&E&`.
+     *
+     * **What it replaced is the reason it exists.** The codec used to read such a character as the
+     * opening of a sequence that never closed and merge the whole remainder of the record into the
+     * field it sat in, reporting nothing at all. One `&` in a result value cost the units, the
+     * abnormal flag and the status together and left the status reading `unspecified` rather than
+     * `final`; one in a surname cost the patient's birth date and sex. Emit then re-escaped the merged
+     * text into a spec-clean-looking line that read back as the same wrong value, so the mis-read
+     * survived a round trip without ever surfacing.
+     *
+     * **This code is not a statement about the rest of the record.** It reports one character. A
+     * *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.
+     */
+    readonly ASTM_UNPAIRED_ESCAPE_CHARACTER: "ASTM_UNPAIRED_ESCAPE_CHARACTER";
     /**
      * A result value field carried an *unescaped* component delimiter, so it split into more than one
      * component. Both the full raw value and the split are surfaced and this warning fires: the
@@ -201,6 +250,28 @@ interface AstmRecordWarning {
  * ```
  */
 declare function unknownRecordType(position: AstmPosition): AstmRecordWarning;
+/**
+ * Build an `ASTM_RECORD_FIELDS_UNSEPARATED` warning. The raw line is surfaced
+ * intact; what is lost is every **modeled** field of the record, because the
+ * delimiters in force never split it.
+ *
+ * **This one is not cosmetic either.** A record with content but no field
+ * separator is a record being read with a delimiter set that does not belong to
+ * it, and on a result record that costs the value, the units and the status in
+ * one go. The fields are not reconstructed, because doing so would mean guessing
+ * which set the sender meant, so a profile is not permitted to tolerate this code.
+ *
+ * **It is a report, not a sweep.** See {@link WARNING_CODES} for the two classes
+ * of the same loss it does not see: its absence never certifies a record split
+ * correctly.
+ *
+ * @example
+ * ```ts
+ * import { fieldsUnseparated } from "@cosyte/astm";
+ * fieldsUnseparated({ recordIndex: 4, recordType: "R" });
+ * ```
+ */
+declare function fieldsUnseparated(position: AstmPosition): AstmRecordWarning;
 /**
  * Build an `ASTM_NONSTANDARD_DELIMITERS` warning. The declared delimiters are
  * used as-is; this only flags that they differ from the canonical set.
@@ -249,6 +320,28 @@ declare function unreadableRedeclaration(position: AstmPosition): AstmRecordWarn
  * ```
  */
 declare function unknownEscapeSequence(position: AstmPosition): AstmRecordWarning;
+/**
+ * Build an `ASTM_UNPAIRED_ESCAPE_CHARACTER` warning. The character is preserved
+ * verbatim as a literal in the decoded value and opens no atom, so it does not
+ * merge the rest of the record; the warning body carries neither the character's
+ * surroundings nor any field value.
+ *
+ * **It is a statement about that one character, not about the record.** A
+ * different escape character in the same record may head a real three-character
+ * sequence, and if that sequence's body is a delimiter, that delimiter does not
+ * split. See {@link WARNING_CODES.ASTM_UNPAIRED_ESCAPE_CHARACTER}.
+ *
+ * A profile **may** tolerate this code: the value it reports is byte-identical
+ * with the warning and without it, because reading the character as a literal is
+ * the parse, not a consequence of the warning.
+ *
+ * @example
+ * ```ts
+ * import { unpairedEscapeCharacter } from "@cosyte/astm";
+ * unpairedEscapeCharacter({ recordIndex: 4, recordType: "R", fieldIndex: 4 });
+ * ```
+ */
+declare function unpairedEscapeCharacter(position: AstmPosition): AstmRecordWarning;
 /**
  * Build an `ASTM_RECORD_AMBIGUOUS_VALUE_SPLIT` warning. Emitted when a result
  * value field split on an unescaped component delimiter: the full raw value and
@@ -1700,6 +1793,16 @@ interface TerminatorRecord extends RecordBase {
  * starts by reading the type letter, so a header the reader could not recognize
  * arrives here instead, opens no message, and the messages either side of it are
  * grouped as one. Check `rawType` before trusting a split.
+ *
+ * **And one of these may be a `Q`.** Message classification counts type letters
+ * too, so a message carrying an unsupported record is classified `indeterminate`
+ * unless a `Q` was read outright: see
+ * {@link AstmMessageClassification.hasUnrecognized}.
+ *
+ * **A header that arrives here also failed to re-scope the delimiters.** The
+ * records after it are read with the set already in force, and where that set is
+ * not theirs they do not split at all, which is reported per record as
+ * `ASTM_RECORD_FIELDS_UNSEPARATED`.
  */
 interface UnsupportedRecord extends RecordBase {
     readonly type: "unsupported";
@@ -1738,7 +1841,14 @@ type AstmMessageKind = "host-query" | "results" | "orders" | "indeterminate";
  * ```
  */
 interface AstmMessageClassification {
-    /** The message kind. */
+    /**
+     * The message kind.
+     *
+     * `indeterminate` also covers a message the reader declines to classify: when
+     * {@link AstmMessageClassification.hasUnrecognized} is `true` and no `Q` was read, the kind is
+     * withheld rather than guessed, because the unreadable letter may have been that `Q`. The `has*`
+     * flags below stay truthful in that case, so a caller that wants the raw counts still has them.
+     */
     readonly kind: AstmMessageKind;
     /** At least one `Q` (request-information) record is present. */
     readonly hasQuery: boolean;
@@ -1747,8 +1857,20 @@ interface AstmMessageClassification {
     /** At least one `O` (order) record is present. */
     readonly hasOrders: boolean;
     /**
-     * `true` **iff** `kind === "host-query"` (a `Q` record is present), the safety surface: gate on this
+     * At least one record's type letter was **not recognized** (an
+     * {@link UnsupportedRecord}), so the letter counts above are known to be incomplete.
+     *
+     * Any of them may have been a `Q`, which is why a message carrying one is classified
+     * `indeterminate` unless a `Q` was read outright. `ASTM_RECORD_UNKNOWN_TYPE` reports the same
+     * condition on {@link AstmMessage.warnings}.
+     */
+    readonly hasUnrecognized: boolean;
+    /**
+     * `true` **iff** `kind === "host-query"` (a `Q` record was read), the safety surface: gate on this
      * before treating records as results, so a query is never misread as a result upload.
+     *
+     * `false` is **not** a warrant that the message is a result set. Read `kind` for that: it is
+     * `indeterminate` whenever the reader could not account for every type letter.
      */
     readonly isHostQueryRequest: boolean;
 }
@@ -2639,6 +2761,17 @@ declare function messages(msg: AstmMessage): readonly AstmStreamMessage[];
  * result set, even if a result record is also present (an anomaly, which the
  * parser flags separately with `ASTM_RECORD_AMBIGUOUS_MESSAGE_KIND`). This is the
  * whole point: a `Q`-bearing message can never silently read as a result upload.
+ *
+ * **A letter the reader could not recognize blocks a positive answer.** The rule
+ * above is stated on a count of type letters, so it only holds while every letter
+ * was legible. A record whose type is unsupported may be the very `Q` the rule
+ * exists to honor, and reading such a message as a result set is exactly the
+ * outcome the rule forbids. So an unsupported record, with no `Q` to settle the
+ * question, yields `indeterminate` rather than `results` or `orders`: the honest
+ * answer is that the kind is not knowable, and the parser reports the unreadable
+ * letter separately with `ASTM_RECORD_UNKNOWN_TYPE`. A `Q` that *was* read still
+ * dominates, because an unreadable letter can only ever add a kind, never remove
+ * the query that is already there.
  */
 
 /**
@@ -2649,6 +2782,12 @@ declare function messages(msg: AstmMessage): readonly AstmStreamMessage[];
  * a result (`R`) record is also present, so a query is never misread as a result
  * upload. (The `Q`+`R` anomaly is separately warned at parse time.)
  *
+ * An **unsupported** record letter with no `Q` alongside it yields `indeterminate`,
+ * never `results` or `orders`: an unreadable letter may have been the `Q`, and
+ * claiming a positive kind over it is how a query comes to read as a result set.
+ * {@link AstmMessageClassification.hasUnrecognized} reports why the answer is
+ * withheld, and the `has*` counts stay truthful throughout.
+ *
  * @param records - The parsed records, in wire order.
  * @returns The message classification.
  * @example
@@ -2677,8 +2816,10 @@ declare function classifyMessage(records: readonly AstmRecord[]): AstmMessageCla
  *
  * @param record - The raw record text.
  * @param d - The delimiters resolved from the header.
- * @param onUnknownEscape - Called (with the 1-based field index) for each
+ * @param onUnknownEscape - Called (with the 0-based field index) for each
  *   unrecognized escape sequence encountered, so the caller can warn.
+ * @param onUnpairedEscape - Called (with the 0-based field index) for each escape
+ *   character that heads no escape sequence and was therefore read as a literal.
  * @returns The record's fields.
  * @example
  * ```ts
@@ -2687,18 +2828,19 @@ declare function classifyMessage(records: readonly AstmRecord[]): AstmMessageCla
  * fields[3].components[0]; // "28.6"
  * ```
  */
-declare function tokenizeRecord(record: string, d: Delimiters, onUnknownEscape?: (fieldIndex: number) => void): AstmField[];
+declare function tokenizeRecord(record: string, d: Delimiters, onUnknownEscape?: (fieldIndex: number) => void, onUnpairedEscape?: (fieldIndex: number) => void): AstmField[];
 /**
  * Tokenize an `H` (header) record into its fields.
  *
  * A header cannot go through {@link tokenizeRecord}: its second field is the
- * **delimiter declaration**, which carries the escape character *literally*
- * rather than as an escape sequence. The generic escape-aware split treats that
- * lone escape character as the opening of an unterminated escape and swallows
- * the whole remainder of the record into one field, so every data field after
- * the declaration is lost. This tokenizer instead takes the declaration verbatim
- * as one opaque field and applies the ordinary escape-aware tokenizer to the
- * data portion that follows it.
+ * **delimiter declaration**, which carries all three non-field delimiters
+ * *literally* rather than as escape sequences. Run through the generic tokenizer
+ * the declaration would be split on its own repeat and component characters and
+ * its escape character would be decoded and reported as unpaired, so what the
+ * header declares would come back as fragments plus a spurious warning. This
+ * tokenizer instead takes the declaration verbatim as one opaque field, never
+ * decoded, and applies the ordinary escape-aware tokenizer to the data portion
+ * that follows it.
  *
  * `fields[0]` is the type-letter field and `fields[1]` is the delimiter
  * declaration (verbatim, never escape-decoded); the header's ASTM data fields
@@ -2708,6 +2850,9 @@ declare function tokenizeRecord(record: string, d: Delimiters, onUnknownEscape?:
  * @param d - The delimiters declared by this header.
  * @param onUnknownEscape - Called with the 0-based whole-record field index for
  *   each unrecognized escape sequence in the data portion.
+ * @param onUnpairedEscape - Called with the 0-based whole-record field index for
+ *   each unpaired escape character in the data portion. The declaration itself is
+ *   opaque, so the escape character it names never reports here.
  * @returns The header's fields.
  * @example
  * ```ts
@@ -2717,7 +2862,7 @@ declare function tokenizeRecord(record: string, d: Delimiters, onUnknownEscape?:
  * fields[4].raw; // "sender"
  * ```
  */
-declare function tokenizeHeader(record: string, d: Delimiters, onUnknownEscape?: (fieldIndex: number) => void): AstmField[];
+declare function tokenizeHeader(record: string, d: Delimiters, onUnknownEscape?: (fieldIndex: number) => void, onUnpairedEscape?: (fieldIndex: number) => void): AstmField[];
 /**
  * The primary scalar of a field: its first repeat's first component, decoded.
  * Returns `undefined` for a truly empty field so callers can distinguish
@@ -2833,6 +2978,26 @@ declare class AstmParseError extends Error {
  * leaf**: the escape sequence survives the split intact and only then decodes to
  * a single literal, so `1&S&40` reads as exactly one component.
  *
+ * **An escape sequence is exactly three characters** (the escape character, one
+ * body character, and the escape character again), and both functions here agree
+ * on that, because they have to: a split that thinks `&X…&` is one atom while the
+ * decoder thinks otherwise is the same class of mis-read the ordering above
+ * exists to prevent. An escape character that does not sit at the head of such a
+ * triple is not an escape at all: it is read as the **literal character it is**,
+ * it opens no atom, and the parse layer reports it
+ * (`ASTM_UNPAIRED_ESCAPE_CHARACTER`). Both functions used to scan forward for the
+ * next escape character with no bound, which meant a single unescaped `&` in a
+ * value merged every field after it into that value, in silence.
+ *
+ * **The atom rule is unchanged and still costs a boundary in one case.** A triple
+ * is opaque by design, so where its body is itself a delimiter (`&|&` under the
+ * canonical set) that delimiter does not split. That is deliberate: it is what
+ * keeps `&F&` one token under a declared set that names `F` as a delimiter. Where
+ * the body is not a recognized mnemonic the parse layer reports it as
+ * `ASTM_UNKNOWN_ESCAPE_SEQUENCE`, so it is never silent, but that code is
+ * tolerable and a field boundary has still gone. Do not "fix" that by narrowing
+ * the atom: the narrowing would break the guarantee the atom exists for.
+ *
  * Re-escaping (the inverse, for spec-clean emit) lives in the serializer and is
  * deliberately not implemented here.
  */
@@ -2844,11 +3009,19 @@ declare class AstmParseError extends Error {
  * warning. Optional so the codec can be used purely.
  */
 type UnknownEscapeSink = () => void;
+/**
+ * A callback the codec calls when it encounters an escape character that does not
+ * head a three-character escape sequence. The character is preserved verbatim as a
+ * literal; the callback lets the parser surface a value-free
+ * `ASTM_UNPAIRED_ESCAPE_CHARACTER` warning. Optional so the codec can be used purely.
+ */
+type UnpairedEscapeSink = () => void;
 /**
  * Decode the four recognized ASTM escape mnemonics in a single already-split
  * leaf (a component string), substituting the *active* delimiters read from the
- * header. Unrecognized `&…&` bodies are preserved verbatim and reported through
- * `onUnknown` (never dropped, never guessed).
+ * header. Unrecognized `&X&` bodies are preserved verbatim and reported through
+ * `onUnknown` (never dropped, never guessed), and an escape character that heads
+ * no sequence at all is preserved as a literal and reported through `onUnpaired`.
  *
  * This runs **after** splitting, so a decoded delimiter becomes ordinary literal
  * text and can never introduce a new split boundary.
@@ -2856,23 +3029,34 @@ type UnknownEscapeSink = () => void;
  * @param leaf - One component string, escape-aware split already applied.
  * @param d - The delimiters resolved from the header.
  * @param onUnknown - Called once per unrecognized escape body encountered.
+ * @param onUnpaired - Called once per escape character that heads no sequence.
  * @returns The decoded string.
  * @example
  * ```ts
  * import { decodeEscapes, CANONICAL_DELIMITERS } from "@cosyte/astm";
  * decodeEscapes("1&S&40", CANONICAL_DELIMITERS); // "1^40"
+ * decodeEscapes("O&Brien", CANONICAL_DELIMITERS); // "O&Brien" (literal, reported)
  * ```
  */
-declare function decodeEscapes(leaf: string, d: Delimiters, onUnknown?: UnknownEscapeSink): string;
+declare function decodeEscapes(leaf: string, d: Delimiters, onUnknown?: UnknownEscapeSink, onUnpaired?: UnpairedEscapeSink): string;
 /**
- * Split `text` on `delimiter`, treating any escape sequence (`escape …
- * escape`) as an opaque atom so a delimiter that appears *inside* an escape body
- * never causes a split. Returns the raw (still-encoded) segments: decoding is
- * the caller's next step, per the escape-aware-split-then-decode contract.
+ * Split `text` on `delimiter`, treating an escape sequence (escape, one body
+ * character, escape) as an opaque atom so a delimiter that appears *inside* an
+ * escape body never causes a split. Returns the raw (still-encoded) segments:
+ * decoding is the caller's next step, per the escape-aware-split-then-decode
+ * contract.
+ *
+ * For the four canonical mnemonics the opacity is belt-and-suspenders (their
+ * bodies are letters, not delimiters), but it makes the "an escaped delimiter is
+ * one token" guarantee hold for any declared delimiter set, including adversarial
+ * input. A single body character is all that guarantee needs.
  *
- * For the four canonical mnemonics this is belt-and-suspenders (their bodies are
- * letters, not delimiters), but it makes the "an escaped delimiter is one token"
- * guarantee hold for any declared delimiter set, including adversarial input.
+ * An escape character that heads no sequence is **not** an escape: it is ordinary
+ * text, and it opens no atom. Reading it as the opening of a sequence that never
+ * closes is what used to merge the whole remainder of a record into one field.
+ * Decoding the resulting leaf is what reports it, so this function stays a pure
+ * split. Note the two rules together: a delimiter after such a character does
+ * split, and a delimiter sitting inside a real three-character atom does not.
  *
  * @param text - The field or repeat string to split.
  * @param delimiter - The delimiter to split on.
@@ -2883,6 +3067,7 @@ declare function decodeEscapes(leaf: string, d: Delimiters, onUnknown?: UnknownE
  * import { splitEscapeAware } from "@cosyte/astm";
  * splitEscapeAware("a^b^c", "^", "&"); // ["a", "b", "c"]
  * splitEscapeAware("1&S&40", "^", "&"); // ["1&S&40"]  (escape body is opaque)
+ * splitEscapeAware("O&Brien^John", "^", "&"); // ["O&Brien", "John"]  (unpaired: literal)
  * ```
  */
 declare function splitEscapeAware(text: string, delimiter: string, escape: string): string[];
@@ -3190,40 +3375,96 @@ declare function resolveProfileTransport(profile: AstmProfile | undefined): Astm
  * where one message ends and the next begins, so an unrecognized header opens no
  * message and two messages are read as one, pairing a patient with results that
  * arrived under a different header. Message classification counts `Q` / `R` / `O`
- * records by the same letter, so an unrecognized `Q` costs a host-query request its
- * `Q`-dominates guarantee: it reads as a result set, and the
- * `ASTM_RECORD_AMBIGUOUS_MESSAGE_KIND` warning that flags that contradiction goes
+ * records by the same letter, so an unrecognized `Q` cost a host-query request its
+ * `Q`-dominates guarantee: it read as a result set, and the
+ * `ASTM_RECORD_AMBIGUOUS_MESSAGE_KIND` warning that flags that contradiction went
  * with it. In both cases `ASTM_RECORD_UNKNOWN_TYPE` is the only warning left on the
  * stream, while the allow-list still described it as harmless. Tolerating it
  * re-badged the single report that the reader had lost its place, and a strict parse
  * then accepted the stream. It is off the list for that reason, and its removal is
  * what part 2 above is written down to prevent a repeat of.
  *
- * **So the three that remain are recorded with the reading each one survives**, not
+ * The classifier no longer answers `results` over a letter it could not read (it
+ * withholds the kind instead), so that particular misreading is closed at the
+ * source as well as reported. The allow-list conclusion is unchanged either way:
+ * part 2 asks whether anything **reads** the reported condition, and the classifier
+ * still does, now to decide whether it may answer at all.
+ *
+ * **A third reader of record structure landed with
+ * `ASTM_RECORD_FIELDS_UNSEPARATED`, and the allow-list was re-derived against it.**
+ * That code reports a record the delimiters in force could not split at all, which
+ * is one signature of a record being read in a set that is not its own. It is
+ * safety-critical (it reports lost values, so it fails part 1 outright) and it is
+ * on the forbidden side by construction, because that side is computed rather than
+ * listed. What it required was re-reading the survivors below against it:
+ * none of them is a statement about whether a record split, so none of them is now
+ * hiding it. Note the code is deliberately **partial** (see its own docs): it does
+ * not fire wherever a field went missing to a foreign delimiter set, only where the
+ * field separator was absent outright, so it is a reader of record structure that
+ * cannot be relied on as a sweep.
+ *
+ * **So the ones that remain are recorded with the reading each one survives**, not
  * merely with the value it preserves. Each was re-derived against both readers of
  * record structure above, plus the single-message / single-patient guards:
  *
  * - `ASTM_NONSTANDARD_DELIMITERS`: the header's own declared delimiters are read
  *   and honored either way, and this notes only that they differ from the canonical
- *   set. Neither reader sees them: the stream is cut into records on a line break,
+ *   set. No reader sees them: the stream is cut into records on a line break,
  *   and a record's type letter is the first character of its line, both taken before
- *   any delimiter-driven tokenization runs.
+ *   any delimiter-driven tokenization runs. It survives the split reader too, and
+ *   the distinction is worth stating precisely: this code says the declared set is
+ *   unusual, `ASTM_RECORD_FIELDS_UNSEPARATED` says a record did not match the set in
+ *   force. A stream may be wholly non-canonical and split perfectly, and a wholly
+ *   canonical stream can still carry a record that does not split, so tolerating the
+ *   first can never quiet the second.
  * - `ASTM_UNKNOWN_ESCAPE_SEQUENCE`: an unrecognized escape body is **preserved
  *   byte-for-byte** in the decoded value (the escape codec does not guess at one),
- *   so the value is identical with or without the profile. Neither reader sees it
- *   either: a decoded field value is never cut back into records, and the type
- *   letter is read before decoding.
+ *   so the value is identical with or without the profile. No reader sees it
+ *   either: a decoded field value is never cut back into records, the type
+ *   letter is read before decoding, and the split reader counts fields, which the
+ *   escape-aware tokenizer has already finished dividing before any body is decoded.
+ *
+ *   **This entry is on the list and is recorded as questionable, deliberately.**
+ *   The argument above is about the *decoded value*, and it holds. What it does not
+ *   cover is that the escape-aware split itself treats an `&X&` triple as opaque, so
+ *   where `X` is a delimiter that delimiter never became a boundary: the split the
+ *   argument says has "already finished dividing" divided one time too few, and this
+ *   code is the only report of it. Measured on the canonical set:
+ *   `R|1|^^^687|28.6&|&U/L||||F` yields a value of `28.6&|&U/L`, no units, and status
+ *   `unspecified` rather than `final`, with this as the sole warning, so a profile
+ *   tolerating it (the shipped `referenceCorpus` does) lets `{ strict: true }` accept
+ *   it. That fails part 1 of the two-clause test on the reading, not on the value.
+ *   It is **left on the list on purpose**: removing it would change behavior for
+ *   every profile naming it, and what should report a swallowed boundary instead, and
+ *   at what severity, is a question this file cannot settle on its own. Do not read
+ *   this bullet as an endorsement; read it as the open question it is, and do not
+ *   close it by narrowing the atom, which is what keeps `&F&` one token under a
+ *   delimiter set that names `F` as a delimiter.
+ * - `ASTM_UNPAIRED_ESCAPE_CHARACTER`: an escape character heading no escape
+ *   sequence, read as the **literal character it is** and kept byte-for-byte in the
+ *   decoded value, so the value is identical with or without the profile. Note what
+ *   makes this admissible is a property of the *parse*, not of the warning: reading
+ *   the character as a literal is unconditional, and tolerating the code changes
+ *   nothing about how the record splits. No reader sees it, on the same grounds as
+ *   the entry above: the type letter is read before any decoding, the split reader
+ *   counts fields the escape-aware tokenizer has already finished dividing, and a
+ *   decoded value is never cut back into records. Contrast the condition it
+ *   replaced, which **would** have failed part 1: reading the same character as an
+ *   unterminated sequence merged every field after it into one, and a code reporting
+ *   that would have been a report of lost values.
  * - `ASTM_RECORD_UNINTERPRETED_QUERY_STATUS`: a request-information status carried
  *   verbatim as a leaf field on a `Q` record; the code set is paywalled and is not
  *   interpreted, profile or not. Classification reads whether a `Q` record is
- *   *present*, never what this field says, and grouping does not read `Q` at all.
+ *   *present*, never what this field says; grouping does not read `Q` at all; and the
+ *   split reader is a count of fields, not a reading of any one of them, so a record
+ *   carrying this warning has by definition already split.
  *
  * Everything a wrong value could hide from: a result value split ambiguity, an
  * undefined abnormal flag or result status, an unparseable reference range, absent
  * units, a mis-attached comment, a partial timestamp, a query-vs-result ambiguity,
- * an unrecognized record type, a bad frame checksum / sequence gap / unterminated /
- * oversize frame, an ambiguous transport, an unexpected protocol event, or a
- * rejected frame: is forbidden.
+ * an unrecognized record type, a record the delimiters in force could not split, a
+ * bad frame checksum / sequence gap / unterminated / oversize frame, an ambiguous
+ * transport, an unexpected protocol event, or a rejected frame: is forbidden.
  *
  * **What this file cannot do for you.** Part 2 is a review obligation, not a
  * mechanical one. There is no honest automatic check for "nothing load-bearing
@@ -3247,8 +3488,12 @@ declare function resolveProfileTransport(profile: AstmProfile | undefined): Astm
  * `ASTM_RECORD_UNKNOWN_TYPE` is **not** on this list, and used to be. An
  * unrecognized record type may be a header the reader did not recognize as one, in
  * which case two messages have been read as one, or a `Q` it did not recognize, in
- * which case a host-query request reads as a result set. Tolerating it can quiet
- * the only report either happened.
+ * which case the message kind is no longer knowable. Tolerating it can quiet the
+ * only report either happened.
+ *
+ * `ASTM_RECORD_FIELDS_UNSEPARATED` is not on this list either, and never was. It
+ * reports a record the delimiters in force could not split, so every modeled field
+ * of that record is missing: it fails the first half of the test outright.
  *
  * @example
  * ```ts
@@ -4115,12 +4360,49 @@ declare function decodeAstmFrames(bytes: Uint8Array, options?: FrameOptions): De
  *
  * A record must carry bytes: an empty record (or an empty record list) is a typed
  * {@link AstmFrameEncodeError}, never an empty frame.
+ *
+ * **A record given as a `string` is a byte string.** Each character stands for one
+ * byte, so a character above `U+00FF` has no byte to stand for and the record is
+ * refused rather than written. See {@link AstmFrameEncodeError} for what that
+ * turns away and how to frame such content instead.
  */
+/**
+ * The reasons {@link composeAstmFrames} refuses rather than emitting bytes that
+ * are not the record it was handed.
+ *
+ * - `ASTM_FRAME_EMPTY_RECORD`: an empty record list, or a record with no bytes.
+ *   A frame must carry a record; an empty one is a structural error, never an
+ *   empty frame.
+ * - `ASTM_FRAME_UNENCODABLE_CHARACTER`: a record given as a `string` holds a
+ *   character above `U+00FF`, which has no single byte to stand for.
+ *
+ * @example
+ * ```ts
+ * import type { AstmFrameEncodeErrorCode } from "@cosyte/astm";
+ * const code: AstmFrameEncodeErrorCode = "ASTM_FRAME_UNENCODABLE_CHARACTER";
+ * ```
+ */
+type AstmFrameEncodeErrorCode = "ASTM_FRAME_EMPTY_RECORD" | "ASTM_FRAME_UNENCODABLE_CHARACTER";
 /**
  * Thrown by {@link composeAstmFrames} when the input cannot be framed into a
- * spec-clean stream: an empty record list, or a record with no bytes (a frame
- * must carry a record; an empty one is a structural error, never an empty frame).
- * Carries a stable code + the offending record index, never record bytes.
+ * spec-clean stream. Carries a stable code + positional context, never the
+ * record bytes and never the offending character (PHI discipline).
+ *
+ * **The unencodable-character case, and why it is a refusal.** A record passed as
+ * a `string` is a **byte string**: character `i` becomes byte `i`, which is the
+ * exact inverse of how this package turns record bytes back into a string (one
+ * `String.fromCharCode` per byte, so every byte survives 1:1). A character above
+ * `U+00FF` has no byte to become. Turning one into bytes takes a character
+ * encoding, and nothing this package reads from an ASTM stream says which one:
+ * it reads no character-set declaration from any record, so picking one would be
+ * a guess at bytes the caller never supplied. Emit also has no warning channel,
+ * so a warning here could only be ignored while the wrong bytes still shipped.
+ *
+ * **Framing content outside Latin-1.** Encode it yourself, with the code page
+ * your instrument actually uses, and hand {@link composeAstmFrames} the
+ * `Uint8Array`: it accepts bytes directly and writes them through untouched.
+ * The refusal removes no capability, it routes you to the parameter that already
+ * carried it.
  *
  * @example
  * ```ts
@@ -4134,11 +4416,17 @@ declare function decodeAstmFrames(bytes: Uint8Array, options?: FrameOptions): De
  */
 declare class AstmFrameEncodeError extends Error {
     /** Stable discriminant. */
-    readonly code: "ASTM_FRAME_EMPTY_RECORD";
+    readonly code: AstmFrameEncodeErrorCode;
     /** Index of the offending record within the input, when applicable. */
     readonly recordIndex?: number;
+    /**
+     * Position of the offending character within that record, when applicable:
+     * its index in the string, never the character itself and never its code
+     * point. Enough to find it in the caller's own data.
+     */
+    readonly characterIndex?: number;
     /** @internal */
-    constructor(message: string, recordIndex?: number);
+    constructor(message: string, recordIndex?: number, code?: AstmFrameEncodeErrorCode, characterIndex?: number);
 }
 /** Options for {@link composeAstmFrames}. */
 interface ComposeFramesOptions {
@@ -4157,11 +4445,31 @@ interface ComposeFramesOptions {
  * across the whole stream; every frame's modulo-256 checksum is computed and
  * emitted uppercase.
  *
+ * **A record in either accepted form is written through unchanged, or refused.** A
+ * record given as a `Uint8Array` is already bytes. A record given as a `string` is
+ * a **byte string**, character `i` becoming byte `i`, the exact inverse of how a
+ * decoded record becomes a string again. A character above `U+00FF` is not a byte,
+ * so it is refused with `ASTM_FRAME_UNENCODABLE_CHARACTER` rather than replaced by
+ * a different character (it used to be truncated to its low byte, which is another
+ * ordinary character, and reached the wire silently). To frame content outside
+ * Latin-1, encode it with the character encoding your instrument uses and pass the
+ * resulting `Uint8Array`. Those two forms are the whole of what `records` accepts.
+ * A caller reaching this from JavaScript with some **other** typed array is outside
+ * the signature and gets no such refusal: each element is still written as its low
+ * byte, the same substitution described above. Pass a `Uint8Array` or a string.
+ *
+ * That covers the string-to-bytes step only. It is **not** a guarantee that any
+ * accepted record reads back: a record already carrying an `STX`, `ETX` or `ETB`
+ * byte is framed as given and re-decodes wrong, which this refusal does not touch
+ * and does not claim to.
+ *
  * @param records - The reassembled record byte-strings (`Uint8Array` or latin1
  *   `string`), one entry per complete record.
  * @param options - Encode options.
  * @returns The framed byte stream.
- * @throws {@link AstmFrameEncodeError} when the list is empty or a record has no bytes.
+ * @throws {@link AstmFrameEncodeError} when the list is empty, a record has no
+ *   bytes (`ASTM_FRAME_EMPTY_RECORD`), or a record string holds a character above
+ *   `U+00FF` (`ASTM_FRAME_UNENCODABLE_CHARACTER`).
  * @example
  * ```ts
  * import { composeAstmFrames, decodeAstmFrames } from "@cosyte/astm";
@@ -4238,11 +4546,18 @@ declare function parseFramedAstm(bytes: Uint8Array, options?: FrameOptions & Ast
  * {@link decodeAstmFrames} reassembles: `parseFramedAstm(serializeFramedAstm(msg))`
  * yields an equal message.
  *
+ * A value carrying a character above `U+00FF` is **refused** here rather than
+ * framed: the record layer is happy to hold one, but a frame carries bytes and
+ * nothing in the message says which character encoding to turn it into. A message
+ * whose every value is Latin-1 is unaffected.
+ *
  * @param input - A parsed {@link AstmMessage} or a list of {@link AstmRecord}s.
  * @param options - Frame-encode options.
  * @returns The framed byte stream.
  * @throws {@link AstmSerializeError} when a value contains an unencodable `CR`/`LF`.
- * @throws {@link AstmFrameEncodeError} when there are no records to frame.
+ * @throws {@link AstmFrameEncodeError} when there are no records to frame
+ *   (`ASTM_FRAME_EMPTY_RECORD`), or a value holds a character above `U+00FF`
+ *   (`ASTM_FRAME_UNENCODABLE_CHARACTER`).
  * @example
  * ```ts
  * import { parseAstmRecords, serializeFramedAstm, parseFramedAstm } from "@cosyte/astm";
@@ -4414,4 +4729,4 @@ declare class AstmFrameStrictError extends Error {
  */
 declare const VERSION: string;
 
-export { ALL_ASTM_WARNING_CODES, AMBIGUOUS_CODES, ACK as ASTM_ACK, ENQ as ASTM_ENQ, EOT as ASTM_EOT, NAK as ASTM_NAK, type AbnormalFlag, type AbnormalFlagCode, type AbnormalFlagMeaning, type AmbiguousCode, type AnyAstmWarningCode, AstmAmbiguousStreamError, type AstmDate, type AstmDatePrecision, type AstmField, type AstmFrame, AstmFrameEncodeError, type AstmFramePosition, AstmFrameStrictError, type AstmFrameWarning, type AstmFraming, type AstmLivdWarning, type AstmLtpWarning, type AstmMessage, type AstmMessageClassification, type AstmMessageKind, AstmParseError, type AstmParseOptions, type AstmPosition, type AstmProfile, AstmProfileDefinitionError, type AstmProfileProvenance, type AstmQuirkMatch, type AstmQuirkTolerance, type AstmRecord, type AstmRecordInput, type AstmRecordWarning, AstmSerializeError, type AstmSerializeErrorCode, type AstmStreamMessage, AstmStrictError, CANONICAL_DELIMITERS, type CommentInput, type CommentRecord, type ComposeFramesOptions, type DecodeAstmFramesResult, type DefineAstmProfileOptions, type Delimiters, type DetectFramingOptions, type DetectFramingResult, FATAL_CODES, FRAME_WARNING_CODES, type FatalCode, type FrameChecksum, type FrameOptions, type FrameTerminator, type FrameWarningCode, type FramedAstmResult, type HeaderInput, type HeaderRecord, LIVD_WARNING_CODES, LTP_WARNING_CODES, type LivdAnnotation, type LivdCatalog, type LivdEntry, type LivdLookup, type LivdMapping, type LivdResult, type LivdWarningCode, type LtpAction, type LtpEvent, type LtpPhase, type LtpState, type LtpTransition, type LtpWarningCode, type ManufacturerRecord, type MessageInput, type OrderInput, type OrderRecord, type PatientInput, type PatientName, type PatientNameInput, type PatientRecord, type QueryInput, type QueryRecord, type ReferenceRange, type ReferenceRangeKind, type ResultInput, type ResultRecord, type ResultStatus, type ResultStatusCode, type ResultStatusMeaning, SAFETY_CRITICAL_CODES, type ScientificRecord, TOLERABLE_CODES, type TerminatorRecord, type UniversalTestId, type UniversalTestIdProvenance, type UnknownEscapeSink, type UnsupportedRecord, VERSION, type VerbatimInput, WARNING_CODES, type WarningCode, ambiguousMessageKind, ambiguousValueSplit, applyAstmProfile, applyAstmProfileToWarnings, applyLivd, astmDateToLocalISO, astmProfiles, attachComments, buildAstmMessage, classifyMessage, comments, commentsFor, composeAstmFrames, computeChecksum, decodeAstmFrames, decodeEscapes, deepFreeze, defineAstmProfile, defineLivdCatalog, delimitersRedeclared, detectFraming, encodeComponent, fieldScalar, frameBadChecksum, frameOversize, frameSequenceGap, frameUnterminated, getAstmProfile, getDefaultAstmProfile, 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, readDelimiters, recognizeUniversalTestId, resolveProfileTransport, results, serializeAstmRecord, serializeAstmRecords, serializeField, serializeFramedAstm, setDefaultAstmProfile, splitEscapeAware, toChecksumHex, tokenizeHeader, tokenizeRecord, undefinedAbnormalFlag, undefinedResultStatus, uninterpretedQueryStatus, unitsAbsent, unknownEscapeSequence, unknownRecordType, unparseableReferenceRange, unreadableRedeclaration };
+export { ALL_ASTM_WARNING_CODES, AMBIGUOUS_CODES, ACK as ASTM_ACK, ENQ as ASTM_ENQ, EOT as ASTM_EOT, NAK as ASTM_NAK, type AbnormalFlag, type AbnormalFlagCode, type AbnormalFlagMeaning, type AmbiguousCode, type AnyAstmWarningCode, AstmAmbiguousStreamError, type AstmDate, type AstmDatePrecision, type AstmField, type AstmFrame, AstmFrameEncodeError, type AstmFrameEncodeErrorCode, type AstmFramePosition, AstmFrameStrictError, type AstmFrameWarning, type AstmFraming, type AstmLivdWarning, type AstmLtpWarning, type AstmMessage, type AstmMessageClassification, type AstmMessageKind, AstmParseError, type AstmParseOptions, type AstmPosition, type AstmProfile, AstmProfileDefinitionError, type AstmProfileProvenance, type AstmQuirkMatch, type AstmQuirkTolerance, type AstmRecord, type AstmRecordInput, type AstmRecordWarning, AstmSerializeError, type AstmSerializeErrorCode, type AstmStreamMessage, AstmStrictError, CANONICAL_DELIMITERS, type CommentInput, type CommentRecord, type ComposeFramesOptions, type DecodeAstmFramesResult, type DefineAstmProfileOptions, type Delimiters, type DetectFramingOptions, type DetectFramingResult, FATAL_CODES, FRAME_WARNING_CODES, type FatalCode, type FrameChecksum, type FrameOptions, type FrameTerminator, type FrameWarningCode, type FramedAstmResult, type HeaderInput, type HeaderRecord, LIVD_WARNING_CODES, LTP_WARNING_CODES, type LivdAnnotation, type LivdCatalog, type LivdEntry, type LivdLookup, type LivdMapping, type LivdResult, type LivdWarningCode, type LtpAction, type LtpEvent, type LtpPhase, type LtpState, type LtpTransition, type LtpWarningCode, type ManufacturerRecord, type MessageInput, type OrderInput, type OrderRecord, type PatientInput, type PatientName, type PatientNameInput, type PatientRecord, type QueryInput, type QueryRecord, type ReferenceRange, type ReferenceRangeKind, type ResultInput, type ResultRecord, type ResultStatus, type ResultStatusCode, type ResultStatusMeaning, SAFETY_CRITICAL_CODES, type ScientificRecord, TOLERABLE_CODES, type TerminatorRecord, type UniversalTestId, type UniversalTestIdProvenance, type UnknownEscapeSink, type UnpairedEscapeSink, type UnsupportedRecord, VERSION, type VerbatimInput, WARNING_CODES, type WarningCode, ambiguousMessageKind, ambiguousValueSplit, applyAstmProfile, applyAstmProfileToWarnings, applyLivd, astmDateToLocalISO, astmProfiles, attachComments, buildAstmMessage, classifyMessage, comments, commentsFor, composeAstmFrames, computeChecksum, decodeAstmFrames, decodeEscapes, deepFreeze, defineAstmProfile, defineLivdCatalog, delimitersRedeclared, detectFraming, encodeComponent, fieldScalar, fieldsUnseparated, frameBadChecksum, frameOversize, frameSequenceGap, frameUnterminated, getAstmProfile, getDefaultAstmProfile, 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, readDelimiters, recognizeUniversalTestId, resolveProfileTransport, results, serializeAstmRecord, serializeAstmRecords, serializeField, serializeFramedAstm, setDefaultAstmProfile, splitEscapeAware, toChecksumHex, tokenizeHeader, tokenizeRecord, undefinedAbnormalFlag, undefinedResultStatus, uninterpretedQueryStatus, unitsAbsent, unknownEscapeSequence, unknownRecordType, unpairedEscapeCharacter, unparseableReferenceRange, unreadableRedeclaration };