@cloudbitmaps/core 0.19.1 → 0.20.0

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

@@ -53,7 +53,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. 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;
     /**
@@ -67,7 +69,8 @@ export interface CrbmStorageChunkSourceOptions extends CrbmReaderOptions {
      * 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 index 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;
 }
@@ -81,12 +84,12 @@ export interface PinnedObject {
     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. */
@@ -112,6 +115,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
@@ -141,6 +159,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 +176,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 +189,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 +283,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 +344,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 +376,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,7 +406,7 @@ 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
@@ -356,30 +419,48 @@ 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.
      */
     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>;
@@ -407,16 +488,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 +524,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
@@ -475,13 +575,27 @@ export declare function writeCrbmGeneration(driver: IStorageDriver, key: GenKey,
     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.
+ * 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 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>;
+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
@@ -678,6 +792,12 @@ export interface PublishResult {
      * 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:
@@ -686,7 +806,7 @@ export interface PublishResult {
 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
+ * 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>;
@@ -829,9 +949,29 @@ export declare function bulkLoadAhead(driver: IStorageDriver, ref: SegmentRef, a
 /**
  * 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.
+ * 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 openGenerationReader(storage: IStorageDriver, key: GenKey, crypto: CrbmCrypto | undefined, options?: Omit<CrbmReaderOptions, 'crypto'>): Promise<CrbmReader>;
+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

package/dist/core/engine.d.ts

@@ -3,7 +3,7 @@ import type { Budget, BudgetOption } from './budget.js';
 import type { Clock } from './determinism.js';
 import type { BoundedLru } from './lru.js';
 import type { IMetricsSink } from './metrics.js';
-import type { GenerationMetadata, StorageChunkSource, SegmentRef, SegmentSize } from './ports.js';
+import type { GenerationMetadata, StorageChunkSource, SegmentRef } from './ports.js';
 /**
  * Range requests a stream holds ahead of a combine or `iterate` by default (chunk keys, on a source that reads chunk by
  * chunk, and for `count`'s fallback) — bounds memory and concurrent reads (invariant 6). A read that does not fit
@@ -128,20 +128,21 @@ export declare class SegmentEngine {
      */
     count(seg: SegmentRef): Promise<number>;
     /**
-     * What the segment's current generation is: its number, its id count and its metadata, from one resolution, so the
-     * three cannot straddle a publish. A source with no summary answers from `count()` and the generation it resolves.
+     * What the segment's current generation is: its number, its id count, its metadata and the size of its object in
+     * bytes. A source with a `stat` (the `.crbm` source) answers all four from one resolution, so they cannot straddle
+     * a publish: from the registry row's summary when it can use it, else from the opened generation's footer and
+     * index, with no payload read. A source without one answers from its other methods, each its own resolution: its
+     * summary when it has one, else `count()` and the generation it resolves, and its `sizeOf`, or `sizeBytes: null`
+     * when it has none. A segment with no generation answers `{ generation: null, cardinality: 0, sizeBytes: null }`.
      */
     stat(seg: SegmentRef): Promise<{
         generation: number | null;
         cardinality: number;
         metadata?: GenerationMetadata;
+        sizeBytes: number | null;
     }>;
-    /** Whether the Storage source can measure segment size (for grounded cost); false ⇒ storage isn't grounded. */
-    get supportsStorageSize(): boolean;
-    /** How often the Storage source re-reads a pointer while reading (cost reporting); undefined if it does not say. */
-    get pointerRefreshMs(): number | undefined;
-    /** Grounded Storage size of a segment's current generation (cost reporting), or null if it has no generation. */
-    segmentSize(seg: SegmentRef): Promise<SegmentSize | null>;
+    /** The size of the segment's current generation from the source's `sizeOf`, or `null` when it cannot say. */
+    private sizeOf;
     /** The chunks of `seg` at `chunkKeys`, read through a window of {@link DEFAULT_INTERSECT_CONCURRENCY}. */
     private chunkWindow;
     /**
@@ -219,11 +220,13 @@ export declare class SegmentEngine {
      * the result — every chunk read is a whole, checksum-verified, immutable generation. The edge a *long* call can
      * hit is invariant 3's: if it straddles a mid-call `cache.genTtlMs` boundary and a load has published, an
      * operand's not-yet-requested chunks may re-resolve forward to the newer generation (a generation hop within one long
-     * call) — the call never crashes or returns a torn object, but may mix generations. Three things hop it without
-     * waiting for the TTL, so a shorter call can meet them too: **the reader cache evicting an operand mid-call**
-     * (`maxOpenSegments`), whose re-read re-resolves fresh; a sweep deleting the generation it was reading, which
-     * heals the read forward; and an invalidation, which this store's own `load`, `rollback` and `eraseSubject` make
-     * and `invalidate()` makes on request. Still whole/immutable per read, never torn. An operand's stream resolves its
+     * call) — the call never crashes or returns a torn object, but may mix generations. Some things hop it without
+     * waiting for the TTL, so a shorter call can meet them too: **the reader cache evicting an operand mid-call** on a
+     * store with no timed refresh (`maxOpenSegments`), whose re-read re-resolves fresh, and on a store with one the
+     * resolution cache letting the operand's resolution go; a sweep deleting the generation it was reading, or another
+     * object under its number, met by this read or another, which heals the read forward, as another read's failed open
+     * of the operand does; and an invalidation, which this store's own `load`, `rollback` and `eraseSubject` make and
+     * `invalidate()` makes on request. Still whole/immutable per read, never torn. An operand's stream resolves its
      * segment again before it serves each chunk, so each of those moves a running read as it would a read of one chunk, and
      * the ranges it had requested of the earlier generation are dropped, not served.
      */