@cloudbitmaps/core 0.18.3 → 0.19.1

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

@@ -68,9 +68,11 @@
  * 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 is the same case: it writes its object above the pointer before it publishes, and an
- * erasure that finds the id in that object deletes it as it does any holder there, so a load that then publishes
- * leaves the pointer naming a missing object.
+ * 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.
  */
 import { type IAuditSink } from './audit.js';
 import type { CodecInterface } from './codec.js';
@@ -137,8 +139,9 @@ export interface EraseIdResult {
      * re-run settles it, which is why it is the documented action for this reason and for no other.
      *
      * The first three reasons are also returned when the row changes *underneath* a call already in flight, not
-     * only when it is read up front — a concurrent `dropSegment` gives `'destroyed'`, a retention sweep that purges
-     * the row gives `'absent'`. A caller branching on `reason` never has to care which it was.
+     * only when it is read up front — a concurrent `dropSegment` gives `'destroyed'`, once the tombstone's objects have
+     * been searched as a fresh call searches them, and a retention sweep that purges the row gives `'absent'`. A caller
+     * branching on `reason` never has to care which it was.
      */
     readonly reason?: 'absent' | 'destroyed' | 'no-generation' | 'not-member' | 'superseded';
     /**

package/dist/core/erasure.d.ts

@@ -14,7 +14,7 @@
  */
 import { type IAuditSink } from './audit.js';
 import { type ChurnDeps } from './leases.js';
-import type { IStorageDriver, IRegistryDriver, SegmentRef } from './ports.js';
+import type { IStorageDriver, IRegistryDriver, RegistryRecord, SegmentRef } from './ports.js';
 export interface EraseDeps extends ChurnDeps {
     readonly registry: IRegistryDriver;
 }
@@ -165,7 +165,7 @@ export interface DropResult {
  * but the object exists, and it holds the complete set. A single list-then-delete misses it entirely. The re-sweep
  * converges because the tombstone *is* a hard fence on **publishing**, so only loads already under way can write
  * and they are finite. One that writes after the last pass deletes its own object when its publish is refused, as a
- * refused load does under a `destroyed` row; only one whose process stops in between, or whose publish fails without
+ * refused load and a refused erasure rewrite do under a `destroyed` row; only one whose process stops in between, or whose publish fails without
  * a definite answer (a lost response, a timeout), leaves it behind, for a re-run of the drop, and
  * `generationsRemaining` cannot report an object written after this call returned.
  *
@@ -188,3 +188,23 @@ export declare function dropSegment(ref: SegmentRef, deps: DropDeps, options: {
     dryRun?: boolean;
     audit?: IAuditSink;
 }): Promise<DropResult>;
+/**
+ * What the retention sweep adds to a drop. `wanted` is judged on every row the shred is about to replace with a
+ * tombstone, so a row whose expiry was extended or cleared after the sweep looked, or that someone else has already
+ * destroyed or purged, is left as it is rather than retired. `stamp` is the `retention` the tombstone carries, written
+ * 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 {
+    readonly wanted: (row: RegistryRecord) => boolean;
+    readonly stamp: (retention: RegistryRecord['retention']) => RegistryRecord['retention'];
+}
+/**
+ * {@link dropSegment}, with what a retention sweep adds: `null` when `sweep.wanted` refused the row, with nothing
+ * written or deleted.
+ */
+export declare function dropSegmentFor(ref: SegmentRef, deps: DropDeps, options: {
+    confirmSegment: string;
+    dryRun?: boolean;
+    audit?: IAuditSink;
+}, sweep: SweepDrop | undefined): Promise<DropResult | null>;

package/dist/core/errors.d.ts

@@ -64,8 +64,8 @@ export declare class LeaseLimitError extends CloudRoaringError {
 /**
  * An operand a call relied on changed while the call ran, so what the call built from it is not published. Carries the
  * operand's name in the call and why it is stale (`'moved'`: it was pinned at a generation and its pointer has since
- * moved; `'erased'`: an erasure ran in the store after a call with a feed began, or after a held operand the call reads
- * was made, so what the feed gave it, or what the operand holds, may hold an erased id), under the stable `code`
+ * moved; `'erased'`: an erasure ran in the store after a call with a feed began, so what the feed gave it may hold an
+ * erased id), under the stable `code`
  * `'stale-operand'`. Deterministic: run the call again against the current operand.
  */
 export declare class StaleOperandError extends CloudRoaringError {
@@ -150,4 +150,12 @@ export declare function isNotFoundError(err: unknown): err is NotFoundError;
 export declare function isIntegrityError(err: unknown): err is IntegrityError;
 /** Invalid caller input. */
 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;
+/** A driver lacks a capability the store's wiring needs. */
+export declare function isCapabilityError(err: unknown): err is CapabilityError;
+/** A call would pass its per-op request budget, so it was refused before fanning out. */
+export declare function isBudgetExceededError(err: unknown): err is BudgetExceededError;
+/** No key the keystore holds can unwrap an encrypted segment's data key. */
+export declare function isKeyUnavailableError(err: unknown): err is KeyUnavailableError;
 export {};

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

@@ -45,8 +45,8 @@ export interface LoadNumber {
  * `superseded`. The orphan above stays unpublished; the load whose check meets it numbers past it by the listing,
  * 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, the chunk cache and a pin all key on
- * the number and the row's token, and the token has moved on.
+ * 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.
  */
 export declare function nextLoadGeneration(ref: SegmentRef, deps: GenerationDeps, row: RegistryRecord | null): Promise<LoadNumber>;
 /**

package/dist/core/keys.d.ts

@@ -1,7 +1,35 @@
 import type { ChunkRef, SegmentRef } from './ports.js';
 export declare function segmentKey(ref: SegmentRef): string;
 export declare function segmentPrefix(ref: SegmentRef): string;
+/**
+ * How many segments' encoded keys a {@link KeptSegmentKeys} holds before it empties: the reader cache's default
+ * segment count, a working set a long-lived reader keeps open. With 30-character names that is about 150 KB.
+ */
+export declare const KEPT_SEGMENT_KEYS = 1024;
+/**
+ * Segments' encoded keys ({@link segmentKey}, or {@link segmentPrefix}: whichever `encode` gives), kept so a read that
+ * looks up chunk after chunk compares names rather than encoding them again, which costs about a third of a warm
+ * `has()`. Held by namespace and then by segment, so segments of one name in several namespaces sit side by side, and
+ * no number of segments read in turn makes every lookup encode again. Bounded: at `max` entries it empties and fills
+ * again. An encoding is the names' and nothing else, so a kept one is the one an encoding would give now.
+ */
+export declare class KeptSegmentKeys {
+    private readonly encode;
+    private readonly max;
+    private readonly byNamespace;
+    private kept;
+    constructor(encode: (ref: SegmentRef) => string, max?: number);
+    /** The segment's encoded key. */
+    of(ref: SegmentRef): string;
+    /** How many encoded keys are kept. */
+    get size(): number;
+}
 export declare function chunkRefKey(ref: ChunkRef): string;
+/**
+ * {@link chunkRefKey}, or {@link chunkGenKey} with a `version`, from the segment's {@link segmentPrefix} already
+ * encoded: for a caller that looks up many chunks of a few segments and keeps their prefixes.
+ */
+export declare function chunkKeyUnder(prefix: string, chunkKey: number, version?: string | number): string;
 /**
  * Cache key for a chunk scoped to a specific **version** of the segment — {@link chunkRefKey} plus that
  * version (space-delimited, injection-proof exactly as above — the name parts are already encoded). A publish bumps the version, so it naturally

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

@@ -57,12 +57,11 @@ export declare class ChunkLoadInput {
  * Check a load's input and decode a bitmap input, before the load makes any request.
  *
  * @returns ids unchanged, to be consumed lazily by the write, or the decoded bitmap.
- * @param subject names what takes the input in a refusal's message.
  * @throws {ValidationError} for a byte array passed as ids; bytes that are malformed, over the cap, or followed by
  * more bytes; a `{ bitmap }` with no `serialize` method, or whose `serialize('portable')` returns no `Uint8Array`;
  * 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, subject?: string): Iterable<number> | AsyncIterable<number> | DecodedLoadInput;
+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.

package/dist/core/load.d.ts

@@ -59,8 +59,9 @@ export interface LoadDeps {
 /**
  * What a plausible result looks like, so an implausible one is refused instead of published.
  *
- * Both bounds are compared against the **current** generation's cardinality, read from the `.crbm` index rather
- * than its payload — one object-header read, and only when a bound is actually set.
+ * `minCardinality` judges the new generation alone. `minRetained` and `maxGrowth` judge it against the **current**
+ * generation's cardinality, which the load takes from the registry row's summary of it when the row has a usable one,
+ * and otherwise from the `.crbm` index (one object-header read, never the payload), and only when a bound needs it.
  */
 export interface LoadGuard {
     /** Refuse a generation with fewer than this many ids. Use for "this segment is never legitimately tiny". */
@@ -76,7 +77,25 @@ export interface LoadGuard {
      * permissive, which is where an inversion would eventually be written and not noticed.
      */
     readonly minRetained?: number;
+    /**
+     * Refuse a generation larger than this multiple of the current one — `1.5` means "at most half as large again".
+     * The ceiling to `minRetained`'s floor: a source that lands duplicated or joined wrong grows a segment as quietly as
+     * a partial one shrinks it. A shrinking load is never refused by this bound, and neither is the first load of a
+     * segment nor one onto an empty segment, which have no size to multiply. `1` means "never grow".
+     *
+     * `0` means no bound, as on the two fields above. Setting it makes the load read the current size and fence its
+     * publish on it, as `minRetained` does, `allowEmpty: true` or not. The comparison is in floating point, so do not
+     * rely on the exact boundary: `100 × 1.15` is `114.99999999999999`.
+     */
+    readonly maxGrowth?: number;
 }
+/**
+ * Check a guard's bounds before any round trip, and copy them: the one check `load` and each output of
+ * `materializeMany` share. The copy is what the load judges, so a guard object the caller reuses or changes while the
+ * call runs cannot change the bound it is judged by. `where` prefixes each field's name in the message (`''`, or
+ * `'outputs[3].'`).
+ */
+export declare function checkedGuard(guard: LoadGuard | undefined, where: string): LoadGuard | undefined;
 export interface LoadOptions {
     /**
      * Publish an empty generation over a non-empty one. Off by default: an empty result is far more often an
@@ -119,15 +138,43 @@ export interface LoadOptions {
     readonly metadata?: GenerationMetadata;
     readonly audit?: IAuditSink;
 }
+/** The bounds a guard can refuse a generation for: every {@link LoadRefusal} but a lost race. */
+export type GuardRefusal = Exclude<LoadRefusal, 'superseded'>;
+/**
+ * The bound a generation of `cardinality` ids breaks over a current one of `before` (`null`: none, or not read), in the
+ * order a load checks them, or `undefined`. Pure: the one judgement a load and a dry run share.
+ */
+export declare function guardRefusal(cardinality: number, before: number | null, guard: LoadGuard | undefined, allowEmpty: boolean | undefined): GuardRefusal | undefined;
+/** What a dry run learns about one write: the size it would replace, and the bound that would refuse it. */
+export interface LoadJudgement {
+    /**
+     * The current generation's size: `null` when there is none or its object is gone, and, where no bound needs the size,
+     * when its object could not be read, as the load would not read it. Always asked for.
+     */
+    readonly cardinalityBefore: number | null;
+    /** The bound a load of this size would be refused for now, absent when it would publish. */
+    readonly wouldRefuse?: GuardRefusal;
+    /** The requests the judgement made: the row, and the object's index when the row had no usable summary. */
+    readonly reads: number;
+}
+/**
+ * Judge a write of `cardinality` ids into `ref` as a load would, and write nothing: read the row and the current size
+ * as the load reads them, and apply the same bounds. A `destroyed` segment throws the `ValidationError` a load's write
+ * would, and an encrypted one with no keystore the `KeyUnavailableError`. What it says holds for now only: a load
+ * made later is judged against the segment as it is then.
+ */
+export declare function judgeLoad(ref: SegmentRef, cardinality: number, deps: LoadDeps, options?: Pick<LoadOptions, 'allowEmpty' | 'guard'>): Promise<LoadJudgement>;
 /** Why a load did not become current. */
-export type LoadRefusal = 'empty' | 'min-cardinality' | 'min-retained'
+export type LoadRefusal = 'empty' | 'min-cardinality' | 'min-retained' | 'max-growth'
 /**
  * Another writer got there first. Either another load wrote the same generation number first, so the write-once
  * put refused this one and it wrote nothing (`size: 0`); or the segment's registry row changed while the load was
- * writing: another load published, a retention change, a rollback or an erasure wrote the row, or the row was
- * deleted. Once another write has changed the row, the object stays in the bucket, because its generation number
- * may by then name another incarnation's live object; once the row is `destroyed` (dropped or crypto-shredded),
- * the object is deleted, and once the row is gone, so is an object its footer proves this load's own.
+ * writing: another load published, a retention change, a rollback or an erasure wrote the row, the row was
+ * deleted, or a row appeared where the load found none. Once another write has changed the row, the object stays in
+ * the bucket, still billed, until a later load's collection deletes it (at the latest the listing a load runs
+ * every sixteenth generation) or the segment is dropped, because its generation number may by then name another
+ * incarnation's live object; once the row is `destroyed` (dropped or crypto-shredded), the object is deleted, and
+ * once the row is gone, so is an object its footer proves this load's own.
  */
  | 'superseded';
 export interface LoadResult {

package/dist/core/metrics.d.ts

@@ -14,8 +14,15 @@
  * per-series metric labels unless they're known low-cardinality and PII-free. See the observability
  * guide.
  */
-/** The segment operations that emit an `op` latency event (timed with the injected clock, at the facade). */
-export type MetricOpName = 'has' | 'count' | 'intersectInto' | 'unionInto' | 'andNotInto';
+/**
+ * The operations that emit an `op` latency event (timed with the injected clock, at the facade). `materializeMany` is
+ * timed from its first request, the pins, to its last publish: a call its input checks refuse emits none.
+ *
+ * A name added here stops two kinds of code compiling: a sink that switches on `name` with an exhaustive `never` check
+ * (add a case, or use a `default` branch, which needs no change), and a `Record<MetricOpName, …>` built by hand, a
+ * `MetricsSnapshot` literal among them (add the key).
+ */
+export type MetricOpName = 'has' | 'count' | 'intersectInto' | 'unionInto' | 'andNotInto' | 'materializeMany';
 /**
  * One observability event. A discriminated union on `kind` — new variants can be added over time without
  * breaking consumers (they switch on the kinds they care about). `namespace` is the segment's namespace
@@ -27,10 +34,11 @@ export type MetricEvent = {
     readonly namespace?: string;
     readonly segment: string;
     /**
-     * One event per request for chunks: a range request of a combine or `iterate`, which carries every chunk the read
-     * needs from a stretch of the object, or the one chunk of a read made on its own, however many callers were waiting
-     * on it. Bytes returned: the range's, the gaps between its chunks included (0 if a single chunk was absent — a GET
-     * still happened).
+     * One event per request for chunks: a range request of a combine, `iterate` or `materializeMany`, which carries
+     * every chunk the read needs from a stretch of the object, or the one chunk of a read made on its own, however
+     * many callers were waiting on it. A `materializeMany` range serves every output of its group, so its events
+     * count the requests the call sent, not requests per output. Bytes returned: the range's, the gaps between its
+     * chunks included (0 if a single chunk was absent — a GET still happened).
      */
     readonly bytes: number;
     /**
@@ -45,7 +53,7 @@ export type MetricEvent = {
      * no cached chunk. A combine or `iterate` looks up every chunk it needs when it opens its streams. A caller that
      * missed while another caller's read of the same chunk was open waits on that read and adds no `storage.get`, and a
      * range carries several chunks, so the misses can outnumber the `storage.get` events; the `storage.get` count is
-     * the number of requests for chunks.
+     * the number of requests for chunks. `materializeMany` never looks up the cache, so it emits none.
      */
     readonly kind: 'cache';
     readonly hit: boolean;
@@ -57,6 +65,10 @@ export type MetricEvent = {
     readonly attempt: number;
     readonly delayMs: number;
 } | {
+    /**
+     * One per chunk-aligned combine of one operator. `materializeMany` emits none: an output is an expression over
+     * several operators, and the call's `stats.chunks.pruned` counts the index keys it did not read.
+     */
     readonly kind: 'intersect';
     /**
      * Which chunk-aligned combine this was. **Optional** — absent means `'intersect'`.

package/dist/core/ports.d.ts

@@ -10,7 +10,10 @@
 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. */
+/**
+ * Opaque optimistic-concurrency token — unique per write with overwhelming probability, since it carries random parts
+ * (see {@link RegistryRecord.token}), and compared by equality only.
+ */
 export type Token = string;
 /**
  * The address of one segment: a `namespace` and a `segment` name, both any non-empty string of at most 256
@@ -191,6 +194,10 @@ export interface StorageChunkSource {
      * Note that putting the incarnation in the *object key* would not fix this: the new incarnation still starts
      * at generation 0, so the cache key collides either way. The identity has to reach the cache.
      *
+     * Within one incarnation a number can be taken again once its object is deleted, so two objects must never share
+     * a version either, however long after its pointer read a source opens the object: the `.crbm` source's version
+     * ends with the fingerprint of the object it opened.
+     *
      * Returns `null` when the segment resolves to no generation. A source that only ever serves one immutable
      * generation may omit this, and the engine falls back to the generation alone.
      */
@@ -214,8 +221,14 @@ export interface StorageCaps {
  * shipped driver to them:
  *
  * - **`putImmutable` is write-once and reports a collision as {@link WriteConflictError}.** It never overwrites a
- *   stored object. `load` reads that error as a lost race for the generation number (`superseded`), so a driver
- *   that threw anything else for an existing key would surface as a failed load.
+ *   stored object, two concurrent writes of one key included: exactly one lands. `load` reads that error as a lost
+ *   race for the generation number (`superseded`), so a driver that threw anything else for an existing key would
+ *   surface as a failed load. A write whose writer fails stores nothing, and the key can be written after.
+ * - **Keys keep every name apart.** One segment in two namespaces, two names an encoding could fold into one (`a/b`
+ *   and `a_b`), and a name that extends another (`s` and `s.1`) are separate objects, each listed and deleted alone;
+ *   generations are listed and deleted by number, never by a prefix of one.
+ * - **A bucket or container that does not exist is not a missing object**: it fails with an error that is neither
+ *   {@link NotFoundError}, which would read as an empty segment, nor a {@link TransientError}, which a retry cannot fix.
  * - **A missing object makes `getRange` and `getTail` throw {@link NotFoundError}** — never an empty or short
  *   result. Heal-forward (a read whose generation a sweep collected re-resolves), the erasure's holder probe and
  *   its verify of the rewrite, and a pin's replaced-object check all branch on that one error. (A zero-length
@@ -234,6 +247,8 @@ export interface StorageCaps {
  *   holding the id, `dropSegment`'s `generationsRemaining`, the retention sweep's check that a tombstone's storage
  *   is gone, and rollback's post-move check prove a deletion or a presence by listing, so a listing that lags
  *   reports an erasure as incomplete or a stale object as gone.
+ * - **`list` yields every generation, however many pages the service splits it into.** One that stops after its
+ *   first page drops generations from every collection and every check above.
  * - **Never replay a conditional write without telling the replay apart.** A `putImmutable` that lands and then
  *   loses its response, sent again, finds its own object and would report a collision. Either send each write
  *   once, with the backend client's retry off for that request, or recognise your own write when the
@@ -486,47 +501,6 @@ 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.
@@ -623,8 +597,8 @@ export declare function brandAsBackend<T extends {
 export declare function isStorageBackend(value: unknown): value is StorageBackend;
 /**
  * Per-segment registry — the authoritative source of `currentGen`, the discovery index, and the wrapped-DEK
- * holder. One row per segment under OCC: a never-reused, equality-compared {@link Token} (ABA-safe across
- * delete→recreate).
+ * holder. One row per segment under OCC: an equality-compared {@link Token} that is never reused, with overwhelming
+ * probability (ABA-safe across delete→recreate).
  *
  * **What a driver must do** — callers rely on each of these, and the registry conformance suite holds every
  * shipped driver to them:
@@ -643,7 +617,11 @@ export declare function isStorageBackend(value: unknown): value is StorageBacken
  *   **With `expected` it is fenced**: it lands only while the row still carries that token, and otherwise throws
  *   {@link WriteConflictError} and leaves the row.
  * - **Reads are strongly consistent** (`RegCaps.strongRead`), and `list` yields every existing row,
- *   `destroyed` tombstones included, with every field (see {@link IRegistryDriver.list}).
+ *   `destroyed` tombstones included, with every field (see {@link IRegistryDriver.list}), however many pages the
+ *   service splits the listing into.
+ * - **A bucket or container that does not exist is not an absent row**: a read, a listing and a write fail with an
+ *   error that is neither {@link NotFoundError} nor a {@link TransientError}, and a read never answers `null`, which would
+ *   read as a segment with no generation.
  * - **Never replay a conditional write without telling the replay apart.** A `create` or `compareAndSwap`
  *   that lands and then loses its response, sent again, finds its own write and would report a conflict.
  *   Either send each write once, with the backend client's retry off for that request, or recognise your own
@@ -701,20 +679,5 @@ 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/retention-sweep.d.ts

@@ -177,7 +177,8 @@ export type RetireEntry = {
      * expiring is the silence that costs a retention commitment.
      * `'limit'` — eligible, but this cycle's `limit` was already spent. Re-run to continue.
      * `'tombstone-not-empty'` — a tombstone whose Storage generations are not gone even after a GC
-     * attempt, so its row is kept: the row is what keeps the segment reachable by the generation collection and
+     * attempt, so its row is kept, and, unless the collection lost a race to a write of the row, a refused purge
+     * (see {@link RetireExpiredResult.purgeFaults}): the row is what keeps the segment reachable by the generation collection and
      * refused by every writer. Several causes, all self-healing: the storage really could not be reclaimed,
      * the collection *declined* because the row changed underneath it (`WriteConflictError`, which this
      * sweep swallows deliberately), or this was a `dryRun`, which reports the reason without attempting the
@@ -193,7 +194,10 @@ export type RetireEntry = {
 export interface RetireExpiredResult {
     /** Registry rows enumerated. */
     readonly scanned: number;
-    /** Rows whose policy said "expired" — including any the `limit` deferred. */
+    /**
+     * Rows whose policy said "expired", counted until the `limit` stopped the scan: the first row it deferred is counted
+     * and the rows after it are not read, so with `limited: true` this is a lower bound.
+     */
     readonly eligible: number;
     /**
      * Segments **actually retired**. Zero under `dryRun` — see `wouldRetire`. Kept honest because this is the field
@@ -208,8 +212,9 @@ export interface RetireExpiredResult {
     /** True when `limit` cut the cycle short — **more segments are still eligible**. Re-run. */
     readonly limited: boolean;
     /**
-     * Deletes this sweep attempted that the registry **refused for a reason other than a lost race**: a tombstone's
-     * purge, or the removal of a due-index pointer. A policy that denies delete, an Azure blob with a snapshot, or any
+     * Deletes this sweep attempted that were **refused for a reason other than a lost race**: a tombstone's purge
+     * (including one whose objects were still there after a collection that raised nothing), or the removal of a
+     * due-index pointer. A policy that denies delete, an Azure blob with a snapshot, or any
      * raw provider error is one; a write that landed between the sweep's read and its fenced delete is not (that is
      * `failed: contended` in the ledger). Each leaves its row or pointer in place, so a purge that keeps failing never
      * frees the name.

package/dist/core/retention.d.ts

@@ -44,6 +44,14 @@ export interface SetRetentionResult {
      */
     readonly indexed: boolean;
 }
+/**
+ * The key of the retention sweep's mark on a tombstone it wrote, which is what lets a later sweep purge the row. Only the
+ * sweep's own tombstone write sets it, and every other tombstone write removes it ({@link withoutSweepMark}), so a
+ * restored or hand-edited row cannot hand the sweep a tombstone it did not write.
+ */
+export declare const SWEEP_MARK = "retiredBySweepAt";
+/** `meta` without the sweep's mark, or `undefined` when it carries none, so a write that changes nothing is not made. */
+export declare function withoutSweepMark(meta: GovernanceMeta | undefined): GovernanceMeta | undefined | null;
 /**
  * Read the policy off a registry row's `retention` metadata. Returns `null` when there is no policy, and
  * `'invalid'` when the key is present but unusable (wrong type, or below the epoch-seconds floor).
@@ -56,6 +64,15 @@ export interface SetRetentionResult {
 export declare function readRetentionPolicy(meta: GovernanceMeta | undefined): RetentionPolicy | null | 'invalid';
 /** The stored policy for one segment, or `null` if it has none (and `'invalid'` for a malformed one). */
 export declare function getSegmentRetention(ref: SegmentRef, deps: RetentionDeps): Promise<RetentionPolicy | null | 'invalid'>;
+/**
+ * Record when a segment becomes eligible for retirement, creating its registry row if it has none.
+ *
+ * Idempotent and safe to re-run: writing the same instant twice is a no-op in effect. Other keys already in the
+ * row's `retention` metadata are preserved — this owns one key, not the whole object.
+ *
+ * Refuses a `destroyed` segment: a tombstone has nothing left to retire, and putting a policy on one would make
+ * a sweep repeatedly "retire" bytes that are already gone.
+ */
 export declare function setSegmentRetention(ref: SegmentRef, deps: RetentionDeps, policy: RetentionPolicy): Promise<SetRetentionResult>;
 /**
  * Remove a segment's expiry so no sweep will retire it. Returns whether a policy was actually removed (`false`

package/dist/core/retry.d.ts

@@ -75,6 +75,12 @@ export type ReadRetry = RetryDeps & {
  * The write itself is never passed here.
  */
 export declare function retryRead<T>(op: () => Promise<T>, retry: ReadRetry | undefined): Promise<T>;
+/**
+ * `policy`, checked when it is wired rather than at the first retry: a delay or factor that is not a finite number, a
+ * negative delay, a factor below 1 or a jitter mode it does not know would make the backoff `NaN`, which a timer reads
+ * as 1 ms, so bounded backoff silently became a hot retry loop.
+ */
+export declare function checkedRetryPolicy(policy: RetryPolicy): RetryPolicy;
 /**
  * Run `op`, retrying transient failures per `policy`. Resolves with `op`'s result, or rejects with the last
  * error once attempts are exhausted (or immediately for a non-retryable error). The thrown error is always

package/dist/driver-kit.d.ts

@@ -1,7 +1,7 @@
 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 { IntegrityError, isIntegrityError, isNotFoundError, isTransientError, isValidationError, isWriteConflictError, NotFoundError, TransientError, ValidationError, WriteConflictError, } from './core/errors.js';
 export { validateSegmentRef } from './core/validate.js';
 export type { BlobSink } from './core/blob.js';
 export { MAX_ROW_BYTES, ObjectStoreRegistry, ObjectVersionRaced, } from './drivers/_shared/object-registry.js';