@cloudbitmaps/core 0.9.0 → 0.10.0

package/dist/core/consistency.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Fail-safe cross-store disaster-recovery check. The registry (`currentGen`) and the immutable `.crbm`
+ * generations can be restored **independently**, so a failover can recover the registry *ahead of* the storage
+ * objects — leaving `currentGen` pointing at a generation whose `.crbm` isn't present yet. That is likelier
+ * than it sounds even now that both usually live in one bucket: a restore scoped to a prefix, or replayed
+ * per-object from a version history, recovers the two prefixes at different points. That's a torn restore: reads of the affected segment then throw. This scan
+ * detects it up front (run it at startup after a restore) instead of discovering it on the first read.
+ *
+ * Read-only; bounded fan-out. `destroyed` (crypto-shredded) segments are skipped — their Storage is intentionally
+ * gone/unreadable, not a torn restore. A segment whose Storage/registry can't be read this pass is recorded in
+ * `errored` (never aborts the scan). Each segment is checked against its **authoritative live pointer** — one
+ * strong `registry.get` per segment — never the enumeration snapshot from `registry.list`, which can be
+ * eventually-consistent (an unindexed Scan) and lag a recent in-place pointer advance: trusting it would both
+ * miss a torn *live* generation and cry torn on a generation the pointer has already advanced past (GC'd during
+ * the scan). Residual: a load's publish plus a GC landing in the tiny per-segment get→list gap can still yield a
+ * transient false positive — run the scan against a quiesced fleet (the documented restore procedure), or re-run
+ * to confirm a reported tear.
+ */
+import type { IStorageDriver, IRegistryDriver } from './ports.js';
+/** Default in-flight fan-out for the consistency scan — bounded, no thundering herd. */
+/**
+ * Default ceiling on how many registry records one consistency check may hold resident: 250,000.
+ *
+ * **Named `maxScanSegments`, not `maxSegments`, on purpose.** A `maxSegments`-style option caps how much work
+ * one cycle does and then *continues normally* (the retention sweep's `limit` is that shape). This one caps how
+ * much a scan may hold and *refuses* past it. Same-sounding names with opposite behaviour at the limit is a
+ * trap; the name says what it is — a ceiling on a scan that fails closed.
+ *
+ * Generous — fleets of 100K+ segments are the design target — while still bounding a DR drill's memory to
+ * something a modest operator box survives. Raisable, because a ceiling you cannot lift is a landmine.
+ */
+export { DEFAULT_MAX_SCAN_SEGMENTS } from './registry-scan.js';
+export interface ConsistencyIssue {
+    readonly segment: string;
+    readonly namespace?: string;
+    /** The registry's `currentGen` for the segment — the generation whose `.crbm` is missing from Storage. */
+    readonly currentGen: number;
+    /** The only issue class today: `currentGen` references a Storage generation that is not present (torn restore). */
+    readonly issue: 'missing-storage-generation';
+}
+/** A segment that could not be checked this pass (Storage/registry read fault) — not proof of a torn restore. */
+export interface ConsistencyErrorEntry {
+    readonly segment: string;
+    readonly namespace?: string;
+    /** The read error's message (never the raw error, so the report stays serializable/loggable). */
+    readonly error: string;
+}
+export interface ConsistencyReport {
+    /** Registered segments scanned (a `destroyed` segment counts as scanned but is never an issue). */
+    readonly checked: number;
+    /** Segments whose `currentGen` `.crbm` is absent — recover the object store (or restore to a coherent point). */
+    readonly inconsistent: ConsistencyIssue[];
+    /**
+     * Segments that couldn't be read this pass (a transient/partial object store during a restore is exactly when
+     * this runs) — **triage these too**: an unread segment is neither proven-coherent nor proven-torn. Empty on a
+     * clean pass.
+     */
+    readonly errored: ConsistencyErrorEntry[];
+}
+/**
+ * Verify every registered segment's `currentGen` `.crbm` actually exists in Storage. Enumerates the registry
+ * (optionally one namespace) and, for each non-`destroyed` segment, checks the object store lists that
+ * generation. Returns the torn segments in `inconsistent` (empty ⇒ coherent) and any unreadable segments in
+ * `errored`.
+ */
+export declare function runConsistencyCheck(deps: {
+    readonly storage: IStorageDriver;
+    readonly registry: IRegistryDriver;
+}, options?: {
+    namespace?: string;
+    concurrency?: number;
+    maxScanSegments?: number;
+}): Promise<ConsistencyReport>;

