@sofa-buffers/corelib 0.8.0

package/dist/index.d.cts

@@ -0,0 +1,825 @@
+/**
+ * Wire-format constants for SofaBuffers.
+ *
+ * The format is specified, language-neutrally, in the
+ * {@link https://github.com/sofa-buffers/documentation | SofaBuffers documentation}.
+ * Every field on the wire begins with a varint header `(id << 3) | wireType`,
+ * so the wire type lives in the low three bits and the field id in the rest.
+ */
+/**
+ * The SofaBuffers API version this library implements. The generator and other
+ * tooling read it to verify compatibility. Bumped only on a breaking API change.
+ */
+declare const API_VERSION = 1;
+/** The three low bits of a field header: what kind of field follows. */
+declare const WireType: {
+    /** Unsigned varint scalar. */
+    readonly Unsigned: 0;
+    /** Signed varint scalar (zig-zag encoded). */
+    readonly Signed: 1;
+    /** Fixed-length value: fp32, fp64, string or blob (see {@link FixlenSubtype}). */
+    readonly Fixlen: 2;
+    /** Array of unsigned varints. */
+    readonly ArrayUnsigned: 3;
+    /** Array of signed (zig-zag) varints. */
+    readonly ArraySigned: 4;
+    /** Array of fixed-length values (fp32 / fp64 only). */
+    readonly ArrayFixlen: 5;
+    /** Opens a nested sequence (new id scope). */
+    readonly SequenceStart: 6;
+    /** Closes the current sequence. Encoded as the single byte `0x07`. */
+    readonly SequenceEnd: 7;
+};
+/** A field's wire type: one of the {@link WireType} values. */
+type WireType = (typeof WireType)[keyof typeof WireType];
+/** The three low bits of a fixlen length header: which fixed-length type. */
+declare const FixlenSubtype: {
+    /** IEEE-754 32-bit float, little-endian. */
+    readonly Fp32: 0;
+    /** IEEE-754 64-bit double, little-endian. */
+    readonly Fp64: 1;
+    /** UTF-8 string (no null terminator). */
+    readonly String: 2;
+    /** Arbitrary binary data. */
+    readonly Blob: 3;
+};
+/** A fixed-length value's type: one of the {@link FixlenSubtype} values. */
+type FixlenSubtype = (typeof FixlenSubtype)[keyof typeof FixlenSubtype];
+/** Which element kind an array field carries (reported to {@link Visitor.arrayBegin}). */
+declare const ArrayKind: {
+    /** Unsigned-integer elements. */
+    readonly Unsigned: 0;
+    /** Signed-integer (zig-zag) elements. */
+    readonly Signed: 1;
+    /** IEEE-754 32-bit float elements. */
+    readonly Fp32: 2;
+    /** IEEE-754 64-bit double elements. */
+    readonly Fp64: 3;
+};
+/** An array field's element kind: one of the {@link ArrayKind} values. */
+type ArrayKind = (typeof ArrayKind)[keyof typeof ArrayKind];
+/** Largest permitted field id and fixlen length / array count: `INT32_MAX`. */
+declare const ID_MAX = 2147483647;
+/** Largest permitted fixlen byte length: `INT32_MAX`. */
+declare const FIXLEN_MAX = 2147483647;
+/** Largest permitted array element count: `INT32_MAX`. */
+declare const ARRAY_MAX = 2147483647;
+/** Largest unsigned 64-bit value (`2^64 - 1`). */
+declare const U64_MAX = 18446744073709551615n;
+/** Smallest signed 64-bit value (`-2^63`). */
+declare const I64_MIN = -9223372036854775808n;
+/** Largest signed 64-bit value (`2^63 - 1`). */
+declare const I64_MAX = 9223372036854775807n;
+/**
+ * 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
+ * nests deeper with an `InvalidMessage` error rather than risk unbounded
+ * recursion / stack growth.
+ */
+declare const MAX_DEPTH = 255;
+/**
+ * The terminal outcome of a decode (MESSAGE_SPEC §7), reported identically for
+ * one-shot and streaming decode with **no** finish / finalize / end promotion
+ * step:
+ *
+ * - `Complete` — the bytes ended exactly at a field boundary: a valid message.
+ * - `Incomplete` — the bytes ended *inside* a field (an unterminated varint, a
+ *   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.
+ *
+ * {@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.
+ */
+declare const DecodeStatus: {
+    /** The bytes ended exactly at a field boundary — a valid message. */
+    readonly Complete: "COMPLETE";
+    /** The bytes ended inside a field; more bytes could complete it (not an error). */
+    readonly Incomplete: "INCOMPLETE";
+    /** The bytes are malformed regardless of what follows. */
+    readonly Invalid: "INVALID";
+};
+/** A decode's terminal outcome: one of the {@link DecodeStatus} values. */
+type DecodeStatus = (typeof DecodeStatus)[keyof typeof DecodeStatus];
+
+/**
+ * Error handling for SofaBuffers.
+ *
+ * Both encoder and decoder report problems through a single {@link SofabError}
+ * carrying a {@link SofabErrorCode}, mirroring the C reference's `sofab_ret_t`
+ * return codes so the failure modes line up across the language family.
+ *
+ * The decoder distinguishes two *kinds* of decode failure (MESSAGE_SPEC §7):
+ * {@link SofabErrorCode.InvalidMsg} for input that is malformed regardless of
+ * what follows (`INVALID`), and {@link SofabErrorCode.Incomplete} for input that
+ * merely ends inside a field (`INCOMPLETE`) — a truncation that more bytes could
+ * complete, and so is *not* the same as a malformed message. A third code,
+ * {@link SofabErrorCode.LimitExceeded}, is orthogonal to both: it reports a
+ * receiver-configured decode limit being hit — *policy*, not a property of the
+ * 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
+ * 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`). */
+    readonly InvalidMsg: "INVALID_MSG";
+    /**
+     * The input being decoded ends inside a field (`INCOMPLETE`, MESSAGE_SPEC §7):
+     * an unterminated varint, a payload shorter than its declared length, an array
+     * that runs off the end, or a nested sequence never closed. Not a malformed
+     * message — more bytes could complete it, and the caller owns end-of-input.
+     */
+    readonly Incomplete: "INCOMPLETE";
+    /**
+     * 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`)
+     * 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
+     * as a conformance divergence. The decoder never clamps or truncates; it
+     * rejects, before the offending field is materialized.
+     */
+    readonly LimitExceeded: "LIMIT_EXCEEDED";
+};
+/** A {@link SofabError}'s cause: one of the {@link SofabErrorCode} values. */
+type SofabErrorCode = (typeof SofabErrorCode)[keyof typeof SofabErrorCode];
+/** The single error type thrown by the encoder and decoder. */
+declare class SofabError extends Error {
+    /** The machine-readable cause. */
+    readonly code: SofabErrorCode;
+    constructor(code: SofabErrorCode, message: string);
+}
+
+/**
+ * A 64-bit integer value carried as two unsigned 32-bit halves.
+ *
+ * SofaBuffers accepts `bigint` at every 64-bit surface for ergonomics, but a
+ * `bigint` in the encode/decode hot path is expensive — especially on
+ * JavaScriptCore (Bun), where profiling showed the `bigint` split/materialise
+ * and zig-zag operations dominating the 64-bit array codecs. `Long` lets a
+ * caller (and the generated code) stay entirely on `number` arithmetic: the
+ * codec reads `.low`/`.high` directly, and any `bigint`↔`Long` conversion
+ * happens once at the API boundary rather than once per encode.
+ *
+ * Values are stored as raw two's-complement bits; the same `Long` serves an
+ * unsigned or signed field — {@link Long.toBigInt} takes the signedness.
+ */
+declare class Long {
+    /** Low 32 bits (unsigned). */
+    readonly low: number;
+    /** High 32 bits (unsigned). */
+    readonly high: number;
+    constructor(low: number, high: number);
+    /**
+     * The 64-bit zero. `Long` is immutable (readonly halves), so this single shared
+     * instance is safe to reuse anywhere a zero default is needed — generated code
+     * uses it for fixed-count array defaults and pad-fill instead of
+     * `Long.fromValue(0)`, which would run `bigint` arithmetic per call on the hot
+     * decode/encode path.
+     */
+    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). */
+    static fromBigInt(value: bigint): Long;
+    /** From an integer `number` (`|n| < 2^53`); sign handled via `bigint` once. */
+    static fromNumber(n: number): Long;
+    /** Accept a `Long` as-is, or convert a `bigint` / `number` once. */
+    static fromValue(v: Long | bigint | number): Long;
+    /** Materialise as a `bigint`. `signed` reads the high bit as two's complement. */
+    toBigInt(signed?: boolean): bigint;
+    /** Decimal string (`signed` interprets the high bit as two's complement). */
+    toString(signed?: boolean): string;
+}
+
+/**
+ * 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.
+ */
+type FlushSink = (chunk: Uint8Array) => void;
+
+/**
+ * The SofaBuffers encoder.
+ *
+ * `OStream` writes fields into a byte buffer. Two modes:
+ *
+ * - **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.
+ *
+ * Generated code typically writes one field per message field; the methods map
+ * one-to-one onto the wire types. Problems throw {@link SofabError}.
+ */
+
+/**
+ * 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}.
+ */
+declare class OStream {
+    private buf;
+    private pos;
+    private start;
+    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`. */
+    constructor(buffer: Uint8Array, offset?: number, flush?: FlushSink);
+    /** Bytes currently held in the buffer (since construction or the last flush). */
+    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.
+     */
+    bytes(): Uint8Array;
+    /** Drain buffered bytes to the flush sink (no-op without one). */
+    flush(): void;
+    /**
+     * 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
+     * the encoder a new buffer for the next batch of bytes, so encoding continues
+     * 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).
+     */
+    setBuffer(buffer: Uint8Array, offset?: 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
+     * encode. Any view previously returned by {@link bytes} is invalidated.
+     */
+    reset(): void;
+    /** Write an unsigned integer field. */
+    writeUnsigned(id: number, value: number | bigint): void;
+    /** Write a signed integer field (zig-zag encoded). */
+    writeSigned(id: number, value: number | bigint): 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 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. */
+    writeFixlen(id: number, data: Uint8Array, subtype: FixlenSubtype): void;
+    /** Write an array of unsigned integers (each a varint). */
+    writeUnsignedArray(id: number, values: ArrayLike<number | bigint>): void;
+    /** Write an array of signed integers (each zig-zag + varint). */
+    writeSignedArray(id: number, values: ArrayLike<number | bigint>): void;
+    /**
+     * Write an unsigned 64-bit array from {@link Long}[] — the `bigint`-free path.
+     * Produces the identical wire to {@link writeUnsignedArray}; reads each Long's
+     * 32-bit halves directly, so no `bigint` is created per element.
+     */
+    writeUnsignedArrayLong(id: number, values: readonly Long[]): void;
+    /**
+     * Write a signed 64-bit array (zig-zag) from {@link Long}[] — the `bigint`-free
+     * path. Zig-zag `(n << 1) ^ (n >> 63)` is computed on the lo/hi pair.
+     */
+    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 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. */
+    writeSequenceEnd(): void;
+    /** Ensure exactly `value`'s varint size, then write it (bigint path). */
+    private putVarint;
+    /** Ensure exactly `value`'s varint size, then write it (number fast path). */
+    private putVarintNum;
+    private header;
+    private fixlenHead;
+    private arrayHead;
+    /** Copy `data` out, flushing/growing as needed (large payloads stay chunked). */
+    private writeRaw;
+    /** Ensure `n` contiguous bytes are free at `pos`; returns `pos` for chaining. */
+    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).
+ *
+ * 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).
+ *
+ * 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.**
+ *
+ * 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).
+ */
+interface DecodeLimits {
+    /**
+     * Reject a dynamic (`u*` / `i*`, `fp32` / `fp64`) array whose element `count`
+     * exceeds this, before the array is materialized. Omit for no cap.
+     */
+    maxArrayCount?: number;
+    /**
+     * Reject a UTF-8 string whose declared byte length exceeds this, before the
+     * payload is decoded or streamed. Omit for no cap.
+     */
+    maxStringLen?: number;
+    /**
+     * Reject a blob whose declared byte length exceeds this, before the payload is
+     * accepted or streamed. Omit for no cap.
+     */
+    maxBlobLen?: number;
+}
+
+/**
+ * The SofaBuffers decoder.
+ *
+ * `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.
+ *
+ * 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.
+ */
+
+/**
+ * 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.
+ *
+ * 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}.
+ */
+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.
+     */
+    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. */
+    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 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;
+    /** 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.
+     */
+    sequenceBegin?(id: number): Visitor | void;
+    /** End of the nested sequence this visitor was handling. */
+    sequenceEnd?(): 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}.
+ */
+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}).
+     */
+    feed(chunk: Uint8Array, visitor: Visitor): void;
+    /**
+     * 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).
+     *
+     * 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}.)
+     */
+    end(): DecodeStatus;
+}
+/**
+ * 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 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).
+ */
+declare function decode(bytes: Uint8Array, visitor: Visitor, limits?: DecodeLimits): 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`.
+ */
+
+/**
+ * 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;
+}
+
+/**
+ * The acceleration seam.
+ *
+ * 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
+ * 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.
+ *
+ * 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.
+ */
+interface Kernel {
+    /** A short identifier, surfaced in diagnostics and the parity tests. */
+    readonly name: string;
+    /** Encode each element as an unsigned varint. */
+    encodeUnsignedVarints(values: ArrayLike<number | bigint>, out: Uint8Array, pos: number): number;
+    /** Zig-zag then varint-encode each element. */
+    encodeSignedVarints(values: ArrayLike<number | bigint>, out: Uint8Array, pos: number): number;
+    /** Pack each element as a little-endian fp32 (4 bytes). */
+    packFp32Array(values: ArrayLike<number>, out: Uint8Array, pos: number): number;
+    /** Pack each element as a little-endian fp64 (8 bytes). */
+    packFp64Array(values: ArrayLike<number>, out: Uint8Array, pos: number): number;
+}
+/** Install `kernel` as the active acceleration backend. */
+declare function setKernel(kernel: Kernel): void;
+/** The currently active kernel (the JS kernel until something replaces it). */
+declare function getKernel(): Kernel;
+
+/**
+ * The default, pure-TypeScript {@link Kernel}.
+ *
+ * Always available — no native dependency, no WebAssembly — so SofaBuffers runs
+ * unchanged in Node.js, browsers, Electron and bundled builds. Importing this
+ * module registers it as the default kernel (idempotently); a native or WASM
+ * kernel can later override it via {@link setKernel}.
+ */
+
+/**
+ * The default, pure-TypeScript {@link Kernel} — active until {@link setKernel}
+ * installs another. It implements the bulk encoder transforms with no native or
+ * WebAssembly dependency, so it works in every environment.
+ */
+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.
+ */
+
+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_DecodeStatus = DecodeStatus;
+declare const _public_FIXLEN_MAX: typeof FIXLEN_MAX;
+type _public_FixlenSubtype = FixlenSubtype;
+type _public_FlushSink = FlushSink;
+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_Kernel = Kernel;
+type _public_Long = Long;
+declare const _public_Long: typeof Long;
+declare const _public_MAX_DEPTH: typeof MAX_DEPTH;
+type _public_OStream = OStream;
+declare const _public_OStream: typeof OStream;
+type _public_SofabError = SofabError;
+declare const _public_SofabError: typeof SofabError;
+type _public_SofabErrorCode = SofabErrorCode;
+declare const _public_U64_MAX: typeof U64_MAX;
+type _public_Visitor = Visitor;
+type _public_WasmKernelFactory = WasmKernelFactory;
+type _public_WireType = WireType;
+declare const _public_decode: typeof decode;
+declare const _public_getKernel: typeof getKernel;
+declare const _public_jsKernel: typeof jsKernel;
+declare const _public_loadNativeKernel: typeof loadNativeKernel;
+declare const _public_loadWasmKernel: typeof loadWasmKernel;
+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 { 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 };