@cloudbitmaps/core 0.11.2 → 0.13.0

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

@@ -1,4 +1,4 @@
-import type { IStorageDriver, IRegistryDriver, SegmentRef } from './ports.js';
+import type { GenKey, IStorageDriver, IRegistryDriver, RegistryRecord, SegmentRef } from './ports.js';
 /** The two ports generation bookkeeping needs: the objects, and the pointer that says which one is current. */
 export interface GenerationDeps {
     readonly storage: IStorageDriver;
@@ -6,7 +6,9 @@ export interface GenerationDeps {
 }
 /**
  * The generation number a writer should use for the segment's **next** object: one above the highest generation
- * the registry points at *or* that is present in Storage — whichever is higher.
+ * the registry points at *or* that is present in Storage — whichever is higher. The erasure rewrite numbers this
+ * way; a load numbers with {@link nextLoadGeneration}, which lists as this does when its existence check finds the
+ * number taken or cannot answer.
  *
  * Both are consulted because they can disagree. A load that wrote its object and crashed before publishing leaves
  * an object *above* `currentGen`; a writer that consulted only the pointer would pick that same number and hit the
@@ -17,6 +19,46 @@ export interface GenerationDeps {
  * A segment with no row and no objects starts at 0. An admin/write-path helper, never on the read path.
  */
 export declare function nextGeneration(ref: SegmentRef, deps: GenerationDeps): Promise<number>;
+/** The number a load takes, and whether one existence check proved it free (so nothing is above the pointer). */
+export interface LoadNumber {
+    readonly generation: number;
+    /**
+     * `true` when the number is `currentGen + 1` and the check found no object holding it. Collection by name rests
+     * on it: the row named `generation - 1` as current, so every number the window evicts is below it, and nothing
+     * the listing would have kept is a name the pass takes. `false` when the listing numbered the load.
+     */
+    readonly checked: boolean;
+}
+/**
+ * The generation number a load takes, from the row it has already read: `currentGen + 1` (0 with no row or no
+ * pointer yet) when no object holds that number, which one existence check proves (a zero-byte `getTail`, one
+ * metadata request on every shipped driver); otherwise one above the pointer and above everything listed, as
+ * {@link nextGeneration} numbers. The check finding the number taken (a crashed load's orphan, the object of a
+ * load still in flight, or the generations a rollback left above the pointer) and the check failing in any way
+ * other than "not found" both take the listing, so the listing stays the authority whenever the check cannot
+ * prove the number free. A failed check falls back silently: nothing records it, and what it costs is the listing,
+ * one more PUT-class request on S3, so a fault that makes every check fail shows only in the bill.
+ *
+ * A load can therefore take a number **below** an object already in the bucket: an orphan at `currentGen + 2`
+ * with `currentGen + 1` free is numbered under, not past. That is as safe as a listing's number. A load never
+ * takes a number an object holds, and a put that races onto one fails write-once, so the load reports
+ * `superseded`. The orphan above stays unpublished; the load whose check meets it numbers past it by the listing,
+ * and collection takes it once a generation above it is current. Like a listing's, the number can be one whose
+ * object was deleted (an erasure removes the generations above a rolled-back pointer that held the id), which is
+ * why nothing identifies a generation by its number alone: the reader cache, the chunk cache and a pin all key on
+ * the number and the row's token, and the token has moved on.
+ */
+export declare function nextLoadGeneration(ref: SegmentRef, deps: GenerationDeps, row: RegistryRecord | null): Promise<LoadNumber>;
+/**
+ * How often a load that could collect by name lists instead: every generation divisible by this. A name-only pass
+ * takes one generation a load and never looks at the rest, so what it misses (a refused load's object that stayed
+ * because the row had changed, extras left by a `keep` that shrank, an object a rollback or an erasure left
+ * stranded below the pointer) waits for a listing. The number is a generation's, not a clock's, so the choice needs
+ * no state and no time, and a segment that loads cleanly lists once in this many loads at most. The bound is in
+ * generation numbers: a rollback moves the pointer down, and the loads that then take the numbers above it count
+ * from there.
+ */
+export declare const LIST_COLLECTION_CADENCE = 16;
 /**
  * Garbage-collect superseded Storage generations for a segment: everything strictly below `currentGen`, keeping
  * the most recent `keep` of them as a grace window, so a read still fetching from a just-superseded
@@ -42,8 +84,8 @@ export declare function nextGeneration(ref: SegmentRef, deps: GenerationDeps): P
  * an empty array is not: `eraseIdFromSegment` reads the returned list as the physical half of its erasure
  * receipt, and would otherwise report `erased: true` over bytes still in the bucket. Re-run it.
  *
- * That state is reachable in practice: a `dropSegment` whose Storage sweep threw part-way, or a load that was
- * already writing its object when the tombstone landed and finished the write afterwards. `dropSegment` re-sweeps
+ * That state is reachable in practice: a `dropSegment` whose Storage sweep threw part-way, or a load that had read
+ * the row before the tombstone landed, wrote its object afterwards, and stopped before its refusal deleted it. `dropSegment` re-sweeps
  * and reports whatever it could not reclaim in `generationsRemaining`, but a drop that was never re-run leaves a
  * residual, and this is what eventually collects it from the retention sweep.
  *
@@ -54,3 +96,59 @@ export declare function nextGeneration(ref: SegmentRef, deps: GenerationDeps): P
 export declare function gcOrphanGenerations(ref: SegmentRef, deps: GenerationDeps, options?: {
     keep?: number;
 }): Promise<number[]>;
+/**
+ * Collect after a load's publish: by name when `byName` (the load numbered its generation with one existence check,
+ * the object its row named was there when the guard looked, and its caller does not ask for a listing) and `keep` is
+ * at most one, and by listing otherwise ({@link gcOrphanGenerations}). A load lists in three cases: `keep` of 2 or
+ * more, which a name cannot serve because the window then counts generations that may be absent (a refused
+ * neighbour's number is a gap, and by name would take one the window promised to keep); a number the listing chose,
+ * so something sits above the pointer or the check could not answer, or a current object the load's check found gone; and
+ * every {@link LIST_COLLECTION_CADENCE}th generation, which collects what a name-only pass leaves. It makes no
+ * request when `keep` is at least the generation published, since no more generations than that exist below it. A
+ * load onto a `destroyed` row is refused at its publish and never reaches here; a drop that lands after the publish
+ * leaves this pass collecting the tombstone's generations, one by name or all of them by listing, and the drop's own
+ * sweep takes the rest.
+ */
+export declare function collectAfterLoad(ref: SegmentRef, deps: GenerationDeps, options: {
+    generation: number;
+    keep: number;
+    byName: boolean;
+    /**
+     * The object the load's row named as current, which the caller did not open. Before it collects by name a generation
+     * the window keeps (a `keep` of 1), the pass looks for this object with one zero-byte read, and lists instead
+     * unless that finds it: a name-only pass is safe only while the object the row named is in the bucket.
+     */
+    proveCurrent?: GenKey;
+}): Promise<number[]>;
+/**
+ * Collect, with no listing, the one generation a publish of `generation` pushed out of a grace window of `keep`
+ * (0 or 1): `generation - keep - 1`, when that is a number at all. Returns that name, whether or not an object was
+ * there: a delete of an absent object succeeds on every backend and says nothing, so the name returned is the one
+ * asked for, not one found, and a generation a concurrent pass, an erasure or a lifecycle rule had already taken is
+ * listed all the same. A list is not a receipt (invariant 4), and neither is this.
+ *
+ * The caller has published `generation` having numbered it with one existence check, so the row named
+ * `generation - 1` and every generation the window newly evicts is below it. With `keep` of 0 or 1 that name is
+ * the one a listing pass would also take, or one it left to a later pass: never a generation the listing keeps.
+ * That rests on the object the row named being in the bucket, and a fault can break it (a lifecycle rule or a
+ * partial restore removing it, or an erasure deleting the object of a load whose publish then landed;
+ * `checkConsistency` reports the state). The caller, which learns that from its guard's read of the current
+ * generation or, when the guard took the size from the row's summary and opened nothing, from one zero-byte read of
+ * it (see {@link collectAfterLoad}), lists instead; a load that made neither (`allowEmpty` without `minRetained`)
+ * cannot tell, and deletes by name the older generation a listing would have kept as the window. `keep` of 2 or more is refused,
+ * because there the window counts the generations that exist, which a name cannot know.
+ *
+ * Collection never touches the current generation, and the row is re-proved before the delete as every pass does.
+ * A row that is gone, or a pointer that has fallen below `generation` (a rollback, or a name purged and re-created
+ * with fewer loads), deletes nothing and returns `[]`: the publish already landed, nothing here protects it or
+ * needs the result, and a throw would hand the caller a failure for a load that took effect. A pointer that has
+ * moved above `generation` does not stop it: a publish landing in the meantime leaves routine collection working.
+ * A fault, a registry read or a delete that throws, still propagates, with the pointer at `generation`. The bound
+ * is `generation`, the pointer this load's own publish set, so the lower-of-two-pointers rule of a listing pass
+ * holds with one observation in place of two. Nothing is deleted when `generation` has nothing below its window,
+ * and no request is made.
+ */
+export declare function collectByName(ref: SegmentRef, deps: GenerationDeps, options: {
+    generation: number;
+    keep: number;
+}): Promise<number[]>;

package/dist/core/load-input.d.ts

@@ -0,0 +1,55 @@
+/**
+ * What a load accepts: ids, or a whole bitmap as `{ serialized }` bytes or as a `{ bitmap }` that serializes to
+ * them.
+ *
+ * Every bitmap input takes one path. The bytes are size-capped, checked structurally and decoded by the codec's
+ * safe deserializer into a bitmap of the codec's own, which then writes its chunks straight from its containers:
+ * no id passes through JavaScript. `{ bitmap }` is only a spelling of `{ serialized }`, serialized once, here, so
+ * a caller's bitmap is never trusted as a structure and a change made to it after the call is not loaded.
+ *
+ * All of it runs before the load's first request, so a malformed input costs no round trip and writes nothing.
+ */
+import type { CodecBitmap, CodecInterface } from './codec.js';
+/**
+ * Anything that serializes itself to portable Roaring: `roaring`'s `RoaringBitmap32` is one. Typed by shape, so
+ * no codec's own class appears in a signature. A bitmap that can also say how large its serialization is
+ * (`getSerializationSizeInBytes`) is asked first, so one over the cap is refused before it is serialized.
+ */
+export interface PortableBitmap {
+    serialize(format: 'portable'): Uint8Array;
+    getSerializationSizeInBytes?(format: 'portable'): number;
+}
+/**
+ * What a load writes as the segment's new contents.
+ *
+ * - **ids**: an iterable or async iterable of integers in `[0, 2^32)`, consumed lazily. Not a `Uint8Array`,
+ *   `Uint8ClampedArray` or `Buffer`, which a load refuses, since each byte would load as an id.
+ * - **`{ serialized }`**: one bitmap in the portable Roaring format, checked before anything is written.
+ * - **`{ bitmap }`**: an object with `serialize('portable')`, loaded as `{ serialized: bitmap.serialize('portable') }`.
+ */
+export type LoadInput = Iterable<number> | AsyncIterable<number> | {
+    readonly serialized: Uint8Array;
+} | {
+    readonly bitmap: PortableBitmap;
+};
+/**
+ * No canonical 32-bit Roaring bitmap serializes to more than this. Under the run cookie, the larger of the two
+ * headers, it is a 4-byte cookie, 8,192 bytes of run flags and 8 bytes of header for each of the 65,536
+ * containers, and no container's body is over 8,192 bytes: a bitset is 8,192, and a run container is kept only
+ * where it is smaller. 537,403,396 bytes, about 512.5 MiB.
+ */
+export declare const MAX_SERIALIZED_LOAD_BYTES: number;
+/** A bitmap input, decoded into the codec's own bitmap: written from its chunks, never id by id. */
+export declare class DecodedLoadInput {
+    readonly bitmap: CodecBitmap;
+    constructor(bitmap: CodecBitmap);
+}
+/**
+ * Check a load's input and decode a bitmap input, before the load makes any request.
+ *
+ * @returns ids unchanged, to be consumed lazily by the write, or the decoded bitmap.
+ * @throws {ValidationError} for a byte array passed as ids; bytes that are malformed, over the cap, or followed by
+ * more bytes; a `{ bitmap }` with no `serialize` method, or whose `serialize('portable')` returns no `Uint8Array`;
+ * and anything that is none of the three inputs. An error the caller's own `serialize` throws propagates as it is.
+ */
+export declare function prepareLoadInput(input: LoadInput, codec: CodecInterface): Iterable<number> | AsyncIterable<number> | DecodedLoadInput;

package/dist/core/load.d.ts

@@ -15,15 +15,17 @@
  *
  * 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
- * gone. Once another write has changed the row, the object's number may name a re-created segment's live object,
- * so it stays, and collection takes it like any other generation once one above it is current.
+ * pointer), so a refused load deletes its own object before returning, while the segment's row is unchanged, gone
+ * or `destroyed`. Once another write has changed the row, the object's number may name a re-created segment's live
+ * object, so it stays, and collection takes it like any other generation once one above it is current.
  */
 import { type IAuditSink } from './audit.js';
 import { type CodecInterface } from './codec.js';