package/dist/core/cooperative.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Cooperative yielding for the long CPU-bound loops.
+ *
+ * Everything this library does on the hot read path is small. Bulk-load is the exception: it is the one place
+ * where a single call legitimately occupies the CPU for hundreds of milliseconds, and Node has exactly one thread
+ * to occupy. Measured on a 1M-id load, 62,455 chunks: **442 ms wall, and 450 ms during which the event loop did
+ * not turn at all**. Wire that to a request handler and every other in-flight request on the instance — health
+ * checks included — waits out the whole load.
+ *
+ * The fix is not to make the work asynchronous. That was measured too, and it is a 7x *regression*: handing each
+ * chunk's insert to the threadpool costs ~9 µs of dispatch against ~1.5 µs of actual work once ids are spread
+ * across ~62,000 chunks (636 ms versus 92 ms). The work is genuinely CPU-bound and genuinely small per chunk;
+ * the only thing wrong with it is that it never stops to let anyone else go. So the fix is to keep the work
+ * synchronous and periodically hand the loop back.
+ *
+ * TWO TRAPS, both of which make a plausible implementation measure as no change at all:
+ *
+ * 1. **`await Promise.resolve()` — and equally `Clock.sleep(0)` — do nothing.** Both resolve on a microtask, and
+ *    the microtask queue drains to empty before the event loop advances a single phase. A loop awaiting them
+ *    yields to other *microtasks* and to nothing else; no pending I/O callback runs. Measured: 555 ms of
+ *    starvation against a 568 ms unyielded baseline **on the synthetic yield-primitive benchmark below** —
+ *    a different, smaller workload than the 442 ms end-to-end load above, which is why the two baselines
+ *    differ. The yield must be a **macrotask** — hence
+ *    `Clock.yieldNow`, backed by `setImmediate` in production wiring.
+ * 2. **Yielding per unit of work costs more than the work.** The yield has to be periodic, and `everyN` has to be
+ *    large enough that its cost disappears into the batch it interrupts.
+ *
+ * At `everyN = 1024` over that same synthetic workload the trade is close to free: 569 ms wall against a 568 ms
+ * baseline, with the worst event-loop gap down from 568 ms to 13.8 ms.
+ *
+ * **Three experiments, three sets of numbers — do not mix them.** (a) The end-to-end 1M-id bulk load:
+ * 442 ms wall / 450 ms blocked before, 256 ms / 19 ms after. (b) This synthetic yield-primitive comparison:
+ * 568 ms / 568 ms unyielded, 569 ms / 13.8 ms with `setImmediate`. (c) A per-chunk insert microbenchmark:
+ * 92 ms sync versus 636 ms via the threadpool. Quoting a baseline from one against a result from another is
+ * how this file previously published a 92 ms operation with 819 ms of starvation inside it.
+ */
+/**
+ * The only part of a `Clock` that yielding actually needs.
+ *
+ * Deliberately looser than `Clock` so a write path can opt in with whatever it has: a bulk load or a rewrite
+ * yields when its caller supplies a clock that can, and simply runs unbroken when handed nothing (or a bare
+ * `{ now }`). Requiring a full `Clock` would make every out-of-process caller wire one just to write a
+ * generation.
+ */
+export interface Yielder {
+    yieldNow?(): Promise<void>;
+    sleep?(ms: number): Promise<void>;
+}
+/**
+ * How many units of work pass between yields. Sized so the yield is unmeasurable against the batch it interrupts
+ * (~60 yields across a 1M-id load) while still capping any single blocking stretch in the low tens of ms.
+ */
+export declare const YIELD_EVERY = 1024;
+/**
+ * Build a periodic yield.
+ *
+ * Call the returned function **once per unit of work**. It returns `null` on the vast majority of calls — nothing
+ * to await, nothing allocated — and a promise only on the `everyN`th, so the caller pays for a yield only when
+ * one actually happens:
+ *
+ * ```ts
+ * const tick = yieldEvery(clock);
+ * for (const item of millions) {
+ *   work(item);
+ *   const pause = tick();
+ *   if (pause !== null) await pause;
+ * }
+ * ```
+ *
+ * The two-line shape is deliberate. `await tick()` would read better and would force a microtask turn on every
+ * single iteration — an unconditional cost on the very loop this exists to keep fast.
+ *
+ * With no `clock` the result always returns `null`: the loop runs exactly as it did before this existed, so
+ * adding a yield point to a code path can never change behaviour for a caller who did not opt in. `core/` cannot
+ * supply a clock itself — it is timer-free by lint, which is the whole reason scheduling goes through the seam —
+ * so `@cloudbitmaps/roaring` pre-binds a real one and flavor users get this with no wiring at all.
+ */
+export declare function yieldEvery(clock: Yielder | undefined, everyN?: number): () => Promise<void> | null;

