@cloudbitmaps/core 0.19.1 → 0.20.0

package/dist/core/erase-id.d.ts

@@ -11,9 +11,11 @@
  *
  * The rewrite is the same generation without one id, so it keeps everything else: the new object carries the source's
  * metadata as it is, and the row's summary of it, built from what was written, counts one id fewer and holds the same
- * metadata. Metadata is not scanned for the id. On an encrypted segment, a source object with no metadata block whose
- * row's sealed summary of it has metadata is rewritten with the row's: the block's presence is not authenticated, so
- * the authenticated copy decides, and the erasure still goes through.
+ * metadata. Metadata is not scanned for the id. A source object whose metadata block was stripped is another object
+ * than the row's summary names: its size is not the one the summary records, so the fingerprint check refuses it
+ * before the erasure reads any of its ids. Only one forged to match that fingerprint gets past, and on an encrypted
+ * segment it is rewritten with the metadata of the row's sealed summary: the block's presence is not authenticated, so
+ * the authenticated copy decides.
  *
  * **`erased: true` is a claim about every generation of the segment, not only the one it replaced.** A rollback
  * leaves generations above the pointer that were once current and can be made current again, so a holder can sit
@@ -48,16 +50,17 @@
  * Which reason comes from **re-reading the row**, not from assuming a supersession: a moved pointer is
  * `'superseded'`, a tombstoned row `'destroyed'`, a purged row `'absent'`, a row with no pointer
  * `'no-generation'`. A pointer still on `from` means the object it names is genuinely gone — the forbidden
- * `missing-storage-generation` state — and that throws, because no re-run fixes it. That `NotFoundError` is the only
- * signal of that state, so a faulting re-read rethrows it rather than replacing it with a transient-looking
- * registry error.
+ * `missing-storage-generation` state — or is another object than the row's summary names by its fingerprint, and that
+ * throws, because no re-run fixes either. That `NotFoundError` is the only signal of those states, so a faulting
+ * re-read rethrows it rather than replacing it with a transient-looking registry error.
  *
  * **A refused rewrite deletes its own object when it would outlive the winner above the pointer.** `putImmutable`
  * commits atomically, so a rewrite whose stream throws leaves no object at all. One that completed is either
  * below the winner's pointer, where the winner's collection takes it, or above it: the case where this call took
  * its number after the winner's object was already in the bucket. Up there nothing collects it, and it was derived
  * from a generation the winner has replaced, so when the winner was another erasure it still holds the id that
- * erasure has just reported gone. That object is deleted before this call returns — see `discardRefused`.
+ * erasure has just reported gone. That object is deleted before this call returns, once its footer proves it the
+ * rewrite's own, under the version that read reported — see `discardRefused`.
  *
  * Without that fence the failure was silent and severe, and both halves were reproduced: `nextGeneration` picks a
  * number above everything in the bucket, so a forward-only publish here always won — discarding a concurrent
@@ -68,11 +71,21 @@
  * A live read still fetching from the collected generation heals forward to the rewrite, and a pin of it fails with
  * `NotFoundError` for any chunk it has yet to read: that is the documented cost of physical deletion on return. **Do not re-load the id while erasing it**: a load that lands after this rewrite
  * carries whatever its source held, and the library cannot know that source was meant to exclude the id.
- * A load already in flight writes its object above the pointer before it publishes. An erasure that finds the id in that
- * object writes the row before deleting it, so the load's publish, fenced on the row it read, is refused
- * (`published: false`) and the pointer never names a missing object (see `fenceInFlight`). On a row with no pointer
- * the erasure writes nothing to the row, so a first load's object there may still be published; an erasure that finds
- * the id in it refuses instead of deleting it.
+ * A load already in flight writes its object above the pointer before it publishes, or, as a first load onto a row with
+ * no pointer, before there is a pointer at all. An erasure that finds the id in that object renews the row's `pointerId`
+ * before deleting it, so the load's publish, fenced on the row it read, is refused (`published: false`) and the pointer
+ * never names a missing object (see `fenceInFlight`). An erasure that finds no holder writes nothing.
+ *
+ * An object sealed under a key its row does not hold cannot be searched, and no read of the segment can open it: a
+ * first load's on a row with no pointer, whose key that load has not published; on a segment with a key, a first
+ * load's that lost the race to the one that published, or crashed, under a key it made and never stored; and on a
+ * cleartext segment with a pointer, any encrypted object, since a key is made only for a segment's first generation
+ * and a publish never adds one to a segment that has generations: a first load's that minted a key and crashed, or
+ * lost the race to a cleartext first load. It counts as
+ * a holder whatever the id: an erasure of any id that finds one deletes it, under the same renewal of the row and read
+ * before the delete, and lists it in `collected`, and a first load still in flight that wrote it is refused. Only a
+ * searched object that held the id makes the answer `erased: true`. The current generation is never one of them: one
+ * the row's key does not open throws, as every read of the segment does.
  */
 import { type IAuditSink } from './audit.js';
 import type { CodecInterface } from './codec.js';
