@cloudbitmaps/core 0.20.0 → 0.22.0

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

@@ -1,30 +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). 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> {
-    private readonly keys;
-    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;
-    constructor(keys: readonly number[], fetch: (chunkKey: number) => Promise<T>, max: number, ramp: boolean, 
-    /** With `ramp`, the width the window opens at (default 1). */
-    rampStart?: number);
-    /** 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,18 +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;
-/**
- * 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,151 +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_INDEX_COMPRESSED: 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,44 +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 back
- * ascending and disjoint, each covering one or more of the chunks, every chunk in exactly one read.
- *
- * 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: readonly ChunkExtent[], region: ChunkRegion): readonly PlannedRead[];

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

@@ -1,13 +0,0 @@
-/** 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

@@ -1,68 +0,0 @@
-import type { CrbmCrypto } from '../crypto.js';
-import type { GenerationMetadata } from '../ports.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}.
-     *
-     * A codec id rather than a roaring-specific one, 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;
-    /**
-     * The generation's metadata, checked against the metadata rules and copied as its canonical JSON when the writer
-     * is constructed, so a later change to the caller's object never reaches the object. A value that breaks a rule
-     * throws {@link ValidationError} from the constructor, before a byte is written. None, or the empty object, writes
-     * format 1.0.
-     */
-    readonly metadata?: GenerationMetadata;
-}
-export declare class CrbmWriter {
-    private readonly sink;
-    private readonly options;
-    private readonly entries;
-    private offset;
-    private lastKey;
-    private totalCardinality;
-    private preambleWritten;
-    private finished;
-    /** The metadata's canonical JSON, copied at construction; `undefined` leaves the footer's extension flag clear. */
-    private readonly metadata;
-    /** Bytes written so far, the footer included once {@link finish} has run. */
-    private written;
-    private footerCrc32c;
-    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>;
-    /**
-     * Write the extension block (when there is metadata), the index region and the fixed footer. After this the object
-     * is complete and immutable.
-     */
-    finish(): Promise<void>;
-    /**
-     * The finished object's size and its footer's CRC: what names it, as a reader's fingerprint does. A writer that
-     * has to tell its own object from another stored later under the same key compares these with the object's
-     * footer. Throws before {@link finish}.
-     */
-    get identity(): {
-        readonly size: number;
-        readonly footerCrc: number;
-    };
-    private ensurePreamble;
-    /**
-     * The extension block: one metadata section (`u8 type ‖ u32 length ‖ bytes`), then the trailer
-     * (`u32 sectionsLength ‖ u32 crc32c(sections ‖ sectionsLength) ‖ "CRBX"`). Encrypted, the section holds
-     * `nonce ‖ ciphertext ‖ tag`, sealed with the metadata scope of the associated data.
-     */
-    private extensionBlock;
-    private encodeIndex;
-    private buildFooter;
-}

package/dist/core/due-index.d.ts

@@ -1,53 +0,0 @@
-import { MAX_NAME_LENGTH } from './validate.js';
-import type { RegistryRecord, SegmentRef } from './ports.js';
-/** Bucket width. One day: small enough that a cycle reads little, coarse enough that the index stays tiny. */
-export declare const DUE_BUCKET_MS = 86400000;
-/**
- * The name-length cap, and an index row encodes **both** of the original ref's parts into one name — so a ref
- * whose encoding would exceed it is simply not indexed (see {@link canIndex}).
- *
- * Re-exported from the validator rather than restated. The two were separate constants with the same value
- * until the validator started measuring the **encoded** length; `canIndex` went on counting raw characters and
- * began answering `true` for refs the registry then refused, turning a documented graceful degradation into a
- * guaranteed throw on the retention fast path.
- */
-export { MAX_NAME_LENGTH };
-/** Which bucket an expiry falls in. Total and reversible; no calendar, no timezone, no ambient time. */
-export declare function dueBucket(expiresAt: number): number;
-/** The namespace holding one bucket's pointers. */
-export declare function dueNamespace(bucket: number): string;
-/** Is this record a due-index pointer rather than a segment? */
-export declare function isDueIndexRow(record: Pick<RegistryRecord, 'namespace'>): boolean;
-/**
- * Encode a ref into one index-row name, unambiguously.
- *
- * `${namespaceLength}.${namespace}${segment}` — a decimal length, a dot, then the two parts concatenated. The
- * length prefix is what makes it reversible: a name may contain any character, the dot included, so no
- * separator character could ever be unambiguous on its own. Reading the digits
- * up to the first dot tells the parser exactly where the namespace ends.
- */
-export declare function encodeDueName(ref: SegmentRef): string;
-/**
- * Can this ref be indexed at all? False when the encoded name would exceed the 256-character name cap —
- * possible only for a ref whose namespace and segment are together near the limit.
- *
- * **Not indexable is not "not retired".** The repair scan still sees the segment's own row, so the consequence
- * is that it expires on the repair cadence instead of the fast one. Callers must not treat `false` as an error.
- */
-export declare function canIndex(ref: SegmentRef): boolean;
-/** The registry ref of the pointer for `ref` in `bucket`. Throws if the ref cannot be encoded — check first. */
-export declare function dueIndexRef(bucket: number, ref: SegmentRef): SegmentRef;
-/**
- * Recover the original ref from an index row's name. `null` for anything we did not write — a foreign row in
- * the reserved namespace is ignored rather than acted upon.
- */
-export declare function decodeDueName(name: string): SegmentRef | null;
-/**
- * Which buckets a cycle must read at `now`: everything from `since` up to and including the current one.
- *
- * Past buckets are included because a sweep that did not run — a scaled-to-zero worker, a failed deploy, a
- * paused schedule — must not leave its buckets stranded. `lookbackBuckets` bounds how far back a first run
- * reaches, so a long outage costs a bounded number of list calls per cycle rather than one per day since the
- * epoch; anything older is the repair scan's job.
- */
-export declare function dueBucketsAt(now: number, lookbackBuckets: number): number[];

