@cloudbitmaps/core 0.22.0 → 0.23.0

package/dist/core/audit.d.ts

@@ -73,10 +73,13 @@ export type AuditEvent = {
      * segment's registry row changed while the load was writing). `cardinality` is what the refused generation
      * would have contained, and `0` for a load that lost its generation number and wrote nothing.
      *
-     * `unanswered` is present, and `true`, on a `'superseded'` refusal whose registry write ended without an answer
-     * before the row was found to have moved on: that write may have landed, so the generation may have been the
-     * segment's current one for a while before another writer replaced it. The refusal says only that it is not
-     * current now. Absent when every write the load made was answered.
+     * `unanswered` is present, and `true`, on a `'superseded'` refusal after a registry write whose answer did not
+     * say whether it landed: one that ended without an answer, or a conflict its registry marked as one that may
+     * follow the write's own landing (Azure Blob marks every conflict of a row write, since its client may have sent
+     * the write twice). That write may have landed, so the generation may have been the segment's current one for a
+     * while before another write replaced it, or, where a write renewed the row's `pointerId` over it, may be current
+     * still. Absent when every write was answered and every conflict was one its registry vouches the write did not
+     * land.
      */
     readonly kind: 'segment.load-refused';
     readonly namespace?: string;
@@ -115,11 +118,12 @@ export type AuditEvent = {
      * not hold, or an encrypted one under a cleartext row (a first load's that lost the race, or crashed). The one
      * emitter is `eraseIdFromSegment`, once a listing of the bucket shows nothing left holding the id, so the record
      * exists only for a finished erasure. A call that ends otherwise throws or reports `erased: false` with another
-     * reason and emits nothing, even when it had deleted a holder; its re-run emits when it finishes, and reports
-     * `'not-member'` with no event when another collection deleted the last holder meanwhile, as its ledger entry
-     * does. One finished erasure emits it and then throws `NotFoundError`: one that found, after its deletes, the
-     * segment's pointer on a generation it had deleted (a rollback moved it there meanwhile), so the deletion is on
-     * the record although the call cannot answer.
+     * reason and emits nothing, even when it had deleted a holder; its re-run emits when it finishes, and, when
+     * another collection deleted the last holder meanwhile, emits nothing and answers `'not-member'`, which
+     * `eraseSubject`'s ledger shows by listing nothing for the segment. One finished erasure emits it and then
+     * throws `NotFoundError`: one that found, after its deletes, the segment's pointer on a generation it had
+     * deleted (a rollback moved it there meanwhile), so the deletion is on the record although the call cannot
+     * answer.
      *
      * `fromGeneration` is the newest generation the call found holding the id, and is absent when it found the id in
      * none and deleted only objects it could not search: then the ledger lists no entry for the segment, and this
@@ -137,24 +141,52 @@ export type AuditEvent = {
     readonly collected: readonly number[];
 } | {
     /**
-     * A segment was **crypto-shredded** — its wrapped DEK(s) are gone, so its at-rest Storage bytes are now
-     * permanently unreadable. Emitted only for a genuine key shred, never for a cleartext tombstone (which
-     * leaves the Storage bytes readable) or an idempotent re-run.
+     * A segment was **crypto-shredded**: its wrapped DEK(s) are gone from the segment's **current** registry row,
+     * so nothing that opens the segment through that row can decrypt its Storage bytes, in the bucket or in any
+     * backup, replica or WORM copy of its objects. It destroys no KEK: a noncurrent version, a backup or a
+     * point-in-time copy of the row still holds the wrapped DEK(s), and a registry restore to a point before the
+     * shred makes the segment readable again wherever its objects survive. The destruction is complete once no
+     * retained copy of the row holds them, or once every KEK that wrapped them is destroyed. A process that had
+     * already opened the segment keeps its unwrapped key in memory until told (`store.invalidate(ref)`). Emitted
+     * only for a genuine key shred, never for a cleartext tombstone (which leaves the Storage bytes readable) or
+     * an idempotent re-run.
      */
     readonly kind: 'segment.erase';
     readonly namespace?: string;
     readonly segment: string;
     /** The incarnation of the row the shred turned into a tombstone. */
     readonly incarnation?: string;
+} | {
+    /**
+     * A segment was tombstoned **without a key shred**: `destroySegment` or `eraseNamespace` with `allowCleartext`
+     * turned the row of a segment that holds no wrapped key into a `destroyed` tombstone. No read resolves the
+     * segment any more, but nothing was deleted and no key was destroyed, so its objects stay readable in the
+     * bucket, in any backup and through any copy of the row from before the tombstone.
+     *
+     * Deliberately not {@link AuditEvent} `segment.erase`, which attests a key shred, nor `segment.dispose`, which
+     * attests that a drop swept the storage: this one is the record that the row was tombstoned, which is what a
+     * registry restore undoes and what the restore procedure looks for. `objectsReadable` is always `true`; it
+     * is a field so a consumer that forwards events cannot read this one as an erasure receipt. Emitted once per
+     * tombstone this call wrote, not for the idempotent re-run, and not for a segment that was encrypted
+     * (`segment.erase`), or dropped (`segment.dispose`).
+     */
+    readonly kind: 'segment.tombstone';
+    readonly namespace?: string;
+    readonly segment: string;
+    /** The incarnation of the row the call turned into a tombstone. */
+    readonly incarnation?: string;
+    /** Always `true`: the segment's objects were not deleted and no key was destroyed. */
+    readonly objectsReadable: true;
 } | {
     /**
      * A segment was **disposed of** — tombstoned and its storage reclaimed (its Storage generations deleted) by
      * `dropSegment`, *without* a key shred.
      *
      * Deliberately a separate kind from {@link AuditEvent} `segment.erase`, and the distinction is the point.
-     * `segment.erase` attests that bytes are unreadable **everywhere, backups included** — the only claim that
-     * survives WORM. Deleting an object is strictly weaker: a noncurrent version, a cross-region replica or a
-     * PITR snapshot can still hold the cleartext. Emitting one kind for both would make a compliance dashboard
+     * `segment.erase` attests that the current row no longer holds the key, which is the one erasure claim that
+     * reaches WORM copies of the objects, once no retained copy of the row holds it. Deleting an object is
+     * strictly weaker: a noncurrent version, a cross-region replica or a PITR snapshot can still hold the
+     * cleartext. Emitting one kind for both would make a compliance dashboard
      * over-attest, so a cleartext drop gets this instead.
      *
      * An **encrypted** segment dropped via `dropSegment` emits **both** — `segment.erase` for the key shred and
@@ -178,6 +210,10 @@ export type AuditEvent = {
 };
 /** Sink for {@link AuditEvent}s. Injected via the lifecycle options; omit it and nothing is recorded. */
 export interface IAuditSink {
+    /**
+     * Receives one audit event, called synchronously by the operation that caused it. What it throws, or rejects with, is
+     * swallowed and never breaks that operation.
+     */
     onEvent(event: AuditEvent): void;
 }
 /** The default sink: records nothing. */
@@ -200,8 +236,10 @@ export declare function ignoreRejection(returned: unknown): void;
 /** A ready-made sink that records events into an in-memory list — handy for tests + simple audit trails. */
 export declare class RecordingAuditSink implements IAuditSink {
     private readonly recorded;
+    /** Records the event, in emission order. */
     onEvent(event: AuditEvent): void;
     /** An independent copy of the recorded events, in emission order. */
     snapshot(): AuditEvent[];
+    /** Forgets every recorded event. */
     reset(): void;
 }

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

@@ -13,6 +13,8 @@ interface BitRoute {
 }
 /** Was `err` thrown by {@link splitId} for an id outside the u32 range? */
 export declare function isBadIdError(err: unknown): err is ValidationError;
+/** The refusal {@link splitId} throws for a value that is not a u32 id, for a caller that checks the range itself. */
+export declare function refusalOfId(id: unknown): ValidationError;
 /** Split a u32 id into `{ chunkKey, remainder }`. Throws `ValidationError` for non-u32 input. */
 export declare function splitId(id: number): BitRoute;
 /**

package/dist/core/blob.d.ts

@@ -3,6 +3,10 @@
  * the write resolves, so a sink that holds bytes past that copies them.
  */
 export interface BlobSink {
+    /**
+     * Appends `bytes` to the object. Once it resolves the caller may reuse the buffer, so a sink that keeps the bytes
+     * copies them.
+     */
     write(bytes: Uint8Array): Promise<void>;
 }
 /**

package/dist/core/budget.d.ts

@@ -15,6 +15,11 @@
  * search generation by generation is also charged one unit for each generation it opens beyond the current one,
  * since that is O(generations) work the segment count alone does not show.
  */
+/**
+ * The cap on one operation's fan-out: its `maxRequests` units, counted in storage chunk fetches for a read and in
+ * segments scanned for an admin scan. `eraseSubject` also charges one unit for each generation beyond the current one
+ * that it opens, in a segment it has to search generation by generation.
+ */
 export interface Budget {
     /** Max units of fan-out (Storage chunk fetches, or segments scanned) one op may issue before it is refused. */
     readonly maxRequests: number;
@@ -30,13 +35,13 @@ export type BudgetOption = Partial<Budget> | false;
 /**
  * Resolve a budget option against a fallback to a concrete `Budget`, or `null` when disabled. Validates: anything but
  * `false`, an absent value or an object of `{ maxRequests }` is refused, since a cap of the wrong shape (`5`,
- * `{ maxRequest: 5 }`) would otherwise read as no override and leave the fallback in force. `null` and a key whose value
- * is `undefined` read as absent.
+ * `{ maxRequest: 5 }`) would otherwise read as no override and leave the fallback in force. A key whose value is `undefined` reads
+ * as absent; a `null` budget and a `maxRequests` of `null` are refused.
  */
 export declare function resolveBudget(opt: BudgetOption | undefined, fallback: Budget): Budget | null;
 /**
  * Resolve a **per-op** budget override against the store's own resolved budget (never the raw global default):
- * `undefined` or `null` inherits the store budget as-is (including a disabled `null`); a partial `{}` / omitted
+ * `undefined` inherits the store budget as-is (including a disabled `null`); a partial `{}` / omitted
  * `maxRequests` inherits the store's *tightening* (so a per-op passthrough of an absent config value can't
  * silently lift a tight tenant ceiling back to the generous default); `{ maxRequests }` replaces it; `false`
  * disables. Falls back to {@link DEFAULT_BUDGET} only when the store itself has no budget (disabled).

package/dist/core/check.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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.
+ */
+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/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

@@ -51,6 +51,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-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
@@ -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,
@@ -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>;