@cloudbitmaps/core 0.15.0 → 0.17.0

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

@@ -1,12 +1,13 @@
 import { type IAuditSink } from './audit.js';
 import type { Yielder } from './cooperative.js';
 import type { Clock, Rng } from './determinism.js';
+import type { PublishedKept } from './generation-gc.js';
 import type { Aead, CrbmCrypto, IKeystore, WrappedDek } from './crypto.js';
 import type { ChunkRef, ChunkRead, ReadChunksOptions, StorageChunkSource, GenerationMetadata, GenerationSummary, GenKey, IStorageDriver, IRegistryDriver, RegistryRecord, RegistrySummary, SegmentRef, SegmentSize, Token } from './ports.js';
 import { CrbmReader } from './crbm/reader.js';
 import type { CrbmReaderOptions } from './crbm/reader.js';
 import type { CodecBitmap, CodecInterface } from './codec.js';
-import { DecodedLoadInput } from './load-input.js';
+import { ChunkLoadInput, DecodedLoadInput } from './load-input.js';
 export interface CrbmStorageChunkSourceOptions extends CrbmReaderOptions {
     /**
      * Optional {@link IRegistryDriver}. When provided, the current generation is resolved via the registry's
@@ -78,6 +79,18 @@ export interface PinnedObject {
     readonly version: string;
     readonly fingerprint?: string;
 }
+/**
+ * What one resolution of a segment's pointer found: the target, and what its row says of the generation, each
+ * computed only when asked for. The key is unwrapped once however many ask, and a failure is not remembered, so a
+ * transient fault in the keystore is asked again.
+ */
+/** What a pin that leases its generation does between reading the row and opening the object. */
+export interface PinLease {
+    /** Write the lease against the row the pin read: its token, or `'moved'` when the pointer is no longer at the generation. */
+    take(row: RegistryRecord): Promise<{
+        readonly token: Token;
+    } | 'moved'>;
+}
 export declare class CrbmStorageChunkSource implements StorageChunkSource {
     private readonly driver;
     /**
@@ -216,9 +229,27 @@ export declare class CrbmStorageChunkSource implements StorageChunkSource {
      * and a `keep: 0` sweep can land in that gap, and nothing has been handed out yet, so the generation current
      * once the swept one is gone is exactly what a pin taken now should hold. One retry, then propagate.
      */
-    pinGeneration(ref: SegmentRef): Promise<({
+    pinGeneration(ref: SegmentRef, lease?: PinLease): Promise<({
         generation: number;
     } & Required<PinnedObject>) | null>;
+    /**
+     * Open one named generation and verify it is the object `at.fingerprint` names, for a pin the caller reopens. One
+     * row read and one tail read with a registry (none of the row for a store without one): the open is the one a
+     * pinned read makes ({@link readerAt}), memoised under the version the pin will read by, so the pin's first read
+     * finds it open. A generation that is gone, above the row's pointer, on a destroyed or absent row, or another
+     * object than the fingerprint names, throws `NotFoundError`; nothing here reads empty.
+     *
+     * A generation counts as published while the pointer is at or above it. A rollback deletes nothing, so after one
+     * and a later load, a generation it rolled back from can be reopened while its object is still stored and the
+     * fingerprint matches. Like `pinGeneration`'s pinned reads, this opens the object without the live open's check
+     * of the row's summary against it, since that check is made where the row's own generation is read.
+     */
+    pinGenerationAt(ref: SegmentRef, at: {
+        readonly generation: number;
+        readonly fingerprint: string;
+    }, lease?: PinLease): Promise<{
+        generation: number;
+    } & Required<PinnedObject>>;
     private pinOnce;
     /**
      * Where a pinned reader of one object is memoised. With a registry that is its version, which names the object:
@@ -460,72 +491,17 @@ export declare function writeCrbmGenerationStream(driver: IStorageDriver, key: G
     clock?: Yielder;
     metadata?: GenerationMetadata;
 }): Promise<StreamWriteResult>;
-/**
- * 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
- *   `holdsOwnObject` proves the object under it the caller's: the write landed, and the publish returns `true`. Only
- *   the writer of a write-once object publishes its number, and a number is never taken while an object holds it;
- * - 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.
- *
- * **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 publishGeneration(registry: IRegistryDriver, key: GenKey, options?: {
+export declare function publishGenerationKept(registry: IRegistryDriver, key: GenKey, options?: {
     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;
     /**
      * Publish only while the segment still has **no registry row**.
      *
@@ -584,7 +560,39 @@ export declare function publishGeneration(registry: IRegistryDriver, key: GenKey
      * held its generation for a while before another writer moved on.
      */
     onUnanswered?: () => void;
-}): Promise<boolean>;
+    /**
+     * 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 (`keptGens`: the newest `keep` of the row's own list and the generation that was
+     * current), 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 records, the row records none, and a collection lists.
+     */
+    keep?: number;
+}): 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;
+}
+/**
+ * {@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?: Parameters<typeof publishGenerationKept>[2]): Promise<boolean>;
 /**
  * Whether the object under `key` is the one `fingerprint` names, from one read of its footer: false when it is another
  * object or gone. Unlike {@link holdsObject}, a read that cannot tell throws, for a caller that must not take "could
@@ -655,7 +663,7 @@ export interface BulkLoadResult {
  * {@link WriteConflictError} (write-once). Without a registry a `StorageChunkSource` serves the **highest**
  * generation present, so a too-high number silently shadows real data; with one, `publishGeneration` decides.
  */
