@cloudbitmaps/core 0.20.0 → 0.21.0

package/dist/core/crbm-storage-source.d.ts

@@ -1,14 +1,7 @@
-import { type IAuditSink } from './audit.js';
-import { ValidationError } from './errors.js';
-import type { Yielder } from './cooperative.js';
-import type { Clock, Rng } from './determinism.js';
-import type { PublishedKept } from './generation-gc.js';
-import type { Aead, CrbmCrypto, IKeystore, WrappedDek } from './crypto.js';
-import type { ChunkRef, ChunkRead, ReadChunksOptions, StorageChunkSource, GenerationMetadata, GenerationSummary, GenKey, IStorageDriver, IRegistryDriver, RegistryRecord, RegistrySummary, SegmentRef, SegmentSize, Token } from './ports.js';
-import { CrbmReader } from './crbm/reader.js';
+import type { Clock } from './determinism.js';
+import type { IKeystore } from './crypto.js';
+import type { ChunkRef, ChunkRead, ReadChunksOptions, StorageChunkSource, GenerationSummary, IStorageDriver, IRegistryDriver, RegistryRecord, SegmentRef, SegmentSize, Token } from './ports.js';
 import type { CrbmReaderOptions } from './crbm/reader.js';
-import type { CodecBitmap, CodecInterface } from './codec.js';
-import { ChunkLoadInput, DecodedLoadInput } from './load-input.js';
 export interface CrbmStorageChunkSourceOptions extends CrbmReaderOptions {
     /**
      * Optional {@link IRegistryDriver}. When provided, the current generation is resolved via the registry's
@@ -45,7 +38,7 @@ export interface CrbmStorageChunkSourceOptions extends CrbmReaderOptions {
      * How long (ms) a resolved `currentGen` is trusted before the next read re-resolves it (default 2000) — the
      * bound on read staleness after a load publishes: a reader may serve the prior generation for up to this long,
      * then converges. Lazy (checked on read — no timer); ≤ one cheap registry read per segment per window, and a
-     * new {@link CrbmReader} is opened only when the generation actually changed. `0` turns the refresh off, as a
+     * new {@link CrbmReader} is opened only when the row's pointer was renewed. `0` turns the refresh off, as a
      * missing clock or registry does: {@link clock} says what that changes, and what it does not.
      */
     readonly currentGenTtlMs?: number;
@@ -53,7 +46,7 @@ export interface CrbmStorageChunkSourceOptions extends CrbmReaderOptions {
      * Hard ceiling on how many segments' readers (each holding a fully-parsed `.crbm` index) are cached at once
      * (default 1024) — a memory bound for a long-running server. Past it, the least-recently-used
      * segment's reader is evicted; the next read of an evicted segment re-opens it (one cheap tail GET, since
-     * generations are immutable). Raise it for a big cache working set of small segments. A source with a timed refresh
+     * generations are immutable). Raise it for a big cache working set of small segments, and raise {@link maxOpenIndexBytes} with it: each open reader counts about 3.75 KiB there, so past about 17,000 tiny readers the byte ceiling binds first. A source with a timed refresh
      * also keeps up to 8 times this many segments' resolutions apart from their readers, for the TTL: the re-open then
      * reads no row, and comes only when a read needs the reader, for the index or for a chunk.
      */
