@sofa-buffers/corelib 0.8.0 → 0.10.0

package/dist/index.d.cts

@@ -123,16 +123,14 @@ type DecodeStatus = (typeof DecodeStatus)[keyof typeof DecodeStatus];
  * bytes — so it is kept distinct from `InvalidMsg`.
  */
 /**
- * The cause of a {@link SofabError}. `Argument`, `Usage`, `BufferFull` and
- * `InvalidMsg` match the C reference's `sofab_ret_t` codes; `Incomplete` is the
+ * The cause of a {@link SofabError}. `Argument`, `BufferFull` and `InvalidMsg`
+ * match the C reference's `sofab_ret_t` codes; `Incomplete` is the
  * finish-less INCOMPLETE decode outcome (MESSAGE_SPEC §7), a distinct,
  * more-bytes-could-complete-it signal split out from `InvalidMsg`.
  */
 declare const SofabErrorCode: {
     /** A caller argument was invalid (e.g. id out of range, empty array). */
     readonly Argument: "ARGUMENT";
-    /** The API was used incorrectly (e.g. unbalanced sequence end). */
-    readonly Usage: "USAGE";
     /** The output buffer is full and no flush sink was provided. */
     readonly BufferFull: "BUFFER_FULL";
     /** The input being decoded is malformed regardless of what follows (`INVALID`). */
@@ -231,6 +229,12 @@ type FlushSink = (chunk: Uint8Array) => void;
  *
  * Generated code typically writes one field per message field; the methods map
  * one-to-one onto the wire types. Problems throw {@link SofabError}.
+ *
+ * Nested sequences are opened with {@link OStream.writeSequenceBeginLazy}, which
+ * holds the header back until the sequence proves it has content, so an
+ * all-default one is omitted rather than framed empty (MESSAGE_SPEC §2). Close a
+ * `struct`/`union` field or an array wrapper with {@link OStream.writeSequenceEnd}
+ * and a wrapper-array *element* with {@link OStream.writeSequenceEndKeep}.
  */
 
 /**
@@ -248,6 +252,26 @@ declare class OStream {
     private readonly flushSink;
     private readonly canGrow;
     private depth;
+    /**
+     * Ids of the innermost open sequences whose header has not been written yet
+     * (MESSAGE_SPEC §2 lazy framing, {@link OStream.writeSequenceBeginLazy}).
+     * Always a contiguous suffix of the open sequences: writing any field commits
+     * the whole run at once, so {@link OStream.writeSequenceEnd} can drop the
+     * innermost one by dropping the last entry. Held-back ids are encoder state,
+     * never buffer content, so a flush can never split a run.
+     *
+     * Storage plus an explicit count rather than `push`/`pop`, so the slots are
+     * reused across messages (no allocation on a pooled encoder) and so
+     * {@link OStream.commitPending} can zero the count *before* it writes.
+     *
+     * The array grows on demand and is bounded only by `MAX_DEPTH` — there is no
+     * fixed hold-back window and hence no eager-framing fallback, which is what
+     * CORELIB_PLAN §6 ("How deep the hold-back reaches") demands of an
+     * implementation that can allocate: canonical output at *every* depth.
+     */
+    private readonly pending;
+    /** Valid entries in {@link OStream.pending}. */
+    private nPending;
     private kernel;
     /** In-memory encoder backed by an auto-growing buffer. */
     constructor();
@@ -311,17 +335,100 @@ declare class OStream {
     writeSignedArrayLong(id: number, values: readonly Long[]): void;
     /** Write an array of IEEE-754 32-bit floats. */
     writeFp32Array(id: number, values: ArrayLike<number>): void;
+    /**
+     * Write an fp32 array from its raw little-endian element payload. The bytes
+     * are emitted verbatim — no per-element `setFloat32` — so a signaling NaN
+     * survives bit-for-bit (§4.6), which {@link writeFp32Array} cannot guarantee
+     * because it re-quantizes each JS `number`. `payload.length` must be a
+     * multiple of 4; the element count is `payload.length / 4`.
+     */
+    writeFp32ArrayRaw(id: number, payload: Uint8Array): void;
     /** Write an array of IEEE-754 64-bit doubles. */
     writeFp64Array(id: number, values: ArrayLike<number>): void;
-    /** Open a nested sequence (a fresh id scope). */
-    writeSequenceBegin(id: number): void;
-    /** Close the current sequence. */
+    /**
+     * Open a nested sequence (a fresh id scope) whose header is **held back**
+     * until the sequence turns out to have content.
+     *
+     * MESSAGE_SPEC §2 omits a sequence-typed field whose value equals its declared
+     * default, and "not one child was written" is exactly that condition —
+     * evaluated per child field, recursively, for free, because the message layer
+     * already omits every child equal to its default. A sequence closed with
+     * nothing in it therefore emits **nothing** instead of a two-byte empty frame,
+     * and an all-default message becomes the empty byte string. No byte image is
+     * ever compared, so in-memory layout never enters the decision.
+     *
+     * This is the only way to open a sequence. How it closes decides whether a
+     * contentless one survives: {@link OStream.writeSequenceEnd} drops it,
+     * {@link OStream.writeSequenceEndKeep} forces the frame out.
+     */
+    writeSequenceBeginLazy(id: number): void;
+    /**
+     * Close the current sequence, letting it **vanish** if it received no content.
+     *
+     * Use it wherever absence encodes the same value as an empty frame: a
+     * `struct`/`union` field, and an array field whose declared `default` is the
+     * empty collection (MESSAGE_SPEC §2). Where the frame must be visible, close
+     * with {@link OStream.writeSequenceEndKeep} instead.
+     *
+     * An end with no matching begin is not rejected: the encoder writes what it is
+     * told, and the resulting bytes are then malformed, which is the decoder's
+     * verdict to make. No other port refuses it. The depth counter stops at zero
+     * so the MAX_DEPTH check on begin cannot be fooled by an underflow.
+     */
     writeSequenceEnd(): void;
+    /**
+     * Close the current sequence, **keeping** its frame even when it received no
+     * content.
+     *
+     * Behaves like a write: it first emits any held-back headers — this frame's
+     * and every enclosing one's — and then the end marker, so an empty sequence
+     * reaches the wire as `begin` + `end`.
+     *
+     * Required wherever the frame carries information beyond its contents:
+     * - a **wrapper-array element** (`struct`/`union`/nested row): element
+     *   presence is what carries a dynamic array's length — *highest present id +
+     *   1* (MESSAGE_SPEC §5.1) — so dropping an all-default element would change
+     *   the decoded length, not just the bytes;
+     * - an array field already known to **differ from a non-empty declared
+     *   `default`**: absence would reconstruct that default, so the empty frame is
+     *   the only encoding of "explicitly empty" (§2, §3).
+     *
+     * The two failure directions are not symmetric, which is why this is the safe
+     * choice when in doubt: using it where {@link OStream.writeSequenceEnd} would
+     * do costs one non-canonical empty frame that a decoder normalizes away, while
+     * the reverse silently changes an array's length.
+     */
+    writeSequenceEndKeep(): void;
     /** Ensure exactly `value`'s varint size, then write it (bigint path). */
     private putVarint;
     /** Ensure exactly `value`'s varint size, then write it (number fast path). */
     private putVarintNum;
+    /**
+     * Write a field header, the `(id << 3) | wireType` tag, as a varint.
+     *
+     * This is the single choke point every field write passes through — the
+     * scalar, fixlen, float, string, blob and both array writers all reach the
+     * wire through `header` / `fixlenHead` / `arrayHead`, and `fixlenHead` and
+     * `arrayHead` are themselves nothing but `header` plus a follow-up varint. So
+     * this is also where a held-back sequence run is committed: the field about to
+     * be written is content, which means every enclosing sequence is non-default
+     * and must be framed after all (MESSAGE_SPEC §2).
+     *
+     * The only writers that do *not* pass through here are the two sequence
+     * closers, which must not commit ({@link OStream.writeSequenceEnd}) or commit
+     * explicitly ({@link OStream.writeSequenceEndKeep}), and
+     * {@link OStream.writeSequenceBeginLazy}, which writes no byte at all.
+     */
     private header;
+    /**
+     * Write out the held-back sequence headers, **outermost first**, and clear the
+     * run. Runs at most once per non-default sequence, never per field — the cost
+     * on the hot path is the single `nPending` test in {@link header}.
+     *
+     * The count is zeroed before the first byte goes out, so a write re-entered
+     * from a flush sink cannot emit the same run twice.
+     */
+    private commitPending;
     private fixlenHead;
     private arrayHead;
     /** Copy `data` out, flushing/growing as needed (large payloads stay chunked). */
@@ -417,9 +524,29 @@ interface Visitor {
     unsigned?(id: number, value: number | bigint): void;
     /** A signed integer field. Number-first like {@link unsigned} (`|value| ≤ 2^53-1` ⇒ `number`). */
     signed?(id: number, value: number | bigint): void;
-    /** An IEEE-754 32-bit float field. */
-    fp32?(id: number, value: number): void;
-    /** An IEEE-754 64-bit double field. */
+    /**
+     * Opt in to the raw-bytes channel on {@link fp32} / {@link arrayFp32}. Off by
+     * default so a value-only consumer pays nothing: when this is not `true` the
+     * decoder never allocates the per-value little-endian view (which, per fp32
+     * element, roughly quartered array-decode throughput in a microbenchmark). Set
+     * it `true` only in a bit-exact consumer (transcode / raw-bits oracle) that
+     * needs `raw` to preserve a signaling NaN.
+     */
+    readonly fp32Raw?: boolean;
+    /**
+     * An IEEE-754 32-bit float field. When you set {@link fp32Raw} to `true`,
+     * `raw` is a zero-copy little-endian view of the exact 4 wire bytes; use it —
+     * not `value` — when the bytes must round-trip bit-for-bit (§4.6). `value` is
+     * a JS `number` (a 64-bit double), and widening a *signaling* NaN into a
+     * double quiets it (sets the is-quiet bit), so `value` cannot represent an
+     * fp32 sNaN faithfully. The view aliases the decoder's working buffer and is
+     * valid only for the duration of the call — copy it if you retain it, exactly
+     * as with a string/blob `chunk`. Without {@link fp32Raw}, `raw` is `undefined`
+     * (no allocation). fp64 needs no such channel: a double holds all 64 bits
+     * verbatim (see {@link fp64}).
+     */
+    fp32?(id: number, value: number, raw?: Uint8Array): void;
+    /** An IEEE-754 64-bit double field. `value` is exact — a double is 64 bits wide. */
     fp64?(id: number, value: number): void;
     /** A chunk of a UTF-8 string field. */
     string?(id: number, total: number, offset: number, chunk: Uint8Array): void;
@@ -431,9 +558,9 @@ interface Visitor {
     arrayUnsigned?(id: number, index: number, value: number | bigint): void;
     /** One signed array element. Number-first like {@link signed}. */
     arraySigned?(id: number, index: number, value: number | bigint): void;
-    /** One fp32 array element. */
-    arrayFp32?(id: number, index: number, value: number): void;
-    /** One fp64 array element. */
+    /** One fp32 array element. `raw` (the element's 4 wire bytes) is present only under {@link fp32Raw} — see {@link fp32}. */
+    arrayFp32?(id: number, index: number, value: number, raw?: Uint8Array): void;
+    /** One fp64 array element. `value` is exact — see {@link fp64}. */
     arrayFp64?(id: number, index: number, value: number): void;
     /** End of an array. */
     arrayEnd?(id: number): void;
@@ -612,31 +739,70 @@ declare class Cursor {
     readSigned(): number | bigint;
     /** Read a 32-bit float scalar (wire {@link WireType.Fixlen}, subtype fp32). */
     readFp32(): number;
+    /**
+     * Read a 32-bit float scalar as its raw 4 wire bytes (little-endian), zero-copy
+     * — the bit-preserving companion to {@link readFp32}.
+     *
+     * {@link readFp32} returns a JS `number` (a 64-bit double), and widening an
+     * fp32 *signaling* NaN into a double quiets it (0x7F800001 → 0x7FC00001), so a
+     * value consumer can never round-trip one bit-for-bit (§4.6). Generated
+     * bit-exact decode reads the bytes here instead and re-emits them verbatim with
+     * {@link OStream.writeFixlen} (subtype fp32) — mirroring the visitor `raw`
+     * channel on the push paths (fast.ts / state.ts), which the pull path was
+     * missing (corelib-ts#66).
+     *
+     * The header (subtype fp32, length 4) is validated exactly as in
+     * {@link readFp32}; the returned view aliases the source buffer, valid only
+     * until it is reused, like {@link readBlob}.
+     */
+    readFp32Raw(): Uint8Array;
     /** Read a 64-bit float scalar (wire {@link WireType.Fixlen}, subtype fp64). */
     readFp64(): number;
-    /** Read a UTF-8 string scalar (wire {@link WireType.Fixlen}, subtype string). */
-    readString(): string;
+    /**
+     * Read a UTF-8 string scalar (wire {@link WireType.Fixlen}, subtype string).
+     * Pass the schema `maxlen` (byte length) for a bounded string so an
+     * over-length is rejected as `INVALID` at the header, before the payload is
+     * taken (see {@link fixlenLen}); the wire length is exactly the UTF-8 byte
+     * length, so the check is exact. Omit for an unbounded string.
+     */
+    readString(schemaMaxlen?: number): string;
     /**
      * Read a blob scalar (wire {@link WireType.Fixlen}, subtype blob) as a
      * zero-copy {@link Uint8Array} view into the source buffer.
      */
-    readBlob(): Uint8Array;
-    /** Read an unsigned array (wire {@link WireType.ArrayUnsigned}), number-first per element. */
-    readUnsignedArray(): (number | bigint)[];
+    readBlob(schemaMaxlen?: number): Uint8Array;
+    /**
+     * Read an unsigned array (wire {@link WireType.ArrayUnsigned}), number-first
+     * per element. Pass the schema `count` for a bounded array so an over-count is
+     * rejected as `INVALID` at the header (see {@link arrayCount}); omit it for an
+     * unbounded array (today's behavior).
+     */
+    readUnsignedArray(schemaCount?: number): (number | bigint)[];
     /** Read a signed array (wire {@link WireType.ArraySigned}), zig-zag, number-first per element. */
-    readSignedArray(): (number | bigint)[];
+    readSignedArray(schemaCount?: number): (number | bigint)[];
     /**
      * Read an unsigned 64-bit array into {@link Long}[] — the `bigint`-free path.
      * Each element keeps the raw lo/hi halves; call {@link Long.toBigInt} to
      * materialise only the values the caller actually needs.
      */
-    readUnsignedArrayLong(): Long[];
+    readUnsignedArrayLong(schemaCount?: number): Long[];
     /** Read a signed 64-bit array (zig-zag) into {@link Long}[] — the `bigint`-free path. */
-    readSignedArrayLong(): Long[];
+    readSignedArrayLong(schemaCount?: number): Long[];
     /** Read an fp32 array (wire {@link WireType.ArrayFixlen}, element subtype fp32). */
-    readFp32Array(): number[];
+    readFp32Array(schemaCount?: number): number[];
+    /**
+     * Read an fp32 array as its raw little-endian element payload (`count * 4`
+     * bytes), zero-copy — the bit-preserving companion to {@link readFp32Array}.
+     * Widening each element to a JS `number` quiets an fp32 *signaling* NaN just as
+     * on the scalar path (§4.6; see {@link readFp32Raw}), so bit-exact decode reads
+     * the whole payload here and re-emits it with {@link OStream.writeFp32ArrayRaw}
+     * (corelib-ts#66). The header (element subtype fp32, size 4) is validated
+     * exactly as in {@link readFp32Array}; the returned view aliases the source
+     * buffer, like {@link readBlob}.
+     */
+    readFp32ArrayRaw(schemaCount?: number): Uint8Array;
     /** Read an fp64 array (wire {@link WireType.ArrayFixlen}, element subtype fp64). */
-    readFp64Array(): number[];
+    readFp64Array(schemaCount?: number): number[];
     /**
      * Consume the value of the field whose header {@link readHeader} just accepted,
      * discarding it — for a `default:` branch that keeps the cursor in sync on an
@@ -658,13 +824,25 @@ declare class Cursor {
      * reads one byte, it never decodes a varint.
      */
     private peekFixSub;
-    /** Read and validate an array count word (0..ARRAY_MAX; §4.7/§4.8). */
+    /**
+     * Read and validate an array count word (0..ARRAY_MAX; §4.7/§4.8). When a
+     * `schemaCount` is given, a count above it is a schema-bound violation and is
+     * rejected as `INVALID` — see the check below.
+     */
     private arrayCount;
     /** Read a scalar fixlen sub-header, asserting subtype and exact byte length (floats). */
     private fixlenHeader;
-    /** Read a scalar fixlen sub-header for a string/blob, asserting subtype; returns byte length. */
+    /**
+     * Read a scalar fixlen sub-header for a string/blob, asserting subtype;
+     * returns the byte length. When a `schemaMaxlen` is given, a length above it
+     * is a schema-bound violation and is rejected as `INVALID` — see below.
+     */
     private fixlenLen;
-    /** Read an array fixlen element header (count + element type); returns the count. */
+    /**
+     * Read an array fixlen element header (count + element type); returns the
+     * count. When a `schemaCount` is given, a count above it is a schema-bound
+     * violation and is rejected as `INVALID` — see below.
+     */
     private arrayFixlenHeader;
     /** Hand back a zero-copy view of the next `len` bytes, advancing the cursor. */
     private take;

package/dist/index.d.ts

@@ -123,16 +123,14 @@ type DecodeStatus = (typeof DecodeStatus)[keyof typeof DecodeStatus];
  * bytes — so it is kept distinct from `InvalidMsg`.
  */
 /**
- * The cause of a {@link SofabError}. `Argument`, `Usage`, `BufferFull` and
- * `InvalidMsg` match the C reference's `sofab_ret_t` codes; `Incomplete` is the
+ * The cause of a {@link SofabError}. `Argument`, `BufferFull` and `InvalidMsg`
+ * match the C reference's `sofab_ret_t` codes; `Incomplete` is the
  * finish-less INCOMPLETE decode outcome (MESSAGE_SPEC §7), a distinct,
  * more-bytes-could-complete-it signal split out from `InvalidMsg`.
  */
 declare const SofabErrorCode: {
     /** A caller argument was invalid (e.g. id out of range, empty array). */
     readonly Argument: "ARGUMENT";
-    /** The API was used incorrectly (e.g. unbalanced sequence end). */
-    readonly Usage: "USAGE";
     /** The output buffer is full and no flush sink was provided. */
     readonly BufferFull: "BUFFER_FULL";
     /** The input being decoded is malformed regardless of what follows (`INVALID`). */
@@ -231,6 +229,12 @@ type FlushSink = (chunk: Uint8Array) => void;
  *
  * Generated code typically writes one field per message field; the methods map
  * one-to-one onto the wire types. Problems throw {@link SofabError}.
+ *
+ * Nested sequences are opened with {@link OStream.writeSequenceBeginLazy}, which
+ * holds the header back until the sequence proves it has content, so an
+ * all-default one is omitted rather than framed empty (MESSAGE_SPEC §2). Close a
+ * `struct`/`union` field or an array wrapper with {@link OStream.writeSequenceEnd}
+ * and a wrapper-array *element* with {@link OStream.writeSequenceEndKeep}.
  */
 
 /**
@@ -248,6 +252,26 @@ declare class OStream {
     private readonly flushSink;
     private readonly canGrow;
     private depth;
+    /**
+     * Ids of the innermost open sequences whose header has not been written yet
+     * (MESSAGE_SPEC §2 lazy framing, {@link OStream.writeSequenceBeginLazy}).
+     * Always a contiguous suffix of the open sequences: writing any field commits
+     * the whole run at once, so {@link OStream.writeSequenceEnd} can drop the
+     * innermost one by dropping the last entry. Held-back ids are encoder state,
+     * never buffer content, so a flush can never split a run.
+     *
+     * Storage plus an explicit count rather than `push`/`pop`, so the slots are
+     * reused across messages (no allocation on a pooled encoder) and so
+     * {@link OStream.commitPending} can zero the count *before* it writes.
+     *
+     * The array grows on demand and is bounded only by `MAX_DEPTH` — there is no
+     * fixed hold-back window and hence no eager-framing fallback, which is what
+     * CORELIB_PLAN §6 ("How deep the hold-back reaches") demands of an
+     * implementation that can allocate: canonical output at *every* depth.
+     */
+    private readonly pending;
+    /** Valid entries in {@link OStream.pending}. */
+    private nPending;
     private kernel;
     /** In-memory encoder backed by an auto-growing buffer. */
     constructor();
@@ -311,17 +335,100 @@ declare class OStream {
     writeSignedArrayLong(id: number, values: readonly Long[]): void;
     /** Write an array of IEEE-754 32-bit floats. */
     writeFp32Array(id: number, values: ArrayLike<number>): void;
+    /**
+     * Write an fp32 array from its raw little-endian element payload. The bytes
+     * are emitted verbatim — no per-element `setFloat32` — so a signaling NaN
+     * survives bit-for-bit (§4.6), which {@link writeFp32Array} cannot guarantee
+     * because it re-quantizes each JS `number`. `payload.length` must be a
+     * multiple of 4; the element count is `payload.length / 4`.
+     */
+    writeFp32ArrayRaw(id: number, payload: Uint8Array): void;
     /** Write an array of IEEE-754 64-bit doubles. */
     writeFp64Array(id: number, values: ArrayLike<number>): void;
-    /** Open a nested sequence (a fresh id scope). */
-    writeSequenceBegin(id: number): void;
-    /** Close the current sequence. */
+    /**
+     * Open a nested sequence (a fresh id scope) whose header is **held back**
+     * until the sequence turns out to have content.
+     *
+     * MESSAGE_SPEC §2 omits a sequence-typed field whose value equals its declared
+     * default, and "not one child was written" is exactly that condition —
+     * evaluated per child field, recursively, for free, because the message layer
+     * already omits every child equal to its default. A sequence closed with
+     * nothing in it therefore emits **nothing** instead of a two-byte empty frame,
+     * and an all-default message becomes the empty byte string. No byte image is
+     * ever compared, so in-memory layout never enters the decision.
+     *
+     * This is the only way to open a sequence. How it closes decides whether a
+     * contentless one survives: {@link OStream.writeSequenceEnd} drops it,
+     * {@link OStream.writeSequenceEndKeep} forces the frame out.
+     */
+    writeSequenceBeginLazy(id: number): void;
+    /**
+     * Close the current sequence, letting it **vanish** if it received no content.
+     *
+     * Use it wherever absence encodes the same value as an empty frame: a
+     * `struct`/`union` field, and an array field whose declared `default` is the
+     * empty collection (MESSAGE_SPEC §2). Where the frame must be visible, close
+     * with {@link OStream.writeSequenceEndKeep} instead.
+     *
+     * An end with no matching begin is not rejected: the encoder writes what it is
+     * told, and the resulting bytes are then malformed, which is the decoder's
+     * verdict to make. No other port refuses it. The depth counter stops at zero
+     * so the MAX_DEPTH check on begin cannot be fooled by an underflow.
+     */
     writeSequenceEnd(): void;
+    /**
+     * Close the current sequence, **keeping** its frame even when it received no
+     * content.
+     *
+     * Behaves like a write: it first emits any held-back headers — this frame's
+     * and every enclosing one's — and then the end marker, so an empty sequence
+     * reaches the wire as `begin` + `end`.
+     *
+     * Required wherever the frame carries information beyond its contents:
+     * - a **wrapper-array element** (`struct`/`union`/nested row): element
+     *   presence is what carries a dynamic array's length — *highest present id +
+     *   1* (MESSAGE_SPEC §5.1) — so dropping an all-default element would change
+     *   the decoded length, not just the bytes;
+     * - an array field already known to **differ from a non-empty declared
+     *   `default`**: absence would reconstruct that default, so the empty frame is
+     *   the only encoding of "explicitly empty" (§2, §3).
+     *
+     * The two failure directions are not symmetric, which is why this is the safe
+     * choice when in doubt: using it where {@link OStream.writeSequenceEnd} would
+     * do costs one non-canonical empty frame that a decoder normalizes away, while
+     * the reverse silently changes an array's length.
+     */
+    writeSequenceEndKeep(): void;
     /** Ensure exactly `value`'s varint size, then write it (bigint path). */
     private putVarint;
     /** Ensure exactly `value`'s varint size, then write it (number fast path). */
     private putVarintNum;
+    /**
+     * Write a field header, the `(id << 3) | wireType` tag, as a varint.
+     *
+     * This is the single choke point every field write passes through — the
+     * scalar, fixlen, float, string, blob and both array writers all reach the
+     * wire through `header` / `fixlenHead` / `arrayHead`, and `fixlenHead` and
+     * `arrayHead` are themselves nothing but `header` plus a follow-up varint. So
+     * this is also where a held-back sequence run is committed: the field about to
+     * be written is content, which means every enclosing sequence is non-default
+     * and must be framed after all (MESSAGE_SPEC §2).
+     *
+     * The only writers that do *not* pass through here are the two sequence
+     * closers, which must not commit ({@link OStream.writeSequenceEnd}) or commit
+     * explicitly ({@link OStream.writeSequenceEndKeep}), and
+     * {@link OStream.writeSequenceBeginLazy}, which writes no byte at all.
+     */
     private header;
+    /**
+     * Write out the held-back sequence headers, **outermost first**, and clear the
+     * run. Runs at most once per non-default sequence, never per field — the cost
+     * on the hot path is the single `nPending` test in {@link header}.
+     *
+     * The count is zeroed before the first byte goes out, so a write re-entered
+     * from a flush sink cannot emit the same run twice.
+     */
+    private commitPending;
     private fixlenHead;
     private arrayHead;
     /** Copy `data` out, flushing/growing as needed (large payloads stay chunked). */
@@ -417,9 +524,29 @@ interface Visitor {
     unsigned?(id: number, value: number | bigint): void;
     /** A signed integer field. Number-first like {@link unsigned} (`|value| ≤ 2^53-1` ⇒ `number`). */
     signed?(id: number, value: number | bigint): void;
-    /** An IEEE-754 32-bit float field. */
-    fp32?(id: number, value: number): void;
-    /** An IEEE-754 64-bit double field. */
+    /**
+     * Opt in to the raw-bytes channel on {@link fp32} / {@link arrayFp32}. Off by
+     * default so a value-only consumer pays nothing: when this is not `true` the
+     * decoder never allocates the per-value little-endian view (which, per fp32
+     * element, roughly quartered array-decode throughput in a microbenchmark). Set
+     * it `true` only in a bit-exact consumer (transcode / raw-bits oracle) that
+     * needs `raw` to preserve a signaling NaN.
+     */
+    readonly fp32Raw?: boolean;
+    /**
+     * An IEEE-754 32-bit float field. When you set {@link fp32Raw} to `true`,
+     * `raw` is a zero-copy little-endian view of the exact 4 wire bytes; use it —
+     * not `value` — when the bytes must round-trip bit-for-bit (§4.6). `value` is
+     * a JS `number` (a 64-bit double), and widening a *signaling* NaN into a
+     * double quiets it (sets the is-quiet bit), so `value` cannot represent an
+     * fp32 sNaN faithfully. The view aliases the decoder's working buffer and is
+     * valid only for the duration of the call — copy it if you retain it, exactly
+     * as with a string/blob `chunk`. Without {@link fp32Raw}, `raw` is `undefined`
+     * (no allocation). fp64 needs no such channel: a double holds all 64 bits
+     * verbatim (see {@link fp64}).
+     */
+    fp32?(id: number, value: number, raw?: Uint8Array): void;
+    /** An IEEE-754 64-bit double field. `value` is exact — a double is 64 bits wide. */
     fp64?(id: number, value: number): void;
     /** A chunk of a UTF-8 string field. */
     string?(id: number, total: number, offset: number, chunk: Uint8Array): void;
@@ -431,9 +558,9 @@ interface Visitor {
     arrayUnsigned?(id: number, index: number, value: number | bigint): void;
     /** One signed array element. Number-first like {@link signed}. */
     arraySigned?(id: number, index: number, value: number | bigint): void;
-    /** One fp32 array element. */
-    arrayFp32?(id: number, index: number, value: number): void;
-    /** One fp64 array element. */
+    /** One fp32 array element. `raw` (the element's 4 wire bytes) is present only under {@link fp32Raw} — see {@link fp32}. */
+    arrayFp32?(id: number, index: number, value: number, raw?: Uint8Array): void;
+    /** One fp64 array element. `value` is exact — see {@link fp64}. */
     arrayFp64?(id: number, index: number, value: number): void;
     /** End of an array. */
     arrayEnd?(id: number): void;
@@ -612,31 +739,70 @@ declare class Cursor {
     readSigned(): number | bigint;
     /** Read a 32-bit float scalar (wire {@link WireType.Fixlen}, subtype fp32). */
     readFp32(): number;
+    /**
+     * Read a 32-bit float scalar as its raw 4 wire bytes (little-endian), zero-copy
+     * — the bit-preserving companion to {@link readFp32}.
+     *
+     * {@link readFp32} returns a JS `number` (a 64-bit double), and widening an
+     * fp32 *signaling* NaN into a double quiets it (0x7F800001 → 0x7FC00001), so a
+     * value consumer can never round-trip one bit-for-bit (§4.6). Generated
+     * bit-exact decode reads the bytes here instead and re-emits them verbatim with
+     * {@link OStream.writeFixlen} (subtype fp32) — mirroring the visitor `raw`
+     * channel on the push paths (fast.ts / state.ts), which the pull path was
+     * missing (corelib-ts#66).
+     *
+     * The header (subtype fp32, length 4) is validated exactly as in
+     * {@link readFp32}; the returned view aliases the source buffer, valid only
+     * until it is reused, like {@link readBlob}.
+     */
+    readFp32Raw(): Uint8Array;
     /** Read a 64-bit float scalar (wire {@link WireType.Fixlen}, subtype fp64). */
     readFp64(): number;
-    /** Read a UTF-8 string scalar (wire {@link WireType.Fixlen}, subtype string). */
-    readString(): string;
+    /**
+     * Read a UTF-8 string scalar (wire {@link WireType.Fixlen}, subtype string).
+     * Pass the schema `maxlen` (byte length) for a bounded string so an
+     * over-length is rejected as `INVALID` at the header, before the payload is
+     * taken (see {@link fixlenLen}); the wire length is exactly the UTF-8 byte
+     * length, so the check is exact. Omit for an unbounded string.
+     */
+    readString(schemaMaxlen?: number): string;
     /**
      * Read a blob scalar (wire {@link WireType.Fixlen}, subtype blob) as a
      * zero-copy {@link Uint8Array} view into the source buffer.
      */
-    readBlob(): Uint8Array;
-    /** Read an unsigned array (wire {@link WireType.ArrayUnsigned}), number-first per element. */
-    readUnsignedArray(): (number | bigint)[];
+    readBlob(schemaMaxlen?: number): Uint8Array;
+    /**
+     * Read an unsigned array (wire {@link WireType.ArrayUnsigned}), number-first
+     * per element. Pass the schema `count` for a bounded array so an over-count is
+     * rejected as `INVALID` at the header (see {@link arrayCount}); omit it for an
+     * unbounded array (today's behavior).
+     */
+    readUnsignedArray(schemaCount?: number): (number | bigint)[];
     /** Read a signed array (wire {@link WireType.ArraySigned}), zig-zag, number-first per element. */
-    readSignedArray(): (number | bigint)[];
+    readSignedArray(schemaCount?: number): (number | bigint)[];
     /**
      * Read an unsigned 64-bit array into {@link Long}[] — the `bigint`-free path.
      * Each element keeps the raw lo/hi halves; call {@link Long.toBigInt} to
      * materialise only the values the caller actually needs.
      */
-    readUnsignedArrayLong(): Long[];
+    readUnsignedArrayLong(schemaCount?: number): Long[];
     /** Read a signed 64-bit array (zig-zag) into {@link Long}[] — the `bigint`-free path. */
-    readSignedArrayLong(): Long[];
+    readSignedArrayLong(schemaCount?: number): Long[];
     /** Read an fp32 array (wire {@link WireType.ArrayFixlen}, element subtype fp32). */
-    readFp32Array(): number[];
+    readFp32Array(schemaCount?: number): number[];
+    /**
+     * Read an fp32 array as its raw little-endian element payload (`count * 4`
+     * bytes), zero-copy — the bit-preserving companion to {@link readFp32Array}.
+     * Widening each element to a JS `number` quiets an fp32 *signaling* NaN just as
+     * on the scalar path (§4.6; see {@link readFp32Raw}), so bit-exact decode reads
+     * the whole payload here and re-emits it with {@link OStream.writeFp32ArrayRaw}
+     * (corelib-ts#66). The header (element subtype fp32, size 4) is validated
+     * exactly as in {@link readFp32Array}; the returned view aliases the source
+     * buffer, like {@link readBlob}.
+     */
+    readFp32ArrayRaw(schemaCount?: number): Uint8Array;
     /** Read an fp64 array (wire {@link WireType.ArrayFixlen}, element subtype fp64). */
-    readFp64Array(): number[];
+    readFp64Array(schemaCount?: number): number[];
     /**
      * Consume the value of the field whose header {@link readHeader} just accepted,
      * discarding it — for a `default:` branch that keeps the cursor in sync on an
@@ -658,13 +824,25 @@ declare class Cursor {
      * reads one byte, it never decodes a varint.
      */
     private peekFixSub;
-    /** Read and validate an array count word (0..ARRAY_MAX; §4.7/§4.8). */
+    /**
+     * Read and validate an array count word (0..ARRAY_MAX; §4.7/§4.8). When a
+     * `schemaCount` is given, a count above it is a schema-bound violation and is
+     * rejected as `INVALID` — see the check below.
+     */
     private arrayCount;
     /** Read a scalar fixlen sub-header, asserting subtype and exact byte length (floats). */
     private fixlenHeader;
-    /** Read a scalar fixlen sub-header for a string/blob, asserting subtype; returns byte length. */
+    /**
+     * Read a scalar fixlen sub-header for a string/blob, asserting subtype;
+     * returns the byte length. When a `schemaMaxlen` is given, a length above it
+     * is a schema-bound violation and is rejected as `INVALID` — see below.
+     */
     private fixlenLen;
-    /** Read an array fixlen element header (count + element type); returns the count. */
+    /**
+     * Read an array fixlen element header (count + element type); returns the
+     * count. When a `schemaCount` is given, a count above it is a schema-bound
+     * violation and is rejected as `INVALID` — see below.
+     */
     private arrayFixlenHeader;
     /** Hand back a zero-copy view of the next `len` bytes, advancing the cursor. */
     private take;