package/dist/core/cost.d.ts

@@ -0,0 +1,102 @@
+/** Pluggable rate card. Rates differ by cloud/region/term and drift over time; the formulas don't. */
+export interface PricingProfile {
+    readonly name: string;
+    readonly storage: {
+        /** Object GET (per **million** requests). A ranged GET bills as a full GET. */
+        readonly getPerMillion: number;
+        /** Object PUT (per million) — what a load pays, per request. */
+        readonly putPerMillion: number;
+        readonly storagePerGiBMonth: number;
+    };
+    /** The always-on baseline to compare against (e.g. an ElastiCache HA cluster). */
+    readonly redis: {
+        readonly monthlyUSD: number;
+    };
+}
+/**
+ * Default profile — **AWS us-east-1, on-demand**, mid-2026, from the fact-checked
+ * published pricing rather than copied from a blog post. Override it for your region, cloud, or committed term.
+ */
+export declare const AWS_US_EAST_1_ONDEMAND: PricingProfile;
+export declare const DEFAULT_PRICING: PricingProfile;
+/** Sustained access pattern. All rates default to 0; unspecified ⇒ that op contributes nothing. */
+export interface Workload {
+    /** Point reads (`has`) per second. Each cache miss is one object GET. */
+    readonly readsPerSec?: number;
+    readonly intersectsPerSec?: number;
+    /** CACHE-cache hit rate in `[0, 1]` — hits are free; only misses cost. Default 0. */
+    readonly cacheHitRate?: number;
+    /** Storage chunks fetched per intersection (the chunk-skipping survivors). Default 1. */
+    readonly chunksPerIntersect?: number;
+    /**
+     * Generations published per month across the modeled data — the write side of a loaded store. Default **0**
+     * ⇒ loads are not modeled and the report *discloses* the omission rather than silently under-reporting.
+     */
+    readonly loadsPerMonth?: number;
+    /**
+     * PUT-class requests one load issues. Default **1** (a single-object PUT). A multipart load of `P` parts bills
+     * `P + 2` (initiate, the parts, complete) — set it when you know your object sizes. Still small money: at
+     * $5/million, a thousand 100-part loads a month is $0.51.
+     */
+    readonly requestsPerLoad?: number;
+}
+/** One (group of) segment(s) for planning. `count` = how many like this (default 1). */
+export interface SegmentSizing {
+    readonly sizeBytes?: number;
+    readonly cardinality?: number;
+    /** Number of segments with these characteristics. Default 1. */
+    readonly count?: number;
+}
+export interface EstimateInput {
+    readonly segments: readonly SegmentSizing[];
+    readonly workload?: Workload;
+    readonly pricing?: PricingProfile;
+}
+export interface CostReport {
+    readonly monthlyUSD: {
+        readonly byOp: {
+            readonly reads: number;
+            readonly intersects: number;
+            readonly storage: number;
+            /** Loads (object PUTs). 0 unless `loadsPerMonth` is set. */
+            readonly loads: number;
+        };
+        readonly total: number;
+    };
+    /**
+     * Sustained read rate at which the pay-per-use model's cost passes the flat Redis baseline (with every other
+     * axis at 0), **evaluated at this report's `cacheHitRate`** — so a higher cache-hit rate raises it (cache hits
+     * are free). `Infinity` means it never crosses (a 100% cache-hit rate). The published anchor (~329 reads/s) is
+     * at `cacheHitRate: 0`.
+     */
+    readonly redisCrossover: {
+        readonly readsPerSec: number;
+    };
+    readonly verdict: 'win-big' | 'win' | 'lose-zone';
+    readonly rationale: string;
+    readonly assumptions: {
+        readonly cacheHitRate: number;
+        readonly pricingName: string;
+        /** True when segment **sizes** were real (grounded `costReport`), false for a pure `estimateCost`. */
+        readonly grounded: boolean;
+        readonly notes: readonly string[];
+    };
+}
+/**
+ * **Planning** cost estimate — pure, no instance or live data needed (sizing, sales, what-if). Segment sizes
+ * are taken as given (or roughly derived from cardinality); use the grounded `segment.costReport()` for
+ * exact, real sizes. See {@link CostReport}.
+ */
+export declare function estimateCost(input: EstimateInput): CostReport;
+/**
+ * **Grounded** report from a real segment byte total (from the `.crbm` index) + a supplied workload. Used by
+ * `Segment.costReport()` in the facade. `grounded` defaults to true (the size is exact, not estimated); the
+ * caller passes `grounded: false` + a note when the Storage source can't measure size.
+ */
+export declare function groundedReport(input: {
+    readonly storageBytes: number;
+    readonly grounded?: boolean;
+    readonly workload?: Workload;
+    readonly pricing?: PricingProfile;
+    readonly extraNotes?: readonly string[];
+}): CostReport;

