@cloudbitmaps/core 0.22.0 → 0.23.0

package/dist/core/ports.d.ts

@@ -25,16 +25,29 @@ export type Token = string;
  * segment in such a namespace would be invisible to an erasure, a consistency check, an export and a retention sweep.
  * A driver takes the prefix, since the due index's own rows go through it. Only that exact prefix is reserved:
  * `cbm.dueX` and `cbmdue.eu` are ordinary namespaces, and a segment name is never restricted.
+ *
+ * **A key other than `segment` and `namespace` throws `ValidationError`**, in every call of the store and of the free
+ * functions behind it that takes a ref, and at a driver port (which also takes a `generation`, a `chunkKey` and a
+ * registry row's own fields): a misspelt `namespace` would otherwise address the segment of that name in the default
+ * namespace. A `segments()` row is the one exception at the store: its `currentGen` and `status` are taken and read for
+ * nothing. A segment handle, a registry row from `registry.get()` or `list()` (a driver port takes one, a store call does
+ * not), and a result row such as a consistency issue, a ledger entry, an export manifest entry or an audit event, is not
+ * a ref at the store: pass `{ segment, namespace }`.
  */
 export interface SegmentRef {
+    /** The segment's namespace, or `undefined` for the default one. */
     readonly namespace?: string;
+    /** The segment's name. */
     readonly segment: string;
 }
+/** One chunk of a segment: the segment, and the chunk's key. */
 export interface ChunkRef extends SegmentRef {
+    /** The chunk's key: an integer from 0 to 65,535, the high 16 bits of the ids the chunk holds. */
     readonly chunkKey: number;
 }
 /** Identifies one immutable `.crbm` object — a single generation of a segment. */
 export interface GenKey extends SegmentRef {
+    /** The generation number of the object. */
     readonly generation: number;
 }
 /**
@@ -43,6 +56,7 @@ export interface GenKey extends SegmentRef {
  * holds for an operand's stream.
  */
 export interface SegmentSize {
+    /** The size of the current generation's object, in bytes. */
     readonly sizeBytes: number;
 }
 /**
@@ -52,8 +66,11 @@ export interface SegmentSize {
  * can key what it keeps by the generation the bytes came from rather than the one it resolved earlier.
  */
 export interface ChunkRead {
+    /** The chunk key that was asked for. */
     readonly key: number;
+    /** The chunk's bytes, or `null` where the generation holds none. */
     readonly bytes: Uint8Array | null;
+    /** The version of the generation the bytes were read from, or `null` when the segment has no generation. */
     readonly version: string | null;
 }
 /** Options of {@link StorageChunkSource.getChunks}. */
@@ -91,6 +108,7 @@ export interface ReadChunksOptions {
 export interface StorageChunkSource {
     /** Read-only bytes for the chunk, or `null` if absent. Callers must not mutate the buffer. */
     getChunk(ref: ChunkRef): Promise<Uint8Array | null>;
+    /** The chunk keys the segment's current generation holds, or an empty list when it has none. */
     listChunkKeys(ref: SegmentRef): Promise<number[]>;
     /**
      * Optional: several chunks of one segment as a stream, read **from one generation** with fewer storage requests than
@@ -330,6 +348,7 @@ export interface StorageDeleteOptions {
  *   retry can ride it out and a write's caller can tell it from a deterministic failure.
  */
 export interface IStorageDriver {
+    /** What this driver can do. Range reads and `maxObjectBytes` are required; the other capabilities are optional. */
     capabilities(): StorageCaps;
     /**
      * Stream a new immutable generation. The driver opens a destination, hands `write` a {@link BlobSink},
@@ -337,6 +356,12 @@ export interface IStorageDriver {
      * already exists (write-once). Call `write` once: the object committed is the bytes that one call wrote, because
      * the caller records the write identity of that call's object (its footer) for every later proof; a driver that
      * runs `write` again after a failed attempt must commit only the last run's bytes.
+     *
+     * What a second run of `write` does depends on what is written. A load of ids, of a bitmap or of a combine's chunks
+     * holds its chunks in memory, so each run writes the whole object again, under a write identity of its own, and the
+     * load records the run that was committed. A write that streams its chunks, a load with `sorted: true` and an
+     * erasure's rewrite, reads them once, so its second run throws {@link IntegrityError} before writing a byte: commit
+     * nothing then, and the call throws that error, with the first run's error as its `cause`.
      */
     putImmutable(key: GenKey, write: (sink: BlobSink) => Promise<void>): Promise<{
         size: number;
@@ -368,8 +393,9 @@ export interface IStorageDriver {
     list(ref: SegmentRef): AsyncIterable<GenKey>;
 }
 /**
- * Lifecycle status of a segment. `active` is the steady state; `destroyed` is the post-crypto-shred tombstone
- * (the row is kept for audit but the segment is logically gone).
+ * Lifecycle status of a segment. `active` is the steady state; `destroyed` is the tombstone left by a crypto-shred, a
+ * cleartext destroy or a drop (the row is kept for audit but the segment is logically gone: no read resolves a
+ * generation through it).
  */
 export type RegistryStatus = 'active' | 'destroyed';
 /**
@@ -404,7 +430,9 @@ export type RegistrySummary = ClearRegistrySummary | SealedRegistrySummary;
 export type GenerationMetadata = Readonly<Record<string, string | number>>;
 /** What a generation is, as one read answers it: its number, its id count and the metadata it was written with. */
 export interface GenerationSummary {
+    /** The generation's number. */
     readonly generation: number;
+    /** The number of ids the generation holds. */
     readonly cardinality: number;
     /** Absent when the generation has none. */
     readonly metadata?: GenerationMetadata;
@@ -486,8 +514,9 @@ export interface RegistryRecord extends SegmentRef {
     readonly currentGen: number | null;
     /**
      * Per-segment data-key (DEK) wrappings for encryption-at-rest: the DEK envelope-wrapped under one or more KEKs
-     * (active + optional recovery). Reading unwraps with any held KEK; **crypto-shred deletes this whole list**,
-     * making the segment's at-rest bytes permanently unrecoverable. Absent ⇒ the segment is cleartext.
+     * (active + optional recovery). Reading unwraps with any held KEK; **crypto-shred deletes this whole list** from
+     * the current row, so the segment's at-rest bytes are unrecoverable once no retained copy of the row (a noncurrent
+     * version, a backup) still holds it, or every KEK that wrapped it is destroyed. Absent ⇒ the segment is cleartext.
      */
     readonly wrappedDeks?: readonly WrappedDek[];
     /**
@@ -496,6 +525,10 @@ export interface RegistryRecord extends SegmentRef {
      * keystore. Clearable on crypto-shred.
      */
     readonly keyId?: string;
+    /**
+     * `'active'`, or `'destroyed'` for the tombstone of a segment that was crypto-shredded, destroyed in the clear or
+     * dropped.
+     */
     readonly status: RegistryStatus;
     /**
      * Governance policy. `retention.expiresAt` drives the retention sweep (see {@link GovernanceMeta}); `residency`
@@ -503,6 +536,7 @@ export interface RegistryRecord extends SegmentRef {
      * `list()` projection — a fleet sweep reads the policy from the enumeration rather than per-segment.
      */
     readonly retention?: GovernanceMeta;
+    /** Residency metadata, a plain object. It is stored and returned as given; nothing reads it yet. */
     readonly residency?: GovernanceMeta;
     /**
      * A cached description of the current generation (see {@link RegistrySummary}). Optional: a row without one is
@@ -539,6 +573,7 @@ export interface RegistryRecord extends SegmentRef {
     readonly leases?: readonly LeaseEntry[];
     /** Epoch-ms of creation / last mutation (from the driver's injected clock). */
     readonly createdAt: number;
+    /** Epoch-ms of the row's last write, from the driver's clock. */
     readonly updatedAt: number;
     /**
      * Opaque OCC token — compare-by-equality, ABA-safe. A shipped registry gives no two writes under one name the same
@@ -566,11 +601,15 @@ export interface RegistryRecord extends SegmentRef {
 export interface NewRegistryRecord {
     /** `null` ⇒ the segment has no Storage generation yet — see {@link RegistryRecord.currentGen}. */
     readonly currentGen: number | null;
+    /** The segment's wrapped data keys, which make it an encrypted segment. Absent for a cleartext one. */
     readonly wrappedDeks?: readonly WrappedDek[];
+    /** An external key reference. Reserved: the in-process keystore does not use it. */
     readonly keyId?: string;
     /** Defaults to `'active'`. */
     readonly status?: RegistryStatus;
+    /** The retention policy, a plain object; its `expiresAt` is what the retention sweep reads. */
     readonly retention?: GovernanceMeta;
+    /** Residency metadata, a plain object. It is stored and returned as given; nothing reads it yet. */
     readonly residency?: GovernanceMeta;
     /** Must name `currentGen` when given. */
     readonly summary?: RegistrySummary;
@@ -615,6 +654,11 @@ export interface RegistryWriteOptions {
      * when the write names a resolved field. A write that does not land leaves no row carrying it. A call refused before
      * it has a token to send, on a conflict its own read finds, reports none.
      *
+     * A publish relies on the report coming first, both ways. A write that faults after its report may have landed, and
+     * is settled by reading the row. A `TransientError` before any report is taken for a fault before sending, such as
+     * the driver's own read of the row: the publish throws it at once, with no read of the row and no fresh write. So
+     * nothing that can land is sent before the report, a client's own resend included.
+     *
      * The token is unique to that write attempt, also against another writer racing the same version: two writers that
      * send a write against the same row version never carry the same token, so a version counter alone is not enough.
      * Otherwise a loser's write would pass for the winner's.
@@ -701,6 +745,38 @@ export interface StorageBackend {
      * exception propagates from the store's constructor, so a backend's bug fails fast rather than going unseen.
      */
     attachMetrics?(sink: IMetricsSink): void;
+    /**
+     * Optional. Reads the setup the backend cannot change but can be broken by, and says whether it will delete or
+     * archive what the store keeps: today, the bucket's lifecycle rules over the generation objects and the
+     * `<prefix>registry/` rows. It is meant for a check run by hand or at deploy time, not for the read or write path, and
+     * costs one request, plus the SDK's own retries. It never rejects: a check that could not be made resolves to `unchecked` with the
+     * reason in `detail`. A backend without it, a third-party one or a {@link brandAsBackend} wrapper that does not
+     * forward it, offers no lifecycle check, and `store.preflight()` reads that as `unchecked`.
+     *
+     * The cloud rules stay in the driver. A `detail` is for a person, carries no credential, and never changes what a
+     * caller does: act on `status`.
+     */
+    checkLifecycle?(): Promise<LifecycleVerdict>;
+}
+/**
+ * What {@link StorageBackend.checkLifecycle} found.
+ *
+ * - `ok`: no rule that could delete or archive the store's objects. `detail` may still carry advice, such as a missing
+ *   rule that cleans up abandoned multipart uploads, which is never a `problem` by itself.
+ * - `problem`: a rule that deletes or archives the store's current objects, or one that cannot be told apart from it.
+ *   Where a rule is unclear, the check reports a `problem`: a condition it does not interpret, or a value it does not
+ *   recognise (a storage class, an action).
+ * - `unchecked`: the check could not be made (no permission to read the configuration, an error, or a backend whose
+ *   rules are out of the data plane's reach). `detail` says what to grant or how to check by hand.
+ */
+export interface LifecycleVerdict {
+    /**
+     * `'ok'` when no rule would delete or archive the store's objects, `'problem'` when one would or may, `'unchecked'`
+     * when the check could not be made.
+     */
+    readonly status: 'ok' | 'problem' | 'unchecked';
+    /** A sentence or two for a person. Never a credential. */
+    readonly detail: string;
 }
 /**
  * The brand key, for the type-only `declare` field a backend class carries.
@@ -750,7 +826,7 @@ export declare function isStorageBackend(value: unknown): value is StorageBacken
  * 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:
+ * shipped driver to them, except the rule on `unsettledConflict`, which the suite does not test:
  *
  * - **`create` and `compareAndSwap` are atomic conditional writes.** A `create` over a live row, and a
  *   `compareAndSwap` whose token is not the stored one, throw {@link WriteConflictError} and change nothing.
@@ -780,9 +856,19 @@ export declare function isStorageBackend(value: unknown): value is StorageBacken
  *   Either send each write once, with the backend client's retry off for that request, or recognise your own
  *   write when the precondition fails by reading an id you stored with it back. The shipped registries do
  *   one or the other.
+ * - **Raise a conflict that may follow your own write's landing with `unsettledConflict`** (from the driver kit). A
+ *   driver whose client may have sent the write more than once cannot say, after a conflict, that this write did not
+ *   land first: a row is overwritten, so another writer's write found on the read-back may have gone over this one, and
+ *   a row that is gone may have been removed after it landed. Raise every conflict it cannot rule that out for (another
+ *   writer's write on the read-back, a compare-and-swap that finds the row gone, a read-back that finds nothing) as
+ *   `unsettledConflict`, so a load refused after it reports `unanswered: true`. A conflict that proves the write did
+ *   not land (a write sent once, a check made before sending anything) is a plain {@link WriteConflictError}. A
+ *   registry that wraps another rethrows the conflict it was given, unchanged: the check that reads the mark is
+ *   internal, so a conflict built anew loses it.
  * - **Raise a transient fault as {@link TransientError}.**
  */
 export interface IRegistryDriver {
+    /** What this registry can do. Strongly consistent reads are required; the other capabilities are optional. */
     capabilities(): RegCaps;
     /**
      * `true` when every `create` and `compareAndSwap` of this registry reports the token its write carries to
@@ -793,8 +879,15 @@ export interface IRegistryDriver {
      *
      * The flag may be a getter or a field. A registry that wraps or extends another and overrides `create` or
      * `compareAndSwap` either passes `options` through to the write it forwards, or sets `reportsWriteTokens` to
-     * `false`. One that does neither reads every write of its own that landed after an error or a lost answer as not its
-     * own (`superseded`), and deletes nothing.
+     * `false`. One that does neither reads a write of its own that landed and then met a conflict as not its own
+     * (`superseded`), and takes every `TransientError` of its writes, a throttle and a lost answer alike, for a fault
+     * before sending: the publish throws it at once, with no read of the row and no fresh write. Either way it deletes
+     * nothing.
+     *
+     * A publish relies on the report coming first, both ways. A write that faults after its report may have landed, and
+     * is settled by reading the row. A `TransientError` before any report is taken for a fault before sending, such as
+     * the driver's own read of the row: the publish throws it at once, with no read of the row and no fresh write. So
+     * nothing that can land is sent before the report, a client's own resend included.
      */
     readonly reportsWriteTokens?: boolean;
     /**

package/dist/core/preflight.d.ts

@@ -0,0 +1,80 @@
+/**
+ * `runPreflight` — the first-run check of a store's storage and registry, behind `store.preflight()`.
+ *
+ * ```
+ *   registry ── get(probe row) must be null, canWrite !== false
+ *   write ───── put marker A under the probe key
+ *   write-once  put marker B under the same key: must throw WriteConflictError
+ *   read ────── getTail: must return A (read-after-write); gives the version
+ *   list ────── list the probe segment: must name the probe
+ *   delete ──── (finally) delete this run's own key, with the tail's version when it has one
+ *   lifecycle ─ backend.checkLifecycle(), bounded by a timer, unchecked when the backend has none
+ * ```
+ *
+ * The probe key is `cbm.due.preflight/segments/probe.<n>.crbm`, where `<n>` is a 48-bit random number. That
+ * namespace sits inside the reserved `cbm.due.` prefix an application can never name, so no segment of the application's can collide with it, and the registry
+ * writes nothing: the probe is a storage object only, which no registry row names and no scan of the registry
+ * reaches. Storage is only ever listed one segment at a time, from rows or from refs the application gave.
+ *
+ * A finding never throws. A step that fails (a transient fault included) is a `problem` whose detail says so, and the
+ * checks that cannot run without it are `unchecked`; the lifecycle step is the exception, whose failures, its timeout
+ * included, are `unchecked`. Every step runs through one guard, so nothing a step meets (an error whose getters throw,
+ * a verdict whose getters throw, a clock whose sleep rejects, an entropy source that throws) escapes. The only throw
+ * is a store with nothing to check, which the facade refuses before it gets here.
+ *
+ * Not checked: read-after-delete, the registry's `If-Match` on compare-and-swap, multipart abort permission,
+ * versioning and backups.
+ *
+ * Time arrives through the injected {@link Clock}: the lifecycle step is bounded by {@link LIFECYCLE_TIMEOUT_MS},
+ * counted in short sleeps of {@link LIFECYCLE_TICK_MS} so that a check that answers at once leaves no long timer
+ * holding a short-lived process open.
+ */
+import type { Clock, Entropy } from './determinism.js';
+import type { IRegistryDriver, IStorageDriver, LifecycleVerdict } from './ports.js';
+/**
+ * What one check found.
+ *
+ * - `ok`: the check ran and found nothing wrong.
+ * - `problem`: the check ran and found something wrong, or the request it makes failed (a transient fault included:
+ *   `detail` says to run again then). The lifecycle check is the exception: its failures, its timeout included, are
+ *   `unchecked`.
+ * - `unchecked`: the check could not be made, because a step it depends on failed (`write-once`, `read`, `list` and
+ *   `delete` after a failed `write`), or the backend offers no such check, or the lifecycle check did not answer in
+ *   time. `ok` on the result does not vouch for it.
+ */
+export interface PreflightCheck {
+    /** Which check this is. A run lists all seven, in this order. */
+    readonly name: 'registry' | 'write' | 'write-once' | 'read' | 'list' | 'delete' | 'lifecycle';
+    /** What the check found. */
+    readonly status: 'ok' | 'problem' | 'unchecked';
+    /** A sentence or two for a person: what was found, and what to do. The name and message of a failed step's error. */
+    readonly detail: string;
+}
+/** What `store.preflight()` found: every check, and whether none of them is a `problem`. */
+export interface PreflightResult {
+    /** True when no check is a `problem`. A check that is `unchecked` does not make it false. */
+    readonly ok: boolean;
+    /** All seven checks, in the order the type of `PreflightCheck.name` lists them. */
+    readonly checks: PreflightCheck[];
+}
+/** What a run needs: the store's raw drivers, an entropy source for the probe's number, and a clock for the bound. */
+export interface PreflightDeps {
+    readonly storage: IStorageDriver;
+    readonly registry: IRegistryDriver;
+    readonly clock: Clock;
+    readonly entropy: Entropy;
+    /** The backend's lifecycle check, bound to the backend; absent for a backend that has none. */
+    readonly checkLifecycle?: (() => Promise<LifecycleVerdict>) | undefined;
+}
+/** The probe's namespace, inside the reserved prefix; no application ref can name it. */
+export declare const PREFLIGHT_NAMESPACE = "cbm.due.preflight";
+/** The probe's segment name. */
+export declare const PREFLIGHT_SEGMENT = "probe";
+/** How long the lifecycle step may take before it is read as `unchecked`: 30 seconds of the injected clock. */
+export declare const LIFECYCLE_TIMEOUT_MS = 30000;
+/** The length of each sleep the bound is counted in. */
+export declare const LIFECYCLE_TICK_MS = 250;
+/**
+ * Run the seven checks. Never rejects: see the module comment.
+ */
+export declare function runPreflight(deps: PreflightDeps): Promise<PreflightResult>;

package/dist/core/retention-sweep.d.ts

@@ -2,8 +2,24 @@ import { type IAuditSink } from './audit.js';
 import type { DropDeps, DropResult } from './erasure.js';
 /** Default cap on retirements per sweep — a bounded batch, so a policy mistake costs one batch, not the fleet. */
 export declare const DEFAULT_RETIRE_LIMIT = 100;
+/**
+ * The shortest `tombstoneGraceMs` a sweep takes: one hour. A first load whose create got no answer is sent again, and a
+ * tombstone purged before that copy arrives lets it create the row again over the purged name, wrapped key included.
+ * A grace of seconds is for a test, which advances an injected clock.
+ */
+export declare const MIN_TOMBSTONE_GRACE_MS = 3600000;
+/**
+ * Options of a retention sweep: the instant to judge policies at (`now`), which segments it considers, how many it
+ * retires in one call, how it finds them, whether it only reports (`dryRun`), where retirements are audited (`audit`),
+ * and whether and when it purges the tombstones of earlier retirements.
+ */
 export interface RetireExpiredOptions {
-    /** Scope the sweep to one namespace. Omit to sweep every namespace the registry knows. */
+    /**
+     * Scope the sweep to one namespace. Omit to sweep every namespace the registry knows, segments loaded with no
+     * namespace included. `'_default'`, the label the export tool and the disaster-recovery samples print, and the
+     * bucket's object keys use, for those segments, is an ordinary namespace name here: it scopes the sweep to a
+     * namespace of that name, not to them.
+     */
     readonly namespace?: string;
     /**
      * The instant to compare policies against (epoch-ms). Required here because `core/` takes its time from the
@@ -11,7 +27,7 @@ export interface RetireExpiredOptions {
      */
     readonly now: number;
     /**
-     * Maximum segments to retire in this cycle (default 100). It also bounds the purges attempted (a purge the registry
+     * Maximum segments to retire in this cycle (default 100; an integer of at least 1, `null` refused). It also bounds the purges attempted (a purge the registry
      * refuses is not charged; {@link RetireExpiredResult.purgeFaults} says how purging stops after refusals), the
      * due-index pointers to nothing one call removes, and, counted apart from the retirements, the tombstones this sweep
      * did not write whose pointers one call removes.
@@ -21,7 +37,10 @@ export interface RetireExpiredOptions {
     readonly dryRun?: boolean;
     /** Forwarded to each `dropSegment`, so every retirement lands in the audit trail as `segment.dispose`. */
     readonly audit?: IAuditSink;
-    /** Ceiling on rows enumerated (default 250,000); exceeding it throws. */
+    /**
+     * Ceiling on rows enumerated (default 250,000); exceeding it throws. On an `'index'` scan the check runs before
+     * each pointer's row is read, so live rows equal to the ceiling followed by a pointer whose row is gone throw too.
+     */
     readonly maxScanSegments?: number;
     /**
      * **Where the candidates come from.**
@@ -41,6 +60,8 @@ export interface RetireExpiredOptions {
      * tombstone under the day the tombstone's grace ends, and the scan reads it back with the expiry pointers. A pointer
      * whose segment is gone is removed once read, by an index scan in the buckets it reads, and by an unscoped `'fleet'`
      * scan (no `namespace`) in every bucket.
+     *
+     * Any other value, a misspelt `'index'` or a `null` included, throws `ValidationError` rather than running the fleet scan.
      */
     readonly scan?: 'fleet' | 'index';
     /**
@@ -49,14 +70,17 @@ export interface RetireExpiredOptions {
      * across restarts.
      */
     readonly shards?: readonly number[];
-    /** Total shards the fleet is split into. Required with {@link shards}; ignored without it. */
+    /**
+     * Total shards the fleet is split into. Required with {@link shards}; ignored without it. `shards` must list at least
+     * one number from 0 to `totalShards - 1`, each once, else `ValidationError`.
+     */
     readonly totalShards?: number;
     /**
      * How many **past** buckets an `'index'` scan reads besides the current one (default 7, one per day).
      * A sweep that did not run — scaled to zero, a failed deploy, a paused
      * schedule — leaves its buckets behind, and this is how far back a later cycle reaches for them. Bounded so a
      * long outage costs a bounded number of list calls per cycle rather than one per day since the epoch;
-     * anything older is the `'fleet'` repair pass's job.
+     * anything older is the `'fleet'` repair pass's job. An integer from 0 to 3660 on either scan, else `ValidationError`.
      */
     readonly lookbackBuckets?: number;
     /**
@@ -76,7 +100,13 @@ export interface RetireExpiredOptions {
      * zero is the opposite of another's is a reading hazard for whoever tunes both.
      */
     readonly purgeTombstones?: boolean;
-    /** How long a retirement's tombstone must age before this sweep deletes it (default 24 h). */
+    /**
+     * How long a retirement's tombstone must age before this sweep deletes it: at least one hour (`ValidationError`
+     * below), 24 h by default. The floor keeps the tombstone in place longer than a first load's create can take to be
+     * sent again after it got no answer, which would otherwise create the row again over the purged name, wrapped key
+     * included. Keep it well above the longest time a first load's registry write can still arrive (seconds on S3 and
+     * GCS, over a minute on Azure Blob at the SDK's default retry schedule). `null` is refused.
+     */
     readonly tombstoneGraceMs?: number;
 }
 /** What happened to one segment in a sweep. */
@@ -88,10 +118,13 @@ export type RetireEntry = {
     readonly expiresAt: number;
     readonly result: DropResult;
     /**
-     * Present when the retirement **completed the destructive part and then faulted** — the tombstone is written
-     * and the segment reads empty, but something after that (the Storage sweep) threw. The storage may not be fully
-     * reclaimed; re-run. Reported as `retired` rather than `skipped` because the segment really is retired, and
-     * saying otherwise is the one thing a caller cannot recover from.
+     * Present when the **tombstone landed and the retirement then faulted**: its storage sweep or listing threw, or
+     * the shred's own write got no answer that a read of the row could settle (then no `segment.erase` was emitted:
+     * record the crypto-shred yourself). `result.generationsRemaining` lists what a listing of the bucket found after
+     * the fault (the generations the row named, when that listing failed too). A sweep's re-run does not collect
+     * those objects inside `tombstoneGraceMs`: run `store.dropSegment(ref, { confirmSegment })`. Reported as `retired`
+     * rather than `skipped` because the segment really is retired, and saying otherwise is the one thing a caller
+     * cannot recover from.
      */
     readonly fault?: `failed: ${string}`;
 } | {
@@ -114,7 +147,8 @@ export type RetireEntry = {
      * `'invalid-policy'` — the row has an `expiresAt` that is not usable (hand-edited, or restored from another
      * schema). Reported rather than ignored: reading as "never expires" on a segment someone believes is
      * expiring is the silence that costs a retention commitment.
-     * `'limit'` — eligible, but this cycle's `limit` was already spent. Re-run to continue.
+     * `'limit'` — never written: a segment the cycle's `limit` deferred gets no entry, and
+     * {@link RetireExpiredResult.limited} is what says the cap cut the pass short. 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, 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
@@ -127,9 +161,14 @@ export type RetireEntry = {
      * re-reads before every deletion precisely so cancelling an expiry works on a sweep already in flight.
      * `` `failed: …` `` — any fault, isolated to this segment. A fault that happened *after* the tombstone
      * landed is reported as `retired` with a `fault` instead, because that segment IS retired.
+     * When the row cannot be read afterwards either, the reason says the tombstone may have landed.
      */
     readonly reason: 'invalid-policy' | 'limit' | 'tombstone-not-empty' | 'policy-changed' | `failed: ${string}`;
 };
+/**
+ * What a retention sweep did: the rows it read, what it retired, and a ledger entry for each segment it acted on or
+ * skipped.
+ */
 export interface RetireExpiredResult {
     /** Registry rows enumerated. */
     readonly scanned: number;
@@ -146,11 +185,15 @@ export interface RetireExpiredResult {
     readonly retired: number;
     /** Segments a real sweep **would** have retired. Only ever non-zero under `dryRun`. */
     readonly wouldRetire: number;
-    /** Tombstone rows actually deleted. Zero under `dryRun`; the `would-purge-tombstone` entries carry the preview. */
+    /**
+     * Tombstone rows this sweep saw deleted. Zero under `dryRun`; the `would-purge-tombstone` entries carry the preview.
+     * A purge another sweep made at the same moment is counted by both.
+     */
     readonly tombstonesPurged: number;
     /**
-     * True when `limit` cut the cycle short — **more segments are still eligible**. Re-run. The cap on removing pointers
-     * of tombstones this sweep did not write leaves it false.
+     * True when `limit` cut the pass short — **more work remains**: retirements, or purges of this sweep's tombstones,
+     * which the same `limit` counts. Re-run. The cap on removing pointers of tombstones this sweep did not write leaves
+     * it false.
      */
     readonly limited: boolean;
     /**
@@ -171,8 +214,10 @@ export interface RetireExpiredResult {
     readonly purgeFaults: number;
     /** The first of those faults, as a ledger reason (`failed: …` with the provider's message). Absent when there were none. */
     readonly firstPurgeFault?: `failed: ${string}`;
+    /** Whether the sweep was a dry run, which changes nothing. */
     readonly dryRun: boolean;
-    /** Per-segment ledger. Inspect it: a `skipped` or failed entry is a segment that still holds data. */
+    /** Per-segment ledger. Inspect it: a `skipped` or failed entry is a segment that still holds data, except one whose reason says the row could
+     * not be read afterwards: its tombstone may have landed. */
     readonly entries: readonly RetireEntry[];
 }
 /**

package/dist/core/retention.d.ts

@@ -22,15 +22,23 @@ export interface RetentionPolicy {
 export interface RetentionDeps extends ChurnDeps {
     readonly registry: IRegistryDriver;
 }
+/**
+ * What setting a segment's retention policy did: the policy now stored, and whether it created the row and wrote the
+ * due-index pointer.
+ */
 export interface SetRetentionResult {
+    /** The segment's name. */
     readonly segment: string;
+    /** The segment's namespace, or `undefined` for the default one. */
     readonly namespace?: string;
     /** The policy now stored on the row. */
     readonly expiresAt: number;
     /**
      * True iff this call **minted the registry row** — a policy recorded before the segment's first load. The
      * segment is now enumerable by `registry.list()` and therefore by every fleet-wide operation; the row claims no
-     * Storage generation (`currentGen: null`), so reads answer empty until the first load publishes onto it.
+     * Storage generation (`currentGen: null`), so reads answer empty until the first load publishes onto it. A create
+     * that got no answer is read back and counts when the row carries this call's write token: a later policy or lease
+     * write does not hide it, and a later load's publish does (the call then decides again, and answers `false`).
      */
     readonly createdRow: boolean;
     /**
@@ -70,14 +78,17 @@ export declare function getSegmentRetention(ref: SegmentRef, deps: RetentionDeps
  * 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.
+ * Refuses a `destroyed` segment: a sweep never retires a tombstone (it purges only its own, by their stamp), so a
+ * policy on one would never act. Objects a destroy left in the bucket are deleted by `dropSegment` on the tombstone,
+ * not by a policy.
  */
 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`
- * for a segment with no row, or one that had no policy) — a separate verb from setting one, because "cancel the
- * expiry" and "expire at time T" are different intents and a magic sentinel value for the first is how a typo
+ * Remove a segment's expiry so no sweep will retire it. Returns whether this call removed a policy (`false` for a
+ * segment with no row, or one that had no policy, and also when a write that got no answer cannot be shown to be this
+ * call's and the row holds no expiry: the expiry is gone either way, and its due-index pointer is removed. A later
+ * write that set an expiry is cleared too, and the answer is `true`). A separate verb from setting one, because "cancel
+ * the expiry" and "expire at time T" are different intents and a magic sentinel value for the first is how a typo
  * becomes a deletion.
  *
  * Other `retention` keys are left in place; if removing the expiry empties the metadata, the field is cleared.

package/dist/core/retry.d.ts

@@ -48,7 +48,7 @@ export declare function backoffDelayMs(policy: RetryPolicy, attempt: number): nu
 /** Apply the policy's jitter to a computed delay using the injected RNG. */
 export declare function applyJitter(policy: RetryPolicy, delayMs: number, rng: Rng): number;
 /** A clock that can wait: the one member {@link jitteredWait} uses. */
-interface Sleeper {
+export interface Sleeper {
     readonly sleep?: ((ms: number) => Promise<void>) | undefined;
 }
 /**
@@ -83,4 +83,3 @@ export declare function checkedRetryPolicy(policy: RetryPolicy): RetryPolicy;
  * the *operation's* error — never a wrapper — so callers keep their typed-error branching.
  */
 export declare function withRetry<T>(op: () => Promise<T>, policy: RetryPolicy, deps: RetryDeps): Promise<T>;
-export {};

package/dist/core/rollback.d.ts

@@ -17,8 +17,12 @@ export interface GenerationListDeps extends ChurnDeps {
 }
 /** One generation present in the bucket. */
 export interface GenerationEntry {
+    /** The generation's number. */
     readonly generation: number;
-    /** Whether the registry pointer currently names this generation. */
+    /**
+     * Whether the registry pointer currently names this generation. `false` for every generation of a destroyed
+     * segment: a destroyed row keeps the pointer it had, but no read resolves a generation through it.
+     */
     readonly current: boolean;
     /**
      * Whether the row's record of the generations it published, `knownGens`, names this generation. A rollback onto a known
@@ -76,8 +80,8 @@ export interface RollbackResult {
  * - a generation whose object is **not in the bucket** — collected, or never written — is refused with
  *   `NotFoundError` rather than pointed at, because a pointer naming a missing object is the one state the whole
  *   design exists to avoid;
- * - a **crypto-shredded** segment is refused: every generation of it is unreadable, so a rollback would produce a
- *   segment that resolves and then fails;
+ * - a **destroyed** segment (crypto-shredded, destroyed in the clear or dropped) is refused: no generation resolves
+ *   through a destroyed row, so moving its pointer would change nothing a reader sees;
  * - a target that is **not what the row says the segment is** is refused with `IntegrityError`: a cleartext object
  *   under a row with keys, or an encrypted one under a row with none, either of which every read would then refuse.
  *   One tail read of the target decides it, as does a footer that fails its own checks;
@@ -110,15 +114,21 @@ export interface RollbackResult {
  * failure of the keystore is thrown. After the swap the target's footer is read once more, and the pointer put back,
  * restoring the summary and the record the row had, unless it is still the object that was read: collection can delete a
  * target below the old pointer between the read and the swap, and an erasure can delete one above it and a load take its
- * number. A swap that gets no answer is settled by reading the row: one the row shows landed, the row being the one the
- * swap leaves, is checked as any swap is, and otherwise its `TransientError` is thrown, since it may have landed or may
- * still land, and a re-run finds the pointer where it is. A write by another writer is not taken for it, unless it leaves
- * the very row this swap would. On a cleartext segment two writes can: another rollback onto the same target, whatever
- * row it read, and a load that wrote under that number the very object the rollback read and carried the ledger the
- * rollback would (a load that carries a usable ledger, as one with a `keep` above 64 does; over a row with no usable
- * ledger the rollback writes none and a load seeds one, so those rows differ). On an encrypted segment a rollback with no
- * key at hand writes no summary, so another such rollback onto the same target can too. That call then reports and
- * audits the move as its own; the pointer is where it asked for it.
+ * number. A swap that meets a conflict or gets no answer is settled by reading the row. On a registry that reports its
+ * writes' tokens, one the row shows landed, its pointer at the target over the token of a swap this call sent, is
+ * checked as any swap is, the move audited and reported, whatever else was written to the row since (a lease, a
+ * retention or residency write, or a write of the ledger alone). Otherwise the call throws, and nothing is audited or
+ * deleted: the `WriteConflictError` after a conflict, and the `TransientError` after no answer, since it may have
+ * landed or may still land and a re-run finds the pointer where it is. Another writer's write of the same pointer is not
+ * taken for it, another rollback's identical move included, and neither is a write that renewed the row's `pointerId` over
+ * this swap, which cannot be told from it. A registry that reports no tokens settles a swap that got no answer by the
+ * row it would leave, and never settles a conflict as landed. Over such a registry a write by another writer is not
+ * taken for the swap unless it leaves the very row this swap would. On a cleartext segment two writes can: another
+ * rollback onto the same target, whatever row it read, and a load that wrote under that number the very object the
+ * rollback read and carried the ledger the rollback would (a load that carries a usable ledger, as one with a `keep`
+ * above 64 does; over a row with no usable ledger the rollback writes none and a load seeds one, so those rows differ).
+ * On an encrypted segment a rollback with no key at hand writes no summary, so another such rollback onto the same
+ * target can too. That call then reports and audits the move as its own; the pointer is where it asked for it.
  *
  * What it does **not** do is delete anything. The generations above the new pointer stay in the bucket, which is
  * what makes the rollback reversible — roll forward again by naming one of them. They are also then *above*