@cosyte/astm 0.0.13 → 0.0.15

package/dist/index.d.cts

@@ -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?: {
@@ -2042,7 +2042,10 @@ declare function attachComments(records: readonly AstmRecord[], warnings: AstmRe
  * set (a non-canonical source is normalized to `H|\^&` by default). Normalizing sets the
  * four delimiter **roles**; it does not delete a declaration's surplus characters, so a
  * canonically-declared header that arrived carrying surplus keeps it on the default path
- * too.
+ * too, **except where that surplus could not be read back as surplus, when all of it is
+ * dropped** (see `declarationResidual` below). Emit re-encodes what it read, so bytes
+ * can differ without anything being lost: `O&BRIEN` in a canonical stream goes out as
+ * `O&E&BRIEN`.
  *
  * **One delimiter set for the whole stream.** Every record (including `H`, `M` and `S`)
  * is emitted against the delimiters being emitted with, and the header declares that same
@@ -2063,7 +2066,11 @@ declare function attachComments(records: readonly AstmRecord[], warnings: AstmRe
  * `H|\^&#` rather than losing the `#`. That holds on the **default** canonical path as
  * well as when a set is passed explicitly: the surplus of a canonically-declared header
  * survives normalization, because normalization is about the four roles and the surplus
- * has none.
+ * has none. It stops holding where the surplus itself could not be read back, and then
+ * **the whole surplus is dropped, not the offending character alone**, on the default
+ * path as much as any other: `declarationResidual` states which surpluses those are and
+ * why an all-or-nothing drop is the only one of the available answers that invents
+ * nothing.
  *
  * **Never break framing.** A component leaf that contains a record terminator
  * (`CR`/`LF`) cannot be escaped by the ASTM escape codec (only the four declared
@@ -2084,10 +2091,15 @@ declare function attachComments(records: readonly AstmRecord[], warnings: AstmRe
  * 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
+ * of a header's delimiter declaration, where a 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.
+ * Measured, one character at a time in the surplus of an otherwise spec-clean
+ * `H|\^&` header: **31 of the 33 C0/`DEL` characters reach that rule and are
+ * dropped**, with `warnings: []` and no error. The two that do not are `CR` and
+ * `LF`, which never reach it at all, because they end the record while it is being
+ * read and so are never part of any surplus the model carries.
  *
  * **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
@@ -2166,10 +2178,12 @@ declare class AstmSerializeError extends Error {
 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&`)
- * so a later delimiter substitution can never double-encode the `&` it just
- * introduced; then the field / component / repeat delimiters map to their
- * mnemonics.
+ * `decodeEscapes`. Each character is read **once**, in one left-to-right pass, and
+ * written either as itself or as a whole `escape` + mnemonic + `escape` triple
+ * (`&` → `&E&`, the field / component / repeat delimiters → `&F&` / `&S&` / `&R&`).
+ * Nothing this encoder writes is examined again, which is what makes it the exact
+ * inverse of the decoder: the decoder reads the same output one token at a time,
+ * so every triple it meets is a triple this encoder wrote.
  *
  * A `CR`/`LF` in the leaf has no escape mnemonic and would break framing, so it
  * is rejected with an {@link AstmSerializeError} rather than emitted raw, as is a
@@ -2199,7 +2213,11 @@ declare function encodeComponent(leaf: string, d: Delimiters, recordIndex?: numb
  * The header (`H`) is special-cased: its delimiter-definition field is emitted as
  * the **literal** declaration of `d`, never escaped, escaping it would corrupt the
  * very declaration a reader depends on, followed by any characters the modeled
- * declaration carried beyond the three a reader takes its roles from. Manufacturer
+ * declaration carried beyond the three a reader takes its roles from. Those surplus
+ * characters are kept unless the surplus could not be read back as surplus, when
+ * **all** of it is dropped: that covers a surplus carrying the field delimiter or
+ * any control character, and it is silent, because emit has no warning channel.
+ * Manufacturer
  * (`M`) and scientific (`S`) records are reproduced **byte-identically** from their
  * preserved `rawLine` when they are already in `d`, and re-encoded from their fields
  * when they are not, so their fields never collapse into one on the next read.
@@ -2234,7 +2252,11 @@ declare function serializeAstmRecord(record: AstmRecord, d?: Delimiters): string
  * re-parsing it recovers every field. Passing `d` explicitly emits against that set
  * instead, and the header declares it. Normalization replaces the four delimiter
  * **roles**; a header declaration carrying characters beyond the three that hold a
- * role keeps them, on this path as on any other, rather than being truncated.
+ * role keeps them, on this path as on any other, rather than being truncated. The
+ * exception is a surplus that could not be read back as one, carrying the field
+ * delimiter or any control character: there the **whole** surplus is dropped, on
+ * every path including the default one, and silently, because emit returns a bare
+ * string with no channel to say so.
  *
  * **`d` is checked before anything is written.** Each of the four separators must be
  * exactly one character, none may be a record terminator, and no two may share a
@@ -4407,7 +4429,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.
@@ -4432,6 +4455,9 @@ declare function decodeAstmFrames(bytes: Uint8Array, options?: FrameOptions): De
  * - `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
@@ -4439,7 +4465,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" | "ASTM_FRAME_RESERVED_BYTE";
+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
@@ -4471,6 +4497,20 @@ type AstmFrameEncodeErrorCode = "ASTM_FRAME_EMPTY_RECORD" | "ASTM_FRAME_UNENCODA
  * 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";
@@ -4500,8 +4540,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;
 }
@@ -4539,6 +4613,17 @@ interface ComposeFramesOptions {
  * 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.
@@ -4547,10 +4632,12 @@ interface ComposeFramesOptions {
  *   `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`), 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`).
+ * @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";
@@ -4625,7 +4712,11 @@ 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
@@ -4645,10 +4736,11 @@ declare function parseFramedAstm(bytes: Uint8Array, options?: FrameOptions & Ast
  *   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`), 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`).
+ * @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.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?: {
@@ -2042,7 +2042,10 @@ declare function attachComments(records: readonly AstmRecord[], warnings: AstmRe
  * set (a non-canonical source is normalized to `H|\^&` by default). Normalizing sets the
  * four delimiter **roles**; it does not delete a declaration's surplus characters, so a
  * canonically-declared header that arrived carrying surplus keeps it on the default path
- * too.
+ * too, **except where that surplus could not be read back as surplus, when all of it is
+ * dropped** (see `declarationResidual` below). Emit re-encodes what it read, so bytes
+ * can differ without anything being lost: `O&BRIEN` in a canonical stream goes out as
+ * `O&E&BRIEN`.
  *
  * **One delimiter set for the whole stream.** Every record (including `H`, `M` and `S`)
  * is emitted against the delimiters being emitted with, and the header declares that same
@@ -2063,7 +2066,11 @@ declare function attachComments(records: readonly AstmRecord[], warnings: AstmRe
  * `H|\^&#` rather than losing the `#`. That holds on the **default** canonical path as
  * well as when a set is passed explicitly: the surplus of a canonically-declared header
  * survives normalization, because normalization is about the four roles and the surplus
- * has none.
+ * has none. It stops holding where the surplus itself could not be read back, and then
+ * **the whole surplus is dropped, not the offending character alone**, on the default
+ * path as much as any other: `declarationResidual` states which surpluses those are and
+ * why an all-or-nothing drop is the only one of the available answers that invents
+ * nothing.
  *
  * **Never break framing.** A component leaf that contains a record terminator
  * (`CR`/`LF`) cannot be escaped by the ASTM escape codec (only the four declared
@@ -2084,10 +2091,15 @@ declare function attachComments(records: readonly AstmRecord[], warnings: AstmRe
  * 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
+ * of a header's delimiter declaration, where a 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.
+ * Measured, one character at a time in the surplus of an otherwise spec-clean
+ * `H|\^&` header: **31 of the 33 C0/`DEL` characters reach that rule and are
+ * dropped**, with `warnings: []` and no error. The two that do not are `CR` and
+ * `LF`, which never reach it at all, because they end the record while it is being
+ * read and so are never part of any surplus the model carries.
  *
  * **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
@@ -2166,10 +2178,12 @@ declare class AstmSerializeError extends Error {
 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&`)
- * so a later delimiter substitution can never double-encode the `&` it just
- * introduced; then the field / component / repeat delimiters map to their
- * mnemonics.
+ * `decodeEscapes`. Each character is read **once**, in one left-to-right pass, and
+ * written either as itself or as a whole `escape` + mnemonic + `escape` triple
+ * (`&` → `&E&`, the field / component / repeat delimiters → `&F&` / `&S&` / `&R&`).
+ * Nothing this encoder writes is examined again, which is what makes it the exact
+ * inverse of the decoder: the decoder reads the same output one token at a time,
+ * so every triple it meets is a triple this encoder wrote.
  *
  * A `CR`/`LF` in the leaf has no escape mnemonic and would break framing, so it
  * is rejected with an {@link AstmSerializeError} rather than emitted raw, as is a
@@ -2199,7 +2213,11 @@ declare function encodeComponent(leaf: string, d: Delimiters, recordIndex?: numb
  * The header (`H`) is special-cased: its delimiter-definition field is emitted as
  * the **literal** declaration of `d`, never escaped, escaping it would corrupt the
  * very declaration a reader depends on, followed by any characters the modeled
- * declaration carried beyond the three a reader takes its roles from. Manufacturer
+ * declaration carried beyond the three a reader takes its roles from. Those surplus
+ * characters are kept unless the surplus could not be read back as surplus, when
+ * **all** of it is dropped: that covers a surplus carrying the field delimiter or
+ * any control character, and it is silent, because emit has no warning channel.
+ * Manufacturer
  * (`M`) and scientific (`S`) records are reproduced **byte-identically** from their
  * preserved `rawLine` when they are already in `d`, and re-encoded from their fields
  * when they are not, so their fields never collapse into one on the next read.
@@ -2234,7 +2252,11 @@ declare function serializeAstmRecord(record: AstmRecord, d?: Delimiters): string
  * re-parsing it recovers every field. Passing `d` explicitly emits against that set
  * instead, and the header declares it. Normalization replaces the four delimiter
  * **roles**; a header declaration carrying characters beyond the three that hold a
- * role keeps them, on this path as on any other, rather than being truncated.
+ * role keeps them, on this path as on any other, rather than being truncated. The
+ * exception is a surplus that could not be read back as one, carrying the field
+ * delimiter or any control character: there the **whole** surplus is dropped, on
+ * every path including the default one, and silently, because emit returns a bare
+ * string with no channel to say so.
  *
  * **`d` is checked before anything is written.** Each of the four separators must be
  * exactly one character, none may be a record terminator, and no two may share a
@@ -4407,7 +4429,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.
@@ -4432,6 +4455,9 @@ declare function decodeAstmFrames(bytes: Uint8Array, options?: FrameOptions): De
  * - `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
@@ -4439,7 +4465,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" | "ASTM_FRAME_RESERVED_BYTE";
+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
@@ -4471,6 +4497,20 @@ type AstmFrameEncodeErrorCode = "ASTM_FRAME_EMPTY_RECORD" | "ASTM_FRAME_UNENCODA
  * 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";
@@ -4500,8 +4540,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;
 }
@@ -4539,6 +4613,17 @@ interface ComposeFramesOptions {
  * 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.
@@ -4547,10 +4632,12 @@ interface ComposeFramesOptions {
  *   `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`), 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`).
+ * @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";
@@ -4625,7 +4712,11 @@ 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
@@ -4645,10 +4736,11 @@ declare function parseFramedAstm(bytes: Uint8Array, options?: FrameOptions & Ast
  *   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`), 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`).
+ * @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

@@ -1433,6 +1433,13 @@ function encodeComponent(leaf, d, recordIndex) {
   assertEmittableDelimiters(d, recordIndex);
   return encodeLeaf(leaf, d, recordIndex);
 }
+function escapeMnemonic(ch, d) {
+  if (ch === d.escape) return "E";
+  if (ch === d.field) return "F";
+  if (ch === d.component) return "S";
+  if (ch === d.repeat) return "R";
+  return void 0;
+}
 function encodeLeaf(leaf, d, recordIndex) {
   if (leaf.includes("\r") || leaf.includes("\n")) {
     throw new AstmSerializeError(
@@ -1440,7 +1447,13 @@ function encodeLeaf(leaf, d, recordIndex) {
       recordIndex
     );
   }
-  return leaf.split(d.escape).join(d.escape + "E" + d.escape).split(d.field).join(d.escape + "F" + d.escape).split(d.component).join(d.escape + "S" + d.escape).split(d.repeat).join(d.escape + "R" + d.escape);
+  let out = "";
+  for (let i = 0; i < leaf.length; i += 1) {
+    const ch = leaf.charAt(i);
+    const mnemonic = escapeMnemonic(ch, d);
+    out += mnemonic === void 0 ? ch : d.escape + mnemonic + d.escape;
+  }
+  return out;
 }
 function encodeField(repeats, d, recordIndex) {
   return repeats.map((rep) => rep.map((c) => encodeLeaf(c, d, recordIndex)).join(d.component)).join(d.repeat);
@@ -2288,6 +2301,15 @@ function assertFramable(bytes, recordIndex) {
     }
   }
 }
+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];
@@ -2296,11 +2318,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) {
@@ -2345,7 +2369,7 @@ function concatBytes3(chunks) {
 }
 
 // src/index.ts
-var VERSION = "0.0.13";
+var VERSION = "0.0.15";
 
 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