@cloudbitmaps/roaring 0.8.2 → 0.10.0

package/dist/index.d.ts

@@ -1,277 +1,205 @@
-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, 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.
- *
- * `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.
- *
- * 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.
+ * CloudRoaring — distributed, cloud-native Roaring Bitmaps, read from object storage.
  *
- * 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 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 a `keystore` for encryption-at-rest / crypto-shred.
  *
- * 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: `bulkLoadCrbmGeneration` streams a set of ids
+ * into one immutable object and publishes it forward-only. Every other write in the library is a load in
+ * 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 { SegmentEngine } from '@cloudbitmaps/core';
+import type { BudgetOption, GenerationEntry, LoadGuard, LoadOptions, LoadRefusal, LoadResult, RollbackResult, Clock, StorageChunkSource, ConsistencyReport, CostReport, DropResult, EstimateInput, ExportManifest, ExportOptions, ExportSink, IAuditSink, IStorageDriver, IKeystore, IMetricsSink, StorageBackend, PricingProfile, RetentionPolicy, RetireExpiredOptions, RetireExpiredResult, RetryPolicy, Rng, SetRetentionResult, PinnedAt, SegmentRef, Workload } from '@cloudbitmaps/core';
+import type { 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. The free functions take `backend.storage`; 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 storage read retries **transient** faults (throttling, 5xx, dropped
+     * connections) with bounded, jittered exponential backoff (see {@link DEFAULT_RETRY_POLICY}). Pass a partial
+     * policy to tune it — anything you leave out keeps its default — or `false` to disable the transient-retry
+     * wrapper entirely (e.g. if your injected client already retries). Deterministic errors
+     * (`ValidationError`/`IntegrityError`/`WriteConflictError`/…) are never retried by this layer.
      */
-    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;
+    /**
+     * 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 metrics?: IMetricsSink;
+    /**
+     * Per-op **denial-of-wallet** budget: the max backend requests a single
+     * `count`/`iterate`/`intersect`/`union`/`andNot`/`subjectReport`/`eraseSubject` may fan out into before it's
+     * refused with {@link BudgetExceededError} — so one runaway op can't drive unbounded GET cost on a shared
+     * 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 budget?: BudgetOption;
+    /**
+     * Determinism seams, for tests and replayable jobs. Production stores leave this out and get a system clock
+     * and a `Math.random`-backed source.
+     */
+    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;
     /**
      * 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.
+     * (default 2000) — the bound on read staleness after a load publishes a new generation. Applies when
+     * `storage` is a **backend**, whose registry supplies the cheap `currentGen` read the refresh needs. A store
+     * wired with a bare `IStorageDriver` has no registry at all and pins the generation for the source's
+     * lifetime. Lazy — no timer; ≤ one registry read per segment per window, opening a new reader only when the
+     * generation actually advanced.
      */
-    readonly coldGenTtlMs?: number;
+    readonly genTtlMs?: 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).
+     * (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 coldReaderCacheMax?: number;
+    readonly readerMax?: 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.
+     * 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 coldReaderCacheMaxBytes?: number;
+    readonly readerMaxBytes?: number;
+}
+/** {@link CloudRoaringOptions.encryption} — encryption at rest and crypto-shred. */
+export interface EncryptionOptions {
     /**
-     * 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.
+     * 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 retry?: RetryPolicy | false;
-    /** Backoff schedule between OCC conflict retries; defaults to a small, tight one. */
-    readonly occBackoff?: RetryPolicy;
+    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.
+     *
+     * 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 required?: boolean;
+}
+/**
+ * {@link CloudRoaringOptions.retry} — a partial {@link RetryPolicy} plus the retry callback.
+ *
+ * Partial on purpose: the flat form this replaces took a **whole** `RetryPolicy`, so tuning one field meant
+ * restating all five. Anything omitted here keeps its {@link DEFAULT_RETRY_POLICY} value.
+ */
+export interface RetryOptions extends Partial<RetryPolicy> {
     /** Observability: called before each transient-retry backoff wait. */
     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;
+}
+export interface SegmentOptions {
+    readonly namespace?: string;
     /**
-     * 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.
-     */
-    readonly metrics?: IMetricsSink;
-    /**
-     * 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.)
-     */
-    readonly warmReadConsistency?: 'strong' | 'eventual';
-    /**
-     * 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.
+     * **When this segment stops being readable** — an absolute epoch-ms instant, declared where the segment is
+     * named instead of in a separate `setRetention` call.
      *
-     * 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.
+     * 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.
      *
-     * 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.
-     */
-    readonly writeConcurrency?: number;
-    /**
-     * Hard ceiling on the warm-delta bytes one segment scan may hold resident. Default **64 MiB**.
+     * **Two things this does NOT do, both deliberate:**
      *
-     * **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.
+     * - 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.
      *
-     * Raise it for genuinely large segments; it exists to keep a modest container alive, not to second-guess you.
-     */
-    readonly maxWarmScanBytes?: number;
-    /**
-     * 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.
+     * 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 budget?: BudgetOption;
-}
-interface SegmentOptions {
-    readonly namespace?: string;
+    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 +207,186 @@ 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** a member and a generation without it is now current — and the generation that held
+     * the bit has been deleted from the bucket. The physical half is inherent: an erasure is a rewrite, and the
+     * rewrite's predecessor is collected before this entry is returned (see {@link CloudRoaring.eraseSubject}).
+     */
+    readonly erased: boolean;
+    /** The generation the id was found in (present whenever the segment was read). */
+    readonly fromGeneration?: number;
+    /** The generation written without the id (present whenever one was written). */
+    readonly generation?: number;
+    /**
+     * Why the id was NOT erased from this segment, when `erased` is false. `'superseded'` — a newer generation
+     * was published while the rewrite was in flight, by a load or by another erasure, so **this call** did not
+     * erase the id; re-run against the new generation, which erases it if it is still there and reports nothing
+     * for the segment if the racing writer already removed it. `` `error: <message>` `` — an isolated per-segment
+     * fault (per-segment faults are recorded so one segment can't discard the whole ledger); re-run after fixing
+     * the fault. A fault that landed once part of the work was already done — a Storage `delete` fault, or a collect
+     * that could not prove the segment was still the same one, whether or not a rewrite was published first —
+     * also re-runs, but **read what the re-run says**: it usually reports `erased: true` against the superseded generation it found the id in, it reports
+     * nothing at all if a racing collector took that generation first (the bit is gone, but no run holds a
+     * receipt for it), and if the segment's row has since been purged it is no longer scanned at all — anything
+     * left in its bucket is an orphan for `checkConsistency` / `gcOrphanGenerations`. **Segments the id is not in
+     * 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 — it is what was written and then deleted again. */
+    readonly generation: number;
+    /**
+     * Whether this generation is now the destination's current one.
+     *
+     * Before the guard existed this was always true, because a materialisation always published. Branch on it:
+     * a refusal is reported, not thrown, so a caller that ignores it sees a successful-looking result for a
+     * write that deliberately did not happen.
+     */
+    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[];
+}
+/**
+ * Options that moved into a group, and where each one went.
+ *
+ * TypeScript rejects these at the call site, which covers most callers. It does not cover a plain-JS caller, a
+ * config object that arrived as JSON, or anything that reached the constructor through an `as` cast — and for
+ * this particular set, being ignored is worse than being rejected, because **every one of them is a knob whose
+ * absence is silent and wrong**: a dropped `requireEncryption` reads cleartext when the caller demanded
+ * encryption, a dropped `clock` makes a "deterministic" job non-deterministic, and a dropped
+ * `coldReaderCacheMaxBytes` restores a 64 MiB ceiling someone had deliberately lowered for a small heap.
+ * None of those announces itself; each looks like the store simply working.
+ */
+/**
+ * How a `0.9.x` option is answered: it moved into a group, it was renamed, or it is gone.
+ *
+ * The category is DATA, not inferred from how the guidance happens to be punctuated. The first version
+ * decided by testing whether the replacement text looked like an identifier, which got two entries wrong in
+ * opposite directions: `registry` HAS a successor and was announced as "removed", and `cold` → `storage` was
+ * announced as "moved into a group" when `storage` is the one required flat option, not a group. A reader
+ * told to look in a group that does not exist is the failure this whole guard is about.
+ */
+export declare class CloudRoaring {
     private readonly engine;
+    private readonly cache;
+    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 an option that moved into a group, naming where it went.
+     *
+     * Silently ignoring one would be the exact failure this release exists to remove — see {@link MOVED_OPTIONS}
+     * for why each of these is unsafe to drop rather than merely untidy.
+     */
+    private static rejectMovedOptions;
     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.
+     * Out-of-process callers use the free functions with explicit deps.
      */
-    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 forward-only — the shared body of the `*Into`
+     * verbs. The destination's previous generation stays readable until the publish lands (readers re-resolve
+     * within `cache.genTtlMs`).
+     *
+     * This routes through `loadSegment` rather than writing the generation itself, and that is the whole point
+     * of it. A materialisation is a load whose ids happen to come from a combine instead of from upstream, so
+     * everything `load()` learned the hard way applies unchanged: the generation is written UNPUBLISHED, the
+     * guard runs while the old generation is still authoritative, the publish is fenced (on the pointer it
+     * judged, on the row's identity, and — where it judged an ABSENT segment — on that absence), and a refused
+     * object is reclaimed only after re-reading the row and finding the same incarnation (hard invariant 1:
+     * deleting it after a purge-and-recreate would put a live row over a missing generation).
+     *
+     * That last check narrows the window rather than closing it: the row read and the delete are two round
+     * trips, and `IStorageDriver` has no conditional delete to make them one. `gcOrphanGenerations` carries
+     * the same residual and says so. The failure it leaves is an orphan object, which costs storage until
+     * something collects it — deliberately the cheaper side of the trade.
+     *
+     * Materialising used to do none of that. It wrote and published in one step, so an empty combine — a typo'd
+     * operand, an `exclude` that swallowed everything, an operand that had not loaded yet — silently replaced
+     * `dest` with an empty generation. That is the same failure `load()`'s guard exists to prevent, on the same
+     * data, and it was reachable without passing any option at all.
      *
-     * 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).
+     * **A lost race still throws.** `loadSegment` reports one as `reason: 'superseded'`; the `*Into` verbs have
+     * always thrown {@link WriteConflictError} for it, and a caller who wrote `catch (WriteConflictError)` must
+     * keep working. So that one refusal is translated back into the throw, and `MaterializeResult.reason` never
+     * carries it.
+     *
+     * **A `WriteConflictError` does not by itself mean nothing was published**, and that is worth knowing
+     * before you write the retry. `'superseded'` covers four different causes — the write-once PUT collided,
+     * the pointer moved, the row's token changed, the row was purged — and only the first two are the
+     * "somebody beat us" the name suggests. A token can also change on a write that is not a supersession at
+     * all, such as a `setRetention` on the destination. On top of that, the collection pass that runs AFTER a
+     * successful publish can raise the same error. So: treat it as "re-read the destination and decide",
+     * never as "the write did not happen".
+     *
+     * **And it still collects nothing**, unlike `load()`. See the `keep` default below.
+     */
+    private materialize;
+    /**
+     * **Subject access (GDPR Art. 15 / CCPA right-to-know): which segments is this id a member of?**
+     *
+     * Enumerates the **registered** segments (via the store's own `registry`) and does a `has(id)` on each — no
+     * drivers to re-pass. Complete only over registered segments (every loaded segment has a row, so register the
+     * registry the loads used). There is deliberately **no `id → segments` reverse index** — that would tax every
+     * load for a rare request; this admin scan is `O(registered segments)` and touches no hot path. Requires a
+     * `registry` in the store config (throws {@link UnsupportedError} otherwise).
      */
     subjectReport(id: number, options?: {
         namespace?: string;
@@ -346,42 +395,53 @@ 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;
+     * **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. The returned per-segment record is your **erasure ledger** —
+     * persist it / route it to your audit sink as the proof of deletion (a `segment.rewrite` audit event is also
+     * emitted per rewrite when you pass `audit`).
+     *
+     * Uses the backend's **own** two halves, so the membership check and the rewrite provably run
+     * over the same generation. Requires the store built with a **backend** (throws
+     * {@link UnsupportedError} otherwise; a pre-built `StorageChunkSource` store has no `IStorageDriver` to write
+     * through — use the `eraseIdFromSegment` free function there).
+     *
+     * **One contract remains** (an integrator obligation the library cannot check): **do not load the segment
+     * while erasing from it.** A load that lands after the rewrite carries whatever its source held, and the
+     * library cannot know that source was meant to exclude the id. Quiesce loads of the affected segments for the
+     * duration, or fix the source first and load after. A writer that lands *during* the rewrite is caught: the
+     * rewrite's publish is refused **by the fence** — `publishGeneration`'s `expectFrom`, which lands the CAS only
+     * while the pointer is still on the generation the rewrite streamed — and the entry says `note: 'superseded'`,
+     * so re-run. Forward-only alone would NOT refuse it: `nextGeneration` numbers above everything in the bucket,
+     * so the rewrite would out-rank the newer generation and then collect it.
+     *
+     * A racing **erasure** is caught before that, and reported the same way. It collects with `keep: 0`, taking
+     * every generation below its new pointer — the one this rewrite is streaming, and the object this rewrite
+     * just wrote — so the loser can find its own inputs deleted mid-flight. That surfaces as a reason rather than
+     * an error, read off the row: a moved pointer is `'superseded'`, a concurrent `dropSegment` `'destroyed'`,
+     * a retention sweep that purged the row `'absent'`. Re-running is the fix in every case.
+     *
+     * **Read `note` on any `erased: false` entry — the two reasons mean different things.** `'superseded'` means
+     * another writer (a load, or another erasure) moved the pointer mid-rewrite, so **this call** did not erase
+     * the id. Re-run: it erases the id if it is still there, and lists nothing for the segment if a racing
+     * erasure of the same id already removed it. Do not read `'superseded'` as "the id is still present" —
+     * read it as "not done by this call, and the re-run settles it".
+     * `` `error: …` `` is a per-segment fault (caught so one segment can't discard the whole ledger) and it can land
+     * on either side of the publish: if the rewrite had not published, the id is still there and a re-run erases
+     * it; if the publish succeeded and only the **collection** of the old generation failed, the id is already
+     * absent from every read and what remains is an object in the bucket that still contains the bit. A re-run
+     * then reports nothing for that segment (the id is not in the current generation), so **that residual is
+     * collected by `gcOrphanGenerations(ref, deps, { keep: 0 })` or the next retention sweep**, not by another
+     * `eraseSubject`. Re-running is otherwise safe and idempotent: a segment the id is no longer in is not listed. Admin-only path;
      * `O(registered segments)`, no hot-path cost. Per-subject crypto-shred is infeasible (a subject's bit is
      * 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 +449,141 @@ 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 `list` call; 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 `registry`.
+     *
+     * ```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 — except behind a driver that buffers its
+     * enumeration to retry it as a unit, which `RetryingRegistryDriver` does: wrapped in that, the whole scan is
+     * paid for and resident before the first row arrives.
+     *
+     * Yields `destroyed` tombstones and rows with `currentGen: null`, because a filtered enumeration that looks
+     * complete is worse than an honest one — filter on `status`/`currentGen` yourself, or ask
+     * {@link CloudRoaring.exists} the narrower question. Needs a `registry`.
+     *
+     * ```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, so they remain until a later load raises the
+     * pointer past them. An operator who has just undone a bad load should not have the evidence collected out from
+     * under them.
+     *
+     * Needs a backend.
+     */
+    rollback(ref: SegmentRef, toGeneration: number, options?: {
+        audit?: IAuditSink;
+    }): 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('audience:active', idsFromWarehouse, {
+     *   guard: { maxShrink: 0.5 },   // refuse a load that drops 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.
+     *
+     * The object written for a refused load is deleted again before returning — it sits above `currentGen`, where
+     * generation collection deliberately never looks, so nothing else would reclaim it. The exception is a load
+     * that finds the segment **re-created** underneath it: the generation number it holds may then name the new
+     * incarnation's live object, so it leaves the orphan rather than risk deleting live data.
+     *
+     * Two things it does **throw** for, rather than report: a crypto-shredded segment (`ValidationError` — there
+     * is no key to write under), and a collection pass that could not prove the segment was still the same one
+     * (`WriteConflictError`). The second can be raised **after** the publish already landed, so a throw does not
+     * by itself mean the load did not take effect — re-read the pointer rather than assuming.
+     *
+     * 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 +595,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 +606,19 @@ 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.
-     *
-     * 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
+     * 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 `cache.genTtlMs` (default 2 s), not instantly: a store that had already read this
+     * segment may answer from its cached generation + cached chunks until that window lapses. A reader that never
+     * touched it sees empty at once. **That bound needs a clock and `cache.genTtlMs > 0`** — a store built without a
+     * clock, or with `cache.genTtlMs: 0` ("pin forever"), holds its resolved snapshot for its own lifetime and can
      * keep answering `true` for a dropped segment indefinitely; restart it.
      *
-     * 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;
@@ -449,54 +626,211 @@ declare class CloudRoaring {
         audit?: IAuditSink;
     }): Promise<DropResult>;
     /**
-     * **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).
+     * **Record when this segment becomes eligible for retirement.** One registry write; nothing is deleted here,
+     * and nothing starts running. `retireExpired` is what acts on the policy, and **you** decide when that runs —
+     * an EventBridge rule, a CronJob, a queue consumer, whatever your deployment already has. This library starts
+     * 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 every load
+     * rewrites both, so "expire 30 days after the last write" would keep a busy daily bucket alive forever
+     * precisely because it is being reloaded.
+     *
+     * ```ts
+     * const DAY = 86_400_000;
+     * const ref = { namespace: 'active-daily', segment: '2026-08-05' };
+     * await store.setRetention(ref, { expiresAt: Date.now() + 30 * DAY });
+     * ```
+     *
+     * **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.
+     */
+    setRetention(ref: SegmentRef, policy: RetentionPolicy): Promise<SetRetentionResult>;
+    /**
+     * **The stored retention policy**, or `null` if the segment has none (or has no registry row, or is a
+     * tombstone). Returns the string `'invalid'` for a row whose `expiresAt` is present but unusable — a
+     * hand-edited row, or one from a restore — so a malformed policy is visible rather than silently reading as
+     * "never expires" on a segment someone believes is expiring.
+     */
+    getRetention(ref: SegmentRef): Promise<RetentionPolicy | null | 'invalid'>;
+    /**
+     * **Cancel a segment's expiry** so no sweep retires it. Returns whether a policy was actually removed (`false`
+     * when there was none). A separate verb from `setRetention` on purpose: "never expire" as a magic value passed
+     * to the setter is how a typo becomes a deletion.
+     */
+    clearRetention(ref: SegmentRef): Promise<boolean>;
+    /**
+     * **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,
+     * 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 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})`);
+     *
+     * const swept = await store.retireExpired({ namespace: 'active-daily' });
+     * for (const e of swept.entries) {
+     *   if (e.action === 'skipped') console.warn(`${e.segment}: ${e.reason}`); // invalid-policy / limit / failed: …
+     *   if (e.action === 'retired' && e.result.generationsRemaining.length > 0) {
+     *     console.warn(`${e.segment}: storage not fully reclaimed — re-run`);
+     *   }
+     * }
+     * if (swept.limited) scheduleAnotherPassSoon(); // more are still eligible
+     * ```
+     *
+     * **Read the ledger.** A per-segment *fault* is an entry, not an exception — a throw from the middle of a fleet
+     * 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` 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 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. Pass
+     * `purgeTombstones: false` to keep every tombstone.
+     *
+     * 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 verbs on this class handle themselves — `eraseSubject`, `dropSegment` and `retireExpired` invalidate
+     * what they touch. This method is for the cases they cannot see:
+     *
+     * - **`destroySegment` / `eraseNamespace`**, which are free functions over raw drivers rather than methods
+     *   here, so a crypto-shred performed beside this store leaves it holding an open reader and an unwrapped
+     *   DEK. Until it is told, it keeps decrypting — including chunks it had never fetched before the shred.
+     * - **Another process.** Erasing on one box invalidates nothing on the others; each store bounds its own
+     *   staleness by `cache.genTtlMs`, and a store built with no clock or `cache.genTtlMs: 0` ("pin forever") never
+     *   converges at all. If a compliance deadline depends on every reader converging, you need to signal them —
+     *   this is the call to make when your own fan-out delivers.
+     *
+     * Synchronous, best-effort, and safe to call for a segment this store has never read.
+     *
+     * ```ts
+     * await destroySegment(ref, { storage, registry, keystore }, { confirmSegment: ref.segment });
+     * 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**, which is safe precisely
+     * because the cache is keyed by the source's version rather than the generation number: the pinned view
+     * reports the version captured at pin time, so its decoded chunks cannot collide with the live generation's.
+     * Sharing it on a generation-only key was how a pinned read could resurrect an id already reported
+     * physically gone.
+     */
+    private pinSegment;
+    /**
+     * An engine reading every segment in `pins` at its pinned generation and everything else live.
+     *
+     * It **shares the store's chunk cache**, which is safe only because that cache is keyed by the source's
+     * version rather than the generation number: a pinned view reports the version captured at pin time, so its
+     * decoded chunks cannot collide with the live generation's.
+     */
+    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.
+     */
+    private engineForCombine;
+    /** The store's registry, or a typed error naming the operation that needs one. */
+    private requireRegistry;
+    /**
+     * **Cross-tier DR consistency check.** After a restore/failover, verify every registered segment's `currentGen`
+     * actually has its `.crbm` present in Storage — catching a **torn restore** where the registry (`currentGen`) came
+     * back ahead of the object store, so a pointer references a generation that isn't there (reads would then
+     * throw). Read-only, bounded fan-out; run it at startup after a restore. Returns `{ checked, inconsistent }` —
+     * `inconsistent` empty ⇒ coherent; otherwise it names the segments to recover (restore the object store, or
+     * roll the registry back to a coherent point). Needs the store built with a **backend**
+     * (throws {@link UnsupportedError} otherwise). `destroyed` (crypto-shredded) segments are skipped. Pair it with
+     * the DR runbook (docs/guide/disaster-recovery.md).
      */
     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}.
- *
- * **`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.
- */
 /** 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 {
+    /** 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.
@@ -505,96 +839,215 @@ 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 {
+export interface CombineOptions extends BaseCombineOptions {
     /** Segments whose ids are subtracted from the result. */
     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` was the one write path in the library that could make a generation current and
+     * leave no trace in the compliance trail.
+     *
+     * It sits HERE rather than on {@link BaseCombineOptions}, where it used to, for the reason this type exists:
+     * the streaming verbs write nothing, so an audit sink on `intersect()` was a parameter that could not do
+     * anything. Same rule, now applied to itself.
+     */
+    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}.
+     *
+     * **Defaults to keeping everything**, unlike `load()`, which keeps 1 and collects the rest. A
+     * materialisation has never collected, and an operator's recovery story can depend on that: `rollbackSegment`
+     * refuses a target that has been collected. Pass a number to collect on the way through; `0` keeps only the
+     * 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'>;
+/** How a `Segment` hands a result stream back to its store to become a new generation of `dest`. */
+/** Build a pinned twin of a handle — injected into `Segment` so it stays free of store wiring. */
+type Pin = (ref: SegmentRef, expiresAt?: number) => Promise<Segment>;
+/**
+ * The engine a combine should run on, given every handle involved — `undefined` when none is pinned and the
+ * store's own engine will do. Injected so `Segment` stays free of store wiring.
+ */
+type CombineEngine = (handles: readonly Segment[]) => SegmentEngine | undefined;
+type Materialize = (dest: SegmentRef, ids: AsyncIterable<number>, op: string, options?: MaterializeOptions) => Promise<MaterializeResult>;
+/**
+ * A handle bound to one segment — the read verbs, plus the three `*Into` verbs that write a **new generation**
+ * of another segment.
+ *
+ * **IDs must be integers in `[0, 2^32)`** (dense 32-bit). A non-integer / negative / out-of-range id
+ * throws {@link ValidationError}.
+ *
+ * There is no `add`/`remove` on a handle: data enters a segment as a whole generation (`bulkLoadCrbmGeneration`,
+ * or one of the `*Into` verbs), and leaves it the same way (`eraseSubject`, `dropSegment`).
+ */
+export declare class Segment {
     private readonly engine;
     private readonly ref;
     private readonly clock;
     private readonly metrics;
+    private readonly materialize;
+    /** Build a pinned twin of this handle — injected so `Segment` stays free of store wiring. */
+    private readonly pinned;
+    private readonly combineEngine;
+    /** Absolute epoch-ms deadline from {@link SegmentOptions.expiresAt}; `undefined` ⇒ this handle never expires. */
+    readonly expiresAt?: number | undefined;
+    /**
+     * The generation this handle is held at, when it came from {@link Segment.pin}. Read by the store so a
+     * pinned handle passed as an **operand** is still read at its pin rather than live.
+     */
+    readonly pinnedAt?: PinnedAt | undefined;
     private readonly metricsOn;
-    constructor(engine: SegmentEngine, ref: SegmentRef, clock: Clock, metrics: IMetricsSink);
+    constructor(engine: SegmentEngine, ref: SegmentRef, clock: Clock, metrics: IMetricsSink, materialize: Materialize, 
+    /** Build a pinned twin of this handle — injected so `Segment` stays free of store wiring. */
+    pinned: Pin, combineEngine: CombineEngine, 
+    /** Absolute epoch-ms deadline from {@link SegmentOptions.expiresAt}; `undefined` ⇒ this handle never expires. */
+    expiresAt?: number | undefined, 
     /**
-     * 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>;
+    pinnedAt?: PinnedAt | undefined);
     /**
-     * Add many ids, from a **sync or async** iterable. Not atomic across chunks — see the class note.
+     * **Hold this segment at the generation that is current right now**, for as long as you keep the handle.
+     *
+     * 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 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
+     * ```
+     *
+     * **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.
      *
