@cloudbitmaps/roaring 0.10.0 → 0.11.1

package/dist/index.js

@@ -6,44 +6,251 @@ import {
   CrbmStorageChunkSource,
   DEFAULT_BUDGET,
   DEFAULT_RETRY_POLICY,
+  withRetry,
   isStorageBackend,
   NOOP_METRICS,
   RetryingStorageChunkSource,
   SegmentEngine,
   UnsupportedError,
-  ValidationError,
+  ValidationError as ValidationError2,
   WriteConflictError,
   MIN_EXPIRES_AT_MS,
+  checkBudget,
   collectWithinBudget,
   excludingReservedRows,
   dropSegment,
+  eraseIdFromSegment,
   estimateCost,
   groundedReport,
+  loadSegment,
   mapWithConcurrency,
   resolveBudget,
   resolvePerOpBudget,
   retireExpired,
   runConsistencyCheck,
-  runExport as runExport2,
+  runExport,
   setSegmentRetention,
   clearSegmentRetention,
   getSegmentRetention,
   safeMetrics,
-  splitId,
-  validateSegmentRef
+  splitId
 } from "@cloudbitmaps/core";
+import { validateSegmentRef } from "@cloudbitmaps/core/driver-kit";
 
-// src/codec-bound.ts
-import {
-  bulkLoadCrbmGeneration as coreBulkLoad,
-  eraseIdFromSegment as coreEraseIdFromSegment,
-  loadSegment as coreLoadSegment,
-  runExport as coreRunExport
-} from "@cloudbitmaps/core";
+// 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;
@@ -57,18 +264,24 @@ var SafeBitmap = class _SafeBitmap {
     return new _SafeBitmap(new RoaringBitmap32(values));
   }
   /**
-   * Validate size, then deserialize with the **portable** (validated) format.
-   * Throws `IntegrityError` if the input exceeds `maxBytes` or fails to decode — the
-   * native addon is never handed unbounded or unsafe-format input.
+   * 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() {
@@ -96,8 +309,10 @@ var SafeBitmap = class _SafeBitmap {
     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();
@@ -172,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
@@ -196,65 +411,54 @@ var SystemClock = class {
   }
 };
 
-// src/codec-bound.ts
-var bulkLoadCrbmGeneration = (driver, key, ids, options = {}) => coreBulkLoad(driver, key, ids, {
-  ...options,
-  codec: options.codec ?? roaringCodec,
-  clock: options.clock ?? new SystemClock()
-});
-var eraseIdFromSegment = (ref, id, deps, options) => coreEraseIdFromSegment(
-  ref,
-  id,
-  { ...deps, codec: deps.codec ?? roaringCodec, clock: deps.clock ?? new SystemClock() },
-  options
-);
-var runExport = (reader, registry, sink, options = {}) => coreRunExport(reader, registry, sink, { ...options, codec: options.codec ?? roaringCodec });
-var loadSegment = (ref, ids, deps, options = {}) => coreLoadSegment(
-  ref,
-  ids,
-  { ...deps, codec: deps.codec ?? roaringCodec, clock: deps.clock ?? new SystemClock() },
-  options
-);
-
-// src/index.ts
-import { listGenerations, rollbackSegment } from "@cloudbitmaps/core";
-import { listSegments, segmentExists } from "@cloudbitmaps/core";
-
-// src/moved-options.ts
-var MOVED_OPTIONS = [
-  ["cacheMaxChunks", "cache.maxChunks", "group"],
-  ["cacheTtlMs", "cache.ttlMs", "group"],
-  // The `cold*` spellings are what `0.9.x` ACTUALLY had. The `storage*` ones below never appeared in any
-  // release — they existed between two unreleased commits of this cycle — and for a while they were the only
-  // ones here, so the guard written to catch an upgrader missed every real upgrader and caught nobody.
-  ["coldGenTtlMs", "cache.genTtlMs", "group"],
-  ["coldReaderCacheMax", "cache.readerMax", "group"],
-  ["coldReaderCacheMaxBytes", "cache.readerMaxBytes", "group"],
-  ["storageGenTtlMs", "cache.genTtlMs", "group"],
-  ["storageReaderCacheMax", "cache.readerMax", "group"],
-  ["storageReaderCacheMaxBytes", "cache.readerMaxBytes", "group"],
-  ["keystore", "encryption.keystore", "group"],
-  ["requireEncryption", "encryption.required", "group"],
-  ["onRetry", "retry.onRetry", "group"],
-  ["clock", "seams.clock", "group"],
-  ["rng", "seams.rng", "group"],
-  [
-    "registry",
-    "the backend passed as `storage` (S3Storage, GcsStorage, \u2026), which carries it",
-    "renamed"
-  ],
-  ["cold", "storage", "renamed"],
-  // The live (warm) tier and its knobs. `warm` was REQUIRED in `0.9.x`, so every upgrader passes one — and
-  // an upgrader who fixes `cold` first meets this next. None has a successor, so none is offered.
-  ["warm", "the live tier is gone", "gone"],
-  ["warmReadConsistency", "it tuned the live tier", "gone"],
-  ["maxWarmScanBytes", "it tuned the live tier", "gone"],
-  ["writeConcurrency", "it bounded the live tier\u2019s flusher", "gone"],
-  ["occBackoff", "it tuned the live tier\u2019s read-modify-write", "gone"]
-];
+// src/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
-export * from "@cloudbitmaps/core";
+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() {
@@ -265,12 +469,13 @@ 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`
     );
   }
@@ -278,7 +483,7 @@ function requireScope(options, op) {
 function resolveStorageSource(options, clock) {
   const storage = options.storage;
   if (storage === null || typeof storage !== "object") {
-    throw new ValidationError(
+    throw new ValidationError2(
       "`storage` must be a StorageBackend, an IStorageDriver, or a StorageChunkSource"
     );
   }
@@ -288,15 +493,15 @@ function resolveStorageSource(options, clock) {
   const hasPutImmutable = typeof storage.putImmutable === "function";
   const isBackend = isStorageBackend(storage);
   if (isBackend && (hasGetChunk || hasPutImmutable)) {
-    throw new ValidationError(
+    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 ValidationError(
-      "`storage` looks like a driver that also carries a `registry`. Passed as a bare driver it would have no pointer at all \u2014 generations would resolve by list-scan, so reads could serve a generation that was written but never published. If you meant a backend, say so: `createBackend({ storage: <your driver>, registry })`."
+    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) {
@@ -304,12 +509,12 @@ function resolveStorageSource(options, clock) {
     const registryOk = typeof asBackend.registry.compareAndSwap === "function";
     if (!storageOk || !registryOk) {
       const bad = !storageOk ? "`storage` half is not an IStorageDriver (no `putImmutable`)" : "`registry` half is not an IRegistryDriver (no `compareAndSwap`)";
-      throw new ValidationError(
-        "`storage` looks like a backend but its " + bad + " \u2014 build one with a backend class, or with `createBackend({ storage, registry })`."
+      throw new 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 ValidationError(
-      "`storage` must be a backend \u2014 S3Storage, GcsStorage, AzureBlobStorage, LocalFsStorage or MemoryStorage. An object with `.storage` and `.registry` is not one: a backend builds both halves from a single bucket and prefix, so they cannot disagree, and hand-assembling them re-opens exactly that mismatch \u2014 a store whose pointer and generations live in different places reads as empty rather than failing. If you genuinely want halves of your own \u2014 an instrumented driver, a registry in a database you already run \u2014 say so with `createBackend({ storage, registry })`, which is you taking on that they agree."
+    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) {
@@ -329,18 +534,18 @@ function resolveStorageSource(options, clock) {
     };
   }
   if (hasGetChunk && hasPutImmutable) {
-    throw new ValidationError(
+    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(
+    throw new ValidationError2(
       "`storage` must be a StorageBackend, an IStorageDriver, or a StorageChunkSource"
     );
   }
   if (hasGetChunk) {
     if (options.encryption?.keystore !== void 0 || options.encryption?.required === true) {
-      throw new ValidationError(
+      throw new ValidationError2(
         "keystore/requireEncryption apply only when the store builds its own read path; configure them on the StorageChunkSource you passed instead"
       );
     }
@@ -360,9 +565,20 @@ function resolveStorageSource(options, clock) {
     registry: void 0
   };
 }
+var NOT_A_GROUP = {
+  Null: "null",
+  Array: "an array",
+  Map: "a Map",
+  Set: "a Set",
+  Boolean: "a boxed boolean",
+  Number: "a boxed number",
+  String: "a boxed string"
+};
 var CloudRoaring = class _CloudRoaring {
   engine;
   cache;
+  /** The store's retry options, for a pinned engine to read through as the store's own does; undefined when off. */
+  retryOptions;
   crbmSource;
   clock;
   metrics;
