@cloudbitmaps/core 0.19.1 → 0.21.0

package/dist/core/erase-id.d.ts

@@ -11,9 +11,11 @@
  *
  * The rewrite is the same generation without one id, so it keeps everything else: the new object carries the source's
  * metadata as it is, and the row's summary of it, built from what was written, counts one id fewer and holds the same
- * metadata. Metadata is not scanned for the id. On an encrypted segment, a source object with no metadata block whose
- * row's sealed summary of it has metadata is rewritten with the row's: the block's presence is not authenticated, so
- * the authenticated copy decides, and the erasure still goes through.
+ * metadata. Metadata is not scanned for the id. A source object whose metadata block was stripped is another object
+ * than the row's summary names: its size is not the one the summary records, so the fingerprint check refuses it
+ * before the erasure reads any of its ids. Only one forged to match that fingerprint gets past, and on an encrypted
+ * segment it is rewritten with the metadata of the row's sealed summary: the block's presence is not authenticated, so
+ * the authenticated copy decides.
  *
  * **`erased: true` is a claim about every generation of the segment, not only the one it replaced.** A rollback
  * leaves generations above the pointer that were once current and can be made current again, so a holder can sit
@@ -48,16 +50,22 @@
  * Which reason comes from **re-reading the row**, not from assuming a supersession: a moved pointer is
  * `'superseded'`, a tombstoned row `'destroyed'`, a purged row `'absent'`, a row with no pointer
  * `'no-generation'`. A pointer still on `from` means the object it names is genuinely gone — the forbidden
- * `missing-storage-generation` state — and that throws, because no re-run fixes it. That `NotFoundError` is the only
- * signal of that state, so a faulting re-read rethrows it rather than replacing it with a transient-looking
- * registry error.
+ * `missing-storage-generation` state — or is another object than the row's summary names by its fingerprint, and that
+ * throws, because no re-run fixes either. That `NotFoundError` is the only signal of those states, so a faulting
+ * re-read rethrows it rather than replacing it with a transient-looking registry error.
  *
  * **A refused rewrite deletes its own object when it would outlive the winner above the pointer.** `putImmutable`
  * commits atomically, so a rewrite whose stream throws leaves no object at all. One that completed is either
  * below the winner's pointer, where the winner's collection takes it, or above it: the case where this call took
  * its number after the winner's object was already in the bucket. Up there nothing collects it, and it was derived
  * from a generation the winner has replaced, so when the winner was another erasure it still holds the id that
