@cloudbitmaps/roaring 0.8.2 → 0.10.0

package/dist/index.js

@@ -1,8 +1,49 @@
-import { IntegrityError, bulkLoadCrbmGeneration as bulkLoadCrbmGeneration$1, compactSegment as compactSegment$1, runCompactionCycle as runCompactionCycle$1, runExport as runExport$1, safeMetrics, NOOP_METRICS, BoundedLru, RetryingWarmDriver, RetryingColdChunkSource, ValidationError, resolveBudget, DEFAULT_BUDGET, SegmentEngine, UnsupportedError, validateSegmentRef, resolvePerOpBudget, splitId, collectWithinBudget, mapWithConcurrency, validateCompactionOptions, gcOrphanGenerations, dropSegment, runConsistencyCheck, estimateCost, groundedReport, CrbmColdChunkSource } from '@cloudbitmaps/core';
-export * from '@cloudbitmaps/core';
-import roaring from 'roaring';
-
 // src/index.ts
+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;
@@ -16,7 +57,7 @@ var SafeBitmap = class _SafeBitmap {
     return new _SafeBitmap(new RoaringBitmap32(values));
   }
   /**
-   * S1: validate size, then deserialize with the **portable** (validated) format.
+   * 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.
    */
@@ -48,8 +89,8 @@ var SafeBitmap = class _SafeBitmap {
    * a different baseline that happens to land near 63× on the run shape too. `pnpm bench:encoding` prints both
    * columns; don't carry a figure between them without checking which denominator it had.
    *
-   * Called by the engine only when writing an immutable cold generation — see {@link CodecBitmap.optimize} for
-   * why the per-operation warm path deliberately does not.
+   * Called only when writing an immutable objects generation — see {@link CodecBitmap.optimize} for why the read
+   * path deliberately does not.
    */
   optimize() {
     this.bitmap.runOptimize();
@@ -154,17 +195,68 @@ var SystemClock = class {
     });
   }
 };
-var bulkLoadCrbmGeneration = (driver, key, ids, options = {}) => bulkLoadCrbmGeneration$1(driver, key, ids, {
+
+// 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 compactSegment = (ref, deps, options) => compactSegment$1(ref, { ...deps, codec: deps.codec ?? roaringCodec }, options);
-var runCompactionCycle = (deps, options) => runCompactionCycle$1({ ...deps, codec: deps.codec ?? roaringCodec }, options);
-var runExport = (reader, registry, sink, options = {}) => runExport$1(reader, registry, sink, { ...options, codec: options.codec ?? roaringCodec });
+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
+export * 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();
   }
@@ -183,74 +275,163 @@ function requireScope(options, op) {
     );
   }
 }
-function resolveColdSource(options, clock) {
-  const cold = options.cold;
-  if (cold === null || typeof cold !== "object") {
-    throw new ValidationError("`cold` must be an IColdDriver or a ColdChunkSource");
+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
+    };
   }
