@cloudbitmaps/core 0.22.0 → 0.24.0

package/dist/core/errors.d.ts

@@ -24,6 +24,7 @@ declare const TRANSIENT_BRAND: unique symbol;
 export declare class CloudRoaringError extends Error {
     /** Cross-bundle brand — see {@link errorKind}. Non-enumerable-ish (symbol key ⇒ not in JSON). */
     readonly [ERROR_BRAND]: true;
+    /** Builds the error from `message`, and sets `name` to the class's name as written. */
     constructor(message: string);
 }
 /**
@@ -59,6 +60,7 @@ export declare class LeaseExpiredError extends CloudRoaringError {
     readonly until: number;
     /** `'expired'` when the clock reached `until`, `'released'` after `release()`. */
     readonly reason: 'expired' | 'released';
+    /** Builds the error from its `message`, the epoch-ms the lease ran until, and why it ended. */
     constructor(message: string, until: number, reason: 'expired' | 'released');
 }
 /**
@@ -75,11 +77,13 @@ export declare class LeaseLimitError extends CloudRoaringError {
  * `'stale-operand'`. Deterministic: run the call again against the current operand.
  */
 export declare class StaleOperandError extends CloudRoaringError {
+    /** The stable code `'stale-operand'`, to match on. */
     readonly code: "stale-operand";
     /** The operand's name in the call that found it stale. */
     readonly operand: string;
     /** Why it is stale. */
     readonly reason: 'moved' | 'erased';
+    /** Builds the error from its `message`, the operand's name and why it is stale. */
     constructor(message: string, operand: string, reason: 'moved' | 'erased');
 }
 /**
@@ -134,6 +138,7 @@ export declare class BudgetExceededError extends CloudRoaringError {
      * lower bound on the resident bytes it needs (`'maxBufferedBytes'`), or `limit + 1` (`'maxScanSegments'`).
      */
     readonly spent: number;
