@cloudbitmaps/core 0.10.0 → 0.11.1

package/dist/core/crbm-storage-source.d.ts

@@ -1,12 +1,3 @@
-/**
- * Bridges the `.crbm` archive format to the engine's Storage seam.
- *
- * `CrbmStorageChunkSource` implements the {@link StorageChunkSource} the engine reads through, over an
- * {@link IStorageDriver}: it resolves a segment's current generation, opens its {@link CrbmReader} once, and serves
- * per-chunk payloads. `writeCrbmGeneration` / `writeCrbmGenerationStream` are the write primitives (a generation
- * built from bitmaps, in memory or streamed), `bulkLoadCrbmGeneration` is the load path over them, and
- * `publishGeneration` is the forward-only pointer advance every write ends with.
- */
 import { type IAuditSink } from './audit.js';
 import type { Yielder } from './cooperative.js';
 import type { Clock } from './determinism.js';
@@ -22,7 +13,7 @@ export interface CrbmStorageChunkSourceOptions extends CrbmReaderOptions {
      * retirement of that scan. When absent, the source falls back to the `list`-scan (so the
      * in-memory / simple setups keep working with no registry). The resolved generation is cached and
      * **re-resolved on a short TTL** ({@link currentGenTtlMs}, needs a {@link clock}) so a long-lived source
-     * observes a load's new generation within the TTL instead of pinning one generation forever.
+     * observes another process's load within the TTL, not only when something else happens to re-resolve it.
      */
     readonly registry?: IRegistryDriver;
     /**
@@ -40,16 +31,19 @@ export interface CrbmStorageChunkSourceOptions extends CrbmReaderOptions {
     readonly requireEncryption?: boolean;
     /**
      * Time source for the current-generation TTL refresh — the determinism seam; `core/` never reads
-     * ambient time. Refresh needs **both** a clock and a `registry`; without either the source **pins** the
-     * first-resolved generation for its lifetime (the behaviour before the registry was wired in). The `CloudRoaring` facade passes its
-     * clock automatically, so wiring a `registry` is enough to get live cross-generation invalidation.
+     * ambient time. Refresh needs **both** a clock and a `registry`. Without either there is no timed refresh, and
+     * that is the only difference: a segment is still re-resolved when its reader is evicted, when a fetch finds its
+     * generation swept, and on {@link CrbmStorageChunkSource.invalidate}. What goes is the bound on how long another
+     * process's publish takes to arrive. The `CloudRoaring` facade passes its clock automatically, so wiring a
+     * `registry` is enough to get the bounded refresh.
      */
     readonly clock?: Pick<Clock, 'now'>;
     /**
      * How long (ms) a resolved `currentGen` is trusted before the next read re-resolves it (default 2000) — the
      * bound on read staleness after a load publishes: a reader may serve the prior generation for up to this long,
      * then converges. Lazy (checked on read — no timer); ≤ one cheap registry read per segment per window, and a
-     * new {@link CrbmReader} is opened only when the generation actually changed. `0` (or no clock) ⇒ pin forever.
+     * new {@link CrbmReader} is opened only when the generation actually changed. `0` turns the refresh off, as a
+     * missing clock or registry does: {@link clock} says what that changes, and what it does not.
      */
     readonly currentGenTtlMs?: number;
     /**
@@ -70,21 +64,52 @@ export interface CrbmStorageChunkSourceOptions extends CrbmReaderOptions {
      */
     readonly maxOpenIndexBytes?: number;
 }
