@sofa-buffers/corelib 0.8.1 → 0.11.0

package/dist/index.d.cts

@@ -70,6 +70,28 @@ declare const U64_MAX = 18446744073709551615n;
 declare const I64_MIN = -9223372036854775808n;
 /** Largest signed 64-bit value (`2^63 - 1`). */
 declare const I64_MAX = 9223372036854775807n;
+/**
+ * The smallest output buffer this port accepts **for streaming** (CORELIB_PLAN
+ * §5.1, normative): the number a caller sizes a streaming buffer from.
+ *
+ * `1`, because the encoder splits every *atomic unit* — a field header varint, a
+ * fixlen word, an element count, a scalar or array element varint, an `fp32` /
+ * `fp64` element — across a flush, so no write needs contiguous room and the
+ * bytes produced are identical at any buffer size. (A port that required atomic
+ * units to land contiguously would declare the largest run it reserves instead;
+ * §5.1 caps any declaration at `20`.)
+ *
+ * It binds a buffer installed **with** a flush sink, at construction and at
+ * every mid-stream `OStream.setBuffer`: such a buffer must satisfy
+ * `buffer.length - offset >= MIN_OUTPUT_BUFFER` and is rejected right there
+ * with `SofabErrorCode.Argument`, never partway through a message.
+ *
+ * A buffer installed **without** a sink is subject to no minimum: no flush can
+ * occur, so nothing can be split, and the buffer either holds the whole message
+ * or reports `SofabErrorCode.BufferFull`. That is the one-shot `MAX_SIZE` case
+ * and it stays exact — a two-byte message encodes into a two-byte buffer.
+ */
+declare const MIN_OUTPUT_BUFFER = 1;
 /**
  * Maximum nested-sequence depth (§4.9 / §6.2). An encoder must not open more
  * than this many nested sequences, and a decoder must reject a message that
@@ -87,13 +109,22 @@ declare const MAX_DEPTH = 255;
  *   payload shorter than its declared length, an array that runs off the end, or
  *   a nested sequence never closed). **Not an error** — more bytes could
  *   complete it, and the caller owns end-of-input.
- * - `Invalid` — the bytes are malformed regardless of what follows.
+ * - `Invalid` — the bytes are malformed regardless of what follows. **Terminal**
+ *   (CORELIB_PLAN §5.2): no later bytes can undo it.
+ *
+ * **Each of the three leaves by exactly one channel.** {@link IStream.feed}
+ * *returns* `Complete` or `Incomplete` — that is the {@link FeedStatus} pair, and
+ * the caller needs no end step (CORELIB_PLAN §6). `Invalid` is never returned by
+ * anything: it is the name of the outcome the throw carries, a {@link SofabError}
+ * whose `code` is {@link SofabErrorCode.InvalidMsg}, and the verdict latches, so
+ * every further `feed` re-throws without consuming input. There is no accessor
+ * that re-reports any of the three, because a fact with two ways to learn it is a
+ * fact that can be learned two different ways.
  *
- * {@link IStream.end} returns `Complete` or `Incomplete` (an `Invalid` message
- * has already thrown from {@link IStream.feed}); the one-shot {@link decode} /
- * {@link Cursor} path signals `Incomplete` and `Invalid` by throwing a
- * {@link SofabError} whose `code` is {@link SofabErrorCode.Incomplete} or
- * {@link SofabErrorCode.InvalidMsg}, and `Complete` by returning normally.
+ * The one-shot {@link decode} — the same stream, fed once — signals `Incomplete`
+ * and `Invalid` by throwing a {@link SofabError} whose `code` is
+ * {@link SofabErrorCode.Incomplete} or {@link SofabErrorCode.InvalidMsg}, and
+ * `Complete` by returning normally.
  */
 declare const DecodeStatus: {
     /** The bytes ended exactly at a field boundary — a valid message. */
@@ -105,6 +136,19 @@ declare const DecodeStatus: {
 };
 /** A decode's terminal outcome: one of the {@link DecodeStatus} values. */
 type DecodeStatus = (typeof DecodeStatus)[keyof typeof DecodeStatus];
+/**
+ * The two outcomes {@link IStream.feed} can *return* — `Complete` and
+ * `Incomplete`, the ones that leave a stream usable.
+ *
+ * `Invalid` is missing on purpose, and the type is the statement: this port puts
+ * a refusal on the error channel (CORELIB_PLAN §6.3's second option), so a
+ * malformed message throws rather than returning, and a caller switching on the
+ * return value has no unreachable arm to write. The refusal is not lost by being
+ * absent here — it arrives as a {@link SofabError} whose `code` says which
+ * refusal it was, which is more than the outcome triple can express: a
+ * `LimitExceeded` rejection has no value among the three at all.
+ */
+type FeedStatus = typeof DecodeStatus.Complete | typeof DecodeStatus.Incomplete;
 
 /**
  * Error handling for SofaBuffers.
@@ -123,16 +167,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`). */
@@ -147,7 +189,8 @@ declare const SofabErrorCode: {
     /**
      * A receiver-configured decode limit was exceeded — a dynamic array, string or
      * blob on the wire claims more elements / bytes than the caller's
-     * {@link DecodeLimits} (`maxArrayCount` / `maxStringLen` / `maxBlobLen`)
+     * receiver cap (`max_dyn_array_count` / `max_dyn_string_len` /
+     * `max_dyn_blob_len`, §6.2.1 — stated by generated code, never by this codec)
      * allows. Deliberately distinct from {@link SofabErrorCode.InvalidMsg}:
      * exceeding a limit is *policy*, not wire malformation — the identical bytes
      * decode fine under a looser limit — so differential fuzzing must not read it
@@ -178,6 +221,12 @@ declare class SofabError extends Error {
  *
  * Values are stored as raw two's-complement bits; the same `Long` serves an
  * unsigned or signed field — {@link Long.toBigInt} takes the signedness.
+ *
+ * The two `bigint` conversions below go through the shared bit-punning scratch
+ * ({@link "./varint/bits64"}) that the codec's own hot paths use, rather than
+ * through mask-and-shift `bigint` arithmetic: the split allocated four
+ * intermediate `bigint`s per call and the join two, on the very boundary this
+ * class exists to make cheap.
  */
 declare class Long {
     /** Low 32 bits (unsigned). */
@@ -195,7 +244,11 @@ declare class Long {
     static readonly ZERO: Long;
     /** Construct from raw 32-bit halves. */
     static fromBits(low: number, high: number): Long;
-    /** Split a `bigint` into its low/high 32-bit halves (two's complement). */
+    /**
+     * Split a `bigint` into its low/high 32-bit halves (two's complement). The
+     * `BigInt64Array` store *is* `ToBigInt64` — reduction modulo 2^64 — so an
+     * out-of-range value keeps exactly the halves the masks kept (bits64).
+     */
     static fromBigInt(value: bigint): Long;
     /** From an integer `number` (`|n| < 2^53`); sign handled via `bigint` once. */
     static fromNumber(n: number): Long;
@@ -207,62 +260,245 @@ declare class Long {
     toString(signed?: boolean): string;
 }
 
+/**
+ * Encode-side text helper.
+ *
+ * Two paths turn strings into UTF-8:
+ *
+ * - {@link utf8Length} / {@link utf8Write} — an allocation-free, two-pass writer
+ *   used by the encoder's contiguous-write fast path. `writeString` needs the byte
+ *   length *before* the payload (it goes into the fixlen length word), so the
+ *   length is scanned first and the bytes are then written straight into the
+ *   output buffer. This avoids `TextEncoder.encode`'s per-call WHATWG setup cost
+ *   plus the throwaway `Uint8Array` it allocates and the second copy into the
+ *   buffer — which V8 profiling showed to be the encoder's dominant cost (a
+ *   short string cost ~700 ns almost entirely in `TextEncoder`).
+ * - {@link utf8WriteSink} — the same walk, emitting one byte at a time into a
+ *   {@link ByteSink}, for the streaming path where the output buffer is narrower
+ *   than the payload and the encoder drains between bytes. It replaces a
+ *   `TextEncoder.encode` into a throwaway array, which was an allocation on a
+ *   codec path and so is not available to it (CORELIB_PLAN §6.6).
+ *
+ * **Strict UTF-8 (MESSAGE_SPEC §8, CORELIB_PLAN §6.4).** A `string` is UTF-8
+ * text; the encode side is always strict for this Unicode-string target. The
+ * platform encoders are lossy — `TextEncoder`, and the hand-rolled fast path it
+ * once mirrored, both replace an **unpaired surrogate** with `U+FFFD` — which is
+ * the silent data mutation §8 forbids in every mode and direction. Both paths
+ * here instead **reject** an unpaired surrogate with an `InvalidArgument`
+ * {@link SofabError} (the encode-side image of the decode `INVALID` outcome), so
+ * a producer can never emit bytes a strict decoder would refuse. Every *valid*
+ * string — ASCII, multibyte BMP, correctly paired astral code points, embedded
+ * `U+0000` — still encodes byte-for-byte as before.
+ */
+/** Anything that takes UTF-8 one byte at a time — in practice, the encoder itself. */
+interface ByteSink {
+    /** @internal Append one byte, draining to the flush sink when the buffer is full. */
+    putByte(b: number): void;
+}
+
 /**
  * The output drain used for streaming encodes.
  *
  * When an {@link OStream} is given a `FlushSink`, it writes into a small caller
- * buffer and hands each filled region to the sink, so a message can be far
- * larger than the buffer — larger than RAM, even. The chunk passed to the sink
- * is only valid for the duration of the call; copy it if you need to retain it.
+ * buffer and hands each filled region to the sink, so a message can be far larger
+ * than the buffer — larger than RAM, even.
+ *
+ * **The sink is only ever handed the installed output buffer** — `buffer` is the
+ * very array the caller installed, and the bytes are `buffer[start..end)`. There
+ * is no second case: CORELIB_PLAN §5.1.6 forbids an encoder from passing the sink
+ * any other memory, so a sink never has to ask whether what it received is its own
+ * buffer or a payload the encoder handed through from somewhere else. (An earlier
+ * revision of the spec permitted that pass-through, off by default; the permission
+ * is withdrawn.)
+ *
+ * The region is valid for the duration of the call. A sink that **copies** it
+ * simply returns, and the encoder keeps writing into the same buffer from offset
+ * `0`. A sink that **takes** the buffer — queues it, hands it to a transport —
+ * must install a replacement with {@link OStream.setBuffer} before returning
+ * (§5.1.5); returning without one means "I copied".
+ *
+ * Passing the buffer and the coordinates rather than a `subarray` of it is not
+ * cosmetic: a view would be an allocation per flush, and the encoder allocates
+ * nothing after construction (§6.6).
+ *
+ * **`needed`** is how many *contiguous* bytes the encoder wants at the cursor
+ * once the handover is done, or `0` when this flush is not a request for room —
+ * an explicit {@link OStream.flush}, or a drain that only needs *some* space. It
+ * is advisory in both directions: a sink is free to ignore it, and the encoder
+ * has a route that works without it (an atomic unit is split, a bulk write falls
+ * back to writing element by element, producing the identical bytes). What it
+ * buys is that a sink which *does* size its replacement — `growingOStream`'s —
+ * can open the bulk path instead of guessing. Without it, a caller-supplied
+ * growing sink can only double blindly and a large array silently loses its
+ * kernel route.
+ *
+ * A sink written before this argument existed keeps working unchanged: it is the
+ * last parameter, optional, and JavaScript simply drops it.
  */
-type FlushSink = (chunk: Uint8Array) => void;
+type FlushSink = (buffer: Uint8Array, start: number, end: number, needed?: number) => void;
 
 /**
  * The SofaBuffers encoder.
  *
- * `OStream` writes fields into a byte buffer. Two modes:
+ * `OStream` writes fields into a **caller-supplied** byte buffer — the corelib
+ * allocates no output buffer and never grows or reallocates one it was handed
+ * (CORELIB_PLAN §5.1). Two ways to drive it:
+ *
+ * - **One-shot** (`new OStream(buffer, offset?)`): the buffer must hold the
+ *   whole message — the size a caller derives from the generated `MAX_SIZE` —
+ *   and a buffer that fills reports `BUFFER_FULL` rather than growing.
+ * - **Streaming** (`new OStream(buffer, offset?, flush?)`): when the buffer
+ *   fills, the produced bytes go to the `flush` sink and encoding continues —
+ *   so the buffer can be arbitrarily smaller than the message, **down to a
+ *   single byte** (§5.1): no single write requires contiguous room, a value
+ *   larger than the buffer is split across flushes, and the bytes produced are
+ *   identical either way — which is why this port declares
+ *   {@link MIN_OUTPUT_BUFFER} = 1, the floor a buffer installed *with* a sink
+ *   must clear. `offset` reserves room at the front for a lower-layer header,
+ *   and it is `length - offset` that must clear the floor. Without a `flush`
+ *   sink there is nowhere to drain to, so no minimum applies.
  *
- * - **In-memory** (`new OStream()`): an auto-growing buffer; call
- *   {@link OStream.bytes} for the finished message.
- * - **Streaming** (`new OStream(buffer, offset?, flush?)`): writes into a
- *   caller-provided buffer and, when it fills, hands the produced bytes to the
- *   `flush` sink and continues — so the buffer can be much smaller than the
- *   message. `offset` reserves room at the front for a lower-layer header.
+ * Where the message has no schema-derived bound, the allocating half is the
+ * caller's, and CORELIB_PLAN §5.1.2 names the shape it takes: "install a scratch
+ * buffer **with a sink** that appends into the growing result". `growingOStream`
+ * (`./accumulate.ts`) is that caller ready-made — a **helper** (§6.6.1) built out
+ * of the streaming mode below, owning storage the encoder never sees the whole
+ * of. `OStream` itself has no growth mechanism at all.
  *
  * 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}.
  */
 
 /**
  * Encoder for the SofaBuffers wire format. Each `write*` method appends one
- * field and maps one-to-one onto a wire type. Construct it in-memory (an
- * auto-growing buffer, read back with {@link OStream.bytes}) or in streaming
- * mode over a caller-provided buffer that drains to a {@link FlushSink} as it
- * fills, so the message can outgrow the buffer. Invalid arguments and a full
- * buffer with no sink throw {@link SofabError}.
+ * field and maps one-to-one onto a wire type. It writes into the buffer the
+ * caller supplies and into no other: it allocates none of its own, grows
+ * none it was given, and has no hook through which anything else could grow one
+ * for it (CORELIB_PLAN §5.1.2, §6.6). Hand it a buffer that holds the whole
+ * message, or one that drains to a {@link FlushSink} as it fills so the message
+ * can outgrow it. Invalid arguments and a full buffer with no sink throw
+ * {@link SofabError}. To let the buffer follow the message instead, encode into
+ * the accumulator `growingOStream` builds — a helper over the streaming mode,
+ * not a mode of this class.
  */
-declare class OStream {
+declare class OStream implements ByteSink {
     private buf;
     private pos;
+    /**
+     * Where the **current flush unit** begins in {@link buf}: the first byte the
+     * next {@link flush} hands to the sink.
+     */
     private start;
+    /**
+     * Where the **message so far** begins in {@link buf} — what {@link bytes} and
+     * {@link bytesUsed} report from.
+     *
+     * Equal to {@link start} for every ordinary stream, and the two move together:
+     * what has not been flushed is the whole of what is still in the buffer. They
+     * part only when a caller installs a replacement that **already holds** the
+     * earlier bytes of this message (`setBuffer`'s `carried` argument) — the shape
+     * an accumulating caller uses, where each new window opens after the bytes the
+     * previous one left behind in the same storage. Keeping the two apart is what
+     * lets that caller be an ordinary sink (§5.1.5) instead of a growth hook
+     * inside the encoder (§6.6).
+     */
+    private origin;
     private readonly flushSink;
-    private readonly canGrow;
     private depth;
-    private kernel;
-    /** In-memory encoder backed by an auto-growing buffer. */
-    constructor();
-    /** Streaming encoder over a caller buffer, optionally draining to `flush`. */
+    /**
+     * 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 and so {@link OStream.commitPending} can zero the
+     * count *before* it writes.
+     *
+     * **Fixed size, sized at construction** from `MAX_DEPTH` — the "fixed-size
+     * state whose size this document fixes" of CORELIB_PLAN §6.6.2, and the shape
+     * §6.0.1 asks for: the run covers the full depth, so it is always a contiguous
+     * suffix of the open sequences, every sequence stays canonical however deep it
+     * nests, and there is no eager-framing fallback. Nothing is allocated per
+     * message, per field or per sequence.
+     *
+     * A plain array rather than an `Int32Array`: a 255-slot typed array is an
+     * external backing store on V8 (~3.1 µs to allocate on Node 24, against ~5 ns
+     * for this), and an encoder is constructed per message on the accumulator path.
+     * Slots are written before they are read, so it is never read holey.
+     */
+    private readonly pending;
+    /** Valid entries in {@link OStream.pending}. */
+    private nPending;
+    /**
+     * How many buffer installations {@link OStream.setBuffer} has made. Only ever
+     * compared for equality across the flush callback, which is how
+     * {@link OStream.flush} tells "the sink copied and returned" from "the sink
+     * took the buffer and installed a replacement" — the one distinction §5.1
+     * rests the handover contract on, and the one that decides whether the start
+     * offset was consumed or re-armed.
+     */
+    private installs;
+    private readonly kernel;
+    /**
+     * Encoder over a caller buffer, optionally draining to `flush` as it fills.
+     *
+     * Those are the only two buffer models there are (CORELIB_PLAN §5.1.1): the
+     * buffer the caller hands over, and whatever a sink installs in its place
+     * (§5.1.5). There is no third parameter through which the encoder could be
+     * given something to enlarge — growing a destination from a write path is what
+     * §6.6's second violation row names, whoever owns the allocator.
+     *
+     * Constructing one is the only allocating step (§6.6): it sizes the hold-back
+     * run from `MAX_DEPTH` and reads the active kernel once. No `write*` call after
+     * that allocates anything.
+     */
     constructor(buffer: Uint8Array, offset?: number, flush?: FlushSink);
-    /** Bytes currently held in the buffer (since construction or the last flush). */
+    /** Bytes of the message currently held in the buffer (see {@link bytes}). */
     get bytesUsed(): number;
     /**
-     * The encoded message so far, as a view into the working buffer.
-     * Meaningful for the in-memory mode; in streaming mode it is only the
-     * not-yet-flushed tail. The view is valid until the next write.
+     * The encoded message so far, as a view into the working buffer: everything
+     * written since construction, the last {@link reset}, or the last flush the
+     * sink returned from without installing a buffer. With a flush sink that is
+     * normally only the not-yet-flushed tail; on a stream whose sink hands back a
+     * replacement carrying the earlier bytes — the accumulator `growingOStream`
+     * builds — it is the whole message. The view is valid until the next write.
      */
     bytes(): Uint8Array;
-    /** Drain buffered bytes to the flush sink (no-op without one). */
+    /**
+     * Drain buffered bytes to the flush sink (no-op without one).
+     *
+     * A sink that returns **without** installing a buffer has copied what it was
+     * handed, so the encoder keeps writing into the same buffer — resuming at
+     * offset **0**. The start offset belongs to the *installation*, not to the
+     * buffer (CORELIB_PLAN §5.1): the buffer-set that armed it — the constructor
+     * or {@link OStream.setBuffer} — reserved room in the unit it began, and
+     * handing that unit over consumes the reservation. A sink that wants header
+     * room in *every* unit re-arms it by calling `setBuffer(buf, offset)` from
+     * inside the callback, a new installation like any other; a bare return must
+     * not do it implicitly, or the leading bytes would be capacity the rest of the
+     * stream could never use and the two shapes would be indistinguishable.
+     */
     flush(): void;
+    /**
+     * {@link flush}, plus the number of contiguous bytes the caller wants at the
+     * cursor afterwards — `0` when it wants none in particular.
+     *
+     * Split out from the public `flush` so the figure cannot be invented by a
+     * caller: it is the encoder's own reserve request, and a sink that sizes a
+     * replacement from it (`growingOStream`) has to be able to trust it. Everything
+     * else is identical, including that a sink which returns without installing has
+     * *copied* and the cursor resumes at `0`.
+     */
+    private drain;
     /**
      * Install a fresh output buffer to write into, mid-stream. Intended for the
      * streaming (flush-sink) mode: call it from inside your flush callback to hand
@@ -270,8 +506,36 @@ declare class OStream {
      * without interruption. `offset` reserves space at the front of the new
      * buffer. Any not-yet-flushed bytes in the old buffer are dropped, so
      * {@link flush} first (the flush callback fires before you swap).
+     *
+     * Every call is a **new installation**, and its `offset` applies to the unit
+     * it begins and is consumed when that unit is flushed (CORELIB_PLAN §5.1).
+     * Passing the buffer the encoder already has is an installation like any
+     * other: that is how a sink gets header room in *every* flushed unit — one
+     * framing header per packet — where returning bare would resume at `0`.
+     *
+     * On a stream that has a flush sink the new buffer must leave at least
+     * {@link MIN_OUTPUT_BUFFER} usable bytes (`buffer.length - offset`); a smaller
+     * one is rejected here, with {@link SofabErrorCode.Argument}, leaving the
+     * encoder on the buffer it already had. A sink-less stream has no minimum.
+     *
+     * `carried` says how many bytes **immediately before `offset`** the
+     * replacement already holds of *this* message — normally `0`, because a fresh
+     * buffer holds none. A caller that keeps the whole message in one growing
+     * store passes the length it copied across, so {@link bytes} keeps reporting
+     * the message rather than only the piece written after the swap. It changes
+     * nothing on the wire and nothing about flushing: the next flush still begins
+     * at `offset`. `growingOStream` is the caller this exists for; it is the
+     * §5.1.5 handover, not a growth hook inside the encoder (§6.6).
+     *
+     * The accumulating stream `growingOStream` builds is an ordinary streaming
+     * stream, so this works on it too, and means exactly what it means anywhere
+     * else: the not-yet-flushed bytes in the old buffer are dropped, encoding
+     * continues into yours, and its sink takes over growing *that* one from the
+     * next flush — reserve offset included, since what it copies out is the
+     * message rather than the buffer. Encode into a plain
+     * `new OStream(buffer, offset, flush?)` to keep the buffer yours instead.
      */
-    setBuffer(buffer: Uint8Array, offset?: number): void;
+    setBuffer(buffer: Uint8Array, offset?: number, carried?: number): void;
     /**
      * Rewind the encoder to empty, reusing the existing buffer. Lets a caller pool
      * one OStream across many messages instead of allocating a fresh buffer per
@@ -282,21 +546,101 @@ declare class OStream {
     writeUnsigned(id: number, value: number | bigint): void;
     /** Write a signed integer field (zig-zag encoded). */
     writeSigned(id: number, value: number | bigint): void;
+    /**
+     * Write an unsigned 64-bit scalar from a {@link Long} — the `bigint`-free twin
+     * of {@link writeUnsigned}, and the scalar counterpart of
+     * {@link writeUnsignedArrayLong}. Produces the identical wire.
+     *
+     * There is no range check and no scratch round-trip: a `Long` *is* two 32-bit
+     * halves, so it is in the `uint64` domain by construction — which is the whole
+     * of what `splitU64` decides for a `number | bigint`. The halves go straight
+     * into the varint writer, so nothing is allocated per value. Nothing needs
+     * copying out ahead of `header` either, for the same reason the array writers
+     * do not: the halves come off a caller-owned immutable `Long`, not the shared
+     * scratch a re-entrant flush sink could overwrite.
+     */
+    writeUnsignedLong(id: number, value: Long): void;
+    /**
+     * Write a signed 64-bit scalar (zig-zag) from a {@link Long} — the
+     * `bigint`-free twin of {@link writeSigned}, and the scalar counterpart of
+     * {@link writeSignedArrayLong}. Zig-zag `(n << 1) ^ (n >> 63)` is computed on
+     * the lo/hi pair, so the varint goes out at its exact size (a fixed caller
+     * buffer must not see a 10-byte demand for a 2-byte field) and no `bigint` is
+     * created. A `Long` carries exactly 64 bits, so as in {@link writeUnsignedLong}
+     * there is nothing left to range-check.
+     */
+    writeSignedLong(id: number, value: Long): void;
     /** Write a boolean field (encoded as the unsigned value 0 or 1). */
     writeBoolean(id: number, value: boolean): void;
     /** Write an IEEE-754 32-bit float field. */
     writeFp32(id: number, value: number): void;
+    /**
+     * Write an fp32 field from its raw wire bits — the 4 little-endian payload
+     * bytes as one 32-bit word, which is exactly what {@link Visitor.fp32} delivers
+     * as `bits`.
+     *
+     * This is the re-encode half of the bit-exactness rule (CORELIB_PLAN §6.5). A JS
+     * `number` is a 64-bit double, and widening an fp32 **signaling** NaN into one
+     * quiets it, so re-encoding through {@link writeFp32} cannot reproduce such a
+     * payload; the bits go out verbatim here, so decode → re-encode is byte-for-byte
+     * for every fp32 value, sNaN included. §6.5 requires this path of every
+     * double-only target, and names it: "a 32-bit bits accessor".
+     */
+    writeFp32Bits(id: number, bits: number): void;
     /** Write an IEEE-754 64-bit double field. */
     writeFp64(id: number, value: number): void;
     /** Write a UTF-8 string field. */
     writeString(id: number, text: string): void;
     /** Write a blob (arbitrary bytes) field. */
     writeBlob(id: number, data: Uint8Array): void;
-    /** Write a fixed-length field of the given subtype from raw bytes. */
+    /**
+     * Write a fixed-length field of the given subtype from raw bytes.
+     *
+     * This is the byte-level entry point — the one writer that takes the subtype
+     * from the caller rather than picking it — so the payload is checked
+     * **against that subtype** before a byte is written, and it cannot emit a
+     * `fixlen_word` a conformant decoder must reject (`ARGUMENT`, §6.3):
+     *
+     * * subtypes `0x4`–`0x7` are **reserved** — a decoder must treat a field
+     *   carrying one as malformed (`INVALID`, §4.6/§5.2);
+     * * `Fp32` / `Fp64` payloads are **exactly** 4 / 8 bytes — any other declared
+     *   length for those subtypes is malformed, rejected the moment the word is
+     *   read (§4.6);
+     * * `String` / `Blob` take any length up to `FIXLEN_MAX`.
+     *
+     * The typed writers ({@link writeFp32}, {@link writeFp64},
+     * {@link writeString}) are correct by construction and go straight to the
+     * header; only {@link writeBlob}, whose subtype is unconstrained anyway,
+     * shares this path.
+     */
     writeFixlen(id: number, data: Uint8Array, subtype: FixlenSubtype): void;
-    /** Write an array of unsigned integers (each a varint). */
+    /**
+     * Write an array of unsigned integers (each a varint).
+     *
+     * **The bulk kernel writes a whole array in one pass and cannot flush**, so it
+     * runs only where everything is known to fit. Three cases, and none of them
+     * asks the source how wide its elements are:
+     *
+     * * **block mode** (no sink) — the buffer is meant to hold the whole message,
+     *   so the kernel always runs and the buffer's length is the bound, checked
+     *   after the fact. A message that does not fit is `BUFFER_FULL`, which is
+     *   precisely this mode's answer.
+     * * **a stream with room** — `VARINT_MAX_BYTES` per element is the true
+     *   worst case for any 64-bit value, and a *growing* stream always satisfies
+     *   it because it grows to whatever is asked.
+     * * **a chunk too small for that** — fill it to the last byte, hand it over,
+     *   carry on, splitting an element where it falls. That is not a fallback but
+     *   the mode's contract: `MIN_OUTPUT_BUFFER` is 1.
+     *
+     * What is gone is the fourth case, which asked `values.constructor` for a
+     * narrower bound so the kernel would run on a tightly-sized chunk. `constructor`
+     * is an ordinary property, an `ArrayLike` can claim any width, and a wrong
+     * answer silently truncated the message — §5.1's "partial output handed back as
+     * complete". The block mode now reaches the kernel without needing the number
+     * at all, which is where a tightly-sized buffer actually lives.
+     */
     writeUnsignedArray(id: number, values: ArrayLike<number | bigint>): void;
-    /** Write an array of signed integers (each zig-zag + varint). */
+    /** Write an array of signed integers (each zig-zag + varint). See {@link writeUnsignedArray}. */
     writeSignedArray(id: number, values: ArrayLike<number | bigint>): void;
     /**
      * Write an unsigned 64-bit array from {@link Long}[] — the `bigint`-free path.
@@ -311,390 +655,1405 @@ 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;
-    /** Ensure exactly `value`'s varint size, then write it (bigint path). */
-    private putVarint;
+    /**
+     * 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 (number fast path). */
     private putVarintNum;
+    /**
+     * The multi-byte / needs-room tail of {@link putVarintNum}, kept in its own
+     * method so the single-byte test above stays small enough for the JIT to
+     * inline into every `header` / `fixlenHead` / `arrayHead` call site.
+     */
+    private putVarintNumSlow;
+    /**
+     * Write a 64-bit value, held as two 32-bit halves, as a varint.
+     *
+     * Deliberately just a bounds check and two calls: this is what the array
+     * loops call per element, and it only pays its way while it is small enough
+     * for the JIT to inline. Spelling the drain case out here instead — three
+     * more lines — cost 16-19% on an array streamed through a 32/64-byte buffer,
+     * where most elements take the fast path and want it inlined.
+     */
+    private putVarintLoHi;
+    /**
+     * A full buffer that is nonetheless wide enough to hold any varint: drain it
+     * and retry the worst case, which is exactly what `ensure(VARINT_MAX_BYTES)`
+     * did before §5.1 and is still the common streaming case. Sizing the value
+     * first instead — the narrow-buffer path in {@link putVarintLoHiTight} — cost
+     * +125 instructions on every element of an array streamed through a
+     * one-element-wide buffer.
+     */
+    private putVarintLoHiSlow;
+    /**
+     * Zig-zag {@link putVarintLoHi}: `(n << 1) ^ (n >> 63)` on the halves. Keeps
+     * its own worst-case fast path so the signed array loop reaches the combined
+     * zig-zag-and-encode writer directly, exactly as it did before; the drain and
+     * narrow-buffer cases are the same for both signs, so they are shared.
+     */
+    private putZigzagVarintLoHi;
+    /**
+     * The narrow-buffer tail of {@link putVarintLoHi}: the buffer could not hold a
+     * worst-case varint even empty. Sizing the value exactly keeps such a buffer
+     * from flushing for room it does not need; only when it cannot hold the varint
+     * *at all* does the value get split across flushes, seven bits at a time.
+     */
+    private putVarintLoHiTight;
+    /**
+     * Write the 4 little-endian bytes of an fp32 (§4.6).
+     *
+     * Through the shared scratch, not a `DataView` over the buffer: building that
+     * handle costs ~129 ns against the ~2 ns it saves on one value (§6.6.2 allows the
+     * handle, arithmetic forbids it here). The bulk array path amortizes one over the
+     * whole run instead — see the kernel.
+     */
+    private putFp32;
+    private putFp32Slow;
+    /**
+     * Write the 4 little-endian bytes of an fp32 held as a 32-bit word (§4.6) — the
+     * path {@link OStream.writeFp32Bits} takes, and the tail of
+     * {@link OStream.putFp32Slow}.
+     */
+    private putFp32Bits;
+    /**
+     * {@link writeFp32Array} for a `Float32Array` source: its own 32-bit words go
+     * out, never a `number`, which is what keeps a signaling NaN intact (§6.5) —
+     * on the bulk path (the kernel copies words too) and on the streamed one alike,
+     * so a small buffer produces the one-shot bytes (§5.1.4).
+     *
+     * Kept to the header and the bulk call, the streaming loop in its own method:
+     * with the loop in this body an 8-element one-shot array cost +416 Ir/op
+     * (+8.8%) over the pre-#185 encoder, split like this +1.1% (Callgrind).
+     */
+    private writeFp32Words;
+    /**
+     * The streamed half of {@link writeFp32Words}: one `Uint32Array` over the
+     * source per call, the same handle the bulk kernel takes (§6.6.2); reading it gives each word's value whatever the
+     * host byte order, and the shifts below store it little-endian. The words go
+     * out one run per stretch of free buffer, with `buf`/`pos` in locals, and the
+     * split points are {@link putFp32}'s: drain when fewer than 4 bytes are free,
+     * split an element byte by byte only when the buffer itself is narrower than 4.
+     */
+    private putFp32Words;
+    /** Write the 8 little-endian bytes of an fp64 (§4.6) — see {@link putFp32}. */
+    private putFp64;
+    private putFp64Slow;
+    /**
+     * Append one byte, draining to the sink first when the buffer is full.
+     *
+     * @internal Public only because {@link utf8WriteSink} writes through it — the
+     * narrow-buffer string path (§5.1.3). Not part of the field-writing API.
+     */
+    putByte(b: number): void;
+    /**
+     * 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). */
+    /**
+     * Copy `data` out, flushing/growing as needed (large payloads stay chunked).
+     *
+     * The whole-payload case — the common one, and the only one on a buffer sized
+     * from `MAX_SIZE` or on the accumulator — is a single `set` of the caller's
+     * array: a `memcpy`, and no view at all.
+     *
+     * **A payload split across flushes takes a per-piece view: a language-forced
+     * handle under CORELIB_PLAN §6.6.2.** `TypedArray.set` is the only `memcpy`
+     * this language exposes and it takes a *typed array* as its source, so copying a
+     * *range* of one needs a `subarray` — §6.6.2's "the only way to name a region of
+     * the caller's buffer is a wrapper over it". It has the two properties that
+     * clause requires: it carries no message bytes (the storage is the caller's, on
+     * both ends) and no wire number sizes it (a handle over a thousand bytes costs
+     * what a handle over ten costs). The allocation-free alternative is a byte loop,
+     * measured at 358 MB/s against 10,963 MB/s for `set`.
+     *
+     * It never leaves this method: `set` consumes it and no caller can reach it, so
+     * §6.7's ban on exposing a value that outlives its callback is untouched — and so
+     * is §5.1.6, which is why the copy happens at all rather than the payload being
+     * handed to the sink. §6.6.2 asks the port to make such handles visible rather
+     * than invisible: the README itemises it (§9.6) and `heap-free-codec.test.ts`
+     * pins its count and kind.
+     */
     private writeRaw;
-    /** Ensure `n` contiguous bytes are free at `pos`; returns `pos` for chaining. */
+    /**
+     * Make room for `n` contiguous bytes at `pos` if the buffer can hold them at
+     * all: `true` when it can (flushing or growing as needed), `false` when a
+     * fixed caller buffer is simply smaller than `n` and the value must be split
+     * across flushes instead — CORELIB_PLAN §5.1 puts the floor on the output
+     * buffer at a single byte, so no write may demand a contiguous run.
+     *
+     * The one case that still fails is a buffer with no sink to drain to: there is
+     * nowhere for a split to put the earlier bytes, so it reports BufferFull here,
+     * before anything is written, exactly as {@link ensure} did.
+     */
+    private tryEnsure;
+    /**
+     * Reserve `n` contiguous bytes for a bulk write — the whole payload of an
+     * array or a string, written in one pass into a buffer that cannot move under
+     * it. Every caller has an element-at-a-time route to fall back on when this
+     * says no, producing the identical bytes, so a `false` here is never an error.
+     *
+     * The room already at the cursor counts on **any** buffer, which is what makes
+     * the one-shot `new OStream(buf)` case — a caller buffer sized from the
+     * schema's `MAX_SIZE`, the shape CORELIB_PLAN §5.1 puts first — the fast one:
+     * without it a message encoded into a caller's own buffer took `TextEncoder`
+     * for every string and the element loop for every array, measured at 1.9 µs
+     * against 0.16 µs for the same five-field message.
+     *
+     * Beyond that room only a **sink** may be asked, and only by draining. Emptying
+     * the buffer is the one thing that can produce room without an allocation
+     * anywhere (§6.6), and it is legal wherever this is called — every caller has
+     * just written a complete header, so the cursor is on a boundary between atomic
+     * units (§5.1.3). A sink that installs a larger replacement (§5.1.5) therefore
+     * re-opens the bulk route by itself, which is how the accumulating helper keeps
+     * it. Nothing is *demanded*: a `false` sends the caller down its
+     * element-at-a-time route, which produces the identical bytes, so a fixed
+     * buffer too narrow for the worst case never turns into a spurious
+     * `BUFFER_FULL`.
+     */
+    private reserveBulk;
+    /**
+     * Commit the position a bulk kernel returned, in the **block** mode.
+     *
+     * Nothing reserves room in front of that kernel, and nothing could: the bytes an
+     * array takes are only known once it is encoded, and the estimate that used to
+     * stand in — the source's own `constructor`, which any object can set — silently
+     * truncated the message when it was wrong (§5.1). Here the bound is the buffer's
+     * own length, applied afterwards. The varint kernels stop writing at
+     * `out.length` and keep counting (see {@link Kernel}), so a `pos` past the end
+     * is the exact shortfall and nothing was written outside the buffer.
+     *
+     * This is the block mode's error and only its: the buffer is meant to hold the
+     * whole message, so one that does not fit is exactly what `BUFFER_FULL` means.
+     * The streaming mode never gets here, and `BUFFER_FULL` is unreachable there by
+     * contract.
+     */
+    private bulkEnd;
+    /**
+     * Ensure `n` contiguous bytes are free at `pos`; returns `pos` for chaining.
+     *
+     * The only remaining caller is the one-byte sequence-end marker, which is
+     * indivisible: there is no smaller piece to split it into, so a buffer that
+     * cannot take it has nothing left to report but `BUFFER_FULL`.
+     */
     private ensure;
     /** Ensure *some* room (up to `want`); returns how many bytes are available. */
     private ensureSome;
-    private growTo;
 }
 
 /**
- * Opt-in decode resource limits (corelib-ts#38).
+ * `growingOStream` — the caller that lets the buffer follow the message.
+ *
+ * **This is the static helper layer, not the codec** (CORELIB_PLAN §6.6.1). The
+ * codec is {@link OStream}: it writes into the buffer it was handed and has no
+ * way to enlarge one. Where the schema bounds the message, generated code sizes
+ * one buffer from `MAX_SIZE` and a plain `new OStream(buf)` is the whole story.
+ * Where it does not, §5.1.2 names exactly one shape for the unbounded case:
+ *
+ * > Install a scratch buffer **with a sink** that appends into the growing
+ * > result; the scratch is subject to `MIN_OUTPUT_BUFFER` like any
+ * > sink-installed buffer.
+ *
+ * That is what this file builds, so neither generated code nor a hand-written
+ * one-shot encode has to write it again. The scratch and the result are the same
+ * storage: the encoder is installed over the free tail of a buffer this module
+ * owns, and when it fills, the flush callback fires, this module enlarges its
+ * storage and installs the next tail with {@link OStream.setBuffer} — §5.1.5's
+ * taking sink, and §6.6.1's second row, a helper reached from inside a callback
+ * the codec made. Because the encoder was writing *into the result all along*,
+ * absorbing a flush is one assignment: there is no per-flush copy.
+ *
+ * The predecessor was a `BufferOwner` hook: the encoder called it from
+ * `ensureSome`, i.e. from every `write*`, and kept the buffer it returned. That
+ * is §6.6's second violation row — "the codec allocates nothing itself but
+ * requires a growable destination and grows it … it moved the allocator call one
+ * type away, where a source-level audit no longer sees it" — and the hook is gone
+ * with it (A2-0159).
+ *
+ * **No subclass, deliberately.** An `OStream` subclass overriding `bytes()` was
+ * the obvious shape and cost 2.3x on `encode: composite`: a program that uses
+ * both `growingOStream()` and `new OStream(buf)` would then have two receiver
+ * maps at every `os.write*` call site, and V8 stops inlining a polymorphic one.
+ * `setBuffer`'s `carried` argument buys the same behaviour with one map and one
+ * extra number in the encoder, and a stateless module-level sink keeps the
+ * per-stream cost at exactly what it was: one buffer.
+ */
+
+/**
+ * An {@link OStream} whose **buffer follows the message** — the ready-made form
+ * of the caller CORELIB_PLAN §5.1.2 puts the allocation in.
+ *
+ * It is the one-liner for the 90% case, where the message comfortably fits in
+ * memory:
+ *
+ * ```ts
+ * const os = growingOStream();
+ * os.writeUnsigned(1, 42);
+ * const wire = os.bytes();   // the whole message, as a view valid until the next write
+ * ```
+ *
+ * {@link OStream.bytes} is therefore the **whole** message here rather than a
+ * not-yet-flushed tail, and no write reports `BUFFER_FULL`. It is an ordinary
+ * streaming stream in every other respect: {@link OStream.setBuffer} works and
+ * means what it always means — the not-yet-flushed bytes in the old buffer are
+ * dropped and encoding continues into yours, which the accumulator then grows in
+ * turn.
+ *
+ * @param initialCapacity bytes to start from; the accumulator enlarges itself
+ * whenever the message outgrows it, so this only trades an initial allocation
+ * against the number of enlargements and never limits the message. A caller with
+ * a rough size in hand should pass it: 100 KB of *small fields* grows by doubling
+ * and costs nine enlargements from the 256-byte default. A single large field
+ * does not — a bulk write hands the sink its `needed`, so the buffer reaches that
+ * size in one step and the write keeps its bulk route.
+ */
+declare function growingOStream(initialCapacity?: number): OStream;
+
+/**
+ * The SofaBuffers decoder: `IStream`, and the visitor it drives.
+ *
+ * The **visitor is the only decode surface** (CORELIB_PLAN §5.3.1). There is no
+ * pull parser, no iterator, no cursor and no convenience wrapper that decodes by
+ * another route: a second surface is a second implementation of every rule in the
+ * spec, and the divergences that produces are invisible to the shared vectors,
+ * which exercise whichever surface the driver happened to pick.
+ *
+ * `IStream` is a push parser: bind a {@link Visitor} at construction, feed bytes
+ * with {@link IStream.feed}, and it calls one method per decoded field. It is a
+ * resumable state machine, so the chunks can be any size — a whole message, a
+ * network packet, or a single byte — and a field that straddles a chunk boundary
+ * is picked up seamlessly on the next call.
+ *
+ * The visitor is **flat**: one object receives the whole message, and nesting is
+ * reported as {@link Visitor.sequenceBegin} / {@link Visitor.sequenceEnd} events
+ * carrying the sequence's id and depth. A visitor per nested scope would make
+ * every dispatch site here megamorphic — one hidden class per generated message
+ * class in the tree — and would put a per-scope object on the decode path; one
+ * flat visitor keeps the call sites (bi)morphic and the decoder allocation-free
+ * (§6.6). Descending and skipping are unchanged by that choice: `sequenceBegin`
+ * answers `false` to decline a subtree whole, and a field whose callback the
+ * visitor does not implement is skipped.
+ *
+ * There is no finish / finalize step (§5.2.4) and no status accessor beside the
+ * call: {@link IStream.feed} *returns* the outcome for the bytes consumed so far,
+ * and that return value is the whole answer. A message that merely ends inside a
+ * field is reported — never thrown — as {@link DecodeStatus.Incomplete}; only a
+ * *malformed* message throws ({@link SofabErrorCode.InvalidMsg}), which is this
+ * port's channel for {@link DecodeStatus.Invalid}. The caller owns end-of-input
+ * and decides whether a trailing `Incomplete` is a truncation error.
+ *
+ * **One fact, one channel.** Each outcome leaves by exactly one route — two of
+ * the three by the return value, the refusals by the throw — because a second way
+ * to ask the same question is a second thing to keep in step, and this family
+ * shipped the drift: a `status()` accessor answered `COMPLETE` for a message
+ * `feed` had already refused. §5.3.1 makes the general form of the argument for
+ * decode surfaces ("every additional surface is a second implementation of every
+ * rule in this document"); the accessor was the same mistake one size down.
+ */
+
+/**
+ * Where an array's elements are written when the visitor takes the **bulk
+ * hand-off** ({@link Visitor.arrayBulk}): the destination it already owns, handed
+ * over once, instead of one callback per element.
+ *
+ * **Why this replaced the per-element callbacks.** There used to be an
+ * `arrayUnsigned` / `arraySigned` / `arrayFp32` / `arrayFp64` beside this, one call
+ * per element. Measured with `bench/run_callgrind.sh`'s method over 1000-element
+ * arrays (Ir/op for a message that is one array), against this hand-off filling
+ * the same destination:
+ *
+ * | array | per element (removed) | hand-off | |
+ * |---|---:|---:|---:|
+ * | `array<u16>` into a `number[]` | 235 433 | 184 025 | −21.8% |
+ * | `array<u64>` into a `Long[]` | 576 206 | 429 113 | −25.5% |
+ * | `array<u64>` into {@link IntegerArrayTarget.lo}/`hi` | 498 618 | 299 180 | −40.0% |
+ * | `array<fp64>` into a `Float64Array` | 93 520 | 36 890 | −60.6% |
+ * | `array<fp32>` into a `Float32Array` | 94 497 | 35 259 | −62.7% |
+ *
+ * Floats gain most because their *reading* was already bulk (the §6.6.2 handle in
+ * the element drain), so the callback was very nearly all that was left.
+ *
+ * **A short array is not the exception.** The fixed cost — the offer, the
+ * target's resolution, the bound's validation — is about 600 Ir, but the hand-off
+ * takes a whole array in one call, tail elements included, so it is paid once:
+ * four elements at the end of a 37-byte message cost 578 Ir against the 563 the
+ * removed callbacks cost, and everything longer is the table above.
+ *
+ * **What did move is the consumer's side, for a consumer that folds.** An element
+ * callback let a reader sum, hash or convert *inside* the delivery; reading a
+ * filled destination is a second pass. A reader that wants the values where they
+ * are — which is what generated code wants — has no second pass and gets the
+ * table. A reader that folds pays one: the same four-element array costs 1 063 Ir
+ * if it sums the destination at `arrayEnd`, against 563 folding per element.
+ * It is a cheaper pass than the calls it replaced on any array long enough to
+ * matter, and on a four-element one it is not.
+ *
+ * **Declining costs nothing at all.** An array no visitor takes is walked over
+ * rather than decoded: `array<fp64>` 36 890 → 9 383 Ir/op, `array<u16>` 184 025 →
+ * 152 082.
+ *
+ * **This is how array elements are delivered — the only way.** There is no
+ * callback per element beside it: §5.3.1 allows a rule one implementation, and
+ * two delivery routes for the same elements were two places for the element bound
+ * to be compared, two resume paths to keep in step, and a standing invitation for
+ * generated code to take the slower one. `arrayBegin` and `arrayEnd` still fire
+ * for every array; returning `null` declines delivery, and the elements are then
+ * walked over without being decoded into existence — the `skip` half of §6.7.2's
+ * two intents, which is what a visitor that declares no `arrayBulk` gets for
+ * every array.
+ *
+ * **The destination is filled ascending from index 0**, one write per element,
+ * and it must stay valid — same object, same length — until `arrayEnd`, which for
+ * a chunked decode is several {@link IStream.feed} calls later. A plain-array
+ * destination (`values` / `longs`) is **cut to the elements written when the array
+ * ends** — including to zero for an array that is empty on the wire, and to the
+ * prefix when an element is refused — so reusing one across arrays or messages can
+ * never leave the previous array's tail behind, and after `arrayEnd` its `length`
+ * is exactly this array's element count. (Cutting at the end rather than emptying
+ * up front is measured: emptying first makes every element write a grow, which
+ * cost `array<u16>` 181 583 → 231 815 Ir/op.) A typed destination is neither cut
+ * nor emptied — it cannot be — and must already hold `count` elements.
+ *
+ * A decode that fails *inside* an array for any other reason — malformed bytes, or
+ * input that simply ends — leaves the destination holding what had been written
+ * when it stopped. `length` is a statement about the array only once `arrayEnd`
+ * has been raised or an element has been refused. This is the one
+ * place the codec holds a reference to the caller's storage between calls (§6.6
+ * otherwise holds nothing past a callback), and the reference is dropped at
+ * `arrayEnd` and whenever a pooled machine is released.
+ *
+ * **A refused element leaves the destination holding the prefix**: everything
+ * before it is written, the offending element and everything after it is not, and
+ * a plain-array destination is cut to exactly that length. Like every `INVALID`
+ * verdict it is terminal (§5.2.1).
+ */
+type ArrayTarget = IntegerArrayTarget | FloatArrayTarget | BoolArrayTarget;
+/**
+ * A `boolean` array's destination: one byte per element, `0` or `1`.
+ *
+ * It carries **no bound**, and that is the whole reason it is a shape of its own
+ * rather than a {@link IntegerArrayTarget.typed} `Uint8Array`. §4.4 gives a boolean
+ * no width bound — every non-zero wire value is `true` — so there is no interval to
+ * state and nothing for the width check to compare. A raw store would be wrong
+ * twice over: 256 would mask to `0` and turn `true` into `false`. The decoder
+ * NORMALIZES instead, writing `1` for any non-zero, which is also the only value
+ * §4.4 lets an encoder emit back — so a filled destination re-encodes canonically
+ * with no conversion step in between.
+ */
+interface BoolArrayTarget {
+    bool: Uint8Array;
+}
+/**
+ * An integer array's destination and the **element bound** to enforce while
+ * filling it — for an `ArrayKind.Unsigned` or `ArrayKind.Signed` array.
  *
- * SofaBuffers' `count` (arrays) and `maxlen` (strings / blobs) schema bounds are
- * optional; when a schema omits them the decoder accepts whatever count / length
- * the received message claims, with no upper bound. That leaves a receiver no way
- * to cap memory against a hostile, oversized field. {@link DecodeLimits} is that
- * cap: an optional options object accepted by every decode entry point
- * ({@link decode}, the {@link IStream} constructor, and the {@link Cursor}
- * constructor).
+ * Exactly one destination must be set (`values`, `longs`, or `lo` *and* `hi`);
+ * any other combination is a caller mistake and is refused with
+ * {@link SofabErrorCode.Argument} before a single element is written.
  *
- * The limits are a **receiver-side policy**, not part of the wire format or the
- * message schema. The normative source of the values is the sofabgen config
- * (see sofa-buffers/generator#102): the generator bakes them into generated code
- * as constants and passes them here at decoder construction. This corelib only
- * provides the mechanism — **an omitted limit means no cap (today's behavior);
- * there is no corelib-side default.**
+ * **The bound is four halves, and it is never optional.** The interval is the
+ * schema's — `0..65535` for a `u16`, `-2^63..2^63-1` for an `i64` — so its
+ * violation is `INVALID`, a statement about the message (§6.2.1 keeps a
+ * *receiver* cap off a field the schema already bounds; a receiver cap on the
+ * element *count* is compared by the visitor in `arrayBegin`, as before, and this
+ * hand-off happens after it).
  *
- * Enforcement happens at header time — where the count / length is first decoded,
- * before any array is sized or any payload is accepted or streamed — so a claimed
- * oversize is rejected even if the payload never arrives. Exceeding a limit is
- * never clamped or truncated: it throws a {@link SofabError} with code
- * {@link SofabErrorCode.LimitExceeded}, which is deliberately distinct from
- * `InvalidMsg` (policy, not malformation).
+ * Halves rather than a `number` pair because a `number` cannot express the
+ * 64-bit domain: `u64`'s bound is `2^64-1` and `Number.MAX_SAFE_INTEGER` is
+ * `2^53-1`, so a `number` bound both *rejects valid messages* at the top of the
+ * range and makes the comparison a mixed `bigint`/`number` one, which measured
+ * +35% on `array<u64>` — worse than the per-element path it replaces. Two
+ * unsigned 32-bit comparisons are exact and cost nothing.
+ *
+ * For a **signed** array the halves are the two's-complement ones (an `i16`
+ * minimum of `-32768` is `minLo = 0xffff8000`, `minHi = 0xffffffff`).
+ * {@link Long.fromBigInt} is the ready-made way to compute them from the schema's
+ * bound once.
+ *
+ * The codec **compares** the bound; it never owns one (§6.2.1). There is no
+ * default and no "unbounded" spelling, because an integer element always has a
+ * declared width: the widest `u64` interval is `0 .. 0xffffffff_ffffffff` and is
+ * stated as such.
  */
-interface DecodeLimits {
+interface IntegerArrayTarget {
     /**
-     * Reject a dynamic (`u*` / `i*`, `fp32` / `fp64`) array whose element `count`
-     * exceeds this, before the array is materialized. Omit for no cap.
+     * Number-first destination: each element as the `value` its per-element
+     * callback would have received — a `number` when it fits exactly (`≤ 2^53-1`,
+     * every `u8`..`u32` and small 64-bit values) and a `bigint` beyond that. The
+     * right destination for `u8`..`u32` / `i8`..`i32` arrays, where no `bigint` is
+     * ever built.
+     *
+     * A real `Array` — grown as it fills and cut to length when the array ends, so
+     * it need not be pre-sized and never carries a previous array's tail. A typed
+     * array here is refused with {@link SofabErrorCode.Argument}: it would take the
+     * writes and silently drop everything past its own length.
      */
-    maxArrayCount?: number;
+    values?: (number | bigint)[];
     /**
-     * Reject a UTF-8 string whose declared byte length exceeds this, before the
-     * payload is decoded or streamed. Omit for no cap.
+     * Destination taking each element as a {@link Long} — no `bigint` is
+     * materialised at all, which is most of why this is a quarter cheaper than the
+     * per-element path for a 64-bit array (see {@link ArrayTarget}). A real
+     * `Array`, cut to length at the array's end, exactly like {@link values}.
      */
-    maxStringLen?: number;
+    longs?: Long[];
     /**
-     * Reject a blob whose declared byte length exceeds this, before the payload is
-     * accepted or streamed. Omit for no cap.
+     * Allocation-free destination: the element's low half at `lo[index]` and its
+     * high half at `hi[index]` (for a signed array, the two's-complement halves).
+     * Both must be set and both must hold at least `count` elements. The fastest
+     * shape there is — nothing is allocated per element, not even a `Long`.
      */
-    maxBlobLen?: number;
+    /**
+     * Exact-width destination: one typed array whose element width IS the schema's
+     * declared width — a `Uint16Array` for a `u16` array, an `Int8Array` for an
+     * `i8` one. Must hold at least `count` elements.
+     *
+     * **The bound is still compared, and that is not negotiable.** A typed array
+     * *masks* on store (`a[0] = 70000` in a `Uint16Array` is 4464), and
+     * MESSAGE_SPEC §7.1 makes an element outside the declared width INVALID —
+     * neither masked to the width nor kept. So this destination buys the storage,
+     * never the verdict: the fill loop compares exactly as {@link values} does and
+     * refuses the same elements.
+     *
+     * What it does buy is the store (unboxed, and no element-kind transition the
+     * way a `number[]` takes when a value leaves the small-integer range), the
+     * memory (2 bytes for a `u16`, against a tagged slot), and the *encoder's*
+     * side, where the width is then statically known.
+     *
+     * The bound must fit the array's own width: a destination narrower than the
+     * interval could not represent every legal element, and is refused with
+     * {@link SofabErrorCode.Argument} rather than silently masking.
+     */
+    typed?: Uint8Array | Uint16Array | Uint32Array | Int8Array | Int16Array | Int32Array | BigUint64Array | BigInt64Array;
+    lo?: Uint32Array;
+    /** The high halves; see {@link lo}. */
+    hi?: Uint32Array;
+    /** Low half of the smallest element the schema allows. */
+    minLo: number;
+    /** High half of the smallest element the schema allows. */
+    minHi: number;
+    /** Low half of the largest element the schema allows. */
+    maxLo: number;
+    /** High half of the largest element the schema allows. */
+    maxHi: number;
 }
-
 /**
- * The SofaBuffers decoder.
+ * A float array's destination — for an `ArrayKind.Fp32` or `ArrayKind.Fp64`
+ * array. Exactly one of the two must be set, it must match the element width the
+ * array's own `fixlen_word` declared (§4.8), and it must hold at least `count`
+ * elements; anything else is refused with {@link SofabErrorCode.Argument} before
+ * a single element is written.
  *
- * `IStream` is a push parser: feed it bytes with {@link IStream.feed} and it
- * drives a {@link Visitor}, calling one method per decoded field. It is a
- * resumable state machine, so the chunks you feed can be any size — a whole
- * message, a network packet, or a single byte — and a field that straddles a
- * chunk boundary is picked up seamlessly on the next call.
+ * There is no bound here: §4.6 gives a float no schema interval to violate, so
+ * there is nothing to compare and nothing for the caller to state.
  *
- * Nesting is hierarchical: {@link Visitor.sequenceBegin} may return a child
- * visitor, and the decoder routes the nested fields to it until the matching
- * end. Generated message classes use this directly — a class implements
- * `Visitor`, and a nested-message field returns the child instance.
- *
- * There is no finish / finalize step (MESSAGE_SPEC §7): {@link IStream.feed}
- * throws only for a *malformed* message ({@link SofabErrorCode.InvalidMsg}); a
- * message that merely ends inside a field is reported — never thrown — by
- * {@link IStream.end}, which returns {@link DecodeStatus.Incomplete} rather than
- * {@link DecodeStatus.Complete}. The caller owns end-of-input and decides
- * whether a trailing `Incomplete` is a truncation error.
+ * An `fp32` array chooses between the two: {@link f32} takes values, {@link bits}
+ * takes the wire words. The choice is real, not stylistic — reading an `fp32`
+ * through a double quiets a *signaling* NaN (`0x7fa00001` comes back
+ * `0x7fe00001`), so a reader that must reproduce `fp32` payloads bit-for-bit
+ * (§4.6/§6.5) takes {@link bits}. `fp64` needs no such choice: a `Float64Array`
+ * carries all 64 bits, payload NaNs included.
  */
-
+interface FloatArrayTarget {
+    /** Value destination for an `ArrayKind.Fp32` array. */
+    f32?: Float32Array;
+    /**
+     * Bit destination for an `ArrayKind.Fp32` array: each element as its 4 wire
+     * bytes in one little-endian 32-bit word — the same number `OStream.writeFp32Bits`
+     * takes, so a payload read through this and written back reproduces the wire
+     * exactly, signaling NaNs included.
+     */
+    bits?: Uint32Array;
+    /** Destination for an `ArrayKind.Fp64` array. */
+    f64?: Float64Array;
+}
 /**
- * Receives decoded fields from an {@link IStream}. Every method is optional and
- * defaults to a no-op, so a visitor implements only the fields it cares about
- * and silently skips the rest.
+ * Receives decoded fields from an {@link IStream} — the one decode surface
+ * (§5.3.1). Every method is optional and defaults to a no-op, so a visitor
+ * implements only the fields it cares about and silently skips the rest, which is
+ * the `skip` half of the two per-field intents §6.7.2 allows (the other being
+ * `read`: take the value, in the call).
  *
- * String and blob payloads arrive as one or more `chunk`s, each tagged with the
- * field's `total` length and the `offset` of the chunk within the field, so a
- * large payload never has to be held in one piece. Array elements arrive one at
- * a time between {@link Visitor.arrayBegin} and {@link Visitor.arrayEnd}.
+ * **One visitor per message, not per scope.** Nested sequences arrive as
+ * {@link sequenceBegin} / {@link sequenceEnd} events on this same object, each
+ * carrying the sequence's `id` and its `depth` (1 for a sequence opened at the
+ * root). Generated code routes on those two numbers, which it knows statically
+ * from the schema.
+ *
+ * **Nothing handed to a visitor outlives the call.** A `string` / `blob` payload
+ * is reported in pieces as a range of the caller's *own* fed chunk (§6.6.3): the
+ * decoder creates no view over it and holds no storage of its own (§6.6, §6.7),
+ * so a consumer that wants the value copies it out — during the call — into
+ * storage it owns. {@link PayloadAcc} and {@link decodeUtf8} are the ready-made
+ * way to do that.
  */
 interface Visitor {
     /**
-     * An unsigned integer field. Number-first: `value` is a `number` when it fits
-     * exactly (`≤ 2^53-1`, covering ids, u8..u32 and small u64s) and a `bigint`
-     * only beyond that, so the common case avoids a per-value bigint allocation.
+     * A field **header**: its `id` and `wire` type, announced the moment the header
+     * varint is complete — before the value, and before the value's own header word
+     * (a fixlen length word, an array count word, the fields of a nested sequence).
+     *
+     * An observation point for a reader that wants the field stream as it arrives —
+     * which id, in which scope, in which order — without implementing the value
+     * callbacks it would otherwise take to see the same thing.
+     *
+     * **A schema bound does not belong here.** The header settles `id` and `wire`,
+     * and nothing else. An element id past the schema `count` (MESSAGE_SPEC
+     * §7.1/§5.1) looks decidable from the id alone, and it is not: §7.3 applies that
+     * bound only to a field whose *subtype* has confirmed it is the declared one,
+     * and a contradicting subtype is skipped rather than rejected. The subtype
+     * arrives in the fixlen word, so the verdict is due at {@link fixlenBegin}.
+     * CORELIB_PLAN §4.1.1 makes the timing normative: a message ending inside that
+     * word is `INCOMPLETE` even when the id would violate a schema bound, because
+     * the low 3 bits of an unfinished varint must not influence an outcome even
+     * though they are already arithmetically fixed.
+     *
+     * Called exactly once per field, in every scope, for every wire type — the
+     * sequence *end* marker excepted: it closes a scope rather than opening a field
+     * and its id is discarded (§4.9). For a nested sequence it fires before
+     * {@link sequenceBegin}.
+     *
+     * Throwing from it rejects the field — for a verdict the header really does
+     * settle on its own, such as an id this reader will not accept in any shape.
+     */
+    fieldBegin?(id: number, wire: WireType): void;
+    /**
+     * An unsigned integer field.
+     *
+     * `value` is number-first: a `number` when the value fits exactly
+     * (`≤ 2^53-1`, covering ids, u8..u32 and small u64s) and a `bigint` only beyond
+     * that. `lo` / `hi` are the exact 64 bits as two unsigned 32-bit halves — the
+     * ones the varint reader already holds — for a consumer that wants the value
+     * bit-exactly without going through `bigint` arithmetic ({@link Long.fromBits}
+     * builds a `Long` from them). Both describe the same value; use whichever fits.
+     */
+    unsigned?(id: number, value: number | bigint, lo: number, hi: number): void;
+    /**
+     * A signed integer field. `value` is number-first like {@link unsigned}
+     * (`|value| ≤ 2^53-1` ⇒ `number`); `lo` / `hi` are the **decoded**
+     * (zig-zag-undone) two's-complement halves.
+     */
+    signed?(id: number, value: number | bigint, lo: number, hi: number): void;
+    /**
+     * An IEEE-754 32-bit float field.
+     *
+     * `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. `bits` is the exact 4 wire bytes as one little-endian
+     * 32-bit word, which can: re-encode from it with
+     * {@link OStream.writeFp32Bits} and the payload round-trips bit-for-bit
+     * (§4.6/§6.5). It is the "32-bit bits accessor" §6.5 names, and it is always
+     * present — a number costs nothing to pass and needs no opt-in flag, where the
+     * byte view it replaces was an allocation per value and a borrowed slice §6.7
+     * forbids.
      */
-    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. */
+    fp32?(id: number, value: number, bits: number): 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;
-    /** A chunk of a blob field. */
-    blob?(id: number, total: number, offset: number, chunk: Uint8Array): void;
+    /**
+     * Start of a `string`/`blob` field: `total` payload bytes follow, in one or more
+     * {@link string}/{@link blob} calls.
+     *
+     * The counterpart of {@link arrayBegin}, and it exists for the same reason: a
+     * receiver-side bound on the *declared length* is decided by this word, not by
+     * the payload. Without it a visitor could only see `total` once payload bytes
+     * arrive, so a message that ends right after an over-bound length word would
+     * escape the check and degrade to `INCOMPLETE`, where §5.2.3 requires `INVALID`.
+     *
+     * Called exactly once per field, before any payload call — including for a
+     * zero-length payload, which is still announced here and then delivered as one
+     * empty range.
+     */
+    fixlenBegin?(id: number, subtype: FixlenSubtype, total: number): void;
+    /**
+     * A piece of a UTF-8 string field: the bytes `src[start..end)`, at `offset` of
+     * a `total`-byte payload.
+     *
+     * `src` is the **caller's own chunk** — the exact array passed to
+     * {@link IStream.feed} (or to {@link decode}) — handed back with the piece's
+     * coordinates (§6.6.3). The decoder builds no view over it, keeps no storage,
+     * and hands out no borrowed slice of its own (§6.6, §6.7). Once `feed` returns,
+     * the caller may reuse that memory, so a consumer that wants the value copies it
+     * out **during the call**: {@link PayloadAcc} joins pieces into a buffer it
+     * owns, and {@link decodeUtf8} turns a range straight into a string.
+     *
+     * The bytes are **not validated**. §6.4.5 puts the UTF-8 check where a string is
+     * *materialized* — a piece may end mid-code-point, and a skipped field is never
+     * validated at all — so on this surface the caller who materializes owns the
+     * check. {@link decodeUtf8} is it, and a hand-rolled one must be built **fatal**
+     * (`new TextDecoder("utf-8", { fatal: true })`): JavaScript's default
+     * `TextDecoder` substitutes `U+FFFD`, which §6.4 forbids in either direction.
+     */
+    string?(id: number, total: number, offset: number, src: Uint8Array, start: number, end: number): void;
+    /** A piece of a blob field — see {@link string} for the `src`/`start`/`end` contract. */
+    blob?(id: number, total: number, offset: number, src: Uint8Array, start: number, end: number): void;
     /** Start of an array; `count` elements of `kind` follow. */
     arrayBegin?(id: number, kind: ArrayKind, count: number): void;
-    /** One unsigned array element. Number-first like {@link unsigned}. */
-    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. */
-    arrayFp64?(id: number, index: number, value: number): void;
+    /**
+     * Offer of the **bulk hand-off**: return the destination this visitor has
+     * already allocated for array `id` and the decoder fills it directly, one write
+     * per element and no callback at all; return `null` (or leave this method
+     * unimplemented) to be served element by element as before.
+     *
+     * Called once per array, after {@link arrayBegin} and before the first element —
+     * so a receiver cap on `count` is still compared where it always was, in
+     * `arrayBegin`, and a rejected array is never offered. **An array that is empty
+     * on the wire is offered too**, with `count` of 0: there is nothing to write,
+     * but a destination held across fields would otherwise still hold the previous
+     * array's elements, and its length is the only place this array's emptiness
+     * could show.
+     *
+     * `kind` is the element kind and it decides which destination is legal
+     * ({@link IntegerArrayTarget} for `Unsigned` / `Signed`,
+     * {@link FloatArrayTarget} for `Fp32` / `Fp64`); a destination that contradicts
+     * it, or that is shorter than `count`, is a caller mistake and is refused with
+     * {@link SofabErrorCode.Argument} before any element is written. Declining on
+     * a kind this visitor did not expect is always available — and is the right
+     * answer, since `null` costs nothing but the call.
+     *
+     * See {@link ArrayTarget} for what the decoder then guarantees: ascending
+     * writes, the element bound enforced here and only here, the destination held
+     * until `arrayEnd` across as many `feed` calls as the chunking takes, and a
+     * partially filled destination if an element is refused.
+     */
+    arrayBulk?(id: number, kind: ArrayKind, count: number): ArrayTarget | null;
     /** End of an array. */
     arrayEnd?(id: number): void;
     /**
-     * Start of a nested sequence. Return a {@link Visitor} to route the nested
-     * fields to it (its {@link Visitor.sequenceEnd} fires at the matching end);
-     * return nothing to keep using the current visitor.
+     * Start of a nested sequence — a fresh id scope (§4.9) — opened by field `id`
+     * at `depth` (1 at the root).
+     *
+     * Return **`false`** to decline the whole subtree: no callback of any kind fires
+     * inside it, nesting included, its own {@link sequenceEnd} included, and a scope
+     * opened within it is never offered either. Return anything else (or nothing) to
+     * descend, and the nested fields arrive on this same visitor with their own ids
+     * and `depth + 1`.
+     *
+     * A declined subtree is still *parsed* — a sequence is framed by markers, not by
+     * a length, so its end has to be found — but nothing in it is decoded into
+     * existence: no piece is reported and no value is built. No receiver cap fires
+     * inside one either (§6.2.1's "a skipped field is never capped"), and that falls
+     * out of the structure rather than needing a rule: a cap is compared by the
+     * handler this stream would have called, and a declined scope calls none. Format
+     * ceilings (`ARRAY_MAX`, `FIXLEN_MAX`, `MAX_DEPTH`, the varint bound) still apply
+     * everywhere: they bound what the wire may express.
      */
-    sequenceBegin?(id: number): Visitor | void;
-    /** End of the nested sequence this visitor was handling. */
-    sequenceEnd?(): void;
+    sequenceBegin?(id: number, depth: number): boolean | void;
+    /** End of the nested sequence opened by field `id` at `depth`. */
+    sequenceEnd?(id: number, depth: number): void;
 }
 /**
- * Push parser for the SofaBuffers wire format. Feed it bytes in chunks of any
- * size with {@link IStream.feed} and it drives a {@link Visitor}, one call per
- * decoded field, resuming cleanly across chunk boundaries. Call
- * {@link IStream.end} after the final chunk to read whether the message finished
- * on a field boundary. When the whole message is already in one buffer, prefer
- * the faster {@link decode}.
+ * Push parser for the SofaBuffers wire format, and the library's only decode
+ * surface (§5.3.1).
+ *
+ * Bind a {@link Visitor} at construction, then feed bytes in chunks of any size
+ * with {@link feed}: it calls one visitor method per decoded field and resumes
+ * cleanly across chunk boundaries. Every `feed` returns the decode outcome for the
+ * bytes so far, so no end / finalize call is needed — and there is nothing else to
+ * ask: `feed` is the only way to learn where a stream stands, by what it returns
+ * or by what it throws.
+ *
+ * **No receiver limit is configured here, because this codec holds none**
+ * (§6.2.1). A `max_dyn_*` cap is the receiving *application's* number, stated by
+ * generated code, which knows the schema and the target; it is compared inside the
+ * visitor's own `arrayBegin` / `fixlenBegin` — raised by this stream at the count
+ * or length header, before any payload is delivered and only for a field the
+ * visitor reads — and, for a wrapper array's `string` / `blob` elements, inside
+ * the `StringSeq` / `BlobSeq` collector those bounds were passed to.
+ * This class used to take a `DecodeLimits` and default every absent cap to the
+ * format ceiling, which §6.2.1 forbids twice over: a codec must not supply a
+ * default for a limit it was not given, and a format ceiling reached because no
+ * cap was stated is the format's bound and must not be presented as a receiver
+ * cap.
+ *
+ * Constructing one is the only allocating step (§6.6): `feed` itself allocates
+ * nothing at all. The one-shot {@link decode} is exactly this class fed once.
  */
 declare class IStream {
     private readonly state;
     /**
-     * @param limits Optional opt-in decode caps ({@link DecodeLimits}). An
-     * over-limit array count or string / blob length throws {@link SofabError}
-     * (`LIMIT_EXCEEDED`) from {@link feed}, at the offending field's header and
-     * before any of its payload is streamed to the visitor. Omit for no caps.
-     */
-    constructor(limits?: DecodeLimits);
-    /**
-     * Feed a chunk of bytes, dispatching decoded fields to `visitor`. Throws
-     * {@link SofabError} (`INVALID_MSG`) only if the bytes are *malformed*;
-     * running out of bytes mid-field is not an error — it simply suspends until
-     * the next chunk (see {@link end}).
+     * @param visitor The field handler this stream drives, for its whole life — and
+     * the layer that holds the receiver caps, if any (§6.2.1; see the class doc).
      */
-    feed(chunk: Uint8Array, visitor: Visitor): void;
+    constructor(visitor: Visitor);
     /**
-     * Report whether the stream ended exactly at a field boundary. Call after the
-     * final {@link feed}: returns {@link DecodeStatus.Complete} at a clean field
-     * boundary, or {@link DecodeStatus.Incomplete} if the last chunk ended inside
-     * a field (a partial varint, an unfinished payload / array, or a still-open
-     * nested sequence).
+     * Feed a chunk of bytes, dispatching decoded fields to the bound visitor, and
+     * **return** where the decode stands after them (§5.2.1):
+     * {@link DecodeStatus.Complete} when they end exactly at a field boundary,
+     * {@link DecodeStatus.Incomplete} when they end *inside* a field (a partial
+     * varint, an unfinished payload / array, or a still-open nested sequence).
+     * Running out of bytes mid-field is not an error — the decode merely suspends
+     * until the next chunk, and the caller owns end-of-input.
+     *
+     * **This call is the only place the answer is.** There is no finish / finalize
+     * step (§5.2.4) and no status accessor: what this returns, or throws, is the
+     * whole of what the stream has to say, so a caller is never one question short
+     * after it and never has two answers to reconcile. Feeding an empty chunk
+     * re-reads the same value without consuming anything, for a caller that wants
+     * the outcome again without holding on to it.
+     *
+     * The chunk is borrowed **only for the duration of this call** (§6.0): once it
+     * returns, the caller may reuse, overwrite or free that memory, and the decoded
+     * message is unaffected — the decoder retains nothing that points into it.
+     *
+     * `INVALID` travels on the error channel — this port's idiomatic surfacing of
+     * it: *malformed* bytes throw {@link SofabError} (`INVALID_MSG`) instead of
+     * returning a status, which is why the return type names only the other two.
+     * That verdict is **terminal** (§5.2.1): the stream latches it, so a caller that
+     * catches the throw and feeds on gets the same error again from every later
+     * call — no further byte is consumed and no visitor method is invoked. A caller
+     * that caught it already holds the verdict, in the code on the error it caught.
      *
-     * Per the finish-less spec (MESSAGE_SPEC §7) this is a pure accessor: it never
-     * throws and never promotes an incomplete decode to an error — the caller owns
-     * end-of-input and decides whether a trailing `Incomplete` is a truncation
-     * error. (A *malformed* message has already thrown from {@link feed}.)
+     * A receiver-limit rejection (`LIMIT_EXCEEDED`, §6.2.1) travels the same
+     * channel — thrown out of the visitor callback that compared the cap — but it
+     * is **not** the `INVALID` outcome and never becomes one: the bytes are
+     * well-formed and the same message decodes under a looser cap, so it is a
+     * policy rejection (§6.2.1, §6.3). The two stay distinguishable by their code,
+     * which is what §6.3 requires; §6.3 leaves the surfacing open between "a fourth
+     * decode outcome" and "a terminal failure carrying the `LimitExceeded` code on
+     * the error channel", and this port takes the second. **Terminal** is the other
+     * half of that sentence and holds exactly as it does for `INVALID`: the stream
+     * latches the rejection, so every later call re-throws it under the same code,
+     * consumes no byte and drives no visitor method. It is *only* on the error
+     * channel — the three-valued outcome has no value for "valid, but more than I am
+     * configured to accept", so there is nothing about it to read back as a status,
+     * and nothing that has to be kept in step with the throw.
      */
-    end(): DecodeStatus;
+    feed(chunk: Uint8Array): FeedStatus;
 }
 /**
  * Decode a complete message held in one contiguous buffer, in a single call.
  *
- * This is the non-streaming convenience — and the fast path: with the whole
- * message in hand it advances one cursor over the buffer instead of running the
- * resumable per-byte state machine, so it is markedly faster than feeding the
- * same bytes through
- * {@link IStream}. Use {@link IStream} when the message arrives in chunks; use
- * this when you already have it whole.
+ * The non-streaming convenience, and **not** a second decoder: it is one
+ * {@link IStream.feed} of the whole buffer, so it runs the same code, applies the
+ * same rules and has the same memory behaviour as a chunked decode — §6.7.1
+ * forbids the one-shot path from differing, right down to holding no view into
+ * the buffer it was handed. Feeding a whole message is also the case the decoder's
+ * fast lane is built for, so nothing is given up by having one implementation.
  *
- * The whole buffer *is* the end of input, so the two failure outcomes both
- * throw a {@link SofabError} the caller tells apart by `code` (MESSAGE_SPEC §7):
- * malformed input throws `INVALID_MSG`, while input that ends inside a field —
- * truncation or an unclosed sequence — throws `INCOMPLETE`. A complete message
- * returns normally.
+ * The whole buffer *is* the end of input, so the two failure outcomes both throw a
+ * {@link SofabError} the caller tells apart by `code` (MESSAGE_SPEC §7): malformed
+ * input throws `INVALID_MSG`, while input that ends inside a field — truncation or
+ * an unclosed sequence — throws `INCOMPLETE`. A complete message returns normally.
  *
- * Pass `limits` ({@link DecodeLimits}) to cap array counts and string / blob
- * lengths; an over-limit field throws `LIMIT_EXCEEDED` at its header, before it
- * is materialized. Omit for no caps (the default).
+ * The receiver caps of §6.2.1 are the `visitor`'s, not this function's: it takes
+ * no limits argument because this codec holds none. See {@link IStream}.
  */
-declare function decode(bytes: Uint8Array, visitor: Visitor, limits?: DecodeLimits): void;
+declare function decode(bytes: Uint8Array, visitor: Visitor): void;
 
 /**
- * The pull / cursor decoder: a monomorphic companion to {@link "./fast"}.
- *
- * {@link "./fast"}'s {@link decodeContiguous} is a *push* decoder — it drives the
- * buffer and calls a {@link Visitor} method per field. That is the right shape
- * for streaming and skip-subtree callers, but the visitor call sites go
- * megamorphic once a single decode routes through several differently-shaped
- * visitor objects (one per nested message type), which a JIT cannot inline.
- *
- * {@link Cursor} inverts control: it keeps one read cursor over the contiguous
- * {@link Uint8Array} and exposes *pull* primitives — {@link Cursor.readHeader}
- * plus a typed `read*` per wire type — so **generated code drives the loop** with
- * a single `switch (cursor.id)` that reads straight into its own fields. Every
- * call site is then monomorphic (the generated per-type decoder is the only
- * caller), which is what lets V8 inline the whole decode into a flat loop — the
- * same technique protobuf's generated `decode(reader)` uses.
- *
- * It shares {@link "./fast"}'s number-first varint core verbatim: each varint is
- * accumulated into two 32-bit JS *numbers* (`lo`/`hi`) and a `bigint` is
- * materialised only for a 64-bit *value* that does not fit in `2^53-1` (never for
- * ids, lengths or counts). String / blob payloads are returned as a single
- * zero-copy `subarray` view. It reports the same three-valued outcome as the
- * push path (MESSAGE_SPEC §7): malformed input throws a {@link SofabError} with
- * code `INVALID_MSG`, and a read that runs off the end of the buffer mid-field
- * throws `INCOMPLETE`.
+ * Decode-side text helper — the read-path twin of {@link "../encode/fixlen"}.
+ *
+ * Two things make a short string expensive to decode, and this avoids both.
+ *
+ * `TextDecoder.decode` needs a `Uint8Array` covering exactly the payload, so the
+ * decoder has to build a `subarray` per string; on Node 24 that view alone costs
+ * about a third of the whole read (~500 Ir/op for a 13-byte field). And the
+ * decode itself is a WHATWG entry point whose per-call setup dwarfs the payload
+ * at these sizes.
+ *
+ * The obvious fix — walk the bytes in JS and append with `+=`, the way
+ * protobufjs does — trades one problem for another: the repeated concatenation
+ * builds a **rope**, and the rope is flattened later, by the first consumer that
+ * walks it. In a decode-then-encode round trip that consumer is the encoder's own
+ * `utf8Length` / `utf8Write` pass, so the cost does not disappear, it moves out
+ * of the decode where it is easy to miss. Measured on a 13-byte ASCII field
+ * (decode plus one charCodeAt walk): TextDecoder 2006 Ir/op, rope 2095 — the
+ * rope form looks 40 percent cheaper if only the decode is measured, and is
+ * *worse* once the string is used.
+ *
+ * So an all-ASCII payload short enough to name its length is built with a
+ * SINGLE `String.fromCharCode` call, which returns a flat string with no rope to
+ * pay for afterwards: 858 Ir/op on the same measurement, less than half of
+ * either alternative. Everything else — non-ASCII, or longer than
+ * {@link FLAT_MAX} — goes to the fatal {@link TextDecoder} exactly as before.
+ *
+ * This stays **strict** (MESSAGE_SPEC section 8): the fast path is gated on every
+ * byte being below 0x80, and each such byte is a well-formed single-byte UTF-8
+ * sequence, so an all-ASCII run has nothing to reject. Any payload with a high
+ * bit set is handed to the platform decoder whole and gets exactly the
+ * validation it always got — the fast path can never accept bytes the platform
+ * would refuse.
+ *
+ * {@link decodeUtf8} is **public** because the code that needs it is not in this
+ * library. The decoder reports raw, unvalidated payload pieces (§6.4.5 puts the
+ * UTF-8 check where a string is *materialized*, and a piece may end mid-code-point),
+ * so materialization — and therefore the check — belongs to whoever wants the
+ * value. Generated code is that whoever, and without an exported entry point every
+ * generated package builds a plain fatal `TextDecoder` of its own and pays the full
+ * 2006 Ir/op per short string instead of 858.
+ *
+ * It is **static helper layer**, not codec (§6.6.1): it allocates the string it
+ * returns, and no codec path calls it.
+ */
+/**
+ * Decode `buf[start..end)` as strict UTF-8 — the whole of `buf` when the range
+ * is omitted, which is the shape a reassembled payload (see {@link PayloadAcc})
+ * arrives in.
+ *
+ * Malformed bytes throw a {@link SofabError} (`INVALID_MSG`), never the fatal
+ * {@link TextDecoder}'s bare `TypeError`. The mapping belongs here rather than at
+ * each call site: invalid UTF-8 is an invalid *message* (MESSAGE_SPEC §8,
+ * CORELIB_PLAN §6.4), so it has to reach a caller as the same `INVALID` verdict
+ * as every other malformation — through the one `catch (e) { if (e instanceof
+ * SofabError) … }` a consumer writes — and a platform exception escaping that
+ * clause is precisely the bug this closes.
+ *
+ * A zero-length payload is the empty string, decoded without touching the
+ * platform decoder.
  */
+declare function decodeUtf8(buf: Uint8Array, start?: number, end?: number): string;
 
 /**
- * A pull decoder over a complete message held in one contiguous buffer.
- *
- * Usage from generated code: loop on {@link readHeader}; for each field switch on
- * {@link id} and call the matching `read*` (which consumes that field's value and
- * advances the cursor); recurse into a child type's decoder on a nested sequence;
- * fall through to {@link skip} for an unknown id. See {@link readHeader}.
- *
- * Pass {@link DecodeLimits} to cap array counts and string / blob lengths; an
- * over-limit field throws {@link SofabError} (`LIMIT_EXCEEDED`) at its header,
- * before it is materialized. Omit for no caps (the default).
- */
-declare class Cursor {
-    /** Field id of the header last accepted by {@link readHeader}. */
-    id: number;
-    /** Wire type of the header last accepted by {@link readHeader}. */
-    wire: number;
-    /**
-     * Fixlen subtype of the header last accepted by {@link readHeader} — one of
-     * {@link FixlenSubtype} — when its {@link wire} is {@link WireType.Fixlen} or
-     * {@link WireType.ArrayFixlen}; `-1` otherwise (a non-fixlen field, or a
-     * fixlen field whose subtype word is truncated away).
-     *
-     * The four fixlen subtypes (`fp32`, `fp64`, `string`, `blob`) all share one
-     * {@link wire} type, so {@link wire} alone cannot separate them. This is the
-     * companion accessor that can: a generated guard reads it right after
-     * {@link readHeader} to skip a field whose delivered subtype contradicts the
-     * schema (MESSAGE_SPEC §7.3), exactly as it already does on {@link wire} for
-     * the other kinds:
-     *
-     * ```ts
-     * case 9: if (c.wire !== WireType.Fixlen || c.fixSub !== FixlenSubtype.Fp64) {
-     *   c.skip(c.wire); break;
-     * } o.somefp64 = c.readFp64(); break;
-     * ```
-     *
-     * It is *peeked* — the subtype word is not consumed — so the matching typed
-     * reader (or {@link skip}) still reads and validates it, and a malformed or
-     * truncated word surfaces `INVALID` / `INCOMPLETE` there as before.
-     */
-    fixSub: number;
-    private readonly buf;
-    private readonly view;
-    private readonly n;
-    private p;
-    private readonly maxArrayCount;
-    private readonly maxStringLen;
-    private readonly maxBlobLen;
-    private lo;
-    private hi;
-    private depth;
-    constructor(buf: Uint8Array, limits?: DecodeLimits);
-    /**
-     * Advance to the next field header. Returns `true` and sets {@link id} /
-     * {@link wire} when a field follows; returns `false` — consuming the marker —
-     * at the end of the buffer *or* at the sequence-end that closes the sequence
-     * this decoder is reading. So a generated per-type decoder loops uniformly:
-     *
-     * ```ts
-     * while (c.readHeader()) {
-     *   switch (c.id) {
-     *     case 4: this.u32 = Number(c.readUnsigned()); break;
-     *     case 10: this.child = Child.decodeFrom(c); break; // nested sequence
-     *     default: c.skip(c.wire); break;                   // unknown field
-     *   }
-     * }
-     * ```
-     *
-     * At the root the loop ends at end-of-buffer; inside a nested sequence it ends
-     * at the matching {@link WireType.SequenceEnd} (which is consumed). A field
-     * whose id is out of range throws {@link SofabError} (`INVALID_MSG`).
-     */
-    readHeader(): boolean;
-    /** Read an unsigned scalar (wire {@link WireType.Unsigned}), number-first. */
-    readUnsigned(): number | bigint;
-    /** Read a signed scalar (wire {@link WireType.Signed}), zig-zag, number-first. */
-    readSigned(): number | bigint;
-    /** Read a 32-bit float scalar (wire {@link WireType.Fixlen}, subtype fp32). */
-    readFp32(): number;
-    /** 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 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)[];
-    /** Read a signed array (wire {@link WireType.ArraySigned}), zig-zag, number-first per element. */
-    readSignedArray(): (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[];
-    /** Read a signed 64-bit array (zig-zag) into {@link Long}[] — the `bigint`-free path. */
-    readSignedArrayLong(): Long[];
-    /** Read an fp32 array (wire {@link WireType.ArrayFixlen}, element subtype fp32). */
-    readFp32Array(): number[];
-    /** Read an fp64 array (wire {@link WireType.ArrayFixlen}, element subtype fp64). */
-    readFp64Array(): 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
-     * unknown id. Pass {@link wire}. A {@link WireType.SequenceStart} skips the
-     * whole nested sequence.
-     */
-    skip(wire: number): void;
-    private skipValue;
-    private skipSequence;
-    /**
-     * Peek the delivered fixlen subtype of the field {@link readHeader} just
-     * accepted, **without advancing the cursor** — the readers / {@link skip}
-     * still re-read and validate the word. Returns one of {@link FixlenSubtype}
-     * (0..3), a reserved value (4..7), or `-1` when the wire is not a fixlen kind
-     * or the subtype word is truncated away.
-     *
-     * The subtype is the low 3 bits of the fixlen sub-header word, and the low
-     * bits of a LEB128 word live entirely in its **first** byte — so this only
-     * reads one byte, it never decodes a varint.
-     */
-    private peekFixSub;
-    /** Read and validate an array count word (0..ARRAY_MAX; §4.7/§4.8). */
-    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. */
-    private fixlenLen;
-    /** Read an array fixlen element header (count + element type); returns the count. */
-    private arrayFixlenHeader;
-    /** Hand back a zero-copy view of the next `len` bytes, advancing the cursor. */
-    private take;
-    private rawFp32;
-    private rawFp64;
-    /**
-     * The last varint's full value as a `bigint` (64-bit fidelity). Only ever
-     * called from {@link unsignedValue} / {@link signedValue} on the `hi` overflow
-     * path (`this.hi >>> 0 > 0x1fffff`), so `hi` is always non-zero here.
-     */
-    private big;
-    /**
-     * The last varint as an unsigned value, number-first: a `number` when it fits
-     * exactly (`≤ 2^53-1`), a `bigint` only beyond that.
-     */
-    private unsignedValue;
-    /** The last zig-zag varint as a signed value, number-first. */
-    private signedValue;
-    /** The last varint's value as a JS number — exact for ids/lengths/counts. */
-    private num;
-    /** The last varint with its low 3 tag bits stripped (`value >> 3`). */
-    private upper;
-    /**
-     * Decode one LEB128 varint at the cursor into {@link lo} / {@link hi} (each an
-     * unsigned 32-bit half), advancing {@link p}. Throws on truncation or a value
-     * spilling past 64 bits (>10 bytes). Unrolled, number-only — no `bigint`.
-     */
-    private readVarint;
-    private set;
+ * Generated-layer support: reassembling a `string` / `blob` payload that the
+ * decoder reported in pieces.
+ *
+ * This is the **static helper layer** of CORELIB_PLAN §6.6.1, not part of the
+ * codec: it allocates, on the generated layer's behalf, and the codec never calls
+ * into it — the call graph runs generated code → helper → codec, never the other
+ * way round. §6.6 binds the codec; this side of the boundary is where a value gets
+ * built.
+ *
+ * {@link IStream} reports a payload to {@link Visitor.string} /
+ * {@link Visitor.blob} as one or more pieces, each a range of the caller's own fed
+ * chunk tagged with the field's `total` byte length and the `offset` of the piece
+ * within it. That memory is borrowed only for the duration of the call (§6.0), so
+ * a consumer that wants the *value* has to copy out — and generated code always
+ * wants the value: a schema field is a `string`, not a sequence of pieces.
+ *
+ * That join has the same shape for every schema — it is decided entirely by
+ * `total` and `offset`, both runtime values — so it lives here rather than in
+ * every generated package (ARCHITECTURE §8). It is also the piece that is easiest
+ * to get subtly wrong and hardest to catch: two implementations can disagree about
+ * where a payload was split and still produce byte-identical output on every
+ * shared vector, because the split is a property of how the caller fed the bytes,
+ * not of the bytes. {@link PayloadAcc} is pinned instead by a unit test that
+ * splits one payload at *every* offset and requires one answer.
+ */
+/**
+ * Joins a `string` / `blob` payload that arrived across several fed pieces.
+ *
+ * **One per decoder, shared by every field.** Exactly one payload is in flight at
+ * a time across a whole decode, however deep the nesting — a fixlen payload is
+ * atomic on the wire, so nothing can begin inside it — so one accumulator is
+ * enough.
+ *
+ * **What it returns is owned by the caller** and aliases nothing: the bytes are
+ * copied into storage this accumulator allocated, on the whole-payload path
+ * exactly as on the split one (§6.7 — "there is no mode in which the destination
+ * aliases the input"). A consumer may keep the result, and a payload that arrived
+ * whole is not a special case with a different lifetime.
+ *
+ * Sizing follows the declared `total`, so a hostile length word is bounded by
+ * whatever bound the caller already applied to it — the schema `maxlen` its
+ * generated guard checks, or the receiver caps of §6.2.1, both of which
+ * are enforced at the length word before a piece is ever delivered. This class
+ * enforces neither: it is handed a payload the caller has already accepted.
+ */
+declare class PayloadAcc {
+    private buf;
+    private len;
+    /**
+     * Contribute one piece — the bytes `src[start..end)` at `offset` of a
+     * `total`-byte payload — and return the **whole** payload once it is complete,
+     * or `null` while bytes are still outstanding.
+     *
+     * `offset === 0` starts a payload — and *resets* the accumulator, so a decode
+     * that was abandoned mid-payload (an `INVALID` field, a declined subtree) leaves
+     * nothing behind to corrupt the next one.
+     *
+     * A late piece with no payload in progress returns `null` rather than writing
+     * anywhere: the accumulator has no buffer to append to, and inventing one would
+     * fabricate a payload out of a fragment.
+     */
+    take(total: number, offset: number, src: Uint8Array, start: number, end: number): Uint8Array | null;
+}
+
+/**
+ * Generated-layer support: the element collectors for a **wrapper-sequence array**
+ * (MESSAGE_SPEC §5.1) — {@link ElementSeq} and {@link FramedSeq} for the index
+ * rules of any element kind, {@link StringSeq} / {@link BlobSeq} for the two leaf
+ * kinds whose payload arrives here as well.
+ *
+ * Static helper layer, not codec (CORELIB_PLAN §6.6.1): these allocate — that is
+ * their job — and no codec path reaches them. Generated code drives them from
+ * inside its own flat {@link Visitor}, which is what knows, from the schema, that
+ * the scope it is currently in *is* the wrapper array.
+ *
+ * A wrapper array is an ordinary sequence whose child fields *are* the elements,
+ * and whose field id *is* the array index. So a collector is fed the two events a
+ * `string` / `blob` element produces — {@link StringSeq.begin} at the length word
+ * and {@link StringSeq.element} per payload piece — and places each value at
+ * `out[id]`.
+ *
+ * Every part of that is schema-independent. Both bounds on the index (the schema
+ * `count`, the receiver cap) and both on the element's byte length (the element
+ * `maxlen`, the receiver cap) arrive as constructor arguments — runtime values —
+ * and the field name is carried along only so a rejection can say which field it
+ * was about. So the collectors belong here rather than being re-emitted, textually
+ * identical, into every generated package (ARCHITECTURE §8).
+ *
+ * Four rules are implemented here and are worth stating once, since nothing in the
+ * shared vectors can distinguish an implementation that gets them wrong from one
+ * that does not — they are properties of the *decoded value*, not of the bytes
+ * (which is exactly why CORELIB_PLAN §7.2 item 8 asks for them separately):
+ *
+ * - **Gaps are legal.** An interior element equal to its default is not written at
+ *   all, so ids `0, 2, 3` are well-formed. The missing index is filled with the
+ *   element default, never skipped over: everything after a gap keeps its index.
+ * - **Length is highest present id + 1.** The wrapper carries no length, and the
+ *   last element is never elided, so growing to `id + 1` on each element is
+ *   exactly right and no trailing fill is ever needed.
+ * - **A repeated element id replaces.** Last occurrence wins per id (§7.4);
+ *   placing at `out[id]` does that by construction, with no bookkeeping.
+ * - **A rejected id extends nothing.** Every bound is checked before the
+ *   destination grows, so a rejection leaves the array exactly as it was and a
+ *   lower id delivered afterwards still lands correctly.
+ *
+ * **Two bounds, never both** (§6.2.1). Index and element length each carry a
+ * schema bound and a receiver cap, and exactly one of the pair applies: where the
+ * schema declared a bound its violation is `INVALID` — a statement about validity
+ * — and where it declared none the receiver's cap governs and its violation is
+ * `LIMIT_EXCEEDED`, a policy rejection on well-formed bytes. "They **MUST NOT** be
+ * applied to a field the schema already bounds", so the caps are exclusive with
+ * the bounds and never additive.
+ *
+ * **Every bound is a required argument, and none of them has a default** (§6.2.1).
+ * The comparison runs here; the *number* never originates here. A corelib "**MUST
+ * NOT** hold a limit of its own, **MUST NOT** supply a default for one it was not
+ * given, **MUST NOT** read an omitted argument as *unlimited*, and **MUST NOT**
+ * clamp to one", and a format ceiling (§6.2) reached because no cap was stated "is
+ * the **format's** bound, not a receiver cap, and a port **MUST NOT** present it as
+ * one". These constructors used to default `receiverCap` to `ARRAY_MAX` and
+ * `receiverElemMax` to `FIXLEN_MAX`, which did exactly that: they reported
+ * `LIMIT_EXCEEDED` against a ceiling nobody configured. The defaults are gone and
+ * the arguments are required — §6.2.1's "strictest form, and the recommended one".
+ * The *schema* bounds beside them (`cap`, `elemMax`) are required too, with
+ * {@link UNBOUNDED} as the explicit "the schema declared none" spelling: an absent
+ * schema bound is a fact about the schema, which only the caller knows.
+ *
+ * **And an argument that states no cap is a caller mistake, not a policy
+ * rejection.** A required argument can still arrive as `-1`, `undefined` or
+ * `Infinity` from an untyped caller, and the same reasoning applies one level in:
+ * no receiver policy was set, so there is no `LIMIT_EXCEEDED` to report and no
+ * unlimited mode to fall back to. Such a bound is refused at construction with
+ * `Argument` (§6.3's third row: "every remaining caller mistake is
+ * `InvalidArgument`") — see {@link requireReceiverBound}.
+ */
+
+/**
+ * No *schema* bound — what `cap` / `elemMax` take for an array or element the
+ * schema left open (§7.2), so the receiver cap beside them governs instead.
+ *
+ * Exported because the schema bounds are required arguments with no default: an
+ * absent one is a fact about the **schema**, which only generated code knows, and
+ * §6.2.1's ban on a codec defaulting a bound is easiest to keep honest when every
+ * bound has to be spelled. This is the spelling for "there is none".
+ */
+declare const UNBOUNDED = -1;
+/**
+ * The slots of a wrapper-sequence array: the index rules of MESSAGE_SPEC §5.1 and
+ * the two bounds of CORELIB_PLAN §6.2.1, once, for any element type.
+ *
+ * {@link StringSeq} and {@link BlobSeq} place leaf elements through it, and
+ * generated code places a **framed** element — a `struct` / `union` / nested row —
+ * through it directly: {@link reserve} at the element's `sequenceBegin`, then build
+ * the child into `out[id]`. The element kind changes which path arrives here and
+ * nothing else, which is the point — the bound is the index (§7.2 item 8).
+ *
+ * @param out The destination array; grown to `id + 1` as elements arrive.
+ * @param def The element default, written into a gap and into a reserved slot.
+ * @param cap The schema `count` as an index capacity: `id >= cap` is `INVALID`
+ * (§7.1) — a statement about validity. Pass {@link UNBOUNDED} (`-1`) for an array
+ * the schema left open, where `receiverCap` governs instead.
+ * @param name The schema field name, used only in a rejection message.
+ * @param receiverCap The receiver-side index cap for a schema-unbounded array
+ * (§6.2.1): `id >= receiverCap` is `LIMIT_EXCEEDED`, a policy rejection. There is
+ * no unlimited setting — a wrapper array announces no count, so the index is the
+ * only place a receiver can bound it. **Required, with no default**: the number is
+ * generated code's, and falling back to `ARRAY_MAX` would report a policy
+ * rejection against a format ceiling nobody configured (§6.2.1). A value that
+ * states no cap at all — negative, `NaN`, `Infinity` — is `Argument` at
+ * construction, never `LIMIT_EXCEEDED` ({@link requireReceiverBound}).
+ */
+declare class ElementSeq<T> {
+    readonly out: T[];
+    readonly def: T;
+    readonly cap: number;
+    readonly name: string;
+    readonly receiverCap: number;
+    /**
+     * The one index bound in force, picked once by `indexBound`: the schema
+     * `count` where the schema stated one, the receiver cap where it did not. Which
+     * of the two it is decides the verdict, which is `rejectIndex`'s job.
+     */
+    private readonly bound;
+    constructor(out: T[], def: T, cap: number, name: string, receiverCap: number);
+    /**
+     * Bound-check `id` and grow `out` to `id + 1`, filling any gap — and the slot
+     * itself — with the element default.
+     *
+     * The check runs **before** the growth, which is the whole of §7.2 item 8's
+     * "after a rejected id the container is not left partially extended": a
+     * rejection leaves `out` exactly as it was, so a lower id delivered afterwards
+     * still lands at its own index.
+     */
+    reserve(id: number): void;
+    /**
+     * The two index bounds, without growing: the schema `count` as validity
+     * (`INVALID`) or, where the schema left the array open, the receiver cap as
+     * capacity (`LIMIT_EXCEEDED`). Never both — §6.2.1 keeps a cap off a field the
+     * schema already bounds, which is why one `bound` can stand for both.
+     *
+     * Split out from {@link reserve} because a leaf element is bound-checked at its
+     * length word, before its payload has arrived and so before there is anything to
+     * place ({@link StringSeq.begin}).
+     */
+    checkIndex(id: number): void;
+    /**
+     * What {@link reserve} does, then `value` written into the slot. A repeat
+     * replaces (§7.4).
+     *
+     * Written out rather than delegating to {@link reserve}: on the baseline tier a
+     * call is not free, and this is the per-element path. The check still precedes
+     * the growth, which is the property §7.2 item 8 asks for.
+     */
+    place(id: number, value: T): void;
+}
+/**
+ * The slots of a wrapper-sequence array whose element default is a **fresh
+ * object**: a framed element (`struct` / `union`) or a nested row.
+ *
+ * {@link ElementSeq}'s twin, and it differs in exactly one thing — the gap value
+ * comes from a **factory** instead of being shared. That single axis is why it is
+ * a second class rather than a second argument: a framed element's default is
+ * `new Elem()` and a row's is `[]`, both mutable and both reachable by the
+ * caller, so one shared instance would alias every gap of the array onto it and —
+ * since an arriving element decodes into the slot the reservation placed — would
+ * alias every *element* onto it too, which is not a near miss but a flatly wrong
+ * decode. {@link ElementSeq}'s `""` and zero-length `Uint8Array` have no state to
+ * share, which is what makes sharing right there and wrong here.
+ *
+ * Everything else is {@link ElementSeq}, deliberately: the same argument order
+ * with `make` in `def`'s slot, the same two exclusive index bounds through the
+ * same `indexBound` / `rejectIndex` pair, the same growth geometry, the same
+ * construction-time refusal of a receiver cap that states no cap.
+ *
+ * Generated code calls {@link reserve} at the element's own `sequenceBegin` and
+ * then keeps routing the child's fields into `out[id]` itself. This class owns
+ * the bound and the growth; it never owns the routing, which is the part that has
+ * a different shape for every schema (ARCHITECTURE §8).
+ *
+ * @param out The destination array; grown to `id + 1` as elements arrive.
+ * @param make Builds one element default. Called once per gap slot, and once for
+ * the reserved slot itself in {@link reserve} — never for a slot already present,
+ * so a re-opened element keeps the object earlier fields decoded into.
+ * @param cap The schema `count` as an index capacity: `id >= cap` is `INVALID`
+ * (§7.1) — a statement about validity. Pass {@link UNBOUNDED} (`-1`) for an array
+ * the schema left open, where `receiverCap` governs instead.
+ * @param name The schema field name, used only in a rejection message.
+ * @param receiverCap The receiver-side index cap for a schema-unbounded array
+ * (§6.2.1): `id >= receiverCap` is `LIMIT_EXCEEDED`, a policy rejection, never
+ * `INVALID`, and never applied beside a `cap` the schema stated. **Required, with
+ * no default**; a value that states no cap at all is `Argument` at construction
+ * ({@link requireReceiverBound}).
+ */
+declare class FramedSeq<T> {
+    readonly out: T[];
+    readonly make: () => T;
+    readonly cap: number;
+    readonly name: string;
+    readonly receiverCap: number;
+    /** The one index bound in force, picked once by `indexBound` — see {@link ElementSeq}. */
+    private readonly bound;
+    constructor(out: T[], make: () => T, cap: number, name: string, receiverCap: number);
+    /**
+     * The two index bounds, without growing — see {@link ElementSeq.checkIndex}.
+     *
+     * Split out for the same reason it is there: a caller may have a second bound
+     * to take before anything is allocated. A native matrix row is that case in this
+     * port — its element `count` is rejected at the array header, and §7.2 item 8
+     * wants that rejection to leave the row container exactly as it was.
+     */
+    checkIndex(id: number): void;
+    /**
+     * Bound-check `id`, **then** grow `out` to `id + 1`, each new slot its own
+     * `make()`.
+     *
+     * The order is §7.2 item 8's "after a rejected id the container is not left
+     * partially extended": a rejection leaves `out` exactly as it was, so a lower id
+     * delivered afterwards still lands at its own index. A slot already present is
+     * left alone — a re-opened `struct` / `union` element merges into the object it
+     * already built, which is what §7.4's last-occurrence-wins means for a scope
+     * whose value *is* the scope.
+     */
+    reserve(id: number): void;
+    /**
+     * Bound-check `id`, fill the gap below it, then write `value` into the slot —
+     * what a nested **row** needs, an array wrapper *replacing* whatever an earlier
+     * opening built at that index (§7.4) rather than merging into it.
+     *
+     * The gap fill stops one short of `id` on purpose: the slot is about to be
+     * overwritten, so calling `make()` for it would allocate an element default
+     * nobody ever reads. Assigning at `out.length` extends the array by exactly one,
+     * which is the same array a {@link reserve} would have left.
+     */
+    place(id: number, value: T): void;
 }
+/**
+ * Collects the elements of a `string` wrapper-sequence array into `out`.
+ *
+ * @param out The destination, placed at `out[id]`; grown as elements arrive, with
+ * gaps filled by the element default `""`.
+ * @param acc The decoder's shared {@link PayloadAcc} — one per decode, since only
+ * one payload is ever in flight.
+ * @param cap The schema `count`, an index **capacity**: an element id at or above
+ * it is `INVALID` (§7.1/§5.1) — a statement about validity. Pass
+ * {@link UNBOUNDED} (`-1`) for an array the schema left unbounded, where
+ * `receiverCap` governs instead.
+ * @param elemMax The element `maxlen` in bytes, or {@link UNBOUNDED} (`-1`) for an
+ * element the schema left open, where `receiverElemMax` governs instead.
+ * @param name The schema field name, used only in the rejection message.
+ * @param receiverCap The receiver-side index cap that applies **only** when the
+ * schema left the array unbounded (§6.2.1): exceeding it is `LIMIT_EXCEEDED`, a
+ * policy rejection, not `INVALID`. There is no unlimited setting — a wrapper array
+ * announces no count, so the index is the only place a receiver can bound it.
+ * **Required, with no default** (§6.2.1).
+ * @param receiverElemMax The receiver-side `max_dyn_string_len` for an element the
+ * schema left unbounded (§6.2.1), checked at the length word and answered with
+ * `LIMIT_EXCEEDED`. A wrapper array's `string` elements never reach the generated
+ * visitor — their length words come here — so this is where that cap belongs, and
+ * it is why the decoder needs no module-wide limit object at all. **Required, with
+ * no default**: `FIXLEN_MAX` is the format's bound, not a receiver cap, and §6.2.1
+ * forbids presenting it as one.
+ */
+declare class StringSeq {
+    readonly out: string[];
+    readonly acc: PayloadAcc;
+    readonly cap: number;
+    readonly elemMax: number;
+    readonly name: string;
+    readonly receiverCap: number;
+    readonly receiverElemMax: number;
+    /** The index rules and both index bounds, shared with every other element kind. */
+    private readonly slots;
+    constructor(out: string[], acc: PayloadAcc, cap: number, elemMax: number, name: string, receiverCap: number, receiverElemMax: number);
+    /**
+     * The element's fixlen length word ({@link Visitor.fixlenBegin}).
+     *
+     * The bounds are decided by this word, so they are checked here — before any
+     * payload byte — and again in {@link element} below.
+     *
+     * That is not redundancy for its own sake: a message that ends *inside* an
+     * over-long element must still be `INVALID`, and only this event runs early
+     * enough to say so. Without it the verdict would degrade to `INCOMPLETE`, which
+     * §5.2.3 forbids for input already known to be malformed and which §6.4 forbids
+     * a chunk boundary from changing.
+     *
+     * An element of the wrong fixlen subtype is left alone: §7.3 requires it to be
+     * *skipped*, not rejected, and it is skipped by this class simply ignoring it.
+     */
+    begin(id: number, subtype: FixlenSubtype, total: number): void;
+    /** One payload piece of element `id` ({@link Visitor.string}). */
+    element(id: number, total: number, offset: number, src: Uint8Array, start: number, end: number): void;
+    /** Every bound for one element. Rejects **before** the destination grows. */
+    private check;
+}
+/**
+ * Collects the elements of a `blob` wrapper-sequence array into `out`. The
+ * `string` twin above, with two differences: the payload is stored as bytes rather
+ * than decoded, and gaps are filled with an empty {@link Uint8Array}.
+ *
+ * Each element is storage of its own — what {@link PayloadAcc} returns is a buffer
+ * it allocated and handed over, never a view into the fed chunk (§6.7) — so a
+ * stored element cannot rot when the caller reuses its input.
+ *
+ * @param out The destination, placed at `out[id]`.
+ * @param acc The decoder's shared {@link PayloadAcc}.
+ * @param cap The schema `count` as an index capacity, or {@link UNBOUNDED} (`-1`)
+ * for unbounded.
+ * @param elemMax The element `maxlen` in bytes, or {@link UNBOUNDED} (`-1`) for an
+ * element the schema left open, where `receiverElemMax` governs instead.
+ * @param name The schema field name, used only in the rejection message.
+ * @param receiverCap The receiver-side index cap for a schema-unbounded array
+ * (§6.2.1) — see {@link StringSeq}. Required, with no default.
+ * @param receiverElemMax The receiver-side `max_dyn_blob_len` for a schema-unbounded
+ * element (§6.2.1) — see {@link StringSeq}. Required, with no default.
+ */
+declare class BlobSeq {
+    readonly out: Uint8Array[];
+    readonly acc: PayloadAcc;
+    readonly cap: number;
+    readonly elemMax: number;
+    readonly name: string;
+    readonly receiverCap: number;
+    readonly receiverElemMax: number;
+    /** The index rules and both index bounds, shared with every other element kind. */
+    private readonly slots;
+    constructor(out: Uint8Array[], acc: PayloadAcc, cap: number, elemMax: number, name: string, receiverCap: number, receiverElemMax: number);
+    /** See {@link StringSeq.begin} — the early bound check, for subtype `blob`. */
+    begin(id: number, subtype: FixlenSubtype, total: number): void;
+    /** One payload piece of element `id` ({@link Visitor.blob}). */
+    element(id: number, total: number, offset: number, src: Uint8Array, start: number, end: number): void;
+    /** Every bound for one element. Rejects **before** the destination grows. */
+    private check;
+}
+
+/**
+ * Generated-layer support: the array half of the ≠-default test that decides
+ * whether a field is written at all (MESSAGE_SPEC §2).
+ *
+ * SofaBuffers omits a field whose value equals its schema default, so every
+ * generated `serialize` compares before it writes. For a scalar that is `!==`;
+ * for an array it is element-wise, because two distinct `Uint8Array` /
+ * `number[]` instances holding the same values are the same *value* and must
+ * encode the same way — `a !== b` would emit the field whenever the destination
+ * happened to be a fresh object, and the wire is supposed to be canonical.
+ *
+ * The comparison has no schema in it: the declared type only decides which
+ * arrays are handed over. So it is written once here instead of being emitted
+ * into every generated package (ARCHITECTURE §8).
+ */
+
+/**
+ * Element-wise equality for two array-likes: same length, and `===` at every
+ * index. Covers what a leaf array field can hold — `Uint8Array` (blob), and
+ * `number[]` / `bigint[]` / `boolean[]` / `string[]` — including a mixed pair
+ * such as a `Uint8Array` value against a plain-array default from the schema.
+ *
+ * Deliberately **not** deep: a nested (wrapper) array of messages is compared by
+ * the generated `isDefault()` of its element type, which is the only code that
+ * knows what a default element is. Equally deliberately `===`, which makes `NaN`
+ * unequal to itself — matching the scalar `!==` test, the IEEE-754 rule the rest
+ * of the encoder follows, and the only reading under which an `fp32`/`fp64`
+ * `NaN` element survives the round trip rather than being omitted as "default".
+ * There is no identity short-circuit for the same reason: `elementsEqual(x, x)`
+ * has to give the same answer as `elementsEqual(x, x.slice())`.
+ */
+declare function elementsEqual(a: ArrayLike<unknown>, b: ArrayLike<unknown>): boolean;
+/**
+ * The {@link Long} flavour of {@link elementsEqual}: same length, and the same
+ * 64-bit value at every index.
+ *
+ * A separate function rather than an argument to the one above, because the
+ * comparison itself is different. A `Long` is an *object identity* — two
+ * instances holding the same 64 bits are `!==` — so `elementsEqual`'s `===` would
+ * report every `Long`-backed array as unequal to its schema default and the
+ * ≠-default test (MESSAGE_SPEC §2) would emit a field that should have been
+ * omitted. Comparing the `(low, high)` halves is what "same value" means for this
+ * representation, and it is the only 64-bit representation that needs it:
+ * `bigint` and `number` elements are values already and go through
+ * {@link elementsEqual}.
+ *
+ * Which arrays are handed over is the declared type's business, so there is no
+ * schema in here either (ARCHITECTURE §8).
+ */
+declare function longElementsEqual(a: ArrayLike<Long>, b: ArrayLike<Long>): boolean;
+
+/**
+ * A fresh 4-byte companion holding one fp32 word's wire image: the four
+ * little-endian bytes of its 32-bit word, byte `k` in bits `8*k`.
+ *
+ * Generated-layer support, not a codec path: an `fp32` field whose value is a
+ * `NaN` cannot be re-encoded from the `number` a JS host stored it in — the host
+ * normalizes the payload bits — so the generated message keeps the four raw wire
+ * bytes beside the value and re-emits those (MESSAGE_SPEC §6.5). What the decoder
+ * hands over is the 32-bit *word*, because a number costs nothing to pass where
+ * the byte view it replaced was an allocation per value and a borrowed slice
+ * §6.7 forbids; turning that word back into bytes is this function, and it is the
+ * same four shifts for every schema (ARCHITECTURE §8).
+ *
+ * One function and not two. An `into(out, off, bits)` flavour beside it would be
+ * the natural companion — it is what the fp32 *array* path would want — but that
+ * path was retired before this one moved here (§6.7 killed the view), so the
+ * whole family builds this companion per `NaN` scalar and nothing else calls it.
+ * Public API with no consumer drifts, so there is exactly one entry point and it
+ * allocates: the allocation is per `NaN`, not per field.
+ */
+declare function fp32RawBytes(bits: number): Uint8Array;
 
 /**
  * The acceleration seam.
@@ -702,19 +2061,47 @@ declare class Cursor {
  * The encoder's bulk array paths run through a {@link Kernel} — a small set of
  * self-contained, buffer-oriented transforms over a region the caller has
  * already sized. The default {@link "./js"} kernel is pure TypeScript and works
- * everywhere; a C++ (N-API) or WebAssembly build can implement the same
- * interface and be swapped in with {@link setKernel} for a speed-up, with **no
- * change to the public API**. The boundary is deliberately *bulk* (a whole
+ * everywhere, and is the active kernel unless the caller replaces it: no
+ * accelerated build is published, and this interface is the entire seam for one
+ * (#115). A C++ (N-API) or WebAssembly build implements the same interface and
+ * is swapped in with {@link setKernel} — the caller loads its own module and
+ * hands over the kernel it builds — for a speed-up with **no change to the
+ * public API**. The boundary is deliberately *bulk* (a whole
  * array per call, into guaranteed capacity) so the cost of crossing into native
  * code is amortised — never one call per element.
  */
 /**
- * Bulk, capacity-guaranteed transforms used on the encoder's fast path.
+ * Bulk transforms used on the encoder's fast path.
  *
- * Every method writes into `out` starting at `pos`, assuming the caller has
- * already ensured enough room, and returns the position just past the last byte
- * written. Headers, counts, flushing and validation stay in the stream classes;
- * a kernel only moves bytes.
+ * Every method writes into `out` starting at `pos` and returns the position just
+ * past the last byte written.
+ *
+ * **`out.length` is the bound, and the only one.** The two packers are handed a
+ * region the caller has already sized exactly (4 or 8 bytes an element, a number
+ * the caller can compute), so for them "enough room" is a guarantee. The two
+ * *varint* kernels are not: a varint's length depends on the value, so the caller
+ * cannot know the size without encoding it, and asking the source how wide its
+ * elements are is exactly the guess that silently truncated messages (§5.1). So a
+ * varint kernel must
+ *
+ * * **never write at or past `out.length`**, and
+ * * **keep counting anyway**, returning the position it *would* have reached.
+ *
+ * The caller compares that against `out.length`: past the end means the message
+ * does not fit, which in the block mode is `BUFFER_FULL` — the answer that mode
+ * exists to give. The JS kernel satisfies this for free (a typed-array store past
+ * the end is dropped while `pos` keeps advancing); a native or WebAssembly kernel
+ * must implement it deliberately, counting the remaining elements without storing. Headers, counts and flushing stay in the stream classes; a kernel
+ * only moves bytes — with one obligation it cannot delegate, because it is the
+ * only code that ever looks at the elements: **the integer kernels must reject
+ * an element outside the 64-bit value domain** (CORELIB_PLAN §6.2 — `0 .. 2^64
+ * - 1` unsigned, `-2^63 .. 2^63 - 1` signed) by throwing `argumentError`,
+ * rather than reducing it modulo 2^64. The stream classes range-check the same
+ * values on their element-at-a-time streaming path, so a kernel that skipped
+ * the check would make the wire depend on which constructor the caller used
+ * (#106). The check is one store, one load and one compare on the `bigint`
+ * branch (`splitU64` / `splitI64`); the `number` fast paths are already gated
+ * on the domain and pay nothing.
  */
 interface Kernel {
     /** A short identifier, surfaced in diagnostics and the parity tests. */
@@ -749,36 +2136,6 @@ declare function getKernel(): Kernel;
  */
 declare const jsKernel: Kernel;
 
-/**
- * Attempt to load and install the native kernel.
- *
- * @returns `true` if a valid native kernel was installed, `false` if it could
- *   not be loaded (not on Node, addon not installed, or wrong shape). Never
- *   throws for a missing addon — the JS kernel remains the fallback.
- */
-declare function loadNativeKernel(): Promise<boolean>;
-
-/**
- * Optional WebAssembly acceleration loader.
- *
- * Unlike the native addon, a WASM kernel runs in the browser too. This module
- * does nothing at import time; call {@link loadWasmKernel} with the compiled
- * module's bytes (or a streaming source) to instantiate it and install it as
- * the active {@link Kernel}. A real WASM build is shipped separately; this
- * loader is the stable entry point the rest of the library is wired through.
- */
-
-/** A factory the WASM glue exposes: given the instance exports, build a Kernel. */
-type WasmKernelFactory = (exports: WebAssembly.Exports) => Kernel;
-/**
- * Instantiate a WASM module and install the kernel it produces.
- *
- * @param source compiled-module bytes, a `Response`/stream, or a ready module.
- * @param factory wraps the instance exports into a {@link Kernel}.
- * @returns `true` once installed; throws only if instantiation itself fails.
- */
-declare function loadWasmKernel(source: BufferSource | Response | PromiseLike<Response> | WebAssembly.Module, factory: WasmKernelFactory, imports?: WebAssembly.Imports): Promise<boolean>;
-
 /**
  * The complete public surface of the library, re-exported by {@link "./index"}
  * both as flat named exports and, aggregated, under the `sofab` namespace.
@@ -787,39 +2144,55 @@ declare function loadWasmKernel(source: BufferSource | Response | PromiseLike<Re
 declare const _public_API_VERSION: typeof API_VERSION;
 declare const _public_ARRAY_MAX: typeof ARRAY_MAX;
 type _public_ArrayKind = ArrayKind;
-type _public_Cursor = Cursor;
-declare const _public_Cursor: typeof Cursor;
-type _public_DecodeLimits = DecodeLimits;
+type _public_ArrayTarget = ArrayTarget;
+type _public_BlobSeq = BlobSeq;
+declare const _public_BlobSeq: typeof BlobSeq;
+type _public_BoolArrayTarget = BoolArrayTarget;
 type _public_DecodeStatus = DecodeStatus;
+type _public_ElementSeq<T> = ElementSeq<T>;
+declare const _public_ElementSeq: typeof ElementSeq;
 declare const _public_FIXLEN_MAX: typeof FIXLEN_MAX;
+type _public_FeedStatus = FeedStatus;
 type _public_FixlenSubtype = FixlenSubtype;
+type _public_FloatArrayTarget = FloatArrayTarget;
 type _public_FlushSink = FlushSink;
+type _public_FramedSeq<T> = FramedSeq<T>;
+declare const _public_FramedSeq: typeof FramedSeq;
 declare const _public_I64_MAX: typeof I64_MAX;
 declare const _public_I64_MIN: typeof I64_MIN;
 declare const _public_ID_MAX: typeof ID_MAX;
 type _public_IStream = IStream;
 declare const _public_IStream: typeof IStream;
+type _public_IntegerArrayTarget = IntegerArrayTarget;
 type _public_Kernel = Kernel;
 type _public_Long = Long;
 declare const _public_Long: typeof Long;
 declare const _public_MAX_DEPTH: typeof MAX_DEPTH;
+declare const _public_MIN_OUTPUT_BUFFER: typeof MIN_OUTPUT_BUFFER;
 type _public_OStream = OStream;
 declare const _public_OStream: typeof OStream;
+type _public_PayloadAcc = PayloadAcc;
+declare const _public_PayloadAcc: typeof PayloadAcc;
 type _public_SofabError = SofabError;
 declare const _public_SofabError: typeof SofabError;
 type _public_SofabErrorCode = SofabErrorCode;
+type _public_StringSeq = StringSeq;
+declare const _public_StringSeq: typeof StringSeq;
 declare const _public_U64_MAX: typeof U64_MAX;
+declare const _public_UNBOUNDED: typeof UNBOUNDED;
 type _public_Visitor = Visitor;
-type _public_WasmKernelFactory = WasmKernelFactory;
 type _public_WireType = WireType;
 declare const _public_decode: typeof decode;
+declare const _public_decodeUtf8: typeof decodeUtf8;
+declare const _public_elementsEqual: typeof elementsEqual;
+declare const _public_fp32RawBytes: typeof fp32RawBytes;
 declare const _public_getKernel: typeof getKernel;
+declare const _public_growingOStream: typeof growingOStream;
 declare const _public_jsKernel: typeof jsKernel;
-declare const _public_loadNativeKernel: typeof loadNativeKernel;
-declare const _public_loadWasmKernel: typeof loadWasmKernel;
+declare const _public_longElementsEqual: typeof longElementsEqual;
 declare const _public_setKernel: typeof setKernel;
 declare namespace _public {
-  export { _public_API_VERSION as API_VERSION, _public_ARRAY_MAX as ARRAY_MAX, type _public_ArrayKind as ArrayKind, _public_Cursor as Cursor, type _public_DecodeLimits as DecodeLimits, type _public_DecodeStatus as DecodeStatus, _public_FIXLEN_MAX as FIXLEN_MAX, type _public_FixlenSubtype as FixlenSubtype, type _public_FlushSink as FlushSink, _public_I64_MAX as I64_MAX, _public_I64_MIN as I64_MIN, _public_ID_MAX as ID_MAX, _public_IStream as IStream, type _public_Kernel as Kernel, _public_Long as Long, _public_MAX_DEPTH as MAX_DEPTH, _public_OStream as OStream, _public_SofabError as SofabError, type _public_SofabErrorCode as SofabErrorCode, _public_U64_MAX as U64_MAX, type _public_Visitor as Visitor, type _public_WasmKernelFactory as WasmKernelFactory, type _public_WireType as WireType, _public_decode as decode, _public_getKernel as getKernel, _public_jsKernel as jsKernel, _public_loadNativeKernel as loadNativeKernel, _public_loadWasmKernel as loadWasmKernel, _public_setKernel as setKernel };
+  export { _public_API_VERSION as API_VERSION, _public_ARRAY_MAX as ARRAY_MAX, type _public_ArrayKind as ArrayKind, type _public_ArrayTarget as ArrayTarget, _public_BlobSeq as BlobSeq, type _public_BoolArrayTarget as BoolArrayTarget, type _public_DecodeStatus as DecodeStatus, _public_ElementSeq as ElementSeq, _public_FIXLEN_MAX as FIXLEN_MAX, type _public_FeedStatus as FeedStatus, type _public_FixlenSubtype as FixlenSubtype, type _public_FloatArrayTarget as FloatArrayTarget, type _public_FlushSink as FlushSink, _public_FramedSeq as FramedSeq, _public_I64_MAX as I64_MAX, _public_I64_MIN as I64_MIN, _public_ID_MAX as ID_MAX, _public_IStream as IStream, type _public_IntegerArrayTarget as IntegerArrayTarget, type _public_Kernel as Kernel, _public_Long as Long, _public_MAX_DEPTH as MAX_DEPTH, _public_MIN_OUTPUT_BUFFER as MIN_OUTPUT_BUFFER, _public_OStream as OStream, _public_PayloadAcc as PayloadAcc, _public_SofabError as SofabError, type _public_SofabErrorCode as SofabErrorCode, _public_StringSeq as StringSeq, _public_U64_MAX as U64_MAX, _public_UNBOUNDED as UNBOUNDED, type _public_Visitor as Visitor, type _public_WireType as WireType, _public_decode as decode, _public_decodeUtf8 as decodeUtf8, _public_elementsEqual as elementsEqual, _public_fp32RawBytes as fp32RawBytes, _public_getKernel as getKernel, _public_growingOStream as growingOStream, _public_jsKernel as jsKernel, _public_longElementsEqual as longElementsEqual, _public_setKernel as setKernel };
 }
 
-export { API_VERSION, ARRAY_MAX, ArrayKind, Cursor, type DecodeLimits, DecodeStatus, FIXLEN_MAX, FixlenSubtype, type FlushSink, I64_MAX, I64_MIN, ID_MAX, IStream, type Kernel, Long, MAX_DEPTH, OStream, SofabError, SofabErrorCode, U64_MAX, type Visitor, type WasmKernelFactory, WireType, decode, getKernel, jsKernel, loadNativeKernel, loadWasmKernel, setKernel, _public as sofab };
+export { API_VERSION, ARRAY_MAX, ArrayKind, type ArrayTarget, BlobSeq, type BoolArrayTarget, DecodeStatus, ElementSeq, FIXLEN_MAX, type FeedStatus, FixlenSubtype, type FloatArrayTarget, type FlushSink, FramedSeq, I64_MAX, I64_MIN, ID_MAX, IStream, type IntegerArrayTarget, type Kernel, Long, MAX_DEPTH, MIN_OUTPUT_BUFFER, OStream, PayloadAcc, SofabError, SofabErrorCode, StringSeq, U64_MAX, UNBOUNDED, type Visitor, WireType, decode, decodeUtf8, elementsEqual, fp32RawBytes, getKernel, growingOStream, jsKernel, longElementsEqual, setKernel, _public as sofab };