@cloudbitmaps/roaring 0.9.0 → 0.10.0

package/dist/bin/export-segments.js

@@ -1,21 +1,1493 @@
 #!/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';
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
 
-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";
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  CloudRoaring: () => CloudRoaring,
+  SafeBitmap: () => SafeBitmap,
+  Segment: () => Segment,
+  VERSION: () => VERSION,
+  bulkLoadCrbmGeneration: () => bulkLoadCrbmGeneration,
+  eraseIdFromSegment: () => eraseIdFromSegment,
+  loadSegment: () => loadSegment,
+  roaringCodec: () => roaringCodec,
+  runExport: () => runExport
+});
+import {
+  BoundedLru,
+  PinnedStorageChunkSource,
+  segmentKey,
+  CrbmStorageChunkSource,
+  DEFAULT_BUDGET,
+  DEFAULT_RETRY_POLICY,
+  isStorageBackend,
+  NOOP_METRICS,
+  RetryingStorageChunkSource,
+  SegmentEngine,
+  UnsupportedError,
+  ValidationError,
+  WriteConflictError,
+  MIN_EXPIRES_AT_MS,
+  collectWithinBudget,
+  excludingReservedRows,
+  dropSegment,
+  estimateCost,
+  groundedReport,
+  mapWithConcurrency,
+  resolveBudget,
+  resolvePerOpBudget,
+  retireExpired,
+  runConsistencyCheck,
+  runExport as runExport2,
+  setSegmentRetention,
+  clearSegmentRetention,
+  getSegmentRetention,
+  safeMetrics,
+  splitId,
+  validateSegmentRef
+} from "@cloudbitmaps/core";
+
+// src/codec-bound.ts
+import {
+  bulkLoadCrbmGeneration as coreBulkLoad,
+  eraseIdFromSegment as coreEraseIdFromSegment,
+  loadSegment as coreLoadSegment,
+  runExport as coreRunExport
+} from "@cloudbitmaps/core";
+
+// src/roaring-codec.ts
+import roaring from "roaring";
+import { IntegrityError } from "@cloudbitmaps/core";
+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));
+  }
+  /**
+   * Validate size, then deserialize with the **portable** (validated) format.
+   * Throws `IntegrityError` if the input exceeds `maxBytes` or fails to decode — the
+   * native addon is never handed unbounded or unsafe-format input.
+   */
+  static safeDeserialize(bytes, maxBytes) {
+    if (bytes.length > maxBytes) {
+      throw new IntegrityError(`serialized bitmap is ${bytes.length}B, exceeds cap ${maxBytes}B`);
+    }
+    try {
+      return new _SafeBitmap(RoaringBitmap32.deserialize(bytes, DeserializationFormat.portable));
+    } catch (err) {
+      throw new IntegrityError(`failed to deserialize bitmap: ${err.message}`);
+    }
+  }
+  serialize() {
+    return this.bitmap.serialize(SerializationFormat.portable);
+  }
+  /**
+   * Convert containers to run-encoding where that is smaller. Representation only — membership is untouched, and
+   * the portable format still round-trips through {@link RoaringCodec.safeDeserialize}.
+   *
+   * Roaring's third container type is a RUN, and no implementation selects it on its own: it takes an explicit
+   * `runOptimize()` pass. Nothing here made that call, so run-shaped ids paid array or bitset prices — measured
+   * at **570×** for a contiguous 1M-id range (128.1 KiB → 0.2 KiB) and **63×** for a 2,000-run shape
+   * (536.5 KiB → 8.5 KiB). Sparse ids come out byte-identical, so this is never a losing trade; roaring keeps
+   * whichever encoding is smaller per container.
+   *
+   * Those two factors are THIS CALL's own before/after on the same ids. They are not the ones the site quotes
+   * (543× and 63×) — those compare the optimized encoding against the best *fixed* representation at its floor,
+   * a different baseline that happens to land near 63× on the run shape too. `pnpm bench:encoding` prints both
+   * columns; don't carry a figure between them without checking which denominator it had.
+   *
+   * Called 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 container index, so the engine's
+   * per-chunk range assertion costs one call per chunk rather than a walk per id.
+   */
+  maximum() {
+    return this.bitmap.isEmpty ? void 0 : this.bitmap.maximum();
+  }
+  add(value) {
+    this.bitmap.add(value);
+  }
+  addMany(values) {
+    this.bitmap.addMany(values);
+  }
+  remove(value) {
+    this.bitmap.remove(value);
+  }
+  removeMany(values) {
+    this.bitmap.removeMany(values);
+  }
+  has(value) {
+    return this.bitmap.has(value);
+  }
+  get size() {
+    return this.bitmap.size;
+  }
+  get isEmpty() {
+    return this.bitmap.isEmpty;
+  }
+  clone() {
+    return new _SafeBitmap(this.bitmap.clone());
+  }
+  // The binary set ops take the `CodecBitmap` interface type (per the seam), but a single store is
+  // single-codec (homogeneity contract), so `other` is always a `SafeBitmap` here — reach its private
+  // `bitmap` (accessible on same-class instances) for the native op.
+  /** In-place union: `this = this ∪ other`. */
+  orInPlace(other) {
+    this.bitmap.orInPlace(other.bitmap);
+  }
+  /** In-place difference: `this = this \ other`. */
+  andNotInPlace(other) {
+    this.bitmap.andNotInPlace(other.bitmap);
+  }
+  /** In-place intersection: `this = this ∩ other`. */
+  andInPlace(other) {
+    this.bitmap.andInPlace(other.bitmap);
+  }
+  /** Ascending iterator over the set values. */
+  [Symbol.iterator]() {
+    return this.bitmap[Symbol.iterator]();
+  }
+  toArray() {
+    return this.bitmap.toArray();
+  }
+};
+var roaringCodec = {
+  empty: () => SafeBitmap.empty(),
+  fromValues: (values) => SafeBitmap.fromValues(values),
+  safeDeserialize: (bytes, maxBytes) => SafeBitmap.safeDeserialize(bytes, maxBytes)
+};
+
+// src/system-clock.ts
+var SystemClock = class {
+  now() {
+    return Date.now();
+  }
+  sleep(ms) {
+    if (ms <= 0) return Promise.resolve();
+    return new Promise((resolve) => {
+      setTimeout(resolve, ms);
+    });
+  }
+  /**
+   * `setImmediate`, and it has to be — this is the one place where the choice of primitive is the whole feature.
+   *
+   * A long CPU-bound loop in `core/` (bulk-load is the one that matters) periodically hands the loop back so a
+   * co-resident HTTP server keeps answering. Measured on the **synthetic yield-primitive benchmark** — a
+   * 61,035-iteration loop yielding every 1,024, isolating the primitive rather than timing a real load (the
+   * end-to-end figures are 450 ms → 19 ms; see `cooperative.ts`, which lists all three experiments):
+   *
+   * ```text
+   *   no yield         568 ms wall   568.0 ms worst event-loop gap
+   *   sleep(0)         555 ms wall   555.2 ms   ← a microtask. Yields NOTHING.
+   *   setImmediate     569 ms wall    13.8 ms   ← free, and 41x less starvation
+   *   setTimeout(1)    625 ms wall    15.0 ms   ← +10% wall for no extra relief
+   * ```
+   *
+   * `sleep(0)` resolving on a microtask is correct for its own contract and useless for this: microtasks drain
+   * before the loop ever advances a phase, so `await sleep(0)` in a tight loop never lets a single pending I/O
+   * callback run. `setImmediate` fires in the check phase *after* pending I/O, which is exactly the ordering a
+   * server wants — inbound requests are serviced before the loop resumes chewing.
+   *
+   * A timer is not ref'd here (unlike {@link sleep}): a yield expresses "someone else may go first", never
+   * "there is outstanding work" — and `setImmediate` cannot outlive the turn that scheduled it anyway.
+   */
+  yieldNow() {
+    return new Promise((resolve) => {
+      setImmediate(resolve);
+    });
+  }
+};
+
+// src/codec-bound.ts
+var bulkLoadCrbmGeneration = (driver, key, ids, options = {}) => coreBulkLoad(driver, key, ids, {
+  ...options,
+  codec: options.codec ?? roaringCodec,
+  clock: options.clock ?? new SystemClock()
+});
+var eraseIdFromSegment = (ref, id, deps, options) => coreEraseIdFromSegment(
+  ref,
+  id,
+  { ...deps, codec: deps.codec ?? roaringCodec, clock: deps.clock ?? new SystemClock() },
+  options
+);
+var runExport = (reader, registry, sink, options = {}) => coreRunExport(reader, registry, sink, { ...options, codec: options.codec ?? roaringCodec });
+var loadSegment = (ref, ids, deps, options = {}) => coreLoadSegment(
+  ref,
+  ids,
+  { ...deps, codec: deps.codec ?? roaringCodec, clock: deps.clock ?? new SystemClock() },
+  options
+);
+
+// src/index.ts
+import { listGenerations, rollbackSegment } from "@cloudbitmaps/core";
+import { listSegments, segmentExists } from "@cloudbitmaps/core";
+
+// src/moved-options.ts
+var MOVED_OPTIONS = [
+  ["cacheMaxChunks", "cache.maxChunks", "group"],
+  ["cacheTtlMs", "cache.ttlMs", "group"],
+  // The `cold*` spellings are what `0.9.x` ACTUALLY had. The `storage*` ones below never appeared in any
+  // release — they existed between two unreleased commits of this cycle — and for a while they were the only
+  // ones here, so the guard written to catch an upgrader missed every real upgrader and caught nobody.
+  ["coldGenTtlMs", "cache.genTtlMs", "group"],
+  ["coldReaderCacheMax", "cache.readerMax", "group"],
+  ["coldReaderCacheMaxBytes", "cache.readerMaxBytes", "group"],
+  ["storageGenTtlMs", "cache.genTtlMs", "group"],
+  ["storageReaderCacheMax", "cache.readerMax", "group"],
+  ["storageReaderCacheMaxBytes", "cache.readerMaxBytes", "group"],
+  ["keystore", "encryption.keystore", "group"],
+  ["requireEncryption", "encryption.required", "group"],
+  ["onRetry", "retry.onRetry", "group"],
+  ["clock", "seams.clock", "group"],
+  ["rng", "seams.rng", "group"],
+  [
+    "registry",
+    "the backend passed as `storage` (S3Storage, GcsStorage, \u2026), which carries it",
+    "renamed"
+  ],
+  ["cold", "storage", "renamed"],
+  // The live (warm) tier and its knobs. `warm` was REQUIRED in `0.9.x`, so every upgrader passes one — and
+  // an upgrader who fixes `cold` first meets this next. None has a successor, so none is offered.
+  ["warm", "the live tier is gone", "gone"],
+  ["warmReadConsistency", "it tuned the live tier", "gone"],
+  ["maxWarmScanBytes", "it tuned the live tier", "gone"],
+  ["writeConcurrency", "it bounded the live tier\u2019s flusher", "gone"],
+  ["occBackoff", "it tuned the live tier\u2019s read-modify-write", "gone"]
+];
+
+// src/index.ts
+__reExport(src_exports, core_star);
+import * as core_star 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 ValidationError(`concurrency must be a positive integer; got ${concurrency}`);
+  }
+}
+function requireScope(options, op) {
+  if (options.namespace === void 0 && options.allNamespaces !== true) {
+    throw new ValidationError(
+      `${op} scans the global id space across all namespaces \u2014 pass an explicit \`namespace\`, or \`{ allNamespaces: true }\` to intentionally sweep the whole fleet`
+    );
+  }
+}
+function resolveStorageSource(options, clock) {
+  const storage = options.storage;
+  if (storage === null || typeof storage !== "object") {
+    throw new ValidationError(
+      "`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 ValidationError(
+      `\`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 ValidationError(
+      "`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, say so: `createBackend({ storage: <your driver>, registry })`."
+    );
+  }
+  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 ValidationError(
+        "`storage` looks like a backend but its " + bad + " \u2014 build one with a backend class, or with `createBackend({ storage, registry })`."
+      );
+    }
+    throw new ValidationError(
+      "`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. If you genuinely want halves of your own \u2014 an instrumented driver, a registry in a database you already run \u2014 say so with `createBackend({ storage, registry })`, which is you 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 ValidationError(
+      "`storage` exposes both `getChunk` and `putImmutable` \u2014 ambiguous; pass a StorageBackend, an IStorageDriver, or a StorageChunkSource, not a hybrid"
+    );
+  }
+  if (!hasGetChunk && !hasPutImmutable) {
+    throw new ValidationError(
+      "`storage` must be a StorageBackend, an IStorageDriver, or a StorageChunkSource"
+    );
+  }
+  if (hasGetChunk) {
+    if (options.encryption?.keystore !== void 0 || options.encryption?.required === true) {
+      throw new ValidationError(
+        "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 CloudRoaring = class _CloudRoaring {
+  engine;
+  cache;
+  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 an option that moved into a group, naming where it went.
+   *
+   * Silently ignoring one would be the exact failure this release exists to remove — see {@link MOVED_OPTIONS}
+   * for why each of these is unsafe to drop rather than merely untidy.
+   */
+  static rejectMovedOptions(options) {
+    if (options === null || options === void 0 || typeof options !== "object") {
+      throw new ValidationError(
+        "CloudRoaring needs an options object with a `storage` key \u2014 got " + (options === null ? "null" : typeof options)
+      );
+    }
+    const bag = options;
+    const moved = MOVED_OPTIONS.filter(([from]) => bag[from] !== void 0);
+    if (moved.length === 0) return;
+    const clause = (kind, one, many) => {
+      const hits = moved.filter(([, , k]) => k === kind);
+      if (hits.length === 0) return null;
+      const body = hits.map(
+        ([from, to]) => kind === "gone" ? `\`${from}\` (${to})` : `\`${from}\` \u2192 ${/^[\w.]+$/.test(to) ? `\`${to}\`` : to}`
+      ).join(" \xB7 ");
+      return `${hits.length > 1 ? many : one}: ${body}`;
+    };
+    const parts = [
+      clause("group", "option moved into a group", "options moved into groups"),
+      clause("renamed", "option renamed", "options renamed"),
+      clause("gone", "option removed", "options removed")
+    ].filter((c) => c !== null);
+    throw new ValidationError(
+      `CloudRoaring ${parts.join("; ")}. Options are now one required \`storage\` plus four optional groups \u2014 \`cache\`, \`encryption\`, \`retry\` and \`seams\`. \`metrics\` and \`budget\` are unchanged flat options; leave them as they are. Full guide: https://github.com/cloudbitmaps/cloudbitmaps/blob/main/MIGRATING.md`
+    );
+  }
+  constructor(options) {
+    _CloudRoaring.rejectMovedOptions(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.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.
+   * Out-of-process callers use the free functions with explicit deps.
+   */
+  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. Out of process, call the equivalent free function with explicit deps instead.`
+      );
+    }
+    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 longer a separate \`registry\` option to add.`
+      );
+    }
+    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);
+    const expiresAt = options?.expiresAt;
+    if (expiresAt !== void 0) {
+      if (!Number.isFinite(expiresAt) || !Number.isInteger(expiresAt) || expiresAt < MIN_EXPIRES_AT_MS) {
+        throw new ValidationError(
+          `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 new Segment(
+      this.engine,
+      ref,
+      this.clock,
+      this.metrics,
+      (dest, ids, op, options2) => this.materialize(dest, ids, op, options2),
+      (r, e) => this.pinSegment(r, e),
+      (handles) => this.engineForCombine(handles),
+      expiresAt
+    );
+  }
+  /**
+   * Write `ids` as a **new generation of `dest`** and publish it forward-only — the shared body of the `*Into`
+   * verbs. 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 (on the pointer it
+   * judged, on the row's identity, and — where it judged an ABSENT segment — on that absence), and a refused
+   * object is reclaimed only after re-reading the row and finding the same incarnation (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. `gcOrphanGenerations` carries
+   * the same residual and says so. The failure it leaves is an orphan object, which costs storage until
+   * something collects it — deliberately the cheaper side of the trade.
+   *
+   * Materialising used to do none of that. It wrote and published in one step, so an empty combine — a typo'd
+   * operand, an `exclude` that swallowed everything, an operand that had not loaded yet — silently replaced
+   * `dest` with an empty generation. That is the same failure `load()`'s guard exists to prevent, on the same
+   * data, and it was reachable without passing any option at all.
+   *
+   * **A lost race still throws.** `loadSegment` reports one as `reason: 'superseded'`; the `*Into` verbs have
+   * always thrown {@link WriteConflictError} for it, and a caller who wrote `catch (WriteConflictError)` must
+   * keep working. So that one refusal is translated back 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 four different causes — the write-once PUT collided,
+   * the pointer moved, the row's token changed, the row was purged — and only the first two 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 it still collects nothing**, unlike `load()`. See the `keep` default below.
+   */
+  async materialize(dest, ids, op, options) {
+    const deps = this.lifecycleDeps(op);
+    const 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. A materialisation has never collected: the guide states "**It deletes nothing.** The
+      // destination's previous generation stays in the bucket until you collect it", and the ownership table
+      // puts that call on the operator. Inheriting `load()`'s collection would have silently deleted 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 }
+    });
+    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 register the
+   * registry 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. Requires a
+   * `registry` in the store config (throws {@link UnsupportedError} otherwise).
+   */
+  async subjectReport(id, options = {}) {
+    const registry = this.requireRegistry("subjectReport");
+    requireScope(options, "subjectReport");
+    validateConcurrency(options.concurrency);
+    const budget = resolvePerOpBudget(options.budget, this.budget);
+    splitId(id);
+    const recs = await collectWithinBudget(
+      // A subject cannot be in a coordination 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 };
+        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. 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 — use the `eraseIdFromSegment` free function there).
+   *
+   * **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** — `publishGeneration`'s `expectFrom`, which lands the CAS 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: `nextGeneration` numbers 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 a reason rather than
+   * an error, read off the row: a moved pointer is `'superseded'`, a concurrent `dropSegment` `'destroyed'`,
+   * a retention sweep that purged the row `'absent'`. Re-running is the fix in every case.
+   *
+   * **Read `note` on any `erased: false` entry — the two reasons mean different things.** `'superseded'` means
+   * another writer (a load, or another erasure) moved the pointer mid-rewrite, 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. A re-run
+   * then reports nothing for that segment (the id is not in the current generation), so **that residual is
+   * collected by `gcOrphanGenerations(ref, deps, { keep: 0 })` or the next retention sweep**, not by another
+   * `eraseSubject`. Re-running is otherwise safe and idempotent: a segment the id is no longer in is not listed. Admin-only path;
+   * `O(registered segments)`, no hot-path cost. Per-subject crypto-shred is infeasible (a subject's bit is
+   * co-mingled in a shared container), so this is the single-subject erasure route; whole-segment/tenant erasure
+   * is `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"
+    );
+    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, deps, { 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 `list` call; 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 `registry`.
+   *
+   * ```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 — except behind a driver that buffers its
+   * enumeration to retry it as a unit, which `RetryingRegistryDriver` does: wrapped in that, the whole scan is
+   * paid for and resident before the first row arrives.
+   *
+   * 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 `registry`.
+   *
+   * ```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 });
+    }
+    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, so they remain until a later load raises the
+   * pointer past them. An operator who has just undone a bad load should not have the evidence collected out from
+   * under them.
+   *
+   * 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('audience:active', idsFromWarehouse, {
+   *   guard: { maxShrink: 0.5 },   // refuse a load that drops 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.
+   *
+   * The object written for a refused load is deleted again before returning — it sits above `currentGen`, where
+   * generation collection deliberately never looks, so nothing else would reclaim it. The exception is a load
+   * that finds the segment **re-created** underneath it: the generation number it holds may then name the new
+   * incarnation's live object, so it leaves the orphan rather than risk deleting live data.
+   *
+   * Two things it does **throw** for, rather than report: a crypto-shredded segment (`ValidationError` — there
+   * is no key to write under), and a collection pass that could not prove the segment was still the same one
+   * (`WriteConflictError`). The second 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. A reader that never
+   * touched it sees empty at once. **That bound needs a clock and `cache.genTtlMs > 0`** — a store built without a
+   * clock, or with `cache.genTtlMs: 0` ("pin forever"), holds its resolved snapshot for its own lifetime and can
+   * keep answering `true` for a dropped segment indefinitely; restart it.
+   *
+   * Needs the store built with a **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 `registry`
+   * in the store config (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.retired} of ${preview.scanned} (limited: ${preview.limited})`);
+   *
+   * const swept = await store.retireExpired({ namespace: 'active-daily' });
+   * for (const e of swept.entries) {
+   *   if (e.action === 'skipped') console.warn(`${e.segment}: ${e.reason}`); // invalid-policy / limit / failed: …
+   *   if (e.action === 'retired' && e.result.generationsRemaining.length > 0) {
+   *     console.warn(`${e.segment}: storage not fully reclaimed — re-run`);
+   *   }
+   * }
+   * if (swept.limited) scheduleAnotherPassSoon(); // more are still eligible
+   * ```
+   *
+   * **Read the ledger.** A per-segment *fault* is an entry, not an exception — a throw from the middle of a fleet
+   * sweep would leave the caller unable to say which segments were retired, having already retired some. (A bad
+   * argument does throw, and so does a fleet larger than `maxScanSegments`.) `limited: true` means the per-cycle
+   * `limit` (default 100) cut the pass short and more are eligible. That cap is charged on **attempts**, not
+   * successes, which is what makes it a real bound: `dropSegment` 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. Pass
+   * `purgeTombstones: false` to keep every tombstone.
+   *
+   * 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 verbs on this class handle themselves — `eraseSubject`, `dropSegment` and `retireExpired` 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 leaves it holding an open reader and an unwrapped
+   *   DEK. Until it is told, it keeps decrypting — including chunks it had never fetched before the shred.
+   * - **Another process.** Erasing on one box invalidates nothing on the others; each store bounds its own
+   *   staleness by `cache.genTtlMs`, and a store built with no clock or `cache.genTtlMs: 0` ("pin forever") never
+   *   converges at all. 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.
+   *
+   * Synchronous, best-effort, and safe to call for a segment this store has never read.
+   *
+   * ```ts
+   * await destroySegment(ref, { storage, registry, keystore }, { confirmSegment: ref.segment });
+   * store.invalidate(ref);                       // this process
+   * await bus.publish('cloudbitmaps.invalidate', ref); // and every other one
+   * ```
+   */
+  invalidate(ref) {
+    validateSegmentRef(ref);
+    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**, which is safe precisely
+   * because the cache is keyed by the source's version rather than the generation number: the pinned view
+   * reports the version captured at pin time, so its decoded chunks cannot collide with the live generation's.
+   * Sharing it on a generation-only key was how a pinned read could resurrect an id already reported
+   * physically gone.
+   */
+  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 crbm.pinGeneration(ref);
+    const pinnedAt = { generation: at?.generation ?? null, version: at?.version ?? null };
+    const pins = /* @__PURE__ */ new Map([[segmentKey(ref), pinnedAt]]);
+    return new Segment(
+      this.engineWithPins(pins),
+      ref,
+      this.clock,
+      this.metrics,
+      (dest, ids, op, options) => this.materialize(dest, ids, op, options),
+      (r, e) => this.pinSegment(r, e),
+      (handles) => this.engineForCombine(handles),
+      expiresAt,
+      pinnedAt
+    );
+  }
+  /**
+   * An engine reading every segment in `pins` at its pinned generation and everything else live.
+   *
+   * It **shares the store's chunk cache**, which is safe only because that cache is keyed by the source's
+   * version rather than the generation number: a pinned view reports the version captured at pin time, so its
+   * decoded chunks cannot collide with the live generation's.
+   */
+  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)"
+      );
+    }
+    return new SegmentEngine({
+      storage: new PinnedStorageChunkSource(crbm, pins),
+      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.
+   */
+  engineForCombine(handles) {
+    const pins = /* @__PURE__ */ new Map();
+    for (const h of handles) {
+      const at = h.pinnedAt;
+      if (at !== void 0) pins.set(h.key(), at);
+    }
+    return pins.size === 0 ? void 0 : this.engineWithPins(pins);
+  }
+  /** 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 longer a separate \`registry\` option to add.`
+      );
+    }
+    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 }` —
+   * `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).
+   */
+  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 runExport2(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 EMPTY_IDS = {
+  async *[Symbol.asyncIterator]() {
+  }
+};
+var KEEP_EVERY_GENERATION = Number.MAX_SAFE_INTEGER;
+var Segment = class {
+  constructor(engine, ref, clock, metrics, materialize, pinned, combineEngine, expiresAt, pinnedAt) {
+    this.engine = engine;
+    this.ref = ref;
+    this.clock = clock;
+    this.metrics = metrics;
+    this.materialize = materialize;
+    this.pinned = pinned;
+    this.combineEngine = combineEngine;
+    this.expiresAt = expiresAt;
+    this.pinnedAt = pinnedAt;
+    this.metricsOn = metrics !== NOOP_METRICS;
+  }
+  engine;
+  ref;
+  clock;
+  metrics;
+  materialize;
+  pinned;
+  combineEngine;
+  expiresAt;
+  pinnedAt;
+  metricsOn;
+  /**
+   * **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.
+   *
+   * **It is a hold, not a lease.** Nothing here stops `gcOrphanGenerations` 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 [Sizing `keep`](../../docs/guide/getting-started.md#sizing-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 pin
+   * taken before a crypto-shred stops reading when the shred lands: the destroyed row is re-checked every time
+   * the pinned reader opens, so a pin cannot outlive the key it was using.
+   *
+   * 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);
+  }
+  /** This handle's segment, as the cache/pin key — `ref` stays private; the encapsulation is worth the method. */
+  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 publishes an **empty generation over `dest`** — 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 — now 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 ValidationError(
+        `${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. */
+  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. */
+  iterate() {
+    if (this.expired()) return EMPTY_IDS;
+    return this.engine.iterate(this.ref);
+  }
+  /**
+   * Map the facade's `Segment` handles in `exclude` down to the plain refs `core` takes. A method rather than
+   * a module function because `ref` is class-private — the encapsulation is worth more than the free function.
+   */
+  refsIn(options) {
+    if (options === void 0) return void 0;
+    const { exclude, ...rest } = options;
+    return exclude === void 0 ? rest : { ...rest, exclude: exclude.map((o) => o.ref) };
+  }
+  /**
+   * 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 engine = this.combineEngine([this, ...others, ...options?.exclude ?? []]) ?? this.engine;
+    return engine.intersect([this.ref, ...others.map((o) => o.ref)], this.refsIn(options));
+  }
+  /**
+   * 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
+   * forward-only, 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 ?? []]);
+    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 exclude = options?.exclude ?? [];
+      return exclude.length > 0 ? this.andNot([...exclude], options) : this.iterate();
+    }
+    if (live.length !== others.length) return this.union(live, options);
+    const engine = this.combineEngine([this, ...others, ...options?.exclude ?? []]) ?? this.engine;
+    return engine.union([this.ref, ...others.map((o) => o.ref)], this.refsIn(options));
+  }
+  /** 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 ?? []]);
+    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.
+   *
+   * 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.iterate();
+    if (liveExcludes.length !== excludes.length) return this.andNot(liveExcludes, options);
+    const engine = this.combineEngine([this, ...excludes]) ?? this.engine;
+    return engine.andNot(
+      this.ref,
+      excludes.map((o) => o.ref),
+      options
+    );
+  }
+  /** Materialize `this \ (excludes…)` as a **new generation of `dest`** — see {@link intersectInto}. */
+  async andNotInto(dest, excludes, options) {
+    this.refuseIfExpired("andNotInto", dest, 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. 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;
+    return groundedReport({
+      storageBytes: size?.sizeBytes ?? 0,
+      grounded: canMeasure,
+      workload: options?.workload,
+      pricing: options?.pricing,
+      extraNotes: canMeasure ? void 0 : ["storage source has no sizeOf() \u2014 storage not measured, reported as $0."]
+    });
+  }
+};
+var VERSION = "0.10.0";
+
+// src/bin/export-segments.ts
 function parseConfig(env) {
   const root = env.CR_EXPORT_ROOT;
   if (root === void 0 || root === "") {
@@ -30,14 +1502,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, (0, src_exports.namespacePathPart)(ref.namespace));
       await mkdir(dir, { recursive: true, mode: 448 });
-      const finalPath = join(dir, `${ref.segment}${ext}`);
+      const finalPath = join(dir, `${(0, src_exports.encodeNameForPath)(ref.segment)}${ext}`);
       const tmpPath = `${finalPath}.${randomUUID()}.part`;
       const handle = await open(tmpPath, "wx", 384);
       return {
@@ -73,16 +1545,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 src_exports.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 +1577,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 +1601,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