@cloudbitmaps/core 0.19.1 → 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,9 @@ 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.
+     * 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.
      */
     readonly maxOpenSegments?: number;
     /**
@@ -62,31 +57,33 @@ 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.
+     * 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>:<row token>`, or
+ * What a live version's resolution named, without the object's fingerprint: `<generation>:<pointerId>`, or
  * `<generation>` with no registry. For a caller that compares a live version, from
- * {@link CrbmStorageChunkSource.currentVersion} or a chunk of its `getChunks`, with a row it read, which names no
- * object. A live version always ends with the suffix, which holds no `#`, so the match starts at its last `#` and a row
- * token holding `#` of its own is kept whole. Known limit: a string with no suffix, such as a pin's version or one
- * from another source, loses its end when its row token itself ends in `#<base 36>.<base 36>`; no caller passes one.
+ * {@link CrbmStorageChunkSource.currentVersion} or a chunk of its `getChunks`, with a row it read. A live version always
+ * ends with the suffix, which holds no `#`, so the match starts at its last `#` and a `pointerId` holding `#` of its own
+ * is kept whole. Known limit: a string with no suffix, such as a pin's version or one from another source, loses its end
+ * when its `pointerId` itself ends in `#<base 36>.<base 36>`; no caller passes one.
  */
 export declare function rowVersionOf(version: string): string;
 /** What a pin that leases its generation does between reading the row and opening the object. */
@@ -96,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;
     /**
@@ -112,6 +118,21 @@ export declare class CrbmStorageChunkSource implements StorageChunkSource {
      * steady-state memory bound; re-opening an evicted segment is one cheap tail GET.
      */
     private readonly snapshots;
+    /**
+     * Each segment's resolution, kept apart from its reader, by segment: what a read of its row found, for the TTL from
+     * the instant that read was sent, whether or not the reader cache still holds the segment's reader. So letting a reader
+     * go moves nothing: the next read builds a snapshot on the resolution, reads no row, and opens the object when it needs
+     * the index or a chunk the chunk cache does not hold (a version, a count and a stat from the row's summary need
+     * neither). It holds the resolved fields only ({@link Resolved}): the wrapped keys, never an unwrapped one, so a
+     * snapshot built on it unwraps the key again through the keystore. It never holds a resolution that found no
+     * generation: the next read of such a segment reads the row.
+     *
+     * Only a source with a timed refresh has one: without it, letting a reader go is one of the few things that ever moves
+     * a read on, and keeping the resolution would keep it forever. **Bounded** by count and by bytes, both derived from
+     * the reader cache's: {@link RESOLUTIONS_PER_OPEN_SEGMENT} times its count bound, and its byte bound over
+     * {@link RESOLUTION_BYTES_DIVISOR}. An entry heavier than the byte bound is kept alone, as the reader cache keeps one.
+     */
+    private readonly resolutions;
     /**
      * Pins ({@link heldKey}) whose object has been found replaced: another object is under its generation's key. Kept,
      * and bounded as the readers are, so that a pin's later chunk reads and any reopen fail at once rather than pay for
@@ -133,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
@@ -141,6 +167,13 @@ export declare class CrbmStorageChunkSource implements StorageChunkSource {
      * the disagreement again.
      */
     private readonly distrusted;
+    /**
+     * The readers held to the row's summary: by a live open ({@link openLive}), or by a live pin that shared one. A pin
+     * that finds one memoised under its version shares it as it is: the version names the row's `pointerId`, and every
+     * write of the summary renews it, so the summary it was held to is the one the row has now. Any other memoised reader
+     * (a `pinAt`'s, held to the fingerprint its caller named) is held to the row's summary before a live pin shares it.
+     */
+    private readonly rowChecked;
     private readonly registry;
     private readonly keystore;
     private readonly requireEncryption;