package/dist/core/crbm/crc32c.d.ts

@@ -0,0 +1,10 @@
+/**
+ * CRC32C (Castagnoli, polynomial 0x1EDC6F41) — the pre-deserialize integrity screen for `.crbm`
+ * payloads, index, and footer.
+ *
+ * Pure TypeScript, table-driven: `core/` may not import `crypto`/`node:crypto` (the determinism lint
+ * enforces it), and a from-scratch implementation is what the cross-language golden corpus will be pinned
+ * against. CRC32C (not CRC32) is the locked choice — it matches the hardware-accelerated checksum used
+ * by SSE/iSCSI/Btrfs, and it is the algorithm the `.crbm` format locks in.
+ */
+export declare function crc32c(bytes: Uint8Array, seed?: number): number;

package/dist/core/crbm/format.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Frozen `.crbm` v1.0 layout constants.
+ *
+ * These byte widths/offsets are pinned by the golden corpus and must never change for v1 —
+ * a new layout is a new format version. All multi-byte integers are little-endian (v1 fixes LE).
+ */
+/** 4-byte magic at both file ends: "CRBM". */
+export declare const MAGIC: Uint8Array<ArrayBuffer>;
+export declare const VERSION_MAJOR = 1;
+export declare const VERSION_MINOR = 0;
+/** Front preamble: magic(4) + version_major(1) + version_minor(1) + reserved(2). */
+export declare const PREAMBLE_BYTES = 8;
+/** Payloads begin immediately after the preamble. */
+export declare const PAYLOAD_START = 8;
+/** Fixed footer size (v1.0). */
+export declare const FOOTER_BYTES = 104;
+/** Byte offsets of each field within the 104-byte footer. */
+export declare const FOOTER: {
+    readonly indexOffset: 0;
+    readonly indexLength: 8;
+    readonly indexCrc32c: 16;
+    readonly flags: 20;
+    readonly payloadCodecId: 24;
+    readonly elementWidth: 26;
+    readonly containerCodec: 27;
+    readonly versionMajor: 28;
+    readonly versionMinor: 29;
+    readonly reserved2: 30;
+    readonly generation: 32;
+    readonly indexNonce: 40;
+    readonly indexTag: 52;
+    readonly keyId: 68;
+    readonly chunkCount: 84;
+    readonly totalCardinality: 88;
+    readonly footerCrc32c: 96;
+    readonly endMagic: 100;
+};
+/** Footer bytes covered by `footer_crc32c` (everything before the CRC field). */
+export declare const FOOTER_CRC_COVERAGE: 96;
+/** `flags` bit positions. */
+export declare const FLAG_ENCRYPTED: number;
+export declare const FLAG_INDEX_COMPRESSED: number;
+export declare const FLAG_LITTLE_ENDIAN: number;
+/** Flag bits a v1 reader understands; any bit outside this mask is an unsupported feature. */
+export declare const KNOWN_FLAGS: number;
+/**
+ * Default element width: 32-bit ids (the u32 member space). `64` is the *reserved* escape above the
+ * ~4.29 B-ids/segment u32 ceiling; a v1 (32-bit) reader must **reject** a 64-bit generation rather than feed
+ * it to the 32-bit deserializer (which would mis-count fleet-wide). A future 64-bit generation is therefore a
+ * **major**-version bump (auto-rejected by old readers), never a silent minor one — see
+ * {@link CrbmReader.open} validates this.
+ */
+export declare const ELEMENT_WIDTH_32 = 32;
+/**
+ * **Which codec produced the chunk payloads.** Recorded in the footer, validated on read.
+ *
+ * `.crbm` is a shared container: the index, the CRC32Cs, the AEAD framing and the generation model are all
+ * codec-independent, and **only the chunk payload bytes belong to a flavor** (hence *Chunked Remote BitMap* —
+ * see the `.crbm` format section of the API reference). This field is what lets one container hold either, the same way ZIP tags each member
+ * with a compression method.
+ *
+ * **Why this is not named `roaringSerializationId` any more.** It was, and the name was a trap waiting for the
+ * `1.0` format freeze. A second codec is genuinely expected — `soaring` is a planned Roaring *variant*, so its
+ * serialized bytes are unlikely to be roaring-portable, and it lands *after* `1.0`. A field frozen under a
+ * codec-specific name cannot be reinterpreted later without a major format version, so generalizing it is a
+ * one-line change now and an expensive one after the freeze. The byte layout is untouched: same offset (24),
+ * same width (u16), same golden corpus.
+ *
+ * **Ids are permanent once published.** Add to {@link KNOWN_PAYLOAD_CODEC_IDS} when a codec ships; never
+ * reuse or renumber. Ids are deliberately *not* pre-allocated for codecs that do not exist — a reserved number
+ * for an unbuilt codec is a guess about a format nobody has designed.
+ */
+export declare const PAYLOAD_CODEC_ROARING_PORTABLE = 1;
+/**
+ * Every payload codec id this reader can decode.
+ *
+ * The reader validates membership rather than equality with a single constant. That is the whole point of the
+ * generalization: an unknown id is rejected with a typed error naming it, so an old reader meeting a
+ * future-codec generation **fails closed** — the correct direction, and the reason a store built on one codec
+ * can never silently misread another's bytes as its own. (The homogeneity contract means one store is one
+ * codec, so meeting a foreign generation implies misconfiguration, and a loud rejection is exactly what you
+ * want there.)
+ */
+export declare const KNOWN_PAYLOAD_CODEC_IDS: ReadonlySet<number>;
+/**
+ * The only container codec v1 defines: `0` = none (payloads are stored as the portable roaring serialization
+ * with no extra container-level transform). A non-zero codec is a future format feature; a v1 reader rejects
+ * it ({@link UnsupportedError}) rather than mis-decode. Stamped by the writer, validated by the reader.
+ */
+export declare const CONTAINER_CODEC_NONE = 0;
+/**
+ * Default speculative-tail-read size. The spec's worst-case index (a full 16-bit span) is ~400–650 KB,
+ * so 256 KB collapses the read to a single GET for the vast majority of real (sparse/medium) segments;
+ * only near-full-span segments take the documented second GET.
+ */
+export declare const DEFAULT_TAIL_BYTES: number;
+/**
+ * Hard cap on the index region a reader will fetch/parse from one (untrusted) object. The index is read
+ * whole on the cheap `open()`/`count()` path, so it must be bounded before allocation — generously
+ * above the ~650 KB full-span worst case, well below a denial-of-wallet allocation.
+ */
+export declare const DEFAULT_MAX_INDEX_BYTES: number;
+/** Hard cap on a single chunk payload, defending the native deserializer against oversized input. */
+export declare const DEFAULT_MAX_PAYLOAD_BYTES: number;
+/** A chunk's cardinality is in `[1, 65536]` (empty chunks are never written). */
+export declare const MAX_CHUNK_CARDINALITY = 65536;
+/** Fixed width of a per-chunk CRC32C field in the index (high-entropy → not varint). */
+export declare const CRC32C_BYTES = 4;
+/**
+ * v1 AEAD framing sizes (AES-256-GCM), fixed by the format exactly like the roaring serialization id — a
+ * different cipher is a new format version. An encrypted chunk payload is stored as `nonce ‖ ciphertext ‖ tag`;
+ * the encrypted **index**'s nonce/tag live in the footer's reserved `indexNonce`/`indexTag` slots. Matches
+ * {@link FOOTER.indexNonce} (12 B) and {@link FOOTER.indexTag} (16 B).
+ */
+export declare const AEAD_NONCE_BYTES = 12;
+export declare const AEAD_TAG_BYTES = 16;

