@cloudbitmaps/roaring 0.9.0 → 0.11.0

package/dist/index.d.ts

@@ -1,277 +1,228 @@
-import { bulkLoadCrbmGeneration as bulkLoadCrbmGeneration$1, compactSegment as compactSegment$1, runCompactionCycle as runCompactionCycle$1, runExport as runExport$1, CodecBitmap, CodecInterface, BudgetOption, IColdDriver, ColdChunkSource, IWarmDriver, IRegistryDriver, IKeystore, Clock, Rng, RetryPolicy, IMetricsSink, SegmentEngine, SegmentRef, PricingProfile, Workload, Topology, CostReport, IAuditSink, CompactionOptions, CompactionResult, DropResult, RetentionPolicy, SetRetentionResult, RetireExpiredOptions, RetireExpiredResult, ConsistencyReport, ExportSink, ExportOptions, ExportManifest, EstimateInput } from '@cloudbitmaps/core';
-export * from '@cloudbitmaps/core';
-
 /**
- * Codec-bound wrappers over the public `@cloudbitmaps/core` entry points that need a bitmap codec.
+ * CloudRoaring — distributed, cloud-native Roaring Bitmaps, read from object storage.
  *
- * `core` is codec-agnostic and therefore cannot default the codec (the concrete codec lives *here*, in a package
- * that depends on core — a default over there would invert the dependency arrow). But an application using
- * `@cloudbitmaps/roaring` should never have to pass one. So this module re-binds each such entry point with
- * {@link roaringCodec} and the facade re-exports these **explicitly**, which shadows the same names coming from
- * `export * from '@cloudbitmaps/core'` (an explicit export always wins over a star export). Net effect: every
- * call signature is unchanged from before the family split — you can still call
- * `bulkLoadCrbmGeneration(driver, key, ids)` with no options at all.
+ * The `CloudRoaring` class is the read engine over **loaded** segments: write-once `.crbm` generations in an
+ * 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 `encryption: { keystore }` for encryption-at-rest / crypto-shred.
  *
- * A caller who *wants* a different codec passes it explicitly; the binding only fills an absent one — via
- * `?? roaringCodec` rather than spread order, so an explicit `codec: undefined` still gets the binding
- * (`exactOptionalPropertyTypes` is off, so that call typechecks and must not fall through to the throw).
- */
-
-type BulkLoad = typeof bulkLoadCrbmGeneration$1;
-type CompactSegment = typeof compactSegment$1;
-type RunCompactionCycle = typeof runCompactionCycle$1;
-type RunExport = typeof runExport$1;
-/**
- * {@link coreBulkLoad} with the roaring codec **and a real clock** pre-bound.
- *
- * The clock is what makes a large load **cooperative**: bulk-load yields the event loop periodically instead of
- * stalling the process for its whole duration (measured end-to-end at 450 ms of unbroken blocking for a 1M-id
- * load, now ~19 ms worst case). `core/` cannot
- * default it — it is timer-free by lint, which is precisely why waiting goes through the `Clock` seam — so the
- * flavor package supplies it, exactly as it supplies the codec. A caller who passes their own clock (a virtual
- * one in a simulation, say) keeps it.
- */
-declare const bulkLoadCrbmGeneration: BulkLoad;
-/** {@link coreCompactSegment} with the roaring codec pre-bound. */
-declare const compactSegment: CompactSegment;
-/** {@link coreRunCompactionCycle} with the roaring codec pre-bound. */
-declare const runCompactionCycle: RunCompactionCycle;
-/** {@link coreRunExport} with the roaring codec pre-bound (only the `'roaring'` format needs it). */
-declare const runExport: RunExport;
-
-declare class SafeBitmap implements CodecBitmap {
-    private readonly bitmap;
-    private constructor();
-    static empty(): SafeBitmap;
-    static fromValues(values: Iterable<number>): SafeBitmap;
-    /**
-     * S1: validate size, then deserialize with the **portable** (validated) format.
-     * Throws `IntegrityError` if the input exceeds `maxBytes` or fails to decode — the
-     * native addon is never handed unbounded or unsafe-format input.
-     */
-    static safeDeserialize(bytes: Uint8Array, maxBytes: number): SafeBitmap;
-    serialize(): Uint8Array;
-    /**
-     * Convert containers to run-encoding where that is smaller. Representation only — membership is untouched, and
-     * the portable format still round-trips through {@link RoaringCodec.safeDeserialize}.
-     *
-     * Roaring's third container type is a RUN, and no implementation selects it on its own: it takes an explicit
-     * `runOptimize()` pass. Nothing here made that call, so run-shaped ids paid array or bitset prices — measured
-     * at **570×** for a contiguous 1M-id range (128.1 KiB → 0.2 KiB) and **63×** for a 2,000-run shape
-     * (536.5 KiB → 8.5 KiB). Sparse ids come out byte-identical, so this is never a losing trade; roaring keeps
-     * whichever encoding is smaller per container.
-     *
-     * Those two factors are THIS CALL's own before/after on the same ids. They are not the ones the site quotes
-     * (543× and 63×) — those compare the optimized encoding against the best *fixed* representation at its floor,
-     * a different baseline that happens to land near 63× on the run shape too. `pnpm bench:encoding` prints both
-     * columns; don't carry a figure between them without checking which denominator it had.
-     *
-     * Called by the engine only when writing an immutable cold generation — see {@link CodecBitmap.optimize} for
-     * why the per-operation warm path deliberately does not.
-     */
-    optimize(): void;
-    /**
-     * Largest value, or `undefined` when empty. O(1) — roaring reads it off the container index, so the engine's
-     * per-chunk range assertion costs one call per chunk rather than a walk per id.
-     */
-    maximum(): number | undefined;
-    add(value: number): void;
-    addMany(values: Iterable<number>): void;
-    remove(value: number): void;
-    removeMany(values: Iterable<number>): void;
-    has(value: number): boolean;
-    get size(): number;
-    get isEmpty(): boolean;
-    clone(): SafeBitmap;
-    /** In-place union: `this = this ∪ other`. */
-    orInPlace(other: CodecBitmap): void;
-    /** In-place difference: `this = this \ other`. */
-    andNotInPlace(other: CodecBitmap): void;
-    /** In-place intersection: `this = this ∩ other`. */
-    andInPlace(other: CodecBitmap): void;
-    /** Ascending iterator over the set values. */
-    [Symbol.iterator](): IterableIterator<number>;
-    toArray(): number[];
-}
-/**
- * The roaring {@link CodecInterface} — the flagship codec, delegating to {@link SafeBitmap}'s statics. This is
- * the default the `CloudRoaring` facade injects into the engine; `core/` itself never hard-references it once a
- * caller supplies a codec. Moves to `@cloudbitmaps/roaring` when the package split lands.
- */
-declare const roaringCodec: CodecInterface;
-
-/**
- * CloudRoaring — distributed, cloud-native Roaring Bitmaps.
- *
- * The `CloudRoaring` class is the read/write engine over the tiered seams. You wire storage **once**, as a
- * single config object: a Cold driver (`cold`), a Warm driver (`warm`), and optionally a `registry` (the
- * authoritative generation pointer — needed to read encrypted segments and to resolve generations without a
- * cold `list`-scan) and a `keystore` (encryption-at-rest / crypto-shred). Pass a **raw** {@link IColdDriver}
- * as `cold` (e.g. `S3ColdDriver`, `LocalFsColdDriver`, `MemoryColdDriver`) and the store assembles the `.crbm`
- * cold source ({@link CrbmColdChunkSource}) for you — so each driver is named exactly once. Or pass an
- * already-built {@link ColdChunkSource} to control advanced reader options yourself.
+ * 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.
  *
- * In-process lifecycle helpers — `compact`, `eraseSubject`, `subjectReport` — reuse the store's own drivers, so
- * you never re-pass them (they need the store built with a raw cold driver + registry). Out-of-process cold
- * writers (the compaction daemon, the seed/bulk-load CLI, `destroySegment`/`eraseNamespace`) wire their own deps
- * against the same drivers — they run in separate processes.
+ * **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.
  *
- * **You do not need any of them to start.** Construct a store and call `add`/`addMany`/`has`/`remove` — a segment
- * with no Cold generation at all is fully functional, because a read merges `(cold ∪ warm.adds) \ warm.removes`
- * and an absent Cold tier just makes that merge trivial. `bulkLoadCrbmGeneration` is an **import** path for data
- * you already have elsewhere, not an initialization step, and compaction is a **cost** optimization, never a
- * correctness requirement. See the README and the getting-started guide.
+ * In-process lifecycle helpers — `eraseSubject`, `subjectReport`, `dropSegment`, `retireExpired`,
+ * `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 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 `cold` and `warm` are required** — the minimal call is
- * `new CloudRoaring({ cold, warm })`. Add a `registry` to unlock eject / compaction / encryption and to skip the
- * cold list-scan (recommended for anything beyond a quick look). Everything else is **optional tuning with
- * sensible defaults** — resilience/retries are already on, the hot cache is bounded, metrics are a no-op — so
- * reach for them only when you need to.
+ * Wiring for a {@link CloudRoaring} store. **Only `storage` is required** — the minimal call is
+ * `new CloudRoaring({ storage: backend })`. A backend resolves generations with one strong read, reads
+ * encrypted segments, and unlocks every lifecycle helper; the narrower shapes `storage` also accepts are
+ * described on the option itself. Everything else is **optional
+ * tuning with sensible defaults** — resilience/retries are already on, the cache is bounded, metrics are a
+ * no-op — so reach for them only when you need to.
  */