package/dist/core/generation-gc.d.ts

@@ -1,179 +0,0 @@
-import type { GenKey, IStorageDriver, IRegistryDriver, RegistryRecord, SegmentRef, Token } from './ports.js';
-/** The two ports generation bookkeeping needs: the objects, and the pointer that says which one is current. */
-export interface GenerationDeps {
-    readonly storage: IStorageDriver;
-    readonly registry: IRegistryDriver;
-}
-/**
- * The generation number a writer should use for the segment's **next** object: one above the highest generation
- * the registry points at *or* that is present in Storage — whichever is higher. The erasure rewrite numbers this
- * way; a load numbers with {@link nextLoadGeneration}, which lists as this does when its existence check finds the
- * number taken or cannot answer.
- *
- * Both are consulted because they can disagree. A load that wrote its object and crashed before publishing leaves
- * an object *above* `currentGen`; a writer that consulted only the pointer would pick that same number and hit the
- * write-once conflict on every retry. Skipping past it costs one `list` and keeps the retry trivial — the crashed
- * object is an orphan {@link gcOrphanGenerations} collects once the pointer moves on. Reusing such an object
- * instead of skipping it (verify-and-publish) is `load()`'s job, not a numbering helper's.
- *
- * A segment with no row and no objects starts at 0. An admin/write-path helper, never on the read path.
- */
-export declare function nextGeneration(ref: SegmentRef, deps: GenerationDeps): Promise<number>;
-/** The number a load takes, and whether one existence check proved it free (so nothing is above the pointer). */
-export interface LoadNumber {
-    readonly generation: number;
-    /**
-     * `true` when the number is `currentGen + 1` and the check found no object holding it. Collection by name rests
-     * on it: the row named `generation - 1` as current, so every number the window evicts is below it, and nothing
-     * the listing would have kept is a name the pass takes. `false` when the listing numbered the load.
-     */
-    readonly checked: boolean;
-}
-/**
- * The generation number a load takes, from the row it has already read: `currentGen + 1` (0 with no row or no
- * pointer yet) when no object holds that number, which one existence check proves (a zero-byte `getTail`, one
- * metadata request on every shipped driver); otherwise one above the pointer and above everything listed, as
- * {@link nextGeneration} numbers. The check finding the number taken (a crashed load's orphan, the object of a
- * load still in flight, or the generations a rollback left above the pointer) and the check failing in any way
- * other than "not found" both take the listing, so the listing stays the authority whenever the check cannot
- * prove the number free. A failed check falls back silently: nothing records it, and what it costs is the listing,
- * one more PUT-class request on S3, so a fault that makes every check fail shows only in the bill.
- *
- * A load can therefore take a number **below** an object already in the bucket: an orphan at `currentGen + 2`
- * with `currentGen + 1` free is numbered under, not past. That is as safe as a listing's number. A load never
- * takes a number an object holds, and a put that races onto one fails write-once, so the load reports
- * `superseded`. The orphan above stays unpublished; the load whose check meets it numbers past it by the listing,
- * and collection takes it once a generation above it is current. Like a listing's, the number can be one whose
- * object was deleted (an erasure removes the generations above a rolled-back pointer that held the id), which is
- * why nothing identifies a generation by its number alone: the reader cache and the chunk cache key on the number and
- * the row's `pointerId`, which every write that takes a number again renews, and an open of a row with a usable
- * summary holds the object to the fingerprint the summary records; a pin keys on its object's fingerprint.
- */
-export declare function nextLoadGeneration(ref: SegmentRef, deps: GenerationDeps, row: RegistryRecord | null): Promise<LoadNumber>;
-/**
- * How often a load that could collect by name lists instead: every generation divisible by this. A name-only pass
- * takes the names its publish pushed out of the row's window and never looks at the rest, so what it misses (a crashed
- * or refused load's object, a delete that failed, extras a fault left after a `keep` that shrank, an object a rollback
- * or an erasure left stranded below the pointer) waits for a listing. The number is a generation's, not a clock's, so the choice needs
- * no state and no time, and a segment that loads cleanly lists once in this many loads at most. The bound is in
- * generation numbers: a rollback moves the pointer down, and the loads that then take the numbers above it count
- * from there.
- */
-export declare const LIST_COLLECTION_CADENCE = 16;
-/**
- * Garbage-collect superseded Storage generations for a segment: everything strictly below `currentGen`, keeping
- * the most recent `keep` of them as a grace window, so a read still fetching from a just-superseded
- * generation need not re-resolve mid-call (**invariant 4**). It is a window, not a lock: a read whose
- * generation is swept anyway re-resolves and retries once rather than failing (see `withFreshSnapshot`), so
- * `keep` trades storage for round trips. Generations ≥ `currentGen` are never touched. Returns the generations
- * deleted.
- *
- * **Except on a `destroyed` segment, where EVERY generation is garbage** and the grace window is meaningless.
- * A tombstoned segment resolves no generation for any reader, pinned or not — a pin cannot be taken on one, and
- * a pin taken while it was still active re-checks the status on every open — and nothing else in the library
- * would ever collect them, so without this those objects are billed forever.
- *
- * **Throws {@link WriteConflictError} when it cannot act on the row it read**: the row is gone when it is re-read,
- * after the listing or before a delete; on an active segment, the pointer has fallen below the cutoff before a
- * delete; on a `destroyed` segment, the row's token has changed. Not to be confused with the empty array it still
- * returns when there was genuinely nothing to collect (no row at all, or no pointer yet), which is why an empty
- * array is not a receipt. The row is read before the listing and acted on after it, so a name that was purged and
- * re-created in that window is a *different* segment wearing the same name, and its live object must not be
- * collected on the strength of the old row: on an active segment the lower of the two pointers is what keeps it
- * safe, and on a `destroyed` one the token. Refusing is safe — the objects are not going anywhere and the next
- * pass reads a consistent row — but it has to be **distinguishable** from "there was nothing to collect", which
- * an empty array is not: `eraseIdFromSegment` reads the returned list as the physical half of its erasure
- * receipt, and would otherwise report `erased: true` over bytes still in the bucket. Re-run it.
- *
- * That state is reachable in practice: a `dropSegment` whose Storage sweep threw part-way, or a load that had read
- * the row before the tombstone landed, wrote its object afterwards, and stopped before its refusal deleted it. `dropSegment` re-sweeps
- * and reports whatever it could not reclaim in `generationsRemaining`, but a drop that was never re-run leaves a
- * residual, and this is what eventually collects it from the retention sweep.
- *
- * `keep: 0` is how a subject-erasure rewrite makes a bit **physically** gone on return: the generation that held
- * it is collected the moment the rewrite is current. A live read still fetching from it heals forward to the
- * rewrite, and a pin of it (`seg.pin()`) fails with `NotFoundError` for any chunk it has yet to read.
- */
-export declare function gcOrphanGenerations(ref: SegmentRef, deps: GenerationDeps, options?: {
-    keep?: number;
-}): Promise<number[]>;
-/**
- * What makes a collection spare leased generations: the clock that says whether a lease has ended. Only a load's
- * collection passes one, and a load with no clock passes none: it cannot tell a live lease from an ended one, so it
- * reads none. A pass without a guard never reads the row's leases, which is what keeps erasure, shred and drop deleting
- * what a lease names.
- */
-export interface LeaseGuard {
-    readonly now: () => number;
-}
-/** What a load's publish recorded in the row, as `publishGeneration` reports it. */
-export interface PublishedKept {
-    /** The list the publish wrote, or `undefined` when it wrote none (the row then does not know which are kept). */
-    readonly list: readonly number[] | undefined;
-    /** The names the publish pushed out of the window, ascending. */
-    readonly evict: readonly number[];
-    /** The token of the row the publish wrote, when it is known: a write settled by reading the row has none. */
-    readonly token: Token | undefined;
-}
-/**
- * Collect after a load's publish. The row records the generations the load keeps, so the pass deletes by name what the
- * publish pushed out of that window ({@link deleteEvicted}) and lists the segment ({@link gcOrphanGenerations}'s
- * pass) only when it cannot rely on the row or must catch what a name does not:
- *
- *  - the row recorded no list (a `keep` above {@link MAX_KEPT_GENERATIONS}, a row an earlier schema wrote, one a
- *    rollback or an erasure moved, or a publish whose write was settled by reading the row): the pass keeps the
- *    newest `keep` generations present below the pointer, and records them with one compare-and-swap, fenced on the
- *    publish's own token, so the next load collects by name;
- *  - the guard found the current generation's object gone, or, for a `keep` of 1 or more when the guard took the size
- *    from the row's summary and opened nothing, one zero-byte read of it does not find it (`proveCurrent`): the
- *    window then counts a generation that is not there, so the same pass keeps what is;
- *  - a number the listing chose (something sits above the pointer, or the existence check could not answer), a
- *    caller that asks for a listing, and every {@link LIST_COLLECTION_CADENCE}th generation: the pass deletes every
- *    generation below the pointer the row does not name, which collects what a name-only pass leaves.
- *
- * It makes no request when `keep` is at least the generation published, since no more generations than that exist
- * below it. A load onto a `destroyed` row is refused at its publish and never reaches here; a drop that lands after
- * the publish leaves this pass collecting the tombstone's generations, and the drop's own sweep takes the rest.
- *
- * The seed's compare-and-swap moves the row's token, so a derived writer in flight on the row (an erasure rewrite)
- * meets a lost fence and re-derives: it happens once per row that recorded no list. A `WriteConflictError` from it is
- * a lost race, and the load took effect, so it is not raised; the next load records the list. Any other fault is
- * raised, as every fault of a collection after a landed publish is.
- */
-export declare function collectAfterLoad(ref: SegmentRef, deps: GenerationDeps, options: {
-    generation: number;
-    keep: number;
-    /** The load's number was proved free by one existence check, and no caller asked for a listing. */
-    byName: boolean;
-    /** The guard opened the current generation's object and found it gone. */
-    currentGone?: boolean;
-    kept: PublishedKept | undefined;
-    /**
-     * The object the load's row named as current, which the caller did not open. Before it collects by name, the pass
-     * looks for this object with one zero-byte read, and lists instead unless that finds it: a name-only pass is
-     * safe only while the object the row named is in the bucket.
-     */
-    proveCurrent?: GenKey;
-    /** Spare the generations the row's live leases hold. Absent, the pass ignores leases. */
-    leases?: LeaseGuard;
-}): Promise<number[]>;
-/**
- * Delete, with no listing, the generations a publish of `generation` pushed out of its row's window, `evict`, taken
- * from the list the publish was written against. Returns the names asked for, whether or not an object was there: a
- * delete of an absent object succeeds on every backend and says nothing, so a generation a concurrent pass, an erasure
- * or a lifecycle rule had already taken is listed all the same. A list is not a receipt (invariant 4), and neither is
- * this.
- *
- * Each delete re-reads the row first (invariant 4) and stops the pass, deleting nothing more and raising nothing, unless
- * the row still has a pointer at or above `generation` (a rollback, or a name purged and re-created with fewer loads,
- * has moved it below: the publish already landed, nothing here protects it or needs the result), the name is below
- * that pointer, and the row's own list is usable and does not name it. The last condition is what keeps a late delete
- * from taking a generation that a later publish, after a rollback, put in the window. A pointer that has moved above
- * `generation` does not stop it: a publish landing in the meantime leaves routine collection working. A fault, a
- * registry read or a delete that throws, propagates, with the pointer at `generation`.
- */
-export declare function deleteEvicted(ref: SegmentRef, deps: GenerationDeps, options: {
-    generation: number;
-    evict: readonly number[];
-    leases?: LeaseGuard;
-}): Promise<number[]>;