@cloudbitmaps/core 0.19.0 → 0.20.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
@@ -194,6 +200,10 @@ export interface StorageChunkSource {
      * Note that putting the incarnation in the *object key* would not fix this: the new incarnation still starts
      * at generation 0, so the cache key collides either way. The identity has to reach the cache.
      *
+     * Within one incarnation a number can be taken again once its object is deleted, so two objects must never share
+     * a version either, however long after its pointer read a source opens the object: the `.crbm` source's version
+     * ends with the fingerprint of the object it opened.
+     *
      * Returns `null` when the segment resolves to no generation. A source that only ever serves one immutable
      * generation may omit this, and the engine falls back to the generation alone.
      */
@@ -207,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,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
@@ -272,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.
@@ -303,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
@@ -333,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;
 }
@@ -341,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;
 }
@@ -426,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;
@@ -447,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'>>;
 /**
@@ -488,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.
@@ -609,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.
@@ -662,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.

package/dist/core/summary.d.ts

@@ -2,15 +2,17 @@
  * A generation's summary on its registry row: how a writer builds it, how a reader opens it, and how it is held
  * against the object it describes.
  *
- * The row carries a cached description of the current generation, `{ generation, cardinality, metadata? }`, written by
- * the same compare-and-swap that moves the pointer. On a cleartext segment the values are in the clear. On an
- * encrypted one the row holds `{ generation, sealed }` instead: the cardinality as a fixed-width little-endian u64,
- * then the metadata's canonical JSON if there is any, sealed under the segment's data key with the summary scope of
- * the associated data, which binds it to its namespace, segment and generation. The count is fixed-width so the
- * ciphertext's length reveals only the metadata's size, never how many digits the count has. Pure: no I/O.
+ * The row carries a cached description of the current generation, `{ generation, cardinality, fingerprint, metadata? }`,
+ * written by the same compare-and-swap that moves the pointer. The fingerprint names the generation's object, by its
+ * size and footer checksum, as `CrbmReader.fingerprint` does. On a cleartext segment the values are in the clear. On an
+ * encrypted one the row holds `{ generation, sealed }` instead: the cardinality as a fixed-width little-endian u64, the
+ * object's size as a u64 and its footer checksum as a u32, then the metadata's canonical JSON if there is any, sealed
+ * under the segment's data key with the summary scope of the associated data, which binds it to its namespace, segment
+ * and generation. The numbers are fixed-width so the ciphertext's length reveals only the metadata's size, never how
+ * many digits the count or the size has. Pure: no I/O.
  *
  * The generation's `.crbm` object stays the truth, and the summary is a copy of it. {@link summaryAgrees} is the
- * comparison of one with the other.
+ * comparison of one with the other, and the fingerprint is what a reader holds every object it opens against.
  */
 import type { Aead } from './crypto.js';
 import type { ClearRegistrySummary, GenerationMetadata, RegistryRecord, RegistrySummary, SealedRegistrySummary, SegmentRef } from './ports.js';
@@ -19,28 +21,39 @@ export interface GenerationDescription {
     readonly cardinality: number;
     readonly metadata?: GenerationMetadata | undefined;
 }
-/** The clear summary of a generation on a cleartext segment. `metadata` is left off when there is none. */
-export declare function clearSummary(generation: number, cardinality: number, metadata?: GenerationMetadata): ClearRegistrySummary;
+/** What a row's summary says: the generation's description, and the fingerprint of the object it describes. */
+export interface SummaryDescription extends GenerationDescription {
+    readonly fingerprint: string;
+}
+/** The size of the object a fingerprint names, in bytes: what `stat()` reports from a row's summary. */
+export declare function sizeOfFingerprint(fingerprint: string): number;
+/**
+ * The clear summary of a generation on a cleartext segment, naming its object by `fingerprint`. `metadata` is left off
+ * when there is none.
+ */
+export declare function clearSummary(generation: number, cardinality: number, fingerprint: string, metadata?: GenerationMetadata): ClearRegistrySummary;
 /**
- * The sealed summary of a generation on an encrypted segment: the cardinality as a u64, then the metadata's canonical
- * JSON, sealed under `aead` and bound to `ref` and `generation`.
+ * The sealed summary of a generation on an encrypted segment: the cardinality as a u64, the object's size as a u64 and
+ * its footer checksum as a u32, then the metadata's canonical JSON, sealed under `aead` and bound to `ref` and
+ * `generation`.
  */
-export declare function sealSummary(aead: Aead, ref: SegmentRef, generation: number, cardinality: number, metadata?: GenerationMetadata): SealedRegistrySummary;
+export declare function sealSummary(aead: Aead, ref: SegmentRef, generation: number, cardinality: number, fingerprint: string, metadata?: GenerationMetadata): SealedRegistrySummary;
 /**
  * What a sealed summary says, opened with `aead` under the summary scope of `ref` and the summary's own generation.
  * The bytes are untrusted: a blob that is not base64, is the wrong size, fails its authentication (tampered, or moved
- * from another generation's row), or holds a count outside 0 to 2^32 or metadata that breaks the rules, is an
- * {@link IntegrityError}.
+ * from another generation's row), or holds a count outside 0 to 2^32, a size no object can have, or metadata that
+ * breaks the rules, is an {@link IntegrityError}.
  */
