@sofa-buffers/corelib 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -6,10 +6,63 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 While the version is below `1.0.0`, breaking changes bump the **minor** version.
 
-## [Unreleased]
+## [0.10.0] - 2026-08-01
+
+> The breaking entries below make the next release a **minor** bump (the first
+> since `0.2.0`), per the pre-`1.0.0` rule above — never a patch. The published
+> package is `@sofa-buffers/corelib`; the git tag is the source of truth for the
+> version number, and `package.json` stays at `0.0.0-dev`.
 
 ### Changed
 
+- **BREAKING (encode API) — an all-default sequence is now *omitted*, not framed
+  empty (MESSAGE_SPEC §2, CORELIB_PLAN §6).** A sequence-typed **field** whose
+  value equals its declared default carries no information, so it no longer
+  reaches the wire at all, where it previously appeared as the two-byte empty
+  frame `0E 07`. An all-default message is now the **empty byte string**. A
+  wrapper-array **element** is the exception and keeps its frame: element
+  presence is what carries a dynamic array's length (§5.1), so dropping one
+  would change the decoded value, not just the bytes.
+
+  Deciding this without buffering the sub-message means the sequence header has
+  to be held back until the sequence proves it has content, which changes the
+  encoder's public sequence API:
+
+  | before | after |
+  |---|---|
+  | `writeSequenceBegin(id)` — **removed** | `writeSequenceBeginLazy(id)` — opens the scope and holds the header back; writes no byte |
+  | `writeSequenceEnd()` | `writeSequenceEnd()` — drops the frame (header *and* end marker) if the sequence got no content |
+  | — | `writeSequenceEndKeep()` — new; emits the held-back headers plus the end marker, so a contentless sequence still reaches the wire as `begin` + `end` |
+
+  **Migration.** Replace every `writeSequenceBegin` with
+  `writeSequenceBeginLazy`. Then pick the closer *statically*, by the position in
+  the schema — it is a property of the position, not of the value:
+  `writeSequenceEnd` for a `struct`/`union` field and for an array-field wrapper;
+  `writeSequenceEndKeep` for a wrapper-array element, and for an array field
+  already known to differ from a **non-empty** declared default. When in doubt
+  `writeSequenceEndKeep` is the safe choice: the failure directions are not
+  symmetric — a needless `endKeep` costs one non-canonical empty frame that a
+  decoder normalizes away, while a wrong `end` silently changes an array's
+  length. Code that transcodes or replays raw bytes (rather than encoding a
+  schema value) wants `writeSequenceEndKeep` throughout, so its output reproduces
+  its input frame for frame.
+
+  **Decoding is unaffected**, in both directions: an empty frame remains valid
+  input that the message layer normalizes to the default, and an omitted
+  sequence field was already reconstructed from the schema default. Old and new
+  encoders therefore interoperate; they disagree only about which encoding is
+  canonical. Every non-sequence byte is unchanged — the shared
+  `assets/test_vectors.json` is re-synced and every `serialized` hex is
+  byte-identical; the vectors' separate `serialized_sparse` column is the new
+  canonical form, and is exercised by the generator's conformance drivers (a
+  corelib has no message layer and cannot produce it).
+
+  The hold-back run is bounded only by `MAX_DEPTH`: this port can allocate, so
+  it holds back to the full nesting depth and is canonical at every depth
+  (CORELIB_PLAN §6, "How deep the hold-back reaches"). Held-back ids are encoder
+  state and never buffer content, so a flush cannot split a run and a buffer
+  smaller than the message still produces the one-shot bytes.
+
 - **Strict UTF-8 for `string` fields (corelib-ts#85, MESSAGE_SPEC §8,
   CORELIB_PLAN §6.4).** JavaScript strings are a Unicode string type, so the
   corelib transcodes `string` payloads at the boundary and is now **always

package/README.md

