@cloudbitmaps/core 0.1.0-rc.0

package/dist/index.d.ts

@@ -0,0 +1,1945 @@
+import { a as IWarmDriver, h as ColdChunkSource, S as SegmentRef, W as WarmReadOptions, i as SegmentSize, I as IColdDriver, d as IRegistryDriver, j as IKeystore, b as ChunkRef, C as ColdCaps, G as GenKey, B as BlobSink, R as RegCaps, e as RegistryRecord, f as NewRegistryRecord, T as Token, g as RegistryPatch, c as WarmRow, N as NoRow, k as CrbmCrypto, l as BlobReader, m as WrappedDek, A as Aead, n as AeadSealed } from './ports-D3BrJ6ax.js';
+export { o as BufferReader, p as BufferSink, q as GovernanceMeta, r as NO_ROW, s as RegistryStatus, t as aadFor } from './ports-D3BrJ6ax.js';
+
+/**
+ * The **bitmap-codec seam**.
+ *
+ * `core/` is **codec-agnostic**: `SegmentEngine`, compaction, and the `.crbm` read/write helpers only ever
+ * construct and combine bitmaps through the {@link CodecInterface} factory + the {@link CodecBitmap} value type
+ * defined here — never a concrete implementation. The flagship codec is roaring (`roaringCodec`, today in
+ * `core/bitmap.ts`; it moves to `@cloudbitmaps/roaring` when the package split lands); `@cloudbitmaps/bitmap`
+ * (plain bitset) and `@cloudbitmaps/soaring` plug in behind the same seam with zero engine or driver changes.
+ *
+ * **Homogeneity contract:** a single store uses a single codec, so every {@link CodecBitmap} an operation sees
+ * was produced by the same {@link CodecInterface}. The binary set ops ({@link CodecBitmap.orInPlace} etc.) may
+ * therefore assume `other` is the same concrete type and are not required to interoperate across codecs.
+ * (Corollary: a decoded-chunk HOT cache is codec-specific — never share one `cache` across engines built with
+ * different codecs, or a cached bitmap from codec A could reach codec B's in-place op. The `CloudRoaring` facade
+ * mints the cache per store, so this cannot arise in normal use.)
+ *
+ * **Interface surface = exactly what the engine needs**, kept general enough for the known fast-follow codecs
+ * (positional/rank-select access + raw-bitset interop that `@cloudbitmaps/bitmap` will add live on that
+ * package's own extended value type, not here — the engine never calls them). The one codec-linked concern
+ * this seam intentionally leaves in the format layer is the `.crbm` **serialization id** (`ROARING_PORTABLE_ID`
+ * in `crbm/format.ts`): it is stamped in the footer and validated on read, and generalizes to a per-codec id
+ * *with* the second codec's format work — a documented follow-up, not part of this interface.
+ */
+/**
+ * The value type a codec produces — a mutable set of `u32` with set algebra and portable (de)serialization.
+ * This is the shape `SafeBitmap` already has; the engine holds these, caches them, and merges tiers with them.
+ */
+interface CodecBitmap {
+    /** Serialize with the codec's **stable, portable** format (never a frozen/unsafe variant). */
+    serialize(): Uint8Array;
+    add(value: number): void;
+    addMany(values: Iterable<number>): void;
+    remove(value: number): void;
+    removeMany(values: Iterable<number>): void;
+    has(value: number): boolean;
+    /** Cardinality. */
+    readonly size: number;
+    readonly isEmpty: boolean;
+    /** A deep copy — mutating the clone must not touch the original (the HOT cache relies on this). */
+    clone(): CodecBitmap;
+    /** In-place union `this = this ∪ other`. `other` is from the same codec (see the homogeneity contract). */
+    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[];
+}
+/**
+ * A pluggable bitmap codec — the factory the codec-agnostic engine constructs {@link CodecBitmap}s through.
+ * Implementations **must** size-cap before handing untrusted bytes to any native decoder and use a safe
+ * (never a trusting/frozen) deserializer (threat model S1).
+ */
+interface CodecInterface {
+    /** An empty set. */
+    empty(): CodecBitmap;
+    /** A set seeded from an iterable of `u32` values. */
+    fromValues(values: Iterable<number>): CodecBitmap;
+    /**
+     * Size-cap (`bytes.length <= maxBytes`) then portable-deserialize. Throws `IntegrityError` when the input
+     * exceeds the cap or fails to decode — the native decoder is never handed unbounded or unsafe-format input.
+     */
+    safeDeserialize(bytes: Uint8Array, maxBytes: number): CodecBitmap;
+}
+
+/**
+ * Per-op denial-of-wallet budget (Decision #3 / invariant T3). A read/admin op is refused
+ * **before it fans out** if its projected fan-out would exceed `maxRequests` — so one runaway
+ * `count`/`iterate`/`intersect`/`subjectReport`/`eraseSubject` can't drive unbounded RCU/GET cost on a shared
+ * backend. The check is O(1) (a single comparison against the already-known fan-out size), so the hot path is
+ * untouched. Each request's payload is separately size-capped (the safe-deserialize ceiling), so bounding the
+ * fan-out count transitively bounds bytes — the budget is intentionally count-based, not a second byte
+ * accumulator that would add per-chunk work.
+ *
+ * **What the count is.** For the read ops it is the number of Cold **chunk fetches** (`count`/`iterate`: one per
+ * effective chunk; `intersect`: surviving keys × operands). For the admin scans it is the number of **segments
+ * fanned out to** (`subjectReport`: one tier-merged `has()` each; `eraseSubject`: one force-compaction each) —
+ * i.e. it bounds the *breadth* of the fan-out, not the request total of each segment's own compaction. That's
+ * the right lever for a runaway (a million-segment sweep); it is not a byte/request meter.
+ */
+interface Budget {
+    /** Max units of fan-out (Cold chunk fetches, or segments scanned) one op may issue before it is refused. */
+    readonly maxRequests: number;
+}
+/**
+ * Default: **on but generous** — even a full single-segment scan (≤ 65 536 chunks) or a large single-namespace
+ * admin scan stays well under it; it exists to catch a true runaway (a million-segment scan, a pathological
+ * intersection). Tune it down for tighter multi-tenant control, or set `budget: false` to disable.
+ */
+declare const DEFAULT_BUDGET: Budget;
+/** A store/per-op budget option: partial overrides, or `false` to disable entirely. */
+type BudgetOption = Partial<Budget> | false;
+/** Resolve a budget option against a fallback to a concrete `Budget`, or `null` when disabled. Validates. */
+declare function resolveBudget(opt: BudgetOption | undefined, fallback: Budget): Budget | null;
+/**
+ * Resolve a **per-op** budget override against the store's own resolved budget (never the raw global default):
+ * `undefined` inherits the store budget as-is (including a disabled `null`); a partial `{}` / omitted
+ * `maxRequests` inherits the store's *tightening* (so a per-op passthrough of an absent config value can't
+ * silently lift a tight tenant ceiling back to the generous default); `{ maxRequests }` replaces it; `false`
+ * disables. Falls back to {@link DEFAULT_BUDGET} only when the store itself has no budget (disabled).
+ */
+declare function resolvePerOpBudget(opt: BudgetOption | undefined, storeBudget: Budget | null): Budget | null;
+/**
+ * Refuse an op whose projected fan-out exceeds the budget. **Call before fan-out**, with the exact fan-out size
+ * the op is about to issue (Cold chunk fetches, or segments to scan). O(1). No-op when `budget` is `null`
+ * (disabled).
+ */
+declare function checkBudget(budget: Budget | null, projectedRequests: number, op: string): void;
+
+/**
+ * The determinism seam.
+ *
+ * `core/` is a pure function of its inputs + injected dependencies — it never reaches for
+ * ambient time or randomness. Production wiring supplies real implementations; the deterministic
+ * simulator supplies controlled, seeded ones, so any run can be replayed exactly from a seed.
+ *
+ * These are interfaces only (Phase 0 scaffold) — no feature code yet.
+ */
+/** Injected time source. `core/` must never call `Date.now()` directly. */
+interface Clock {
+    /** Milliseconds since the Unix epoch. */
+    now(): number;
+    /**
+     * Resolve after at least `ms` have elapsed. The retry/backoff path's only way to wait — `core/` must
+     * never reach for `setTimeout` directly (it's timer-free, lint-enforced). Production wiring supplies a
+     * `setTimeout`-backed implementation; the simulator supplies a virtual-time one so a backoff schedule is
+     * replayable. `ms <= 0` resolves on a microtask without scheduling a timer.
+     */
+    sleep(ms: number): Promise<void>;
+}
+/** Injected randomness. `core/` must never call `Math.random()` directly. Seedable for simulation. */
+interface Rng {
+    /** A float in the half-open interval [0, 1). */
+    next(): number;
+}
+
+/**
+ * Bounded LRU cache with optional TTL — the HOT tier's memory ceiling (finding C6).
+ *
+ * Time comes from an injected `Clock` (never `Date.now()`) so the cache is deterministic
+ * under simulation.
+ *
+ * The cache can be bounded by entry **count** (`maxEntries`, always) and, optionally, by an aggregate
+ * **byte weight** (`maxBytes`). The byte bound exists for values whose footprint is large and uneven — the
+ * cold reader cache, where one entry pins a fully-parsed `.crbm` index that can be ~6 MB for a wide segment
+ * yet a few hundred bytes for a small one (gap #1: a count-only bound lets 1024 wide indices blow a Lambda's
+ * memory even though the count is "in bounds"). Weights arrive **after** insertion (a cached reader is a
+ * pending promise; its size is known only once it resolves), so weight is reported via {@link setWeight} and
+ * eviction re-runs then.
+ */
+
+interface LruOptions {
+    /** Hard ceiling on entries; the least-recently-used is evicted past it. */
+    readonly maxEntries: number;
+    /**
+     * Optional aggregate byte ceiling across all entries' reported weights (see {@link BoundedLru.setWeight}).
+     * When set, the least-recently-used entries are evicted until the total is within budget — in addition to
+     * the `maxEntries` bound. Omit for a pure count-bounded cache (weights stay 0, no byte eviction).
+     */
+    readonly maxBytes?: number;
+    /** Optional time-to-live in ms; an entry older than this is treated as absent. */
+    readonly ttlMs?: number;
+    /** Only `now()` is used (never `sleep`), so a count-only cache can pass a minimal time source. */
+    readonly clock: Pick<Clock, 'now'>;
+}
+declare class BoundedLru<K, V> {
+    private readonly map;
+    private readonly maxEntries;
+    private readonly maxBytes;
+    private readonly ttlMs;
+    private readonly clock;
+    private totalBytes;
+    constructor(options: LruOptions);
+    get(key: K): V | undefined;
+    /** Read a value **without** counting as an access (recency unchanged, no purge on expiry). */
+    peek(key: K): V | undefined;
+    set(key: K, value: V): void;
+    /**
+     * Report an entry's byte weight (typically once a cached promise resolves and its size is known). Updates
+     * the running total and evicts the least-recently-used entries if the aggregate now exceeds `maxBytes`.
+     * Recency is **not** changed. The `key` being weighted is protected from this eviction pass (we just
+     * populated it) — so a single entry larger than the whole budget is kept rather than immediately dropped.
+     */
+    setWeight(key: K, bytes: number): void;
+    private evictToBudget;
+    /** The least-recently-used key that is not `protectKey`, or undefined if none other exists. */
+    private oldestExcept;
+    private dropKey;
+    private drop;
+    /** Membership test that does NOT count as an access (recency is unchanged). Purges if expired. */
+    has(key: K): boolean;
+    delete(key: K): boolean;
+    clear(): void;
+    /** Current entry count (may include not-yet-evicted expired entries). */
+    get size(): number;
+    /** Current aggregate reported weight (bytes) across all entries. */
+    get weightBytes(): number;
+}
+
+/**
+ * Metrics seam (Phase 5a) — an injected sink the engine pushes typed events
+ * to, exactly like the `Clock`/`Rng`/driver seams keep `core/` pure and storage-agnostic.
+ *
+ * Design: the library emits **neutral domain events** and stays vendor-agnostic — you (or a ~12-line
+ * adapter) map them to OpenTelemetry / Datadog / a log line. The default is a **no-op**, and emission is
+ * skipped entirely when no sink is wired (near-zero overhead, no telemetry dependency). Events carry **raw
+ * observations** (bytes, counts, ms); turning those into billable units / dollars is the cost model's job
+ * (Phase 5b), which keeps rates pluggable.
+ *
+ * Two caveats for sink authors: `onEvent` runs **synchronously on the I/O path**, so keep it cheap and
+ * non-blocking (offload batching/network to your own async queue); and `segment`/`namespace` are
+ * caller-controlled strings that may be PII and are **unbounded-cardinality** — do not map them to
+ * per-series metric labels unless they're known low-cardinality and PII-free. See the getting-started
+ * "Observability" section.
+ */
+/** The segment operations that emit an `op` latency event (timed with the injected clock, at the facade). */
+type MetricOpName = 'add' | 'remove' | 'addMany' | 'removeMany' | 'has' | 'count' | 'intersectInto';
+/**
+ * One observability event. A discriminated union on `kind` — new variants can be added over time without
+ * breaking consumers (they switch on the kinds they care about). `namespace` is the segment's namespace
+ * (absent ⇒ the default namespace). Segment names are identifiers, never bitmap contents (threat model:
+ * never log PII / bitmap bits).
+ */
+type MetricEvent = {
+    readonly kind: 'cold.get';
+    readonly namespace?: string;
+    readonly segment: string;
+    /** Bytes returned (0 if the chunk was absent — a GET still happened). */
+    readonly bytes: number;
+    /**
+     * Elapsed wall time of the read — includes any transient-retry backoff on the cold call. From the
+     * injected clock, clamped to ≥ 0 (0 under the no-wait test clock).
+     */
+    readonly ms: number;
+} | {
+    readonly kind: 'cache';
+    readonly hit: boolean;
+} | {
+    readonly kind: 'warm.read';
+    readonly namespace?: string;
+    readonly segment: string;
+    /** Bytes read — a single-row get, or the summed rows of a list scan. */
+    readonly bytes: number;
+} | {
+    readonly kind: 'warm.write';
+    readonly namespace?: string;
+    readonly segment: string;
+    /** Bytes of the committed delta row (emitted only on a successful conditional write). */
+    readonly bytes: number;
+} | {
+    readonly kind: 'retry';
+    /** `occ` = optimistic-concurrency conflict backoff; `transient` = infrastructure-fault backoff. */
+    readonly reason: 'occ' | 'transient';
+    /** 1-based number of the attempt about to be retried. */
+    readonly attempt: number;
+    readonly delayMs: number;
+} | {
+    readonly kind: 'intersect';
+    readonly operands: number;
+    /** Shared **distinct** chunk-keys selected to fetch (present in every operand). */
+    readonly fetchedChunks: number;
+    /**
+     * **Distinct** chunk-keys pruned — never fetched (the chunk-skipping saving). Counts distinct keys,
+     * not per-operand GETs, so it under-states the true GET saving when 3+ operands partially overlap.
+     */
+    readonly skippedChunks: number;
+} | {
+    readonly kind: 'compaction';
+    readonly namespace?: string;
+    readonly segment: string;
+    /** True iff this call committed a new generation. */
+    readonly compacted: boolean;
+    /** Why nothing was committed (when `compacted` is false) — the `CompactionResult.reason` (Phase D). */
+    readonly reason?: string;
+    /** Dirty Warm chunks pinned at scan time. */
+    readonly dirtyChunks: number;
+    /** Archived Warm rows actually purged (≤ dirtyChunks). */
+    readonly purged: number;
+    /** Elapsed wall time of the attempt (injected clock, ≥ 0; 0 under the no-wait test clock). */
+    readonly ms: number;
+} | {
+    readonly kind: 'op';
+    readonly name: MetricOpName;
+    readonly ms: number;
+};
+/**
+ * The sink you plug in. One method, synchronous, fire-and-forget. It must never throw back into the
+ * caller — `CloudRoaring` wraps a user sink with {@link safeMetrics} so a buggy sink can't break I/O.
+ */
+interface IMetricsSink {
+    onEvent(event: MetricEvent): void;
+}
+/** The default sink: discards everything, zero overhead. Used whenever no sink is wired. */
+declare const NOOP_METRICS: IMetricsSink;
+/**
+ * Wrap a sink so a throwing/buggy `onEvent` can never break the data path — observability is strictly
+ * best-effort. `CloudRoaring` applies this to the user-supplied sink at construction.
+ */
+declare function safeMetrics(sink: IMetricsSink): IMetricsSink;
+/** Accumulated totals — the shape returned by {@link CountingMetricsSink.snapshot}. */
+interface MetricsSnapshot {
+    readonly cold: {
+        readonly gets: number;
+        readonly bytes: number;
+        readonly totalMs: number;
+    };
+    readonly warm: {
+        readonly reads: number;
+        readonly readBytes: number;
+        readonly writes: number;
+        readonly writeBytes: number;
+    };
+    readonly cache: {
+        readonly hits: number;
+        readonly misses: number;
+    };
+    readonly retries: {
+        readonly occ: number;
+        readonly transient: number;
+    };
+    readonly intersect: {
+        readonly calls: number;
+        readonly fetchedChunks: number;
+        readonly skippedChunks: number;
+    };
+    readonly compaction: {
+        readonly attempts: number;
+        readonly committed: number;
+        readonly dirtyChunks: number;
+        readonly purged: number;
+        readonly totalMs: number;
+    };
+    readonly ops: Readonly<Record<MetricOpName, {
+        readonly count: number;
+        readonly totalMs: number;
+    }>>;
+}
+/**
+ * A ready-made sink that tallies events into a {@link MetricsSnapshot} — handy for tests, quick scripts,
+ * and (Phase 5b) as the grounded-request-cost source behind `costReport()`. `snapshot()` returns an
+ * independent copy; `reset()` zeroes the counters.
+ */
+declare class CountingMetricsSink implements IMetricsSink {
+    private cold;
+    private warm;
+    private cache;
+    private retries;
+    private intersect;
+    private compaction;
+    private ops;
+    private static zeroOps;
+    onEvent(event: MetricEvent): void;
+    snapshot(): MetricsSnapshot;
+    reset(): void;
+}
+
+/**
+ * `withRetry` — the one retry/backoff primitive.
+ *
+ * A pure, storage-agnostic helper: it knows nothing about HTTP, AWS, or any SDK. It retries an operation
+ * while the operation keeps failing with a **retryable** error (by default {@link TransientError}), waiting
+ * a bounded, jittered, exponentially-growing delay between attempts. Time and randomness are **injected**
+ * (the determinism seam) — production wires a `setTimeout`-backed clock + a real RNG; the
+ * simulator wires virtual ones — so a backoff schedule is replayable from a seed and unit tests run with no
+ * real sleeping.
+ *
+ * It deliberately does **not** retry deterministic failures ({@link WriteConflictError},
+ * {@link ValidationError}, {@link IntegrityError}, {@link NotFoundError}, …): retrying those either can't
+ * help or would be incorrect. OCC conflicts are retried by a *separate* loop (the engine's read-modify-write)
+ * because each retry must re-read and re-apply, not blindly replay the same call.
+ */
+
+interface RetryPolicy {
+    /** Total attempts including the first (so `maxAttempts: 4` = 1 try + 3 retries). Must be ≥ 1. */
+    readonly maxAttempts: number;
+    /** Delay before the first retry, in ms. Grows by `backoffFactor` each subsequent retry. */
+    readonly baseDelayMs: number;
+    /** Upper bound on a single (pre-jitter) delay, in ms — caps the exponential growth. */
+    readonly maxDelayMs: number;
+    /** Exponential growth factor between retries (e.g. 2 ⇒ base, 2·base, 4·base, …). */
+    readonly backoffFactor: number;
+    /**
+     * `'full'` ⇒ the actual wait is uniform in `[0, computed]` (AWS-recommended full jitter: decorrelates
+     * concurrent retriers so they don't reconverge into a thundering herd). `'none'` ⇒ wait exactly `computed`.
+     */
+    readonly jitter: 'full' | 'none';
+}
+/**
+ * Conservative defaults: 4 attempts, 50ms → 100 → 200 (×2), capped at 2s, full jitter. Tuned for a cloud
+ * backend's brief throttle/5xx blip — enough to ride out a transient fault without turning a hard outage
+ * into a long hang. Override per store/driver if your latency budget differs.
+ */
+declare const DEFAULT_RETRY_POLICY: RetryPolicy;
+/** Backoff for the engine's OCC conflict loop — local contention resolves fast, so smaller + tighter. */
+declare const DEFAULT_OCC_BACKOFF: RetryPolicy;
+interface RetryDeps {
+    readonly clock: Clock;
+    readonly rng: Rng;
+    /** Override which errors are retryable. Default: any {@link TransientError} (incl. `TimeoutError`). */
+    readonly isRetryable?: (err: unknown) => boolean;
+    /** Optional hook (observability) fired before each backoff wait. `attempt` is 1-based (the one that failed). */
+    readonly onRetry?: (info: {
+        attempt: number;
+        delayMs: number;
+        err: unknown;
+    }) => void;
+}
+/** Default classifier: retry transient infrastructure faults only. */
+declare function isTransient(err: unknown): boolean;
+/**
+ * Run `op`, retrying transient failures per `policy`. Resolves with `op`'s result, or rejects with the last
+ * error once attempts are exhausted (or immediately for a non-retryable error). The thrown error is always
+ * the *operation's* error — never a wrapper — so callers keep their typed-error branching.
+ */
+declare function withRetry<T>(op: () => Promise<T>, policy: RetryPolicy, deps: RetryDeps): Promise<T>;
+
+interface EngineDeps {
+    readonly warm: IWarmDriver;
+    readonly cold: ColdChunkSource;
+    /** Optional HOT cache of decoded (immutable) Cold chunks. */
+    readonly cache?: BoundedLru<string, CodecBitmap>;
+    readonly maxBitmapBytes?: number;
+    /**
+     * The bitmap codec (DECISIONS #58) — **required**. `core/` is
+     * codec-agnostic: it can have no default, because the concrete codec lives in a *flavor* package that depends
+     * on core (a default here would invert that arrow). A flavor's facade injects it — `@cloudbitmaps/roaring`
+     * passes `roaringCodec` — so applications never see this.
+     */
+    readonly codec: CodecInterface;
+    readonly maxRetries?: number;
+    /** Injected for jittered OCC backoff + replayable tests; defaults to an instant clock / zero RNG. */
+    readonly clock?: Clock;
+    readonly rng?: Rng;
+    /** Backoff schedule between OCC conflict retries; defaults to {@link DEFAULT_OCC_BACKOFF}. */
+    readonly occBackoff?: RetryPolicy;
+    /** Observability sink (Phase 5a); defaults to a no-op. Assumed exception-safe (the facade wraps it). */
+    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 RCU (gap #9). The OCC
+     * read-modify-write path is always strong regardless (correctness).
+     */
+    readonly warmReadConsistency?: 'strong' | 'eventual';
+    /**
+     * Max Warm chunk writes in flight per `addMany`/`removeMany` (the bounded flusher). Default **1** (serial —
+     * unchanged behavior). Higher values fan out distinct-chunk writes for throughput; each chunk is its own OCC
+     * row, so bounded concurrency is safe (`addMany` is already non-atomic on partial failure).
+     */
+    readonly writeConcurrency?: number;
+    /**
+     * Per-op denial-of-wallet budget (07 Decision #3 / T3), already resolved by the facade: a {@link Budget} to
+     * enforce, or `null` to disable. Undefined ⇒ {@link DEFAULT_BUDGET} (a direct engine construction still gets
+     * the generous default). Read ops refuse before fan-out if they'd exceed it.
+     */
+    readonly budget?: Budget | null;
+}
+declare class SegmentEngine {
+    private readonly warm;
+    private readonly cold;
+    private readonly cache;
+    private readonly codec;
+    private readonly maxBitmapBytes;
+    private readonly maxRetries;
+    private readonly clock;
+    private readonly rng;
+    private readonly occBackoff;
+    private readonly metrics;
+    private readonly metricsOn;
+    /** Consistency for READ-path Warm fetches (precomputed; OCC RMW passes strong explicitly, see `warmGet`). */
+    private readonly readOpts;
+    private readonly writeConcurrency;
+    /** Resolved per-op budget (null = disabled); undefined deps ⇒ the generous default. See {@link checkBudget}. */
+    private readonly budget;
+    constructor(deps: EngineDeps);
+    add(seg: SegmentRef, id: number): Promise<void>;
+    remove(seg: SegmentRef, id: number): Promise<void>;
+    addMany(seg: SegmentRef, ids: Iterable<number>): Promise<void>;
+    removeMany(seg: SegmentRef, ids: Iterable<number>): Promise<void>;
+    has(seg: SegmentRef, id: number, opts?: WarmReadOptions): Promise<boolean>;
+    count(seg: SegmentRef): Promise<number>;
+    /** Whether the Cold source can measure segment size (for grounded cost); false ⇒ storage isn't grounded. */
+    get supportsColdSize(): boolean;
+    /** Grounded Cold size of a segment's current generation (cost reporting), or null if it has no generation. */
+    segmentSize(seg: SegmentRef): Promise<SegmentSize | null>;
+    iterate(seg: SegmentRef): AsyncGenerator<number>;
+    /**
+     * Chunk-skipping intersection. Computes
+     * `seg[0] ∩ seg[1] ∩ …` and streams the result ids ascending. It aligns each segment's *effective*
+     * chunk-key set (Warm ∪ Cold), keeps only keys present in **all** operands (a key missing from any
+     * operand can't contribute → its **Cold chunks are never fetched** — the core saving), then for each
+     * surviving key merges tiers per operand (operand fetches run in parallel) and hands the buffers to the
+     * roaring engine for the AND, streaming results through a bounded in-flight window.
+     *
+     * **Memory:** the Cold payload footprint is bounded by the window (`concurrency × operands × chunk`), not
+     * by segment size — that's the Lambda-friendly property. The **Warm** side, however, is snapshotted up
+     * front (`collectWarm` per operand), so total memory also carries each operand's Warm size. Under
+     * Topology-A (read-mostly; compaction keeps Warm small) that's negligible; a streaming Warm/Cold
+     * merge-join for large Warm is Phase 4.
+     *
+     * Generation-consistent within the call (normal case): each operand's current generation is resolved **once**
+     * up front (before the fan-out) and threaded into every chunk read, so a concurrent compaction can't corrupt
+     * or tear the result — every chunk read is a whole, checksum-verified, immutable generation (finding C10).
+     * The edge a *long* call can hit: if it straddles a mid-call `coldGenTtlMs` boundary and a compaction has
+     * committed, an operand's not-yet-read chunks may re-resolve forward to the newer generation (a generation
+     * hop within one long call) — the call never crashes or returns a torn object, but may mix generations. That
+     * window is a single TTL (default 2 s), not the multi-cycle GC-sweep window it took pre-Phase-B. A shorter call
+     * is unaffected **unless the reader cache evicts an operand mid-call** (`maxOpenSegments`, gap #1): the re-read
+     * re-resolves fresh (bypassing the TTL), which can hop generations even sub-TTL — still whole/immutable per
+     * read, never torn. Full intra-op snapshot isolation is deferred (gap #4).
+     */
+    intersect(segs: readonly SegmentRef[], options?: {
+        concurrency?: number;
+        budget?: BudgetOption;
+    }): AsyncGenerator<number>;
+    /**
+     * The AND of one chunk key across all operands (tier-merged per operand), or `null` if empty. Operand
+     * chunks are fetched **in parallel** (the spec's parallel byte-range reads). `acc` takes ownership of the
+     * first operand's effective chunk and mutates it in place — safe because `effectiveChunk` always returns
+     * a FRESH bitmap (never a cached/shared Cold instance), so this can't poison the HOT cache.
+     */
+    private intersectChunk;
+    /**
+     * Materialize `seg[0] ∩ seg[1] ∩ …` into `dest` via batched `addMany` (streaming, bounded memory).
+     * **Not atomic** — like `addMany`, ids land chunk-by-chunk; a failure mid-stream leaves a partial result.
+     * `dest` is added to, not replaced.
+     */
+    intersectInto(dest: SegmentRef, segs: readonly SegmentRef[], options?: {
+        concurrency?: number;
+        batchSize?: number;
+    }): Promise<void>;
+    private mutateMany;
+    /** OCC read-modify-write on a chunk's Warm delta, retrying on conflict (bounded). */
+    private readModifyWrite;
+    /** `warm.get` + a `warm.read` metric (read bytes = the row size, 0 if absent). */
+    private warmGet;
+    private collectWarm;
+    private chunkKeys;
+    /**
+     * Tier-derived keys are untrusted (invariant 5) — fail fast on a corrupt/out-of-range key rather than
+     * letting it flow into `joinId` and produce a bogus id.
+     */
+    private assertChunkKeyInRange;
+    private effectiveChunk;
+    /** The segment's current generation, resolved once per op (`undefined` ⇒ source can't report it). */
+    private currentGen;
+    /**
+     * Decode a Cold chunk. `gen` is the segment's current generation, resolved **once per op** by the caller (not
+     * per chunk — that would put a registry re-resolve on every chunk of a count/intersect). The HOT cache is
+     * keyed by it (gap #4), so a compaction that advances the generation misses the cache and re-reads the new
+     * bytes instead of serving a stale decoded chunk (an erased id can't resurrect from a cached pre-compaction
+     * chunk). `gen === null` ⇒ the source reports no current generation ⇒ no cold bytes for any chunk, so skip the
+     * fetch entirely (also avoids a redundant re-resolve on the warm-only path). `gen === undefined` ⇒ the source
+     * can't report a generation (pins one for its lifetime) ⇒ the key stays generation-free (unchanged behaviour).
+     * Superseded-generation entries age out under the LRU ceiling — no active purge.
+     */
+    private coldChunk;
+}
+
+/** Pluggable rate card. Rates differ by cloud/region/term and drift over time; the formulas don't. */
+interface PricingProfile {
+    readonly name: string;
+    readonly cold: {
+        /** S3 GET (per **million** requests). A ranged GET bills as a full GET. */
+        readonly getPerMillion: number;
+        /** S3 PUT (per million). */
+        readonly putPerMillion: number;
+        readonly storagePerGiBMonth: number;
+    };
+    readonly warm: {
+        /** DynamoDB read-request-units (per million). */
+        readonly rruPerMillion: number;
+        /** DynamoDB write-request-units (per million). **0 models a provisioned/flat tier** (no per-write charge). */
+        readonly wruPerMillion: number;
+        /** KiB billed per read unit (DynamoDB: 4). */
+        readonly readUnitKiB: number;
+        /** KiB billed per write unit (DynamoDB: 1 — the write cost driver). */
+        readonly writeUnitKiB: number;
+        readonly storagePerGiBMonth: number;
+        /** Strongly-consistent reads bill 1 RRU/unit; eventually-consistent bill 0.5. */
+        readonly stronglyConsistent: boolean;
+    };
+    /** The always-on baseline to compare against (e.g. an ElastiCache HA cluster). */
+    readonly redis: {
+        readonly monthlyUSD: number;
+    };
+}
+/**
+ * Default profile — **AWS us-east-1, on-demand**, mid-2026, from the fact-checked
+ * published pricing rather than copied from a blog post. Override it for your region, cloud, or committed term.
+ */
+declare const AWS_US_EAST_1_ONDEMAND: PricingProfile;
+declare const DEFAULT_PRICING: PricingProfile;
+/** Which write path is live. `A` = Hot+Cold read-mostly (writes via bulk-load); `B` = live Warm writes. */
+type Topology = 'A' | 'B';
+/** Sustained access pattern. All rates default to 0; unspecified ⇒ that op contributes nothing. */
+interface Workload {
+    readonly readsPerSec?: number;
+    readonly writesPerSec?: number;
+    readonly intersectsPerSec?: number;
+    /** HOT-cache hit rate in `[0, 1]` — hits are free; only misses cost. Default 0. */
+    readonly cacheHitRate?: number;
+    /** Avg serialized chunk/item size (KiB) — drives read/write units. Default 8 (a full roaring bitmap container). */
+    readonly avgItemKiB?: number;
+    /** Cold chunks fetched per intersection (the chunk-skipping survivors). Default 1. */
+    readonly chunksPerIntersect?: number;
+    /**
+     * Compaction cycles per month across the modeled data (gap #10). Default **0** ⇒ compaction is not modeled
+     * and the report *discloses* the omission (rather than silently under-reporting). Set it to fold in the
+     * background job that usually dominates operational cost.
+     */
+    readonly compactionsPerMonth?: number;
+    /**
+     * Cold chunks re-read per compaction cycle — the whole generation (clean chunks are copied through, 1 GET
+     * each). Default: derived from `coldBytes / avgItemKiB` (i.e. the whole modeled cold set is one generation —
+     * exact for a single-segment/grounded report; for a multi-segment fleet set this to your *per-segment* chunk
+     * count). This whole-generation re-read is the dominant compaction term.
+     */
+    readonly chunksPerCompaction?: number;
+    /** Dirty Warm rows purged per compaction — the secondary RRU-read + WRU-delete term. Default 0. */
+    readonly dirtyChunksPerCompaction?: number;
+}
+/** One (group of) segment(s) for planning. `count` = how many like this (default 1). */
+interface SegmentSizing {
+    readonly sizeBytes?: number;
+    readonly cardinality?: number;
+    /** Number of segments with these characteristics. Default 1. */
+    readonly count?: number;
+}
+interface EstimateInput {
+    readonly segments: readonly SegmentSizing[];
+    readonly workload?: Workload;
+    readonly topology?: Topology;
+    readonly pricing?: PricingProfile;
+}
+/**
+ * A self-relative cost hint. See {@link CostReport.advisories}.
+ *
+ * `code` is the stable, machine-readable identity — branch on it rather than parsing `message`.
+ */
+interface CostAdvisory {
+    /**
+     * `'batchable-writes'` — the modeled write count far exceeds the number of distinct Warm rows the data can
+     * occupy, so each row is being rewritten many times over. If those ids ever arrive together, `addMany()`
+     * collapses them to one write per chunk and bulk-load writes Cold directly.
+     */
+    readonly code: 'batchable-writes';
+    /** Human-readable, safe to log or print. Carries the numbers that triggered it. */
+    readonly message: string;
+    /** The modeled cost of the term this advisory is about (USD/month). */
+    readonly currentUSD: number;
+    /**
+     * A **floor**, not a promise: the same term if the writes were perfectly batched into one write per distinct
+     * Warm row. Real batching lands between this and {@link CostAdvisory.currentUSD}, depending on how the ids
+     * actually arrive — which the estimator cannot know.
+     */
+    readonly batchedFloorUSD: number;
+}
+interface CostReport {
+    readonly monthlyUSD: {
+        readonly byTier: {
+            readonly hot: number;
+            readonly warm: number;
+            readonly cold: number;
+        };
+        readonly byOp: {
+            readonly reads: number;
+            readonly writes: number;
+            readonly intersects: number;
+            readonly storage: number;
+            /** Background compaction (whole-generation re-read + PUT + Warm purge). 0 unless `compactionsPerMonth` is set. */
+            readonly compaction: number;
+        };
+        readonly total: number;
+    };
+    /**
+     * Sustained rate at which the pay-per-use model's cost passes the flat Redis baseline (per axis, the other
+     * at 0), **evaluated at this report's `cacheHitRate` + `avgItemKiB`** — so a higher cache-hit rate raises
+     * `readsPerSec` (cache hits are free). `Infinity` means that axis never crosses (e.g. a flat/provisioned
+     * tier, or a 100% cache-hit rate). The published anchors (~26 writes/s, ~329 reads/s) are at `cacheHitRate: 0`.
+     */
+    readonly redisCrossover: {
+        readonly writesPerSec: number;
+        readonly readsPerSec: number;
+    };
+    readonly verdict: 'win-big' | 'win' | 'lose-zone';
+    readonly rationale: string;
+    /**
+     * Zero or more **self-relative** hints: places this workload is paying more than *this same library* would
+     * charge for the same outcome. Distinct from {@link CostReport.verdict}, which only compares against the flat
+     * Redis baseline — a workload can beat Redis by 40× and still be 100× more expensive than it needs to be, and
+     * the verdict alone would call that `win-big` and say nothing.
+     *
+     * Empty is the normal case. Advisories never change the dollar figures; they are additive commentary, and each
+     * carries a machine-readable {@link CostAdvisory.code} so consumers don't string-match.
+     */
+    readonly advisories: readonly CostAdvisory[];
+    readonly assumptions: {
+        readonly cacheHitRate: number;
+        readonly pricingName: string;
+        /** True when segment **sizes** were real (grounded `costReport`), false for a pure `estimateCost`. */
+        readonly grounded: boolean;
+        readonly topology: Topology;
+        readonly notes: readonly string[];
+    };
+}
+/**
+ * **Planning** cost estimate — pure, no instance or live data needed (sizing, sales, what-if). Segment sizes
+ * are taken as given (or roughly derived from cardinality); use the grounded `segment.costReport()` for
+ * exact, real sizes. See {@link CostReport}.
+ */
+declare function estimateCost(input: EstimateInput): CostReport;
+/**
+ * **Grounded** report from a real segment byte total (from the `.crbm` index) + a supplied workload. Used by
+ * `Segment.costReport()` in `index.ts`. `grounded` defaults to true (the size is exact, not estimated); the
+ * caller passes `grounded: false` + a note when the Cold source can't measure size.
+ */
+declare function groundedReport(input: {
+    readonly coldBytes: number;
+    readonly grounded?: boolean;
+    readonly workload?: Workload;
+    readonly topology?: Topology;
+    readonly pricing?: PricingProfile;
+    readonly extraNotes?: readonly string[];
+    /**
+     * Hard upper bound on distinct Warm rows, for the advisories. Defaults to {@link CHUNK_COUNT} — this models
+     * ONE segment, and a 16-bit chunk key caps a segment there. `SegmentSize` carries only `sizeBytes` today, so
+     * an exact per-segment chunk count would need a driver-interface change; the id-space cap needs nothing and is
+     * sound in the safe direction (it can only make the advisory quieter).
+     */
+    readonly maxWarmRows?: number;
+}): CostReport;
+
+/**
+ * Audit sink (Phase 5d) — an injected, no-op-by-default seam for **security/compliance** events, distinct
+ * from the metrics sink (5a). Different audience (an audit log / SIEM, not a dashboard), different retention,
+ * and only the compliance-relevant *state changes* — never routine reads/writes (that's the metrics sink).
+ * It doubles as the GDPR Art. 30 "record of processing" surface: publishes, compactions, and erasures.
+ *
+ * Like `Clock`/`Rng`/`IMetricsSink`, it's injected (into the lifecycle operations that emit — compaction,
+ * bulk-load, erasure) and wrapped exception-safe, so a buggy sink can never break the operation it observes.
+ * Events are vendor-neutral and carry no timestamp/actor — the sink runs synchronously at the event, so it
+ * stamps its own time / attaches the caller identity (keeps `core/` free of ambient time). As with metrics,
+ * `segment`/`namespace` are caller-controlled strings that may be PII — treat them accordingly when routing.
+ *
+ * Not (yet) emitted: **KEK rotation** — rotation here is operator-side keystore reconfiguration (key-id-tagged
+ * wrappings, no data re-encryption), so there is no library call to hook. A future `rewrapSegment()` op would
+ * add a `kek.rotate` variant; until then, audit key changes at your keystore-config layer.
+ */
+/** A security/compliance-relevant state change. Vendor-neutral; the sink adds its own timestamp/actor. */
+type AuditEvent = {
+    /** A new immutable Cold generation *became the segment's current generation* (via bulk-load publish). */
+    readonly kind: 'segment.publish';
+    readonly namespace?: string;
+    readonly segment: string;
+    readonly generation: number;
+} | {
+    /** Compaction committed a new generation (emitted at the durable commit, before Warm-row purge). */
+    readonly kind: 'segment.compact';
+    readonly namespace?: string;
+    readonly segment: string;
+    readonly generation: number;
+} | {
+    /**
+     * A segment was **crypto-shredded** — its wrapped DEK(s) are gone, so its at-rest Cold bytes are now
+     * permanently unreadable. Emitted only for a genuine key shred, never for a cleartext tombstone (which
+     * leaves the Cold bytes readable) or an idempotent re-run.
+     */
+    readonly kind: 'segment.erase';
+    readonly namespace?: string;
+    readonly segment: string;
+} | {
+    /** A namespace erasure was executed. `segmentsShredded` is the count actually crypto-shredded (may be 0). */
+    readonly kind: 'namespace.erase';
+    readonly namespace: string;
+    readonly segmentsShredded: number;
+};
+/** The `kind` discriminant of an {@link AuditEvent}. */
+type AuditEventKind = AuditEvent['kind'];
+/** Sink for {@link AuditEvent}s. Injected via the lifecycle options; the default is {@link NOOP_AUDIT}. */
+interface IAuditSink {
+    onEvent(event: AuditEvent): void;
+}
+/** The default sink: records nothing. */
+declare const NOOP_AUDIT: IAuditSink;
+/** A ready-made sink that records events into an in-memory list — handy for tests + simple audit trails. */
+declare class RecordingAuditSink implements IAuditSink {
+    private readonly recorded;
+    onEvent(event: AuditEvent): void;
+    /** An independent copy of the recorded events, in emission order. */
+    snapshot(): AuditEvent[];
+    reset(): void;
+}
+
+/**
+ * Crash-safe compaction — the 2-phase commit that folds Warm deltas into a fresh immutable Cold generation
+ * (invariants I3/I4/I5).
+ *
+ * Memory (Phase 4f): a generation is merged **and written as a stream** — {@link mergeChunksStream} yields one
+ * merged chunk at a time and {@link writeCrbmGenerationStream} feeds each to a streaming cold sink (S3 multipart
+ * / LocalFs temp file), freeing it. The cold generation is merged and written as a stream, so peak COLD-side
+ * memory is ~one chunk + one upload part + the cold reader's index. Caveat: `collectDirty` first materializes
+ * the whole dirty Warm delta set in memory, so total peak also scales with the dirty-warm working set (up to a
+ * whole segment for an all-warm/never-compacted segment) — pinning only `{chunkKey,token}` + lazy re-read is a
+ * deferred fix (gap #12).
+ *
+ * The algorithm, per chunk: `newCold(k) = (cold_g(k) ∪ adds(k)) \ removes(k)` — exactly the read-time
+ * effective set ({@link effective}), so the segment's visible set is unchanged (**I3**). Steps:
+ *
+ *   1. LEASE   acquire the per-segment compaction lease (status→compacting; steal an expired one)
+ *   2. PIN     g := registry.currentGen; archive each dirty chunk's OCC token (`v_archived`)
+ *   3. RECONCILE delete orphan Cold generations > g (a crashed prior stage), safe under the lease
+ *   4. MERGE   build gen g+1: dirty chunks merged, clean chunks copied through
+ *   5. STAGE   write segment.<g+1>.crbm (immutable, write-once)
+ *   6. VERIFY  re-open it; its chunk-key set + footer cardinality must equal the merge (+ the codec's CRC checks)
+ *   7. SWAP    registry.currentGen := g+1, release the lease — CONDITIONAL on the lease token (atomic commit)
+ *   8. PURGE   delete each archived Warm row CONDITIONAL on token == v_archived (a write after the scan has a
+ *              newer token → its purge fails → it survives into the next dirty set: **no lost writes, I4**)
+ *
+ * **Correctness without a lock:** the commit is the conditional `currentGen` swap; write-once generations +
+ * version-fenced purge make even two concurrent compactions safe (the loser's staged generation is an orphan
+ * GC'd later; no torn read — readers are pinned to a committed generation, **I5**). The lease only avoids that
+ * wasted duplicate work (see DECISIONS #18).
+ *
+ * Pure orchestration over the injected driver interfaces + an injected {@link Clock} (timer-free; the daemon
+ * layer owns scheduling/heartbeat). A crash at *any* step is recoverable: nothing is destructive until after
+ * the commit, and the swap is atomic.
+ */
+
+interface CompactionDeps {
+    readonly cold: IColdDriver;
+    readonly warm: IWarmDriver;
+    readonly registry: IRegistryDriver;
+    /** Injected time source for lease expiry (the determinism seam — `core/` never reads ambient time). */
+    readonly clock: Pick<Clock, 'now'>;
+    readonly maxBitmapBytes?: number;
+    /**
+     * Bitmap codec ([DECISIONS #58]) — compaction only merges bitmaps through it. Optional in the type so this
+     * stays call-compatible public API; a **flavor** package binds it (see {@link requireCodec}).
+     */
+    readonly codec?: CodecInterface;
+    /**
+     * Keystore for **encrypted** segments (Phase 4e). An encrypted segment (its registry record carries wrapped
+     * DEK(s)) reuses that same DEK: compaction unwraps it to decrypt the old generation and encrypt the new one.
+     * A bootstrap (gen 0) with a keystore mints a fresh DEK. Compacting an encrypted segment without a keystore
+     * throws {@link KeyUnavailableError}. Absent ⇒ cleartext compaction (unless {@link requireEncryption}).
+     */
+    readonly keystore?: IKeystore;
+    /** When true, refuse to write a cleartext generation — a segment without a keystore-backed DEK throws. */
+    readonly requireEncryption?: boolean;
+    /**
+     * Optional observability sink (Phase D, gap #2). `compactSegment` emits one `compaction` event per attempt
+     * (committed or not, timed). Assumed exception-safe (the `CloudRoaring` facade wraps the user sink); the emit
+     * is additionally guarded so a throwing sink can never break compaction. Absent ⇒ no emission.
+     */
+    readonly metrics?: IMetricsSink;
+}
+interface CompactionOptions {
+    /** Opaque id of this worker — the lease owner (e.g. `host:pid:uuid`). Required so a steal is attributable. */
+    readonly owner: string;
+    /** Lease duration in ms (default 60s). */
+    readonly leaseMs?: number;
+    /**
+     * Optional audit sink (Phase 5d). A `segment.compact` event is emitted once per **committed** generation
+     * (never on a no-op/contention path). Exception-safe; the default records nothing.
+     */
+    readonly audit?: IAuditSink;
+}
+interface CompactionResult {
+    readonly segment: string;
+    readonly namespace?: string;
+    /** True iff a new generation was committed. */
+    readonly compacted: boolean;
+    /**
+     * Why nothing was committed, when `compacted` is false: `'clean'` (no dirty rows), `'leased-by-other'`
+     * (a live lease elsewhere), `'lease-lost'` (our lease was stolen before the commit — staged gen is an
+     * orphan, no rows purged), `'superseded'` (a concurrent publish/bulk-load advanced `currentGen` past the
+     * generation we pinned — we abort so RECONCILE never deletes the just-published generation; the next cycle
+     * re-pins the new current gen; gap #5), `'bootstrap-raced'` (another worker wrote gen 0; our rows are left
+     * for the next compaction), `'stage-conflict'` (a generation write-conflict we couldn't reconcile),
+     * `'destroyed'` (the segment was crypto-shredded — terminal), or `'error'` (an isolated per-segment fault
+     * recorded by {@link runCompactionCycle}).
+     */
+    readonly reason?: string;
+    /** The fault message when `reason === 'error'` (a per-segment failure isolated by {@link runCompactionCycle}). */
+    readonly error?: string;
+    readonly fromGen: number | null;
+    readonly toGen?: number;
+    readonly dirtyChunks: number;
+    /** Archived Warm rows actually purged (≤ dirtyChunks; the rest were rewritten post-scan and survive). */
+    readonly purged: number;
+    readonly survived: number;
+}
+/**
+ * Fail fast on bad lease config at the boundary: an empty owner makes a lease steal unattributable, and a
+ * non-positive/NaN leaseMs would produce a lease that's already expired (or never), silently defeating the
+ * lease's whole job. Cheap to check once, up front, so a misconfigured daemon errors immediately. Exported so
+ * callers that mutate **before** compacting (e.g. `CloudRoaring.eraseSubject`, which writes a `remove` tombstone
+ * first) can validate the options up front rather than after the tombstone is written.
+ */
+declare function validateCompactionOptions(options: CompactionOptions): void;
+/**
+ * Compact one segment. A no-op (returns `compacted: false`) if it has no dirty Warm rows or another worker
+ * holds a live lease. Never throws on the normal contention/lease-loss paths — those are reported in `reason`.
+ * Emits a `compaction` metric event per attempt (Phase D, gap #2) when a sink is wired, timing the attempt.
+ */
+declare function compactSegment(ref: SegmentRef, deps: CompactionDeps, options: CompactionOptions): Promise<CompactionResult>;
+/**
+ * Garbage-collect superseded Cold generations for a segment: everything strictly below `currentGen`, keeping
+ * the most recent `keep` of them as a grace window for in-flight readers pinned to a just-superseded
+ * generation (**I5**). Generations ≥ `currentGen` are never touched. Returns the generations deleted.
+ */
+declare function gcOrphanGenerations(ref: SegmentRef, deps: Pick<CompactionDeps, 'cold' | 'registry'>, options?: {
+    keep?: number;
+}): Promise<number[]>;
+interface DiscoveryOptions {
+    /** Scope discovery to one namespace (registry `list(namespace)`). */
+    readonly namespace?: string;
+    /** Minimum dirty Warm rows for a segment to be a candidate (default 1). */
+    readonly threshold?: number;
+    /**
+     * Extra segments to consider beyond the registry's known set. Discovery enumerates `registry.list()`, which
+     * only contains segments that have a committed generation — a brand-new **all-warm** segment isn't there
+     * yet, so name it here (or bulk-load it once) for the daemon to pick it up.
+     */
+    readonly candidates?: readonly SegmentRef[];
+    /**
+     * Shard this worker's slice of the fleet (gap #3). With `totalShards > 1`, discovery considers only segments
+     * whose **stable hash** (FNV-1a of the segment key, mod `totalShards`) falls in `shard` (0-based). Run N
+     * daemons with `{ shard: i, totalShards: N }` to partition the fleet N ways — each **drains and compacts** only
+     * its ~1/N of segments per cycle. NB: the registry enumeration + in-memory candidate set stay O(total segments)
+     * per worker (the hash needs the key, which only the scan yields); only the Warm drain + compaction shard. The
+     * O(dirty) indexed-enumeration seam that would shard the scan too is deferred (gap #3). Default: handle all.
+     */
+    readonly shard?: number;
+    readonly totalShards?: number;
+    /**
+     * Poison-segment quarantine (gap #2): a segment whose `consecutiveFailures` has reached this threshold is
+     * skipped by discovery (not even drained) until `quarantineCooldownMs` since its last registry update has
+     * elapsed — then it's retried once (a transient fault self-heals; a persistent one re-quarantines). Default 5.
+     */
+    readonly quarantineThreshold?: number;
+    /** Cooldown (ms) before a quarantined segment is retried once (default 5 min). */
+    readonly quarantineCooldownMs?: number;
+}
+interface CompactionCandidate {
+    readonly ref: SegmentRef;
+    readonly dirtyChunks: number;
+    readonly currentGen: number | null;
+    /** Epoch-ms of the segment's last successful compaction (undefined = never) — the urgency tie-break. */
+    readonly lastCompactedAt?: number;
+}
+/**
+ * Find segments worth compacting: those in this worker's shard with ≥ `threshold` dirty Warm rows, excluding
+ * quarantined poison segments (gap #2). Enumerates the registry (optionally one namespace) plus explicit
+ * `candidates`, then for each in-shard, non-quarantined segment drains `warm.listChunks` to count dirty rows —
+ * O(total warm / shards) (turning that into O(dirty) needs the deferred GSI/Select:COUNT seam, gap #3). Refreshes
+ * the `dirtyChunkCount` hint only when it **changed** (change-guarded CAS — no idle-segment write storm).
+ */
+declare function findCompactable(deps: Pick<CompactionDeps, 'warm' | 'registry' | 'clock'>, options?: DiscoveryOptions): Promise<CompactionCandidate[]>;
+/** What one {@link runCompactionCycle} did: candidates found, how many committed, how many the budget deferred. */
+interface CompactionCycleResult {
+    /** In-shard, non-quarantined segments over threshold this cycle. */
+    readonly candidates: number;
+    /** How many committed a new generation. */
+    readonly compacted: number;
+    /** Candidates left unprocessed by the `maxSegments` budget — run again to drain them. */
+    readonly deferred: number;
+    readonly results: CompactionResult[];
+}
+/**
+ * Run one discovery → compact → GC cycle. The CLI/daemon calls this once (Lambda) or on a loop (K8s/ECS).
+ * Candidates are processed **most-dirty first** (tie-broken by oldest/never-compacted), and an optional
+ * `maxSegments` budget caps the **compact/GC** work per cycle — the rest are `deferred` to the next cycle
+ * (urgency ordering keeps the hottest from starving). The budget bounds only compaction: discovery (the registry
+ * scan + in-shard Warm drain + urgency sort) is paid in full each cycle, so at very large fleets discovery — not
+ * compaction — is the per-cycle floor; the deferred resumable cursor (gap #3) is what will bound it. Per-segment
+ * faults are isolated **and** counted toward quarantine (gap #2), so one poison segment can neither abort the
+ * cycle nor silently freeze.
+ */
+declare function runCompactionCycle(deps: CompactionDeps, options: CompactionOptions & DiscoveryOptions & {
+    keep?: number;
+    maxSegments?: number;
+}): Promise<CompactionCycleResult>;
+
+/**
+ * Segment **export ("eject")** — dump every registered segment's current *effective* set to a portable file,
+ * using only public read APIs, so your data is readable **without CloudRoaring** (a first-class exit path;
+ * see the README "Your data stays yours" section).
+ *
+ * Two formats:
+ * - `'roaring'` (default) — one **portable RoaringBitmap32** per segment (the cross-language CRoaring format,
+ *   loadable by any roaring library in Java/Go/Python/Rust/C++/…). Compact; builds one bitmap in memory per
+ *   segment.
+ * - `'ndjson'` — newline-delimited ids, streamed (constant memory, any segment size); zero dependencies to read.
+ *
+ * The engine is **storage-agnostic and I/O-free**: it enumerates via an {@link IRegistryDriver}, reads the
+ * tier-merged effective set via a store's `segment(...).iterate()`, and writes bytes through an injected
+ * {@link ExportSink} — so it never imports `node:fs` (the `export-segments` CLI supplies a filesystem sink; a
+ * test supplies an in-memory one; you could supply an S3 uploader). Crypto-shredded (`destroyed`) segments are
+ * skipped (their bytes are unrecoverable); an encrypted segment is decrypted transparently **iff** the store was
+ * wired with its keystore — so the export is **cleartext**, and protecting it is on you.
+ *
+ * **Enumeration** = the registry's known set (segments with a committed cold generation) **plus** any explicit
+ * {@link ExportOptions.candidates}. A brand-new **all-warm** segment — written only via real-time
+ * `add()`/`remove()`, never compacted — isn't in the registry yet, so name it in `candidates` (CLI:
+ * `CR_EXPORT_SEGMENTS`) to include it, or compact/bulk-load it once first. This mirrors the compaction daemon's
+ * discovery contract (see `findCompactable`).
+ *
+ * **Per-segment fault isolation:** a segment that can't be read (a corrupt cold object, or an encrypted segment
+ * when the store has no keystore) is recorded in the manifest's {@link ExportManifest.failed} list and the export
+ * **continues** — one bad segment never blocks the rest. Its partial output is aborted, so a truncated file never
+ * masquerades as complete. Therefore "a manifest exists" means *the run finished*, not that every segment
+ * succeeded — check `failed` (the CLI also exits non-zero when it's non-empty).
+ */
+
+/** Output format for {@link runExport} / `CloudRoaring.exportSegments`. */
+type ExportFormat = 'roaring' | 'ndjson';
+/** A writer for one segment's output — inject a filesystem file, an S3 upload, stdout, or a test buffer. */
+interface ExportWriter {
+    /** Append bytes (called one or more times; for `ndjson`, batched line chunks; for `roaring`, once). */
+    write(bytes: Uint8Array): Promise<void> | void;
+    /** **Commit** the output — called once, only on success (all bytes written). Finalize/flush/rename here. */
+    close(): Promise<void> | void;
+    /**
+     * **Discard** a partial output — called instead of `close()` if a fault occurs mid-segment, so a truncated file
+     * never masquerades as complete (e.g. delete the temp file). Optional; sinks with nothing to undo can omit it.
+     */
+    abort?(): Promise<void> | void;
+}
+/** A destination the export writes each segment to. `ext` is `.roaring` or `.ndjson`. */
+interface ExportSink {
+    open(ref: SegmentRef, ext: string): Promise<ExportWriter> | ExportWriter;
+}
+interface ExportOptions {
+    /** Output format; defaults to `'roaring'`. */
+    readonly format?: ExportFormat;
+    /**
+     * Bitmap codec used to build the exported bitmap for the `'roaring'` format ([DECISIONS #58]). Optional in the
+     * type so this stays call-compatible public API; a **flavor** package binds it (see `requireCodec`). Not needed
+     * for `'ndjson'`, which streams plain ids.
+     */
+    readonly codec?: CodecInterface;
+    /** Scope the export to one namespace; omit to export every registered segment. */
+    readonly namespace?: string;
+    /** `ndjson` flush threshold in ~bytes (ids are ASCII, so ≈ chars); defaults to 64 KiB. */
+    readonly ndjsonBatchBytes?: number;
+    /**
+     * Extra segments to export beyond the registry's known set. The registry only lists segments with a committed
+     * cold generation, so an **all-warm** segment (written via real-time `add()`/`remove()`, never compacted) must
+     * be named here to be included (CLI: `CR_EXPORT_SEGMENTS`). Deduped against the registry set; when `namespace`
+     * is set, only candidates in that namespace are exported.
+     */
+    readonly candidates?: readonly SegmentRef[];
+}
+/** Per-segment result recorded in the {@link ExportManifest}. */
+interface ExportedSegment {
+    readonly segment: string;
+    readonly namespace?: string;
+    /** Ids written (the segment's effective cardinality at export time). */
+    readonly count: number;
+    /** Bytes written to the sink for this segment. */
+    readonly bytes: number;
+}
+/**
+ * A segment that could **not** be exported — recorded rather than aborting the whole run (fault isolation), so a
+ * single corrupt/undecryptable segment never blocks the rest of the dump.
+ */
+interface ExportFailure {
+    readonly segment: string;
+    readonly namespace?: string;
+    /** Why it failed (an error message) — e.g. a corrupt cold object, or an encrypted segment with no keystore. */
+    readonly error: string;
+}
+/** What {@link runExport} produced — a self-describing summary the CLI persists as `manifest.json`. */
+interface ExportManifest {
+    /** Schema version of this manifest shape (currently `1`) — insurance for evolving the format post-1.0. */
+    readonly version: number;
+    readonly format: ExportFormat;
+    readonly totalSegments: number;
+    readonly totalIds: number;
+    readonly segments: readonly ExportedSegment[];
+    /**
+     * Segments that could not be read (empty when everything succeeded). Its presence in the manifest is the point:
+     * "a manifest exists" ⇒ the run finished, **not** that every segment succeeded — always check this list.
+     */
+    readonly failed: readonly ExportFailure[];
+}
+/** The minimal read surface the export needs from a store — a `CloudRoaring` satisfies this structurally. */
+interface SegmentReader {
+    segment(name: string, options?: {
+        namespace?: string;
+    }): {
+        iterate(): AsyncIterable<number>;
+    };
+}
+/**
+ * Export every enumerated segment's effective set through `sink`. Enumerates via `registry` (+ any
+ * `options.candidates`), reads via `reader` (the store). Returns a manifest. `CloudRoaring.exportSegments` is the
+ * public entry — it calls this with its own store + registry (so enumeration and the read path provably share one
+ * registry).
+ *
+ * **Fault isolation:** a per-segment read/write fault aborts that segment's partial (so a truncated file never
+ * looks complete), records it in `failed`, and the run continues — one bad segment never blocks the rest. A
+ * `close()` fault is likewise recorded (never triggering `abort()` — they're mutually exclusive).
+ *
+ * Re-running overwrites the segments it re-exports but does **not** prune files for segments that have since
+ * disappeared — export to a fresh directory for a clean dump. For a *current* image, run against a
+ * freshly-constructed store: a store's cold source pins each segment's generation for its lifetime, so a
+ * long-lived store that has since been compacted would export the pinned (stale) view.
+ */
+declare function runExport(reader: SegmentReader, registry: IRegistryDriver, sink: ExportSink, options?: ExportOptions): Promise<ExportManifest>;
+
+interface BitRoute {
+    /** Top 16 bits — the chunk key (0..65535). */
+    readonly chunkKey: number;
+    /** Bottom 16 bits — the value within the chunk (0..65535). */
+    readonly remainder: number;
+}
+/** Split a u32 id into `{ chunkKey, remainder }`. Throws `ValidationError` for non-u32 input. */
+declare function splitId(id: number): BitRoute;
+/**
+ * Recombine a chunk key + remainder back into the u32 id. Precondition: `chunkKey` is a validated
+ * 16-bit value (tier-derived keys are validated upstream in the engine before reaching here, per
+ * invariant 5); `remainder` is masked to 16 bits.
+ */
+declare function joinId(chunkKey: number, remainder: number): number;
+
+/**
+ * Bounded-concurrency fan-out — the missing primitive for running async work over many items without either
+ * a thundering herd (unbounded `Promise.all` → N simultaneous S3/DynamoDB calls) or full serial latency
+ * (`for await`). Pure + I/O-free, so it lives in `core/`; callers inject the async work.
+ */
+/**
+ * Run `fn` over `items` with at most `limit` promises in flight at once, returning results in **input order**
+ * (regardless of completion order). If any `fn` rejects, the pool stops scheduling new work, lets the in-flight
+ * tasks settle, and rejects with the **first** error — callers that must not abort on one failure (e.g. an
+ * erasure ledger that records per-item faults) should catch inside `fn` so it never rejects.
+ *
+ * `items` is a materialized array on purpose: every caller here already enumerates its source (registry list,
+ * S3 page, chunk map), so an array keeps the pool trivial and race-free (no shared-iterator hazard).
+ */
+declare function mapWithConcurrency<T, R>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
+
+declare function validateSegmentRef(ref: SegmentRef): void;
+
+/**
+ * Canonical key encoding for a segment / chunk — one source of truth, used by both the storage
+ * drivers and the HOT cache (DRY). The encoding is collision-proof and injection-proof:
+ *
+ * - The field delimiter (a space) and the "no namespace" sentinel (`/`) are characters the name
+ *   grammar forbids in a namespace/segment — so they can never appear inside
+ *   a name, can't be injected across the delimiter, and the absent-namespace case (`undefined`) is
+ *   encoded distinctly from any real namespace (an empty string is rejected by the grammar anyway).
+ */
+
+declare function segmentKey(ref: SegmentRef): string;
+declare function chunkRefKey(ref: ChunkRef): string;
+
+declare class MemoryWarmDriver implements IWarmDriver {
+    private readonly rows;
+    private seq;
+    private nextToken;
+    get(ref: ChunkRef): Promise<WarmRow | null>;
+    putConditional(ref: ChunkRef, bytes: Uint8Array, expected: Token | NoRow): Promise<{
+        token: Token;
+    }>;
+    deleteConditional(ref: ChunkRef, expected: Token): Promise<void>;
+    listChunks(ref: SegmentRef): AsyncIterable<{
+        chunkKey: number;
+    } & WarmRow>;
+}
+declare class MemoryColdChunkSource implements ColdChunkSource {
+    private readonly chunks;
+    getChunk(ref: ChunkRef): Promise<Uint8Array | null>;
+    listChunkKeys(ref: SegmentRef): Promise<number[]>;
+    sizeOf(ref: SegmentRef): Promise<SegmentSize | null>;
+    /** Test/seed helper — populate immutable Cold bytes for a chunk (no bulk-load path until Phase 3). */
+    seed(ref: ChunkRef, bytes: Uint8Array): void;
+}
+interface MemoryRegistryDriverOptions {
+    /** Injected clock for `createdAt`/`updatedAt`; defaults to `Date.now` (drivers may use ambient time). */
+    readonly now?: () => number;
+}
+/**
+ * In-memory {@link IRegistryDriver} — one record per segment under OCC. The token is a single global,
+ * monotonic, never-reused counter (so a record recreated after `delete` always gets a strictly-greater
+ * token → ABA-safe even though `delete` removes the row physically). Mirrors {@link MemoryWarmDriver}.
+ */
+declare class MemoryRegistryDriver implements IRegistryDriver {
+    private readonly rows;
+    private readonly now;
+    private seq;
+    constructor(options?: MemoryRegistryDriverOptions);
+    private nextToken;
+    capabilities(): RegCaps;
+    get(ref: SegmentRef): Promise<RegistryRecord | null>;
+    create(ref: SegmentRef, record: NewRegistryRecord): Promise<{
+        token: Token;
+    }>;
+    compareAndSwap(ref: SegmentRef, expected: Token, patch: RegistryPatch): Promise<{
+        token: Token;
+    }>;
+    list(namespace?: string): AsyncIterable<RegistryRecord>;
+    delete(ref: SegmentRef): Promise<void>;
+}
+/**
+ * In-memory {@link IColdDriver} — write-once immutable generation objects as opaque bytes. A "dumb byte
+ * mover" (understands neither roaring nor `.crbm`), so it's a faithful cold backend for tests, the compaction
+ * simulator, and a zero-setup local cold tier. Mirrors the LocalFs/S3 contract (write-once, range/tail reads).
+ */
+declare class MemoryColdDriver implements IColdDriver {
+    private readonly objects;
+    capabilities(): ColdCaps;
+    putImmutable(key: GenKey, write: (sink: BlobSink) => Promise<void>): Promise<{
+        size: number;
+        sha256: string;
+    }>;
+    getRange(key: GenKey, offset: number, length: number): Promise<Uint8Array>;
+    getTail(key: GenKey, maxBytes: number): Promise<{
+        bytes: Uint8Array;
+        size: number;
+    }>;
+    delete(key: GenKey): Promise<void>;
+    list(ref: SegmentRef): AsyncIterable<GenKey>;
+    private require;
+}
+
+declare class LocalFsColdDriver implements IColdDriver {
+    private readonly root;
+    constructor(root: string);
+    capabilities(): ColdCaps;
+    putImmutable(key: GenKey, write: (sink: BlobSink) => Promise<void>): Promise<{
+        size: number;
+        sha256: string;
+    }>;
+    getRange(key: GenKey, offset: number, length: number): Promise<Uint8Array>;
+    getTail(key: GenKey, maxBytes: number): Promise<{
+        bytes: Uint8Array;
+        size: number;
+    }>;
+    delete(key: GenKey): Promise<void>;
+    list(ref: SegmentRef): AsyncIterable<GenKey>;
+    private openRead;
+}
+
+declare class LocalFsWarmDriver implements IWarmDriver {
+    private readonly root;
+    private readonly maxRowBytes;
+    /** Per-row promise chain — serializes read-modify-write so an in-process CAS never loses an update. */
+    private readonly chain;
+    constructor(root: string, maxRowBytes?: number);
+    get(ref: ChunkRef): Promise<WarmRow | null>;
+    putConditional(ref: ChunkRef, bytes: Uint8Array, expected: Token | NoRow): Promise<{
+        token: Token;
+    }>;
+    deleteConditional(ref: ChunkRef, expected: Token): Promise<void>;
+    listChunks(ref: SegmentRef): AsyncIterable<{
+        chunkKey: number;
+    } & WarmRow>;
+    private readRow;
+    private writeRow;
+    /**
+     * Serialize callbacks for a given row path so read-modify-write is atomic in-process. `prev.then(fn,
+     * fn)` runs `fn` regardless of whether the predecessor fulfilled or rejected — a conflict on one
+     * writer must not stall the row's chain.
+     */
+    private withRowLock;
+}
+
+interface LocalFsRegistryDriverOptions {
+    /** Injected clock for `createdAt`/`updatedAt`; defaults to `Date.now`. */
+    readonly now?: () => number;
+}
+declare class LocalFsRegistryDriver implements IRegistryDriver {
+    private readonly root;
+    /** Per-row promise chain — serializes read-modify-write so an in-process CAS never loses an update. */
+    private readonly chain;
+    private readonly now;
+    constructor(root: string, options?: LocalFsRegistryDriverOptions);
+    capabilities(): RegCaps;
+    get(ref: SegmentRef): Promise<RegistryRecord | null>;
+    create(ref: SegmentRef, record: NewRegistryRecord): Promise<{
+        token: Token;
+    }>;
+    compareAndSwap(ref: SegmentRef, expected: Token, patch: RegistryPatch): Promise<{
+        token: Token;
+    }>;
+    list(namespace?: string): AsyncIterable<RegistryRecord>;
+    delete(ref: SegmentRef): Promise<void>;
+    /** Namespaces to scan: just the one requested, or every namespace dir under the root. */
+    private namespaceDirs;
+    private readRow;
+    private writeRow;
+    /** Serialize callbacks for a row path so read-modify-write is atomic in-process (mirrors the Warm tier). */
+    private withRowLock;
+}
+
+interface CrbmReaderOptions {
+    /** Speculative tail size in bytes (default 256 KB; clamped up to at least the footer size). */
+    readonly tailBytes?: number;
+    /** Hard cap on a single chunk payload length (default 16 MB). */
+    readonly maxPayloadBytes?: number;
+    /** Hard cap on the whole index region fetched/parsed from one object (default 8 MB). */
+    readonly maxIndexBytes?: number;
+    /** Decryption context for an encrypted object (its DEK's AEAD + AAD builder). Required iff `FLAG_ENCRYPTED`. */
+    readonly crypto?: CrbmCrypto;
+}
+declare class CrbmReader {
+    private readonly blob;
+    private readonly objectSize;
+    readonly generation: number;
+    readonly totalCardinality: number;
+    private readonly entries;
+    private readonly orderedKeys;
+    /** True when `open()` satisfied the index from the tail GET alone (no second range read). */
+    readonly servedFromTail: boolean;
+    /** Set iff the object is encrypted — used to decrypt each chunk payload in {@link getChunk}. */
+    private readonly crypto;
+    private constructor();
+    /** Total object bytes (from the one-GET tail read) — for grounded storage cost (Phase 5b). */
+    get sizeBytes(): number;
+    /**
+     * Estimated retained JS heap of this reader's parsed index — the weight the cold reader cache bounds on
+     * (gap #1: a wide segment's index dominates the reader's footprint). `entries.size` scales with the number
+     * of resident chunks (≤ 65536), so this is `entries.size × {@link RETAINED_BYTES_PER_INDEX_ENTRY}`.
+     */
+    get retainedIndexBytes(): number;
+    /** Per-chunk cardinality (`chunkKey → count`) from the parsed index — no payload reads (Phase 5c cheap count). */
+    cardinalities(): Map<number, number>;
+    static open(blob: BlobReader, options?: CrbmReaderOptions): Promise<CrbmReader>;
+    /** Chunk keys present in this generation, ascending. */
+    chunkKeys(): number[];
+    /** Segment cardinality from the footer (no payload reads) — the cheap `count()` path. */
+    count(): number;
+    has(chunkKey: number): boolean;
+    /**
+     * Range-GET one chunk's payload, verifying its CRC32C before returning. Returns `null` if the chunk is
+     * absent. Throws `IntegrityError` on a CRC mismatch (the bytes must never reach the native
+     * deserializer). The returned buffer is a **read-only view** owned by the reader/driver — callers must
+     * not mutate it.
+     */
+    getChunk(chunkKey: number): Promise<Uint8Array | null>;
+}
+
+/**
+ * Bridges the `.crbm` archive format to the engine's Cold seam (decision 4).
+ *
+ * `CrbmColdChunkSource` implements the Phase-1 {@link ColdChunkSource} over an {@link IColdDriver}: it
+ * pins a segment's latest generation, opens its {@link CrbmReader} once, and serves per-chunk payloads —
+ * so the **engine is unchanged**, it just reads real on-disk generations now. `writeCrbmGeneration` is
+ * the inverse seed primitive (a generation built from in-memory bitmaps), the basis for the Phase-3
+ * bulk-load and Phase-4 compaction writers.
+ */
+
+interface CrbmColdChunkSourceOptions extends CrbmReaderOptions {
+    /**
+     * Optional {@link IRegistryDriver}. When provided, the current generation is resolved via the registry's
+     * authoritative `currentGen` (one cheap strong read) instead of a `list` scan of every generation — the
+     * Phase-4c retirement of that scan. When absent, the source falls back to the `list`-scan (so the
+     * in-memory / simple setups keep working with no registry). The resolved generation is cached and
+     * **re-resolved on a short TTL** ({@link currentGenTtlMs}, needs a {@link clock}) so a long-lived source
+     * observes a compaction's new generation within the TTL instead of pinning one generation forever (gap #4).
+     */
+    readonly registry?: IRegistryDriver;
+    /**
+     * Optional {@link IKeystore} for reading **encrypted** segments (Phase 4e). When a segment's registry record
+     * carries wrapped DEK(s), the source unwraps the DEK via this keystore and decrypts each chunk/index. Reading
+     * an encrypted segment without a keystore throws {@link KeyUnavailableError}; cleartext segments ignore it.
+     * Requires a `registry` (that's where the wrapped DEKs live).
+     */
+    readonly keystore?: IKeystore;
+    /**
+     * Enforce that every segment read is encrypted (Phase 4e). When true, resolving a **cleartext** segment (no
+     * wrapped DEKs) throws {@link KeyUnavailableError} — a guard against silently reading a segment that should
+     * have been encrypted. Off by default (encryption is opt-in).
+     */
+    readonly requireEncryption?: boolean;
+    /**
+     * Time source for the current-generation TTL refresh (gap #4) — the determinism seam; `core/` never reads
+     * ambient time. Refresh needs **both** a clock and a `registry`; without either the source **pins** the
+     * first-resolved generation for its lifetime (the pre-Phase-B behaviour). The `CloudRoaring` facade passes its
+     * clock automatically, so wiring a `registry` is enough to get live cross-generation invalidation.
+     */
+    readonly clock?: Pick<Clock, 'now'>;
+    /**
+     * How long (ms) a resolved `currentGen` is trusted before the next read re-resolves it (default 2000) — the
+     * bound on read staleness after a compaction: a reader may serve the prior generation for up to this long,
+     * then converges. Lazy (checked on read — no timer); ≤ one cheap registry read per segment per window, and a
+     * new {@link CrbmReader} is opened only when the generation actually changed. `0` (or no clock) ⇒ pin forever.
+     */
+    readonly currentGenTtlMs?: number;
+    /**
+     * Hard ceiling on how many segments' readers (each holding a fully-parsed `.crbm` index) are cached at once
+     * (default 1024) — a memory bound for a long-running server (gap #1). Past it, the least-recently-used
+     * segment's reader is evicted; the next read of an evicted segment re-opens it (one cheap tail GET, since
+     * generations are immutable). Raise it for a big hot working set of small segments.
+     */
+    readonly maxOpenSegments?: number;
+    /**
+     * Aggregate byte ceiling on the parsed `.crbm` indices resident in the reader cache (default 64 MiB) — the
+     * **second half of the gap #1 fix**. `maxOpenSegments` alone bounds by *count*, but a wide/dense segment's
+     * parsed index can be several MB, so 1024 wide indices could pin ~GBs and blow a small heap (e.g. a 128 MB
+     * Lambda) while the count is nominally "in bounds". This caps the summed {@link CrbmReader.retainedIndexBytes}
+     * across cached readers; the least-recently-used reader is evicted once the total would exceed it — whichever
+     * of the count/byte bounds binds first. Lower it for memory-tight deployments with wide segments; a single
+     * segment whose index alone exceeds the budget is still cached (it can't be shrunk) but nothing else alongside.
+     */
+    readonly maxOpenIndexBytes?: number;
+}
+declare class CrbmColdChunkSource implements ColdChunkSource {
+    private readonly driver;
+    /**
+     * One resolved reader per segment, re-resolved on a short TTL ({@link CrbmColdChunkSourceOptions.currentGenTtlMs},
+     * needs a clock). Within the TTL a segment's Cold bytes are treated as an immutable snapshot; when the TTL
+     * elapses the next read cheaply re-resolves `currentGen` and, only if it advanced (a compaction committed),
+     * opens the new generation — so a long-lived source observes new generations within the TTL rather than
+     * pinning one forever (gap #4). The engine pairs this with a **generation-keyed** HOT cache so a bump never
+     * serves a stale decoded chunk. Without a clock or a registry the source pins the first generation for its
+     * lifetime (pre-Phase-B behaviour). A segment with no generation yet is not memoized, so it's re-checked until
+     * one exists. **Bounded** by a {@link BoundedLru} ({@link CrbmColdChunkSourceOptions.maxOpenSegments}, default
+     * 1024): past the ceiling the least-recently-used segment's reader (and its parsed index) is evicted — the
+     * steady-state memory bound (gap #1); re-opening an evicted segment is one cheap tail GET.
+     */
+    private readonly snapshots;
+    private readonly registry;
+    private readonly keystore;
+    private readonly requireEncryption;
+    private readonly readerOptions;
+    private readonly clock;
+    private readonly currentGenTtlMs;
+    constructor(driver: IColdDriver, options?: CrbmColdChunkSourceOptions);
+    /** The current resolved reader for a segment, refreshing on the TTL (gap #4). Cheap within the TTL window. */
+    private resolvedReader;
+    /** TTL elapsed: cheaply re-resolve `currentGen`; reopen only if it actually changed, else reuse the prior reader. */
+    private computeRefreshedReader;
+    /**
+     * Memoize a reader-promise as the segment's snapshot at `now()`, forgetting it later if it resolves to
+     * null / throws (identity-guarded, so a stale cleanup never clobbers a fresher snapshot). Installing the
+     * (pending) promise **synchronously** is what lets concurrent callers coalesce onto one in-flight resolve.
+     */
+    private install;
+    private now;
+    private expired;
+    /**
+     * The segment's current generation number (gap #4) — the engine keys its HOT chunk cache by this so a
+     * compaction bump is observed instead of serving a stale decoded chunk. Served from the (TTL-refreshed)
+     * snapshot, so no extra backend read within the TTL window. `null` if the segment has no committed generation.
+     */
+    currentGeneration(ref: SegmentRef): Promise<number | null>;
+    private resolveLatest;
+    /** Open a {@link CrbmReader} for an already-resolved generation target (decrypting if the segment is encrypted). */
+    private openForTarget;
+    /**
+     * The current generation + its DEK wrappings: the registry's authoritative record (one strong read), or a
+     * `list` scan for the max generation when there's no registry (a registry-less source can only read cleartext
+     * — there's nowhere a wrapped DEK could live).
+     */
+    private resolveTarget;
+    /** Build the per-generation decryption context for an encrypted segment (undefined for cleartext). */
+    private cryptoForRead;
+    getChunk(ref: ChunkRef): Promise<Uint8Array | null>;
+    listChunkKeys(ref: SegmentRef): Promise<number[]>;
+    sizeOf(ref: SegmentRef): Promise<SegmentSize | null>;
+    cardinalities(ref: SegmentRef): Promise<ReadonlyMap<number, number> | null>;
+    /**
+     * Run `read` against the pinned snapshot, healing the one torn-read window compaction's GC can open: if the
+     * generation we pinned was superseded *and* swept (the grace window elapsed) mid-read, the Cold driver throws
+     * {@link NotFoundError}. Rather than surface that as a query failure (**I5**), we drop the stale snapshot,
+     * re-resolve `currentGen`, and retry once — the read then serves the newer (committed, immutable) generation,
+     * a monotonic move forward. A *second* NotFound is pathological (GC outrunning resolution) and propagates
+     * rather than fabricate an absent answer — never return a wrong result. `ifGone` is returned only when the
+     * segment legitimately has no committed generation at all (cold is empty). The single retry is bounded.
+     */
+    private withFreshSnapshot;
+}
+/**
+ * Write one immutable generation from in-memory bitmaps (the seed / bulk-load primitive). Chunks are
+ * sorted ascending and empty bitmaps skipped (empty chunks are never stored). Returns the driver's
+ * `{ size, sha256 }` for the written object. Pass `options.crypto` to AES-256-GCM-encrypt the generation
+ * (the caller builds it from the segment's DEK + a `(segment, generation)`-bound {@link aadFor}).
+ */
+declare function writeCrbmGeneration(driver: IColdDriver, key: GenKey, chunks: Iterable<{
+    chunkKey: number;
+    bitmap: CodecBitmap;
+}>, options?: {
+    crypto?: CrbmCrypto;
+}): Promise<{
+    size: number;
+    sha256: string;
+}>;
+/**
+ * Point a segment's registry `currentGen` at `key.generation` — the publish step that makes a freshly-written
+ * generation the authoritative latest (so registry-aware readers see it). **Forward-only and idempotent:**
+ * if the registry has no row it creates one; if it's already at/ahead of `key.generation` it's a no-op (an
+ * out-of-order/duplicate publish never regresses the pointer); otherwise it advances via compare-and-swap,
+ * retrying a few times under contention. Separated from the Cold write so callers can publish atomically
+ * after the immutable object is durable (write-then-publish).
+ */
+declare function publishGeneration(registry: IRegistryDriver, key: GenKey, options?: {
+    wrappedDeks?: readonly WrappedDek[];
+}): Promise<boolean>;
+/** What a bulk-load wrote — the driver's `{ size, sha256 }` plus a summary of the built generation. */
+interface BulkLoadResult {
+    /** Bytes written to the Cold object. */
+    readonly size: number;
+    /** The driver's content hash of the object. */
+    readonly sha256: string;
+    /** Distinct non-empty chunks written (≤ 65536). */
+    readonly chunkCount: number;
+    /** Total distinct ids in the generation (post-dedup). */
+    readonly cardinality: number;
+}
+/**
+ * **Bulk-load** a whole immutable generation from a flat id source — the batch "seed/sweep" entry point.
+ * Unlike {@link writeCrbmGeneration} (which takes pre-grouped bitmaps), this
+ * consumes an arbitrary, **unsorted** stream of u32 ids (sync or async) and routes each into its chunk's
+ * Roaring bitmap as it goes. The input is consumed lazily and ids dedup on insert, so memory is bounded by
+ * the **built generation** — the in-memory Roaring representation of the *distinct* set (≤ one bitmap per
+ * non-empty chunk) — not by the input length: you can stream a billion duplicate-heavy ids and hold only the
+ * distinct result. Note this is `O(distinct set)`, **not** window-bounded like {@link SegmentEngine.intersect}:
+ * bulk-load holds the whole generation in RAM, which suits batch seed/sweep jobs but not an
+ * unbounded-cardinality stream (a segment larger than RAM needs external-merge / pre-sorted input — later phase).
+ *
+ * Each id must be an integer in `[0, 2³²)` ({@link splitId} throws {@link ValidationError} otherwise) — the
+ * source is consumed lazily, so a bad id aborts mid-stream without writing a partial object (the driver
+ * commits only after the callback resolves). An empty source writes a valid empty generation.
+ *
+ * Writing a fresh full snapshot of a segment; merging a new delta into the *existing* Cold (compaction) is
+ * Phase 4. The caller picks the generation number in `key` and a `ColdChunkSource` serves the **highest**, so
+ * pick a known-fresh number (on an empty segment, `0`): a too-high number silently shadows real data, and
+ * re-using an existing generation throws {@link WriteConflictError} (write-once). Registry-assigned
+ * generations arrive in Phase 4.
+ */
+declare function bulkLoadCrbmGeneration(driver: IColdDriver, key: GenKey, ids: Iterable<number> | AsyncIterable<number>, options?: {
+    registry?: IRegistryDriver;
+    keystore?: IKeystore;
+    requireEncryption?: boolean;
+    audit?: IAuditSink;
+    /** Bitmap codec ([DECISIONS #58]). Optional in the type; a **flavor** package binds it ({@link requireCodec}). */
+    codec?: CodecInterface;
+}): Promise<BulkLoadResult>;
+
+/**
+ * Typed errors — callers learn *why* something failed, never by parsing strings. Retry is the driver
+ * decorators' job, not the engine's: a driver classifies its backend's failures into this vocabulary, and
+ * `withRetry` decides what is transient.
+ */
+/**
+ * Registry-symbol brands. The package ships as multiple bundles — the core entry and the `./s3` / `./dynamodb`
+ * subpaths — and the builder inlines `core/errors` into each. A driver in a subpath bundle therefore throws a
+ * *different* class object than the one the core engine/retry code would `instanceof`-check, so `instanceof`
+ * silently returns false across that boundary in the published CJS package (defeating OCC/transient retry and
+ * compaction race-handling). These `Symbol.for` brands are identity-stable across bundles/realms; classify
+ * errors with the exported predicates below (never `instanceof`) anywhere an error may cross the boundary.
+ */
+declare const ERROR_BRAND: unique symbol;
+declare const TRANSIENT_BRAND: unique symbol;
+/** Base class for every error CloudRoaring throws. */
+declare class CloudRoaringError extends Error {
+    /** Cross-bundle brand — see the predicates ({@link isCloudRoaringError}, …). Non-enumerable-ish (symbol key ⇒ not in JSON). */
+    readonly [ERROR_BRAND]: true;
+    constructor(message: string);
+}
+/** Invalid caller input (bad id, segment name, options). Raised before any storage call. */
+declare class ValidationError extends CloudRoaringError {
+}
+/** An OCC conditional write/delete lost the race — the row changed since it was read. */
+declare class WriteConflictError extends CloudRoaringError {
+}
+/** Bytes from a tier are corrupt, oversized, or fail a checksum/format check. */
+declare class IntegrityError extends CloudRoaringError {
+}
+/**
+ * A requested object/row does not exist. Part of the driver error vocabulary; thrown by
+ * persistent drivers from Phase 2 — the Phase-1 engine + in-memory drivers return `null` instead.
+ */
+declare class NotFoundError extends CloudRoaringError {
+}
+/**
+ * This build/configuration cannot perform the requested operation, though nothing is malformed. Two uses:
+ * (1) **format** — the bytes are well-formed but unreadable here (an unknown `.crbm` major version, an
+ * encrypted file before the crypto path exists) — distinct from `IntegrityError` (corruption); and (2)
+ * **store configuration** — an operation this store's wiring doesn't support (e.g. a lifecycle helper like
+ * `compact`/`eraseSubject` called on a store built without a raw cold driver + registry). Raised at
+ * operation time, before any mutation.
+ */
+declare class UnsupportedError extends CloudRoaringError {
+}
+/**
+ * A driver cannot meet a capability the chosen topology requires (e.g. a Cold driver without range
+ * reads). Raised fail-fast at wiring time, never mid-operation.
+ */
+declare class CapabilityError extends CloudRoaringError {
+}
+/**
+ * An operation would exceed its per-op **denial-of-wallet budget** — too many backend requests for a single
+ * `count`/`iterate`/`intersect`/`subjectReport`/`eraseSubject` call — so it is refused **before** fanning out
+ * (Decision #3 / invariant T3). Default-on but generous (normal ops never hit it); tune it
+ * per store (`budget`) or per op, or disable with `budget: false`. Deterministic (never retried): the op is too
+ * big by policy, not by luck. Each request's bytes are separately capped (the safe-deserialize ceiling), so
+ * bounding the request count transitively bounds bytes. Carries the projected count + the limit, never data.
+ */
+declare class BudgetExceededError extends CloudRoaringError {
+}
+/**
+ * An encrypted segment's data key (DEK) cannot be unwrapped because the keystore holds none of the
+ * key-encryption-keys (KEKs) its wrappings reference — the KEK was never configured, rotated away without
+ * keeping the old key, or lost. Deterministic (never retried): without a KEK the ciphertext is unreadable by
+ * design. The flip side of crypto-shred — when this is *intended* (a destroyed segment) the registry row is
+ * already a `destroyed` tombstone; when it's *not*, restore the missing KEK (or its recovery KEK). Carries no
+ * key material.
+ */
+declare class KeyUnavailableError extends CloudRoaringError {
+}
+/**
+ * A **transient** infrastructure fault that is safe to retry — throttling, a 5xx, a dropped connection,
+ * a client-side request timeout. Drivers classify their backend's retryable faults and raise this (the
+ * SDK-specific knowledge stays in the SDK-specific driver); the retry layer (`core/retry`) retries **only**
+ * this class, never a deterministic error like {@link ValidationError}, {@link IntegrityError},
+ * {@link NotFoundError}, or {@link WriteConflictError} (retrying those is pointless or wrong). The original
+ * error is preserved in `cause` so callers can still inspect it.
+ *
+ * Note for logging hygiene (threat-model S12): `cause` is the **raw SDK error**, which may carry operational
+ * metadata (endpoint host, request IDs, `$metadata`). The library's own `message` is identifier-only and safe
+ * to log; if you serialize the whole error *chain*, be aware you're including that metadata.
+ */
+declare class TransientError extends CloudRoaringError {
+    /** A second brand so the whole transient subtree (incl. {@link TimeoutError}) is classifiable cross-bundle. */
+    readonly [TRANSIENT_BRAND]: true;
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * A single attempt exceeded its time budget. Subclass of {@link TransientError} so the retry layer treats a
+ * timeout as retryable by default — a stalled request often succeeds on a fresh connection. Raised by a
+ * driver whose injected client reports a request timeout — setting one on your injected client is the
+ * recommended way to bound a hang.
+ */
+declare class TimeoutError extends TransientError {
+}
+/** Any error thrown by CloudRoaring (any tier, any bundle). */
+declare function isCloudRoaringError(err: unknown): err is CloudRoaringError;
+/** An OCC conditional write/delete lost the race — retry the read-modify-write, don't fail. */
+declare function isWriteConflictError(err: unknown): err is WriteConflictError;
+/** A retryable transient infrastructure fault (incl. {@link TimeoutError}). The retry layer keys on this. */
+declare function isTransientError(err: unknown): err is TransientError;
+/** A requested object/row does not exist. */
+declare function isNotFoundError(err: unknown): err is NotFoundError;
+/** Corrupt/oversized/failed-checksum bytes from a tier. */
+declare function isIntegrityError(err: unknown): err is IntegrityError;
+/** Invalid caller input. */
+declare function isValidationError(err: unknown): err is ValidationError;
+
+/** AES-256-GCM AEAD bound to one 32-byte key. A fresh CSPRNG 96-bit nonce per `seal`; `aad` is authenticated,
+ * never stored. Nonce-reuse safety: the random-96-bit birthday bound is ~q²/2⁹⁷, negligible below ~2³² seals
+ * under one key. A per-segment DEK is **reused across all generations** (compaction re-encrypts under it), so
+ * seal count is cumulative over the segment's life — a segment approaching ~2³² lifetime chunk-seals should be
+ * re-seeded (a fresh segment ⇒ fresh DEK). Far beyond any realistic workload; noted for completeness. */
+declare class NodeAead implements Aead {
+    private readonly key;
+    constructor(key: Uint8Array);
+    seal(plaintext: Uint8Array, aad: Uint8Array): AeadSealed;
+    open(sealed: AeadSealed, aad: Uint8Array): Uint8Array;
+}
+/**
+ * Options for {@link InProcessKeystore}. `keys` maps a `keyId` → its 32-byte KEK; `activeKeyId` names the KEK
+ * new DEKs are wrapped under; an optional `recoveryKeyId` additionally wraps each new DEK under a second
+ * (e.g. offline) KEK, so losing the active KEK isn't fatal. Rotating the active KEK needs no data
+ * re-encryption: add the new KEK, point `activeKeyId` at it, keep the old one to unwrap existing segments.
+ */
+interface InProcessKeystoreOptions {
+    readonly keys: Readonly<Record<string, Uint8Array>>;
+    readonly activeKeyId: string;
+    readonly recoveryKeyId?: string;
+}
+/**
+ * Dependency-free BYOK keystore: envelope-wraps a fresh random per-segment DEK under the active (and optional
+ * recovery) KEK using `node:crypto`. No external service. The raw DEK never leaves a returned {@link NodeAead}.
+ */
+declare class InProcessKeystore implements IKeystore {
+    private readonly keys;
+    private readonly activeKeyId;
+    private readonly recoveryKeyId;
+    constructor(options: InProcessKeystoreOptions);
+    createDek(): Promise<{
+        wrapped: WrappedDek[];
+        aead: Aead;
+    }>;
+    openDek(wrapped: readonly WrappedDek[]): Promise<Aead>;
+}
+
+/**
+ * Crypto-shred erasure (Phase 4e, [DECISIONS #19]).
+ *
+ * GDPR "right to erasure" on immutable/backed-up Cold storage: you can't delete a `.crbm` object from every
+ * backup, but you can **delete its key**. `destroySegment` drops the segment's wrapped DEK(s) from the registry
+ * (a CAS to a `destroyed` tombstone) — the encrypted Cold bytes are then permanently unreadable, everywhere,
+ * forever — and physically deletes the segment's (cleartext) Warm rows. **Immediate + irreversible**, so it's
+ * gated behind an explicit confirmation (name the exact segment/namespace). A `destroyed` segment reads as
+ * empty (its DEK is gone). Only works on an **encrypted** segment; a cleartext segment has no key to shred.
+ *
+ * Note (scope): this shreds the Cold key + clears Warm rows present *now*. Preventing *new* writes to a
+ * destroyed segment (a registry-checked write path) is a later hardening; the write path stays uncoupled today.
+ */
+
+interface EraseDeps {
+    readonly registry: IRegistryDriver;
+    readonly warm: IWarmDriver;
+}
+interface DestroyResult {
+    readonly segment: string;
+    readonly namespace?: string;
+    /** True iff the segment is now a `destroyed` tombstone (incl. the idempotent already-destroyed case). */
+    readonly destroyed: boolean;
+    /**
+     * True iff **this call** performed a genuine crypto-shred — an encrypted segment whose wrapped DEK(s) were
+     * dropped, so its Cold bytes are now permanently unreadable. False for a cleartext tombstone (bytes remain
+     * readable), for the idempotent already-destroyed case, and for an absent segment. This is what the
+     * `segment.erase` audit event keys off — a cleartext "erase" is not an irreversible destruction.
+     */
+    readonly cryptoShredded: boolean;
+    /** `'absent'` (no registry row), `'already'` (already destroyed), or `'cleartext'` (no DEK to shred). */
+    readonly reason?: string;
+    /** Warm rows physically deleted as part of the erase. */
+    readonly warmRowsDeleted: number;
+}
+/**
+ * Crypto-shred one segment. **Irreversible.** `confirmSegment` must equal `ref.segment` (a guard against an
+ * accidental destroy — you must name the exact segment). A non-encrypted segment is rejected unless you opt in
+ * via `allowCleartext` (there's no key to shred; its Cold bytes stay readable, only Warm is cleared).
+ */
+declare function destroySegment(ref: SegmentRef, deps: EraseDeps, options: {
+    confirmSegment: string;
+    allowCleartext?: boolean;
+    audit?: IAuditSink;
+}): Promise<DestroyResult>;
+/**
+ * Crypto-shred every segment in a namespace. **Irreversible.** `confirmNamespace` must equal `namespace`.
+ * Returns a per-segment result (skips cleartext segments unless `allowCleartext`).
+ */
+declare function eraseNamespace(namespace: string, deps: EraseDeps, options: {
+    confirmNamespace: string;
+    allowCleartext?: boolean;
+    audit?: IAuditSink;
+}): Promise<{
+    destroyed: DestroyResult[];
+}>;
+
+/**
+ * Fail-safe cross-tier DR check (gap #11). The registry (`currentGen`, e.g. in
+ * DynamoDB) and the immutable `.crbm` generations (e.g. in S3) back up and restore **independently**, so a
+ * failover can recover the registry *ahead of* the object store — leaving `currentGen` pointing at a generation
+ * whose `.crbm` isn't present yet. That's a torn restore: reads of the affected segment then throw. This scan
+ * detects it up front (run it at startup after a restore) instead of discovering it on the first read.
+ *
+ * Read-only; bounded fan-out. `destroyed` (crypto-shredded) segments are skipped — their Cold is intentionally
+ * gone/unreadable, not a torn restore. A segment whose Cold/registry can't be read this pass is recorded in
+ * `errored` (never aborts the scan). Each segment is checked against its **authoritative live pointer** — one
+ * strong `registry.get` per segment — never the enumeration snapshot from `registry.list`, which can be
+ * eventually-consistent (an unindexed Scan) and lag a recent in-place pointer advance: trusting it would both
+ * miss a torn *live* generation and cry torn on a generation the pointer has already advanced past (GC'd during
+ * the scan). Residual: a full compaction+GC landing in the tiny per-segment get→list gap can still yield a
+ * transient false positive — run the scan against a quiesced fleet (the documented restore procedure), or re-run
+ * to confirm a reported tear.
+ */
+
+interface ConsistencyIssue {
+    readonly segment: string;
+    readonly namespace?: string;
+    /** The registry's `currentGen` for the segment — the generation whose `.crbm` is missing from Cold. */
+    readonly currentGen: number;
+    /** The only issue class today: `currentGen` references a Cold generation that is not present (torn restore). */
+    readonly issue: 'missing-cold-generation';
+}
+/** A segment that could not be checked this pass (Cold/registry read fault) — not proof of a torn restore. */
+interface ConsistencyErrorEntry {
+    readonly segment: string;
+    readonly namespace?: string;
+    /** The read error's message (never the raw error, so the report stays serializable/loggable). */
+    readonly error: string;
+}
+interface ConsistencyReport {
+    /** Registered segments scanned (a `destroyed` segment counts as scanned but is never an issue). */
+    readonly checked: number;
+    /** Segments whose `currentGen` `.crbm` is absent — recover the object store (or restore to a coherent point). */
+    readonly inconsistent: ConsistencyIssue[];
+    /**
+     * Segments that couldn't be read this pass (a transient/partial object store during a restore is exactly when
+     * this runs) — **triage these too**: an unread segment is neither proven-coherent nor proven-torn. Empty on a
+     * clean pass.
+     */
+    readonly errored: ConsistencyErrorEntry[];
+}
+/**
+ * Verify every registered segment's `currentGen` `.crbm` actually exists in Cold. Enumerates the registry
+ * (optionally one namespace) and, for each non-`destroyed` segment, checks the object store lists that
+ * generation. Returns the torn segments in `inconsistent` (empty ⇒ coherent) and any unreadable segments in
+ * `errored`.
+ */
+declare function runConsistencyCheck(deps: {
+    readonly cold: IColdDriver;
+    readonly registry: IRegistryDriver;
+}, options?: {
+    namespace?: string;
+    concurrency?: number;
+}): Promise<ConsistencyReport>;
+
+/**
+ * Retry decorators (Phase 4b).
+ *
+ * Transparent wrappers that add bounded, jittered retry of **transient** faults to any driver, using the one
+ * shared `core/retry` primitive — so every backend (DynamoDB, S3, LocalFS, …) inherits the same, simulator-
+ * replayable policy instead of each rolling its own. Pure composition over the port interfaces (no SDK, no
+ * I/O of their own); the wrapped driver is responsible for *classifying* its transient faults (raising
+ * {@link TransientError}); these decorators decide *whether and when* to retry.
+ *
+ * **Streaming methods** (`listChunks`, `list`) are retried by **re-enumerating from the start**, buffering
+ * the result — a partially-consumed async iterator can't be safely resumed mid-stream (it would re-yield
+ * earlier items). Their consumers in the engine already collect fully (the Warm dirty-set is small under
+ * Topology-A; the cold `list` is a discovery scan), so buffering preserves current semantics. Point methods
+ * are retried in place with no buffering.
+ *
+ * What is **not** retried here: {@link WriteConflictError} (OCC — the engine's read-modify-write loop owns
+ * that; a blind replay would re-apply against a stale token), and every deterministic error
+ * (`ValidationError`/`IntegrityError`/`NotFoundError`/…). Default classifier: {@link isTransient}.
+ */
+
+interface RetryingOptions {
+    readonly clock: Clock;
+    readonly rng: Rng;
+    /** Defaults to {@link DEFAULT_RETRY_POLICY}. */
+    readonly policy?: RetryPolicy;
+    /** Override which errors are retryable. Default: {@link isTransient} (any `TransientError`). */
+    readonly isRetryable?: (err: unknown) => boolean;
+    /** Observability hook fired before each backoff wait. */
+    readonly onRetry?: (info: {
+        attempt: number;
+        delayMs: number;
+        err: unknown;
+    }) => void;
+}
+/** Wrap a warm driver so its calls retry transient faults. OCC conflicts are deliberately not retried here. */
+declare class RetryingWarmDriver implements IWarmDriver {
+    private readonly inner;
+    private readonly policy;
+    private readonly deps;
+    constructor(inner: IWarmDriver, opts: RetryingOptions);
+    get(ref: ChunkRef, opts?: WarmReadOptions): Promise<WarmRow | null>;
+    putConditional(ref: ChunkRef, bytes: Uint8Array, expected: Token | NoRow): Promise<{
+        token: Token;
+    }>;
+    deleteConditional(ref: ChunkRef, expected: Token): Promise<void>;
+    listChunks(ref: SegmentRef, opts?: WarmReadOptions): AsyncIterable<{
+        chunkKey: number;
+    } & WarmRow>;
+}
+/** Wrap a cold chunk source so its reads retry transient faults. */
+declare class RetryingColdChunkSource implements ColdChunkSource {
+    private readonly inner;
+    private readonly policy;
+    private readonly deps;
+    /** Present only when the inner source supports it — so capability detection stays honest. */
+    readonly sizeOf?: (ref: SegmentRef) => Promise<SegmentSize | null>;
+    readonly cardinalities?: (ref: SegmentRef) => Promise<ReadonlyMap<number, number> | null>;
+    readonly currentGeneration?: (ref: SegmentRef) => Promise<number | null>;
+    constructor(inner: ColdChunkSource, opts: RetryingOptions);
+    getChunk(ref: ChunkRef): Promise<Uint8Array | null>;
+    listChunkKeys(ref: SegmentRef): Promise<number[]>;
+}
+/** Wrap a cold driver so its byte operations retry transient faults. */
+declare class RetryingColdDriver implements IColdDriver {
+    private readonly inner;
+    private readonly policy;
+    private readonly deps;
+    constructor(inner: IColdDriver, opts: RetryingOptions);
+    capabilities(): ColdCaps;
+    putImmutable(key: GenKey, write: (sink: BlobSink) => Promise<void>): Promise<{
+        size: number;
+        sha256: string;
+    }>;
+    getRange(key: GenKey, offset: number, length: number): Promise<Uint8Array>;
+    getTail(key: GenKey, maxBytes: number): Promise<{
+        bytes: Uint8Array;
+        size: number;
+    }>;
+    delete(key: GenKey): Promise<void>;
+    list(ref: SegmentRef): AsyncIterable<GenKey>;
+}
+/** Wrap a registry driver so its calls retry transient faults. CAS conflicts are not retried (caller-owned). */
+declare class RetryingRegistryDriver implements IRegistryDriver {
+    private readonly inner;
+    private readonly policy;
+    private readonly deps;
+    constructor(inner: IRegistryDriver, opts: RetryingOptions);
+    capabilities(): RegCaps;
+    get(ref: SegmentRef): Promise<RegistryRecord | null>;
+    create(ref: SegmentRef, record: NewRegistryRecord): Promise<{
+        token: Token;
+    }>;
+    compareAndSwap(ref: SegmentRef, expected: Token, patch: RegistryPatch): Promise<{
+        token: Token;
+    }>;
+    list(namespace?: string): AsyncIterable<RegistryRecord>;
+    delete(ref: SegmentRef): Promise<void>;
+}
+
+interface CrbmWriterOptions {
+    /** Self-describing generation number (also encoded in the object key). */
+    readonly generation: number;
+    readonly roaringSerializationId?: number;
+    readonly elementWidth?: number;
+    /** When set, payloads + index are AES-256-GCM-encrypted, bound to `(segment, generation, scope)` via AAD. */
+    readonly crypto?: CrbmCrypto;
+}
+declare class CrbmWriter {
+    private readonly sink;
+    private readonly options;
+    private readonly entries;
+    private offset;
+    private lastKey;
+    private totalCardinality;
+    private preambleWritten;
+    private finished;
+    constructor(sink: BlobSink, options: CrbmWriterOptions);
+    /**
+     * Append one chunk's payload (the roaring-serialized bytes) with its cardinality. `chunkKey` must be
+     * strictly greater than the previous one (ascending, no duplicates); `cardinality` is `[1, 65536]`.
+     */
+    addChunk(chunkKey: number, payload: Uint8Array, cardinality: number): Promise<void>;
+    /** Seal one chunk payload into the on-disk frame `nonce ‖ ciphertext ‖ tag`, bound to its chunkKey. */
+    private sealChunk;
+    /** Write the index region + the fixed footer. After this the object is complete and immutable. */
+    finish(): Promise<void>;
+    private ensurePreamble;
+    private encodeIndex;
+    private buildFooter;
+}
+
+export { AWS_US_EAST_1_ONDEMAND, Aead, AeadSealed, type AuditEvent, type AuditEventKind, BlobReader, BlobSink, BoundedLru, type Budget, BudgetExceededError, type BudgetOption, type BulkLoadResult, CapabilityError, ChunkRef, type Clock, CloudRoaringError, type CodecBitmap, type CodecInterface, ColdCaps, ColdChunkSource, type CompactionCandidate, type CompactionCycleResult, type CompactionDeps, type CompactionOptions, type CompactionResult, type ConsistencyErrorEntry, type ConsistencyIssue, type ConsistencyReport, type CostAdvisory, type CostReport, CountingMetricsSink, CrbmColdChunkSource, type CrbmColdChunkSourceOptions, CrbmCrypto, CrbmReader, type CrbmReaderOptions, CrbmWriter, type CrbmWriterOptions, DEFAULT_BUDGET, DEFAULT_OCC_BACKOFF, DEFAULT_PRICING, DEFAULT_RETRY_POLICY, type DestroyResult, type DiscoveryOptions, type EngineDeps, type EraseDeps, type EstimateInput, type ExportFailure, type ExportFormat, type ExportManifest, type ExportOptions, type ExportSink, type ExportWriter, type ExportedSegment, GenKey, type IAuditSink, IColdDriver, IKeystore, type IMetricsSink, IRegistryDriver, IWarmDriver, InProcessKeystore, type InProcessKeystoreOptions, IntegrityError, KeyUnavailableError, LocalFsColdDriver, LocalFsRegistryDriver, type LocalFsRegistryDriverOptions, LocalFsWarmDriver, MemoryColdChunkSource, MemoryColdDriver, MemoryRegistryDriver, type MemoryRegistryDriverOptions, MemoryWarmDriver, type MetricEvent, type MetricOpName, type MetricsSnapshot, NOOP_AUDIT, NOOP_METRICS, NewRegistryRecord, NoRow, NodeAead, NotFoundError, type PricingProfile, RecordingAuditSink, RegCaps, RegistryPatch, RegistryRecord, type RetryDeps, type RetryPolicy, RetryingColdChunkSource, RetryingColdDriver, type RetryingOptions, RetryingRegistryDriver, RetryingWarmDriver, type Rng, SegmentEngine, SegmentRef, SegmentSize, type SegmentSizing, TimeoutError, Token, type Topology, TransientError, UnsupportedError, ValidationError, WarmReadOptions, WarmRow, type Workload, WrappedDek, WriteConflictError, bulkLoadCrbmGeneration, checkBudget, chunkRefKey, compactSegment, destroySegment, eraseNamespace, estimateCost, findCompactable, gcOrphanGenerations, groundedReport, isCloudRoaringError, isIntegrityError, isNotFoundError, isTransient, isTransientError, isValidationError, isWriteConflictError, joinId, mapWithConcurrency, publishGeneration, resolveBudget, resolvePerOpBudget, runCompactionCycle, runConsistencyCheck, runExport, safeMetrics, segmentKey, splitId, validateCompactionOptions, validateSegmentRef, withRetry, writeCrbmGeneration };