@cloudbitmaps/core 0.16.0 → 0.17.0

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

@@ -1,6 +1,7 @@
 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';
@@ -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

package/dist/core/engine.d.ts

@@ -166,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.
      *

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;

package/dist/core/leases.d.ts

@@ -0,0 +1,119 @@
+import type { Clock, Rng } from './determinism.js';
+import type { IRegistryDriver, LeaseEntry, RegistryRecord, SegmentRef, Token } from './ports.js';
+/** The longest lease: a `leaseUntil` further than this from the clock is refused. */
+export declare const MAX_LEASE_MS: number;
+/**
+ * How much longer than `until` a collector holds a lease, and the most a collector will believe a lease runs past
+ * its own clock. It is the tolerated difference between the holder's clock and the collector's, in either direction.
+ */
+export declare const LEASE_SKEW_MS = 60000;
+/** The most live leases a writer records on one segment; the next one is refused with {@link LeaseLimitError}. */
+export declare const MAX_LEASES_PER_SEGMENT = 64;
+/** The most entries a stored row may hold: four times what a writer writes, so a release can raise the cap. */
+export declare const MAX_STORED_LEASES = 256;
+/**
+ * Read-modify-write attempts of one take or release before it reports contention. Takers of one row serialise: each
+ * round exactly one write lands, so the slowest of `k` simultaneous takers needs `k` attempts. The bound is the cap
+ * plus a few, so that the most a segment can hold, all arriving at once, can all land.
+ */
+export declare const LEASE_CAS_ATTEMPTS: number;
+/**
+ * Whether an entry holds its generation against a collector reading `now`: it has not ended (`until` plus the margin
+ * is ahead), and it does not run further past `now` than any honest holder with a clock inside the margin could have
+ * written (`until` at most the longest lease plus the margin ahead). The second clause bounds a corrupt or forged
+ * `until` without refusing the row: an entry past it is read and not honoured.
+ */
+export declare function isLive(entry: LeaseEntry, now: number): boolean;
+/** The generations a collector reading `now` must spare, from the row it holds. */
+export declare function heldGenerations(record: RegistryRecord | null, now: number): ReadonlySet<number>;
+/** The entries of a row that are live at `now`, in the row's order. */
+export declare function liveLeases(record: RegistryRecord | null, now: number): readonly LeaseEntry[];
+/**
+ * What a writer that fences on the row's token needs to wait out lease churn: a sleep, and the rng that spreads it.
+ * Both are optional; without a sleep a retry follows at once.
+ */
+export interface ChurnDeps {
+    readonly clock?: {
+        readonly sleep?: (ms: number) => Promise<void>;
+    } | undefined;
+    readonly rng?: Rng | undefined;
+}
+/**
+ * How many times one writer retries after meeting a row that differs from the one it read only in its leases. Takers of
+ * one row serialise: each round exactly one write lands, so a writer racing `k` holders needs up to `k + 1` rounds, and a
+ * holder can take and release inside one job, so the bound covers a take and a release by every holder the row can
+ * hold, with a few to spare: 2 * {@link MAX_LEASES_PER_SEGMENT} + 8. At waits of up to 25 ms growing to up to 400 ms it is a
+ * minute at the very most before the writer reports the conflict it had, and a lease writer that goes on beyond
+ * that has stopped being a lease writer and become a flood.
+ */
+export declare const LEASE_ONLY_RETRIES: number;
+/**
+ * Whether `now` is `held` with nothing changed but its leases: the same incarnation, and every other field equal,
+ * `updatedAt` and the token (which every write moves) aside. `alsoIgnore` names fields the caller's own earlier write
+ * changed, so a writer comparing against a row it has itself written does not take its own change for another's.
+ *
+ * This is the one test that lets a writer fenced on the row's token go on after a lease write: a lease is written by
+ * readers, in numbers no operator controls, and it says nothing about the content the writer derived, the pointer it
+ * judged or the key it holds. Any other difference is another writer's, and the fence refuses as it always has.
+ */
+export declare function onlyLeasesDiffer(held: RegistryRecord, now: RegistryRecord, alsoIgnore?: readonly (keyof RegistryRecord)[]): boolean;
+/** A writer's count of the lease-only changes it has waited out, and the wait. One per call of the writer. */
+export interface LeaseChurn {
+    /**
+     * When `now` is `held` changed only in its leases and the bound is not spent: wait, then read the row again with
+     * `reread`, and return what it found. The wait comes before the read, so the writer's next write is made against a row
+     * as fresh as one round trip, not one as stale as the wait. The caller checks that row against `held` once more (a
+     * write may have landed during the wait) and goes on against it, without redoing its work. `undefined` otherwise, and
+     * the caller does what it always did.
+     *
+     * The wait is uniform in `[0, bound)`, the bound starting at 25 ms and doubling to 400 ms, taken on the injected
+     * clock's `sleep` and spread by its `rng`. With no `sleep` there is no wait, and the retries follow one another at
+     * once; with no `rng` the wait is exactly the bound, so contenders stay in step. The store always supplies both.
+     */
+    settle(held: RegistryRecord | null | undefined, now: RegistryRecord | null, reread: () => Promise<RegistryRecord | null>, alsoIgnore?: readonly (keyof RegistryRecord)[]): Promise<{
+        readonly row: RegistryRecord | null;
+    } | undefined>;
+}
+export declare function leaseChurn(deps: ChurnDeps): LeaseChurn;
+/** What the lease writers need: the registry, the clock that judges liveness and waits, and the rng that spreads waits. */
+export interface LeaseDeps {
+    readonly registry: IRegistryDriver;
+    readonly clock: Clock;
+    readonly rng?: Rng;
+}
+/** What a take asks for. */
+export interface LeaseTake {
+    /** Drawn once per pin call, outside any retry, so a write that landed unseen is found again and never duplicated. */
+    readonly holder: string;
+    /** The generation to hold. */
+    readonly generation: number;
+    /** Epoch-ms, already checked against the caller's clock. */
+    readonly until: number;
+    /** The row the caller read; the first write is made against it, with no row read of its own. */
+    readonly row: RegistryRecord;
+    /** The generation must still be the row's pointer on every attempt: a pin of the current generation. */
+    readonly current: boolean;
+}
+/** A lease that landed: the token its write returned, and the row that write was made against. */
+export interface TakenLease {
+    readonly token: Token;
+    readonly row: RegistryRecord;
+}
+/**
+ * Write a lease entry for `take.holder`, fenced on the row it was made against, so a lease that lands proves the row
+ * was unchanged since the caller read it. Returns `'moved'` when `take.current` and the pointer is no longer at the
+ * generation (the caller starts over from a fresh read). Throws {@link NotFoundError} for a row that is gone,
+ * destroyed or has no such published generation, {@link LeaseLimitError} when the segment already has
+ * {@link MAX_LEASES_PER_SEGMENT} live leases (nothing is written), `WriteConflictError` after
+ * {@link LEASE_CAS_ATTEMPTS} lost races, and the registry's own `TransientError` for a write that stayed unanswered.
+ *
+ * Idempotent by holder: an entry for the holder is replaced, so a retry of a whole pin re-takes without duplicating,
+ * and a write that got no answer is settled by reading the row for the holder's entry.
+ */
+export declare function takeLease(ref: SegmentRef, deps: LeaseDeps, take: LeaseTake): Promise<TakenLease | 'moved'>;
+/**
+ * Remove `holder`'s entry, and every entry that has ended, in one write. Idempotent: a row that is gone, destroyed or
+ * has no entry for the holder is already released. Throws `WriteConflictError` after {@link LEASE_CAS_ATTEMPTS} lost
+ * races and the registry's `TransientError` for a write that stayed unanswered over an unchanged row.
+ */
+export declare function releaseLease(ref: SegmentRef, deps: LeaseDeps, holder: string): Promise<void>;

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

@@ -62,3 +62,15 @@ export declare class ChunkLoadInput {
  * 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;
+/**
+ * Portable bytes a caller holds, checked and decoded by the codec's safe deserializer: the one check every bitmap
+ * input of a load goes through, and what a flavor offers its users to decode bytes they hold themselves.
+ *
+ * The bytes must be a `Uint8Array` (a Node `Buffer` is one), at most {@link MAX_SERIALIZED_LOAD_BYTES}, one whole
+ * bitmap and structurally sound. A view is read over the bytes it really holds, and bytes in a `SharedArrayBuffer`
+ * are copied first. An empty or detached buffer is the empty bitmap.
+ *
+ * @param what names the input in a refusal's message.
+ * @throws {ValidationError} for anything that is not such bytes; nothing reaches the codec's native decoder then.
+ */
+export declare function decodeSerialized(bytes: unknown, codec: CodecInterface, what?: string): CodecBitmap;