-import type { Clock } from './determinism.js';
+import type { Clock, Rng } from './determinism.js';
 import type { IKeystore } from './crypto.js';
-import type { IStorageDriver, IRegistryDriver, SegmentRef } from './ports.js';
+import { type LoadInput } from './load-input.js';
+import { type ReadRetry } from './retry.js';
+import type { GenerationMetadata, IStorageDriver, IRegistryDriver, SegmentRef } from './ports.js';
 /** What {@link loadSegment} needs: the objects, the pointer, the codec, and key material if encrypted. */
 export interface LoadDeps {
     readonly storage: IStorageDriver;
@@ -32,6 +34,27 @@ export interface LoadDeps {
     readonly keystore?: IKeystore;
     readonly requireEncryption?: boolean;
     readonly clock?: Clock;
+    /**
+     * The random source that spreads the waits between a publish's fresh compare-and-swaps (a random time under each
+     * bound). Absent, the read retry's source is used if it has one, and otherwise each wait is its bound.
+     */
+    readonly rng?: Rng;
+    /**
+     * 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
+     * registry write that gets no answer is settled by reading the row, and sent again only as a bounded fresh
+     * compare-and-swap.
+     */
+    readonly readRetry?: ReadRetry;
+    /**
+     * Collect by listing the segment's objects after the publish, whatever `keep` is. Absent, a load that keeps at
+     * most one generation and found nothing above its pointer deletes by name the one generation its publish pushed
+     * out of the window, and lists every sixteenth generation to take what that leaves; the generations older than
+     * the window wait for that listing. Set it for a caller whose `keep` promises every generation below the new
+     * one beyond the window is gone when the call returns: the `*Into` verbs, whose `keep` is how an operator clears
+     * a destination that earlier materialisations kept in full.
+     */
+    readonly collectByListing?: boolean;
 }
 /**
  * What a plausible result looks like, so an implausible one is refused instead of published.
@@ -71,8 +94,27 @@ export interface LoadOptions {
      * collected. Keep at least one generation for every one that can be written above the pinned one while your
      * longest pinned job runs, on every writer that loads the segment — see "Generations and `keep`" in the loading
      * guide.
+     *
+     * With `keep` of 0 or 1, a load that found nothing above the pointer collects without listing: it deletes the one
+     * generation 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 the generations an earlier, wider `keep` held. With `keep` of 2 or more
+     * it lists on every load, and so does one 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 takes a
+     * name. A `keep` at least the generation published collects nothing and asks for nothing.
      */
     readonly keep?: number;
+    /**
+     * Small, immutable metadata of your own for this generation: what it was computed from, such as a definition's
+     * version, the time its data landed, or a run id. A flat object of string keys and string or finite-number values,
+     * at most 1,024 bytes as canonical JSON (keys sorted by UTF-16 code unit, no whitespace), and no key longer than 128
+     * bytes. It is stored in the generation's object, and written to the segment's row by the write that makes the
+     * generation current, so whoever sees this generation as current sees its metadata. It never changes once written:
+     * a new generation is how it changes. `undefined` and the empty object store nothing. Anything else that breaks a
+     * rule (a boolean, `null`, an array, nesting, `NaN`, a key that is not well-formed text) throws `ValidationError`
+     * before a request is made. **Never put a subject's id in it**: an erasure rewrites the ids and carries the metadata
+     * over as it is. Sealed under the segment's key when the segment is encrypted.
+     */
+    readonly metadata?: GenerationMetadata;
     readonly audit?: IAuditSink;
 }
 /** Why a load did not become current. */
