@cloudbitmaps/core 0.20.0 → 0.21.0

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
@@ -73,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
@@ -97,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;
@@ -135,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;
@@ -156,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
@@ -171,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 {};

package/dist/core/invalidation-scope.d.ts

@@ -0,0 +1,77 @@
+/**
+ * What the engines reading through one chunk cache share about invalidations: how many there have been, the segment
+ * each of the latest was of, and the chunk reads open right now. A store's own engine, each pin's and each combine's
+ * with a pinned operand read through one cache, and an invalidation through any of them must reach a read running on
+ * another: a read that had its bytes before the invalidation would otherwise write them back into the cache it
+ * shares, and later reads would be answered from them, an erased id included, until the cache evicted them.
+ *
+ * ```
+ *  engine (store) ──┐
+ *  engine (pin)   ──┼── one InvalidationScope ── epoch · latest invalidation of each segment · open reads
+ *  engine (combine)─┘        └── one chunk cache
+ * ```
+ *
+ * A stream records the epoch it opened at and asks {@link InvalidationRecord.invalidatedSince} before it caches a
+ * chunk, so the scope holds no reference to a stream: a read its caller drops without closing holds nothing here. The
+ * `.crbm` source keeps an {@link InvalidationRecord} of its own, by segment, which a pinned stream asks before it hands
+ * out a chunk, so only its own segment's invalidation makes it open its object again.
+ *
+ * Internal to core: not exported from any entry point.
+ */
+import type { CodecBitmap } from './codec.js';
+/**
+ * How many segments' latest invalidation a record remembers. Past it the oldest is forgotten, and a segment the record
+ * does not remember, never-invalidated ones included, counts as invalidated at the newest invalidation it has
+ * forgotten, which is always on the safe side. In the engines' scope it means a stream that opened before then caches
+ * no more of that segment's chunks, which costs it cache entries, never correctness: so a sweep that invalidates more
+ * than this many segments at once (a `retireExpired` or an `eraseSubject` over a large fleet) stops every stream open
+ * at the time caching, whatever segment it reads. In the `.crbm` source it means a pinned stream looks its pin up
+ * again, which costs a request only where the reader cache has let the pin's reader go. With names at their
+ * 256-character limit a record is about 0.6 MB, and about 0.1 MB with 30-character names; a store keeps two.
+ */
+export declare const REMEMBERED_INVALIDATIONS = 1024;
+/** A chunk read in flight: `token` tells the read whether its entry is still the registered one. */
+export interface OpenRead {
+    readonly token: object;
+    readonly read: Promise<CodecBitmap | null>;
+}
+/**
+ * How many invalidations there have been, and the epoch of each of the latest {@link REMEMBERED_INVALIDATIONS}
+ * segments' latest one, by whatever key names a segment to its owner: a cache-key prefix in the engines' scope, a
+ * segment key in the `.crbm` source.
+ */
+export declare class InvalidationRecord {
+    private count;
+    /** The epoch of each remembered segment's latest invalidation, the oldest first. */
+    private readonly latest;
+    /** The epoch of the newest invalidation the record has forgotten: what a segment it does not remember counts as. */
+    private floor;
+    /** How many invalidations there have been: a read compares it with the epoch it began under. */
+    get epoch(): number;
+    /** Record an invalidation of the segment `key` names. */
+    invalidate(key: string): void;
+    /** Whether the segment `key` names has been invalidated since epoch `since`. */
+    invalidatedSince(key: string, since: number): boolean;
+}
+/** The engines' record, by cache-key prefix, and the chunk reads open on all of them. */
+export declare class InvalidationScope extends InvalidationRecord {
+    /**
+     * The chunk reads open right now, by cache key: a caller that misses the cache and finds its key here awaits that
+     * read instead of making its own. An entry lives from the request until it settles, so the map holds at most one
+     * promise per distinct key in flight. An invalidation drops the segment's entries, and a read whose entry is gone
+     * caches nothing.
+     */
+    private readonly openReads;
+    /** Record an invalidation of the segment whose cache keys start with `prefix`, and drop its open reads. */
+    invalidate(prefix: string): void;
+    /** The read of `key` open now, for a caller that misses the cache to await instead of making its own. */
+    openRead(key: string): Promise<CodecBitmap | null> | undefined;
+    /** Whether a read of `key` is open, without joining it. */
+    hasOpenRead(key: string): boolean;
+    /** Register `entry` as the open read of `key`. */
+    beginRead(key: string, entry: OpenRead): void;
+    /** `entry` has settled: forget it, unless an invalidation dropped it and a newer read has taken the key. */
+    endRead(key: string, entry: OpenRead): void;
+    /** Whether the read `token` names is still the open read of `key`: one an invalidation dropped caches nothing. */
+    isOpen(key: string, token: object): boolean;
+}

