@cloudbitmaps/core 0.21.0 → 0.23.0

package/dist/core/absent-operands.d.ts

@@ -1,8 +0,0 @@
-/**
- * Throws {@link ValidationError} naming every one of `candidates` whose segment does not exist, asking `exists` of
- * each, at most `limit` at once, in their order. A streamed combine asks only after operands that hold no chunk at all;
- * the batch combine also asks after every operand it did not index (one no output names, or every operand when the range
- * is empty). `op` begins the message (`intersect`, `materializeMany`); `nameOf` is how the caller's operands are named
- * in it, each in double quotes. The first `exists` to reject rejects the call at once; none is asked after that.
- */
-export declare function refuseAbsent<T>(op: string, candidates: readonly T[], limit: number, exists: (candidate: T) => Promise<boolean>, nameOf: (candidate: T) => string): Promise<void>;

package/dist/core/bulk-load.d.ts

@@ -1,148 +0,0 @@
-/**
- * The loader `load()` is built on: ids, a decoded bitmap or a combine's chunks in, one generation written, and published
- * when a registry is wired and the caller does not defer it, as `load()` does to publish after its guard.
- */
-import { type IAuditSink } from './audit.js';
-import { ValidationError } from './errors.js';
-import type { Clock } from './determinism.js';
-import type { Aead, IKeystore, WrappedDek } from './crypto.js';
-import type { GenerationMetadata, GenKey, IStorageDriver, IRegistryDriver, RegistryRecord, RegistrySummary, SegmentRef } from './ports.js';
-import type { CodecInterface } from './codec.js';
-import { ChunkLoadInput, DecodedLoadInput } from './load-input.js';
-/** What a bulk-load wrote — the driver's `{ size, sha256 }` plus a summary of the built generation. */
-export interface BulkLoadResult {
-    /** Bytes written to the Storage object. */
-    readonly size: number;
-    /** The driver's content hash of the object. */
-    readonly sha256: string;
-    /** Distinct non-empty chunks written (≤ 65536). */
-    readonly chunkCount: number;
-    /**
-     * The DEK freshly minted for this generation, wrapped — present only when the segment is encrypted AND this
-     * call minted one (an existing segment reuses its key, which is already on the row).
-     *
-     * Returned so a caller that deliberately does **not** pass `registry` here — writing now and publishing later,
-     * which is how a load applies a guard while the old generation is still authoritative — can carry the key onto
-     * its own `publishGeneration`. Without it that publish stores no DEK and the generation it makes current is
-     * unreadable: the bytes are encrypted with a key nothing recorded.
-     */
-    readonly wrappedDeks?: readonly WrappedDek[];
-    /** Whether the object was written encrypted: under the segment's key, or under one this call minted. */
-    readonly encrypted: boolean;
-    /** The written object's fingerprint, which tells it from an object stored later under the same key. */
-    readonly fingerprint: string;
-    /** Total distinct ids in the generation (post-dedup). */
-    readonly cardinality: number;
-    /**
-     * The summary of what was written, for the write that makes it current: its id count and metadata, sealed under the
-     * segment's key when the object was written with one. A caller that defers the publish (`publish: false`) passes it
-     * to {@link publishGeneration}.
-     */
-    readonly summary: RegistrySummary;
-    /**
-     * Whether this generation is now the segment's **current** one — `undefined` when no `registry` was wired, so
-     * there is no pointer and no publish step to report on.
-     *
-     * `false` means the object is durable but a **concurrent writer published a higher generation first**, so this
-     * one is an orphan that no reader will ever resolve. The write succeeded and the *load* did not: whatever this
-     * call was asked to make the segment contain, the segment does not contain. That is not a detail a caller can
-     * be left to infer — a `*Into` materialisation that reported the generation it wrote as "the destination's new
-     * current generation" on this path would state a plain untruth — so the flag is on the result and the verbs that
-     * promise a published generation check it.
-     */
-    readonly becameCurrent?: boolean;
-}
-/**
- * **Bulk-load** a whole immutable generation from a flat id source — the batch "seed/rebuild" entry point.
- * Unlike {@link writeCrbmGeneration} (which takes pre-grouped bitmaps), this
- * consumes an arbitrary, **unsorted** stream of u32 ids (sync or async) and routes each into its chunk's
- * Roaring bitmap as it goes. The input is consumed lazily and ids dedup on insert, so memory is bounded by
- * the **built generation** — the in-memory Roaring representation of the *distinct* set (≤ one bitmap per
- * non-empty chunk) — not by the input length: you can stream a billion duplicate-heavy ids and hold only the
- * distinct result. Note this is `O(distinct set)`, **not** window-bounded like {@link SegmentEngine.intersect}:
- * bulk-load holds the whole generation in RAM, which suits batch seed/rebuild jobs but not an
- * unbounded-cardinality stream (a segment larger than RAM needs external-merge / pre-sorted input — later phase).
- *
- * Each id must be an integer in `[0, 2³²)` ({@link splitId} throws {@link ValidationError} otherwise) — the
- * source is consumed lazily, so a bad id aborts mid-stream without writing a partial object (the driver
- * commits only after the callback resolves). An empty source writes a valid empty generation.
- *
- * Writes a fresh full snapshot of a segment. The caller picks the generation number in `key` — `nextGeneration`
- * computes one from the registry and the bucket, as `nextLoadGeneration` does for a load — and re-using an existing
- * generation throws
- * {@link WriteConflictError} (write-once). Without a registry a `StorageChunkSource` serves the **highest**
- * generation present, so a too-high number silently shadows real data; with one, `publishGeneration` decides.
- */
-export declare function bulkLoadCrbmGeneration(driver: IStorageDriver, key: GenKey, ids: Iterable<number> | AsyncIterable<number> | DecodedLoadInput | ChunkLoadInput, options?: {
-    registry?: IRegistryDriver;
-    keystore?: IKeystore;
-    requireEncryption?: boolean;
-    audit?: IAuditSink;
-    /** Bitmap codec. Optional in the type; a **flavor** package binds it ({@link requireCodec}). */
-    codec?: CodecInterface;
-    /**
-     * Injected clock. Supplying one makes bulk-load **cooperative**: it yields the event loop periodically so a
-     * long load does not stall everything else on the process. Without it the load still completes, just
-     * without yielding — which is the pre-existing behaviour, kept so this is purely additive.
-     *
-     * `@cloudbitmaps/roaring` supplies a real clock by default, so flavor users get cooperative behaviour with
-     * no wiring. `core/` cannot default it: it is timer-free by lint, which is exactly why waiting goes through
-     * this seam rather than `setTimeout`.
-     */
-    clock?: Clock;
-    /**
-     * Write the object but do **not** advance the pointer (default: publish when a `registry` is wired).
-     *
-     * For a caller that has to inspect what it wrote before deciding whether it should become current — a
-     * guarded {@link loadSegment} is the one in-tree case — because the check is only meaningful while the old
-     * generation is still authoritative. The `registry` is still required for an encrypted segment and still
-     * consulted: it is where an existing segment's DEK lives, and reusing that key is not optional. The wrapped
-     * DEK comes back on the result so the deferred publish can store it.
-     *
-     * A caller that defers the publish owns what it wrote: an unpublished object sits ABOVE `currentGen`, where
-     * generation collection deliberately never looks, so nothing reclaims it until a later generation above it is
-     * current.
-     */
-    publish?: boolean;
-    /**
-     * The generation's metadata (see {@link GenerationMetadata}), written into the object and carried in the summary.
-     * The caller has checked it against the metadata rules; the writer checks it again, and refuses a record that breaks
-     * one before a byte is written.
-     */
-    metadata?: GenerationMetadata;
-    /**
-     * The segment's row as the caller already read it (`null`: it found none), for a caller that defers the
-     * publish (`publish: false`) and fences it on that same row. A present cleartext row is then used as read,
-     * rather than read again: a row that changes in between (a publish, a drop, a purge and re-create) makes the
-     * fenced publish lose, so the object is never published on the strength of the stale read. A row read as
-     * absent, or one carrying key material, is read again after the ids, as with no row passed: a first load must
-     * see a row another writer created meanwhile, and an encrypted segment's key is unwrapped only from a row read
-     * after the ids, so a segment shredded while they streamed is refused before its key is used.
-     */
-    row?: RegistryRecord | null;
-}): Promise<BulkLoadResult>;
-/**
- * What a load has already started when it calls {@link bulkLoadAhead}: its number, and the segment's data key, each
- * still in flight so their round trips overlap the encoding. Both are joined where the write needs them, and neither
- * may be left to reject unobserved.
- */
-interface LoadAhead {
-    /** The number the generation takes (see {@link nextLoadGeneration}); joined just before the object is written. */
-    readonly generation: PromiseLike<number>;
-    /**
-     * The key a caller already asked the keystore to unwrap, with the wrappings it asked about. Used only when the
-     * row the write reads after the ids carries exactly these wrappings; otherwise the write unwraps for itself.
-     */
-    readonly unwrapped?: {
-        readonly wrapped: readonly WrappedDek[];
-        readonly aead: PromiseLike<Aead>;
-    };
-}
-/** What a load with `requireEncryption` meets on a segment that already has a cleartext generation. */
-export declare function cleartextUnderRequiredEncryption(ref: SegmentRef, currentGen: number): ValidationError;
-/**
- * {@link bulkLoadCrbmGeneration} for a load whose number, and perhaps its key, are still being fetched: the same
- * options, with the same meaning, and the same writes. The number is joined only where the object is written.
- */
-export declare function bulkLoadAhead(driver: IStorageDriver, ref: SegmentRef, ahead: LoadAhead, ids: Parameters<typeof bulkLoadCrbmGeneration>[2], options?: NonNullable<Parameters<typeof bulkLoadCrbmGeneration>[3]>): Promise<BulkLoadResult>;
-export {};