@@ -82,13 +124,14 @@ export type LoadRefusal = 'empty' | 'min-cardinality' | 'min-retained'
  * 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, or the row was
  * deleted. Once another write has changed the row, the object stays in the bucket, because its generation number
- * may by then name another incarnation's live object; once the row is gone, the object is deleted.
+ * 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.
  */
  | 'superseded';
 export interface LoadResult {
     /**
      * The generation written. Present even when refused: a refusal deletes that object while the segment's row is
-     * unchanged or gone, and leaves it in the bucket once another write has changed the row. A load that lost its
+     * 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
      * generation number to another wrote nothing, and reports `size: 0`.
      */
     readonly generation: number;
@@ -108,14 +151,26 @@ export interface LoadResult {
      * whatever happens next.
      */
     readonly cardinalityBefore: number | null;
-    /** The superseded generations collected after publishing. Empty when nothing was published. */
+    /**
+     * The superseded generations collected after publishing. Empty when nothing was published.
+     *
+     * When collection deleted by name (see {@link LoadOptions.keep}) this is the name it deleted, and that generation
+     * may have been gone already: a delete of an absent object succeeds on every backend and does not say so, so the
+     * list names what the pass asked the bucket to delete, not what it found there. A listing pass names the
+     * generations it found and deleted. Neither is a receipt, since a concurrent collector may have taken a generation
+     * first.
+     */
     readonly collected: readonly number[];
 }
 /**
- * Replace a segment's contents with `ids`, as one immutable generation, and make it current.
+ * Replace a segment's contents with `input`, as one immutable generation, and make it current.
+ *
+ * `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.
  *
  * 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
  * interesting cases (a guard tripped, a racing writer won) are operational facts rather than faults.
  */
-export declare function loadSegment(ref: SegmentRef, ids: Iterable<number> | AsyncIterable<number>, deps: LoadDeps, options?: LoadOptions): Promise<LoadResult>;
+export declare function loadSegment(ref: SegmentRef, input: LoadInput, deps: LoadDeps, options?: LoadOptions): Promise<LoadResult>;

package/dist/core/metadata.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Generation metadata: a small, flat record of strings and finite numbers attached to one generation.
+ *
+ * The rules live here once, for every boundary that meets a value: a caller's input, refused with
+ * `ValidationError`, and bytes read back from a tier, refused with `IntegrityError`. The caller passes the error
+ * to raise. Pure: no I/O.
+ */
+import type { GenerationMetadata } from './ports.js';
+/** Cap on the canonical JSON of one generation's metadata, in UTF-8 bytes (braces and quotes included). */
+export declare const MAX_METADATA_BYTES = 1024;
+/** Cap on one metadata key, in UTF-8 bytes. */
+export declare const MAX_METADATA_KEY_BYTES = 128;
+/**
+ * Validate `value` as generation metadata (`GenerationMetadata` in the ports) and return its canonical JSON: RFC 8785
+ * (the JSON Canonicalization Scheme) for a flat object of strings and finite numbers. Keys are sorted by UTF-16 code
+ * unit, strings are escaped as `JSON.stringify` escapes them, numbers are written as ECMAScript's
+ * `Number.prototype.toString` writes them (so `-0` is `0`, and `1e21` is `1e+21`), and there is no whitespace. Key
+ * order therefore never changes the bytes, and `tests/golden/metadata-canonical.json` holds vectors a port can check
+ * itself against. Both caps are in UTF-8 bytes. The container is an object whose prototype is
+ * `Object.prototype` or `null`, holding only enumerable data properties with string keys. `fail` raises the error the
+ * boundary calls for. The empty object passes and returns `{}`: whether it may be stored is the caller's rule.
+ */
+export declare function canonicalMetadataJson(value: unknown, fail: (message: string) => never): string;
+/**
+ * The bytes a generation stores for `value`: its canonical JSON in UTF-8, or `undefined` when it has none (`undefined`
+ * or the empty object, which store nothing). Synchronous, so what is stored is what the caller passed at the call,
+ * whatever it does with its object afterwards. `fail` raises the boundary's error.
+ */
+export declare function metadataBytes(value: unknown, fail: (message: string) => never): Uint8Array | undefined;
+/**
+ * A caller's metadata, checked against the rules and copied, so what is stored is what the caller passed at the call,
+ * whatever it does with its object afterwards: the frozen record in canonical key order, or `undefined` when there is
+ * none (`undefined`, or the empty object, which store nothing). Synchronous. `fail` raises the boundary's error.
+ */
+export declare function copiedMetadata(value: unknown, fail: (message: string) => never): GenerationMetadata | undefined;
+/**
+ * Read metadata back from bytes a tier holds, which are untrusted. They must be at most {@link MAX_METADATA_BYTES},
+ * valid UTF-8, and exactly the canonical JSON of a non-empty record, so a stored copy has one spelling: whitespace, a
+ * key out of order or listed twice, and a number or an escape `JSON.stringify` would write another way are all
+ * refused. Returns a frozen record of its own. `fail` raises the boundary's error.
+ */
+export declare function metadataFromBytes(bytes: Uint8Array, fail: (message: string) => never): GenerationMetadata;

package/dist/core/metrics.d.ts

@@ -26,7 +26,7 @@ export type MetricEvent = {
     readonly kind: 'storage.get';
     readonly namespace?: string;
     readonly segment: string;
-    /** Bytes returned (0 if the chunk was absent — a GET still happened). */
+    /** One event per request, however many callers were waiting on it. Bytes returned (0 if the chunk was absent — a GET still happened). */
     readonly bytes: number;
     /**
      * Elapsed wall time of the read — includes any transient-retry backoff on the storage call. From the
@@ -34,6 +34,12 @@ 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 caller that missed while another caller's read of the same chunk was open waits on that
+     * read and adds no `storage.get`, so the misses can outnumber the `storage.get` events; the `storage.get`
+     * count is the number of requests.
+     */
     readonly kind: 'cache';
     readonly hit: boolean;
 } | {

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

@@ -21,7 +21,7 @@
  * on some other handle. That is why the routing is by segment identity here rather than by which object the
  * caller happened to start from.
  */
-import type { ChunkRef, StorageChunkSource, SegmentRef, SegmentSize } from './ports.js';
+import type { ChunkRef, GenerationSummary, StorageChunkSource, SegmentRef, SegmentSize } from './ports.js';
 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
@@ -67,6 +67,7 @@ export declare class PinnedStorageChunkSource implements StorageChunkSource {
     listChunkKeys(ref: SegmentRef): Promise<number[]>;
     sizeOf(ref: SegmentRef): Promise<SegmentSize | null>;
     cardinalities(ref: SegmentRef): Promise<ReadonlyMap<number, number> | null>;
+    summary(ref: SegmentRef): Promise<GenerationSummary | null>;
     currentGeneration(ref: SegmentRef): Promise<number | null>;
     /**
      * A pinned segment reports the version captured when it was pinned, marked as a pin's, so its decoded chunks

package/dist/core/ports.d.ts

@@ -59,10 +59,18 @@ export interface StorageChunkSource {
     /**
      * 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.
-     * Powers the free `count()` — the engine sums the index instead of fetching a single chunk. A source with no
+     * Powers the free `count()` of a source with no {@link StorageChunkSource.summary} — the engine sums the index
+     * instead of fetching a single chunk. A source with no
      * index (e.g. the in-memory source) omits this, and `count()` falls back to fetching every chunk.
      */
     cardinalities?(ref: SegmentRef): Promise<ReadonlyMap<number, number> | null>;
+    /**
+     * Optional: the current generation's number, id count and metadata, or `null` if the segment has no Storage
+     * generation. The `.crbm` source answers from the registry row's summary when it can use it, which is one
+     * registry read and no read of the object, and from the opened generation when it cannot. A source with no
+     * summary omits this, and `count()` keeps its other paths.
+     */
+    summary?(ref: SegmentRef): Promise<GenerationSummary | 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
@@ -105,10 +113,10 @@ export interface StorageChunkSource {
      * the generation *and* the incarnation of the name it belongs to.
      *
      * {@link StorageChunkSource.currentGeneration} is not enough to key a decoded-chunk cache, and the gap is not
-     * theoretical: a load numbers its generation `max(currentGen, highest object) + 1`, so the number **restarts at 0** once
-     * a registry row is purged and the bucket emptied. A retired, re-created name therefore serves different
-     * data at the same `currentGen`, and a cache keyed on `(segment, chunk, generation)` hands back the previous
-     * incarnation's ids — an erased id reappearing, with no read to intercept.
+     * theoretical: a load numbers its generation from the row's pointer and what is in the bucket, so the number
+     * **restarts at 0** once a registry row is purged and the bucket emptied. A retired, re-created name therefore
+     * serves different data at the same `currentGen`, and a cache keyed on `(segment, chunk, generation)` hands back
+     * the previous incarnation's ids — an erased id reappearing, with no read to intercept.
      *
      * 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.
@@ -160,8 +168,9 @@ export interface StorageCaps {
  *   loses its response, sent again, finds its own object and would report a collision. Either send each write
  *   once, with the backend client's retry off for that request, or recognise your own write when the
  *   precondition fails by reading an id you stored with it back, and treat a match as success. The first is
- *   what the S3 driver and the single-request GCS upload do; the second is what the Azure Blob driver and the
- *   resumable GCS upload do.
+ *   what the registry writes of every shipped driver do; the second is what the Azure Blob driver and the
+ *   resumable GCS upload do, and what the S3 driver and the single-request GCS upload do when they send an object
+ *   again after a throttle, which is the one replay a driver may make on purpose.
  * - **Raise a transient fault as {@link TransientError}** (throttling, a 5xx, a dropped connection), so the read
  *   retry can ride it out and a write's caller can tell it from a deterministic failure.
  */
@@ -212,6 +221,50 @@ export type RegistryStatus = 'active' | 'destroyed';
  * shape-later: stored and round-tripped, no semantics attached.
  */
 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.
+ *
+ * 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
+ * neither the count nor the metadata. A shipped registry refuses a write whose summary disagrees with the row's
+ * keys. It still reads a stored row that disagrees, so that one such row cannot stop every listing: a reader must not
+ * use that row's summary.
+ */
+export type RegistrySummary = ClearRegistrySummary | SealedRegistrySummary;
+/**
+ * A generation's metadata: string keys, string or finite-number values, no nesting, at most 1 KiB as canonical JSON.
+ * The rules are in `core/metadata.ts`.
+ */
+export type GenerationMetadata = Readonly<Record<string, string | number>>;
+/** What a generation is, as one read answers it: its number, its id count and the metadata it was written with. */
+export interface GenerationSummary {
+    readonly generation: number;
+    readonly cardinality: number;
+    /** Absent when the generation has none. */
+    readonly metadata?: GenerationMetadata;
+}
+/** {@link RegistrySummary} on a cleartext segment. */
+export interface ClearRegistrySummary {
+    /** The generation this describes. A non-negative safe integer. */
+    readonly generation: number;
+    /** How many ids the generation holds: an integer from 0 to 2^32. */
+    readonly cardinality: number;
+    /** The generation's metadata, when it has any. Never the empty object. */
+    readonly metadata?: GenerationMetadata;
+}
+/** {@link RegistrySummary} on an encrypted segment. */
+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.
+     */
+    readonly sealed: string;
+}
 /**
  * One registry row — the authoritative per-segment record. Exactly one per segment.
  */
@@ -249,10 +302,23 @@ export interface RegistryRecord extends SegmentRef {
      */
     readonly retention?: GovernanceMeta;
     readonly residency?: GovernanceMeta;
+    /**
+     * A cached description of the current generation (see {@link RegistrySummary}). Optional: a row without one is
+     * correct, and a reader then opens the generation instead. Trusted only for the generation it names.
+     */
+    readonly summary?: RegistrySummary;
     /** Epoch-ms of creation / last mutation (from the driver's injected clock). */
     readonly createdAt: number;
     readonly updatedAt: number;
-    /** Opaque OCC token — compare-by-equality, never reused (ABA-safe). */
+    /**
+     * Opaque OCC token — compare-by-equality, ABA-safe. A shipped registry gives no two writes under one name the same
+     * token: not two writes of this row, not a write of an earlier row under the name, and not a write after this row is
+     * 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.
+     */
     readonly token: Token;
 }
 /** The caller-settable fields at {@link IRegistryDriver.create} (audit + token are driver-managed). */
@@ -265,14 +331,47 @@ export interface NewRegistryRecord {
     readonly status?: RegistryStatus;
     readonly retention?: GovernanceMeta;
     readonly residency?: GovernanceMeta;
+    /** Must name `currentGen` when given. */
+    readonly summary?: RegistrySummary;
 }
-/** Fields a {@link IRegistryDriver.compareAndSwap} may mutate (identity + audit + token are off-limits). */
-export type RegistryPatch = Partial<Pick<RegistryRecord, 'currentGen' | 'wrappedDeks' | 'keyId' | 'status' | 'retention' | 'residency'>>;
+/**
+ * Fields a {@link IRegistryDriver.compareAndSwap} may mutate (identity + audit + token 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.
+ */
+export type RegistryPatch = Partial<Pick<RegistryRecord, 'currentGen' | 'wrappedDeks' | 'keyId' | 'status' | 'retention' | 'residency' | 'summary'>>;
 /** Capabilities a registry driver advertises; validated fail-fast at wiring time. */
 export interface RegCaps {
     /** REQUIRED — `currentGen` feeds read correctness + the publish CAS, so reads must be strongly consistent. */
     readonly strongRead: true;
+    /**
+     * `false` when this registry cannot write a row in this runtime, though it reads: a shipped registry draws random
+     * bytes for every token it issues, and on a runtime with no Web Crypto it has none to draw. A write path that
+     * writes an object before its row (a load, an erasure rewrite) checks it first and refuses with `UnsupportedError`
+     * before it writes anything, rather than leave an object no row names. Absent means the registry can write.
+     */
+    readonly canWrite?: false;
+    /**
+     * `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.
+     *
+     * `false` or absent: every `delete` leaves a tombstone, which every later full `list` still reads. A shipped registry
+     * says which it is.
+     */
+    readonly conditionalDelete?: boolean;
 }
+/**
+ * Refuse, with `UnsupportedError`, a write that would write an object before its row when the registry reports it
+ * cannot write a row (see {@link RegCaps.canWrite}). Called before the write's first request.
+ */
+export declare function assertRegistryCanWrite(registry: IRegistryDriver, what: string): void;
 /**
  * Brand for {@link StorageBackend}.
  *
@@ -365,8 +464,13 @@ export declare function isStorageBackend(value: unknown): value is StorageBacken
  * - **`create` and `compareAndSwap` are atomic conditional writes.** A `create` over a live row, and a
  *   `compareAndSwap` whose token is not the stored one, throw {@link WriteConflictError} and change nothing.
  *   Two racing writers have exactly one winner.
- * - **Tokens are never reused**, not even across `delete` then `create`: a delete leaves a tombstone (or a
- *   global counter) so a recreated row always carries a fresh token and a stale holder cannot swap into it.
+ * - **A token is not reused, not even across `delete` then `create`**, short of a collision of probability 2^-128 for
+ *   any two incarnations of one name: a recreated row carries a token no earlier incarnation held, so a stale holder
+ *   cannot swap into it. The shipped drivers draw a random 128-bit incarnation id into the token of every row they
+ *   create and a random 64-bit part into the token of every write, beside a counter a tombstone (or a global counter)
+ *   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.
  * - **`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.
@@ -408,7 +512,9 @@ export interface IRegistryDriver {
      */
     list(namespace?: string): AsyncIterable<RegistryRecord>;
     /**
-     * Remove the row (tombstoned for ABA-safety — a later `create` still gets a fresh, greater token).
+     * 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
+     * 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/registry-scan.d.ts

@@ -27,6 +27,12 @@ export declare function drainRegistry(registry: IRegistryDriver, options: {
      * one namespace, so it passes false and the refusal does not tell it to narrow what it cannot.
      */
     narrowable?: boolean;
+    /**
+     * Told of each bookkeeping row an unscoped scan skips, which the listing has already paid to read. Only the
+     * retention sweep uses it, to find the due-index pointers whose segment has no row. It is not counted against
+     * `maxScanSegments`, and a caller that holds the rows it is given bounds them itself.
+     */
+    onReserved?: (record: RegistryRecord) => void;
 }): Promise<RegistryRecord[]>;
 /**
  * Is this record **bookkeeping** rather than a segment? Covers every reserved family — today the due-index