-interface CloudRoaringOptions {
+export interface CloudRoaringOptions {
     /**
-     * Cold tier. Pass a **raw** {@link IColdDriver} (`S3ColdDriver`, `LocalFsColdDriver`, `MemoryColdDriver`, …)
-     * and the store wraps it in a {@link CrbmColdChunkSource} using `registry`/`keystore` below — the common case,
-     * so you wire each driver **once**. Or pass an already-built {@link ColdChunkSource} (`MemoryColdChunkSource`,
-     * or a `CrbmColdChunkSource` you configured with advanced reader options) to use as-is.
+     * Where the store keeps everything. **The only required option.**
+     *
+     * Pass a {@link StorageBackend} — `S3Storage`, `GcsStorage`, `AzureBlobStorage`, `LocalFsStorage`,
+     * `MemoryStorage` — and you are done: it carries both halves, the generations and the `currentGen` pointer,
+     * configured from one bucket and one prefix. That is the whole wiring, and it is the shape to reach for.
+     *
+     * **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. `destroySegment` and `eraseNamespace` take `backend.registry`; the store takes `backend`.
+     *
+     * Two lower-level shapes stay accepted for wiring the facade does not cover:
+     *
+     * - a **raw {@link IStorageDriver}**, which the store wraps in a {@link CrbmStorageChunkSource}. There is no
+     *   registry in this shape, so the store resolves generations by list-scanning storage: **cleartext and
+     *   read-only**. Encrypted segments, the `*Into` verbs and every lifecycle helper need a backend.
+     * - an already-built {@link StorageChunkSource}, used as-is, for advanced reader options.
      */
-    readonly cold: IColdDriver | ColdChunkSource;
-    /** Warm tier: the per-chunk delta store under OCC (`DynamoDbWarmDriver`, `LocalFsWarmDriver`, `MemoryWarmDriver`). */
-    readonly warm: IWarmDriver;
+    readonly storage: StorageBackend | IStorageDriver | StorageChunkSource;
     /**
-     * Authoritative registry — the per-segment `currentGen` pointer + wrapped-DEK holder. Applies when `cold` is a
-     * **raw driver**: it (a) resolves the current generation with one strong read instead of a cold `list`-scan,
-     * and (b) lets the store read **encrypted** segments (that's where wrapped DEKs live). Optional — a
-     * registry-less store reads the highest generation by list-scanning Cold (cleartext only). When you pass a
-     * pre-built `ColdChunkSource`, that source resolves its own generations, so a top-level `registry` is inert
-     * there and rejected as a wiring mistake — configure it on the source instead.
+     * Memory and staleness bounds for the read path. Every key is optional and every default is already sane;
+     * reach for these when a deployment's shape differs from "a long-running server with room to breathe".
      */
-    readonly registry?: IRegistryDriver;
+    readonly cache?: CacheOptions;
     /**
-     * Keystore for encryption-at-rest / crypto-shred (Phase 4e). Required to read encrypted segments; needs a
-     * `registry` (that's where wrapped DEKs are stored). Applied only when `cold` is a raw driver — when you pass a
-     * pre-built {@link ColdChunkSource}, configure the keystore on that source instead.
+     * Encryption at rest. Omit it entirely for a cleartext store — encryption is opt-in, and a segment's
+     * encryption is decided at its **first** generation.
      */
-    readonly keystore?: IKeystore;
+    readonly encryption?: EncryptionOptions;
     /**
-     * Refuse to read a **cleartext** segment — a guard against silently reading data that should be encrypted.
-     * Needs a `registry`; applied only when `cold` is a raw driver. Off by default (encryption is opt-in).
+     * 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 requireEncryption?: boolean;
-    /** Injected for deterministic tests; defaults to a system clock. */
-    readonly clock?: Clock;
-    /** Injected for deterministic tests; defaults to `Math.random`-backed. Drives backoff jitter. */
-    readonly rng?: Rng;
-    /** HOT cache ceiling (decoded Cold chunks). */
-    readonly cacheMaxChunks?: number;
-    /** Optional TTL on cached chunks (ms). */
-    readonly cacheTtlMs?: number;
+    readonly retry?: RetryOptions | false;
     /**
-     * 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 compaction commits a new generation (gap #4). Applies
-     * only when `cold` is a raw driver **and** a `registry` is wired (the cheap `currentGen` read the refresh
-     * needs; a registry-less store pins per source lifetime). Lazy — no timer; ≤ one registry read per segment per
-     * window, opening a new reader only when the generation actually advanced.
+     * Observability sink: receives typed metric events (storage GET/bytes, cache hit/miss, retries, intersection
+     * efficiency, op latency). Defaults to a no-op — emission is skipped entirely when unused (near-zero
+     * overhead). Any exception the sink throws is swallowed — metrics can never break a read.
      */
-    readonly coldGenTtlMs?: number;
-    /**
-     * Ceiling on how many segments' `.crbm` readers (each holding a parsed index) the store keeps open at once
-     * (default 1024) — the steady-state memory bound for a long-running server that reads across many segments
-     * (gap #1). Past it the least-recently-used segment's reader is evicted; re-opening it later is one cheap tail
-     * GET. Applies only when `cold` is a raw driver (a pre-built `ColdChunkSource` manages its own reader cache).
-     */
-    readonly coldReaderCacheMax?: number;
-    /**
-     * Aggregate byte ceiling on the parsed `.crbm` indices the open readers hold (default 64 MiB) — the byte
-     * half of the gap #1 memory bound, complementing the `coldReaderCacheMax` *count* bound. A wide/dense
-     * segment's parsed index can be several MB, so a count-only bound could let the open readers pin ~GBs and
-     * blow a small heap (e.g. a 128 MB Lambda); this evicts the least-recently-used reader once the summed index
-     * footprint would exceed the ceiling — whichever of the count/byte bounds binds first. Lower it for
-     * memory-tight deployments that read across wide segments. Applies only when `cold` is a raw driver.
-     */
-    readonly coldReaderCacheMaxBytes?: number;
-    /**
-     * Resilience: by default every warm/cold call retries **transient** faults (throttling, 5xx, dropped
-     * connections) with bounded, jittered exponential backoff (see {@link DEFAULT_RETRY_POLICY}), and OCC
-     * conflicts back off between retries. Pass a {@link RetryPolicy} to tune it, or `false` to disable the
-     * transient-retry wrappers entirely (e.g. if your injected client already retries). Deterministic errors
-     * (`ValidationError`/`IntegrityError`/`WriteConflictError`/…) are never retried by this layer.
-     */
-    readonly retry?: RetryPolicy | false;
-    /** Backoff schedule between OCC conflict retries; defaults to a small, tight one. */
-    readonly occBackoff?: RetryPolicy;
-    /** Observability: called before each transient-retry backoff wait. */
-    readonly onRetry?: (info: {
-        attempt: number;
-        delayMs: number;
-        err: unknown;
-    }) => void;
+    readonly metrics?: IMetricsSink;
     /**
-     * Observability sink (Phase 5a): receives typed metric events (cold GET/bytes, warm read/write, cache
-     * hit/miss, retries, intersection efficiency, op latency). Defaults to a no-op — emission is skipped
-     * entirely when unused (near-zero overhead). Any exception the sink throws is swallowed — metrics can
-     * never break a read/write.
+     * 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} (`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
+     * separately size-capped, so bounding requests transitively bounds bytes.
      */
-    readonly metrics?: IMetricsSink;
+    readonly budget?: BudgetOption;
     /**
-     * Warm read consistency for the READ paths (`has`/`count`/`iterate`/`intersect`). Default `'strong'`
-     * (read-your-writes). `'eventual'` trades read-after-write for **~½ the DynamoDB read cost** (a strong read
-     * bills 2× RCU) — a good fit for read-heavy, staleness-tolerant workloads (mirrors the cold tier's bounded
-     * eventual reads). The compaction/OCC write path is always strongly consistent regardless. No effect on the
-     * in-memory/LocalFs drivers (always strong). (Audit gap #9.)
+     * Determinism seams, for tests and replayable jobs. Production stores leave this out and get a system clock
+     * and a `Math.random`-backed source.
      */
-    readonly warmReadConsistency?: 'strong' | 'eventual';
+    readonly seams?: SeamOptions;
+}
+/** {@link CloudRoaringOptions.cache} — the memory and staleness bounds. */
+export interface CacheOptions {
+    /** Ceiling on decoded Storage chunks held in RAM (default 1024). */
+    readonly maxChunks?: number;
+    /** Optional TTL on cached chunks (ms). Omit to keep a chunk until it is evicted by the count bound. */
+    readonly ttlMs?: number;
     /**
-     * Max Warm chunk writes in flight per `addMany`/`removeMany` (the bounded flusher). Default **4**
-     * (`DEFAULT_WRITE_CONCURRENCY`); set it to `1` for strictly serial writes.
+     * 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. Lazy — no
+     * timer; ≤ one registry read per segment per window, opening a new reader only when the generation actually
+     * advanced.
      *
-     * Distinct chunks are independent OCC rows, so fanning them out cannot make them conflict with each other.
-     * The bound exists for the *backend*: a provisioned-capacity store answers a burst by throttling, and 4 stays
-     * comfortably inside what the transient-retry path absorbs (measured 8x below the first observed failure).
-     * Raise it if your backend is provisioned for the fan-out — on-demand DynamoDB, or a connection pool sized to
-     * match. A pool *smaller* than this needs no action: `pg` and `mysql2` both queue rather than reject, so the
-     * flusher simply degrades toward serial.
+     * **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.
      *
-     * As before, a mid-flush failure can leave a **partial result**; `addMany`/`removeMany` are not atomic. What
-     * concurrency changes is only how much of the batch may already have landed when the first error surfaces.
+     * `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 writeConcurrency?: number;
+    readonly genTtlMs?: number;
     /**
-     * Hard ceiling on the warm-delta bytes one segment scan may hold resident. Default **64 MiB**.
-     *
-     * **A memory bound, deliberately separate from `budget`, and still enforced when `budget: false`.** The
-     * budget limits *cost* (billable requests); this limits *memory*. They are different axes, and treating the
-     * budget as a memory control is what allowed a segment with thousands of warm chunks to materialise ~12 MB
-     * before a `maxRequests: 2` budget could refuse it. It is also the only bound available to `intersect`,
-     * whose budget is `common keys × operands` — a product a single wide operand can legitimately exceed in row
-     * count while remaining entirely within contract.
+     * Ceiling on how many segments' `.crbm` readers (each holding a parsed index) the store keeps open at once
+     * (default 1024) — the steady-state memory bound for a long-running server that reads across many segments.
+     * Past it the least-recently-used segment's reader is evicted; re-opening it later is one cheap tail GET.
+     * Applies whenever the store builds its own read path — a backend or a bare `IStorageDriver`. A pre-built
+     * `StorageChunkSource` manages its own reader cache.
+     */
+    readonly readerMax?: number;
+    /**
+     * Aggregate byte ceiling on the parsed `.crbm` indices the open readers hold (default 64 MiB) — the byte half
+     * of the memory bound, complementing the {@link CacheOptions.readerMax} *count* bound. A wide/dense segment's
+     * parsed index can be several MB, so a count-only bound could let the open readers pin ~GBs and blow a small
+     * heap (e.g. a 128 MB Lambda); this evicts the least-recently-used reader once the summed index footprint
+     * would exceed the ceiling — whichever of the count/byte bounds binds first. Lower it for memory-tight
+     * deployments that read across wide segments. Applies whenever the store builds its own read path.
+     */
+    readonly readerMaxBytes?: number;
+}
+/** {@link CloudRoaringOptions.encryption} — encryption at rest and crypto-shred. */
+export interface EncryptionOptions {
+    /**
+     * The keystore that mints and unwraps per-segment DEKs. Needs a **backend**: the wrapped DEK lives in the
+     * registry, so there is nowhere to put it on a store wired with a bare driver, and that is refused at
+     * construction rather than at the first read.
+     */
+    readonly keystore?: IKeystore;
+    /**
+     * Refuse to touch a **cleartext** segment — a guard against silently reading, or writing, data that should be
+     * encrypted. Needs a backend, for the same reason as {@link EncryptionOptions.keystore}. Off by default.
      *
-     * Raise it for genuinely large segments; it exists to keep a modest container alive, not to second-guess you.
+     * It refuses **writes** as well as reads, which is easy to miss: the `*Into` verbs and `eraseSubject` both
+     * carry it into their write path, so on a cleartext segment a materialisation throws and an erasure records
+     * `note: 'error: requireEncryption: …'` in its ledger rather than erasing. And since a segment's encryption is
+     * decided at its **first** generation, this cannot be switched on for a segment that already has one — load
+     * into a new encrypted segment and drop the old one.
      */
-    readonly maxWarmScanBytes?: number;
+    readonly required?: boolean;
+}
+/**
+ * {@link CloudRoaringOptions.retry} — a partial {@link RetryPolicy} plus the retry callback.
+ *
+ * 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> {
     /**
-     * Per-op **denial-of-wallet** budget (Decision #3 / invariant T3): the max backend requests a
-     * single `count`/`iterate`/`intersect`/`subjectReport`/`eraseSubject` may fan out into before it's refused
-     * with {@link BudgetExceededError} — so one runaway op can't drive unbounded RCU/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 `intersect`/`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 separately
-     * size-capped, so bounding requests transitively bounds bytes.
+     * 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 budget?: BudgetOption;
+    readonly onRetry?: (info: {
+        attempt: number;
+        delayMs: number;
+        err: unknown;
+    }) => void;
+}
+/** {@link CloudRoaringOptions.seams} — injected for deterministic tests and replayable jobs. */
+export interface SeamOptions {
+    /** Defaults to a system clock. */
+    readonly clock?: Clock;
+    /** Defaults to `Math.random`-backed. Drives transient-retry jitter. */
+    readonly rng?: Rng;
 }
-interface SegmentOptions {
+export interface SegmentOptions {
     readonly namespace?: string;
+    /**
+     * **When this segment stops being readable** — an absolute epoch-ms instant, declared where the segment is
+     * named instead of in a separate `setRetention` call.
+     *
+     * Every read through this handle checks it first: past the deadline, `has` is `false`, `count` is `0`, and
+     * `iterate` yields nothing — **one integer compare against the injected clock, no I/O, on every backend**.
+     * That is Redis's lazy expiry, and it is what makes an expiry *correct* rather than *eventually correct*: a
+     * deployment whose sweep is late — or which has no sweep at all, like a Lambda-only reader — still stops
+     * serving the data on time.
+     *
+     * **Two things this does NOT do, both deliberate:**
+     *
+     * - It does not reclaim the bytes. That is {@link CloudRoaring.retireExpired}, and until it runs the data is
+     *   still stored and still billed. `count()` reporting 0 while objects exist is the expected state in that
+     *   window, not a bug.
+     * - It does not apply to *other* handles. The deadline lives on this handle; a second handle opened without
+     *   the option reads the segment normally. Record the policy with {@link CloudRoaring.setRetention} to make
+     *   it durable, fleet-visible, and reclaimable.
+     *
+     * Must be **milliseconds** since the epoch and at or after {@link MIN_EXPIRES_AT_MS} — a seconds value would
+     * land in 1970 and make the segment permanently unreadable, so it is refused rather than honoured.
+     */
+    readonly expiresAt?: number;
 }
 /** A segment reference in a subject report / erasure ledger. */
-interface SubjectSegmentRef {
+export interface SubjectSegmentRef {
     readonly segment: string;
     readonly namespace?: string;
 }
 /** Result of {@link CloudRoaring.subjectReport} — the segments an id is a member of (over registered segments). */
-interface SubjectReport {
+export interface SubjectReport {
     readonly id: number;
     /** The registered segments the id is currently a member of. */
     readonly segments: SubjectSegmentRef[];
@@ -279,65 +230,187 @@ interface SubjectReport {
     readonly scannedSegments: number;
 }
 /** One segment's entry in an erasure ledger (see {@link EraseSubjectResult}). */
-interface SubjectErasureEntry {
+export interface SubjectErasureEntry {
     readonly segment: string;
     readonly namespace?: string;
-    /** The id was present and a logical `remove` tombstone was written. */
-    readonly removed: boolean;
-    /**
-     * True iff *this call* committed a new generation with the segment's tombstones applied — the bit is
-     * physically gone from Cold (assuming no concurrent re-add of the id; see {@link CloudRoaring.eraseSubject}).
-     * `false` is **conservative**: the purge may have been deferred (`note:'leased-by-other'`) or already done by
-     * a concurrent daemon (`note:'clean'`); the logical removal holds regardless.
-     */
-    readonly physicallyPurged: boolean;
-    /** The generation that retired the bit (present when `physicallyPurged`). */
-    readonly toGen?: number;
-    /** Why physical purge wasn't committed by this call (compaction's `reason`, e.g. `'leased-by-other'`, `'clean'`). */
+    /**
+     * 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 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'` — 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, 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.
+     */
     readonly note?: string;
 }
 /**
  * The erasure ledger returned by {@link CloudRoaring.eraseSubject} — your proof-of-deletion artifact. It is a
  * return value only (no library-side persistence): persist it / route it to your audit sink as you see fit.
  */
-interface EraseSubjectResult {
+export interface EraseSubjectResult {
     readonly id: number;
-    /** Per-segment records for the segments the id was erased from (absent segments are not listed). */
+    /** Per-segment records for the segments the id was found in (absent segments are not listed). */
     readonly erasedFrom: SubjectErasureEntry[];
     /** How many registered segments were scanned. */
     readonly scannedSegments: number;
 }
-declare class CloudRoaring {
+/**
+ * Why a materialisation did not become current.
+ *
+ * {@link LoadRefusal} minus `'superseded'`: that one is a lost race, and the `*Into` verbs throw
+ * {@link WriteConflictError} for it rather than reporting it. Narrowing the type rather than saying so only
+ * in prose means the compiler enforces it, and a caller's exhaustive `switch` has no dead branch.
+ */
+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: 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.
+     *
+     * `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. */
+    readonly reason?: MaterializeRefusal;
+    /** Ids in the generation. */
+    readonly cardinality: number;
+    /**
+     * What the destination held when the guard judged it — `null` when it had no current generation, **or when
+     * no bound needed the read**. The read costs an object-header fetch, so it is taken only when a bound will
+     * use it: `allowEmpty: true` with no `guard.minRetained` skips it, and this is `null` even though `dest`
+     * was non-empty.
+     */
+    readonly cardinalityBefore: number | null;
+    /** Non-empty chunks in the generation. */
+    readonly chunkCount: number;
+    /** Bytes of the written object. */
+    readonly size: number;
+    /**
+     * The superseded generations collected after publishing. Empty when nothing was published — and **also
+     * empty on a successful publish** unless you passed `keep`, because a materialisation collects nothing by
+     * default. See {@link MaterializeOptions.keep}.
+     */
+    readonly collected: readonly number[];
+}
+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;
-    private readonly coldDriver;
-    private readonly warmDriver;
+    private readonly storageDriver;
     private readonly registry;
     private readonly keystore;
     private readonly requireEncryption;
     /** Resolved store-level per-op budget (null = disabled); the admin scans use it, with a per-op override. */
     private readonly budget;
+    /**
+     * Refuse any option key the store does not take, at the top level or inside a group, naming each one.
+     *
+     * 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 rejectUnknownOptions;
     constructor(options: CloudRoaringOptions);
     /**
-     * Build {@link CompactionDeps} from the store's own drivers, for the in-process lifecycle helpers
-     * ({@link compact} / {@link eraseSubject}). Requires the store to have been constructed with a **raw cold
-     * driver** (a pre-built `ColdChunkSource` has no underlying `IColdDriver` to compact through) and a `registry`
-     * (the authoritative `currentGen` pointer compaction swaps). Out-of-process callers use the `compactSegment`
-     * free function with explicit deps.
+     * 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.
      */
-    private compactionDeps;
-    /** Get a handle to a segment. Validates the name/namespace grammar (finding S2). */
+    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;
     /**
-     * **Subject access (GDPR Art. 15 / CCPA right-to-know): which segments is this id a member of?** (Phase 6b.)
+     * 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 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. 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.
+     *
+     * 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 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 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".
      *
-     * Enumerates the **registered** segments (via the store's own `registry`) and does a tier-merging `has(id)` on
-     * each — no drivers to re-pass. Complete only over registered segments (register your segments if you claim
-     * SAR support). There is deliberately **no `id → segments` reverse index** — that would tax every write 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).
+     * **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 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;
@@ -346,42 +419,68 @@ declare class CloudRoaring {
         budget?: BudgetOption;
     }): Promise<SubjectReport>;
     /**
-     * **Subject erasure (GDPR Art. 17): remove an id from every segment it's in, with a physical-deletion
-     * guarantee.** (Phase 6b.)
-     *
-     * For each **registered** segment the id is a member of: writes a logical `remove` tombstone (immediate) and
-     * then **force-compacts that segment now** — folding the tombstone into a fresh immutable generation so the
-     * bit is *physically* gone from Cold on return, even for an otherwise-idle/archival segment that organic
-     * compaction would never touch (the P13 fix). The returned per-segment record is your **erasure ledger** —
-     * persist it / route it to your audit sink as the proof of deletion; the physical-purge proof is
-     * compaction's own VERIFY step (a re-`has()` here would be unsound — a pinned cold source can still read the
-     * old generation; take a fresh generation view after erasing, exactly as with the compaction daemon).
-     *
-     * Uses the store's **own** drivers (raw cold + warm + registry), so the old integrator obligation to wire a
-     * matching `CompactionDeps` is gone — the `remove()` and the force-compaction provably run over the same tiers.
-     * Requires the store built with a **raw cold driver + registry** (throws {@link UnsupportedError} otherwise;
-     * a pre-built `ColdChunkSource` store has no `IColdDriver` to compact through — use the `compactSegment` free
-     * function there). **One contract remains** (an integrator obligation the library cannot check): **do not
-     * concurrently re-add the same id while erasing it.** A normal `add(id)` landing between the `remove` and the
-     * compaction clears the tombstone and folds the id back into the new generation
-     * (`effective = (cold ∪ adds) \ removes`); `physicallyPurged` attests only that compaction committed a
-     * generation with the tombstones applied at pin time — quiesce writes for the subject during erasure.
-     *
-     * **A `physicallyPurged:false` entry means the logical removal holds but the physical purge didn't run this
-     * call** — either a daemon held a live lease (`note:'leased-by-other'`; the daemon finishes it), or the
-     * force-compaction hit an isolated fault (`note:'error: …'`; per-segment faults are caught so one segment
-     * can't discard the whole ledger). `physicallyPurged:false` is **conservative** (a concurrent daemon may
-     * already have purged the bit — `'clean'`). **Recovery:** follow up any `physicallyPurged:false` entry with
-     * `store.compact(ref)` (or let the daemon do it) — **re-running `eraseSubject` will NOT re-purge it**, because
-     * `has()` now reads false (the tombstone) so the segment is skipped as a non-member. The physical-purge proof
-     * is compaction's own VERIFY step (a re-`has()` here would be unsound: a pinned cold source can still read the
-     * old generation — take a fresh generation view after erasing, as with the daemon). Admin-only path;
-     * `O(registered segments)`, no hot-path cost. Per-subject crypto-shred is infeasible (a subject's bit is
+     * **Subject erasure (GDPR Art. 17): remove an id from every segment it's in, with the bit physically gone
+     * from the bucket on return.**
+     *
+     * 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. 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; 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** — 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: 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 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, 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. 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 the `destroySegment`/`eraseNamespace` free functions.
+     * is `dropSegment` / the `destroySegment`/`eraseNamespace` free functions.
      */
-    eraseSubject(id: number, options: {
-        owner: string;
+    eraseSubject(id: number, options?: {
         namespace?: string;
         allNamespaces?: boolean;
         audit?: IAuditSink;
@@ -389,20 +488,156 @@ declare class CloudRoaring {
         budget?: BudgetOption;
     }): Promise<EraseSubjectResult>;
     /**
-     * **Compact one segment now**, in-process, using the store's own drivers — a convenience over the
-     * {@link compactSegment} free function. Merges `(cold ∪ adds) \ removes` into a fresh immutable generation,
-     * swaps `currentGen`, then version-fenced-purges the archived Warm rows. A no-op (`compacted:false`) when the
-     * segment has no dirty rows or a daemon holds a live lease — never throws on the normal contention/lease paths.
-     * Requires the store built with a **raw cold driver + registry** (throws {@link UnsupportedError} otherwise);
-     * like the daemon, it uses the raw drivers directly (a transient fault surfaces to you rather than retrying
-     * under the hood). **Not for the request/hot path** — it reads and rewrites a whole Cold generation (streaming,
-     * constant-memory, but full-segment I/O). Use the `compact-segments` daemon (`runCompactionCycle`) for routine
-     * background compaction; reach for `store.compact()` for occasional/manual one-shots — a maintenance endpoint,
-     * a small daemon-less deployment, or right after a targeted `remove`.
+     * Every generation still in the bucket for this segment, ascending, with the current one marked.
+     *
+     * 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 registry read and one listing; it does not open the objects.
+     *
+     * Needs a backend.
+     */
+    generations(ref: SegmentRef): Promise<GenerationEntry[]>;
+    /**
+     * Whether a read of this segment would find anything — the "do I already have this?" question, as one
+     * registry point read.
+     *
+     * There is no `create` in this library: {@link CloudRoaring.segment} is a validated address and does no I/O,
+     * so naming a segment can never collide with an existing one. A segment starts existing when something is
+     * first loaded into it, and this is how you ask whether that has happened.
+     *
+     * **Not the same as `count() > 0`.** A segment loaded with no ids exists and counts zero. Distinguishing
+     * "never loaded" from "loaded, and genuinely empty" is the thing `count()` cannot do and the reason this
+     * exists. It is `false` for a segment whose row was minted ahead of its first load (by `setRetention`) and
+     * for a `destroyed` tombstone, because a read answers empty in both cases.
+     *
+     * Two states answer `true` where a read still gives you nothing: a torn restore (a live pointer whose object
+     * was deleted) makes reads *throw* rather than answer empty — `checkConsistency` is the call for that — and
+     * 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 storage backend.
+     *
+     * ```ts
+     * if (!(await store.exists({ segment: 'users' }))) {
+     *   await store.load({ segment: 'users' }, idsFromUpstream);
+     * }
+     * ```
+     */
+    exists(ref: SegmentRef): Promise<boolean>;
+    /**
+     * Every segment the registry knows about, streamed — optionally scoped to one namespace.
+     *
+     * The registry is already the list of your segments, which is why you should not keep a second one beside it:
+     * a hand-maintained list is a source of truth that drifts from this one the first time a load fails halfway.
+     *
+     * **An admin/discovery call, not a request-path one.** This is the registry's own enumeration — a paged
+     * LIST over the `registry/` prefix — so its cost grows with the size of the fleet rather than with what you
+     * are looking for.
+     *
+     * 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. 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 storage backend.
+     *
+     * ```ts
+     * for await (const s of store.segments({ namespace: 'active-daily' })) {
+     *   console.log(s.segment, s.currentGen, s.status);
+     * }
+     * ```
+     */
+    segments(options?: {
+        namespace?: string;
+    }): AsyncIterable<SegmentInfo>;
+    /**
+     * Move this segment's pointer **back** to a generation still in the bucket — the one write in the library that
+     * is not forward-only.
+     *
+     * Forward-only is right for a writer: a load whose ids came from upstream loses nothing by being out-raced, and
+     * letting it regress would let a slow loader silently undo a fast one. It is wrong for an operator who has
+     * looked at the segment, decided the current generation is wrong, and knows which one they want. So this is
+     * reachable only by asking for it by name — no sweep, retry or reconciliation calls it — and it is audited
+     * (`segment.rollback`), because every other pointer move can be reconstructed from "a load happened" and this
+     * one cannot.
+     *
+     * It refuses rather than guesses: a generation not in the bucket (collected, or never written) throws
+     * `NotFoundError` naming what *is* available, and a crypto-shredded segment throws
+     * {@link ValidationError} because every generation of it is unreadable. Rolling to the generation already
+     * 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. 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.
+     *
+     * The whole write path in one call: take the next generation number, write the object, check the result is
+     * plausible, move the pointer, collect what the move superseded. Composed by hand those are four functions and
+     * the one that gets left out is the last, so segments quietly accumulate superseded generations nobody pays
+     * attention to and everybody pays for.
+     *
+     * ```ts
+     * 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}`);
+     * ```
+     *
+     * **A load REPLACES.** Whatever the stream contains is what the segment contains afterwards, so an upstream
+     * query that returns fewer rows than usual is a shrink nobody asked for and an empty one is a wipe — both
+     * reported as a successful write, because at the storage layer they are one. That is what `guard` and the
+     * default empty refusal are for, and why they run **between** the write and the publish: the only moment where
+     * the new content is known and the old one is still authoritative.
+     *
+     * **Branch on `published`.** A refusal is a normal outcome, not an exception — `published: false` with a
+     * `reason`, in the same shape as a success — so a discarded result is a load that silently did nothing, and
+     * with the empty guard on by default this verb refuses more readily than any other. Note the sibling `*Into`
+     * verbs *throw* on the same superseded condition rather than reporting it; this one follows
+     * `eraseIdFromSegment` instead, because three of its four refusals are expected guard outcomes rather than
+     * faults.
+     *
+     * `'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`.
+     *
+     * 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).
      */
-    compact(ref: SegmentRef, options: CompactionOptions): Promise<CompactionResult>;
+    load(ref: SegmentRef, ids: Iterable<number> | AsyncIterable<number>, options?: LoadOptions): Promise<LoadResult>;
     /**
-     * **Dispose of a segment — tombstone it, delete its Warm rows, delete its Cold objects.** Irreversible.
+     * **Dispose of a segment — tombstone it, then delete its storage objects.** Irreversible.
      *
      * The operation a rolling window needs: `destroySegment` crypto-shreds (bytes unreadable everywhere including
      * backups, but still sitting in your bucket and still billed, and it requires encryption), while this one
@@ -414,7 +649,8 @@ declare class CloudRoaring {
      *
      * ```ts
      * for (const day of expiredDays) {
-     *   // A colon is NOT legal in a name — the family goes in the namespace, the date in the segment.
+     *   // The family in the namespace, the date in the segment — `registry.list(namespace)` then enumerates
+     *   // exactly this family's buckets, which a flat `active:2026-08-01` name cannot do without string-matching.
      *   const ref = { namespace: 'active-daily', segment: day };
      *   await store.dropSegment(ref, { confirmSegment: ref.segment });
      * }
@@ -424,24 +660,23 @@ declare class CloudRoaring {
      * `{ dropped: false, reason: 'absent' }`, not a throw, so a retention loop with that mistake deletes nothing
      * forever and quietly. Branch on `dropped`, and treat `reason: 'absent'` as the alert.
      *
-     * **Works on an accumulator too.** A segment you created by writing to it — never bulk-loaded, never compacted,
-     * so it has no registry row and no Cold objects — is retired by deleting its Warm rows alone. That reports
-     * `{ dropped: true, reason: 'warm-only' }`: there is no tombstone to write, and deliberately none is written,
-     * because a `destroyed` row per retired daily bucket would be registry litter. The data really is gone.
-     *
      * **Inspect `generationsRemaining`.** Empty is the normal outcome; non-empty means the storage was NOT fully
-     * reclaimed and the drop should be re-run. A compaction that was already in flight when the tombstone landed
-     * still finishes staging one more object, so a single sweep can miss it — this call re-sweeps and then reports
-     * whatever it still could not remove rather than returning a result that looks like a clean drop.
+     * reclaimed and the drop should be re-run. A load that was already writing when the tombstone landed still
+     * finishes its object, so a single sweep can miss it — this call re-sweeps and then reports whatever it still
+     * could not remove rather than returning a result that looks like a clean drop.
      *
-     * Reads become empty within `coldGenTtlMs` (default 2 s), not instantly: a store that had already read this
-     * segment may answer from its cached generation + hot chunks until that window lapses. A reader that never
-     * touched it sees empty at once. **That bound needs a clock and `coldGenTtlMs > 0`** — a store built without a
-     * clock, or with `coldGenTtlMs: 0` ("pin forever"), holds its resolved snapshot for its own lifetime and can
-     * keep answering `true` for a dropped segment indefinitely; restart it.
+     * 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, 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 **raw cold driver + a registry** (throws {@link UnsupportedError} otherwise),
-     * because it has to enumerate and delete generations — a pre-built `ColdChunkSource` only reads.
+     * 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.
      */
     dropSegment(ref: SegmentRef, options: {
         confirmSegment: string;
@@ -455,9 +690,9 @@ declare class CloudRoaring {
      * no background thread (it has to work identically in a Lambda, an edge isolate and a long-lived server).
      *
      * `expiresAt` is an **absolute epoch-ms you compute**, not a duration the library derives. A relative TTL would
-     * have to be anchored to something the library knows — `updatedAt`, or the current generation — and compaction
+     * have to be anchored to something the library knows — `updatedAt`, or the current generation — and every load
      * rewrites both, so "expire 30 days after the last write" would keep a busy daily bucket alive forever
-     * precisely because the daemon is working.
+     * precisely because it is being reloaded.
      *
      * ```ts
      * const DAY = 86_400_000;
@@ -465,15 +700,14 @@ declare class CloudRoaring {
      * await store.setRetention(ref, { expiresAt: Date.now() + 30 * DAY });
      * ```
      *
-     * **Works on an accumulator**, which is the whole point: a segment you created by writing to it has no
-     * registry row, so it is invisible to `registry.list()` and therefore to every fleet-wide operation, including
-     * the sweep. This call mints the row (`createdRow: true` in the result) with **no Cold generation**, so it
-     * becomes enumerable while every read still resolves exactly as before.
+     * **Works before the first load**: a segment with no registry row yet gets one (`createdRow: true` in the
+     * result) with **no Storage generation**, so the policy is recorded ahead of the data and the segment is already
+     * enumerable by the sweep; the first load then publishes onto that row.
      *
      * 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>;
     /**
@@ -493,17 +727,17 @@ declare class CloudRoaring {
      * **Run the retention sweep: retire every segment whose `expiresAt` has passed.** This is the call that acts on
      * the policies `setRetention` records — and it is a **call, not a daemon**. Nothing schedules it; you run it from
      * whatever heartbeat your deployment already has (an EventBridge rule, a Kubernetes CronJob, a queue consumer,
-     * your compaction worker's loop). A library that started a timer would behave differently in a Lambda, an edge
+     * the job that runs your loads). A library that started a timer would behave differently in a Lambda, an edge
      * isolate and a long-lived server, which is worse than not having one.
      *
-     * Each retirement goes through `dropSegment`, so the Warm → registry → Cold ordering, the re-sweep for a
-     * generation staged by an in-flight compaction, and the `generationsRemaining` report all come from one
-     * implementation rather than two.
+     * Each retirement goes through `dropSegment`, so the registry → Storage ordering, the re-sweep for an object a
+     * load was still writing, and the `generationsRemaining` report all come from one implementation rather than
+     * two.
      *
      * ```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) {
@@ -519,76 +753,162 @@ declare class CloudRoaring {
      * sweep would leave the caller unable to say which segments were retired, having already retired some. (A bad
      * argument does throw, and so does a fleet larger than `maxScanSegments`.) `limited: true` means the per-cycle
      * `limit` (default 100) cut the pass short and more are eligible. That cap is charged on **attempts**, not
-     * successes, which is what makes it a real bound: `dropSegment` deletes Warm and writes the tombstone before
-     * sweeping Cold, so a fault in the Cold phase is a segment that is already retired. Retirements are sequential
-     * (~8 round trips each), so `limit` is a wall-clock knob too, and `retired` counts deletions only — a dry run
-     * reports `wouldRetire` instead, so a dashboard summing `retired` can never show a phantom deletion.
+     * successes, which is what makes it a real bound: `dropSegment` writes the tombstone before sweeping Storage, so a
+     * fault in the Storage phase is a segment that is already retired. Retirements are sequential, so `limit` is a
+     * wall-clock knob too, and `retired` counts deletions only — a dry run reports `wouldRetire` instead, so a
+     * dashboard summing `retired` can never show a phantom deletion.
      *
      * It also **deletes the tombstone rows its own past retirements left**, after `tombstoneGraceMs` (default 24 h)
-     * and only once that segment's Warm rows and Cold generations are provably gone — collecting a straggler
-     * generation itself 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.
+     * and only once that segment's Storage generations are provably gone — collecting a straggler generation itself
+     * 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. 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 **raw cold driver + a registry** (throws {@link UnsupportedError} otherwise),
-     * because retiring a segment deletes its Cold objects. `now` defaults to the store's clock.
+     * 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.
      */
     retireExpired(options?: Omit<RetireExpiredOptions, 'now'> & {
         now?: number;
     }): Promise<RetireExpiredResult>;
+    /**
+     * **Forget everything this store has cached about a segment.** Use it after destroying or retiring a segment
+     * through a path this store did not perform itself.
+     *
+     * A store keeps two layers of derived state — a resolved snapshot per segment (an open `.crbm` reader, plus
+     * the DEK it unwrapped) and decoded chunks keyed by generation. Both are built for one event: **a publish
+     * 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 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 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 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, { registry: backend.registry }, { confirmSegment: ref.segment });
+     * store.invalidate(ref);                       // this process
+     * await bus.publish('cloudbitmaps.invalidate', ref); // and every other one
+     * ```
+     */
+    invalidate(ref: SegmentRef): void;
+    /**
+     * 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**, 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, 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 and its memory bound**, under keys of its own for each pinned segment.
+     */
+    private engineWithPins;
+    /**
+     * The engine a combine should run on, given the handles involved.
+     *
+     * A pinned handle passed as an **operand** must still be read at its pin. Routing by "which handle the call
+     * was made on" reads it live instead — `snap.intersect([other])` honours the pin while
+     * `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 (audit gap #11).** After a restore/failover, verify every registered
-     * segment's `currentGen` actually has its `.crbm` present in Cold — 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 **raw cold driver + a registry** (throws {@link UnsupportedError} otherwise). `destroyed`
-     * (crypto-shredded) segments are skipped. Pair it with the DR runbook (docs/guide/disaster-recovery.md).
+     * **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,
+     * 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;
         concurrency?: number;
     }): Promise<ConsistencyReport>;
     /**
-     * **Export ("eject") every registered segment's current effective set** through the injected `sink`, using
-     * only public read APIs — so your data is readable **without CloudRoaring** (the exit path; see the README's
-     * "Your data stays yours"). `format: 'roaring'` (default) writes one **portable RoaringBitmap32** per segment
+     * **Export ("eject") every registered segment's current generation** through the injected `sink`, using only
+     * public read APIs — so your data is readable **without CloudRoaring** (the exit path; see the README's "Your
+     * data stays yours"). `format: 'roaring'` (default) writes one **portable RoaringBitmap32** per segment
      * (loadable by any roaring library); `'ndjson'` writes newline-delimited ids (zero-dependency, streaming).
      * Enumerates via the store's **own** registry (needs one — throws {@link UnsupportedError} otherwise) so the
-     * enumeration and the read path provably share one registry; an all-warm segment not yet in the registry can be
-     * named via `options.candidates`. Encrypted segments are decrypted transparently **iff** this store was wired
-     * with their keystore — the export is therefore **cleartext**; protect it. Crypto-shredded segments are skipped.
-     * A segment that can't be read is isolated into the manifest's `failed[]` (the run continues), so "a manifest
-     * exists" means the run finished — check `failed`. The `export-segments` CLI wraps this with a filesystem sink.
+     * enumeration and the read path provably share one registry. Encrypted segments are decrypted transparently
+     * **iff** this store was wired with their keystore — the export is therefore **cleartext**; protect it.
+     * Crypto-shredded segments are skipped. A segment that can't be read is isolated into the manifest's `failed[]`
+     * (the run continues), so "a manifest exists" means the run finished — check `failed`. The `export-segments`
+     * CLI wraps this with a filesystem sink.
      */
     exportSegments(sink: ExportSink, options?: ExportOptions): Promise<ExportManifest>;
     /**
-     * Planning cost estimate (Phase 5b) — pure, no instance/data needed: sizing, sales, what-if. For a real,
-     * grounded report from live segment sizes, use `store.segment(name).costReport()`. See {@link CostReport}.
+     * Planning cost estimate — pure, no instance/data needed: sizing, sales, what-if. For a real, grounded report
+     * from live segment sizes, use `store.segment(name).costReport()`. See {@link CostReport}.
      */
     static estimateCost(input: EstimateInput): CostReport;
 }
 /**
- * A handle bound to one segment — the read/write ops.
- *
- * **IDs must be integers in `[0, 2^32)`** (dense 32-bit). A non-integer / negative / out-of-range id
- * throws {@link ValidationError}.
+ * Options common to every chunk-aligned combine (`intersect` / `union` / `andNot`), and the `*Into` verbs.
  *
- * **`addMany`/`removeMany`/`intersectInto`/`unionInto`/`andNotInto` are not atomic across chunks**: ids are grouped by chunk and
- * applied one chunk at a time, so if a later chunk fails (e.g. {@link WriteConflictError} after retries)
- * earlier chunks are already applied. Within a single chunk the update is atomic.
+ * 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.
  */
-/** Options common to every chunk-aligned combine (`intersect` / `union` / `andNot`). */
-interface BaseCombineOptions {
-    /** Max chunk keys resolved concurrently — bounds the Cold footprint. A positive integer. */
+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). */
     readonly budget?: BudgetOption;
+    /**
+     * Allow an operand naming a segment that does not exist. Default `false`: a combine **refuses** one, because
+     * a misspelled or mis-namespaced operand is indistinguishable from a correct one in the result.
+     *
+     * Reading a segment that does not exist answers empty, and that is right — but passing one as an operand is
+     * different. A suppression list with nobody on it correctly suppresses nothing; one whose `namespace` you
+     * omitted *silently* suppresses nothing, and the result is not obviously-empty, it is the full audience and
+     * plausibly right. The failure mode is mailing the people who opted out.
+     *
+     * ```ts
+     * // `global-opt-out` lives in the `suppression` namespace. This addresses a DIFFERENT segment:
+     * audience.andNot([store.segment('global-opt-out')]);          // throws ValidationError
+     * audience.andNot([store.segment('global-opt-out', { namespace: 'suppression' })]); // correct
+     * ```
+     *
+     * Set `true` when you genuinely intend to combine against a name that may not exist yet. Checked only for an
+     * operand that resolved to no chunks at all, so a normal combine pays nothing for it.
+     */
+    readonly allowAbsentOperands?: boolean;
 }
 /**
  * A combine that can also subtract.
@@ -597,96 +917,287 @@ interface BaseCombineOptions {
  * chunk-aligned pass, and each exclude is read **only at the keys that survived** — so a large global opt-out
  * list costs reads proportional to the audience, not to itself.
  */
-interface CombineOptions extends BaseCombineOptions {
-    /** Segments whose ids are subtracted from the result. */
+export interface CombineOptions extends BaseCombineOptions {
+    /**
+     * 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[];
 }
-/** {@link CombineOptions} plus the write batching used by the `*Into` variants. */
-interface CombineIntoOptions extends CombineOptions {
-    /** Ids buffered per `addMany` while materializing into `dest`. */
-    readonly batchSize?: number;
+/**
+ * A combine that WRITES its result — the extra options `intersect`/`union`/`andNot` have no use for.
+ *
+ * Separate from {@link CombineOptions} on purpose: `allowEmpty` and `guard` decide whether a generation is
+ * published, and a read verb publishes nothing. Offering them on `intersect()` would be offering a parameter
+ * that cannot do anything.
+ */
+export interface MaterializeOptions extends CombineOptions {
+    /**
+     * Audit sink. A materialisation publishes a generation, and a publish is an auditable event
+     * (`segment.publish`, exactly as a load emits) — as is a refusal (`segment.load-refused`).
+     *
+     * 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` 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} 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;
+    /**
+     * Publish an empty result over a non-empty destination. Off by default, exactly as on {@link CloudRoaring.load}:
+     * an empty combine is far more often a mistake upstream — a typo'd operand, a segment that has not loaded
+     * yet, an `exclude` that swallowed everything — than an intent, and once it lands it is indistinguishable
+     * from a correct run.
+     */
+    readonly allowEmpty?: boolean;
+    /** 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}. A value that is not a non-negative
+     * integer throws `ValidationError`.
+     *
+     * **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;
 }
-declare class Segment {
+/**
+ * What `andNotInto` takes: the write options without `exclude`, because its `excludes` argument IS the
+ * subtraction — a second one in the options would be two spellings of one thing.
+ *
+ * Named rather than left as an inline `Omit` so it can be imported and annotated. The read sibling `andNot`
+ * solves the same problem the same way, by taking {@link BaseCombineOptions}.
+ */
+export type AndNotIntoOptions = Omit<MaterializeOptions, 'exclude'>;
+/**
+ * A handle bound to one segment — the read verbs, plus the three `*Into` verbs that write a **new generation**
+ * of another segment.
+ *
+ * **IDs must be integers in `[0, 2^32)`** (dense 32-bit). A non-integer / negative / out-of-range id
+ * throws {@link ValidationError}.
+ *
+ * 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 metricsOn;
-    constructor(engine: SegmentEngine, ref: SegmentRef, clock: Clock, metrics: IMetricsSink);
+    private readonly materialize;
+    private readonly pinned;
+    private readonly combineEngine;
+    /** Absolute epoch-ms deadline from {@link SegmentOptions.expiresAt}; `undefined` ⇒ this handle never expires. */
+    readonly expiresAt?: number;
     /**
-     * Time an op with the injected clock and emit an `op` metric on completion (success or throw). Skipped
-     * entirely when no sink is wired, so the default path pays nothing.
+     * 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.
      */
-    private timed;
-    /** Add an id (integer in `[0, 2^32)`). Throws {@link ValidationError} on a bad id. */
-    add(id: number): Promise<void>;
+    readonly pinnedAt?: PinnedAt;
     /**
-     * Add many ids, from a **sync or async** iterable. Not atomic across chunks — see the class note.
-     *
-     * An async source means a database cursor streams straight in — `addMany(athenaCursor())` rather than
-     * hand-batching `page → addMany(page)`. Ids are grouped by chunk and each chunk is written **exactly once**,
-     * however long the stream: pending ids are held compressed, not buffered-and-flushed, so a long stream costs
-     * no more backend writes than a short one. Peak memory is the roaring representation of the ids you pass.
-     *
-     * **For a very large set, reach for `bulkLoadCrbmGeneration` instead.** `addMany` expresses a *delta* and
-     * writes one warm row per touched chunk — around 61,000 of them for a set spread across the whole id space.
-     * Bulk-load *replaces* the segment with one immutable Cold object. See the guide's cost comparison; picking
-     * the wrong one of these is the most expensive mistake available in this library.
+     * 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.
      */
-    addMany(ids: Iterable<number> | AsyncIterable<number>): Promise<void>;
-    /** Remove an id (integer in `[0, 2^32)`). Throws {@link ValidationError} on a bad id. */
-    remove(id: number): Promise<void>;
-    /** Remove many ids, from a **sync or async** iterable. Not atomic across chunks — see {@link addMany}. */
-    removeMany(ids: Iterable<number> | AsyncIterable<number>): Promise<void>;
+    private constructor();
     /**
-     * **Claim ids atomically — add them, and get back only the ones that were not already there.**
+     * **Hold this segment at the generation that is current right now**, for as long as you keep the handle.
      *
-     * The durable analogue of Redis `SETBIT` returning the prior bit, which is what an exactly-once *"have I
-     * already sent to / already processed this id?"* check needs. `has()` then `add()` cannot give you this: two
-     * workers can both read absent and both proceed.
+     * An ordinary handle re-resolves on `cache.genTtlMs`, so a publish part-way through a long job means its second
+     * half describes a different instant than its first — every chunk whole and verified, but the answer covering
+     * two moments, with nothing in the result saying so. That is fine for a dashboard and wrong for an export, a
+     * reconciliation, or a send that has to match the count you reported. A pin is how you get one instant.
      *
      * ```ts
-     * const sent = store.segment(day, { namespace: 'sent-daily' });
-     * const toSend = await sent.claimMany(candidateIds);   // only the ids this worker won
-     * for (const id of toSend) enqueue(id);                // ...so nobody else will send them
+     * const snap = await store.segment('active-30d').pin();
+     * const total = await snap.count();            // the number you report
+     * for await (const id of snap.iterate()) { … } // …and the ids it counted, however long this takes
      * ```
      *
-     * **Pass a batch, not one id.** A Warm write rewrites a whole 64K-id chunk bitmap, so claiming ids one at a
-     * time is the single most expensive way to use this library — measured at ~5,000 writes and ~23 MB for 5,000
-     * ids, against 1 write and ~8 KB for the same ids in one call. This method does one OCC read-modify-write per
-     * distinct chunk, giving you Redis's *semantics* without Redis's per-id *cost shape*.
+     * **Only this segment is pinned.** `snap.intersect([other])` reads `snap` at its pinned generation and
+     * `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.
+     *
+     * **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 [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 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.
      *
-     * **Exactly-once holds per id**, which is the guarantee that matters: each id lives in one chunk, a chunk is
-     * one OCC row, so exactly one concurrent claimer sees any given id as new. Like `addMany` it is **not** atomic
-     * across chunks — a mid-flight failure can leave some chunks claimed — but re-running is safe, because
-     * already-claimed ids simply come back as not-new.
+     * `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.
      *
-     * Order of the returned ids is unspecified.
+     * 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.
      */
-    claimMany(ids: Iterable<number>): Promise<number[]>;
+    pin(): Promise<Segment>;
+    /**
+     * 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
+     * the injected clock, so it costs nothing on a handle with no deadline and no I/O on one that has expired.
+     *
+     * Deliberately evaluated per call rather than cached: a long-lived handle created before its deadline must
+     * start reading empty the moment the deadline passes, without the caller re-creating it.
+     */
+    private expired;
+    /**
+     * Refuse a materialisation that involves an **expired** handle. Called by the three `*Into` verbs only.
+     *
+     * 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 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 — 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.)
+     *
+     * The verbs are `async` so this surfaces as a **rejected promise**, like every other validation in the facade —
+     * a synchronous throw out of a promise-returning method escapes a caller who attached `.catch()` instead of
+     * awaiting.
+     */
+    private refuseIfExpired;
+    /**
+     * Time an op with the injected clock and emit an `op` metric on completion (success or throw). Skipped
+     * entirely when no sink is wired, so the default path pays nothing.
+     */
+    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.
+     *
+     * 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>;
-    iterate(): AsyncIterable<number>;
     /**
-     * Chunk-skipping intersection: stream the ids in **this** segment AND every segment in `others`, ascending.
-     * Fetches only the Cold chunks present in *all* operands (a key absent from any operand contributes nothing
-     * and is never downloaded), streaming under a bounded in-flight window — so the Cold footprint stays small
-     * (Lambda-friendly) regardless of segment size. Pass `concurrency` to tune that window (a positive integer).
-     * AND is commutative, so `a.intersect([b])` and `b.intersect([a])` yield the same ids. (Warm state is read
-     * up front, so total memory also carries each operand's Warm size — negligible under Topology-A.) Pass
-     * `budget` to override the store's per-op denial-of-wallet budget for this call (or `false` to lift it).
+     * 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>;
     /**
-     * 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.
+     * 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
+     * and is never downloaded), streaming under a bounded in-flight window — so the Storage footprint stays small
+     * (Lambda-friendly) regardless of segment size. Pass `concurrency` to tune that window (a positive integer).
+     * AND is commutative, so `a.intersect([b])` and `b.intersect([a])` yield the same ids. Pass `budget` to
+     * override the store's per-op denial-of-wallet budget for this call (or `false` to lift it).
+     */
     intersect(others: Segment[], options?: CombineOptions): AsyncIterable<number>;
     /**
-     * Materialize `this ∩ others…` (minus `exclude`) **into** `dest` (added, not replaced). Streaming +
-     * bounded-memory, but **not atomic** across chunks — see {@link addMany}.
+     * 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
+     * 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
+     * often a mistake upstream — a typo'd operand, an `exclude` that swallowed everything, an operand that has
+     * not loaded yet — than an intent, and once it publishes it is indistinguishable from a correct run. So the
+     * write is **refused and reported**: `published: false`, `reason: 'empty'`, and `dest` keeps what it had.
+     * Pass `allowEmpty: true` when emptying the destination is the point.
+     *
+     * `guard` adds the same plausibility bounds `load()` takes — `minCardinality` and `minRetained` — judged
+     * against what `dest` held before. A refusal is **reported, not thrown**, exactly as on `load()`; branch on
+     * `published`. A lost race is the one outcome that still throws ({@link WriteConflictError}), because a
+     * materialisation that silently did not take effect is the one thing a caller cannot detect on its own.
+     *
+     * A call involving an **expired handle** is refused before any of this. See {@link refuseIfExpired}.
      */
-    intersectInto(dest: Segment, others: Segment[], options?: CombineIntoOptions): Promise<void>;
+    intersectInto(dest: Segment, others: Segment[], options?: MaterializeOptions): Promise<MaterializeResult>;
     /**
      * `this ∪ others…`, minus `options.exclude` — streamed ascending.
      *
@@ -695,11 +1206,11 @@ declare class Segment {
      * `intersect` prunes any key missing from any operand; union has nothing to prune. It is charged against the
      * same per-op budget, so a wide union is refused rather than quietly billed — pass `budget` to raise it
      * deliberately. If you find yourself unioning the same segments on every read, materializing the combined
-     * segment once (`unionInto`, or a bulk-load rebuild) is the cheaper shape.
+     * segment once (`unionInto`, or a load) is the cheaper shape.
      */
     union(others: Segment[], options?: CombineOptions): AsyncIterable<number>;
-    /** Materialize `this ∪ others…` (minus `exclude`) **into** `dest`. **Not atomic** — see {@link addMany}. */
-    unionInto(dest: Segment, others: Segment[], options?: CombineIntoOptions): Promise<void>;
+    /** Materialize `this ∪ others…` (minus `exclude`) as a **new generation of `dest`** — see {@link intersectInto}. */
+    unionInto(dest: Segment, others: Segment[], options?: MaterializeOptions): Promise<MaterializeResult>;
     /**
      * `this \ (excludes…)` — streamed ascending. Suppression on its own.
      *
@@ -708,27 +1219,27 @@ 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.
      */
     andNot(excludes: Segment[], options?: BaseCombineOptions): AsyncIterable<number>;
-    /** Materialize `this \ (excludes…)` **into** `dest`. **Not atomic** — see {@link addMany}. */
-    andNotInto(dest: Segment, excludes: Segment[], options?: BaseCombineOptions & {
-        batchSize?: number;
-    }): Promise<void>;
+    /** Materialize `this \ (excludes…)` as a **new generation of `dest`** — see {@link intersectInto}. */
+    andNotInto(dest: Segment, excludes: Segment[], options?: AndNotIntoOptions): Promise<MaterializeResult>;
     /**
-     * Grounded cost report for this segment (Phase 5b): storage cost from its **real** `.crbm` size (exact,
-     * no payload reads); request cost from the supplied `workload` rates. A segment with no Cold generation
-     * reports zero storage. See {@link CostReport} — it always includes a verdict (incl. the lose-zone).
+     * 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. 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;
-        topology?: Topology;
     }): Promise<CostReport>;
 }
-
-/** Package version marker. Kept in sync with package.json at release. */
-declare const VERSION = "0.9.0";
-
-export { type BaseCombineOptions, CloudRoaring, type CloudRoaringOptions, type CombineIntoOptions, type CombineOptions, type EraseSubjectResult, SafeBitmap, Segment, type SegmentOptions, type SubjectErasureEntry, type SubjectReport, type SubjectSegmentRef, VERSION, bulkLoadCrbmGeneration, compactSegment, roaringCodec, runCompactionCycle, runExport };
+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';