@cloudbitmaps/core 0.19.1 → 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

@@ -3,7 +3,7 @@
  * from the metrics sink (`IMetricsSink`). Different audience (an audit log / SIEM, not a dashboard), different
  * retention, and only the compliance-relevant *state changes* — never routine reads/writes (that's the metrics
  * sink). It doubles as the GDPR Art. 30 "record of processing" surface: publishes, refused loads, rollbacks,
- * rewrites, erasures and disposals.
+ * rewrites, an erasure's deletion of the generations holding an id, crypto-shreds and disposals.
  *
  * Like `Clock`/`Rng`/`IMetricsSink`, it's injected (into the operations that emit — a load, the `*Into`
  * verbs, a rollback, the erasure rewrite, crypto-shred, disposal and the retention sweep) and wrapped
@@ -16,17 +16,29 @@
  * wrappings, no data re-encryption), so there is no library call to hook. A future `rewrapSegment()` op would
  * add a `kek.rotate` variant; until then, audit key changes at your keystore-config layer.
  */
-/** A security/compliance-relevant state change. Vendor-neutral; the sink adds its own timestamp/actor. */
+/**
+ * A security/compliance-relevant state change. Vendor-neutral; the sink adds its own timestamp/actor.
+ *
+ * Every event about a segment carries `incarnation`: the id of the registry row's incarnation the operation acted on.
+ * A segment's name can be purged and created again, and its generations then start again at `0`; the incarnation
+ * tells those lives of the name apart, and every write of a row keeps it. It does not make a generation number name
+ * one object for good: within one incarnation, a number whose object was deleted (a refused load's object, or a
+ * generation an erasure deleted above the pointer) can be taken again by a later load. It is absent when the row's
+ * token carries no incarnation id, for example from a registry of the caller's own that issues tokens in another
+ * form, and on a `segment.load-refused` from a load that found no row.
+ */
 export type AuditEvent = {
     /** A new immutable Storage generation *became the segment's current generation*, by a load's publish. */
     readonly kind: 'segment.publish';
     readonly namespace?: string;
     readonly segment: string;
+    /** The incarnation of the row whose pointer the publish moved. */
+    readonly incarnation?: string;
     readonly generation: number;
 } | {
     /**
      * 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
@@ -38,8 +50,18 @@ export type AuditEvent = {
     readonly kind: 'segment.rollback';
     readonly namespace?: string;
     readonly segment: string;
+    /** The incarnation of the row whose pointer the rollback moved. */
+    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
@@ -59,6 +81,8 @@ export type AuditEvent = {
     readonly kind: 'segment.load-refused';
     readonly namespace?: string;
     readonly segment: string;
+    /** The incarnation of the row the load read before it wrote; absent when it found no row. */
+    readonly incarnation?: string;
     readonly generation: number;
     readonly reason: 'empty' | 'min-cardinality' | 'min-retained' | 'max-growth' | 'superseded';
     readonly cardinality: number;
@@ -69,13 +93,48 @@ export type AuditEvent = {
      * place. Today the one emitter is `eraseIdFromSegment` (a subject erasure clearing one id), and the event is
      * emitted at the publish — before the superseded generation is collected — so the record exists the moment
      * the generation without the id is authoritative. A `segment.publish` is NOT also emitted for a rewrite: a
-     * rewrite derives its content from the segment itself, a publish brings content in from outside.
+     * rewrite derives its content from the segment itself, a publish brings content in from outside. An erasure
+     * that finds the id only outside the current generation, or deletes only objects no read of the segment can
+     * open, rewrites nothing and emits `segment.collect`.
      */
     readonly kind: 'segment.rewrite';
     readonly namespace?: string;
     readonly segment: string;
+    /** The incarnation of the row the rewrite read `fromGeneration` from and published on. */
+    readonly incarnation?: string;
     readonly fromGeneration: number;
     readonly generation: number;
+} | {
+    /**
+     * An erasure of one id **deleted objects** no reader resolves, and rewrote none. It found the id only in such
+     * objects, or deleted only objects no read of the segment can open, which it cannot search and deletes whatever
+     * the id. The cases: an id that only generations other than the current one hold (someone who left the segment,
+     * whose bit the reader grace window or a rollback target keeps); objects left under a tombstone (a cleartext
+     * destroy, or a drop whose sweep left one); a first load's object on a segment with no generation yet (its load
+     * still running, or one that crashed before its publish); and an object sealed under a key the segment's row does
+     * 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.
+     *
+     * `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
+     * event is the record of the deletion. `collected` is every generation the call deleted, ascending, and the same
+     * list as its result's: below the pointer, when a searched generation held the id, that is every generation,
+     * holder or not, since the deletion takes them all; above it, and wherever none did, only the holders and the
+     * objects it could not search. A holder another collection deleted first is not in it, so the list can be empty.
+     */
+    readonly kind: 'segment.collect';
+    readonly namespace?: string;
+    readonly segment: string;
+    /** The incarnation of the row the erasure read: the active row, or the tombstone. */
+    readonly incarnation?: string;
+    readonly fromGeneration?: number;
+    readonly collected: readonly number[];
 } | {
     /**
      * A segment was **crypto-shredded** — its wrapped DEK(s) are gone, so its at-rest Storage bytes are now
@@ -85,6 +144,8 @@ export type AuditEvent = {
     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 **disposed of** — tombstoned and its storage reclaimed (its Storage generations deleted) by
@@ -106,6 +167,8 @@ export type AuditEvent = {
     readonly kind: 'segment.dispose';
     readonly namespace?: string;
     readonly segment: string;
+    /** The incarnation of the tombstone the drop wrote or found. */
+    readonly incarnation?: string;
     readonly generationsDeleted: number;
 } | {
     /** A namespace erasure was executed. `segmentsShredded` is the count actually crypto-shredded (may be 0). */

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;
@@ -26,16 +24,19 @@ export interface CombineManyOperand {
     /** The generation the operand is pinned to: `null` when pinned to a segment with none, `undefined` when not pinned. */
     readonly pinnedGeneration?: number | null;
     /**
-     * The pin's version: the generation and the registry row's token it was taken under (`<generation>:<token>`), or just
-     * the generation where there is no row. It is what tells a name deleted and created again, which restarts at
+     * The pin's version: the generation and the registry row's `pointerId` it was taken under (`<generation>:<pointerId>`),
+     * or just the generation where there is no row. It is what tells a name deleted and created again, which restarts at
      * generation 0, from the one that was pinned.
      */
     readonly pinnedVersion?: string | null;
     /** The fingerprint of the object the pin holds: the identity of the generation's bytes, where a number can be taken again. */
     readonly pinnedFingerprint?: string | null;
     /**
-     * A fresh read of the segment's registry row: its current generation and token, or `null` when it has no row. Read
-     * for every subtracted pinned operand just before the publishes, and once more at the end of the call for the rest.
+     * A fresh read of the segment's registry row: its current generation and, as `token`, its `pointerId` (the token of the
+     * last write that named a field a read resolves through, so a lease or a policy write does not change it), or `null`
+     * when it
+     * has no row. Read for every subtracted pinned operand just before the publishes, and once more at the end of the call
+     * for the rest.
      */
     readonly current?: (options?: {
         readonly fingerprint?: boolean;
@@ -243,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.
@@ -256,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;
@@ -267,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
@@ -283,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. */
@@ -291,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;
@@ -310,9 +314,11 @@ 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 token of a row's version (`<generation>:<token>`, 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
+ * 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
  * `rowVersionOf` first.
  */
 export declare function tokenOfVersion(version: string | null | undefined): string | undefined;

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[]>;