@cloudbitmaps/roaring 0.9.0 → 0.10.0

package/dist/index.cjs

@@ -1,894 +0,0 @@
-'use strict';
-
-var core = require('@cloudbitmaps/core');
-var roaring = require('roaring');
-
-function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
-
-var roaring__default = /*#__PURE__*/_interopDefault(roaring);
-
-// src/index.ts
-var { RoaringBitmap32, SerializationFormat, DeserializationFormat } = roaring__default.default;
-var SafeBitmap = class _SafeBitmap {
-  bitmap;
-  constructor(bitmap) {
-    this.bitmap = bitmap;
-  }
-  static empty() {
-    return new _SafeBitmap(new RoaringBitmap32());
-  }
-  static fromValues(values) {
-    return new _SafeBitmap(new RoaringBitmap32(values));
-  }
-  /**
-   * 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, maxBytes) {
-    if (bytes.length > maxBytes) {
-      throw new core.IntegrityError(`serialized bitmap is ${bytes.length}B, exceeds cap ${maxBytes}B`);
-    }
-    try {
-      return new _SafeBitmap(RoaringBitmap32.deserialize(bytes, DeserializationFormat.portable));
-    } catch (err) {
-      throw new core.IntegrityError(`failed to deserialize bitmap: ${err.message}`);
-    }
-  }
-  serialize() {
-    return this.bitmap.serialize(SerializationFormat.portable);
-  }
-  /**
-   * 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() {
-    this.bitmap.runOptimize();
-  }
-  /**
-   * 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() {
-    return this.bitmap.isEmpty ? void 0 : this.bitmap.maximum();
-  }
-  add(value) {
-    this.bitmap.add(value);
-  }
-  addMany(values) {
-    this.bitmap.addMany(values);
-  }
-  remove(value) {
-    this.bitmap.remove(value);
-  }
-  removeMany(values) {
-    this.bitmap.removeMany(values);
-  }
-  has(value) {
-    return this.bitmap.has(value);
-  }
-  get size() {
-    return this.bitmap.size;
-  }
-  get isEmpty() {
-    return this.bitmap.isEmpty;
-  }
-  clone() {
-    return new _SafeBitmap(this.bitmap.clone());
-  }
-  // The binary set ops take the `CodecBitmap` interface type (per the seam), but a single store is
-  // single-codec (homogeneity contract), so `other` is always a `SafeBitmap` here — reach its private
-  // `bitmap` (accessible on same-class instances) for the native op.
-  /** In-place union: `this = this ∪ other`. */
-  orInPlace(other) {
-    this.bitmap.orInPlace(other.bitmap);
-  }
-  /** In-place difference: `this = this \ other`. */
-  andNotInPlace(other) {
-    this.bitmap.andNotInPlace(other.bitmap);
-  }
-  /** In-place intersection: `this = this ∩ other`. */
-  andInPlace(other) {
-    this.bitmap.andInPlace(other.bitmap);
-  }
-  /** Ascending iterator over the set values. */
-  [Symbol.iterator]() {
-    return this.bitmap[Symbol.iterator]();
-  }
-  toArray() {
-    return this.bitmap.toArray();
-  }
-};
-var roaringCodec = {
-  empty: () => SafeBitmap.empty(),
-  fromValues: (values) => SafeBitmap.fromValues(values),
-  safeDeserialize: (bytes, maxBytes) => SafeBitmap.safeDeserialize(bytes, maxBytes)
-};
-
-// src/system-clock.ts
-var SystemClock = class {
-  now() {
-    return Date.now();
-  }
-  sleep(ms) {
-    if (ms <= 0) return Promise.resolve();
-    return new Promise((resolve) => {
-      setTimeout(resolve, ms);
-    });
-  }
-  /**
-   * `setImmediate`, and it has to be — this is the one place where the choice of primitive is the whole feature.
-   *
-   * A long CPU-bound loop in `core/` (bulk-load is the one that matters) periodically hands the loop back so a
-   * co-resident HTTP server keeps answering. Measured on the **synthetic yield-primitive benchmark** — a
-   * 61,035-iteration loop yielding every 1,024, isolating the primitive rather than timing a real load (the
-   * end-to-end figures are 450 ms → 19 ms; see `cooperative.ts`, which lists all three experiments):
-   *
-   * ```text
-   *   no yield         568 ms wall   568.0 ms worst event-loop gap
-   *   sleep(0)         555 ms wall   555.2 ms   ← a microtask. Yields NOTHING.
-   *   setImmediate     569 ms wall    13.8 ms   ← free, and 41x less starvation
-   *   setTimeout(1)    625 ms wall    15.0 ms   ← +10% wall for no extra relief
-   * ```
-   *
-   * `sleep(0)` resolving on a microtask is correct for its own contract and useless for this: microtasks drain
-   * before the loop ever advances a phase, so `await sleep(0)` in a tight loop never lets a single pending I/O
-   * callback run. `setImmediate` fires in the check phase *after* pending I/O, which is exactly the ordering a
-   * server wants — inbound requests are serviced before the loop resumes chewing.
-   *
-   * A timer is not ref'd here (unlike {@link sleep}): a yield expresses "someone else may go first", never
-   * "there is outstanding work" — and `setImmediate` cannot outlive the turn that scheduled it anyway.
-   */
-  yieldNow() {
-    return new Promise((resolve) => {
-      setImmediate(resolve);
-    });
-  }
-};
-var bulkLoadCrbmGeneration = (driver, key, ids, options = {}) => core.bulkLoadCrbmGeneration(driver, key, ids, {
-  ...options,
-  codec: options.codec ?? roaringCodec,
-  clock: options.clock ?? new SystemClock()
-});
-var compactSegment = (ref, deps, options) => core.compactSegment(ref, { ...deps, codec: deps.codec ?? roaringCodec }, options);
-var runCompactionCycle = (deps, options) => core.runCompactionCycle({ ...deps, codec: deps.codec ?? roaringCodec }, options);
-var runExport = (reader, registry, sink, options = {}) => core.runExport(reader, registry, sink, { ...options, codec: options.codec ?? roaringCodec });
-
-// src/index.ts
-var SystemRng = class {
-  next() {
-    return Math.random();
-  }
-};
-var DEFAULT_CACHE_MAX_CHUNKS = 1024;
-var DEFAULT_ADMIN_CONCURRENCY = 8;
-function validateConcurrency(concurrency) {
-  if (concurrency !== void 0 && (!Number.isInteger(concurrency) || concurrency < 1)) {
-    throw new core.ValidationError(`concurrency must be a positive integer; got ${concurrency}`);
-  }
-}
-function requireScope(options, op) {
-  if (options.namespace === void 0 && options.allNamespaces !== true) {
-    throw new core.ValidationError(
-      `${op} scans the global id space across all namespaces \u2014 pass an explicit \`namespace\`, or \`{ allNamespaces: true }\` to intentionally sweep the whole fleet`
-    );
-  }
-}
-function resolveColdSource(options, clock) {
-  const cold = options.cold;
-  if (cold === null || typeof cold !== "object") {
-    throw new core.ValidationError("`cold` must be an IColdDriver or a ColdChunkSource");
-  }
-  const hasGetChunk = typeof cold.getChunk === "function";
-  const hasPutImmutable = typeof cold.putImmutable === "function";
-  if (hasGetChunk && hasPutImmutable) {
-    throw new core.ValidationError(
-      "`cold` exposes both `getChunk` and `putImmutable` \u2014 ambiguous; pass an IColdDriver or a ColdChunkSource, not a hybrid"
-    );
-  }
-  if (!hasGetChunk && !hasPutImmutable) {
-    throw new core.ValidationError("`cold` must be an IColdDriver or a ColdChunkSource");
-  }
-  if (hasGetChunk) {
-    if (options.registry !== void 0 || options.keystore !== void 0 || options.requireEncryption === true) {
-      throw new core.ValidationError(
-        "registry/keystore/requireEncryption apply only when `cold` is a raw IColdDriver; configure them on the ColdChunkSource you passed instead"
-      );
-    }
-    return { source: cold, driver: void 0 };
-  }
-  const driver = cold;
-  return {
-    source: new core.CrbmColdChunkSource(driver, {
-      registry: options.registry,
-      keystore: options.keystore,
-      requireEncryption: options.requireEncryption,
-      clock,
-      currentGenTtlMs: options.coldGenTtlMs,
-      maxOpenSegments: options.coldReaderCacheMax,
-      maxOpenIndexBytes: options.coldReaderCacheMaxBytes
-    }),
-    driver
-  };
-}
-var CloudRoaring = class {
-  engine;
-  clock;
-  metrics;
-  // The store's own drivers, kept so the in-process lifecycle helpers (`compact`/`eraseSubject`/`subjectReport`)
-  // reuse them instead of making you re-pass a CompactionDeps. `coldDriver` is set only when `cold` was a raw
-  // IColdDriver (a pre-built ColdChunkSource has no underlying driver to compact through).
-  coldDriver;
-  warmDriver;
-  registry;
-  keystore;
-  requireEncryption;
-  /** Resolved store-level per-op budget (null = disabled); the admin scans use it, with a per-op override. */
-  budget;
-  constructor(options) {
-    const clock = options.clock ?? new SystemClock();
-    const rng = options.rng ?? new SystemRng();
-    const metrics = core.safeMetrics(options.metrics ?? core.NOOP_METRICS);
-    const cache = new core.BoundedLru({
-      maxEntries: options.cacheMaxChunks ?? DEFAULT_CACHE_MAX_CHUNKS,
-      ttlMs: options.cacheTtlMs,
-      clock
-    });
-    const resolved = resolveColdSource(options, clock);
-    let cold = resolved.source;
-    let warm = options.warm;
-    if (options.retry !== false) {
-      const retryOpts = {
-        clock,
-        rng,
-        policy: options.retry,
-        // Bridge transient-fault retries into the metrics stream, then call the user's own hook.
-        onRetry: (info) => {
-          metrics.onEvent({
-            kind: "retry",
-            reason: "transient",
-            attempt: info.attempt,
-            delayMs: info.delayMs
-          });
-          options.onRetry?.(info);
-        }
-      };
-      warm = new core.RetryingWarmDriver(options.warm, retryOpts);
-      cold = new core.RetryingColdChunkSource(cold, retryOpts);
-    }
-    if (options.writeConcurrency !== void 0 && (!Number.isInteger(options.writeConcurrency) || options.writeConcurrency < 1)) {
-      throw new core.ValidationError(
-        `writeConcurrency must be a positive integer; got ${options.writeConcurrency}`
-      );
-    }
-    this.budget = core.resolveBudget(options.budget, core.DEFAULT_BUDGET);
-    const deps = {
-      warm,
-      cold,
-      cache,
-      codec: roaringCodec,
-      // the facade injects the flagship codec; core stays codec-agnostic
-      clock,
-      rng,
-      occBackoff: options.occBackoff,
-      metrics,
-      warmReadConsistency: options.warmReadConsistency,
-      writeConcurrency: options.writeConcurrency,
-      maxWarmScanBytes: options.maxWarmScanBytes,
-      budget: this.budget
-    };
-    this.engine = new core.SegmentEngine(deps);
-    this.clock = clock;
-    this.metrics = metrics;
-    this.coldDriver = resolved.driver;
-    this.warmDriver = options.warm;
-    this.registry = options.registry;
-    this.keystore = options.keystore;
-    this.requireEncryption = options.requireEncryption ?? false;
-  }
-  /**
-   * 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.
-   */
-  compactionDeps() {
-    if (this.coldDriver === void 0) {
-      throw new core.UnsupportedError(
-        "compact/dropSegment/retireExpired/eraseSubject/checkConsistency need the store built with a raw cold driver (IColdDriver), not a pre-built ColdChunkSource \u2014 or call the compactSegment/runConsistencyCheck free functions with explicit deps"
-      );
-    }
-    if (this.registry === void 0) {
-      throw new core.UnsupportedError(
-        "compact/dropSegment/retireExpired/eraseSubject/checkConsistency need a `registry` in the store config"
-      );
-    }
-    return {
-      cold: this.coldDriver,
-      warm: this.warmDriver,
-      registry: this.registry,
-      clock: this.clock,
-      codec: roaringCodec,
-      // facade injects the flagship codec
-      keystore: this.keystore,
-      requireEncryption: this.requireEncryption,
-      metrics: this.metrics
-      // safe-wrapped sink → store.compact/eraseSubject emit `compaction` events (gap #2)
-    };
-  }
-  /** Get a handle to a segment. Validates the name/namespace grammar (finding S2). */
-  segment(name, options) {
-    const ref = { segment: name, namespace: options?.namespace };
-    core.validateSegmentRef(ref);
-    return new Segment(this.engine, ref, this.clock, this.metrics);
-  }
-  /**
-   * **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).
-   */
-  async subjectReport(id, options = {}) {
-    const registry = this.requireRegistry("subjectReport");
-    requireScope(options, "subjectReport");
-    validateConcurrency(options.concurrency);
-    const budget = core.resolvePerOpBudget(options.budget, this.budget);
-    core.splitId(id);
-    const recs = await core.collectWithinBudget(
-      registry.list(options.namespace),
-      budget,
-      "subjectReport"
-    );
-    const membership = await core.mapWithConcurrency(
-      recs,
-      options.concurrency ?? DEFAULT_ADMIN_CONCURRENCY,
-      async (rec) => {
-        if (rec.status === "destroyed") return null;
-        const ref = { segment: rec.segment, namespace: rec.namespace };
-        return await this.engine.has(ref, id, { consistent: true }) ? { segment: rec.segment, namespace: rec.namespace } : null;
-      }
-    );
-    const segments = membership.filter((m) => m !== null);
-    return { id, segments, scannedSegments: recs.length };
-  }
-  /**
-   * **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.
-   */
-  async eraseSubject(id, options) {
-    const compaction = this.compactionDeps();
-    core.validateCompactionOptions({ owner: options.owner });
-    requireScope(options, "eraseSubject");
-    validateConcurrency(options.concurrency);
-    const budget = core.resolvePerOpBudget(options.budget, this.budget);
-    core.splitId(id);
-    const recs = await core.collectWithinBudget(
-      compaction.registry.list(options.namespace),
-      budget,
-      "eraseSubject"
-    );
-    const entries = await core.mapWithConcurrency(
-      recs,
-      options.concurrency ?? DEFAULT_ADMIN_CONCURRENCY,
-      async (rec) => {
-        if (rec.status === "destroyed") return null;
-        const ref = { segment: rec.segment, namespace: rec.namespace };
-        let removed = false;
-        try {
-          if (!await this.engine.has(ref, id, { consistent: true })) return null;
-          await this.engine.remove(ref, id);
-          removed = true;
-          const result = await core.compactSegment(ref, compaction, {
-            owner: options.owner,
-            audit: options.audit
-          });
-          return {
-            segment: rec.segment,
-            namespace: rec.namespace,
-            removed: true,
-            physicallyPurged: result.compacted,
-            toGen: result.toGen,
-            note: result.compacted ? void 0 : result.reason
-          };
-        } catch (err) {
-          return {
-            segment: rec.segment,
-            namespace: rec.namespace,
-            removed,
-            physicallyPurged: false,
-            note: `error: ${err instanceof Error ? err.message : String(err)}`
-          };
-        }
-      }
-    );
-    const erasedFrom = entries.filter((e) => e !== null);
-    return { id, erasedFrom, scannedSegments: recs.length };
-  }
-  /**
-   * **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`.
-   */
-  async compact(ref, options) {
-    core.validateSegmentRef(ref);
-    const deps = this.compactionDeps();
-    const result = await core.compactSegment(ref, deps, options);
-    if (result.compacted) {
-      await core.gcOrphanGenerations(ref, { cold: deps.cold, registry: deps.registry }).catch(
-        () => void 0
-      );
-    }
-    return result;
-  }
-  /**
-   * **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.
-   */
-  async dropSegment(ref, options) {
-    core.validateSegmentRef(ref);
-    const deps = this.compactionDeps();
-    return core.dropSegment(ref, { registry: deps.registry, warm: deps.warm, cold: deps.cold }, options);
-  }
-  /**
-   * **Record when this segment becomes eligible for retirement.** One registry write; nothing is deleted here,
-   * and nothing starts running. `retireExpired` is what acts on the policy, and **you** decide when that runs —
-   * an EventBridge rule, a CronJob, a queue consumer, whatever your deployment already has. This library starts
-   * no background thread (it has to work identically in a Lambda, an edge isolate and a long-lived server).
-   *
-   * `expiresAt` is an **absolute epoch-ms you compute**, not a duration the library derives. A relative TTL would
-   * have to be anchored to something the library knows — `updatedAt`, or the current generation — and compaction
-   * rewrites both, so "expire 30 days after the last write" would keep a busy daily bucket alive forever
-   * precisely because the daemon is working.
-   *
-   * ```ts
-   * const DAY = 86_400_000;
-   * const ref = { namespace: 'active-daily', segment: '2026-08-05' };
-   * await store.setRetention(ref, { expiresAt: Date.now() + 30 * DAY });
-   * ```
-   *
-   * **Works on an accumulator**, which is the whole point: a segment you created by writing to it has no
-   * registry row, so it is invisible to `registry.list()` and therefore to every fleet-wide operation, including
-   * the sweep. This call mints the row (`createdRow: true` in the result) with **no Cold generation**, so it
-   * becomes enumerable while every read still resolves exactly as before.
-   *
-   * A value in the past is legal and means "eligible on the next sweep" — backfilling a policy onto existing
-   * buckets is normal. A value below `MIN_EXPIRES_AT_MS` (2001-09-09) is rejected: it is almost certainly epoch
-   * **seconds**, which would read as long-expired and retire the segment on the next pass. Needs a `registry`
-   * in the store config (throws {@link UnsupportedError} otherwise), and refuses a crypto-shredded segment.
-   */
-  async setRetention(ref, policy) {
-    core.validateSegmentRef(ref);
-    return core.setSegmentRetention(ref, { registry: this.requireRegistry("setRetention") }, policy);
-  }
-  /**
-   * **The stored retention policy**, or `null` if the segment has none (or has no registry row, or is a
-   * tombstone). Returns the string `'invalid'` for a row whose `expiresAt` is present but unusable — a
-   * hand-edited row, or one from a restore — so a malformed policy is visible rather than silently reading as
-   * "never expires" on a segment someone believes is expiring.
-   */
-  async getRetention(ref) {
-    core.validateSegmentRef(ref);
-    return core.getSegmentRetention(ref, { registry: this.requireRegistry("getRetention") });
-  }
-  /**
-   * **Cancel a segment's expiry** so no sweep retires it. Returns whether a policy was actually removed (`false`
-   * when there was none). A separate verb from `setRetention` on purpose: "never expire" as a magic value passed
-   * to the setter is how a typo becomes a deletion.
-   */
-  async clearRetention(ref) {
-    core.validateSegmentRef(ref);
-    return core.clearSegmentRetention(ref, { registry: this.requireRegistry("clearRetention") });
-  }
-  /**
-   * **Run the retention sweep: retire every segment whose `expiresAt` has passed.** This is the call that acts on
-   * the policies `setRetention` records — and it is a **call, not a daemon**. Nothing schedules it; you run it from
-   * whatever heartbeat your deployment already has (an EventBridge rule, a Kubernetes CronJob, a queue consumer,
-   * your compaction worker's loop). A library that started a timer would behave differently in a Lambda, an edge
-   * isolate and a long-lived server, which is worse than not having one.
-   *
-   * Each retirement goes through `dropSegment`, so the Warm → registry → Cold ordering, the re-sweep for a
-   * generation staged by an in-flight compaction, and the `generationsRemaining` report all come from one
-   * implementation rather than two.
-   *
-   * ```ts
-   * // In your scheduled handler. Start with a preview in a new deployment.
-   * const preview = await store.retireExpired({ namespace: 'active-daily', dryRun: true });
-   * console.log(`would retire ${preview.retired} of ${preview.scanned} (limited: ${preview.limited})`);
-   *
-   * const swept = await store.retireExpired({ namespace: 'active-daily' });
-   * for (const e of swept.entries) {
-   *   if (e.action === 'skipped') console.warn(`${e.segment}: ${e.reason}`); // invalid-policy / limit / failed: …
-   *   if (e.action === 'retired' && e.result.generationsRemaining.length > 0) {
-   *     console.warn(`${e.segment}: storage not fully reclaimed — re-run`);
-   *   }
-   * }
-   * if (swept.limited) scheduleAnotherPassSoon(); // more are still eligible
-   * ```
-   *
-   * **Read the ledger.** A per-segment *fault* is an entry, not an exception — a throw from the middle of a fleet
-   * sweep would leave the caller unable to say which segments were retired, having already retired some. (A bad
-   * argument does throw, and so does a fleet larger than `maxScanSegments`.) `limited: true` means the per-cycle
-   * `limit` (default 100) cut the pass short and more are eligible. That cap is charged on **attempts**, not
-   * successes, which is what makes it a real bound: `dropSegment` deletes Warm and writes the tombstone before
-   * sweeping Cold, so a fault in the Cold phase is a segment that is already retired. Retirements are sequential
-   * (~8 round trips each), so `limit` is a wall-clock knob too, and `retired` counts deletions only — a dry run
-   * reports `wouldRetire` instead, so a dashboard summing `retired` can never show a phantom deletion.
-   *
-   * It also **deletes the tombstone rows its own past retirements left**, after `tombstoneGraceMs` (default 24 h)
-   * and only once that segment's Warm rows and Cold generations are provably gone — collecting a straggler
-   * generation itself first, since nothing else ever would for a tombstoned segment. Attribution is a **positive
-   * marker the sweep stamps on its own retirements**, not an inference from "destroyed + an expired policy": a
-   * crypto-shred leaves `retention` untouched, so setting a policy and then honouring a right-to-erasure request
-   * mid-window produces exactly that row, and deleting it would destroy the Art. 17 attestation and un-fence the
-   * name. Pass `purgeTombstones: false` to keep every tombstone.
-   *
-   * Needs the store built with a **raw cold driver + a registry** (throws {@link UnsupportedError} otherwise),
-   * because retiring a segment deletes its Cold objects. `now` defaults to the store's clock.
-   */
-  async retireExpired(options = {}) {
-    const deps = this.compactionDeps();
-    return core.retireExpired(
-      { registry: deps.registry, warm: deps.warm, cold: deps.cold },
-      { ...options, now: options.now ?? this.clock.now() }
-    );
-  }
-  /** The store's registry, or a typed error naming the operation that needs one. */
-  requireRegistry(op) {
-    if (this.registry === void 0) {
-      throw new core.UnsupportedError(`${op} needs a \`registry\` in the store config`);
-    }
-    return this.registry;
-  }
-  /**
-   * **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).
-   */
-  async checkConsistency(options = {}) {
-    const deps = this.compactionDeps();
-    return core.runConsistencyCheck({ cold: deps.cold, registry: deps.registry }, options);
-  }
-  /**
-   * **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.
-   */
-  async exportSegments(sink, options = {}) {
-    const registry = this.requireRegistry("exportSegments");
-    return core.runExport(this, registry, sink, {
-      ...options,
-      codec: options.codec ?? roaringCodec
-    });
-  }
-  /**
-   * 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) {
-    return core.estimateCost(input);
-  }
-};
-var Segment = class {
-  constructor(engine, ref, clock, metrics) {
-    this.engine = engine;
-    this.ref = ref;
-    this.clock = clock;
-    this.metrics = metrics;
-    this.metricsOn = metrics !== core.NOOP_METRICS;
-  }
-  engine;
-  ref;
-  clock;
-  metrics;
-  metricsOn;
-  /**
-   * 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.
-   */
-  async timed(name, fn) {
-    if (!this.metricsOn) return fn();
-    const startedAt = this.clock.now();
-    try {
-      return await fn();
-    } finally {
-      this.metrics.onEvent({ kind: "op", name, ms: Math.max(0, this.clock.now() - startedAt) });
-    }
-  }
-  /** Add an id (integer in `[0, 2^32)`). Throws {@link ValidationError} on a bad id. */
-  add(id) {
-    return this.timed("add", () => this.engine.add(this.ref, id));
-  }
-  /**
-   * 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) {
-    return this.timed("addMany", () => this.engine.addMany(this.ref, ids));
-  }
-  /** Remove an id (integer in `[0, 2^32)`). Throws {@link ValidationError} on a bad id. */
-  remove(id) {
-    return this.timed("remove", () => this.engine.remove(this.ref, id));
-  }
-  /** Remove many ids, from a **sync or async** iterable. Not atomic across chunks — see {@link addMany}. */
-  removeMany(ids) {
-    return this.timed("removeMany", () => this.engine.removeMany(this.ref, ids));
-  }
-  /**
-   * **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) {
-    return this.timed("claimMany", () => this.engine.claimMany(this.ref, ids));
-  }
-  has(id) {
-    return this.timed("has", () => this.engine.has(this.ref, id));
-  }
-  count() {
-    return this.timed("count", () => this.engine.count(this.ref));
-  }
-  iterate() {
-    return this.engine.iterate(this.ref);
-  }
-  /**
-   * 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.
-   */
-  refsIn(options) {
-    if (options === void 0) return void 0;
-    const { exclude, ...rest } = options;
-    return exclude === void 0 ? rest : { ...rest, exclude: exclude.map((o) => o.ref) };
-  }
-  intersect(others, options) {
-    return this.engine.intersect([this.ref, ...others.map((o) => o.ref)], this.refsIn(options));
-  }
-  /**
-   * Materialize `this ∩ others…` (minus `exclude`) **into** `dest` (added, not replaced). Streaming +
-   * bounded-memory, but **not atomic** across chunks — see {@link addMany}.
-   */
-  intersectInto(dest, others, options) {
-    return this.timed(
-      "intersectInto",
-      () => this.engine.intersectInto(
-        dest.ref,
-        [this.ref, ...others.map((o) => o.ref)],
-        this.refsIn(options)
-      )
-    );
-  }
-  /**
-   * `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, options) {
-    return this.engine.union([this.ref, ...others.map((o) => o.ref)], this.refsIn(options));
-  }
-  /** Materialize `this ∪ others…` (minus `exclude`) **into** `dest`. **Not atomic** — see {@link addMany}. */
-  unionInto(dest, others, options) {
-    return this.timed(
-      "unionInto",
-      () => this.engine.unionInto(
-        dest.ref,
-        [this.ref, ...others.map((o) => o.ref)],
-        this.refsIn(options)
-      )
-    );
-  }
-  /**
-   * `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, options) {
-    return this.engine.andNot(
-      this.ref,
-      excludes.map((o) => o.ref),
-      options
-    );
-  }
-  /** Materialize `this \ (excludes…)` **into** `dest`. **Not atomic** — see {@link addMany}. */
-  andNotInto(dest, excludes, options) {
-    return this.timed(
-      "andNotInto",
-      () => this.engine.andNotInto(
-        dest.ref,
-        this.ref,
-        excludes.map((o) => o.ref),
-        options
-      )
-    );
-  }
-  /**
-   * 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).
-   */
-  async costReport(options) {
-    const canMeasure = this.engine.supportsColdSize;
-    const size = canMeasure ? await this.engine.segmentSize(this.ref) : null;
-    return core.groundedReport({
-      coldBytes: size?.sizeBytes ?? 0,
-      grounded: canMeasure,
-      workload: options?.workload,
-      topology: options?.topology,
-      pricing: options?.pricing,
-      extraNotes: canMeasure ? void 0 : ["cold source has no sizeOf() \u2014 storage not measured, reported as $0."]
-    });
-  }
-};
-var VERSION = "0.9.0";
-
-exports.CloudRoaring = CloudRoaring;
-exports.SafeBitmap = SafeBitmap;
-exports.Segment = Segment;
-exports.VERSION = VERSION;
-exports.bulkLoadCrbmGeneration = bulkLoadCrbmGeneration;
-exports.compactSegment = compactSegment;
-exports.roaringCodec = roaringCodec;
-exports.runCompactionCycle = runCompactionCycle;
-exports.runExport = runExport;
-Object.keys(core).forEach(function (k) {
-  if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
-    enumerable: true,
-    get: function () { return core[k]; }
-  });
-});
-//# sourceMappingURL=index.cjs.map
-//# sourceMappingURL=index.cjs.map