+/**
+ * What a pin holds of the object it pinned: the version its cache entries are keyed by, and the object's
+ * fingerprint, which a pinned read checks each time it opens the generation. `pinGeneration` always records one.
+ * A pin built by hand without one is not checked: it reads whatever object is under its generation's key.
+ */
+export interface PinnedObject {
+    readonly version: string;
+    readonly fingerprint?: string;
+}
 export declare class CrbmStorageChunkSource implements StorageChunkSource {
     private readonly driver;
     /**
      * One resolved reader per segment, re-resolved on a short TTL ({@link CrbmStorageChunkSourceOptions.currentGenTtlMs},
      * needs a clock). Within the TTL a segment's Storage bytes are treated as an immutable snapshot; when the TTL
      * elapses the next read cheaply re-resolves `currentGen` and, only if it advanced (a load published),
-     * opens the new generation — so a long-lived source observes new generations within the TTL rather than
-     * pinning one forever. The engine pairs this with a **generation-keyed** cache so a bump never
-     * serves a stale decoded chunk. Without a clock or a registry the source pins the first generation for its
-     * lifetime (the behaviour before the registry was wired in). A segment with no generation yet is not memoized, so it's re-checked until
-     * one exists. **Bounded** by a {@link BoundedLru} ({@link CrbmStorageChunkSourceOptions.maxOpenSegments}, default
+     * opens the new generation — so a long-lived source observes new generations within the TTL. The engine pairs
+     * this with a **generation-keyed** cache so a bump never serves a stale decoded chunk. Without a clock or a
+     * registry there is no timed refresh, and a segment's reader is replaced only when it is evicted, when a read
+     * has to fetch from a generation a sweep deleted, or when {@link invalidate} drops it. A segment with no generation yet is not memoized, so
+     * it's re-checked until one exists. **Bounded** by a {@link BoundedLru} ({@link CrbmStorageChunkSourceOptions.maxOpenSegments}, default
      * 1024): past the ceiling the least-recently-used segment's reader (and its parsed index) is evicted — the
      * steady-state memory bound; re-opening an evicted segment is one cheap tail GET.
      */
     private readonly snapshots;
+    /**
+     * Pins ({@link heldKey}) whose object has been found replaced: another object is under its generation's key. Kept,
+     * and bounded as the readers are, so that a pin's later chunk reads and any reopen fail at once rather than pay for
+     * the check again. A replacement can be undone, by a restore that puts the pinned object back, so
+     * {@link invalidate} forgets the segment's, and a pin of the same version that opens the object forgets the one
+     * against it. An object found gone is not kept: that is the open's own `NotFoundError`, and a 404 can pass. A
+     * reader still memoised keeps answering from the index it holds, so the pin's `count()` does, until a later pin of
+     * that version opens the object now under the key, which takes its place.
+     */
+    private readonly replacedPins;
+    /**
+     * A check of a pinned object still under way, by {@link heldKey}, so the reads that ask at once share one footer
+     * read. One forgotten before it ends, by {@link invalidate} or a pin, keeps nothing it finds.
+     */
+    private readonly checking;
+    /**
+     * How many times {@link invalidate} has run, so a read that waited can tell whether the store was told something
+     * meanwhile. An eviction from the reader cache is not an invalidation, and what a read found stands through one. It
+     * counts every segment's invalidations: a read that waited through another segment's only costs a later read the
+     * check again.
+     */
+    private invalidations;
     private readonly registry;
     private readonly keystore;
     private readonly requireEncryption;
@@ -94,6 +119,12 @@ export declare class CrbmStorageChunkSource implements StorageChunkSource {
     constructor(driver: IStorageDriver, options?: CrbmStorageChunkSourceOptions);
     /** The current resolved reader for a segment, refreshing on the TTL. Cheap within the TTL window. */
     private resolvedReader;
+    /**
+     * A refresh failed transiently and the prior reader keeps serving: make this snapshot lapse after
+     * {@link REFRESH_RETRY_MS} (never longer than the TTL) rather than after a whole TTL, so the next read after
+     * that asks the registry again. It costs no read of its own; it only changes when the next refresh happens.
+     */
+    private retrySoon;
     /** TTL elapsed: cheaply re-resolve `currentGen`; reopen only if it actually changed, else reuse the prior reader. */
     private computeRefreshedReader;
     /**
@@ -103,85 +134,143 @@ export declare class CrbmStorageChunkSource implements StorageChunkSource {
      */
     private install;
     private now;
+    /**
+     * How often this source re-reads a segment's pointer while the segment is being read, in ms: its TTL, or 0 when
+     * it has no timed refresh (no clock, no registry, or a TTL of 0). The grounded cost report prices the refresh at
+     * this.
+     */
+    get pointerRefreshMs(): number;
     private expired;
     /**
      * The segment's current generation number — the engine keys its chunk cache by this so a generation bump
      * is observed instead of serving a stale decoded chunk. Served from the (TTL-refreshed)
      * snapshot, so no extra backend read within the TTL window. `null` if the segment has no committed generation.
      *
-     * Heals a swept generation exactly like {@link withFreshSnapshot} — the engine calls this **once per op**,
-     * before any chunk fetch, so an unhealed miss here fails the whole operation rather than one chunk. It is
-     * spelled out rather than delegated because this is the hottest call in the library: once per operand of
-     * every `has`/`count`/`iterate`/`intersect`, and almost always served from the cached snapshot with no
-     * backend call at all. Routing it through the generic helper cost ~115 ns/op on that path (a second async
+     * Heals a swept generation exactly like {@link withFreshSnapshot}: a caller that resolves the generation once
+     * per op, before any chunk fetch, would otherwise fail the whole operation rather than one chunk. The engine
+     * keys by {@link currentVersion} instead, which heals the same way, and falls back to this for a source that
+     * cannot report a version. It is spelled out rather than delegated because a lookup like this runs once per
+     * operand of every `has`/`count`/`iterate`/`intersect`, almost always served from the cached snapshot with
+     * no backend call at all. Routing it through the generic helper cost ~115 ns/op on that path (a second async
      * frame, a per-call closure, and an `await` on a plain number) for a race that fires only during a
      * concurrent sweep. One retry, then propagate — same contract, same eviction rule.
      */
     currentGeneration(ref: SegmentRef): Promise<number | null>;
     /**
      * Forget everything derived from `ref`: the resolved snapshot and the open reader behind it (and with the
-     * reader, the DEK it unwrapped at open time). The next read resolves `currentGen` from the registry again.
+     * reader, the DEK it unwrapped at open time), and what its pins' objects were found to be. The next read
+     * resolves the segment again.
      *
      * Needed because the TTL refresh only ever answers "has the pointer moved?", and every *destructive* verb —
      * an erasure that deletes the generation holding the bit, a `dropSegment`, a crypto-shred, a retirement —
      * leaves the pointer's answer unchanged from this source's point of view while making the snapshot wrong.
      * Until this is called the source keeps serving that snapshot with no backend read at all, so nothing on the
-     * storage side can close the window; with `cache.genTtlMs: 0` or no clock it never closes.
+     * storage side can close the window; with no registry, no clock or `cache.genTtlMs: 0`, nothing bounds it at all.
      */
     invalidate(ref: SegmentRef): void;
     /**
-     * Whether the segment is a registered name at all. With a registry that is exactly "a row exists" — including
-     * a row with no generation yet (minted by `setRetention` before the first load) and a `destroyed` tombstone,
-     * both of which are names somebody deliberately created. Without a registry there is no registration to
-     * consult, so the honest answer is whether the bucket holds any generation of it.
+     * `<generation>` for a registry-less source, or `<generation>:<row token>` with one. The token moves on every row
+     * write, so an unrelated write (a `setRetention`) costs the segment's decoded chunks once — bounded, and on an
+     * admin path. Exactness in the direction that matters: with a registry, two incarnations can never share a version
+     * string. Without one they can: a name purged and loaded again out of band restarts at the same bare number, and
+     * a live read that reopens it after an eviction reads the new object's chunks beside the old one's cached ones. A
+     * store with no registry cannot write, so that takes a change made from outside it; a pin is kept apart from it by
+     * the fingerprint it records.
      *
-     * Deliberately NOT served from the snapshot memo: the memo resolves to `null` for both states this exists to
-     * tell apart.
-     */
-    /**
-     * `<generation>` for a registry-less source (no row, so no incarnation to confuse), or
-     * `<generation>:<row token>` with one. The token moves on every row write, so an unrelated write (a
-     * `setRetention`) costs the segment's decoded chunks once — bounded, and on an admin path. Exactness in the
-     * direction that matters: two incarnations can never share a version string.
+     * This is the call the engine makes **once per operand of every read**, before any chunk fetch, to key its
+     * chunk cache, so it heals a swept generation exactly as {@link currentGeneration} does: unhealed, a cold read
+     * racing a publish and a `keep: 0` sweep failed the whole operation with `NotFoundError`, where the same race
+     * on a chunk fetch heals. Spelled out rather than delegated for the reason `currentGeneration` gives: it is
+     * almost always served from the cached snapshot with no backend call at all. One retry, then propagate.
      */
     currentVersion(ref: SegmentRef): Promise<string | null>;
     /**
      * Resolve the segment **once** and report what a pin should hold: the generation, and the version that
      * identifies those exact bytes. `null` when the segment resolves to no generation — there is nothing to pin,
      * and a caller must treat that as "this handle reads empty", not "pinning is unsupported here".
+     *
+     * Heals a generation swept between the registry read and the open, as {@link currentVersion} does: a publish
+     * and a `keep: 0` sweep can land in that gap, and nothing has been handed out yet, so the generation current
+     * once the swept one is gone is exactly what a pin taken now should hold. One retry, then propagate.
      */
-    pinGeneration(ref: SegmentRef): Promise<{
+    pinGeneration(ref: SegmentRef): Promise<({
         generation: number;
-        version: string;
-    } | null>;
+    } & Required<PinnedObject>) | null>;
+    private pinOnce;
+    /**
+     * Where a pinned reader of one object is memoised. With a registry that is its version, which names the object:
+     * a name purged and loaded again gets a new row, and with it a new token. Without one the version is the bare
+     * generation number, which two incarnations share, so the object's fingerprint is added to tell them apart.
+     */
+    private pinnedKey;
+    /**
+     * One pin's hold on one segment: its version, and the fingerprint of the object it pinned. A check of that object
+     * is shared under it, and what the check finds is kept under it, with a registry or without one: pins of one
+     * version can hold different objects, since a pin built by hand can name any, and an object replaced from outside
+     * the store leaves the row, and so the version, as it was.
+     */
+    private heldKey;
     /**
      * A reader for one **specific** generation, memoized in the same bounded LRU as the live snapshots under a
      * generation-qualified key.
      *
      * Sharing the LRU is the point, not an implementation detail. A pinned reader held in a private field is
      * outside the memory ceiling the library advertises — measured at 10.34 MiB per live pin, 32 pins holding
-     * 111.7 MiB against an 8 MiB configured bound. A pinned *generation number* has no such problem: the
-     * generation is immutable, so eviction is harmless and re-opening at the same number reproduces the same
-     * bytes. It also removes a memoized-rejection bug by construction — `install` forgets a promise that rejects,
+     * 111.7 MiB against an 8 MiB configured bound. A pinned *generation number* has no such problem: an object is
+     * immutable, so eviction is harmless, and re-opening at the same number reopens the same bytes unless the name
+     * was purged and loaded again, which the pin's fingerprint then says. It also removes a memoized-rejection bug by
+     * construction — `install` forgets a promise that rejects,
      * where a hand-rolled `this.reader ??= open()` cached the rejection for the life of the handle and made a pin
      * the one read path with no resilience.
      *
      * **`status` is re-checked here**, on every open rather than once at pin time. A pin taken before a
      * crypto-shred must not keep unwrapping a DEK the shred destroyed; a destroyed segment resolves no generation
-     * for anyone, pinned or not.
+     * for anyone, and a pin's read of one fails. That holds from the pin's next open: a reader already open keeps
+     * the key it unwrapped until it is evicted or invalidated.
+     *
+     * **And the object is checked**, when the caller says which one it pinned. A generation number is not an
+     * identity (invariant 1): once a name is purged and loaded again, its new segment starts again at generation 0,
+     * so a pin of the old one would open the new one's object as its own, and read it beside the chunks it had
+     * already cached from the old one. The row's token cannot tell them apart, since it moves on every write, a
+     * publish included; the object's fingerprint can, and a pin whose object has been replaced fails, as one whose
+     * generation has been swept does. The memo is keyed so that two pins of one generation number in two
+     * incarnations never share a reader, with a registry or without one ({@link pinnedKey}).
      */
     private readerAt;
     private openAt;
-    /** The row's current key wrappings, for opening a pinned generation. */
-    private deksFor;
-    /** Read one chunk of a specific generation — the pinned read path. */
-    getChunkAt(ref: ChunkRef, generation: number): Promise<Uint8Array | null>;
-    /** Chunk keys of a specific generation — the pinned shape read. */
-    listChunkKeysAt(ref: SegmentRef, generation: number): Promise<number[]>;
-    /** Per-chunk cardinalities of a specific generation — powers a pinned `count()` with no payload reads. */
-    cardinalitiesAt(ref: SegmentRef, generation: number): Promise<ReadonlyMap<number, number> | null>;
-    /** Grounded size of a specific generation. */
-    sizeOfAt(ref: SegmentRef, generation: number): Promise<SegmentSize | null>;
+    /**
+     * Read one chunk of a specific generation — the pinned read path. `held`, when given, is what a pin holds of the
+     * object, and the read fails if the generation is now another object.
+     */
+    getChunkAt(ref: ChunkRef, generation: number, held?: PinnedObject): Promise<Uint8Array | null>;
+    /**
+     * Throws the pin's NotFoundError if the object under `generation`'s key is no longer the one the pin holds. Its
+     * footer says, read with no key and no row ({@link CrbmReader.sameObject}), so an object written under a key this
+     * store lacks answers the same way, and so does one gone from its key. A replacement is kept
+     * ({@link replacedPins}), and a check under way is shared by the reads that ask at once; neither "gone" nor "the
+     * same" is kept, since either can change. A transient fault is rethrown, for the store's retries to see for what it
+     * is. A footer that cannot be read otherwise says nothing about which object is there, so this returns, and the
+     * caller's own error stands.
+     */
+    private throwIfReplaced;
+    /** Chunk keys of a specific generation — the pinned shape read. `held` as for {@link getChunkAt}. */
+    listChunkKeysAt(ref: SegmentRef, generation: number, held?: PinnedObject): Promise<number[]>;
+    /**
+     * Per-chunk cardinalities of a specific generation — powers a pinned `count()` with no payload reads. `held` as
+     * for {@link getChunkAt}.
+     */
+    cardinalitiesAt(ref: SegmentRef, generation: number, held?: PinnedObject): Promise<ReadonlyMap<number, number> | null>;
+    /** Grounded size of a specific generation. `held` as for {@link getChunkAt}. */
+    sizeOfAt(ref: SegmentRef, generation: number, held?: PinnedObject): Promise<SegmentSize | null>;
+    /**
+     * Whether the segment is a registered name at all. With a registry that is exactly "a row exists" — including
+     * a row with no generation yet (minted by `setRetention` before the first load) and a `destroyed` tombstone,
+     * both of which are names somebody deliberately created. Without a registry there is no registration to
+     * consult, so the honest answer is whether the bucket holds any generation of it.
+     *
+     * Deliberately NOT served from the snapshot memo: the memo resolves to `null` for both states this exists to
+     * tell apart.
+     */
     exists(ref: SegmentRef): Promise<boolean>;
     /**
      * Evict a snapshot we just failed to read from — matched by its reader *promise*, so a concurrent call's
@@ -233,7 +322,7 @@ export declare class CrbmStorageChunkSource implements StorageChunkSource {
     private withFreshSnapshot;
 }
 /**
- * Write one immutable generation from in-memory bitmaps (the seed / bulk-load primitive). Chunks are
+ * 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)`).
@@ -356,9 +445,9 @@ export interface BulkLoadResult {
      * `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 used to report the generation it wrote as "the destination's
-     * new current generation" on exactly this path, which is a plain untruth — so the flag is on the result and the
-     * verbs that promise a published generation check it.
+     * 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;
 }
@@ -409,7 +498,8 @@ export declare function bulkLoadCrbmGeneration(driver: IStorageDriver, key: GenK
      * 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 else will ever reclaim it.
+     * generation collection deliberately never looks, so nothing reclaims it until a later generation above it is
+     * current.
      */
     publish?: boolean;
 }): Promise<BulkLoadResult>;

