@cloudbitmaps/roaring 0.8.2 → 0.10.0

package/dist/index.d.cts

@@ -1,642 +0,0 @@
-import { bulkLoadCrbmGeneration as bulkLoadCrbmGeneration$1, compactSegment as compactSegment$1, runCompactionCycle as runCompactionCycle$1, runExport as runExport$1, CodecBitmap, CodecInterface, BudgetOption, IColdDriver, ColdChunkSource, IWarmDriver, IRegistryDriver, IKeystore, Clock, Rng, RetryPolicy, IMetricsSink, SegmentEngine, SegmentRef, PricingProfile, Workload, Topology, CostReport, IAuditSink, CompactionOptions, CompactionResult, DropResult, ConsistencyReport, ExportSink, ExportOptions, ExportManifest, EstimateInput } from '@cloudbitmaps/core';
-export * from '@cloudbitmaps/core';
-
-/**
- * Codec-bound wrappers over the public `@cloudbitmaps/core` entry points that need a bitmap codec.
- *
- * `core` is codec-agnostic and therefore cannot default the codec (the concrete codec lives *here*, in a package
- * that depends on core — a default over there would invert the dependency arrow). But an application using
- * `@cloudbitmaps/roaring` should never have to pass one. So this module re-binds each such entry point with
- * {@link roaringCodec} and the facade re-exports these **explicitly**, which shadows the same names coming from
- * `export * from '@cloudbitmaps/core'` (an explicit export always wins over a star export). Net effect: every
- * call signature is unchanged from before the family split — you can still call
- * `bulkLoadCrbmGeneration(driver, key, ids)` with no options at all.
- *
- * A caller who *wants* a different codec passes it explicitly; the binding only fills an absent one — via
- * `?? roaringCodec` rather than spread order, so an explicit `codec: undefined` still gets the binding
- * (`exactOptionalPropertyTypes` is off, so that call typechecks and must not fall through to the throw).
- */
-
-type BulkLoad = typeof bulkLoadCrbmGeneration$1;
-type CompactSegment = typeof compactSegment$1;
-type RunCompactionCycle = typeof runCompactionCycle$1;
-type RunExport = typeof runExport$1;
-/**
- * {@link coreBulkLoad} with the roaring codec **and a real clock** pre-bound.
- *
- * The clock is what makes a large load **cooperative**: bulk-load yields the event loop periodically instead of
- * stalling the process for its whole duration (measured end-to-end at 450 ms of unbroken blocking for a 1M-id
- * load, now ~19 ms worst case). `core/` cannot
- * default it — it is timer-free by lint, which is precisely why waiting goes through the `Clock` seam — so the
- * flavor package supplies it, exactly as it supplies the codec. A caller who passes their own clock (a virtual
- * one in a simulation, say) keeps it.
- */
-declare const bulkLoadCrbmGeneration: BulkLoad;
-/** {@link coreCompactSegment} with the roaring codec pre-bound. */
-declare const compactSegment: CompactSegment;
-/** {@link coreRunCompactionCycle} with the roaring codec pre-bound. */
-declare const runCompactionCycle: RunCompactionCycle;
-/** {@link coreRunExport} with the roaring codec pre-bound (only the `'roaring'` format needs it). */
-declare const runExport: RunExport;
-
-declare class SafeBitmap implements CodecBitmap {
-    private readonly bitmap;
-    private constructor();
-    static empty(): SafeBitmap;
-    static fromValues(values: Iterable<number>): SafeBitmap;
-    /**
-     * S1: validate size, then deserialize with the **portable** (validated) format.
-     * Throws `IntegrityError` if the input exceeds `maxBytes` or fails to decode — the
-     * native addon is never handed unbounded or unsafe-format input.
-     */
-    static safeDeserialize(bytes: Uint8Array, maxBytes: number): SafeBitmap;
-    serialize(): Uint8Array;
-    /**
-     * Convert containers to run-encoding where that is smaller. Representation only — membership is untouched, and
-     * the portable format still round-trips through {@link RoaringCodec.safeDeserialize}.
-     *
-     * Roaring's third container type is a RUN, and no implementation selects it on its own: it takes an explicit
-     * `runOptimize()` pass. Nothing here made that call, so run-shaped ids paid array or bitset prices — measured
-     * at **570×** for a contiguous 1M-id range (128.1 KiB → 0.2 KiB) and **63×** for a 2,000-run shape
-     * (536.5 KiB → 8.5 KiB). Sparse ids come out byte-identical, so this is never a losing trade; roaring keeps
-     * whichever encoding is smaller per container.
-     *
-     * Those two factors are THIS CALL's own before/after on the same ids. They are not the ones the site quotes
-     * (543× and 63×) — those compare the optimized encoding against the best *fixed* representation at its floor,
-     * a different baseline that happens to land near 63× on the run shape too. `pnpm bench:encoding` prints both
-     * columns; don't carry a figure between them without checking which denominator it had.
-     *
-     * Called by the engine only when writing an immutable cold generation — see {@link CodecBitmap.optimize} for
-     * why the per-operation warm path deliberately does not.
-     */
-    optimize(): void;
-    /**
-     * Largest value, or `undefined` when empty. O(1) — roaring reads it off the container index, so the engine's
-     * per-chunk range assertion costs one call per chunk rather than a walk per id.
-     */
-    maximum(): number | undefined;
-    add(value: number): void;
-    addMany(values: Iterable<number>): void;
-    remove(value: number): void;
-    removeMany(values: Iterable<number>): void;
-    has(value: number): boolean;
-    get size(): number;
-    get isEmpty(): boolean;
-    clone(): SafeBitmap;
-    /** In-place union: `this = this ∪ other`. */
-    orInPlace(other: CodecBitmap): void;
-    /** In-place difference: `this = this \ other`. */
-    andNotInPlace(other: CodecBitmap): void;
-    /** In-place intersection: `this = this ∩ other`. */
-    andInPlace(other: CodecBitmap): void;
-    /** Ascending iterator over the set values. */
-    [Symbol.iterator](): IterableIterator<number>;
-    toArray(): number[];
-}
-/**
- * The roaring {@link CodecInterface} — the flagship codec, delegating to {@link SafeBitmap}'s statics. This is
- * the default the `CloudRoaring` facade injects into the engine; `core/` itself never hard-references it once a
- * caller supplies a codec. Moves to `@cloudbitmaps/roaring` when the package split lands.
- */
-declare const roaringCodec: CodecInterface;
-
-/**
- * CloudRoaring — distributed, cloud-native Roaring Bitmaps.
- *
- * The `CloudRoaring` class is the read/write engine over the tiered seams. You wire storage **once**, as a
- * single config object: a Cold driver (`cold`), a Warm driver (`warm`), and optionally a `registry` (the
- * authoritative generation pointer — needed to read encrypted segments and to resolve generations without a
- * cold `list`-scan) and a `keystore` (encryption-at-rest / crypto-shred). Pass a **raw** {@link IColdDriver}
- * as `cold` (e.g. `S3ColdDriver`, `LocalFsColdDriver`, `MemoryColdDriver`) and the store assembles the `.crbm`
- * cold source ({@link CrbmColdChunkSource}) for you — so each driver is named exactly once. Or pass an
- * already-built {@link ColdChunkSource} to control advanced reader options yourself.
- *
- * 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.
- *
- * **You do not need any of them to start.** Construct a store and call `add`/`addMany`/`has`/`remove` — a segment
- * with no Cold generation at all is fully functional, because a read merges `(cold ∪ warm.adds) \ warm.removes`
- * and an absent Cold tier just makes that merge trivial. `bulkLoadCrbmGeneration` is an **import** path for data
- * you already have elsewhere, not an initialization step, and compaction is a **cost** optimization, never a
- * correctness requirement. See the README and the getting-started guide.
- */
-
-/**
- * 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 **4**
-     * (`DEFAULT_WRITE_CONCURRENCY`); set it to `1` for strictly serial writes.
-     *
-     * Distinct chunks are independent OCC rows, so fanning them out cannot make them conflict with each other.
-     * The bound exists for the *backend*: a provisioned-capacity store answers a burst by throttling, and 4 stays
-     * comfortably inside what the transient-retry path absorbs (measured 8x below the first observed failure).
-     * Raise it if your backend is provisioned for the fan-out — on-demand DynamoDB, or a connection pool sized to
-     * match. A pool *smaller* than this needs no action: `pg` and `mysql2` both queue rather than reject, so the
-     * flusher simply degrades toward serial.
-     *
-     * As before, a mid-flush failure can leave a **partial result**; `addMany`/`removeMany` are not atomic. What
-     * concurrency changes is only how much of the batch may already have landed when the first error surfaces.
-     */
-    readonly writeConcurrency?: number;
-    /**
-     * Hard ceiling on the warm-delta bytes one segment scan may hold resident. Default **64 MiB**.
-     *
-     * **A memory bound, deliberately separate from `budget`, and still enforced when `budget: false`.** The
-     * budget limits *cost* (billable requests); this limits *memory*. They are different axes, and treating the
-     * budget as a memory control is what allowed a segment with thousands of warm chunks to materialise ~12 MB
-     * before a `maxRequests: 2` budget could refuse it. It is also the only bound available to `intersect`,
-     * whose budget is `common keys × operands` — a product a single wide operand can legitimately exceed in row
-     * count while remaining entirely within contract.
-     *
-     * Raise it for genuinely large segments; it exists to keep a modest container alive, not to second-guess you.
-     */
-    readonly maxWarmScanBytes?: number;
-    /**
-     * Per-op **denial-of-wallet** budget (Decision #3 / invariant T3): the max backend requests a
-     * single `count`/`iterate`/`intersect`/`subjectReport`/`eraseSubject` may fan out into before it's refused
-     * with {@link BudgetExceededError} — so one runaway op can't drive unbounded RCU/GET cost on a shared backend.
-     * **On by default, generous** ({@link DEFAULT_BUDGET}: 1,000,000 requests — a normal op never hits it). Tune
-     * with `{ maxRequests }`, override per op (on `intersect`/`subjectReport`/`eraseSubject`), or set `false` to
-     * disable. The check is O(1) (before fan-out), so the hot path is untouched; per-request bytes are separately
-     * size-capped, so bounding requests transitively bounds bytes.
-     */
-    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.
-     * 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>;
-    /**
-     * **Dispose of a segment — tombstone it, delete its Warm rows, delete its Cold objects.** Irreversible.
-     *
-     * The operation a rolling window needs: `destroySegment` crypto-shreds (bytes unreadable everywhere including
-     * backups, but still sitting in your bucket and still billed, and it requires encryption), while this one
-     * removes the storage and works on a cleartext segment. On an encrypted segment it does both.
-     *
-     * Pass `{ dryRun: true }` first — it reports the generations it *would* delete and changes nothing. That
-     * matters more than the `confirmSegment` guard for anything automated, because in a loop the guard is the same
-     * variable twice.
-     *
-     * ```ts
-     * for (const day of expiredDays) {
-     *   // A colon is NOT legal in a name — the family goes in the namespace, the date in the segment.
-     *   const ref = { namespace: 'active-daily', segment: day };
-     *   await store.dropSegment(ref, { confirmSegment: ref.segment });
-     * }
-     * ```
-     *
-     * **Omitting the namespace addresses a different segment and is a silent no-op** — you get
-     * `{ dropped: false, reason: 'absent' }`, not a throw, so a retention loop with that mistake deletes nothing
-     * forever and quietly. Branch on `dropped`, and treat `reason: 'absent'` as the alert.
-     *
-     * **Works on an accumulator too.** A segment you created by writing to it — never bulk-loaded, never compacted,
-     * so it has no registry row and no Cold objects — is retired by deleting its Warm rows alone. That reports
-     * `{ dropped: true, reason: 'warm-only' }`: there is no tombstone to write, and deliberately none is written,
-     * because a `destroyed` row per retired daily bucket would be registry litter. The data really is gone.
-     *
-     * **Inspect `generationsRemaining`.** Empty is the normal outcome; non-empty means the storage was NOT fully
-     * reclaimed and the drop should be re-run. A compaction that was already in flight when the tombstone landed
-     * still finishes staging one more object, so a single sweep can miss it — this call re-sweeps and then reports
-     * whatever it still could not remove rather than returning a result that looks like a clean drop.
-     *
-     * Reads become empty within `coldGenTtlMs` (default 2 s), not instantly: a store that had already read this
-     * segment may answer from its cached generation + hot chunks until that window lapses. A reader that never
-     * touched it sees empty at once. **That bound needs a clock and `coldGenTtlMs > 0`** — a store built without a
-     * clock, or with `coldGenTtlMs: 0` ("pin forever"), holds its resolved snapshot for its own lifetime and can
-     * keep answering `true` for a dropped segment indefinitely; restart it.
-     *
-     * Needs the store built with a **raw cold driver + a registry** (throws {@link UnsupportedError} otherwise),
-     * because it has to enumerate and delete generations — a pre-built `ColdChunkSource` only reads.
-     */
-    dropSegment(ref: SegmentRef, options: {
-        confirmSegment: string;
-        dryRun?: boolean;
-        audit?: IAuditSink;
-    }): Promise<DropResult>;
-    /**
-     * **Cross-tier DR consistency check (audit gap #11).** After a restore/failover, verify every registered
-     * segment's `currentGen` actually has its `.crbm` present in Cold — catching a **torn restore** where the
-     * registry (`currentGen`) came back ahead of the object store, so a pointer references a generation that
-     * isn't there (reads would then throw). Read-only, bounded fan-out; run it at startup after a restore.
-     * Returns `{ checked, inconsistent }` — `inconsistent` empty ⇒ coherent; otherwise it names the segments to
-     * recover (restore the object store, or roll the registry back to a coherent point). Needs the store built
-     * with a **raw cold driver + a registry** (throws {@link UnsupportedError} otherwise). `destroyed`
-     * (crypto-shredded) segments are skipped. Pair it with the DR runbook (docs/guide/disaster-recovery.md).
-     */
-    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 read/write ops.
- *
- * **IDs must be integers in `[0, 2^32)`** (dense 32-bit). A non-integer / negative / out-of-range id
- * throws {@link ValidationError}.
- *
- * **`addMany`/`removeMany`/`intersectInto`/`unionInto`/`andNotInto` are not atomic across chunks**: ids are grouped by chunk and
- * applied one chunk at a time, so if a later chunk fails (e.g. {@link WriteConflictError} after retries)
- * earlier chunks are already applied. Within a single chunk the update is atomic.
- */
-/** Options common to every chunk-aligned combine (`intersect` / `union` / `andNot`). */
-interface BaseCombineOptions {
-    /** Max chunk keys resolved concurrently — bounds the Cold footprint. A positive integer. */
-    readonly concurrency?: number;
-    /** Override the store's per-op denial-of-wallet budget for this call (`false` lifts it). */
-    readonly budget?: BudgetOption;
-}
-/**
- * A combine that can also subtract.
- *
- * `exclude` is why suppression does not need an intermediate segment: applied here it folds into the same
- * chunk-aligned pass, and each exclude is read **only at the keys that survived** — so a large global opt-out
- * list costs reads proportional to the audience, not to itself.
- */
-interface CombineOptions extends BaseCombineOptions {
-    /** Segments whose ids are subtracted from the result. */
-    readonly exclude?: Segment[];
-}
-/** {@link CombineOptions} plus the write batching used by the `*Into` variants. */
-interface CombineIntoOptions extends CombineOptions {
-    /** Ids buffered per `addMany` while materializing into `dest`. */
-    readonly batchSize?: number;
-}
-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, from a **sync or async** iterable. Not atomic across chunks — see the class note.
-     *
-     * An async source means a database cursor streams straight in — `addMany(athenaCursor())` rather than
-     * hand-batching `page → addMany(page)`. Ids are grouped by chunk and each chunk is written **exactly once**,
-     * however long the stream: pending ids are held compressed, not buffered-and-flushed, so a long stream costs
-     * no more backend writes than a short one. Peak memory is the roaring representation of the ids you pass.
-     *
-     * **For a very large set, reach for `bulkLoadCrbmGeneration` instead.** `addMany` expresses a *delta* and
-     * writes one warm row per touched chunk — around 61,000 of them for a set spread across the whole id space.
-     * Bulk-load *replaces* the segment with one immutable Cold object. See the guide's cost comparison; picking
-     * the wrong one of these is the most expensive mistake available in this library.
-     */
-    addMany(ids: Iterable<number> | AsyncIterable<number>): Promise<void>;
-    /** Remove an id (integer in `[0, 2^32)`). Throws {@link ValidationError} on a bad id. */
-    remove(id: number): Promise<void>;
-    /** Remove many ids, from a **sync or async** iterable. Not atomic across chunks — see {@link addMany}. */
-    removeMany(ids: Iterable<number> | AsyncIterable<number>): Promise<void>;
-    /**
-     * **Claim ids atomically — add them, and get back only the ones that were not already there.**
-     *
-     * The durable analogue of Redis `SETBIT` returning the prior bit, which is what an exactly-once *"have I
-     * already sent to / already processed this id?"* check needs. `has()` then `add()` cannot give you this: two
-     * workers can both read absent and both proceed.
-     *
-     * ```ts
-     * const sent = store.segment(day, { namespace: 'sent-daily' });
-     * const toSend = await sent.claimMany(candidateIds);   // only the ids this worker won
-     * for (const id of toSend) enqueue(id);                // ...so nobody else will send them
-     * ```
-     *
-     * **Pass a batch, not one id.** A Warm write rewrites a whole 64K-id chunk bitmap, so claiming ids one at a
-     * time is the single most expensive way to use this library — measured at ~5,000 writes and ~23 MB for 5,000
-     * ids, against 1 write and ~8 KB for the same ids in one call. This method does one OCC read-modify-write per
-     * distinct chunk, giving you Redis's *semantics* without Redis's per-id *cost shape*.
-     *
-     * **Exactly-once holds per id**, which is the guarantee that matters: each id lives in one chunk, a chunk is
-     * one OCC row, so exactly one concurrent claimer sees any given id as new. Like `addMany` it is **not** atomic
-     * across chunks — a mid-flight failure can leave some chunks claimed — but re-running is safe, because
-     * already-claimed ids simply come back as not-new.
-     *
-     * Order of the returned ids is unspecified.
-     */
-    claimMany(ids: Iterable<number>): Promise<number[]>;
-    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).
-     */
-    /**
-     * Map the facade's `Segment` handles in `exclude` down to the plain refs `core` takes. A method rather than
-     * a module function because `ref` is class-private — the encapsulation is worth more than the free function.
-     */
-    private refsIn;
-    intersect(others: Segment[], options?: CombineOptions): AsyncIterable<number>;
-    /**
-     * Materialize `this ∩ others…` (minus `exclude`) **into** `dest` (added, not replaced). Streaming +
-     * bounded-memory, but **not atomic** across chunks — see {@link addMany}.
-     */
-    intersectInto(dest: Segment, others: Segment[], options?: CombineIntoOptions): Promise<void>;
-    /**
-     * `this ∪ others…`, minus `options.exclude` — streamed ascending.
-     *
-     * **The one composite read with no chunk-skipping,** and that is inherent to union rather than a limitation
-     * here: an id in *any* operand belongs to the result, so every chunk of every operand must be read.
-     * `intersect` prunes any key missing from any operand; union has nothing to prune. It is charged against the
-     * same per-op budget, so a wide union is refused rather than quietly billed — pass `budget` to raise it
-     * deliberately. If you find yourself unioning the same segments on every read, materializing the combined
-     * segment once (`unionInto`, or a bulk-load rebuild) is the cheaper shape.
-     */
-    union(others: Segment[], options?: CombineOptions): AsyncIterable<number>;
-    /** Materialize `this ∪ others…` (minus `exclude`) **into** `dest`. **Not atomic** — see {@link addMany}. */
-    unionInto(dest: Segment, others: Segment[], options?: CombineIntoOptions): Promise<void>;
-    /**
-     * `this \ (excludes…)` — streamed ascending. Suppression on its own.
-     *
-     * Reads every chunk of `this` (any of them may survive the subtraction) but each exclude **only where it
-     * overlaps this segment**, so the cost tracks the segment being filtered rather than the size of the
-     * suppression list: at most one read per surviving key of `this`, so subtracting a 61,000-chunk global
-     * opt-out list from a 40-chunk audience costs at most 40 reads, not 61,000.
-     *
-     * To filter the *result of an intersection*, do not chain — pass `exclude` to {@link intersect} instead, so
-     * the suppression folds into the same pass rather than materializing an intermediate segment first.
-     */
-    andNot(excludes: Segment[], options?: BaseCombineOptions): AsyncIterable<number>;
-    /** Materialize `this \ (excludes…)` **into** `dest`. **Not atomic** — see {@link addMany}. */
-    andNotInto(dest: Segment, excludes: Segment[], options?: BaseCombineOptions & {
-        batchSize?: number;
-    }): Promise<void>;
-    /**
-     * 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.8.2";
-
-export { type BaseCombineOptions, CloudRoaring, type CloudRoaringOptions, type CombineIntoOptions, type CombineOptions, type EraseSubjectResult, SafeBitmap, Segment, type SegmentOptions, type SubjectErasureEntry, type SubjectReport, type SubjectSegmentRef, VERSION, bulkLoadCrbmGeneration, compactSegment, roaringCodec, runCompactionCycle, runExport };

package/dist/mongodb/index.cjs

@@ -1,14 +0,0 @@
-'use strict';
-
-var mongodb = require('@cloudbitmaps/core/mongodb');
-
-
-
-Object.keys(mongodb).forEach(function (k) {
-	if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
-		enumerable: true,
-		get: function () { return mongodb[k]; }
-	});
-});
-//# sourceMappingURL=index.cjs.map
-//# sourceMappingURL=index.cjs.map