package/dist/core/crbm/reader.d.ts

@@ -0,0 +1,69 @@
+import type { BlobReader } from '../blob.js';
+import type { CrbmCrypto } from '../crypto.js';
+export interface CrbmIndexEntry {
+    readonly chunkKey: number;
+    readonly offset: number;
+    readonly length: number;
+    readonly cardinality: number;
+    readonly crc32c: number;
+}
+export interface CrbmReaderOptions {
+    /** Speculative tail size in bytes (default 256 KB; clamped up to at least the footer size). */
+    readonly tailBytes?: number;
+    /** Hard cap on a single chunk payload length (default 16 MB). */
+    readonly maxPayloadBytes?: number;
+    /** Hard cap on the whole index region fetched/parsed from one object (default 8 MB). */
+    readonly maxIndexBytes?: number;
+    /** Decryption context for an encrypted object (its DEK's AEAD + AAD builder). Required iff `FLAG_ENCRYPTED`. */
+    readonly crypto?: CrbmCrypto;
+    /**
+     * Opaque marker for the *incarnation of the name* this object belongs to — the caller's own identity for the
+     * registry row it resolved. The reader never interprets it; it carries it so a caller holding an open reader
+     * can tell "the same generation of the same segment" from "the same generation NUMBER of a segment that was
+     * deleted and re-created", which the number alone cannot express.
+     */
+    readonly lineage?: unknown;
+}
+export declare class CrbmReader {
+    private readonly blob;
+    private readonly objectSize;
+    readonly generation: number;
+    /** See {@link CrbmReaderOptions.lineage} — carried, never interpreted. */
+    readonly lineage: unknown;
+    readonly totalCardinality: number;
+    private readonly entries;
+    private readonly orderedKeys;
+    /** True when `open()` satisfied the index from the tail GET alone (no second range read). */
+    readonly servedFromTail: boolean;
+    /** Set iff the object is encrypted — used to decrypt each chunk payload in {@link getChunk}. */
+    private readonly crypto;
+    private constructor();
+    /** Total object bytes (from the one-GET tail read) — for grounded storage cost. */
+    get sizeBytes(): number;
+    /**
+     * Estimated retained JS heap of this reader's parsed index — the weight the storage reader cache bounds on
+     * (a wide segment's parsed index, not its payloads, dominates the reader's footprint). `entries.size` scales with the number
+     * of resident chunks (≤ 65536), so this is `entries.size × {@link RETAINED_BYTES_PER_INDEX_ENTRY}`.
+     */
+    get retainedIndexBytes(): number;
+    /** Per-chunk cardinality (`chunkKey → count`) from the parsed index — no payload reads. */
+    cardinalities(): Map<number, number>;
+    static open(blob: BlobReader, options?: CrbmReaderOptions): Promise<CrbmReader>;
+    /** Chunk keys present in this generation, ascending. */
+    chunkKeys(): number[];
+    /** Segment cardinality from the footer (no payload reads) — the cheap `count()` path. */
+    count(): number;
+    has(chunkKey: number): boolean;
+    /**
+     * Range-GET one chunk's payload, verifying its CRC32C before returning. Returns `null` if the chunk is
+     * absent. Throws `IntegrityError` on a CRC mismatch (the bytes must never reach the native
+     * deserializer). The returned buffer is a **read-only view** owned by the reader/driver — callers must
+     * not mutate it.
+     */
+    getChunk(chunkKey: number): Promise<Uint8Array | null>;
+}
+export declare function parseIndex(indexBytes: Uint8Array, objectSize: number, maxPayloadBytes: number): {
+    entries: Map<number, CrbmIndexEntry>;
+    orderedKeys: number[];
+    cardinalitySum: number;
+};

