@cloudbitmaps/core 0.20.0 → 0.21.0

package/dist/core/absent-operands.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Throws {@link ValidationError} naming every one of `candidates` whose segment does not exist, asking `exists` of
+ * each, at most `limit` at once, in their order. A streamed combine asks only after operands that hold no chunk at all;
+ * the batch combine also asks after every operand it did not index (one no output names, or every operand when the range
+ * is empty). `op` begins the message (`intersect`, `materializeMany`); `nameOf` is how the caller's operands are named
+ * in it, each in double quotes. The first `exists` to reject rejects the call at once; none is asked after that.
+ */
+export declare function refuseAbsent<T>(op: string, candidates: readonly T[], limit: number, exists: (candidate: T) => Promise<boolean>, nameOf: (candidate: T) => string): Promise<void>;

package/dist/core/audit.d.ts

@@ -38,7 +38,7 @@ export type AuditEvent = {
 } | {
     /**
      * A segment's pointer was moved by a rollback to a generation still in the bucket that the caller named:
-     * **backwards**, or forward with `allowForward`, which undoes an earlier rollback.
+     * **backwards**, or forward onto a generation a rollback left above the pointer, which undoes an earlier rollback.
      *
      * The only non-forward-only pointer move in the library, and the only one no automatic path can perform —
      * a human decided the current generation was wrong and named the one they wanted. Every other pointer move
@@ -54,6 +54,14 @@ export type AuditEvent = {
     readonly incarnation?: string;
     readonly fromGeneration: number | null;
     readonly generation: number;
+    /**
+     * Present, and `true`, when the row did not vouch for the target: the call passed `allowUnknown` for a generation the
+     * row does not know or whose object is not the one it recorded, or the row has no usable record of its generations
+     * (a registry that drops the field, or a pointer moved by hand) or the target is below a full record's bound, where the
+     * pointer alone decides for a target below it. Absent when the move was
+     * checked against the row's record.
+     */
+    readonly unknown?: true;
 } | {
     /**
      * A load was **refused**: it did not publish, because its result failed a guard or another writer got there
@@ -109,7 +117,9 @@ export type AuditEvent = {
      * 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.
+     * 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.
      *
      * `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

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

@@ -1,6 +1,6 @@
 export declare const U32_MAX = 4294967295;
 export declare const CHUNK_COUNT = 65536;
-export interface BitRoute {
+interface BitRoute {
     /** Top 16 bits — the chunk key (0..65535). */
     readonly chunkKey: number;
     /** Bottom 16 bits — the value within the chunk (0..65535). */
@@ -19,3 +19,4 @@ export declare const MAX_REMAINDER: number;
  * invariant 5); `remainder` is masked to 16 bits.
  */
 export declare function joinId(chunkKey: number, remainder: number): number;
+export {};

package/dist/core/blob.d.ts

