@cloudbitmaps/roaring 0.9.0 → 0.11.0

package/dist/index.js

@@ -1,8 +1,256 @@
-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, setSegmentRetention, getSegmentRetention, clearSegmentRetention, retireExpired, 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,
+  withRetry,
+  isStorageBackend,
+  NOOP_METRICS,
+  RetryingStorageChunkSource,
+  SegmentEngine,
+  UnsupportedError,
+  ValidationError as ValidationError2,
+  WriteConflictError,
+  MIN_EXPIRES_AT_MS,
+  checkBudget,
+  collectWithinBudget,
+  excludingReservedRows,
+  dropSegment,
+  eraseIdFromSegment,
+  estimateCost,
+  groundedReport,
+  loadSegment,
+  mapWithConcurrency,
+  resolveBudget,
+  resolvePerOpBudget,
+  retireExpired,
+  runConsistencyCheck,
+  runExport,
+  setSegmentRetention,
+  clearSegmentRetention,
+  getSegmentRetention,
+  safeMetrics,
+  splitId
+} from "@cloudbitmaps/core";
+import { validateSegmentRef } from "@cloudbitmaps/core/driver-kit";
+
+// src/open-charging-storage.ts
+var OpenChargingStorage = class {
+  /**
+   * @param inner   the driver the erasure would otherwise use
+   * @param current the generation the segment's row named when it was listed, or `null` when it named none
+   * @param charge  called once per charged open; it throws to refuse
+   */
+  constructor(inner, current, charge) {
+    this.inner = inner;
+    this.charge = charge;
+    if (current !== null) this.free.add(current);
+  }
+  inner;
+  charge;
+  free = /* @__PURE__ */ new Set();
+  capabilities() {
+    return this.inner.capabilities();
+  }
+  async putImmutable(key, write) {
+    const written = await this.inner.putImmutable(key, write);
+    this.free.add(key.generation);
+    return written;
+  }
+  getRange(key, offset, length) {
+    return this.inner.getRange(key, offset, length);
+  }
+  /** One `getTail` is one open: a reader takes the footer and the index from it, and reads chunks with `getRange`. */
+  async getTail(key, maxBytes) {
+    if (!this.free.has(key.generation)) this.charge();
+    return this.inner.getTail(key, maxBytes);
+  }
+  delete(key) {
+    return this.inner.delete(key);
+  }
+  list(ref) {
+    return this.inner.list(ref);
+  }
+};
 
 // src/index.ts
+import { listGenerations, rollbackSegment } from "@cloudbitmaps/core";
+import { listSegments, segmentExists } from "@cloudbitmaps/core";
+
+// src/reserved-namespace.ts
+import { ValidationError } from "@cloudbitmaps/core";
+var RESERVED_NAMESPACE_PREFIX = "cbm.due.";
+function refuseReservedNamespace(namespace) {
+  if (namespace !== void 0 && namespace.startsWith(RESERVED_NAMESPACE_PREFIX)) {
+    throw new ValidationError(
+      `namespace "${namespace}" is reserved: names starting with "${RESERVED_NAMESPACE_PREFIX}" hold the library's own bookkeeping rows, which every fleet-wide scan skips, so a segment there would be invisible to an erasure, a consistency check, an export and a retention sweep. Choose another namespace.`
+    );
+  }
+}
+
+// src/roaring-codec.ts
+import roaring from "roaring";
+import { IntegrityError as IntegrityError2 } from "@cloudbitmaps/core";
+
+// src/portable/layout.ts
+import { IntegrityError } from "@cloudbitmaps/core";
+var SERIAL_COOKIE_NO_RUNCONTAINER = 12346;
+var SERIAL_COOKIE = 12347;
+var NO_OFFSET_THRESHOLD = 4;
+var ARRAY_MAX_CARDINALITY = 4096;
+var BITMAP_CONTAINER_BYTES = 8192;
+var MAX_LOW = 65535;
+var ARRAY = 0;
+var BITMAP = 1;
+var RUN = 2;
+function overrun(bytes, offset, length, what) {
+  return new IntegrityError(
+    `portable roaring: ${what} needs bytes [${offset}, ${offset + length}) of a ${bytes.byteLength}-byte buffer`
+  );
+}
+function checkPortableLayout(bytes) {
+  walk(bytes, null);
+}
+function walk(bytes, out) {
+  const length = bytes.byteLength;
+  if (length === 0) return;
+  const view = new DataView(bytes.buffer, bytes.byteOffset, length);
+  if (length < 4) throw overrun(bytes, 0, 4, "the cookie");
+  const cookie = view.getUint32(0, true);
+  let count;
+  let runFlagsAt = -1;
+  let pos;
+  if (cookie === SERIAL_COOKIE_NO_RUNCONTAINER) {
+    if (length < 8) throw overrun(bytes, 4, 4, "the container count");
+    count = view.getUint32(4, true);
+    pos = 8;
+  } else if ((cookie & 65535) === SERIAL_COOKIE) {
+    count = (cookie >>> 16) + 1;
+    runFlagsAt = 4;
+    const flagBytes = count + 7 >>> 3;
+    if (runFlagsAt + flagBytes > length) {
+      throw overrun(bytes, runFlagsAt, flagBytes, "the run-container bitmap");
+    }
+    pos = runFlagsAt + flagBytes;
+  } else {
+    throw new IntegrityError(
+      `portable roaring: unrecognized cookie 0x${cookie.toString(16)}, not a portable-format bitmap`
+    );
+  }
+  const descriptiveAt = pos;
+  if (pos + count * 4 > length) throw overrun(bytes, pos, count * 4, "the descriptive header");
+  pos += count * 4;
+  let offsetsAt = -1;
+  if (runFlagsAt < 0 || count >= NO_OFFSET_THRESHOLD) {
+    if (pos + count * 4 > length) throw overrun(bytes, pos, count * 4, "the offset header");
+    offsetsAt = pos;
+    pos += count * 4;
+  }
+  let previousKey = -1;
+  for (let i = 0; i < count; i++) {
+    const key = view.getUint16(descriptiveAt + i * 4, true);
+    if (key <= previousKey) {
+      throw new IntegrityError(
+        `portable roaring: container keys are not strictly ascending (${previousKey} then ${key} at index ${i})`
+      );
+    }
+    previousKey = key;
+    const cardinality = view.getUint16(descriptiveAt + i * 4 + 2, true) + 1;
+    const isRun = runFlagsAt >= 0 && (bytes[runFlagsAt + (i >>> 3)] & 1 << (i & 7)) !== 0;
+    const kind = isRun ? RUN : cardinality > ARRAY_MAX_CARDINALITY ? BITMAP : ARRAY;
+    if (offsetsAt >= 0) {
+      const stated = view.getUint32(offsetsAt + i * 4, true);
+      if (stated !== pos) {
+        throw new IntegrityError(
+          `portable roaring: the offset header puts container ${i} at byte ${stated}, but it starts at ${pos}`
+        );
+      }
+    }
+    let size;
+    if (kind === ARRAY) {
+      size = cardinality * 2;
+      if (pos + size > length) throw overrun(bytes, pos, size, `container ${i} (array)`);
+      checkArray(view, pos, cardinality, i);
+    } else if (kind === BITMAP) {
+      size = BITMAP_CONTAINER_BYTES;
+      if (pos + size > length) throw overrun(bytes, pos, size, `container ${i} (bitmap)`);
+      const bits = popcount(view, pos);
+      if (bits !== cardinality) {
+        throw new IntegrityError(
+          `portable roaring: container ${i} (bitmap) holds ${bits} values, but its header says ${cardinality}`
+        );
+      }
+    } else {
+      if (pos + 2 > length) throw overrun(bytes, pos, 2, `container ${i} (run count)`);
+      const runs = view.getUint16(pos, true);
+      size = 2 + runs * 4;
+      if (pos + size > length) throw overrun(bytes, pos, size, `container ${i} (run)`);
+      const covered = checkRuns(view, pos + 2, runs, i);
+      if (covered !== cardinality) {
+        throw new IntegrityError(
+          `portable roaring: container ${i} (run) covers ${covered} values, but its header says ${cardinality}`
+        );
+      }
+    }
+    out?.push({ key, cardinality, kind, offset: pos });
+    pos += size;
+  }
+}
+function checkArray(view, at, cardinality, index) {
+  let previous = -1;
+  let p = at;
+  const end = at + cardinality * 2;
+  for (; p + 4 <= end; p += 4) {
+    const pair = view.getUint32(p, true);
+    const first = pair & 65535;
+    const second = pair >>> 16;
+    if (first <= previous || second <= first) throw unordered(index, (p - at) / 2);
+    previous = second;
+  }
+  if (p < end && view.getUint16(p, true) <= previous) throw unordered(index, (p - at) / 2);
+}
+function unordered(index, element) {
+  return new IntegrityError(
+    `portable roaring: container ${index} (array) is not strictly ascending at or after element ${element}`
+  );
+}
+function checkRuns(view, at, runs, index) {
+  let covered = 0;
+  let lowest = 0;
+  for (let r = 0; r < runs; r++) {
+    const run = view.getUint32(at + r * 4, true);
+    const start = run & 65535;
+    const last = start + (run >>> 16);
+    if (start < lowest) {
+      throw new IntegrityError(
+        `portable roaring: container ${index} (run) has run ${r} out of order, overlapping or touching the one before`
+      );
+    }
+    if (last > MAX_LOW) {
+      throw new IntegrityError(
+        `portable roaring: container ${index} (run) has run ${r} running past the end of the container`
+      );
+    }
+    covered += last - start + 1;
+    lowest = last + 2;
+  }
+  return covered;
+}
+function popcount(view, at) {
+  let bits = 0;
+  for (let p = at, end = at + BITMAP_CONTAINER_BYTES; p < end; p += 4) {
+    let w = view.getUint32(p, true);
+    w -= w >>> 1 & 1431655765;
+    w = (w & 858993459) + (w >>> 2 & 858993459);
+    bits += Math.imul(w + (w >>> 4) & 252645135, 16843009) >>> 24;
+  }
+  return bits;
+}
+
+// src/roaring-codec.ts
 var { RoaringBitmap32, SerializationFormat, DeserializationFormat } = roaring;
 var SafeBitmap = class _SafeBitmap {
   bitmap;
@@ -16,18 +264,24 @@ var SafeBitmap = class _SafeBitmap {
     return new _SafeBitmap(new RoaringBitmap32(values));
   }
   /**
-   * S1: validate size, then deserialize with the **portable** (validated) format.
-   * Throws `IntegrityError` if the input exceeds `maxBytes` or fails to decode — the
-   * native addon is never handed unbounded or unsafe-format input.
+   * Cap the size, check the structure, then deserialize with the **portable** format.
+   * Throws `IntegrityError` if the input exceeds `maxBytes`, is not a well-formed portable bitmap, or fails to
+   * decode — the native addon is never handed unbounded, malformed or unsafe-format input.
+   *
+   * The structural check is what makes the decoded bitmap's answers mean anything. The native deserializer
+   * bounds its reads and checks nothing else, so bytes of the right length and the wrong shape (containers or
+   * values out of order, overlapping runs, a cardinality that disagrees with the bits) decode into a bitmap
+   * whose `maximum()`, `has()` and `size` are wrong, and some of those shapes crash the process when used.
    */
   static safeDeserialize(bytes, maxBytes) {
     if (bytes.length > maxBytes) {
-      throw new IntegrityError(`serialized bitmap is ${bytes.length}B, exceeds cap ${maxBytes}B`);
+      throw new IntegrityError2(`serialized bitmap is ${bytes.length}B, exceeds cap ${maxBytes}B`);
     }
+    checkPortableLayout(bytes);
     try {
       return new _SafeBitmap(RoaringBitmap32.deserialize(bytes, DeserializationFormat.portable));
     } catch (err) {
-      throw new IntegrityError(`failed to deserialize bitmap: ${err.message}`);
+      throw new IntegrityError2(`failed to deserialize bitmap: ${err.message}`);
     }
   }
   serialize() {
@@ -48,15 +302,17 @@ 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();
   }
   /**
-   * Largest value, or `undefined` when empty. O(1) — roaring reads it off the container index, so the engine's
-   * per-chunk range assertion costs one call per chunk rather than a walk per id.
+   * Largest value, or `undefined` when empty. O(1) — roaring reads it off the last container, so the engine's
+   * per-chunk range assertion costs one call per chunk rather than a walk per id. The last container holds the
+   * largest value only because {@link SafeBitmap.safeDeserialize} refuses bytes whose containers or values are
+   * out of order.
    */
   maximum() {
     return this.bitmap.isEmpty ? void 0 : this.bitmap.maximum();
@@ -131,7 +387,7 @@ var SystemClock = class {
    * A long CPU-bound loop in `core/` (bulk-load is the one that matters) periodically hands the loop back so a
    * co-resident HTTP server keeps answering. Measured on the **synthetic yield-primitive benchmark** — a
    * 61,035-iteration loop yielding every 1,024, isolating the primitive rather than timing a real load (the
-   * end-to-end figures are 450 ms → 19 ms; see `cooperative.ts`, which lists all three experiments):
+   * end-to-end figures are 519 ms → 24 ms; see `cooperative.ts`, which lists all three experiments):
    *
    * ```text
    *   no yield         568 ms wall   568.0 ms worst event-loop gap
@@ -154,17 +410,57 @@ var SystemClock = class {
     });
   }
 };
-var bulkLoadCrbmGeneration = (driver, key, ids, options = {}) => bulkLoadCrbmGeneration$1(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 });
+
+// src/option-keys.ts
+var OPTION_KEYS = {
+  top: ["storage", "cache", "encryption", "retry", "metrics", "budget", "seams"],
+  cache: ["maxChunks", "ttlMs", "genTtlMs", "readerMax", "readerMaxBytes"],
+  encryption: ["keystore", "required"],
+  retry: ["maxAttempts", "baseDelayMs", "maxDelayMs", "backoffFactor", "jitter", "onRetry"],
+  budget: ["maxRequests"],
+  seams: ["clock", "rng"]
+};
 
 // src/index.ts
+import {
+  MemoryStorage,
+  LocalFsStorage,
+  CrbmStorageChunkSource as CrbmStorageChunkSource2,
+  destroySegment,
+  eraseNamespace,
+  excludingReservedRows as excludingReservedRows2,
+  readRetentionPolicy,
+  MIN_EXPIRES_AT_MS as MIN_EXPIRES_AT_MS2,
+  InProcessKeystore,
+  NodeAead,
+  aadFor,
+  CloudRoaringError,
+  ValidationError as ValidationError3,
+  WriteConflictError as WriteConflictError2,
+  IntegrityError as IntegrityError3,
+  NotFoundError,
+  UnsupportedError as UnsupportedError2,
+  CapabilityError,
+  TransientError,
+  KeyUnavailableError,
+  BudgetExceededError,
+  isCloudRoaringError,
+  isWriteConflictError,
+  isTransientError,
+  isNotFoundError,
+  isIntegrityError,
+  isValidationError,
+  CrbmReader,
+  BufferReader,
+  CountingMetricsSink,
+  RecordingAuditSink,
+  DEFAULT_RETRY_POLICY as DEFAULT_RETRY_POLICY2,
+  AWS_US_EAST_1_ONDEMAND,
+  ELASTICACHE_REDIS_US_EAST_1_ONDEMAND,
+  ONE_REDIS_HA_CLUSTER
+} from "@cloudbitmaps/core";
 var SystemRng = class {
+  /** A float in `[0, 1)`. Jitter only — never key material, never anything a caller can observe. */
   next() {
     return Math.random();
   }
@@ -173,84 +469,195 @@ var DEFAULT_CACHE_MAX_CHUNKS = 1024;
 var DEFAULT_ADMIN_CONCURRENCY = 8;
 function validateConcurrency(concurrency) {
   if (concurrency !== void 0 && (!Number.isInteger(concurrency) || concurrency < 1)) {
-    throw new ValidationError(`concurrency must be a positive integer; got ${concurrency}`);
+    throw new ValidationError2(`concurrency must be a positive integer; got ${concurrency}`);
   }
 }
 function requireScope(options, op) {
+  refuseReservedNamespace(options.namespace);
   if (options.namespace === void 0 && options.allNamespaces !== true) {
-    throw new ValidationError(
+    throw new ValidationError2(
       `${op} scans the global id space across all namespaces \u2014 pass an explicit \`namespace\`, or \`{ allNamespaces: true }\` to intentionally sweep the whole fleet`
     );
   }
 }