-export declare function openSummary(aead: Aead, ref: SegmentRef, summary: SealedRegistrySummary): GenerationDescription;
+export declare function openSummary(aead: Aead, ref: SegmentRef, summary: SealedRegistrySummary): SummaryDescription;
 /**
  * What a row's summary says of its current generation, or `undefined` when it says nothing a reader may use. It is
  * used only for the generation it names, on an active row, and in the shape the row's keys call for: clear on a row
  * with no wrapped keys, sealed on a row with them. A sealed one is opened with `aead`, and is unusable without it,
- * or when it does not open, so a summary a tamperer moved or rewrote is never believed. Never throws for a bad
- * summary: the row's copy is a cache, and a copy that cannot be used is a copy that is not there.
+ * or when it does not open, so a summary a tamperer moved or rewrote is never believed; a clear one whose fingerprint
+ * names no object is unusable too. Never throws for a bad summary: the row's copy is a cache, and a copy that cannot be
+ * used is a copy that is not there.
  */
-export declare function usableSummary(ref: SegmentRef, row: RegistryRecord, aead: Aead | undefined): GenerationDescription | undefined;
+export declare function usableSummary(ref: SegmentRef, row: Pick<RegistryRecord, 'summary' | 'status' | 'currentGen' | 'wrappedDeks'>, aead: Aead | undefined): SummaryDescription | undefined;
 /**
  * Whether a summary's description of a generation is what its object holds: the same id count and the same metadata,
  * compared in canonical form, so key order never matters. A summary with metadata over an object with none, and the
@@ -54,8 +67,12 @@ export declare function summaryAgrees(summary: GenerationDescription, object: Ge
  * metadata block is not authenticated, so a block stripped from one reads as none, and the sealed summary on the row is
  * the one copy that says there was a block; carrying it keeps the rewrite from erasing the record of what it dropped.
  * Pass `authenticated` only for a summary that was opened (a clear one has no more authority than the block it sits
- * beside). Never refuses: a rewrite over a stripped block is still an erasure.
+ * beside). Never refuses. The erasure reaches this with a stripped block only past a fingerprint forged to match the
+ * row's, since stripping the block changes the object's size and the open is held to the row's fingerprint.
  */
 export declare function metadataToCarry(object: GenerationMetadata | undefined, authenticated: GenerationDescription | undefined): GenerationMetadata | undefined;
-/** The summary of a generation of `ref`, clear or sealed under `aead` as the segment's keys call for. */
-export declare function summaryOf(ref: SegmentRef, generation: number, description: GenerationDescription, aead: Aead | undefined): RegistrySummary;
+/**
+ * The summary of a generation of `ref`, describing the object `description.fingerprint` names, clear or sealed under
+ * `aead` as the segment's keys call for.
+ */
+export declare function summaryOf(ref: SegmentRef, generation: number, description: SummaryDescription, aead: Aead | undefined): RegistrySummary;

package/dist/core/token.d.ts

@@ -4,8 +4,8 @@
  * A shipped registry gives a row it creates a token `<incarnation>.<counter>.<write>`: 32 lowercase hex digits drawn
  * from injected entropy when the row is created, a decimal counter, and 16 hex digits drawn for each write. Every write
  * of the row keeps the incarnation, and a name created again draws a new one, so two incarnations are told apart by it
- * even when their rows were created in the same millisecond or one is gone. A row a 0.11 build wrote has no incarnation
- * for as long as it lives (`"7"`, then `"8.<write>"`), and a registry of someone else's issues tokens in any form.
+ * even when their rows were created in the same millisecond or one is gone. A registry of someone else's issues tokens
+ * in any form, and one whose tokens carry no incarnation id is told apart only by the row's creation stamp.
  *
  * This lives in `core/` so the publish can read it, and the registry drivers, which build the tokens, import it from
  * here: the form has one definition.
@@ -14,18 +14,23 @@ import type { Token } from './ports.js';
 /** An incarnation-form token: the incarnation id, the counter and a write part, `.`-separated, in lowercase hex. */
 export declare const INCARNATION_TOKEN: RegExp;
 /**
- * The incarnation id in a token, or `undefined` for one that has none: a schema-1-born row's, or any token another
- * driver issues. Two tokens with the same incarnation are writes of one incarnation of a row.
+ * The incarnation id in a token, or `undefined` for one that has none: a token a registry of someone else's issues in
+ * another form. Two tokens with the same incarnation are writes of one incarnation of a row.
  */
 export declare function incarnationOf(token: Token): string | undefined;
