@cosyte/astm 0.0.11 → 0.0.14

package/dist/index.d.ts

@@ -1103,7 +1103,7 @@ declare function detectFraming(bytes: Uint8Array, options?: DetectFramingOptions
  * Any warning code from any of the three registries: the record layer
  * (`ASTM_RECORD_*` / `ASTM_NONSTANDARD_DELIMITERS` / `ASTM_UNKNOWN_ESCAPE_SEQUENCE`),
  * the frame codec (`ASTM_FRAME_*`), or the LTP protocol layer (`ASTM_LTP_*`). A
- * {@link QuirkTolerance} may *name* any of them, but the safety gate refuses all
+ * {@link AstmQuirkTolerance} may *name* any of them, but the safety gate refuses all
  * but the small, benign, record-layer subset, so the union exists mainly to let
  * the gate reject a frame/LTP code with a precise, typed message.
  */
@@ -1136,7 +1136,7 @@ interface AstmProfileProvenance {
     readonly note?: string;
 }
 /**
- * Optional structural narrowing for a {@link QuirkTolerance}. When present, the
+ * Optional structural narrowing for an {@link AstmQuirkTolerance}. When present, the
  * tolerance applies only to warnings whose PHI-free {@link AstmPosition} matches
  * every provided field, so a profile can expect a deviation on one record type
  * (e.g. an unknown escape only inside `R` result values) without blanket-tolerating
@@ -1911,7 +1911,7 @@ interface AstmMessage {
      * The vendor profile that was active for this parse, when one applied: its
      * `name` and resolved `lineage` (attribution only; the profile object itself is
      * not embedded). Absent when no profile applied. A profile that tolerated a
-     * deviation shows up as a `PROFILE_QUIRK_APPLIED` entry in {@link warnings}, not
+     * deviation shows up as a `PROFILE_QUIRK_APPLIED` entry in {@link AstmMessage.warnings}, not
      * here.
      */
     readonly profile?: {
@@ -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";
@@ -4353,7 +4407,8 @@ declare function decodeAstmFrames(bytes: Uint8Array, options?: FrameOptions): De
  *   case of);
  * - the **frame number** `0`–`7`, starting at `1` and rolling over `7 → 0 → 1`,
  *   continuous across every frame in the stream (as the decoder's sequence check
- *   expects);
+ *   expects); a caller may start the sequence elsewhere to compose one transfer
+ *   across several calls, but only at a number a frame can actually carry;
  * - the **240-byte text split**: a record longer than 240 bytes is split across
  *   frames closed by `ETB` (intermediate) with a final `ETX`; the seven framing
  *   control bytes are never counted toward the 240.
@@ -4375,6 +4430,12 @@ 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.
+ * - `ASTM_FRAME_INVALID_START_FRAME_NUMBER`: `options.startFrameNumber` is not a
+ *   whole number from `0` to `7`. A frame's number is one ASCII digit, so a
+ *   value outside that range has no digit to be written as.
  *
  * @example
  * ```ts
@@ -4382,7 +4443,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" | "ASTM_FRAME_INVALID_START_FRAME_NUMBER";
 /**
  * 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 +4465,30 @@ 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.
+ *
+ * **The start-frame-number case, and why an option gets an error of its own.** A
+ * frame's number is a single ASCII digit, `FN_ZERO + n` for `n` in `0`-`7`, and
+ * nothing used to check that `options.startFrameNumber` was one. What went out
+ * instead was whatever byte that sum truncated to: measured on this package's own
+ * round trip, `-1` wrote `/` into the frame-number position and `NaN`, `Infinity`
+ * and `-Infinity` each wrote a `NUL` byte into every frame of the stream, after
+ * which the decoder read no frame number at all and emitted **none** of the
+ * records. Out-of-domain values that happened to land back on a digit were worse
+ * in a quieter way: `1.5` and `257` both produced the byte-for-byte stream a
+ * `startFrameNumber` of `1` produces, so the option silently accepted a value it
+ * documented as invalid. This one refusal is about the caller's own option rather
+ * than about record content, so its message names the value received. Nothing
+ * from the stream is quoted.
+ *
  * @example
  * ```ts
  * import { composeAstmFrames, AstmFrameEncodeError } from "@cosyte/astm";