-function 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 ValidationError2(
+      "`storage` must be a StorageBackend, an IStorageDriver, or a StorageChunkSource"
+    );
+  }
+  const asBackend = storage;
+  const isObject = (v) => v !== null && typeof v === "object";
+  const hasGetChunk = typeof storage.getChunk === "function";
+  const hasPutImmutable = typeof storage.putImmutable === "function";
+  const isBackend = isStorageBackend(storage);
+  if (isBackend && (hasGetChunk || hasPutImmutable)) {
+    throw new ValidationError2(
+      `\`storage\` is a StorageBackend that also exposes ${hasGetChunk ? "`getChunk`" : "`putImmutable`"} \u2014 ambiguous. A backend must not also be a driver or a source; pass whichever one you mean.`
+    );
+  }
+  const hasStorageHalf = isObject(asBackend.storage);
+  const hasRegistryHalf = isObject(asBackend.registry);
+  if (!isBackend && hasPutImmutable && hasRegistryHalf) {
+    throw new ValidationError2(
+      "`storage` looks like a driver that also carries a `registry`. Passed as a bare driver it would have no pointer at all \u2014 generations would resolve by list-scan, so reads could serve a generation that was written but never published. If you meant a backend, use a backend class \u2014 S3Storage, GcsStorage, AzureBlobStorage, LocalFsStorage or MemoryStorage \u2014 or, to pair a driver of your own with a registry, brand the pair with `brandAsBackend` from `@cloudbitmaps/core/driver-kit`."
+    );
+  }
+  if (!isBackend && !hasGetChunk && !hasPutImmutable && hasStorageHalf && hasRegistryHalf) {
+    const storageOk = typeof asBackend.storage.putImmutable === "function";
+    const registryOk = typeof asBackend.registry.compareAndSwap === "function";
+    if (!storageOk || !registryOk) {
+      const bad = !storageOk ? "`storage` half is not an IStorageDriver (no `putImmutable`)" : "`registry` half is not an IRegistryDriver (no `compareAndSwap`)";
+      throw new ValidationError2(
+        "`storage` looks like a backend but its " + bad + " \u2014 use a backend class, or brand a pair of drivers with `brandAsBackend` from `@cloudbitmaps/core/driver-kit`."
+      );
+    }
+    throw new ValidationError2(
+      "`storage` must be a backend \u2014 S3Storage, GcsStorage, AzureBlobStorage, LocalFsStorage or MemoryStorage. An object with `.storage` and `.registry` is not one: a backend builds both halves from a single bucket and prefix, so they cannot disagree, and hand-assembling them re-opens exactly that mismatch \u2014 a store whose pointer and generations live in different places reads as empty rather than failing. A driver author who genuinely wants halves of their own \u2014 an instrumented driver, a registry in a database you already run \u2014 brands the pair with `brandAsBackend` from `@cloudbitmaps/core/driver-kit`, which is taking on that they agree."
+    );
+  }
+  if (isBackend) {
+    const backend = storage;
+    return {
+      source: new CrbmStorageChunkSource(backend.storage, {
+        registry: backend.registry,
+        keystore: options.encryption?.keystore,
+        requireEncryption: options.encryption?.required,
+        clock,
+        currentGenTtlMs: options.cache?.genTtlMs,
+        maxOpenSegments: options.cache?.readerMax,
+        maxOpenIndexBytes: options.cache?.readerMaxBytes
+      }),
+      driver: backend.storage,
+      registry: backend.registry
+    };
   }