- * erasure has just reported gone. That object is deleted before this call returns — see `discardRefused`.
+ * erasure has just reported gone. That object is deleted before this call returns, once its footer matches the
+ * rewrite's and a renewal of the row has refused every publish fenced on a row read before it, under the version the
+ * footer read reported, unless {@link DISCARD_ATTEMPTS} renewals lose to other writes (a load, a rollback, a
+ * retention write): then it is kept, and can hold the winner's id, until a later call takes it: any erasure that
+ * rewrites the segment (this one's re-run among them, while its id is still in the current generation) numbers above it
+ * and its `keep: 0` collection takes it, an erasure of the winner's id deletes it as a holder, and once loads number
+ * past it their collection takes it as it takes any orphan — see `discardRefused`.
  *
  * Without that fence the failure was silent and severe, and both halves were reproduced: `nextGeneration` picks a
  * number above everything in the bucket, so a forward-only publish here always won — discarding a concurrent
@@ -68,11 +76,28 @@
  * A live read still fetching from the collected generation heals forward to the rewrite, and a pin of it fails with
  * `NotFoundError` for any chunk it has yet to read: that is the documented cost of physical deletion on return. **Do not re-load the id while erasing it**: a load that lands after this rewrite
  * carries whatever its source held, and the library cannot know that source was meant to exclude the id.
- * A load already in flight writes its object above the pointer before it publishes. An erasure that finds the id in that
- * object writes the row before deleting it, so the load's publish, fenced on the row it read, is refused
- * (`published: false`) and the pointer never names a missing object (see `fenceInFlight`). On a row with no pointer
- * the erasure writes nothing to the row, so a first load's object there may still be published; an erasure that finds
- * the id in it refuses instead of deleting it.
+ * A load already in flight writes its object above the pointer before it publishes, or, as a first load onto a row with
+ * no pointer, before there is a pointer at all. An erasure that finds the id in that object renews the row's `pointerId`
+ * before deleting it, so the load's publish, fenced on the row it read, is refused (`published: false`) and the pointer
+ * never names a missing object (see `fence`). An erasure that finds no holder writes nothing.
+ *
+ * Before it deletes anything, a call that found a holder takes every generation it will delete out of the row's ledger
+ * of known generations, in one write made after its search (the same write as the renewal where there is one). A
+ * generation the ledger names is one a collection by a count spares, so the delete comes after the name goes: a
+ * rollback that raced the write loses its swap, and a collection that reads the row before a delete spares what the row
+ * names. That write is made only when the ledger names something to delete, and it is the
+ * one case in which an erasure of an id held only by an older generation writes the row.
+ *
+ * An object sealed under a key its row does not hold cannot be searched, and no read of the segment can open it: a
+ * first load's on a row with no pointer, whose key that load has not published; on a segment with a key, a first
+ * load's that lost the race to the one that published, or crashed, under a key it made and never stored; and on a
+ * cleartext segment with a pointer, any encrypted object, since a key is made only for a segment's first generation
+ * and a publish never adds one to a segment that has generations: a first load's that minted a key and crashed, or
+ * lost the race to a cleartext first load. It counts as
+ * a holder whatever the id: an erasure of any id that finds one deletes it, under the same renewal of the row and read
+ * before the delete, and lists it in `collected`, and a first load still in flight that wrote it is refused. Only a
+ * searched object that held the id makes the answer `erased: true`. The current generation is never one of them: one
+ * the row's key does not open throws, as every read of the segment does.
  */
 import { type IAuditSink } from './audit.js';
 import type { CodecInterface } from './codec.js';
@@ -81,6 +106,20 @@ import type { Rng } from './determinism.js';
 import type { IKeystore } from './crypto.js';
 import type { IStorageDriver, IRegistryDriver, SegmentRef } from './ports.js';
 import { type ReadRetry } from './retry.js';
+/**
+ * Renewals a refused rewrite's discard makes before it keeps its object: the first, and one more each time a write that
+ * is neither a write of leases alone nor another erasure's renewal of the row lands between its read of the row and its
+ * renewal. Those two are waited out, up to the limit on lease waits (`LEASE_ONLY_RETRIES`), and cost none, so the
+ * losers of one race of erasures all delete their rewrites; a write that gets no answer is sent again within the same
+ * renewal.
+ */
+export declare const DISCARD_ATTEMPTS = 8;
+/**
+ * Writes a call's fence makes before it gives up on a row that keeps changing under it: each one lost to another writer
+ * (a load, a rollback, another erasure) that is not a write of the row's leases alone costs one. The call then reports
+ * `'superseded'` with nothing deleted.
+ */
+export declare const FENCE_ATTEMPTS = 5;
 /** What {@link eraseIdFromSegment} needs: the objects, the pointer, the codec, and the key material if encrypted. */
 export interface EraseIdDeps {
     readonly storage: IStorageDriver;
@@ -98,11 +137,15 @@ export interface EraseIdDeps {
     readonly keystore?: IKeystore;
     /** When true, refuse to rewrite a **cleartext** segment (the same guard the read path and a load offer). */
     readonly requireEncryption?: boolean;
-    /** Supplying a clock that can yield makes the rewrite cooperative, as it makes a load. */
+    /**
+     * Supplying a clock that can yield makes the rewrite cooperative, as it makes a load. Its `sleep` is what a registry
+     * write that got no answer waits on before a fresh one is sent; with no `sleep`, such a write is not sent again and
+     * its `TransientError` is thrown.
+     */
     readonly clock?: Yielder;
     /**
-     * The random source that spreads the waits between the rewrite's fresh compare-and-swaps. Absent, the read retry's
-     * source is used if it has one, and otherwise each wait is its bound.
+     * The random source that spreads the waits between the fresh compare-and-swaps of the rewrite and of the row's
+     * renewal. Absent, the read retry's source is used if it has one, and otherwise each wait is its bound.
      */
     readonly rng?: Rng;
     /** Per-chunk decode ceiling (invariant 5); defaults to 1 MiB. The `.crbm` reader refuses an entry above its own `maxPayloadBytes` (1 MiB, plus 28 bytes when encrypted) at open, so raise that on the chunk source too. */
@@ -111,7 +154,7 @@ export interface EraseIdDeps {
      * The store's read retry, for the reads the rewrite makes along the way: the generation it rewrites and each of its
      * chunks, the read-back that verifies the generation it wrote, and any other generation it checks for the id. A
      * transient fault on one is run again under it rather than failing the erasure. Absent, each read is made once.
-     * The deletes are not retried, and the rewrite's registry write is settled as a load's is.
+     * The deletes are not retried, and the rewrite's registry write and the row's renewal are settled as a load's is.
      */
     readonly readRetry?: ReadRetry;
 }
@@ -127,13 +170,20 @@ export interface EraseIdResult {
     readonly erased: boolean;
     /**
      * Why the id was not erased, when `erased` is false. `'absent'` (no registry row), `'destroyed'` (a crypto-shred
-     * tombstone — already unreadable), `'no-generation'` (a row with no Storage data yet), `'not-member'` (no
-     * generation in the bucket holds the id — the common case across a fleet scan), or `'superseded'`.
+     * tombstone — already unreadable), `'no-generation'` (a row with no generation yet: its bucket can hold first loads'
+     * objects, none of them found to hold the id, and `collected` names any this call deleted unsearched, see below),
+     * `'not-member'` (no
+     * generation in the bucket holds the id — the common case across a fleet scan — with the same note on `collected`),
+     * or `'superseded'`.
      *
      * **`'superseded'` means this call did not erase the id, not that the id is still there.** Another writer — a
-     * load, another erasure, or a rollback — moved the pointer off the generation this call read, so what it was
-     * doing no longer follows from what is current: a rewrite derived from that generation is not a valid successor
-     * to the new one, and a generation it meant to delete above the pointer may be the one the pointer now names.
+     * load, another erasure, or a rollback — moved the pointer off the generation this call read (on a row with no
+     * pointer, any other write of the row before this call renewed it, a `setRetention` included), or replaced an
+     * object it meant to delete (another erasure deleted a holder above the pointer, or on a row with no pointer, and a
+     * load stored another object under its number, so the storage driver's conditional delete refused this call's,
+     * whether or not the pointer moved). What it was doing no longer follows from what is current: a rewrite derived
+     * from that generation is not a valid successor to the new one, and a generation it meant to delete may be the one
+     * the pointer now names, or another object than the one it read.
      * Re-run against the new generation: if the id is still present it is erased then; if the racing writer was
      * another erasure of the *same* id, the re-run reports `'not-member'` because it is already gone. Either way the
      * re-run settles it, which is why it is the documented action for this reason and for no other.
@@ -151,14 +201,20 @@ export interface EraseIdResult {
     readonly fromGeneration?: number;
     /**
      * The generation written without the id (present whenever one was written, even if `superseded`). A refused
-     * rewrite whose object sits above the winner's pointer deletes that object again before it returns.
+     * rewrite whose object sits above the winner's pointer deletes that object again before it returns, when its footer
+     * matches the rewrite's and a renewal of the row refuses every publish fenced on a row read before it.
      */
     readonly generation?: number;
     /**
      * Generations this call deleted. On a rewrite that is normally `[fromGeneration]`, plus any older orphans. When
-     * the current generation did not hold the id, it is every generation below the pointer (`keep: 0` takes them
-     * together) and each one above the pointer that held the id; the ones above it that did not hold the id stay,
-     * because they are an operator's rollback targets. Empty when nothing was deleted.
+     * the current generation did not hold the id and a generation this call searched did, it is every generation below
+     * the pointer (`keep: 0` takes them together) and each one above the pointer that held the id; the ones above it
+     * that did not hold the id stay, because they are an operator's rollback targets. On a row with no pointer it is
+     * each first load's object that held the id. Wherever it found them, it is also each object sealed under a key the
+     * row does not hold, which this call cannot search and deletes whatever the id. When those are the only holders, it
+     * is only those, deleted one by one, and every generation this call searched stays: `reason` is then
+     * `'no-generation'` on a row with no pointer and `'not-member'` on one with a pointer. Empty when nothing was
+     * deleted.
      *
      * **It is what THIS call deleted, not the proof that the id is gone** — those differ: a concurrent collector can
      * take a generation holding the id first, and then `erased: true` is returned without it in `collected`, because
@@ -170,7 +226,18 @@ export interface EraseIdResult {
      * collection pass that could not prove the segment was still the same one (which an ordinary retirement landing
      * mid-call is enough to cause); the same refusal on the path where the current generation did not hold the id
      * and nothing was published at all; and a generation still holding the id when the bucket is listed at the end
-     * — one an operator rolled the pointer onto while a rewrite was collecting, say.
+     * — one an operator rolled the pointer onto while a rewrite was collecting, say, or, on a row with no pointer, the
+     * object of a first load that read the row before this call renewed it and wrote it after this call listed the
+     * bucket. The row write an erasure makes before deleting a holder a load may still publish, or before a refused
+     * rewrite discards its own object, when it gets no answer that reading the row can settle, throws the registry's
+     * `TransientError`, and that object is not deleted.
+     *
+     * A rollback that lands between the call's read of the row and one of its deletes, onto the generation being deleted,
+     * leaves the pointer on an object that is gone. The call finds it at its next read of the row, or by reading the row
+     * once more after its last delete, and **throws `NotFoundError`** rather than report anything: every read of the
+     * segment fails until a rollback moves the pointer to a generation still in the bucket, and nothing restores the
+     * deleted object. When nothing left in the bucket holds the id, the call has emitted its `segment.collect` event
+     * first, so the deletion is on the record. Re-run it after that rollback.
      *
      * **Re-run it**, and read what the re-run says rather than assuming it finished the job. The re-run looks for
      * the id in every generation in the bucket, not only the current one, and there are three outcomes:
@@ -192,7 +259,10 @@ export interface EraseIdResult {
  * it. See the module note for the contract.
  *
  * Emits one `segment.rewrite` audit event at the publish (before the superseded generation is collected), so the
- * compliance record exists the moment the generation without the id is authoritative.
+ * compliance record exists the moment the generation without the id is authoritative. An erasure that rewrites nothing,
+ * because only other generations held the id, emits one `segment.collect` once no generation holds it, and so does one
+ * that deleted only objects no read of the segment can open, which names no generation the id was found in. Either
+ * event comes before the `NotFoundError` of a rollback that moved the pointer onto a generation the call deleted.
  */
 export declare function eraseIdFromSegment(ref: SegmentRef, id: number, deps: EraseIdDeps, options?: {
     audit?: IAuditSink;

package/dist/core/erasure.d.ts

@@ -13,7 +13,7 @@
  * operation — `eraseIdFromSegment` rewrites the generation without it.
  */
 import { type IAuditSink } from './audit.js';
-import { type ChurnDeps } from './leases.js';
+import type { ChurnDeps } from './leases.js';
 import type { IStorageDriver, IRegistryDriver, RegistryRecord, SegmentRef } from './ports.js';
 export interface EraseDeps extends ChurnDeps {
     readonly registry: IRegistryDriver;
@@ -60,7 +60,7 @@ export declare function destroySegment(ref: SegmentRef, deps: EraseDeps, options
  * listing is capped at `maxScanSegments` (default {@link DEFAULT_MAX_SCAN_SEGMENTS}, 250,000), the ceiling every
  * other fleet scan keeps. A namespace over it throws `BudgetExceededError` **before any segment is destroyed**,
  * never part-way through; raise `maxScanSegments` when the namespace really is that large and the memory is there.
- * A `maxScanSegments` that is not a finite number >= 1 throws `ValidationError`, again before anything is destroyed.
+ * A `maxScanSegments` that is not a safe whole number of at least 1 throws `ValidationError`, again before anything is destroyed.
  */
 export declare function eraseNamespace(namespace: string, deps: EraseDeps, options: {
     confirmNamespace: string;
@@ -195,7 +195,7 @@ export declare function dropSegment(ref: SegmentRef, deps: DropDeps, options: {
  * in the shred's own write, so only a tombstone a sweep wrote ever carries a sweep's mark, which is what lets a later
  * sweep purge it and never a crypto-shred's.
  */
-export interface SweepDrop {
+interface SweepDrop {
     readonly wanted: (row: RegistryRecord) => boolean;
     readonly stamp: (retention: RegistryRecord['retention']) => RegistryRecord['retention'];
 }
@@ -208,3 +208,4 @@ export declare function dropSegmentFor(ref: SegmentRef, deps: DropDeps, options:
     dryRun?: boolean;
     audit?: IAuditSink;
 }, sweep: SweepDrop | undefined): Promise<DropResult | null>;
+export {};

package/dist/core/errors.d.ts

@@ -26,7 +26,11 @@ export declare class CloudRoaringError extends Error {
     readonly [ERROR_BRAND]: true;
     constructor(message: string);
 }
-/** Invalid caller input (bad id, segment name, options). Raised before any storage call. */
+/**
+ * Invalid input, which the same call fails on again. Most is refused before any storage call (a bad id, segment name
+ * or option); some is found by the call itself: a read past the end of an object, or a bucket or container a cloud
+ * driver finds does not exist.
+ */
 export declare class ValidationError extends CloudRoaringError {
 }
 /** An OCC conditional write/delete lost the race — the row changed since it was read. */
@@ -148,7 +152,9 @@ export declare function isLeaseLimitError(err: unknown): err is LeaseLimitError;
 export declare function isNotFoundError(err: unknown): err is NotFoundError;
 /** Corrupt/oversized/failed-checksum bytes from a tier. */
 export declare function isIntegrityError(err: unknown): err is IntegrityError;
-/** Invalid caller input. */
+/**
+ * Invalid caller input; also the error a cloud driver raises for a bucket or container it finds does not exist.
+ */
 export declare function isValidationError(err: unknown): err is ValidationError;
 /** This build or this store's wiring cannot do what was asked, though nothing is malformed. */
 export declare function isUnsupportedError(err: unknown): err is UnsupportedError;

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

@@ -1,9 +1,84 @@
-import type { GenKey, IStorageDriver, IRegistryDriver, RegistryRecord, SegmentRef, Token } from './ports.js';
+import { NotFoundError } from './errors.js';
+import type { GenKey, IStorageDriver, IRegistryDriver, KnownGeneration, 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 {
+interface GenerationDeps {
     readonly storage: IStorageDriver;
     readonly registry: IRegistryDriver;
+    /** What a delete loop waits on before it reads the row again ({@link watchDeletes}). Absent, it does not wait. */
+    readonly clock?: {
+        readonly sleep?: (ms: number) => Promise<void>;
+    };
 }
+/**
+ * The waits, in milliseconds, before each further read of the row when a delete loop finds the pointer on a generation
+ * it deleted, with no object under it ({@link watchDeletes}). A rollback that moved the pointer there checks the bucket
+ * after its move, and when the check runs after the delete it finds the object gone and puts the pointer back: one
+ * listing of the segment's objects (one page while the segment holds under a thousand) and one compare-and-swap, two
+ * round trips, three when a lease write lands first. A rollback client farther from the store than the deleting
+ * client takes that much longer, so the loop reads the row once at once and, with a clock that can wait, three more
+ * times over 1.75 s in all, which covers clients a few hundred milliseconds away. Paid only when a read finds the
+ * pointer on a missing generation the loop deleted, never on a pass where nothing raced.
+ */
+export declare const DELETE_SETTLE_WAITS_MS: readonly number[];
+/** What a delete loop has deleted, held to every read of the segment's row it makes after a delete. */
+interface DeleteWatch {
+    /** Note a delete that landed. */
+    deleted(generation: number): void;
+    /** Every generation noted so far. */
+    readonly gone: ReadonlySet<number>;
+    /**
+     * `row`, a read of the row made after `held`, the row a delete was decided on, held to what was deleted: the deleted
+     * generation it leaves the pointer on, with no object under it once the row is read again, or `undefined`.
+     */
+    check(held: RegistryRecord, row: RegistryRecord | null): Promise<number | undefined>;
+    /** The same for one more read of the row, made only when a delete landed since the last {@link check}. */
+    settle(held: RegistryRecord): Promise<number | undefined>;
+}
+/**
+ * Hold a delete loop's reads of the row to what it deleted.
+ *
+ * Every loop that deletes generations reads the row before each delete, and one round trip remains between that read
+ * and the delete. A rollback that lands inside it onto the generation being deleted passes its own check (a listing made
+ * before the delete) and leaves the pointer on an object that is gone. Nothing can put the object back, so the loop
+ * detects it instead: every read of the row it makes after a delete, and one more after its last delete when it made no
+ * read since, is held to what it deleted.
+ *
+ * A read names a deleted generation when its row is active, of the incarnation `held` was read from, and its pointer
+ * names one. A tombstone never does, since no rollback moves a `destroyed` row's pointer, and neither does a row purged
+ * and made again, whose numbers are its own. Then:
+ *
+ *  - The bucket is asked, with one zero-byte read, a metadata request on every shipped driver. A number can be taken
+ *    again once its object is deleted (invariant 2): after a rollback below it, a load can number it afresh and
+ *    publish, and then the object there is that load's, and nothing is missing. Where the storage driver ignores a
+ *    delete's condition, the loop's own delete can take that object too, and the read finds it missing, which it is.
+ *  - A missing object is not yet the answer. A rollback whose own check ran after the delete finds the object gone and
+ *    puts the pointer back, and the loop's read can fall between its move and that undo. So the row is read again, at
+ *    once and, with a clock that can wait, after each of {@link DELETE_SETTLE_WAITS_MS}, each read judged as the first
+ *    was, the bucket asked again; the answer is the generation the last of them names, only if every one names a
+ *    deleted generation with no object under it.
+ *
+ * A read of the bucket that fails in any other way than "not found" throws: it says nothing about the object.
+ */
+export declare function watchDeletes(deps: GenerationDeps, ref: SegmentRef): DeleteWatch;
+/** Who deleted the generation a {@link pointerOnDeletedError} names, which leads its message. */
+type Deleter = {
+    readonly kind: 'collection';
+} | {
+    readonly kind: 'erasure';
+} | {
+    readonly kind: 'load';
+    readonly published: number;
+} | {
+    readonly kind: 'refused-load';
+    readonly refusal: string;
+};
+/**
+ * The error for a pointer a delete loop found on a generation it deleted ({@link watchDeletes}). The writer that moved
+ * the pointer there is a rollback, or, where the storage driver ignores a delete's condition, a load that took the
+ * number again and published. A rollback slower than the loop's further reads can still put the pointer back after
+ * them, so the message says to look before acting.
+ */
+export declare function pointerOnDeletedError(ref: SegmentRef, deleter: Deleter, generation: number): NotFoundError;
 /**
  * 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 erasure rewrite numbers this
@@ -20,7 +95,7 @@ export interface GenerationDeps {
  */
 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 {
+interface LoadNumber {
     readonly generation: number;
     /**
      * `true` when the number is `currentGen + 1` and the check found no object holding it. Collection by name rests
@@ -28,6 +103,8 @@ export interface LoadNumber {
      * the listing would have kept is a name the pass takes. `false` when the listing numbered the load.
      */
     readonly checked: boolean;
+    /** The generations that listing found, when the load listed: a seed of the ledger reads them instead of listing again. */
+    readonly listed?: readonly number[];
 }
 /**
  * The generation number a load takes, from the row it has already read: `currentGen + 1` (0 with no row or no
@@ -46,7 +123,8 @@ export interface LoadNumber {
  * 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 and the chunk cache key on the number and
- * the row's token, checked against the object a reader opens, and a pin on its object's fingerprint.
+ * the row's `pointerId`, which every write that takes a number again renews, and an open of a row with a usable
+ * summary holds the object to the fingerprint the summary records; a pin keys on its object's fingerprint.
  */
 export declare function nextLoadGeneration(ref: SegmentRef, deps: GenerationDeps, row: RegistryRecord | null): Promise<LoadNumber>;
 /**
@@ -72,6 +150,11 @@ export declare const LIST_COLLECTION_CADENCE = 16;
  * a pin taken while it was still active re-checks the status on every open — and nothing else in the library
  * would ever collect them, so without this those objects are billed forever.
  *
+ * **Throws {@link NotFoundError} when a rollback moved the pointer onto a generation it deleted**: the rollback landed
+ * between the pass's re-proof of the row and that delete, so the pointer names an object that is gone. The pass finds
+ * it at its next re-proof, or, after its last delete, by reading the row once more. A deleted object cannot be
+ * restored: the answer is a rollback to a generation still in the bucket.
+ *
  * **Throws {@link WriteConflictError} when it cannot act on the row it read**: the row is gone when it is re-read,
  * after the listing or before a delete; on an active segment, the pointer has fallen below the cutoff before a
  * delete; on a `destroyed` segment, the row's token has changed. Not to be confused with the empty array it still
@@ -96,33 +179,52 @@ export declare const LIST_COLLECTION_CADENCE = 16;
 export declare function gcOrphanGenerations(ref: SegmentRef, deps: GenerationDeps, options?: {
     keep?: number;
 }): Promise<number[]>;
+/**
+ * {@link gcOrphanGenerations}, reporting a rollback onto a generation it deleted in `missing` instead of throwing it: the
+ * pass stopped there. For a caller that records what it deleted before it raises, as an erasure does. With `skipKnown` the
+ * pass also spares every generation the row names when it reads the row before a delete (an erasure's passes on an active
+ * row, which remove from the row what they mean to delete first).
+ */
+export declare function collectBelowPointer(ref: SegmentRef, deps: GenerationDeps, options?: {
+    keep?: number;
+    skipKnown?: boolean;
+}): Promise<{
+    readonly deleted: number[];
+    readonly missing?: number;
+    readonly knownSpared?: number[];
+}>;
 /**
  * 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 {
+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). */
+    /** The window the publish recorded, as numbers, or `undefined` when it recorded none (the row then does not know which are kept). */
     readonly list: readonly number[] | undefined;
+    /** The ledger the publish wrote, in the order the generations were made current, when it wrote one. */
+    readonly known?: readonly KnownGeneration[];
     /** 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
+ * Collect after a load's publish. The row's ledger 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 publish recorded no window to collect by name (a `keep` above {@link MAX_KEPT_GENERATIONS}, a publish that
+ *    seeded its ledger from the bucket, a row with no usable ledger, or a publish whose write was settled by reading the
+ *    row): the pass keeps `keep` of the generations present below the pointer, the ledger's own most recently current
+ *    names first and then the newest others by number, or, over a row with no usable ledger, `previous` first and then
+ *    the newest by number ({@link keptWindow}), and writes nothing: the publish already wrote the ledger, which is what
+ *    the next load derives its window from. It spares every name the row knows when it re-reads the row before a
+ *    delete, which a publish or a rollback that landed since can have added to;
  *  - 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;
@@ -134,10 +236,13 @@ export interface PublishedKept {
  * 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.
+ * Any fault of the collection is raised, as every fault of a collection after a landed publish is.
+ *
+ * So is a rollback onto a generation the pass deleted, which the pass finds by holding every read of the row it makes
+ * after a delete to what it deleted, and by reading the row once more after its last delete
+ * ({@link watchDeletes}): it throws {@link NotFoundError}, saying the load took effect at `generation` and the
+ * generation the pointer names is missing. That read is the one request this adds to a load whose pass deleted
+ * anything.
  */
 export declare function collectAfterLoad(ref: SegmentRef, deps: GenerationDeps, options: {
     generation: number;
@@ -155,6 +260,11 @@ export declare function collectAfterLoad(ref: SegmentRef, deps: GenerationDeps,
     proveCurrent?: GenKey;
     /** Spare the generations the row's live leases hold. Absent, the pass ignores leases. */
     leases?: LeaseGuard;
+    /**
+     * The generation the row named as current when the load read it, which its publish superseded. A window kept by
+     * listing holds it first, while the pointer is still the load's. Absent: the load found no pointer.
+     */
+    previous?: number;
 }): Promise<number[]>;
 /**
  * Delete, with no listing, the generations a publish of `generation` pushed out of its row's window, `evict`, taken
@@ -170,9 +280,14 @@ export declare function collectAfterLoad(ref: SegmentRef, deps: GenerationDeps,
  * 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`.
+ *
+ * A rollback onto a name it deleted is not a stop: every read of the row after a delete is held to what it deleted, and
+ * so is one more read after its last delete when it made none since ({@link watchDeletes}). One that names a
+ * deleted generation throws {@link NotFoundError}, saying the load took effect at `generation`.
  */
 export declare function deleteEvicted(ref: SegmentRef, deps: GenerationDeps, options: {
     generation: number;
     evict: readonly number[];
     leases?: LeaseGuard;
 }): Promise<number[]>;
+export {};

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

@@ -0,0 +1,11 @@
+/**
+ * The generations a segment's bucket holds.
+ */
+import type { IStorageDriver, SegmentRef } from './ports.js';
+/**
+ * The generations the bucket holds for `ref`, from one listing, each once and in ascending order. A listing that spans
+ * a purge and a re-create can yield one number twice (the objects are re-created under the numbers just swept), so the
+ * duplicates are dropped here rather than counted by each caller. A caller that stops at the first object it wants
+ * reads the listing itself.
+ */
+export declare function generationsOf(storage: IStorageDriver, ref: SegmentRef): Promise<number[]>;

package/dist/core/id-window.d.ts

@@ -0,0 +1,46 @@
+import type { CodecBitmap, CodecInterface } from './codec.js';
+/** A validated range: inclusive id bounds, as the chunk key and the remainder at each end. */
+export interface IdWindow {
+    readonly loKey: number;
+    readonly loRem: number;
+    readonly hiKey: number;
+    readonly hiRem: number;
+}
+/** A range as a read is asked for it: each bound optional. */
+interface IdBounds {
+    readonly after?: number | undefined;
+    readonly through?: number | undefined;
+}
+/**
+ * Throws {@link ValidationError} unless `bound` is left out or is an id: an integer from 0 to 4294967295. The message
+ * says what is wrong and never carries the value, which is an id.
+ */
+export declare function assertIdBound(name: 'after' | 'through', bound: number | undefined): void;
+/**
+ * Validate a read's range. `null` when none was asked for, so the read does no extra work; `'empty'` when no id can be
+ * in it (`after >= through`, which is a cursor at the end of its window, not an error).
+ */
+export declare function windowOf(range: IdBounds | undefined): IdWindow | 'empty' | null;
+/** The window a range with neither bound set describes: every id. */
+export declare const WHOLE_ID_SPACE: IdWindow;
+/**
+ * Whether the window cuts inside `chunkKey`: one of its two edge chunks, and only where the bound falls inside the chunk
+ * rather than on its boundary. A chunk the window covers whole is read as it is.
+ */
+export declare const isEdge: (chunkKey: number, w: IdWindow) => boolean;
+/** The ids of an edge chunk that lie inside the window. The chunk iterates ascending, so it stops at the top. */
+export declare function edgeIds(chunk: CodecBitmap, chunkKey: number, w: IdWindow): Generator<number>;
+/** The ascending `keys` inside the window's chunk span, as a new array: two binary searches, no scan. */
+export declare function keysWithin(keys: readonly number[], w: IdWindow): number[];
+/**
+ * The ascending `keys` inside the window's chunk span (every key, for `null`) and above the key `after`: what a read
+ * that plans again after taking `after` still reads.
+ */
+export declare function keysAbove(keys: readonly number[], w: IdWindow | null, after: number): number[];
+/** The index of the first element of ascending `a` greater than `value`: a binary search. */
+export declare function firstAbove(a: Uint32Array, value: number): number;
+/** The part of an edge chunk's ascending remainders `rem` inside the window, as a view of `rem`. */
+export declare function remaindersWithin(rem: Uint32Array, chunkKey: number, w: IdWindow): Uint32Array;
+/** An edge chunk cut to the window, as a new bitmap: the remainders {@link edgeIds} would yield. */
+export declare function cutToWindow(codec: CodecInterface, chunk: CodecBitmap, chunkKey: number, w: IdWindow): CodecBitmap;
+export {};