+    /** Builds the error from its `message` and the `option`, `limit` and `spent` it reports. */
     constructor(message: string, details: {
         readonly option: 'budget.maxRequests' | 'maxBufferedBytes' | 'maxScanSegments';
         readonly limit: number;
@@ -166,6 +171,7 @@ export declare class KeyUnavailableError extends CloudRoaringError {
 export declare class TransientError extends CloudRoaringError {
     /** A second brand so a transient fault is classifiable cross-bundle. */
     readonly [TRANSIENT_BRAND]: true;
+    /** Builds the error from `message`; `options.cause`, when given, is kept as `cause`. */
     constructor(message: string, options?: {
         cause?: unknown;
     });
@@ -174,6 +180,30 @@ export declare class TransientError extends CloudRoaringError {
 export declare function isCloudRoaringError(err: unknown): err is CloudRoaringError;
 /** An OCC conditional write/delete lost the race — retry the read-modify-write, don't fail. */
 export declare function isWriteConflictError(err: unknown): err is WriteConflictError;
+/**
+ * A {@link WriteConflictError} for a registry `create` or `compareAndSwap` that may have landed before it met the
+ * conflict, so the conflict does not prove the write was refused. Throw it for every conflict of a write your backend's
+ * client may have sent more than once and that you cannot prove did not land: the read-back finds another writer's
+ * write over the row (a row is overwritten, so that writer may have swapped in over this write after it landed), or
+ * finds the row gone, or the compare-and-swap itself is answered that the row is gone. Throw a plain
+ * `WriteConflictError` for a conflict that does prove it: a write sent once, or a check your driver made before sending
+ * anything. A registry that wraps another rethrows the conflict it was given, not a new one, which would lose the mark.
+ *
+ * It is a `WriteConflictError` in every other way: `errorKind` names it `'WriteConflictError'`, `instanceof` holds on
+ * the same copy of the package, and every caller that handles a conflict handles it. A load's publish reads the row
+ * again, as after any conflict, and takes the write as its own when the row shows it there. Otherwise the write is
+ * reported to the load, as a write with no answer is, so a load refused after it carries `unanswered: true` on its
+ * `segment.load-refused` audit event. The mark is a registered `Symbol.for` brand, read
+ * across copies of the package. It is lost when the error is cloned or copied into a new one, and a conflict raised
+ * anywhere but a registry write is read as the plain conflict it also is.
+ */
+export declare function unsettledConflict(message: string): WriteConflictError;
+/**
+ * Whether `err` is a conflict a driver raised with {@link unsettledConflict}: a {@link WriteConflictError}, by brand
+ * and name as {@link isWriteConflictError} reads it, that carries the unsettled mark. It reads the registered brand,
+ * so it holds for an error from another copy of the package. Like the other predicates, no entry exports it.
+ */
+export declare function isUnsettledConflict(err: unknown): boolean;
 /** A retryable transient infrastructure fault. The retry layer keys on this. */
 export declare function isTransientError(err: unknown): err is TransientError;
 /** A read came after its pin's lease ended. */

package/dist/core/leases.d.ts

@@ -40,9 +40,11 @@ export declare function liveLeases(record: RegistryRecord | null, now: number):
  * Both are optional; without a sleep a retry follows at once.
  */
 export interface ChurnDeps {
+    /** The clock whose `sleep` waits out lease churn. Without a `sleep`, a retry follows at once. */
     readonly clock?: {
         readonly sleep?: (ms: number) => Promise<void>;
     } | undefined;
+    /** The source that spreads each wait over a share of its bound. Without one, each wait is its whole bound. */
     readonly rng?: Rng | undefined;
 }
 /**

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

@@ -17,7 +17,12 @@ import type { CombinedChunk } from './engine.js';
  * (`getSerializationSizeInBytes`) is asked first, so one over the cap is refused before it is serialized.
  */
 export interface PortableBitmap {
+    /** The bitmap in the portable Roaring format. */
     serialize(format: 'portable'): Uint8Array;
+    /**
+     * The size in bytes of `serialize('portable')`, when the bitmap can say without serializing. A load asks it first, so
+     * an input over the size cap is refused before it is serialized.
+     */
     getSerializationSizeInBytes?(format: 'portable'): number;
 }
 /**
@@ -53,6 +58,49 @@ export declare class ChunkLoadInput {
     readonly chunks: AsyncIterable<CombinedChunk>;
     constructor(chunks: AsyncIterable<CombinedChunk>);
 }
+/**
+ * Mark `err` as raised by a load's input (its ids, a bitmap's encoding, a combine's chunks) rather than by the write,
+ * and return it. A write-once conflict is a lost race only when the write raised it: a source that reads another
+ * segment (through a pin, say) can throw this library's own `WriteConflictError`, which is the source's to report.
+ */
+export declare function raisedBySource<T>(err: T): T;
+/** Whether a load's input raised `err` ({@link raisedBySource}). */
+export declare function isSourceError(err: unknown): boolean;
+/**
+ * Ids the caller says ascend (`sorted: true`), written chunk by chunk while they are read, during the object's upload,
+ * so a load holds one chunk and the writer's index rather than the whole generation. Made only by
+ * {@link sortedLoadInput}, from ids.
+ *
+ * The first error the ids raise, or their check raises (an id out of range, or lower than the one before it), or the
+ * chunker raises building a chunk, is kept here, and the load throws that same error. The driver's upload never sees
+ * it: the chunker throws a sentinel of its own into the writer instead, so no driver maps, redacts or probes the
+ * caller's error on its way out.
+ */
+export declare class SortedLoadInput {
+    readonly ids: Iterable<number> | AsyncIterable<number>;
+    private failure;
+    constructor(ids: Iterable<number> | AsyncIterable<number>);
+    /** Keep `error` as what the ids raised, unless an earlier one is kept. */
+    fail(error: unknown): void;
+    /** What the load throws for a write that failed with `err`: the error the ids raised, when they raised one. */
+    thrown(err: unknown): unknown;
+}
+/**
+ * Whether a load was asked for `sorted: true`. `undefined` and `false` mean no; anything else that is not a boolean is
+ * refused before any request, since `sorted: 'yes'` read as absent would hold the whole generation in memory instead.
+ *
+ * @throws {ValidationError} for a value that is not a boolean.
+ */
+export declare function wantsSorted(sorted: unknown): boolean;
+/**
+ * The input a load reads under its `sorted` option: ids as {@link SortedLoadInput} when it is `true`, anything else
+ * unchanged.
+ *
+ * @throws {ValidationError} for a `sorted` that is not a boolean, and for `sorted: true` with `{ serialized }`,
+ * `{ bitmap }` or a bitmap of the flavor's own: those are written from their own chunks already, so the option would
+ * do nothing, and an option that does nothing is refused rather than ignored.
+ */
+export declare function sortedLoadInput(prepared: ReturnType<typeof prepareLoadInput>, sorted: unknown): ReturnType<typeof prepareLoadInput> | SortedLoadInput;
 /**
  * Check a load's input and decode a bitmap input, before the load makes any request.
  *
@@ -71,6 +119,6 @@ export declare function prepareLoadInput(input: LoadInput, codec: CodecInterface
  * are copied first. An empty or detached buffer is the empty bitmap.
  *
  * @param what names the input in a refusal's message.
- * @throws {ValidationError} for anything that is not such bytes; nothing reaches the codec's native decoder then.
+ * @throws {ValidationError} for anything that is not such bytes; nothing reaches the codec's decoder then.
  */
 export declare function decodeSerialized(bytes: unknown, codec: CodecInterface, what?: string): CodecBitmap;

package/dist/core/load.d.ts

@@ -140,6 +140,26 @@ export interface LoadOptions {
     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 bitmap itself (an
+     * iterable with a `serialize` method, which a flavor loads as `{ bitmap }`), 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'>;
@@ -170,8 +190,9 @@ 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
+ * 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.
  */

package/dist/core/metrics.d.ts

@@ -136,6 +136,10 @@ export type MetricEvent = {
  * 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,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>;