@cloudbitmaps/core 0.21.0 → 0.23.0

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

@@ -5,9 +5,10 @@
  * There is no per-id delete on an immutable object, and there is no mutable tier to hold a tombstone, so erasure
  * is what every other write in this library is: a new generation. The current generation is streamed chunk by
  * chunk through the ascending writer — every chunk decoded, range-checked and re-encoded, the one holding the id
- * with that bit cleared — then published fenced on the generation it streamed, and that generation is collected immediately
- * (`keep: 0`), so the bit is **physically gone from the bucket when this returns**. Bounded memory: a window of 32
- * chunk reads ahead of the writer, never the whole segment.
+ * with that bit cleared — then published fenced on the generation it streamed, and that generation is collected
+ * immediately (`keep: 0`), so when it answers `erased: true` the bit is **physically gone from the bucket when this
+ * returns** (a noncurrent version, a replica or a backup keeps the old object until its own lifecycle removes it).
+ * Bounded memory: a window of 32 chunk reads ahead of the writer, never the whole segment.
  *
  * The rewrite is the same generation without one id, so it keeps everything else: the new object carries the source's
  * metadata as it is, and the row's summary of it, built from what was written, counts one id fewer and holds the same
@@ -21,12 +22,17 @@
  * leaves generations above the pointer that were once current and can be made current again, so a holder can sit
  * above the pointer as well as below it, and there can be several. Before it reports `erased: true` the call
  * therefore lists the bucket once more and reads every generation it has not already seen to be clean; any that
- * still holds the id makes it report or throw instead. In the ordinary case that list returns one generation, the
- * current one, and costs one `list`.
+ * still holds the id makes it report or throw instead. A number can be taken again once its object is deleted, so a
+ * generation it saw clean is read again too, but for two: the one it found current and its own rewrite, each skipped
+ * only while the row, read after that listing, names it with the footer checksum of the object the call read or wrote.
+ * In the ordinary case that list returns one generation, the current one, which the row names: one `list` and one
+ * read of the row.
  *
  * What it does NOT reach: backups, replicas and noncurrent object versions hold the old object until their own
- * lifecycle removes it. For an at-rest guarantee that survives those, use encryption plus crypto-shred
- * (`destroySegment`), which is per segment — a per-id shred is infeasible because one DEK covers the whole segment.
+ * lifecycle removes it. For an at-rest guarantee that reaches those, use encryption plus crypto-shred
+ * (`destroySegment`), which is per segment — a per-id shred is infeasible because one DEK covers the whole segment —
+ * and is complete once no retained copy of the segment's registry row holds its wrapped key, or every KEK that
+ * wrapped it is destroyed.
  *
  * Concurrency. This is a **read-modify-write**, not a plain forward-only publish, and that distinction is where
  * its correctness lives: the new generation is `from` minus one bit, so it is a valid successor to `from` and to
@@ -36,8 +42,8 @@
  * incarnation of a name, and a name that is retired and re-created restarts at `0`, so the number alone matched
  * a different segment entirely. Anything else — a load that published in the meantime, or another
  * erasure that got there first — is reported as `reason: 'superseded'`, `erased: false`, and the caller re-runs
- * against the new generation. A writer that claims the same generation *number* first surfaces as a
- * `WriteConflictError` (write-once).
+ * against the new generation. So is a writer that claims the same generation *number* first (write-once): the put
+ * is refused with a `WriteConflictError`, which is read here as the lost race it is.
  *
  * The same answer covers the read half, and for the same reason. An erasure collects with `keep: 0`, which takes
  * every generation below its new pointer — so a racing erasure can delete the generation this call is streaming,