-  const hasGetChunk = typeof cold.getChunk === "function";
-  const hasPutImmutable = typeof cold.putImmutable === "function";
   if (hasGetChunk && hasPutImmutable) {
     throw new ValidationError(
-      "`cold` exposes both `getChunk` and `putImmutable` \u2014 ambiguous; pass an IColdDriver or a ColdChunkSource, not a hybrid"
+      "`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("`cold` must be an IColdDriver or a ColdChunkSource");
+    throw new ValidationError(
+      "`storage` must be a StorageBackend, an IStorageDriver, or a StorageChunkSource"
+    );
   }
   if (hasGetChunk) {
-    if (options.registry !== void 0 || options.keystore !== void 0 || options.requireEncryption === true) {
+    if (options.encryption?.keystore !== void 0 || options.encryption?.required === true) {
       throw new ValidationError(
-        "registry/keystore/requireEncryption apply only when `cold` is a raw IColdDriver; configure them on the ColdChunkSource you passed instead"
+        "keystore/requireEncryption apply only when the store builds its own read path; configure them on the StorageChunkSource you passed instead"
       );
     }
-    return { source: cold, driver: void 0 };
+    return { source: storage, driver: void 0, registry: void 0 };
   }
-  const driver = cold;
+  const driver = storage;
   return {
-    source: new CrbmColdChunkSource(driver, {
-      registry: options.registry,
-      keystore: options.keystore,
-      requireEncryption: options.requireEncryption,
+    source: new CrbmStorageChunkSource(driver, {
+      keystore: options.encryption?.keystore,
+      requireEncryption: options.encryption?.required,
       clock,
-      currentGenTtlMs: options.coldGenTtlMs,
-      maxOpenSegments: options.coldReaderCacheMax,
-      maxOpenIndexBytes: options.coldReaderCacheMaxBytes
+      currentGenTtlMs: options.cache?.genTtlMs,
+      maxOpenSegments: options.cache?.readerMax,
+      maxOpenIndexBytes: options.cache?.readerMaxBytes
     }),
-    driver
+    driver,
+    registry: void 0
   };
 }
-var CloudRoaring = class {
+var CloudRoaring = class _CloudRoaring {
   engine;
+  cache;
+  crbmSource;
   clock;
   metrics;
-  // The store's own drivers, kept so the in-process lifecycle helpers (`compact`/`eraseSubject`/`subjectReport`)
-  // reuse them instead of making you re-pass a CompactionDeps. `coldDriver` is set only when `cold` was a raw
-  // IColdDriver (a pre-built ColdChunkSource has no underlying driver to compact through).
-  coldDriver;
-  warmDriver;
+  // 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) {
-    const clock = options.clock ?? new SystemClock();
-    const rng = options.rng ?? new SystemRng();
+    _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.cacheMaxChunks ?? DEFAULT_CACHE_MAX_CHUNKS,
-      ttlMs: options.cacheTtlMs,
+      maxEntries: options.cache?.maxChunks ?? DEFAULT_CACHE_MAX_CHUNKS,
+      ttlMs: options.cache?.ttlMs,
       clock
     });
-    const resolved = resolveColdSource(options, clock);
-    let cold = resolved.source;
-    let warm = options.warm;
+    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: options.retry,
+        policy,
         // Bridge transient-fault retries into the metrics stream, then call the user's own hook.
         onRetry: (info) => {
           metrics.onEvent({
@@ -259,100 +440,171 @@ var CloudRoaring = class {
             attempt: info.attempt,
             delayMs: info.delayMs
           });
-          options.onRetry?.(info);
+          userOnRetry?.(info);
         }
       };
-      warm = new RetryingWarmDriver(options.warm, retryOpts);
-      cold = new RetryingColdChunkSource(cold, retryOpts);
-    }
-    if (options.writeConcurrency !== void 0 && (!Number.isInteger(options.writeConcurrency) || options.writeConcurrency < 1)) {
-      throw new ValidationError(
-        `writeConcurrency must be a positive integer; got ${options.writeConcurrency}`
-      );
+      storage = new RetryingStorageChunkSource(storage, retryOpts);
     }
     this.budget = resolveBudget(options.budget, DEFAULT_BUDGET);
     const deps = {
-      warm,
-      cold,
+      storage,
       cache,
       codec: roaringCodec,
       // the facade injects the flagship codec; core stays codec-agnostic
       clock,
-      rng,
-      occBackoff: options.occBackoff,
       metrics,
-      warmReadConsistency: options.warmReadConsistency,
-      writeConcurrency: options.writeConcurrency,
-      maxWarmScanBytes: options.maxWarmScanBytes,
       budget: this.budget
     };
     this.engine = new SegmentEngine(deps);
+    this.cache = cache;
+    this.crbmSource = resolved.source instanceof CrbmStorageChunkSource ? resolved.source : void 0;
     this.clock = clock;
     this.metrics = metrics;
-    this.coldDriver = resolved.driver;
-    this.warmDriver = options.warm;
-    this.registry = options.registry;
-    this.keystore = options.keystore;
-    this.requireEncryption = options.requireEncryption ?? false;
+    this.storageDriver = resolved.driver;
+    this.registry = resolved.registry;
+    this.keystore = options.encryption?.keystore;
+    this.requireEncryption = options.encryption?.required ?? false;
   }
   /**
-   * Build {@link CompactionDeps} from the store's own drivers, for the in-process lifecycle helpers
-   * ({@link compact} / {@link eraseSubject}). Requires the store to have been constructed with a **raw cold
-   * driver** (a pre-built `ColdChunkSource` has no underlying `IColdDriver` to compact through) and a `registry`
-   * (the authoritative `currentGen` pointer compaction swaps). Out-of-process callers use the `compactSegment`
-   * free function with explicit deps.
+   * 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.
    */
-  compactionDeps() {
-    if (this.coldDriver === void 0) {
+  lifecycleDeps(op) {
+    if (this.storageDriver === void 0) {
       throw new UnsupportedError(
-        "compact/dropSegment/eraseSubject/checkConsistency need the store built with a raw cold driver (IColdDriver), not a pre-built ColdChunkSource \u2014 or call the compactSegment/runConsistencyCheck free functions with explicit deps"
+        `${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(
-        "compact/eraseSubject/checkConsistency need a `registry` in the store config"
+        `${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 {
-      cold: this.coldDriver,
-      warm: this.warmDriver,
+      storage: this.storageDriver,
       registry: this.registry,
       clock: this.clock,
       codec: roaringCodec,
       // facade injects the flagship codec
       keystore: this.keystore,
-      requireEncryption: this.requireEncryption,
-      metrics: this.metrics
-      // safe-wrapped sink → store.compact/eraseSubject emit `compaction` events (gap #2)
+      requireEncryption: this.requireEncryption
     };
   }
-  /** Get a handle to a segment. Validates the name/namespace grammar (finding S2). */
+  /** 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);
-    return new Segment(this.engine, ref, this.clock, this.metrics);
+    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?** (Phase 6b.)
+   * **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 tier-merging `has(id)` on
-   * each — no drivers to re-pass. Complete only over registered segments (register your segments if you claim
-   * SAR support). There is deliberately **no `id → segments` reverse index** — that would tax every write for a
-   * rare request; this admin scan is `O(registered segments)` and touches no hot path.
-   * Requires a `registry` in the store config
-   * (throws {@link UnsupportedError} otherwise).
+   * 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 = {}) {
-    if (this.registry === void 0) {
-      throw new UnsupportedError("subjectReport needs a `registry` in the store config");
-    }
-    const registry = this.registry;
+    const registry = this.requireRegistry("subjectReport");
     requireScope(options, "subjectReport");
     validateConcurrency(options.concurrency);
     const budget = resolvePerOpBudget(options.budget, this.budget);
     splitId(id);
     const recs = await collectWithinBudget(
-      registry.list(options.namespace),
+      // 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"
     );
@@ -362,56 +614,67 @@ var CloudRoaring = class {
       async (rec) => {
         if (rec.status === "destroyed") return null;
         const ref = { segment: rec.segment, namespace: rec.namespace };
-        return await this.engine.has(ref, id, { consistent: true }) ? { segment: rec.segment, namespace: rec.namespace } : null;
+        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 a physical-deletion
-   * guarantee.** (Phase 6b.)
-   *
-   * For each **registered** segment the id is a member of: writes a logical `remove` tombstone (immediate) and
-   * then **force-compacts that segment now** — folding the tombstone into a fresh immutable generation so the
-   * bit is *physically* gone from Cold on return, even for an otherwise-idle/archival segment that organic
-   * compaction would never touch (the P13 fix). The returned per-segment record is your **erasure ledger** —
-   * persist it / route it to your audit sink as the proof of deletion; the physical-purge proof is
-   * compaction's own VERIFY step (a re-`has()` here would be unsound — a pinned cold source can still read the
-   * old generation; take a fresh generation view after erasing, exactly as with the compaction daemon).
-   *
-   * Uses the store's **own** drivers (raw cold + warm + registry), so the old integrator obligation to wire a
-   * matching `CompactionDeps` is gone — the `remove()` and the force-compaction provably run over the same tiers.
-   * Requires the store built with a **raw cold driver + registry** (throws {@link UnsupportedError} otherwise;
-   * a pre-built `ColdChunkSource` store has no `IColdDriver` to compact through — use the `compactSegment` free
-   * function there). **One contract remains** (an integrator obligation the library cannot check): **do not
-   * concurrently re-add the same id while erasing it.** A normal `add(id)` landing between the `remove` and the
-   * compaction clears the tombstone and folds the id back into the new generation
-   * (`effective = (cold ∪ adds) \ removes`); `physicallyPurged` attests only that compaction committed a
-   * generation with the tombstones applied at pin time — quiesce writes for the subject during erasure.
-   *
-   * **A `physicallyPurged:false` entry means the logical removal holds but the physical purge didn't run this
-   * call** — either a daemon held a live lease (`note:'leased-by-other'`; the daemon finishes it), or the
-   * force-compaction hit an isolated fault (`note:'error: …'`; per-segment faults are caught so one segment
-   * can't discard the whole ledger). `physicallyPurged:false` is **conservative** (a concurrent daemon may
-   * already have purged the bit — `'clean'`). **Recovery:** follow up any `physicallyPurged:false` entry with
-   * `store.compact(ref)` (or let the daemon do it) — **re-running `eraseSubject` will NOT re-purge it**, because
-   * `has()` now reads false (the tombstone) so the segment is skipped as a non-member. The physical-purge proof
-   * is compaction's own VERIFY step (a re-`has()` here would be unsound: a pinned cold source can still read the
-   * old generation — take a fresh generation view after erasing, as with the daemon). Admin-only path;
+   * **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 the `destroySegment`/`eraseNamespace` free functions.
+   * is `dropSegment` / the `destroySegment`/`eraseNamespace` free functions.
    */
-  async eraseSubject(id, options) {
-    const compaction = this.compactionDeps();
-    validateCompactionOptions({ owner: options.owner });
+  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(
-      compaction.registry.list(options.namespace),
+      excludingReservedRows(deps.registry.list(options.namespace)),
       budget,
       "eraseSubject"
     );
@@ -421,31 +684,31 @@ var CloudRoaring = class {
       async (rec) => {
         if (rec.status === "destroyed") return null;
         const ref = { segment: rec.segment, namespace: rec.namespace };
-        let removed = false;
         try {
-          if (!await this.engine.has(ref, id, { consistent: true })) return null;
-          await this.engine.remove(ref, id);
-          removed = true;
-          const result = await compactSegment$1(ref, compaction, {
-            owner: options.owner,
-            audit: options.audit
-          });
+          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,
-            removed: true,
-            physicallyPurged: result.compacted,
-            toGen: result.toGen,
-            note: result.compacted ? void 0 : result.reason
+            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,
-            removed,
-            physicallyPurged: false,
+            erased: false,
             note: `error: ${err instanceof Error ? err.message : String(err)}`
           };
+        } finally {
+          try {
+            this.engine.invalidate(ref);
+          } catch {
+          }
         }
       }
     );
@@ -453,30 +716,164 @@ var CloudRoaring = class {
     return { id, erasedFrom, scannedSegments: recs.length };
   }
   /**
-   * **Compact one segment now**, in-process, using the store's own drivers — a convenience over the
-   * {@link compactSegment} free function. Merges `(cold ∪ adds) \ removes` into a fresh immutable generation,
-   * swaps `currentGen`, then version-fenced-purges the archived Warm rows. A no-op (`compacted:false`) when the
-   * segment has no dirty rows or a daemon holds a live lease — never throws on the normal contention/lease paths.
-   * Requires the store built with a **raw cold driver + registry** (throws {@link UnsupportedError} otherwise);
-   * like the daemon, it uses the raw drivers directly (a transient fault surfaces to you rather than retrying
-   * under the hood). **Not for the request/hot path** — it reads and rewrites a whole Cold generation (streaming,
-   * constant-memory, but full-segment I/O). Use the `compact-segments` daemon (`runCompactionCycle`) for routine
-   * background compaction; reach for `store.compact()` for occasional/manual one-shots — a maintenance endpoint,
-   * a small daemon-less deployment, or right after a targeted `remove`.
+   * 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 compact(ref, options) {
+  async generations(ref) {
     validateSegmentRef(ref);
-    const deps = this.compactionDeps();
-    const result = await compactSegment$1(ref, deps, options);
-    if (result.compacted) {
-      await gcOrphanGenerations(ref, { cold: deps.cold, registry: deps.registry }).catch(
-        () => void 0
-      );
+    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 result;
+    return listSegments(this.requireRegistry("segments"), options);
   }
   /**
-   * **Dispose of a segment — tombstone it, delete its Warm rows, delete its Cold objects.** Irreversible.
+   * 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
@@ -488,7 +885,8 @@ var CloudRoaring = class {
    *
    * ```ts
    * for (const day of expiredDays) {
-   *   // A colon is NOT legal in a name — the family goes in the namespace, the date in the segment.
+   *   // 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 });
    * }
@@ -498,173 +896,428 @@ var CloudRoaring = class {
    * `{ dropped: false, reason: 'absent' }`, not a throw, so a retention loop with that mistake deletes nothing
    * forever and quietly. Branch on `dropped`, and treat `reason: 'absent'` as the alert.
    *
-   * **Works on an accumulator too.** A segment you created by writing to it — never bulk-loaded, never compacted,
-   * so it has no registry row and no Cold objects — is retired by deleting its Warm rows alone. That reports
-   * `{ dropped: true, reason: 'warm-only' }`: there is no tombstone to write, and deliberately none is written,
-   * because a `destroyed` row per retired daily bucket would be registry litter. The data really is gone.
-   *
    * **Inspect `generationsRemaining`.** Empty is the normal outcome; non-empty means the storage was NOT fully
-   * reclaimed and the drop should be re-run. A compaction that was already in flight when the tombstone landed
-   * still finishes staging one more object, so a single sweep can miss it — this call re-sweeps and then reports
-   * whatever it still could not remove rather than returning a result that looks like a clean drop.
-   *
-   * Reads become empty within `coldGenTtlMs` (default 2 s), not instantly: a store that had already read this
-   * segment may answer from its cached generation + hot chunks until that window lapses. A reader that never
-   * touched it sees empty at once. **That bound needs a clock and `coldGenTtlMs > 0`** — a store built without a
-   * clock, or with `coldGenTtlMs: 0` ("pin forever"), holds its resolved snapshot for its own lifetime and can
+   * 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 **raw cold driver + a registry** (throws {@link UnsupportedError} otherwise),
-   * because it has to enumerate and delete generations — a pre-built `ColdChunkSource` only reads.
+   * 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.compactionDeps();
-    return dropSegment(ref, { registry: deps.registry, warm: deps.warm, cold: deps.cold }, options);
+    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 (audit gap #11).** After a restore/failover, verify every registered
-   * segment's `currentGen` actually has its `.crbm` present in Cold — catching a **torn restore** where the
-   * registry (`currentGen`) came back ahead of the object store, so a pointer references a generation that
-   * isn't there (reads would then throw). Read-only, bounded fan-out; run it at startup after a restore.
-   * Returns `{ checked, inconsistent }` — `inconsistent` empty ⇒ coherent; otherwise it names the segments to
-   * recover (restore the object store, or roll the registry back to a coherent point). Needs the store built
-   * with a **raw cold driver + a registry** (throws {@link UnsupportedError} otherwise). `destroyed`
-   * (crypto-shredded) segments are skipped. Pair it with the DR runbook (docs/guide/disaster-recovery.md).
+   * **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.compactionDeps();
-    return runConsistencyCheck({ cold: deps.cold, registry: deps.registry }, options);
+    const deps = this.lifecycleDeps("checkConsistency");
+    return runConsistencyCheck({ storage: deps.storage, registry: deps.registry }, options);
   }
   /**
-   * **Export ("eject") every registered segment's current effective set** through the injected `sink`, using
-   * only public read APIs — so your data is readable **without CloudRoaring** (the exit path; see the README's
-   * "Your data stays yours"). `format: 'roaring'` (default) writes one **portable RoaringBitmap32** per segment
+   * **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; an all-warm segment not yet in the registry can be
-   * named via `options.candidates`. Encrypted segments are decrypted transparently **iff** this store was wired
-   * with their keystore — the export is therefore **cleartext**; protect it. Crypto-shredded segments are skipped.
-   * A segment that can't be read is isolated into the manifest's `failed[]` (the run continues), so "a manifest
-   * exists" means the run finished — check `failed`. The `export-segments` CLI wraps this with a filesystem sink.
+   * 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 = {}) {
-    if (this.registry === void 0) {
-      throw new UnsupportedError("exportSegments needs a `registry` in the store config");
-    }
-    return runExport$1(this, this.registry, sink, {
+    const registry = this.requireRegistry("exportSegments");
+    return runExport2(this, registry, sink, {
       ...options,
       codec: options.codec ?? roaringCodec
     });
   }
   /**
-   * Planning cost estimate (Phase 5b) — pure, no instance/data needed: sizing, sales, what-if. For a real,
-   * grounded report from live segment sizes, use `store.segment(name).costReport()`. See {@link CostReport}.
+   * 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) {
+  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;
   /**
-   * 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.
+   * **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 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) });
-    }
+  async pin() {
+    return this.pinned(this.ref, this.expiresAt);
   }
-  /** Add an id (integer in `[0, 2^32)`). Throws {@link ValidationError} on a bad id. */
-  add(id) {
-    return this.timed("add", () => this.engine.add(this.ref, id));
+  /** This handle's segment, as the cache/pin key — `ref` stays private; the encapsulation is worth the method. */
+  key() {
+    return segmentKey(this.ref);
   }
   /**
-   * Add many ids, from a **sync or async** iterable. Not atomic across chunks — see the class note.
+   * 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.
    *
-   * An async source means a database cursor streams straight in — `addMany(athenaCursor())` rather than
-   * hand-batching `page → addMany(page)`. Ids are grouped by chunk and each chunk is written **exactly once**,
-   * however long the stream: pending ids are held compressed, not buffered-and-flushed, so a long stream costs
-   * no more backend writes than a short one. Peak memory is the roaring representation of the ids you pass.
-   *
-   * **For a very large set, reach for `bulkLoadCrbmGeneration` instead.** `addMany` expresses a *delta* and
-   * writes one warm row per touched chunk — around 61,000 of them for a set spread across the whole id space.
-   * Bulk-load *replaces* the segment with one immutable Cold object. See the guide's cost comparison; picking
-   * the wrong one of these is the most expensive mistake available in this library.
+   * 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.
    */
-  addMany(ids) {
-    return this.timed("addMany", () => this.engine.addMany(this.ref, ids));
-  }
-  /** Remove an id (integer in `[0, 2^32)`). Throws {@link ValidationError} on a bad id. */
-  remove(id) {
-    return this.timed("remove", () => this.engine.remove(this.ref, id));
-  }
-  /** Remove many ids, from a **sync or async** iterable. Not atomic across chunks — see {@link addMany}. */
-  removeMany(ids) {
-    return this.timed("removeMany", () => this.engine.removeMany(this.ref, ids));
+  expired() {
+    return this.expiresAt !== void 0 && this.clock.now() >= this.expiresAt;
   }
   /**
-   * **Claim ids atomically — add them, and get back only the ones that were not already there.**
-   *
-   * The durable analogue of Redis `SETBIT` returning the prior bit, which is what an exactly-once *"have I
-   * already sent to / already processed this id?"* check needs. `has()` then `add()` cannot give you this: two
-   * workers can both read absent and both proceed.
+   * Refuse a materialisation that involves an **expired** handle. Called by the three `*Into` verbs only.
    *
-   * ```ts
-   * const sent = store.segment(day, { namespace: 'sent-daily' });
-   * const toSend = await sent.claimMany(candidateIds);   // only the ids this worker won
-   * for (const id of toSend) enqueue(id);                // ...so nobody else will send them
-   * ```
+   * 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.
    *
-   * **Pass a batch, not one id.** A Warm write rewrites a whole 64K-id chunk bitmap, so claiming ids one at a
-   * time is the single most expensive way to use this library — measured at ~5,000 writes and ~23 MB for 5,000
-   * ids, against 1 write and ~8 KB for the same ids in one call. This method does one OCC read-modify-write per
-   * distinct chunk, giving you Redis's *semantics* without Redis's per-id *cost shape*.
+   * 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.
    *
-   * **Exactly-once holds per id**, which is the guarantee that matters: each id lives in one chunk, a chunk is
-   * one OCC row, so exactly one concurrent claimer sees any given id as new. Like `addMany` it is **not** atomic
-   * across chunks — a mid-flight failure can leave some chunks claimed — but re-running is safe, because
-   * already-claimed ids simply come back as not-new.
+   * (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.)
    *
-   * Order of the returned ids is unspecified.
+   * 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.
    */
-  claimMany(ids) {
-    return this.timed("claimMany", () => this.engine.claimMany(this.ref, ids));
+  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);
   }
-  /**
-   * Chunk-skipping intersection: stream the ids in **this** segment AND every segment in `others`, ascending.
-   * Fetches only the Cold chunks present in *all* operands (a key absent from any operand contributes nothing
-   * and is never downloaded), streaming under a bounded in-flight window — so the Cold footprint stays small
-   * (Lambda-friendly) regardless of segment size. Pass `concurrency` to tune that window (a positive integer).
-   * AND is commutative, so `a.intersect([b])` and `b.intersect([a])` yield the same ids. (Warm state is read
-   * up front, so total memory also carries each operand's Warm size — negligible under Topology-A.) Pass
-   * `budget` to override the store's per-op denial-of-wallet budget for this call (or `false` to lift it).
-   */
   /**
    * Map the facade's `Segment` handles in `exclude` down to the plain refs `core` takes. A method rather than
    * a module function because `ref` is class-private — the encapsulation is worth more than the free function.
@@ -674,21 +1327,43 @@ var Segment = class {
     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) {
-    return this.engine.intersect([this.ref, ...others.map((o) => o.ref)], this.refsIn(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`) **into** `dest` (added, not replaced). Streaming +
-   * bounded-memory, but **not atomic** across chunks — see {@link addMany}.
+   * 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}.
    */
-  intersectInto(dest, others, options) {
+  async intersectInto(dest, others, options) {
+    this.refuseIfExpired("intersectInto", dest, [...others, ...options?.exclude ?? []]);
     return this.timed(
       "intersectInto",
-      () => this.engine.intersectInto(
-        dest.ref,
-        [this.ref, ...others.map((o) => o.ref)],
-        this.refsIn(options)
-      )
+      () => this.materialize(dest.ref, this.intersect(others, options), "intersectInto", options)
     );
   }
   /**
@@ -699,20 +1374,28 @@ var Segment = class {
    * `intersect` prunes any key missing from any operand; union has nothing to prune. It is charged against the
    * same per-op budget, so a wide union is refused rather than quietly billed — pass `budget` to raise it
    * deliberately. If you find yourself unioning the same segments on every read, materializing the combined
-   * segment once (`unionInto`, or a bulk-load rebuild) is the cheaper shape.
+   * segment once (`unionInto`, or a load) is the cheaper shape.
    */
   union(others, options) {
-    return this.engine.union([this.ref, ...others.map((o) => o.ref)], this.refsIn(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`) **into** `dest`. **Not atomic** — see {@link addMany}. */
-  unionInto(dest, others, 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.engine.unionInto(
-        dest.ref,
-        [this.ref, ...others.map((o) => o.ref)],
-        this.refsIn(options)
-      )
+      () => this.materialize(dest.ref, this.union(others, options), "unionInto", options)
     );
   }
   /**
@@ -727,44 +1410,52 @@ var Segment = class {
    * the suppression folds into the same pass rather than materializing an intermediate segment first.
    */
   andNot(excludes, options) {
-    return this.engine.andNot(
+    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…)` **into** `dest`. **Not atomic** — see {@link addMany}. */
-  andNotInto(dest, excludes, 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.engine.andNotInto(
-        dest.ref,
-        this.ref,
-        excludes.map((o) => o.ref),
-        options
-      )
+      () => this.materialize(dest.ref, this.andNot(excludes, options), "andNotInto", options)
     );
   }
   /**
-   * Grounded cost report for this segment (Phase 5b): storage cost from its **real** `.crbm` size (exact,
-   * no payload reads); request cost from the supplied `workload` rates. A segment with no Cold generation
-   * reports zero storage. See {@link CostReport} — it always includes a verdict (incl. the lose-zone).
+   * 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.supportsColdSize;
+    const canMeasure = this.engine.supportsStorageSize;
     const size = canMeasure ? await this.engine.segmentSize(this.ref) : null;
     return groundedReport({
-      coldBytes: size?.sizeBytes ?? 0,
+      storageBytes: size?.sizeBytes ?? 0,
       grounded: canMeasure,
       workload: options?.workload,
-      topology: options?.topology,
       pricing: options?.pricing,
-      extraNotes: canMeasure ? void 0 : ["cold source has no sizeOf() \u2014 storage not measured, reported as $0."]
+      extraNotes: canMeasure ? void 0 : ["storage source has no sizeOf() \u2014 storage not measured, reported as $0."]
     });
   }
 };
-var VERSION = "0.8.2";
-
-export { CloudRoaring, SafeBitmap, Segment, VERSION, bulkLoadCrbmGeneration, compactSegment, roaringCodec, runCompactionCycle, runExport };
+var VERSION = "0.10.0";
+export {
+  CloudRoaring,
+  SafeBitmap,
+  Segment,
+  VERSION,
+  bulkLoadCrbmGeneration,
+  eraseIdFromSegment,
+  loadSegment,
+  roaringCodec,
+  runExport
+};
 //# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map