@cloudbitmaps/core 0.22.0 → 0.24.0

package/dist/core/check.d.ts

@@ -0,0 +1,50 @@
+/**
+ * A value as a message shows it: a number or boolean as itself, a bigint with an `n` (so `5n` is not mistaken for
+ * `5`), a string quoted (so `'200'` is not mistaken for `200`), and anything else by its type.
+ */
+export declare function shown(value: unknown): string;
+/**
+ * `value` if it is a safe integer from `min` to `max` (inclusive; `max` defaults to the largest safe integer), else a
+ * `ValidationError` naming `what`: `<what> must be an integer from <min> to <max>; got <value>`.
+ */
+export declare function requireInteger(value: unknown, bounds: {
+    readonly min: number;
+    readonly max?: number;
+    readonly what: string;
+    readonly note?: string;
+}): number;
+/**
+ * Refuse a `requireEncryption` that is present and not exactly a boolean. Every site that acts on the flag compares it
+ * with `=== true`, so a truthy string would be taken for `true` by one and for `false` by another.
+ */
+export declare function checkRequireEncryption(value: unknown): void;
+/** `value` if it is a safe integer of 1 or more, else a `ValidationError` naming `what`. */
+export declare function requirePositiveInteger(value: unknown, what: string): number;
+/**
+ * `value` if it is a finite number within the optional `min` and `max` (inclusive), else a `ValidationError` naming
+ * `what`: `<what> must be a finite number from <min> to <max>; got <value>`. `NaN` and the infinities are refused.
+ */
+export declare function requireFiniteNumber(value: unknown, bounds: {
+    readonly min?: number;
+    readonly max?: number;
+    readonly what: string;
+    readonly note?: string;
+}): number;
+/**
+ * Refuse an options bag that is not an object, or that holds a key not in `keys`, naming each such key and the keys it
+ * takes. `hint`, when given, ends the message, to point at where a likely mistake belongs (`an S3 client goes in
+ * \`client\``). Only the bag's own enumerable string keys are read, so a key inherited through a prototype is not
+ * checked.
+ */
+export declare function refuseUnknownOptions(name: string, options: unknown, keys: readonly string[], hint?: string): void;
+/**
+ * The option `name`'s `value`, refused with `ValidationError` unless it is absent or a boolean: a truthy string or a
+ * `1` is not taken for `true`, and `null` is not taken for absent. An absent value comes back `undefined`, for the
+ * caller's default.
+ */
+export declare function requireBool(name: string, value: unknown): boolean | undefined;
+/**
+ * The option `name`'s `value`, refused with `ValidationError` unless it is absent or a string with something in it
+ * (one that is empty or only whitespace is refused, as is `null`). An absent value comes back `undefined`.
+ */
+export declare function requireNonEmptyString(name: string, value: unknown): string | undefined;

package/dist/core/codec.d.ts

