@cloudbitmaps/core 0.19.1 → 0.21.0

package/dist/core/crbm-write.d.ts

@@ -0,0 +1,75 @@
+import type { Yielder } from './cooperative.js';
+import type { CrbmCrypto } from './crypto.js';
+import type { GenerationMetadata, GenKey, IStorageDriver } from './ports.js';
+import type { CodecBitmap, EncodedChunk } from './codec.js';
+/**
+ * Write one immutable generation from in-memory bitmaps. Chunks are
+ * sorted ascending and empty bitmaps skipped (empty chunks are never stored). Returns the driver's
+ * `{ size, sha256 }` for the written object. Pass `options.crypto` to AES-256-GCM-encrypt the generation
+ * (built from the segment's DEK, with associated data bound to `(segment, generation)`).
+ */
+export declare function writeCrbmGeneration(driver: IStorageDriver, key: GenKey, chunks: Iterable<{
+    chunkKey: number;
+    bitmap: CodecBitmap;
+}>, options?: {
+    crypto?: CrbmCrypto;
+    clock?: Yielder;
+    metadata?: GenerationMetadata;
+}): Promise<{
+    size: number;
+    sha256: string;
+    fingerprint: string;
+    tailBytes: number;
+}>;
+/** Each non-empty bitmap as the chunk it stores, in the order given. */
+export declare function encodeEach(chunks: Iterable<{
+    chunkKey: number;
+    bitmap: CodecBitmap;
+}>): Generator<EncodedChunk>;
+/**
+ * Write one immutable generation from chunks already encoded, which must ascend by key (the writer refuses one
+ * that does not). Returns the driver's `{ size, sha256 }` and a tally of what was written.
+ */
+export declare function writeEncodedChunks(driver: IStorageDriver, key: GenKey, chunks: Iterable<EncodedChunk>, options: {
+    crypto?: CrbmCrypto;
+    clock?: Yielder;
+    metadata?: GenerationMetadata;
+}): Promise<{
+    size: number;
+    sha256: string;
+    chunkCount: number;
+    cardinality: number;
+    fingerprint: string;
+    /** The bytes after the chunk payloads ({@link CrbmReader.tailBytes}). */
+    tailBytes: number;
+}>;
+/** What {@link writeCrbmGenerationStream} wrote: the driver's `{ size, sha256 }` + a tally of the generation. */
+interface StreamWriteResult {
+    readonly size: number;
+    readonly sha256: string;
+    /** Non-empty chunk keys written, in ascending order (for the post-write verify, since the stream is consumed). */
+    readonly chunkKeys: number[];
+    /** Total ids written. */
+    readonly cardinality: number;
+    /** The fingerprint of what this call wrote ({@link CrbmReader.fingerprint}), which tells it from another object under its key. */
+    readonly fingerprint: string;
+    /** The bytes after the chunk payloads ({@link CrbmReader.tailBytes}). */
+    readonly tailBytes: number;
+}
+/**
+ * Streaming variant of {@link writeCrbmGeneration} for a **constant-memory** rewrite (the erasure rewrite, a
+ * sorted load): consumes an **already-ascending** async stream of `{ chunkKey, bitmap }`, feeding each to the
+ * codec and freeing it, instead of materializing the whole generation. Paired with a streaming storage sink (S3
+ * multipart / LocalFs temp file), the writer itself holds ~one chunk + one part. Returns a tally so the caller can verify
+ * the re-opened object without re-iterating the (now-consumed) stream. Input **must** be ascending by `chunkKey`
+ * — the codec rejects an out-of-order chunk; empty bitmaps are skipped.
+ */
+export declare function writeCrbmGenerationStream(driver: IStorageDriver, key: GenKey, chunks: AsyncIterable<{
+    chunkKey: number;
+    bitmap: CodecBitmap;
+}>, options?: {
+    crypto?: CrbmCrypto;
+    clock?: Yielder;
+    metadata?: GenerationMetadata;
+}): Promise<StreamWriteResult>;
+export {};

