@cloudbitmaps/roaring 0.10.0 → 0.11.0

package/dist/index.d.ts

@@ -5,14 +5,16 @@
  * object store, behind one registry pointer per segment. You wire storage **once**, as a single config object:
  * pass a **backend** as `storage` — `S3Storage`, `GcsStorage`, `AzureBlobStorage`, `LocalFsStorage` or
  * `MemoryStorage` — and it carries both halves, the generations and the pointer, from one bucket and one
- * prefix. Add a `keystore` for encryption-at-rest / crypto-shred.
+ * prefix. Add `encryption: { keystore }` for encryption-at-rest / crypto-shred.
  *
  * Two narrower shapes are also accepted for `storage`: a bare {@link IStorageDriver}, which has no pointer and
  * so resolves generations by list-scanning storage (**cleartext and read-only**), and an already-built
  * {@link StorageChunkSource} for advanced reader options you configure yourself.
  *
- * **Data gets in by loading a generation**, never by mutating one: `bulkLoadCrbmGeneration` streams a set of ids
- * into one immutable object and publishes it forward-only. Every other write in the library is a load in
+ * **Data gets in by loading a generation**, never by mutating one: `store.load()` streams a set of ids into one
+ * immutable object and advances the segment's pointer to it. The pointer only moves forward, so a load out-raced by
+ * a newer generation reports `superseded` instead of landing, and so does one that read the row when the row has
+ * changed since. Every other write in the library is a load in
  * disguise — `intersectInto`/`unionInto`/`andNotInto` write a new generation of their destination, and
  * `eraseSubject` rewrites a generation without one id. Reads (`has`/`count`/`iterate`/`intersect`/`union`/`andNot`)
  * see whole, checksum-verified generations and nothing else.
@@ -21,8 +23,7 @@
  * `checkConsistency`, `exportSegments` — reuse the store's own drivers, so you never re-pass them (they need the
  * store built with a backend). See the README and the getting-started guide.
  */
