@cloudbitmaps/core 0.21.0 → 0.23.0

package/dist/core/load.d.ts

@@ -1,6 +1,6 @@
 import { type IAuditSink } from './audit.js';
 import { type CodecBitmap, type CodecInterface } from './codec.js';
-import type { Clock, Rng } from './determinism.js';
+import type { Clock, Entropy, Rng } from './determinism.js';
 import type { IKeystore } from './crypto.js';
 import { type LoadInput } from './load-input.js';
 import { type ReadRetry } from './retry.js';
@@ -18,6 +18,14 @@ export interface LoadDeps {
      * bound). Absent, the read retry's source is used if it has one, and otherwise each wait is its bound.
      */
     readonly rng?: Rng;
+    /**
+     * The source of the write's identity: 12 random bytes the new generation's footer carries (for a cleartext generation;
+     * an encrypted one carries its index's AEAD nonce), so two loads of the same ids at the same number are two objects
+     * and every check that a footer is "mine" names this write. Required: a load without one (a JavaScript caller can
+     * leave it out) is refused with {@link ValidationError} before any read, keystore call or write.
+     * `@cloudbitmaps/roaring` supplies Web Crypto's by default.
+     */
+    readonly entropy: Entropy;
     /**
      * The store's read retry, for the read the guard makes of the current generation: a transient fault there is run
      * again under it rather than failing the load. Absent, the read is made once. It does not govern the write: a
@@ -75,12 +83,20 @@ export interface LoadGuard {
  * `'outputs[3].'`).
  */
 export declare function checkedGuard(guard: LoadGuard | undefined, where: string): LoadGuard | undefined;
+/**
+ * Options of `store.load` and of core's `loadSegment`: what a load may publish (`allowEmpty`, `guard`), what it keeps
+ * (`keep`) and what it records (`metadata`, `audit`).
+ */
 export interface LoadOptions {
     /**
      * Publish an empty generation over a non-empty one. Off by default: an empty result is far more often an
      * upstream failure than an intent, and the failure is indistinguishable from success once it lands.
      */
     readonly allowEmpty?: boolean;
+    /**
+     * Bounds a plausible result must meet, judged before the pointer moves; a load outside them is refused
+     * (`published: false`), not thrown. See {@link LoadGuard}.
+     */
     readonly guard?: LoadGuard;
     /**
      * Generations to keep below the new pointer as a grace window (default 1). A non-negative integer: anything
@@ -97,14 +113,17 @@ export interface LoadOptions {
      * load superseded comes first. After a rollback that is the one the rollback restored, and it stays in the window of
      * every load after it, ahead of the generations the rollback moved away from, for as many loads as `keep` says.
      *
-     * The segment's row records the generations a load keeps, up to 64, so a load whose number one existence check found
-     * free 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 collects by listing on every load, and so does the first load of a row with
-     * no usable ledger, which starts one from the bucket; 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.
+     * The segment's row records the generations a load keeps, up to 127.
+     *
+     * With a `keep` of at most 64, a load whose number one existence check found free deletes by name 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 load lists instead on every load when `keep` is above 64, when the row has a pointer and no usable record (the
+     * load starts one from the bucket), when the row's record names more than 64 generations below the pointer that no
+     * lease holds (as after a `keep` above 64, or `materializeMany`), or when the guard's read, or the zero-byte read
+     * before a delete by name, finds the current generation's object missing. A publish that a read of the row settles
+     * after its last attempt lists too. A `keep` at least the generation published collects nothing and asks for nothing.
      */
     readonly keep?: number;
     /**
@@ -119,7 +138,28 @@ export interface LoadOptions {
      * over as it is. Sealed under the segment's key when the segment is encrypted.
      */
     readonly metadata?: GenerationMetadata;
+    /** Audit sink for this load: it receives `segment.publish`, or `segment.load-refused` when the load is refused. */
     readonly audit?: IAuditSink;
+    /**
+     * The ids ascend: write them as they are read, one chunk at a time, while the object uploads, so the load holds one
+     * chunk and the writer's index of the chunks written (up to about 7 MiB, about 8 MiB for an encrypted segment,
+     * derived, at the 65,536 chunks a segment can have) rather than the whole generation, whatever the segment's size.
+     * Repeats are fine (an id equal to the one before is skipped); an id lower than the one before throws
+     * `ValidationError`, naming its position and never the id. The object is the same, byte for byte, as an unsorted load
+     * of the same ids writes under the same write identity.
+     *
+     * For ids only (an iterable or an async iterable): with `{ serialized }`, `{ bitmap }` or a `RoaringBitmap32` of the
+     * flavor's own `roaring` (one from another copy loads as its ids, and takes `sorted`), and on core's
+     * `loadSegmentChunks`, it throws `ValidationError`, as does a value that is not a boolean, before any request.
+     *
+     * The ids are read after the segment's row is read and judged, and after its number and key are settled, so a load
+     * that refuses a destroyed or keyless segment reads none of them. They are read while the object uploads: an error
+     * they raise, or a refused id, fails the upload, and no object is committed, but the parts uploaded before it may
+     * already have been billed (see the production guide). That error reaches the caller as the very object raised,
+     * and the storage driver never sees it. The ids can be read once: a storage driver that runs its write again gets
+     * `IntegrityError`, and nothing is written.
+     */
+    readonly sorted?: boolean;
 }
 /** The bounds a guard can refuse a generation for: every {@link LoadRefusal} but a lost race. */
 export type GuardRefusal = Exclude<LoadRefusal, 'superseded'>;