-  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"
+    throw new ValidationError2(
+      "`storage` exposes both `getChunk` and `putImmutable` \u2014 ambiguous; pass a StorageBackend, an IStorageDriver, or a StorageChunkSource, not a hybrid"
     );
   }
   if (!hasGetChunk && !hasPutImmutable) {
-    throw new ValidationError("`cold` must be an IColdDriver or a ColdChunkSource");
+    throw new ValidationError2(
+      "`storage` must be a StorageBackend, an IStorageDriver, or a StorageChunkSource"
+    );
   }
   if (hasGetChunk) {
-    if (options.registry !== void 0 || options.keystore !== void 0 || options.requireEncryption === true) {
-      throw new ValidationError(
-        "registry/keystore/requireEncryption apply only when `cold` is a raw IColdDriver; configure them on the ColdChunkSource you passed instead"
+    if (options.encryption?.keystore !== void 0 || options.encryption?.required === true) {
+      throw new ValidationError2(
+        "keystore/requireEncryption apply only when the store builds its own read path; configure them on the StorageChunkSource you passed instead"
       );
     }
-    return { source: 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 NOT_A_GROUP = {
+  Null: "null",
+  Array: "an array",
+  Map: "a Map",
+  Set: "a Set",
+  Boolean: "a boxed boolean",
+  Number: "a boxed number",
+  String: "a boxed string"
+};
+var CloudRoaring = class _CloudRoaring {
   engine;
+  cache;
+  /** The store's retry options, for a pinned engine to read through as the store's own does; undefined when off. */
+  retryOptions;
+  crbmSource;
   clock;
   metrics;
-  // The store's own drivers, kept so the 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 any option key the store does not take, at the top level or inside a group, naming each one.
+   *
+   * An option the store ignored would do nothing and look as if it had — a typo'd `cache.maxChunk`, a key from
+   * another library's config spread into this one — so every key is checked against {@link OPTION_KEYS}.
+   */
+  static rejectUnknownOptions(options) {
+    if (options === null || options === void 0 || typeof options !== "object") {
+      throw new ValidationError2(
+        "CloudRoaring needs an options object with a `storage` key \u2014 got " + (options === null ? "null" : typeof options)
+      );
+    }
+    const bag = options;
+    const unknown = [];
+    for (const key of Object.keys(bag)) {
+      if (!OPTION_KEYS.top.includes(key)) unknown.push({ group: null, key });
+    }
+    const groups = Object.keys(OPTION_KEYS).filter((g) => g !== "top");
+    for (const group of groups) {
+      const value = bag[group];
+      if (value === void 0) continue;
+      const offOk = group === "retry" || group === "budget";
+      if (value === false && offOk) continue;
+      const tag = Object.prototype.toString.call(value).slice(8, -1);
+      if (typeof value !== "object" || value === null || NOT_A_GROUP[tag] !== void 0) {
+        const got = typeof value !== "object" ? typeof value : NOT_A_GROUP[tag];
+        throw new ValidationError2(
+          `CloudRoaring's \`${group}\` must be an object${offOk ? " or `false`" : ""} \u2014 got ${got}`
+        );
+      }
+      const known = OPTION_KEYS[group];
+      for (const key of Object.keys(value)) if (!known.includes(key)) unknown.push({ group, key });
+    }
+    if (unknown.length === 0) return;
+    const takes = (keys) => keys.map((k) => `\`${k}\``).join(", ");
+    const named = [...new Set(unknown.map((u) => u.group))];
+    throw new ValidationError2(
+      `CloudRoaring does not take ${takes(unknown.map((u) => u.group === null ? u.key : `${u.group}.${u.key}`))}. ` + named.map(
+        (g) => g === null ? `The store takes ${takes(OPTION_KEYS.top)}.` : `\`${g}\` takes ${takes(OPTION_KEYS[g])}.`
+      ).join(" ") + " https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/api-reference.md#build-a-store--new-cloudroaringoptions"
+    );
+  }
   constructor(options) {
-    const clock = options.clock ?? new SystemClock();
-    const rng = options.rng ?? new SystemRng();
+    _CloudRoaring.rejectUnknownOptions(options);
+    const clock = options.seams?.clock ?? new SystemClock();
+    const rng = options.seams?.rng ?? new SystemRng();
     const metrics = safeMetrics(options.metrics ?? NOOP_METRICS);
     const cache = new BoundedLru({
-      maxEntries: options.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,88 +666,175 @@ 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.retryOptions = 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.
    */
-  compactionDeps() {
-    if (this.coldDriver === void 0) {
+  lifecycleDeps(op) {
+    if (this.storageDriver === void 0) {
       throw new UnsupportedError(
-        "compact/dropSegment/retireExpired/eraseSubject/checkConsistency need the store built with a raw cold driver (IColdDriver), not a pre-built ColdChunkSource \u2014 or call the compactSegment/runConsistencyCheck free functions with explicit deps"
+        `${op} needs the store built with a storage backend \u2014 S3Storage, GcsStorage, AzureBlobStorage, LocalFsStorage or MemoryStorage. A pre-built StorageChunkSource is read-only: it has no IStorageDriver underneath to write generations through. Build the store on one of those backend classes to write.`
       );
     }
     if (this.registry === void 0) {
       throw new UnsupportedError(
-        "compact/dropSegment/retireExpired/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 separate \`registry\` option: a backend carries it.`
       );
     }
     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);
+    refuseReservedNamespace(ref.namespace);
+    const expiresAt = options?.expiresAt;
+    if (expiresAt !== void 0) {
+      if (!Number.isFinite(expiresAt) || !Number.isInteger(expiresAt) || expiresAt < MIN_EXPIRES_AT_MS) {
+        throw new ValidationError2(
+          `segment: expiresAt must be an integer epoch-MILLISECONDS >= ${MIN_EXPIRES_AT_MS}; got ${expiresAt} (a value in seconds lands in 1970 and would make the segment read as permanently empty)`
+        );
+      }
+    }
+    return makeSegment({
+      engine: this.engine,
+      ref,
+      clock: this.clock,
+      metrics: this.metrics,
+      materialize: (dest, ids, op, options2) => this.materialize(dest, ids, op, options2),
+      pinned: (r, e) => this.pinSegment(r, e),
+      combineEngine: (handles) => this.engineForCombine(handles),
+      expiresAt
+    });
+  }
+  /**
+   * Write `ids` as a **new generation of `dest`** and publish it — the shared body of the `*Into` verbs. An `*Into`
+   * materialisation is a load, and publishes the same way (hard invariant 1): every load that finds a row fences its
+   * publish on the row's token; a guarded load (the default, since the empty refusal reads the current generation)
+   * also fences on the pointer it judged (`expectFrom`), and one that found no row fences on that absence instead.
+   * Only an unguarded load (`allowEmpty: true` and no `guard.minRetained`) onto a segment with no row publishes bare
+   * forward-only. The destination's previous generation stays readable until the publish lands (readers re-resolve
+   * within `cache.genTtlMs`).
+   *
+   * This routes through `loadSegment` rather than writing the generation itself, and that is the whole point
+   * of it. A materialisation is a load whose ids happen to come from a combine instead of from upstream, so
+   * everything `load()` learned the hard way applies unchanged: the generation is written UNPUBLISHED, the
+   * guard runs while the old generation is still authoritative, the publish is fenced as above, and a refused
+   * object is reclaimed only when a re-read finds the row unchanged (the same token) or gone (hard invariant 1:
+   * deleting it after a purge-and-recreate would put a live row over a missing generation).
+   *
+   * That last check narrows the window rather than closing it: the row read and the delete are two round
+   * trips, and `IStorageDriver` has no conditional delete to make them one. the collection a load runs carries
+   * the same residual. The failure it leaves is an orphan object, which costs storage until
+   * something collects it — deliberately the cheaper side of the trade.
+   *
+   * Written and published in one step, with no guard, an empty combine — a typo'd operand, an `exclude` that
+   * swallowed everything, an operand that had not loaded yet — would silently replace `dest` with an empty
+   * generation: the same failure `load()`'s guard exists to prevent, on the same data, reachable without passing
+   * any option at all.
+   *
+   * **A lost race throws.** `loadSegment` reports one as `reason: 'superseded'`; the `*Into` verbs throw
+   * {@link WriteConflictError} for it, so a caller can `catch (WriteConflictError)`. That one refusal is
+   * translated into the throw, and `MaterializeResult.reason` never carries it.
+   *
+   * **A `WriteConflictError` does not by itself mean nothing was published**, and that is worth knowing
+   * before you write the retry. `'superseded'` covers five different causes — the write-once PUT collided,
+   * the pointer moved, a row appeared where the load found none, the row's token changed, the row was purged —
+   * and only the first three are the "somebody beat us" the name suggests. A token can also change on a write
+   * that is not a supersession at all, such as a `setRetention` on the destination. On top of that, the collection pass that runs AFTER a
+   * successful publish can raise the same error. So: treat it as "re-read the destination and decide",
+   * never as "the write did not happen".
+   *
+   * **And by default it collects nothing**, unlike `load()`. See the `keep` default below.
+   */
+  async materialize(dest, ids, op, options) {
+    const deps = this.lifecycleDeps(op);
+    let result;
+    try {
+      result = await loadSegment(dest, ids, deps, {
+        ...options?.allowEmpty === void 0 ? {} : { allowEmpty: options.allowEmpty },
+        ...options?.guard === void 0 ? {} : { guard: options.guard },
+        // COLLECT NOTHING by default, which `loadSegment` does not — it keeps a grace window of 1 and deletes
+        // the rest. By default a materialisation collects nothing: the guide states "**It deletes nothing**,
+        // unlike `load()`. The destination's previous generations stay in the bucket until you collect them", and
+        // the ownership table
+        // puts that call on the operator. Inheriting `load()`'s collection would silently delete the
+        // generations an operator's recovery story depends on — `rollbackSegment` refuses a collected target —
+        // as a side effect of adding a guard whose entire purpose is preventing data loss. Opt in with `keep`.
+        keep: options?.keep ?? KEEP_EVERY_GENERATION,
+        ...options?.audit === void 0 ? {} : { audit: options.audit }
+      });
+    } finally {
+      this.engine.invalidate(dest);
+    }
+    const reason = result.reason;
+    if (reason === "superseded") {
+      const wrote = result.size > 0 ? `generation ${result.generation} was written and did not become current` : `nothing was written \u2014 another writer took generation ${result.generation} first`;
+      throw new WriteConflictError(
+        `${op}: the destination "${dest.segment}" changed while this materialisation was in flight, so it never became current: ${wrote}. The pointer may have moved, the row may have been rewritten (a retention policy does this) or purged. Re-read the destination and re-run.`
+      );
+    }
+    return {
+      generation: result.generation,
+      published: result.published,
+      ...reason === void 0 ? {} : { reason },
+      cardinality: result.cardinality,
+      cardinalityBefore: result.cardinalityBefore,
+      chunkCount: result.chunkCount,
+      size: result.size,
+      collected: result.collected
+    };
   }
   /**
-   * **Subject access (GDPR Art. 15 / CCPA right-to-know): which segments is this id a member of?** (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 `has(id)` on each — no
+   * drivers to re-pass. Complete only over registered segments (every loaded segment has a row, so build the
+   * store on the backend the loads used). There is deliberately **no `id → segments` reverse index** — that would
+   * tax every load for a rare request; this admin scan is `O(registered segments)` and touches no hot path. Needs
+   * a storage backend (throws {@link UnsupportedError} otherwise).
    *
-   * 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).
+   * **Current as of the registry row, not as of the reader's cache.** Each segment's resolved generation is
+   * compared with the row the scan listed, and a segment whose cached generation differs is re-resolved before the
+   * read, so a load or an erasure from another process shows at once — whatever `cache.genTtlMs` is, `0` included.
+   * The comparison is on the generation **and** the row's token, so a segment retired, purged and loaded again from
+   * generation 0 while this store held its old generation 0 is told apart too.
    */
   async subjectReport(id, options = {}) {
     const registry = this.requireRegistry("subjectReport");
@@ -349,7 +843,9 @@ var CloudRoaring = class {
     const budget = resolvePerOpBudget(options.budget, this.budget);
     splitId(id);
     const recs = await collectWithinBudget(
-      registry.list(options.namespace),
+      // A subject cannot be in a due-index row, and charging this request's budget for them would refuse a
+      // GDPR Art. 15 report for a reason unrelated to the subject.
+      excludingReservedRows(registry.list(options.namespace)),
       budget,
       "subjectReport"
     );
@@ -359,90 +855,131 @@ 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;
+        if (this.crbmSource !== void 0) {
+          const held = await this.crbmSource.currentVersion(ref);
+          const listed = rec.currentGen === null ? null : `${rec.currentGen}:${String(rec.token)}`;
+          if (held !== listed) this.engine.invalidate(ref);
+        }
+        return await this.engine.has(ref, id) ? { segment: rec.segment, namespace: rec.namespace } : null;
       }
     );
     const segments = membership.filter((m) => m !== null);
     return { id, segments, scannedSegments: recs.length };
   }
   /**
-   * **Subject erasure (GDPR Art. 17): remove an id from every segment it's in, with a physical-deletion
-   * guarantee.** (Phase 6b.)
-   *
-   * For each **registered** segment the id is a member of: writes a logical `remove` tombstone (immediate) and
-   * then **force-compacts that segment now** — folding the tombstone into a fresh immutable generation so the
-   * bit is *physically* gone from Cold on return, even for an otherwise-idle/archival segment that organic
-   * compaction would never touch (the P13 fix). The returned per-segment record is your **erasure ledger** —
-   * persist it / route it to your audit sink as the proof of deletion; the physical-purge proof is
-   * compaction's own VERIFY step (a re-`has()` here would be unsound — a pinned cold source can still read the
-   * old generation; take a fresh generation view after erasing, exactly as with the compaction daemon).
-   *
-   * Uses the store's **own** drivers (raw cold + warm + registry), so the old integrator obligation to wire a
-   * matching `CompactionDeps` is gone — the `remove()` and the force-compaction provably run over the same tiers.
-   * Requires the store built with a **raw cold driver + registry** (throws {@link UnsupportedError} otherwise;
-   * a pre-built `ColdChunkSource` store has no `IColdDriver` to compact through — use the `compactSegment` free
-   * function there). **One contract remains** (an integrator obligation the library cannot check): **do not
-   * concurrently re-add the same id while erasing it.** A normal `add(id)` landing between the `remove` and the
-   * compaction clears the tombstone and folds the id back into the new generation
-   * (`effective = (cold ∪ adds) \ removes`); `physicallyPurged` attests only that compaction committed a
-   * generation with the tombstones applied at pin time — quiesce writes for the subject during erasure.
-   *
-   * **A `physicallyPurged:false` entry means the logical removal holds but the physical purge didn't run this
-   * call** — either a daemon held a live lease (`note:'leased-by-other'`; the daemon finishes it), or the
-   * force-compaction hit an isolated fault (`note:'error: …'`; per-segment faults are caught so one segment
-   * can't discard the whole ledger). `physicallyPurged:false` is **conservative** (a concurrent daemon may
-   * already have purged the bit — `'clean'`). **Recovery:** follow up any `physicallyPurged:false` entry with
-   * `store.compact(ref)` (or let the daemon do it) — **re-running `eraseSubject` will NOT re-purge it**, because
-   * `has()` now reads false (the tombstone) so the segment is skipped as a non-member. The physical-purge proof
-   * is compaction's own VERIFY step (a re-`has()` here would be unsound: a pinned cold source can still read the
-   * old generation — take a fresh generation view after erasing, as with the daemon). Admin-only path;
-   * `O(registered segments)`, no hot-path cost. Per-subject crypto-shred is infeasible (a subject's bit is
+   * **Subject erasure (GDPR Art. 17): remove an id from every segment it's in, with the bit physically gone
+   * from the bucket on return.**
+   *
+   * For each **registered** segment the id is a member of, `eraseIdFromSegment` rewrites the current generation
+   * without the id — every chunk streamed through, one bit cleared — publishes the rewrite **fenced on the
+   * generation it was derived from**, and collects the generation that held the bit. A segment whose current
+   * generation does not hold the id is searched anyway, every generation in its bucket: a retained superseded one
+   * can still hold it, and so can one above the pointer after a {@link CloudRoaring.rollback}, which the rollback
+   * could make current again. Each holder is deleted — below the pointer by a `keep: 0` collection, above it one
+   * by one, re-proved against the row first — and the generations above the pointer that never held the id stay
+   * as rollback targets. An entry says `erased: true` only once the call has listed the bucket and read what is
+   * left: **no generation of the segment holds the id**. The returned per-segment record is your **erasure ledger** —
+   * persist it / route it to your audit sink as the proof of deletion (a `segment.rewrite` audit event is also
+   * emitted per rewrite when you pass `audit`).
+   *
+   * Uses the backend's **own** two halves, so the membership check and the rewrite provably run
+   * over the same generation. Requires the store built with a **backend** (throws
+   * {@link UnsupportedError} otherwise; a pre-built `StorageChunkSource` store has no `IStorageDriver` to write
+   * through; build the store on a backend instead).
+   *
+   * **One contract remains** (an integrator obligation the library cannot check): **do not load the segment
+   * while erasing from it.** A load that lands after the rewrite carries whatever its source held, and the
+   * library cannot know that source was meant to exclude the id. Quiesce loads of the affected segments for the
+   * duration, or fix the source first and load after. A writer that lands *during* the rewrite is caught: the
+   * rewrite's publish is refused **by the fence** — the publish lands its compare-and-swap only
+   * while the pointer is still on the generation the rewrite streamed — and the entry says `note: 'superseded'`,
+   * so re-run. Forward-only alone would NOT refuse it: the rewrite's number goes above everything in the bucket,
+   * so the rewrite would out-rank the newer generation and then collect it.
+   *
+   * A racing **erasure** is caught before that, and reported the same way. It collects with `keep: 0`, taking
+   * every generation below its new pointer — the one this rewrite is streaming, and the object this rewrite
+   * just wrote — so the loser can find its own inputs deleted mid-flight. That surfaces as an outcome rather than
+   * an error, read off the row: a moved pointer is a `'superseded'` entry, which a re-run settles, and a segment
+   * that a concurrent `dropSegment` tombstoned or a retention sweep purged is left out of the ledger, as a fresh
+   * call would leave it out.
+   *
+   * **Read `note` on any `erased: false` entry — the two reasons mean different things.** `'superseded'` means
+   * another writer (a load, another erasure, or a rollback) moved the pointer mid-call, so **this call** did not
+   * erase the id. Re-run: it erases the id if it is still there, and lists nothing for the segment if a racing
+   * erasure of the same id already removed it. Do not read `'superseded'` as "the id is still present" —
+   * read it as "not done by this call, and the re-run settles it".
+   * `` `error: …` `` is a per-segment fault (caught so one segment can't discard the whole ledger) and it can land
+   * on either side of the publish: if the rewrite had not published, the id is still there and a re-run erases
+   * it; if the publish succeeded and only the **collection** of the old generation failed, the id is already
+   * absent from every read and what remains is an object in the bucket that still contains the bit. The same
+   * note, after a publish, can mean a rollback moved the pointer back onto a generation that still holds the id
+   * while the collection ran — then the id is served again, and the entry says so rather than `erased: true`. A
+   * re-run searches every generation in the bucket, so it rewrites or collects what is left and usually reports
+   * `erased: true`; {@link SubjectErasureEntry.note} says what else a re-run can report. Re-running is otherwise safe
+   * and idempotent: a segment the id is no longer in is not listed. Admin-only path;
+   * `O(registered segments + superseded generations)`, no hot-path cost: a segment whose current generation lacks
+   * the id is searched generation by generation, one open for each other generation in its bucket, and with the
+   * keep-everything default of the `*Into` verbs that is one per generation the segment ever had. The per-op
+   * `budget` is charged one unit for each segment and one for each generation opened beyond the one its row names,
+   * so a fleet with long histories can exhaust it where the segment count alone would not. A segment that does is
+   * reported `erased: false` with an `error:` note, before it deletes anything (the one refusal that can come after a
+   * rewrite is the last check for a generation a concurrent writer left behind), and the
+   * rest of the scan continues: the call itself does not throw for it. Per-subject crypto-shred is infeasible (a subject's bit is
    * co-mingled in a shared container), so this is the single-subject erasure route; whole-segment/tenant erasure
-   * is 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"
     );
+    let opens = 0;
+    const charge = () => {
+      opens += 1;
+      checkBudget(budget, recs.length + opens, "eraseSubject");
+    };
     const entries = await mapWithConcurrency(
       recs,
       options.concurrency ?? DEFAULT_ADMIN_CONCURRENCY,
       async (rec) => {
         if (rec.status === "destroyed") return null;
         const ref = { segment: rec.segment, namespace: rec.namespace };
-        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,
+            budget === null ? deps : { ...deps, storage: new OpenChargingStorage(deps.storage, rec.currentGen, charge) },
+            { audit: options.audit }
+          );
+          if (result.reason === "not-member" || result.reason === "absent") return null;
+          if (result.reason === "no-generation") return null;
+          if (result.reason === "destroyed") return null;
           return {
             segment: rec.segment,
             namespace: rec.namespace,
-            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 {
+          }
         }
       }
     );
@@ -450,30 +987,179 @@ 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 registry read and one listing; 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 storage backend.
+   *
+   * ```ts
+   * if (!(await store.exists({ segment: 'users' }))) {
+   *   await store.load({ segment: 'users' }, idsFromUpstream);
+   * }
+   * ```
+   */
+  async exists(ref) {
+    validateSegmentRef(ref);
+    return segmentExists(ref, this.requireRegistry("exists"));
+  }
+  /**
+   * Every segment the registry knows about, streamed — optionally scoped to one namespace.
+   *
+   * The registry is already the list of your segments, which is why you should not keep a second one beside it:
+   * a hand-maintained list is a source of truth that drifts from this one the first time a load fails halfway.
+   *
+   * **An admin/discovery call, not a request-path one.** This is the registry's own enumeration — a paged
+   * LIST over the `registry/` prefix — so its cost grows with the size of the fleet rather than with what you
+   * are looking for.
+   *
+   * Scoping to a namespace narrows the LIST prefix, so it really is the difference between reading one tenant
+   * and reading all of them.
+   *
+   * It streams, and stopping the iteration stops the scan. It reads the registry directly and is not retried: a
+   * transient fault part-way through ends the loop with that error, and calling `segments()` again scans from the
+   * start.
+   *
+   * Yields `destroyed` tombstones and rows with `currentGen: null`, because a filtered enumeration that looks
+   * complete is worse than an honest one — filter on `status`/`currentGen` yourself, or ask
+   * {@link CloudRoaring.exists} the narrower question. Needs a storage backend.
+   *
+   * ```ts
+   * for await (const s of store.segments({ namespace: 'active-daily' })) {
+   *   console.log(s.segment, s.currentGen, s.status);
+   * }
+   * ```
+   */
+  segments(options = {}) {
+    if (options.namespace !== void 0) {
+      validateSegmentRef({ segment: "x", namespace: options.namespace });
+      refuseReservedNamespace(options.namespace);
     }
-    return 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. They remain until a load numbers above them
+   * (collection then keeps the newest `keep` of what is below its pointer), {@link CloudRoaring.dropSegment}
+   * deletes them, or {@link CloudRoaring.eraseSubject} does: all of those present when it rewrites, and only those holding
+   * the id when the current generation does not. An operator who has just undone a bad load should not have the
+   * evidence collected out from under them, while a rollback target that still holds erased data would make the
+   * erasure undoable.
+   *
+   * A target **above** the pointer needs `{ allowForward: true }`, and is refused with {@link ValidationError}
+   * without it: that is also where objects live that were never published, such as a load that wrote its object
+   * and died before the publish. Undoing an earlier rollback is what the opt-in is for.
+   *
+   * Needs a backend.
+   */
+  async rollback(ref, toGeneration, options = {}) {
+    validateSegmentRef(ref);
+    const deps = this.lifecycleDeps("rollback");
+    try {
+      return await rollbackSegment(ref, toGeneration, deps, options);
+    } finally {
+      this.engine.invalidate(ref);
+    }
+  }
+  /**
+   * **Replace this segment's contents** with `ids`, as one new immutable generation, and make it current.
+   *
+   * The whole write path in one call: take the next generation number, write the object, check the result is
+   * plausible, move the pointer, collect what the move superseded. Composed by hand those are four functions and
+   * the one that gets left out is the last, so segments quietly accumulate superseded generations nobody pays
+   * attention to and everybody pays for.
+   *
+   * ```ts
+   * const r = await store.load({ segment: 'audience:active' }, idsFromWarehouse, {
+   *   guard: { minRetained: 0.5 }, // refuse a load that would drop more than half the segment
+   * });
+   * if (!r.published) console.warn(`load refused: ${r.reason}`);
+   * ```
+   *
+   * **A load REPLACES.** Whatever the stream contains is what the segment contains afterwards, so an upstream
+   * query that returns fewer rows than usual is a shrink nobody asked for and an empty one is a wipe — both
+   * reported as a successful write, because at the storage layer they are one. That is what `guard` and the
+   * default empty refusal are for, and why they run **between** the write and the publish: the only moment where
+   * the new content is known and the old one is still authoritative.
+   *
+   * **Branch on `published`.** A refusal is a normal outcome, not an exception — `published: false` with a
+   * `reason`, in the same shape as a success — so a discarded result is a load that silently did nothing, and
+   * with the empty guard on by default this verb refuses more readily than any other. Note the sibling `*Into`
+   * verbs *throw* on the same superseded condition rather than reporting it; this one follows
+   * `eraseIdFromSegment` instead, because three of its four refusals are expected guard outcomes rather than
+   * faults.
+   *
+   * `'superseded'` means another writer got there first: another load took the same generation number, so this
+   * one wrote nothing (`size: 0`), or the segment's registry row changed while the load was writing — another load
+   * published, a retention change, a rollback or an erasure wrote the row, or the row was deleted.
+   *
+   * A refused load deletes the object it wrote before returning — it sits above `currentGen`, where generation
+   * collection deliberately never looks — but only while the segment's registry row is unchanged or gone. Once
+   * another write has changed the row, the generation number it holds may name another incarnation's live object,
+   * so it leaves the orphan rather than risk deleting live data. The orphan is an ordinary generation once a later
+   * one is current above it, and collection counts it within `keep`.
+   *
+   * What it **throws** for is a fault rather than an outcome: invalid options or ids, and a crypto-shredded
+   * segment (`ValidationError`); a key the keystore cannot provide (`KeyUnavailableError`); a current generation
+   * that will not open when a guard reads its size (`IntegrityError`); a driver failure; and a collection pass
+   * that could not prove the segment was still the same one (`WriteConflictError`). The last can be raised
+   * **after** the publish already landed, so a throw does not by itself mean the load did not take effect —
+   * re-read the pointer rather than assuming.
+   *
+   * Needs a backend (throws {@link UnsupportedError} otherwise).
+   */
+  async load(ref, ids, options = {}) {
+    validateSegmentRef(ref);
+    const deps = this.lifecycleDeps("load");
+    try {
+      return await loadSegment(ref, ids, deps, options);
+    } finally {
+      this.engine.invalidate(ref);
+    }
+  }
+  /**
+   * **Dispose of a segment — tombstone it, then delete its storage objects.** Irreversible.
    *
    * The operation a rolling window needs: `destroySegment` crypto-shreds (bytes unreadable everywhere including
    * backups, but still sitting in your bucket and still billed, and it requires encryption), while this one
@@ -485,7 +1171,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 });
    * }
@@ -495,29 +1182,32 @@ 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.
+   * 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 `coldGenTtlMs` (default 2 s), not instantly: a store that had already read this
-   * segment may answer from its cached generation + hot chunks until that window lapses. A reader that never
-   * touched it sees empty at once. **That bound needs a clock and `coldGenTtlMs > 0`** — a store built without a
-   * clock, or with `coldGenTtlMs: 0` ("pin forever"), holds its resolved snapshot for its own lifetime and can
-   * keep answering `true` for a dropped segment indefinitely; restart it.
+   * Reads become empty within `cache.genTtlMs` (default 2 s), not instantly: a store that had already read this
+   * segment may answer from its cached generation + cached chunks until that window lapses, or, while the registry
+   * cannot be read because of a transient fault, until a retry 500 ms apart reaches it again. A reader that never
+   * touched it sees empty at once. **That bound needs a registry and `cache.genTtlMs > 0`.** A store with no registry
+   * (a bare `IStorageDriver`), with `cache.genTtlMs: 0`, or on a storage source built with no clock, has no timed
+   * refresh. It notices the drop only when a read has to fetch
+   * from a deleted generation or its reader cache evicts the segment, and until then a chunk it has cached
+   * answers without reaching storage, so it can keep answering `true` for a dropped segment indefinitely. Tell
+   * it with {@link invalidate}, or restart it.
    *
-   * Needs the store built with a **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,
@@ -526,9 +1216,9 @@ var CloudRoaring = class {
    * no background thread (it has to work identically in a Lambda, an edge isolate and a long-lived server).
    *
    * `expiresAt` is an **absolute epoch-ms you compute**, not a duration the library derives. A relative TTL would
-   * have to be anchored to something the library knows — `updatedAt`, or the current generation — and compaction
+   * 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 the daemon is working.
+   * precisely because it is being reloaded.
    *
    * ```ts
    * const DAY = 86_400_000;
@@ -536,15 +1226,14 @@ var CloudRoaring = class {
    * await store.setRetention(ref, { expiresAt: Date.now() + 30 * DAY });
    * ```
    *
-   * **Works on an accumulator**, which is the whole point: a segment you created by writing to it has no
-   * registry row, so it is invisible to `registry.list()` and therefore to every fleet-wide operation, including
-   * the sweep. This call mints the row (`createdRow: true` in the result) with **no Cold generation**, so it
-   * becomes enumerable while every read still resolves exactly as before.
+   * **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.
+   * **seconds**, which would read as long-expired and retire the segment on the next pass. Needs a storage
+   * backend (throws {@link UnsupportedError} otherwise), and refuses a crypto-shredded segment.
    */
   async setRetention(ref, policy) {
     validateSegmentRef(ref);
@@ -573,17 +1262,17 @@ var CloudRoaring = class {
    * **Run the retention sweep: retire every segment whose `expiresAt` has passed.** This is the call that acts on
    * the policies `setRetention` records — and it is a **call, not a daemon**. Nothing schedules it; you run it from
    * whatever heartbeat your deployment already has (an EventBridge rule, a Kubernetes CronJob, a queue consumer,
-   * your compaction worker's loop). A library that started a timer would behave differently in a Lambda, an edge
+   * 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 Warm → registry → Cold ordering, the re-sweep for a
-   * generation staged by an in-flight compaction, and the `generationsRemaining` report all come from one
-   * implementation rather than two.
+   * 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})`);
+   * console.log(`would retire ${preview.wouldRetire} of ${preview.scanned} (limited: ${preview.limited})`);
    *
    * const swept = await store.retireExpired({ namespace: 'active-daily' });
    * for (const e of swept.entries) {
@@ -599,90 +1288,424 @@ var CloudRoaring = class {
    * sweep would leave the caller unable to say which segments were retired, having already retired some. (A bad
    * argument does throw, and so does a fleet larger than `maxScanSegments`.) `limited: true` means the per-cycle
    * `limit` (default 100) cut the pass short and more are eligible. That cap is charged on **attempts**, not
-   * successes, which is what makes it a real bound: `dropSegment` deletes Warm and writes the tombstone before
-   * sweeping Cold, so a fault in the Cold phase is a segment that is already retired. Retirements are sequential
-   * (~8 round trips each), so `limit` is a wall-clock knob too, and `retired` counts deletions only — a dry run
-   * reports `wouldRetire` instead, so a dashboard summing `retired` can never show a phantom deletion.
+   * 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 Warm rows and Cold generations are provably gone — collecting a straggler
-   * generation itself first, since nothing else ever would for a tombstoned segment. Attribution is a **positive
-   * marker the sweep stamps on its own retirements**, not an inference from "destroyed + an expired policy": a
-   * crypto-shred leaves `retention` untouched, so setting a policy and then honouring a right-to-erasure request
-   * mid-window produces exactly that row, and deleting it would destroy the Art. 17 attestation and un-fence the
-   * name. Pass `purgeTombstones: false` to keep every tombstone.
+   * and only once that segment's Storage generations are provably gone — collecting a straggler generation itself
+   * first, since nothing else ever would for a tombstoned segment. Attribution is a **positive marker the sweep
+   * stamps on its own retirements**, not an inference from "destroyed + an expired policy": a crypto-shred leaves
+   * `retention` untouched, so setting a policy and then honouring a right-to-erasure request mid-window produces
+   * exactly that row, and deleting it would destroy the Art. 17 attestation and un-fence the name. By default a
+   * segment that held nothing has its row deleted in the pass that retires it, since that row would only fence the name.
+   * Pass `purgeTombstones: false` to keep every tombstone, that row included.
    *
-   * Needs the store built with a **raw cold driver + a registry** (throws {@link UnsupportedError} otherwise),
-   * because retiring a segment deletes its Cold objects. `now` defaults to the store's clock.
+   * 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.compactionDeps();
-    return retireExpired(
-      { registry: deps.registry, warm: deps.warm, cold: deps.cold },
+    const deps = this.lifecycleDeps("retireExpired");
+    const result = await retireExpired(
+      { registry: deps.registry, storage: deps.storage },
       { ...options, now: options.now ?? this.clock.now() }
     );
+    if (options.dryRun !== true) {
+      for (const entry of result.entries) {
+        this.engine.invalidate({ segment: entry.segment, namespace: entry.namespace });
+      }
+    }
+    return result;
+  }
+  /**
+   * **Forget everything this store has cached about a segment.** Use it after destroying or retiring a segment
+   * through a path this store did not perform itself.
+   *
+   * A store keeps two layers of derived state — a resolved snapshot per segment (an open `.crbm` reader, plus
+   * the DEK it unwrapped) and decoded chunks keyed by generation. Both are built for one event: **a publish
+   * that advances `currentGen`**, which the snapshot TTL notices and the generation-keyed cache misses on.
+   * Neither notices an event that *destroys* what they were derived from.
+   *
+   * The store's own writes handle themselves: `load`, `rollback`, `eraseSubject`, `dropSegment` and `retireExpired`
+   * here, and a segment's `*Into` verbs, invalidate what they touch. This method is for the cases they cannot see:
+   *
+   * - **`destroySegment` / `eraseNamespace`**, which are free functions over raw drivers rather than methods
+   *   here, so a crypto-shred performed beside this store invalidates nothing in it. It keeps its open reader and
+   *   the unwrapped DEK, and decrypts with them, chunks it had never fetched before the shred included, until its
+   *   snapshot re-resolves: within `cache.genTtlMs` when the store has a registry and a `genTtlMs` above 0, and
+   *   otherwise only when its caches let the segment go or a read has to fetch from a generation a sweep collected.
+   *   A pin answers with no timed bound, until it is told or both caches let it go.
+   * - **Another process.** Erasing on one box invalidates nothing on the others; each store bounds its own
+   *   staleness by `cache.genTtlMs`, and a store with no registry (a bare `IStorageDriver`), with
+   *   `cache.genTtlMs: 0`, or on a storage source built with no clock has no bound at all: it converges only when a read happens to miss its caches. If a compliance deadline depends on every
+   *   reader converging, you need to signal them — this is the call to make when your own fan-out delivers.
+   *
+   * It also forgets any replacement this store found of a pin's object, so once it is called after a restore puts that
+   * object back, the pin reads it again.
+   *
+   * Synchronous, best-effort, and safe to call for a segment this store has never read.
+   *
+   * ```ts
+   * await destroySegment(ref, { registry: backend.registry }, { confirmSegment: ref.segment });
+   * store.invalidate(ref);                       // this process
+   * await bus.publish('cloudbitmaps.invalidate', ref); // and every other one
+   * ```
+   */
+  invalidate(ref) {
+    validateSegmentRef(ref);
+    refuseReservedNamespace(ref.namespace);
+    this.engine.invalidate(ref);
+  }
+  /**
+   * Build a handle held at the generation `ref` resolves to right now. See {@link Segment.pin}.
+   *
+   * The pinned handle gets its own engine but **shares the store's chunk cache**, under keys of its own: the
+   * pinned view reports the version captured at pin time, marked as a pin's, so its decoded chunks are never
+   * those of a live read that fetched across a publish (see {@link PinnedStorageChunkSource.currentVersion}).
+   */
+  async pinSegment(ref, expiresAt) {
+    const crbm = this.crbmSource;
+    if (crbm === void 0) {
+      throw new UnsupportedError(
+        "pin() needs the `.crbm` storage source \u2014 pass a backend or a raw IStorageDriver as `storage` (a pre-built StorageChunkSource that cannot resolve a generation has nothing to pin)"
+      );
+    }
+    const at = await this.withRetries(() => crbm.pinGeneration(ref));
+    const pinnedAt = {
+      generation: at?.generation ?? null,
+      version: at?.version ?? null,
+      fingerprint: at?.fingerprint ?? null
+    };
+    const pins = /* @__PURE__ */ new Map([[segmentKey(ref), pinnedAt]]);
+    return makeSegment({
+      engine: this.engineWithPins(pins),
+      ref,
+      clock: this.clock,
+      metrics: this.metrics,
+      materialize: (dest, ids, op, options) => this.materialize(dest, ids, op, options),
+      pinned: (r, e) => this.pinSegment(r, e),
+      combineEngine: (handles) => this.engineForCombine(handles),
+      expiresAt,
+      pinnedAt
+    });
+  }
+  /**
+   * An engine reading every segment in `pins` at its pinned generation and everything else live, with the store's
+   * retries, so a transient fault on a pinned read is retried as it would be on a live one.
+   *
+   * It **shares the store's chunk cache and its memory bound**, under keys of its own for each pinned segment.
+   */
+  engineWithPins(pins) {
+    const crbm = this.crbmSource;
+    if (crbm === void 0) {
+      throw new UnsupportedError(
+        "pin() needs the `.crbm` storage source \u2014 pass a backend or a raw IStorageDriver as `storage` (a pre-built StorageChunkSource that cannot resolve a generation has nothing to pin)"
+      );
+    }
+    const pinned = new PinnedStorageChunkSource(crbm, pins);
+    return new SegmentEngine({
+      storage: this.retryOptions === void 0 ? pinned : new RetryingStorageChunkSource(pinned, this.retryOptions),
+      cache: this.cache,
+      codec: roaringCodec,
+      clock: this.clock,
+      metrics: this.metrics,
+      budget: this.budget
+    });
+  }
+  /**
+   * The engine a combine should run on, given the handles involved.
+   *
+   * A pinned handle passed as an **operand** must still be read at its pin. Routing by "which handle the call
+   * was made on" reads it live instead — `snap.intersect([other])` honours the pin while
+   * `other.intersect([snap])` silently does not, and the two are the same question. So the combine collects
+   * every pin in play and runs on an engine that honours all of them. With no pins anywhere this is the
+   * store's own engine and costs nothing.
+   *
+   * One engine reads a segment at one generation, so a combine that holds the same segment at two — two pins of
+   * it, or a pin and a live handle — is refused. Keeping one of them would answer the question for the wrong
+   * instant, and say nothing: diffing two snapshots of a segment returned no ids at all.
+   */
+  engineForCombine(handles) {
+    if (!handles.some((h) => h.pinnedAt !== void 0)) return void 0;
+    const pins = /* @__PURE__ */ new Map();
+    const held = /* @__PURE__ */ new Map();
+    for (const h of handles) {
+      const key = h.key();
+      const at = h.pinnedAt;
+      if (held.has(key)) {
+        const before = held.get(key);
+        if (!samePin(before, at)) {
+          throw new ValidationError2(
+            `the same segment is in this combine twice, ${twoPins(before, at)}: one call reads a segment at one generation, so materialise one of them into a segment of its own first, with \`intersectInto(dest, [])\``
+          );
+        }
+      } else {
+        held.set(key, at);
+      }
+      if (at !== void 0) pins.set(key, at);
+    }
+    return this.engineWithPins(pins);
+  }
+  /** `op` under the store's retries, as the store's own reads run; bare when the store has retries off. */
+  withRetries(op) {
+    const r = this.retryOptions;
+    return r === void 0 ? op() : withRetry(op, r.policy ?? DEFAULT_RETRY_POLICY, r);
   }
   /** The store's registry, or a typed error naming the operation that needs one. */
   requireRegistry(op) {
     if (this.registry === void 0) {
-      throw new UnsupportedError(`${op} needs a \`registry\` in the store config`);
+      throw new UnsupportedError(
+        `${op} needs a storage backend \u2014 S3Storage, GcsStorage, AzureBlobStorage, LocalFsStorage or MemoryStorage. A bare IStorageDriver has no generation pointer to publish through, and there is no separate \`registry\` option: a backend carries it.`
+      );
     }
     return this.registry;
   }
   /**
-   * **Cross-tier DR consistency check (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,
+   * errored }` — `inconsistent` empty ⇒ coherent; otherwise it names the segments to recover (restore the object
+   * store, or roll the registry back to a coherent point). Needs the store built with a **backend**
+   * (throws {@link UnsupportedError} otherwise). `destroyed` (crypto-shredded) segments are skipped. Pair it with
+   * the DR runbook (docs/guide/disaster-recovery.md).
+   *
+   * It holds the registry rows it enumerates resident, at most 250,000 of them, and throws
+   * `BudgetExceededError` past that rather than report a partial scan as a whole one. This method takes no
+   * ceiling of its own: narrow the scan with `namespace`, or call `runConsistencyCheck` over the backend's
+   * `storage` and `registry` with a higher `maxScanSegments`.
    */
   async checkConsistency(options = {}) {
-    const deps = this.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 = {}) {
     const registry = this.requireRegistry("exportSegments");
-    return runExport$1(this, registry, sink, {
+    return runExport(this, registry, sink, {
       ...options,
       codec: options.codec ?? roaringCodec
     });
   }
   /**
-   * Planning cost estimate (Phase 5b) — pure, no instance/data needed: sizing, sales, what-if. For a real,
-   * grounded report from live segment sizes, use `store.segment(name).costReport()`. See {@link CostReport}.
+   * 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 Segment = class {
-  constructor(engine, ref, clock, metrics) {
-    this.engine = engine;
-    this.ref = ref;
-    this.clock = clock;
-    this.metrics = metrics;
-    this.metricsOn = metrics !== NOOP_METRICS;
+var failing = (err) => ({
+  [Symbol.asyncIterator]: () => ({ next: () => Promise.reject(err) })
+});
+var samePin = (a, b) => a === void 0 || b === void 0 ? a === b : a.generation === b.generation && a.fingerprint === b.fingerprint;
+var twoPins = (a, b) => {
+  const one = (p) => p === void 0 ? "live" : `pinned at generation ${p.generation ?? "none"}`;
+  return a !== void 0 && b !== void 0 && a.generation === b.generation ? `pinned twice at generation ${a.generation ?? "none"}, as two different objects` : `${one(a)} and ${one(b)}`;
+};
+var rangeOf = (options) => ({
+  after: options.after,
+  through: options.through
+});
+var readOptions = (options) => ({
+  ...rangeOf(options),
+  concurrency: options.concurrency,
+  budget: options.budget,
+  allowAbsentOperands: options.allowAbsentOperands
+});
+var NO_SEGMENTS = [];
+var EMPTY_IDS = {
+  async *[Symbol.asyncIterator]() {
   }
+};
+var KEEP_EVERY_GENERATION = Number.MAX_SAFE_INTEGER;
+var makeSegment;
+var minting = false;
+var Segment = class _Segment {
+  metricsOn;
   engine;
   ref;
   clock;
   metrics;
-  metricsOn;
+  materialize;
+  pinned;
+  combineEngine;
+  /** Absolute epoch-ms deadline from {@link SegmentOptions.expiresAt}; `undefined` ⇒ this handle never expires. */
+  expiresAt;
+  /**
+   * The generation this handle is held at, when it came from {@link Segment.pin}. Read by the store so a
+   * pinned handle passed as an **operand** is still read at its pin rather than live.
+   */
+  pinnedAt;
+  static {
+    makeSegment = (parts) => {
+      minting = true;
+      try {
+        return new _Segment(parts);
+      } finally {
+        minting = false;
+      }
+    };
+  }
+  /**
+   * Not constructible: a handle comes from {@link CloudRoaring.segment}, which wires it to the store's engine,
+   * caches and write path. The constructor takes those internals, so it is not part of the surface.
+   */
+  constructor(parts) {
+    if (!minting) {
+      throw new ValidationError2(
+        "a Segment is not constructed directly; call `store.segment(name)`"
+      );
+    }
+    this.engine = parts.engine;
+    this.ref = parts.ref;
+    this.clock = parts.clock;
+    this.metrics = parts.metrics;
+    this.materialize = parts.materialize;
+    this.pinned = parts.pinned;
+    this.combineEngine = parts.combineEngine;
+    this.expiresAt = parts.expiresAt;
+    this.pinnedAt = parts.pinnedAt;
+    this.metricsOn = parts.metrics !== NOOP_METRICS;
+  }
+  /**
+   * **Hold this segment at the generation that is current right now**, for as long as you keep the handle.
+   *
+   * An ordinary handle re-resolves on `cache.genTtlMs`, so a publish part-way through a long job means its second
+   * half describes a different instant than its first — every chunk whole and verified, but the answer covering
+   * two moments, with nothing in the result saying so. That is fine for a dashboard and wrong for an export, a
+   * reconciliation, or a send that has to match the count you reported. A pin is how you get one instant.
+   *
+   * ```ts
+   * const snap = await store.segment('active-30d').pin();
+   * const total = await snap.count();            // the number you report
+   * for await (const id of snap.iterate()) { … } // …and the ids it counted, however long this takes
+   * ```
+   *
+   * **Only this segment is pinned.** `snap.intersect([other])` reads `snap` at its pinned generation and
+   * `other` at whatever is current — pin each segment if you want the whole query held. And a pinned handle
+   * used as an *operand* is still read at its pin, never live.
+   *
+   * **One call reads a segment at one generation**, so a combine that holds this segment at two —
+   * `snap0.andNot([snap1])`, or `live.intersect([snap])` — throws {@link ValidationError} when it is read, and an
+   * `*Into` of one throws before it reads anything. Materialise one side first, with `intersectInto(dest, [])`.
+   *
+   * **A pin knows its object, not only its number.** A name purged and loaded again starts again at generation
+   * 0, so a pin of the old segment never reads the new one: what it has already read still answers, as the
+   * instant it pinned, and anything it would have to fetch fails with `NotFoundError`, as a swept pin's does.
+   *
+   * **It is a hold, not a lease.** Nothing here stops a collection deleting the generation underneath
+   * you: a pinned read deliberately does **not** heal forward, because silently serving a different generation
+   * is the one thing a pin exists to prevent, so it fails instead. Size `keep` to cover your longest pinned
+   * job — see [Generations and `keep`](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/loading.md#generations-and-keep) — or take the pin on a segment
+   * you are not collecting.
+   *
+   * A segment with no current generation pins nothing and reads empty, exactly as it would unpinned. A pinned
+   * segment whose row is later dropped or destroyed fails once it must open its object again, rather than go empty
+   * part-way through a call. **A pin
+   * keeps the key its reader unwrapped for as long as that reader stays open, and answers from the chunks it
+   * decoded for as long as they stay cached.** This store invalidates a pin:
+   *
+   * - a `load`, a `rollback` or an `*Into` invalidates a pin of the segment it writes;
+   * - `dropSegment` invalidates a pin of the segment it drops, and `retireExpired` a pin of each segment its ledger
+   *   lists, retired or not, neither on a dry run;
+   * - `eraseSubject` invalidates a pin of each segment it scans that is not already destroyed.
+   *
+   * An invalidated pin opens its object again, and fails if that object is gone or replaced, or its row is gone or
+   * destroyed.
+   * Anything else leaves the pin as it is: after a `destroySegment` beside this store, or an erasure, a drop or a
+   * retirement through another store, in this process or another, the pin answers from what it holds until this
+   * store's reader cache evicts the pin's reader and its chunk cache evicts the chunks the pin decoded, or
+   * {@link CloudRoaring.invalidate} is called on this store. Where the
+   * object the pin reads has been deleted, by an erasure, a drop or a sweep, a chunk the pin has not cached fails at
+   * once. No timed refresh bounds any of that, as none bounds anything else a pin holds.
+   *
+   * A replacement a pin has found is remembered, so its later chunk reads fail with no request, until the store
+   * forgets it: an invalidation of the segment does, as does a later `pin()` of the same version that opens the object
+   * again, and the store remembers at most `cache.readerMax` of them. So once a restore puts the pinned object back,
+   * call {@link CloudRoaring.invalidate} on this store: the pin then reads the object again.
+   *
+   * `pin()` reads the registry row and opens the generation at once, so the pin knows its object before its first
+   * read. With a registry, pins of one generation taken while its row is unchanged share one reader while the store
+   * keeps it open, pins taken at the same moment included: the first costs a tail read, and a key unwrap for an
+   * encrypted segment, whether or not it is read, and the rest cost the row read alone. Without a registry every
+   * `pin()` lists the segment's objects and makes the tail read, since only the object can tell two incarnations of
+   * a name apart there. It retries a
+   * transient fault as the store's reads do, and heals a generation swept between the two, but it fails where the
+   * generation cannot be opened: `NotFoundError` for a pointer at a missing object, `IntegrityError` for a damaged
+   * or misfiled one.
+   *
+   * Needs a store built on the `.crbm` storage source (the default when you pass a backend or a raw driver). Throws
+   * {@link UnsupportedError} on a store wired with a pre-built source that cannot pin.
+   */
+  async pin() {
+    return this.pinned(this.ref, this.expiresAt);
+  }
+  /**
+   * An opaque string that names this handle's segment, namespace included: two handles of one segment have the
+   * same key, a live handle and its pins among them. Use it as a `Map` key or a log field when you track handles
+   * and have not kept the name you made them with. The format is not specified and is not a storage key, so
+   * compare keys, never parse one.
+   */
+  key() {
+    return segmentKey(this.ref);
+  }
+  /**
+   * Has this handle's deadline passed? **The lazy half of expiry** — the whole check is one comparison against
+   * the injected clock, so it costs nothing on a handle with no deadline and no I/O on one that has expired.
+   *
+   * Deliberately evaluated per call rather than cached: a long-lived handle created before its deadline must
+   * start reading empty the moment the deadline passes, without the caller re-creating it.
+   */
+  expired() {
+    return this.expiresAt !== void 0 && this.clock.now() >= this.expiresAt;
+  }
+  /**
+   * Refuse a materialisation that involves an **expired** handle. Called by the three `*Into` verbs only.
+   *
+   * On the read verbs an expired handle answers empty, which is the point of lazy expiry. On a *write* the same
+   * rule would be destructive in a way nobody asks for: `a.intersectInto(dest, [b])` where `b`'s deadline has
+   * quietly passed would, unrefused, replace `dest` with an **empty generation** — a wipe, reported as a successful
+   * write, with the cause (a deadline on a handle somewhere) nowhere in the result. Reads degrade to empty; writes must not.
+   *
+   * So every handle in the call is checked, `dest` included: an expired `dest` does not change the bytes written,
+   * but a caller who put a deadline on the thing they are writing into has said something contradictory and is
+   * better told than guessed at. Open a handle without `expiresAt` to write, or drop the deadline.
+   *
+   * (The broader guard — refusing to publish an empty or implausible generation over a non-empty one, with an
+   * `allowEmpty` override — covers these verbs too: they route through the same guarded write path as
+   * {@link CloudRoaring.load}. The two stay separate because they differ in kind. That one is a REPORTED
+   * refusal a caller may legitimately override; an expired handle is a wiring mistake, so it THROWS, before
+   * any object is written — and `allowEmpty: true` does not reach it.)
+   *
+   * The verbs are `async` so this surfaces as a **rejected promise**, like every other validation in the facade —
+   * a synchronous throw out of a promise-returning method escapes a caller who attached `.catch()` instead of
+   * awaiting.
+   */
+  refuseIfExpired(op, dest, operands) {
+    const stale = [];
+    for (const seg of [this, dest, ...operands]) {
+      if (seg.expired())
+        stale.push(seg.ref.namespace ? `${seg.ref.namespace}/${seg.ref.segment}` : seg.ref.segment);
+    }
+    if (stale.length > 0) {
+      throw new ValidationError2(
+        `${op}: refusing to publish a generation while these handles have expired \u2014 ${[...new Set(stale)].join(", ")}. An expired handle reads as empty, so this would write an empty (or short) generation over "${dest.ref.segment}". Open the handles without \`expiresAt\` if you meant to materialise, or drop the deadline.`
+      );
+    }
+  }
   /**
    * Time an op with the injected clock and emit an `op` metric on completion (success or throw). Skipped
    * entirely when no sink is wired, so the default path pays nothing.
@@ -696,104 +1719,122 @@ var Segment = class {
       this.metrics.onEvent({ kind: "op", name, ms: Math.max(0, this.clock.now() - startedAt) });
     }
   }
-  /** Add an id (integer in `[0, 2^32)`). Throws {@link ValidationError} on a bad id. */
-  add(id) {
-    return this.timed("add", () => this.engine.add(this.ref, id));
+  /** 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));
   }
   /**
-   * Add many ids, from a **sync or async** iterable. Not atomic across chunks — see the class note.
-   *
-   * An async source means a database cursor streams straight in — `addMany(athenaCursor())` rather than
-   * hand-batching `page → addMany(page)`. Ids are grouped by chunk and each chunk is written **exactly once**,
-   * however long the stream: pending ids are held compressed, not buffered-and-flushed, so a long stream costs
-   * no more backend writes than a short one. Peak memory is the roaring representation of the ids you pass.
+   * Cardinality — summed from the `.crbm` index with **zero payload reads** on a loaded segment.
    *
-   * **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.
+   * What this trusts: the answer is the sum of the per-chunk cardinalities the index records, and no payload is
+   * decoded to confirm it. The index is checked for internal consistency when the object is opened (each key in
+   * range and ascending, each cardinality in `1..65536`, each payload inside the payload region, and, on an
+   * unencrypted object, the footer's chunk count and total agreeing with the index), and a corrupt index that is
+   * still internally consistent yields a wrong count. `iterate()` and the combines decode the payloads, whose
+   * structure is checked.
    */
-  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));
+  count() {
+    if (this.expired()) return Promise.resolve(0);
+    return this.timed("count", () => this.engine.count(this.ref));
   }
   /**
-   * **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.
+   * Every id, ascending, streamed one chunk at a time. Pass a range to read part of the segment: the ids in
+   * `(after, through]`, fetching only the chunks the range overlaps. The per-op budget is charged for every chunk in
+   * the range, so give a page `through` as well as `after`. On a pinned handle it reads the pinned generation, as a
+   * full read does.
    *
    * ```ts
-   * 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
+   * // Keyset paging: each page resumes where the one before ended, and stops at its window's end.
+   * for await (const id of seg.iterate({ after: previousEnd, through: windowEnd })) await send(id);
    * ```
    *
-   * **Pass a batch, not one id.** A Warm write rewrites a whole 64K-id chunk bitmap, so claiming ids one at a
-   * time is the single most expensive way to use this library — measured at ~5,000 writes and ~23 MB for 5,000
-   * ids, against 1 write and ~8 KB for the same ids in one call. This method does one OCC read-modify-write per
-   * distinct chunk, giving you Redis's *semantics* without Redis's per-id *cost shape*.
-   *
-   * **Exactly-once holds per id**, which is the guarantee that matters: each id lives in one chunk, a chunk is
-   * one OCC row, so exactly one concurrent claimer sees any given id as new. Like `addMany` it is **not** atomic
-   * across chunks — a mid-flight failure can leave some chunks claimed — but re-running is safe, because
-   * already-claimed ids simply come back as not-new.
-   *
-   * Order of the returned ids is unspecified.
+   * Each bound is optional and an integer in `0..4294967295`; a bad one throws {@link ValidationError} when the
+   * stream is first read. `after >= through` is an empty range, which reads nothing. An expired handle reads empty
+   * without checking its options, as every read of one does.
    */
-  claimMany(ids) {
-    return this.timed("claimMany", () => this.engine.claimMany(this.ref, ids));
+  iterate(options) {
+    if (this.expired()) return EMPTY_IDS;
+    const range = options == null ? void 0 : rangeOf(options);
+    const none = range === void 0 || range.after === void 0 && range.through === void 0;
+    return this.engine.iterate(this.ref, none ? void 0 : range);
   }
-  has(id) {
-    return this.timed("has", () => this.engine.has(this.ref, id));
-  }
-  count() {
-    return this.timed("count", () => this.engine.count(this.ref));
+  /**
+   * The options a combine hands the engine, read once, when it is called ({@link readOptions}), with the `exclude`
+   * it was given, already reduced to its live handles ({@link liveExcludes}) and mapped down to the plain refs
+   * `core` takes. A method rather than a module function because `ref` is class-private — the encapsulation is
+   * worth more than the free function.
+   *
+   * Each field is named rather than copied with a rest spread: a rest copy takes only own enumerable properties, so
+   * a bound held in a getter or inherited from a prototype was dropped, and the read silently widened to the whole
+   * segment.
+   */
+  refsIn(options, exclude) {
+    if (options == null) return void 0;
+    return {
+      ...readOptions(options),
+      exclude: exclude.length > 0 ? exclude.map((o) => o.ref) : void 0
+    };
   }
-  iterate() {
-    return this.engine.iterate(this.ref);
+  /**
+   * The handles in `options.exclude` that have not expired. **An expired exclusion excludes nothing**, in every
+   * combine, so it is dropped here, before the engine is asked for anything: it is never fetched, never
+   * checked for absence, and never counted in the pin-consistency check. `exclude` is read once, so a getter sees
+   * one call.
+   *
+   * With no `exclude` this is one property read and a shared empty list, and with none expired it returns the
+   * caller's own array, so the common case allocates nothing.
+   */
+  liveExcludes(options) {
+    const exclude = options?.exclude;
+    if (exclude == null || exclude.length === 0) return NO_SEGMENTS;
+    return exclude.some((e) => e.expired()) ? exclude.filter((e) => !e.expired()) : exclude;
   }
   /**
    * Chunk-skipping intersection: stream the ids in **this** segment AND every segment in `others`, ascending.
-   * Fetches only the 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
+   * 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. (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.
+   * 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).
    */
-  refsIn(options) {
-    if (options === void 0) return void 0;
-    const { exclude, ...rest } = options;
-    return exclude === void 0 ? rest : { ...rest, exclude: exclude.map((o) => o.ref) };
-  }
   intersect(others, options) {
-    return this.engine.intersect([this.ref, ...others.map((o) => o.ref)], this.refsIn(options));
+    if (this.expired() || others.some((o) => o.expired())) return EMPTY_IDS;
+    const exclude = this.liveExcludes(options);
+    let engine;
+    try {
+      engine = this.combineEngine([this, ...others, ...exclude]) ?? this.engine;
+    } catch (err) {
+      return failing(err);
+    }
+    return engine.intersect([this.ref, ...others.map((o) => o.ref)], this.refsIn(options, exclude));
   }
   /**
-   * Materialize `this ∩ others…` (minus `exclude`) **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
+   * as a load is (the pointer advances to it, fenced on the row), so readers of `dest` see either the old generation
+   * or the new one, never a partial. Needs the
+   * store built with a backend (throws {@link UnsupportedError} otherwise).
+   *
+   * **An empty result does NOT overwrite a non-empty destination.** A combine that comes out empty is far more
+   * often a mistake upstream — a typo'd operand, an `exclude` that swallowed everything, an operand that has
+   * not loaded yet — than an intent, and once it publishes it is indistinguishable from a correct run. So the
+   * write is **refused and reported**: `published: false`, `reason: 'empty'`, and `dest` keeps what it had.
+   * Pass `allowEmpty: true` when emptying the destination is the point.
+   *
+   * `guard` adds the same plausibility bounds `load()` takes — `minCardinality` and `minRetained` — judged
+   * against what `dest` held before. A refusal is **reported, not thrown**, exactly as on `load()`; branch on
+   * `published`. A lost race is the one outcome that still throws ({@link WriteConflictError}), because a
+   * materialisation that silently did not take effect is the one thing a caller cannot detect on its own.
+   *
+   * A call involving an **expired handle** is refused before any of this. See {@link refuseIfExpired}.
    */
-  intersectInto(dest, others, options) {
+  async intersectInto(dest, others, options) {
+    this.refuseIfExpired("intersectInto", dest, [...others, ...options?.exclude ?? []]);
+    this.combineEngine([this, ...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)
     );
   }
   /**
@@ -804,20 +1845,35 @@ 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 exclude2 = this.liveExcludes(options);
+      return exclude2.length > 0 ? this.andNot([...exclude2], options) : this.union([], options);
+    }
+    if (live.length !== others.length) return this.union(live, options);
+    const exclude = this.liveExcludes(options);
+    let engine;
+    try {
+      engine = this.combineEngine([this, ...others, ...exclude]) ?? this.engine;
+    } catch (err) {
+      return failing(err);
+    }
+    return engine.union([this.ref, ...others.map((o) => o.ref)], this.refsIn(options, exclude));
   }
-  /** Materialize `this ∪ others…` (minus `exclude`) **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 ?? []]);
+    this.combineEngine([this, ...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)
     );
   }
   /**
@@ -828,48 +1884,99 @@ var Segment = class {
    * suppression list: at most one read per surviving key of `this`, so subtracting a 61,000-chunk global
    * opt-out list from a 40-chunk audience costs at most 40 reads, not 61,000.
    *
+   * An expired handle in `excludes` excludes nothing, and is skipped without being read; if every one has
+   * expired the result is `this` whole. An expired `this` is empty. `exclude` on `intersect` and `union` follows
+   * the same rule.
+   *
    * To filter the *result of an intersection*, do not chain — pass `exclude` to {@link intersect} instead, so
    * the suppression folds into the same pass rather than materializing an intermediate segment first.
    */
   andNot(excludes, options) {
-    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.union([], options == null ? void 0 : readOptions(options));
+    }
+    if (liveExcludes.length !== excludes.length) return this.andNot(liveExcludes, options);
+    let engine;
+    try {
+      engine = this.combineEngine([this, ...excludes]) ?? this.engine;
+    } catch (err) {
+      return failing(err);
+    }
+    return engine.andNot(
       this.ref,
       excludes.map((o) => o.ref),
-      options
+      options == null ? void 0 : readOptions(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);
+    this.combineEngine([this, ...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. The pointer refresh is priced at the store's own `cache.genTtlMs`, or at none when the store never
+   * refreshes, unless the workload sets `genTtlMs`. See {@link CostReport} — it always includes a verdict (incl.
+   * the lose-zone).
    */
   async costReport(options) {
-    const canMeasure = this.engine.supportsColdSize;
+    const canMeasure = this.engine.supportsStorageSize;
     const size = canMeasure ? await this.engine.segmentSize(this.ref) : null;
+    const refreshMs = this.engine.pointerRefreshMs;
+    const workload = refreshMs === void 0 || options?.workload?.genTtlMs !== void 0 ? options?.workload : { ...options?.workload, genTtlMs: refreshMs };
     return groundedReport({
-      coldBytes: size?.sizeBytes ?? 0,
+      storageBytes: size?.sizeBytes ?? 0,
       grounded: canMeasure,
-      workload: options?.workload,
-      topology: options?.topology,
+      workload,
       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.9.0";
-
-export { CloudRoaring, SafeBitmap, Segment, VERSION, bulkLoadCrbmGeneration, compactSegment, roaringCodec, runCompactionCycle, runExport };
+export {
+  AWS_US_EAST_1_ONDEMAND,
+  BudgetExceededError,
+  BufferReader,
+  CapabilityError,
+  CloudRoaring,
+  CloudRoaringError,
+  CountingMetricsSink,
+  CrbmReader,
+  CrbmStorageChunkSource2 as CrbmStorageChunkSource,
+  DEFAULT_RETRY_POLICY2 as DEFAULT_RETRY_POLICY,
+  ELASTICACHE_REDIS_US_EAST_1_ONDEMAND,
+  InProcessKeystore,
+  IntegrityError3 as IntegrityError,
+  KeyUnavailableError,
+  LocalFsStorage,
+  MIN_EXPIRES_AT_MS2 as MIN_EXPIRES_AT_MS,
+  MemoryStorage,
+  NodeAead,
+  NotFoundError,
+  ONE_REDIS_HA_CLUSTER,
+  RecordingAuditSink,
+  Segment,
+  TransientError,
+  UnsupportedError2 as UnsupportedError,
+  ValidationError3 as ValidationError,
+  WriteConflictError2 as WriteConflictError,
+  aadFor,
+  destroySegment,
+  eraseNamespace,
+  excludingReservedRows2 as excludingReservedRows,
+  isCloudRoaringError,
+  isIntegrityError,
+  isNotFoundError,
+  isTransientError,
+  isValidationError,
+  isWriteConflictError,
+  readRetentionPolicy
+};
 //# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map