@cloudbitmaps/core 0.15.0 → 0.17.0

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

@@ -10,6 +10,7 @@
  * All of it runs before the load's first request, so a malformed input costs no round trip and writes nothing.
  */
 import type { CodecBitmap, CodecInterface } from './codec.js';
+import type { CombinedChunk } from './engine.js';
 /**
  * Anything that serializes itself to portable Roaring: `roaring`'s `RoaringBitmap32` is one. Typed by shape, so
  * no codec's own class appears in a signature. A bitmap that can also say how large its serialization is
@@ -44,6 +45,14 @@ export declare class DecodedLoadInput {
     readonly bitmap: CodecBitmap;
     constructor(bitmap: CodecBitmap);
 }
+/**
+ * A combine's result as the bitmaps of its chunks, ascending by key: written as they are, never id by id. Made only by
+ * {@link loadSegmentChunks}, never by {@link prepareLoadInput}, so no input a load is handed can be one.
+ */
+export declare class ChunkLoadInput {
+    readonly chunks: AsyncIterable<CombinedChunk>;
+    constructor(chunks: AsyncIterable<CombinedChunk>);
+}
 /**
  * Check a load's input and decode a bitmap input, before the load makes any request.
  *
@@ -53,3 +62,15 @@ export declare class DecodedLoadInput {
  * 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;

package/dist/core/load.d.ts

@@ -20,7 +20,7 @@
  * object, so it stays, and collection takes it like any other generation once one above it is current.
  */
 import { type IAuditSink } from './audit.js';
-import { type CodecInterface } from './codec.js';
+import { type CodecBitmap, type CodecInterface } from './codec.js';
 import type { Clock, Rng } from './determinism.js';
 import type { IKeystore } from './crypto.js';
 import { type LoadInput } from './load-input.js';