package/dist/core/cas-retry.d.ts

@@ -1,27 +0,0 @@
-import type { WriteConflictError } from './errors.js';
-import { type ChurnDeps } from './leases.js';
-import type { IRegistryDriver, RegistryRecord, SegmentRef } from './ports.js';
-/** What `casRetry` needs: the registry, and the clock and rng that spread a wait out. */
-type CasRetryDeps = ChurnDeps & {
-    readonly registry: IRegistryDriver;
-};
-/** How many attempts a caller gets, and the error it throws once they are spent. */
-interface CasRetryPlan {
-    /** Attempts that count; a wait out of lease churn does not use one. */
-    readonly attempts: number;
-    /** The error thrown when every attempt lost. */
-    readonly contention: () => WriteConflictError;
-}
-/**
- * Read a segment's row, run `step` on it, and run it again on a fresh read when `step` throws a write conflict.
- *
- * Every lost race uses one of `plan.attempts`, except one lost by a run that followed a wait. When the row read after a
- * lost race differs from the one `step` was given only in its leases, the loop waits the churn out (up to the churn
- * bound), reads the row again and runs `step` against that without using an attempt. A race lost on the last attempt
- * is not waited out. `step` returns the caller's result, or throws: a write conflict retries, anything else leaves
- * `casRetry` untouched.
- *
- * Exhausting `attempts` throws `plan.contention()`.
- */
-export declare function casRetry<T>(deps: CasRetryDeps, ref: SegmentRef, plan: CasRetryPlan, step: (row: RegistryRecord | null) => Promise<T>): Promise<T>;
-export {};