@@ -64,24 +57,25 @@ export interface CrbmStorageChunkSourceOptions extends CrbmReaderOptions {
      * **second half of that memory bound**. `maxOpenSegments` alone bounds by *count*, but a wide/dense segment's
      * parsed index can reach about 1.3 MB, so 1024 wide indices could pin over a GB and blow a small heap (e.g. a 128 MB
      * Lambda) while the count is nominally "in bounds". This caps the summed {@link CrbmReader.retainedBytes} (the
-     * parsed index, any metadata a generation carries, and any kept chunk bytes) across cached readers; the least-recently-used reader is evicted once the total would exceed it — whichever
+     * parsed index, any metadata a generation carries, and any kept chunk bytes) plus a fixed 3.75 KiB for the objects each open reader
+     * holds around them, across cached readers, so that many tiny segments are bounded too; the least-recently-used reader is evicted once the total would exceed it — whichever
      * of the count/byte bounds binds first. A reader whose open read the whole object keeps a copy of its chunk region when
      * that region is at most this ceiling divided by {@link maxOpenSegments} (64 KiB by default) — its fair share — so a small generation's
      * chunks are served from memory with no further request, and a bigger one is read by range. Only a source with a timed
      * pointer refresh ({@link currentGenTtlMs} above 0, a registry and a clock) keeps chunk bytes. Lower it for memory-tight deployments with wide segments; a single
