@cloudbitmaps/core 0.20.0 → 0.22.0

package/dist/core/errors.d.ts

@@ -15,20 +15,26 @@
  * does not match — and silently, because a `catch` that stops matching just falls through, defeating
  * transient retry and the publish path's conflict handling with no error of its own.
  *
- * `Symbol.for` is identity-stable across copies, bundles and realms, so classify errors with the exported
- * predicates below (never `instanceof`) anywhere an error may cross that boundary.
+ * `Symbol.for` is identity-stable across copies, bundles and realms, so classify errors with `errorKind`
+ * (never `instanceof`) anywhere an error may cross that boundary.
  */
 declare const ERROR_BRAND: unique symbol;
 declare const TRANSIENT_BRAND: unique symbol;
 /** Base class for every error CloudRoaring throws. */
 export declare class CloudRoaringError extends Error {
-    /** Cross-bundle brand — see the predicates ({@link isCloudRoaringError}, …). Non-enumerable-ish (symbol key ⇒ not in JSON). */
+    /** Cross-bundle brand — see {@link errorKind}. Non-enumerable-ish (symbol key ⇒ not in JSON). */
     readonly [ERROR_BRAND]: true;
     constructor(message: string);
 }
-/** Invalid caller input (bad id, segment name, options). Raised before any storage call. */
+/**
+ * Invalid input, which the same call fails on again. Most is refused before any storage call (a bad id, segment name
+ * or option); some is found by the call itself: a read past the end of an object, or a bucket or container a cloud
+ * driver finds does not exist.
+ */
 export declare class ValidationError extends CloudRoaringError {
 }
+/** What a contention {@link WriteConflictError} ends with: the call is safe to run again. */
+export declare const CONTENTION_NEXT_STEP = "; another writer changed the segment's row while this call ran. Re-run the call: it reads the row afresh";
 /** An OCC conditional write/delete lost the race — the row changed since it was read. */
 export declare class WriteConflictError extends CloudRoaringError {
 }