@@ -376,39 +592,49 @@ var CloudRoaring = class _CloudRoaring {
   /** Resolved store-level per-op budget (null = disabled); the admin scans use it, with a per-op override. */
   budget;
   /**
-   * Refuse an option that moved into a group, naming where it went.
+   * Refuse any option key the store does not take, at the top level or inside a group, naming each one.
    *
-   * Silently ignoring one would be the exact failure this release exists to remove — see {@link MOVED_OPTIONS}
-   * for why each of these is unsafe to drop rather than merely untidy.
+   * 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 rejectMovedOptions(options) {
+  static rejectUnknownOptions(options) {
     if (options === null || options === void 0 || typeof options !== "object") {
-      throw new ValidationError(
+      throw new ValidationError2(
         "CloudRoaring needs an options object with a `storage` key \u2014 got " + (options === null ? "null" : typeof options)
       );
     }
     const bag = options;
-    const moved = MOVED_OPTIONS.filter(([from]) => bag[from] !== void 0);
-    if (moved.length === 0) return;
-    const clause = (kind, one, many) => {
-      const hits = moved.filter(([, , k]) => k === kind);
-      if (hits.length === 0) return null;
-      const body = hits.map(
-        ([from, to]) => kind === "gone" ? `\`${from}\` (${to})` : `\`${from}\` \u2192 ${/^[\w.]+$/.test(to) ? `\`${to}\`` : to}`
-      ).join(" \xB7 ");
-      return `${hits.length > 1 ? many : one}: ${body}`;
-    };
-    const parts = [
-      clause("group", "option moved into a group", "options moved into groups"),
-      clause("renamed", "option renamed", "options renamed"),
-      clause("gone", "option removed", "options removed")
-    ].filter((c) => c !== null);
-    throw new ValidationError(
-      `CloudRoaring ${parts.join("; ")}. Options are now one required \`storage\` plus four optional groups \u2014 \`cache\`, \`encryption\`, \`retry\` and \`seams\`. \`metrics\` and \`budget\` are unchanged flat options; leave them as they are. Full guide: https://github.com/cloudbitmaps/cloudbitmaps/blob/main/MIGRATING.md`
+    const unknown = [];
+    for (const key of Object.keys(bag)) {
+      if (!OPTION_KEYS.top.includes(key)) unknown.push({ group: null, key });
+    }
+    const groups = Object.keys(OPTION_KEYS).filter((g) => g !== "top");
+    for (const group of groups) {
+      const value = bag[group];
+      if (value === void 0) continue;
+      const offOk = group === "retry" || group === "budget";
+      if (value === false && offOk) continue;
+      const tag = Object.prototype.toString.call(value).slice(8, -1);
+      if (typeof value !== "object" || value === null || NOT_A_GROUP[tag] !== void 0) {
+        const got = typeof value !== "object" ? typeof value : NOT_A_GROUP[tag];
+        throw new ValidationError2(
+          `CloudRoaring's \`${group}\` must be an object${offOk ? " or `false`" : ""} \u2014 got ${got}`
+        );
+      }
+      const known = OPTION_KEYS[group];
+      for (const key of Object.keys(value)) if (!known.includes(key)) unknown.push({ group, key });
+    }
+    if (unknown.length === 0) return;
+    const takes = (keys) => keys.map((k) => `\`${k}\``).join(", ");
+    const named = [...new Set(unknown.map((u) => u.group))];
+    throw new ValidationError2(
+      `CloudRoaring does not take ${takes(unknown.map((u) => u.group === null ? u.key : `${u.group}.${u.key}`))}. ` + named.map(
+        (g) => g === null ? `The store takes ${takes(OPTION_KEYS.top)}.` : `\`${g}\` takes ${takes(OPTION_KEYS[g])}.`
+      ).join(" ") + " https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/api-reference.md#build-a-store--new-cloudroaringoptions"
     );
   }
   constructor(options) {
-    _CloudRoaring.rejectMovedOptions(options);
+    _CloudRoaring.rejectUnknownOptions(options);
     const clock = options.seams?.clock ?? new SystemClock();
     const rng = options.seams?.rng ?? new SystemRng();
     const metrics = safeMetrics(options.metrics ?? NOOP_METRICS);
@@ -444,6 +670,7 @@ var CloudRoaring = class _CloudRoaring {
         }
       };
       storage = new RetryingStorageChunkSource(storage, retryOpts);
+      this.retryOptions = retryOpts;
     }
     this.budget = resolveBudget(options.budget, DEFAULT_BUDGET);
     const deps = {
@@ -470,17 +697,16 @@ var CloudRoaring = class _CloudRoaring {
    * the store to have been constructed with a **backend**, which supplies both halves: an `IStorageDriver` to
    * write generations through (a pre-built `StorageChunkSource` has none) and the registry holding the pointer
    * every write publishes.
-   * Out-of-process callers use the free functions with explicit deps.
    */
   lifecycleDeps(op) {
     if (this.storageDriver === void 0) {
       throw new UnsupportedError(
-        `${op} needs the store built with a storage backend \u2014 S3Storage, GcsStorage, AzureBlobStorage, LocalFsStorage or MemoryStorage. A pre-built StorageChunkSource is read-only: it has no IStorageDriver underneath to write generations through. Out of process, call the equivalent free function with explicit deps instead.`
+        `${op} needs the store built with a storage backend \u2014 S3Storage, GcsStorage, AzureBlobStorage, LocalFsStorage or MemoryStorage. A pre-built StorageChunkSource is read-only: it has no IStorageDriver underneath to write generations through. Build the store on one of those backend classes to write.`
       );
     }
     if (this.registry === void 0) {
       throw new UnsupportedError(
-        `${op} needs a storage backend \u2014 S3Storage, GcsStorage, AzureBlobStorage, LocalFsStorage or MemoryStorage. A bare IStorageDriver has no generation pointer to publish through, and there is no longer a separate \`registry\` option to add.`
+        `${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 {
@@ -497,77 +723,86 @@ var CloudRoaring = class _CloudRoaring {
   segment(name, options) {
     const ref = { segment: name, namespace: options?.namespace };
     validateSegmentRef(ref);
+    refuseReservedNamespace(ref.namespace);
     const expiresAt = options?.expiresAt;
     if (expiresAt !== void 0) {
       if (!Number.isFinite(expiresAt) || !Number.isInteger(expiresAt) || expiresAt < MIN_EXPIRES_AT_MS) {
-        throw new ValidationError(
+        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 new Segment(
-      this.engine,
+    return makeSegment({
+      engine: this.engine,
       ref,
-      this.clock,
-      this.metrics,
-      (dest, ids, op, options2) => this.materialize(dest, ids, op, options2),
-      (r, e) => this.pinSegment(r, e),
-      (handles) => this.engineForCombine(handles),
+      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 forward-only — the shared body of the `*Into`
-   * verbs. The destination's previous generation stays readable until the publish lands (readers re-resolve
+   * 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 (on the pointer it
-   * judged, on the row's identity, and — where it judged an ABSENT segment — on that absence), and a refused
-   * object is reclaimed only after re-reading the row and finding the same incarnation (hard invariant 1:
+   * 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. `gcOrphanGenerations` carries
-   * the same residual and says so. The failure it leaves is an orphan object, which costs storage until
+   * 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.
    *
-   * Materialising used to do none of that. It wrote and published in one step, so an empty combine — a typo'd
-   * operand, an `exclude` that swallowed everything, an operand that had not loaded yet — silently replaced
-   * `dest` with an empty generation. That is the same failure `load()`'s guard exists to prevent, on the same
-   * data, and it was reachable without passing any option at all.
+   * 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 still throws.** `loadSegment` reports one as `reason: 'superseded'`; the `*Into` verbs have
-   * always thrown {@link WriteConflictError} for it, and a caller who wrote `catch (WriteConflictError)` must
-   * keep working. So that one refusal is translated back into the throw, and `MaterializeResult.reason` never
-   * carries it.
+   * **A 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 four different causes — the write-once PUT collided,
-   * the pointer moved, the row's token changed, the row was purged — and only the first two are the
-   * "somebody beat us" the name suggests. A token can also change on a write that is not a supersession at
-   * all, such as a `setRetention` on the destination. On top of that, the collection pass that runs AFTER a
+   * 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 it still collects nothing**, unlike `load()`. See the `keep` default below.
+   * **And by default it collects nothing**, unlike `load()`. See the `keep` default below.
    */
   async materialize(dest, ids, op, options) {
     const deps = this.lifecycleDeps(op);
-    const result = await loadSegment(dest, ids, deps, {
-      ...options?.allowEmpty === void 0 ? {} : { allowEmpty: options.allowEmpty },
-      ...options?.guard === void 0 ? {} : { guard: options.guard },
-      // COLLECT NOTHING by default, which `loadSegment` does not — it keeps a grace window of 1 and deletes
-      // the rest. A materialisation has never collected: the guide states "**It deletes nothing.** The
-      // destination's previous generation stays in the bucket until you collect it", and the ownership table
-      // puts that call on the operator. Inheriting `load()`'s collection would have silently deleted the
-      // generations an operator's recovery story depends on — `rollbackSegment` refuses a collected target —
-      // as a side effect of adding a guard whose entire purpose is preventing data loss. Opt in with `keep`.
-      keep: options?.keep ?? KEEP_EVERY_GENERATION,
-      ...options?.audit === void 0 ? {} : { audit: options.audit }
-    });
+    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`;
@@ -590,10 +825,16 @@ var CloudRoaring = class _CloudRoaring {
    * **Subject access (GDPR Art. 15 / CCPA right-to-know): which segments is this id a member of?**
    *
    * Enumerates the **registered** segments (via the store's own `registry`) and does a `has(id)` on each — no
-   * drivers to re-pass. Complete only over registered segments (every loaded segment has a row, so register the
-   * registry the loads used). There is deliberately **no `id → segments` reverse index** — that would tax every
-   * load for a rare request; this admin scan is `O(registered segments)` and touches no hot path. Requires a
-   * `registry` in the store config (throws {@link UnsupportedError} otherwise).
+   * drivers to re-pass. Complete only over registered segments (every loaded segment has a row, so build the
+   * store on the backend the loads used). There is deliberately **no `id → segments` reverse index** — that would
+   * tax every load for a rare request; this admin scan is `O(registered segments)` and touches no hot path. Needs
+   * a storage backend (throws {@link UnsupportedError} otherwise).
+   *
+   * **Current as of the registry row, not as of the reader's cache.** Each segment's resolved generation is
+   * compared with the row the scan listed, and a segment whose cached generation differs is re-resolved before the
+   * read, so a load or an erasure from another process shows at once — whatever `cache.genTtlMs` is, `0` included.
+   * The comparison is on the generation **and** the row's token, so a segment retired, purged and loaded again from
+   * generation 0 while this store held its old generation 0 is told apart too.
    */
   async subjectReport(id, options = {}) {
     const registry = this.requireRegistry("subjectReport");
@@ -602,7 +843,7 @@ var CloudRoaring = class _CloudRoaring {
     const budget = resolvePerOpBudget(options.budget, this.budget);
     splitId(id);
     const recs = await collectWithinBudget(
-      // A subject cannot be in a coordination row, and charging this request's budget for them would refuse a
+      // 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,
@@ -614,6 +855,11 @@ var CloudRoaring = class _CloudRoaring {
       async (rec) => {
         if (rec.status === "destroyed") return null;
         const ref = { segment: rec.segment, namespace: rec.namespace };
+        if (this.crbmSource !== void 0) {
+          const held = await this.crbmSource.currentVersion(ref);
+          const listed = rec.currentGen === null ? null : `${rec.currentGen}:${String(rec.token)}`;
+          if (held !== listed) this.engine.invalidate(ref);
+        }
         return await this.engine.has(ref, id) ? { segment: rec.segment, namespace: rec.namespace } : null;
       }
     );
@@ -626,44 +872,59 @@ var CloudRoaring = class _CloudRoaring {
    *
    * For each **registered** segment the id is a member of, `eraseIdFromSegment` rewrites the current generation
    * without the id — every chunk streamed through, one bit cleared — publishes the rewrite **fenced on the
-   * generation it was derived from**, and
-   * collects the generation that held the bit. The returned per-segment record is your **erasure ledger** —
+   * 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 — use the `eraseIdFromSegment` free function there).
+   * 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** — `publishGeneration`'s `expectFrom`, which lands the CAS only
+   * 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: `nextGeneration` numbers above everything in the bucket,
+   * 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 a reason rather than
-   * an error, read off the row: a moved pointer is `'superseded'`, a concurrent `dropSegment` `'destroyed'`,
-   * a retention sweep that purged the row `'absent'`. Re-running is the fix in every case.
+   * 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, or another erasure) moved the pointer mid-rewrite, so **this call** did not erase
-   * the id. Re-run: it erases the id if it is still there, and lists nothing for the segment if a racing
+   * 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. A re-run
-   * then reports nothing for that segment (the id is not in the current generation), so **that residual is
-   * collected by `gcOrphanGenerations(ref, deps, { keep: 0 })` or the next retention sweep**, not by another
-   * `eraseSubject`. Re-running is otherwise safe and idempotent: a segment the id is no longer in is not listed. Admin-only path;
-   * `O(registered segments)`, no hot-path cost. Per-subject crypto-shred is infeasible (a subject's bit is
+   * absent from every read and what remains is an object in the bucket that still contains the bit. The same
+   * note, after a publish, can mean a rollback moved the pointer back onto a generation that still holds the id
+   * while the collection ran — then the id is served again, and the entry says so rather than `erased: true`. A
+   * re-run searches every generation in the bucket, so it rewrites or collects what is left and usually reports
+   * `erased: true`; {@link SubjectErasureEntry.note} says what else a re-run can report. Re-running is otherwise safe
+   * and idempotent: a segment the id is no longer in is not listed. Admin-only path;
+   * `O(registered segments + superseded generations)`, no hot-path cost: a segment whose current generation lacks
+   * the id is searched generation by generation, one open for each other generation in its bucket, and with the
+   * keep-everything default of the `*Into` verbs that is one per generation the segment ever had. The per-op
+   * `budget` is charged one unit for each segment and one for each generation opened beyond the one its row names,
+   * so a fleet with long histories can exhaust it where the segment count alone would not. A segment that does is
+   * reported `erased: false` with an `error:` note, before it deletes anything (the one refusal that can come after a
+   * rewrite is the last check for a generation a concurrent writer left behind), and the
+   * rest of the scan continues: the call itself does not throw for it. Per-subject crypto-shred is infeasible (a subject's bit is
    * co-mingled in a shared container), so this is the single-subject erasure route; whole-segment/tenant erasure
    * is `dropSegment` / the `destroySegment`/`eraseNamespace` free functions.
    */
@@ -678,6 +939,11 @@ var CloudRoaring = class _CloudRoaring {
       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,
@@ -685,7 +951,12 @@ var CloudRoaring = class _CloudRoaring {
         if (rec.status === "destroyed") return null;
         const ref = { segment: rec.segment, namespace: rec.namespace };
         try {
-          const result = await eraseIdFromSegment(ref, id, deps, { audit: options.audit });
+          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;
@@ -720,7 +991,7 @@ var CloudRoaring = class _CloudRoaring {
    *
    * What the bucket holds, not what the segment has ever been — collection deletes superseded objects, so this is
    * the grace window plus whatever has not been collected yet. It is the set {@link CloudRoaring.rollback} can
-   * choose from, which is the reason to look at it. One `list` call; it does not open the objects.
+   * 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.
    */
@@ -746,7 +1017,7 @@ var CloudRoaring = class _CloudRoaring {
    * a handle carrying an expired `expiresAt` reads empty by a rule that lives on the handle, not the row.
    *
    * Not a lock: the answer can change the moment it returns. If it has to hold, use the fence built for that —
-   * `load`'s `guard`, or `expectFrom`/`expectToken` on a publish. Needs a `registry`.
+   * `load`'s `guard`, or `expectFrom`/`expectToken` on a publish. Needs a storage backend.
    *
    * ```ts
    * if (!(await store.exists({ segment: 'users' }))) {
@@ -771,13 +1042,13 @@ var CloudRoaring = class _CloudRoaring {
    * Scoping to a namespace narrows the LIST prefix, so it really is the difference between reading one tenant
    * and reading all of them.
    *
-   * It streams, and stopping the iteration stops the scan — except behind a driver that buffers its
-   * enumeration to retry it as a unit, which `RetryingRegistryDriver` does: wrapped in that, the whole scan is
-   * paid for and resident before the first row arrives.
+   * 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 `registry`.
+   * {@link CloudRoaring.exists} the narrower question. Needs a storage backend.
    *
    * ```ts
    * for await (const s of store.segments({ namespace: 'active-daily' })) {
@@ -788,6 +1059,7 @@ var CloudRoaring = class _CloudRoaring {
   segments(options = {}) {
     if (options.namespace !== void 0) {
       validateSegmentRef({ segment: "x", namespace: options.namespace });
+      refuseReservedNamespace(options.namespace);
     }
     return listSegments(this.requireRegistry("segments"), options);
   }
@@ -808,9 +1080,16 @@ var CloudRoaring = class _CloudRoaring {
    * current is a no-op that reports itself.
    *
    * It deletes nothing. The generations above the new pointer stay put — which is what makes this reversible —
-   * and are then *above* `currentGen`, where collection never looks, so they remain until a later load raises the
-   * pointer past them. An operator who has just undone a bad load should not have the evidence collected out from
-   * under them.
+   * 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.
    */
@@ -832,8 +1111,8 @@ var CloudRoaring = class _CloudRoaring {
    * attention to and everybody pays for.
    *
    * ```ts
-   * const r = await store.load('audience:active', idsFromWarehouse, {
-   *   guard: { maxShrink: 0.5 },   // refuse a load that drops more than half the segment
+   * 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}`);
    * ```
@@ -851,15 +1130,22 @@ var CloudRoaring = class _CloudRoaring {
    * `eraseIdFromSegment` instead, because three of its four refusals are expected guard outcomes rather than
    * faults.
    *
-   * The object written for a refused load is deleted again before returning — it sits above `currentGen`, where
-   * generation collection deliberately never looks, so nothing else would reclaim it. The exception is a load
-   * that finds the segment **re-created** underneath it: the generation number it holds may then name the new
-   * incarnation's live object, so it leaves the orphan rather than risk deleting live data.
+   * `'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`.
    *
-   * Two things it does **throw** for, rather than report: a crypto-shredded segment (`ValidationError` — there
-   * is no key to write under), and a collection pass that could not prove the segment was still the same one
-   * (`WriteConflictError`). The second can be raised **after** the publish already landed, so a throw does not
-   * by itself mean the load did not take effect — re-read the pointer rather than assuming.
+   * 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).
    */
@@ -902,10 +1188,14 @@ var CloudRoaring = class _CloudRoaring {
    * could not remove rather than returning a result that looks like a clean drop.
    *
    * Reads become empty within `cache.genTtlMs` (default 2 s), not instantly: a store that had already read this
-   * segment may answer from its cached generation + cached chunks until that window lapses. A reader that never
-   * touched it sees empty at once. **That bound needs a clock and `cache.genTtlMs > 0`** — a store built without a
-   * clock, or with `cache.genTtlMs: 0` ("pin forever"), holds its resolved snapshot for its own lifetime and can
-   * keep answering `true` for a dropped segment indefinitely; restart it.
+   * segment may answer from its cached generation + cached chunks until that window lapses, or, while the registry
+   * cannot be read because of a transient fault, until a retry 500 ms apart reaches it again. A reader that never
+   * touched it sees empty at once. **That bound needs a registry and `cache.genTtlMs > 0`.** A store with no registry
+   * (a bare `IStorageDriver`), with `cache.genTtlMs: 0`, or on a storage source built with no clock, has no timed
+   * refresh. It notices the drop only when a read has to fetch
+   * from a deleted generation or its reader cache evicts the segment, and until then a chunk it has cached
+   * answers without reaching storage, so it can keep answering `true` for a dropped segment indefinitely. Tell
+   * it with {@link invalidate}, or restart it.
    *
    * Needs the store built with a **backend** (throws {@link UnsupportedError} otherwise),
    * because it has to enumerate and delete generations — a pre-built `StorageChunkSource` only reads.
@@ -942,8 +1232,8 @@ var CloudRoaring = class _CloudRoaring {
    *
    * 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);
@@ -982,7 +1272,7 @@ var CloudRoaring = class _CloudRoaring {
    * ```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) {
@@ -1008,8 +1298,9 @@ var CloudRoaring = class _CloudRoaring {
    * 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.
+   * exactly that row, and deleting it would destroy the Art. 17 attestation and un-fence the name. By default a
+   * segment that held nothing has its row deleted in the pass that retires it, since that row would only fence the name.
+   * Pass `purgeTombstones: false` to keep every tombstone, that row included.
    *
    * Needs the store built with a **backend** (throws {@link UnsupportedError} otherwise),
    * because retiring a segment deletes its storage objects. `now` defaults to the store's clock.
@@ -1036,37 +1327,42 @@ var CloudRoaring = class _CloudRoaring {
    * that advances `currentGen`**, which the snapshot TTL notices and the generation-keyed cache misses on.
    * Neither notices an event that *destroys* what they were derived from.
    *
-   * The verbs on this class handle themselves — `eraseSubject`, `dropSegment` and `retireExpired` invalidate
-   * what they touch. This method is for the cases they cannot see:
+   * 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 leaves it holding an open reader and an unwrapped
-   *   DEK. Until it is told, it keeps decrypting — including chunks it had never fetched before the shred.
+   *   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 built with no clock or `cache.genTtlMs: 0` ("pin forever") never
-   *   converges at all. If a compliance deadline depends on every reader converging, you need to signal them —
-   *   this is the call to make when your own fan-out delivers.
+   *   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, { storage, registry, keystore }, { confirmSegment: ref.segment });
+   * 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**, which is safe precisely
-   * because the cache is keyed by the source's version rather than the generation number: the pinned view
-   * reports the version captured at pin time, so its decoded chunks cannot collide with the live generation's.
-   * Sharing it on a generation-only key was how a pinned read could resurrect an id already reported
-   * physically gone.
+   * 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;
@@ -1075,27 +1371,30 @@ var CloudRoaring = class _CloudRoaring {
         "pin() needs the `.crbm` storage source \u2014 pass a backend or a raw IStorageDriver as `storage` (a pre-built StorageChunkSource that cannot resolve a generation has nothing to pin)"
       );
     }
-    const at = await crbm.pinGeneration(ref);
-    const pinnedAt = { generation: at?.generation ?? null, version: at?.version ?? null };
+    const 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 new Segment(
-      this.engineWithPins(pins),
+    return makeSegment({
+      engine: this.engineWithPins(pins),
       ref,
-      this.clock,
-      this.metrics,
-      (dest, ids, op, options) => this.materialize(dest, ids, op, options),
-      (r, e) => this.pinSegment(r, e),
-      (handles) => this.engineForCombine(handles),
+      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.
+   * 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**, which is safe only because that cache is keyed by the source's
-   * version rather than the generation number: a pinned view reports the version captured at pin time, so its
-   * decoded chunks cannot collide with the live generation's.
+   * 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;
@@ -1104,8 +1403,9 @@ var CloudRoaring = class _CloudRoaring {
         "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: new PinnedStorageChunkSource(crbm, pins),
+      storage: this.retryOptions === void 0 ? pinned : new RetryingStorageChunkSource(pinned, this.retryOptions),
       cache: this.cache,
       codec: roaringCodec,
       clock: this.clock,
@@ -1121,20 +1421,42 @@ var CloudRoaring = class _CloudRoaring {
    * `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 (at !== void 0) pins.set(h.key(), at);
+      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 pins.size === 0 ? void 0 : this.engineWithPins(pins);
+    return this.engineWithPins(pins);
+  }
+  /** `op` under the store's retries, as the store's own reads run; bare when the store has retries off. */
+  withRetries(op) {
+    const r = this.retryOptions;
+    return r === void 0 ? op() : withRetry(op, r.policy ?? DEFAULT_RETRY_POLICY, r);
   }
   /** The store's registry, or a typed error naming the operation that needs one. */
   requireRegistry(op) {
     if (this.registry === void 0) {
       throw new UnsupportedError(
-        `${op} needs a storage backend \u2014 S3Storage, GcsStorage, AzureBlobStorage, LocalFsStorage or MemoryStorage. A bare IStorageDriver has no generation pointer to publish through, and there is no longer a separate \`registry\` option to add.`
+        `${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;
@@ -1143,11 +1465,16 @@ var CloudRoaring = class _CloudRoaring {
    * **Cross-tier DR consistency check.** After a restore/failover, verify every registered segment's `currentGen`
    * actually has its `.crbm` present in Storage — catching a **torn restore** where the registry (`currentGen`) came
    * back ahead of the object store, so a pointer references a generation that isn't there (reads would then
-   * throw). Read-only, bounded fan-out; run it at startup after a restore. Returns `{ checked, inconsistent }` —
-   * `inconsistent` empty ⇒ coherent; otherwise it names the segments to recover (restore the object store, or
-   * roll the registry back to a coherent point). Needs the store built with a **backend**
+   * throw). Read-only, bounded fan-out; run it at startup after a restore. Returns `{ checked, inconsistent,
+   * errored }` — `inconsistent` empty ⇒ coherent; otherwise it names the segments to recover (restore the object
+   * store, or roll the registry back to a coherent point). Needs the store built with a **backend**
    * (throws {@link UnsupportedError} otherwise). `destroyed` (crypto-shredded) segments are skipped. Pair it with
    * the DR runbook (docs/guide/disaster-recovery.md).
+   *
+   * It holds the registry rows it enumerates resident, at most 250,000 of them, and throws
+   * `BudgetExceededError` past that rather than report a partial scan as a whole one. This method takes no
+   * ceiling of its own: narrow the scan with `namespace`, or call `runConsistencyCheck` over the backend's
+   * `storage` and `registry` with a higher `maxScanSegments`.
    */
   async checkConsistency(options = {}) {
     const deps = this.lifecycleDeps("checkConsistency");
@@ -1167,7 +1494,7 @@ var CloudRoaring = class _CloudRoaring {
    */
   async exportSegments(sink, options = {}) {
     const registry = this.requireRegistry("exportSegments");
-    return runExport2(this, registry, sink, {
+    return runExport(this, registry, sink, {
       ...options,
       codec: options.codec ?? roaringCodec
     });
@@ -1180,24 +1507,34 @@ var CloudRoaring = class _CloudRoaring {
     return estimateCost(input);
   }
 };
+var failing = (err) => ({
+  [Symbol.asyncIterator]: () => ({ next: () => Promise.reject(err) })
+});
+var samePin = (a, b) => a === void 0 || b === void 0 ? a === b : a.generation === b.generation && a.fingerprint === b.fingerprint;
+var twoPins = (a, b) => {
+  const one = (p) => p === void 0 ? "live" : `pinned at generation ${p.generation ?? "none"}`;
+  return a !== void 0 && b !== void 0 && a.generation === b.generation ? `pinned twice at generation ${a.generation ?? "none"}, as two different objects` : `${one(a)} and ${one(b)}`;
+};
+var rangeOf = (options) => ({
+  after: options.after,
+  through: options.through
+});
+var readOptions = (options) => ({
+  ...rangeOf(options),
+  concurrency: options.concurrency,
+  budget: options.budget,
+  allowAbsentOperands: options.allowAbsentOperands
+});
+var NO_SEGMENTS = [];
 var EMPTY_IDS = {
   async *[Symbol.asyncIterator]() {
   }
 };
 var KEEP_EVERY_GENERATION = Number.MAX_SAFE_INTEGER;
-var Segment = class {
-  constructor(engine, ref, clock, metrics, materialize, pinned, combineEngine, expiresAt, pinnedAt) {
-    this.engine = engine;
-    this.ref = ref;
-    this.clock = clock;
-    this.metrics = metrics;
-    this.materialize = materialize;
-    this.pinned = pinned;
-    this.combineEngine = combineEngine;
-    this.expiresAt = expiresAt;
-    this.pinnedAt = pinnedAt;
-    this.metricsOn = metrics !== NOOP_METRICS;
-  }
+var makeSegment;
+var minting = false;
+var Segment = class _Segment {
+  metricsOn;
   engine;
   ref;
   clock;
@@ -1205,9 +1542,44 @@ var Segment = class {
   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;
-  metricsOn;
+  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.
    *
@@ -1226,15 +1598,54 @@ var Segment = class {
    * `other` at whatever is current — pin each segment if you want the whole query held. And a pinned handle
    * used as an *operand* is still read at its pin, never live.
    *
-   * **It is a hold, not a lease.** Nothing here stops `gcOrphanGenerations` deleting the generation underneath
+   * **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 [Sizing `keep`](../../docs/guide/getting-started.md#sizing-keep) — or take the pin on a segment
+   * 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 pin
-   * taken before a crypto-shred stops reading when the shred lands: the destroyed row is re-checked every time
-   * the pinned reader opens, so a pin cannot outlive the key it was using.
+   * 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.
@@ -1242,7 +1653,12 @@ var Segment = class {
   async pin() {
     return this.pinned(this.ref, this.expiresAt);
   }
-  /** This handle's segment, as the cache/pin key — `ref` stays private; the encapsulation is worth the method. */
+  /**
+   * 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);
   }
@@ -1261,15 +1677,15 @@ var Segment = class {
    *
    * On the read verbs an expired handle answers empty, which is the point of lazy expiry. On a *write* the same
    * rule would be destructive in a way nobody asks for: `a.intersectInto(dest, [b])` where `b`'s deadline has
-   * quietly passed publishes an **empty generation over `dest`** — a wipe, reported as a successful write, with
-   * the cause (a deadline on a handle somewhere) nowhere in the result. Reads degrade to empty; writes must not.
+   * 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 — now covers these verbs too: they route through the same guarded write path as
+   * `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.)
@@ -1285,7 +1701,7 @@ var Segment = class {
         stale.push(seg.ref.namespace ? `${seg.ref.namespace}/${seg.ref.segment}` : seg.ref.segment);
     }
     if (stale.length > 0) {
-      throw new ValidationError(
+      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.`
       );
     }
@@ -1308,24 +1724,71 @@ var Segment = class {
     if (this.expired()) return Promise.resolve(false);
     return this.timed("has", () => this.engine.has(this.ref, id));
   }
-  /** Cardinality — summed from the `.crbm` index with **zero payload reads** on a loaded segment. */
+  /**
+   * Cardinality — summed from the `.crbm` index with **zero payload reads** on a loaded segment.
+   *
+   * What this trusts: the answer is the sum of the per-chunk cardinalities the index records, and no payload is
+   * decoded to confirm it. The index is checked for internal consistency when the object is opened (each key in
+   * range and ascending, each cardinality in `1..65536`, each payload inside the payload region, and, on an
+   * unencrypted object, the footer's chunk count and total agreeing with the index), and a corrupt index that is
+   * still internally consistent yields a wrong count. `iterate()` and the combines decode the payloads, whose
+   * structure is checked.
+   */
   count() {
     if (this.expired()) return Promise.resolve(0);
     return this.timed("count", () => this.engine.count(this.ref));
   }
-  /** Every id, ascending, streamed one chunk at a time. */
-  iterate() {
+  /**
+   * Every id, ascending, streamed one chunk at a time. Pass a range to read part of the segment: the ids in
+   * `(after, through]`, fetching only the chunks the range overlaps. The per-op budget is charged for every chunk in
+   * the range, so give a page `through` as well as `after`. On a pinned handle it reads the pinned generation, as a
+   * full read does.
+   *
+   * ```ts
+   * // Keyset paging: each page resumes where the one before ended, and stops at its window's end.
+   * for await (const id of seg.iterate({ after: previousEnd, through: windowEnd })) await send(id);
+   * ```
+   *
+   * Each bound is optional and an integer in `0..4294967295`; a bad one throws {@link ValidationError} when the
+   * stream is first read. `after >= through` is an empty range, which reads nothing. An expired handle reads empty
+   * without checking its options, as every read of one does.
+   */
+  iterate(options) {
     if (this.expired()) return EMPTY_IDS;
-    return this.engine.iterate(this.ref);
+    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);
   }
   /**
-   * 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.
+   * 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) {
-    if (options === void 0) return void 0;
-    const { exclude, ...rest } = options;
-    return exclude === void 0 ? rest : { ...rest, exclude: exclude.map((o) => o.ref) };
+  refsIn(options, exclude) {
+    if (options == null) return void 0;
+    return {
+      ...readOptions(options),
+      exclude: exclude.length > 0 ? exclude.map((o) => o.ref) : void 0
+    };
+  }
+  /**
+   * The handles in `options.exclude` that have not expired. **An expired exclusion excludes nothing**, in every
+   * combine, so it is dropped here, before the engine is asked for anything: it is never fetched, never
+   * checked for absence, and never counted in the pin-consistency check. `exclude` is read once, so a getter sees
+   * one call.
+   *
+   * With no `exclude` this is one property read and a shared empty list, and with none expired it returns the
+   * caller's own array, so the common case allocates nothing.
+   */
+  liveExcludes(options) {
+    const exclude = options?.exclude;
+    if (exclude == null || exclude.length === 0) return NO_SEGMENTS;
+    return exclude.some((e) => e.expired()) ? exclude.filter((e) => !e.expired()) : exclude;
   }
   /**
    * Chunk-skipping intersection: stream the ids in **this** segment AND every segment in `others`, ascending.
@@ -1337,13 +1800,20 @@ var Segment = class {
    */
   intersect(others, options) {
     if (this.expired() || others.some((o) => o.expired())) return EMPTY_IDS;
-    const engine = this.combineEngine([this, ...others, ...options?.exclude ?? []]) ?? this.engine;
-    return engine.intersect([this.ref, ...others.map((o) => o.ref)], this.refsIn(options));
+    const exclude = this.liveExcludes(options);
+    let engine;
+    try {
+      engine = this.combineEngine([this, ...others, ...exclude]) ?? this.engine;
+    } catch (err) {
+      return failing(err);
+    }
+    return engine.intersect([this.ref, ...others.map((o) => o.ref)], this.refsIn(options, exclude));
   }
   /**
    * Materialize `this ∩ others…` (minus `exclude`) as a **new generation of `dest`** — `dest`'s previous contents
    * are superseded, not added to. Streaming + bounded-memory; the result is one immutable object published
-   * forward-only, so readers of `dest` see either the old generation or the new one, never a partial. Needs the
+   * 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
@@ -1361,6 +1831,7 @@ var Segment = class {
    */
   async intersectInto(dest, others, options) {
     this.refuseIfExpired("intersectInto", dest, [...others, ...options?.exclude ?? []]);
+    this.combineEngine([this, ...others, ...options?.exclude ?? []]);
     return this.timed(
       "intersectInto",
       () => this.materialize(dest.ref, this.intersect(others, options), "intersectInto", options)
@@ -1383,16 +1854,23 @@ var Segment = class {
       return live[0].union(live.slice(1), options);
     }
     if (live.length === 0 && others.length > 0) {
-      const exclude = options?.exclude ?? [];
-      return exclude.length > 0 ? this.andNot([...exclude], options) : this.iterate();
+      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 engine = this.combineEngine([this, ...others, ...options?.exclude ?? []]) ?? this.engine;
-    return engine.union([this.ref, ...others.map((o) => o.ref)], this.refsIn(options));
+    const exclude = this.liveExcludes(options);
+    let engine;
+    try {
+      engine = this.combineEngine([this, ...others, ...exclude]) ?? this.engine;
+    } catch (err) {
+      return failing(err);
+    }
+    return engine.union([this.ref, ...others.map((o) => o.ref)], this.refsIn(options, exclude));
   }
   /** Materialize `this ∪ others…` (minus `exclude`) as a **new generation of `dest`** — see {@link intersectInto}. */
   async unionInto(dest, others, options) {
     this.refuseIfExpired("unionInto", dest, [...others, ...options?.exclude ?? []]);
+    this.combineEngine([this, ...others, ...options?.exclude ?? []]);
     return this.timed(
       "unionInto",
       () => this.materialize(dest.ref, this.union(others, options), "unionInto", options)
@@ -1406,24 +1884,36 @@ 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) {
     if (this.expired()) return EMPTY_IDS;
     const liveExcludes = excludes.filter((e) => !e.expired());
-    if (liveExcludes.length === 0 && excludes.length > 0) return this.iterate();
+    if (liveExcludes.length === 0 && excludes.length > 0) {
+      return this.union([], options == null ? void 0 : readOptions(options));
+    }
     if (liveExcludes.length !== excludes.length) return this.andNot(liveExcludes, options);
-    const engine = this.combineEngine([this, ...excludes]) ?? this.engine;
+    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…)` as a **new generation of `dest`** — see {@link intersectInto}. */
   async andNotInto(dest, excludes, options) {
     this.refuseIfExpired("andNotInto", dest, excludes);
+    this.combineEngine([this, ...excludes]);
     return this.timed(
       "andNotInto",
       () => this.materialize(dest.ref, this.andNot(excludes, options), "andNotInto", options)
@@ -1432,30 +1922,61 @@ var Segment = class {
   /**
    * Grounded cost report for this segment: storage cost from its **real** `.crbm` size (exact, no payload
    * reads); request cost from the supplied `workload` rates. A segment with no Storage generation reports zero
-   * storage. See {@link CostReport} — it always includes a verdict (incl. the lose-zone).
+   * storage. The pointer refresh is priced at the store's own `cache.genTtlMs`, or at none when the store never
+   * refreshes, unless the workload sets `genTtlMs`. See {@link CostReport} — it always includes a verdict (incl.
+   * the lose-zone).
    */
   async costReport(options) {
     const canMeasure = this.engine.supportsStorageSize;
     const size = canMeasure ? await this.engine.segmentSize(this.ref) : null;
+    const refreshMs = this.engine.pointerRefreshMs;
+    const workload = refreshMs === void 0 || options?.workload?.genTtlMs !== void 0 ? options?.workload : { ...options?.workload, genTtlMs: refreshMs };
     return groundedReport({
       storageBytes: size?.sizeBytes ?? 0,
       grounded: canMeasure,
-      workload: options?.workload,
+      workload,
       pricing: options?.pricing,
       extraNotes: canMeasure ? void 0 : ["storage source has no sizeOf() \u2014 storage not measured, reported as $0."]
     });
   }
 };
-var VERSION = "0.10.0";
 export {
+  AWS_US_EAST_1_ONDEMAND,
+  BudgetExceededError,
+  BufferReader,
+  CapabilityError,
   CloudRoaring,
-  SafeBitmap,
+  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,
-  VERSION,
-  bulkLoadCrbmGeneration,
-  eraseIdFromSegment,
-  loadSegment,
-  roaringCodec,
-  runExport
+  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