@cloudbitmaps/core 0.21.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

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

@@ -1,3 +1,8 @@
+/**
+ * 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>`.
@@ -8,6 +13,11 @@ export declare function requireInteger(value: unknown, bounds: {
     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;
 /**
@@ -20,3 +30,20 @@ export declare function requireFiniteNumber(value: unknown, bounds: {
     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/codec.d.ts

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

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

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

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

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

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

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

package/dist/core/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/determinism.d.ts

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

package/dist/core/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.