@cloudbitmaps/core 0.19.1 → 0.21.0

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
@@ -235,13 +281,37 @@ export interface StorageCaps {
  *   `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.
+ * - **`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. 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.
+ *   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 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.
+ * - **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 +346,19 @@ 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}). `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<{
-        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 +381,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 +413,18 @@ 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 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;
 }
@@ -345,11 +433,25 @@ 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), 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,
@@ -407,15 +509,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.
@@ -430,12 +545,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 `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.
+     */
+    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;
@@ -447,19 +573,24 @@ 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 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.
+ * `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.
  */
@@ -476,6 +607,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 {
@@ -492,9 +642,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 +761,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.
@@ -631,6 +783,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
@@ -666,8 +831,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/publish.d.ts

@@ -0,0 +1,207 @@
+import type { Yielder } from './cooperative.js';
+import type { Rng } from './determinism.js';
+import type { PublishedKept } from './generation-gc.js';
+import type { WrappedDek } from './crypto.js';
+import type { GenKey, IRegistryDriver, KnownGeneration, RegistryRecord, RegistrySummary, Token } from './ports.js';
+/** What a publish is told, beyond the registry and the generation key. */
+interface PublishOptions {
+    wrappedDeks?: readonly WrappedDek[];
+    expectFrom?: number;
+    expectToken?: Token;
+    /**
+     * The row `expectToken` names, as the caller read it. With it, a row whose token has moved but which differs from
+     * this one only in its leases (a reader took or released one) does not refuse the publish: it goes on against the
+     * fresh row, after a jittered wait and without the caller redoing its work, up to a bound. Any other difference
+     * refuses as ever. Without it, a moved token refuses.
+     */
+    expectRow?: RegistryRecord | null;
+    /**
+     * Fields of `expectRow` that a row may also differ in, beside its leases, without the fence refusing: a write that
+     * changed only those did not touch what the caller derived its content from. An erasure's rewrite passes `knownGens`,
+     * since another erasure's removal of generations from the ledger leaves the generation it streamed alone. A write that
+     * also renewed the row's `pointerId` still refuses.
+     */
+    expectRowIgnores?: readonly (keyof RegistryRecord)[];
+    /**
+     * Publish only while the segment still has **no registry row**.
+     *
+     * The fence for a caller whose decision rests on the row being ABSENT: every load that found no row sets it,
+     * guarded or not. `expectFrom` and `expectToken` cannot express it: both compare against a value read from a
+     * row, so when there was no row there is nothing to compare and both are simply omitted — leaving the publish a
+     * bare forward-only advance that happily lands over whatever appeared in the meantime.
+     *
+     * Without it, a guarded load into a segment that did not exist yet would judge "no row", pass its empty and
+     * `minRetained` bounds vacuously, and land an EMPTY generation over the ids a concurrent writer had just loaded,
+     * reporting `published: true`. An unguarded load would move the pointer over another first load's generation or
+     * onto a row `setRetention` made, and, where an erasure had deleted its object above that row's pointer, onto an
+     * object that is gone. Materialising into a destination that does not exist yet is the ordinary first run of a
+     * pipeline, so the `*Into` verbs reach this as often as `loadSegment` does.
+     */
+    expectAbsent?: boolean;
+    /**
+     * The generation's summary (see {@link RegistrySummary}), written by the write that moves the pointer to it. It
+     * names `key.generation`. Absent, the row is left with none for this generation.
+     */
+    summary?: RegistrySummary;
+    /**
+     * The segment's row as the caller already read it (`null`: it found none). The first attempt acts on it
+     * instead of reading the row again, which is sound because that attempt writes only under the row's own
+     * fence: its compare-and-swap carries this row's token, and with no row it creates create-only, so a row
+     * that changed or appeared since makes the write lose and the next attempt reads the row afresh. Only the
+     * idempotent "already current" answer writes nothing, so a reused row never gives it.
+     */
+    row?: RegistryRecord | null;
+    /**
+     * The object was written without encryption. Its publish is refused, with {@link KeyUnavailableError}, onto a row
+     * that carries key material: a reader of that segment opens every generation with its key, and a later
+     * `destroySegment` would attest that shredding it made a readable object unreadable. A caller decides its key
+     * from the row it read before the write, so this closes the window in which another writer creates the
+     * segment encrypted meanwhile.
+     */
+    cleartext?: boolean;
+    /**
+     * Whether the object under `key` is the one the caller wrote, and throws when it cannot tell. Asked only when a
+     * registry write failed and the row then names `key.generation`, on a registry that does not report its writes'
+     * tokens ({@link IRegistryDriver.reportsWriteTokens}; one that does settles it by the row's `pointerId` and never
+     * asks), to tell this publish's write from another writer's at the same number. Every caller that writes the object
+     * passes it. Without it, such a write that ended without an answer over a row that names `key.generation` cannot be
+     * settled: the publish throws {@link TransientError} and the caller keeps its object.
+     */
+    holdsOwnObject?: () => Promise<boolean>;
+    /**
+     * What a publish waits on before it sends a fresh compare-and-swap, after a write that ended without an answer and
+     * left the row as it was. Without a `sleep`, such a write throws at once instead of being sent again.
+     */
+    clock?: Yielder;
+    /** Spreads that wait (full jitter) so concurrent publishers do not retry together. Without it the wait is the bound. */
+    rng?: Rng;
+    /**
+     * Called once for each registry write that ended without an answer, before the row is read back. A caller whose
+     * publish then answers `false` can say that it cannot tell whether its own write landed first: the row may have
+     * held its generation for a while before another writer moved on.
+     */
+    onUnanswered?: () => void;
+    /**
+     * The clock that judges whether a lease has ended. With it, a publish over a row that holds ended leases drops
+     * them in the write that moves the pointer, which rewrites the row anyway. Without it, leases are left as they are.
+     */
+    leasesNow?: () => number;
+    /**
+     * Clear the row's leases in the write that moves the pointer: the caller's collection deletes every generation
+     * below the new pointer whatever a lease says, as a subject erasure's does.
+     */
+    clearLeases?: boolean;
+    /**
+     * How many generations below the new pointer the caller keeps. With it, the write that moves the pointer also
+     * records the window in the row (the entries of `knownGens`: the `keep` most recently current of the generations
+     * below the new one, and the ones a live lease holds), derived from the very row the write is made against, and the
+     * result names the generations the window dropped. Without it, or above the most a row collects by name, the result
+     * names no window, and a collection lists.
+     */
+    keep?: number;
+    /**
+     * The footer checksum of the object under `key` (the second half of its fingerprint), which the write that moves the
+     * pointer records in the row's `knownGens` beside the generation. It comes from the object the caller wrote or opened,
+     * the same one its `summary` describes.
+     */
+    footerCrc: number;
+    /**
+     * The window a ledger starts with, over a row that has no usable one ({@link readSeed}): the generations a count by
+     * `keep` keeps, which the write records as the ledger's entries before the new generation.
+     */
+    seed?: readonly KnownGeneration[];
+}
+/**
+ * Point a segment's registry `currentGen` at `key.generation` — the publish step that makes a freshly-written
+ * generation the authoritative latest (so registry-aware readers see it). **Forward-only and idempotent:**
+ * if the registry has no row it creates one; if it's already at/ahead of `key.generation` it's a no-op (an
+ * out-of-order/duplicate publish never regresses the pointer); otherwise it advances via compare-and-swap,
+ * retrying a few times under contention. Separated from the Storage write so callers can publish atomically
+ * after the immutable object is durable (write-then-publish).
+ *
+ * **Throws** rather than returning, in two cases, because each would otherwise create a state no reader can
+ * recover from: a `destroyed` (crypto-shredded) row, where advancing the pointer would name an object encrypted
+ * under a shredded key; and an advance carrying **new** `wrappedDeks`, which would either strand that key or make
+ * the row advertise encryption over cleartext generations. Contention that never clears throws
+ * {@link WriteConflictError} after the retries.
+ *
+ * **`expectFrom` turns forward-only into read-modify-write.** Forward-only is the right rule for a writer whose
+ * content does not depend on what was current — a load computes its ids upstream, so publishing over a newer
+ * generation loses nothing the loader knew about. It is the WRONG rule for a writer that *derived* its content
+ * from a particular generation: the erasure rewrite streams generation `from` and clears one bit, so publishing
+ * it over a newer generation silently discards whatever that generation added. Passing `expectFrom` makes the
+ * publish land only while the pointer is still exactly there, and return `false` otherwise, so the caller can
+ * report `superseded` and re-derive. The compare-and-swap itself carries the token read in the same iteration,
+ * so the check and the write see the same row.
+ *
+ * **`expectToken` fences the LINEAGE, and a derived writer needs both.** A generation number identifies a
+ * generation only within one incarnation of a name: the numbering restarts at `0` once the row is purged and
+ * the bucket empty, so a name that is retired and re-created has a *different* segment wearing the *same*
+ * `currentGen`. `expectFrom` alone matched it — and an erasure rewrite then published one incarnation's content
+ * over another's, deleted the live objects with its `keep: 0` collection, and returned `erased: true`. The row's
+ * OCC token is the identity that survives this: a shipped registry's later `create` gets a token never issued before
+ * under that name, but for a collision of probability 2^-128 per pair of incarnations, so no token is reused across them.
+ *
+ * Pass the token read alongside `expectFrom` and the publish lands only on the same row it was derived from.
+ * The check is deliberately **conservative**: the token also changes on writes that are not supersessions at
+ * all (a `setRetention`, a due-index reindex), so such a write makes a derived publish report `superseded` and
+ * the caller re-derive. That costs a re-run on a rare, unrelated write; the alternative costs a segment.
+ *
+ * **The driver sends a registry write once, and an unanswered one is reconciled by its effect.** A `create` or
+ * `compareAndSwap` that fails with {@link TransientError} (a throttle, a lost response, a timeout) may or may not
+ * have landed, and may still be in flight. The publish reads the row once more and decides from what it holds:
+ *
+ * - the pointer names `key.generation`, on the incarnation the write was made against (the row's `createdAt`), and the
+ *   write is the caller's own: the write is taken to have landed, and the publish returns `true`. A registry that
+ *   reports each write's token ({@link IRegistryDriver.reportsWriteTokens}) settles it by the row's `pointerId`, which
+ *   names the writer of the write that last set the pointer: the write is the call's own when that is the token of a
+ *   write this call sent. One that does not is settled by `holdsOwnObject` finding the caller's bytes under the number:
+ *   only the writer of a write-once object publishes its number, but a number is taken again once its object is
+ *   deleted, and a load of the same cleartext ids writes the same bytes, so another writer's identical object under
+ *   the number passes for the caller's;
+ * - the row is still the one the write was made against (the same token, or still no row): the write may land yet. The
+ *   publish then waits, on the injected clock, and sends a **new** write from the row it just read: a request of its
+ *   own, not a replay of the driver's, carrying the same version, so under the registry's fence at most one of the two
+ *   lands and the other meets a conflict, which the next read settles. At most {@link UNANSWERED_RESENDS} follow, after
+ *   a wait under 500 ms, then 1 s, then 2 s (full jitter when an `rng` is given); each is settled the same way. Still
+ *   unanswered, or with no clock to wait on, this throws the registry's own `TransientError` and writes nothing more.
+ *   A caller must not delete its object on it;
+ * - anything else: the row has moved past the state the write was conditioned on, so that write can never land, and
+ *   the publish goes on as after a lost race, from the row it just read. A pointer at `key.generation` that is not over
+ *   the caller's own object, or is on another incarnation, is a lost race too and answers `false`, never an already
+ *   current re-publish.
+ *
+ * A failed read throws `TransientError` too. The same check of the pointer runs after a {@link WriteConflictError},
+ * so a write that landed and then met itself (a registry whose client re-sent it) is not taken for a lost race.
+ * The check runs before the next attempt's `expectAbsent`, `expectToken` and `expectFrom` fences, which a write of the
+ * caller's own that landed would fail. With a registry that reports tokens it names the writer of the write that last
+ * set the pointer, so another writer's identical object under the number does not pass it; with one that does not,
+ * that object can.
+ *
+ * **A `summary` goes in the same write that moves the pointer**, so a reader that sees this generation as current
+ * sees the count and metadata that describe it, and every attempt sends the same one. It must be the shape the row's
+ * keys call for: sealed for an object written with a key, clear for one written without.
+ */
+export declare function publishGenerationKept(registry: IRegistryDriver, key: GenKey, options: PublishOptions): Promise<PublishResult>;
+/** What a publish did: whether the pointer is at the generation, and what the write recorded in the row. */
+export interface PublishResult {
+    readonly published: boolean;
+    /**
+     * What the write that moved the pointer recorded: the list, the generations the window dropped, and the new row's
+     * token. Absent when no write of this call is known to have landed (the pointer was already there, or the outcome
+     * was settled without knowing which write it was), and a collection then lists.
+     */
+    readonly kept?: PublishedKept;
+    /**
+     * A token of the row whose pointer is at the generation, when it is published: the one the write was given, or the
+     * row read that showed the pointer there. Every write of a row keeps its incarnation, so this names the incarnation
+     * the publish landed in, for the audit event.
+     */
+    readonly token?: Token;
+}
+/**
+ * {@link publishGenerationKept}'s answer to "did the pointer move", for a caller with no use for what it recorded:
+ * a publish with no `keep` leaves the row recording no list.
+ */
+export declare function publishGeneration(registry: IRegistryDriver, key: GenKey, options: PublishOptions): Promise<boolean>;
+export {};

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;