@cloudbitmaps/roaring 0.9.0 → 0.11.0

package/dist/bin/export-segments.js

@@ -1,21 +1,1957 @@
 #!/usr/bin/env node
-import { src_exports, CloudRoaring } from '../chunk-D6LIJSGF.js';
-import { randomUUID } from 'crypto';
-import { mkdir, writeFile, rename, rm, open } from 'fs/promises';
-import { join } from 'path';
-import { pathToFileURL } from 'url';
-import { validateSegmentRef } from '@cloudbitmaps/core';
 
-function parseSegments(raw) {
-  const entries = (raw ?? "").split(",").map((s) => s.trim()).filter((s) => s.length > 0);
-  if (entries.length === 0) return void 0;
-  return entries.map((entry) => {
-    const slash = entry.indexOf("/");
-    const ref = slash === -1 ? { segment: entry } : { namespace: entry.slice(0, slash), segment: entry.slice(slash + 1) };
-    validateSegmentRef(ref);
-    return ref;
-  });
+// src/bin/export-segments.ts
+import { randomUUID } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { mkdir, open, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { encodeNameForPath, namespacePathPart } from "@cloudbitmaps/core/driver-kit";
+
+// src/index.ts
+import {
+  BoundedLru,
+  PinnedStorageChunkSource,
+  segmentKey,
+  CrbmStorageChunkSource,
+  DEFAULT_BUDGET,
+  DEFAULT_RETRY_POLICY,
+  withRetry,
+  isStorageBackend,
+  NOOP_METRICS,
+  RetryingStorageChunkSource,
+  SegmentEngine,
+  UnsupportedError,
+  ValidationError as ValidationError2,
+  WriteConflictError,
+  MIN_EXPIRES_AT_MS,
+  checkBudget,
+  collectWithinBudget,
+  excludingReservedRows,
+  dropSegment,
+  eraseIdFromSegment,
+  estimateCost,
+  groundedReport,
+  loadSegment,
+  mapWithConcurrency,
+  resolveBudget,
+  resolvePerOpBudget,
+  retireExpired,
+  runConsistencyCheck,
+  runExport,
+  setSegmentRetention,
+  clearSegmentRetention,
+  getSegmentRetention,
+  safeMetrics,
+  splitId
+} from "@cloudbitmaps/core";
+import { validateSegmentRef } from "@cloudbitmaps/core/driver-kit";
+
+// src/open-charging-storage.ts
+var OpenChargingStorage = class {
+  /**
+   * @param inner   the driver the erasure would otherwise use
+   * @param current the generation the segment's row named when it was listed, or `null` when it named none
+   * @param charge  called once per charged open; it throws to refuse
+   */
+  constructor(inner, current, charge) {
+    this.inner = inner;
+    this.charge = charge;
+    if (current !== null) this.free.add(current);
+  }
+  inner;
+  charge;
+  free = /* @__PURE__ */ new Set();
+  capabilities() {
+    return this.inner.capabilities();
+  }
+  async putImmutable(key, write) {
+    const written = await this.inner.putImmutable(key, write);
+    this.free.add(key.generation);
+    return written;
+  }
+  getRange(key, offset, length) {
+    return this.inner.getRange(key, offset, length);
+  }
+  /** One `getTail` is one open: a reader takes the footer and the index from it, and reads chunks with `getRange`. */
+  async getTail(key, maxBytes) {
+    if (!this.free.has(key.generation)) this.charge();
+    return this.inner.getTail(key, maxBytes);
+  }
+  delete(key) {
+    return this.inner.delete(key);
+  }
+  list(ref) {
+    return this.inner.list(ref);
+  }
+};
+
+// src/index.ts
+import { listGenerations, rollbackSegment } from "@cloudbitmaps/core";
+import { listSegments, segmentExists } from "@cloudbitmaps/core";
+
+// src/reserved-namespace.ts
+import { ValidationError } from "@cloudbitmaps/core";
+var RESERVED_NAMESPACE_PREFIX = "cbm.due.";
+function refuseReservedNamespace(namespace) {
+  if (namespace !== void 0 && namespace.startsWith(RESERVED_NAMESPACE_PREFIX)) {
+    throw new ValidationError(
+      `namespace "${namespace}" is reserved: names starting with "${RESERVED_NAMESPACE_PREFIX}" hold the library's own bookkeeping rows, which every fleet-wide scan skips, so a segment there would be invisible to an erasure, a consistency check, an export and a retention sweep. Choose another namespace.`
+    );
+  }
 }
+
+// src/roaring-codec.ts
+import roaring from "roaring";
+import { IntegrityError as IntegrityError2 } from "@cloudbitmaps/core";
+
+// src/portable/layout.ts
+import { IntegrityError } from "@cloudbitmaps/core";
+var SERIAL_COOKIE_NO_RUNCONTAINER = 12346;
+var SERIAL_COOKIE = 12347;
+var NO_OFFSET_THRESHOLD = 4;
+var ARRAY_MAX_CARDINALITY = 4096;
+var BITMAP_CONTAINER_BYTES = 8192;
+var MAX_LOW = 65535;
+var ARRAY = 0;
+var BITMAP = 1;
+var RUN = 2;
+function overrun(bytes, offset, length, what) {
+  return new IntegrityError(
+    `portable roaring: ${what} needs bytes [${offset}, ${offset + length}) of a ${bytes.byteLength}-byte buffer`
+  );
+}
+function checkPortableLayout(bytes) {
+  walk(bytes, null);
+}
+function walk(bytes, out) {
+  const length = bytes.byteLength;
+  if (length === 0) return;
+  const view = new DataView(bytes.buffer, bytes.byteOffset, length);
+  if (length < 4) throw overrun(bytes, 0, 4, "the cookie");
+  const cookie = view.getUint32(0, true);
+  let count;
+  let runFlagsAt = -1;
+  let pos;
+  if (cookie === SERIAL_COOKIE_NO_RUNCONTAINER) {
+    if (length < 8) throw overrun(bytes, 4, 4, "the container count");
+    count = view.getUint32(4, true);
+    pos = 8;
+  } else if ((cookie & 65535) === SERIAL_COOKIE) {
+    count = (cookie >>> 16) + 1;
+    runFlagsAt = 4;
+    const flagBytes = count + 7 >>> 3;
+    if (runFlagsAt + flagBytes > length) {
+      throw overrun(bytes, runFlagsAt, flagBytes, "the run-container bitmap");
+    }
+    pos = runFlagsAt + flagBytes;
+  } else {
+    throw new IntegrityError(
+      `portable roaring: unrecognized cookie 0x${cookie.toString(16)}, not a portable-format bitmap`
+    );
+  }
+  const descriptiveAt = pos;
+  if (pos + count * 4 > length) throw overrun(bytes, pos, count * 4, "the descriptive header");
+  pos += count * 4;
+  let offsetsAt = -1;
+  if (runFlagsAt < 0 || count >= NO_OFFSET_THRESHOLD) {
+    if (pos + count * 4 > length) throw overrun(bytes, pos, count * 4, "the offset header");
+    offsetsAt = pos;
+    pos += count * 4;
+  }
+  let previousKey = -1;
+  for (let i = 0; i < count; i++) {
+    const key = view.getUint16(descriptiveAt + i * 4, true);
+    if (key <= previousKey) {
+      throw new IntegrityError(
+        `portable roaring: container keys are not strictly ascending (${previousKey} then ${key} at index ${i})`
+      );
+    }
+    previousKey = key;
+    const cardinality = view.getUint16(descriptiveAt + i * 4 + 2, true) + 1;
+    const isRun = runFlagsAt >= 0 && (bytes[runFlagsAt + (i >>> 3)] & 1 << (i & 7)) !== 0;
+    const kind = isRun ? RUN : cardinality > ARRAY_MAX_CARDINALITY ? BITMAP : ARRAY;
+    if (offsetsAt >= 0) {
+      const stated = view.getUint32(offsetsAt + i * 4, true);
+      if (stated !== pos) {
+        throw new IntegrityError(
+          `portable roaring: the offset header puts container ${i} at byte ${stated}, but it starts at ${pos}`
+        );
+      }
+    }
+    let size;
+    if (kind === ARRAY) {
+      size = cardinality * 2;
+      if (pos + size > length) throw overrun(bytes, pos, size, `container ${i} (array)`);
+      checkArray(view, pos, cardinality, i);
+    } else if (kind === BITMAP) {
+      size = BITMAP_CONTAINER_BYTES;
+      if (pos + size > length) throw overrun(bytes, pos, size, `container ${i} (bitmap)`);
+      const bits = popcount(view, pos);
+      if (bits !== cardinality) {
+        throw new IntegrityError(
+          `portable roaring: container ${i} (bitmap) holds ${bits} values, but its header says ${cardinality}`
+        );
+      }
+    } else {
+      if (pos + 2 > length) throw overrun(bytes, pos, 2, `container ${i} (run count)`);
+      const runs = view.getUint16(pos, true);
+      size = 2 + runs * 4;
+      if (pos + size > length) throw overrun(bytes, pos, size, `container ${i} (run)`);
+      const covered = checkRuns(view, pos + 2, runs, i);
+      if (covered !== cardinality) {
+        throw new IntegrityError(
+          `portable roaring: container ${i} (run) covers ${covered} values, but its header says ${cardinality}`
+        );
+      }
+    }
+    out?.push({ key, cardinality, kind, offset: pos });
+    pos += size;
+  }
+}
+function checkArray(view, at, cardinality, index) {
+  let previous = -1;
+  let p = at;
+  const end = at + cardinality * 2;
+  for (; p + 4 <= end; p += 4) {
+    const pair = view.getUint32(p, true);
+    const first = pair & 65535;
+    const second = pair >>> 16;
+    if (first <= previous || second <= first) throw unordered(index, (p - at) / 2);
+    previous = second;
+  }
+  if (p < end && view.getUint16(p, true) <= previous) throw unordered(index, (p - at) / 2);
+}
+function unordered(index, element) {
+  return new IntegrityError(
+    `portable roaring: container ${index} (array) is not strictly ascending at or after element ${element}`
+  );
+}
+function checkRuns(view, at, runs, index) {
+  let covered = 0;
+  let lowest = 0;
+  for (let r = 0; r < runs; r++) {
+    const run = view.getUint32(at + r * 4, true);
+    const start = run & 65535;
+    const last = start + (run >>> 16);
+    if (start < lowest) {
+      throw new IntegrityError(
+        `portable roaring: container ${index} (run) has run ${r} out of order, overlapping or touching the one before`
+      );
+    }
+    if (last > MAX_LOW) {
+      throw new IntegrityError(
+        `portable roaring: container ${index} (run) has run ${r} running past the end of the container`
+      );
+    }
+    covered += last - start + 1;
+    lowest = last + 2;
+  }
+  return covered;
+}
+function popcount(view, at) {
+  let bits = 0;
+  for (let p = at, end = at + BITMAP_CONTAINER_BYTES; p < end; p += 4) {
+    let w = view.getUint32(p, true);
+    w -= w >>> 1 & 1431655765;
+    w = (w & 858993459) + (w >>> 2 & 858993459);
+    bits += Math.imul(w + (w >>> 4) & 252645135, 16843009) >>> 24;
+  }
+  return bits;
+}
+
+// src/roaring-codec.ts
+var { RoaringBitmap32, SerializationFormat, DeserializationFormat } = roaring;
+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));
+  }
+  /**
+   * Cap the size, check the structure, then deserialize with the **portable** format.
+   * Throws `IntegrityError` if the input exceeds `maxBytes`, is not a well-formed portable bitmap, or fails to
+   * decode — the native addon is never handed unbounded, malformed or unsafe-format input.
+   *
+   * The structural check is what makes the decoded bitmap's answers mean anything. The native deserializer
+   * bounds its reads and checks nothing else, so bytes of the right length and the wrong shape (containers or
+   * values out of order, overlapping runs, a cardinality that disagrees with the bits) decode into a bitmap
+   * whose `maximum()`, `has()` and `size` are wrong, and some of those shapes crash the process when used.
+   */
+  static safeDeserialize(bytes, maxBytes) {
+    if (bytes.length > maxBytes) {
+      throw new IntegrityError2(`serialized bitmap is ${bytes.length}B, exceeds cap ${maxBytes}B`);
+    }
+    checkPortableLayout(bytes);
+    try {
+      return new _SafeBitmap(RoaringBitmap32.deserialize(bytes, DeserializationFormat.portable));
+    } catch (err) {
+      throw new IntegrityError2(`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 only when writing an immutable objects generation — see {@link CodecBitmap.optimize} for why the read
+   * path deliberately does not.
+   */
+  optimize() {
+    this.bitmap.runOptimize();
+  }
+  /**
+   * Largest value, or `undefined` when empty. O(1) — roaring reads it off the last container, so the engine's
+   * per-chunk range assertion costs one call per chunk rather than a walk per id. The last container holds the
+   * largest value only because {@link SafeBitmap.safeDeserialize} refuses bytes whose containers or values are
+   * out of order.
+   */
+  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 519 ms → 24 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);
+    });
+  }
+};
+
+// src/option-keys.ts
+var OPTION_KEYS = {
+  top: ["storage", "cache", "encryption", "retry", "metrics", "budget", "seams"],
+  cache: ["maxChunks", "ttlMs", "genTtlMs", "readerMax", "readerMaxBytes"],
+  encryption: ["keystore", "required"],
+  retry: ["maxAttempts", "baseDelayMs", "maxDelayMs", "backoffFactor", "jitter", "onRetry"],
+  budget: ["maxRequests"],
+  seams: ["clock", "rng"]
+};
+
+// src/index.ts
+import {
+  MemoryStorage,
+  LocalFsStorage,
+  CrbmStorageChunkSource as CrbmStorageChunkSource2,
+  destroySegment,
+  eraseNamespace,
+  excludingReservedRows as excludingReservedRows2,
+  readRetentionPolicy,
+  MIN_EXPIRES_AT_MS as MIN_EXPIRES_AT_MS2,
+  InProcessKeystore,
+  NodeAead,
+  aadFor,
+  CloudRoaringError,
+  ValidationError as ValidationError3,
+  WriteConflictError as WriteConflictError2,
+  IntegrityError as IntegrityError3,
+  NotFoundError,
+  UnsupportedError as UnsupportedError2,
+  CapabilityError,
+  TransientError,
+  KeyUnavailableError,
+  BudgetExceededError,
+  isCloudRoaringError,
+  isWriteConflictError,
+  isTransientError,
+  isNotFoundError,
+  isIntegrityError,
+  isValidationError,
+  CrbmReader,
+  BufferReader,
+  CountingMetricsSink,
+  RecordingAuditSink,
+  DEFAULT_RETRY_POLICY as DEFAULT_RETRY_POLICY2,
+  AWS_US_EAST_1_ONDEMAND,
+  ELASTICACHE_REDIS_US_EAST_1_ONDEMAND,
+  ONE_REDIS_HA_CLUSTER
+} from "@cloudbitmaps/core";
+var SystemRng = class {
+  /** A float in `[0, 1)`. Jitter only — never key material, never anything a caller can observe. */
+  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 ValidationError2(`concurrency must be a positive integer; got ${concurrency}`);
+  }
+}
+function requireScope(options, op) {
+  refuseReservedNamespace(options.namespace);
+  if (options.namespace === void 0 && options.allNamespaces !== true) {
+    throw new ValidationError2(
+      `${op} scans the global id space across all namespaces \u2014 pass an explicit \`namespace\`, or \`{ allNamespaces: true }\` to intentionally sweep the whole fleet`
+    );
+  }
+}
+function resolveStorageSource(options, clock) {
+  const storage = options.storage;
+  if (storage === null || typeof storage !== "object") {
+    throw new ValidationError2(
+      "`storage` must be a StorageBackend, an IStorageDriver, or a StorageChunkSource"
+    );
+  }
+  const asBackend = storage;
+  const isObject = (v) => v !== null && typeof v === "object";
+  const hasGetChunk = typeof storage.getChunk === "function";
+  const hasPutImmutable = typeof storage.putImmutable === "function";
+  const isBackend = isStorageBackend(storage);
+  if (isBackend && (hasGetChunk || hasPutImmutable)) {
+    throw new ValidationError2(
+      `\`storage\` is a StorageBackend that also exposes ${hasGetChunk ? "`getChunk`" : "`putImmutable`"} \u2014 ambiguous. A backend must not also be a driver or a source; pass whichever one you mean.`
+    );
+  }
+  const hasStorageHalf = isObject(asBackend.storage);
+  const hasRegistryHalf = isObject(asBackend.registry);
+  if (!isBackend && hasPutImmutable && hasRegistryHalf) {
+    throw new ValidationError2(
+      "`storage` looks like a driver that also carries a `registry`. Passed as a bare driver it would have no pointer at all \u2014 generations would resolve by list-scan, so reads could serve a generation that was written but never published. If you meant a backend, use a backend class \u2014 S3Storage, GcsStorage, AzureBlobStorage, LocalFsStorage or MemoryStorage \u2014 or, to pair a driver of your own with a registry, brand the pair with `brandAsBackend` from `@cloudbitmaps/core/driver-kit`."
+    );
+  }
+  if (!isBackend && !hasGetChunk && !hasPutImmutable && hasStorageHalf && hasRegistryHalf) {
+    const storageOk = typeof asBackend.storage.putImmutable === "function";
+    const registryOk = typeof asBackend.registry.compareAndSwap === "function";
+    if (!storageOk || !registryOk) {
+      const bad = !storageOk ? "`storage` half is not an IStorageDriver (no `putImmutable`)" : "`registry` half is not an IRegistryDriver (no `compareAndSwap`)";
+      throw new ValidationError2(
+        "`storage` looks like a backend but its " + bad + " \u2014 use a backend class, or brand a pair of drivers with `brandAsBackend` from `@cloudbitmaps/core/driver-kit`."
+      );
+    }
+    throw new ValidationError2(
+      "`storage` must be a backend \u2014 S3Storage, GcsStorage, AzureBlobStorage, LocalFsStorage or MemoryStorage. An object with `.storage` and `.registry` is not one: a backend builds both halves from a single bucket and prefix, so they cannot disagree, and hand-assembling them re-opens exactly that mismatch \u2014 a store whose pointer and generations live in different places reads as empty rather than failing. A driver author who genuinely wants halves of their own \u2014 an instrumented driver, a registry in a database you already run \u2014 brands the pair with `brandAsBackend` from `@cloudbitmaps/core/driver-kit`, which is taking on that they agree."
+    );
+  }
+  if (isBackend) {
+    const backend = storage;
+    return {
+      source: new CrbmStorageChunkSource(backend.storage, {
+        registry: backend.registry,
+        keystore: options.encryption?.keystore,
+        requireEncryption: options.encryption?.required,
+        clock,
+        currentGenTtlMs: options.cache?.genTtlMs,
+        maxOpenSegments: options.cache?.readerMax,
+        maxOpenIndexBytes: options.cache?.readerMaxBytes
+      }),
+      driver: backend.storage,
+      registry: backend.registry
+    };
+  }
+  if (hasGetChunk && hasPutImmutable) {
+    throw new ValidationError2(
+      "`storage` exposes both `getChunk` and `putImmutable` \u2014 ambiguous; pass a StorageBackend, an IStorageDriver, or a StorageChunkSource, not a hybrid"
+    );
+  }
+  if (!hasGetChunk && !hasPutImmutable) {
+    throw new ValidationError2(
+      "`storage` must be a StorageBackend, an IStorageDriver, or a StorageChunkSource"
+    );
+  }
+  if (hasGetChunk) {
+    if (options.encryption?.keystore !== void 0 || options.encryption?.required === true) {
+      throw new ValidationError2(
+        "keystore/requireEncryption apply only when the store builds its own read path; configure them on the StorageChunkSource you passed instead"
+      );
+    }
+    return { source: storage, driver: void 0, registry: void 0 };
+  }
+  const driver = storage;
+  return {
+    source: new CrbmStorageChunkSource(driver, {
+      keystore: options.encryption?.keystore,
+      requireEncryption: options.encryption?.required,
+      clock,
+      currentGenTtlMs: options.cache?.genTtlMs,
+      maxOpenSegments: options.cache?.readerMax,
+      maxOpenIndexBytes: options.cache?.readerMaxBytes
+    }),
+    driver,
+    registry: void 0
+  };
+}
+var NOT_A_GROUP = {
+  Null: "null",
+  Array: "an array",
+  Map: "a Map",
+  Set: "a Set",
+  Boolean: "a boxed boolean",
+  Number: "a boxed number",
+  String: "a boxed string"
+};
+var CloudRoaring = class _CloudRoaring {
+  engine;
+  cache;
+  /** The store's retry options, for a pinned engine to read through as the store's own does; undefined when off. */
+  retryOptions;
+  crbmSource;
+  clock;
+  metrics;
+  // The store's own drivers, kept so the lifecycle helpers and the `*Into` verbs reuse them instead of making
+  // you re-pass deps. `storageDriver` is set only when `storage` was a raw IStorageDriver (a pre-built StorageChunkSource has
+  // no underlying driver to write through).
+  storageDriver;
+  registry;
+  keystore;
+  requireEncryption;
+  /** Resolved store-level per-op budget (null = disabled); the admin scans use it, with a per-op override. */
+  budget;
+  /**
+   * Refuse any option key the store does not take, at the top level or inside a group, naming each one.
+   *
+   * An option the store ignored would do nothing and look as if it had — a typo'd `cache.maxChunk`, a key from
+   * another library's config spread into this one — so every key is checked against {@link OPTION_KEYS}.
+   */
+  static rejectUnknownOptions(options) {
+    if (options === null || options === void 0 || typeof options !== "object") {
+      throw new ValidationError2(
+        "CloudRoaring needs an options object with a `storage` key \u2014 got " + (options === null ? "null" : typeof options)
+      );
+    }
+    const bag = options;
+    const unknown = [];
+    for (const key of Object.keys(bag)) {
+      if (!OPTION_KEYS.top.includes(key)) unknown.push({ group: null, key });
+    }
+    const groups = Object.keys(OPTION_KEYS).filter((g) => g !== "top");
+    for (const group of groups) {
+      const value = bag[group];
+      if (value === void 0) continue;
+      const offOk = group === "retry" || group === "budget";
+      if (value === false && offOk) continue;
+      const tag = Object.prototype.toString.call(value).slice(8, -1);
+      if (typeof value !== "object" || value === null || NOT_A_GROUP[tag] !== void 0) {
+        const got = typeof value !== "object" ? typeof value : NOT_A_GROUP[tag];
+        throw new ValidationError2(
+          `CloudRoaring's \`${group}\` must be an object${offOk ? " or `false`" : ""} \u2014 got ${got}`
+        );
+      }
+      const known = OPTION_KEYS[group];
+      for (const key of Object.keys(value)) if (!known.includes(key)) unknown.push({ group, key });
+    }
+    if (unknown.length === 0) return;
+    const takes = (keys) => keys.map((k) => `\`${k}\``).join(", ");
+    const named = [...new Set(unknown.map((u) => u.group))];
+    throw new ValidationError2(
+      `CloudRoaring does not take ${takes(unknown.map((u) => u.group === null ? u.key : `${u.group}.${u.key}`))}. ` + named.map(
+        (g) => g === null ? `The store takes ${takes(OPTION_KEYS.top)}.` : `\`${g}\` takes ${takes(OPTION_KEYS[g])}.`
+      ).join(" ") + " https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/api-reference.md#build-a-store--new-cloudroaringoptions"
+    );
+  }
+  constructor(options) {
+    _CloudRoaring.rejectUnknownOptions(options);
+    const clock = options.seams?.clock ?? new SystemClock();
+    const rng = options.seams?.rng ?? new SystemRng();
+    const metrics = safeMetrics(options.metrics ?? NOOP_METRICS);
+    const cache = new BoundedLru({
+      maxEntries: options.cache?.maxChunks ?? DEFAULT_CACHE_MAX_CHUNKS,
+      ttlMs: options.cache?.ttlMs,
+      clock
+    });
+    const resolved = resolveStorageSource(options, clock);
+    let storage = resolved.source;
+    if (options.retry !== false) {
+      const { onRetry: userOnRetry, ...ov } = options.retry ?? {};
+      const policy = {
+        maxAttempts: ov.maxAttempts ?? DEFAULT_RETRY_POLICY.maxAttempts,
+        baseDelayMs: ov.baseDelayMs ?? DEFAULT_RETRY_POLICY.baseDelayMs,
+        maxDelayMs: ov.maxDelayMs ?? DEFAULT_RETRY_POLICY.maxDelayMs,
+        backoffFactor: ov.backoffFactor ?? DEFAULT_RETRY_POLICY.backoffFactor,
+        jitter: ov.jitter ?? DEFAULT_RETRY_POLICY.jitter
+      };
+      const retryOpts = {
+        clock,
+        rng,
+        policy,
+        // 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
+          });
+          userOnRetry?.(info);
+        }
+      };
+      storage = new RetryingStorageChunkSource(storage, retryOpts);
+      this.retryOptions = retryOpts;
+    }
+    this.budget = resolveBudget(options.budget, DEFAULT_BUDGET);
+    const deps = {
+      storage,
+      cache,
+      codec: roaringCodec,
+      // the facade injects the flagship codec; core stays codec-agnostic
+      clock,
+      metrics,
+      budget: this.budget
+    };
+    this.engine = new SegmentEngine(deps);
+    this.cache = cache;
+    this.crbmSource = resolved.source instanceof CrbmStorageChunkSource ? resolved.source : void 0;
+    this.clock = clock;
+    this.metrics = metrics;
+    this.storageDriver = resolved.driver;
+    this.registry = resolved.registry;
+    this.keystore = options.encryption?.keystore;
+    this.requireEncryption = options.encryption?.required ?? false;
+  }
+  /**
+   * The write-side deps, from the store's own drivers, for the lifecycle helpers and the `*Into` verbs. Requires
+   * the store to have been constructed with a **backend**, which supplies both halves: an `IStorageDriver` to
+   * write generations through (a pre-built `StorageChunkSource` has none) and the registry holding the pointer
+   * every write publishes.
+   */
+  lifecycleDeps(op) {
+    if (this.storageDriver === void 0) {
+      throw new UnsupportedError(
+        `${op} needs the store built with a storage backend \u2014 S3Storage, GcsStorage, AzureBlobStorage, LocalFsStorage or MemoryStorage. A pre-built StorageChunkSource is read-only: it has no IStorageDriver underneath to write generations through. Build the store on one of those backend classes to write.`
+      );
+    }
+    if (this.registry === void 0) {
+      throw new UnsupportedError(
+        `${op} needs a storage backend \u2014 S3Storage, GcsStorage, AzureBlobStorage, LocalFsStorage or MemoryStorage. A bare IStorageDriver has no generation pointer to publish through, and there is no separate \`registry\` option: a backend carries it.`
+      );
+    }
+    return {
+      storage: this.storageDriver,
+      registry: this.registry,
+      clock: this.clock,
+      codec: roaringCodec,
+      // facade injects the flagship codec
+      keystore: this.keystore,
+      requireEncryption: this.requireEncryption
+    };
+  }
+  /** Get a handle to a segment. Validates the name (non-empty, well-formed, within the encoded-length cap). */
+  segment(name, options) {
+    const ref = { segment: name, namespace: options?.namespace };
+    validateSegmentRef(ref);
+    refuseReservedNamespace(ref.namespace);
+    const expiresAt = options?.expiresAt;
+    if (expiresAt !== void 0) {
+      if (!Number.isFinite(expiresAt) || !Number.isInteger(expiresAt) || expiresAt < MIN_EXPIRES_AT_MS) {
+        throw new ValidationError2(
+          `segment: expiresAt must be an integer epoch-MILLISECONDS >= ${MIN_EXPIRES_AT_MS}; got ${expiresAt} (a value in seconds lands in 1970 and would make the segment read as permanently empty)`
+        );
+      }
+    }
+    return makeSegment({
+      engine: this.engine,
+      ref,
+      clock: this.clock,
+      metrics: this.metrics,
+      materialize: (dest, ids, op, options2) => this.materialize(dest, ids, op, options2),
+      pinned: (r, e) => this.pinSegment(r, e),
+      combineEngine: (handles) => this.engineForCombine(handles),
+      expiresAt
+    });
+  }
+  /**
+   * Write `ids` as a **new generation of `dest`** and publish it — the shared body of the `*Into` verbs. An `*Into`
+   * materialisation is a load, and publishes the same way (hard invariant 1): every load that finds a row fences its
+   * publish on the row's token; a guarded load (the default, since the empty refusal reads the current generation)
+   * also fences on the pointer it judged (`expectFrom`), and one that found no row fences on that absence instead.
+   * Only an unguarded load (`allowEmpty: true` and no `guard.minRetained`) onto a segment with no row publishes bare
+   * forward-only. The destination's previous generation stays readable until the publish lands (readers re-resolve
+   * within `cache.genTtlMs`).
+   *
+   * This routes through `loadSegment` rather than writing the generation itself, and that is the whole point
+   * of it. A materialisation is a load whose ids happen to come from a combine instead of from upstream, so
+   * everything `load()` learned the hard way applies unchanged: the generation is written UNPUBLISHED, the
+   * guard runs while the old generation is still authoritative, the publish is fenced as above, and a refused
+   * object is reclaimed only when a re-read finds the row unchanged (the same token) or gone (hard invariant 1:
+   * deleting it after a purge-and-recreate would put a live row over a missing generation).
+   *
+   * That last check narrows the window rather than closing it: the row read and the delete are two round
+   * trips, and `IStorageDriver` has no conditional delete to make them one. the collection a load runs carries
+   * the same residual. The failure it leaves is an orphan object, which costs storage until
+   * something collects it — deliberately the cheaper side of the trade.
+   *
+   * Written and published in one step, with no guard, an empty combine — a typo'd operand, an `exclude` that
+   * swallowed everything, an operand that had not loaded yet — would silently replace `dest` with an empty
+   * generation: the same failure `load()`'s guard exists to prevent, on the same data, reachable without passing
+   * any option at all.
+   *
+   * **A lost race throws.** `loadSegment` reports one as `reason: 'superseded'`; the `*Into` verbs throw
+   * {@link WriteConflictError} for it, so a caller can `catch (WriteConflictError)`. That one refusal is
+   * translated into the throw, and `MaterializeResult.reason` never carries it.
+   *
+   * **A `WriteConflictError` does not by itself mean nothing was published**, and that is worth knowing
+   * before you write the retry. `'superseded'` covers five different causes — the write-once PUT collided,
+   * the pointer moved, a row appeared where the load found none, the row's token changed, the row was purged —
+   * and only the first three are the "somebody beat us" the name suggests. A token can also change on a write
+   * that is not a supersession at all, such as a `setRetention` on the destination. On top of that, the collection pass that runs AFTER a
+   * successful publish can raise the same error. So: treat it as "re-read the destination and decide",
+   * never as "the write did not happen".
+   *
+   * **And by default it collects nothing**, unlike `load()`. See the `keep` default below.
+   */
+  async materialize(dest, ids, op, options) {
+    const deps = this.lifecycleDeps(op);
+    let result;
+    try {
+      result = await loadSegment(dest, ids, deps, {
+        ...options?.allowEmpty === void 0 ? {} : { allowEmpty: options.allowEmpty },
+        ...options?.guard === void 0 ? {} : { guard: options.guard },
+        // COLLECT NOTHING by default, which `loadSegment` does not — it keeps a grace window of 1 and deletes
+        // the rest. By default a materialisation collects nothing: the guide states "**It deletes nothing**,
+        // unlike `load()`. The destination's previous generations stay in the bucket until you collect them", and
+        // the ownership table
+        // puts that call on the operator. Inheriting `load()`'s collection would silently delete the
+        // generations an operator's recovery story depends on — `rollbackSegment` refuses a collected target —
+        // as a side effect of adding a guard whose entire purpose is preventing data loss. Opt in with `keep`.
+        keep: options?.keep ?? KEEP_EVERY_GENERATION,
+        ...options?.audit === void 0 ? {} : { audit: options.audit }
+      });
+    } finally {
+      this.engine.invalidate(dest);
+    }
+    const reason = result.reason;
+    if (reason === "superseded") {
+      const wrote = result.size > 0 ? `generation ${result.generation} was written and did not become current` : `nothing was written \u2014 another writer took generation ${result.generation} first`;
+      throw new WriteConflictError(
+        `${op}: the destination "${dest.segment}" changed while this materialisation was in flight, so it never became current: ${wrote}. The pointer may have moved, the row may have been rewritten (a retention policy does this) or purged. Re-read the destination and re-run.`
+      );
+    }
+    return {
+      generation: result.generation,
+      published: result.published,
+      ...reason === void 0 ? {} : { reason },
+      cardinality: result.cardinality,
+      cardinalityBefore: result.cardinalityBefore,
+      chunkCount: result.chunkCount,
+      size: result.size,
+      collected: result.collected
+    };
+  }
+  /**
+   * **Subject access (GDPR Art. 15 / CCPA right-to-know): which segments is this id a member of?**
+   *
+   * Enumerates the **registered** segments (via the store's own `registry`) and does a `has(id)` on each — no
+   * drivers to re-pass. Complete only over registered segments (every loaded segment has a row, so build the
+   * store on the backend the loads used). There is deliberately **no `id → segments` reverse index** — that would
+   * tax every load for a rare request; this admin scan is `O(registered segments)` and touches no hot path. Needs
+   * a storage backend (throws {@link UnsupportedError} otherwise).
+   *
+   * **Current as of the registry row, not as of the reader's cache.** Each segment's resolved generation is
+   * compared with the row the scan listed, and a segment whose cached generation differs is re-resolved before the
+   * read, so a load or an erasure from another process shows at once — whatever `cache.genTtlMs` is, `0` included.
+   * The comparison is on the generation **and** the row's token, so a segment retired, purged and loaded again from
+   * generation 0 while this store held its old generation 0 is told apart too.
+   */
+  async subjectReport(id, options = {}) {
+    const registry = this.requireRegistry("subjectReport");
+    requireScope(options, "subjectReport");
+    validateConcurrency(options.concurrency);
+    const budget = resolvePerOpBudget(options.budget, this.budget);
+    splitId(id);
+    const recs = await collectWithinBudget(
+      // A subject cannot be in a due-index row, and charging this request's budget for them would refuse a
+      // GDPR Art. 15 report for a reason unrelated to the subject.
+      excludingReservedRows(registry.list(options.namespace)),
+      budget,
+      "subjectReport"
+    );
+    const membership = await mapWithConcurrency(
+      recs,
+      options.concurrency ?? DEFAULT_ADMIN_CONCURRENCY,
+      async (rec) => {
+        if (rec.status === "destroyed") return null;
+        const ref = { segment: rec.segment, namespace: rec.namespace };
+        if (this.crbmSource !== void 0) {
+          const held = await this.crbmSource.currentVersion(ref);
+          const listed = rec.currentGen === null ? null : `${rec.currentGen}:${String(rec.token)}`;
+          if (held !== listed) this.engine.invalidate(ref);
+        }
+        return await this.engine.has(ref, id) ? { 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 the bit physically gone
+   * from the bucket on return.**
+   *
+   * For each **registered** segment the id is a member of, `eraseIdFromSegment` rewrites the current generation
+   * without the id — every chunk streamed through, one bit cleared — publishes the rewrite **fenced on the
+   * generation it was derived from**, and collects the generation that held the bit. A segment whose current
+   * generation does not hold the id is searched anyway, every generation in its bucket: a retained superseded one
+   * can still hold it, and so can one above the pointer after a {@link CloudRoaring.rollback}, which the rollback
+   * could make current again. Each holder is deleted — below the pointer by a `keep: 0` collection, above it one
+   * by one, re-proved against the row first — and the generations above the pointer that never held the id stay
+   * as rollback targets. An entry says `erased: true` only once the call has listed the bucket and read what is
+   * left: **no generation of the segment holds the id**. The returned per-segment record is your **erasure ledger** —
+   * persist it / route it to your audit sink as the proof of deletion (a `segment.rewrite` audit event is also
+   * emitted per rewrite when you pass `audit`).
+   *
+   * Uses the backend's **own** two halves, so the membership check and the rewrite provably run
+   * over the same generation. Requires the store built with a **backend** (throws
+   * {@link UnsupportedError} otherwise; a pre-built `StorageChunkSource` store has no `IStorageDriver` to write
+   * through; build the store on a backend instead).
+   *
+   * **One contract remains** (an integrator obligation the library cannot check): **do not load the segment
+   * while erasing from it.** A load that lands after the rewrite carries whatever its source held, and the
+   * library cannot know that source was meant to exclude the id. Quiesce loads of the affected segments for the
+   * duration, or fix the source first and load after. A writer that lands *during* the rewrite is caught: the
+   * rewrite's publish is refused **by the fence** — the publish lands its compare-and-swap only
+   * while the pointer is still on the generation the rewrite streamed — and the entry says `note: 'superseded'`,
+   * so re-run. Forward-only alone would NOT refuse it: the rewrite's number goes above everything in the bucket,
+   * so the rewrite would out-rank the newer generation and then collect it.
+   *
+   * A racing **erasure** is caught before that, and reported the same way. It collects with `keep: 0`, taking
+   * every generation below its new pointer — the one this rewrite is streaming, and the object this rewrite
+   * just wrote — so the loser can find its own inputs deleted mid-flight. That surfaces as an outcome rather than
+   * an error, read off the row: a moved pointer is a `'superseded'` entry, which a re-run settles, and a segment
+   * that a concurrent `dropSegment` tombstoned or a retention sweep purged is left out of the ledger, as a fresh
+   * call would leave it out.
+   *
+   * **Read `note` on any `erased: false` entry — the two reasons mean different things.** `'superseded'` means
+   * another writer (a load, another erasure, or a rollback) moved the pointer mid-call, so **this call** did not
+   * erase the id. Re-run: it erases the id if it is still there, and lists nothing for the segment if a racing
+   * erasure of the same id already removed it. Do not read `'superseded'` as "the id is still present" —
+   * read it as "not done by this call, and the re-run settles it".
+   * `` `error: …` `` is a per-segment fault (caught so one segment can't discard the whole ledger) and it can land
+   * on either side of the publish: if the rewrite had not published, the id is still there and a re-run erases
+   * it; if the publish succeeded and only the **collection** of the old generation failed, the id is already
+   * absent from every read and what remains is an object in the bucket that still contains the bit. The same
+   * note, after a publish, can mean a rollback moved the pointer back onto a generation that still holds the id
+   * while the collection ran — then the id is served again, and the entry says so rather than `erased: true`. A
+   * re-run searches every generation in the bucket, so it rewrites or collects what is left and usually reports
+   * `erased: true`; {@link SubjectErasureEntry.note} says what else a re-run can report. Re-running is otherwise safe
+   * and idempotent: a segment the id is no longer in is not listed. Admin-only path;
+   * `O(registered segments + superseded generations)`, no hot-path cost: a segment whose current generation lacks
+   * the id is searched generation by generation, one open for each other generation in its bucket, and with the
+   * keep-everything default of the `*Into` verbs that is one per generation the segment ever had. The per-op
+   * `budget` is charged one unit for each segment and one for each generation opened beyond the one its row names,
+   * so a fleet with long histories can exhaust it where the segment count alone would not. A segment that does is
+   * reported `erased: false` with an `error:` note, before it deletes anything (the one refusal that can come after a
+   * rewrite is the last check for a generation a concurrent writer left behind), and the
+   * rest of the scan continues: the call itself does not throw for it. 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 `dropSegment` / the `destroySegment`/`eraseNamespace` free functions.
+   */
+  async eraseSubject(id, options = {}) {
+    const deps = this.lifecycleDeps("eraseSubject");
+    requireScope(options, "eraseSubject");
+    validateConcurrency(options.concurrency);
+    const budget = resolvePerOpBudget(options.budget, this.budget);
+    splitId(id);
+    const recs = await collectWithinBudget(
+      excludingReservedRows(deps.registry.list(options.namespace)),
+      budget,
+      "eraseSubject"
+    );
+    let opens = 0;
+    const charge = () => {
+      opens += 1;
+      checkBudget(budget, recs.length + opens, "eraseSubject");
+    };
+    const entries = await mapWithConcurrency(
+      recs,
+      options.concurrency ?? DEFAULT_ADMIN_CONCURRENCY,
+      async (rec) => {
+        if (rec.status === "destroyed") return null;
+        const ref = { segment: rec.segment, namespace: rec.namespace };
+        try {
+          const result = await eraseIdFromSegment(
+            ref,
+            id,
+            budget === null ? deps : { ...deps, storage: new OpenChargingStorage(deps.storage, rec.currentGen, charge) },
+            { audit: options.audit }
+          );
+          if (result.reason === "not-member" || result.reason === "absent") return null;
+          if (result.reason === "no-generation") return null;
+          if (result.reason === "destroyed") return null;
+          return {
+            segment: rec.segment,
+            namespace: rec.namespace,
+            erased: result.erased,
+            fromGeneration: result.fromGeneration,
+            generation: result.generation,
+            note: result.erased ? void 0 : result.reason
+          };
+        } catch (err) {
+          return {
+            segment: rec.segment,
+            namespace: rec.namespace,
+            erased: false,
+            note: `error: ${err instanceof Error ? err.message : String(err)}`
+          };
+        } finally {
+          try {
+            this.engine.invalidate(ref);
+          } catch {
+          }
+        }
+      }
+    );
+    const erasedFrom = entries.filter((e) => e !== null);
+    return { id, erasedFrom, scannedSegments: recs.length };
+  }
+  /**
+   * Every generation still in the bucket for this segment, ascending, with the current one marked.
+   *
+   * What the bucket holds, not what the segment has ever been — collection deletes superseded objects, so this is
+   * the grace window plus whatever has not been collected yet. It is the set {@link CloudRoaring.rollback} can
+   * choose from, which is the reason to look at it. One registry read and one listing; it does not open the objects.
+   *
+   * Needs a backend.
+   */
+  async generations(ref) {
+    validateSegmentRef(ref);
+    return listGenerations(ref, this.lifecycleDeps("generations"));
+  }
+  /**
+   * Whether a read of this segment would find anything — the "do I already have this?" question, as one
+   * registry point read.
+   *
+   * There is no `create` in this library: {@link CloudRoaring.segment} is a validated address and does no I/O,
+   * so naming a segment can never collide with an existing one. A segment starts existing when something is
+   * first loaded into it, and this is how you ask whether that has happened.
+   *
+   * **Not the same as `count() > 0`.** A segment loaded with no ids exists and counts zero. Distinguishing
+   * "never loaded" from "loaded, and genuinely empty" is the thing `count()` cannot do and the reason this
+   * exists. It is `false` for a segment whose row was minted ahead of its first load (by `setRetention`) and
+   * for a `destroyed` tombstone, because a read answers empty in both cases.
+   *
+   * Two states answer `true` where a read still gives you nothing: a torn restore (a live pointer whose object
+   * was deleted) makes reads *throw* rather than answer empty — `checkConsistency` is the call for that — and
+   * a handle carrying an expired `expiresAt` reads empty by a rule that lives on the handle, not the row.
+   *
+   * Not a lock: the answer can change the moment it returns. If it has to hold, use the fence built for that —
+   * `load`'s `guard`, or `expectFrom`/`expectToken` on a publish. Needs a storage backend.
+   *
+   * ```ts
+   * if (!(await store.exists({ segment: 'users' }))) {
+   *   await store.load({ segment: 'users' }, idsFromUpstream);
+   * }
+   * ```
+   */
+  async exists(ref) {
+    validateSegmentRef(ref);
+    return segmentExists(ref, this.requireRegistry("exists"));
+  }
+  /**
+   * Every segment the registry knows about, streamed — optionally scoped to one namespace.
+   *
+   * The registry is already the list of your segments, which is why you should not keep a second one beside it:
+   * a hand-maintained list is a source of truth that drifts from this one the first time a load fails halfway.
+   *
+   * **An admin/discovery call, not a request-path one.** This is the registry's own enumeration — a paged
+   * LIST over the `registry/` prefix — so its cost grows with the size of the fleet rather than with what you
+   * are looking for.
+   *
+   * Scoping to a namespace narrows the LIST prefix, so it really is the difference between reading one tenant
+   * and reading all of them.
+   *
+   * It streams, and stopping the iteration stops the scan. It reads the registry directly and is not retried: a
+   * transient fault part-way through ends the loop with that error, and calling `segments()` again scans from the
+   * start.
+   *
+   * Yields `destroyed` tombstones and rows with `currentGen: null`, because a filtered enumeration that looks
+   * complete is worse than an honest one — filter on `status`/`currentGen` yourself, or ask
+   * {@link CloudRoaring.exists} the narrower question. Needs a storage backend.
+   *
+   * ```ts
+   * for await (const s of store.segments({ namespace: 'active-daily' })) {
+   *   console.log(s.segment, s.currentGen, s.status);
+   * }
+   * ```
+   */
+  segments(options = {}) {
+    if (options.namespace !== void 0) {
+      validateSegmentRef({ segment: "x", namespace: options.namespace });
+      refuseReservedNamespace(options.namespace);
+    }
+    return listSegments(this.requireRegistry("segments"), options);
+  }
+  /**
+   * Move this segment's pointer **back** to a generation still in the bucket — the one write in the library that
+   * is not forward-only.
+   *
+   * Forward-only is right for a writer: a load whose ids came from upstream loses nothing by being out-raced, and
+   * letting it regress would let a slow loader silently undo a fast one. It is wrong for an operator who has
+   * looked at the segment, decided the current generation is wrong, and knows which one they want. So this is
+   * reachable only by asking for it by name — no sweep, retry or reconciliation calls it — and it is audited
+   * (`segment.rollback`), because every other pointer move can be reconstructed from "a load happened" and this
+   * one cannot.
+   *
+   * It refuses rather than guesses: a generation not in the bucket (collected, or never written) throws
+   * `NotFoundError` naming what *is* available, and a crypto-shredded segment throws
+   * {@link ValidationError} because every generation of it is unreadable. Rolling to the generation already
+   * current is a no-op that reports itself.
+   *
+   * It deletes nothing. The generations above the new pointer stay put — which is what makes this reversible —
+   * and are then *above* `currentGen`, where collection never looks. They remain until a load numbers above them
+   * (collection then keeps the newest `keep` of what is below its pointer), {@link CloudRoaring.dropSegment}
+   * deletes them, or {@link CloudRoaring.eraseSubject} does: all of those present when it rewrites, and only those holding
+   * the id when the current generation does not. An operator who has just undone a bad load should not have the
+   * evidence collected out from under them, while a rollback target that still holds erased data would make the
+   * erasure undoable.
+   *
+   * A target **above** the pointer needs `{ allowForward: true }`, and is refused with {@link ValidationError}
+   * without it: that is also where objects live that were never published, such as a load that wrote its object
+   * and died before the publish. Undoing an earlier rollback is what the opt-in is for.
+   *
+   * Needs a backend.
+   */
+  async rollback(ref, toGeneration, options = {}) {
+    validateSegmentRef(ref);
+    const deps = this.lifecycleDeps("rollback");
+    try {
+      return await rollbackSegment(ref, toGeneration, deps, options);
+    } finally {
+      this.engine.invalidate(ref);
+    }
+  }
+  /**
+   * **Replace this segment's contents** with `ids`, as one new immutable generation, and make it current.
+   *
+   * The whole write path in one call: take the next generation number, write the object, check the result is
+   * plausible, move the pointer, collect what the move superseded. Composed by hand those are four functions and
+   * the one that gets left out is the last, so segments quietly accumulate superseded generations nobody pays
+   * attention to and everybody pays for.
+   *
+   * ```ts
+   * const r = await store.load({ segment: 'audience:active' }, idsFromWarehouse, {
+   *   guard: { minRetained: 0.5 }, // refuse a load that would drop more than half the segment
+   * });
+   * if (!r.published) console.warn(`load refused: ${r.reason}`);
+   * ```
+   *
+   * **A load REPLACES.** Whatever the stream contains is what the segment contains afterwards, so an upstream
+   * query that returns fewer rows than usual is a shrink nobody asked for and an empty one is a wipe — both
+   * reported as a successful write, because at the storage layer they are one. That is what `guard` and the
+   * default empty refusal are for, and why they run **between** the write and the publish: the only moment where
+   * the new content is known and the old one is still authoritative.
+   *
+   * **Branch on `published`.** A refusal is a normal outcome, not an exception — `published: false` with a
+   * `reason`, in the same shape as a success — so a discarded result is a load that silently did nothing, and
+   * with the empty guard on by default this verb refuses more readily than any other. Note the sibling `*Into`
+   * verbs *throw* on the same superseded condition rather than reporting it; this one follows
+   * `eraseIdFromSegment` instead, because three of its four refusals are expected guard outcomes rather than
+   * faults.
+   *
+   * `'superseded'` means another writer got there first: another load took the same generation number, so this
+   * one wrote nothing (`size: 0`), or the segment's registry row changed while the load was writing — another load
+   * published, a retention change, a rollback or an erasure wrote the row, or the row was deleted.
+   *
+   * A refused load deletes the object it wrote before returning — it sits above `currentGen`, where generation
+   * collection deliberately never looks — but only while the segment's registry row is unchanged or gone. Once
+   * another write has changed the row, the generation number it holds may name another incarnation's live object,
+   * so it leaves the orphan rather than risk deleting live data. The orphan is an ordinary generation once a later
+   * one is current above it, and collection counts it within `keep`.
+   *
+   * What it **throws** for is a fault rather than an outcome: invalid options or ids, and a crypto-shredded
+   * segment (`ValidationError`); a key the keystore cannot provide (`KeyUnavailableError`); a current generation
+   * that will not open when a guard reads its size (`IntegrityError`); a driver failure; and a collection pass
+   * that could not prove the segment was still the same one (`WriteConflictError`). The last can be raised
+   * **after** the publish already landed, so a throw does not by itself mean the load did not take effect —
+   * re-read the pointer rather than assuming.
+   *
+   * Needs a backend (throws {@link UnsupportedError} otherwise).
+   */
+  async load(ref, ids, options = {}) {
+    validateSegmentRef(ref);
+    const deps = this.lifecycleDeps("load");
+    try {
+      return await loadSegment(ref, ids, deps, options);
+    } finally {
+      this.engine.invalidate(ref);
+    }
+  }
+  /**
+   * **Dispose of a segment — tombstone it, then delete its storage objects.** Irreversible.
+   *
+   * The operation a rolling window needs: `destroySegment` crypto-shreds (bytes unreadable everywhere including
+   * backups, but still sitting in your bucket and still billed, and it requires encryption), while this one
+   * 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) {
+   *   // The family in the namespace, the date in the segment — `registry.list(namespace)` then enumerates
+   *   // exactly this family's buckets, which a flat `active:2026-08-01` name cannot do without string-matching.
+   *   const ref = { namespace: 'active-daily', segment: day };
+   *   await store.dropSegment(ref, { confirmSegment: ref.segment });
+   * }
+   * ```
+   *
+   * **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.
+   *
+   * **Inspect `generationsRemaining`.** Empty is the normal outcome; non-empty means the storage was NOT fully
+   * reclaimed and the drop should be re-run. A load that was already writing when the tombstone landed still
+   * finishes its object, so a single sweep can miss it — this call re-sweeps and then reports whatever it still
+   * could not remove rather than returning a result that looks like a clean drop.
+   *
+   * Reads become empty within `cache.genTtlMs` (default 2 s), not instantly: a store that had already read this
+   * segment may answer from its cached generation + cached chunks until that window lapses, or, while the registry
+   * cannot be read because of a transient fault, until a retry 500 ms apart reaches it again. A reader that never
+   * touched it sees empty at once. **That bound needs a registry and `cache.genTtlMs > 0`.** A store with no registry
+   * (a bare `IStorageDriver`), with `cache.genTtlMs: 0`, or on a storage source built with no clock, has no timed
+   * refresh. It notices the drop only when a read has to fetch
+   * from a deleted generation or its reader cache evicts the segment, and until then a chunk it has cached
+   * answers without reaching storage, so it can keep answering `true` for a dropped segment indefinitely. Tell
+   * it with {@link invalidate}, or restart it.
+   *
+   * Needs the store built with a **backend** (throws {@link UnsupportedError} otherwise),
+   * because it has to enumerate and delete generations — a pre-built `StorageChunkSource` only reads.
+   */
+  async dropSegment(ref, options) {
+    validateSegmentRef(ref);
+    const deps = this.lifecycleDeps("dropSegment");
+    try {
+      return await dropSegment(ref, { registry: deps.registry, storage: deps.storage }, options);
+    } finally {
+      if (options.dryRun !== true) this.engine.invalidate(ref);
+    }
+  }
+  /**
+   * **Record when this segment becomes eligible for retirement.** One registry write; nothing is deleted here,
+   * and nothing starts running. `retireExpired` is what acts on the policy, and **you** decide when that runs —
+   * an EventBridge rule, a CronJob, a queue consumer, whatever your deployment already has. This library starts
+   * no background thread (it has to work identically in a Lambda, an edge isolate and a long-lived server).
+   *
+   * `expiresAt` is an **absolute epoch-ms you compute**, not a duration the library derives. A relative TTL would
+   * have to be anchored to something the library knows — `updatedAt`, or the current generation — and every load
+   * rewrites both, so "expire 30 days after the last write" would keep a busy daily bucket alive forever
+   * precisely because it is being reloaded.
+   *
+   * ```ts
+   * const DAY = 86_400_000;
+   * const ref = { namespace: 'active-daily', segment: '2026-08-05' };
+   * await store.setRetention(ref, { expiresAt: Date.now() + 30 * DAY });
+   * ```
+   *
+   * **Works before the first load**: a segment with no registry row yet gets one (`createdRow: true` in the
+   * result) with **no Storage generation**, so the policy is recorded ahead of the data and the segment is already
+   * enumerable by the sweep; the first load then publishes onto that row.
+   *
+   * A value in the past is legal and means "eligible on the next sweep" — backfilling a policy onto existing
+   * buckets is normal. A value below `MIN_EXPIRES_AT_MS` (2001-09-09) is rejected: it is almost certainly epoch
+   * **seconds**, which would read as long-expired and retire the segment on the next pass. Needs a storage
+   * backend (throws {@link UnsupportedError} otherwise), and refuses a crypto-shredded segment.
+   */
+  async setRetention(ref, policy) {
+    validateSegmentRef(ref);
+    return 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) {
+    validateSegmentRef(ref);
+    return 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) {
+    validateSegmentRef(ref);
+    return 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,
+   * the job that runs your loads). A library that started a timer would behave differently in a Lambda, an edge
+   * isolate and a long-lived server, which is worse than not having one.
+   *
+   * Each retirement goes through `dropSegment`, so the registry → Storage ordering, the re-sweep for an object a
+   * load was still writing, and the `generationsRemaining` report all come from one implementation rather than
+   * two.
+   *
+   * ```ts
+   * // In your scheduled handler. Start with a preview in a new deployment.
+   * const preview = await store.retireExpired({ namespace: 'active-daily', dryRun: true });
+   * console.log(`would retire ${preview.wouldRetire} of ${preview.scanned} (limited: ${preview.limited})`);
+   *
+   * const swept = await store.retireExpired({ namespace: 'active-daily' });
+   * for (const e of swept.entries) {
+   *   if (e.action === 'skipped') console.warn(`${e.segment}: ${e.reason}`); // invalid-policy / limit / failed: …
+   *   if (e.action === 'retired' && e.result.generationsRemaining.length > 0) {
+   *     console.warn(`${e.segment}: storage not fully reclaimed — re-run`);
+   *   }
+   * }
+   * if (swept.limited) scheduleAnotherPassSoon(); // more are still eligible
+   * ```
+   *
+   * **Read the ledger.** A per-segment *fault* is an entry, not an exception — a throw from the middle of a fleet
+   * sweep would leave the caller unable to say which segments were retired, having already retired some. (A bad
+   * argument does throw, and so does a fleet larger than `maxScanSegments`.) `limited: true` means the per-cycle
+   * `limit` (default 100) cut the pass short and more are eligible. That cap is charged on **attempts**, not
+   * successes, which is what makes it a real bound: `dropSegment` writes the tombstone before sweeping Storage, so a
+   * fault in the Storage phase is a segment that is already retired. Retirements are sequential, so `limit` is a
+   * wall-clock knob too, and `retired` counts deletions only — a dry run reports `wouldRetire` instead, so a
+   * dashboard summing `retired` can never show a phantom deletion.
+   *
+   * It also **deletes the tombstone rows its own past retirements left**, after `tombstoneGraceMs` (default 24 h)
+   * and only once that segment's Storage generations are provably gone — collecting a straggler generation itself
+   * first, since nothing else ever would for a tombstoned segment. Attribution is a **positive marker the sweep
+   * stamps on its own retirements**, not an inference from "destroyed + an expired policy": a crypto-shred leaves
+   * `retention` untouched, so setting a policy and then honouring a right-to-erasure request mid-window produces
+   * exactly that row, and deleting it would destroy the Art. 17 attestation and un-fence the name. By default a
+   * segment that held nothing has its row deleted in the pass that retires it, since that row would only fence the name.
+   * Pass `purgeTombstones: false` to keep every tombstone, that row included.
+   *
+   * Needs the store built with a **backend** (throws {@link UnsupportedError} otherwise),
+   * because retiring a segment deletes its storage objects. `now` defaults to the store's clock.
+   */
+  async retireExpired(options = {}) {
+    const deps = this.lifecycleDeps("retireExpired");
+    const result = await retireExpired(
+      { registry: deps.registry, storage: deps.storage },
+      { ...options, now: options.now ?? this.clock.now() }
+    );
+    if (options.dryRun !== true) {
+      for (const entry of result.entries) {
+        this.engine.invalidate({ segment: entry.segment, namespace: entry.namespace });
+      }
+    }
+    return result;
+  }
+  /**
+   * **Forget everything this store has cached about a segment.** Use it after destroying or retiring a segment
+   * through a path this store did not perform itself.
+   *
+   * A store keeps two layers of derived state — a resolved snapshot per segment (an open `.crbm` reader, plus
+   * the DEK it unwrapped) and decoded chunks keyed by generation. Both are built for one event: **a publish
+   * that advances `currentGen`**, which the snapshot TTL notices and the generation-keyed cache misses on.
+   * Neither notices an event that *destroys* what they were derived from.
+   *
+   * The store's own writes handle themselves: `load`, `rollback`, `eraseSubject`, `dropSegment` and `retireExpired`
+   * here, and a segment's `*Into` verbs, invalidate what they touch. This method is for the cases they cannot see:
+   *
+   * - **`destroySegment` / `eraseNamespace`**, which are free functions over raw drivers rather than methods
+   *   here, so a crypto-shred performed beside this store invalidates nothing in it. It keeps its open reader and
+   *   the unwrapped DEK, and decrypts with them, chunks it had never fetched before the shred included, until its
+   *   snapshot re-resolves: within `cache.genTtlMs` when the store has a registry and a `genTtlMs` above 0, and
+   *   otherwise only when its caches let the segment go or a read has to fetch from a generation a sweep collected.
+   *   A pin answers with no timed bound, until it is told or both caches let it go.
+   * - **Another process.** Erasing on one box invalidates nothing on the others; each store bounds its own
+   *   staleness by `cache.genTtlMs`, and a store with no registry (a bare `IStorageDriver`), with
+   *   `cache.genTtlMs: 0`, or on a storage source built with no clock has no bound at all: it converges only when a read happens to miss its caches. If a compliance deadline depends on every
+   *   reader converging, you need to signal them — this is the call to make when your own fan-out delivers.
+   *
+   * It also forgets any replacement this store found of a pin's object, so once it is called after a restore puts that
+   * object back, the pin reads it again.
+   *
+   * Synchronous, best-effort, and safe to call for a segment this store has never read.
+   *
+   * ```ts
+   * await destroySegment(ref, { registry: backend.registry }, { confirmSegment: ref.segment });
+   * store.invalidate(ref);                       // this process
+   * await bus.publish('cloudbitmaps.invalidate', ref); // and every other one
+   * ```
+   */
+  invalidate(ref) {
+    validateSegmentRef(ref);
+    refuseReservedNamespace(ref.namespace);
+    this.engine.invalidate(ref);
+  }
+  /**
+   * Build a handle held at the generation `ref` resolves to right now. See {@link Segment.pin}.
+   *
+   * The pinned handle gets its own engine but **shares the store's chunk cache**, under keys of its own: the
+   * pinned view reports the version captured at pin time, marked as a pin's, so its decoded chunks are never
+   * those of a live read that fetched across a publish (see {@link PinnedStorageChunkSource.currentVersion}).
+   */
+  async pinSegment(ref, expiresAt) {
+    const crbm = this.crbmSource;
+    if (crbm === void 0) {
+      throw new UnsupportedError(
+        "pin() needs the `.crbm` storage source \u2014 pass a backend or a raw IStorageDriver as `storage` (a pre-built StorageChunkSource that cannot resolve a generation has nothing to pin)"
+      );
+    }
+    const at = await this.withRetries(() => crbm.pinGeneration(ref));
+    const pinnedAt = {
+      generation: at?.generation ?? null,
+      version: at?.version ?? null,
+      fingerprint: at?.fingerprint ?? null
+    };
+    const pins = /* @__PURE__ */ new Map([[segmentKey(ref), pinnedAt]]);
+    return makeSegment({
+      engine: this.engineWithPins(pins),
+      ref,
+      clock: this.clock,
+      metrics: this.metrics,
+      materialize: (dest, ids, op, options) => this.materialize(dest, ids, op, options),
+      pinned: (r, e) => this.pinSegment(r, e),
+      combineEngine: (handles) => this.engineForCombine(handles),
+      expiresAt,
+      pinnedAt
+    });
+  }
+  /**
+   * An engine reading every segment in `pins` at its pinned generation and everything else live, with the store's
+   * retries, so a transient fault on a pinned read is retried as it would be on a live one.
+   *
+   * It **shares the store's chunk cache and its memory bound**, under keys of its own for each pinned segment.
+   */
+  engineWithPins(pins) {
+    const crbm = this.crbmSource;
+    if (crbm === void 0) {
+      throw new UnsupportedError(
+        "pin() needs the `.crbm` storage source \u2014 pass a backend or a raw IStorageDriver as `storage` (a pre-built StorageChunkSource that cannot resolve a generation has nothing to pin)"
+      );
+    }
+    const pinned = new PinnedStorageChunkSource(crbm, pins);
+    return new SegmentEngine({
+      storage: this.retryOptions === void 0 ? pinned : new RetryingStorageChunkSource(pinned, this.retryOptions),
+      cache: this.cache,
+      codec: roaringCodec,
+      clock: this.clock,
+      metrics: this.metrics,
+      budget: this.budget
+    });
+  }
+  /**
+   * The engine a combine should run on, given the handles involved.
+   *
+   * A pinned handle passed as an **operand** must still be read at its pin. Routing by "which handle the call
+   * was made on" reads it live instead — `snap.intersect([other])` honours the pin while
+   * `other.intersect([snap])` silently does not, and the two are the same question. So the combine collects
+   * every pin in play and runs on an engine that honours all of them. With no pins anywhere this is the
+   * store's own engine and costs nothing.
+   *
+   * One engine reads a segment at one generation, so a combine that holds the same segment at two — two pins of
+   * it, or a pin and a live handle — is refused. Keeping one of them would answer the question for the wrong
+   * instant, and say nothing: diffing two snapshots of a segment returned no ids at all.
+   */
+  engineForCombine(handles) {
+    if (!handles.some((h) => h.pinnedAt !== void 0)) return void 0;
+    const pins = /* @__PURE__ */ new Map();
+    const held = /* @__PURE__ */ new Map();
+    for (const h of handles) {
+      const key = h.key();
+      const at = h.pinnedAt;
+      if (held.has(key)) {
+        const before = held.get(key);
+        if (!samePin(before, at)) {
+          throw new ValidationError2(
+            `the same segment is in this combine twice, ${twoPins(before, at)}: one call reads a segment at one generation, so materialise one of them into a segment of its own first, with \`intersectInto(dest, [])\``
+          );
+        }
+      } else {
+        held.set(key, at);
+      }
+      if (at !== void 0) pins.set(key, at);
+    }
+    return this.engineWithPins(pins);
+  }
+  /** `op` under the store's retries, as the store's own reads run; bare when the store has retries off. */
+  withRetries(op) {
+    const r = this.retryOptions;
+    return r === void 0 ? op() : withRetry(op, r.policy ?? DEFAULT_RETRY_POLICY, r);
+  }
+  /** The store's registry, or a typed error naming the operation that needs one. */
+  requireRegistry(op) {
+    if (this.registry === void 0) {
+      throw new UnsupportedError(
+        `${op} needs a storage backend \u2014 S3Storage, GcsStorage, AzureBlobStorage, LocalFsStorage or MemoryStorage. A bare IStorageDriver has no generation pointer to publish through, and there is no separate \`registry\` option: a backend carries it.`
+      );
+    }
+    return this.registry;
+  }
+  /**
+   * **Cross-tier DR consistency check.** After a restore/failover, verify every registered segment's `currentGen`
+   * actually has its `.crbm` present in Storage — catching a **torn restore** where the registry (`currentGen`) came
+   * back ahead of the object store, so a pointer references a generation that isn't there (reads would then
+   * throw). Read-only, bounded fan-out; run it at startup after a restore. Returns `{ checked, inconsistent,
+   * errored }` — `inconsistent` empty ⇒ coherent; otherwise it names the segments to recover (restore the object
+   * store, or roll the registry back to a coherent point). Needs the store built with a **backend**
+   * (throws {@link UnsupportedError} otherwise). `destroyed` (crypto-shredded) segments are skipped. Pair it with
+   * the DR runbook (docs/guide/disaster-recovery.md).
+   *
+   * It holds the registry rows it enumerates resident, at most 250,000 of them, and throws
+   * `BudgetExceededError` past that rather than report a partial scan as a whole one. This method takes no
+   * ceiling of its own: narrow the scan with `namespace`, or call `runConsistencyCheck` over the backend's
+   * `storage` and `registry` with a higher `maxScanSegments`.
+   */
+  async checkConsistency(options = {}) {
+    const deps = this.lifecycleDeps("checkConsistency");
+    return runConsistencyCheck({ storage: deps.storage, registry: deps.registry }, options);
+  }
+  /**
+   * **Export ("eject") every registered segment's current generation** through the injected `sink`, using only
+   * public read APIs — so your data is readable **without CloudRoaring** (the exit path; see the README's "Your
+   * data stays yours"). `format: 'roaring'` (default) writes one **portable RoaringBitmap32** per segment
+   * (loadable by any roaring library); `'ndjson'` writes newline-delimited ids (zero-dependency, streaming).
+   * Enumerates via the store's **own** registry (needs one — throws {@link UnsupportedError} otherwise) so the
+   * enumeration and the read path provably share one registry. 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 runExport(this, registry, sink, {
+      ...options,
+      codec: options.codec ?? roaringCodec
+    });
+  }
+  /**
+   * Planning cost estimate — pure, no instance/data needed: sizing, sales, what-if. For a real, grounded report
+   * from live segment sizes, use `store.segment(name).costReport()`. See {@link CostReport}.
+   */
+  static estimateCost(input) {
+    return estimateCost(input);
+  }
+};
+var failing = (err) => ({
+  [Symbol.asyncIterator]: () => ({ next: () => Promise.reject(err) })
+});
+var samePin = (a, b) => a === void 0 || b === void 0 ? a === b : a.generation === b.generation && a.fingerprint === b.fingerprint;
+var twoPins = (a, b) => {
+  const one = (p) => p === void 0 ? "live" : `pinned at generation ${p.generation ?? "none"}`;
+  return a !== void 0 && b !== void 0 && a.generation === b.generation ? `pinned twice at generation ${a.generation ?? "none"}, as two different objects` : `${one(a)} and ${one(b)}`;
+};
+var rangeOf = (options) => ({
+  after: options.after,
+  through: options.through
+});
+var readOptions = (options) => ({
+  ...rangeOf(options),
+  concurrency: options.concurrency,
+  budget: options.budget,
+  allowAbsentOperands: options.allowAbsentOperands
+});
+var NO_SEGMENTS = [];
+var EMPTY_IDS = {
+  async *[Symbol.asyncIterator]() {
+  }
+};
+var KEEP_EVERY_GENERATION = Number.MAX_SAFE_INTEGER;
+var makeSegment;
+var minting = false;
+var Segment = class _Segment {
+  metricsOn;
+  engine;
+  ref;
+  clock;
+  metrics;
+  materialize;
+  pinned;
+  combineEngine;
+  /** Absolute epoch-ms deadline from {@link SegmentOptions.expiresAt}; `undefined` ⇒ this handle never expires. */
+  expiresAt;
+  /**
+   * The generation this handle is held at, when it came from {@link Segment.pin}. Read by the store so a
+   * pinned handle passed as an **operand** is still read at its pin rather than live.
+   */
+  pinnedAt;
+  static {
+    makeSegment = (parts) => {
+      minting = true;
+      try {
+        return new _Segment(parts);
+      } finally {
+        minting = false;
+      }
+    };
+  }
+  /**
+   * Not constructible: a handle comes from {@link CloudRoaring.segment}, which wires it to the store's engine,
+   * caches and write path. The constructor takes those internals, so it is not part of the surface.
+   */
+  constructor(parts) {
+    if (!minting) {
+      throw new ValidationError2(
+        "a Segment is not constructed directly; call `store.segment(name)`"
+      );
+    }
+    this.engine = parts.engine;
+    this.ref = parts.ref;
+    this.clock = parts.clock;
+    this.metrics = parts.metrics;
+    this.materialize = parts.materialize;
+    this.pinned = parts.pinned;
+    this.combineEngine = parts.combineEngine;
+    this.expiresAt = parts.expiresAt;
+    this.pinnedAt = parts.pinnedAt;
+    this.metricsOn = parts.metrics !== NOOP_METRICS;
+  }
+  /**
+   * **Hold this segment at the generation that is current right now**, for as long as you keep the handle.
+   *
+   * An ordinary handle re-resolves on `cache.genTtlMs`, so a publish part-way through a long job means its second
+   * half describes a different instant than its first — every chunk whole and verified, but the answer covering
+   * two moments, with nothing in the result saying so. That is fine for a dashboard and wrong for an export, a
+   * reconciliation, or a send that has to match the count you reported. A pin is how you get one instant.
+   *
+   * ```ts
+   * const snap = await store.segment('active-30d').pin();
+   * const total = await snap.count();            // the number you report
+   * for await (const id of snap.iterate()) { … } // …and the ids it counted, however long this takes
+   * ```
+   *
+   * **Only this segment is pinned.** `snap.intersect([other])` reads `snap` at its pinned generation and
+   * `other` at whatever is current — pin each segment if you want the whole query held. And a pinned handle
+   * used as an *operand* is still read at its pin, never live.
+   *
+   * **One call reads a segment at one generation**, so a combine that holds this segment at two —
+   * `snap0.andNot([snap1])`, or `live.intersect([snap])` — throws {@link ValidationError} when it is read, and an
+   * `*Into` of one throws before it reads anything. Materialise one side first, with `intersectInto(dest, [])`.
+   *
+   * **A pin knows its object, not only its number.** A name purged and loaded again starts again at generation
+   * 0, so a pin of the old segment never reads the new one: what it has already read still answers, as the
+   * instant it pinned, and anything it would have to fetch fails with `NotFoundError`, as a swept pin's does.
+   *
+   * **It is a hold, not a lease.** Nothing here stops a collection deleting the generation underneath
+   * you: a pinned read deliberately does **not** heal forward, because silently serving a different generation
+   * is the one thing a pin exists to prevent, so it fails instead. Size `keep` to cover your longest pinned
+   * job — see [Generations and `keep`](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/loading.md#generations-and-keep) — or take the pin on a segment
+   * you are not collecting.
+   *
+   * A segment with no current generation pins nothing and reads empty, exactly as it would unpinned. A pinned
+   * segment whose row is later dropped or destroyed fails once it must open its object again, rather than go empty
+   * part-way through a call. **A pin
+   * keeps the key its reader unwrapped for as long as that reader stays open, and answers from the chunks it
+   * decoded for as long as they stay cached.** This store invalidates a pin:
+   *
+   * - a `load`, a `rollback` or an `*Into` invalidates a pin of the segment it writes;
+   * - `dropSegment` invalidates a pin of the segment it drops, and `retireExpired` a pin of each segment its ledger
+   *   lists, retired or not, neither on a dry run;
+   * - `eraseSubject` invalidates a pin of each segment it scans that is not already destroyed.
+   *
+   * An invalidated pin opens its object again, and fails if that object is gone or replaced, or its row is gone or
+   * destroyed.
+   * Anything else leaves the pin as it is: after a `destroySegment` beside this store, or an erasure, a drop or a
+   * retirement through another store, in this process or another, the pin answers from what it holds until this
+   * store's reader cache evicts the pin's reader and its chunk cache evicts the chunks the pin decoded, or
+   * {@link CloudRoaring.invalidate} is called on this store. Where the
+   * object the pin reads has been deleted, by an erasure, a drop or a sweep, a chunk the pin has not cached fails at
+   * once. No timed refresh bounds any of that, as none bounds anything else a pin holds.
+   *
+   * A replacement a pin has found is remembered, so its later chunk reads fail with no request, until the store
+   * forgets it: an invalidation of the segment does, as does a later `pin()` of the same version that opens the object
+   * again, and the store remembers at most `cache.readerMax` of them. So once a restore puts the pinned object back,
+   * call {@link CloudRoaring.invalidate} on this store: the pin then reads the object again.
+   *
+   * `pin()` reads the registry row and opens the generation at once, so the pin knows its object before its first
+   * read. With a registry, pins of one generation taken while its row is unchanged share one reader while the store
+   * keeps it open, pins taken at the same moment included: the first costs a tail read, and a key unwrap for an
+   * encrypted segment, whether or not it is read, and the rest cost the row read alone. Without a registry every
+   * `pin()` lists the segment's objects and makes the tail read, since only the object can tell two incarnations of
+   * a name apart there. It retries a
+   * transient fault as the store's reads do, and heals a generation swept between the two, but it fails where the
+   * generation cannot be opened: `NotFoundError` for a pointer at a missing object, `IntegrityError` for a damaged
+   * or misfiled one.
+   *
+   * Needs a store built on the `.crbm` storage source (the default when you pass a backend or a raw driver). Throws
+   * {@link UnsupportedError} on a store wired with a pre-built source that cannot pin.
+   */
+  async pin() {
+    return this.pinned(this.ref, this.expiresAt);
+  }
+  /**
+   * An opaque string that names this handle's segment, namespace included: two handles of one segment have the
+   * same key, a live handle and its pins among them. Use it as a `Map` key or a log field when you track handles
+   * and have not kept the name you made them with. The format is not specified and is not a storage key, so
+   * compare keys, never parse one.
+   */
+  key() {
+    return segmentKey(this.ref);
+  }
+  /**
+   * Has this handle's deadline passed? **The lazy half of expiry** — the whole check is one comparison against
+   * the injected clock, so it costs nothing on a handle with no deadline and no I/O on one that has expired.
+   *
+   * Deliberately evaluated per call rather than cached: a long-lived handle created before its deadline must
+   * start reading empty the moment the deadline passes, without the caller re-creating it.
+   */
+  expired() {
+    return this.expiresAt !== void 0 && this.clock.now() >= this.expiresAt;
+  }
+  /**
+   * Refuse a materialisation that involves an **expired** handle. Called by the three `*Into` verbs only.
+   *
+   * On the read verbs an expired handle answers empty, which is the point of lazy expiry. On a *write* the same
+   * rule would be destructive in a way nobody asks for: `a.intersectInto(dest, [b])` where `b`'s deadline has
+   * quietly passed would, unrefused, replace `dest` with an **empty generation** — a wipe, reported as a successful
+   * write, with the cause (a deadline on a handle somewhere) nowhere in the result. Reads degrade to empty; writes must not.
+   *
+   * So every handle in the call is checked, `dest` included: an expired `dest` does not change the bytes written,
+   * but a caller who put a deadline on the thing they are writing into has said something contradictory and is
+   * better told than guessed at. Open a handle without `expiresAt` to write, or drop the deadline.
+   *
+   * (The broader guard — refusing to publish an empty or implausible generation over a non-empty one, with an
+   * `allowEmpty` override — covers these verbs too: they route through the same guarded write path as
+   * {@link CloudRoaring.load}. The two stay separate because they differ in kind. That one is a REPORTED
+   * refusal a caller may legitimately override; an expired handle is a wiring mistake, so it THROWS, before
+   * any object is written — and `allowEmpty: true` does not reach it.)
+   *
+   * The verbs are `async` so this surfaces as a **rejected promise**, like every other validation in the facade —
+   * a synchronous throw out of a promise-returning method escapes a caller who attached `.catch()` instead of
+   * awaiting.
+   */
+  refuseIfExpired(op, dest, operands) {
+    const stale = [];
+    for (const seg of [this, dest, ...operands]) {
+      if (seg.expired())
+        stale.push(seg.ref.namespace ? `${seg.ref.namespace}/${seg.ref.segment}` : seg.ref.segment);
+    }
+    if (stale.length > 0) {
+      throw new ValidationError2(
+        `${op}: refusing to publish a generation while these handles have expired \u2014 ${[...new Set(stale)].join(", ")}. An expired handle reads as empty, so this would write an empty (or short) generation over "${dest.ref.segment}". Open the handles without \`expiresAt\` if you meant to materialise, or drop the deadline.`
+      );
+    }
+  }
+  /**
+   * 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) });
+    }
+  }
+  /** Membership: one chunk — the cache, else one ranged GET. Throws {@link ValidationError} on a bad id. */
+  has(id) {
+    if (this.expired()) return Promise.resolve(false);
+    return this.timed("has", () => this.engine.has(this.ref, id));
+  }
+  /**
+   * Cardinality — summed from the `.crbm` index with **zero payload reads** on a loaded segment.
+   *
+   * What this trusts: the answer is the sum of the per-chunk cardinalities the index records, and no payload is
+   * decoded to confirm it. The index is checked for internal consistency when the object is opened (each key in
+   * range and ascending, each cardinality in `1..65536`, each payload inside the payload region, and, on an
+   * unencrypted object, the footer's chunk count and total agreeing with the index), and a corrupt index that is
+   * still internally consistent yields a wrong count. `iterate()` and the combines decode the payloads, whose
+   * structure is checked.
+   */
+  count() {
+    if (this.expired()) return Promise.resolve(0);
+    return this.timed("count", () => this.engine.count(this.ref));
+  }
+  /**
+   * Every id, ascending, streamed one chunk at a time. Pass a range to read part of the segment: the ids in
+   * `(after, through]`, fetching only the chunks the range overlaps. The per-op budget is charged for every chunk in
+   * the range, so give a page `through` as well as `after`. On a pinned handle it reads the pinned generation, as a
+   * full read does.
+   *
+   * ```ts
+   * // Keyset paging: each page resumes where the one before ended, and stops at its window's end.
+   * for await (const id of seg.iterate({ after: previousEnd, through: windowEnd })) await send(id);
+   * ```
+   *
+   * Each bound is optional and an integer in `0..4294967295`; a bad one throws {@link ValidationError} when the
+   * stream is first read. `after >= through` is an empty range, which reads nothing. An expired handle reads empty
+   * without checking its options, as every read of one does.
+   */
+  iterate(options) {
+    if (this.expired()) return EMPTY_IDS;
+    const range = options == null ? void 0 : rangeOf(options);
+    const none = range === void 0 || range.after === void 0 && range.through === void 0;
+    return this.engine.iterate(this.ref, none ? void 0 : range);
+  }
+  /**
+   * The options a combine hands the engine, read once, when it is called ({@link readOptions}), with the `exclude`
+   * it was given, already reduced to its live handles ({@link liveExcludes}) and mapped 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.
+   *
+   * Each field is named rather than copied with a rest spread: a rest copy takes only own enumerable properties, so
+   * a bound held in a getter or inherited from a prototype was dropped, and the read silently widened to the whole
+   * segment.
+   */
+  refsIn(options, exclude) {
+    if (options == null) return void 0;
+    return {
+      ...readOptions(options),
+      exclude: exclude.length > 0 ? exclude.map((o) => o.ref) : void 0
+    };
+  }
+  /**
+   * The handles in `options.exclude` that have not expired. **An expired exclusion excludes nothing**, in every
+   * combine, so it is dropped here, before the engine is asked for anything: it is never fetched, never
+   * checked for absence, and never counted in the pin-consistency check. `exclude` is read once, so a getter sees
+   * one call.
+   *
+   * With no `exclude` this is one property read and a shared empty list, and with none expired it returns the
+   * caller's own array, so the common case allocates nothing.
+   */
+  liveExcludes(options) {
+    const exclude = options?.exclude;
+    if (exclude == null || exclude.length === 0) return NO_SEGMENTS;
+    return exclude.some((e) => e.expired()) ? exclude.filter((e) => !e.expired()) : exclude;
+  }
+  /**
+   * Chunk-skipping intersection: stream the ids in **this** segment AND every segment in `others`, ascending.
+   * Fetches only the Storage chunks present in *all* operands (a key absent from any operand contributes nothing
+   * and is never downloaded), streaming under a bounded in-flight window — so the Storage footprint stays small
+   * (Lambda-friendly) regardless of segment size. Pass `concurrency` to tune that window (a positive integer).
+   * AND is commutative, so `a.intersect([b])` and `b.intersect([a])` yield the same ids. Pass `budget` to
+   * override the store's per-op denial-of-wallet budget for this call (or `false` to lift it).
+   */
+  intersect(others, options) {
+    if (this.expired() || others.some((o) => o.expired())) return EMPTY_IDS;
+    const exclude = this.liveExcludes(options);
+    let engine;
+    try {
+      engine = this.combineEngine([this, ...others, ...exclude]) ?? this.engine;
+    } catch (err) {
+      return failing(err);
+    }
+    return engine.intersect([this.ref, ...others.map((o) => o.ref)], this.refsIn(options, exclude));
+  }
+  /**
+   * Materialize `this ∩ others…` (minus `exclude`) as a **new generation of `dest`** — `dest`'s previous contents
+   * are superseded, not added to. Streaming + bounded-memory; the result is one immutable object published
+   * as a load is (the pointer advances to it, fenced on the row), so readers of `dest` see either the old generation
+   * or the new one, never a partial. Needs the
+   * store built with a backend (throws {@link UnsupportedError} otherwise).
+   *
+   * **An empty result does NOT overwrite a non-empty destination.** A combine that comes out empty is far more
+   * often a mistake upstream — a typo'd operand, an `exclude` that swallowed everything, an operand that has
+   * not loaded yet — than an intent, and once it publishes it is indistinguishable from a correct run. So the
+   * write is **refused and reported**: `published: false`, `reason: 'empty'`, and `dest` keeps what it had.
+   * Pass `allowEmpty: true` when emptying the destination is the point.
+   *
+   * `guard` adds the same plausibility bounds `load()` takes — `minCardinality` and `minRetained` — judged
+   * against what `dest` held before. A refusal is **reported, not thrown**, exactly as on `load()`; branch on
+   * `published`. A lost race is the one outcome that still throws ({@link WriteConflictError}), because a
+   * materialisation that silently did not take effect is the one thing a caller cannot detect on its own.
+   *
+   * A call involving an **expired handle** is refused before any of this. See {@link refuseIfExpired}.
+   */
+  async intersectInto(dest, others, options) {
+    this.refuseIfExpired("intersectInto", dest, [...others, ...options?.exclude ?? []]);
+    this.combineEngine([this, ...others, ...options?.exclude ?? []]);
+    return this.timed(
+      "intersectInto",
+      () => this.materialize(dest.ref, this.intersect(others, options), "intersectInto", 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 load) is the cheaper shape.
+   */
+  union(others, options) {
+    const live = others.filter((o) => !o.expired());
+    if (this.expired()) {
+      if (live.length === 0) return EMPTY_IDS;
+      return live[0].union(live.slice(1), options);
+    }
+    if (live.length === 0 && others.length > 0) {
+      const exclude2 = this.liveExcludes(options);
+      return exclude2.length > 0 ? this.andNot([...exclude2], options) : this.union([], options);
+    }
+    if (live.length !== others.length) return this.union(live, options);
+    const exclude = this.liveExcludes(options);
+    let engine;
+    try {
+      engine = this.combineEngine([this, ...others, ...exclude]) ?? this.engine;
+    } catch (err) {
+      return failing(err);
+    }
+    return engine.union([this.ref, ...others.map((o) => o.ref)], this.refsIn(options, exclude));
+  }
+  /** Materialize `this ∪ others…` (minus `exclude`) as a **new generation of `dest`** — see {@link intersectInto}. */
+  async unionInto(dest, others, options) {
+    this.refuseIfExpired("unionInto", dest, [...others, ...options?.exclude ?? []]);
+    this.combineEngine([this, ...others, ...options?.exclude ?? []]);
+    return this.timed(
+      "unionInto",
+      () => this.materialize(dest.ref, this.union(others, options), "unionInto", 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.
+   *
+   * An expired handle in `excludes` excludes nothing, and is skipped without being read; if every one has
+   * expired the result is `this` whole. An expired `this` is empty. `exclude` on `intersect` and `union` follows
+   * the same rule.
+   *
+   * 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) {
+    if (this.expired()) return EMPTY_IDS;
+    const liveExcludes = excludes.filter((e) => !e.expired());
+    if (liveExcludes.length === 0 && excludes.length > 0) {
+      return this.union([], options == null ? void 0 : readOptions(options));
+    }
+    if (liveExcludes.length !== excludes.length) return this.andNot(liveExcludes, options);
+    let engine;
+    try {
+      engine = this.combineEngine([this, ...excludes]) ?? this.engine;
+    } catch (err) {
+      return failing(err);
+    }
+    return engine.andNot(
+      this.ref,
+      excludes.map((o) => o.ref),
+      options == null ? void 0 : readOptions(options)
+    );
+  }
+  /** Materialize `this \ (excludes…)` as a **new generation of `dest`** — see {@link intersectInto}. */
+  async andNotInto(dest, excludes, options) {
+    this.refuseIfExpired("andNotInto", dest, excludes);
+    this.combineEngine([this, ...excludes]);
+    return this.timed(
+      "andNotInto",
+      () => this.materialize(dest.ref, this.andNot(excludes, options), "andNotInto", options)
+    );
+  }
+  /**
+   * Grounded cost report for this segment: storage cost from its **real** `.crbm` size (exact, no payload
+   * reads); request cost from the supplied `workload` rates. A segment with no Storage generation reports zero
+   * storage. The pointer refresh is priced at the store's own `cache.genTtlMs`, or at none when the store never
+   * refreshes, unless the workload sets `genTtlMs`. See {@link CostReport} — it always includes a verdict (incl.
+   * the lose-zone).
+   */
+  async costReport(options) {
+    const canMeasure = this.engine.supportsStorageSize;
+    const size = canMeasure ? await this.engine.segmentSize(this.ref) : null;
+    const refreshMs = this.engine.pointerRefreshMs;
+    const workload = refreshMs === void 0 || options?.workload?.genTtlMs !== void 0 ? options?.workload : { ...options?.workload, genTtlMs: refreshMs };
+    return groundedReport({
+      storageBytes: size?.sizeBytes ?? 0,
+      grounded: canMeasure,
+      workload,
+      pricing: options?.pricing,
+      extraNotes: canMeasure ? void 0 : ["storage source has no sizeOf() \u2014 storage not measured, reported as $0."]
+    });
+  }
+};
+
+// src/bin/export-segments.ts
 function parseConfig(env) {
   const root = env.CR_EXPORT_ROOT;
   if (root === void 0 || root === "") {
@@ -30,14 +1966,14 @@ function parseConfig(env) {
     throw new Error(`CR_EXPORT_FORMAT must be "roaring" or "ndjson"; got ${format}`);
   }
   const namespace = env.CR_EXPORT_NAMESPACE || void 0;
-  return { root, out, format, namespace, segments: parseSegments(env.CR_EXPORT_SEGMENTS) };
+  return { root, out, format, namespace };
 }
 function fsSink(out) {
   return {
     async open(ref, ext) {
-      const dir = join(out, ref.namespace ?? "_default");
+      const dir = join(out, namespacePathPart(ref.namespace));
       await mkdir(dir, { recursive: true, mode: 448 });
-      const finalPath = join(dir, `${ref.segment}${ext}`);
+      const finalPath = join(dir, `${encodeNameForPath(ref.segment)}${ext}`);
       const tmpPath = `${finalPath}.${randomUUID()}.part`;
       const handle = await open(tmpPath, "wx", 384);
       return {
@@ -73,16 +2009,11 @@ var log = (obj) => {
 };
 async function main(env = process.env, now = () => Date.now()) {
   const config = parseConfig(env);
-  const registry = new src_exports.LocalFsRegistryDriver(join(config.root, "registry"));
-  const store = new CloudRoaring({
-    cold: new src_exports.LocalFsColdDriver(join(config.root, "cold")),
-    warm: new src_exports.LocalFsWarmDriver(join(config.root, "warm")),
-    registry
-  });
+  const storage = new LocalFsStorage(config.root);
+  const store = new CloudRoaring({ storage });
   const manifest = await store.exportSegments(fsSink(config.out), {
     format: config.format,
-    namespace: config.namespace,
-    candidates: config.segments
+    namespace: config.namespace
   });
   await mkdir(config.out, { recursive: true, mode: 448 });
   const manifestPath = join(config.out, "manifest.json");
@@ -110,7 +2041,16 @@ async function main(env = process.env, now = () => Date.now()) {
   });
   return manifest;
 }
-if (process.argv[1] !== void 0 && import.meta.url === pathToFileURL(process.argv[1]).href) {
+function invokedAsCli() {
+  const entry = process.argv[1];
+  if (entry === void 0) return false;
+  try {
+    return import.meta.url === pathToFileURL(entry).href || import.meta.url === pathToFileURL(realpathSync(entry)).href;
+  } catch {
+    return false;
+  }
+}
+if (invokedAsCli()) {
   main().then((manifest) => {
     if (manifest.failed.length > 0) {
       process.stderr.write(
@@ -125,7 +2065,9 @@ if (process.argv[1] !== void 0 && import.meta.url === pathToFileURL(process.argv
     process.exit(1);
   });
 }
-
-export { fsSink, main, parseConfig };
+export {
+  fsSink,
+  main,
+  parseConfig
+};
 //# sourceMappingURL=export-segments.js.map
-//# sourceMappingURL=export-segments.js.map