@@ -12,12 +12,23 @@ export interface BlobSink {
 export interface BlobReader {
     /** Exactly `length` bytes starting at `offset`. Out-of-range is a `ValidationError`, never a short read. */
     getRange(offset: number, length: number): Promise<Uint8Array>;
-    /** The last `min(maxBytes, size)` bytes plus the total size — the one-GET footer+index path. */
+    /**
+     * The last `min(maxBytes, size)` bytes plus the total size — the one-GET footer+index path. `maxBytes` is a safe
+     * integer, zero or less for an empty tail; any other length is refused with `ValidationError`.
+     */
     getTail(maxBytes: number): Promise<{
         bytes: Uint8Array;
         size: number;
     }>;
 }
+/**
+ * Check the length a tail read asks for, the one rule every tail read holds to (each storage driver's `getTail` and
+ * {@link BufferReader.getTail}): a safe integer. Zero or less answers an empty tail with the size, and a length past
+ * the object's size answers the whole object. Anything else is refused with `ValidationError` before anything is read:
+ * `NaN`, a fraction (a negative one too), an infinity of either sign, and a whole number past the safe range (2^53 or
+ * more, or -2^53 or less), so no reader takes one for some other length.
+ */
+export declare function checkTailLength(maxBytes: number): void;
 /** In-memory `BlobSink` that accumulates written bytes; `bytes()` returns the concatenation. */
 export declare class BufferSink implements BlobSink {
     private readonly chunks;

package/dist/core/bulk-load.d.ts

@@ -0,0 +1,148 @@
+/**
+ * The loader `load()` is built on: ids, a decoded bitmap or a combine's chunks in, one generation written, and published
+ * when a registry is wired and the caller does not defer it, as `load()` does to publish after its guard.
+ */
+import { type IAuditSink } from './audit.js';
+import { ValidationError } from './errors.js';
+import type { Clock } from './determinism.js';
+import type { Aead, IKeystore, WrappedDek } from './crypto.js';
+import type { GenerationMetadata, GenKey, IStorageDriver, IRegistryDriver, RegistryRecord, RegistrySummary, SegmentRef } from './ports.js';
+import type { CodecInterface } from './codec.js';
+import { ChunkLoadInput, DecodedLoadInput } from './load-input.js';
+/** What a bulk-load wrote — the driver's `{ size, sha256 }` plus a summary of the built generation. */
+export interface BulkLoadResult {
+    /** Bytes written to the Storage object. */
+    readonly size: number;
+    /** The driver's content hash of the object. */
+    readonly sha256: string;
+    /** Distinct non-empty chunks written (≤ 65536). */
+    readonly chunkCount: number;
+    /**
+     * The DEK freshly minted for this generation, wrapped — present only when the segment is encrypted AND this
+     * call minted one (an existing segment reuses its key, which is already on the row).
+     *
+     * Returned so a caller that deliberately does **not** pass `registry` here — writing now and publishing later,
+     * which is how a load applies a guard while the old generation is still authoritative — can carry the key onto
+     * its own `publishGeneration`. Without it that publish stores no DEK and the generation it makes current is
+     * unreadable: the bytes are encrypted with a key nothing recorded.
+     */
+    readonly wrappedDeks?: readonly WrappedDek[];
+    /** Whether the object was written encrypted: under the segment's key, or under one this call minted. */
+    readonly encrypted: boolean;
+    /** The written object's fingerprint, which tells it from an object stored later under the same key. */
+    readonly fingerprint: string;
+    /** Total distinct ids in the generation (post-dedup). */
+    readonly cardinality: number;
+    /**
+     * The summary of what was written, for the write that makes it current: its id count and metadata, sealed under the
+     * segment's key when the object was written with one. A caller that defers the publish (`publish: false`) passes it
+     * to {@link publishGeneration}.
+     */
+    readonly summary: RegistrySummary;
+    /**
+     * Whether this generation is now the segment's **current** one — `undefined` when no `registry` was wired, so
+     * there is no pointer and no publish step to report on.
+     *
+     * `false` means the object is durable but a **concurrent writer published a higher generation first**, so this
+     * one is an orphan that no reader will ever resolve. The write succeeded and the *load* did not: whatever this
+     * call was asked to make the segment contain, the segment does not contain. That is not a detail a caller can
+     * be left to infer — a `*Into` materialisation that reported the generation it wrote as "the destination's new
+     * current generation" on this path would state a plain untruth — so the flag is on the result and the verbs that
+     * promise a published generation check it.
+     */
+    readonly becameCurrent?: boolean;
+}
+/**
+ * **Bulk-load** a whole immutable generation from a flat id source — the batch "seed/rebuild" entry point.
+ * Unlike {@link writeCrbmGeneration} (which takes pre-grouped bitmaps), this
+ * consumes an arbitrary, **unsorted** stream of u32 ids (sync or async) and routes each into its chunk's
+ * Roaring bitmap as it goes. The input is consumed lazily and ids dedup on insert, so memory is bounded by
+ * the **built generation** — the in-memory Roaring representation of the *distinct* set (≤ one bitmap per
+ * non-empty chunk) — not by the input length: you can stream a billion duplicate-heavy ids and hold only the
+ * distinct result. Note this is `O(distinct set)`, **not** window-bounded like {@link SegmentEngine.intersect}:
+ * bulk-load holds the whole generation in RAM, which suits batch seed/rebuild jobs but not an
+ * unbounded-cardinality stream (a segment larger than RAM needs external-merge / pre-sorted input — later phase).
+ *
+ * Each id must be an integer in `[0, 2³²)` ({@link splitId} throws {@link ValidationError} otherwise) — the
+ * source is consumed lazily, so a bad id aborts mid-stream without writing a partial object (the driver
+ * commits only after the callback resolves). An empty source writes a valid empty generation.
+ *
+ * Writes a fresh full snapshot of a segment. The caller picks the generation number in `key` — `nextGeneration`
+ * computes one from the registry and the bucket, as `nextLoadGeneration` does for a load — and re-using an existing
+ * generation throws
+ * {@link WriteConflictError} (write-once). Without a registry a `StorageChunkSource` serves the **highest**
+ * generation present, so a too-high number silently shadows real data; with one, `publishGeneration` decides.
+ */
+export declare function bulkLoadCrbmGeneration(driver: IStorageDriver, key: GenKey, ids: Iterable<number> | AsyncIterable<number> | DecodedLoadInput | ChunkLoadInput, options?: {
+    registry?: IRegistryDriver;
+    keystore?: IKeystore;
+    requireEncryption?: boolean;
+    audit?: IAuditSink;
+    /** Bitmap codec. Optional in the type; a **flavor** package binds it ({@link requireCodec}). */
+    codec?: CodecInterface;
+    /**
+     * Injected clock. Supplying one makes bulk-load **cooperative**: it yields the event loop periodically so a
+     * long load does not stall everything else on the process. Without it the load still completes, just
+     * without yielding — which is the pre-existing behaviour, kept so this is purely additive.
+     *
+     * `@cloudbitmaps/roaring` supplies a real clock by default, so flavor users get cooperative behaviour with
+     * no wiring. `core/` cannot default it: it is timer-free by lint, which is exactly why waiting goes through
+     * this seam rather than `setTimeout`.
+     */
+    clock?: Clock;
+    /**
+     * Write the object but do **not** advance the pointer (default: publish when a `registry` is wired).
+     *
+     * For a caller that has to inspect what it wrote before deciding whether it should become current — a
+     * guarded {@link loadSegment} is the one in-tree case — because the check is only meaningful while the old
+     * generation is still authoritative. The `registry` is still required for an encrypted segment and still
+     * consulted: it is where an existing segment's DEK lives, and reusing that key is not optional. The wrapped
+     * DEK comes back on the result so the deferred publish can store it.
+     *
+     * A caller that defers the publish owns what it wrote: an unpublished object sits ABOVE `currentGen`, where
+     * generation collection deliberately never looks, so nothing reclaims it until a later generation above it is
+     * current.
+     */
+    publish?: boolean;
+    /**
+     * The generation's metadata (see {@link GenerationMetadata}), written into the object and carried in the summary.
+     * The caller has checked it against the metadata rules; the writer checks it again, and refuses a record that breaks
+     * one before a byte is written.
+     */
+    metadata?: GenerationMetadata;
+    /**
+     * The segment's row as the caller already read it (`null`: it found none), for a caller that defers the
+     * publish (`publish: false`) and fences it on that same row. A present cleartext row is then used as read,
+     * rather than read again: a row that changes in between (a publish, a drop, a purge and re-create) makes the
+     * fenced publish lose, so the object is never published on the strength of the stale read. A row read as
+     * absent, or one carrying key material, is read again after the ids, as with no row passed: a first load must
+     * see a row another writer created meanwhile, and an encrypted segment's key is unwrapped only from a row read
+     * after the ids, so a segment shredded while they streamed is refused before its key is used.
+     */
+    row?: RegistryRecord | null;
+}): Promise<BulkLoadResult>;
+/**
+ * What a load has already started when it calls {@link bulkLoadAhead}: its number, and the segment's data key, each
+ * still in flight so their round trips overlap the encoding. Both are joined where the write needs them, and neither
+ * may be left to reject unobserved.
+ */
+interface LoadAhead {
+    /** The number the generation takes (see {@link nextLoadGeneration}); joined just before the object is written. */
+    readonly generation: PromiseLike<number>;
+    /**
+     * The key a caller already asked the keystore to unwrap, with the wrappings it asked about. Used only when the
+     * row the write reads after the ids carries exactly these wrappings; otherwise the write unwraps for itself.
+     */
+    readonly unwrapped?: {
+        readonly wrapped: readonly WrappedDek[];
+        readonly aead: PromiseLike<Aead>;
+    };
+}
+/** What a load with `requireEncryption` meets on a segment that already has a cleartext generation. */
+export declare function cleartextUnderRequiredEncryption(ref: SegmentRef, currentGen: number): ValidationError;
+/**
+ * {@link bulkLoadCrbmGeneration} for a load whose number, and perhaps its key, are still being fetched: the same
+ * options, with the same meaning, and the same writes. The number is joined only where the object is written.
+ */
+export declare function bulkLoadAhead(driver: IStorageDriver, ref: SegmentRef, ahead: LoadAhead, ids: Parameters<typeof bulkLoadCrbmGeneration>[2], options?: NonNullable<Parameters<typeof bulkLoadCrbmGeneration>[3]>): Promise<BulkLoadResult>;
+export {};

package/dist/core/cas-retry.d.ts

@@ -0,0 +1,27 @@
+import type { WriteConflictError } from './errors.js';
+import { type ChurnDeps } from './leases.js';
+import type { IRegistryDriver, RegistryRecord, SegmentRef } from './ports.js';
+/** What `casRetry` needs: the registry, and the clock and rng that spread a wait out. */
+type CasRetryDeps = ChurnDeps & {
+    readonly registry: IRegistryDriver;
+};
+/** How many attempts a caller gets, and the error it throws once they are spent. */
+interface CasRetryPlan {
+    /** Attempts that count; a wait out of lease churn does not use one. */
+    readonly attempts: number;
+    /** The error thrown when every attempt lost. */
+    readonly contention: () => WriteConflictError;
+}
+/**
+ * Read a segment's row, run `step` on it, and run it again on a fresh read when `step` throws a write conflict.
+ *
+ * Every lost race uses one of `plan.attempts`, except one lost by a run that followed a wait. When the row read after a
+ * lost race differs from the one `step` was given only in its leases, the loop waits the churn out (up to the churn
+ * bound), reads the row again and runs `step` against that without using an attempt. A race lost on the last attempt
+ * is not waited out. `step` returns the caller's result, or throws: a write conflict retries, anything else leaves
+ * `casRetry` untouched.
+ *
+ * Exhausting `attempts` throws `plan.contention()`.
+ */
+export declare function casRetry<T>(deps: CasRetryDeps, ref: SegmentRef, plan: CasRetryPlan, step: (row: RegistryRecord | null) => Promise<T>): Promise<T>;
+export {};

package/dist/core/check.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `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;
+/** `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;

package/dist/core/chunk-checks.d.ts

@@ -6,7 +6,12 @@ import type { CodecBitmap, CodecInterface } from './codec.js';
 export declare function assertChunkKeyInRange(k: number): void;
 /** A chunk holds at least one id and at most {@link CHUNK_COUNT}; a count outside that came from a corrupt tier. */
 export declare function assertChunkCardinalityInRange(c: number): void;
-/** A segment's chunk keys, ascending — a shape read off the index, no payload. Keys are untrusted (invariant 5). */
+/**
+ * A segment's chunk keys, ascending — a shape read off the index, no payload. Keys are untrusted (invariant 5): each is
+ * an integer in `[0, CHUNK_COUNT)` and none repeats. One pass range-checks every key and notes whether the list is
+ * already strictly ascending, which an index read off a `.crbm` always is; only a list that is not is sorted and scanned
+ * for a repeat. The caller gets a list of its own.
+ */
 export declare function checkedChunkKeys(listed: Iterable<number>): number[];
 /**
  * The other half of invariant 5: a chunk payload holds **remainders** — 16-bit offsets within one chunk — so

package/dist/core/chunk-window.d.ts

@@ -3,15 +3,16 @@
  * With `ramp`, the window opens 1, 2, 4 … wide (or at `rampStart`, then doubling) up to `max` instead of `max` at once, so a consumer that stops
  * after a few chunks has fetched a handful, not a full window.
  *
- * `T` is whatever one read yields (a decoded chunk, or the raw bytes of one). Each read is wrapped to resolve and
+ * `T` is whatever one read yields (a decoded chunk, or the raw bytes of one), and `K` what names a read to launch: a
+ * chunk key, or a planned range. The reads to launch are a list, or an iterator pulled from only as the window opens
+ * a read, so a long plan is never made ahead of what the window can hold. Each read is wrapped to resolve and
  * never reject, so a read nobody consumes (the consumer stopped, or an earlier chunk failed) cannot raise an
  * unhandled rejection; its error surfaces from {@link take} only if the consumer reaches that chunk. Memory is
  * bounded by the window: at most `max` results are held ahead.
  *
  * Internal to core: not exported from any entry point.
  */
-export declare class ChunkWindow<T> {
-    private readonly keys;
+export declare class ChunkWindow<T, K = number> {
     private readonly fetch;
     private readonly max;
     private readonly ramp;
@@ -20,9 +21,15 @@ export declare class ChunkWindow<T> {
     private readonly open;
     private launched;
     private taken;
-    constructor(keys: readonly number[], fetch: (chunkKey: number) => Promise<T>, max: number, ramp: boolean, 
+    private readonly list;
+    private readonly source;
+    /** What the source threw, so a later {@link take} throws it again rather than reading the spent source as done. */
+    private failure;
+    constructor(keys: readonly K[] | Iterator<K>, fetch: (key: K) => Promise<T>, max: number, ramp: boolean, 
     /** With `ramp`, the width the window opens at (default 1). */
     rampStart?: number);
+    /** The next read to launch, or {@link DONE} when there is none. */
+    private nextKey;
     /** Resolves once every read launched and not yet taken has settled; it never rejects, as the reads never do. */
     settle(): Promise<void>;
     /** The next read's result in key order, or the error that read raised. */

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

@@ -21,7 +21,7 @@ export type ExprNode = {
     readonly kids: readonly ExprNode[];
 };
 /** How many nodes one {@link compileExpr} call may still allocate; shared across the expressions of one output. */
-export interface NodeBudget {
+interface NodeBudget {
     remaining: number;
 }
 /**
@@ -38,8 +38,6 @@ export interface KeyBounds {
     readonly keys: Uint16Array;
     readonly card: Uint32Array;
 }
-/** The keys of an operand the plan cannot know (a fed one): every key. Compared by identity, never by content. */
-export declare const ANY_KEYS: Uint16Array;
 /** The bounds of an operand the plan cannot know. */
 export declare const ANY_BOUNDS: KeyBounds;
 /** What {@link planKeys} keeps of each operator node: the keys it can be non-empty at. */

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

@@ -1,18 +1,3 @@
-/**
- * The chunk-ordered feed of a batch combine: operands that arrive as records, one chunk key at a time, and are checked
- * and converted as they arrive. Pure: it reads through the iterable it is given and knows no store, clock or storage.
- *
- * ```
- * record { key, operands: { name: Uint32Array } }
- *   check    key in range and not below the last; every name declared; every value a real Uint32Array; ids strictly
- *            ascending and inside the key; each operand at most once per key        (a refusal, never a repair)
- *   convert  each operand's ids into one compressed bitmap, charged to the ledger as it is built
- *   group    the records of one key, held until a record with a higher key arrives or the feed ends
- * end of feed   counts equal what was seen; a declared operand that never appeared is refused unless allowed
- * ```
- *
- * Nothing here ever reads a bad feed as fewer members: every check is a refusal, and a refusal ends the feed.
- */
 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 {
@@ -56,7 +41,7 @@ export declare class FeedClosed extends Error {
 export declare class FeedStale extends Error {
 }
 /** What a {@link FeedCursor} needs from the pass that runs it. */
-export interface FeedCursorDeps {
+interface FeedCursorDeps {
     readonly feed: CheckedFeed;
     readonly codec: CodecInterface;
     /** The index the first fed operand has among the call's operands. */
@@ -136,3 +121,4 @@ export declare class FeedCursor {
     /** The counts and the empty rule, run once, after the iterator has ended and before anything is published. */
     private finish;
 }
+export {};

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

@@ -11,8 +11,6 @@ export { MAX_EXPR_DEPTH, MAX_EXPR_NODES } from './combine-expr.js';
 export type { CombineManyFeed, CombineManyFeedRecord } 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;
-/** The largest `publishConcurrency` and `concurrency` a call may ask for. */
-export declare const MAX_BATCH_PARALLELISM = 1024;
 /** One named stored operand, as the pass reads it. */
 export interface CombineManyOperand {
     readonly name: string;
@@ -246,8 +244,6 @@ export interface CombineManyRun<R> {
 export interface CompiledCombineMany<R> {
     readonly request: CombineManyRequest<R>;
 }
-/** The most nodes the expressions of one call may hold in all, so that a thousand large outputs cannot be planned at once. */
-export declare const MAX_CALL_NODES = 200000;
 /**
  * Check a request: every expression, option and number, before any request is made. Throws {@link ValidationError}
  * naming the output index and the path. Pure.
@@ -259,7 +255,7 @@ export declare function compileCombineMany<R>(request: CombineManyRequest<R>): C
  */
 export declare function rebindCombineMany<R>(compiled: CompiledCombineMany<R>, operands: readonly CombineManyOperand[]): CompiledCombineMany<R>;
 /** What {@link GroupCost} reads of an output. */
-export interface GroupCostItem {
+interface GroupCostItem {
     readonly bound: number;
     readonly serializedBound: number;
     readonly rootKeys: Uint16Array;
@@ -270,14 +266,15 @@ export interface GroupCostItem {
 }
 /**
  * Work counters of the planner, for the tests that hold it to its cost: how many times a group was priced, how many
- * operands those prices walked, and how many group plans were built. Plain numbers, never read by the planner.
+ * operands those prices walked, and how many group plans were built. A call counts into the one it is given
+ * ({@link runCombineManyCounted}), and into none otherwise; the planner never reads them.
  */
-export declare const combineWork: {
+export interface PlanWork {
     adds: number;
     withs: number;
     operandSteps: number;
     planBuilds: number;
-};
+}
 /**
  * The resident bytes a group needs, kept as outputs are added so that one is priced in work proportional to its own
  * operands, not to the group's size: its buffered outputs, its operand streams, the chunks being evaluated, the objects
@@ -286,6 +283,8 @@ export declare const combineWork: {
 export declare class GroupCost {
     private readonly streamBytes;
     private readonly publishConcurrency;
+    /** Where this pricing is counted, when it is. */
+    private readonly work?;
     private outputs;
     private depth;
     /** The serialized bounds of the largest outputs, descending: at most `publishConcurrency` of them are written at once. */
@@ -294,7 +293,9 @@ export declare class GroupCost {
     private streams;
     private planWork;
     private readonly operands;
-    constructor(streamBytes: (operand: number) => number, publishConcurrency: number);
+    constructor(streamBytes: (operand: number) => number, publishConcurrency: number, 
+    /** Where this pricing is counted, when it is. */
+    work?: PlanWork | undefined);
     /** The cost of the group with `o` added. */
     with(o: GroupCostItem): number;
     add(o: GroupCostItem): void;
@@ -313,6 +314,8 @@ export declare class GroupCost {
  * budget, both before any chunk is read.
  */
 export declare function runCombineMany<R>(compiled: CompiledCombineMany<R>, deps: CombineManyDeps): Promise<CombineManyRun<R>>;
+/** {@link runCombineMany}, counting the planner's work into `work`. Not exported from the package. */
+export declare function runCombineManyCounted<R>(compiled: CompiledCombineMany<R>, deps: CombineManyDeps, work: PlanWork): Promise<CombineManyRun<R>>;
 /**
  * The `pointerId` of a row's version (`<generation>:<pointerId>`, as a pin holds it), or `undefined` where the version
  * names no row. A live version from the `.crbm` source ends with the opened object's fingerprint: read it through

package/dist/core/concurrency.d.ts

@@ -13,3 +13,11 @@
  * S3 page, chunk map), so an array keeps the pool trivial and race-free (no shared-iterator hazard).
  */
 export declare function mapWithConcurrency<T, R>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
+/**
+ * `Promise.all` over `items` with at most `limit` calls of `fn` in flight: the results in input order, or the first
+ * failure, at once. Unlike {@link mapWithConcurrency} it does not wait for the calls still in flight before it rejects,
+ * as `Promise.all` does not; it starts no call after a failure, and what the calls in flight answer is dropped. For reads
+ * a caller abandons on the first fault, never for work that must finish or be accounted for once begun. When every item
+ * fits under `limit` it is `Promise.all` itself, so a small fan-out costs and interleaves exactly as `Promise.all` does.
+ */
+export declare function boundedAll<T, R>(items: readonly T[], limit: number, fn: (item: T) => Promise<R>): Promise<R[]>;

package/dist/core/consistency.d.ts

@@ -3,18 +3,23 @@
  * generations can be restored **independently**, so a failover can recover the registry *ahead of* the storage
  * objects — leaving `currentGen` pointing at a generation whose `.crbm` isn't present yet. That is likelier
  * than it sounds even with both in one bucket: a restore scoped to a prefix, or replayed
- * per-object from a version history, recovers the two prefixes at different points. That's a torn restore: reads of the affected segment then throw. This scan
+ * per-object from a version history, recovers the two prefixes at different points. That's a torn restore: reads of
+ * 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
- * `errored` (never aborts the scan). Each segment is checked against its **authoritative live pointer** — one
+ * `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.
+ * Each segment is checked against its **authoritative live pointer** — one
  * strong `registry.get` per segment — never the enumeration snapshot from `registry.list`, which a driver may
  * serve eventually-consistently and so lag a recent in-place pointer advance: trusting it would both
  * miss a torn *live* generation and cry torn on a generation the pointer has already advanced past (GC'd during
- * the scan). Residual: a load's publish plus a GC landing in the tiny per-segment get→list gap can still yield a
- * transient false positive — run the scan against a quiesced fleet (the documented restore procedure), or re-run
- * to confirm a reported tear.
+ * the scan). Residual: a load's publish plus a GC landing in the per-segment gap between the pointer read and the
+ * object reads (one read, or with `generations` as many as the ledger names) can still yield a transient false
+ * positive — run the scan against a quiesced fleet (the documented restore procedure), or re-run to confirm a
+ * reported tear.
  */
 import type { IStorageDriver, IRegistryDriver } from './ports.js';
 import type { IKeystore } from './crypto.js';
@@ -33,7 +38,11 @@ export { DEFAULT_MAX_SCAN_SEGMENTS } from './registry-scan.js';
 export interface ConsistencyIssue {
     readonly segment: string;
     readonly namespace?: string;
-    /** The registry's `currentGen` for the segment — the generation whose `.crbm` is missing from Storage. */
+    /**
+     * The registry's `currentGen` for the segment. For `missing-storage-generation` it is the generation whose `.crbm` is
+     * missing from Storage; for the other issues it is the segment's current generation, whichever generation the issue
+     * is about (see `generation`).
+     */
     readonly currentGen: number;
     /**
      * `missing-storage-generation`: `currentGen` references a Storage generation that is not present (torn restore).
@@ -44,8 +53,20 @@ export interface ConsistencyIssue {
      * that opens the object refuses it; one whose count or metadata disagrees is answered from until a read opens the
      * object, which stops that store using it; one whose fingerprint names no object is not used, so every read opens the
      * object unchecked.
+     * `known-generation-mismatch` (only when asked for): the object under the number `generation` is not the one the row's
+     * ledger of known generations recorded for it: its footer checksum differs, or its footer fails its own checks (it is
+     * not a `.crbm` object, or is cut short). It says nothing of what a rollback does with that generation.
+     * What it covers: each object's footer is held to the recorded checksum, so another object, or bytes that are not a
+     * `.crbm`, under a known number is found. It does not find damage inside an object whose footer is intact (a cut or a
+     * flipped byte in the body: a read of that generation reports it as `IntegrityError`), nor a metadata change that keeps
+     * the footer's bytes.
      */
-    readonly issue: 'missing-storage-generation' | 'summary-mismatch';
+    readonly issue: 'missing-storage-generation' | 'summary-mismatch' | 'known-generation-mismatch';
+    /**
+     * With `known-generation-mismatch` only: the generation whose object is not the one the row recorded. It is
+     * `currentGen` when the current object is the one that differs. Absent on every other issue.
+     */
+    readonly generation?: number;
 }
 /** A segment that could not be checked this pass (Storage/registry read fault) — not proof of a torn restore. */
 export interface ConsistencyErrorEntry {
@@ -57,12 +78,17 @@ export interface ConsistencyErrorEntry {
 export interface ConsistencyReport {
     /** Registered segments scanned (a `destroyed` segment counts as scanned but is never an issue). */
     readonly checked: number;
-    /** Segments whose `currentGen` `.crbm` is absent — recover the object store (or restore to a coherent point). */
+    /**
+     * The issues found, one entry each: a segment whose `currentGen` `.crbm` is absent (recover the object store, or
+     * restore to a coherent point), and with the options asked for the other kinds. One segment can have several entries:
+     * at most one for its current object plus one per entry of its ledger, so at most 1 plus the ledger's length (384 at
+     * most). The ledger's length is bounded by the registry, and the report is not capped.
+     */
     readonly inconsistent: ConsistencyIssue[];
     /**
      * Segments that couldn't be read this pass (a transient/partial object store during a restore is exactly when
-     * this runs) — **triage these too**: an unread segment is neither proven-coherent nor proven-torn. Empty on a
-     * clean pass.
+     * this runs) — **triage these too**: an unread segment is neither proven-coherent nor proven-torn. A segment can be in
+     * this list and in `inconsistent` too: what was found before the read that failed is kept. Empty on a clean pass.
      */
     readonly errored: ConsistencyErrorEntry[];
     /**
@@ -71,19 +97,44 @@ export interface ConsistencyReport {
      * only when summaries were asked for.
      */
     readonly summariesUnchecked?: number;
+    /**
+     * With `generations: true`, the rows with a pointer whose ledger of known generations could not be used (absent, or
+     * failing the validation every reader of it applies, or not shaped as a ledger a registry of this library stores):
+     * none of their known generations was held against its object. A count, not an issue. Present only when generations
+     * were asked for.
+     */
+    readonly generationsUnchecked?: number;
 }
 /**
  * Verify every registered segment's `currentGen` `.crbm` actually exists in Storage. Enumerates the registry
- * (optionally one namespace) and, for each non-`destroyed` segment, checks the object store lists that
- * generation. Returns the torn segments in `inconsistent` (empty ⇒ coherent) and any unreadable segments in
+ * (optionally one namespace) and, for each non-`destroyed` segment, asks the object store for that generation with a
+ * zero-length tail read. Returns the torn segments in `inconsistent` (empty ⇒ coherent) and any unreadable segments in
  * `errored`.
  *
+ * When that read fails, in any way, the segment's listing decides and its own error is the segment's, so a missing
+ * object, a missing bucket and a failing store are reported as when every segment was listed. One difference: a store
+ * that answers reads but refuses listings (an identity without list permission, or a listing-only outage) reports each
+ * object that is there as present, where every segment was reported errored.
+ *
  * With `summaries: true` it also opens each segment's current object (one tail read, and a second for an index longer
- * than it) and holds the row's summary against it: the object it names by its fingerprint, and the count and metadata it
- * says, reporting `summary-mismatch` where they disagree, and for a clear summary whose fingerprint names no object,
- * which no read uses. A sealed summary
- * needs `deps.keystore`; without it the segment is counted in `summariesUnchecked`. Off by default, since the
- * default check only lists.
+ * than it) and holds the row's summary against it: the object it names by its fingerprint, and the count and metadata
+ * it says, reporting `summary-mismatch` where they disagree, and for a clear summary whose fingerprint names no
+ * object, which no read uses. For a row with a clear summary that open is the only request of the object; if it fails
+ * before its first read answered, the listing decides, and once that read has answered a failure is an error of the
+ * segment. A sealed summary needs `deps.keystore`; without it the segment is counted in `summariesUnchecked`. Off by
+ * default, since the default check only looks for the object.
+ *
+ * With `generations: true` it also holds every generation a row's ledger of known generations names, the current one
+ * included, against its object: one footer read each (104 bytes, no key, not retried), reporting
+ * `known-generation-mismatch` with the `generation` where the object's footer checksum is not the one the ledger records
+ * or its footer fails its own checks. That finds another object, or bytes that are not a `.crbm`, under a known number;
+ * it does not find damage inside an object whose footer is intact (a read of it reports that as `IntegrityError`), nor a
+ * metadata change that keeps the footer's bytes. A segment adds at most 1 plus its ledger's length issues. A named
+ * generation that is not in the bucket is not reported. A row with a pointer whose ledger cannot be used (absent, failing
+ * the validation every reader of it applies, or not shaped as a ledger a registry of this library stores) is counted in
+ * `generationsUnchecked` and none of its objects is read. The listing is not used: a read of a missing object
+ * answers `NotFoundError`, which is how an absent one is told. A segment whose current object is missing is reported as
+ * ever and its older generations are still checked. Off by default.
  */
 export declare function runConsistencyCheck(deps: {
     readonly storage: IStorageDriver;
@@ -94,4 +145,5 @@ export declare function runConsistencyCheck(deps: {
     concurrency?: number;
     maxScanSegments?: number;
     summaries?: boolean;
+    generations?: boolean;
 }): Promise<ConsistencyReport>;

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

@@ -11,6 +11,11 @@ export declare function fingerprintParts(fingerprint: unknown): {
     readonly size: number;
     readonly footerCrc: number;
 } | undefined;
+/**
+ * The footer CRC of a fingerprint a writer or a reader produced, which a row's ledger records beside the generation.
+ * Throws {@link IntegrityError} for text that is not a fingerprint, which neither produces.
+ */
+export declare function footerCrcOf(fingerprint: string): number;
 /**
  * A fingerprint spelled short, for a key a read builds on every chunk: its size and its footer's CRC in base 36,
  * `<size>.<crc>`. Two compact spellings are equal exactly when the fingerprints are.