@@ -93,14 +99,46 @@ export declare class UnsupportedError extends CloudRoaringError {
 export declare class CapabilityError extends CloudRoaringError {
 }
 /**
- * An operation would exceed its per-op **denial-of-wallet budget** — too many backend requests for a single
- * `count`/`iterate`/`intersect`/`subjectReport`/`eraseSubject` call — so it is refused **before** fanning out
- * (hard invariant 6). Default-on but generous (normal ops never hit it); tune it
- * per store (`budget`) or per op, or disable with `budget: false`. Deterministic (never retried): the op is too
- * big by policy, not by luck. Each request's bytes are separately capped (the safe-deserialize ceiling), so
- * bounding the request count transitively bounds bytes. Carries the projected count + the limit, never data.
+ * An operation would exceed one of its per-op **denial-of-wallet bounds** — too many backend requests
+ * (`budget.maxRequests`), too many bytes held at once by a combine (`maxBufferedBytes`), or too many registry rows
+ * in a scan (`maxScanSegments`) — so it is refused, before the fan-out where it can be known beforehand (hard
+ * invariant 6). Default-on but generous (normal ops never hit it); tune each per store or per op, or disable the
+ * request budget with `budget: false`. Deterministic (never retried): the op is too big by policy, not by luck.
+ * Each request's bytes are separately capped (the safe-deserialize ceiling), so bounding the request count
+ * transitively bounds bytes.
+ *
+ * Carries an option name and two numbers, and no data: `option` names the option to raise, `limit` is the bound in
+ * force, and `spent` is what the call had reached when it was refused. What `spent` measures depends on `option`:
+ *
+ * - `'budget.maxRequests'`: the requests the call needs, which raising the option to it lets through. For a plan, it
+ *   is the planned reads (with the reads already taken, when a run plans again); an enumeration that
+ *   stops at the bound reports `limit + 1`, a lower bound.
+ * - `'maxBufferedBytes'`: a **lower bound** on the bytes the call needs resident: what it held plus what it asked
+ *   for at the moment it was refused. Raising the limit to `spent` can be refused again, further on, because the
+ *   call had not finished growing. The one figure that lets an output through is the per-output refusal's, which
+ *   the message gives as "raise maxBufferedBytes to at least N". Otherwise raise the limit with room to spare, or
+ *   split the outputs across calls.
+ * - `'maxScanSegments'`: `limit + 1`, a lower bound: the scan stops at the first row past the bound (for the retention
+ *   sweep's due-index scan, the first due-index pointer, unread, which may be stale), so it never learns the fleet's
+ *   size.
+ *
+ * The message states the same limit.
  */
 export declare class BudgetExceededError extends CloudRoaringError {
+    /** The option to raise to let the call through. */
+    readonly option: 'budget.maxRequests' | 'maxBufferedBytes' | 'maxScanSegments';
+    /** The bound in force: requests, bytes or rows, by `option`. */
+    readonly limit: number;
+    /**
+     * What the call had reached when refused. By `option`: the requests the call needs (`'budget.maxRequests'`), a
+     * lower bound on the resident bytes it needs (`'maxBufferedBytes'`), or `limit + 1` (`'maxScanSegments'`).
+     */
+    readonly spent: number;
+    constructor(message: string, details: {
+        readonly option: 'budget.maxRequests' | 'maxBufferedBytes' | 'maxScanSegments';
+        readonly limit: number;
+        readonly spent: number;
+    });
 }
 /**
  * An encrypted segment's data key (DEK) cannot be unwrapped because the keystore holds none of the
@@ -148,7 +186,9 @@ export declare function isLeaseLimitError(err: unknown): err is LeaseLimitError;
 export declare function isNotFoundError(err: unknown): err is NotFoundError;
 /** Corrupt/oversized/failed-checksum bytes from a tier. */
 export declare function isIntegrityError(err: unknown): err is IntegrityError;
-/** Invalid caller input. */
+/**
+ * Invalid caller input; also the error a cloud driver raises for a bucket or container it finds does not exist.
+ */
 export declare function isValidationError(err: unknown): err is ValidationError;
 /** This build or this store's wiring cannot do what was asked, though nothing is malformed. */
 export declare function isUnsupportedError(err: unknown): err is UnsupportedError;
@@ -158,4 +198,14 @@ export declare function isCapabilityError(err: unknown): err is CapabilityError;
 export declare function isBudgetExceededError(err: unknown): err is BudgetExceededError;
 /** No key the keystore holds can unwrap an encrypted segment's data key. */
 export declare function isKeyUnavailableError(err: unknown): err is KeyUnavailableError;
+/** The name of one of the library's error classes, as `errorKind` returns it. */
+export type ErrorKind = 'CloudRoaringError' | 'ValidationError' | 'WriteConflictError' | 'IntegrityError' | 'NotFoundError' | 'UnsupportedError' | 'CapabilityError' | 'TransientError' | 'KeyUnavailableError' | 'BudgetExceededError' | 'LeaseExpiredError' | 'LeaseLimitError' | 'StaleOperandError';
+/**
+ * Which of the library's error classes `err` is, or `undefined` when it is none of them. Works on every copy of
+ * the package, every bundle and every realm, where `instanceof` can silently stop matching: it reads the
+ * `Symbol.for` brands and the error's `name`. An application's own subclass of one class returns
+ * `'CloudRoaringError'`, except a subclass of `TransientError`, which returns `'TransientError'`; an error
+ * cloned out of a worker (the brand is gone) returns `undefined`.
+ */
+export declare function errorKind(err: unknown): ErrorKind | undefined;
 export {};

package/dist/core/leases.d.ts

@@ -18,8 +18,8 @@ export declare const MAX_STORED_LEASES = 256;
  */
 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.
+ * Fresh writes sent after one that got no answer and left the row as it was, by the lease writers, by an erasure's
+ * renewal of the row and by a publish: four sends of the row write in all.
  */
 export declare const UNANSWERED_RESENDS = 3;
 /** The upper bound of the first of those waits, in ms; each next one doubles it. */
@@ -65,7 +65,7 @@ export declare const LEASE_ONLY_RETRIES: number;
  */
 export declare function onlyLeasesDiffer(held: RegistryRecord, now: RegistryRecord, alsoIgnore?: readonly (keyof RegistryRecord)[]): boolean;
 /** A writer's count of the lease-only changes it has waited out, and the wait. One per call of the writer. */
-export interface LeaseChurn {
+interface LeaseChurn {
     /**
      * When `now` is `held` changed only in its leases and the bound is not spent: wait, then read the row again with
      * `reread`, and return what it found. The wait comes before the read, so the writer's next write is made against a row
@@ -124,3 +124,4 @@ export declare function takeLease(ref: SegmentRef, deps: LeaseDeps, take: LeaseT
  * races and the registry's `TransientError` for a write that stayed unanswered over an unchanged row.
  */
 export declare function releaseLease(ref: SegmentRef, deps: LeaseDeps, holder: string): Promise<void>;
+export {};

package/dist/core/load.d.ts

@@ -1,29 +1,6 @@
-/**
- * `loadSegment` — the loaded store's primary write path, as one call.
- *
- * A load is always the same four steps: take the next generation number, write one immutable object, move the
- * pointer, collect what the move superseded. Inside the library each is its own internal function, and the
- * step a hand-composed load leaves out is the last one, so a store that composed it would accumulate superseded
- * generations it keeps paying for.
- * Composing it here, once, is the point.
- *
- * The other reason it is one call is the **guard**. A load REPLACES a segment: whatever the stream contains is
- * what the segment contains afterwards. That makes an upstream query returning fewer rows than usual — or none —
- * a silent, successful-looking wipe, and nothing downstream can tell it from a legitimate shrink. The guard is
- * the place to say what a plausible result looks like, and it has to sit **between the write and the publish**,
- * because that is the only moment where the new content is known and the old one is still authoritative.
- *
- * 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 (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';
-import type { Clock, Rng } from './determinism.js';
+import type { Clock, Entropy, Rng } from './determinism.js';
 import type { IKeystore } from './crypto.js';
 import { type LoadInput } from './load-input.js';
 import { type ReadRetry } from './retry.js';
@@ -41,6 +18,14 @@ export interface LoadDeps {
      * bound). Absent, the read retry's source is used if it has one, and otherwise each wait is its bound.
      */
     readonly rng?: Rng;
+    /**
+     * The source of the write's identity: 12 random bytes the new generation's footer carries (for a cleartext generation;
+     * an encrypted one carries its index's AEAD nonce), so two loads of the same ids at the same number are two objects
+     * and every check that a footer is "mine" names this write. Required: a load without one (a JavaScript caller can
+     * leave it out) is refused with {@link ValidationError} before any read, keystore call or write.
+     * `@cloudbitmaps/roaring` supplies Web Crypto's by default.
+     */
+    readonly entropy: Entropy;
     /**
      * The store's read retry, for the read the guard makes of the current generation: a transient fault there is run
      * again under it rather than failing the load. Absent, the read is made once. It does not govern the write: a
@@ -98,12 +83,20 @@ export interface LoadGuard {
  * `'outputs[3].'`).
  */
 export declare function checkedGuard(guard: LoadGuard | undefined, where: string): LoadGuard | undefined;
+/**
+ * Options of `store.load` and of core's `loadSegment`: what a load may publish (`allowEmpty`, `guard`), what it keeps
+ * (`keep`) and what it records (`metadata`, `audit`).
+ */
 export interface LoadOptions {
     /**
      * Publish an empty generation over a non-empty one. Off by default: an empty result is far more often an
      * upstream failure than an intent, and the failure is indistinguishable from success once it lands.
      */
     readonly allowEmpty?: boolean;
+    /**
+     * Bounds a plausible result must meet, judged before the pointer moves; a load outside them is refused
+     * (`published: false`), not thrown. See {@link LoadGuard}.
+     */
     readonly guard?: LoadGuard;
     /**
      * Generations to keep below the new pointer as a grace window (default 1). A non-negative integer: anything
@@ -116,14 +109,21 @@ export interface LoadOptions {
      * longest pinned job runs, on every writer that loads the segment — see "Generations and `keep`" in the loading
      * guide.
      *
-     * The segment's row records the generations a load keeps, up to 64, so a load that found nothing above the pointer
-     * collects without listing: it deletes the generations its publish pushed out of the window, and lists the segment's
-     * objects on every sixteenth generation to take whatever that pass leaves, such as an object a crashed load left
-     * below the pointer. A `keep` above 64 records no list and lists on every load, and so does the first load of a
-     * row that records none, which then records it; so does a load whose check found the current generation's object
-     * gone: the guard's read of it, or, when the guard took the size from the row's summary, one zero-byte read made
-     * before a `keep` of 1 or more takes a name. A `keep` at least the generation published collects nothing and asks
-     * for nothing.
+     * The window is the `keep` most recently current generations below the one the load publishes, so the generation the
+     * load superseded comes first. After a rollback that is the one the rollback restored, and it stays in the window of
+     * every load after it, ahead of the generations the rollback moved away from, for as many loads as `keep` says.
+     *
+     * The segment's row records the generations a load keeps, up to 127.
+     *
+     * With a `keep` of at most 64, a load whose number one existence check found free deletes by name the generations
+     * its publish pushed out of the window, and lists the segment's objects on every sixteenth generation to take
+     * whatever that pass leaves, such as an object a crashed load left below the pointer.
+     *
+     * A load lists instead on every load when `keep` is above 64, when the row has a pointer and no usable record (the
+     * load starts one from the bucket), when the row's record names more than 64 generations below the pointer that no
+     * lease holds (as after a `keep` above 64, or `materializeMany`), or when the guard's read, or the zero-byte read
+     * before a delete by name, finds the current generation's object missing. A publish that a read of the row settles
+     * after its last attempt lists too. A `keep` at least the generation published collects nothing and asks for nothing.
      */
     readonly keep?: number;
     /**
@@ -138,15 +138,11 @@ export interface LoadOptions {
      * over as it is. Sealed under the segment's key when the segment is encrypted.
      */
     readonly metadata?: GenerationMetadata;
+    /** Audit sink for this load: it receives `segment.publish`, or `segment.load-refused` when the load is refused. */
     readonly audit?: IAuditSink;
 }
 /** The bounds a guard can refuse a generation for: every {@link LoadRefusal} but a lost race. */
 export type GuardRefusal = Exclude<LoadRefusal, 'superseded'>;
-/**
- * The bound a generation of `cardinality` ids breaks over a current one of `before` (`null`: none, or not read), in the
- * order a load checks them, or `undefined`. Pure: the one judgement a load and a dry run share.
- */
-export declare function guardRefusal(cardinality: number, before: number | null, guard: LoadGuard | undefined, allowEmpty: boolean | undefined): GuardRefusal | undefined;
 /** What a dry run learns about one write: the size it would replace, and the bound that would refuse it. */
 export interface LoadJudgement {
     /**
@@ -165,7 +161,7 @@ export interface LoadJudgement {
  * would, and an encrypted one with no keystore the `KeyUnavailableError`. What it says holds for now only: a load
  * made later is judged against the segment as it is then.
  */
-export declare function judgeLoad(ref: SegmentRef, cardinality: number, deps: LoadDeps, options?: Pick<LoadOptions, 'allowEmpty' | 'guard'>): Promise<LoadJudgement>;
+export declare function judgeLoad(ref: SegmentRef, cardinality: number, deps: Omit<LoadDeps, 'entropy'>, options?: Pick<LoadOptions, 'allowEmpty' | 'guard'>): Promise<LoadJudgement>;
 /** Why a load did not become current. */
 export type LoadRefusal = 'empty' | 'min-cardinality' | 'min-retained' | 'max-growth'
 /**
@@ -173,16 +169,23 @@ export type LoadRefusal = 'empty' | 'min-cardinality' | 'min-retained' | 'max-gr
  * put refused this one and it wrote nothing (`size: 0`); or the segment's registry row changed while the load was
  * writing: another load published, a retention change, a rollback or an erasure wrote the row, the row was
  * deleted, or a row appeared where the load found none. Once another write has changed the row, the object stays in
- * the bucket, still billed, until a later load's collection deletes it (at the latest the listing a load runs
- * every sixteenth generation) or the segment is dropped, because its generation number may by then name another
- * incarnation's live object; once the row is `destroyed` (dropped or crypto-shredded), the object is deleted, and
- * once the row is gone, so is an object its footer proves this load's own.
+ * the bucket, still billed, until a later load's collection deletes it or the segment is dropped, because its
+ * generation number may by then name another writer's object; until it goes, a rollback onto it needs `allowUnknown`, as onto any generation the row does not know. Once the row is
+ * `destroyed` (dropped or crypto-shredded), the object is deleted; once the row is gone, so is an object whose footer
+ * matches what this load wrote (another load's object of the same ids is not a match: the footer carries each write's
+ * own identity), and so is a cleartext one under a row with key material.
  */
  | 'superseded';
+/**
+ * What a load did: the generation it wrote, whether that is now current (`published`, and `reason` when not), the
+ * object it wrote and what it collected.
+ */
 export interface LoadResult {
     /**
      * The generation written. Present even when refused: a refusal deletes that object while the segment's row is
-     * unchanged or `destroyed`, or gone once its footer proves it this load's own, and leaves it in the bucket once another write has changed the row. A load that lost its
+     * unchanged or `destroyed`, and, once one read of its footer matches what the load wrote, when the row is gone or,
+     * for a cleartext object, has key material. Under any other row another write changed, the object stays in the
+     * bucket, an orphan a later load's collection takes, and until then a rollback onto it needs `allowUnknown`. A load that lost its
      * generation number to another wrote nothing, and reports `size: 0`.
      */
     readonly generation: number;
@@ -190,10 +193,19 @@ export interface LoadResult {
     readonly published: boolean;
     /** Set only when `published` is false. */
     readonly reason?: LoadRefusal;
+    /**
+     * Bytes of the generation's object as stored, or 0 when another load took the generation number first and
+     * nothing was written.
+     */
     readonly size: number;
+    /**
+     * SHA-256 of the object as stored, or `''` when another load took the generation number first. The library neither
+     * keeps nor checks it; reads are checked with CRC32C.
+     */
     readonly sha256: string;
+    /** Non-empty chunks in the generation written (at most 65,536), or 0 when nothing was written. */
     readonly chunkCount: number;
-    /** Distinct ids in the generation that was written, post-dedup. */
+    /** Distinct ids in the generation that was written, post-dedup, or 0 when nothing was written. */
     readonly cardinality: number;
     /**
      * What the segment held when the guard judged it — `null` when there was no current generation, or when no
@@ -218,7 +230,8 @@ export interface LoadResult {
  *
  * `input` is ids, or a whole bitmap as `{ serialized }` portable Roaring bytes or a `{ bitmap }` with
  * `serialize('portable')` ({@link LoadInput}). A bitmap input is checked, decoded and serialized before the first
- * request, and is written from its own chunks; the generation is byte for byte the one its ids would write.
+ * request, and is written from its own chunks; the generation holds chunk for chunk what its ids would write, and carries its own write
+ * identity in the footer like any other.
  *
  * Returns what was written and whether it became current. A refusal is **not** an exception: `published: false`
  * with a `reason` is a normal outcome a caller branches on, in the same shape as a successful load, because the

package/dist/core/lru.d.ts

@@ -1,19 +1,5 @@
-/**
- * Bounded LRU cache with optional TTL — the cache tier's memory ceiling.
- *
- * Time comes from an injected `Clock` (never `Date.now()`) so the cache is deterministic
- * under simulation.
- *
- * The cache can be bounded by entry **count** (`maxEntries`, always) and, optionally, by an aggregate
- * **byte weight** (`maxBytes`). The byte bound exists for values whose footprint is large and uneven — the
- * storage reader cache, where one entry pins a fully-parsed `.crbm` index that can be ~6 MB for a wide segment
- * yet a few hundred bytes for a small one (a count-only bound lets 1024 wide indices blow a Lambda's
- * memory even though the count is "in bounds"). Weights arrive **after** insertion (a cached reader is a
- * pending promise; its size is known only once it resolves), so weight is reported via {@link setWeight} and
- * eviction re-runs then.
- */
 import type { Clock } from './determinism.js';
-export interface LruOptions {
+interface LruOptions {
     /** Hard ceiling on entries; the least-recently-used is evicted past it. */
     readonly maxEntries: number;
     /**
@@ -67,3 +53,4 @@ export declare class BoundedLru<K, V> {
     /** Current aggregate reported weight (bytes) across all entries. */
     get weightBytes(): number;
 }
+export {};

package/dist/core/metrics.d.ts

@@ -49,8 +49,10 @@ export type MetricEvent = {
     readonly ms: number;
 } | {
     /**
-     * One decoded-chunk cache lookup (emitted only when a cache is configured). `hit: false` means the lookup found
-     * no cached chunk. A combine or `iterate` looks up every chunk it needs when it opens its streams. A caller that
+     * One decoded-chunk cache lookup, or one chunk counted a miss without a lookup (emitted only when a cache is
+     * configured). `hit: false` means the cache did not hold the chunk. A combine or `iterate` counts every chunk it
+     * needs when it opens its streams: a lookup each, except that on a cache that holds nothing each chunk after the
+     * one a stream starts at is counted a miss without one. A caller that
      * missed while another caller's read of the same chunk was open waits on that read and adds no `storage.get`, and a
      * range carries several chunks, so the misses can outnumber the `storage.get` events; the `storage.get` count is
      * the number of requests for chunks. `materializeMany` never looks up the cache, so it emits none.
@@ -131,7 +133,7 @@ export type MetricEvent = {
 };
 /**
  * The sink you plug in. One method, synchronous, fire-and-forget. It must never throw back into the
- * caller — `CloudRoaring` wraps a user sink with {@link safeMetrics} so a buggy sink can't break I/O.
+ * caller — `CloudRoaring` wraps a user sink so that a buggy sink can't break I/O.
  */
 export interface IMetricsSink {
     onEvent(event: MetricEvent): void;

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

@@ -27,14 +27,14 @@ import type { CrbmStorageChunkSource } from './crbm-storage-source.js';
  * What a pin holds for one segment: the generation, the version identifying those exact bytes, and the pinned
  * object's fingerprint, so a read can tell that the generation it opens is still that object.
  *
- * `fingerprint` is optional so that a pin built by hand, before there was one, still compiles. Nothing checks the
- * object such a pin reads, so it cannot tell a name purged and loaded again from the segment it pinned.
- * `seg.pin()` always records it.
+ * `fingerprint` is required for a pin of a generation (`null` only when `generation` is `null`): without it a read
+ * could not tell a name purged and loaded again from the segment it pinned. `seg.pin()` always records it, and a
+ * pin of a generation without a string `version` and `fingerprint` is refused with a `ValidationError`.
  */
 export interface PinnedAt {
     readonly generation: number | null;
     readonly version: string | null;
-    readonly fingerprint?: string | null;
+    readonly fingerprint: string | null;
 }
 export declare class PinnedStorageChunkSource implements StorageChunkSource {
     private readonly inner;

package/dist/core/ports.d.ts

@@ -281,12 +281,18 @@ export interface StorageDeleteOptions {
  *   `getRange` may answer empty without reaching the backend, so it proves neither that the object exists nor
  *   that the offset lies inside it: the cloud drivers answer it empty, the memory and local-filesystem drivers
  *   throw for a missing object or an offset past the end.)
+ * - **A deleted object is missing to the next read**: once `delete(key)` has resolved, `getTail` and a non-empty `getRange`
+ *   of that key throw {@link NotFoundError} (a zero-length `getRange` is the exemption above), with no stale answer from a
+ *   cache or a replica. A rollback reads its target's footer once
+ *   after moving the pointer, in place of listing the bucket, and takes a read that succeeds as proof that the object is
+ *   there.
  * - **An out-of-range read throws {@link ValidationError}**: a range that runs past the end of the object, or a
  *   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, and, where the driver has
- *   one, the object's `version` ({@link TailRead.version}) from the same response as the bytes.
+ *   one, the object's `version` ({@link TailRead.version}) from the same response as the bytes. Its length is a safe
+ *   integer, zero or less for an empty tail; any other length throws {@link ValidationError} before anything is read.
  * - **`delete` is idempotent.** Deleting an absent key is a no-op, not an error: collection passes race each
  *   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`
@@ -299,7 +305,7 @@ export interface StorageDeleteOptions {
  *   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.
+ *   object whose footer, read once, matched what it wrote 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.
@@ -328,7 +334,9 @@ export interface IStorageDriver {
     /**
      * Stream a new immutable generation. The driver opens a destination, hands `write` a {@link BlobSink},
      * then atomically commits (and computes the content hash). Throws {@link WriteConflictError} if the key
-     * already exists (write-once).
+     * already exists (write-once). Call `write` once: the object committed is the bytes that one call wrote, because
+     * the caller records the write identity of that call's object (its footer) for every later proof; a driver that
+     * runs `write` again after a failed attempt must commit only the last run's bytes.
      */
     putImmutable(key: GenKey, write: (sink: BlobSink) => Promise<void>): Promise<{
         size: number;
@@ -341,7 +349,10 @@ 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**, and its `version`
-     * where the driver has one ({@link TailRead}). A missing object throws {@link NotFoundError}.
+     * where the driver has one ({@link TailRead}). `maxBytes` must be a safe integer: zero or less answers an empty tail
+     * with the size, and one past the size the whole object. Any other `maxBytes` (`NaN`, a fraction, a negative one
+     * included, an infinity of either sign, a whole number past the safe range (2^53 or more, or -2^53 or less)) throws
+     * {@link ValidationError} before anything is read. A missing object throws {@link NotFoundError}.
      */
     getTail(key: GenKey, maxBytes: number): Promise<TailRead>;
     /**
@@ -405,11 +416,16 @@ export interface ClearRegistrySummary {
     /** 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.
+     * The fingerprint of the generation's object, `<size>:<footer checksum>` in decimal, as a pin's `pinnedAt.fingerprint`
+     * spells it: the object's size in bytes, which `stat()` reports, and the CRC32C its footer stores.
      */
     readonly fingerprint: string;
+    /**
+     * The bytes from the end of the last chunk payload to the end of the object: the extension block, if any, the index and
+     * the footer. A cold open reads this many bytes from the object's end to open it in one request. An integer from 104,
+     * the footer's size, to the object's size less its 8-byte preamble, and at most 8,392,820.
+     */
+    readonly tailBytes: number;
     /** The generation's metadata, when it has any. Never the empty object. */
     readonly metadata?: GenerationMetadata;
 }
@@ -419,11 +435,24 @@ export interface SealedRegistrySummary {
     readonly generation: number;
     /**
      * 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.
+     * little-endian u64 and its footer checksum as a little-endian u32 (its fingerprint), its `tailBytes` as a
+     * little-endian u32, 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;
 }
+/**
+ * A generation a row knows it published: its number, and the checksum its object's footer stores. A rollback moves only
+ * onto a generation the row knows, and an object whose footer carries another checksum is another object under that
+ * number. The footer's checksum covers the index's checksum, which covers each chunk's, so it commits to the object's ids
+ * and shape; for a cleartext object it does not cover the extension block's bytes.
+ */
+export interface KnownGeneration {
+    /** A non-negative safe integer. */
+    readonly generation: number;
+    /** The object's footer CRC32C (the second half of its fingerprint `<size>:<crc>`), an integer from 0 to 2^32 - 1. */
+    readonly footerCrc: number;
+}
 /**
  * One lease on a generation. It names no fingerprint: a collector spares a generation by number and cannot compare an
  * object without reading it, and a purge and re-create drops the whole list with the row. A pin's own fingerprint,
@@ -481,15 +510,28 @@ export interface RegistryRecord extends SegmentRef {
      */
     readonly summary?: RegistrySummary;
     /**
-     * The generations below `currentGen` that the last publish kept as its grace window, ascending. Optional: absent
-     * means the row does not know which generations are kept, and a load then lists the bucket to collect and records
-     * them; an empty list means none are. Trusted only while every entry is below `currentGen`. A patch that moves
+     * The generations this row knows and has not decided to delete, the current one included, with each object's footer
+     * checksum: the ones it made current, in the order they were made current, oldest first and the current one last, and,
+     * when a publish over a row with no usable ledger seeds one, the ones a count by `keep` keeps in the bucket, which can
+     * include an object no load published (an orphan or a stray). An entry says the library knows the generation and its
+     * footer checksum, not that a load published it. A generation appears once,
+     * at its most recent time current (a rollback onto it moves it to the end). The entries before the last are the kept
+     * window, the generations a live lease holds, and what a rollback left; those numbered above `currentGen` are what a
+     * rollback left. In the clear on every
+     * row, an encrypted one included: a footer checksum of an encrypted object covers a random nonce and says nothing about
+     * its count, size or content, but the entries above the pointer show anyone who reads the registry that a rollback
+     * happened, and from which generation.
+     *
+     * Optional: absent means the row does not know, and a load then lists the bucket to collect. A shipped registry stores
+     * the list in the order given, at most 192 entries written and 384 read, and refuses a list that repeats a
+     * generation, one whose last entry is not the row's `currentGen`, and one whose current entry's checksum disagrees with
+     * a clear `summary`'s fingerprint. A stored list that disagrees with its row is read and not used. A patch that moves
      * `currentGen` without naming it drops it.
      */
-    readonly keptGens?: readonly number[];
+    readonly knownGens?: readonly KnownGeneration[];
     /**
      * The leases on this segment's generations: each keeps one generation out of a load's collection until it ends.
-     * Optional; absent means none. Unlike {@link keptGens} it does not follow the pointer: a patch that moves
+     * Optional; absent means none. Unlike {@link knownGens} it does not follow the pointer: a patch that moves
      * `currentGen` leaves it as it was, and only a patch that names it, or the row going away, changes it. Entries
      * past their end are ignored by every collector and pruned by the next write that names the list. A row's identity
      * is its token, so a purged and re-created segment starts with none.
@@ -510,7 +552,7 @@ export interface RegistryRecord extends SegmentRef {
     /**
      * 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`
+     * the one the field already had included. A write that names only `leases`, `retention`, `residency` or `knownGens`
      * 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.
@@ -532,8 +574,8 @@ export interface NewRegistryRecord {
     readonly residency?: GovernanceMeta;
     /** Must name `currentGen` when given. */
     readonly summary?: RegistrySummary;
-    /** Every entry below `currentGen`, ascending; see {@link RegistryRecord.keptGens}. */
-    readonly keptGens?: readonly number[];
+    /** In the order made current, the last entry the new row's `currentGen`; see {@link RegistryRecord.knownGens}. */
+    readonly knownGens?: readonly KnownGeneration[];
 }
 /**
  * Fields a {@link IRegistryDriver.compareAndSwap} may mutate (identity, audit, `token` and `pointerId` are
@@ -542,14 +584,14 @@ export interface NewRegistryRecord {
  * 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.
+ * `currentGen` the row will have. `knownGens` follows the pointer the same way: a patch that moves `currentGen` and does
+ * not mention it drops it, and one that gives it must end with 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'>>;
+export type RegistryPatch = Partial<Pick<RegistryRecord, 'currentGen' | 'wrappedDeks' | 'keyId' | 'status' | 'retention' | 'residency' | 'summary' | 'knownGens' | 'leases'>>;
 /**
  * What a caller passes {@link IRegistryDriver.create} or {@link IRegistryDriver.compareAndSwap} besides the write itself.
  */
@@ -566,6 +608,25 @@ export interface RegistryWriteOptions {
      * settled by reading the row, never by this record. A driver that ignores the option reads the row.
      */
     readonly held?: RegistryRecord | null;
+    /**
+     * Called with the token this write carries, before the write is sent. A write sent again with a new token reports
+     * it; one that repeats the same body repeats the token already reported. The token is the one the write records:
+     * when the write lands, the row's {@link RegistryRecord.token} is it, and so is its {@link RegistryRecord.pointerId}
+     * when the write names a resolved field. A write that does not land leaves no row carrying it. A call refused before
+     * it has a token to send, on a conflict its own read finds, reports none.
+     *
+     * The token is unique to that write attempt, also against another writer racing the same version: two writers that
+     * send a write against the same row version never carry the same token, so a version counter alone is not enough.
+     * Otherwise a loser's write would pass for the winner's.
+     *
+     * It tells a writer which row writes are its own, whatever became of its request: a write that failed, or got no
+     * answer, may still have landed, and the row's `pointerId` names its writer when no later write has renewed it: it is
+     * then one of the tokens the writer was told. Only a registry that reports {@link IRegistryDriver.reportsWriteTokens}
+     * calls it; one that does not ignores it, and a writer then settles such a write by reading the object it published.
+     * A registry that wraps or extends another and overrides `create` or `compareAndSwap` passes this option through to
+     * the write it forwards, or sets the flag to `false`.
+     */
+    readonly onToken?: (token: Token) => void;
 }
 /** Capabilities a registry driver advertises; validated fail-fast at wiring time. */
 export interface RegCaps {
@@ -610,8 +671,8 @@ declare const STORAGE_BACKEND_BRAND: unique symbol;
  * Where a store keeps everything: the generations, and the pointer saying which one is current.
  *
  * **Branded on purpose.** The two fields alone are not enough to qualify, and that is the whole point. This
- * shape is also {@link LoadDeps}, so before the brand any `{ storage, registry }`
- * object literal satisfied it — including one assembling halves from two *unrelated* stores, which the store
+ * same two fields are the heart of the deps core's standalone functions take, so without the brand any `{ storage, registry }`
+ * object literal would satisfy it — including one assembling halves from two *unrelated* stores, which the store
  * accepted and then answered **empty** for a segment that holds data, because it read a pointer from a place
  * nothing had ever been written. That is the exact silent-empty failure one-class-per-backend exists to
  * remove, and it was reachable in five lines.
@@ -723,6 +784,19 @@ export declare function isStorageBackend(value: unknown): value is StorageBacken
  */
 export interface IRegistryDriver {
     capabilities(): RegCaps;
+    /**
+     * `true` when every `create` and `compareAndSwap` of this registry reports the token its write carries to
+     * {@link RegistryWriteOptions.onToken} before sending it, a resend included. A load, an erasure's rewrite and every
+     * other publish then knows whether a write that conflicted or got no answer landed by whether the row's `pointerId`
+     * is a token it was told, which names the writer and not only the bytes. Absent or `false`: the registry reports
+     * none, and such a write is settled by reading the object the publish wrote. A shipped registry says which it is.
+     *
+     * The flag may be a getter or a field. A registry that wraps or extends another and overrides `create` or
+     * `compareAndSwap` either passes `options` through to the write it forwards, or sets `reportsWriteTokens` to
+     * `false`. One that does neither reads every write of its own that landed after an error or a lost answer as not its
+     * own (`superseded`), and deletes nothing.
+     */
+    readonly reportsWriteTokens?: boolean;
     /**
      * The segment's record, or `null` if it doesn't exist (or was deleted). Throw {@link TransientError} for a fault
      * worth riding out (throttling, a 5xx, a dropped connection): a reader whose pointer refresh meets one keeps