package/dist/core/chunk-checks.d.ts

@@ -1,39 +0,0 @@
-import type { CodecBitmap, CodecInterface } from './codec.js';
-/**
- * Tier-derived keys are untrusted (invariant 5) — fail fast on a corrupt/out-of-range key rather than
- * letting it flow into the id-routing step and produce a bogus id.
- */
-export declare function assertChunkKeyInRange(k: number): void;
-/** A chunk holds at least one id and at most {@link CHUNK_COUNT}; a count outside that came from a corrupt tier. */
-export declare function assertChunkCardinalityInRange(c: number): void;
-/**
- * A segment's chunk keys, ascending — a shape read off the index, no payload. Keys are untrusted (invariant 5): each is
- * an integer in `[0, CHUNK_COUNT)` and none repeats. One pass range-checks every key and notes whether the list is
- * already strictly ascending, which an index read off a `.crbm` always is; only a list that is not is sorted and scanned
- * for a repeat. The caller gets a list of its own.
- */
-export declare function checkedChunkKeys(listed: Iterable<number>): number[];
-/**
- * The other half of invariant 5: a chunk payload holds **remainders** — 16-bit offsets within one chunk — so
- * every value must be `<= 0xffff`.
- *
- * Nothing upstream establishes that. The byte cap bounds *size*, and CRC/AEAD prove the bytes are the bytes
- * that were written — which anyone able to write the bucket satisfies trivially. A value `>= 65536` would then
- * reach the id-routing step, which masks it (`remainder & 0xffff`) and emits a **fabricated id belonging to a different
- * chunk's id space**: indistinguishable from real data, inflating `count()` and creating spurious `intersect`
- * matches.
- *
- * Costs one `maximum()` per chunk, not per id — `maximum` is optional on the codec seam precisely so a codec
- * that cannot answer in O(1) opts out instead of making the read path walk every value.
- *
- * One value stands for all of them only because the decode is structurally checked. Roaring answers `maximum()`
- * from its last container, so a payload listing its containers out of order would report the wrong one's
- * largest value and pass here while holding values above 65,535. The codec's `safeDeserialize` refuses that
- * payload, and every other shape that would make this answer wrong, before it reaches this check.
- */
-export declare function assertChunkPayloadInRange(bitmap: CodecBitmap, chunkKey: number): void;
-/**
- * A chunk's stored bytes decoded under the size cap (invariant 5) and range-checked: the one place a chunk becomes a
- * bitmap, whether its bytes came from a request of its own or from a stream of coalesced ranges.
- */
-export declare function decodeChunkBytes(codec: CodecInterface, bytes: Uint8Array, chunkKey: number, maxBitmapBytes: number): CodecBitmap;