@@ -141,7 +181,7 @@ export interface LoadJudgement {
  * 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>;
+export declare function judgeLoad(ref: SegmentRef, cardinality: number, deps: Omit<LoadDeps, 'entropy'>, options?: Pick<LoadOptions, 'allowEmpty' | 'guard'>): Promise<LoadJudgement>;
 /** Why a load did not become current. */
 export type LoadRefusal = 'empty' | 'min-cardinality' | 'min-retained' | 'max-growth'
 /**
@@ -150,12 +190,17 @@ export type LoadRefusal = 'empty' | 'min-cardinality' | 'min-retained' | 'max-gr
  * 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 or the segment is dropped, because its
- * generation number may by then name another writer's object; until it goes, a rollback onto it needs `allowUnknown`, as onto any generation the row does not know. Once the row is
- * `destroyed` (dropped or crypto-shredded), the object is deleted; once the row is gone, so is an object whose footer
- * matches what this load wrote (a re-created segment's load of the same cleartext ids writes a match), and so is a
- * cleartext one under a row with key material.
+ * generation number may by then name another writer's object; until it goes, a rollback onto it needs
+ * `allowUnknown`, as onto any generation the row does not know. Once the row is `destroyed` (crypto-shredded,
+ * destroyed in the clear or dropped), the object is deleted; once the row is gone, so is an object whose footer
+ * matches what this load wrote (another load's object of the same ids is not a match: the footer carries each write's
+ * own identity), and so is a cleartext one under a row with key material.
  */
  | 'superseded';
+/**
+ * What a load did: the generation it wrote, whether that is now current (`published`, and `reason` when not), the
+ * object it wrote and what it collected.
+ */
 export interface LoadResult {
     /**
      * The generation written. Present even when refused: a refusal deletes that object while the segment's row is
@@ -169,10 +214,19 @@ export interface LoadResult {
     readonly published: boolean;
     /** Set only when `published` is false. */
     readonly reason?: LoadRefusal;
+    /**
+     * Bytes of the generation's object as stored, or 0 when another load took the generation number first and
+     * nothing was written.
+     */
     readonly size: number;
+    /**
+     * SHA-256 of the object as stored, or `''` when another load took the generation number first. The library neither
+     * keeps nor checks it; reads are checked with CRC32C.
+     */
     readonly sha256: string;
+    /** Non-empty chunks in the generation written (at most 65,536), or 0 when nothing was written. */
     readonly chunkCount: number;
-    /** Distinct ids in the generation that was written, post-dedup. */
+    /** Distinct ids in the generation that was written, post-dedup, or 0 when nothing was written. */
     readonly cardinality: number;
     /**
      * What the segment held when the guard judged it — `null` when there was no current generation, or when no
@@ -197,7 +251,8 @@ export interface LoadResult {
  *
  * `input` is ids, or a whole bitmap as `{ serialized }` portable Roaring bytes or a `{ bitmap }` with
  * `serialize('portable')` ({@link LoadInput}). A bitmap input is checked, decoded and serialized before the first
- * request, and is written from its own chunks; the generation is byte for byte the one its ids would write.
+ * request, and is written from its own chunks; the generation holds chunk for chunk what its ids would write, and carries its own write
+ * identity in the footer like any other.
  *
  * Returns what was written and whether it became current. A refusal is **not** an exception: `published: false`
  * with a `reason` is a normal outcome a caller branches on, in the same shape as a successful load, because the

package/dist/core/metrics.d.ts

@@ -133,9 +133,13 @@ export type MetricEvent = {
 };
 /**
  * The sink you plug in. One method, synchronous, fire-and-forget. It must never throw back into the
- * caller — `CloudRoaring` wraps a user sink with {@link safeMetrics} so a buggy sink can't break I/O.
+ * caller — `CloudRoaring` wraps a user sink so that a buggy sink can't break I/O.
  */
 export interface IMetricsSink {
+    /**
+     * Receives one event, synchronously. What it throws, or an async one's rejection, is swallowed and never breaks the
+     * call it observes.
+     */
     onEvent(event: MetricEvent): void;
 }
 /** The default sink: discards everything, zero overhead. Used whenever no sink is wired. */
@@ -147,23 +151,37 @@ export declare const NOOP_METRICS: IMetricsSink;
 export declare function safeMetrics(sink: IMetricsSink): IMetricsSink;
 /** Accumulated totals — the shape returned by {@link CountingMetricsSink.snapshot}. */
 export interface MetricsSnapshot {
+    /**
+     * Chunk requests to storage: how many, the bytes they returned, and the time they took in ms, transient-retry backoff
+     * included.
+     */
     readonly storage: {
         readonly gets: number;
         readonly bytes: number;
         readonly totalMs: number;
     };
+    /**
+     * Decoded-chunk cache hits and misses. A chunk counted without a lookup is a miss; `materializeMany` reads no cache, so
+     * it counts none.
+     */
     readonly cache: {
         readonly hits: number;
         readonly misses: number;
     };
+    /** Retries taken after a transient fault. */
     readonly retries: {
         readonly transient: number;
     };
+    /**
+     * Chunk-aligned combines of every operator (intersect, union and andNot): how many ran, the chunk keys they fetched
+     * and the keys they skipped without a fetch.
+     */
     readonly intersect: {
         readonly calls: number;
         readonly fetchedChunks: number;
         readonly skippedChunks: number;
     };
+    /** By operation name, how many calls were timed and their total time in ms. */
     readonly ops: Readonly<Record<MetricOpName, {
         readonly count: number;
         readonly totalMs: number;
@@ -181,7 +199,10 @@ export declare class CountingMetricsSink implements IMetricsSink {
     private intersect;
     private ops;
     private static zeroOps;
+    /** Adds the event to the totals. An `advisory` event is a note, not a quantity, and adds nothing. */
     onEvent(event: MetricEvent): void;
+    /** A copy of the totals so far, which later events do not change. */
     snapshot(): MetricsSnapshot;
+    /** Sets every total back to zero. */
     reset(): void;
 }

package/dist/core/pinned-storage-source.d.ts

@@ -27,15 +27,34 @@ import type { CrbmStorageChunkSource } from './crbm-storage-source.js';
  * What a pin holds for one segment: the generation, the version identifying those exact bytes, and the pinned
  * object's fingerprint, so a read can tell that the generation it opens is still that object.
  *
- * `fingerprint` is required for a pin of a generation (`null` only when `generation` is `null`): without it a read
- * could not tell a name purged and loaded again from the segment it pinned. `seg.pin()` always records it, and a
- * pin of a generation without a string `version` and `fingerprint` is refused with a `ValidationError`.
+ * It is one of two shapes, told apart by `generation`: a pin of a generation holds all three fields, and a pin of a
+ * segment that had no generation holds `null` in all three. Narrowing on `generation` (or on either other field)
+ * narrows the record whole, so a numbered pin passes to `pinAt` as it is:
+ *
+ * ```ts
+ * const at = first.pinnedAt;
+ * if (at !== undefined && at.generation !== null) await store.segment('active-30d').pinAt(at);
+ * ```
+ *
+ * `fingerprint` is never `null` for a pin of a generation: without it a read could not tell a name purged and loaded
+ * again from the segment it pinned. `seg.pin()` always records it, and a pin of a generation without a string
+ * `version` and `fingerprint` is refused with a `ValidationError`.
  */
-export interface PinnedAt {
-    readonly generation: number | null;
-    readonly version: string | null;
-    readonly fingerprint: string | null;
-}
+export type PinnedAt = {
+    /** The pinned generation. */
+    readonly generation: number;
+    /** The version of that generation's object. */
+    readonly version: string;
+    /** The fingerprint of that generation's object. */
+    readonly fingerprint: string;
+} | {
+    /** `null`: the segment had no generation when it was pinned. */
+    readonly generation: null;
+    /** `null`, as `generation` is. */
+    readonly version: null;
+    /** `null`, as `generation` is. */
+    readonly fingerprint: null;
+};
 export declare class PinnedStorageChunkSource implements StorageChunkSource {
     private readonly inner;
     /**

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

@@ -17,3 +17,12 @@ export declare function renewPointer(row: Pick<RegistryRecord, 'currentGen'>): R
  * cannot key a cache on it. A TypeScript registry fails to compile instead; this catches one in JavaScript.
  */
 export declare function pointerIdOf(row: RegistryRecord): Token;
+/**
+ * Whether `now` shows a write this call sent as the one that put the pointer where it is: an active row of the same
+ * incarnation as `before` (a `create` has none to compare), whose pointer names `generation` and whose `pointerId` is
+ * the token of one of the writes in `sent`, which a registry that reports its writes' tokens gave before sending each.
+ * The token decides and nothing else is asked, so another writer's write of the same pointer is not taken for this
+ * call's. A write that renews the `pointerId` over this call's own landed write (an erasure's renewal, or a write of
+ * the pointer back onto the same generation) reads as not this call's: the two cannot be told apart. Pure: no I/O.
+ */
+export declare function pointerSetBy(now: RegistryRecord | null, before: RegistryRecord | null, generation: number, sent: ReadonlySet<Token>): boolean;

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,11 +348,20 @@ 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},
      * then atomically commits (and computes the content hash). Throws {@link WriteConflictError} if the key
-     * already exists (write-once).
+     * 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;
@@ -366,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';
 /**
@@ -402,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;
@@ -414,9 +444,8 @@ export interface ClearRegistrySummary {
     /** How many ids the generation holds: an integer from 0 to 2^32. */
     readonly cardinality: number;
     /**
-     * The fingerprint of the generation's object, `<size>:<footer checksum>` in decimal, as `CrbmReader.fingerprint` and
-     * a pin's `pinnedAt.fingerprint` spell it: the object's size in bytes, which `stat()` reports, and the CRC32C its
-     * footer stores.
+     * The fingerprint of the generation's object, `<size>:<footer checksum>` in decimal, as a pin's `pinnedAt.fingerprint`
+     * spells it: the object's size in bytes, which `stat()` reports, and the CRC32C its footer stores.
      */
     readonly fingerprint: string;
     /**
@@ -485,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[];
     /**
@@ -495,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`
@@ -502,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
@@ -538,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
@@ -565,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;
@@ -614,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.
@@ -670,8 +715,8 @@ declare const STORAGE_BACKEND_BRAND: unique symbol;
  * Where a store keeps everything: the generations, and the pointer saying which one is current.
  *
  * **Branded on purpose.** The two fields alone are not enough to qualify, and that is the whole point. This
- * shape is also {@link LoadDeps}, so before the brand any `{ storage, registry }`
- * object literal satisfied it — including one assembling halves from two *unrelated* stores, which the store
+ * same two fields are the heart of the deps core's standalone functions take, so without the brand any `{ storage, registry }`
+ * object literal would satisfy it — including one assembling halves from two *unrelated* stores, which the store
  * accepted and then answered **empty** for a segment that holds data, because it read a pointer from a place
  * nothing had ever been written. That is the exact silent-empty failure one-class-per-backend exists to
  * remove, and it was reachable in five lines.
@@ -700,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.
@@ -749,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.
@@ -779,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
@@ -792,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>;