@cloudbitmaps/roaring 0.1.0-rc.0

package/dist/index.d.ts

@@ -0,0 +1,446 @@
+import { bulkLoadCrbmGeneration as bulkLoadCrbmGeneration$1, compactSegment as compactSegment$1, runCompactionCycle as runCompactionCycle$1, runExport as runExport$1, CodecBitmap, CodecInterface, IColdDriver, ColdChunkSource, IWarmDriver, IRegistryDriver, IKeystore, Clock, Rng, RetryPolicy, IMetricsSink, BudgetOption, SegmentEngine, SegmentRef, PricingProfile, Workload, Topology, CostReport, IAuditSink, CompactionOptions, CompactionResult, ConsistencyReport, ExportSink, ExportOptions, ExportManifest, EstimateInput } from '@cloudbitmaps/core';
+export * from '@cloudbitmaps/core';
+
+/**
+ * Codec-bound wrappers over the public `@cloudbitmaps/core` entry points that need a bitmap codec.
+ *
+ * `core` is codec-agnostic and therefore cannot default the codec (the concrete codec lives *here*, in a package
+ * that depends on core — a default over there would invert the dependency arrow). But an application using
+ * `@cloudbitmaps/roaring` should never have to pass one. So this module re-binds each such entry point with
+ * {@link roaringCodec} and the facade re-exports these **explicitly**, which shadows the same names coming from
+ * `export * from '@cloudbitmaps/core'` (an explicit export always wins over a star export). Net effect: every
+ * call signature is unchanged from before the family split — you can still call
+ * `bulkLoadCrbmGeneration(driver, key, ids)` with no options at all.
+ *
+ * A caller who *wants* a different codec passes it explicitly; the binding only fills an absent one — via
+ * `?? roaringCodec` rather than spread order, so an explicit `codec: undefined` still gets the binding
+ * (`exactOptionalPropertyTypes` is off, so that call typechecks and must not fall through to the throw).
+ */
+
+type BulkLoad = typeof bulkLoadCrbmGeneration$1;
+type CompactSegment = typeof compactSegment$1;
+type RunCompactionCycle = typeof runCompactionCycle$1;
+type RunExport = typeof runExport$1;
+/** {@link coreBulkLoad} with the roaring codec pre-bound. */
+declare const bulkLoadCrbmGeneration: BulkLoad;
+/** {@link coreCompactSegment} with the roaring codec pre-bound. */
+declare const compactSegment: CompactSegment;
+/** {@link coreRunCompactionCycle} with the roaring codec pre-bound. */
+declare const runCompactionCycle: RunCompactionCycle;
+/** {@link coreRunExport} with the roaring codec pre-bound (only the `'roaring'` format needs it). */
+declare const runExport: RunExport;
+
+declare class SafeBitmap implements CodecBitmap {
+    private readonly bitmap;
+    private constructor();
+    static empty(): SafeBitmap;
+    static fromValues(values: Iterable<number>): SafeBitmap;
+    /**
+     * S1: validate size, then deserialize with the **portable** (validated) format.
+     * Throws `IntegrityError` if the input exceeds `maxBytes` or fails to decode — the
+     * native addon is never handed unbounded or unsafe-format input.
+     */
+    static safeDeserialize(bytes: Uint8Array, maxBytes: number): SafeBitmap;
+    serialize(): Uint8Array;
+    add(value: number): void;
+    addMany(values: Iterable<number>): void;
+    remove(value: number): void;
+    removeMany(values: Iterable<number>): void;
+    has(value: number): boolean;
+    get size(): number;
+    get isEmpty(): boolean;
+    clone(): SafeBitmap;
+    /** In-place union: `this = this ∪ other`. */
+    orInPlace(other: CodecBitmap): void;
+    /** In-place difference: `this = this \ other`. */
+    andNotInPlace(other: CodecBitmap): void;
+    /** In-place intersection: `this = this ∩ other`. */
+    andInPlace(other: CodecBitmap): void;
+    /** Ascending iterator over the set values. */
+    [Symbol.iterator](): IterableIterator<number>;
+    toArray(): number[];
+}
+/**
+ * The roaring {@link CodecInterface} — the flagship codec, delegating to {@link SafeBitmap}'s statics. This is
+ * the default the `CloudRoaring` facade injects into the engine; `core/` itself never hard-references it once a
+ * caller supplies a codec. Moves to `@cloudbitmaps/roaring` when the package split lands ([DECISIONS #58]).
+ */
+declare const roaringCodec: CodecInterface;
+
+/**
+ * CloudRoaring — distributed, cloud-native Roaring Bitmaps.
+ *
+ * The `CloudRoaring` class is the read/write engine over the tiered seams. You wire storage **once**, as a
+ * single config object: a Cold driver (`cold`), a Warm driver (`warm`), and optionally a `registry` (the
+ * authoritative generation pointer — needed to read encrypted segments and to resolve generations without a
+ * cold `list`-scan) and a `keystore` (encryption-at-rest / crypto-shred). Pass a **raw** {@link IColdDriver}
+ * as `cold` (e.g. `S3ColdDriver`, `LocalFsColdDriver`, `MemoryColdDriver`) and the store assembles the `.crbm`
+ * cold source ({@link CrbmColdChunkSource}) for you — so each driver is named exactly once. Or pass an
+ * already-built {@link ColdChunkSource} to control advanced reader options yourself.
+ *
+ * In-process lifecycle helpers — `compact`, `eraseSubject`, `subjectReport` — reuse the store's own drivers, so
+ * you never re-pass them (they need the store built with a raw cold driver + registry). Out-of-process cold
+ * writers (the compaction daemon, the seed/bulk-load CLI, `destroySegment`/`eraseNamespace`) wire their own deps
+ * against the same drivers — they run in separate processes.md + the
+ * getting-started guide.
+ */
+
+/**
+ * Wiring for a {@link CloudRoaring} store. **Only `cold` and `warm` are required** — the minimal call is
+ * `new CloudRoaring({ cold, warm })`. Add a `registry` to unlock eject / compaction / encryption and to skip the
+ * cold list-scan (recommended for anything beyond a quick look). Everything else is **optional tuning with
+ * sensible defaults** — resilience/retries are already on, the hot cache is bounded, metrics are a no-op — so
+ * reach for them only when you need to.
+ */
+interface CloudRoaringOptions {
+    /**
+     * Cold tier. Pass a **raw** {@link IColdDriver} (`S3ColdDriver`, `LocalFsColdDriver`, `MemoryColdDriver`, …)
+     * and the store wraps it in a {@link CrbmColdChunkSource} using `registry`/`keystore` below — the common case,
+     * so you wire each driver **once**. Or pass an already-built {@link ColdChunkSource} (`MemoryColdChunkSource`,
+     * or a `CrbmColdChunkSource` you configured with advanced reader options) to use as-is.
+     */
+    readonly cold: IColdDriver | ColdChunkSource;
+    /** Warm tier: the per-chunk delta store under OCC (`DynamoDbWarmDriver`, `LocalFsWarmDriver`, `MemoryWarmDriver`). */
+    readonly warm: IWarmDriver;
+    /**
+     * Authoritative registry — the per-segment `currentGen` pointer + wrapped-DEK holder. Applies when `cold` is a
+     * **raw driver**: it (a) resolves the current generation with one strong read instead of a cold `list`-scan,
+     * and (b) lets the store read **encrypted** segments (that's where wrapped DEKs live). Optional — a
+     * registry-less store reads the highest generation by list-scanning Cold (cleartext only). When you pass a
+     * pre-built `ColdChunkSource`, that source resolves its own generations, so a top-level `registry` is inert
+     * there and rejected as a wiring mistake — configure it on the source instead.
+     */
+    readonly registry?: IRegistryDriver;
+    /**
+     * Keystore for encryption-at-rest / crypto-shred (Phase 4e). Required to read encrypted segments; needs a
+     * `registry` (that's where wrapped DEKs are stored). Applied only when `cold` is a raw driver — when you pass a
+     * pre-built {@link ColdChunkSource}, configure the keystore on that source instead.
+     */
+    readonly keystore?: IKeystore;
+    /**
+     * Refuse to read a **cleartext** segment — a guard against silently reading data that should be encrypted.
+     * Needs a `registry`; applied only when `cold` is a raw driver. Off by default (encryption is opt-in).
+     */
+    readonly requireEncryption?: boolean;
+    /** Injected for deterministic tests; defaults to a system clock. */
+    readonly clock?: Clock;
+    /** Injected for deterministic tests; defaults to `Math.random`-backed. Drives backoff jitter. */
+    readonly rng?: Rng;
+    /** HOT cache ceiling (decoded Cold chunks). */
+    readonly cacheMaxChunks?: number;
+    /** Optional TTL on cached chunks (ms). */
+    readonly cacheTtlMs?: number;
+    /**
+     * How long (ms) the store trusts a segment's resolved `currentGen` before re-resolving it on the next read
+     * (default 2000) — the bound on read staleness after a compaction commits a new generation (gap #4). Applies
+     * only when `cold` is a raw driver **and** a `registry` is wired (the cheap `currentGen` read the refresh
+     * needs; a registry-less store pins per source lifetime). Lazy — no timer; ≤ one registry read per segment per
+     * window, opening a new reader only when the generation actually advanced.
+     */
+    readonly coldGenTtlMs?: number;
+    /**
+     * Ceiling on how many segments' `.crbm` readers (each holding a parsed index) the store keeps open at once
+     * (default 1024) — the steady-state memory bound for a long-running server that reads across many segments
+     * (gap #1). Past it the least-recently-used segment's reader is evicted; re-opening it later is one cheap tail
+     * GET. Applies only when `cold` is a raw driver (a pre-built `ColdChunkSource` manages its own reader cache).
+     */
+    readonly coldReaderCacheMax?: number;
+    /**
+     * Aggregate byte ceiling on the parsed `.crbm` indices the open readers hold (default 64 MiB) — the byte
+     * half of the gap #1 memory bound, complementing the `coldReaderCacheMax` *count* bound. A wide/dense
+     * segment's parsed index can be several MB, so a count-only bound could let the open readers pin ~GBs and
+     * blow a small heap (e.g. a 128 MB Lambda); this evicts the least-recently-used reader once the summed index
+     * footprint would exceed the ceiling — whichever of the count/byte bounds binds first. Lower it for
+     * memory-tight deployments that read across wide segments. Applies only when `cold` is a raw driver.
+     */
+    readonly coldReaderCacheMaxBytes?: number;
+    /**
+     * Resilience: by default every warm/cold call retries **transient** faults (throttling, 5xx, dropped
+     * connections) with bounded, jittered exponential backoff (see {@link DEFAULT_RETRY_POLICY}), and OCC
+     * conflicts back off between retries. Pass a {@link RetryPolicy} to tune it, or `false` to disable the
+     * transient-retry wrappers entirely (e.g. if your injected client already retries). Deterministic errors
+     * (`ValidationError`/`IntegrityError`/`WriteConflictError`/…) are never retried by this layer.
+     */
+    readonly retry?: RetryPolicy | false;
+    /** Backoff schedule between OCC conflict retries; defaults to a small, tight one. */
+    readonly occBackoff?: RetryPolicy;
+    /** Observability: called before each transient-retry backoff wait. */
+    readonly onRetry?: (info: {
+        attempt: number;
+        delayMs: number;
+        err: unknown;
+    }) => void;
+    /**
+     * Observability sink (Phase 5a): receives typed metric events (cold GET/bytes, warm read/write, cache
+     * hit/miss, retries, intersection efficiency, op latency). Defaults to a no-op — emission is skipped
+     * entirely when unused (near-zero overhead). Any exception the sink throws is swallowed — metrics can
+     * never break a read/write.
+     */
+    readonly metrics?: IMetricsSink;
+    /**
+     * Warm read consistency for the READ paths (`has`/`count`/`iterate`/`intersect`). Default `'strong'`
+     * (read-your-writes). `'eventual'` trades read-after-write for **~½ the DynamoDB read cost** (a strong read
+     * bills 2× RCU) — a good fit for read-heavy, staleness-tolerant workloads (mirrors the cold tier's bounded
+     * eventual reads). The compaction/OCC write path is always strongly consistent regardless. No effect on the
+     * in-memory/LocalFs drivers (always strong). (Audit gap #9.)
+     */
+    readonly warmReadConsistency?: 'strong' | 'eventual';
+    /**
+     * Max Warm chunk writes in flight per `addMany`/`removeMany` (the bounded flusher). Default **1** (serial —
+     * unchanged). Raise it to fan distinct-chunk writes out for throughput on wide multi-chunk batches; each
+     * chunk is its own OCC row so this is safe, and (as before) a mid-flush failure can leave a partial result.
+     */
+    readonly writeConcurrency?: number;
+    /**
+     * Per-op **denial-of-wallet** budget (Decision #3 / invariant T3): the max backend requests a
+     * single `count`/`iterate`/`intersect`/`subjectReport`/`eraseSubject` may fan out into before it's refused
+     * with {@link BudgetExceededError} — so one runaway op can't drive unbounded RCU/GET cost on a shared backend.
+     * **On by default, generous** ({@link DEFAULT_BUDGET}: 1,000,000 requests — a normal op never hits it). Tune
+     * with `{ maxRequests }`, override per op (on `intersect`/`subjectReport`/`eraseSubject`), or set `false` to
+     * disable. The check is O(1) (before fan-out), so the hot path is untouched; per-request bytes are separately
+     * size-capped, so bounding requests transitively bounds bytes.
+     */
+    readonly budget?: BudgetOption;
+}
+interface SegmentOptions {
+    readonly namespace?: string;
+}
+/** A segment reference in a subject report / erasure ledger. */
+interface SubjectSegmentRef {
+    readonly segment: string;
+    readonly namespace?: string;
+}
+/** Result of {@link CloudRoaring.subjectReport} — the segments an id is a member of (over registered segments). */
+interface SubjectReport {
+    readonly id: number;
+    /** The registered segments the id is currently a member of. */
+    readonly segments: SubjectSegmentRef[];
+    /** How many registered segments were scanned (the completeness denominator). */
+    readonly scannedSegments: number;
+}
+/** One segment's entry in an erasure ledger (see {@link EraseSubjectResult}). */
+interface SubjectErasureEntry {
+    readonly segment: string;
+    readonly namespace?: string;
+    /** The id was present and a logical `remove` tombstone was written. */
+    readonly removed: boolean;
+    /**
+     * True iff *this call* committed a new generation with the segment's tombstones applied — the bit is
+     * physically gone from Cold (assuming no concurrent re-add of the id; see {@link CloudRoaring.eraseSubject}).
+     * `false` is **conservative**: the purge may have been deferred (`note:'leased-by-other'`) or already done by
+     * a concurrent daemon (`note:'clean'`); the logical removal holds regardless.
+     */
+    readonly physicallyPurged: boolean;
+    /** The generation that retired the bit (present when `physicallyPurged`). */
+    readonly toGen?: number;
+    /** Why physical purge wasn't committed by this call (compaction's `reason`, e.g. `'leased-by-other'`, `'clean'`). */
+    readonly note?: string;
+}
+/**
+ * The erasure ledger returned by {@link CloudRoaring.eraseSubject} — your proof-of-deletion artifact. It is a
+ * return value only (no library-side persistence): persist it / route it to your audit sink as you see fit.
+ */
+interface EraseSubjectResult {
+    readonly id: number;
+    /** Per-segment records for the segments the id was erased from (absent segments are not listed). */
+    readonly erasedFrom: SubjectErasureEntry[];
+    /** How many registered segments were scanned. */
+    readonly scannedSegments: number;
+}
+declare class CloudRoaring {
+    private readonly engine;
+    private readonly clock;
+    private readonly metrics;
+    private readonly coldDriver;
+    private readonly warmDriver;
+    private readonly registry;
+    private readonly keystore;
+    private readonly requireEncryption;
+    /** Resolved store-level per-op budget (null = disabled); the admin scans use it, with a per-op override. */
+    private readonly budget;
+    constructor(options: CloudRoaringOptions);
+    /**
+     * Build {@link CompactionDeps} from the store's own drivers, for the in-process lifecycle helpers
+     * ({@link compact} / {@link eraseSubject}). Requires the store to have been constructed with a **raw cold
+     * driver** (a pre-built `ColdChunkSource` has no underlying `IColdDriver` to compact through) and a `registry`
+     * (the authoritative `currentGen` pointer compaction swaps). Out-of-process callers use the `compactSegment`
+     * free function with explicit deps.
+     */
+    private compactionDeps;
+    /** Get a handle to a segment. Validates the name/namespace grammar (finding S2). */
+    segment(name: string, options?: SegmentOptions): Segment;
+    /**
+     * **Subject access (GDPR Art. 15 / CCPA right-to-know): which segments is this id a member of?** (Phase 6b.)
+     *
+     * Enumerates the **registered** segments (via the store's own `registry`) and does a tier-merging `has(id)` on
+     * each — no drivers to re-pass. Complete only over registered segments (register your segments if you claim
+     * SAR support). There is deliberately **no `id → segments` reverse index** — that would tax every write for a
+     * rare request; this admin scan is `O(registered segments)` and touches no hot path
+     * (phases/06). Requires a `registry` in the store config
+     * (throws {@link UnsupportedError} otherwise).
+     */
+    subjectReport(id: number, options?: {
+        namespace?: string;
+        allNamespaces?: boolean;
+        concurrency?: number;
+        budget?: BudgetOption;
+    }): Promise<SubjectReport>;
+    /**
+     * **Subject erasure (GDPR Art. 17): remove an id from every segment it's in, with a physical-deletion
+     * guarantee.** (Phase 6b.)
+     *
+     * For each **registered** segment the id is a member of: writes a logical `remove` tombstone (immediate) and
+     * then **force-compacts that segment now** — folding the tombstone into a fresh immutable generation so the
+     * bit is *physically* gone from Cold on return, even for an otherwise-idle/archival segment that organic
+     * compaction would never touch (the P13 fix). The returned per-segment record is your **erasure ledger** —
+     * persist it / route it to your audit sink as the proof of deletion; the physical-purge proof is
+     * compaction's own VERIFY step (a re-`has()` here would be unsound — a pinned cold source can still read the
+     * old generation; take a fresh generation view after erasing, exactly as with the compaction daemon).
+     *
+     * Uses the store's **own** drivers (raw cold + warm + registry), so the old integrator obligation to wire a
+     * matching `CompactionDeps` is gone — the `remove()` and the force-compaction provably run over the same tiers.
+     * Requires the store built with a **raw cold driver + registry** (throws {@link UnsupportedError} otherwise;
+     * a pre-built `ColdChunkSource` store has no `IColdDriver` to compact through — use the `compactSegment` free
+     * function there). **One contract remains** (an integrator obligation the library cannot check): **do not
+     * concurrently re-add the same id while erasing it.** A normal `add(id)` landing between the `remove` and the
+     * compaction clears the tombstone and folds the id back into the new generation
+     * (`effective = (cold ∪ adds) \ removes`); `physicallyPurged` attests only that compaction committed a
+     * generation with the tombstones applied at pin time — quiesce writes for the subject during erasure.
+     *
+     * **A `physicallyPurged:false` entry means the logical removal holds but the physical purge didn't run this
+     * call** — either a daemon held a live lease (`note:'leased-by-other'`; the daemon finishes it), or the
+     * force-compaction hit an isolated fault (`note:'error: …'`; per-segment faults are caught so one segment
+     * can't discard the whole ledger). `physicallyPurged:false` is **conservative** (a concurrent daemon may
+     * already have purged the bit — `'clean'`). **Recovery:** follow up any `physicallyPurged:false` entry with
+     * `store.compact(ref)` (or let the daemon do it) — **re-running `eraseSubject` will NOT re-purge it**, because
+     * `has()` now reads false (the tombstone) so the segment is skipped as a non-member. The physical-purge proof
+     * is compaction's own VERIFY step (a re-`has()` here would be unsound: a pinned cold source can still read the
+     * old generation — take a fresh generation view after erasing, as with the daemon). Admin-only path;
+     * `O(registered segments)`, no hot-path cost. Per-subject crypto-shred is infeasible (a subject's bit is
+     * co-mingled in a shared container), so this is the single-subject erasure route; whole-segment/tenant erasure
+     * is the `destroySegment`/`eraseNamespace` free functions.
+     */
+    eraseSubject(id: number, options: {
+        owner: string;
+        namespace?: string;
+        allNamespaces?: boolean;
+        audit?: IAuditSink;
+        concurrency?: number;
+        budget?: BudgetOption;
+    }): Promise<EraseSubjectResult>;
+    /**
+     * **Compact one segment now**, in-process, using the store's own drivers — a convenience over the
+     * {@link compactSegment} free function. Merges `(cold ∪ adds) \ removes` into a fresh immutable generation,
+     * swaps `currentGen`, then version-fenced-purges the archived Warm rows. A no-op (`compacted:false`) when the
+     * segment has no dirty rows or a daemon holds a live lease — never throws on the normal contention/lease paths.
+     * Requires the store built with a **raw cold driver + registry** (throws {@link UnsupportedError} otherwise);
+     * like the daemon, it uses the raw drivers directly (a transient fault surfaces to you rather than retrying
+     * under the hood). **Not for the request/hot path** — it reads and rewrites a whole Cold generation (streaming,
+     * constant-memory, but full-segment I/O). Use the `compact-segments` daemon (`runCompactionCycle`) for routine
+     * background compaction; reach for `store.compact()` for occasional/manual one-shots — a maintenance endpoint,
+     * a small daemon-less deployment, or right after a targeted `remove`.
+     */
+    compact(ref: SegmentRef, options: CompactionOptions): Promise<CompactionResult>;
+    /**
+     * **Cross-tier DR consistency check (audit gap #11).** After a restore/failover, verify every registered
+     * segment's `currentGen` actually has its `.crbm` present in Cold — catching a **torn restore** where the
+     * registry (`currentGen`) came back ahead of the object store, so a pointer references a generation that
+     * isn't there (reads would then throw). Read-only, bounded fan-out; run it at startup after a restore.
+     * Returns `{ checked, inconsistent }` — `inconsistent` empty ⇒ coherent; otherwise it names the segments to
+     * recover (restore the object store, or roll the registry back to a coherent point). Needs the store built
+     * with a **raw cold driver + a registry** (throws {@link UnsupportedError} otherwise). `destroyed`
+     * (crypto-shredded) segments are skipped. Pair it with the DR runbook (docs/guide/disaster-recovery.md).
+     */
+    checkConsistency(options?: {
+        namespace?: string;
+        concurrency?: number;
+    }): Promise<ConsistencyReport>;
+    /**
+     * **Export ("eject") every registered segment's current effective set** through the injected `sink`, using
+     * only public read APIs — so your data is readable **without CloudRoaring** (the exit path; see the README's
+     * "Your data stays yours"). `format: 'roaring'` (default) writes one **portable RoaringBitmap32** per segment
+     * (loadable by any roaring library); `'ndjson'` writes newline-delimited ids (zero-dependency, streaming).
+     * Enumerates via the store's **own** registry (needs one — throws {@link UnsupportedError} otherwise) so the
+     * enumeration and the read path provably share one registry; an all-warm segment not yet in the registry can be
+     * named via `options.candidates`. Encrypted segments are decrypted transparently **iff** this store was wired
+     * with their keystore — the export is therefore **cleartext**; protect it. Crypto-shredded segments are skipped.
+     * A segment that can't be read is isolated into the manifest's `failed[]` (the run continues), so "a manifest
+     * exists" means the run finished — check `failed`. The `export-segments` CLI wraps this with a filesystem sink.
+     */
+    exportSegments(sink: ExportSink, options?: ExportOptions): Promise<ExportManifest>;
+    /**
+     * Planning cost estimate (Phase 5b) — pure, no instance/data needed: sizing, sales, what-if. For a real,
+     * grounded report from live segment sizes, use `store.segment(name).costReport()`. See {@link CostReport}.
+     */
+    static estimateCost(input: EstimateInput): CostReport;
+}
+/**
+ * A handle bound to one segment — the seven ops.
+ *
+ * **IDs must be integers in `[0, 2^32)`** (dense 32-bit). A non-integer / negative / out-of-range id
+ * throws {@link ValidationError}.
+ *
+ * **`addMany`/`removeMany`/`intersectInto` are not atomic across chunks**: ids are grouped by chunk and
+ * applied one chunk at a time, so if a later chunk fails (e.g. {@link WriteConflictError} after retries)
+ * earlier chunks are already applied. Within a single chunk the update is atomic.
+ */
+declare class Segment {
+    private readonly engine;
+    private readonly ref;
+    private readonly clock;
+    private readonly metrics;
+    private readonly metricsOn;
+    constructor(engine: SegmentEngine, ref: SegmentRef, clock: Clock, metrics: IMetricsSink);
+    /**
+     * Time an op with the injected clock and emit an `op` metric on completion (success or throw). Skipped
+     * entirely when no sink is wired, so the default path pays nothing.
+     */
+    private timed;
+    /** Add an id (integer in `[0, 2^32)`). Throws {@link ValidationError} on a bad id. */
+    add(id: number): Promise<void>;
+    /** Add many ids. Not atomic across chunks — see the class note. */
+    addMany(ids: Iterable<number>): Promise<void>;
+    /** Remove an id (integer in `[0, 2^32)`). Throws {@link ValidationError} on a bad id. */
+    remove(id: number): Promise<void>;
+    /** Remove many ids. Not atomic across chunks — see the class note. */
+    removeMany(ids: Iterable<number>): Promise<void>;
+    has(id: number): Promise<boolean>;
+    count(): Promise<number>;
+    iterate(): AsyncIterable<number>;
+    /**
+     * Chunk-skipping intersection: stream the ids in **this** segment AND every segment in `others`, ascending.
+     * Fetches only the Cold chunks present in *all* operands (a key absent from any operand contributes nothing
+     * and is never downloaded), streaming under a bounded in-flight window — so the Cold footprint stays small
+     * (Lambda-friendly) regardless of segment size. Pass `concurrency` to tune that window (a positive integer).
+     * AND is commutative, so `a.intersect([b])` and `b.intersect([a])` yield the same ids. (Warm state is read
+     * up front, so total memory also carries each operand's Warm size — negligible under Topology-A.) Pass
+     * `budget` to override the store's per-op denial-of-wallet budget for this call (or `false` to lift it).
+     */
+    intersect(others: Segment[], options?: {
+        concurrency?: number;
+        budget?: BudgetOption;
+    }): AsyncIterable<number>;
+    /**
+     * Materialize `this ∩ others…` **into** `dest` (added, not replaced). Streaming + bounded-memory, but
+     * **not atomic** across chunks — see {@link addMany}.
+     */
+    intersectInto(dest: Segment, others: Segment[], options?: {
+        concurrency?: number;
+        batchSize?: number;
+    }): Promise<void>;
+    /**
+     * Grounded cost report for this segment (Phase 5b): storage cost from its **real** `.crbm` size (exact,
+     * no payload reads); request cost from the supplied `workload` rates. A segment with no Cold generation
+     * reports zero storage. See {@link CostReport} — it always includes a verdict (incl. the lose-zone).
+     */
+    costReport(options?: {
+        pricing?: PricingProfile;
+        workload?: Workload;
+        topology?: Topology;
+    }): Promise<CostReport>;
+}
+
+/** Package version marker. Kept in sync with package.json at release. */
+declare const VERSION = "0.1.0-rc.0";
+
+export { CloudRoaring, type CloudRoaringOptions, type EraseSubjectResult, SafeBitmap, Segment, type SegmentOptions, type SubjectErasureEntry, type SubjectReport, type SubjectSegmentRef, VERSION, bulkLoadCrbmGeneration, compactSegment, roaringCodec, runCompactionCycle, runExport };