package/dist/core/chunk-stream.d.ts

@@ -1,22 +0,0 @@
-import type { ChunkRead } from './ports.js';
-/**
- * One operand's chunks as the source streams them, taken a key at a time. The engine asks for keys in ascending order
- * and the stream yields them in that order, so each `take` is the next item; `take` calls the iterator at once, before
- * anything is awaited, which is what keeps concurrent takes lined up with the keys they were made for (an async
- * generator answers overlapping `next()` calls in the order they were made).
- *
- * A stream that fails fails every take after the one that met it with the same error, and a stream that ends before the
- * key asked for, or answers another key, is an {@link IntegrityError}: a source that misaligns its answers must not
- * hand one chunk's bytes to another key.
- *
- * Internal to core: not exported from any entry point.
- */
-export declare class ChunkStream {
-    private readonly iterator;
-    private failure;
-    constructor(stream: AsyncIterable<ChunkRead>);
-    /** The chunk for `key`, which must be the next key the stream was opened over. */
-    take(key: number): Promise<ChunkRead>;
-    /** Stop the stream: no further range is started, and ranges already in flight finish and are dropped. */
-    close(): void;
-}

package/dist/core/chunk-window.d.ts

@@ -1,37 +0,0 @@
-/**
- * An ordered window of reads: up to `max` reads open ahead of the one being consumed, handed back in key order.
- * With `ramp`, the window opens 1, 2, 4 … wide (or at `rampStart`, then doubling) up to `max` instead of `max` at once, so a consumer that stops
- * after a few chunks has fetched a handful, not a full window.
- *
- * `T` is whatever one read yields (a decoded chunk, or the raw bytes of one), and `K` what names a read to launch: a
- * chunk key, or a planned range. The reads to launch are a list, or an iterator pulled from only as the window opens
- * a read, so a long plan is never made ahead of what the window can hold. Each read is wrapped to resolve and
- * never reject, so a read nobody consumes (the consumer stopped, or an earlier chunk failed) cannot raise an
- * unhandled rejection; its error surfaces from {@link take} only if the consumer reaches that chunk. Memory is
- * bounded by the window: at most `max` results are held ahead.
- *
- * Internal to core: not exported from any entry point.
- */
-export declare class ChunkWindow<T, K = number> {
-    private readonly fetch;
-    private readonly max;
-    private readonly ramp;
-    /** With `ramp`, the width the window opens at (default 1). */
-    private readonly rampStart;
-    private readonly open;
-    private launched;
-    private taken;
-    private readonly list;
-    private readonly source;
-    /** What the source threw, so a later {@link take} throws it again rather than reading the spent source as done. */
-    private failure;
-    constructor(keys: readonly K[] | Iterator<K>, fetch: (key: K) => Promise<T>, max: number, ramp: boolean, 
-    /** With `ramp`, the width the window opens at (default 1). */
-    rampStart?: number);
-    /** The next read to launch, or {@link DONE} when there is none. */
-    private nextKey;
-    /** Resolves once every read launched and not yet taken has settled; it never rejects, as the reads never do. */
-    settle(): Promise<void>;
-    /** The next read's result in key order, or the error that read raised. */
-    take(): Promise<T>;
-}

