@cloudbitmaps/core 0.21.0 → 0.22.0

package/dist/core/bit-route.d.ts

@@ -1,3 +1,8 @@
+/**
+ * BitRouteSplitter — maps a 32-bit id to its chunk (top 16 bits) and remainder
+ * (bottom 16 bits), per the data model.
+ */
+import { ValidationError } from './errors.js';
 export declare const U32_MAX = 4294967295;
 export declare const CHUNK_COUNT = 65536;
 interface BitRoute {
@@ -6,6 +11,8 @@ interface BitRoute {
     /** Bottom 16 bits — the value within the chunk (0..65535). */
     readonly remainder: number;
 }
+/** Was `err` thrown by {@link splitId} for an id outside the u32 range? */
+export declare function isBadIdError(err: unknown): err is ValidationError;
 /** Split a u32 id into `{ chunkKey, remainder }`. Throws `ValidationError` for non-u32 input. */
 export declare function splitId(id: number): BitRoute;
 /**

package/dist/core/codec.d.ts

@@ -103,7 +103,7 @@ export interface CodecBitmap {
     /**
      * This set as storage chunks: ascending by chunk key, empty chunks left out, each payload exactly the bytes that
      * {@link CodecInterface.fromValues} of that chunk's low 16 bits, then {@link optimize}, then {@link serialize}
-     * would give. So a generation written from these is byte for byte the one the same ids write. It may re-encode
+     * would give. So a generation written from these holds chunk for chunk what the same ids write. It may re-encode
      * this bitmap in place first, as `optimize()` does; membership is untouched.
      *
      * **Flavor-author surface, and optional.** A load from a bitmap or from serialized bytes writes these, never

package/dist/core/combine-expr.d.ts

@@ -1,10 +1,14 @@
-/** A string names an operand; a node holds exactly one operator over a non-empty list of expressions. */
-export type CombineExpr = string | {
-    and: CombineExpr[];
+/**
+ * An expression over the operands of a batch combine (a store's `materializeMany`): a string names an operand; a node
+ * holds exactly one of `and`, `or` or `andNot` over a non-empty list of expressions. `andNot` subtracts every entry after
+ * the first from the first, so it takes at least two. Plain JSON, so it can be logged and sent between tasks.
+ */
+export type Expr = string | {
+    and: Expr[];
 } | {
-    or: CombineExpr[];
+    or: Expr[];
 } | {
-    andNot: CombineExpr[];
+    andNot: Expr[];
 };
 /** The most operator nodes one expression may nest. A literal that contains itself is refused by it. */
 export declare const MAX_EXPR_DEPTH = 64;

package/dist/core/combine-feed.d.ts

@@ -1,6 +1,14 @@
 import type { CodecBitmap, CodecInterface } from './codec.js';
-/** One record of a feed: the ids each named operand holds at one chunk key. */
-export interface CombineManyFeedRecord {
+/**
+ * One record of the feed of a batch combine (a store's `materializeMany`): the ids some of the fed operands hold at one
+ * chunk key. `key` is `id >>> 16`, an integer from 0 to 65,535, never below the previous record's; a key may arrive as
+ * several consecutive records, each carrying some of the operands, and one record per key is the usual shape. `operands`
+ * maps a declared fed name to its ids at the key: a real `Uint32Array` (not an `Int32Array`, `Buffer`, array or
+ * look-alike), strictly ascending, every id inside the key. A name is given at most once per key, and an empty array is
+ * the same as leaving the name out. The record is copied as it arrives, so the caller may drop or reuse its arrays once
+ * it has yielded it.
+ */
+export interface MaterializeManyFeedRecord {
     /** The chunk key, `id >>> 16`, from 0 to 65,535. Non-decreasing over the feed; a key may arrive as several records. */
     readonly key: number;
     /** Ids by operand name: ascending, unique, every one inside `key`. An operand is named at most once per key. */
@@ -11,7 +19,7 @@ export interface CombineManyFeed {
     /** The fed operand names, declared up front. */
     readonly names: readonly string[];
     /** The records, read once, in key order. */
-    readonly records: AsyncIterable<CombineManyFeedRecord>;
+    readonly records: AsyncIterable<MaterializeManyFeedRecord>;
     /**
      * The ids each fed operand holds over the whole feed, keyed by exactly `names`: an object, or a function called once
      * after the last record. A count that differs from what the feed held refuses every fed output.

package/dist/core/combine-many.d.ts

@@ -1,14 +1,14 @@
 import type { CodecBitmap, CodecInterface } from './codec.js';
 import type { IMetricsSink } from './metrics.js';
 import type { CombineManyFeed } from './combine-feed.js';
-import type { CombineExpr } from './combine-expr.js';
+import type { Expr } from './combine-expr.js';
 import type { Clock } from './determinism.js';
 import type { Budget } from './budget.js';
 import type { LoadGuard } from './load.js';
 import type { GenerationMetadata, SegmentRef, StorageChunkSource } from './ports.js';
-export type { CombineExpr } from './combine-expr.js';
+export type { Expr } from './combine-expr.js';
 export { MAX_EXPR_DEPTH, MAX_EXPR_NODES } from './combine-expr.js';
-export type { CombineManyFeed, CombineManyFeedRecord } from './combine-feed.js';
+export type { CombineManyFeed, MaterializeManyFeedRecord } from './combine-feed.js';
 /** The range requests a pass keeps in flight at once across all its operands, inside a client's socket pool. */
 export declare const MAX_RANGES_IN_FLIGHT = 64;
 /** One named stored operand, as the pass reads it. */
@@ -48,9 +48,9 @@ export interface CombineManyOperand {
 }
 /** What one output asks for. */
 export interface CombineManyOutput<R> {
-    readonly expr: CombineExpr;
+    readonly expr: Expr;
     /** Subtracted from the result: a root `andNot`. */
-    readonly exclude?: readonly CombineExpr[];
+    readonly exclude?: readonly Expr[];
     readonly allowEmpty?: boolean;
     readonly guard?: LoadGuard;
     readonly metadata?: GenerationMetadata;
@@ -126,8 +126,8 @@ export type CombineManyOutcome<R> = {
     readonly ok: false;
     readonly error: unknown;
 };
-/** What the call did to one operand. */
-export interface CombineManyOperandStats {
+/** What a batch combine (a store's `materializeMany`) did to one operand: see {@link MaterializeManyStats.operands}. */
+export interface MaterializeManyOperandStats {
     /** Whether an output of the call read it. An operand no output names is not read. */
     readonly read: boolean;
     /** Whether the operand was read at a pinned generation. */
@@ -155,8 +155,8 @@ export interface CombineManyOperandStats {
     /** Chunk reads made of it, over all groups. */
     readonly chunkReads: number;
 }
-/** What the call did to one output. */
-export interface CombineManyOutputStats {
+/** What a batch combine (a store's `materializeMany`) did to one output: see {@link MaterializeManyStats.outputs}. */
+export interface MaterializeManyOutputStats {
     /** The names of the operands its expression reads: the stored ones in call order, then the fed ones in `feed.names` order. */
     readonly operands: readonly string[];
     /** The group that computed it (from 0), or `null` when it never ran. */
@@ -171,7 +171,11 @@ export interface CombineManyOutputStats {
     /** The most its buffer held resident, in the ledger's own measure; compare with `boundBytes` to see how tight a plan was. */
     readonly peakBytes: number;
 }
-export interface CombineManyStats {
+/**
+ * What a batch combine (a store's `materializeMany`) did: the groups it ran, its requests by class, the chunk-read budget
+ * it used, the most it held resident, and, for each operand, the generation it was pinned at, began at and ended at.
+ */
+export interface MaterializeManyStats {
     /** Groups run, the re-runs of outputs a lying index made too big included. */
     readonly groups: number;
     readonly requests: {
@@ -233,12 +237,12 @@ export interface CombineManyStats {
         readonly ids: number;
     };
     /** By operand name, an object with no prototype, so any name is a key. */
-    readonly operands: Readonly<Record<string, CombineManyOperandStats>>;
-    readonly outputs: readonly CombineManyOutputStats[];
+    readonly operands: Readonly<Record<string, MaterializeManyOperandStats>>;
+    readonly outputs: readonly MaterializeManyOutputStats[];
 }
 export interface CombineManyRun<R> {
     readonly outputs: readonly CombineManyOutcome<R>[];
-    readonly stats: CombineManyStats;
+    readonly stats: MaterializeManyStats;
 }
 /** A request that passed every check that needs no I/O: what {@link runCombineMany} runs. */
 export interface CompiledCombineMany<R> {

package/dist/core/determinism.d.ts

@@ -42,7 +42,8 @@ export interface Rng {
 }
 /**
  * Injected entropy: `length` cryptographically strong random bytes, for an identity that must never repeat (a
- * registry row's incarnation id, and the random part every registry write adds to its token). Deliberately not an
+ * registry row's incarnation id, the random part every registry write adds to its token, and a generation's write
+ * identity, the 12 bytes a cleartext object's footer carries). Deliberately not an
  * {@link Rng}: an `Rng` is seedable for simulation, and a seeded source hands every process the same "random"
  * identity. Production wiring uses the platform's Web Crypto; a test injects a deterministic source to replay a run.
  */

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

@@ -48,8 +48,8 @@
  * where the truth was to re-run.
  *
  * Which reason comes from **re-reading the row**, not from assuming a supersession: a moved pointer is
- * `'superseded'`, a tombstoned row `'destroyed'`, a purged row `'absent'`, a row with no pointer
- * `'no-generation'`. A pointer still on `from` means the object it names is genuinely gone — the forbidden
+ * `'superseded'`, a tombstoned row `'destroyed'`, a purged row `'absent'`, a row that lost its pointer
+ * `'superseded'` too (its bucket was not searched, so no claim about it is made; a re-run searches it). A pointer still on `from` means the object it names is genuinely gone — the forbidden
  * `missing-storage-generation` state — or is another object than the row's summary names by its fingerprint, and that
  * throws, because no re-run fixes either. That `NotFoundError` is the only signal of those states, so a faulting
  * re-read rethrows it rather than replacing it with a transient-looking registry error.
@@ -102,7 +102,7 @@
 import { type IAuditSink } from './audit.js';
 import type { CodecInterface } from './codec.js';
 import type { Yielder } from './cooperative.js';
-import type { Rng } from './determinism.js';
+import type { Entropy, Rng } from './determinism.js';
 import type { IKeystore } from './crypto.js';
 import type { IStorageDriver, IRegistryDriver, SegmentRef } from './ports.js';
 import { type ReadRetry } from './retry.js';
@@ -148,6 +148,13 @@ export interface EraseIdDeps {
      * renewal. 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 rewrite's identity: 12 random bytes its footer carries when the segment is cleartext (an encrypted
+     * rewrite carries its index's AEAD nonce), so the rewrite is not the same object as a load of the same ids at its
+     * number. Required: an erasure without one (a JavaScript caller can leave it out) is refused with
+     * {@link ValidationError} before any read, keystore call, delete or write, even when it would find nothing to rewrite.
+     */
+    readonly entropy: Entropy;
     /** Per-chunk decode ceiling (invariant 5); defaults to 1 MiB. The `.crbm` reader refuses an entry above its own `maxPayloadBytes` (1 MiB, plus 28 bytes when encrypted) at open, so raise that on the chunk source too. */
     readonly maxBitmapBytes?: number;
     /**
@@ -170,8 +177,9 @@ export interface EraseIdResult {
     readonly erased: boolean;
     /**
      * Why the id was not erased, when `erased` is false. `'absent'` (no registry row), `'destroyed'` (a crypto-shred
-     * tombstone — already unreadable), `'no-generation'` (a row with no generation yet: its bucket can hold first loads'
-     * objects, none of them found to hold the id, and `collected` names any this call deleted unsearched, see below),
+     * tombstone — already unreadable), `'no-generation'` (a row with no generation yet when the call read it, its first
+     * read: its bucket can hold first loads' objects, none of them found to hold the id, and `collected` names any this
+     * call deleted unsearched, see below),
      * `'not-member'` (no
      * generation in the bucket holds the id — the common case across a fleet scan — with the same note on `collected`),
      * or `'superseded'`.
@@ -188,10 +196,12 @@ export interface EraseIdResult {
      * another erasure of the *same* id, the re-run reports `'not-member'` because it is already gone. Either way the
      * re-run settles it, which is why it is the documented action for this reason and for no other.
      *
-     * The first three reasons are also returned when the row changes *underneath* a call already in flight, not
+     * `'absent'` and `'destroyed'` are also returned when the row changes *underneath* a call already in flight, not
      * only when it is read up front — a concurrent `dropSegment` gives `'destroyed'`, once the tombstone's objects have
-     * been searched as a fresh call searches them, and a retention sweep that purges the row gives `'absent'`. A caller
-     * branching on `reason` never has to care which it was.
+     * been searched as a fresh call searches them, and a retention sweep that purges the row gives `'absent'`.
+     * `'no-generation'` is only the answer to a row read with no generation: a row that loses its pointer *after* the
+     * call found one (a purge and re-creation, or a hand-made write) is `'superseded'`, because the call found a holder
+     * in that bucket and stopped before deleting it, and a re-run searches it again.
      */
     readonly reason?: 'absent' | 'destroyed' | 'no-generation' | 'not-member' | 'superseded';
     /**

package/dist/core/erasure.d.ts

@@ -57,7 +57,7 @@ export declare function destroySegment(ref: SegmentRef, deps: EraseDeps, options
  * Returns a per-segment result (skips cleartext segments unless `allowCleartext`).
  *
  * **Bounded.** It lists the whole namespace before it destroys anything, and holds the listing resident, so the
- * listing is capped at `maxScanSegments` (default {@link DEFAULT_MAX_SCAN_SEGMENTS}, 250,000), the ceiling every
+ * listing is capped at `maxScanSegments` (default 250,000), the ceiling every
  * other fleet scan keeps. A namespace over it throws `BudgetExceededError` **before any segment is destroyed**,
  * never part-way through; raise `maxScanSegments` when the namespace really is that large and the memory is there.
  * A `maxScanSegments` that is not a safe whole number of at least 1 throws `ValidationError`, again before anything is destroyed.

package/dist/core/errors.d.ts

@@ -15,14 +15,14 @@
  * does not match — and silently, because a `catch` that stops matching just falls through, defeating
  * transient retry and the publish path's conflict handling with no error of its own.
  *
- * `Symbol.for` is identity-stable across copies, bundles and realms, so classify errors with the exported
- * predicates below (never `instanceof`) anywhere an error may cross that boundary.
+ * `Symbol.for` is identity-stable across copies, bundles and realms, so classify errors with `errorKind`
+ * (never `instanceof`) anywhere an error may cross that boundary.
  */
 declare const ERROR_BRAND: unique symbol;
 declare const TRANSIENT_BRAND: unique symbol;
 /** Base class for every error CloudRoaring throws. */
 export declare class CloudRoaringError extends Error {
-    /** Cross-bundle brand — see the predicates ({@link isCloudRoaringError}, …). Non-enumerable-ish (symbol key ⇒ not in JSON). */
+    /** Cross-bundle brand — see {@link errorKind}. Non-enumerable-ish (symbol key ⇒ not in JSON). */
     readonly [ERROR_BRAND]: true;
     constructor(message: string);
 }
@@ -33,6 +33,8 @@ export declare class CloudRoaringError extends Error {
  */
 export declare class ValidationError extends CloudRoaringError {
 }
+/** What a contention {@link WriteConflictError} ends with: the call is safe to run again. */
+export declare const CONTENTION_NEXT_STEP = "; another writer changed the segment's row while this call ran. Re-run the call: it reads the row afresh";
 /** An OCC conditional write/delete lost the race — the row changed since it was read. */
 export declare class WriteConflictError extends CloudRoaringError {
 }
@@ -97,14 +99,46 @@ export declare class UnsupportedError extends CloudRoaringError {
 export declare class CapabilityError extends CloudRoaringError {
 }
 /**
- * An operation would exceed its per-op **denial-of-wallet budget** — too many backend requests for a single
- * `count`/`iterate`/`intersect`/`subjectReport`/`eraseSubject` call — so it is refused **before** fanning out
- * (hard invariant 6). Default-on but generous (normal ops never hit it); tune it
- * per store (`budget`) or per op, or disable with `budget: false`. Deterministic (never retried): the op is too
- * big by policy, not by luck. Each request's bytes are separately capped (the safe-deserialize ceiling), so
- * bounding the request count transitively bounds bytes. Carries the projected count + the limit, never data.
+ * An operation would exceed one of its per-op **denial-of-wallet bounds** — too many backend requests
+ * (`budget.maxRequests`), too many bytes held at once by a combine (`maxBufferedBytes`), or too many registry rows
+ * in a scan (`maxScanSegments`) — so it is refused, before the fan-out where it can be known beforehand (hard
+ * invariant 6). Default-on but generous (normal ops never hit it); tune each per store or per op, or disable the
+ * request budget with `budget: false`. Deterministic (never retried): the op is too big by policy, not by luck.
+ * Each request's bytes are separately capped (the safe-deserialize ceiling), so bounding the request count
+ * transitively bounds bytes.
+ *
+ * Carries an option name and two numbers, and no data: `option` names the option to raise, `limit` is the bound in
+ * force, and `spent` is what the call had reached when it was refused. What `spent` measures depends on `option`:
+ *
+ * - `'budget.maxRequests'`: the requests the call needs, which raising the option to it lets through. For a plan, it
+ *   is the planned reads (with the reads already taken, when a run plans again); an enumeration that
+ *   stops at the bound reports `limit + 1`, a lower bound.
+ * - `'maxBufferedBytes'`: a **lower bound** on the bytes the call needs resident: what it held plus what it asked
+ *   for at the moment it was refused. Raising the limit to `spent` can be refused again, further on, because the
+ *   call had not finished growing. The one figure that lets an output through is the per-output refusal's, which
+ *   the message gives as "raise maxBufferedBytes to at least N". Otherwise raise the limit with room to spare, or
+ *   split the outputs across calls.
+ * - `'maxScanSegments'`: `limit + 1`, a lower bound: the scan stops at the first row past the bound (for the retention
+ *   sweep's due-index scan, the first due-index pointer, unread, which may be stale), so it never learns the fleet's
+ *   size.
+ *
+ * The message states the same limit.
  */
 export declare class BudgetExceededError extends CloudRoaringError {
+    /** The option to raise to let the call through. */
+    readonly option: 'budget.maxRequests' | 'maxBufferedBytes' | 'maxScanSegments';
+    /** The bound in force: requests, bytes or rows, by `option`. */
+    readonly limit: number;
+    /**
+     * What the call had reached when refused. By `option`: the requests the call needs (`'budget.maxRequests'`), a
+     * lower bound on the resident bytes it needs (`'maxBufferedBytes'`), or `limit + 1` (`'maxScanSegments'`).
+     */
+    readonly spent: number;
+    constructor(message: string, details: {
+        readonly option: 'budget.maxRequests' | 'maxBufferedBytes' | 'maxScanSegments';
+        readonly limit: number;
+        readonly spent: number;
+    });
 }
 /**
  * An encrypted segment's data key (DEK) cannot be unwrapped because the keystore holds none of the
@@ -164,4 +198,14 @@ export declare function isCapabilityError(err: unknown): err is CapabilityError;
 export declare function isBudgetExceededError(err: unknown): err is BudgetExceededError;
 /** No key the keystore holds can unwrap an encrypted segment's data key. */
 export declare function isKeyUnavailableError(err: unknown): err is KeyUnavailableError;
+/** The name of one of the library's error classes, as `errorKind` returns it. */
+export type ErrorKind = 'CloudRoaringError' | 'ValidationError' | 'WriteConflictError' | 'IntegrityError' | 'NotFoundError' | 'UnsupportedError' | 'CapabilityError' | 'TransientError' | 'KeyUnavailableError' | 'BudgetExceededError' | 'LeaseExpiredError' | 'LeaseLimitError' | 'StaleOperandError';
+/**
+ * Which of the library's error classes `err` is, or `undefined` when it is none of them. Works on every copy of
+ * the package, every bundle and every realm, where `instanceof` can silently stop matching: it reads the
+ * `Symbol.for` brands and the error's `name`. An application's own subclass of one class returns
+ * `'CloudRoaringError'`, except a subclass of `TransientError`, which returns `'TransientError'`; an error
+ * cloned out of a worker (the brand is gone) returns `undefined`.
+ */
+export declare function errorKind(err: unknown): ErrorKind | undefined;
 export {};

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,6 +138,7 @@ 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 bounds a guard can refuse a generation for: every {@link LoadRefusal} but a lost race. */
@@ -141,7 +161,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'
 /**
@@ -152,10 +172,14 @@ export type LoadRefusal = 'empty' | 'min-cardinality' | 'min-retained' | 'max-gr
  * 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.
+ * 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 +193,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 +230,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,7 +133,7 @@ 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 {
     onEvent(event: MetricEvent): void;

package/dist/core/ports.d.ts

@@ -334,7 +334,9 @@ export interface IStorageDriver {
     /**
      * 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.
      */
     putImmutable(key: GenKey, write: (sink: BlobSink) => Promise<void>): Promise<{
         size: number;
@@ -414,9 +416,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;
     /**
@@ -670,8 +671,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.

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

@@ -15,11 +15,6 @@ export declare function drainRegistry(registry: IRegistryDriver, options: {
     namespace?: string;
     maxScanSegments: number;
     op: string;
-    /**
-     * How a caller of `op` raises the ceiling, completing "Narrow it with `namespace`, or …" in the refusal.
-     * Defaults to raising `maxScanSegments`, which is right wherever `op` takes that option itself.
-     */
-    raise?: string;
     /**
      * Whether the caller could scope the scan down to a `namespace`. Defaults to true; `eraseNamespace` is already
      * one namespace, so it passes false and the refusal does not tell it to narrow what it cannot.

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

@@ -163,7 +163,7 @@ export interface RetireExpiredResult {
      *
      * A refused purge is not charged to `limit`, so retirements go on: a tombstone that cannot be purged does not hold
      * the segments behind it past their expiry. **Purging stops for the rest of the call after
-     * {@link MAX_CONSECUTIVE_PURGE_FAULTS} (3) refused purges in a row**, and a purge that succeeds starts the count
+     * 3 refused purges in a row**, and a purge that succeeds starts the count
      * again. A blanket refusal therefore costs three attempts a call, and a refusal particular to one row (a blob with a
      * snapshot, an object under a legal hold) holds nothing behind it. The next call tries again. Check this field; a
      * ledger entry for each is `skipped`, but a caller that reads only `retired` sees none of it.

package/dist/core/retention.d.ts

@@ -59,7 +59,7 @@ export declare function withoutSweepMark(meta: GovernanceMeta | undefined): Gove
  * The three-way answer exists so a fleet sweep can *report* a malformed policy instead of choosing between two
  * bad options: treating it as "no policy" hides an operator error on a segment someone believes is expiring, and
  * throwing aborts a ledger over one bad row. Nothing writes an invalid policy through
- * {@link setSegmentRetention} — hand-edited rows, an older/newer writer, or a restore are how it happens.
+ * `store.setRetention` — hand-edited rows, an older/newer writer, or a restore are how it happens.
  */
 export declare function readRetentionPolicy(meta: GovernanceMeta | undefined): RetentionPolicy | null | 'invalid';
 /** The stored policy for one segment, or `null` if it has none (and `'invalid'` for a malformed one). */

package/dist/core/retry.d.ts

@@ -1,4 +1,8 @@
 import type { Clock, Rng } from './determinism.js';
+/**
+ * How the store retries a transient read: attempts, exponential backoff with a cap, and jitter. By default 4 attempts,
+ * a 50 ms base delay, ×2, a 2 s cap and full jitter; the store's `retry` option overrides them a field at a time.
+ */
 export interface RetryPolicy {
     /** Total attempts including the first (so `maxAttempts: 4` = 1 try + 3 retries). Must be ≥ 1. */
     readonly maxAttempts: number;

package/dist/core/rollback.d.ts

@@ -51,6 +51,7 @@ export interface GenerationEntry {
  * carries the id count and metadata its row records, from the same read.
  */
 export declare function listGenerations(ref: SegmentRef, deps: GenerationListDeps): Promise<GenerationEntry[]>;
+/** What a rollback moved: the generation the pointer named before, and the one it names now. */
 export interface RollbackResult {
     /** The generation the pointer named before the rollback. `null` when the segment had no current generation. */
     readonly fromGeneration: number | null;

package/dist/driver-kit.d.ts

@@ -1,7 +1,12 @@
 export type { GenKey, IRegistryDriver, IStorageDriver, SegmentRef, StorageBackend, StorageCaps, StorageDeleteOptions, TailRead, } from './core/ports.js';
 export { brandAsBackend, STORAGE_BACKEND } from './core/ports.js';
-export type { IMetricsSink, MetricEvent } from './core/metrics.js';
-export { IntegrityError, isIntegrityError, isNotFoundError, isTransientError, isValidationError, isWriteConflictError, NotFoundError, TransientError, ValidationError, WriteConflictError, } from './core/errors.js';
+export type { ClearRegistrySummary, GenerationMetadata, GovernanceMeta, KnownGeneration, LeaseEntry, NewRegistryRecord, RegCaps, RegistryPatch, RegistryRecord, RegistryStatus, RegistrySummary, RegistryWriteOptions, SealedRegistrySummary, Token, } from './core/ports.js';
+export type { ChunkRead, ChunkRef, GenerationSummary, ReadChunksOptions, SegmentSize, StorageChunkSource, } from './core/ports.js';
+export type { Aead, AeadSealed, IKeystore, WrappedDek } from './core/crypto.js';
+export type { Entropy } from './core/determinism.js';
+export type { IMetricsSink, MetricEvent, MetricOpName } from './core/metrics.js';
+export { CloudRoaringError, errorKind, IntegrityError, NotFoundError, TransientError, ValidationError, WriteConflictError, } from './core/errors.js';
+export type { ErrorKind } from './core/errors.js';
 export { RESOLVED_FIELDS, pointerIdOf, renewPointer, renewsPointer } from './core/pointer-id.js';
 export { validateSegmentRef } from './core/validate.js';
 export type { BlobSink } from './core/blob.js';