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

@@ -13,7 +13,11 @@ import type { GenerationMetadata, StorageChunkSource, SegmentRef } from './ports
 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.
@@ -143,12 +153,17 @@ export declare class SegmentEngine {
     }>;
     /** 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}. */
+    /**
+     * 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;
     /**
@@ -158,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;
@@ -168,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
@@ -228,7 +308,11 @@ export declare class SegmentEngine {
      * 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>;
     /**
@@ -273,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).
@@ -290,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;
     /**
@@ -305,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
@@ -324,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. */
@@ -351,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
@@ -397,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;
     /**

package/dist/core/erase-id.d.ts

@@ -59,8 +59,13 @@
  * below the winner's pointer, where the winner's collection takes it, or above it: the case where this call took
  * its number after the winner's object was already in the bucket. Up there nothing collects it, and it was derived
  * from a generation the winner has replaced, so when the winner was another erasure it still holds the id that
- * erasure has just reported gone. That object is deleted before this call returns, once its footer proves it the
- * rewrite's own, under the version that read reported — see `discardRefused`.
+ * erasure has just reported gone. That object is deleted before this call returns, once its footer matches the
+ * rewrite's and a renewal of the row has refused every publish fenced on a row read before it, under the version the
+ * footer read reported, unless {@link DISCARD_ATTEMPTS} renewals lose to other writes (a load, a rollback, a
+ * retention write): then it is kept, and can hold the winner's id, until a later call takes it: any erasure that
+ * rewrites the segment (this one's re-run among them, while its id is still in the current generation) numbers above it
+ * and its `keep: 0` collection takes it, an erasure of the winner's id deletes it as a holder, and once loads number
+ * past it their collection takes it as it takes any orphan — see `discardRefused`.
  *
  * Without that fence the failure was silent and severe, and both halves were reproduced: `nextGeneration` picks a
  * number above everything in the bucket, so a forward-only publish here always won — discarding a concurrent
@@ -74,7 +79,14 @@
  * A load already in flight writes its object above the pointer before it publishes, or, as a first load onto a row with
  * no pointer, before there is a pointer at all. An erasure that finds the id in that object renews the row's `pointerId`
  * before deleting it, so the load's publish, fenced on the row it read, is refused (`published: false`) and the pointer
- * never names a missing object (see `fenceInFlight`). An erasure that finds no holder writes nothing.
+ * never names a missing object (see `fence`). An erasure that finds no holder writes nothing.
+ *
+ * Before it deletes anything, a call that found a holder takes every generation it will delete out of the row's ledger
+ * of known generations, in one write made after its search (the same write as the renewal where there is one). A
+ * generation the ledger names is one a collection by a count spares, so the delete comes after the name goes: a
+ * rollback that raced the write loses its swap, and a collection that reads the row before a delete spares what the row
+ * names. That write is made only when the ledger names something to delete, and it is the
+ * one case in which an erasure of an id held only by an older generation writes the row.
  *
  * An object sealed under a key its row does not hold cannot be searched, and no read of the segment can open it: a
  * first load's on a row with no pointer, whose key that load has not published; on a segment with a key, a first
@@ -94,6 +106,20 @@ import type { Rng } from './determinism.js';
 import type { IKeystore } from './crypto.js';
 import type { IStorageDriver, IRegistryDriver, SegmentRef } from './ports.js';
 import { type ReadRetry } from './retry.js';
+/**
+ * Renewals a refused rewrite's discard makes before it keeps its object: the first, and one more each time a write that
+ * is neither a write of leases alone nor another erasure's renewal of the row lands between its read of the row and its
+ * renewal. Those two are waited out, up to the limit on lease waits (`LEASE_ONLY_RETRIES`), and cost none, so the
+ * losers of one race of erasures all delete their rewrites; a write that gets no answer is sent again within the same
+ * renewal.
+ */
+export declare const DISCARD_ATTEMPTS = 8;
+/**
+ * Writes a call's fence makes before it gives up on a row that keeps changing under it: each one lost to another writer
+ * (a load, a rollback, another erasure) that is not a write of the row's leases alone costs one. The call then reports
+ * `'superseded'` with nothing deleted.
+ */
+export declare const FENCE_ATTEMPTS = 5;
 /** What {@link eraseIdFromSegment} needs: the objects, the pointer, the codec, and the key material if encrypted. */
 export interface EraseIdDeps {
     readonly storage: IStorageDriver;
@@ -176,7 +202,7 @@ export interface EraseIdResult {
     /**
      * The generation written without the id (present whenever one was written, even if `superseded`). A refused
      * rewrite whose object sits above the winner's pointer deletes that object again before it returns, when its footer
-     * proves it the rewrite's own.
+     * matches the rewrite's and a renewal of the row refuses every publish fenced on a row read before it.
      */
     readonly generation?: number;
     /**
@@ -202,8 +228,16 @@ export interface EraseIdResult {
      * and nothing was published at all; and a generation still holding the id when the bucket is listed at the end
      * — one an operator rolled the pointer onto while a rewrite was collecting, say, or, on a row with no pointer, the
      * object of a first load that read the row before this call renewed it and wrote it after this call listed the
-     * bucket. The row write an erasure makes before deleting a holder a load may still publish, when it gets no answer
-     * that reading the row can settle, throws the registry's `TransientError`, and that holder is not deleted.
+     * bucket. The row write an erasure makes before deleting a holder a load may still publish, or before a refused
+     * rewrite discards its own object, when it gets no answer that reading the row can settle, throws the registry's
+     * `TransientError`, and that object is not deleted.
+     *
+     * A rollback that lands between the call's read of the row and one of its deletes, onto the generation being deleted,
+     * leaves the pointer on an object that is gone. The call finds it at its next read of the row, or by reading the row
+     * once more after its last delete, and **throws `NotFoundError`** rather than report anything: every read of the
+     * segment fails until a rollback moves the pointer to a generation still in the bucket, and nothing restores the
+     * deleted object. When nothing left in the bucket holds the id, the call has emitted its `segment.collect` event
+     * first, so the deletion is on the record. Re-run it after that rollback.
      *
      * **Re-run it**, and read what the re-run says rather than assuming it finished the job. The re-run looks for
      * the id in every generation in the bucket, not only the current one, and there are three outcomes:
@@ -227,7 +261,8 @@ export interface EraseIdResult {
  * Emits one `segment.rewrite` audit event at the publish (before the superseded generation is collected), so the
  * compliance record exists the moment the generation without the id is authoritative. An erasure that rewrites nothing,
  * because only other generations held the id, emits one `segment.collect` once no generation holds it, and so does one
- * that deleted only objects no read of the segment can open, which names no generation the id was found in.
+ * that deleted only objects no read of the segment can open, which names no generation the id was found in. Either
+ * event comes before the `NotFoundError` of a rollback that moved the pointer onto a generation the call deleted.
  */
 export declare function eraseIdFromSegment(ref: SegmentRef, id: number, deps: EraseIdDeps, options?: {
     audit?: IAuditSink;

package/dist/core/erasure.d.ts

@@ -13,7 +13,7 @@
  * operation — `eraseIdFromSegment` rewrites the generation without it.
  */
 import { type IAuditSink } from './audit.js';
-import { type ChurnDeps } from './leases.js';
+import type { ChurnDeps } from './leases.js';
 import type { IStorageDriver, IRegistryDriver, RegistryRecord, SegmentRef } from './ports.js';
 export interface EraseDeps extends ChurnDeps {
     readonly registry: IRegistryDriver;
@@ -60,7 +60,7 @@ export declare function destroySegment(ref: SegmentRef, deps: EraseDeps, options
  * listing is capped at `maxScanSegments` (default {@link DEFAULT_MAX_SCAN_SEGMENTS}, 250,000), the ceiling every
  * other fleet scan keeps. A namespace over it throws `BudgetExceededError` **before any segment is destroyed**,
  * never part-way through; raise `maxScanSegments` when the namespace really is that large and the memory is there.
- * A `maxScanSegments` that is not a finite number >= 1 throws `ValidationError`, again before anything is destroyed.
+ * A `maxScanSegments` that is not a safe whole number of at least 1 throws `ValidationError`, again before anything is destroyed.
  */
 export declare function eraseNamespace(namespace: string, deps: EraseDeps, options: {
     confirmNamespace: string;
@@ -195,7 +195,7 @@ export declare function dropSegment(ref: SegmentRef, deps: DropDeps, options: {
  * in the shred's own write, so only a tombstone a sweep wrote ever carries a sweep's mark, which is what lets a later
  * sweep purge it and never a crypto-shred's.
  */
-export interface SweepDrop {
+interface SweepDrop {
     readonly wanted: (row: RegistryRecord) => boolean;
     readonly stamp: (retention: RegistryRecord['retention']) => RegistryRecord['retention'];
 }
@@ -208,3 +208,4 @@ export declare function dropSegmentFor(ref: SegmentRef, deps: DropDeps, options:
     dryRun?: boolean;
     audit?: IAuditSink;
 }, sweep: SweepDrop | undefined): Promise<DropResult | null>;
+export {};

package/dist/core/errors.d.ts

@@ -26,7 +26,11 @@ export declare class CloudRoaringError extends Error {
     readonly [ERROR_BRAND]: true;
     constructor(message: string);
 }
-/** Invalid caller input (bad id, segment name, options). Raised before any storage call. */
+/**
+ * Invalid input, which the same call fails on again. Most is refused before any storage call (a bad id, segment name
+ * or option); some is found by the call itself: a read past the end of an object, or a bucket or container a cloud
+ * driver finds does not exist.
+ */
 export declare class ValidationError extends CloudRoaringError {
 }
 /** An OCC conditional write/delete lost the race — the row changed since it was read. */
@@ -148,7 +152,9 @@ export declare function isLeaseLimitError(err: unknown): err is LeaseLimitError;
 export declare function isNotFoundError(err: unknown): err is NotFoundError;
 /** Corrupt/oversized/failed-checksum bytes from a tier. */
 export declare function isIntegrityError(err: unknown): err is IntegrityError;
-/** Invalid caller input. */
+/**
+ * Invalid caller input; also the error a cloud driver raises for a bucket or container it finds does not exist.
+ */
 export declare function isValidationError(err: unknown): err is ValidationError;
 /** This build or this store's wiring cannot do what was asked, though nothing is malformed. */
 export declare function isUnsupportedError(err: unknown): err is UnsupportedError;