@@ -48,8 +54,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 +108,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 +154,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;
     /**
@@ -169,9 +182,10 @@ 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),
+     * Why the id was not erased, when `erased` is false. `'absent'` (no registry row), `'destroyed'` (a tombstone; its
+     * objects are searched first), `'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 +202,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';
     /**
@@ -222,7 +238,7 @@ export interface EraseIdResult {
      * a missing holder as "someone else got there", never as a failure.
      *
      * A call that cannot establish the claim **throws** `WriteConflictError` or the underlying fault rather than
-     * report `erased: true` over bytes that are still there. Four ways that happens: a Storage `delete` fault; a
+     * report `erased: true` over bytes that are still there. Four ways that happens: a Storage `delete` fault the call cannot settle by reading the object back; a
      * collection pass that could not prove the segment was still the same one (which an ordinary retirement landing
      * mid-call is enough to cause); the same refusal on the path where the current generation did not hold the id
      * and nothing was published at all; and a generation still holding the id when the bucket is listed at the end
@@ -232,6 +248,13 @@ export interface EraseIdResult {
      * rewrite discards its own object, when it gets no answer that reading the row can settle, throws the registry's
      * `TransientError`, and that object is not deleted.
      *
+     * A delete that gets no answer is settled by reading its key: gone, it counts as deleted and is listed in
+     * `collected`. Another object under the number, for a delete conditioned on the version searched, is not counted as
+     * deleted: the receipt then rests on the listing of the bucket, and says `erased: true` only when that object does
+     * not hold the id. When that read fails too, or the delete lands after it, the call reports the fault, and a re-run
+     * finds the object gone and lists nothing for the segment: keep the error with the ledger as the record of the
+     * deletion.
+     *
      * A rollback that lands between the call's read of the row and one of its deletes, onto the generation being deleted,
      * leaves the pointer on an object that is gone. The call finds it at its next read of the row, or by reading the row
      * once more after its last delete, and **throws `NotFoundError`** rather than report anything: every read of the
@@ -267,3 +290,13 @@ export interface EraseIdResult {
 export declare function eraseIdFromSegment(ref: SegmentRef, id: number, deps: EraseIdDeps, options?: {
     audit?: IAuditSink;
 }): Promise<EraseIdResult>;
+/** What the search for an id in an object needs of the store: the objects, the codec, and the read bounds. */
+export type SearchDeps = Pick<EraseIdDeps, 'storage' | 'codec' | 'maxBitmapBytes' | 'readRetry'>;
+/**
+ * The newest generation left under a tombstone that holds `id` in the clear, or `null`: the search
+ * {@link eraseIdFromSegment} makes under a tombstone, without its deletes. The caller has read the row as `destroyed`;
+ * this reads no row. It lists the bucket once and opens objects newest first, a few at a time, stopping at the first
+ * that holds the id; an object sealed under a key is no holder. It writes and deletes nothing. A fault on a read is
+ * thrown, after the read retry in `deps.readRetry` (the listing is retried too), never read as "not found".
+ */
+export declare function findIdUnderTombstone(ref: SegmentRef, id: number, deps: SearchDeps): Promise<number | null>;

package/dist/core/erasure.d.ts

@@ -1,33 +1,51 @@
 /**
  * Whole-segment erasure: crypto-shred (`destroySegment`, `eraseNamespace`) and disposal (`dropSegment`).
  *
- * GDPR "right to erasure" on immutable, backed-up storage: you can't delete a `.crbm` object from every
- * backup, but you can **delete its key**. `destroySegment` drops the segment's wrapped DEK(s) from the registry
- * (a CAS to a `destroyed` tombstone) — the encrypted Storage bytes are then permanently unreadable, everywhere,
- * forever. **Immediate + irreversible**, so it's gated behind an explicit confirmation (name the exact
- * segment/namespace). A `destroyed` segment reads as empty (its DEK is gone). Only works on an **encrypted**
- * segment; a cleartext segment has no key to shred.
+ * GDPR "right to erasure" on immutable, backed-up storage: you can't delete a `.crbm` object from every backup, but you
+ * can **delete its key**. `destroySegment` drops the segment's wrapped DEK(s) from its current registry row (a CAS to a
+ * `destroyed` tombstone). Every copy of the encrypted Storage bytes, backups and WORM copies included, is then
+ * unreadable once no retained copy of the row still holds the wrapped key (a noncurrent version, a backup or a
+ * point-in-time copy of the row), or once every KEK that wrapped it is destroyed; until then a registry restore to a
+ * point before the shred makes the segment readable again. **Immediate**, and it cannot be undone through the library
+ * (a registry restore to before it can), so it's gated behind an explicit confirmation (the
+ * segment's name; the namespace is not checked, so build the ref's `namespace` from a value you have checked). A `destroyed` segment reads as empty: no generation resolves through a destroyed row. Only an
+ * **encrypted** segment is crypto-shredded; a cleartext one has no key to shred, and `allowCleartext` tombstones it
+ * with its objects left readable.
  *
- * The tombstone is also the fence every writer respects: a load refuses
- * a `destroyed` row, so a load racing an erasure cannot resurrect the segment. A single id's erasure is a different
- * operation — `eraseIdFromSegment` rewrites the generation without it.
+ * The tombstone is also the fence every writer respects: a load refuses a `destroyed` row, so a load racing an erasure
+ * cannot resurrect the segment. A single id's erasure is a different operation — `eraseIdFromSegment` rewrites the
+ * generation without it.
  */
 import { type IAuditSink } from './audit.js';
 import type { ChurnDeps } from './leases.js';
 import type { IStorageDriver, IRegistryDriver, RegistryRecord, SegmentRef } from './ports.js';
