@cosyte/astm 0.0.13 → 0.0.14

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?: {
@@ -4407,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.
@@ -4432,6 +4433,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 +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" | "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 +4475,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 +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;
 }
@@ -4539,6 +4591,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 +4610,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 +4690,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 +4714,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?: {
@@ -4407,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.
@@ -4432,6 +4433,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 +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" | "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 +4475,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 +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;
 }
@@ -4539,6 +4591,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 +4610,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 +4690,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 +4714,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

@@ -2288,6 +2288,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 +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) {
@@ -2345,7 +2356,7 @@ function concatBytes3(chunks) {
 }
 
 // src/index.ts
-var VERSION = "0.0.13";
+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