package/dist/core/determinism.d.ts

@@ -27,7 +27,7 @@ export interface Clock {
      * yields to nothing at all, and a co-resident server stays blocked for the loop's full duration. A real yield
      * needs a macrotask. `sleep(1)` is one, but it buys the relief at ~1 ms of dead wall-clock per yield.
      *
-     * **Optional**, so every `Clock` written before this member still satisfies the interface. Callers must
+     * **Optional**, so a minimal `Clock` — `now` and `sleep` alone — still satisfies the interface. Callers must
      * therefore degrade rather than assume: `clock.yieldNow?.() ?? clock.sleep(1)` — correct on any clock, cheap
      * on one that implements this. `core/` cannot supply it itself (it is timer-free, lint-enforced); production
      * wiring backs it with `setImmediate`, and a test can make it a no-op so virtual time is not perturbed

package/dist/core/discover.d.ts

@@ -57,11 +57,13 @@ export declare function segmentExists(ref: SegmentRef, registry: IRegistryDriver
  * **Scoping to a namespace narrows the LIST prefix**, so it really is the difference between reading one
  * tenant and reading all of them.
  *
- * Streams, so a large fleet need not be held at once, and stopping the iteration stops the scan — **with one
- * exception that matters**: a driver that buffers its enumeration defeats both properties, and
- * `RetryingRegistryDriver` does exactly that (it must, to retry a `list` as a unit). Wrapped in it, the whole
- * scan is paid for and resident before the first row reaches you. On the four native drivers the guarantee
- * holds; on S3 the granularity is a page, so one LIST page and its in-flight row reads complete regardless.
+ * Streams, so a large fleet need not be held at once, and stopping the iteration stops the scan — as long as the
+ * registry driver's own `list` streams. One that collects its whole enumeration before yielding defeats both
+ * properties, since the scan is then paid for and resident before the first row reaches you, so a custom driver's
+ * `list` should yield each row as it reads it. The registry drivers this library ships all stream; on S3, GCS and
+ * Azure Blob the granularity is a page, so one LIST page and its in-flight row reads complete regardless. Nothing
+ * here retries the scan: a transient fault part-way through ends the iteration with that error, and calling
+ * `listSegments` again scans from the start, since the iterable one call returns is used up.
  *
  * Yields `destroyed` tombstones, and rows whose `currentGen` is `null`, because hiding either would make this
  * disagree with the registry it reports on — a filtered enumeration that looks complete is how a retention

package/dist/core/due-index.d.ts

@@ -1,7 +1,5 @@
 import { MAX_NAME_LENGTH } from './validate.js';
 import type { RegistryRecord, SegmentRef } from './ports.js';
-/** Namespace prefix for due-index rows. */
-export declare const DUE_NAMESPACE_PREFIX = "cbm.due.";
 /** Bucket width. One day: small enough that a cycle reads little, coarse enough that the index stays tiny. */
 export declare const DUE_BUCKET_MS = 86400000;
 /**
@@ -24,13 +22,13 @@ export declare function isDueIndexRow(record: Pick<RegistryRecord, 'namespace'>)
  * Encode a ref into one index-row name, unambiguously.
  *
  * `${namespaceLength}.${namespace}${segment}` — a decimal length, a dot, then the two parts concatenated. The
- * length prefix is what makes it reversible: every character the grammar allows (`.`, `-`, `_`, `:`, alphanumerics)
- * is legal *inside* a name, so no separator character could ever be unambiguous on its own. Reading the digits
+ * length prefix is what makes it reversible: a name may contain any character, the dot included, so no
+ * separator character could ever be unambiguous on its own. Reading the digits
  * up to the first dot tells the parser exactly where the namespace ends.
  */
 export declare function encodeDueName(ref: SegmentRef): string;
 /**
- * Can this ref be indexed at all? False when the encoded name would exceed the grammar's 256-character cap —
+ * Can this ref be indexed at all? False when the encoded name would exceed the 256-character name cap —
  * possible only for a ref whose namespace and segment are together near the limit.
  *
  * **Not indexable is not "not retired".** The repair scan still sees the segment's own row, so the consequence

package/dist/core/engine.d.ts

@@ -12,7 +12,7 @@ export interface EngineDeps {
     /**
      * The bitmap codec — **required**. `core/` is codec-agnostic: it can have no default, because the concrete codec
      * lives in a *flavor* package that depends on core (a default here would invert that arrow). A flavor's facade
-     * injects it — `@cloudbitmaps/roaring` passes `roaringCodec` — so applications never see this.
+     * injects it — `@cloudbitmaps/roaring` passes the roaring codec — so applications never see this.
      */
     readonly codec: CodecInterface;
     /** Time source for the `storage.get` latency metric only; defaults to a clock that reads 0. */
@@ -26,8 +26,27 @@ export interface EngineDeps {
      */
     readonly budget?: Budget | null;
 }
+/**
+ * A range of ids for a read to yield: those greater than `after` and no greater than `through`, `(after, through]`.
+ *
+ * Built for keyset paging: `after` is the last id the caller already has, `through` the end of its window. Each is
+ * optional: left out, the read starts at the first id or runs to the last. Each is an integer in `0..4294967295`, or
+ * the read throws {@link ValidationError} when it is first read. `after >= through` is an empty range, not an error,
+ * because a cursor that has reached the end of its window is normal; an empty range reads nothing, not even whether
+ * 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.
+ */
+export interface IdRange {
+    /** Exclusive lower bound: the read yields only ids greater than this. */
+    readonly after?: number | undefined;
+    /** Inclusive upper bound: the read yields only ids up to and including this. */
+    readonly through?: number | undefined;
+}
 /** Options common to the chunk-aligned combines. */
-export interface CombineOptions {
+export interface CombineOptions extends IdRange {
     /** Max chunk keys resolved concurrently — bounds the Storage footprint. A positive integer. */
     readonly concurrency?: number;
     /** Override the store's per-op budget for this call (`false` lifts it). */
@@ -58,14 +77,29 @@ export declare class SegmentEngine {
      * Cardinality. When the Storage source can serve per-chunk cardinality from its `.crbm` index (the `.crbm`
      * source can), the count is summed from the index with **zero payload reads**. A source without that
      * capability (the in-memory source) falls back to fetching every chunk.
+     *
+     * The index sum is trusted, not confirmed: the reader checked the index for internal consistency when it opened
+     * the object, and a corrupt index that is still internally consistent yields a wrong count. `iterate()` and the
+     * combines decode the payloads.
      */
     count(seg: SegmentRef): Promise<number>;
     /** 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>;
-    /** Every id, ascending, one chunk at a time. */
-    iterate(seg: SegmentRef): AsyncGenerator<number>;
+    /**
+     * Every id, ascending, one chunk at a time; with `range`, only the ids in `(after, through]`, fetching only the
+     * chunks the range overlaps (see {@link IdRange}).
+     *
+     * 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.
+     */
+    iterate(seg: SegmentRef, range?: IdRange): AsyncGenerator<number>;
+    private iterateAll;
+    private iterateRange;
     /**
      * `segs[0] ∩ segs[1] ∩ …`, minus every id in `options.exclude` — streamed ascending.
      *
@@ -89,11 +123,13 @@ export declare class SegmentEngine {
      * Generation-consistent within the call (normal case): each operand's current generation is resolved **once**
      * up front (before the fan-out) and threaded into every chunk read, so a concurrent load can't corrupt or tear
      * the result — every chunk read is a whole, checksum-verified, immutable generation. The edge a *long* call can
-     * hit: if it straddles a mid-call `cache.genTtlMs` boundary and a load has published, an operand's not-yet-read
-     * 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. A shorter call is unaffected **unless the
-     * reader cache evicts an operand mid-call** (`maxOpenSegments`): the re-read re-resolves fresh (bypassing the
-     * TTL), which can hop generations even sub-TTL — still whole/immutable per read, never torn.
+     * hit is invariant 3's: if it straddles a mid-call `cache.genTtlMs` boundary and a load has published, an
+     * operand's not-yet-read 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.
      */
     intersect(segs: readonly SegmentRef[], options?: CombineOptions): AsyncGenerator<number>;
     /**
@@ -142,6 +178,11 @@ export declare class SegmentEngine {
      *
      * Costs one `maximum()` per chunk, not per id — `maximum` is optional on the codec seam precisely so a codec
      * that cannot answer in O(1) opts out instead of making the read path walk every value.
+     *
+     * One value stands for all of them only because the decode is structurally checked. Roaring answers `maximum()`
+     * from its last container, so a payload listing its containers out of order would report the wrong one's
+     * largest value and pass here while holding values above 65,535. The codec's `safeDeserialize` refuses that
+     * payload, and every other shape that would make this answer wrong, before it reaches this check.
      */
     private assertChunkPayloadInRange;
     /**
@@ -161,7 +202,8 @@ export declare class SegmentEngine {
      * **Costs nothing on a normal combine.** `exists` is consulted only for an operand that resolved to zero
      * 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.
+     * `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.
      */
     private refuseAbsentOperands;
     /**
@@ -182,8 +224,8 @@ export declare class SegmentEngine {
      * The cache-key component identifying **which bytes** this op will read: the source's `currentVersion` when
      * it has one, else the generation alone.
      *
-     * The generation alone is not an identity. `nextGeneration` restarts at 0 once a row is purged and the
-     * bucket emptied, so a retired-and-re-created name serves different data at the same `currentGen` — and a
+     * The generation alone is not an identity. A load's generation number restarts at 0 once a row is purged
+     * and the bucket emptied, so a retired-and-re-created name serves different data at the same `currentGen` — and a
      * decoded chunk cached under `(segment, chunk, 0)` is handed straight back to the new incarnation. That is an
      * erased id reappearing with no read to intercept it, which is why this is keyed on the version rather than
      * the number.
@@ -195,7 +237,7 @@ export declare class SegmentEngine {
      * keyed by it, so a load that advances the generation misses the cache and re-reads the new bytes instead of
      * serving a stale decoded chunk (an erased id can't resurrect from a cached superseded chunk). `gen === null`
      * ⇒ the source reports no current generation ⇒ no storage bytes for any chunk, so skip the fetch entirely.
-     * `gen === undefined` ⇒ the source can't report a generation (pins one for its lifetime) ⇒ the key stays
+     * `gen === undefined` ⇒ the source can't report a generation (it only ever serves one) ⇒ the key stays
      * generation-free. Superseded-generation entries age out under the LRU ceiling — no active purge.
      *
      * The returned instance is **shared** (it may be the cached one): callers read it or clone it, never mutate it.