package/dist/core/known-generations-shape.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The shape of a row's known-generations ledger (`knownGens`), in one place. A registry holds a row to it when it writes
+ * and when it reads back, and `checkConsistency` holds a row to it before it reads or walks a ledger a registry of your
+ * own handed back, so the two cannot part on what a ledger is. Pure: no I/O, time or randomness.
+ */
+/**
+ * Why `value` is not a ledger, or `undefined` when it is one (an absent ledger, `undefined`, passes: whether a row
+ * without one is usable is another rule). A ledger is an array of at most `max` entries, each exactly `{ generation,
+ * footerCrc }`, the generation a non-negative safe integer and unique, the checksum an integer from 0 to 2^32 - 1. The
+ * order is not checked: it is not derivable from the numbers. `show` renders a value for the description, which a
+ * caller can truncate.
+ */
+export declare function knownGensShapeFault(value: unknown, max: number, show?: (v: unknown) => string): string | undefined;

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

@@ -0,0 +1,147 @@
+import type { KnownGeneration, RegistryRecord } from './ports.js';
+/**
+ * The most generations a load that collects by name records as its window. A `keep` above it collects by listing.
+ */
+export declare const MAX_KEPT_GENERATIONS = 64;
+/**
+ * A writer keeps entries that nothing protects and no lease holds only while the ledger holds fewer than this many.
+ */
+export declare const KNOWN_FILL = 128;
+/** The most entries a writer writes, and the most the shared validator accepts at a write. */
+export declare const MAX_KNOWN_GENERATIONS = 192;
+/** The most entries a stored row may hold: twice what a writer writes. */
+export declare const MAX_STORED_KNOWN_GENERATIONS = 384;
+/**
+ * The row's ledger when a collection or a rollback may rely on it: present and not empty, on an active row with a
+ * pointer, its last entry the pointer, and, where the row's summary is in the clear and describes that generation, its
+ * checksum the one the summary's fingerprint carries. A well-formed ledger that disagrees with its row is read but not
+ * used (the row counts as one with no ledger), as a summary that names another generation is.
+ */
+export declare function usableKnownGens(record: RegistryRecord | null): readonly KnownGeneration[] | undefined;
+/**
+ * The generations the row keeps as its window: the numbers of the usable ledger's entries below the pointer, in the order
+ * they were made current, or `undefined` when the ledger is not usable. A collection compares against these. An entry
+ * numbered above the pointer is one a rollback left; no collection can take it, so it is no part of the window.
+ */
+export declare function windowOf(record: RegistryRecord | null): readonly number[] | undefined;
+/**
+ * Whether the row's ledger is a window a load with a small `keep` can extend: usable, and naming no more than
+ * {@link MAX_KEPT_GENERATIONS} generations below the pointer that no live lease holds. A ledger carried through
+ * publishes with a larger `keep` (`*Into`, `materializeMany`) names up to 127, and a count by a small `keep` would keep
+ * fewer than it names, so the next small-`keep` load collects by listing instead of by name, over the same ledger. A
+ * generation held only for a lease is no part of the window and does not count toward the limit.
+ */
+export declare function carriesWindow(record: RegistryRecord | null, leased: ReadonlySet<number>): boolean;
+/**
+ * How many generations below its own a publish vouches for at most: what the writer cap leaves beside the new
+ * generation and the 64 generations live leases can hold.
+ */
+export declare const KNOWN_SPAN = 127;
+/** Which generations below a new pointer a grace window holds, and which it lets go: both ascending. */
+interface KeptWindow {
+    readonly kept: number[];
+    readonly evict: number[];
+}
+/**
+ * The generations below a new pointer that a grace window of `keep` holds, out of `below`, when no ledger says which
+ * were made current most recently: the generation the publish superseded first, when it is among them, then the newest
+ * of the rest by number. When it is not among them (no generation was current, or its object has gone from the bucket),
+ * the newest `keep`.
+ *
+ * The superseded generation is the one reads were on until the publish, and, after a rollback, the one the operator
+ * restored, which a pin taken since reads, and the one to roll back to if the new load is bad too. The generations a
+ * rollback moved away from are newer by number, so a window by number alone would keep those and delete it. The window
+ * a listing keeps over a row with no usable ledger comes from here, and so does a ledger's first window
+ * (`ledger-seed.ts`); once the row has a ledger, its order says which were made current most recently.
+ */
+export declare function keptWindow(below: readonly number[], superseded: number | undefined, keep: number): KeptWindow;
+/**
+ * `known`, held to the cap, in the same order. It always keeps the entries numbered in `protect`, then the ones numbered
+ * in `leased`, most recently current first, up to {@link MAX_KNOWN_GENERATIONS}, then the rest, most recently current
+ * first, while the ledger holds fewer than {@link KNOWN_FILL}. So a protected or leased entry is never dropped for room,
+ * and an unprotected one only when the ledger is full. "Most recently current" is the end of the list.
+ */
+export declare function capKnown(known: readonly KnownGeneration[], protect: ReadonlySet<number>, leased?: ReadonlySet<number>): KnownGeneration[];
+/** `known` with `entry` made the most recent: any entry for its generation removed, and the entry added last. */
+export declare function makeCurrent(known: readonly KnownGeneration[], entry: KnownGeneration): KnownGeneration[];
+/** What a publish of a generation writes into the row, and which names it pushes out of the window. */
+export interface KnownAfter {
+    /** The ledger to write: the generation published is its last entry. */
+    readonly known: readonly KnownGeneration[];
+    /** The window as numbers to collect by name, or `undefined` to collect by listing. */
+    readonly list: readonly number[] | undefined;
+    /** The generations the window no longer keeps, ascending: the names to delete. */
+    readonly evict: readonly number[];
+}
+/**
+ * What a publish of `generation` (its object's footer checksum `footerCrc`) over `prev` writes into the row.
+ *
+ * The ledger is in the order the generations were made current, so the order says which were current most recently.
+ * That ranks the window, and the window is drawn from the entries numbered below the new generation only: collection
+ * can only take generations numbered below the pointer. The window is the `keep` most recently current of them (at most
+ * {@link KNOWN_SPAN}), so the generation the publish superseded, the ledger's last entry, comes first, and after a
+ * rollback the ones the operator restored outrank the ones the rollback moved away from.
+ *
+ * What it writes, in the order the entries were made current and the new generation last:
+ *
+ *  - the window;
+ *  - the entries below the new generation that `leased` names (a generation a live lease holds stays known, so it stays a
+ *    rollback target while the lease lives), whatever `keep` says;
+ *  - the entries numbered above the new generation, which a rollback left and a load numbered under: they are carried and
+ *    never evicted, and take no slot of `keep`, while the ledger holds fewer than {@link KNOWN_FILL} entries (see
+ *    {@link capKnown});
+ *  - the new generation. An entry already numbered `generation` is a stale one (its object went outside the ledger) and
+ *    is replaced.
+ *
+ * `evict` is the entries below the new generation that it leaves out, ascending: never a name at or above the new
+ * generation. With a `keep` of at most {@link MAX_KEPT_GENERATIONS} the publish collects by name, so `list` is the
+ * generations of the ledger below the new one; above that, or with no `keep`, `list` is `undefined` and `evict` empty, and
+ * a load lists. A row with a pointer and no usable ledger writes the new generation alone and lists, unless the caller
+ * passes a `seed` (see `ledger-seed.ts`): the window a count keeps, read from the bucket, then the new generation, and
+ * the publish collects by that count. A publish that clears leases is an erasure's rewrite, which deletes every older
+ * generation, so its ledger is the new generation alone.
+ */
+export declare function nextKnown(prev: RegistryRecord | null, generation: number, footerCrc: number, keep: number | undefined, options?: {
+    readonly clearsLeases?: boolean;
+    readonly seed?: readonly KnownGeneration[];
+    readonly leased?: ReadonlySet<number>;
+}): KnownAfter;
+/**
+ * The ledger a rollback onto `target` writes over `prev`: the ledger it found with the target moved to the end, as the
+ * most recently current. A rollback never starts a ledger: over a row with no usable ledger it writes none, and the
+ * next publish seeds one. A target the ledger did not name
+ * is an insert, and the ledger it makes is held to the cap with the target and the generation the rollback leaves
+ * protected; a known target's ledger is written as read, unless another build wrote one that is past the writer's cap.
+ */
+export declare function rollbackKnown(prev: RegistryRecord, target: KnownGeneration): readonly KnownGeneration[] | undefined;
+/**
+ * The row's ledger with the entries numbered in `doomed` removed, which a write that is about to delete those
+ * generations makes first: the entries left keep their order, and the current generation is never removed (the ledger
+ * must end with it). Another build's ledger past the writer's cap is held to it, with the current generation protected
+ * and the generations the row's leases name kept. `undefined` for a row with no usable ledger, which names nothing to
+ * remove.
+ */
+export declare function pruneKnown(record: RegistryRecord, doomed: ReadonlySet<number>): readonly KnownGeneration[] | undefined;
+/**
+ * The ledger that puts a row back as it was, for the undo of a rollback: the row's own when it is usable (the
+ * generation it left is its last entry), held to the writer's cap when another build wrote one past it, with the
+ * generation the undo leaves and the one it moves from protected; `undefined` for a row that had none to put back.
+ */
+export declare function describingKnown(record: RegistryRecord, movedTo: number): readonly KnownGeneration[] | undefined;
+/**
+ * Whether the ledger is full: it names at least {@link KNOWN_FILL} generations, which is when a writer may have let an
+ * older one go (a publish vouches for at most {@link KNOWN_SPAN} below its own, and an inserting rollback drops an entry
+ * once 128 that no lease holds are named). Leased entries do not switch it off: a lease on an entry inside the span
+ * leaves the ledger as full as it was. Past the least recently current entry of a full ledger, a rollback can no longer
+ * tell a generation the row forgot from one it never knew, so it judges a target numbered below that entry as it did
+ * before the ledger existed.
+ */
+export declare function isFullLedger(known: readonly KnownGeneration[]): boolean;
+/**
+ * The number a target below the pointer is judged against on a full ledger: the least recently current entry that no
+ * lease entry of the row names (live or ended: a rollback has no clock). A leased entry stays in the ledger for its lease,
+ * however far the window has moved on since, so it does not mark where the ledger stopped remembering; the first entry no
+ * lease holds does. A ledger whose every entry is leased is judged against its first entry.
+ */
+export declare function fallbackBound(record: RegistryRecord, known: readonly KnownGeneration[]): number;
+export {};