-     * segment whose index alone exceeds the budget is still cached (it can't be shrunk) but nothing else alongside. A
+     * segment whose weight alone exceeds the budget is still cached (it can't be shrunk) but nothing else alongside. A
      * sixteenth of it bounds the resolutions a source with a timed refresh keeps besides (4 MiB by default).
      */
     readonly maxOpenIndexBytes?: number;
 }
 /**
  * What a pin holds of the object it pinned: the version its cache entries are keyed by, and the object's
- * fingerprint, which a pinned read checks each time it opens the generation. `pinGeneration` always records one.
- * A pin built by hand without one is not checked: it reads whatever object is under its generation's key.
+ * fingerprint, which a pinned read checks each time it opens the generation. `pinGeneration` always records both,
+ * and a pinned read given one without both as strings throws a `ValidationError`.
  */
 export interface PinnedObject {
     readonly version: string;
-    readonly fingerprint?: string;
+    readonly fingerprint: string;
 }
 /**
  * What a live version's resolution named, without the object's fingerprint: `<generation>:<pointerId>`, or
@@ -99,6 +93,15 @@ export interface PinLease {
         readonly token: Token;
     } | 'moved'>;
 }
+/**
+ * The fixed heap an open reader's snapshot holds beyond {@link CrbmReader.retainedBytes}: the snapshot, the reader, its
+ * five index arrays as objects, and the closures and promises that tie them. It is added to a reader's weight in the
+ * reader cache, so that the byte ceiling bounds many tiny segments as it does a few wide ones. Measured as the heap that
+ * stayed (full collections until stable) per segment after a source opened 2,000 one-chunk segments, minus the 20 bytes
+ * of index the weight already counts: about 3.7 KiB on Node 24, rounded up to 3.75 KiB.
+ * `tests/core/reader-cache-heap.test.ts` holds the counted weight to that heap.
+ */
+export declare const OPEN_READER_BYTES = 3840;
 export declare class CrbmStorageChunkSource implements StorageChunkSource {
     private readonly driver;
     /**
@@ -151,7 +154,12 @@ export declare class CrbmStorageChunkSource implements StorageChunkSource {
      * counts every segment's invalidations: a read that waited through another segment's only costs a later read the
      * check again.
      */
-    private invalidations;
+    private get invalidations();
+    /**
+     * Which segments {@link invalidate} has been called for, the latest invalidation of up to 1,024 of them: a pinned
+     * stream asks it whether its own segment was invalidated since it last looked.
+     */
+    private readonly invalidated;
     /**
      * Generations whose row summary this process found to disagree with their object, by segment and generation. A
      * summary here is not used again: a count of that generation reads the object. Bounded as the readers are, so a
@@ -409,9 +417,9 @@ export declare class CrbmStorageChunkSource implements StorageChunkSource {
     /** Size of a specific generation. `held` as for {@link getChunkAt}. */
     sizeOfAt(ref: SegmentRef, generation: number, held?: PinnedObject): Promise<SegmentSize | null>;
     /**
-     * Whether the segment is a registered name at all. With a registry that is exactly "a row exists" — including
-     * a row with no generation yet (minted by `setRetention` before the first load) and a `destroyed` tombstone,
-     * both of which are names somebody deliberately created. Without a registry there is no registration to
+     * Whether the segment is a registered name at all. With a registry: a row that is not a `destroyed` tombstone,
+     * including one with no generation yet (minted by `setRetention` before the first load), which somebody deliberately
+     * created. A tombstone holds nothing, so it answers `false`. Without a registry there is no registration to
      * consult, so the honest answer is whether the bucket holds any generation of it.
      *
      * Deliberately NOT served from the snapshot memo: the memo resolves to `null` for both states this exists to
@@ -437,6 +445,22 @@ export declare class CrbmStorageChunkSource implements StorageChunkSource {
      * it should hold the same count and metadata, or the summary is not believed again in this process
      * ({@link distrusted}). Neither check costs a request. A row with no summary it can use names no object, and its
      * generation's object is opened as it is.
+     *
+     * An encrypted generation's tail read is sent first, beside the key, because the key (a keystore call, a network
+     * round trip for a KMS keystore) and the tail are independent: only the index needs the key, and it comes out of the
+     * tail. The row's summary of an encrypted generation is sealed under the same key, so it is read after the key. The
+     * open then holds the footer to the summary and decrypts, as an open that waited for the key does, and nothing of the
+     * tail is read before then. The key is awaited first, so a keystore fault reaches the caller before a storage fault,
+     * and the request already sent is not cancelled: it is billed, and its answer or failure is dropped when the key
+     * fails.
+     *
+     * A cleartext generation's tail read is sized from the `tailBytes` of that summary ({@link sizedTailBytes}), so a
+     * generation whose index is longer than the default tail comes in the one read, with no range read for the index
+     * after it. Only a summary this process still believes sizes a read ({@link trustedSummary}): one found to disagree
+     * with its object is not used again, so a wrong number costs one extra read for the process, not for each open. An
+     * encrypted generation is not sized: its summary is sealed under the key, so sizing from it would send the tail read
+     * after the key, which the early read above avoids where no earlier step has already waited for the key (a cold
+     * `has()` has).
      */
     private openLive;
     private distrustKey;
@@ -478,6 +502,16 @@ export declare class CrbmStorageChunkSource implements StorageChunkSource {
      * {@link getChunks} of a specific generation, the pinned shape read. It yields the chunks without a version: the
      * caller that pinned the generation knows it. It never moves to another generation; `held` as for
      * {@link getChunkAt}.
+     *
+     * Before it hands out a chunk after an {@link invalidate}, it looks its generation up as a read of that chunk alone
+     * would. Where the invalidation was of its segment, which forgets the pinned reader, it opens the object again, and
+     * fails as that read would, with `NotFoundError` once the object is gone or replaced, or its row is gone or
+     * destroyed. An object still there is the one it was reading, since an object is immutable and the open is held to
+     * the pin, so the stream carries on with the ranges it holds. Another segment's invalidation costs it nothing, the
+     * pin's reader still in the reader cache or not, and with no invalidation since it last looked the check is a
+     * compare. The one exception is a store that invalidates more than 1,024 other segments while the stream runs: the
+     * record of invalidations then counts the stream's segment as invalidated too, and the stream looks its pin up
+     * again, at no cost where the reader cache still holds the pin's reader and with one open where it has let it go.
      */
     getChunksAt(ref: SegmentRef, generation: number, keys: readonly number[], held?: PinnedObject, options?: ReadChunksOptions): AsyncGenerator<Omit<ChunkRead, 'version'>>;
     listChunkKeys(ref: SegmentRef): Promise<number[]>;
@@ -539,11 +573,20 @@ export declare class CrbmStorageChunkSource implements StorageChunkSource {
      * is the documented outcome rather than a failure.
      *
      * **Bounded to exactly two resolve-and-open round trips.** That is a cost contract, not a detail: the retry
-     * now re-reads the *registry*, so an unbounded one would hammer the shared, throttle-prone resource in a
+     * re-reads the *registry*, so an unbounded one would hammer the shared, throttle-prone resource in a
      * tight loop on a segment whose pointer names an object that is permanently absent — and an N-way
      * `intersect` would do it N times. Gated in `tests/core/storage-source-heal-open.test.ts` by counting calls.
      */
     private withFreshSnapshot;
+    /** The live snapshot of `ref` and the reader it is opening, as a read holds them while it resolves. */
+    private resolution;
+    /**
+     * The reader `at` resolves to. A caller that retries has the resolution and open run through its `retry`; a failed
+     * one forgets itself, so each try resolves anew and `at` is moved to the snapshot that try resolved.
+     */
+    private resolveReader;
+    /** The options a chunk stream is read with: the caller's tuning, its retry for each range, and this source's clock. */
+    private readOptionsOf;
     /**
      * Whether `err`, raised by a read through the snapshot's reader, came from an object that is no longer the one the
      * reader opened. A generation number can be taken again once its object is deleted (an erasure removes the
@@ -556,433 +599,3 @@ export declare class CrbmStorageChunkSource implements StorageChunkSource {
      */
     private replacedUnder;
 }
-/**
- * Write one immutable generation from in-memory bitmaps. Chunks are
- * sorted ascending and empty bitmaps skipped (empty chunks are never stored). Returns the driver's
- * `{ size, sha256 }` for the written object. Pass `options.crypto` to AES-256-GCM-encrypt the generation
- * (built from the segment's DEK, with associated data bound to `(segment, generation)`).
- */
-export declare function writeCrbmGeneration(driver: IStorageDriver, key: GenKey, chunks: Iterable<{
-    chunkKey: number;
-    bitmap: CodecBitmap;
-}>, options?: {
-    crypto?: CrbmCrypto;
-    clock?: Yielder;
-    metadata?: GenerationMetadata;
-}): Promise<{
-    size: number;
-    sha256: string;
-    fingerprint: string;
-}>;
-/**
- * The object under `key`, when it is provably the one `fingerprint` names ({@link CrbmReader.fingerprint}), from one
- * read of its footer, with the version the driver reported on that read (`undefined` from a driver that reports none).
- * `null` when it is another object, when it is gone, and when the read fails in any way: a caller that deletes what
- * this proves deletes nothing it cannot prove is its own, and passes the version as the delete's `ifVersion`, so a
- * number taken again between the read and the delete keeps the object put under it since.
- */
-export declare function provenObject(storage: IStorageDriver, key: GenKey, fingerprint: string): Promise<{
-    readonly version: string | undefined;
-} | null>;
-/**
- * Whether the object under `key` is still the one `fingerprint` names ({@link CrbmReader.fingerprint}), from one read
- * of its footer. Unlike {@link provenObject}, a fault is not an answer: `NotFoundError` when the key holds no object,
- * and any other failure of the read, thrown as it is.
- */
-export declare function sameObjectUnder(storage: IStorageDriver, key: GenKey, fingerprint: string): Promise<boolean>;
-/**
- * Whether the object under `key` says it is encrypted, from one read of its footer, with no key. `noteVersion` is shown
- * the version the driver reported on that read, when it reported one: a caller that deletes the object for what its
- * footer says passes it as the delete's `ifVersion`.
- */
-export declare function objectIsEncrypted(storage: IStorageDriver, key: GenKey, noteVersion?: (version: string) => void): Promise<boolean>;
-/**
- * What one tail read of the object under `key` tells a rollback about it: whether the footer says it is encrypted, and,
- * when the object and the key agree (an encrypted object opened with `crypto`, a cleartext one with none), the reader
- * the open gives, which holds its count and metadata. No reader when they disagree, which the caller refuses as a
- * target the row cannot use, and none for an encrypted object when the caller has no key. A footer that fails its own
- * checks, an object another generation's, and an index or metadata that do not open are an {@link IntegrityError}.
- */
-export declare function openRollbackTarget(storage: IStorageDriver, key: GenKey, crypto: CrbmCrypto | undefined): Promise<{
-    encrypted: boolean;
-    reader: CrbmReader | undefined;
-}>;
-/** What {@link writeCrbmGenerationStream} wrote: the driver's `{ size, sha256 }` + a tally of the generation. */
-export interface StreamWriteResult {
-    readonly size: number;
-    readonly sha256: string;
-    /** Non-empty chunk keys written, in ascending order (for the post-write verify, since the stream is consumed). */
-    readonly chunkKeys: number[];
-    /** Total ids written. */
-    readonly cardinality: number;
-    /** The fingerprint of what this call wrote ({@link CrbmReader.fingerprint}), which tells it from another object under its key. */
-    readonly fingerprint: string;
-}
-/**
- * Streaming variant of {@link writeCrbmGeneration} for a **constant-memory** rewrite (the erasure rewrite, a
- * sorted load): consumes an **already-ascending** async stream of `{ chunkKey, bitmap }`, feeding each to the
- * codec and freeing it, instead of materializing the whole generation. Paired with a streaming storage sink (S3
- * multipart / LocalFs temp file), the writer itself holds ~one chunk + one part. Returns a tally so the caller can verify
- * the re-opened object without re-iterating the (now-consumed) stream. Input **must** be ascending by `chunkKey`
- * — the codec rejects an out-of-order chunk; empty bitmaps are skipped.
- */
-export declare function writeCrbmGenerationStream(driver: IStorageDriver, key: GenKey, chunks: AsyncIterable<{
-    chunkKey: number;
-    bitmap: CodecBitmap;
-}>, options?: {
-    crypto?: CrbmCrypto;
-    clock?: Yielder;
-    metadata?: GenerationMetadata;
-}): Promise<StreamWriteResult>;
-/**
- * Point a segment's registry `currentGen` at `key.generation` — the publish step that makes a freshly-written
- * generation the authoritative latest (so registry-aware readers see it). **Forward-only and idempotent:**
- * if the registry has no row it creates one; if it's already at/ahead of `key.generation` it's a no-op (an
- * out-of-order/duplicate publish never regresses the pointer); otherwise it advances via compare-and-swap,
- * retrying a few times under contention. Separated from the Storage write so callers can publish atomically
- * after the immutable object is durable (write-then-publish).
- *
- * **Throws** rather than returning, in two cases, because each would otherwise create a state no reader can
- * recover from: a `destroyed` (crypto-shredded) row, where advancing the pointer would name an object encrypted
- * under a shredded key; and an advance carrying **new** `wrappedDeks`, which would either strand that key or make
- * the row advertise encryption over cleartext generations. Contention that never clears throws
- * {@link WriteConflictError} after the retries.
- *
- * **`expectFrom` turns forward-only into read-modify-write.** Forward-only is the right rule for a writer whose
- * content does not depend on what was current — a load computes its ids upstream, so publishing over a newer
- * generation loses nothing the loader knew about. It is the WRONG rule for a writer that *derived* its content
- * from a particular generation: the erasure rewrite streams generation `from` and clears one bit, so publishing
- * it over a newer generation silently discards whatever that generation added. Passing `expectFrom` makes the
- * publish land only while the pointer is still exactly there, and return `false` otherwise, so the caller can
- * report `superseded` and re-derive. The compare-and-swap itself carries the token read in the same iteration,
- * so the check and the write see the same row.
- *
- * **`expectToken` fences the LINEAGE, and a derived writer needs both.** A generation number identifies a
- * generation only within one incarnation of a name: the numbering restarts at `0` once the row is purged and
- * the bucket empty, so a name that is retired and re-created has a *different* segment wearing the *same*
- * `currentGen`. `expectFrom` alone matched it — and an erasure rewrite then published one incarnation's content
- * over another's, deleted the live objects with its `keep: 0` collection, and returned `erased: true`. The row's
- * OCC token is the identity that survives this: a shipped registry's later `create` gets a token never issued before
- * under that name, but for a collision of probability 2^-128 per pair of incarnations, so no token is reused across them.
- *
- * Pass the token read alongside `expectFrom` and the publish lands only on the same row it was derived from.
- * The check is deliberately **conservative**: the token also changes on writes that are not supersessions at
- * all (a `setRetention`, a due-index reindex), so such a write makes a derived publish report `superseded` and
- * the caller re-derive. That costs a re-run on a rare, unrelated write; the alternative costs a segment.
- *
- * **The driver sends a registry write once, and an unanswered one is reconciled by its effect.** A `create` or
- * `compareAndSwap` that fails with {@link TransientError} (a throttle, a lost response, a timeout) may or may not
- * have landed, and may still be in flight. The publish reads the row once more and decides from what it holds:
- *
- * - the pointer names `key.generation`, on the incarnation the write was made against (the row's `createdAt`), and
- *   `holdsOwnObject` proves the object under it the caller's: the write landed, and the publish returns `true`. Only
- *   the writer of a write-once object publishes its number, and a number is never taken while an object holds it;
- * - the row is still the one the write was made against (the same token, or still no row): the write may land yet. The
- *   publish then waits, on the injected clock, and sends a **new** write from the row it just read: a request of its
- *   own, not a replay of the driver's, carrying the same version, so under the registry's fence at most one of the two
- *   lands and the other meets a conflict, which the next read settles. At most {@link UNANSWERED_RESENDS} follow, after
- *   a wait under 500 ms, then 1 s, then 2 s (full jitter when an `rng` is given); each is settled the same way. Still
- *   unanswered, or with no clock to wait on, this throws the registry's own `TransientError` and writes nothing more.
- *   A caller must not delete its object on it;
- * - anything else: the row has moved past the state the write was conditioned on, so that write can never land, and
- *   the publish goes on as after a lost race, from the row it just read. A pointer at `key.generation` that is not over
- *   the caller's own object, or is on another incarnation, is a lost race too and answers `false`, never an already
- *   current re-publish.
- *
- * A failed read throws `TransientError` too. The same check of the pointer runs after a {@link WriteConflictError},
- * so a write that landed and then met itself (a registry whose client re-sent it) is not taken for a lost race.
- *
- * **A `summary` goes in the same write that moves the pointer**, so a reader that sees this generation as current
- * sees the count and metadata that describe it, and every attempt sends the same one. It must be the shape the row's
- * keys call for: sealed for an object written with a key, clear for one written without.
- */
-export declare function publishGenerationKept(registry: IRegistryDriver, key: GenKey, options?: {
-    wrappedDeks?: readonly WrappedDek[];
-    expectFrom?: number;
-    expectToken?: Token;
-    /**
-     * The row `expectToken` names, as the caller read it. With it, a row whose token has moved but which differs from
-     * this one only in its leases (a reader took or released one) does not refuse the publish: it goes on against the
-     * fresh row, after a jittered wait and without the caller redoing its work, up to a bound. Any other difference
-     * refuses as ever. Without it, a moved token refuses.
-     */
-    expectRow?: RegistryRecord | null;
-    /**
-     * Publish only while the segment still has **no registry row**.
-     *
-     * The fence for a caller whose decision rests on the row being ABSENT: every load that found no row sets it,
-     * guarded or not. `expectFrom` and `expectToken` cannot express it: both compare against a value read from a
-     * row, so when there was no row there is nothing to compare and both are simply omitted — leaving the publish a
-     * bare forward-only advance that happily lands over whatever appeared in the meantime.
-     *
-     * Without it, a guarded load into a segment that did not exist yet would judge "no row", pass its empty and
-     * `minRetained` bounds vacuously, and land an EMPTY generation over the ids a concurrent writer had just loaded,
-     * reporting `published: true`. An unguarded load would move the pointer over another first load's generation or
-     * onto a row `setRetention` made, and, where an erasure had deleted its object above that row's pointer, onto an
-     * object that is gone. Materialising into a destination that does not exist yet is the ordinary first run of a
-     * pipeline, so the `*Into` verbs reach this as often as `loadSegment` does.
-     */
-    expectAbsent?: boolean;
-    /**
-     * The generation's summary (see {@link RegistrySummary}), written by the write that moves the pointer to it. It
-     * names `key.generation`. Absent, the row is left with none for this generation.
-     */
-    summary?: RegistrySummary;
-    /**
-     * The segment's row as the caller already read it (`null`: it found none). The first attempt acts on it
-     * instead of reading the row again, which is sound because that attempt writes only under the row's own
-     * fence: its compare-and-swap carries this row's token, and with no row it creates create-only, so a row
-     * that changed or appeared since makes the write lose and the next attempt reads the row afresh. Only the
-     * idempotent "already current" answer writes nothing, so a reused row never gives it.
-     */
-    row?: RegistryRecord | null;
-    /**
-     * The object was written without encryption. Its publish is refused, with {@link KeyUnavailableError}, onto a row
-     * that carries key material: a reader of that segment opens every generation with its key, and a later
-     * `destroySegment` would attest that shredding it made a readable object unreadable. A caller decides its key
-     * from the row it read before the write, so this closes the window in which another writer creates the
-     * segment encrypted meanwhile.
-     */
-    cleartext?: boolean;
-    /**
-     * Whether the object under `key` is the one the caller wrote, and throws when it cannot tell. Asked only when a
-     * registry write failed and the row then names `key.generation`, to tell this publish's write from another
-     * writer's at the same number. Every caller that writes the object passes it. Without it, a write that ended
-     * without an answer over a row that names `key.generation` cannot be settled: the publish throws
-     * {@link TransientError} and the caller keeps its object.
-     */
-    holdsOwnObject?: () => Promise<boolean>;
-    /**
-     * What a publish waits on before it sends a fresh compare-and-swap, after a write that ended without an answer and
-     * left the row as it was. Without a `sleep`, such a write throws at once instead of being sent again.
-     */
-    clock?: Yielder;
-    /** Spreads that wait (full jitter) so concurrent publishers do not retry together. Without it the wait is the bound. */
-    rng?: Rng;
-    /**
-     * Called once for each registry write that ended without an answer, before the row is read back. A caller whose
-     * publish then answers `false` can say that it cannot tell whether its own write landed first: the row may have
-     * held its generation for a while before another writer moved on.
-     */
-    onUnanswered?: () => void;
-    /**
-     * The clock that judges whether a lease has ended. With it, a publish over a row that holds ended leases drops
-     * them in the write that moves the pointer, which rewrites the row anyway. Without it, leases are left as they are.
-     */
-    leasesNow?: () => number;
-    /**
-     * Clear the row's leases in the write that moves the pointer: the caller's collection deletes every generation
-     * below the new pointer whatever a lease says, as a subject erasure's does.
-     */
-    clearLeases?: boolean;
-    /**
-     * How many generations below the new pointer the caller keeps. With it, the write that moves the pointer also
-     * records the window in the row (`keptGens`: the newest `keep` of the row's own list and the generation that was
-     * current), derived from the very row the write is made against, and the result names the generations the window
-     * dropped. Without it, or above the most a row records, the row records none, and a collection lists.
-     */
-    keep?: number;
-}): Promise<PublishResult>;
-/** What a publish did: whether the pointer is at the generation, and what the write recorded in the row. */
-export interface PublishResult {
-    readonly published: boolean;
-    /**
-     * What the write that moved the pointer recorded: the list, the generations the window dropped, and the new row's
-     * token. Absent when no write of this call is known to have landed (the pointer was already there, or the outcome
-     * was settled without knowing which write it was), and a collection then lists.
-     */
-    readonly kept?: PublishedKept;
-    /**
-     * A token of the row whose pointer is at the generation, when it is published: the one the write was given, or the
-     * row read that showed the pointer there. Every write of a row keeps its incarnation, so this names the incarnation
-     * the publish landed in, for the audit event.
-     */
-    readonly token?: Token;
-}
-/**
- * {@link publishGenerationKept}'s answer to "did the pointer move", for a caller with no use for what it recorded:
- * a publish with no `keep` leaves the row recording no list.
- */
-export declare function publishGeneration(registry: IRegistryDriver, key: GenKey, options?: Parameters<typeof publishGenerationKept>[2]): Promise<boolean>;
-/**
- * Whether the object under `key` is the one `fingerprint` names, from one read of its footer: false when it is another
- * object or gone. Unlike {@link provenObject}, a read that cannot tell throws, for a caller that must not take "could
- * not look" for "not this object".
- */
-export declare function provesOwnObject(storage: IStorageDriver, key: GenKey, fingerprint: string): Promise<boolean>;
-/** 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.
- */
-export 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>;
-/**
- * Open a {@link CrbmReader} on one generation over the storage driver's range/tail reads (decrypting if `crypto`).
- * The reader the write paths use to re-read what they wrote, and the erasure rewrite uses to stream the old
- * generation; the engine's read path goes through {@link CrbmStorageChunkSource} instead, which caches these. With
- * `named`, the fingerprint the row's summary records, the object must be that one: another is {@link NotFoundError}.
- * The version of the object it opened, from the tail read the open made, is what {@link objectVersionOf} answers.
- */
-export declare function openGenerationReader(storage: IStorageDriver, key: GenKey, crypto: CrbmCrypto | undefined, options?: Omit<CrbmReaderOptions, 'crypto'>, named?: string): Promise<CrbmReader>;
-/**
- * {@link openGenerationReader}, with `noteVersion` shown the version {@link objectVersionOf} would answer as soon as the
- * tail read that carries it returns, before the open goes on: a caller whose open then fails, on an object sealed under
- * another key, say, still knows which object it met, and can condition a delete of it on that read.
- */
-export declare function openGenerationReaderNoting(storage: IStorageDriver, key: GenKey, crypto: CrbmCrypto | undefined, noteVersion: (version: string) => void): Promise<CrbmReader>;
-/**
- * The version of the object `reader` was opened on, as the driver reported it on the tail read the open made, for a
- * delete conditioned on that object ({@link StorageDeleteOptions.ifVersion}); `undefined` for a reader
- * {@link openGenerationReader} did not open, or a driver that reports none. Held beside the reader rather than on it, so
- * nothing is added to the reader's public surface, and no read the engine makes pays for it.
- */
-export declare function objectVersionOf(reader: CrbmReader): string | undefined;
-/**
- * {@link openGenerationReader}, of the object `fingerprint` names: `undefined` when the object under the key is another
- * one, found from its footer before its index is opened, so an object sealed under another key is told apart as well.
- */
-export declare function openNamedGeneration(storage: IStorageDriver, key: GenKey, crypto: CrbmCrypto | undefined, fingerprint: string): Promise<CrbmReader | undefined>;
-/**
- * Re-open a freshly written generation and assert it round-trips exactly what was streamed into it: the same
- * per-chunk key set *and* the same total cardinality (on top of the codec's own per-chunk CRC + footer checks), and the
- * metadata it was given. `expected` is the streaming writer's tally (the stream is consumed, so it can't be
- * re-iterated) — the key-set comparison catches a dropped/extra chunk that a cardinality-only check could miss when
- * two errors cancel out. The count and the metadata are what the generation's row summary is about to claim, so the
- * summary is held to the object it describes before it is published.
- * Throws {@link IntegrityError}: the object is on disk but must not be published.
- */
-export declare function verifyGeneration(storage: IStorageDriver, key: GenKey, expected: {
-    readonly chunkKeys: readonly number[];
-    readonly cardinality: number;
-    readonly metadata?: GenerationMetadata | undefined;
-}, crypto: CrbmCrypto | undefined): Promise<void>;