package/dist/core/crypto.d.ts

@@ -56,7 +56,10 @@ export interface IKeystore {
     /**
      * Reconstruct the {@link Aead} from a segment's stored wrappings by unwrapping with any KEK currently held.
      * Throws {@link KeyUnavailableError} if it holds none of the referenced KEKs (lost key, or a shredded
-     * segment whose wrappings were deleted).
+     * segment whose wrappings were deleted). Throw {@link TransientError} for a fault worth riding out (a throttle, a 5xx,
+     * a dropped connection, a request timeout): a rollback below a segment's pointer goes ahead without the key on that
+     * error, as on `KeyUnavailableError`, an `IntegrityError` or an `Error` named `TimeoutError`, and is stopped by any
+     * other error the keystore throws.
      */
     openDek(wrapped: readonly WrappedDek[]): Promise<Aead>;
 }
@@ -82,3 +85,5 @@ export declare function aadFor(ref: {
     readonly namespace?: string;
     readonly segment: string;
 }, generation: number, scope: number | 'index' | 'metadata' | 'summary'): Uint8Array;
+/** Whether two rows carry the same wrapped keys. */
+export declare const sameKeys: (a: readonly WrappedDek[] | undefined, b: readonly WrappedDek[]) => boolean;

package/dist/core/engine.d.ts

@@ -3,7 +3,7 @@ import type { Budget, BudgetOption } from './budget.js';
 import type { Clock } from './determinism.js';
 import type { BoundedLru } from './lru.js';
 import type { IMetricsSink } from './metrics.js';
-import type { GenerationMetadata, StorageChunkSource, SegmentRef, SegmentSize } from './ports.js';
+import type { GenerationMetadata, StorageChunkSource, SegmentRef } from './ports.js';
 /**
  * Range requests a stream holds ahead of a combine or `iterate` by default (chunk keys, on a source that reads chunk by
  * chunk, and for `count`'s fallback) — bounds memory and concurrent reads (invariant 6). A read that does not fit
@@ -13,7 +13,11 @@ import type { GenerationMetadata, StorageChunkSource, SegmentRef, SegmentSize }
 export declare const DEFAULT_INTERSECT_CONCURRENCY = 32;
 export interface EngineDeps {
     readonly storage: StorageChunkSource;
-    /** Optional cache of decoded (immutable) Storage chunks. */
+    /**
+     * Optional cache of decoded (immutable) Storage chunks. A cache whose `size` is 0 is taken to hold nothing: a read
+     * that opens a stream on it looks up the chunk the stream starts at and counts each later chunk a miss without
+     * looking it up.
+     */
     readonly cache?: BoundedLru<string, CodecBitmap>;
     /** Per-chunk decode ceiling (invariant 5); defaults to 1 MiB. The `.crbm` reader refuses an entry above its own `maxPayloadBytes` (1 MiB, plus 28 bytes when encrypted) at open, so raise that on the chunk source too. */
     readonly maxBitmapBytes?: number;