+/** An audit event's `incarnation`, from the token of the row it is about: absent for a token that carries none. */
+export declare function incarnationField(token: Token | undefined): {
+    readonly incarnation?: string;
+};
 /**
  * Whether two reads of one name's row are one incarnation of it.
  *
  * - Both tokens carry an incarnation id: the ids decide, and the clock stamps do not enter.
- * - Only one does: different incarnations. A name created again is always given an incarnation id, and a write never
- *   takes one away, so a row without an id never becomes a row with one, nor the reverse.
- * - Neither does (a row 0.11 wrote, or a registry of someone else's): there is no id to compare, and the creation stamp
- *   is the only signal left. It is a clock reading, so a caller that acts on this answer proves its own object too.
+ * - Only one does: different incarnations. A registry gives its rows one form of token, so a row without an id never
+ *   becomes a row with one, nor the reverse.
+ * - Neither does (a registry of someone else's whose tokens carry none): there is no id to compare, and the creation
+ *   stamp is the only signal left. It is a clock reading, so a caller that acts on this answer proves its own object
+ *   too.
  */
 export declare function sameIncarnation(a: {
     readonly token: Token;

package/dist/driver-kit.d.ts

@@ -1,7 +1,8 @@
-export type { GenKey, IRegistryDriver, IStorageDriver, SegmentRef, StorageBackend, StorageCaps, } from './core/ports.js';
+export type { GenKey, IRegistryDriver, IStorageDriver, SegmentRef, StorageBackend, StorageCaps, StorageDeleteOptions, TailRead, } from './core/ports.js';
 export { brandAsBackend, STORAGE_BACKEND } from './core/ports.js';
 export type { IMetricsSink, MetricEvent } from './core/metrics.js';
 export { IntegrityError, isIntegrityError, isNotFoundError, isTransientError, isValidationError, isWriteConflictError, NotFoundError, TransientError, ValidationError, WriteConflictError, } from './core/errors.js';
+export { RESOLVED_FIELDS, pointerIdOf, renewPointer, renewsPointer } from './core/pointer-id.js';
 export { validateSegmentRef } from './core/validate.js';
 export type { BlobSink } from './core/blob.js';
 export { MAX_ROW_BYTES, ObjectStoreRegistry, ObjectVersionRaced, } from './drivers/_shared/object-registry.js';

package/dist/driver-kit.js

@@ -2,6 +2,7 @@ import {
   DEFAULT_NAMESPACE,
   IntegrityError,
   NotFoundError,
+  RESOLVED_FIELDS,
   STORAGE_BACKEND,
   TransientError,
   ValidationError,
@@ -12,7 +13,6 @@ import {
   encodeNameForKey,
   encodeNameForPath,
   entropyIsAvailable,
-  incarnationOf,
   isIntegrityError,
   isNotFoundError,
   isTransientError,
@@ -24,13 +24,16 @@ import {
   newIncarnationToken,
   nextRegistryToken,
   parseRegistryEnvelope,
+  pointerIdOf,
   recordFromNew,
+  renewPointer,
+  renewsPointer,
   serializeRegistryEnvelope,
   validateNewRegistryRecord,
   validateRegistryPatch,
   validateSegmentRef,
   webCryptoEntropy
-} from "./chunk-TNWTIAON.js";
+} from "./chunk-YSC7NJWV.js";
 
 // src/drivers/_shared/object-registry-keys.ts
 var REGISTRY_SUFFIX = ".reg";
@@ -137,7 +140,7 @@ var ObjectStoreRegistry = class {
     const conditionalDelete = this.removesRows();
     return entropyIsAvailable(this.entropy) ? { strongRead: true, conditionalDelete } : { strongRead: true, canWrite: false, conditionalDelete };
   }
-  /** Whether a delete removes a row born with an incarnation id: the store has a delete, and vouches for it. */
+  /** Whether a delete removes a row: the store has a delete, and vouches for it. */
   removesRows() {
     return this.store.conditionalDelete === true && typeof this.store.delete === "function";
   }
@@ -242,7 +245,7 @@ var ObjectStoreRegistry = class {
       }
       try {
         const remove = this.removesRows() ? this.store.delete : void 0;
-        if (remove !== void 0 && incarnationOf(current.env.record.token) !== void 0) {
+        if (remove !== void 0) {
           await remove.call(this.store, key, { version: current.version });
           return;
         }
@@ -316,6 +319,7 @@ export {
   NotFoundError,
   ObjectStoreRegistry,
   ObjectVersionRaced,
+  RESOLVED_FIELDS,
   STORAGE_BACKEND,
   TransientError,
   ValidationError,
@@ -331,7 +335,10 @@ export {
   namespaceKeyPart,
   namespacePathPart,
   normalizeObjectPrefix,
+  pointerIdOf,
   prefixPart,
+  renewPointer,
+  renewsPointer,
   validateSegmentRef
 };
 //# sourceMappingURL=driver-kit.js.map