+/**
+ * What the erasure calls need: the registry whose rows they tombstone, and, optionally, the clock and rng they wait out
+ * lease churn with.
+ */
 export interface EraseDeps extends ChurnDeps {
+    /** The registry holding the segments' rows. */
     readonly registry: IRegistryDriver;
 }
+/**
+ * What destroying one segment did: a crypto-shred, a cleartext tombstone (the bytes stay readable), nothing for a
+ * segment already destroyed or absent, or, with `destroyed: false` and a `reason`, a segment left as it was, which may
+ * still hold data. The result of `destroySegment`, and one entry of what `eraseNamespace` returns.
+ */
 export interface DestroyResult {
+    /** The segment's name. */
     readonly segment: string;
+    /** The segment's namespace, or `undefined` for the default one. */
     readonly namespace?: string;
     /** True iff the segment is now a `destroyed` tombstone (incl. the idempotent already-destroyed case). */
     readonly destroyed: boolean;
     /**
      * True iff **this call** performed a genuine crypto-shred — an encrypted segment whose wrapped DEK(s) were
-     * dropped, so its Storage bytes are now permanently unreadable. False for a cleartext tombstone (bytes remain
-     * readable), for the idempotent already-destroyed case, and for an absent segment. This is what the
-     * `segment.erase` audit event keys off — a cleartext "erase" is not an irreversible destruction.
+     * dropped from its current registry row, so its Storage bytes, in any copy, are unreadable once no retained copy
+     * of the row holds the key, or every KEK that wrapped it is destroyed. False for a cleartext tombstone (bytes
+     * remain readable), for the idempotent already-destroyed case, and for an absent segment. This is what the
+     * `segment.erase` audit event keys off — a cleartext "erase" destroys no key. A shred that throws `TransientError`
+     * after its read-back also failed may have landed; its re-run answers `'already'` with `cryptoShredded: false`.
      */
     readonly cryptoShredded: boolean;
     /**
@@ -38,14 +56,20 @@ export interface DestroyResult {
      *
      * The last two come with `destroyed: false` and mean **the segment still holds data**. A namespace erase
      * returns them rather than throwing, so its entries have to be inspected — see {@link eraseNamespace}.
+     *
+     * A shred that throws `TransientError` after its read-back also failed may have landed; its re-run answers
+     * `'already'` with `cryptoShredded: false`.
      */
     readonly reason?: string;
 }
 /**
- * Crypto-shred one segment. **Irreversible.** `confirmSegment` must equal `ref.segment` (a guard against an
- * accidental destroy — you must name the exact segment). A non-encrypted segment is rejected unless you opt in
- * via `allowCleartext` (there's no key to shred; its Storage bytes stay readable — the tombstone only stops the
- * segment resolving).
+ * Crypto-shred one segment. It cannot be undone through the library (a registry restore to a point before it can).
+ * `confirmSegment` must equal `ref.segment` (a guard against an accidental destroy of another name; it checks the
+ * name only, not the namespace, so build the ref's `namespace` from a value you have checked). A non-encrypted segment is rejected unless you opt in via `allowCleartext` (there's no key to shred; its
+ * Storage bytes stay readable — the tombstone only stops the segment resolving).
+ *
+ * The options are `confirmSegment`, `allowCleartext` and `audit`. Any other key (`dryRun`, which this call does not
+ * take, included) and an `allowCleartext` that is not a boolean throw `ValidationError` before the registry is read.
  */
 export declare function destroySegment(ref: SegmentRef, deps: EraseDeps, options: {
     confirmSegment: string;
@@ -53,14 +77,16 @@ export declare function destroySegment(ref: SegmentRef, deps: EraseDeps, options
     audit?: IAuditSink;
 }): Promise<DestroyResult>;
 /**
- * Crypto-shred every segment in a namespace. **Irreversible.** `confirmNamespace` must equal `namespace`.
- * Returns a per-segment result (skips cleartext segments unless `allowCleartext`).
+ * Crypto-shred every segment in a namespace. It cannot be undone through the library (a registry restore to a point
+ * before it can). `confirmNamespace` must equal `namespace`. 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.
+ * So does any option it does not take (`dryRun` included) and an `allowCleartext` that is not a boolean.
  */
 export declare function eraseNamespace(namespace: string, deps: EraseDeps, options: {
     confirmNamespace: string;
@@ -76,8 +102,11 @@ export declare function eraseNamespace(namespace: string, deps: EraseDeps, optio
 export interface DropDeps extends EraseDeps {
     readonly storage: IStorageDriver;
 }
+/** What `dropSegment` did to one segment, or, on a dry run, would do. */
 export interface DropResult {
+    /** The segment's name. */
     readonly segment: string;
+    /** The segment's namespace, or `undefined` for the default one. */
     readonly namespace?: string;
     /**
      * **True iff this segment is now empty as a result of this call — or already was.** This is the field a
@@ -111,14 +140,16 @@ export interface DropResult {
     readonly wouldDelete?: readonly number[];
     /**
      * On a dry run, whether the real drop would **also** crypto-shred (i.e. the segment is encrypted).
-     * `undefined` on a real run. This is the one fact in the preview that is irreversible *everywhere*, backups
-     * included — a dry run that did not surface it was previewing the recoverable half only.
+     * `undefined` on a real run. This is the one fact in the preview that reaches every copy of the objects, backups
+     * and WORM copies included (once no retained copy of the row holds the key, or every KEK that wrapped it is
+     * destroyed) — a dry run that did not surface it would preview the recoverable half only.
      */
     readonly wouldCryptoShred?: boolean;
     /**
-     * True iff the segment was encrypted and its wrapped DEK(s) were dropped as part of this call — so its bytes
-     * are unreadable *everywhere*, backups included, not merely deleted from the bucket. Deleting an object does
-     * not reach a noncurrent version, a replica, or a PITR snapshot; discarding the key does.
+     * True iff the segment was encrypted and its wrapped DEK(s) were dropped from its current registry row as part of
+     * this call — so its bytes are unreadable in every copy, backups included, once no retained copy of the row holds
+     * the key or every KEK that wrapped it is destroyed, not merely deleted from the bucket. Deleting an object does
+     * not reach a noncurrent version, a replica, or a PITR snapshot; removing the key does, on those terms.
      */
     readonly cryptoShredded: boolean;
     /**
@@ -133,14 +164,17 @@ export interface DropResult {
     readonly reason?: string;
 }
 /**
- * **Dispose of a segment: tombstone it, then delete its Storage objects.** Irreversible.
+ * **Dispose of a segment: tombstone it, then delete its Storage objects.** It cannot be undone through the library
+ * (a restore from the registry's and the bucket's versions or backups can).
  *
  * WHY THIS EXISTS, given {@link destroySegment} already erases. Because `destroySegment` answers a *compliance*
  * question and this one answers an *operational* question, and they are not the same:
  *
- * - `destroySegment` **crypto-shreds** — it discards the key so the bytes are unreadable everywhere including
- *   immutable backups, which is the only erasure that survives WORM. But it **leaves the objects in the
- *   bucket**, still billed, and it *requires* encryption because a cleartext segment has no key to discard.
+ * - `destroySegment` **crypto-shreds** — it removes the key from the segment's current registry row, so the bytes
+ *   are unreadable everywhere, immutable backups included, once no retained copy of the row holds the key or every
+ *   KEK that wrapped it is destroyed: the only erasure that reaches WORM copies of the objects. But it **leaves the
+ *   objects in the bucket**, still billed, and it *requires* encryption because a cleartext segment has no key to
+ *   discard.
  * - `dropSegment` **removes the storage**. It works on a cleartext segment, and on an encrypted one it *also*
  *   drops the DEKs, so it is a strict superset there.
  *

package/dist/core/errors.d.ts

@@ -15,15 +15,16 @@
  * 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;
+    /** Builds the error from `message`, and sets `name` to the class's name as written. */
     constructor(message: string);
 }
 /**
@@ -33,6 +34,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 {
 }
@@ -57,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');
 }
 /**
@@ -73,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');
 }
 /**
@@ -97,14 +103,47 @@ 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;
+    /** 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;
+        readonly spent: number;
+    });
 }
 /**
  * An encrypted segment's data key (DEK) cannot be unwrapped because the keystore holds none of the
@@ -132,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;
     });
@@ -140,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. */
@@ -164,4 +228,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/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.
  *