package/dist/core/combine-ledger.d.ts

@@ -1,43 +0,0 @@
-/**
- * The resident-bytes ledger of a batch combine. Pure: no I/O, time or randomness.
- *
- * It counts what is **resident**, not what a bitmap serializes to: a native bitmap costs a fixed amount over its
- * serialized bytes, so a million small chunks hold far more than their serialized size says. Measured on the shipped
- * codec with one bitmap per chunk, the cost over serialized size was about 440 bytes for a chunk of up to 50 ids,
- * rising to about 1,700 bytes around 3,000 ids (an array container's spare capacity) and falling to about 300 bytes for
- * a bitset. {@link residentBytes} is a model that stays above every measured point.
- */
-/**
- * The fixed resident cost of one native bitmap beyond its serialized bytes. Measured on the shipped codec, over 50,000
- * bitmaps of one chunk each, it was 430 to 450 bytes for a chunk of up to 50 ids on macOS (arm64) and 357 to 373 on Linux
- * (arm64, glibc 2.36), and 279 to 433 for a bitset; the constant sits above the highest of those.
- */
-export declare const RESIDENT_BITMAP_OVERHEAD = 512;
-/** An upper bound on the serialized size of a chunk of `cardinality` ids: an array container, capped at a bitset. */
-export declare function serializedBound(cardinality: number): number;
-/** The resident bytes of one bitmap whose serialized size is `serialized`: above every measured point. */
-export declare function residentBytes(serialized: number): number;
-/** The resident bytes of one chunk of at most `cardinality` ids. */
-export declare function residentBound(cardinality: number): number;
-/**
- * A byte budget with a high-water mark. Everything the pass keeps resident is charged to it and released when it is
- * let go, so `used` is the pass's own count of what it holds, and `maxBufferedBytes` is a bound on it.
- */
-export declare class ResidentLedger {
-    readonly limit: number;
-    private held;
-    private peak;
-    constructor(limit: number);
-    get used(): number;
-    get highWater(): number;
-    /** Bytes still free. */
-    get room(): number;
-    /** Charge `bytes` if they fit. */
-    tryCharge(bytes: number): boolean;
-    /**
-     * Charge `bytes`, asking `makeRoom` to free some while they do not fit. `makeRoom` releases what it frees (through
-     * {@link release}) and answers whether it freed anything; the charge is refused when it cannot.
-     */
-    reserve(bytes: number, makeRoom: () => boolean): boolean;
-    release(bytes: number): void;
-}

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