@@ -47,10 +47,10 @@ export interface LoadDeps {
      */
     readonly readRetry?: ReadRetry;
     /**
-     * Collect by listing the segment's objects after the publish, whatever `keep` is. Absent, a load that keeps at
-     * most one generation and found nothing above its pointer deletes by name the one generation its publish pushed
-     * out of the window, and lists every sixteenth generation to take what that leaves; the generations older than
-     * the window wait for that listing. Set it for a caller whose `keep` promises every generation below the new
+     * Collect by listing the segment's objects after the publish, whatever `keep` is. Absent, a load whose row records
+     * the generations it keeps and that found nothing above its pointer deletes by name the generations its publish
+     * pushed out of the window, and lists every sixteenth generation to take what that leaves; the generations no list
+     * names wait for that listing. Set it for a caller whose `keep` promises every generation below the new
      * one beyond the window is gone when the call returns: the `*Into` verbs, whose `keep` is how an operator clears
      * a destination that earlier materialisations kept in full.
      */
@@ -95,12 +95,14 @@ export interface LoadOptions {
      * longest pinned job runs, on every writer that loads the segment — see "Generations and `keep`" in the loading
      * guide.
      *
-     * With `keep` of 0 or 1, a load that found nothing above the pointer collects without listing: it deletes the one
-     * generation its publish pushed out of the window, and lists the segment's objects on every sixteenth generation to
-     * take whatever that pass leaves, such as the generations an earlier, wider `keep` held. With `keep` of 2 or more
-     * it lists on every load, and so does one whose check found the current generation's object gone: the guard's read of
-     * it, or, when the guard took the size from the row's summary, one zero-byte read made before a `keep` of 1 takes a
-     * name. A `keep` at least the generation published collects nothing and asks for nothing.
+     * The segment's row records the generations a load keeps, up to 64, so a load that found nothing above the pointer
+     * collects without listing: it deletes the generations its publish pushed out of the window, and lists the segment's
+     * objects on every sixteenth generation to take whatever that pass leaves, such as an object a crashed load left
+     * below the pointer. A `keep` above 64 records no list and lists on every load, and so does the first load of a
+     * row that records none, which then records it; so does a load whose check found the current generation's object
+     * gone: the guard's read of it, or, when the guard took the size from the row's summary, one zero-byte read made
+     * before a `keep` of 1 or more takes a name. A `keep` at least the generation published collects nothing and asks
+     * for nothing.
      */
     readonly keep?: number;
     /**
@@ -154,7 +156,7 @@ export interface LoadResult {
     /**
      * The superseded generations collected after publishing. Empty when nothing was published.
      *
-     * When collection deleted by name (see {@link LoadOptions.keep}) this is the name it deleted, and that generation
+     * When collection deleted by name (see {@link LoadOptions.keep}) these are the names it deleted, and one
      * may have been gone already: a delete of an absent object succeeds on every backend and does not say so, so the
      * list names what the pass asked the bucket to delete, not what it found there. A listing pass names the
      * generations it found and deleted. Neither is a receipt, since a concurrent collector may have taken a generation
@@ -174,3 +176,22 @@ export interface LoadResult {
  * interesting cases (a guard tripped, a racing writer won) are operational facts rather than faults.
  */
 export declare function loadSegment(ref: SegmentRef, input: LoadInput, deps: LoadDeps, options?: LoadOptions): Promise<LoadResult>;
+/**
+ * {@link loadSegment} for the result of a combine, as the chunks it is made of: each `{ chunkKey, bitmap }` is the
+ * bitmap of one 16-bit chunk's remainders, and they ascend by key. The chunks are written as they are, so no id is built
+ * for a value. What the `*Into` verbs call; the unwired form of them, as {@link loadSegment} is of `store.load`.
+ *
+ * Every chunk is checked before anything is written. Its bitmap must be one the `codec` made (`codec.owns`, so a codec
+ * without it refuses every chunk), its key an integer in `[0, 65535]` above the one before, and its values 16-bit;
+ * anything else is a {@link ValidationError}. An empty bitmap is left out, as no empty chunk is stored.
+ *
+ * **The load consumes the bitmaps it is given.** Writing a chunk may re-encode its bitmap in place for size, which
+ * changes its representation and never its members, so pass bitmaps you made for this call and do not reuse them. A
+ * bitmap the chunk cache holds, or one a caller still reads, is not one to pass.
+ *
+ * Everything else is `loadSegment`'s, the options, the result and the refusals included.
+ */
+export declare function loadSegmentChunks(ref: SegmentRef, chunks: AsyncIterable<{
+    readonly chunkKey: number;
+    readonly bitmap: CodecBitmap;
+}>, deps: LoadDeps, options?: LoadOptions): Promise<LoadResult>;

package/dist/core/metrics.d.ts

@@ -92,6 +92,30 @@ export type MetricEvent = {
     readonly kind: 'op';
     readonly name: MetricOpName;
     readonly ms: number;
+} | {
+    /**
+     * A once-only note that a setting looks too small for how the store is used. It is not a fault: nothing failed.
+     * Emitted by a backend that can read the setting, never on a request's path after the first, and silent for
+     * anything the backend cannot read, so no event does not mean the setting is large enough.
+     *
+     * `'socket-pool-below-window'`: the S3 client's pool is smaller than `threshold` sockets, twice `concurrency`.
+     * `concurrency` is the default window of a combine (32), since a combine's own `concurrency` is chosen per call
+     * and the backend cannot see it: a store that always passes a lower one can ignore the event. `maxSockets` is
+     * the `maxSockets` of the agent for the scheme of the client's endpoint, or, when the client does not expose an
+     * endpoint, the larger of the agents its handler has made (the event fires only when all are below `threshold`).
+     * `driver` and `bucket` say which backend the pool
+     * belongs to; they never carry a credential, an endpoint or a key.
+     *
+     * A sink that switches on `kind` with an exhaustive `never` check stops compiling at this variant: add a case
+     * for `'advisory'` (ignoring it is fine). A sink with a `default` branch needs no change.
+     */
+    readonly kind: 'advisory';
+    readonly code: 'socket-pool-below-window';
+    readonly driver: string;
+    readonly bucket: string;
+    readonly maxSockets: number;
+    readonly threshold: number;
+    readonly concurrency: number;
 };
 /**
  * The sink you plug in. One method, synchronous, fire-and-forget. It must never throw back into the

package/dist/core/ports.d.ts

@@ -9,6 +9,7 @@
  */
 import type { BlobSink } from './blob.js';
 import type { WrappedDek } from './crypto.js';
+import type { IMetricsSink } from './metrics.js';
 /** Opaque optimistic-concurrency token — unique per write, compared by equality only. */
 export type Token = string;
 /**
@@ -334,6 +335,20 @@ export interface SealedRegistrySummary {
      */
     readonly sealed: string;
 }
+/**
+ * One lease on a generation. It names no fingerprint: a collector spares a generation by number and cannot compare an
+ * object without reading it, and a purge and re-create drops the whole list with the row. A pin's own fingerprint,
+ * which its reads check, stops a number retaken after a rollback being read as the leased object; the entry then spares a
+ * different object from collection until it ends, at most the longest lease.
+ */
+export interface LeaseEntry {
+    /** 16 lowercase hex digits drawn once per pin call; names the holder, so a retried write is idempotent. */
+    readonly holder: string;
+    /** The generation held. */
+    readonly generation: number;
+    /** Epoch-ms the lease runs to on the holder's clock; a collector holds it for the skew margin longer. */
+    readonly until: number;
+}
 /**
  * One registry row — the authoritative per-segment record. Exactly one per segment.
  */
@@ -376,6 +391,21 @@ export interface RegistryRecord extends SegmentRef {
      * correct, and a reader then opens the generation instead. Trusted only for the generation it names.
      */
     readonly summary?: RegistrySummary;
+    /**
+     * The generations below `currentGen` that the last publish kept as its grace window, ascending. Optional: absent
+     * means the row does not know which generations are kept, and a load then lists the bucket to collect and records
+     * them; an empty list means none are. Trusted only while every entry is below `currentGen`. A patch that moves
+     * `currentGen` without naming it drops it.
+     */
+    readonly keptGens?: readonly number[];
+    /**
+     * The leases on this segment's generations: each keeps one generation out of a load's collection until it ends.
+     * Optional; absent means none. Unlike {@link keptGens} it does not follow the pointer: a patch that moves
+     * `currentGen` leaves it as it was, and only a patch that names it, or the row going away, changes it. Entries
+     * past their end are ignored by every collector and pruned by the next write that names the list. A row's identity
+     * is its token, so a purged and re-created segment starts with none.
+     */
+    readonly leases?: readonly LeaseEntry[];
     /** Epoch-ms of creation / last mutation (from the driver's injected clock). */
     readonly createdAt: number;
     readonly updatedAt: number;
@@ -402,6 +432,8 @@ export interface NewRegistryRecord {
     readonly residency?: GovernanceMeta;
     /** Must name `currentGen` when given. */
     readonly summary?: RegistrySummary;
+    /** Every entry below `currentGen`, ascending; see {@link RegistryRecord.keptGens}. */
+    readonly keptGens?: readonly number[];
 }
 /**
  * Fields a {@link IRegistryDriver.compareAndSwap} may mutate (identity + audit + token are off-limits).
@@ -409,9 +441,27 @@ export interface NewRegistryRecord {
  * Presence-based: a field the patch does not mention is left as it was. `summary` is the one exception, because it
  * describes the current generation: a patch that moves `currentGen` and does not mention `summary` drops the old
  * one rather than keep a description of another generation. A `summary` the patch gives must name the
- * `currentGen` the row will have.
+ * `currentGen` the row will have. `keptGens` follows the pointer the same way: a patch that moves `currentGen` and does
+ * not mention it drops it, and one that gives it must name only generations below the `currentGen` the row will have.
  */
-export type RegistryPatch = Partial<Pick<RegistryRecord, 'currentGen' | 'wrappedDeks' | 'keyId' | 'status' | 'retention' | 'residency' | 'summary'>>;
+export type RegistryPatch = Partial<Pick<RegistryRecord, 'currentGen' | 'wrappedDeks' | 'keyId' | 'status' | 'retention' | 'residency' | 'summary' | 'keptGens' | 'leases'>>;
+/**
+ * What a caller passes {@link IRegistryDriver.create} or {@link IRegistryDriver.compareAndSwap} besides the write itself.
+ */
+export interface RegistryWriteOptions {
+    /**
+     * The row the caller read, and is writing against: the record a {@link IRegistryDriver.get} of this registry returned
+     * to it, or `null` when that read found no row. A driver that would read the row to learn the version its conditional
+     * write is fenced on can use the one it observed then, and send the write at once.
+     *
+     * It is a hint, and never the fence: the write is still conditioned on the store's own version of the row, so a row
+     * that has changed since makes it fail as a lost race does, with {@link WriteConflictError}. A driver reads the row
+     * as it does without a hint when it does not recognise the record (one it did not return, or one that is not of
+     * this row), or when `held` and the `expected` token of a `compareAndSwap` disagree. A write that gets no answer is
+     * settled by reading the row, never by this record. A driver that ignores the option reads the row.
+     */
+    readonly held?: RegistryRecord | null;
+}
 /** Capabilities a registry driver advertises; validated fail-fast at wiring time. */
 export interface RegCaps {
     /** REQUIRED — `currentGen` feeds read correctness + the publish CAS, so reads must be strongly consistent. */
@@ -436,6 +486,47 @@ export interface RegCaps {
      */
     readonly conditionalDelete?: boolean;
 }
+/** What {@link IRegistryDriver.reapLegacyTombstones} is asked to do. */
+export interface ReapLegacyTombstonesOptions {
+    /** Only rows in this namespace; every namespace, the library's bookkeeping namespaces included, when absent. */
+    readonly namespace?: string;
+    /** Count what would be removed and remove nothing. */
+    readonly dryRun: boolean;
+    /** The most rows to remove (or, in a dry run, to count as removable) in this call. */
+    readonly limit: number;
+}
+/** What a reap of the tombstones a registry holds found. Every count is of rows, not requests. */
+export interface ReapLegacyTombstonesResult {
+    /** The call was a dry run: nothing was removed, and `wouldReap` says what a real run removes. */
+    readonly dryRun: boolean;
+    /** Rows read. Rows the `limit` stopped the run before reading are not counted. */
+    readonly examined: number;
+    /** Rows removed. Always 0 in a dry run. */
+    readonly reaped: number;
+    /** Rows a dry run found removable. Always 0 in a real run. */
+    readonly wouldReap: number;
+    /**
+     * The `limit` was spent and the listing had more keys: rows were left unread, and they may or may not be removable,
+     * so run again. A run is not resumable: each lists and reads from the start, so a dry run with a `limit` reports the
+     * same first rows every time, and `wouldReap` is a total only when this is `false`.
+     */
+    readonly limited: boolean;
+    /** Rows read and left, by why. */
+    readonly skipped: {
+        /** A live (`active`, not deleted) row. */
+        readonly live: number;
+        /** A `destroyed` row that is not `deleted`: a crypto-shred's or a drop's tombstone, kept as the attestation of an erasure. */
+        readonly destroyed: number;
+        /**
+         * A deleted row that carries an incarnation id, written by a 0.12 or later release. On a registry that removes rows,
+         * `delete` and the sweep remove such a row themselves; one left while the registry could not remove rows (GCS by
+         * default, S3 on a custom endpoint) stays, and this call, which refuses on such a registry, does not remove it.
+         */
+        readonly incarnated: number;
+        /** A row that changed, or was already gone (a 404), between its read and its delete, so the delete (fenced on the version read) refused. */
+        readonly raced: number;
+    };
+}
 /**
  * Refuse, with `UnsupportedError`, a write that would write an object before its row when the registry reports it
  * cannot write a row (see {@link RegCaps.canWrite}). Called before the write's first request.
@@ -479,6 +570,14 @@ export interface StorageBackend {
     readonly storage: IStorageDriver;
     /** Where the `currentGen` pointer, the discovery index and the wrapped DEKs live. */
     readonly registry: IRegistryDriver;
+    /**
+     * Optional. A store with a metrics sink calls this once, as it is built, with that sink (already safe to call: it
+     * never throws back). A backend that has something to say about its own setup, such as a pool it can read and finds
+     * small, keeps the sink and emits an `advisory` event to it later. A backend without it is simply never told. One backend
+     * may be handed to several stores, and is called once by each, with each store's own sink. It must not throw: an
+     * exception propagates from the store's constructor, so a backend's bug fails fast rather than going unseen.
+     */
+    attachMetrics?(sink: IMetricsSink): void;
 }
 /**
  * The brand key, for the type-only `declare` field a backend class carries.
@@ -560,12 +659,20 @@ export interface IRegistryDriver {
      * serving what it holds and asks again shortly, while any other error reaches the read that met it.
      */
     get(ref: SegmentRef): Promise<RegistryRecord | null>;
-    /** Create the row; throws {@link WriteConflictError} if it already exists (use CAS to mutate). */
-    create(ref: SegmentRef, record: NewRegistryRecord): Promise<{
+    /**
+     * Create the row; throws {@link WriteConflictError} if it already exists (use CAS to mutate). With
+     * `options.held` of `null`, the caller found no row: a driver may send the create-only write without reading first,
+     * and one that then loses it reads the row, as it does without the hint.
+     */
+    create(ref: SegmentRef, record: NewRegistryRecord, options?: RegistryWriteOptions): Promise<{
         token: Token;
     }>;
-    /** Server-side compare-and-set: apply `patch` iff the stored token equals `expected`, else `WriteConflictError`. */
-    compareAndSwap(ref: SegmentRef, expected: Token, patch: RegistryPatch): Promise<{
+    /**
+     * Server-side compare-and-set: apply `patch` iff the stored token equals `expected`, else `WriteConflictError`.
+     * `options.held` is the row the caller read, which a driver may use to skip its own read; see
+     * {@link RegistryWriteOptions}.
+     */
+    compareAndSwap(ref: SegmentRef, expected: Token, patch: RegistryPatch, options?: RegistryWriteOptions): Promise<{
         token: Token;
     }>;
     /**
@@ -594,5 +701,20 @@ export interface IRegistryDriver {
      * created after the decision. A third-party driver that ignores `expected` keeps the unfenced behaviour.
      */
     delete(ref: SegmentRef, expected?: Token): Promise<void>;
+    /**
+     * Optional: remove the `deleted: true` rows with no incarnation id, which a release before 0.12 left, or a 0.12 or
+     * later release left by deleting a row born before 0.12, so that no later full `list` reads them. Only a registry that
+     * keeps such rows in its backend implements it; the object registries do.
+     *
+     * It removes a row only if it is `deleted: true` with no incarnation id (whatever its `status`), and only by a delete
+     * the backend applies under the version it read (see {@link RegCaps.conditionalDelete}), so a `create` that lands over
+     * the row first wins. A registry that cannot delete under that precondition throws `CapabilityError` before its first
+     * request. It never touches a live row, a `destroyed` row that is not `deleted`, or a deleted row with an incarnation
+     * id, so it does not remove every row a full `list` reads. If `conditionalDelete` was set on a backend that ignores the
+     * precondition, the delete is unfenced.
+     *
+     * Not resumable: every call lists and reads from the start (R reads for R rows, whatever the `limit`).
+     */
+    reapLegacyTombstones?(options: ReapLegacyTombstonesOptions): Promise<ReapLegacyTombstonesResult>;
 }
 export {};

package/dist/core/registry-reap.d.ts

@@ -0,0 +1,22 @@
+import type { IRegistryDriver, ReapLegacyTombstonesResult } from './ports.js';
+/** Rows one call removes when no `limit` says otherwise. */
+export declare const DEFAULT_REAP_LIMIT = 1000;
+/** The keys `reapRegistryTombstones` takes. */
+export interface ReapRegistryTombstonesOptions {
+    /** Only rows in this namespace. Omit to cover every namespace, the library's own bookkeeping rows included. */
+    readonly namespace?: string;
+    /** Count what a real run would remove, and remove nothing. Needs no `confirmNoLegacyWriters`. */
+    readonly dryRun?: boolean;
+    /** Required `true` for a real run: no process on a release before 0.12 writes this registry. */
+    readonly confirmNoLegacyWriters?: boolean;
+    /** The most rows to remove in this call (default {@link DEFAULT_REAP_LIMIT}); a run that stops on it says `limited`. */
+    readonly limit?: number;
+}
+/** What a reap found and did: see {@link ReapLegacyTombstonesResult}. */
+export type ReapRegistryTombstonesResult = ReapLegacyTombstonesResult;
+/**
+ * Remove the `deleted: true` rows with no incarnation id from `registry`, or count them (`dryRun`).
+ *
+ * Cost over R rows read and E removed: `ceil(R / 1000)` LIST requests, R GETs and E DELETEs.
+ */
+export declare function reapRegistryTombstones(registry: IRegistryDriver, options?: ReapRegistryTombstonesOptions): Promise<ReapRegistryTombstonesResult>;

package/dist/core/retention.d.ts

@@ -1,3 +1,4 @@
+import { type ChurnDeps } from './leases.js';
 import type { GovernanceMeta, IRegistryDriver, SegmentRef } from './ports.js';
 /**
  * The smallest accepted `expiresAt`: 2001-09-09, the point below which an epoch-**seconds** value would land.
@@ -18,7 +19,7 @@ export interface RetentionPolicy {
      */
     readonly expiresAt: number;
 }
-export interface RetentionDeps {
+export interface RetentionDeps extends ChurnDeps {
     readonly registry: IRegistryDriver;
 }
 export interface SetRetentionResult {

package/dist/core/rollback.d.ts

@@ -18,9 +18,10 @@
  */
 import { type IAuditSink } from './audit.js';
 import type { IKeystore } from './crypto.js';
+import { type ChurnDeps } from './leases.js';
 import type { IStorageDriver, GenerationMetadata, IRegistryDriver, SegmentRef } from './ports.js';
 /** What the generation helpers need: the objects, and the pointer that says which one is current. */
-export interface GenerationListDeps {
+export interface GenerationListDeps extends ChurnDeps {
     readonly storage: IStorageDriver;
     readonly registry: IRegistryDriver;
     /**

package/dist/driver-kit.d.ts

@@ -1,5 +1,6 @@
 export type { GenKey, IRegistryDriver, IStorageDriver, SegmentRef, StorageBackend, StorageCaps, } from './core/ports.js';
 export { brandAsBackend, STORAGE_BACKEND } from './core/ports.js';
+export type { IMetricsSink, MetricEvent } from './core/metrics.js';
 export { IntegrityError, isNotFoundError, isValidationError, isWriteConflictError, NotFoundError, TransientError, ValidationError, WriteConflictError, } from './core/errors.js';
 export { validateSegmentRef } from './core/validate.js';
 export type { BlobSink } from './core/blob.js';