@@ -54,7 +54,7 @@ export interface CodecBitmap {
     toArray(): number[];
     /**
      * The set's values as one ascending `Uint32Array` the caller owns: what a batch read converts a chunk with, in one
-     * native step instead of one iterator step per value.
+     * step instead of one iterator step per value.
      *
      * **Optional.** A codec without it is read through its iterator, which is correct and slower.
      *
@@ -125,7 +125,7 @@ export interface EncodedChunk {
 }
 /**
  * A pluggable bitmap codec — the factory the codec-agnostic engine constructs {@link CodecBitmap}s through.
- * Implementations **must** size-cap before handing untrusted bytes to any native decoder and use a safe
+ * Implementations **must** size-cap before handing untrusted bytes to a decoder and use a safe
  * (never a trusting/frozen) deserializer — hard invariant 5.
  */
 export interface CodecInterface {
@@ -135,7 +135,7 @@ export interface CodecInterface {
     fromValues(values: Iterable<number>): CodecBitmap;
     /**
      * Size-cap (`bytes.length <= maxBytes`) then portable-deserialize. Throws `IntegrityError` when the input
-     * exceeds the cap or fails to decode — the native decoder is never handed unbounded or unsafe-format input.
+     * exceeds the cap or fails to decode — the decoder is never handed unbounded or unsafe-format input.
      *
      * "Fails to decode" includes bytes that are the right length and the wrong shape. A bitmap this returns must
      * satisfy every invariant its own operations assume (for roaring: containers and values in order, runs
@@ -161,6 +161,16 @@ export interface CodecInterface {
      * The answer is the whole check: an `owns` that answers `true` for anything lets any object through as a bitmap.
      */
     owns?(bitmap: unknown): boolean;
+    /**
+     * Whether an intersect of three or more operands should meet each chunk's operands smallest-first (by `size`).
+     *
+     * **Optional, and off by default.** A codec whose combine cost depends on the order, because an early operand that is
+     * large and of one container kind makes the running result expensive, sets it; the engine then pays one `size` read per
+     * operand per chunk to put the sparsest first. A codec whose combines cost about the same in any order, or whose
+     * `size` is expensive to read, leaves it out and keeps the operand order it was given. The answer is the
+     * same either way.
+     */
+    readonly intersectSmallestFirst?: boolean;
 }
 /**
  * Resolve a codec that a **public core entry point** was given, failing fast when it is missing.

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

@@ -163,6 +163,10 @@ export interface MaterializeManyOutputStats {
     readonly group: number | null;
     /** Clock time the group's pass began and the output's publish settled (or it failed), when it ran. */
     readonly startedAt: number | null;
+    /**
+     * Clock time (ms) when its publish settled or failed, or `null` when the output never ran. Read from the same clock
+     * as `startedAt`.
+     */
     readonly endedAt: number | null;
     /** Chunks the output holds. */
     readonly chunks: number;
@@ -178,6 +182,7 @@ export interface MaterializeManyOutputStats {
 export interface MaterializeManyStats {
     /** Groups run, the re-runs of outputs a lying index made too big included. */
     readonly groups: number;
+    /** The requests the call made, by class. */
     readonly requests: {
         /** Range requests sent for operand chunks (retries of one request count once). */
         readonly rangeReads: number;
@@ -209,6 +214,7 @@ export interface MaterializeManyStats {
             readonly put: number;
         };
     };
+    /** The chunk-read budget: the limit in force, the reads the plan needed and the reads made. */
     readonly budget: {
         /** The limit used: `null` when lifted. */
         readonly maxRequests: number | null;
@@ -217,6 +223,9 @@ export interface MaterializeManyStats {
         /** Chunk reads made. */
         readonly used: number;
     };
+    /**
+     * The memory the call held: its limit, the most the ledger held at once and what the plan holds for the whole call.
+     */
     readonly memory: {
         readonly maxBufferedBytes: number;
         /** The most the ledger held at once. */
@@ -224,6 +233,7 @@ export interface MaterializeManyStats {
         /** What the plan holds for the whole call, charged to the ledger: operand indexes, and each output's keys and expression. */
         readonly planBytes: number;
     };
+    /** How many chunk keys the call skipped reading. */
     readonly chunks: {
         /** Index keys not read because no output needed them there, summed over groups. */
         readonly pruned: number;
@@ -238,6 +248,7 @@ export interface MaterializeManyStats {
     };
     /** By operand name, an object with no prototype, so any name is a key. */
     readonly operands: Readonly<Record<string, MaterializeManyOperandStats>>;
+    /** One entry per output of the call, in the order the call gave them. */
     readonly outputs: readonly MaterializeManyOutputStats[];
 }
 export interface CombineManyRun<R> {

package/dist/core/consistency.d.ts

@@ -7,8 +7,8 @@
  * the affected segment then throw. This scan
  * detects it up front (run it at startup after a restore) instead of discovering it on the first read.
  *
- * Read-only; bounded fan-out. `destroyed` (crypto-shredded) segments are skipped — their Storage is intentionally
- * gone/unreadable, not a torn restore. A segment whose Storage/registry can't be read this pass is recorded in
+ * Read-only; bounded fan-out. `destroyed` segments are skipped: no generation resolves through one, so a missing
+ * object under it is not a torn restore. A segment whose Storage/registry can't be read this pass is recorded in
  * `errored` (never aborts the scan). One segment can add several entries to `inconsistent` (its current object, and with
  * `generations` one per known generation whose object is not the one recorded) and can also be in `errored`, when a
  * read failed after those were found; with `generations` a segment costs up to one read per entry of its ledger.
@@ -35,8 +35,11 @@ import type { IKeystore } from './crypto.js';
  * something a modest operator box survives. Raisable, because a ceiling you cannot lift is a landmine.
  */
 export { DEFAULT_MAX_SCAN_SEGMENTS } from './registry-scan.js';
+/** One problem the consistency check found with one segment; `issue` says which. */
 export interface ConsistencyIssue {
+    /** The segment's name. */
     readonly segment: string;
+    /** The segment's namespace, or `undefined` for the default one. */
     readonly namespace?: string;
     /**
      * The registry's `currentGen` for the segment. For `missing-storage-generation` it is the generation whose `.crbm` is
@@ -70,11 +73,17 @@ export interface ConsistencyIssue {
 }
 /** A segment that could not be checked this pass (Storage/registry read fault) — not proof of a torn restore. */
 export interface ConsistencyErrorEntry {
+    /** The name of the segment that could not be checked. */
     readonly segment: string;
+    /** That segment's namespace, or `undefined` for the default one. */
     readonly namespace?: string;
     /** The read error's message (never the raw error, so the report stays serializable/loggable). */
     readonly error: string;
 }
+/**
+ * What a consistency check found: how many segments it scanned, the issues, the segments it could not read, and, when
+ * asked for, the checks it could not make.
+ */
 export interface ConsistencyReport {
     /** Registered segments scanned (a `destroyed` segment counts as scanned but is never an issue). */
     readonly checked: number;

package/dist/core/cooperative.d.ts

@@ -3,13 +3,16 @@
  *
  * Everything this library does on the hot read path is small. Bulk-load is the exception: it is the one place
  * where a single call legitimately occupies the CPU for hundreds of milliseconds, and Node has exactly one thread
- * to occupy. Measured on a 1M-id load of 65,536 chunks onto in-memory storage, on a loaded Apple M3 Pro: **518 ms
- * wall, and 519 ms during which the event loop did not turn at all** (medians of 20 fresh-process runs). Wire that to a request handler and every other in-flight request on the instance — health
+ * to occupy. Measured on the native codec of 0.23.0 (every figure in this header is the native codec's, to be
+ * re-measured on the TypeScript codec), on a 1M-id load of 65,536 chunks onto in-memory storage, on a loaded Apple M3
+ * Pro: **518 ms wall, and 519 ms during which the event loop did not turn at all** (medians of 20 fresh-process
+ * runs). Wire that to a request handler and every other in-flight request on the instance — health
  * checks included — waits out the whole load.
  *
- * The fix is not to make the work asynchronous. That was measured too, and it is a 7x *regression*: handing each
- * chunk's insert to the threadpool costs ~9 µs of dispatch against ~1.5 µs of actual work once ids are spread
- * across ~62,000 chunks (636 ms versus 92 ms). The work is genuinely CPU-bound and genuinely small per chunk;
+ * The fix is not to make the work asynchronous. That was measured too, on the native codec's threadpool insert, and
+ * it was a 7x *regression*: handing each chunk's insert to the threadpool cost ~9 µs of dispatch against ~1.5 µs of
+ * actual work once ids are spread across ~62,000 chunks (636 ms versus 92 ms). The TypeScript codec has no
+ * threadpool path. The work is genuinely CPU-bound and genuinely small per chunk;
  * the only thing wrong with it is that it never stops to let anyone else go. So the fix is to keep the work
  * synchronous and periodically hand the loop back.
  *
@@ -51,6 +54,13 @@ export interface Yielder {
  * (~60 yields across a 1M-id load) while still capping any single blocking stretch in the low tens of ms.
  */
 export declare const YIELD_EVERY = 1024;
+/**
+ * Ids between a load's ingest-loop yields, sorted or not. 16x coarser than the per-chunk cadence because the per-id
+ * work is ~40 ns (a `splitId` and an array push) against ~1.3 µs per chunk — matching cadences would put the yield cost
+ * on the wrong side of the work it interrupts. Sized against the *slowest* ingest, an in-memory async generator at
+ * ~220 ns/id, so the resulting stretch stays a few ms there and well under 1 ms on a plain array.
+ */
+export declare const YIELD_EVERY_IDS: number;
 /**
  * Build a periodic yield.
  *

package/dist/core/crbm/reader.d.ts

@@ -179,7 +179,7 @@ export declare class CrbmReader {
     has(chunkKey: number): boolean;
     /**
      * Range-GET one chunk's payload, verifying its CRC32C before returning. Returns `null` if the chunk is
-     * absent. Throws `IntegrityError` on a CRC mismatch (the bytes must never reach the native
+     * absent. Throws `IntegrityError` on a CRC mismatch (the bytes must never reach the codec's
      * deserializer). The returned bytes may be shared (a small generation's chunks are kept by the reader and handed out
      * again), so callers must not change them.
      */

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

@@ -377,7 +377,8 @@ export declare class CrbmStorageChunkSource implements StorageChunkSource {
      * the one read path with no resilience.
      *
      * **`status` is re-checked here**, on every open rather than once at pin time. A pin taken before a
-     * crypto-shred must not keep unwrapping a DEK the shred destroyed; a destroyed segment resolves no generation
+     * crypto-shred must not keep unwrapping a DEK whose wrapping the shred removed; a destroyed segment resolves no
+     * generation
      * for anyone, and a pin's read of one fails. That holds from the pin's next open: a reader already open keeps
      * the key it unwrapped until it is evicted or invalidated.
      *
@@ -419,7 +420,8 @@ export declare class CrbmStorageChunkSource implements StorageChunkSource {
     /**
      * Whether the segment is a registered name at all. With a registry: a row that is not a `destroyed` tombstone,
      * including one with no generation yet (minted by `setRetention` before the first load), which somebody deliberately
-     * created. A tombstone holds nothing, so it answers `false`. Without a registry there is no registration to
+     * created. No generation resolves through a tombstone, so it answers `false`. Without a registry there is no
+     * registration to
      * consult, so the honest answer is whether the bucket holds any generation of it.
      *
      * Deliberately NOT served from the snapshot memo: the memo resolves to `null` for both states this exists to
@@ -569,8 +571,9 @@ export declare class CrbmStorageChunkSource implements StorageChunkSource {
      *
      * A *second* NotFound is pathological (GC outrunning resolution) and propagates rather than fabricating an
      * absent answer — never return a wrong result. `ifGone` is returned when the segment has no committed
-     * generation to serve: storage is empty, or the row was dropped or crypto-shredded, in which case reading empty
-     * is the documented outcome rather than a failure.
+     * generation to serve: storage is empty, or the row is destroyed (crypto-shredded, destroyed in the clear or
+     * dropped), in which case
+     * reading empty is the documented outcome rather than a failure.
      *
      * **Bounded to exactly two resolve-and-open round trips.** That is a cost contract, not a detail: the retry
      * re-reads the *registry*, so an unbounded one would hammer the shared, throttle-prone resource in a

package/dist/core/crypto.d.ts

@@ -8,8 +8,11 @@
  */
 /** One AEAD result: a fresh per-message nonce, the ciphertext, and the authentication tag. */
 export interface AeadSealed {
+    /** The fresh per-message nonce. */
     readonly nonce: Uint8Array;
+    /** The encrypted bytes. */
     readonly ciphertext: Uint8Array;
+    /** The authentication tag. */
     readonly tag: Uint8Array;
 }
 /**
@@ -36,7 +39,9 @@ export interface Aead {
  * plaintext key material — safe to store in the registry next to the (encrypted) data.
  */
 export interface WrappedDek {
+    /** The id of the key-encryption key (KEK) this wrapping is under. */
     readonly keyId: string;
+    /** The wrapped data key, an opaque base64 string. */
     readonly wrapped: string;
 }
 /**

package/dist/core/discover.d.ts

@@ -20,9 +20,11 @@ export interface SegmentInfo extends SegmentRef {
      */
     readonly currentGen: number | null;
     /**
-     * `destroyed` is a tombstone: the row stays so sweeps can still find it, and the generations are gone — on an
-     * encrypted segment the DEK wrappings went with them, which is what makes the bytes unrecoverable rather than
-     * merely deleted.
+     * `destroyed` is a tombstone: the row stays so sweeps can still find it, and no generation resolves through it. A
+     * `dropSegment` deletes the generations (check its `generationsRemaining`); a crypto-shred leaves them in the bucket
+     * and removes the DEK wrappings from the row, which makes every copy of the bytes unreadable once no retained copy of
+     * the row still holds them, or every KEK that wrapped them is destroyed. A cleartext segment destroyed with
+     * `allowCleartext` has no key to remove: its objects stay in the bucket and stay readable.
      */
     readonly status: RegistryRecord['status'];
 }

package/dist/core/engine.d.ts

@@ -346,11 +346,11 @@ export declare class SegmentEngine {
      * for the range's edge, never a chunk the cache holds or another operand's. The reads, the budget, the metric and the
      * errors are the id reads' own.
      */
-    intersectChunks(segs: readonly SegmentRef[], options?: CombineOptions): AsyncGenerator<CombinedChunk>;
+    intersectChunks(segs: readonly SegmentRef[], options?: CombineOptions, label?: string): AsyncGenerator<CombinedChunk>;
     /** {@link union}, as chunks: see {@link intersectChunks}. */
-    unionChunks(segs: readonly SegmentRef[], options?: CombineOptions): AsyncGenerator<CombinedChunk>;
+    unionChunks(segs: readonly SegmentRef[], options?: CombineOptions, label?: string): AsyncGenerator<CombinedChunk>;
     /** {@link andNot}, as chunks: see {@link intersectChunks}. */
-    andNotChunks(seg: SegmentRef, excludes: readonly SegmentRef[], options?: Omit<CombineOptions, 'exclude'>): AsyncGenerator<CombinedChunk>;
+    andNotChunks(seg: SegmentRef, excludes: readonly SegmentRef[], options?: Omit<CombineOptions, 'exclude'>, label?: string): AsyncGenerator<CombinedChunk>;
     /**
      * Everything a combine decides before it reads a chunk: validation, each operand's keys and generation, the
      * absent-operand refusal, key alignment, the budget and the metric. `null` when the range is empty. The per-id
@@ -401,7 +401,7 @@ export declare class SegmentEngine {
      * The AND (or OR) of one chunk key across all operands, minus the excludes that hold it, or `null` if empty.
      * Operand chunks are fetched **in parallel** (the spec's parallel byte-range reads).
      *
-     * The accumulator is a **clone** of the first operand's chunk, and that clone is load-bearing: every other
+     * The accumulator is a **clone** of one operand's chunk (the first, or for a codec that asks the one with the fewest values), and that clone is load-bearing: every other
      * bitmap here is the cached, shared Storage instance and must never be mutated, or the cache is poisoned for
      * every later reader. The remaining operands and the excludes are only *read* by the in-place ops, so they are
      * used as-is — one clone per key, not one per operand.
@@ -546,7 +546,7 @@ export declare class SegmentEngine {
      * the read listed the segment's keys: the read then lists them again, and caches as a read begun after the call.
      *
      * The decoded-chunk cache is keyed by generation, which handles a *publish* (the new generation misses) but
-     * not a *destruction*: a segment that was erased from, dropped, shredded or retired has no newer generation
+     * not a *destruction*: a segment that was erased from, dropped, destroyed or retired has no newer generation
      * whose key would miss, so its decoded chunks stay resident and keep answering. That is why the erasing
      * process itself could report `erased: true` and then still answer `true` for the same id, out of RAM, with
      * no storage read to intercept.

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,
@@ -60,7 +66,7 @@
  * its number after the winner's object was already in the bucket. Up there nothing collects it, and it was derived
  * from a generation the winner has replaced, so when the winner was another erasure it still holds the id that
  * erasure has just reported gone. That object is deleted before this call returns, once its footer matches the
- * rewrite's and a renewal of the row has refused every publish fenced on a row read before it, under the version the
+ * rewrite's (a read of it that faults is thrown instead, and the object stays) and a renewal of the row has refused every publish fenced on a row read before it, under the version the
  * footer read reported, unless {@link DISCARD_ATTEMPTS} renewals lose to other writes (a load, a rollback, a
  * retention write): then it is kept, and can hold the winner's id, until a later call takes it: any erasure that
  * rewrites the segment (this one's re-run among them, while its id is still in the current generation) numbers above it
@@ -176,8 +182,8 @@ 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 when the call read it, its first
+     * 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
@@ -232,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
@@ -242,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
@@ -277,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 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.
  *