@@ -4422,7 +4507,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 */
@@ -4431,8 +4518,42 @@ declare class AstmFrameEncodeError extends Error {
 /** Options for {@link composeAstmFrames}. */
 interface ComposeFramesOptions {
     /**
-     * The frame number to start the sequence at (`0`–`7`). Defaults to
-     * {@link FIRST_FRAME_NUMBER} (`1`): the ASTM convention.
+     * The frame number to start the sequence at: a whole number from `0` to `7`.
+     * Defaults to `1`, the number ASTM gives the first frame of a transfer and the
+     * one {@link decodeAstmFrames} expects to read first.
+     *
+     * **Any other value writes a continuation rather than the start of a transfer,
+     * and that is what the option is for**: composing one transfer across more than
+     * one call. Concatenating `composeAstmFrames(head)` with
+     * `composeAstmFrames(tail, { startFrameNumber: n })`, where `n` is the number
+     * after the last frame `head` used, is byte-identical to composing the whole
+     * list in a single call and decodes with an empty warnings array, across the
+     * `7 → 0` rollover included.
+     *
+     * **Decoded on its own, a stream that starts anywhere but `1` opens on a
+     * sequence gap.** The decoder never bridges a gap silently, so it warns
+     * (`ASTM_FRAME_SEQUENCE_GAP`) and does not emit that first record.
+     * **What {@link parseFramedAstm} does after that varies with the message
+     * shape and no rule is offered for it here.** It may throw, under more than
+     * one code, and it may return a message that is simply one record short. **The
+     * one thing that does hold is that the record layer never reports the loss**:
+     * `parseFramedAstm` hands the record parser only the frames the codec
+     * vouched for, so `message.warnings` carries what the surviving records
+     * warrant and nothing about the record that did not survive. **Read
+     * `frameWarnings`.** That is the cost of the option rather than a defect in
+     * the caller's records, and it is why `1` is the default.
+     *
+     * **Finding the number to continue from.** Nothing here returns it, and the
+     * frame count is not it once a record splits: decode the part you just
+     * composed and read the last frame's number, then add one modulo 8, as in
+     * `((decodeAstmFrames(part).frames.at(-1)?.frameNumber ?? 0) + 1) % 8`. A frame
+     * carries no number only when the stream ends immediately after its `STX`,
+     * which is not something this encoder writes, so that fallback never fires on
+     * a part composed here. Getting the number wrong costs the record at the join,
+     * warned rather than silently.
+     *
+     * A value outside `0`-`7`, or one that is not a whole number, is refused with
+     * `ASTM_FRAME_INVALID_START_FRAME_NUMBER`.
      */
     readonly startFrameNumber?: number;
 }
@@ -4456,20 +4577,45 @@ 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.
+ *
+ * **`options.startFrameNumber` is checked before *this function* reads a record**,
+ * so on this entry point the refusal never depends on the caller's data.
+ * ({@link serializeFramedAstm} serializes every record *before* it gets here, so
+ * a record that cannot be serialized is refused first on that route.) It has to
+ * be a whole number from `0` to `7`, because a frame's number is one ASCII digit;
+ * anything else is `ASTM_FRAME_INVALID_START_FRAME_NUMBER` rather than whatever
+ * byte the arithmetic truncated to. A value other than the default `1` writes a
+ * **continuation** of a sequence already in progress, which is what the option is
+ * for, and a continuation decoded on its own opens on a sequence gap: see
+ * {@link ComposeFramesOptions}.
+ *
+ * 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`).
+ * @throws {@link AstmFrameEncodeError} when `options.startFrameNumber` is not a
+ *   whole number from `0` to `7` (`ASTM_FRAME_INVALID_START_FRAME_NUMBER`), the
+ *   list is empty, a record has no 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";
@@ -4544,20 +4690,35 @@ declare function parseFramedAstm(bytes: Uint8Array, options?: FrameOptions & Ast
  * delimiters, embedded delimiters re-escaped) and then framed **independently**
  * (one record per `ETX`-closed frame run), so the framing exactly mirrors what
  * {@link decodeAstmFrames} reassembles: `parseFramedAstm(serializeFramedAstm(msg))`
- * yields an equal message.
+ * yields an equal message **with the default `startFrameNumber`**. That clause is
+ * load-bearing rather than pedantic: a non-default start writes a continuation of
+ * a sequence already in progress, and a continuation read on its own opens on a
+ * sequence gap, so the decoder does not emit its first record and this round trip
+ * does not hold for it. See {@link ComposeFramesOptions}.
  *
  * 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 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`).
