@cosyte/astm 0.0.11 → 0.0.13

package/dist/index.d.cts

@@ -2071,15 +2071,43 @@ declare function attachComments(records: readonly AstmRecord[], warnings: AstmRe
  * The serializer refuses: an embedded `CR`/`LF` is a typed {@link AstmSerializeError},
  * never emitted raw.
  *
+ * **A value keeps the bytes the *frame* layer reserves, on purpose.** `STX`, `ETB`
+ * and `ETX` are deliberately **not** refused here. They break a record only once it
+ * is framed, and this layer returns a `string`, which is not yet on any wire: a
+ * consumer on a raw transport, which is a real ASTM deployment this library models
+ * (`detectFraming`), gets such a value back byte for byte through parse and emit,
+ * measured on every modeled value. Refusing it here would take a
+ * byte the caller genuinely supplied away from consumers who never frame anything.
+ * `composeAstmFrames` is the total gate on the framed route, including through
+ * `serializeFramedAstm`, and refuses it there (`ASTM_FRAME_RESERVED_BYTE`).
+ * `CR`/`LF` are different: they end a *record*, so they corrupt this layer's own
+ * output, which is why they are refused at this one.
+ *
+ * **One position is not a modeled value and does not keep the byte:** the surplus
+ * of a header's delimiter declaration, where any control character is dropped
+ * silently (see `declarationResidual` below, where that disposition is argued and
+ * where it long predates the frame-layer refusal). So "the record layer carries
+ * these bytes" is a statement about values, not about every byte of every line.
+ *
  * **Check the delimiter set before writing.** Three conditions are required for the
  * emitted bytes to read back as the records that produced them (each separator exactly
  * one character, no separator a `CR`/`LF`, no two separators the same character) and a
  * set failing any of them is a typed {@link AstmSerializeError}
  * (`ASTM_EMIT_INVALID_DELIMITERS`) rather than output this library's own parser would
- * reject or silently re-read with a different field tree. These are **necessary**
- * conditions, not a guarantee of readback: a set can pass all three and still produce a
- * stream that reads back wrong, a separator that collides with a record's type letter
- * is the known case, and it corrupts identically with or without this check.
+ * reject or silently re-read with a different field tree. These are conditions on the
+ * **set alone**, so they are not a readback guarantee on their own: a set can pass all
+ * three and still collide with a particular record's type letter, which is why that is
+ * checked per record, on the bytes actually written
+ * (`ASTM_EMIT_TYPE_LETTER_COLLISION`). That one is a **transcoding** condition, not
+ * merely a caller's choice of set, so it is reachable on the default canonical path
+ * too, when a record was read under a set other than the one being emitted.
+ *
+ * **What is still not guaranteed.** Together the two checks guarantee that every
+ * record re-reads as its own *type*. They do not guarantee that every *field* of it
+ * lands where it did: an escape sequence whose body is itself a delimiter is read as
+ * one opaque atom, so that delimiter never becomes a boundary and the fields after it
+ * shift. That is reported on the parse side (`ASTM_UNKNOWN_ESCAPE_SEQUENCE`) and is
+ * not what these refusals cover.
  */
 
 /**
@@ -2104,7 +2132,8 @@ declare class AstmSerializeError extends Error {
     /**
      * Stable discriminant. `ASTM_EMIT_UNENCODABLE_VALUE` for a `CR`/`LF` in a value;
      * `ASTM_EMIT_INVALID_DELIMITERS` for a delimiter set that cannot be emitted
-     * reversibly.
+     * reversibly; `ASTM_EMIT_TYPE_LETTER_COLLISION` for a record whose own type
+     * letter the set being emitted with would escape away.
      */
     readonly code: AstmSerializeErrorCode;
     /** 0-based ordinal of the record within the message, when known. */
@@ -2119,8 +2148,14 @@ declare class AstmSerializeError extends Error {
  *   (`CR`/`LF`), which the escape codec has no mnemonic for.
  * - `ASTM_EMIT_INVALID_DELIMITERS`: the delimiter set to emit against failed one
  *   of the three conditions readback requires (see {@link serializeAstmRecords}).
- *   Those conditions are necessary rather than sufficient, so this code means a
+ *   Those conditions are checked against the *set alone*, so this code means a
  *   set was rejected, not that every unreversible set is.
+ * - `ASTM_EMIT_TYPE_LETTER_COLLISION`: this record's type letter would not be the
+ *   first character of its own emitted line, so the record would read back as a
+ *   **different** record. Raised per record rather than per set, because whether
+ *   a set collides depends on which record is being written: a record read under
+ *   one delimiter set and written under another can hit it with **no** set passed
+ *   at all, so it is not avoided by emitting on the default canonical path.
  *
  * @example
  * ```ts
@@ -2128,7 +2163,7 @@ declare class AstmSerializeError extends Error {
  * const code: AstmSerializeErrorCode = "ASTM_EMIT_INVALID_DELIMITERS";
  * ```
  */
-type AstmSerializeErrorCode = "ASTM_EMIT_UNENCODABLE_VALUE" | "ASTM_EMIT_INVALID_DELIMITERS";
+type AstmSerializeErrorCode = "ASTM_EMIT_UNENCODABLE_VALUE" | "ASTM_EMIT_INVALID_DELIMITERS" | "ASTM_EMIT_TYPE_LETTER_COLLISION";
 /**
  * Escape-encode one component leaf for spec-clean emit: the inverse of
  * `decodeEscapes`. The **escape character itself is encoded first** (`&` → `&E&`)
@@ -2146,8 +2181,10 @@ type AstmSerializeErrorCode = "ASTM_EMIT_UNENCODABLE_VALUE" | "ASTM_EMIT_INVALID
  * @returns The escaped component text.
  * @throws {@link AstmSerializeError} for a `CR`/`LF` in the leaf
  *   (`ASTM_EMIT_UNENCODABLE_VALUE`), or for a delimiter set failing one of the
- *   three conditions readback requires (`ASTM_EMIT_INVALID_DELIMITERS`), which
- *   are necessary, not sufficient, so a set can pass them and still not reverse.
+ *   three conditions readback requires (`ASTM_EMIT_INVALID_DELIMITERS`). This
+ *   helper takes a leaf and no record, so it never raises
+ *   `ASTM_EMIT_TYPE_LETTER_COLLISION`: a caller assembling a record line out of it
+ *   is outside that check and gets no guarantee that a type letter survives.
  * @example
  * ```ts
  * import { encodeComponent, CANONICAL_DELIMITERS } from "@cosyte/astm";
@@ -2171,9 +2208,13 @@ declare function encodeComponent(leaf: string, d: Delimiters, recordIndex?: numb
  * @param d - The delimiters to emit against; defaults to `H|\^&`.
  * @returns The record's wire text, terminator excluded.
  * @throws {@link AstmSerializeError} when a component contains an unencodable `CR`/`LF`
- *   (`ASTM_EMIT_UNENCODABLE_VALUE`), or when `d` fails one of the three conditions
- *   readback requires (`ASTM_EMIT_INVALID_DELIMITERS`): necessary conditions, not
- *   sufficient ones, so a set can pass them and still not reverse.
+ *   (`ASTM_EMIT_UNENCODABLE_VALUE`), when `d` fails one of the three conditions
+ *   readback requires (`ASTM_EMIT_INVALID_DELIMITERS`), or when this record's type
+ *   letter would not be the first character of its own emitted line
+ *   (`ASTM_EMIT_TYPE_LETTER_COLLISION`), which would make it read back as a
+ *   different record. That last one is a transcoding condition and needs no `d`
+ *   argument to fire: a record read under a different delimiter set can carry a
+ *   type letter the canonical set escapes away.
  * @example
  * ```ts
  * import { serializeAstmRecord, parseAstmRecords } from "@cosyte/astm";
@@ -2202,18 +2243,29 @@ declare function serializeAstmRecord(record: AstmRecord, d?: Delimiters): string
  * fails is an {@link AstmSerializeError} with code `ASTM_EMIT_INVALID_DELIMITERS`.
  * This is stricter than the parser, which reads some sets it cannot reverse, so
  * `serializeAstmRecords(msg, msg.delimiters)` can refuse a message that parsed:
- * in exactly the cases where it used to emit a stream that read back wrong. The
- * three conditions are necessary rather than sufficient: a set that passes them can
- * still read back wrong if a separator collides with a record's type letter, which
- * this check does not claim to catch.
+ * in exactly the cases where it used to emit a stream that read back wrong.
+ *
+ * **And each record is checked against the set it is being written with.** Those
+ * three conditions read the set alone, so they cannot see that `field` = `R`
+ * escapes an `R` record's own type letter away. Every record's emitted line is
+ * therefore checked to start with the letter the record models, and one that does
+ * not is `ASTM_EMIT_TYPE_LETTER_COLLISION` rather than a stream that reads back as
+ * different records. What neither check promises is that every *field* lands where
+ * it did: an escape sequence whose body is a delimiter is an opaque atom, so that
+ * delimiter never becomes a boundary, and the parse side reports that
+ * (`ASTM_UNKNOWN_ESCAPE_SEQUENCE`) rather than emit refusing it.
  *
  * @param input - A parsed {@link AstmMessage} or a list of {@link AstmRecord}s.
  * @param d - The delimiters to emit against; defaults to the canonical `H|\^&` set.
  * @returns The serialized record stream (`CR` after every record).
  * @throws {@link AstmSerializeError} when a component contains an unencodable `CR`/`LF`
- *   (`ASTM_EMIT_UNENCODABLE_VALUE`), or when `d` fails one of the three conditions
- *   readback requires (`ASTM_EMIT_INVALID_DELIMITERS`): necessary conditions, not
- *   sufficient ones, so a set can pass them and still not reverse.
+ *   (`ASTM_EMIT_UNENCODABLE_VALUE`), when `d` fails one of the three conditions
+ *   readback requires (`ASTM_EMIT_INVALID_DELIMITERS`), or when a record's type
+ *   letter would not be the first character of its own emitted line
+ *   (`ASTM_EMIT_TYPE_LETTER_COLLISION`). The last of the three fires on the
+ *   **default** canonical path as well: it compares each record against the set
+ *   being emitted with, so a record read under a different set can carry a type
+ *   letter the canonical set escapes away. Omitting `d` is not a way around it.
  * @example
  * ```ts
  * import { parseAstmRecords, serializeAstmRecords } from "@cosyte/astm";
@@ -2232,8 +2284,10 @@ declare function serializeAstmRecords(input: AstmMessage | readonly AstmRecord[]
  * @returns The escaped field text.
  * @throws {@link AstmSerializeError} when a component contains an unencodable `CR`/`LF`
  *   (`ASTM_EMIT_UNENCODABLE_VALUE`), or when `d` fails one of the three conditions
- *   readback requires (`ASTM_EMIT_INVALID_DELIMITERS`): necessary conditions, not
- *   sufficient ones, so a set can pass them and still not reverse.
+ *   readback requires (`ASTM_EMIT_INVALID_DELIMITERS`). Like
+ *   {@link encodeComponent} this takes no record, so it never raises
+ *   `ASTM_EMIT_TYPE_LETTER_COLLISION`: encoding a record's type-letter field
+ *   through it will escape that letter away without objecting.
  * @example
  * ```ts
  * import { serializeField, tokenizeRecord, CANONICAL_DELIMITERS } from "@cosyte/astm";
@@ -4375,6 +4429,9 @@ declare function decodeAstmFrames(bytes: Uint8Array, options?: FrameOptions): De
  *   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.
+ * - `ASTM_FRAME_RESERVED_BYTE`: a record holds a byte this layer reads as frame
+ *   structure (`STX`, `ETB` or `ETX`). Framing has no escape mechanism, so such
+ *   a byte cannot be carried inside a frame at all.
  *
  * @example
  * ```ts
@@ -4382,7 +4439,7 @@ declare function decodeAstmFrames(bytes: Uint8Array, options?: FrameOptions): De
  * const code: AstmFrameEncodeErrorCode = "ASTM_FRAME_UNENCODABLE_CHARACTER";
  * ```
  */
-type AstmFrameEncodeErrorCode = "ASTM_FRAME_EMPTY_RECORD" | "ASTM_FRAME_UNENCODABLE_CHARACTER";
+type AstmFrameEncodeErrorCode = "ASTM_FRAME_EMPTY_RECORD" | "ASTM_FRAME_UNENCODABLE_CHARACTER" | "ASTM_FRAME_RESERVED_BYTE";
 /**
  * Thrown by {@link composeAstmFrames} when the input cannot be framed into a
  * spec-clean stream. Carries a stable code + positional context, never the
@@ -4404,6 +4461,16 @@ type AstmFrameEncodeErrorCode = "ASTM_FRAME_EMPTY_RECORD" | "ASTM_FRAME_UNENCODA
  * The refusal removes no capability, it routes you to the parameter that already
  * carried it.
  *
+ * **The reserved-byte case, and why it has no escape hatch.** `STX`, `ETB` and
+ * `ETX` are what {@link decodeAstmFrames} reads as frame structure: `STX` opens
+ * a frame, and the first `ETB`/`ETX` after it *is* the end of that frame's text.
+ * A record carrying one of those bytes therefore cannot be framed and read back,
+ * whichever form it arrives in, and this layer has no escape sequence to hide one
+ * behind. Passing bytes instead of a string does **not** route around it, because
+ * the byte is the problem rather than the encoding. Take the byte out of the value
+ * before framing: which byte belongs in a clinical value is the sender's call, not
+ * this library's, so it refuses rather than substituting or deleting one.
+ *
  * @example
  * ```ts
  * import { composeAstmFrames, AstmFrameEncodeError } from "@cosyte/astm";
@@ -4422,7 +4489,9 @@ declare class AstmFrameEncodeError extends Error {
     /**
      * 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.
+     * point. Enough to find it in the caller's own data. For a record supplied as
+     * a `Uint8Array` this is the offending byte's index, which is the same
+     * position: a record string is a byte string, so the two indices coincide.
      */
     readonly characterIndex?: number;
     /** @internal */
@@ -4456,20 +4525,32 @@ interface ComposeFramesOptions {
  * 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.
+ * byte, the same substitution described above. The reserved-byte check below does
+ * not reach that route either, because it compares elements against the three byte
+ * values and an element like `0x0103` is not one of them, though its low byte
+ * becomes an `ETX` on the wire. Pass a `Uint8Array` or a string.
+ *
+ * **A record carrying a frame-structure byte is refused too, in either form.**
+ * `STX`, `ETB` and `ETX` are what the decoder reads as the shape of a frame, and
+ * framing has no escape sequence to hide one behind, so a record holding one is
+ * `ASTM_FRAME_RESERVED_BYTE` rather than a frame truncated at that byte. It used
+ * to be written as given, and the result was not reliably loud: with the two
+ * following bytes matching, the truncated frame verifies and a whole record is
+ * absorbed into the previous one with an empty warnings array at both layers.
+ * Supplying the record as a `Uint8Array` does not route around this check.
+ *
+ * What is still **not** guaranteed: that an accepted record round-trips through
+ * the *record* layer. A delimiter colliding with a record's type letter, for one,
+ * frames and de-frames byte-exactly and still re-reads as a different record.
  *
  * @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, a record has no
- *   bytes (`ASTM_FRAME_EMPTY_RECORD`), or a record string holds a character above
- *   `U+00FF` (`ASTM_FRAME_UNENCODABLE_CHARACTER`).
+ *   bytes (`ASTM_FRAME_EMPTY_RECORD`), a record string holds a character above
+ *   `U+00FF` (`ASTM_FRAME_UNENCODABLE_CHARACTER`), or a record holds an `STX`,
+ *   `ETB` or `ETX` byte (`ASTM_FRAME_RESERVED_BYTE`).
  * @example
  * ```ts
  * import { composeAstmFrames, decodeAstmFrames } from "@cosyte/astm";
@@ -4548,16 +4629,26 @@ declare function parseFramedAstm(bytes: Uint8Array, options?: FrameOptions & Ast
  *
  * 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.
+ * nothing in the message says which character encoding to turn it into.
+ *
+ * A value carrying a raw `STX`, `ETB` or `ETX` is refused too, and being Latin-1
+ * is no exemption: those three are what {@link decodeAstmFrames} reads as the
+ * shape of a frame, and framing has no escape sequence to hide one behind. The
+ * record layer is happy to hold those as well, so this is a message that
+ * serializes to records perfectly well and cannot be framed.
  *
  * @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 AstmSerializeError} when a value contains an unencodable `CR`/`LF`
+ *   (`ASTM_EMIT_UNENCODABLE_VALUE`), or when a record's own type letter would not
+ *   survive being written in the canonical set this function serializes with
+ *   (`ASTM_EMIT_TYPE_LETTER_COLLISION`). The second reaches messages parsed under a
+ *   **different** delimiter set, since this function passes no set of its own.
  * @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`).
+ *   (`ASTM_FRAME_EMPTY_RECORD`), a value holds a character above `U+00FF`
+ *   (`ASTM_FRAME_UNENCODABLE_CHARACTER`), or a record holds an `STX`, `ETB` or
+ *   `ETX` byte (`ASTM_FRAME_RESERVED_BYTE`).
  * @example
  * ```ts
  * import { parseAstmRecords, serializeFramedAstm, parseFramedAstm } from "@cosyte/astm";

package/dist/index.d.ts

@@ -2071,15 +2071,43 @@ declare function attachComments(records: readonly AstmRecord[], warnings: AstmRe
  * The serializer refuses: an embedded `CR`/`LF` is a typed {@link AstmSerializeError},
  * never emitted raw.
  *
+ * **A value keeps the bytes the *frame* layer reserves, on purpose.** `STX`, `ETB`
+ * and `ETX` are deliberately **not** refused here. They break a record only once it
+ * is framed, and this layer returns a `string`, which is not yet on any wire: a
+ * consumer on a raw transport, which is a real ASTM deployment this library models
+ * (`detectFraming`), gets such a value back byte for byte through parse and emit,
+ * measured on every modeled value. Refusing it here would take a
+ * byte the caller genuinely supplied away from consumers who never frame anything.
+ * `composeAstmFrames` is the total gate on the framed route, including through
+ * `serializeFramedAstm`, and refuses it there (`ASTM_FRAME_RESERVED_BYTE`).
+ * `CR`/`LF` are different: they end a *record*, so they corrupt this layer's own
+ * output, which is why they are refused at this one.
+ *
+ * **One position is not a modeled value and does not keep the byte:** the surplus
+ * of a header's delimiter declaration, where any control character is dropped
+ * silently (see `declarationResidual` below, where that disposition is argued and
+ * where it long predates the frame-layer refusal). So "the record layer carries
+ * these bytes" is a statement about values, not about every byte of every line.
+ *
  * **Check the delimiter set before writing.** Three conditions are required for the
  * emitted bytes to read back as the records that produced them (each separator exactly
  * one character, no separator a `CR`/`LF`, no two separators the same character) and a
  * set failing any of them is a typed {@link AstmSerializeError}
  * (`ASTM_EMIT_INVALID_DELIMITERS`) rather than output this library's own parser would
- * reject or silently re-read with a different field tree. These are **necessary**
- * conditions, not a guarantee of readback: a set can pass all three and still produce a
- * stream that reads back wrong, a separator that collides with a record's type letter
- * is the known case, and it corrupts identically with or without this check.
+ * reject or silently re-read with a different field tree. These are conditions on the
+ * **set alone**, so they are not a readback guarantee on their own: a set can pass all
+ * three and still collide with a particular record's type letter, which is why that is
+ * checked per record, on the bytes actually written
+ * (`ASTM_EMIT_TYPE_LETTER_COLLISION`). That one is a **transcoding** condition, not
+ * merely a caller's choice of set, so it is reachable on the default canonical path
+ * too, when a record was read under a set other than the one being emitted.
+ *
+ * **What is still not guaranteed.** Together the two checks guarantee that every
+ * record re-reads as its own *type*. They do not guarantee that every *field* of it
+ * lands where it did: an escape sequence whose body is itself a delimiter is read as
+ * one opaque atom, so that delimiter never becomes a boundary and the fields after it
+ * shift. That is reported on the parse side (`ASTM_UNKNOWN_ESCAPE_SEQUENCE`) and is
+ * not what these refusals cover.
  */
 
 /**
@@ -2104,7 +2132,8 @@ declare class AstmSerializeError extends Error {
     /**
      * Stable discriminant. `ASTM_EMIT_UNENCODABLE_VALUE` for a `CR`/`LF` in a value;
      * `ASTM_EMIT_INVALID_DELIMITERS` for a delimiter set that cannot be emitted
-     * reversibly.
+     * reversibly; `ASTM_EMIT_TYPE_LETTER_COLLISION` for a record whose own type
+     * letter the set being emitted with would escape away.
      */
     readonly code: AstmSerializeErrorCode;
     /** 0-based ordinal of the record within the message, when known. */
@@ -2119,8 +2148,14 @@ declare class AstmSerializeError extends Error {
  *   (`CR`/`LF`), which the escape codec has no mnemonic for.
  * - `ASTM_EMIT_INVALID_DELIMITERS`: the delimiter set to emit against failed one
  *   of the three conditions readback requires (see {@link serializeAstmRecords}).
- *   Those conditions are necessary rather than sufficient, so this code means a
+ *   Those conditions are checked against the *set alone*, so this code means a
  *   set was rejected, not that every unreversible set is.
+ * - `ASTM_EMIT_TYPE_LETTER_COLLISION`: this record's type letter would not be the
+ *   first character of its own emitted line, so the record would read back as a
+ *   **different** record. Raised per record rather than per set, because whether
+ *   a set collides depends on which record is being written: a record read under
+ *   one delimiter set and written under another can hit it with **no** set passed
+ *   at all, so it is not avoided by emitting on the default canonical path.
  *
  * @example
  * ```ts
@@ -2128,7 +2163,7 @@ declare class AstmSerializeError extends Error {
  * const code: AstmSerializeErrorCode = "ASTM_EMIT_INVALID_DELIMITERS";
  * ```
  */
-type AstmSerializeErrorCode = "ASTM_EMIT_UNENCODABLE_VALUE" | "ASTM_EMIT_INVALID_DELIMITERS";
+type AstmSerializeErrorCode = "ASTM_EMIT_UNENCODABLE_VALUE" | "ASTM_EMIT_INVALID_DELIMITERS" | "ASTM_EMIT_TYPE_LETTER_COLLISION";
 /**
  * Escape-encode one component leaf for spec-clean emit: the inverse of
  * `decodeEscapes`. The **escape character itself is encoded first** (`&` → `&E&`)
@@ -2146,8 +2181,10 @@ type AstmSerializeErrorCode = "ASTM_EMIT_UNENCODABLE_VALUE" | "ASTM_EMIT_INVALID
  * @returns The escaped component text.
  * @throws {@link AstmSerializeError} for a `CR`/`LF` in the leaf
  *   (`ASTM_EMIT_UNENCODABLE_VALUE`), or for a delimiter set failing one of the
- *   three conditions readback requires (`ASTM_EMIT_INVALID_DELIMITERS`), which
- *   are necessary, not sufficient, so a set can pass them and still not reverse.
+ *   three conditions readback requires (`ASTM_EMIT_INVALID_DELIMITERS`). This
+ *   helper takes a leaf and no record, so it never raises
+ *   `ASTM_EMIT_TYPE_LETTER_COLLISION`: a caller assembling a record line out of it
+ *   is outside that check and gets no guarantee that a type letter survives.
  * @example
  * ```ts
  * import { encodeComponent, CANONICAL_DELIMITERS } from "@cosyte/astm";
@@ -2171,9 +2208,13 @@ declare function encodeComponent(leaf: string, d: Delimiters, recordIndex?: numb
  * @param d - The delimiters to emit against; defaults to `H|\^&`.
  * @returns The record's wire text, terminator excluded.
  * @throws {@link AstmSerializeError} when a component contains an unencodable `CR`/`LF`
- *   (`ASTM_EMIT_UNENCODABLE_VALUE`), or when `d` fails one of the three conditions
- *   readback requires (`ASTM_EMIT_INVALID_DELIMITERS`): necessary conditions, not
- *   sufficient ones, so a set can pass them and still not reverse.
+ *   (`ASTM_EMIT_UNENCODABLE_VALUE`), when `d` fails one of the three conditions
+ *   readback requires (`ASTM_EMIT_INVALID_DELIMITERS`), or when this record's type
+ *   letter would not be the first character of its own emitted line
+ *   (`ASTM_EMIT_TYPE_LETTER_COLLISION`), which would make it read back as a
+ *   different record. That last one is a transcoding condition and needs no `d`
+ *   argument to fire: a record read under a different delimiter set can carry a
+ *   type letter the canonical set escapes away.
  * @example
  * ```ts
  * import { serializeAstmRecord, parseAstmRecords } from "@cosyte/astm";
@@ -2202,18 +2243,29 @@ declare function serializeAstmRecord(record: AstmRecord, d?: Delimiters): string
  * fails is an {@link AstmSerializeError} with code `ASTM_EMIT_INVALID_DELIMITERS`.
  * This is stricter than the parser, which reads some sets it cannot reverse, so
  * `serializeAstmRecords(msg, msg.delimiters)` can refuse a message that parsed:
- * in exactly the cases where it used to emit a stream that read back wrong. The
- * three conditions are necessary rather than sufficient: a set that passes them can
- * still read back wrong if a separator collides with a record's type letter, which
- * this check does not claim to catch.
+ * in exactly the cases where it used to emit a stream that read back wrong.
+ *
+ * **And each record is checked against the set it is being written with.** Those
+ * three conditions read the set alone, so they cannot see that `field` = `R`
+ * escapes an `R` record's own type letter away. Every record's emitted line is
+ * therefore checked to start with the letter the record models, and one that does
+ * not is `ASTM_EMIT_TYPE_LETTER_COLLISION` rather than a stream that reads back as
+ * different records. What neither check promises is that every *field* lands where
+ * it did: an escape sequence whose body is a delimiter is an opaque atom, so that
+ * delimiter never becomes a boundary, and the parse side reports that
+ * (`ASTM_UNKNOWN_ESCAPE_SEQUENCE`) rather than emit refusing it.
  *
  * @param input - A parsed {@link AstmMessage} or a list of {@link AstmRecord}s.
  * @param d - The delimiters to emit against; defaults to the canonical `H|\^&` set.
  * @returns The serialized record stream (`CR` after every record).
  * @throws {@link AstmSerializeError} when a component contains an unencodable `CR`/`LF`
- *   (`ASTM_EMIT_UNENCODABLE_VALUE`), or when `d` fails one of the three conditions
- *   readback requires (`ASTM_EMIT_INVALID_DELIMITERS`): necessary conditions, not
- *   sufficient ones, so a set can pass them and still not reverse.
+ *   (`ASTM_EMIT_UNENCODABLE_VALUE`), when `d` fails one of the three conditions
+ *   readback requires (`ASTM_EMIT_INVALID_DELIMITERS`), or when a record's type
+ *   letter would not be the first character of its own emitted line
+ *   (`ASTM_EMIT_TYPE_LETTER_COLLISION`). The last of the three fires on the
+ *   **default** canonical path as well: it compares each record against the set
+ *   being emitted with, so a record read under a different set can carry a type
+ *   letter the canonical set escapes away. Omitting `d` is not a way around it.
  * @example
  * ```ts
  * import { parseAstmRecords, serializeAstmRecords } from "@cosyte/astm";
@@ -2232,8 +2284,10 @@ declare function serializeAstmRecords(input: AstmMessage | readonly AstmRecord[]
  * @returns The escaped field text.
  * @throws {@link AstmSerializeError} when a component contains an unencodable `CR`/`LF`
  *   (`ASTM_EMIT_UNENCODABLE_VALUE`), or when `d` fails one of the three conditions
- *   readback requires (`ASTM_EMIT_INVALID_DELIMITERS`): necessary conditions, not
- *   sufficient ones, so a set can pass them and still not reverse.
+ *   readback requires (`ASTM_EMIT_INVALID_DELIMITERS`). Like
+ *   {@link encodeComponent} this takes no record, so it never raises
+ *   `ASTM_EMIT_TYPE_LETTER_COLLISION`: encoding a record's type-letter field
+ *   through it will escape that letter away without objecting.
  * @example
  * ```ts
  * import { serializeField, tokenizeRecord, CANONICAL_DELIMITERS } from "@cosyte/astm";
@@ -4375,6 +4429,9 @@ declare function decodeAstmFrames(bytes: Uint8Array, options?: FrameOptions): De
  *   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.
+ * - `ASTM_FRAME_RESERVED_BYTE`: a record holds a byte this layer reads as frame
+ *   structure (`STX`, `ETB` or `ETX`). Framing has no escape mechanism, so such
+ *   a byte cannot be carried inside a frame at all.
  *
  * @example
  * ```ts
@@ -4382,7 +4439,7 @@ declare function decodeAstmFrames(bytes: Uint8Array, options?: FrameOptions): De
  * const code: AstmFrameEncodeErrorCode = "ASTM_FRAME_UNENCODABLE_CHARACTER";
  * ```
  */
-type AstmFrameEncodeErrorCode = "ASTM_FRAME_EMPTY_RECORD" | "ASTM_FRAME_UNENCODABLE_CHARACTER";
+type AstmFrameEncodeErrorCode = "ASTM_FRAME_EMPTY_RECORD" | "ASTM_FRAME_UNENCODABLE_CHARACTER" | "ASTM_FRAME_RESERVED_BYTE";
 /**
  * Thrown by {@link composeAstmFrames} when the input cannot be framed into a
  * spec-clean stream. Carries a stable code + positional context, never the
@@ -4404,6 +4461,16 @@ type AstmFrameEncodeErrorCode = "ASTM_FRAME_EMPTY_RECORD" | "ASTM_FRAME_UNENCODA
  * The refusal removes no capability, it routes you to the parameter that already
  * carried it.
  *
+ * **The reserved-byte case, and why it has no escape hatch.** `STX`, `ETB` and
+ * `ETX` are what {@link decodeAstmFrames} reads as frame structure: `STX` opens
+ * a frame, and the first `ETB`/`ETX` after it *is* the end of that frame's text.
+ * A record carrying one of those bytes therefore cannot be framed and read back,
+ * whichever form it arrives in, and this layer has no escape sequence to hide one
+ * behind. Passing bytes instead of a string does **not** route around it, because
+ * the byte is the problem rather than the encoding. Take the byte out of the value
+ * before framing: which byte belongs in a clinical value is the sender's call, not
+ * this library's, so it refuses rather than substituting or deleting one.
+ *
  * @example
  * ```ts
  * import { composeAstmFrames, AstmFrameEncodeError } from "@cosyte/astm";
@@ -4422,7 +4489,9 @@ declare class AstmFrameEncodeError extends Error {
     /**
      * 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.
+     * point. Enough to find it in the caller's own data. For a record supplied as
+     * a `Uint8Array` this is the offending byte's index, which is the same
+     * position: a record string is a byte string, so the two indices coincide.
      */
     readonly characterIndex?: number;
     /** @internal */
@@ -4456,20 +4525,32 @@ interface ComposeFramesOptions {
  * 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.
+ * byte, the same substitution described above. The reserved-byte check below does
+ * not reach that route either, because it compares elements against the three byte
+ * values and an element like `0x0103` is not one of them, though its low byte
+ * becomes an `ETX` on the wire. Pass a `Uint8Array` or a string.
+ *
+ * **A record carrying a frame-structure byte is refused too, in either form.**
+ * `STX`, `ETB` and `ETX` are what the decoder reads as the shape of a frame, and
+ * framing has no escape sequence to hide one behind, so a record holding one is
+ * `ASTM_FRAME_RESERVED_BYTE` rather than a frame truncated at that byte. It used
+ * to be written as given, and the result was not reliably loud: with the two
+ * following bytes matching, the truncated frame verifies and a whole record is
+ * absorbed into the previous one with an empty warnings array at both layers.
+ * Supplying the record as a `Uint8Array` does not route around this check.
+ *
+ * What is still **not** guaranteed: that an accepted record round-trips through
+ * the *record* layer. A delimiter colliding with a record's type letter, for one,
+ * frames and de-frames byte-exactly and still re-reads as a different record.
  *
  * @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, a record has no
- *   bytes (`ASTM_FRAME_EMPTY_RECORD`), or a record string holds a character above
- *   `U+00FF` (`ASTM_FRAME_UNENCODABLE_CHARACTER`).
+ *   bytes (`ASTM_FRAME_EMPTY_RECORD`), a record string holds a character above
+ *   `U+00FF` (`ASTM_FRAME_UNENCODABLE_CHARACTER`), or a record holds an `STX`,
+ *   `ETB` or `ETX` byte (`ASTM_FRAME_RESERVED_BYTE`).
  * @example
  * ```ts
  * import { composeAstmFrames, decodeAstmFrames } from "@cosyte/astm";
@@ -4548,16 +4629,26 @@ declare function parseFramedAstm(bytes: Uint8Array, options?: FrameOptions & Ast
  *
  * 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.
+ * nothing in the message says which character encoding to turn it into.
+ *
+ * A value carrying a raw `STX`, `ETB` or `ETX` is refused too, and being Latin-1
+ * is no exemption: those three are what {@link decodeAstmFrames} reads as the
+ * shape of a frame, and framing has no escape sequence to hide one behind. The
+ * record layer is happy to hold those as well, so this is a message that
+ * serializes to records perfectly well and cannot be framed.
  *
  * @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 AstmSerializeError} when a value contains an unencodable `CR`/`LF`
+ *   (`ASTM_EMIT_UNENCODABLE_VALUE`), or when a record's own type letter would not
+ *   survive being written in the canonical set this function serializes with
+ *   (`ASTM_EMIT_TYPE_LETTER_COLLISION`). The second reaches messages parsed under a
+ *   **different** delimiter set, since this function passes no set of its own.
  * @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`).
+ *   (`ASTM_FRAME_EMPTY_RECORD`), a value holds a character above `U+00FF`
+ *   (`ASTM_FRAME_UNENCODABLE_CHARACTER`), or a record holds an `STX`, `ETB` or
+ *   `ETX` byte (`ASTM_FRAME_RESERVED_BYTE`).
  * @example
  * ```ts
  * import { parseAstmRecords, serializeFramedAstm, parseFramedAstm } from "@cosyte/astm";