@@ -33,6 +37,19 @@ export interface EngineDeps {
      * Read ops refuse before fan-out if they'd exceed it.
      */
     readonly budget?: Budget | null;
+    /**
+     * An engine over the same `cache` whose invalidations this one shares: an {@link SegmentEngine.invalidate} through
+     * either reaches the reads running on both. It is opt-in, and engines that read through one chunk cache must be
+     * built with it: two built without it share nothing, so a read running on one when the other invalidates its
+     * segment writes the chunks it read before the invalidation back into the cache, and later reads through it are
+     * answered from them, an erased id included, until the cache evicts them. The `CloudRoaring` facade builds the
+     * engines of its pins and of its combines with a pinned operand this way.
+     *
+     * The engines share their requests in flight too: a cache miss on one joins a request the other opened for the same
+     * cache key, and gets what that engine's storage, codec and `maxBitmapBytes` made of it, as a cache hit hands over
+     * the chunk the other decoded. Throws {@link ValidationError} unless it is a `SegmentEngine` over the same `cache`.
+     */
+    readonly sharesInvalidationsWith?: SegmentEngine;
 }
 /**
  * A range of ids for a read to yield: those greater than `after` and no greater than `through`, `(after, through]`.
@@ -44,8 +61,9 @@ export interface EngineDeps {
  * a combine's operands exist.
  *
  * A read with a range fetches only the chunks the range overlaps, on a combine for every operand and every
- * `exclude`. The per-op budget is charged once, before the first fetch, for every chunk in the range, so with
- * `after` alone it is charged to the end of the segment however early the caller stops; pass `through` to bound it.
+ * `exclude`. The per-op budget is charged before the first fetch, for every chunk in the range, so with `after` alone
+ * it is charged to the end of the segment however early the caller stops; pass `through` to bound it. A read that
+ * lists its keys again after a move is charged again, with the chunks it has already taken.
  */
 export interface IdRange {
     /** Exclusive lower bound: the read yields only ids greater than this. */
@@ -63,7 +81,7 @@ export interface CombineOptions extends IdRange {
      * is larger), about `concurrency × operands` MiB are held, whatever the segment's size. The stream opens 4 ranges wide
      * (or `concurrency`, if lower) and widens as ranges are taken, so a read that stops early has asked for little past
      * where it stopped, and a read that fits one range makes one request however many chunks it needs. A source that
-     * reads chunk by chunk (a custom one) is read as before: `concurrency` chunk keys at once, opening 8 wide. A running
+     * reads chunk by chunk (a custom one) is read `concurrency` chunk keys at once, opening 8 wide. A running
      * stream holds its operand's reader outside the reader cache's bounds until it ends or the segment moves on.
      */
     readonly concurrency?: number;
@@ -94,18 +112,10 @@ export declare class SegmentEngine {
     /** Resolved per-op budget (null = disabled); undefined deps ⇒ the generous default. */
     private readonly budget;
     /**
-     * The chunk reads open right now, by cache key: a caller that misses the cache and finds its key here awaits that
-     * read instead of making its own. An entry lives from the request until it settles, so the map holds at most one
-     * promise per distinct key in flight.
-     */
-    private readonly openReads;
-    /**
-     * The chunk streams open right now. An {@link invalidate} of a segment marks its streams, which then cache no chunk
-     * they deliver, as a read whose entry an invalidation dropped does not (streams hold no `openReads` entry).
+     * The invalidations this engine shares with every engine over its chunk cache that was built to share them
+     * ({@link EngineDeps.sharesInvalidationsWith}), and the chunk reads open on all of them.
      */
-    private readonly openStreams;
-    /** How many times {@link invalidate} has been called: a read compares it with the count it began under. */
-    private invalidations;
+    private readonly scope;
     /**
      * The cache-key prefixes ({@link segmentPrefix}) of the segments this engine reads, kept rather than encoded for each
      * chunk. A kept prefix is the one {@link invalidate} finds the segment's chunks by.
@@ -128,26 +138,32 @@ export declare class SegmentEngine {
      */
     count(seg: SegmentRef): Promise<number>;
     /**
-     * What the segment's current generation is: its number, its id count and its metadata, from one resolution, so the
-     * three cannot straddle a publish. A source with no summary answers from `count()` and the generation it resolves.
+     * What the segment's current generation is: its number, its id count, its metadata and the size of its object in
+     * bytes. A source with a `stat` (the `.crbm` source) answers all four from one resolution, so they cannot straddle
+     * a publish: from the registry row's summary when it can use it, else from the opened generation's footer and
+     * index, with no payload read. A source without one answers from its other methods, each its own resolution: its
+     * summary when it has one, else `count()` and the generation it resolves, and its `sizeOf`, or `sizeBytes: null`
+     * when it has none. A segment with no generation answers `{ generation: null, cardinality: 0, sizeBytes: null }`.
      */
     stat(seg: SegmentRef): Promise<{
         generation: number | null;
         cardinality: number;
         metadata?: GenerationMetadata;
+        sizeBytes: number | null;
     }>;
-    /** Whether the Storage source can measure segment size (for grounded cost); false ⇒ storage isn't grounded. */
-    get supportsStorageSize(): boolean;
-    /** How often the Storage source re-reads a pointer while reading (cost reporting); undefined if it does not say. */
-    get pointerRefreshMs(): number | undefined;
-    /** Grounded Storage size of a segment's current generation (cost reporting), or null if it has no generation. */
-    segmentSize(seg: SegmentRef): Promise<SegmentSize | null>;
-    /** The chunks of `seg` at `chunkKeys`, read through a window of {@link DEFAULT_INTERSECT_CONCURRENCY}. */
+    /** The size of the segment's current generation from the source's `sizeOf`, or `null` when it cannot say. */
+    private sizeOf;
+    /**
+     * The chunks of `seg` at `chunkKeys`, read through a window of {@link DEFAULT_INTERSECT_CONCURRENCY}. A cached chunk
+     * that is no longer the segment's version marks `moves`, when given.
+     */
     private chunkWindow;
     /**
      * The chunks of `seg` at `chunkKeys`, taken in ascending key order by a read that may stop at any point: one stream of
      * coalesced ranges when the source has `getChunks`, opening 1, 2, 4 … ranges wide up to {@link DEFAULT_INTERSECT_CONCURRENCY},
-     * else the chunk-by-chunk window of that many reads. `close` stops what is left of it.
+     * else the chunk-by-chunk window of that many reads. `close` stops what is left of it. A chunk that shows the segment
+     * moved marks `moves`: one of the stream named by another version, or one cached under `gen` that is no longer the
+     * segment's.
      */
     private chunkSequence;
     /**
@@ -157,9 +173,13 @@ export declare class SegmentEngine {
      * chunks the range overlaps (see {@link IdRange}). A source that reads chunk by chunk is read through a window of up to
      * 32 chunk fetches that opens 1, 2, 4 … 32 wide.
      *
+     * The chunk keys are listed once, before the first fetch. A move of the segment the read meets while it runs (see
+     * {@link Moves}) lists them again, from the generation current then, and the read goes on with the keys above the one
+     * it last took: it reads a chunk the new generation added, and not one it dropped.
+     *
      * Two generators, not one with a branch: a second `yield` site in the full read's generator grows its frame, and
-     * every id of a read that asked for no range paid for it (measured at about 5% per id). The full read keeps the
-     * loop it always had.
+     * every id of a read that asked for no range paid for it (measured at about 5% per id). The full read keeps one
+     * `yield`, in a loop of its own.
      */
     iterate(seg: SegmentRef, range?: IdRange): AsyncGenerator<number>;
     private iterateAll;
@@ -167,10 +187,71 @@ export declare class SegmentEngine {
     /**
      * {@link iterate}, one `Uint32Array` per chunk instead of one id at a time: the same chunks, in the same order, with
      * the same ids (a range cut at its edges the same way), and no array for a chunk that holds none of them. The
-     * reads, the budget charge and the window are the per-id read's. Each array is at most 65,536 ids (256 KiB) and is
-     * the caller's to keep.
+     * reads, the budget charge, the window and a move met while it runs are the per-id read's. Each array is at most
+     * 65,536 ids (256 KiB) and is the caller's to keep.
      */
     iterateBatches(seg: SegmentRef, range?: IdRange): AsyncGenerator<Uint32Array>;
+    /**
+     * Plan an `iterate` of the keys of `seg` above `after` and inside `w`: list them with their version
+     * ({@link listKeys}), charge the budget one storage fetch for each and for each of the `spent` keys earlier plans
+     * took, before any fetch, and open their chunks.
+     */
+    private iteratePlan;
+    /** The first plan of an `iterate`: every key in `w`. */
+    private planIterate;
+    /**
+     * The chunk at the next key of `run`, and `run.key` that key, or `undefined` once its keys are used up. Not `async`:
+     * when nothing has moved and no look is due, the chunk's own promise is all a key costs.
+     */
+    private nextChunk;
+    private takeNext;
+    /**
+     * {@link nextChunk} once the read has looked at its segment's version, and planned again if it is not the one the
+     * plan was made under. A chunk that suggested a move is confirmed so: a source whose chunks name their version
+     * otherwise than its `currentVersion` does costs a look, never a plan.
+     */
+    private nextChunkAfterLook;
+    /**
+     * Plan the rest of `run` again, after a move: the keys above the one it last took, from the generation current now.
+     * What the plan's stream still has in flight is dropped, not served.
+     */
+    private replanIterate;
+    /**
+     * A segment's chunk keys, ascending and checked, and the version they are read under, with the invalidation epoch
+     * they were listed from. The version is resolved AFTER the shape read (`listChunkKeys`): a non-empty shape read means
+     * the source resolved and cached a non-null snapshot, so the version cannot then come back null while storage data is
+     * present, and `storageChunk` cannot skip every chunk on a stale null.
+     *
+     * A write of this store that moves the segment while the two are read would leave the keys of one generation under
+     * the version of the next, and nothing later could tell: the read's chunks and its looks would all name that newer
+     * version. So when the segment was invalidated in this store's scope while they were read, they are read again. Only
+     * that segment's invalidations count, so a store busy invalidating other segments costs a listing nothing more; with
+     * none since the listing began the check is a number compare.
+     *
+     * Honest note on how much the ordering buys, so a future reader does not take an untested claim for a tested one.
+     * Against a `CrbmStorageChunkSource`, the only source with a generation to resolve, both reads go through the same
+     * resolved-reader memo, so the pathological state (keys non-empty, version null) does not arise and swapping the two
+     * is observably identical. The ordering is kept because it is the order that is correct for *any* source satisfying
+     * the port (a custom source that resolves its shape and its generation independently can still produce that state),
+     * not because a test can currently tell the difference. Within a call shorter than `cache.genTtlMs` the two share one
+     * snapshot, so the read is generation-consistent, absent cache-pressure eviction (see `intersect`).
+     */
+    private listKeys;
+    /**
+     * A read's {@link Looks}, from the invalidation epoch `epoch` its plan began at: due at the first key after a later
+     * invalidation, or after `every` keys.
+     */
+    private looks;
+    /**
+     * Whether a look is due before the next key: an invalidation since the read last looked, or its keys counted down. The
+     * caller counts the key, as it takes one, before it asks.
+     */
+    private lookDue;
+    /**
+     * The read looks now, before the key it takes next: the next look is due `every` keys on, or at the next
+     * invalidation. Called before the look awaits, so an invalidation while it waits is met at the next key.
+     */
+    private looked;
     /**
      * The ids at 1-based ranks `n`, `2n`, `3n` … counted over the ids in `range`, ascending. The rank of each boundary
      * is placed from the index's per-chunk counts, so only the chunks that hold a boundary are read, each once however
@@ -219,13 +300,19 @@ export declare class SegmentEngine {
      * the result — every chunk read is a whole, checksum-verified, immutable generation. The edge a *long* call can
      * hit is invariant 3's: if it straddles a mid-call `cache.genTtlMs` boundary and a load has published, an
      * operand's not-yet-requested chunks may re-resolve forward to the newer generation (a generation hop within one long
-     * call) — the call never crashes or returns a torn object, but may mix generations. Three things hop it without
-     * waiting for the TTL, so a shorter call can meet them too: **the reader cache evicting an operand mid-call**
-     * (`maxOpenSegments`), whose re-read re-resolves fresh; a sweep deleting the generation it was reading, which
-     * heals the read forward; and an invalidation, which this store's own `load`, `rollback` and `eraseSubject` make
-     * and `invalidate()` makes on request. Still whole/immutable per read, never torn. An operand's stream resolves its
+     * call) — the call never crashes or returns a torn object, but may mix generations. Some things hop it without
+     * waiting for the TTL, so a shorter call can meet them too: **the reader cache evicting an operand mid-call** on a
+     * store with no timed refresh (`maxOpenSegments`), whose re-read re-resolves fresh, and on a store with one the
+     * resolution cache letting the operand's resolution go; a sweep deleting the generation it was reading, or another
+     * object under its number, met by this read or another, which heals the read forward, as another read's failed open
+     * of the operand does; and an invalidation, which this store's own `load`, `rollback` and `eraseSubject` make and
+     * `invalidate()` makes on request. Still whole/immutable per read, never torn. An operand's stream resolves its
      * segment again before it serves each chunk, so each of those moves a running read as it would a read of one chunk, and
-     * the ranges it had requested of the earlier generation are dropped, not served.
+     * the ranges it had requested of the earlier generation are dropped, not served. The read then lists every operand's
+     * keys again above the key it last took, from the generation current then, so a key an operand gained is read and one
+     * it lost is not asked for. It meets a move through a chunk it is served that comes from another generation than it
+     * listed its keys under, and by looking at its operands' generations before the first key after an invalidation, and,
+     * with an `exclude` or as a union, every `concurrency` keys.
      */
     intersect(segs: readonly SegmentRef[], options?: CombineOptions): AsyncGenerator<number>;
     /**
@@ -270,12 +357,46 @@ export declare class SegmentEngine {
      * read and the batch read share it, so the two cannot disagree about what is read or charged.
      */
     private combinePlan;
+    /**
+     * Each operand's chunk-key set inside the read's range and above the key `after`, and the version it was listed under
+     * ({@link listKeys}), include operands first, each in its order. At most {@link OPERANDS_AT_ONCE} are listed at once;
+     * the first listing to fail rejects the plan at once, and no other is begun after it.
+     */
+    private combineOperands;
+    /**
+     * The operands' streams over `keys` and the window that reads them. Each include is read as a stream of coalesced
+     * ranges, and so is each exclude that is read with the includes (one include, or a union). An exclude that waits on
+     * an AND of two or more includes is read in batches of the keys whose AND is not empty ({@link ExcludeBatch}), since
+     * an emptied AND never needs its chunk. The window starts its first reads at once, so a plan is opened only once its
+     * budget has passed.
+     */
+    private openCombine;
+    /**
+     * The next key's combined chunk of `run`, `undefined` once its keys are used up. Not `async`: when nothing has moved
+     * and no look is due, the window's own promise is all a key costs.
+     */
+    private nextSlot;
+    /**
+     * {@link nextSlot} once the read has looked at every operand's version, and planned again if one is not the version
+     * the plan was made under. An operand the keys left do not read would otherwise never show the read its move: an
+     * exclude whose keys the survivors do not reach, or an include of a union past its last key. A chunk that suggested a
+     * move is confirmed so, as in {@link nextChunkAfterLook}. The versions are looked up at most {@link OPERANDS_AT_ONCE}
+     * at once, all of them: a look that finds no move has compared every one.
+     */
+    private nextSlotAfterLook;
+    /**
+     * Plan the rest of `run` again, after a move: every operand's keys above the key it last took, from the generation
+     * current now, aligned, charged to the budget with the reads of the keys already taken, and read through new streams
+     * and a new window. What the plan it replaces still has in flight is dropped, not served. The absent-operand refusal
+     * and the metric are the first plan's alone: a segment dropped while the read runs reads empty from there on.
+     */
+    private replanCombine;
+    /** Stop the streams of `plan`; the reads its window holds settle on their own and are dropped. */
+    private closeCombine;
     private combine;
     private combineBatches;
     /** The chunk read: the plan every combine shares, then each key's result, cut to the range at its edges. */
     private combineChunks;
-    /** An edge chunk's bitmap cut to the window, as a new bitmap: the remainders `edgeIds` would yield. */
-    private cutToWindow;
     /**
      * The AND (or OR) of one chunk key across all operands, minus the excludes that hold it, or `null` if empty.
      * Operand chunks are fetched **in parallel** (the spec's parallel byte-range reads).
@@ -287,8 +408,64 @@ export declare class SegmentEngine {
      */
     private combineChunk;
     /**
-     * One operand's chunk at `key`: from its stream when it has one, else a read of that chunk on its own. Not `async`,
-     * so a stream's take is made before anything is awaited: concurrent takes of one stream must be made in key order.
+     * Read `exclude` in batches, when the source can read ranges and the exclude has a generation; one that names the same
+     * segment and version as an exclude already opened shares its batch. Nothing is requested until a key asks.
+     */
+    private openBatch;
+    /**
+     * The chunk `exclude` holds at `chunkKey`, for a key whose AND is not empty. One the cache holds, or another read has
+     * in flight, is read as a read of that chunk alone is (cache lookup and version check, or joining the read); only a
+     * chunk that would be requested waits for the batch.
+     */
+    private excludeChunk;
+    /**
+     * Ask `batch` for the exclude chunk at `key`. A batch is read when it holds half the combine's concurrency in keys; when
+     * the asking has gone quiet for {@link BATCH_QUIET_HOPS} turns of the microtask queue (checked as each key asks and as
+     * the caller asks for each slot) and the caller is waiting on a slot, or has come within half a
+     * window of the oldest key held, so a held key is read at least that far ahead of it; and when every key of the combine
+     * has been started (none is left that could still ask).
+     * Refused once the combine has stopped or planned again, so a key it was still working on sends nothing more.
+     */
+    private askBatch;
+    /** Start the wait of `batch` for its asking to go quiet, unless it is running. */
+    private settleSoon;
+    /**
+     * Wait until no key has asked for {@link BATCH_QUIET_HOPS} turns of the microtask queue. If the caller is waiting on a
+     * slot, or is within half a window of the oldest key held, or every key of the combine has been started (so no more
+     * can ask), the keys held are read; otherwise they are held for the keys the combine has yet to start, until half a
+     * window of them is held or the caller comes near. The wait is of microtask turns, so it always ends, and the loop is left rather than spun while
+     * keys are held.
+     */
+    private settleBatch;
+    /** Read the keys `batch` holds now. */
+    private flushBatch;
+    /**
+     * Read the keys that asked: one whose chunk is already being read (by another read, or by an earlier key of this batch
+     * that names it again) joins that read, and the rest are one stream of coalesced ranges over those keys alone, so a
+     * request is sent for each range of them and never for a chunk nobody asked for. The stream is a
+     * {@link StreamedChunks} like an include's, so a chunk is cached under the version it was read from, counted as a cache
+     * hit or miss once, checked against the segment's version when it comes from the cache, and marks `moves` when it
+     * shows the segment moved. Each key it reads is registered as the open read of its chunk, so a read of that chunk by
+     * anything else joins it. Every ask is answered, with its own key's chunk or the error its read raised.
+     */
+    private readBatch;
+    /**
+     * Register the read of the chunk `ref` that a batch's stream makes as its open read, so a read of it by anything else
+     * joins it, until it settles. A joiner does not share the stream's failure: a stream ends at its first failed range
+     * and fails every take after it, those of keys whose own ranges did not fail included, so when the read fails the
+     * entry goes and a joiner reads the chunk on its own, one request for each joined key that failed.
+     */
+    private registerRead;
+    /**
+     * Stop `batch`: the keys still waiting are refused. The streams of the batches in flight are not closed: every range of
+     * one was requested when it was read, a read of one of its chunks by another call may be joined to it, and each closes
+     * itself once its last key is answered.
+     */
+    private closeBatch;
+    /**
+     * One operand's chunk at `key`: from its stream when it has one, else a read of that chunk on its own, whose cached
+     * chunk marks `moves` when it is no longer the operand's version. Not `async`, so a stream's take is made before
+     * anything is awaited: concurrent takes of one stream must be made in key order.
      */
     private operandChunk;
     /**
@@ -302,6 +479,10 @@ export declare class SegmentEngine {
      * not hold. Each later key is counted as a cache hit or miss here, so a key is counted once whichever way it is served.
      */
     private startStream;
+    /**
+     * Stop the stream of `streamed`. Nothing else is kept for an open stream, so a read whose caller drops it without
+     * closing it leaves nothing behind in the engine.
+     */
     private closeStreamed;
     /**
      * The decoded chunk at `chunkKey` of a streamed read: from the cache while the stream is unopened and the cache holds
@@ -321,9 +502,10 @@ export declare class SegmentEngine {
      * stream does for the chunks it delivers; a chunk served from the cache is checked here, or a read whose chunks are
      * all cached would go on serving the generation it planned under, an erased id included, for as long as it is pulled.
      * Within `cache.genTtlMs` the source answers from its snapshot, so the check is a lookup, not a request. `report`:
-     * emit the `cache` event for this lookup, which a key counted when its stream opened does not. `streamed`: the read
-     * this chunk belongs to, which a move carries to the version now current, so the rest of it looks there: a read whose
-     * stream is not yet open reads the rest as one stream, not a chunk at a time.
+     * emit the `cache` event for this lookup, which a key counted when its stream opened does not. `moves`: where the read
+     * this chunk belongs to learns of a move, so it plans its keys again. `streamed`: the read's stream, which a move
+     * carries to the version now current, so the rest of it looks there: a read whose stream is not yet open reads the
+     * rest as one stream, not a chunk at a time.
      */
     private cachedIfCurrent;
     /** The cache key of a chunk: by the version it was read under, or by segment and key alone for a source with none. */
@@ -348,11 +530,20 @@ export declare class SegmentEngine {
      * chunks — a segment with data is self-evidently registered — so the check is a registry read exactly when
      * a combine was about to do something suspicious, and no reads at all otherwise. A source that cannot answer
      * `exists` (it has no notion of registration) skips the check rather than guessing. An operand is judged by
-     * all its chunks, not those inside a range: one with nothing in range but data elsewhere is not suspicious.
+     * all its chunks, not those inside a range: one with nothing in range but data elsewhere is not suspicious. At most
+     * {@link OPERANDS_AT_ONCE} are asked after at once.
      */
     private refuseAbsentOperands;
     /**
-     * Drop every piece of state this engine derived from `ref`, and tell the Storage source to do the same.
+     * Forget what was derived from `ref`: drop its decoded chunks from the chunk cache, which every engine sharing this
+     * one's invalidations reads through, record the invalidation where they all see it, and tell this engine's Storage
+     * source to forget the segment too. An engine sharing the invalidations over another source instance does not tell
+     * its own source: engines that read one source, as the facade's do, need only one of them told. A read of the
+     * segment already running on any of them caches nothing more of what it began reading before the call, whether a
+     * request already in flight or a stream already open; a stream that opens after the call, or a request sent after
+     * it, reads afresh and, on a source that names versions (`currentVersion`), caches what it reads. On one that does
+     * not, a read that began before the call caches nothing from a stream it opens after it, unless the call landed while
+     * 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
@@ -394,8 +585,9 @@ export declare class SegmentEngine {
      * one): callers read it or clone it, never mutate it.
      *
      * `recheck`: `gen` was planned for a read of many chunks, so a cached chunk is served only while it is still the
-     * segment's version ({@link cachedIfCurrent}). A point read resolves `gen` just before it asks, and passes none.
-     * `report`: emit the `cache` event for this lookup; a key already counted for this read does not.
+     * segment's version ({@link cachedIfCurrent}), and one that is not marks `moves`. A point read resolves `gen` just
+     * before it asks, and passes none. `report`: emit the `cache` event for this lookup; a key already counted for this
+     * read does not.
      */
     private storageChunk;
     /**