@@ -104,6 +104,61 @@ for (let i = 0; i < 1000; i++) os.writeUnsigned(i, BigInt(i));
 os.flush();                                            // push the tail
 ```
 
+### Nested sequences
+
+A nested message is a *sequence*: a fresh id scope between a begin header and the
+`0x07` end marker. MESSAGE_SPEC §2 omits a sequence-typed **field** whose value
+equals its declared default, so the encoder holds the begin header back until the
+sequence proves it has content — no buffering of the sub-message, and nothing to
+compare byte images against:
+
+```ts
+const os = new OStream();
+os.writeUnsigned(1, 42);
+os.writeSequenceBeginLazy(2);   // a nested field...
+os.writeSequenceEnd();          // ...that got no content: header and end both vanish
+os.writeSequenceBeginLazy(3);
+os.writeString(1, "hi");        // content — commits the held-back header first
+os.writeSequenceEnd();
+os.bytes();                     // 08 2a 1e 0a 12 68 69 07  (field 2 is not on the wire)
+```
+
+Which closer to use is decided **statically**, by the position in the schema, not
+by the value:
+
+| position | closer |
+|---|---|
+| `struct` / `union` field, array-field wrapper | `writeSequenceEnd()` — drops a contentless frame |
+| wrapper-array **element**, or an array field differing from a non-empty declared default | `writeSequenceEndKeep()` — always emits `begin` + `end` |
+
+An element keeps its frame because element presence is what carries a dynamic
+array's length (highest present id + 1, §5.1); dropping an all-default element
+would change the decoded length, not just the bytes. The failure directions are
+not symmetric, so `writeSequenceEndKeep()` is the safe choice when in doubt: a
+needless one costs a non-canonical empty frame that a decoder normalizes away,
+while a wrong `writeSequenceEnd()` shortens an array. Raw transcoding — replaying
+bytes rather than encoding a schema value — should use `writeSequenceEndKeep()`
+throughout, so the output reproduces the input frame for frame.
+
+```ts
+const os = new OStream();
+os.writeSequenceBeginLazy(4);   // the wrapper array
+os.writeSequenceBeginLazy(0);   // element 0 — has content
+os.writeUnsigned(0, 7);
+os.writeSequenceEndKeep();
+os.writeSequenceBeginLazy(1);   // element 1 — all-default, but still present
+os.writeSequenceEndKeep();      // ...so its frame stays: the array has length 2
+os.writeSequenceEnd();
+os.bytes();                     // 26 06 00 07 07 0e 07 07
+```
+
+Decoding is unaffected by the distinction: an empty frame is valid input that the
+message layer normalizes to the default, and an absent sequence field is
+reconstructed from the schema default. Nesting is capped at `MAX_DEPTH` (255) on
+both sides; the encoder holds headers back to that full depth, so its output is
+canonical however deep a message nests. A held-back header is encoder state, never
+buffer content, so streaming through a small buffer produces the same bytes.
+
 ### Deserialize
 
 `decode()` walks a whole buffer and calls one optional `Visitor` method per field;

package/dist/index.cjs

@@ -97,8 +97,6 @@ var DecodeStatus = {
 var SofabErrorCode = {
   /** A caller argument was invalid (e.g. id out of range, empty array). */
   Argument: "ARGUMENT",
-  /** The API was used incorrectly (e.g. unbalanced sequence end). */
-  Usage: "USAGE",
   /** The output buffer is full and no flush sink was provided. */
   BufferFull: "BUFFER_FULL",
   /** The input being decoded is malformed regardless of what follows (`INVALID`). */
@@ -133,9 +131,6 @@ var SofabError = class _SofabError extends Error {
 function argumentError(message) {
   return new SofabError(SofabErrorCode.Argument, message);
 }
-function usageError(message) {
-  return new SofabError(SofabErrorCode.Usage, message);
-}
 function bufferFullError(message) {
   return new SofabError(SofabErrorCode.BufferFull, message);
 }
@@ -449,6 +444,26 @@ var SIGNED_FAST_MAX2 = 4503599627370496;
 var OStream = class {
   constructor(buffer, offset = 0, flush) {
     this.depth = 0;
+    /**
+     * 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.
+     */
+    this.pending = [];
+    /** Valid entries in {@link OStream.pending}. */
+    this.nPending = 0;
     this.kernel = getKernel();
     if (buffer === void 0) {
       this.buf = new Uint8Array(DEFAULT_CAPACITY);
@@ -510,6 +525,7 @@ var OStream = class {
   reset() {
     this.pos = this.start;
     this.depth = 0;
+    this.nPending = 0;
   }
   // --- scalars ------------------------------------------------------------
   /** Write an unsigned integer field. */
@@ -660,6 +676,23 @@ var OStream = class {
       }
     }
   }
+  /**
+   * 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, payload) {
+    if ((payload.length & 3) !== 0) {
+      throw argumentError(
+        `fp32 array payload length ${payload.length} is not a multiple of 4`
+      );
+    }
+    this.arrayHead(id, WireType.ArrayFixlen, payload.length >> 2);
+    this.putVarintNum(4 * 8 + FixlenSubtype.Fp32);
+    this.writeRaw(payload);
+  }
   /** Write an array of IEEE-754 64-bit doubles. */
   writeFp64Array(id, values) {
     this.arrayHead(id, WireType.ArrayFixlen, values.length);
@@ -675,20 +708,82 @@ var OStream = class {
     }
   }
   // --- sequences ----------------------------------------------------------
-  /** Open a nested sequence (a fresh id scope). */
-  writeSequenceBegin(id) {
+  /**
+   * 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) {
     if (this.depth >= MAX_DEPTH) {
-      throw usageError(`nesting exceeds MAX_DEPTH (${MAX_DEPTH})`);
+      throw argumentError(`nesting exceeds MAX_DEPTH (${MAX_DEPTH})`);
     }
-    this.header(id, WireType.SequenceStart);
+    if (id < 0 || id > ID_MAX || !Number.isInteger(id)) {
+      throw argumentError(`field id ${id} out of range 0..${ID_MAX}`);
+    }
+    this.pending[this.nPending++] = id;
     this.depth++;
   }
-  /** Close the current sequence. */
+  /**
+   * 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() {
-    if (this.depth <= 0) throw usageError("sequence end without matching begin");
+    if (this.nPending !== 0) {
+      this.nPending--;
+      if (this.depth > 0) this.depth--;
+      return;
+    }
     this.ensure(1);
     this.buf[this.pos++] = WireType.SequenceEnd;
-    this.depth--;
+    if (this.depth > 0) this.depth--;
+  }
+  /**
+   * 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() {
+    if (this.nPending !== 0) this.commitPending();
+    this.ensure(1);
+    this.buf[this.pos++] = WireType.SequenceEnd;
+    if (this.depth > 0) this.depth--;
   }
   // --- internals ----------------------------------------------------------
   /** Ensure exactly `value`'s varint size, then write it (bigint path). */
@@ -701,12 +796,44 @@ var OStream = class {
     this.ensure(varintSizeNum(value));
     this.pos = encodeVarintNum(value, this.buf, this.pos);
   }
+  /**
+   * 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.
+   */
   header(id, type) {
     if (id < 0 || id > ID_MAX || !Number.isInteger(id)) {
       throw argumentError(`field id ${id} out of range 0..${ID_MAX}`);
     }
+    if (this.nPending !== 0) this.commitPending();
     this.putVarintNum(id * 8 + type);
   }
+  /**
+   * 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.
+   */
+  commitPending() {
+    const n = this.nPending;
+    this.nPending = 0;
+    for (let i = 0; i < n; i++) {
+      this.putVarintNum(this.pending[i] * 8 + WireType.SequenceStart);
+    }
+  }
   fixlenHead(id, length, subtype) {
     this.header(id, WireType.Fixlen);
     this.putVarintNum(length * 8 + subtype);
@@ -826,9 +953,14 @@ var FastDecoder = class {
           if (sub === FixlenSubtype.Fp32 || sub === FixlenSubtype.Fp64) {
             const want = sub === FixlenSubtype.Fp32 ? 4 : 8;
             if (len !== want) throw invalidMsgError("fixlen float length mismatch");
-            const value = sub === FixlenSubtype.Fp32 ? this.readFp32() : this.readFp64();
-            if (sub === FixlenSubtype.Fp32) top.fp32?.(id, value);
-            else top.fp64?.(id, value);
+            if (sub === FixlenSubtype.Fp32) {
+              const p = this.p;
+              const value = this.readFp32();
+              top.fp32?.(id, value, top.fp32Raw ? this.buf.subarray(p, p + 4) : void 0);
+            } else {
+              const value = this.readFp64();
+              top.fp64?.(id, value);
+            }
           } else {
             const chunk = this.take(len);
             if (sub === FixlenSubtype.String) top.string?.(id, len, 0, chunk);
@@ -867,9 +999,11 @@ var FastDecoder = class {
           else throw invalidMsgError("invalid fixlen array element type");
           top.arrayBegin?.(id, kind, count);
           if (kind === ArrayKind.Fp32) {
+            const wantRaw = top.fp32Raw === true;
             for (let i = 0; i < count; i++) {
+              const p = this.p;
               const value = this.readFp32();
-              top.arrayFp32?.(id, i, value);
+              top.arrayFp32?.(id, i, value, wantRaw ? this.buf.subarray(p, p + 4) : void 0);
             }
           } else {
             for (let i = 0; i < count; i++) {
@@ -1130,8 +1264,10 @@ var DecoderState = class {
           i = this.fpStep(input, i);
           if (this.have < this.need) return;
           const value = this.fixSub === FixlenSubtype.Fp32 ? unpackFp32(this.scratch, 0) : unpackFp64(this.scratch, 0);
-          if (this.fixSub === FixlenSubtype.Fp32) this.top().fp32?.(this.id, value);
-          else this.top().fp64?.(this.id, value);
+          if (this.fixSub === FixlenSubtype.Fp32) {
+            const top = this.top();
+            top.fp32?.(this.id, value, top.fp32Raw ? this.scratch.subarray(0, 4) : void 0);
+          } else this.top().fp64?.(this.id, value);
           this.state = 0 /* Header */;
           break;
         }
@@ -1213,8 +1349,10 @@ var DecoderState = class {
           i = this.fpStep(input, i);
           if (this.have < this.need) return;
           const value = this.arrKind === ArrayKind.Fp32 ? unpackFp32(this.scratch, 0) : unpackFp64(this.scratch, 0);
-          if (this.arrKind === ArrayKind.Fp32) this.top().arrayFp32?.(this.id, this.arrIndex, value);
-          else this.top().arrayFp64?.(this.id, this.arrIndex, value);
+          if (this.arrKind === ArrayKind.Fp32) {
+            const top = this.top();
+            top.arrayFp32?.(this.id, this.arrIndex, value, top.fp32Raw ? this.scratch.subarray(0, 4) : void 0);
+          } else this.top().arrayFp64?.(this.id, this.arrIndex, value);
           this.have = 0;
           this.advanceArray();
           break;
@@ -1509,7 +1647,12 @@ var Cursor = class {
     }
     const id = this.upper();
     if (id > ID_MAX) throw invalidMsgError(`field id ${id} out of range`);
-    if (wire === WireType.SequenceStart) this.depth++;
+    if (wire === WireType.SequenceStart) {
+      if (this.depth >= MAX_DEPTH) {
+        throw invalidMsgError(`nesting exceeds MAX_DEPTH (${MAX_DEPTH})`);
+      }
+      this.depth++;
+    }
     this.id = id;
     this.wire = wire;
     this.fixSub = this.peekFixSub(wire);
@@ -1530,14 +1673,40 @@ var Cursor = class {
     this.fixlenHeader(FixlenSubtype.Fp32, 4);
     return this.rawFp32();
   }
+  /**
+   * 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() {
+    this.fixlenHeader(FixlenSubtype.Fp32, 4);
+    return this.take(4);
+  }
   /** Read a 64-bit float scalar (wire {@link WireType.Fixlen}, subtype fp64). */
   readFp64() {
     this.fixlenHeader(FixlenSubtype.Fp64, 8);
     return this.rawFp64();
   }
-  /** Read a UTF-8 string scalar (wire {@link WireType.Fixlen}, subtype string). */
-  readString() {
-    const len = this.fixlenLen(FixlenSubtype.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) {
+    const len = this.fixlenLen(FixlenSubtype.String, schemaMaxlen);
     const bytes = this.take(len);
     try {
       return _utf8.decode(bytes);
@@ -1549,13 +1718,18 @@ var Cursor = class {
    * Read a blob scalar (wire {@link WireType.Fixlen}, subtype blob) as a
    * zero-copy {@link Uint8Array} view into the source buffer.
    */
-  readBlob() {
-    const len = this.fixlenLen(FixlenSubtype.Blob);
+  readBlob(schemaMaxlen) {
+    const len = this.fixlenLen(FixlenSubtype.Blob, schemaMaxlen);
     return this.take(len);
   }
-  /** Read an unsigned array (wire {@link WireType.ArrayUnsigned}), number-first per element. */
-  readUnsignedArray() {
-    const count = this.arrayCount();
+  /**
+   * 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) {
+    const count = this.arrayCount(schemaCount);
     const out = new Array(count);
     for (let i = 0; i < count; i++) {
       this.readVarint();
@@ -1564,8 +1738,8 @@ var Cursor = class {
     return out;
   }
   /** Read a signed array (wire {@link WireType.ArraySigned}), zig-zag, number-first per element. */
-  readSignedArray() {
-    const count = this.arrayCount();
+  readSignedArray(schemaCount) {
+    const count = this.arrayCount(schemaCount);
     const out = new Array(count);
     for (let i = 0; i < count; i++) {
       this.readVarint();
@@ -1578,8 +1752,8 @@ var Cursor = class {
    * Each element keeps the raw lo/hi halves; call {@link Long.toBigInt} to
    * materialise only the values the caller actually needs.
    */
-  readUnsignedArrayLong() {
-    const count = this.arrayCount();
+  readUnsignedArrayLong(schemaCount) {
+    const count = this.arrayCount(schemaCount);
     const out = new Array(count);
     for (let i = 0; i < count; i++) {
       this.readVarint();
@@ -1588,8 +1762,8 @@ var Cursor = class {
     return out;
   }
   /** Read a signed 64-bit array (zig-zag) into {@link Long}[] — the `bigint`-free path. */
-  readSignedArrayLong() {
-    const count = this.arrayCount();
+  readSignedArrayLong(schemaCount) {
+    const count = this.arrayCount(schemaCount);
     const out = new Array(count);
     for (let i = 0; i < count; i++) {
       this.readVarint();
@@ -1601,15 +1775,29 @@ var Cursor = class {
     return out;
   }
   /** Read an fp32 array (wire {@link WireType.ArrayFixlen}, element subtype fp32). */
-  readFp32Array() {
-    const count = this.arrayFixlenHeader(FixlenSubtype.Fp32, 4);
+  readFp32Array(schemaCount) {
+    const count = this.arrayFixlenHeader(FixlenSubtype.Fp32, 4, schemaCount);
     const out = new Array(count);
     for (let i = 0; i < count; i++) out[i] = this.rawFp32();
     return out;
   }
+  /**
+   * 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) {
+    const count = this.arrayFixlenHeader(FixlenSubtype.Fp32, 4, schemaCount);
+    return this.take(count * 4);
+  }
   /** Read an fp64 array (wire {@link WireType.ArrayFixlen}, element subtype fp64). */
-  readFp64Array() {
-    const count = this.arrayFixlenHeader(FixlenSubtype.Fp64, 8);
+  readFp64Array(schemaCount) {
+    const count = this.arrayFixlenHeader(FixlenSubtype.Fp64, 8, schemaCount);
     const out = new Array(count);
     for (let i = 0; i < count; i++) out[i] = this.rawFp64();
     return out;
@@ -1689,8 +1877,14 @@ var Cursor = class {
       }
       const id = this.upper();
       if (id > ID_MAX) throw invalidMsgError(`field id ${id} out of range`);
-      if (wire === WireType.SequenceStart) depth++;
-      else this.skipValue(wire);
+      if (wire === WireType.SequenceStart) {
+        if (this.depth + depth - 1 >= MAX_DEPTH) {
+          throw invalidMsgError(`nesting exceeds MAX_DEPTH (${MAX_DEPTH})`);
+        }
+        depth++;
+      } else {
+        this.skipValue(wire);
+      }
     }
   }
   // --- field helpers ------------------------------------------------------
@@ -1717,11 +1911,18 @@ var Cursor = class {
     }
     return -1;
   }
-  /** Read and validate an array count word (0..ARRAY_MAX; §4.7/§4.8). */
-  arrayCount() {
+  /**
+   * 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.
+   */
+  arrayCount(schemaCount) {
     this.readVarint();
     const count = this.num();
     if (count > ARRAY_MAX) throw invalidMsgError("array count out of range");
+    if (schemaCount !== void 0 && count > schemaCount) {
+      throw invalidMsgError("array count above schema capacity");
+    }
     if (count > this.maxArrayCount) {
       throw limitExceededError(
         `array count ${count} exceeds maxArrayCount ${this.maxArrayCount}`
@@ -1738,13 +1939,20 @@ var Cursor = class {
     if (sub !== wantSub) throw invalidMsgError(`invalid fixlen subtype ${sub}`);
     if (len !== wantLen) throw invalidMsgError("fixlen float length mismatch");
   }
-  /** Read a scalar fixlen sub-header for a string/blob, asserting subtype; returns byte length. */
-  fixlenLen(wantSub) {
+  /**
+   * 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.
+   */
+  fixlenLen(wantSub, schemaMaxlen) {
     this.readVarint();
     const sub = this.lo & 7;
     const len = this.upper();
     if (sub !== wantSub) throw invalidMsgError(`invalid fixlen subtype ${sub}`);
     if (len > FIXLEN_MAX) throw invalidMsgError("fixlen length out of range");
+    if (schemaMaxlen !== void 0 && len > schemaMaxlen) {
+      throw invalidMsgError("fixlen length above schema maxlen");
+    }
     const limit = wantSub === FixlenSubtype.String ? this.maxStringLen : this.maxBlobLen;
     if (len > limit) {
       const what = wantSub === FixlenSubtype.String ? "string" : "blob";
@@ -1755,11 +1963,18 @@ var Cursor = class {
     }
     return len;
   }
-  /** Read an array fixlen element header (count + element type); returns the count. */
-  arrayFixlenHeader(wantSub, wantSize) {
+  /**
+   * 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.
+   */
+  arrayFixlenHeader(wantSub, wantSize, schemaCount) {
     this.readVarint();
     const count = this.num();
     if (count > ARRAY_MAX) throw invalidMsgError("array count out of range");
+    if (schemaCount !== void 0 && count > schemaCount) {
+      throw invalidMsgError("array count above schema capacity");
+    }
     if (count > this.maxArrayCount) {
       throw limitExceededError(
         `array count ${count} exceeds maxArrayCount ${this.maxArrayCount}`