@@ -98,11 +111,15 @@ export interface EraseIdDeps {
     readonly keystore?: IKeystore;
     /** When true, refuse to rewrite a **cleartext** segment (the same guard the read path and a load offer). */
     readonly requireEncryption?: boolean;
-    /** Supplying a clock that can yield makes the rewrite cooperative, as it makes a load. */
+    /**
+     * Supplying a clock that can yield makes the rewrite cooperative, as it makes a load. Its `sleep` is what a registry
+     * write that got no answer waits on before a fresh one is sent; with no `sleep`, such a write is not sent again and
+     * its `TransientError` is thrown.
+     */
     readonly clock?: Yielder;
     /**
-     * The random source that spreads the waits between the rewrite's fresh compare-and-swaps. Absent, the read retry's
-     * source is used if it has one, and otherwise each wait is its bound.
+     * The random source that spreads the waits between the fresh compare-and-swaps of the rewrite and of the row's
+     * renewal. Absent, the read retry's source is used if it has one, and otherwise each wait is its bound.
      */
     readonly rng?: Rng;
     /** Per-chunk decode ceiling (invariant 5); defaults to 1 MiB. The `.crbm` reader refuses an entry above its own `maxPayloadBytes` (1 MiB, plus 28 bytes when encrypted) at open, so raise that on the chunk source too. */
@@ -111,7 +128,7 @@ export interface EraseIdDeps {
      * The store's read retry, for the reads the rewrite makes along the way: the generation it rewrites and each of its
      * chunks, the read-back that verifies the generation it wrote, and any other generation it checks for the id. A
      * transient fault on one is run again under it rather than failing the erasure. Absent, each read is made once.
-     * The deletes are not retried, and the rewrite's registry write is settled as a load's is.
+     * The deletes are not retried, and the rewrite's registry write and the row's renewal are settled as a load's is.
      */
     readonly readRetry?: ReadRetry;
 }
@@ -127,13 +144,20 @@ export interface EraseIdResult {
     readonly erased: boolean;
     /**
      * Why the id was not erased, when `erased` is false. `'absent'` (no registry row), `'destroyed'` (a crypto-shred
-     * tombstone — already unreadable), `'no-generation'` (a row with no Storage data yet), `'not-member'` (no
-     * generation in the bucket holds the id — the common case across a fleet scan), or `'superseded'`.
+     * tombstone — already unreadable), `'no-generation'` (a row with no generation yet: its bucket can hold first loads'
+     * objects, none of them found to hold the id, and `collected` names any this call deleted unsearched, see below),
+     * `'not-member'` (no
+     * generation in the bucket holds the id — the common case across a fleet scan — with the same note on `collected`),
+     * or `'superseded'`.
      *
      * **`'superseded'` means this call did not erase the id, not that the id is still there.** Another writer — a
-     * load, another erasure, or a rollback — moved the pointer off the generation this call read, so what it was
-     * doing no longer follows from what is current: a rewrite derived from that generation is not a valid successor
-     * to the new one, and a generation it meant to delete above the pointer may be the one the pointer now names.
+     * load, another erasure, or a rollback — moved the pointer off the generation this call read (on a row with no
+     * pointer, any other write of the row before this call renewed it, a `setRetention` included), or replaced an
+     * object it meant to delete (another erasure deleted a holder above the pointer, or on a row with no pointer, and a
+     * load stored another object under its number, so the storage driver's conditional delete refused this call's,
+     * whether or not the pointer moved). What it was doing no longer follows from what is current: a rewrite derived
+     * from that generation is not a valid successor to the new one, and a generation it meant to delete may be the one
+     * the pointer now names, or another object than the one it read.
      * Re-run against the new generation: if the id is still present it is erased then; if the racing writer was
      * another erasure of the *same* id, the re-run reports `'not-member'` because it is already gone. Either way the
      * re-run settles it, which is why it is the documented action for this reason and for no other.
@@ -151,14 +175,20 @@ export interface EraseIdResult {
     readonly fromGeneration?: number;
     /**
      * The generation written without the id (present whenever one was written, even if `superseded`). A refused
-     * rewrite whose object sits above the winner's pointer deletes that object again before it returns.
+     * rewrite whose object sits above the winner's pointer deletes that object again before it returns, when its footer
+     * proves it the rewrite's own.
      */
     readonly generation?: number;
     /**
      * Generations this call deleted. On a rewrite that is normally `[fromGeneration]`, plus any older orphans. When
-     * the current generation did not hold the id, it is every generation below the pointer (`keep: 0` takes them
-     * together) and each one above the pointer that held the id; the ones above it that did not hold the id stay,
-     * because they are an operator's rollback targets. Empty when nothing was deleted.
+     * the current generation did not hold the id and a generation this call searched did, it is every generation below
+     * the pointer (`keep: 0` takes them together) and each one above the pointer that held the id; the ones above it
+     * that did not hold the id stay, because they are an operator's rollback targets. On a row with no pointer it is
+     * each first load's object that held the id. Wherever it found them, it is also each object sealed under a key the
+     * row does not hold, which this call cannot search and deletes whatever the id. When those are the only holders, it
+     * is only those, deleted one by one, and every generation this call searched stays: `reason` is then
+     * `'no-generation'` on a row with no pointer and `'not-member'` on one with a pointer. Empty when nothing was
+     * deleted.
      *
      * **It is what THIS call deleted, not the proof that the id is gone** — those differ: a concurrent collector can
      * take a generation holding the id first, and then `erased: true` is returned without it in `collected`, because
@@ -170,7 +200,10 @@ export interface EraseIdResult {
      * collection pass that could not prove the segment was still the same one (which an ordinary retirement landing
      * mid-call is enough to cause); the same refusal on the path where the current generation did not hold the id
      * and nothing was published at all; and a generation still holding the id when the bucket is listed at the end
-     * — one an operator rolled the pointer onto while a rewrite was collecting, say.
+     * — one an operator rolled the pointer onto while a rewrite was collecting, say, or, on a row with no pointer, the
+     * object of a first load that read the row before this call renewed it and wrote it after this call listed the
+     * bucket. The row write an erasure makes before deleting a holder a load may still publish, when it gets no answer
+     * that reading the row can settle, throws the registry's `TransientError`, and that holder is not deleted.
      *
      * **Re-run it**, and read what the re-run says rather than assuming it finished the job. The re-run looks for
      * the id in every generation in the bucket, not only the current one, and there are three outcomes:
@@ -192,7 +225,9 @@ export interface EraseIdResult {
  * it. See the module note for the contract.
  *
  * Emits one `segment.rewrite` audit event at the publish (before the superseded generation is collected), so the
- * compliance record exists the moment the generation without the id is authoritative.
+ * compliance record exists the moment the generation without the id is authoritative. An erasure that rewrites nothing,
+ * because only other generations held the id, emits one `segment.collect` once no generation holds it, and so does one
+ * that deleted only objects no read of the segment can open, which names no generation the id was found in.
  */
 export declare function eraseIdFromSegment(ref: SegmentRef, id: number, deps: EraseIdDeps, options?: {
     audit?: IAuditSink;

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

@@ -46,7 +46,8 @@ export interface LoadNumber {
  * and collection takes it once a generation above it is current. Like a listing's, the number can be one whose
  * object was deleted (an erasure removes the generations above a rolled-back pointer that held the id), which is
  * why nothing identifies a generation by its number alone: the reader cache and the chunk cache key on the number and
- * the row's token, checked against the object a reader opens, and a pin on its object's fingerprint.
+ * the row's `pointerId`, which every write that takes a number again renews, and an open of a row with a usable
+ * summary holds the object to the fingerprint the summary records; a pin keys on its object's fingerprint.
  */
 export declare function nextLoadGeneration(ref: SegmentRef, deps: GenerationDeps, row: RegistryRecord | null): Promise<LoadNumber>;
 /**

package/dist/core/leases.d.ts

@@ -17,6 +17,13 @@ export declare const MAX_STORED_LEASES = 256;
  * plus a few, so that the most a segment can hold, all arriving at once, can all land.
  */
 export declare const LEASE_CAS_ATTEMPTS: number;
+/**
+ * Fresh writes sent after one that got no answer and left the row as it was, by the lease writers and by an erasure's
+ * renewal of the row.
+ */
+export declare const UNANSWERED_RESENDS = 3;
+/** The upper bound of the first of those waits, in ms; each next one doubles it. */
+export declare const UNANSWERED_BASE_MS = 500;
 /**
  * Whether an entry holds its generation against a collector reading `now`: it has not ended (`until` plus the margin
  * is ahead), and it does not run further past `now` than any honest holder with a clock inside the margin could have

package/dist/core/load.d.ts

@@ -15,9 +15,11 @@
  *
  * Refusing therefore has to clean up after itself. The object is already durable at that point, and it sits
  * ABOVE `currentGen`, where generation collection deliberately never looks (it deletes strictly below the
- * pointer), so a refused load deletes its own object before returning, while the segment's row is unchanged, gone
- * or `destroyed`. Once another write has changed the row, the object's number may name a re-created segment's live
- * object, so it stays, and collection takes it like any other generation once one above it is current.
+ * pointer), so a refused load deletes its own object before returning, while the segment's row is unchanged (or
+ * differs only in its leases), gone or `destroyed`, or has key material when the load wrote cleartext. Under a row
+ * that is gone or keyed, a read of the object's footer must prove it the load's own first. Once another write has
+ * otherwise changed the row, the object's number may name a re-created segment's live object, so it stays, and
+ * collection takes it like any other generation once one above it is current.
  */
 import { type IAuditSink } from './audit.js';
 import { type CodecBitmap, type CodecInterface } from './codec.js';

package/dist/core/metrics.d.ts

@@ -5,8 +5,8 @@
  * Design: the library emits **neutral domain events** and stays vendor-agnostic — you (or a ~12-line
  * adapter) map them to OpenTelemetry / Datadog / a log line. The default is a **no-op**, and emission is
  * skipped entirely when no sink is wired (near-zero overhead, no telemetry dependency). Events carry **raw
- * observations** (bytes, counts, ms); turning those into billable units / dollars is the cost model's job,
- * which keeps rates pluggable.
+ * observations** (bytes, counts, ms); turning those into billable units / dollars is left to whoever reads them,
+ * which keeps rates out of the library (`@cloudbitmaps/tools` prices a workload you give it).
  *
  * Two caveats for sink authors: `onEvent` runs **synchronously on the I/O path**, so keep it cheap and
  * non-blocking (offload batching/network to your own async queue); and `segment`/`namespace` are
@@ -168,9 +168,9 @@ export interface MetricsSnapshot {
     }>>;
 }
 /**
- * A ready-made sink that tallies events into a {@link MetricsSnapshot} — handy for tests, quick scripts,
- * and as the grounded-request-cost source behind `costReport()`. `snapshot()` returns an independent copy;
- * `reset()` zeroes the counters.
+ * A ready-made sink that tallies events into a {@link MetricsSnapshot} — handy for tests, quick scripts, and for
+ * reading the request rates a cost model is given. `snapshot()` returns an independent copy; `reset()` zeroes the
+ * counters.
  */
 export declare class CountingMetricsSink implements IMetricsSink {
     private storage;

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

@@ -53,8 +53,6 @@ export declare class PinnedStorageChunkSource implements StorageChunkSource {
      * wrong answer this exists to prevent.
      */
     pins: ReadonlyMap<string, PinnedAt>);
-    /** The unpinned segments refresh as the store's own source does; a pinned one never does. */
-    get pointerRefreshMs(): number;
     /**
      * The pin for this segment, or `undefined` if it is not pinned here.
      *
@@ -74,12 +72,14 @@ export declare class PinnedStorageChunkSource implements StorageChunkSource {
     sizeOf(ref: SegmentRef): Promise<SegmentSize | null>;
     cardinalities(ref: SegmentRef): Promise<ReadonlyMap<number, number> | null>;
     summary(ref: SegmentRef): Promise<GenerationSummary | null>;
+    stat(ref: SegmentRef): Promise<(GenerationSummary & SegmentSize) | null>;
     currentGeneration(ref: SegmentRef): Promise<number | null>;
     /**
      * A pinned segment reports the version captured when it was pinned, marked as a pin's, so its decoded chunks
      * are cached under keys that no live read writes. A live read keys its fetches by the version it resolved when
      * it began, but is served whatever generation the live source holds when each fetch lands — after a publish
-     * and a lapsed `cache.genTtlMs`, a reader-cache eviction, a sweep that heals the read forward, or an
+     * and a lapsed `cache.genTtlMs`, a reader-cache eviction on a store with no timed refresh, the resolution
+     * cache letting the segment's resolution go on a store with one, a sweep that heals the read forward, or an
      * invalidation, a different one — so an entry under a live version can hold another generation's chunk.
      * Invariant 3 lets that live call see it, and later live reads resolve the current version and never look the
      * entry up; a pin sharing the key would be handed it, and return a read that mixed two generations. A pinned

package/dist/core/pointer-id.d.ts

@@ -0,0 +1,19 @@
+import type { RegistryPatch, RegistryRecord, Token } from './ports.js';
+/** The fields a read resolves through: a patch that names any of them renews the row's `pointerId`. */
+export declare const RESOLVED_FIELDS: readonly ["currentGen", "status", "wrappedDeks", "keyId", "summary"];
+/**
+ * Whether a compare-and-swap of `patch` renews the row's `pointerId`: whether it names a resolved field, by presence
+ * (`'field' in patch`), whatever the value, as every patch rule reads a patch.
+ */
+export declare function renewsPointer(patch: RegistryPatch): boolean;
+/**
+ * The patch that renews a row's `pointerId` and changes nothing a read resolves: the pointer, named at the value it
+ * has. A same-value pointer keeps the summary and the kept window, which follow the pointer only when it changes value.
+ */
+export declare function renewPointer(row: Pick<RegistryRecord, 'currentGen'>): RegistryPatch;
+/**
+ * The row's `pointerId`, refusing a row that has none with {@link UnsupportedError}: a registry written against an
+ * earlier port contract returns rows without it, and a reader that cannot tell which write set the row's resolution
+ * cannot key a cache on it. A TypeScript registry fails to compile instead; this catches one in JavaScript.
+ */
+export declare function pointerIdOf(row: RegistryRecord): Token;

package/dist/core/ports.d.ts

@@ -38,8 +38,9 @@ export interface GenKey extends SegmentRef {
     readonly generation: number;
 }
 /**
- * A segment's grounded on-disk footprint — the current generation's Storage object bytes, read cheaply from the
- * `.crbm` footer/index (no payload reads). Powers the grounded `costReport()`.
+ * A segment's on-disk footprint — the current generation's Storage object bytes, read cheaply from the `.crbm`
+ * footer/index (no payload reads). It is the `sizeBytes` a segment's `stat()` reports, and what bounds the bytes a combine
+ * holds for an operand's stream.
  */
 export interface SegmentSize {
     readonly sizeBytes: number;
@@ -119,16 +120,10 @@ export interface StorageChunkSource {
      */
     getChunks?(ref: SegmentRef, keys: readonly number[], options?: ReadChunksOptions): AsyncIterable<ChunkRead>;
     /**
-     * Optional: the current generation's grounded size, cheaply (from the already-parsed `.crbm` index — no
-     * payload reads), or `null` if the segment has no Storage generation. Powers the grounded `costReport()`.
+     * Optional: the current generation's size, cheaply (from the already-parsed `.crbm` index — no payload reads), or
+     * `null` if the segment has no Storage generation.
      */
     sizeOf?(ref: SegmentRef): Promise<SegmentSize | null>;
-    /**
-     * Optional: how often this source re-reads a segment's pointer while the segment is being read, in ms, or 0 if
-     * it never does. The grounded `costReport()` prices the pointer refresh at this interval; a source that omits it
-     * is priced at the store's default.
-     */
-    readonly pointerRefreshMs?: number;
     /**
      * Optional: the current generation's **per-chunk cardinality** (`chunkKey → count`), read from the
      * already-parsed `.crbm` index with **no payload reads**, or `null` if the segment has no Storage generation.
@@ -144,6 +139,17 @@ export interface StorageChunkSource {
      * summary omits this, and `count()` keeps its other paths.
      */
     summary?(ref: SegmentRef): Promise<GenerationSummary | null>;
+    /**
+     * Optional: what {@link summary} answers, with the size of the generation's object, both from **one** resolution of
+     * the segment, so the size is the size of the generation described; `null` if the segment has no Storage
+     * generation. The `.crbm` source answers from the registry row's summary when it can use it, whose fingerprint
+     * carries the object's size: one registry read and no read of the object. When it cannot, it opens the generation
+     * (one tail read of the object when it is not open already, and a range read for an index longer than the tail) and
+     * answers from its footer and index, with no payload read. For a source that omits it, `stat()` asks
+     * {@link summary} and {@link sizeOf}, two resolutions that can straddle a publish, and reports no size when
+     * there is no `sizeOf` either.
+     */
+    stat?(ref: SegmentRef): Promise<(GenerationSummary & SegmentSize) | null>;
     /**
      * Optional: the segment's **current generation number** as this source resolves it right now (registry
      * `currentGen`, or the highest storage generation), or `null` if the segment has no Storage generation. The engine
@@ -211,6 +217,46 @@ export interface StorageCaps {
     readonly maxObjectBytes: number;
     /** Optional: enables the pure-object `LATEST`-pointer registry variant (S3 conditional put). */
     readonly conditionalPut?: boolean;
+    /**
+     * Optional: `true` when `delete` applies {@link StorageDeleteOptions.ifVersion}. The driver then removes an object
+     * only while it is still the one that version names, by a check the backend applies in the same step as the removal
+     * (a precondition on the request, or a check and a removal with nothing between them), refuses another object under
+     * the key with {@link WriteConflictError}, and reports a `version` on every {@link IStorageDriver.getTail} of an
+     * object. `false` or absent: `delete` ignores `ifVersion` and removes whatever is under the key, and a caller that
+     * decided to delete one object can remove another stored under the key since.
+     *
+     * A driver that learns this from its client may report `false` until its first delete given `ifVersion`; what the
+     * delete does is what it states. The S3 driver does: it reads where the client sends its requests, and whether the
+     * SDK sends the header, on its first such delete, and reports `false` for good when that cannot be found out.
+     */
+    readonly conditionalDelete?: boolean;
+}
+/** What {@link IStorageDriver.getTail} read. */
+export interface TailRead {
+    /** The last `min(maxBytes, size)` bytes of the object. */
+    readonly bytes: Uint8Array;
+    /** The object's true total size, not the number of bytes returned. */
+    readonly size: number;
+    /**
+     * Optional: which object the read saw, as the backend names it (an S3 or Azure Blob ETag, a GCS object generation),
+     * taken from the response that carried `bytes`, or from the metadata read when no bytes were asked for. Opaque, and
+     * compared by equality only, by the driver that reported it. It names the object, not the key: two objects stored
+     * one after the other under one key carry different versions, except where the backend's version is computed from
+     * the bytes (an S3 ETag of an object stored without SSE-KMS or SSE-C is), where two objects with the same bytes, each
+     * stored whole in one request, or each in parts of the same sizes, share one. A driver that reports
+     * `conditionalDelete: true` reports it on every read; another may omit it.
+     */
+    readonly version?: string;
+}
+/** Options of {@link IStorageDriver.delete}. */
+export interface StorageDeleteOptions {
+    /**
+     * Delete the object only while it is the one this version names: the `version` a {@link IStorageDriver.getTail} of
+     * it reported. Pass the one read when the decision to delete was made, never one read after it, or the condition
+     * names whatever is under the key by then. Applied only by a driver that reports
+     * {@link StorageCaps.conditionalDelete}; ignored by any other, and absent, the delete is unconditional.
+     */
+    readonly ifVersion?: string;
 }
 /**
  * Immutable object storage for `.crbm` generations. A "dumb byte mover": it
@@ -239,9 +285,27 @@ export interface StorageCaps {
  *   negative or non-integer offset or length. Never a clamped, short or adjacent read. A pin whose object
  *   was purged and loaded again as a smaller one asks for a range past its end, and this error is what sends it
  *   to check that the object is still the one it pinned.
- * - **`getTail` reports the object's true total size**, not the number of bytes it returned.
+ * - **`getTail` reports the object's true total size**, not the number of bytes it returned, and, where the driver has
+ *   one, the object's `version` ({@link TailRead.version}) from the same response as the bytes.
  * - **`delete` is idempotent.** Deleting an absent key is a no-op, not an error: collection passes race each
- *   other and retry.
+ *   other and retry. That holds with `ifVersion` too: an absent object is a no-op whatever version is given.
+ * - **`delete` with `ifVersion` does what {@link StorageCaps.conditionalDelete} says.** A driver that reports `true`
+ *   removes the object only while it is the one the version names, by a check the backend applies in the same step as
+ *   the removal (S3 `If-Match`, GCS `ifGenerationMatch`, Azure Blob `ifMatch`; in memory, the check and the removal with
+ *   no await between them), and for another object under the key throws {@link WriteConflictError} and leaves it. A
+ *   check made by reading the object first and deleting after is not one step, and does not qualify. Where the service
+ *   answers a failed precondition for a key with no object, the driver looks again before it reports a conflict, so an
+ *   absent object stays a no-op. A driver that reports `false`, or omits it, ignores `ifVersion` and deletes whatever is
+ *   under the key. A number can be taken again once its object is deleted, so this is what keeps a delete decided from
+ *   one read, and delayed, from removing an object stored under the number since: the erasure's delete of a holder
+ *   above the pointer passes the version it read when it searched that object, and a refused load's delete of an
+ *   object it proved its own by a footer read passes the version of that read.
+ * - **A driver that wraps another forwards `ifVersion` and the `version` of a tail read, or reports
+ *   `conditionalDelete: false`.** A wrapper that hands `delete` the key alone, and reports the inner driver's
+ *   capability, makes every conditional delete through it unconditional without a word.
+ * - **A conditional delete may be sent again**, by the backend client's retry, after a lost response: a copy that meets
+ *   its own landed delete finds the object absent, which is its success, and one that meets an object stored since is
+ *   refused. It can remove nothing the first copy could not.
  * - **`list` is strongly consistent, read-after-delete.** Once `delete` has resolved, `list` no longer yields
  *   that generation, and once `putImmutable` has resolved it does. The erasure's re-check for a generation still
  *   holding the id, `dropSegment`'s `generationsRemaining`, the retention sweep's check that a tombstone's storage
@@ -276,15 +340,16 @@ export interface IStorageDriver {
      */
     getRange(key: GenKey, offset: number, length: number): Promise<Uint8Array>;
     /**
-     * Speculative tail read: the last `min(maxBytes, size)` bytes + the object's **true total size**. A missing
-     * object throws {@link NotFoundError}.
+     * Speculative tail read: the last `min(maxBytes, size)` bytes + the object's **true total size**, and its `version`
+     * where the driver has one ({@link TailRead}). A missing object throws {@link NotFoundError}.
      */
-    getTail(key: GenKey, maxBytes: number): Promise<{
-        bytes: Uint8Array;
-        size: number;
-    }>;
-    /** Idempotent: deleting an absent key is a no-op, not an error. */
-    delete(key: GenKey): Promise<void>;
+    getTail(key: GenKey, maxBytes: number): Promise<TailRead>;
+    /**
+     * Idempotent: deleting an absent key is a no-op, not an error. With `options.ifVersion`, on a driver that reports
+     * {@link StorageCaps.conditionalDelete}, the object is removed only while it is the one that version names, and
+     * another object under the key is left and the delete throws {@link WriteConflictError}; any other driver ignores it.
+     */
+    delete(key: GenKey, options?: StorageDeleteOptions): Promise<void>;
     /**
      * Enumerate the generations present for a segment (orphan sweep / latest-gen resolution). Strongly
      * consistent, read-after-delete and read-after-put.
@@ -307,10 +372,12 @@ export type RegistryStatus = 'active' | 'destroyed';
  */
 export type GovernanceMeta = Record<string, unknown>;
 /**
- * A cached description of one generation, carried on the registry row: how many ids it holds, and the metadata it
- * was loaded with. The generation's `.crbm` object stays the truth; this is a copy, written by the same write that
- * moves the pointer, and it names the generation it describes so a copy left behind by a writer that did not
- * carry it can never be taken for another generation's.
+ * A cached description of one generation, carried on the registry row: how many ids it holds, the metadata it was
+ * loaded with, and the fingerprint of its object (its size and footer checksum). The generation's `.crbm` object stays
+ * the truth; this is a copy, written by the same write that moves the pointer, and it names the generation it describes
+ * so a copy left behind by a writer that did not carry it can never be taken for another generation's. The fingerprint
+ * names the object too: a reader checks every object it opens for the row's generation against it, and refuses one
+ * that is another object under that number.
  *
  * Two shapes. On a cleartext segment the values are in the clear. On an encrypted segment (a row with
  * `wrappedDeks`) they are sealed under the segment's data key, as the generation's index is, so the row reveals
@@ -337,6 +404,12 @@ export interface ClearRegistrySummary {
     readonly generation: number;
     /** How many ids the generation holds: an integer from 0 to 2^32. */
     readonly cardinality: number;
+    /**
+     * The fingerprint of the generation's object, `<size>:<footer checksum>` in decimal, as `CrbmReader.fingerprint` and
+     * a pin's `pinnedAt.fingerprint` spell it: the object's size in bytes, which `stat()` reports, and the CRC32C its
+     * footer stores.
+     */
+    readonly fingerprint: string;
     /** The generation's metadata, when it has any. Never the empty object. */
     readonly metadata?: GenerationMetadata;
 }
@@ -345,8 +418,9 @@ export interface SealedRegistrySummary {
     /** The generation this describes. A non-negative safe integer. */
     readonly generation: number;
     /**
-     * Base64 of `nonce(12) ‖ ciphertext ‖ tag(16)`, sealing the cardinality as a little-endian u64 followed by the
-     * metadata's canonical JSON, if any. The count is fixed-width, so the length reveals only the metadata's size.
+     * Base64 of `nonce(12) ‖ ciphertext ‖ tag(16)`, sealing the cardinality as a little-endian u64, the object's size as a
+     * little-endian u64 and its footer checksum as a little-endian u32 (its fingerprint), then the metadata's canonical
+     * JSON, if any. The numbers are fixed-width, so the length reveals only the metadata's size.
      */
     readonly sealed: string;
 }
@@ -430,12 +504,23 @@ export interface RegistryRecord extends SegmentRef {
      * restored from a backup. It holds with overwhelming probability rather than by construction, since the token carries random parts: a
      * 128-bit incarnation id drawn when the row is created, and a 64-bit part drawn for each write. Two incarnations of one
      * name meet with probability 2^-128 for any pair (about n^2 / 2^129 among n of them), and two writes at one counter,
-     * after a restore, with probability 2^-64. A bare decimal token, on a row no 0.12 or later registry has written,
-     * carries neither part.
+     * after a restore, with probability 2^-64.
      */
     readonly token: Token;
+    /**
+     * The token of the most recent write that named a field a read resolves through: the row's create, or a compare-and-swap
+     * whose patch named `currentGen`, `status`, `wrappedDeks`, `keyId` or `summary` (the resolved fields), at any value,
+     * the one the field already had included. A write that names only `leases`, `retention`, `residency` or `keptGens`
+     * leaves it. The registry sets it; a caller never does. Compared by equality only, and never reused under one name,
+     * since a token is not: a reader keys what it caches on a generation with it, so a lease or a policy write leaves a
+     * warm reader's cache standing, and a write that changes the resolution never does.
+     */
+    readonly pointerId: Token;
 }
-/** The caller-settable fields at {@link IRegistryDriver.create} (audit + token are driver-managed). */
+/**
+ * The caller-settable fields at {@link IRegistryDriver.create} (audit, `token` and `pointerId` are driver-managed: the new
+ * row's `pointerId` is the token the create returns).
+ */
 export interface NewRegistryRecord {
     /** `null` ⇒ the segment has no Storage generation yet — see {@link RegistryRecord.currentGen}. */
     readonly currentGen: number | null;
@@ -451,13 +536,18 @@ export interface NewRegistryRecord {
     readonly keptGens?: readonly number[];
 }
 /**
- * Fields a {@link IRegistryDriver.compareAndSwap} may mutate (identity + audit + token are off-limits).
+ * Fields a {@link IRegistryDriver.compareAndSwap} may mutate (identity, audit, `token` and `pointerId` are
+ * off-limits).
  *
  * Presence-based: a field the patch does not mention is left as it was. `summary` is the one exception, because it
  * describes the current generation: a patch that moves `currentGen` and does not mention `summary` drops the old
  * one rather than keep a description of another generation. A `summary` the patch gives must name the
  * `currentGen` the row will have. `keptGens` follows the pointer the same way: a patch that moves `currentGen` and does
  * not mention it drops it, and one that gives it must name only generations below the `currentGen` the row will have.
+ * "Moves" means changes value: a patch that names `currentGen` at the value it has keeps both.
+ *
+ * A patch that names a resolved field (`currentGen`, `status`, `wrappedDeks`, `keyId`, `summary`), by presence and at any
+ * value, sets the row's {@link RegistryRecord.pointerId} to the token the write returns; any other patch leaves it.
  */
 export type RegistryPatch = Partial<Pick<RegistryRecord, 'currentGen' | 'wrappedDeks' | 'keyId' | 'status' | 'retention' | 'residency' | 'summary' | 'keptGens' | 'leases'>>;
 /**
@@ -492,9 +582,7 @@ export interface RegCaps {
      * `true` when this registry's `delete` removes a row from its backend for good, so that no later `list` reads it, and
      * removes it only while it is still the exact version the delete read: by a delete the backend applies under a
      * precondition (an S3 or Azure Blob ETag, a GCS object generation), or under a lock no other writer of the backend
-     * can take. Only a row whose token carries an incarnation id is removed so. A row first written by a release before
-     * 0.12 has a bare decimal token, and a delete still tombstones it: a process on that release, re-creating the name
-     * over nothing, would issue those counters again from 0, so its row could not be told apart from the deleted one.
+     * can take.
      *
      * `false` or absent: every `delete` leaves a tombstone, which every later full `list` still reads. A shipped registry
      * says which it is.
@@ -613,6 +701,10 @@ export declare function isStorageBackend(value: unknown): value is StorageBacken
  *   keeps going; where nothing of the earlier row is left, or the row is restored from a backup to an older counter, the
  *   random parts alone keep the tokens apart: with probability 1 - 2^-128 per pair of incarnations, and 1 - 2^-64 per
  *   pair of writes at one counter.
+ * - **Every row carries its `pointerId`** ({@link RegistryRecord.pointerId}): `create` sets it to the token it returns,
+ *   a `compareAndSwap` whose patch names a resolved field (`renewsPointer` in `@cloudbitmaps/core/driver-kit`) sets it
+ *   to the token that write returns, and every other write leaves it. `get` and `list` return it. A caller's write
+ *   never sets it. A row returned without one fails every read of the segment with {@link UnsupportedError}.
  * - **`delete` is idempotent** without an `expected` token: deleting an absent row is a no-op, not an error.
  *   **With `expected` it is fenced**: it lands only while the row still carries that token, and otherwise throws
  *   {@link WriteConflictError} and leaves the row.
@@ -666,8 +758,8 @@ export interface IRegistryDriver {
      */
     list(namespace?: string): AsyncIterable<RegistryRecord>;
     /**
-     * Remove the row. A registry whose {@link RegCaps.conditionalDelete} is `true` removes a row whose token carries an
-     * incarnation id from its backend; every other row is tombstoned. Either way a later `create` gets a token no
+     * Remove the row. A registry whose {@link RegCaps.conditionalDelete} is `true` removes it from its backend; any other
+     * tombstones it. Either way a later `create` gets a token no
      * earlier incarnation of the name held, but for a collision of probability 2^-128 per pair of incarnations.
      *
      * Without `expected`, idempotent: deleting an absent row is a no-op.

package/dist/core/reader-defaults.d.ts

@@ -1,7 +1,6 @@
 /**
- * The storage reader's defaults, stated once for the two modules that need them: the reader, which applies them,
- * and the cost model, which prices what they cause. The cost model once imported them from the reader itself,
- * which pulled the whole read path into a module that is otherwise arithmetic.
+ * The storage reader's defaults. `@cloudbitmaps/tools` prices what two of them cause and keeps its own copies, which
+ * `tests/tools/store-defaults.test.ts` holds equal to these.
  */
 /** Default TTL (ms) for re-resolving a segment's `currentGen` — the bound on post-publish read staleness. */
 export declare const DEFAULT_CURRENT_GEN_TTL_MS = 2000;
@@ -16,3 +15,15 @@ export declare const REFRESH_RETRY_MS = 500;
 export declare const DEFAULT_MAX_OPEN_SEGMENTS = 1024;
 /** Default aggregate ceiling (bytes) on resident parsed indices in the reader cache — the steady-state byte bound. */
 export declare const DEFAULT_MAX_OPEN_INDEX_BYTES: number;
+/**
+ * How many segments' resolutions a store keeps per reader it keeps open: the resolution cache's count bound is this
+ * times `cache.readerMax` (8,192 by default). A resolution is the few hundred bytes of a row a read resolves through,
+ * kept for `cache.genTtlMs` whether or not the segment's reader is still open, so a store reading more segments at once
+ * than its readers hold keeps more of them than it keeps readers.
+ */
+export declare const RESOLUTIONS_PER_OPEN_SEGMENT = 8;
+/**
+ * The resolution cache's byte bound is `cache.readerMaxBytes` divided by this (4 MiB by default): what it holds is a
+ * sixteenth of what the readers may.
+ */
+export declare const RESOLUTION_BYTES_DIVISOR = 16;

package/dist/core/rollback.d.ts

@@ -95,7 +95,8 @@ export interface RollbackResult {
  * `currentGen`, where generation collection never looks. They stay until loads pass them (the first load whose
  * number one of them holds numbers above them all, and collection then keeps the newest `keep` of what is below its
  * pointer), `dropSegment` deletes them, or a subject erasure
- * deletes them: all of those present when it rewrites, and only those holding the id when the current generation does not.
+ * deletes them: all of those present when it rewrites, and, when the current generation does not hold the id, only those
+ * holding it and any no read of the segment can open, whatever the id.
  * Not collecting them is a deliberate trade: an operator who has just undone a bad load should not have the
  * evidence collected out from under them, while a rollback target that still holds erased data would make the
  * erasure undoable by an ordinary operator action.