-     * 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.
+     * **It is a hold, not a lease.** Nothing here stops `gcOrphanGenerations` deleting the generation underneath
+     * you: a pinned read deliberately does **not** heal forward, because silently serving a different generation
+     * is the one thing a pin exists to prevent, so it fails instead. Size `keep` to cover your longest pinned
+     * job — see [Sizing `keep`](../../docs/guide/getting-started.md#sizing-keep) — or take the pin on a segment
+     * you are not collecting.
      *
-     * **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.
+     * A segment with no current generation pins nothing and reads empty, exactly as it would unpinned. A pin
+     * taken before a crypto-shred stops reading when the shred lands: the destroyed row is re-checked every time
+     * the pinned reader opens, so a pin cannot outlive the key it was using.
+     *
+     * 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.
      */
-    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>;
+    pin(): Promise<Segment>;
+    /** This handle's segment, as the cache/pin key — `ref` stays private; the encapsulation is worth the method. */
+    key(): string;
     /**
-     * **Claim ids atomically — add them, and get back only the ones that were not already there.**
+     * 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.
      *
-     * 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.
+     * 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.
      *
-     * ```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
-     * ```
+     * On the read verbs an expired handle answers empty, which is the point of lazy expiry. On a *write* the same
+     * rule would be destructive in a way nobody asks for: `a.intersectInto(dest, [b])` where `b`'s deadline has
+     * quietly passed publishes an **empty generation over `dest`** — a wipe, reported as a successful write, with
+     * the cause (a deadline on a handle somewhere) nowhere in the result. Reads degrade to empty; writes must not.
      *
-     * **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*.
+     * 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.
      *
-     * **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.
+     * (The broader guard — refusing to publish an empty or implausible generation over a non-empty one, with an
+     * `allowEmpty` override — now covers these verbs too: they route through the same guarded write path as
+     * {@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.)
      *
-     * Order of the returned ids is unspecified.
+     * 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.
      */
-    claimMany(ids: Iterable<number>): Promise<number[]>;
+    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. */
     count(): Promise<number>;
+    /** Every id, ascending, streamed one chunk at a time. */
     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).
-     */
     /**
      * 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.
      */
     private refsIn;
+    /**
+     * 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
+     * forward-only, 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.
      *
@@ -603,11 +1056,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.
      *
@@ -620,23 +1073,20 @@ declare class Segment {
      * 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. See {@link CostReport} — it always includes a verdict (incl. the lose-zone).
      */
     costReport(options?: {
         pricing?: PricingProfile;
         workload?: Workload;
-        topology?: Topology;
     }): Promise<CostReport>;
 }
-
+export * from '@cloudbitmaps/core';
+export { bulkLoadCrbmGeneration, eraseIdFromSegment, loadSegment, runExport } from './codec-bound.js';
+export { SafeBitmap, roaringCodec } from './roaring-codec.js';
 /** Package version marker. Kept in sync with package.json at release. */
-declare const VERSION = "0.8.2";
-
-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 declare const VERSION = "0.10.0";