+ * @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 `options.startFrameNumber` is not a
+ *   whole number from `0` to `7` (`ASTM_FRAME_INVALID_START_FRAME_NUMBER`), there
+ *   are no records to frame (`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.mjs

@@ -1385,7 +1385,8 @@ var AstmSerializeError = class 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.
    */
   code;
   /** 0-based ordinal of the record within the message, when known. */
@@ -1449,10 +1450,24 @@ function serializeAstmRecord(record, d = CANONICAL_DELIMITERS) {
   return serializeRecordChecked(record, d);
 }
 function serializeRecordChecked(record, d) {
+  return assertTypeLetterSurvives(serializeRecordText(record, d), record);
+}
+function serializeRecordText(record, d) {
   if (record.type === "M" || record.type === "S") return serializeVerbatimRecord(record, d);
   if (record.type === "H") return serializeHeader(record, d);
   return record.fields.map((f) => encodeField(f.repeats, d, record.recordIndex)).join(d.field);
 }
+function recordTypeLetter(record) {
+  return record.type === "unsupported" ? record.rawType : record.type;
+}
+function assertTypeLetterSurvives(text, record) {
+  if (text.charAt(0) === recordTypeLetter(record)) return text;
+  throw new AstmSerializeError(
+    "A record's type letter is escaped away by the delimiters being emitted with, so the record would read back as a different record. The record's index is on the error; the letter itself is not quoted, because on an unsupported record it is a byte off the wire.",
+    record.recordIndex,
+    "ASTM_EMIT_TYPE_LETTER_COLLISION"
+  );
+}
 function serializeVerbatimRecord(record, d) {
   if (recoversVerbatim(record, d)) return record.rawLine;
   return record.fields.map((f) => encodeField(f.repeats, d, record.recordIndex)).join(d.field);
@@ -2227,7 +2242,9 @@ var AstmFrameEncodeError = class 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.
    */
   characterIndex;
   /** @internal */
@@ -2257,6 +2274,29 @@ function toBytes(input, recordIndex) {
   }
   return out;
 }
+var RESERVED_STRUCTURE_BYTES = /* @__PURE__ */ new Set([STX, ETB, ETX]);
+function assertFramable(bytes, recordIndex) {
+  for (let i = 0; i < bytes.length; i += 1) {
+    const byte = bytes[i];
+    if (byte !== void 0 && RESERVED_STRUCTURE_BYTES.has(byte)) {
+      throw new AstmFrameEncodeError(
+        "A record contains a byte the framing layer reads as structure (STX, ETB or ETX). A frame has no escape sequence for one, so it cannot be carried inside a frame: remove it from the record before framing.",
+        recordIndex,
+        "ASTM_FRAME_RESERVED_BYTE",
+        i
+      );
+    }
+  }
+}
+function assertStartFrameNumber(value) {
+  if (!Number.isInteger(value) || value < 0 || value > FRAME_NUMBER_MODULUS - 1) {
+    throw new AstmFrameEncodeError(
+      `startFrameNumber must be a whole number from 0 to 7: a frame's number is one ASCII digit and the sequence is modulo 8. Received: ${String(value)}.`,
+      void 0,
+      "ASTM_FRAME_INVALID_START_FRAME_NUMBER"
+    );
+  }
+}
 function encodeFrame(text, frameNumber, isFinal) {
   const term = isFinal ? ETX : ETB;
   const bytes = [STX, FN_ZERO + frameNumber, ...text, term];
@@ -2265,11 +2305,13 @@ function encodeFrame(text, frameNumber, isFinal) {
   return [...bytes, hex.charCodeAt(0), hex.charCodeAt(1), CR, LF];
 }
 function composeAstmFrames(records, options = {}) {
+  const start = options.startFrameNumber ?? FIRST_FRAME_NUMBER;
+  assertStartFrameNumber(start);
   if (records.length === 0) {
     throw new AstmFrameEncodeError("Cannot frame an empty record list: nothing to transmit.");
   }
   const out = [];
-  let frameNumber = options.startFrameNumber ?? FIRST_FRAME_NUMBER;
+  let frameNumber = start;
   records.forEach((record, recordIndex) => {
     const bytes = toBytes(record, recordIndex);
     if (bytes.length === 0) {
@@ -2278,6 +2320,7 @@ function composeAstmFrames(records, options = {}) {
         recordIndex
       );
     }
+    assertFramable(bytes, recordIndex);
     for (let offset = 0; offset < bytes.length; offset += MAX_FRAME_TEXT) {
       const chunk = bytes.subarray(offset, offset + MAX_FRAME_TEXT);
       const isFinal = offset + MAX_FRAME_TEXT >= bytes.length;
@@ -2313,7 +2356,7 @@ function concatBytes3(chunks) {
 }
 
 // src/index.ts
-var VERSION = "0.0.11";
+var VERSION = "0.0.14";
 
 export { ALL_ASTM_WARNING_CODES, AMBIGUOUS_CODES, ACK as ASTM_ACK, ENQ as ASTM_ENQ, EOT as ASTM_EOT, NAK as ASTM_NAK, AstmAmbiguousStreamError, AstmFrameEncodeError, AstmFrameStrictError, AstmParseError, AstmProfileDefinitionError, AstmSerializeError, AstmStrictError, CANONICAL_DELIMITERS, FATAL_CODES, FRAME_WARNING_CODES, LIVD_WARNING_CODES, LTP_WARNING_CODES, SAFETY_CRITICAL_CODES, TOLERABLE_CODES, VERSION, WARNING_CODES, 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 };
 //# sourceMappingURL=index.mjs.map