package/dist/core/crbm/varint.d.ts

@@ -0,0 +1,13 @@
+/** Append the LEB128 encoding of a u32 `value` to `out`. */
+export declare function writeVarint(out: number[], value: number): void;
+export interface VarintRead {
+    readonly value: number;
+    /** Offset just past the bytes consumed. */
+    readonly next: number;
+}
+/**
+ * Decode a LEB128 varint from `bytes` starting at `offset`. Throws `IntegrityError` on a truncated or
+ * over-long (> 5-byte / > u32) encoding — the bytes are untrusted, so a malformed index must fail
+ * cleanly, never loop or overflow.
+ */
+export declare function readVarint(bytes: Uint8Array, offset: number): VarintRead;

package/dist/core/crbm/writer.d.ts

@@ -0,0 +1,39 @@
+import type { CrbmCrypto } from '../crypto.js';
+import type { BlobSink } from '../blob.js';
+export interface CrbmWriterOptions {
+    /** Self-describing generation number (also encoded in the object key). */
+    readonly generation: number;
+    /**
+     * Which codec produced the chunk payloads. Defaults to {@link PAYLOAD_CODEC_ROARING_PORTABLE}.
+     *
+     * Renamed from `roaringSerializationId` in 0.7.0 — same footer field, same offset and width, generalized
+     * because `.crbm` is a shared container and a second codec is expected before the format freezes.
+     */
+    readonly payloadCodecId?: number;
+    readonly elementWidth?: number;
+    /** When set, payloads + index are AES-256-GCM-encrypted, bound to `(segment, generation, scope)` via AAD. */
+    readonly crypto?: CrbmCrypto;
+}
+export declare class CrbmWriter {
+    private readonly sink;
+    private readonly options;
+    private readonly entries;
+    private offset;
+    private lastKey;
+    private totalCardinality;
+    private preambleWritten;
+    private finished;
+    constructor(sink: BlobSink, options: CrbmWriterOptions);
+    /**
+     * Append one chunk's payload (the roaring-serialized bytes) with its cardinality. `chunkKey` must be
+     * strictly greater than the previous one (ascending, no duplicates); `cardinality` is `[1, 65536]`.
+     */
+    addChunk(chunkKey: number, payload: Uint8Array, cardinality: number): Promise<void>;
+    /** Seal one chunk payload into the on-disk frame `nonce ‖ ciphertext ‖ tag`, bound to its chunkKey. */
+    private sealChunk;
+    /** Write the index region + the fixed footer. After this the object is complete and immutable. */
+    finish(): Promise<void>;
+    private ensurePreamble;
+    private encodeIndex;
+    private buildFooter;
+}