-export declare function bulkLoadCrbmGeneration(driver: IStorageDriver, key: GenKey, ids: Iterable<number> | AsyncIterable<number> | DecodedLoadInput, options?: {
+export declare function bulkLoadCrbmGeneration(driver: IStorageDriver, key: GenKey, ids: Iterable<number> | AsyncIterable<number> | DecodedLoadInput | ChunkLoadInput, options?: {
     registry?: IRegistryDriver;
     keystore?: IKeystore;
     requireEncryption?: boolean;
@@ -724,7 +732,7 @@ export interface LoadAhead {
  * {@link bulkLoadCrbmGeneration} for a load whose number, and perhaps its key, are still being fetched: the same
  * options, with the same meaning, and the same writes. The number is joined only where the object is written.
  */
-export declare function bulkLoadAhead(driver: IStorageDriver, ref: SegmentRef, ahead: LoadAhead, ids: Iterable<number> | AsyncIterable<number> | DecodedLoadInput, options?: NonNullable<Parameters<typeof bulkLoadCrbmGeneration>[3]>): Promise<BulkLoadResult>;
+export declare function bulkLoadAhead(driver: IStorageDriver, ref: SegmentRef, ahead: LoadAhead, ids: Parameters<typeof bulkLoadCrbmGeneration>[2], options?: NonNullable<Parameters<typeof bulkLoadCrbmGeneration>[3]>): Promise<BulkLoadResult>;
 /**
  * Open a {@link CrbmReader} on one generation over the storage driver's range/tail reads (decrypting if `crypto`).
  * The reader the write paths use to re-read what they wrote, and the erasure rewrite uses to stream the old

package/dist/core/engine.d.ts

@@ -78,6 +78,11 @@ export interface CombineOptions extends IdRange {
      */
     readonly allowAbsentOperands?: boolean;
 }
+/** One chunk of a combine's result: the bitmap of its remainders, owned by whoever reads it. */
+export interface CombinedChunk {
+    readonly chunkKey: number;
+    readonly bitmap: CodecBitmap;
+}
 export declare class SegmentEngine {
     private readonly storage;
     private readonly cache;
@@ -99,6 +104,8 @@ export declare class SegmentEngine {
      * they deliver, as a read whose entry an invalidation dropped does not (streams hold no `openReads` entry).
      */
     private readonly openStreams;
+    /** How many times {@link invalidate} has been called: a read compares it with the count it began under. */
+    private invalidations;
     constructor(deps: EngineDeps);
     /** Membership: one chunk lookup — the cache, else one Storage fetch of that chunk. */
     has(seg: SegmentRef, id: number): Promise<boolean>;
@@ -159,6 +166,29 @@ export declare class SegmentEngine {
      * the caller's to keep.
      */
     iterateBatches(seg: SegmentRef, range?: IdRange): AsyncGenerator<Uint32Array>;
+    /**
+     * The ids at 1-based ranks `n`, `2n`, `3n` … counted over the ids in `range`, ascending. The rank of each boundary
+     * is placed from the index's per-chunk counts, so only the chunks that hold a boundary are read, each once however
+     * many boundaries it holds, through the same coalesced stream, window and budget unit as {@link iterate}. A range with
+     * `after` inside a chunk reads that chunk too, to count the ids at or below `after`. A last partial window yields
+     * nothing.
+     *
+     * The counts place ids, and are trusted as `count()` trusts them: a chunk that is read must decode to the size its
+     * index says, or the read throws {@link IntegrityError} (invariant 5), but a chunk that is not read is not checked, so
+     * an index that lies consistently about one (on an unencrypted object, the sum still matches the footer's total,
+     * which opening the object checks before any boundary is placed) shifts the ranks after it. An encrypted object's
+     * index is authenticated and bound to the object, so a wrong count there needs the key. The index and the chunks must come from one
+     * generation (invariant 3): the caller reads through a source that holds one, a pinned one, and a source with no
+     * per-chunk counts is refused.
+     *
+     * Nothing is fetched when the chunks in range hold fewer than `n` ids. The budget is charged before the first fetch
+     * with an upper bound, the cut chunk plus one chunk per boundary the counts allow (capped by the chunks in range),
+     * which can exceed the chunks actually read. A range that cuts its first chunk reads it even when the ids above
+     * `after` turn out to be fewer than `n`, and one that cuts its last chunk may read it and yield nothing.
+     */
+    everyNth(seg: SegmentRef, n: number, range?: IdRange): AsyncGenerator<number>;
+    /** A chunk's remainders ascending, once its size is confirmed against the index's count for it (invariant 5). */
+    private chunkRemainders;
     /**
      * `segs[0] ∩ segs[1] ∩ …`, minus every id in `options.exclude` — streamed ascending.
      *
@@ -215,6 +245,20 @@ export declare class SegmentEngine {
     unionBatches(segs: readonly SegmentRef[], options?: CombineOptions): AsyncGenerator<Uint32Array>;
     /** {@link andNot}, one `Uint32Array` per chunk — see {@link iterateBatches}. */
     andNotBatches(seg: SegmentRef, excludes: readonly SegmentRef[], options?: Omit<CombineOptions, 'exclude'>): AsyncGenerator<Uint32Array>;
+    /**
+     * {@link intersect}, as the chunks the result is made of: `{ chunkKey, bitmap }` in ascending key order, each a
+     * non-empty bitmap of the chunk's 16-bit remainders, cut to the read's range. What a materialisation writes
+     * straight into its new generation, with no id built on the way.
+     *
+     * **Each bitmap belongs to the caller, who may change it:** it is the combine's own accumulator or a bitmap built
+     * for the range's edge, never a chunk the cache holds or another operand's. The reads, the budget, the metric and the
+     * errors are the id reads' own.
+     */
+    intersectChunks(segs: readonly SegmentRef[], options?: CombineOptions): AsyncGenerator<CombinedChunk>;
+    /** {@link union}, as chunks: see {@link intersectChunks}. */
+    unionChunks(segs: readonly SegmentRef[], options?: CombineOptions): AsyncGenerator<CombinedChunk>;
+    /** {@link andNot}, as chunks: see {@link intersectChunks}. */
+    andNotChunks(seg: SegmentRef, excludes: readonly SegmentRef[], options?: Omit<CombineOptions, 'exclude'>): AsyncGenerator<CombinedChunk>;
     /**
      * Everything a combine decides before it reads a chunk: validation, each operand's keys and generation, the
      * absent-operand refusal, key alignment, the budget and the metric. `null` when the range is empty. The per-id
@@ -223,6 +267,10 @@ export declare class SegmentEngine {
     private combinePlan;
     private combine;
     private combineBatches;
+    /** The chunk read: the plan every combine shares, then each key's result, cut to the range at its edges. */
+    private combineChunks;
+    /** An edge chunk's bitmap cut to the window, as a new bitmap: the remainders `edgeIds` would yield. */
+    private cutToWindow;
     /**
      * The AND (or OR) of one chunk key across all operands, minus the excludes that hold it, or `null` if empty.
      * Operand chunks are fetched **in parallel** (the spec's parallel byte-range reads).
@@ -239,16 +287,21 @@ export declare class SegmentEngine {
      */
     private operandChunk;
     /**
-     * Open `keys` of `seg` as a stream of coalesced ranges, or `undefined` when the read is per key: a source with no
-     * `getChunks`, a segment with no generation, or nothing to read. The chunks already decoded in the cache are taken out
-     * of the key list first and served from there, so a repeat read asks the source for nothing it holds. Nothing is
-     * requested until the first chunk is asked for.
+     * `keys` of `seg` as a stream of coalesced ranges, or `undefined` when the read is per key: a source with no
+     * `getChunks`, a segment with no generation, or nothing to read. Nothing is requested, and no cache lookup made, until
+     * the first chunk is asked for (see {@link StreamedChunks}).
      */
     private openStreamed;
+    /**
+     * Open the stream of `streamed`, at its first uncached chunk `from`: over that chunk and the later keys the cache does
+     * not hold. Each later key is counted as a cache hit or miss here, so a key is counted once whichever way it is served.
+     */
+    private startStream;
     private closeStreamed;
     /**
-     * The decoded chunk at `chunkKey` of a streamed read: the next chunk of its stream, or, for a chunk the cache held
-     * when the read opened, the cached instance while it is still there, and a read of that chunk alone once it is not.
+     * The decoded chunk at `chunkKey` of a streamed read: from the cache while the stream is unopened and the cache holds
+     * it; else the next chunk of its stream, or, for a chunk the cache held when the stream opened, the cached instance
+     * while it is still there, and a read of that chunk alone once it is not.
      */
     private streamedChunk;
     /**

package/dist/core/erasure.d.ts

@@ -13,8 +13,9 @@
  * operation — `eraseIdFromSegment` rewrites the generation without it.
  */
 import { type IAuditSink } from './audit.js';
+import { type ChurnDeps } from './leases.js';
 import type { IStorageDriver, IRegistryDriver, SegmentRef } from './ports.js';
-export interface EraseDeps {
+export interface EraseDeps extends ChurnDeps {
     readonly registry: IRegistryDriver;
 }
 export interface DestroyResult {

package/dist/core/errors.d.ts

@@ -42,6 +42,25 @@ export declare class IntegrityError extends CloudRoaringError {
  */
 export declare class NotFoundError extends CloudRoaringError {
 }
+/**
+ * A read of a leased pin came after its lease ended, by `until` or by `release()`. Thrown at every read site of the
+ * handle, including a leased handle used as an operand or an exclude of a combine, and never answered empty: a
+ * handle that read empty here would be an opt-out list that suppresses nobody. Carries the instant the lease ended
+ * and why; never an id or a key.
+ */
+export declare class LeaseExpiredError extends CloudRoaringError {
+    /** Epoch-ms the lease was taken until. */
+    readonly until: number;
+    /** `'expired'` when the clock reached `until`, `'released'` after `release()`. */
+    readonly reason: 'expired' | 'released';
+    constructor(message: string, until: number, reason: 'expired' | 'released');
+}
+/**
+ * A segment already has as many live leases as one row records, so another cannot be taken. Nothing was written.
+ * Release one, wait for one to end, or share one lease across the tasks of a job.
+ */
+export declare class LeaseLimitError extends CloudRoaringError {
+}
 /**
  * This build/configuration cannot perform the requested operation, though nothing is malformed. Two uses:
  * (1) **format** — the bytes are well-formed but unreadable here (an unknown `.crbm` major version) —
@@ -104,6 +123,10 @@ export declare function isCloudRoaringError(err: unknown): err is CloudRoaringEr
 export declare function isWriteConflictError(err: unknown): err is WriteConflictError;
 /** A retryable transient infrastructure fault. The retry layer keys on this. */
 export declare function isTransientError(err: unknown): err is TransientError;
+/** A read came after its pin's lease ended. */
+export declare function isLeaseExpiredError(err: unknown): err is LeaseExpiredError;
+/** A segment has no room for another live lease. */
+export declare function isLeaseLimitError(err: unknown): err is LeaseLimitError;
 /** A requested object/row does not exist. */
 export declare function isNotFoundError(err: unknown): err is NotFoundError;
 /** Corrupt/oversized/failed-checksum bytes from a tier. */

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

@@ -1,4 +1,4 @@
-import type { GenKey, IStorageDriver, IRegistryDriver, RegistryRecord, SegmentRef } from './ports.js';
+import type { GenKey, IStorageDriver, IRegistryDriver, RegistryRecord, SegmentRef, Token } 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;
@@ -51,9 +51,9 @@ export interface LoadNumber {
 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
+ * takes the names its publish pushed out of the row's window and never looks at the rest, so what it misses (a crashed
+ * or refused load's object, a delete that failed, extras a fault left after 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.
@@ -97,58 +97,82 @@ export declare function gcOrphanGenerations(ref: SegmentRef, deps: GenerationDep
     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.
+ * What makes a collection spare leased generations: the clock that says whether a lease has ended. Only a load's
+ * collection passes one, and a load with no clock passes none: it cannot tell a live lease from an ended one, so it
+ * reads none. A pass without a guard never reads the row's leases, which is what keeps erasure, shred and drop deleting
+ * what a lease names.
+ */
+export interface LeaseGuard {
+    readonly now: () => number;
+}
+/** What a load's publish recorded in the row, as `publishGeneration` reports it. */
+export interface PublishedKept {
+    /** The list the publish wrote, or `undefined` when it wrote none (the row then does not know which are kept). */
+    readonly list: readonly number[] | undefined;
+    /** The names the publish pushed out of the window, ascending. */
+    readonly evict: readonly number[];
+    /** The token of the row the publish wrote, when it is known: a write settled by reading the row has none. */
+    readonly token: Token | undefined;
+}
+/**
+ * Collect after a load's publish. The row records the generations the load keeps, so the pass deletes by name what the
+ * publish pushed out of that window ({@link deleteEvicted}) and lists the segment ({@link gcOrphanGenerations}'s
+ * pass) only when it cannot rely on the row or must catch what a name does not:
+ *
+ *  - the row recorded no list (a `keep` above {@link MAX_KEPT_GENERATIONS}, a row an earlier schema wrote, one a
+ *    rollback or an erasure moved, or a publish whose write was settled by reading the row): the pass keeps the
+ *    newest `keep` generations present below the pointer, and records them with one compare-and-swap, fenced on the
+ *    publish's own token, so the next load collects by name;
+ *  - the guard found the current generation's object gone, or, for a `keep` of 1 or more when the guard took the size
+ *    from the row's summary and opened nothing, one zero-byte read of it does not find it (`proveCurrent`): the
+ *    window then counts a generation that is not there, so the same pass keeps what is;
+ *  - a number the listing chose (something sits above the pointer, or the existence check could not answer), a
+ *    caller that asks for a listing, and every {@link LIST_COLLECTION_CADENCE}th generation: the pass deletes every
+ *    generation below the pointer the row does not name, 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, and the drop's own sweep takes the rest.
+ *
+ * The seed's compare-and-swap moves the row's token, so a derived writer in flight on the row (an erasure rewrite)
+ * meets a lost fence and re-derives: it happens once per row that recorded no list. A `WriteConflictError` from it is
+ * a lost race, and the load took effect, so it is not raised; the next load records the list. Any other fault is
+ * raised, as every fault of a collection after a landed publish is.
  */
 export declare function collectAfterLoad(ref: SegmentRef, deps: GenerationDeps, options: {
     generation: number;
     keep: number;
+    /** The load's number was proved free by one existence check, and no caller asked for a listing. */
     byName: boolean;
+    /** The guard opened the current generation's object and found it gone. */
+    currentGone?: boolean;
+    kept: PublishedKept | undefined;
     /**
-     * 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.
+     * The object the load's row named as current, which the caller did not open. Before it collects by name, 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;
+    /** Spare the generations the row's live leases hold. Absent, the pass ignores leases. */
+    leases?: LeaseGuard;
 }): 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.
+ * Delete, with no listing, the generations a publish of `generation` pushed out of its row's window, `evict`, taken
+ * from the list the publish was written against. Returns the names asked for, whether or not an object was there: a
+ * delete of an absent object succeeds on every backend and says nothing, so 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.
+ * Each delete re-reads the row first (invariant 4) and stops the pass, deleting nothing more and raising nothing, unless
+ * the row still has a pointer at or above `generation` (a rollback, or a name purged and re-created with fewer loads,
+ * has moved it below: the publish already landed, nothing here protects it or needs the result), the name is below
+ * that pointer, and the row's own list is usable and does not name it. The last condition is what keeps a late delete
+ * from taking a generation that a later publish, after a rollback, put in the window. 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, propagates, with the pointer at `generation`.
  */
-export declare function collectByName(ref: SegmentRef, deps: GenerationDeps, options: {
+export declare function deleteEvicted(ref: SegmentRef, deps: GenerationDeps, options: {
     generation: number;
-    keep: number;
+    evict: readonly number[];
+    leases?: LeaseGuard;
 }): Promise<number[]>;

package/dist/core/kept-generations.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The generations a segment's row records as kept: the grace window below its pointer, so a load collects what its
+ * publish pushed out of the window by name instead of listing the bucket.
+ *
+ * The record is a cache of what a listing would keep, never an inventory of the bucket. Absent means the row does not
+ * know, and the load lists; an empty list means nothing below the pointer is kept. A patch that moves the pointer
+ * without naming the list drops it (see `applyRegistryPatch`), so a writer that forgets the list leaves a row that
+ * lists, never one that deletes a generation it should keep. Pure: no I/O, time or randomness.
+ */
+import type { RegistryRecord } from './ports.js';
+/**
+ * The most generations a writer records. A `keep` above it records none, and the load lists on every publish. A
+ * reader accepts up to {@link MAX_STORED_KEPT_GENERATIONS}, so a release can write more than this without a new row
+ * schema.
+ */
+export declare const MAX_KEPT_GENERATIONS = 64;
+/** The most entries a stored row may hold: four times what a writer writes. */
+export declare const MAX_STORED_KEPT_GENERATIONS = 256;
+/**
+ * The row's list when a collection may rely on it: present, on a row with a pointer, and every entry below that
+ * pointer. A well-formed list that disagrees with the pointer is read but not used (the load lists instead), as a
+ * summary that names another generation is.
+ */
+export declare function usableKeptGens(record: RegistryRecord | null): readonly number[] | undefined;
+/** What a publish of a generation writes into the row, and which names it pushes out of the window. */
+export interface KeptAfter {
+    /** The list to write, or `undefined` to write none (the row then does not know, and the next load lists). */
+    readonly list: readonly number[] | undefined;
+    /** The generations the window no longer keeps, ascending: the names to delete. */
+    readonly evict: readonly number[];
+}
+/**
+ * The list a publish of `generation` over `prev` writes: the newest `keep` of the row's list and the generation that
+ * was current, and the names that fell out of it. Only generations that were current are named, so a number a refused
+ * or crashed load took is never in it.
+ *
+ * No list is written when the row has no usable list to extend (except for generation 0, which has nothing below it),
+ * when `keep` is above {@link MAX_KEPT_GENERATIONS}, or when no `keep` is given.
+ */
+export declare function nextKept(prev: RegistryRecord | null, generation: number, keep: number | undefined): KeptAfter;