@@ -1,10 +0,0 @@
-/**
- * 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/fingerprint.d.ts

@@ -1,23 +0,0 @@
-/** What names an object: its size, then its footer's CRC. One spelling, for an open reader and a footer read alone. */
-export declare const sizePart: (size: number) => string;
-/** An object's fingerprint, from its size and its footer's CRC (see `CrbmReader.fingerprint`). */
-export declare const fingerprintFor: (size: number, footerCrc: number) => string;
-/**
- * A fingerprint taken apart, or `undefined` for text that is not one an object can have: a size that is a safe integer
- * no smaller than a `.crbm` preamble and footer, and a footer CRC that fits in 32 bits. For a row's summary, which
- * names its object by it and reports the size from it.
- */
-export declare function fingerprintParts(fingerprint: unknown): {
-    readonly size: number;
-    readonly footerCrc: number;
-} | undefined;
-/**
- * The footer CRC of a fingerprint a writer or a reader produced, which a row's ledger records beside the generation.
- * Throws {@link IntegrityError} for text that is not a fingerprint, which neither produces.
- */
-export declare function footerCrcOf(fingerprint: string): number;
-/**
- * A fingerprint spelled short, for a key a read builds on every chunk: its size and its footer's CRC in base 36,
- * `<size>.<crc>`. Two compact spellings are equal exactly when the fingerprints are.
- */
-export declare function compactFingerprint(fingerprint: string): string;

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

@@ -1,150 +0,0 @@
-/**
- * Frozen `.crbm` v1 layout constants (format 1.0, with its optional extension block).
- *
- * 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).
- */
-import { FOOTER_BYTES, PREAMBLE_BYTES } from './frame.js';
-/** 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;
-export { FOOTER_BYTES, PREAMBLE_BYTES };
-/** Payloads begin immediately after the preamble. */
-export declare const PAYLOAD_START = 8;
-/** 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_LITTLE_ENDIAN: number;
-/**
- * The object carries an extension block just before its index (a generation's metadata). Set only when there is
- * something to put in it, so an object without metadata is the same bytes as before the block existed; a reader that
- * does not know the bit refuses the object rather than reading past what it cannot see.
- */
-export declare const FLAG_EXTENSION: 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.
- *
- * **A codec id, not a roaring-specific one.** 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* the `1.0`
- * format freeze. A field frozen under a codec-specific meaning could not be reinterpreted later without a major
- * format version.
- *
- * **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 an
- * id registry: 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;
-/**
- * Largest serialized bitmap the engine decodes (1 MiB, per chunk). A well-formed 16-bit chunk serializes to at most
- * about 8.2 KiB, so no legitimate chunk is near it; both the read engine and the erase path decode under this one cap.
- */
-export declare const DEFAULT_MAX_BITMAP_BYTES: number;
-/** A chunk's cardinality is in `[1, 65536]` (empty chunks are never written). */
-export declare const MAX_CHUNK_CARDINALITY = 65536;
-/**
- * The extension block, present when the footer sets {@link FLAG_EXTENSION}: `section* ‖ u32 sectionsLength ‖ u32
- * crc32c ‖ "CRBX"`, between the last payload and the index, so the index starts right after it. A reader finds it from
- * `indexOffset`: the trailer is the {@link EXT_TRAILER_BYTES} bytes before the index, and the CRC32C covers the sections
- * and the length field. Each section is `u8 type ‖ u32 length ‖ bytes`, in strictly ascending type order; a reader
- * skips a type it does not know, so a section must be safe to ignore.
- */
-export declare const EXT_MAGIC: Uint8Array<ArrayBuffer>;
-/** The trailer: the sections' length (u32), their CRC32C (u32) and {@link EXT_MAGIC}. */
-export declare const EXT_TRAILER_BYTES = 12;
-/** A section's header: its type (u8) and its length (u32). */
-export declare const EXT_SECTION_HEADER_BYTES = 5;
-/**
- * Cap on the sections of one block, in bytes. A reader refuses a larger block from its trailer alone, before it reads
- * any sections beyond what it already holds (the read that brings the index may already hold up to this much before
- * it), and a writer of any 1.x minor keeps within it, so a later section type stays readable by this reader.
- */
-export declare const MAX_EXT_BYTES: number;
-/**
- * Section type 1: the generation's metadata, its canonical JSON in UTF-8. On an encrypted object the section is
- * `nonce ‖ ciphertext ‖ tag`, sealed under the segment's key with the metadata scope of the associated data.
- * Type 0 is not a section type: a reader refuses it.
- */
-export declare const EXT_SECTION_METADATA = 1;
-/** 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 payload codec 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;
-/**
- * Hard cap on one encrypted chunk's stored payload (a cleartext one is capped at the decode cap): the decode cap plus the AEAD framing, so an
- * entry the engine would refuse to decode is refused when the object is opened, before any payload is read. No writer
- * exceeds it: a stored payload is a serialized 16-bit chunk (at most about 8.2 KiB) plus, when encrypted, that framing.
- */
-export declare const DEFAULT_MAX_PAYLOAD_BYTES: number;

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