-import { SegmentEngine } from '@cloudbitmaps/core';
-import type { BudgetOption, GenerationEntry, LoadGuard, LoadOptions, LoadRefusal, LoadResult, RollbackResult, Clock, StorageChunkSource, ConsistencyReport, CostReport, DropResult, EstimateInput, ExportManifest, ExportOptions, ExportSink, IAuditSink, IStorageDriver, IKeystore, IMetricsSink, StorageBackend, PricingProfile, RetentionPolicy, RetireExpiredOptions, RetireExpiredResult, RetryPolicy, Rng, SetRetentionResult, PinnedAt, SegmentRef, Workload } from '@cloudbitmaps/core';
+import type { BudgetOption, GenerationEntry, LoadGuard, LoadOptions, LoadRefusal, LoadResult, RollbackResult, Clock, StorageChunkSource, ConsistencyReport, CostReport, DropResult, EstimateInput, ExportManifest, ExportOptions, ExportSink, IAuditSink, IStorageDriver, IKeystore, IMetricsSink, StorageBackend, PricingProfile, RetentionPolicy, RetireExpiredOptions, RetireExpiredResult, RetryPolicy, Rng, SetRetentionResult, PinnedAt, IdRange, SegmentRef, Workload } from '@cloudbitmaps/core';
 import type { SegmentInfo } from '@cloudbitmaps/core';
 /**
  * Wiring for a {@link CloudRoaring} store. **Only `storage` is required** — the minimal call is
@@ -43,7 +44,7 @@ export interface CloudRoaringOptions {
      * **Pass the backend itself, not `backend.storage`.** They differ by one property access and the mistake is
      * silent: `storage: backend` is the store, while `storage: backend.storage` hands over the *driver half*
      * alone, which constructs without complaint and gives you a cleartext, read-only store that fails later on
-     * the first write or lifecycle call. The free functions take `backend.storage`; the store takes `backend`.
+     * the first write or lifecycle call. `destroySegment` and `eraseNamespace` take `backend.registry`; the store takes `backend`.
      *
      * Two lower-level shapes stay accepted for wiring the facade does not cover:
      *
@@ -64,11 +65,16 @@ export interface CloudRoaringOptions {
      */
     readonly encryption?: EncryptionOptions;
     /**
-     * Resilience: by default every storage read retries **transient** faults (throttling, 5xx, dropped
-     * connections) with bounded, jittered exponential backoff (see {@link DEFAULT_RETRY_POLICY}). Pass a partial
-     * policy to tune it — anything you leave out keeps its default — or `false` to disable the transient-retry
-     * wrapper entirely (e.g. if your injected client already retries). Deterministic errors
-     * (`ValidationError`/`IntegrityError`/`WriteConflictError`/…) are never retried by this layer.
+     * Resilience: by default every read that answers a query retries **transient** faults (throttling, 5xx, dropped
+     * connections) with bounded, jittered exponential backoff (see {@link DEFAULT_RETRY_POLICY}): `has`, `count`,
+     * `iterate` and the combines, the `*Into` verbs' reads of their operands included, a pinned handle's reads and
+     * `pin()` itself. Writes are not retried, and nor are an erasure's reads, a load's guard read, or the calls that
+     * read the registry or list the bucket directly (`exists`, `segments`, `generations`, `getRetention`, and the
+     * registry scan `subjectReport`, `exportSegments` and `checkConsistency` start from): they report a transient fault to their caller, because a conditional write that lands and then loses its response would, replayed,
+     * report its own write as a conflict. Pass a partial policy to tune it — anything you leave out keeps its
+     * default — or `false` to turn the read retry off (e.g. if your injected client already retries).
+     * Deterministic errors (`ValidationError`/`IntegrityError`/`WriteConflictError`/…) are never retried by this
+     * layer.
      */
     readonly retry?: RetryOptions | false;
     /**
@@ -80,7 +86,8 @@ export interface CloudRoaringOptions {
     /**
      * Per-op **denial-of-wallet** budget: the max backend requests a single
      * `count`/`iterate`/`intersect`/`union`/`andNot`/`subjectReport`/`eraseSubject` may fan out into before it's
-     * refused with {@link BudgetExceededError} — so one runaway op can't drive unbounded GET cost on a shared
+     * refused with {@link BudgetExceededError} (`eraseSubject` reports an over-budget segment in its ledger instead,
+     * see {@link CloudRoaring.eraseSubject}) — so one runaway op can't drive unbounded GET cost on a shared
      * backend. **On by default, generous** ({@link DEFAULT_BUDGET}: 1,000,000 requests — a normal op never hits it).
      * Tune with `{ maxRequests }`, override per op (on the combines / `subjectReport` / `eraseSubject`), or set
      * `false` to disable. The check is O(1) (before fan-out), so the hot path is untouched; per-request bytes are
@@ -102,10 +109,23 @@ export interface CacheOptions {
     /**
      * How long (ms) the store trusts a segment's resolved `currentGen` before re-resolving it on the next read
      * (default 2000) — the bound on read staleness after a load publishes a new generation. Applies when
-     * `storage` is a **backend**, whose registry supplies the cheap `currentGen` read the refresh needs. A store
-     * wired with a bare `IStorageDriver` has no registry at all and pins the generation for the source's
-     * lifetime. Lazy — no timer; ≤ one registry read per segment per window, opening a new reader only when the
-     * generation actually advanced.
+     * `storage` is a **backend**, whose registry supplies the cheap `currentGen` read the refresh needs. Lazy — no
+     * timer; ≤ one registry read per segment per window, opening a new reader only when the generation actually
+     * advanced.
+     *
+     * **While the registry cannot be read, the bound stretches.** A refresh that fails with a
+     * {@link TransientError} keeps serving the generation the reader holds, and the key it unwrapped, and is tried
+     * again 500 ms later (or after this TTL, if shorter), so the store converges within one retry of the registry
+     * answering. A refresh that fails with anything else, an access denial or a row that will not parse, is not
+     * ridden out: the read that meets it throws that error, and the reader is dropped.
+     *
+     * `0` turns this timed refresh off, and so does wiring a bare `IStorageDriver`, which has no registry. That is
+     * all it does. The store still moves a segment on to whatever generation is current when its reader cache
+     * evicts the segment, when a read has to fetch from a generation a sweep deleted, and when it is invalidated,
+     * as its own `load`, `rollback`, `eraseSubject` and `*Into` writes do and {@link CloudRoaring.invalidate} does.
+     * A read its caches can answer touches no storage, so a sweep alone moves nothing. What `0` gives up is the bound:
+     * the store notices another process's publish, erasure or drop only through one of those, whenever that happens. To read
+     * one generation for as long as you need it, take a {@link Segment.pin}.
      */
     readonly genTtlMs?: number;
     /**
@@ -149,11 +169,14 @@ export interface EncryptionOptions {
 /**
  * {@link CloudRoaringOptions.retry} — a partial {@link RetryPolicy} plus the retry callback.
  *
- * Partial on purpose: the flat form this replaces took a **whole** `RetryPolicy`, so tuning one field meant
- * restating all five. Anything omitted here keeps its {@link DEFAULT_RETRY_POLICY} value.
+ * Partial on purpose, so tuning one field does not mean restating all five. Anything omitted here keeps its
+ * {@link DEFAULT_RETRY_POLICY} value.
  */
 export interface RetryOptions extends Partial<RetryPolicy> {
-    /** Observability: called before each transient-retry backoff wait. */
+    /**
+     * Observability: called before each transient-retry backoff wait. Best-effort: an error it throws is
+     * swallowed, so it can neither stop the retry nor change the error a read fails with.
+     */
     readonly onRetry?: (info: {
         attempt: number;
         delayMs: number;
@@ -211,27 +234,36 @@ export interface SubjectErasureEntry {
     readonly segment: string;
     readonly namespace?: string;
     /**
-     * True iff the id **was** a member and a generation without it is now current — and the generation that held
-     * the bit has been deleted from the bucket. The physical half is inherent: an erasure is a rewrite, and the
-     * rewrite's predecessor is collected before this entry is returned (see {@link CloudRoaring.eraseSubject}).
+     * True iff the id **was** in the segment and **no generation of it holds the id now** — not the current one, not
+     * one below the pointer, and not one above it, where a rollback leaves the generations it rolled back from. The
+     * current generation is one without it, every generation that held it has been deleted from the bucket, and the
+     * call listed the bucket and read what was left before this entry was returned (see
+     * {@link CloudRoaring.eraseSubject}).
      */
     readonly erased: boolean;
-    /** The generation the id was found in (present whenever the segment was read). */
+    /**
+     * The generation the id was found in (present whenever the segment was read) — the newest of them, when the
+     * current generation did not hold it and several others did.
+     */
     readonly fromGeneration?: number;
     /** The generation written without the id (present whenever one was written). */
     readonly generation?: number;
     /**
-     * Why the id was NOT erased from this segment, when `erased` is false. `'superseded'` — a newer generation
-     * was published while the rewrite was in flight, by a load or by another erasure, so **this call** did not
-     * erase the id; re-run against the new generation, which erases it if it is still there and reports nothing
-     * for the segment if the racing writer already removed it. `` `error: <message>` `` — an isolated per-segment
-     * fault (per-segment faults are recorded so one segment can't discard the whole ledger); re-run after fixing
-     * the fault. A fault that landed once part of the work was already done — a Storage `delete` fault, or a collect
-     * that could not prove the segment was still the same one, whether or not a rewrite was published first —
-     * also re-runs, but **read what the re-run says**: it usually reports `erased: true` against the superseded generation it found the id in, it reports
+     * Why the id was NOT erased from this segment, when `erased` is false. `'superseded'` — the pointer moved while
+     * the call was in flight, by a load, another erasure or a rollback, so **this call** did not erase the id;
+     * re-run against the new generation, which erases it if it is still there and reports nothing for the segment
+     * if the racing writer already removed it. `` `error: <message>` `` — an isolated per-segment fault
+     * (per-segment faults are recorded so one segment can't discard the whole ledger); re-run after fixing the
+     * fault. A budget refusal is one of these: the segment's generations did not fit `budget`, so it was not finished;
+     * re-run with a higher `budget`. A fault that landed once part of the work was already done — a Storage `delete` fault, a collect that
+     * could not prove the segment was still the same one, or a generation still holding the id when the bucket was
+     * listed at the end, whether or not a rewrite was published first — also re-runs, but **read what the re-run
+     * says**: it usually reports `erased: true` against the generation it found the id in, it reports
      * nothing at all if a racing collector took that generation first (the bit is gone, but no run holds a
      * receipt for it), and if the segment's row has since been purged it is no longer scanned at all — anything
-     * left in its bucket is an orphan for `checkConsistency` / `gcOrphanGenerations`. **Segments the id is not in
+     * left in its bucket is an orphan, which `store.generations(ref)` lists and `store.dropSegment(ref, {
+     * confirmSegment })` deletes; `checkConsistency` and the collection a load runs read rows, so neither reaches it.
+     * **Segments the id is not in
      * are not listed, and neither are segments that no longer have a registry row** — an empty ledger is not by
      * itself proof the id is gone.
      */
@@ -258,14 +290,17 @@ export interface EraseSubjectResult {
 export type MaterializeRefusal = Exclude<LoadRefusal, 'superseded'>;
 /** What an `*Into` verb wrote: the new generation of the destination, and whether it became current. */
 export interface MaterializeResult {
-    /** The generation written. Present even when refused — it is what was written and then deleted again. */
+    /**
+     * The generation written. Present even when refused: the refusal deleted that object, unless the destination's
+     * row changed while it was writing, which leaves it in the bucket.
+     */
     readonly generation: number;
     /**
      * Whether this generation is now the destination's current one.
      *
-     * Before the guard existed this was always true, because a materialisation always published. Branch on it:
-     * a refusal is reported, not thrown, so a caller that ignores it sees a successful-looking result for a
-     * write that deliberately did not happen.
+     * `false` when the guard refused the result: an empty one over a non-empty destination, or one outside
+     * `guard`'s bounds. Branch on it: a refusal is reported, not thrown, so a caller that ignores it sees a
+     * successful-looking result for a write that deliberately did not happen.
      */
     readonly published: boolean;
     /** Set only when `published` is false. A lost race throws {@link WriteConflictError} rather than appearing here. */
@@ -290,29 +325,11 @@ export interface MaterializeResult {
      */
     readonly collected: readonly number[];
 }
-/**
- * Options that moved into a group, and where each one went.
- *
- * TypeScript rejects these at the call site, which covers most callers. It does not cover a plain-JS caller, a
- * config object that arrived as JSON, or anything that reached the constructor through an `as` cast — and for
- * this particular set, being ignored is worse than being rejected, because **every one of them is a knob whose
- * absence is silent and wrong**: a dropped `requireEncryption` reads cleartext when the caller demanded
- * encryption, a dropped `clock` makes a "deterministic" job non-deterministic, and a dropped
- * `coldReaderCacheMaxBytes` restores a 64 MiB ceiling someone had deliberately lowered for a small heap.
- * None of those announces itself; each looks like the store simply working.
- */
-/**
- * How a `0.9.x` option is answered: it moved into a group, it was renamed, or it is gone.
- *
- * The category is DATA, not inferred from how the guidance happens to be punctuated. The first version
- * decided by testing whether the replacement text looked like an identifier, which got two entries wrong in
- * opposite directions: `registry` HAS a successor and was announced as "removed", and `cold` → `storage` was
- * announced as "moved into a group" when `storage` is the one required flat option, not a group. A reader
- * told to look in a group that does not exist is the failure this whole guard is about.
- */
 export declare class CloudRoaring {
     private readonly engine;
     private readonly cache;
+    /** The store's retry options, for a pinned engine to read through as the store's own does; undefined when off. */
+    private readonly retryOptions;
     private readonly crbmSource;
     private readonly clock;
     private readonly metrics;
@@ -323,70 +340,77 @@ export declare class CloudRoaring {
     /** Resolved store-level per-op budget (null = disabled); the admin scans use it, with a per-op override. */
     private readonly budget;
     /**
-     * Refuse an option that moved into a group, naming where it went.
+     * Refuse any option key the store does not take, at the top level or inside a group, naming each one.
      *
-     * Silently ignoring one would be the exact failure this release exists to remove — see {@link MOVED_OPTIONS}
-     * for why each of these is unsafe to drop rather than merely untidy.
+     * An option the store ignored would do nothing and look as if it had — a typo'd `cache.maxChunk`, a key from
+     * another library's config spread into this one — so every key is checked against {@link OPTION_KEYS}.
      */
-    private static rejectMovedOptions;
+    private static rejectUnknownOptions;
     constructor(options: CloudRoaringOptions);
     /**
      * The write-side deps, from the store's own drivers, for the lifecycle helpers and the `*Into` verbs. Requires
      * the store to have been constructed with a **backend**, which supplies both halves: an `IStorageDriver` to
      * write generations through (a pre-built `StorageChunkSource` has none) and the registry holding the pointer
      * every write publishes.
-     * Out-of-process callers use the free functions with explicit deps.
      */
     private lifecycleDeps;
     /** Get a handle to a segment. Validates the name (non-empty, well-formed, within the encoded-length cap). */
     segment(name: string, options?: SegmentOptions): Segment;
     /**
-     * Write `ids` as a **new generation of `dest`** and publish it forward-only — the shared body of the `*Into`
-     * verbs. The destination's previous generation stays readable until the publish lands (readers re-resolve
+     * Write `ids` as a **new generation of `dest`** and publish it — the shared body of the `*Into` verbs. An `*Into`
+     * materialisation is a load, and publishes the same way (hard invariant 1): every load that finds a row fences its
+     * publish on the row's token; a guarded load (the default, since the empty refusal reads the current generation)
+     * also fences on the pointer it judged (`expectFrom`), and one that found no row fences on that absence instead.
+     * Only an unguarded load (`allowEmpty: true` and no `guard.minRetained`) onto a segment with no row publishes bare
+     * forward-only. The destination's previous generation stays readable until the publish lands (readers re-resolve
      * within `cache.genTtlMs`).
      *
      * This routes through `loadSegment` rather than writing the generation itself, and that is the whole point
      * of it. A materialisation is a load whose ids happen to come from a combine instead of from upstream, so
      * everything `load()` learned the hard way applies unchanged: the generation is written UNPUBLISHED, the
-     * guard runs while the old generation is still authoritative, the publish is fenced (on the pointer it
-     * judged, on the row's identity, and — where it judged an ABSENT segment — on that absence), and a refused
-     * object is reclaimed only after re-reading the row and finding the same incarnation (hard invariant 1:
+     * guard runs while the old generation is still authoritative, the publish is fenced as above, and a refused
+     * object is reclaimed only when a re-read finds the row unchanged (the same token) or gone (hard invariant 1:
      * deleting it after a purge-and-recreate would put a live row over a missing generation).
      *
      * That last check narrows the window rather than closing it: the row read and the delete are two round
-     * trips, and `IStorageDriver` has no conditional delete to make them one. `gcOrphanGenerations` carries
-     * the same residual and says so. The failure it leaves is an orphan object, which costs storage until
+     * trips, and `IStorageDriver` has no conditional delete to make them one. the collection a load runs carries
+     * the same residual. The failure it leaves is an orphan object, which costs storage until
      * something collects it — deliberately the cheaper side of the trade.
      *
-     * Materialising used to do none of that. It wrote and published in one step, so an empty combine — a typo'd
-     * operand, an `exclude` that swallowed everything, an operand that had not loaded yet — silently replaced
-     * `dest` with an empty generation. That is the same failure `load()`'s guard exists to prevent, on the same
-     * data, and it was reachable without passing any option at all.
+     * Written and published in one step, with no guard, an empty combine — a typo'd operand, an `exclude` that
+     * swallowed everything, an operand that had not loaded yet — would silently replace `dest` with an empty
+     * generation: the same failure `load()`'s guard exists to prevent, on the same data, reachable without passing
+     * any option at all.
      *
-     * **A lost race still throws.** `loadSegment` reports one as `reason: 'superseded'`; the `*Into` verbs have
-     * always thrown {@link WriteConflictError} for it, and a caller who wrote `catch (WriteConflictError)` must
-     * keep working. So that one refusal is translated back into the throw, and `MaterializeResult.reason` never
-     * carries it.
+     * **A lost race throws.** `loadSegment` reports one as `reason: 'superseded'`; the `*Into` verbs throw
+     * {@link WriteConflictError} for it, so a caller can `catch (WriteConflictError)`. That one refusal is
+     * translated into the throw, and `MaterializeResult.reason` never carries it.
      *
      * **A `WriteConflictError` does not by itself mean nothing was published**, and that is worth knowing
-     * before you write the retry. `'superseded'` covers four different causes — the write-once PUT collided,
-     * the pointer moved, the row's token changed, the row was purged — and only the first two are the
-     * "somebody beat us" the name suggests. A token can also change on a write that is not a supersession at
-     * all, such as a `setRetention` on the destination. On top of that, the collection pass that runs AFTER a
+     * before you write the retry. `'superseded'` covers five different causes — the write-once PUT collided,
+     * the pointer moved, a row appeared where the load found none, the row's token changed, the row was purged —
+     * and only the first three are the "somebody beat us" the name suggests. A token can also change on a write
+     * that is not a supersession at all, such as a `setRetention` on the destination. On top of that, the collection pass that runs AFTER a
      * successful publish can raise the same error. So: treat it as "re-read the destination and decide",
      * never as "the write did not happen".
      *
-     * **And it still collects nothing**, unlike `load()`. See the `keep` default below.
+     * **And by default it collects nothing**, unlike `load()`. See the `keep` default below.
      */
     private materialize;
     /**
      * **Subject access (GDPR Art. 15 / CCPA right-to-know): which segments is this id a member of?**
      *
      * Enumerates the **registered** segments (via the store's own `registry`) and does a `has(id)` on each — no
-     * drivers to re-pass. Complete only over registered segments (every loaded segment has a row, so register the
-     * registry the loads used). There is deliberately **no `id → segments` reverse index** — that would tax every
-     * load for a rare request; this admin scan is `O(registered segments)` and touches no hot path. Requires a
-     * `registry` in the store config (throws {@link UnsupportedError} otherwise).
+     * drivers to re-pass. Complete only over registered segments (every loaded segment has a row, so build the
+     * store on the backend the loads used). There is deliberately **no `id → segments` reverse index** — that would
+     * tax every load for a rare request; this admin scan is `O(registered segments)` and touches no hot path. Needs
+     * a storage backend (throws {@link UnsupportedError} otherwise).
+     *
+     * **Current as of the registry row, not as of the reader's cache.** Each segment's resolved generation is
+     * compared with the row the scan listed, and a segment whose cached generation differs is re-resolved before the
+     * read, so a load or an erasure from another process shows at once — whatever `cache.genTtlMs` is, `0` included.
+     * The comparison is on the generation **and** the row's token, so a segment retired, purged and loaded again from
+     * generation 0 while this store held its old generation 0 is told apart too.
      */
     subjectReport(id: number, options?: {
         namespace?: string;
@@ -400,44 +424,59 @@ export declare class CloudRoaring {
      *
      * For each **registered** segment the id is a member of, `eraseIdFromSegment` rewrites the current generation
      * without the id — every chunk streamed through, one bit cleared — publishes the rewrite **fenced on the
-     * generation it was derived from**, and
-     * collects the generation that held the bit. The returned per-segment record is your **erasure ledger** —
+     * generation it was derived from**, and collects the generation that held the bit. A segment whose current
+     * generation does not hold the id is searched anyway, every generation in its bucket: a retained superseded one
+     * can still hold it, and so can one above the pointer after a {@link CloudRoaring.rollback}, which the rollback
+     * could make current again. Each holder is deleted — below the pointer by a `keep: 0` collection, above it one
+     * by one, re-proved against the row first — and the generations above the pointer that never held the id stay
+     * as rollback targets. An entry says `erased: true` only once the call has listed the bucket and read what is
+     * left: **no generation of the segment holds the id**. The returned per-segment record is your **erasure ledger** —
      * persist it / route it to your audit sink as the proof of deletion (a `segment.rewrite` audit event is also
      * emitted per rewrite when you pass `audit`).
      *
      * Uses the backend's **own** two halves, so the membership check and the rewrite provably run
      * over the same generation. Requires the store built with a **backend** (throws
      * {@link UnsupportedError} otherwise; a pre-built `StorageChunkSource` store has no `IStorageDriver` to write
-     * through — use the `eraseIdFromSegment` free function there).
+     * through; build the store on a backend instead).
      *
      * **One contract remains** (an integrator obligation the library cannot check): **do not load the segment
      * while erasing from it.** A load that lands after the rewrite carries whatever its source held, and the
      * library cannot know that source was meant to exclude the id. Quiesce loads of the affected segments for the
      * duration, or fix the source first and load after. A writer that lands *during* the rewrite is caught: the
-     * rewrite's publish is refused **by the fence** — `publishGeneration`'s `expectFrom`, which lands the CAS only
+     * rewrite's publish is refused **by the fence** — the publish lands its compare-and-swap only
      * while the pointer is still on the generation the rewrite streamed — and the entry says `note: 'superseded'`,
-     * so re-run. Forward-only alone would NOT refuse it: `nextGeneration` numbers above everything in the bucket,
+     * so re-run. Forward-only alone would NOT refuse it: the rewrite's number goes above everything in the bucket,
      * so the rewrite would out-rank the newer generation and then collect it.
      *
      * A racing **erasure** is caught before that, and reported the same way. It collects with `keep: 0`, taking
      * every generation below its new pointer — the one this rewrite is streaming, and the object this rewrite
-     * just wrote — so the loser can find its own inputs deleted mid-flight. That surfaces as a reason rather than
-     * an error, read off the row: a moved pointer is `'superseded'`, a concurrent `dropSegment` `'destroyed'`,
-     * a retention sweep that purged the row `'absent'`. Re-running is the fix in every case.
+     * just wrote — so the loser can find its own inputs deleted mid-flight. That surfaces as an outcome rather than
+     * an error, read off the row: a moved pointer is a `'superseded'` entry, which a re-run settles, and a segment
+     * that a concurrent `dropSegment` tombstoned or a retention sweep purged is left out of the ledger, as a fresh
+     * call would leave it out.
      *
      * **Read `note` on any `erased: false` entry — the two reasons mean different things.** `'superseded'` means
-     * another writer (a load, or another erasure) moved the pointer mid-rewrite, so **this call** did not erase
-     * the id. Re-run: it erases the id if it is still there, and lists nothing for the segment if a racing
+     * another writer (a load, another erasure, or a rollback) moved the pointer mid-call, so **this call** did not
+     * erase the id. Re-run: it erases the id if it is still there, and lists nothing for the segment if a racing
      * erasure of the same id already removed it. Do not read `'superseded'` as "the id is still present" —
      * read it as "not done by this call, and the re-run settles it".
      * `` `error: …` `` is a per-segment fault (caught so one segment can't discard the whole ledger) and it can land
      * on either side of the publish: if the rewrite had not published, the id is still there and a re-run erases
      * it; if the publish succeeded and only the **collection** of the old generation failed, the id is already
-     * absent from every read and what remains is an object in the bucket that still contains the bit. A re-run
-     * then reports nothing for that segment (the id is not in the current generation), so **that residual is
-     * collected by `gcOrphanGenerations(ref, deps, { keep: 0 })` or the next retention sweep**, not by another
-     * `eraseSubject`. Re-running is otherwise safe and idempotent: a segment the id is no longer in is not listed. Admin-only path;
-     * `O(registered segments)`, no hot-path cost. Per-subject crypto-shred is infeasible (a subject's bit is
+     * absent from every read and what remains is an object in the bucket that still contains the bit. The same
+     * note, after a publish, can mean a rollback moved the pointer back onto a generation that still holds the id
+     * while the collection ran — then the id is served again, and the entry says so rather than `erased: true`. A
+     * re-run searches every generation in the bucket, so it rewrites or collects what is left and usually reports
+     * `erased: true`; {@link SubjectErasureEntry.note} says what else a re-run can report. Re-running is otherwise safe
+     * and idempotent: a segment the id is no longer in is not listed. Admin-only path;
+     * `O(registered segments + superseded generations)`, no hot-path cost: a segment whose current generation lacks
+     * the id is searched generation by generation, one open for each other generation in its bucket, and with the
+     * keep-everything default of the `*Into` verbs that is one per generation the segment ever had. The per-op
+     * `budget` is charged one unit for each segment and one for each generation opened beyond the one its row names,
+     * so a fleet with long histories can exhaust it where the segment count alone would not. A segment that does is
+     * reported `erased: false` with an `error:` note, before it deletes anything (the one refusal that can come after a
+     * rewrite is the last check for a generation a concurrent writer left behind), and the
+     * rest of the scan continues: the call itself does not throw for it. Per-subject crypto-shred is infeasible (a subject's bit is
      * co-mingled in a shared container), so this is the single-subject erasure route; whole-segment/tenant erasure
      * is `dropSegment` / the `destroySegment`/`eraseNamespace` free functions.
      */
@@ -453,7 +492,7 @@ export declare class CloudRoaring {
      *
      * What the bucket holds, not what the segment has ever been — collection deletes superseded objects, so this is
      * the grace window plus whatever has not been collected yet. It is the set {@link CloudRoaring.rollback} can
-     * choose from, which is the reason to look at it. One `list` call; it does not open the objects.
+     * choose from, which is the reason to look at it. One registry read and one listing; it does not open the objects.
      *
      * Needs a backend.
      */
@@ -476,7 +515,7 @@ export declare class CloudRoaring {
      * a handle carrying an expired `expiresAt` reads empty by a rule that lives on the handle, not the row.
      *
      * Not a lock: the answer can change the moment it returns. If it has to hold, use the fence built for that —
-     * `load`'s `guard`, or `expectFrom`/`expectToken` on a publish. Needs a `registry`.
+     * `load`'s `guard`, or `expectFrom`/`expectToken` on a publish. Needs a storage backend.
      *
      * ```ts
      * if (!(await store.exists({ segment: 'users' }))) {
@@ -498,13 +537,13 @@ export declare class CloudRoaring {
      * Scoping to a namespace narrows the LIST prefix, so it really is the difference between reading one tenant
      * and reading all of them.
      *
-     * It streams, and stopping the iteration stops the scan — except behind a driver that buffers its
-     * enumeration to retry it as a unit, which `RetryingRegistryDriver` does: wrapped in that, the whole scan is
-     * paid for and resident before the first row arrives.
+     * It streams, and stopping the iteration stops the scan. It reads the registry directly and is not retried: a
+     * transient fault part-way through ends the loop with that error, and calling `segments()` again scans from the
+     * start.
      *
      * Yields `destroyed` tombstones and rows with `currentGen: null`, because a filtered enumeration that looks
      * complete is worse than an honest one — filter on `status`/`currentGen` yourself, or ask
-     * {@link CloudRoaring.exists} the narrower question. Needs a `registry`.
+     * {@link CloudRoaring.exists} the narrower question. Needs a storage backend.
      *
      * ```ts
      * for await (const s of store.segments({ namespace: 'active-daily' })) {
@@ -532,14 +571,22 @@ export declare class CloudRoaring {
      * current is a no-op that reports itself.
      *
      * It deletes nothing. The generations above the new pointer stay put — which is what makes this reversible —
-     * and are then *above* `currentGen`, where collection never looks, so they remain until a later load raises the
-     * pointer past them. An operator who has just undone a bad load should not have the evidence collected out from
-     * under them.
+     * and are then *above* `currentGen`, where collection never looks. They remain until a load numbers above them
+     * (collection then keeps the newest `keep` of what is below its pointer), {@link CloudRoaring.dropSegment}
+     * deletes them, or {@link CloudRoaring.eraseSubject} does: all of those present when it rewrites, and only those holding
+     * the id when the current generation does not. An operator who has just undone a bad load should not have the
+     * evidence collected out from under them, while a rollback target that still holds erased data would make the
+     * erasure undoable.
+     *
+     * A target **above** the pointer needs `{ allowForward: true }`, and is refused with {@link ValidationError}
+     * without it: that is also where objects live that were never published, such as a load that wrote its object
+     * and died before the publish. Undoing an earlier rollback is what the opt-in is for.
      *
      * Needs a backend.
      */
     rollback(ref: SegmentRef, toGeneration: number, options?: {
         audit?: IAuditSink;
+        allowForward?: boolean;
     }): Promise<RollbackResult>;
     /**
      * **Replace this segment's contents** with `ids`, as one new immutable generation, and make it current.
@@ -550,8 +597,8 @@ export declare class CloudRoaring {
      * attention to and everybody pays for.
      *
      * ```ts
-     * const r = await store.load('audience:active', idsFromWarehouse, {
-     *   guard: { maxShrink: 0.5 },   // refuse a load that drops more than half the segment
+     * const r = await store.load({ segment: 'audience:active' }, idsFromWarehouse, {
+     *   guard: { minRetained: 0.5 }, // refuse a load that would drop more than half the segment
      * });
      * if (!r.published) console.warn(`load refused: ${r.reason}`);
      * ```
@@ -569,15 +616,22 @@ export declare class CloudRoaring {
      * `eraseIdFromSegment` instead, because three of its four refusals are expected guard outcomes rather than
      * faults.
      *
-     * The object written for a refused load is deleted again before returning — it sits above `currentGen`, where
-     * generation collection deliberately never looks, so nothing else would reclaim it. The exception is a load
-     * that finds the segment **re-created** underneath it: the generation number it holds may then name the new
-     * incarnation's live object, so it leaves the orphan rather than risk deleting live data.
+     * `'superseded'` means another writer got there first: another load took the same generation number, so this
+     * one wrote nothing (`size: 0`), or the segment's registry row changed while the load was writing — another load
+     * published, a retention change, a rollback or an erasure wrote the row, or the row was deleted.
+     *
+     * A refused load deletes the object it wrote before returning — it sits above `currentGen`, where generation
+     * collection deliberately never looks — but only while the segment's registry row is unchanged or gone. Once
+     * another write has changed the row, the generation number it holds may name another incarnation's live object,
+     * so it leaves the orphan rather than risk deleting live data. The orphan is an ordinary generation once a later
+     * one is current above it, and collection counts it within `keep`.
      *
-     * Two things it does **throw** for, rather than report: a crypto-shredded segment (`ValidationError` — there
-     * is no key to write under), and a collection pass that could not prove the segment was still the same one
-     * (`WriteConflictError`). The second can be raised **after** the publish already landed, so a throw does not
-     * by itself mean the load did not take effect — re-read the pointer rather than assuming.
+     * What it **throws** for is a fault rather than an outcome: invalid options or ids, and a crypto-shredded
+     * segment (`ValidationError`); a key the keystore cannot provide (`KeyUnavailableError`); a current generation
+     * that will not open when a guard reads its size (`IntegrityError`); a driver failure; and a collection pass
+     * that could not prove the segment was still the same one (`WriteConflictError`). The last can be raised
+     * **after** the publish already landed, so a throw does not by itself mean the load did not take effect —
+     * re-read the pointer rather than assuming.
      *
      * Needs a backend (throws {@link UnsupportedError} otherwise).
      */
@@ -612,10 +666,14 @@ export declare class CloudRoaring {
      * could not remove rather than returning a result that looks like a clean drop.
      *
      * Reads become empty within `cache.genTtlMs` (default 2 s), not instantly: a store that had already read this
-     * segment may answer from its cached generation + cached chunks until that window lapses. A reader that never
-     * touched it sees empty at once. **That bound needs a clock and `cache.genTtlMs > 0`** — a store built without a
-     * clock, or with `cache.genTtlMs: 0` ("pin forever"), holds its resolved snapshot for its own lifetime and can
-     * keep answering `true` for a dropped segment indefinitely; restart it.
+     * segment may answer from its cached generation + cached chunks until that window lapses, or, while the registry
+     * cannot be read because of a transient fault, until a retry 500 ms apart reaches it again. A reader that never
+     * touched it sees empty at once. **That bound needs a registry and `cache.genTtlMs > 0`.** A store with no registry
+     * (a bare `IStorageDriver`), with `cache.genTtlMs: 0`, or on a storage source built with no clock, has no timed
+     * refresh. It notices the drop only when a read has to fetch
+     * from a deleted generation or its reader cache evicts the segment, and until then a chunk it has cached
+     * answers without reaching storage, so it can keep answering `true` for a dropped segment indefinitely. Tell
+     * it with {@link invalidate}, or restart it.
      *
      * Needs the store built with a **backend** (throws {@link UnsupportedError} otherwise),
      * because it has to enumerate and delete generations — a pre-built `StorageChunkSource` only reads.
@@ -648,8 +706,8 @@ export declare class CloudRoaring {
      *
      * A value in the past is legal and means "eligible on the next sweep" — backfilling a policy onto existing
      * buckets is normal. A value below `MIN_EXPIRES_AT_MS` (2001-09-09) is rejected: it is almost certainly epoch
-     * **seconds**, which would read as long-expired and retire the segment on the next pass. Needs a `registry`
-     * in the store config (throws {@link UnsupportedError} otherwise), and refuses a crypto-shredded segment.
+     * **seconds**, which would read as long-expired and retire the segment on the next pass. Needs a storage
+     * backend (throws {@link UnsupportedError} otherwise), and refuses a crypto-shredded segment.
      */
     setRetention(ref: SegmentRef, policy: RetentionPolicy): Promise<SetRetentionResult>;
     /**
@@ -679,7 +737,7 @@ export declare class CloudRoaring {
      * ```ts
      * // In your scheduled handler. Start with a preview in a new deployment.
      * const preview = await store.retireExpired({ namespace: 'active-daily', dryRun: true });
-     * console.log(`would retire ${preview.retired} of ${preview.scanned} (limited: ${preview.limited})`);
+     * console.log(`would retire ${preview.wouldRetire} of ${preview.scanned} (limited: ${preview.limited})`);
      *
      * const swept = await store.retireExpired({ namespace: 'active-daily' });
      * for (const e of swept.entries) {
@@ -705,8 +763,9 @@ export declare class CloudRoaring {
      * first, since nothing else ever would for a tombstoned segment. Attribution is a **positive marker the sweep
      * stamps on its own retirements**, not an inference from "destroyed + an expired policy": a crypto-shred leaves
      * `retention` untouched, so setting a policy and then honouring a right-to-erasure request mid-window produces
-     * exactly that row, and deleting it would destroy the Art. 17 attestation and un-fence the name. Pass
-     * `purgeTombstones: false` to keep every tombstone.
+     * exactly that row, and deleting it would destroy the Art. 17 attestation and un-fence the name. By default a
+     * segment that held nothing has its row deleted in the pass that retires it, since that row would only fence the name.
+     * Pass `purgeTombstones: false` to keep every tombstone, that row included.
      *
      * Needs the store built with a **backend** (throws {@link UnsupportedError} otherwise),
      * because retiring a segment deletes its storage objects. `now` defaults to the store's clock.
@@ -723,21 +782,27 @@ export declare class CloudRoaring {
      * that advances `currentGen`**, which the snapshot TTL notices and the generation-keyed cache misses on.
      * Neither notices an event that *destroys* what they were derived from.
      *
-     * The verbs on this class handle themselves — `eraseSubject`, `dropSegment` and `retireExpired` invalidate
-     * what they touch. This method is for the cases they cannot see:
+     * The store's own writes handle themselves: `load`, `rollback`, `eraseSubject`, `dropSegment` and `retireExpired`
+     * here, and a segment's `*Into` verbs, invalidate what they touch. This method is for the cases they cannot see:
      *
      * - **`destroySegment` / `eraseNamespace`**, which are free functions over raw drivers rather than methods
-     *   here, so a crypto-shred performed beside this store leaves it holding an open reader and an unwrapped
-     *   DEK. Until it is told, it keeps decrypting — including chunks it had never fetched before the shred.
+     *   here, so a crypto-shred performed beside this store invalidates nothing in it. It keeps its open reader and
+     *   the unwrapped DEK, and decrypts with them, chunks it had never fetched before the shred included, until its
+     *   snapshot re-resolves: within `cache.genTtlMs` when the store has a registry and a `genTtlMs` above 0, and
+     *   otherwise only when its caches let the segment go or a read has to fetch from a generation a sweep collected.
+     *   A pin answers with no timed bound, until it is told or both caches let it go.
      * - **Another process.** Erasing on one box invalidates nothing on the others; each store bounds its own
-     *   staleness by `cache.genTtlMs`, and a store built with no clock or `cache.genTtlMs: 0` ("pin forever") never
-     *   converges at all. If a compliance deadline depends on every reader converging, you need to signal them —
-     *   this is the call to make when your own fan-out delivers.
+     *   staleness by `cache.genTtlMs`, and a store with no registry (a bare `IStorageDriver`), with
+     *   `cache.genTtlMs: 0`, or on a storage source built with no clock has no bound at all: it converges only when a read happens to miss its caches. If a compliance deadline depends on every
+     *   reader converging, you need to signal them — this is the call to make when your own fan-out delivers.
+     *
+     * It also forgets any replacement this store found of a pin's object, so once it is called after a restore puts that
+     * object back, the pin reads it again.
      *
      * Synchronous, best-effort, and safe to call for a segment this store has never read.
      *
      * ```ts
-     * await destroySegment(ref, { storage, registry, keystore }, { confirmSegment: ref.segment });
+     * await destroySegment(ref, { registry: backend.registry }, { confirmSegment: ref.segment });
      * store.invalidate(ref);                       // this process
      * await bus.publish('cloudbitmaps.invalidate', ref); // and every other one
      * ```
@@ -746,19 +811,16 @@ export declare class CloudRoaring {
     /**
      * Build a handle held at the generation `ref` resolves to right now. See {@link Segment.pin}.
      *
-     * The pinned handle gets its own engine but **shares the store's chunk cache**, which is safe precisely
-     * because the cache is keyed by the source's version rather than the generation number: the pinned view
-     * reports the version captured at pin time, so its decoded chunks cannot collide with the live generation's.
-     * Sharing it on a generation-only key was how a pinned read could resurrect an id already reported
-     * physically gone.
+     * The pinned handle gets its own engine but **shares the store's chunk cache**, under keys of its own: the
+     * pinned view reports the version captured at pin time, marked as a pin's, so its decoded chunks are never
+     * those of a live read that fetched across a publish (see {@link PinnedStorageChunkSource.currentVersion}).
      */
     private pinSegment;
     /**
-     * An engine reading every segment in `pins` at its pinned generation and everything else live.
+     * An engine reading every segment in `pins` at its pinned generation and everything else live, with the store's
+     * retries, so a transient fault on a pinned read is retried as it would be on a live one.
      *
-     * It **shares the store's chunk cache**, which is safe only because that cache is keyed by the source's
-     * version rather than the generation number: a pinned view reports the version captured at pin time, so its
-     * decoded chunks cannot collide with the live generation's.
+     * It **shares the store's chunk cache and its memory bound**, under keys of its own for each pinned segment.
      */
     private engineWithPins;
     /**
@@ -769,19 +831,30 @@ export declare class CloudRoaring {
      * `other.intersect([snap])` silently does not, and the two are the same question. So the combine collects
      * every pin in play and runs on an engine that honours all of them. With no pins anywhere this is the
      * store's own engine and costs nothing.
+     *
+     * One engine reads a segment at one generation, so a combine that holds the same segment at two — two pins of
+     * it, or a pin and a live handle — is refused. Keeping one of them would answer the question for the wrong
+     * instant, and say nothing: diffing two snapshots of a segment returned no ids at all.
      */
     private engineForCombine;
+    /** `op` under the store's retries, as the store's own reads run; bare when the store has retries off. */
+    private withRetries;
     /** The store's registry, or a typed error naming the operation that needs one. */
     private requireRegistry;
     /**
      * **Cross-tier DR consistency check.** After a restore/failover, verify every registered segment's `currentGen`
      * actually has its `.crbm` present in Storage — catching a **torn restore** where the registry (`currentGen`) came
      * back ahead of the object store, so a pointer references a generation that isn't there (reads would then
-     * throw). Read-only, bounded fan-out; run it at startup after a restore. Returns `{ checked, inconsistent }` —
-     * `inconsistent` empty ⇒ coherent; otherwise it names the segments to recover (restore the object store, or
-     * roll the registry back to a coherent point). Needs the store built with a **backend**
+     * throw). Read-only, bounded fan-out; run it at startup after a restore. Returns `{ checked, inconsistent,
+     * errored }` — `inconsistent` empty ⇒ coherent; otherwise it names the segments to recover (restore the object
+     * store, or roll the registry back to a coherent point). Needs the store built with a **backend**
      * (throws {@link UnsupportedError} otherwise). `destroyed` (crypto-shredded) segments are skipped. Pair it with
      * the DR runbook (docs/guide/disaster-recovery.md).
+     *
+     * It holds the registry rows it enumerates resident, at most 250,000 of them, and throws
+     * `BudgetExceededError` past that rather than report a partial scan as a whole one. This method takes no
+     * ceiling of its own: narrow the scan with `namespace`, or call `runConsistencyCheck` over the backend's
+     * `storage` and `registry` with a higher `maxScanSegments`.
      */
     checkConsistency(options?: {
         namespace?: string;
@@ -806,8 +879,13 @@ export declare class CloudRoaring {
      */
     static estimateCost(input: EstimateInput): CostReport;
 }
-/** Options common to every chunk-aligned combine (`intersect` / `union` / `andNot`). */
-export interface BaseCombineOptions {
+/**
+ * Options common to every chunk-aligned combine (`intersect` / `union` / `andNot`), and the `*Into` verbs.
+ *
+ * The range, `after` and `through`, applies to every operand and every `exclude`: the combine yields only the ids
+ * in `(after, through]` and fetches only the chunks the range overlaps, as {@link Segment.iterate} does.
+ */
+export interface BaseCombineOptions extends IdRange {
     /** Max chunk keys resolved concurrently — bounds the Storage footprint. A positive integer. */
     readonly concurrency?: number;
     /** Override the store's per-op denial-of-wallet budget for this call (`false` lifts it). */
@@ -840,7 +918,10 @@ export interface BaseCombineOptions {
  * list costs reads proportional to the audience, not to itself.
  */
 export interface CombineOptions extends BaseCombineOptions {
-    /** Segments whose ids are subtracted from the result. */
+    /**
+     * Segments whose ids are subtracted from the result. An **expired** handle here excludes nothing, in every
+     * combine — it is skipped without being read, exactly as in {@link Segment.andNot}.
+     */
     readonly exclude?: Segment[];
 }
 /**
@@ -857,12 +938,11 @@ export interface MaterializeOptions extends CombineOptions {
      *
      * It is on the call rather than on the store because that is where every other auditable operation takes it
      * (`eraseSubject`, `dropSegment`, `retireExpired`): the caller who performs the act decides where the record
-     * goes. Without it a `*Into` was the one write path in the library that could make a generation current and
-     * leave no trace in the compliance trail.
+     * goes. Without it a `*Into` would be the one write path in the library that could make a generation current
+     * and leave no trace in the compliance trail.
      *
-     * It sits HERE rather than on {@link BaseCombineOptions}, where it used to, for the reason this type exists:
-     * the streaming verbs write nothing, so an audit sink on `intersect()` was a parameter that could not do
-     * anything. Same rule, now applied to itself.
+     * It sits HERE rather than on {@link BaseCombineOptions} for the reason this type exists: the streaming verbs
+     * write nothing, so an audit sink on `intersect()` would be a parameter that could not do anything.
      */
     readonly audit?: IAuditSink;
     /**
@@ -875,11 +955,12 @@ export interface MaterializeOptions extends CombineOptions {
     /** Refuse an implausible result rather than publish it. Same bounds, and same meaning, as on `load()`. */
     readonly guard?: LoadGuard;
     /**
-     * Generations to keep below the new pointer — see {@link LoadOptions.keep}.
+     * Generations to keep below the new pointer — see {@link LoadOptions.keep}. A value that is not a non-negative
+     * integer throws `ValidationError`.
      *
-     * **Defaults to keeping everything**, unlike `load()`, which keeps 1 and collects the rest. A
-     * materialisation has never collected, and an operator's recovery story can depend on that: `rollbackSegment`
-     * refuses a target that has been collected. Pass a number to collect on the way through; `0` keeps only the
+     * **Defaults to keeping everything**, unlike `load()`, which keeps 1 and collects the rest. An operator's
+     * recovery story can depend on a materialisation collecting nothing: `rollbackSegment` refuses a target that
+     * has been collected. Pass a number to collect on the way through; `0` keeps only the
      * generation this call publishes.
      */
     readonly keep?: number;
@@ -892,15 +973,6 @@ export interface MaterializeOptions extends CombineOptions {
  * solves the same problem the same way, by taking {@link BaseCombineOptions}.
  */
 export type AndNotIntoOptions = Omit<MaterializeOptions, 'exclude'>;
-/** How a `Segment` hands a result stream back to its store to become a new generation of `dest`. */
-/** Build a pinned twin of a handle — injected into `Segment` so it stays free of store wiring. */
-type Pin = (ref: SegmentRef, expiresAt?: number) => Promise<Segment>;
-/**
- * The engine a combine should run on, given every handle involved — `undefined` when none is pinned and the
- * store's own engine will do. Injected so `Segment` stays free of store wiring.
- */
-type CombineEngine = (handles: readonly Segment[]) => SegmentEngine | undefined;
-type Materialize = (dest: SegmentRef, ids: AsyncIterable<number>, op: string, options?: MaterializeOptions) => Promise<MaterializeResult>;
 /**
  * A handle bound to one segment — the read verbs, plus the three `*Into` verbs that write a **new generation**
  * of another segment.
@@ -908,36 +980,30 @@ type Materialize = (dest: SegmentRef, ids: AsyncIterable<number>, op: string, op
  * **IDs must be integers in `[0, 2^32)`** (dense 32-bit). A non-integer / negative / out-of-range id
  * throws {@link ValidationError}.
  *
- * There is no `add`/`remove` on a handle: data enters a segment as a whole generation (`bulkLoadCrbmGeneration`,
- * or one of the `*Into` verbs), and leaves it the same way (`eraseSubject`, `dropSegment`).
+ * A handle has no per-id write: data enters a segment as a whole generation (`store.load()`, or one of the
+ * `*Into` verbs), and leaves it the same way (`eraseSubject`, `dropSegment`).
  */
 export declare class Segment {
+    private readonly metricsOn;
     private readonly engine;
     private readonly ref;
     private readonly clock;
     private readonly metrics;
     private readonly materialize;
-    /** Build a pinned twin of this handle — injected so `Segment` stays free of store wiring. */
     private readonly pinned;
     private readonly combineEngine;
     /** Absolute epoch-ms deadline from {@link SegmentOptions.expiresAt}; `undefined` ⇒ this handle never expires. */
-    readonly expiresAt?: number | undefined;
+    readonly expiresAt?: number;
     /**
      * The generation this handle is held at, when it came from {@link Segment.pin}. Read by the store so a
      * pinned handle passed as an **operand** is still read at its pin rather than live.
      */
-    readonly pinnedAt?: PinnedAt | undefined;
-    private readonly metricsOn;
-    constructor(engine: SegmentEngine, ref: SegmentRef, clock: Clock, metrics: IMetricsSink, materialize: Materialize, 
-    /** Build a pinned twin of this handle — injected so `Segment` stays free of store wiring. */
-    pinned: Pin, combineEngine: CombineEngine, 
-    /** Absolute epoch-ms deadline from {@link SegmentOptions.expiresAt}; `undefined` ⇒ this handle never expires. */
-    expiresAt?: number | undefined, 
+    readonly pinnedAt?: PinnedAt;
     /**
-     * The generation this handle is held at, when it came from {@link Segment.pin}. Read by the store so a
-     * pinned handle passed as an **operand** is still read at its pin rather than live.
+     * Not constructible: a handle comes from {@link CloudRoaring.segment}, which wires it to the store's engine,
+     * caches and write path. The constructor takes those internals, so it is not part of the surface.
      */
-    pinnedAt?: PinnedAt | undefined);
+    private constructor();
     /**
      * **Hold this segment at the generation that is current right now**, for as long as you keep the handle.
      *
@@ -956,21 +1022,65 @@ export declare class Segment {
      * `other` at whatever is current — pin each segment if you want the whole query held. And a pinned handle
      * used as an *operand* is still read at its pin, never live.
      *
-     * **It is a hold, not a lease.** Nothing here stops `gcOrphanGenerations` deleting the generation underneath
+     * **One call reads a segment at one generation**, so a combine that holds this segment at two —
+     * `snap0.andNot([snap1])`, or `live.intersect([snap])` — throws {@link ValidationError} when it is read, and an
+     * `*Into` of one throws before it reads anything. Materialise one side first, with `intersectInto(dest, [])`.
+     *
+     * **A pin knows its object, not only its number.** A name purged and loaded again starts again at generation
+     * 0, so a pin of the old segment never reads the new one: what it has already read still answers, as the
+     * instant it pinned, and anything it would have to fetch fails with `NotFoundError`, as a swept pin's does.
+     *
+     * **It is a hold, not a lease.** Nothing here stops a collection deleting the generation underneath
      * you: a pinned read deliberately does **not** heal forward, because silently serving a different generation
      * is the one thing a pin exists to prevent, so it fails instead. Size `keep` to cover your longest pinned
-     * job — see [Sizing `keep`](../../docs/guide/getting-started.md#sizing-keep) — or take the pin on a segment
+     * job — see [Generations and `keep`](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/loading.md#generations-and-keep) — or take the pin on a segment
      * you are not collecting.
      *
-     * A segment with no current generation pins nothing and reads empty, exactly as it would unpinned. A pin
-     * taken before a crypto-shred stops reading when the shred lands: the destroyed row is re-checked every time
-     * the pinned reader opens, so a pin cannot outlive the key it was using.
+     * A segment with no current generation pins nothing and reads empty, exactly as it would unpinned. A pinned
+     * segment whose row is later dropped or destroyed fails once it must open its object again, rather than go empty
+     * part-way through a call. **A pin
+     * keeps the key its reader unwrapped for as long as that reader stays open, and answers from the chunks it
+     * decoded for as long as they stay cached.** This store invalidates a pin:
+     *
+     * - a `load`, a `rollback` or an `*Into` invalidates a pin of the segment it writes;
+     * - `dropSegment` invalidates a pin of the segment it drops, and `retireExpired` a pin of each segment its ledger
+     *   lists, retired or not, neither on a dry run;
+     * - `eraseSubject` invalidates a pin of each segment it scans that is not already destroyed.
+     *
+     * An invalidated pin opens its object again, and fails if that object is gone or replaced, or its row is gone or
+     * destroyed.
+     * Anything else leaves the pin as it is: after a `destroySegment` beside this store, or an erasure, a drop or a
+     * retirement through another store, in this process or another, the pin answers from what it holds until this
+     * store's reader cache evicts the pin's reader and its chunk cache evicts the chunks the pin decoded, or
+     * {@link CloudRoaring.invalidate} is called on this store. Where the
+     * object the pin reads has been deleted, by an erasure, a drop or a sweep, a chunk the pin has not cached fails at
+     * once. No timed refresh bounds any of that, as none bounds anything else a pin holds.
+     *
+     * A replacement a pin has found is remembered, so its later chunk reads fail with no request, until the store
+     * forgets it: an invalidation of the segment does, as does a later `pin()` of the same version that opens the object
+     * again, and the store remembers at most `cache.readerMax` of them. So once a restore puts the pinned object back,
+     * call {@link CloudRoaring.invalidate} on this store: the pin then reads the object again.
+     *
+     * `pin()` reads the registry row and opens the generation at once, so the pin knows its object before its first
+     * read. With a registry, pins of one generation taken while its row is unchanged share one reader while the store
+     * keeps it open, pins taken at the same moment included: the first costs a tail read, and a key unwrap for an
+     * encrypted segment, whether or not it is read, and the rest cost the row read alone. Without a registry every
+     * `pin()` lists the segment's objects and makes the tail read, since only the object can tell two incarnations of
+     * a name apart there. It retries a
+     * transient fault as the store's reads do, and heals a generation swept between the two, but it fails where the
+     * generation cannot be opened: `NotFoundError` for a pointer at a missing object, `IntegrityError` for a damaged
+     * or misfiled one.
      *
      * Needs a store built on the `.crbm` storage source (the default when you pass a backend or a raw driver). Throws
      * {@link UnsupportedError} on a store wired with a pre-built source that cannot pin.
      */
     pin(): Promise<Segment>;
-    /** This handle's segment, as the cache/pin key — `ref` stays private; the encapsulation is worth the method. */
+    /**
+     * An opaque string that names this handle's segment, namespace included: two handles of one segment have the
+     * same key, a live handle and its pins among them. Use it as a `Map` key or a log field when you track handles
+     * and have not kept the name you made them with. The format is not specified and is not a storage key, so
+     * compare keys, never parse one.
+     */
     key(): string;
     /**
      * Has this handle's deadline passed? **The lazy half of expiry** — the whole check is one comparison against
@@ -985,15 +1095,15 @@ export declare class Segment {
      *
      * On the read verbs an expired handle answers empty, which is the point of lazy expiry. On a *write* the same
      * rule would be destructive in a way nobody asks for: `a.intersectInto(dest, [b])` where `b`'s deadline has
-     * quietly passed publishes an **empty generation over `dest`** — a wipe, reported as a successful write, with
-     * the cause (a deadline on a handle somewhere) nowhere in the result. Reads degrade to empty; writes must not.
+     * quietly passed would, unrefused, replace `dest` with an **empty generation** — a wipe, reported as a successful
+     * write, with the cause (a deadline on a handle somewhere) nowhere in the result. Reads degrade to empty; writes must not.
      *
      * So every handle in the call is checked, `dest` included: an expired `dest` does not change the bytes written,
      * but a caller who put a deadline on the thing they are writing into has said something contradictory and is
      * better told than guessed at. Open a handle without `expiresAt` to write, or drop the deadline.
      *
      * (The broader guard — refusing to publish an empty or implausible generation over a non-empty one, with an
-     * `allowEmpty` override — now covers these verbs too: they route through the same guarded write path as
+     * `allowEmpty` override — covers these verbs too: they route through the same guarded write path as
      * {@link CloudRoaring.load}. The two stay separate because they differ in kind. That one is a REPORTED
      * refusal a caller may legitimately override; an expired handle is a wiring mistake, so it THROWS, before
      * any object is written — and `allowEmpty: true` does not reach it.)
@@ -1010,15 +1120,54 @@ export declare class Segment {
     private timed;
     /** Membership: one chunk — the cache, else one ranged GET. Throws {@link ValidationError} on a bad id. */
     has(id: number): Promise<boolean>;
-    /** Cardinality — summed from the `.crbm` index with **zero payload reads** on a loaded segment. */
+    /**
+     * Cardinality — summed from the `.crbm` index with **zero payload reads** on a loaded segment.
+     *
+     * What this trusts: the answer is the sum of the per-chunk cardinalities the index records, and no payload is
+     * decoded to confirm it. The index is checked for internal consistency when the object is opened (each key in
+     * range and ascending, each cardinality in `1..65536`, each payload inside the payload region, and, on an
+     * unencrypted object, the footer's chunk count and total agreeing with the index), and a corrupt index that is
+     * still internally consistent yields a wrong count. `iterate()` and the combines decode the payloads, whose
+     * structure is checked.
+     */
     count(): Promise<number>;
-    /** Every id, ascending, streamed one chunk at a time. */
-    iterate(): AsyncIterable<number>;
     /**
-     * Map the facade's `Segment` handles in `exclude` down to the plain refs `core` takes. A method rather than
-     * a module function because `ref` is class-private — the encapsulation is worth more than the free function.
+     * Every id, ascending, streamed one chunk at a time. Pass a range to read part of the segment: the ids in
+     * `(after, through]`, fetching only the chunks the range overlaps. The per-op budget is charged for every chunk in
+     * the range, so give a page `through` as well as `after`. On a pinned handle it reads the pinned generation, as a
+     * full read does.
+     *
+     * ```ts
+     * // Keyset paging: each page resumes where the one before ended, and stops at its window's end.
+     * for await (const id of seg.iterate({ after: previousEnd, through: windowEnd })) await send(id);
+     * ```
+     *
+     * Each bound is optional and an integer in `0..4294967295`; a bad one throws {@link ValidationError} when the
+     * stream is first read. `after >= through` is an empty range, which reads nothing. An expired handle reads empty
+     * without checking its options, as every read of one does.
+     */
+    iterate(options?: IdRange): AsyncIterable<number>;
+    /**
+     * The options a combine hands the engine, read once, when it is called ({@link readOptions}), with the `exclude`
+     * it was given, already reduced to its live handles ({@link liveExcludes}) and mapped down to the plain refs
+     * `core` takes. A method rather than a module function because `ref` is class-private — the encapsulation is
+     * worth more than the free function.
+     *
+     * Each field is named rather than copied with a rest spread: a rest copy takes only own enumerable properties, so
+     * a bound held in a getter or inherited from a prototype was dropped, and the read silently widened to the whole
+     * segment.
      */
     private refsIn;
+    /**
+     * The handles in `options.exclude` that have not expired. **An expired exclusion excludes nothing**, in every
+     * combine, so it is dropped here, before the engine is asked for anything: it is never fetched, never
+     * checked for absence, and never counted in the pin-consistency check. `exclude` is read once, so a getter sees
+     * one call.
+     *
+     * With no `exclude` this is one property read and a shared empty list, and with none expired it returns the
+     * caller's own array, so the common case allocates nothing.
+     */
+    private liveExcludes;
     /**
      * Chunk-skipping intersection: stream the ids in **this** segment AND every segment in `others`, ascending.
      * Fetches only the Storage chunks present in *all* operands (a key absent from any operand contributes nothing
@@ -1031,7 +1180,8 @@ export declare class Segment {
     /**
      * Materialize `this ∩ others…` (minus `exclude`) as a **new generation of `dest`** — `dest`'s previous contents
      * are superseded, not added to. Streaming + bounded-memory; the result is one immutable object published
-     * forward-only, so readers of `dest` see either the old generation or the new one, never a partial. Needs the
+     * as a load is (the pointer advances to it, fenced on the row), so readers of `dest` see either the old generation
+     * or the new one, never a partial. Needs the
      * store built with a backend (throws {@link UnsupportedError} otherwise).
      *
      * **An empty result does NOT overwrite a non-empty destination.** A combine that comes out empty is far more
@@ -1069,6 +1219,10 @@ export declare class Segment {
      * suppression list: at most one read per surviving key of `this`, so subtracting a 61,000-chunk global
      * opt-out list from a 40-chunk audience costs at most 40 reads, not 61,000.
      *
+     * An expired handle in `excludes` excludes nothing, and is skipped without being read; if every one has
+     * expired the result is `this` whole. An expired `this` is empty. `exclude` on `intersect` and `union` follows
+     * the same rule.
+     *
      * To filter the *result of an intersection*, do not chain — pass `exclude` to {@link intersect} instead, so
      * the suppression folds into the same pass rather than materializing an intermediate segment first.
      */
@@ -1078,15 +1232,14 @@ export declare class Segment {
     /**
      * Grounded cost report for this segment: storage cost from its **real** `.crbm` size (exact, no payload
      * reads); request cost from the supplied `workload` rates. A segment with no Storage generation reports zero
-     * storage. See {@link CostReport} — it always includes a verdict (incl. the lose-zone).
+     * storage. The pointer refresh is priced at the store's own `cache.genTtlMs`, or at none when the store never
+     * refreshes, unless the workload sets `genTtlMs`. See {@link CostReport} — it always includes a verdict (incl.
+     * the lose-zone).
      */
     costReport(options?: {
         pricing?: PricingProfile;
         workload?: Workload;
     }): Promise<CostReport>;
 }
-export * from '@cloudbitmaps/core';
-export { bulkLoadCrbmGeneration, eraseIdFromSegment, loadSegment, runExport } from './codec-bound.js';
-export { SafeBitmap, roaringCodec } from './roaring-codec.js';
-/** Package version marker. Kept in sync with package.json at release. */
-export declare const VERSION = "0.10.0";
+export { MemoryStorage, LocalFsStorage, CrbmStorageChunkSource, destroySegment, eraseNamespace, excludingReservedRows, readRetentionPolicy, MIN_EXPIRES_AT_MS, InProcessKeystore, NodeAead, aadFor, CloudRoaringError, ValidationError, WriteConflictError, IntegrityError, NotFoundError, UnsupportedError, CapabilityError, TransientError, KeyUnavailableError, BudgetExceededError, isCloudRoaringError, isWriteConflictError, isTransientError, isNotFoundError, isIntegrityError, isValidationError, CrbmReader, BufferReader, CountingMetricsSink, RecordingAuditSink, DEFAULT_RETRY_POLICY, AWS_US_EAST_1_ONDEMAND, ELASTICACHE_REDIS_US_EAST_1_ONDEMAND, ONE_REDIS_HA_CLUSTER, } from '@cloudbitmaps/core';
+export type { Aead, AeadSealed, AuditEvent, BlobReader, BlobSink, Budget, BudgetOption, ChunkRef, Clock, CodecBitmap, CodecInterface, ConsistencyErrorEntry, ConsistencyIssue, ConsistencyReport, CostReport, CrbmCrypto, CrbmReaderOptions, CrbmStorageChunkSourceOptions, DestroyResult, DropResult, EraseDeps, EstimateInput, ExportFailure, ExportFormat, ExportManifest, ExportOptions, ExportSink, ExportWriter, ExportedSegment, GenKey, GenerationEntry, GovernanceMeta, IAuditSink, IKeystore, IMetricsSink, IRegistryDriver, IStorageDriver, IdRange, InProcessKeystoreOptions, LoadGuard, LoadOptions, LoadRefusal, LoadResult, LocalFsStorageOptions, MemoryStorageOptions, MetricEvent, MetricOpName, MetricsSnapshot, NewRegistryRecord, PinnedAt, PinnedObject, PricingProfile, RedisNodeType, RedisSizing, RegCaps, RegistryPatch, RegistryRecord, RegistryStatus, RetentionPolicy, RetireEntry, RetireExpiredOptions, RetireExpiredResult, RetryPolicy, Rng, RollbackResult, SegmentInfo, SegmentRef, SegmentSize, SegmentSizing, SetRetentionResult, StorageBackend, StorageCaps, StorageChunkSource, Token, Workload, WrappedDek, } from '@cloudbitmaps/core';