@@ -151,8 +184,8 @@ export declare class CrbmStorageChunkSource implements StorageChunkSource {
     private readonly currentGenTtlMs;
     /**
      * Whether the segment's pointer is re-read on a timer: it needs a clock (the TTL), a registry (the cheap row read; with
-     * none, resolving is a listing of the bucket) and a TTL above 0. It decides the keeping of chunk bytes, the TTL lapse
-     * and the refresh interval the cost report prices, so it is decided once.
+     * none, resolving is a listing of the bucket) and a TTL above 0. It decides the keeping of chunk bytes and the TTL
+     * lapse, so it is decided once.
      */
     private readonly timedRefresh;
     constructor(driver: IStorageDriver, options?: CrbmStorageChunkSourceOptions);
@@ -164,63 +197,90 @@ export declare class CrbmStorageChunkSource implements StorageChunkSource {
     private readonly keys;
     private keyOf;
     /**
-     * The segment's live snapshot, refreshing on the TTL. Cheap within the TTL window. The snapshot holds the resolved
-     * target, and its reader once a read has asked for one.
+     * The segment's live snapshot, refreshing on the TTL. Cheap within the TTL window: the snapshot the reader cache holds,
+     * while its resolution is inside the TTL. With a timed refresh, a segment whose reader the cache let go is served a
+     * snapshot built on its kept resolution, while that is inside the TTL: no row is read, and the reader opens only when a
+     * read needs one. Otherwise the pointer is read now. The snapshot holds the resolved target, and its reader once a read
+     * has asked for one.
      */
     private liveSnapshot;
-    /** The current resolved reader for a segment, refreshing on the TTL. */
-    private resolvedReader;
     /**
-     * A refresh failed transiently and the prior reader keeps serving: make this snapshot lapse after
-     * {@link REFRESH_RETRY_MS} (never longer than the TTL) rather than after a whole TTL, so the next read after
-     * that asks the registry again. It costs no read of its own; it only changes when the next refresh happens.
+     * Read the segment's pointer now. The read is sent before this returns, and the TTL counts from this instant: a read
+     * that answers late does not lengthen the life of what it found. The row read is always fresh, so what a snapshot on
+     * it says of the generation (its summary included) is what the row says now, never `prior`'s.
+     *
+     * A read that fails with a transient fault answers what `prior` found, when it found a generation, and is asked again
+     * soon ({@link retrySoon}): `prior` is the resolution of the snapshot the reader cache still holds, so an outage of the
+     * registry keeps that snapshot's generation, and its reader and unwrapped key where it has them; one resolved without
+     * an open, for a count or a generation lookup, unwraps the key from `prior`'s wrapped keys when a read first needs
+     * it. The outage ends shortly after the registry answers.
+     * That answer is the snapshot's alone ({@link Resolution.rodeOut}): it is not kept as the segment's resolution, and a
+     * snapshot built on it after the reader cache let that one go fails with the fault. With no `prior` the fault
+     * fails the read, as a cold resolve's does. If `prior` found none or failed, the pointer is read once more rather than
+     * a dead resolution re-armed (else the segment reads empty for a whole TTL window). Anything else — an access denial, a corrupt row, a
+     * registry that answers NotFound — fails the read exactly as a cold resolve of the segment would, and the resolution
+     * and the snapshot on it are forgotten, so a reader and the key it unwrapped do not outlive a refresh that could not
+     * be trusted.
+     */
+    private resolveNow;
+    /**
+     * A refresh failed transiently and the prior resolution keeps serving: make it lapse after {@link REFRESH_RETRY_MS}
+     * (never longer than the TTL) rather than after a whole TTL, so the next read after that asks the registry again. It
+     * costs no read of its own; it only changes when the next refresh happens.
      */
     private retrySoon;
     /**
-     * TTL elapsed: cheaply re-resolve the pointer. The row read is always fresh, so what the new snapshot says of the
-     * generation (its summary included) is what the row says now, never the prior snapshot's. The reader is reopened
-     * only if the generation or the row changed, and only when a read asks for it.
+     * Keep `resolution` as the segment's, from the instant its read was sent, so the reads that come while it is in flight
+     * share it, and a read after the reader cache let the segment go builds on it. Its weight is reported once it lands,
+     * and one that finds no generation, or fails, is forgotten. Both are identity-guarded, as the reader cache's are, and
+     * nothing is installed when the read lands: an `invalidate` while it is in flight, or a newer resolution, is never
+     * undone by its answer.
      */
-    private refreshedTarget;
+    private remember;
     /**
-     * Memoize a snapshot as the segment's at `now()`, forgetting it later if it resolves to null / throws
-     * (identity-guarded, so a stale cleanup never clobbers a fresher snapshot). Installing the (pending) snapshot
-     * **synchronously** is what lets concurrent callers coalesce onto one in-flight resolve.
+     * A live snapshot on `resolution`. `before` is the snapshot it replaces, while the reader cache still holds one: its
+     * reader is kept if the resolution finds the same generation, `pointerId` and object ({@link Snapshot.reuse}), and its
+     * unwrapped key if the same wrapped keys. A snapshot built after the reader cache let the segment go has neither, so
+     * its open asks the keystore again: a key is held only while a reader of the segment is.
      */
-    private install;
-    private now;
+    private snapshotOn;
+    /** What the snapshot on `resolution` that replaces `before` reads: see {@link snapshotOn}. */
+    private targetOn;
     /**
-     * How often this source re-reads a segment's pointer while the segment is being read, in ms: its TTL, or 0 when
-     * it has no timed refresh (no clock, no registry, or a TTL of 0). The grounded cost report prices the refresh at
-     * this.
+     * Memoize a snapshot as the segment's, forgetting it later if it resolves to null / throws (identity-guarded, so a
+     * stale cleanup never clobbers a fresher snapshot). Installing the (pending) snapshot **synchronously** is what lets
+     * concurrent callers coalesce onto one in-flight resolve.
      */
-    get pointerRefreshMs(): number;
+    private install;
+    private now;
     /**
      * Whether a stream reading from `snap` must resolve its segment again before its next chunk, as a read of one chunk
-     * would: the snapshot's TTL has lapsed, an invalidation has happened since `epoch`, or the snapshot is no longer the
-     * one the reader cache holds for the segment (it let it go, or another read installed a newer one). Else nothing can
-     * have moved it, and the check costs a compare and a lookup.
+     * would. In this order: an invalidation has happened since `epoch` (what the store that erased stops on, at once);
+     * the TTL of the snapshot's resolution has lapsed; or that resolution is no longer the segment's: another read
+     * installed a newer one (a refresh, or a heal), or the resolution cache let it go. With no resolution cache (no timed
+     * refresh) the last test is of the snapshot itself, so there the reader cache letting it go is a move, as it is one of
+     * the few things that ever moves such a store's read on. With one, it is not. Else nothing can have moved it, and the
+     * check costs a compare and a lookup in each cache.
      */
     private mayHaveMoved;
     private expired;
     /**
-     * The segment's current generation number — the engine keys its chunk cache by this so a generation bump
-     * is observed instead of serving a stale decoded chunk. Served from the (TTL-refreshed)
-     * snapshot, so no extra backend read within the TTL window. `null` if the segment has no committed generation.
+     * The segment's current generation number, as its snapshot's resolution found it: no backend read within the TTL
+     * window, and no open of the object, ever. `null` if the segment has no committed generation. A generation swept from
+     * under the resolution is met by the read that fetches from it, which heals ({@link withFreshSnapshot}). Since it
+     * opens nothing, the only error it meets is the resolution's own, and it fails with that error at once: there is
+     * nothing to heal. The reads that can open the object (`listChunkKeys`, `summary`, `currentVersion` and the rest)
+     * resolve once more on any `NotFoundError`, a registry's among them, since theirs can be a swept generation.
      *
-     * Heals a swept generation exactly like {@link withFreshSnapshot}: a caller that resolves the generation once
-     * per op, before any chunk fetch, would otherwise fail the whole operation rather than one chunk. The engine
-     * keys by {@link currentVersion} instead, which heals the same way, and falls back to this for a source that
-     * cannot report a version. It is spelled out rather than delegated because a lookup like this runs once per
-     * operand of every `has`/`count`/`iterate`/`intersect`, almost always served from the cached snapshot with
-     * no backend call at all. Routing it through the generic helper cost ~115 ns/op on that path (a second async
-     * frame, a per-call closure, and an `await` on a plain number) for a race that fires only during a
-     * concurrent sweep. One retry, then propagate — same contract, same eviction rule.
+     * It is spelled out rather than delegated because a lookup like this runs once per operand of every
+     * `has`/`count`/`iterate`/`intersect`, almost always served from the cached snapshot with no backend call at all.
+     * Routing it through the generic helper cost ~115 ns/op on that path (a second async frame, a per-call closure, and
+     * an `await` on a plain number).
      */
     currentGeneration(ref: SegmentRef): Promise<number | null>;
     /**
-     * Forget everything derived from `ref`: the resolved snapshot and the open reader behind it (and with the
-     * reader, the DEK it unwrapped at open time), and what its pins' objects were found to be. The next read
+     * Forget everything derived from `ref`: its resolution, the resolved snapshot and the open reader behind it (and with
+     * the reader, the DEK it unwrapped at open time), and what its pins' objects were found to be. The next read
      * resolves the segment again.
      *
      * Needed because the TTL refresh only ever answers "has the pointer moved?", and every *destructive* verb —
@@ -231,24 +291,34 @@ export declare class CrbmStorageChunkSource implements StorageChunkSource {
      */
     invalidate(ref: SegmentRef): void;
     /**
-     * `<generation>#<object>` for a registry-less source, or `<generation>:<row token>#<object>` with one: the generation
-     * the segment's snapshot resolved, and the object its reader opened, by that object's size and footer checksum in
-     * base 36, which the open read anyway. The token moves on every row write, so an unrelated write (a `setRetention`)
-     * costs the segment's decoded chunks once — bounded, and on an admin path. Two objects do not share a version
-     * string, as far as their sizes and footer checksums tell them apart, whichever way a number came to name a second
-     * one: a name purged and loaded again (a new row, or with no registry the same bare number), a number taken again
-     * within one row once its object was deleted, or an object put back under its key from outside the library. That
-     * holds however long after its row read a reader opens: a snapshot that a `count()` resolved from the row opens its
-     * reader only when a later read needs it, and the object under the key may have changed in between. The version is
-     * opaque: compare two for equality.
+     * `<generation>#<object>` for a registry-less source, or `<generation>:<pointerId>#<object>` with one: the generation
+     * the segment's snapshot resolved, and the object a reader of it opens, by that object's size and footer checksum in
+     * base 36. The row's `pointerId` moves only with a write that names a field a read resolves through, at any value, so
+     * a lease or a policy write (a `setRetention`) leaves the version, the open reader and the decoded chunks as they were.
+     * Two objects do not share a version string, as far as their sizes and footer checksums tell them apart, whichever way
+     * a number came to name a second one: a name purged and loaded again (a new row, or with no registry the same bare
+     * number), a number taken again within one row once its object was deleted, or an object put back under its key from
+     * outside the library. The version is opaque: compare two for equality.
      *
-     * This is the call the engine makes **once per operand of every read**, before any chunk fetch, to key its
-     * chunk cache, so it heals a swept generation exactly as {@link currentGeneration} does: unhealed, a cold read
-     * racing a publish and a `keep: 0` sweep failed the whole operation with `NotFoundError`, where the same race
-     * on a chunk fetch heals. Spelled out rather than delegated for the reason `currentGeneration` gives: it is
-     * almost always served from the cached snapshot with no backend call at all. One retry, then propagate.
+     * Where the row's summary names the object, the version is answered from the resolution, with no open: every live
+     * open of the generation is held to that object ({@link openLive}), refused as a move otherwise, so the one object any
+     * reader of this resolution can name is the one the summary names, and a version named from it is the one that
+     * reader's would be. So a `has()` whose chunk is in the chunk cache opens nothing, after the reader cache let
+     * the segment go included (a read that needs the index opens the object for it, and on an encrypted segment the
+     * key is unwrapped to read the row's sealed summary); an object under the number that is not the row's is met by the read that fetches from it,
+     * which refuses it and heals. Where the row has no summary it can use, or there is no registry, nothing names the
+     * object but the object: the reader is opened, and the version names what it opened, however long after its row read
+     * that is.
+     *
+     * This is the call the engine makes **once per operand of every read**, before any chunk fetch, to key its chunk
+     * cache, so an open it makes heals a swept generation as a read does: unhealed, a cold read racing a publish and a
+     * `keep: 0` sweep failed the whole operation with `NotFoundError`, where the same race on a chunk fetch heals. Spelled
+     * out rather than delegated for the reason `currentGeneration` gives: it is almost always served from the cached
+     * snapshot with no backend call at all. One retry, then propagate.
      */
     currentVersion(ref: SegmentRef): Promise<string | null>;
+    /** {@link currentVersion} of one snapshot: named by the row's summary when it can be, else by the reader, opened. */
+    private versionOn;
     /**
      * Resolve the segment **once** and report what a pin should hold: the generation, and the version that
      * identifies those exact bytes. `null` when the segment resolves to no generation — there is nothing to pin,
@@ -282,7 +352,7 @@ export declare class CrbmStorageChunkSource implements StorageChunkSource {
     private pinOnce;
     /**
      * Where a pinned reader of one object is memoised. With a registry that is its version, which names the object:
-     * a name purged and loaded again gets a new row, and with it a new token. Without one the version is the bare
+     * a name purged and loaded again gets a new row, and with it a new `pointerId`. Without one the version is the bare
      * generation number, which two incarnations share, so the object's fingerprint is added to tell them apart.
      */
     private pinnedKey;
@@ -314,9 +384,10 @@ export declare class CrbmStorageChunkSource implements StorageChunkSource {
      * **And the object is checked**, when the caller says which one it pinned. A generation number is not an
      * identity (invariant 1): once a name is purged and loaded again, its new segment starts again at generation 0,
      * so a pin of the old one would open the new one's object as its own, and read it beside the chunks it had
-     * already cached from the old one. The row's token cannot tell them apart, since it moves on every write, a
-     * publish included; the object's fingerprint can, and a pin whose object has been replaced fails, as one whose
-     * generation has been swept does. The memo is keyed so that two pins of one generation number in two
+     * already cached from the old one. The row's `pointerId` cannot tell them apart, since it moves with every write
+     * that changes what the row resolves to, a publish included, while the pinned object stays what it was; the
+     * object's fingerprint can, and a pin whose object has been replaced fails, as one whose generation has been swept
+     * does. The memo is keyed so that two pins of one generation number in two
      * incarnations never share a reader, with a registry or without one ({@link pinnedKey}).
      */
     private readerAt;
@@ -343,12 +414,12 @@ export declare class CrbmStorageChunkSource implements StorageChunkSource {
      * for {@link getChunkAt}.
      */
     cardinalitiesAt(ref: SegmentRef, generation: number, held?: PinnedObject): Promise<ReadonlyMap<number, number> | null>;
-    /** Grounded size of a specific generation. `held` as for {@link getChunkAt}. */
+    /** 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
@@ -356,30 +427,64 @@ export declare class CrbmStorageChunkSource implements StorageChunkSource {
      */
     exists(ref: SegmentRef): Promise<boolean>;
     /**
-     * Evict a snapshot we just failed to read from — matched by the snapshot itself, so a concurrent call's
-     * fresher snapshot is never clobbered. The identity guard is the whole point: `install` replaces the entry
-     * wholesale, so comparing anything else would drop a good snapshot on the floor.
+     * Evict a snapshot we just failed to read from, and the resolution it was built on — each matched by identity, so a
+     * concurrent call's fresher snapshot or resolution is never clobbered. The identity guard is the whole point: `install`
+     * and `remember` replace an entry wholesale, so comparing anything else would drop a good one on the floor. The
+     * resolution goes too, or the read's retry would build its snapshot on it again and reopen the generation it just
+     * found gone; and so does a snapshot the reader cache holds on that same resolution, which another read built once the
+     * cache had let `snap` go, or the retry would open that one.
      */
     private dropStale;
     /** Open a {@link CrbmReader} for an already-resolved generation target (decrypting if the segment is encrypted). */
     private openForTarget;
     private openGeneration;
     /**
-     * Open the generation a resolution found, and hold the row's summary against the object while it is open anyway:
-     * the same count and metadata, or the summary is not believed again in this process ({@link distrusted}). This
-     * costs no request; a mismatch is not an error, since the object is the truth and this read has it.
+     * Open the generation a resolution found, and hold the row's summary against the object: the object must be the one
+     * the summary names by its fingerprint, and is refused before its index is opened otherwise, as another object under
+     * the generation's number ({@link NotFoundError}, so the read resolves the row again, as for a swept generation); and
+     * 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;
     /** What the row says of the generation, unless it is a summary this process has found to disagree with its object. */
     private trustedSummary;
     /**
-     * The current generation + its DEK wrappings: the registry's authoritative record (one strong read), or a
-     * `list` scan for the max generation when there's no registry (a registry-less source can only read cleartext
-     * — there's nowhere a wrapped DEK could live). The row's summary rides along, to be used or not by whoever
-     * asks.
+     * What the segment resolves to now: the fields of the registry's authoritative record a read resolves through (one
+     * strong read), or the highest generation a `list` of the bucket finds when there is no registry (a registry-less
+     * source can only read cleartext: there is nowhere a wrapped DEK could live). `null` for no generation.
+     */
+    private resolve;
+    /**
+     * The segment resolved afresh for a pin, with the row it read, which a lease is written against. Never a kept
+     * resolution, and kept nowhere: the generation current right now is the whole promise of a pin.
      */
     private resolveLive;
+    /**
+     * What a snapshot, or a pin, makes of a resolution: its decryption context and what the row's summary says of the
+     * generation, each made only when asked for. A snapshot that replaces `prior` with the same wrapped keys keeps the key
+     * `prior` unwrapped, so a count polling an encrypted segment asks the keystore once, not once each `genTtlMs`.
+     * Different keys (a shred, a re-created name) unwrap afresh, and so does a snapshot with no prior: the resolution
+     * holds the wrapped keys, never an unwrapped one.
+     */
+    private liveOf;
     /** Build the per-generation decryption context for an encrypted segment (undefined for cleartext). */
     private cryptoForRead;
     getChunk(ref: ChunkRef): Promise<Uint8Array | null>;
@@ -397,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[]>;
@@ -407,16 +522,35 @@ export declare class CrbmStorageChunkSource implements StorageChunkSource {
      * it can: the row's summary of the generation it names, on an active row, in the shape the row's keys call for
      * (a sealed one is opened with the segment's key), and one this process has not found to disagree with its
      * object. That is one registry read when the snapshot is cold, none when it is warm, and no read of the object.
-     * With no summary it can use (an older row, one for another generation, one that does not open), it opens the
-     * generation and answers from the object. A row that names an object that is gone still answers, while a read
-     * of the object throws: the number is true of the generation the row names.
+     * With no summary it can use (a row written without one, one for another generation, one that does not open), it
+     * opens the generation and answers from the object. A row that names an object that is gone, or another object
+     * under the number, still answers, while a read of the object throws: the number is true of the generation the row
+     * names.
      *
      * What the row says is not confirmed here: a summary edited to agree with itself by whoever can write the row is
      * believed until the next time the object is opened, which holds it against the summary.
      */
     summary(ref: SegmentRef): Promise<GenerationSummary | null>;
+    /**
+     * What one resolution of the segment says of its generation: from the row's summary when this process may use it,
+     * else from the generation's object, opened. `null` for no generation. One heal, as a read of the object has: a
+     * generation swept from under the snapshot, or replaced under its number, is resolved again once.
+     */
+    private described;
     /** {@link summary} of a specific generation, from the object a pin holds. `held` as for {@link getChunkAt}. */
     summaryAt(ref: SegmentRef, generation: number, held?: PinnedObject): Promise<GenerationSummary | null>;
+    /**
+     * The current generation's number, id count and metadata, with its object's size, all from one resolution. The answer
+     * comes from the row when it can, as {@link summary}'s does: the row's summary of the generation it names, whose
+     * fingerprint carries the object's size. That is one registry read when the snapshot is cold, none when it is warm,
+     * and no read of the object; on an encrypted segment the key is unwrapped to open the summary, as for a count. With no
+     * summary it can use, it opens the generation and answers from its footer and index, with no payload read: a tail read
+     * more when cold. A row that names an object that is gone, or another object, still answers from the row: the figures
+     * are the generation's the row names, and `checkConsistency` is what finds such a row.
+     */
+    stat(ref: SegmentRef): Promise<(GenerationSummary & SegmentSize) | null>;
+    /** {@link stat} of a specific generation, from the object a pin holds. `held` as for {@link getChunkAt}. */
+    statAt(ref: SegmentRef, generation: number, held?: PinnedObject): Promise<(GenerationSummary & SegmentSize) | null>;
     /**
      * Run `read` against the pinned snapshot, healing the torn-read window generation GC can open: if the
      * generation we resolved was superseded *and* swept (the grace window elapsed), the Storage driver throws
@@ -424,8 +558,8 @@ export declare class CrbmStorageChunkSource implements StorageChunkSource {
      * caller-visible error, so instead we drop the stale snapshot,
      * re-resolve `currentGen`, and retry once — the read then serves the newer (committed, immutable) generation,
      * a monotonic move forward — within one incarnation of the row. A name that was retired and re-created is a
-     * different segment and can resolve to a LOWER generation, which is why the snapshot carries the row's token
-     * as its lineage rather than trusting the generation number (invariant 1).
+     * different segment and can resolve to a LOWER generation, which is why the snapshot carries the row's
+     * `pointerId` as its lineage rather than trusting the generation number (invariants 1 and 2).
      *
      * **Resolution and open are inside the retry, not before it.** Resolving `currentGen` and opening that
      * generation's object are two backend round trips with a gap between them, so the object can be swept after
@@ -439,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
@@ -456,393 +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;
-}>;
-/**
- * Whether the object under `key` is provably the one `fingerprint` names ({@link CrbmReader.fingerprint}), from one
- * read of its footer. False when it is another object, when it is gone, and when the read fails in any way: a caller
- * that deletes on `true` deletes nothing it cannot prove is its own.
- */
-export declare function holdsObject(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. */
-export declare function objectIsEncrypted(storage: IStorageDriver, key: GenKey): 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;
-}
-/**
- * {@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 holdsObject}, 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.
- */
-export declare function openGenerationReader(storage: IStorageDriver, key: GenKey, crypto: CrbmCrypto | undefined, options?: Omit<CrbmReaderOptions, 'crypto'>): Promise<CrbmReader>;
-/**
- * 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>;