@@ -1,10 +0,0 @@
-/**
- * The two widths every `.crbm` v1 object is framed by: its front preamble and its footer. Frozen with the rest of the
- * layout in `format.ts`, which re-exports them. They live in a module of their own, with no imports, so that what needs
- * only the smallest size an object can have (the registry's check of a summary's fingerprint) does not bring the
- * format's other constants, or the reader, with it.
- */
-/** Front preamble: magic(4) + version_major(1) + version_minor(1) + reserved(2). */
-export declare const PREAMBLE_BYTES = 8;
-/** Fixed footer size (v1.0). */
-export declare const FOOTER_BYTES = 104;

package/dist/core/crbm/plan-reads.d.ts

@@ -1,50 +0,0 @@
-/**
- * The most unneeded bytes one read may carry between two needed chunks: reading 256 KiB that nothing wants costs
- * a few milliseconds of transfer, while the request it saves costs a round trip.
- */
-export declare const MAX_COALESCE_GAP_BYTES: number;
-/**
- * The most bytes one read may span, unless it holds a single chunk. It equals the decode cap, so a window of
- * coalesced reads holds the window's width times the per-chunk cap that bounds a window of single-chunk reads.
- */
-export declare const MAX_COALESCED_READ_BYTES: number;
-/**
- * The default number of range reads a chunk stream holds ahead of its consumer, in flight or landed and not yet taken;
- * the rest of the plan follows as the consumer takes them. A range is at most {@link MAX_COALESCED_READ_BYTES} unless
- * it is one chunk, so a stream holds at most this many times the per-chunk decode cap, whatever the key list and the
- * object: the memory bound a window of single-chunk reads has, and no more connections than it opens.
- */
-export declare const MAX_RANGES_IN_FLIGHT = 32;
-/** One needed chunk, as its index entry places it in the object. */
-export interface ChunkExtent {
-    readonly key: number;
-    readonly offset: number;
-    readonly length: number;
-}
-/** One byte range to read, and the needed chunks inside it, in object order. */
-export interface PlannedRead {
-    readonly offset: number;
-    readonly length: number;
-    readonly chunks: readonly ChunkExtent[];
-}
-/** The part of an object that holds chunk payloads: `[start, end)`. */
-export interface ChunkRegion {
-    readonly start: number;
-    readonly end: number;
-}
-/**
- * Plan the reads for `extents`: the needed chunks of one object, ascending by offset (the index lists chunks in key
- * order, which is object order), each at least a byte long, none overlapping another. The reads come out ascending
- * and disjoint, each covering one or more of the chunks, every chunk in exactly one read.
- *
- * Lazy: the plan is a walk, so a consumer that takes the first reads pulls only the extents those reads cover (and
- * the one after, which closes the last of them), and a plan over a very wide object costs nothing until it is read.
- * Each extent is checked as the walk reaches it, before the read that would carry it is handed out, so no read ever
- * covers an extent that was not checked; a plan taken to its end has checked them all. The reads are exactly the ones
- * a plan made all at once would hold, in the same order.
- *
- * Throws {@link IntegrityError} for an extent that is not a pair of safe integers, or is outside `region`, or out of
- * order, or overlapping the one before it:
- * the index a plan is made from is untrusted bytes, and a read is never planned outside the chunk region.
- */
-export declare function planChunkReads(extents: Iterable<ChunkExtent>, region: ChunkRegion): Generator<PlannedRead, void, undefined>;

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

@@ -1,14 +0,0 @@
-/** Append the LEB128 encoding of a u32 `value` to `out`. */
-export declare function writeVarint(out: number[], value: number): void;
-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;
-export {};