package/dist/core/leases.d.ts

@@ -18,8 +18,8 @@ export declare const MAX_STORED_LEASES = 256;
  */
 export declare const LEASE_CAS_ATTEMPTS: number;
 /**
- * Fresh writes sent after one that got no answer and left the row as it was, by the lease writers and by an erasure's
- * renewal of the row.
+ * Fresh writes sent after one that got no answer and left the row as it was, by the lease writers, by an erasure's
+ * renewal of the row and by a publish: four sends of the row write in all.
  */
 export declare const UNANSWERED_RESENDS = 3;
 /** The upper bound of the first of those waits, in ms; each next one doubles it. */
@@ -65,7 +65,7 @@ export declare const LEASE_ONLY_RETRIES: number;
  */
 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 {
+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
@@ -124,3 +124,4 @@ export declare function takeLease(ref: SegmentRef, deps: LeaseDeps, take: LeaseT
  * 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>;
+export {};

package/dist/core/ledger-seed.d.ts

@@ -0,0 +1,17 @@
+import { type ReadRetry } from './retry.js';
+import type { IStorageDriver, KnownGeneration, RegistryRecord, SegmentRef } from './ports.js';
+/**
+ * Whether a publish over `row` seeds its ledger: only at a birth, over an active row that has a pointer and no usable
+ * ledger. A usable ledger is never seeded again, however wide it is.
+ */
+export declare function wantsSeed(row: RegistryRecord | null): boolean;
+/**
+ * The entries a seed names: the listed generations below the new one that a live lease holds and the window does not
+ * keep, then the window oldest first by number with the generation the row named as current last. `listed` is the
+ * listing the load's numbering made, when it made one; otherwise the bucket is listed once. Every entry's checksum is
+ * read from its object's footer (a 104-byte read, under the store's read retry, {@link SEED_READS} at a time), the
+ * superseded generation's too: when a clear summary describes it with another checksum, the row and the bucket
+ * disagree about that number and it is left out. A generation gone from the bucket, or whose footer fails its own
+ * checks, is left out; any other failed read throws, before anything is published.
+ */
+export declare function readSeed(storage: IStorageDriver, ref: SegmentRef, row: RegistryRecord | null, generation: number, keep: number, listed: readonly number[] | undefined, leased: ReadonlySet<number>, readRetry?: ReadRetry): Promise<KnownGeneration[]>;