@cloudbitmaps/core 0.10.0 → 0.11.0

package/dist/index.js

@@ -7,14 +7,13 @@ import {
   KeyUnavailableError,
   MAX_NAME_LENGTH,
   NotFoundError,
-  TimeoutError,
+  RESERVED_NAMESPACE_PREFIX,
   TransientError,
   UnsupportedError,
   ValidationError,
   WriteConflictError,
   applyRegistryPatch,
   brandAsBackend,
-  createBackend,
   decodeNameFromPath,
   encodeNameForKey,
   encodeNameForPath,
@@ -22,6 +21,7 @@ import {
   isCloudRoaringError,
   isIntegrityError,
   isNotFoundError,
+  isReservedNamespace,
   isStorageBackend,
   isTransientError,
   isValidationError,
@@ -35,8 +35,10 @@ import {
   validateChunkRef,
   validateNewRegistryRecord,
   validateRegistryPatch,
-  validateSegmentRef
-} from "./chunk-BUPDGZRR.js";
+  validateSegmentRef,
+  validateUserNamespace,
+  validateUserRef
+} from "./chunk-5OMC5U7U.js";
 
 // src/core/bit-route.ts
 var U32_MAX = 4294967295;
@@ -202,6 +204,57 @@ var CountingMetricsSink = class _CountingMetricsSink {
 var DEFAULT_MAX_BITMAP_BYTES = 1 << 20;
 var DEFAULT_INTERSECT_CONCURRENCY = 8;
 var ZERO_CLOCK = { now: () => 0 };
+function windowOf(range) {
+  const after = range?.after;
+  const through = range?.through;
+  if (after === void 0 && through === void 0) return null;
+  for (const [name, bound] of [
+    ["after", after],
+    ["through", through]
+  ]) {
+    if (bound !== void 0 && (!Number.isInteger(bound) || bound < 0 || bound > U32_MAX)) {
+      const got = typeof bound === "number" ? String(bound) : `a ${typeof bound}`;
+      throw new ValidationError(`${name} must be an integer in 0..${U32_MAX}; got ${got}`);
+    }
+  }
+  const lo = after === void 0 ? 0 : after + 1;
+  const hi = through ?? U32_MAX;
+  if (lo > hi) return "empty";
+  return {
+    loKey: Math.floor(lo / CHUNK_COUNT),
+    loRem: lo % CHUNK_COUNT,
+    hiKey: Math.floor(hi / CHUNK_COUNT),
+    hiRem: hi % CHUNK_COUNT
+  };
+}
+var WHOLE_ID_SPACE = {
+  loKey: 0,
+  loRem: 0,
+  hiKey: CHUNK_COUNT - 1,
+  hiRem: MAX_REMAINDER
+};
+var isEdge = (chunkKey, w) => chunkKey === w.loKey && w.loRem > 0 || chunkKey === w.hiKey && w.hiRem < MAX_REMAINDER;
+function* edgeIds(chunk, chunkKey, w) {
+  const from = chunkKey === w.loKey ? w.loRem : 0;
+  const to = chunkKey === w.hiKey ? w.hiRem : MAX_REMAINDER;
+  for (const remainder of chunk) {
+    if (remainder > to) return;
+    if (remainder >= from) yield joinId(chunkKey, remainder);
+  }
+}
+function keysWithin(keys, w) {
+  const firstAtLeast = (key) => {
+    let lo = 0;
+    let hi = keys.length;
+    while (lo < hi) {
+      const mid = lo + hi >>> 1;
+      if (keys[mid] < key) lo = mid + 1;
+      else hi = mid;
+    }
+    return lo;
+  };
+  return keys.slice(firstAtLeast(w.loKey), firstAtLeast(w.hiKey + 1));
+}
 var SegmentEngine = class {
   storage;
   cache;
@@ -232,6 +285,10 @@ var SegmentEngine = class {
    * Cardinality. When the Storage source can serve per-chunk cardinality from its `.crbm` index (the `.crbm`
    * source can), the count is summed from the index with **zero payload reads**. A source without that
    * capability (the in-memory source) falls back to fetching every chunk.
+   *
+   * The index sum is trusted, not confirmed: the reader checked the index for internal consistency when it opened
+   * the object, and a corrupt index that is still internally consistent yields a wrong count. `iterate()` and the
+   * combines decode the payloads.
    */
   async count(seg) {
     const cardinalities = this.storage.cardinalities ? await this.storage.cardinalities(seg) : null;
@@ -256,12 +313,26 @@ var SegmentEngine = class {
   get supportsStorageSize() {
     return typeof this.storage.sizeOf === "function";
   }
+  /** How often the Storage source re-reads a pointer while reading (cost reporting); undefined if it does not say. */
+  get pointerRefreshMs() {
+    return this.storage.pointerRefreshMs;
+  }
   /** Grounded Storage size of a segment's current generation (cost reporting), or null if it has no generation. */
   segmentSize(seg) {
     return this.storage.sizeOf ? this.storage.sizeOf(seg) : Promise.resolve(null);
   }
-  /** Every id, ascending, one chunk at a time. */
-  async *iterate(seg) {
+  /**
+   * Every id, ascending, one chunk at a time; with `range`, only the ids in `(after, through]`, fetching only the
+   * chunks the range overlaps (see {@link IdRange}).
+   *
+   * Two generators, not one with a branch: a second `yield` site in the full read's generator grows its frame, and
+   * every id of a read that asked for no range paid for it (measured at about 5% per id). The full read keeps the
+   * loop it always had.
+   */
+  iterate(seg, range) {
+    return range === void 0 ? this.iterateAll(seg) : this.iterateRange(seg, range);
+  }
+  async *iterateAll(seg) {
     const chunkKeys = await this.chunkKeys(seg);
     checkBudget(this.budget, chunkKeys.length, "iterate");
     const gen = await this.cacheVersion(seg);
@@ -271,6 +342,22 @@ var SegmentEngine = class {
       for (const remainder of chunk) yield joinId(chunkKey, remainder);
     }
   }
+  async *iterateRange(seg, range) {
+    const w = windowOf(range) ?? WHOLE_ID_SPACE;
+    if (w === "empty") return;
+    const chunkKeys = keysWithin(await this.chunkKeys(seg), w);
+    checkBudget(this.budget, chunkKeys.length, "iterate");
+    const gen = await this.cacheVersion(seg);
+    for (const chunkKey of chunkKeys) {
+      const chunk = await this.storageChunk({ ...seg, chunkKey }, gen);
+      if (chunk === null) continue;
+      if (isEdge(chunkKey, w)) {
+        for (const id of edgeIds(chunk, chunkKey, w)) yield id;
+      } else {
+        for (const remainder of chunk) yield joinId(chunkKey, remainder);
+      }
+    }
+  }
   /**
    * `segs[0] ∩ segs[1] ∩ …`, minus every id in `options.exclude` — streamed ascending.
    *
@@ -294,11 +381,13 @@ var SegmentEngine = class {
    * Generation-consistent within the call (normal case): each operand's current generation is resolved **once**
    * up front (before the fan-out) and threaded into every chunk read, so a concurrent load can't corrupt or tear
    * the result — every chunk read is a whole, checksum-verified, immutable generation. The edge a *long* call can
-   * hit: if it straddles a mid-call `cache.genTtlMs` boundary and a load has published, an operand's not-yet-read
-   * chunks may re-resolve forward to the newer generation (a generation hop within one long call) — the call
-   * never crashes or returns a torn object, but may mix generations. A shorter call is unaffected **unless the
-   * reader cache evicts an operand mid-call** (`maxOpenSegments`): the re-read re-resolves fresh (bypassing the
-   * TTL), which can hop generations even sub-TTL — still whole/immutable per read, never torn.
+   * hit is invariant 3's: if it straddles a mid-call `cache.genTtlMs` boundary and a load has published, an
+   * operand's not-yet-read chunks may re-resolve forward to the newer generation (a generation hop within one long
+   * call) — the call never crashes or returns a torn object, but may mix generations. Three things hop it without
+   * waiting for the TTL, so a shorter call can meet them too: **the reader cache evicting an operand mid-call**
+   * (`maxOpenSegments`), whose re-read re-resolves fresh; a sweep deleting the generation it was reading, which
+   * heals the read forward; and an invalidation, which this store's own `load`, `rollback` and `eraseSubject` make
+   * and `invalidate()` makes on request. Still whole/immutable per read, never torn.
    */
   intersect(segs, options) {
     return this.combine(segs, options?.exclude ?? [], "all", "intersect", options);
@@ -337,10 +426,13 @@ var SegmentEngine = class {
       );
     }
     const budget = resolvePerOpBudget(options?.budget, this.budget);
+    const w = windowOf(options);
+    if (w === "empty") return;
     const extract = async (seg) => {
-      const keys = await this.chunkKeys(seg);
+      const all = await this.chunkKeys(seg);
       const gen = await this.cacheVersion(seg);
-      return { seg, keys: new Set(keys), gen };
+      const keys = w === null ? all : keysWithin(all, w);
+      return { seg, keys: new Set(keys), chunkless: all.length === 0, gen };
     };
     const [operands, excludes] = await Promise.all([
       Promise.all(segs.map(extract)),
@@ -392,7 +484,11 @@ var SegmentEngine = class {
       if (next < common.length) inFlight.push(startAt(common[next++]));
       if (slot.error !== void 0) throw slot.error;
       if (slot.result && !slot.result.isEmpty) {
-        for (const remainder of slot.result) yield joinId(slot.key, remainder);
+        if (w !== null && isEdge(slot.key, w)) {
+          for (const id of edgeIds(slot.result, slot.key, w)) yield id;
+        } else {
+          for (const remainder of slot.result) yield joinId(slot.key, remainder);
+        }
       }
     }
   }
@@ -442,7 +538,13 @@ var SegmentEngine = class {
   async chunkKeys(seg) {
     const keys = [...await this.storage.listChunkKeys(seg)];
     for (const k of keys) this.assertChunkKeyInRange(k);
-    return keys.sort((a, b) => a - b);
+    keys.sort((a, b) => a - b);
+    for (let i = 1; i < keys.length; i++) {
+      if (keys[i] === keys[i - 1]) {
+        throw new IntegrityError(`chunk key from a tier is listed twice: ${keys[i]}`);
+      }
+    }
+    return keys;
   }
   /**
    * Tier-derived keys are untrusted (invariant 5) — fail fast on a corrupt/out-of-range key rather than
@@ -465,6 +567,11 @@ var SegmentEngine = class {
    *
    * Costs one `maximum()` per chunk, not per id — `maximum` is optional on the codec seam precisely so a codec
    * that cannot answer in O(1) opts out instead of making the read path walk every value.
+   *
+   * One value stands for all of them only because the decode is structurally checked. Roaring answers `maximum()`
+   * from its last container, so a payload listing its containers out of order would report the wrong one's
+   * largest value and pass here while holding values above 65,535. The codec's `safeDeserialize` refuses that
+   * payload, and every other shape that would make this answer wrong, before it reaches this check.
    */
   assertChunkPayloadInRange(bitmap, chunkKey) {
     const max = bitmap.maximum?.();
@@ -491,11 +598,12 @@ var SegmentEngine = class {
    * **Costs nothing on a normal combine.** `exists` is consulted only for an operand that resolved to zero
    * chunks — a segment with data is self-evidently registered — so the check is a registry read exactly when
    * a combine was about to do something suspicious, and no reads at all otherwise. A source that cannot answer
-   * `exists` (it has no notion of registration) skips the check rather than guessing.
+   * `exists` (it has no notion of registration) skips the check rather than guessing. An operand is judged by
+   * all its chunks, not those inside a range: one with nothing in range but data elsewhere is not suspicious.
    */
   async refuseAbsentOperands(resolved, allow, op) {
     if (allow === true || this.storage.exists === void 0) return;
-    const empty = resolved.filter((o) => o.keys.size === 0);
+    const empty = resolved.filter((o) => o.chunkless);
     if (empty.length === 0) return;
     const checked = await Promise.all(
       empty.map(async (o) => ({ seg: o.seg, exists: await this.storage.exists(o.seg) }))
@@ -531,8 +639,8 @@ var SegmentEngine = class {
    * The cache-key component identifying **which bytes** this op will read: the source's `currentVersion` when
    * it has one, else the generation alone.
    *
-   * The generation alone is not an identity. `nextGeneration` restarts at 0 once a row is purged and the
-   * bucket emptied, so a retired-and-re-created name serves different data at the same `currentGen` — and a
+   * The generation alone is not an identity. A load's generation number restarts at 0 once a row is purged
+   * and the bucket emptied, so a retired-and-re-created name serves different data at the same `currentGen` — and a
    * decoded chunk cached under `(segment, chunk, 0)` is handed straight back to the new incarnation. That is an
    * erased id reappearing with no read to intercept it, which is why this is keyed on the version rather than
    * the number.
@@ -547,7 +655,7 @@ var SegmentEngine = class {
    * keyed by it, so a load that advances the generation misses the cache and re-reads the new bytes instead of
    * serving a stale decoded chunk (an erased id can't resurrect from a cached superseded chunk). `gen === null`
    * ⇒ the source reports no current generation ⇒ no storage bytes for any chunk, so skip the fetch entirely.
-   * `gen === undefined` ⇒ the source can't report a generation (pins one for its lifetime) ⇒ the key stays
+   * `gen === undefined` ⇒ the source can't report a generation (it only ever serves one) ⇒ the key stays
    * generation-free. Superseded-generation entries age out under the LRU ceiling — no active purge.
    *
    * The returned instance is **shared** (it may be the cached one): callers read it or clone it, never mutate it.
@@ -721,18 +829,58 @@ var BoundedLru = class {
   }
 };
 
+// src/core/reader-defaults.ts
+var DEFAULT_CURRENT_GEN_TTL_MS = 2e3;
+var REFRESH_RETRY_MS = 500;
+var DEFAULT_MAX_OPEN_SEGMENTS = 1024;
+var DEFAULT_MAX_OPEN_INDEX_BYTES = 64 * 1024 * 1024;
+
 // src/core/cost.ts
-var AWS_US_EAST_1_ONDEMAND = {
+function deepFreeze(value) {
+  if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
+    Object.freeze(value);
+    for (const inner of Object.values(value)) deepFreeze(inner);
+  }
+  return value;
+}
+var ELASTICACHE_REDIS_US_EAST_1_ONDEMAND = deepFreeze({
+  source: "ElastiCache for Redis OSS, us-east-1 on-demand, AWS price list 20260914063714",
+  replicasPerShard: 2,
+  reservedMemoryFraction: 0.25,
+  nodeTypes: [
+    { name: "cache.t4g.micro", memoryGiB: 0.5, hourlyUSD: 0.016, maxShards: 1 },
+    { name: "cache.t4g.small", memoryGiB: 1.37, hourlyUSD: 0.032, maxShards: 1 },
+    { name: "cache.t4g.medium", memoryGiB: 3.09, hourlyUSD: 0.065, maxShards: 1 },
+    { name: "cache.m6g.large", memoryGiB: 6.38, hourlyUSD: 0.149 },
+    { name: "cache.r6g.large", memoryGiB: 13.07, hourlyUSD: 0.206 },
+    { name: "cache.r6g.xlarge", memoryGiB: 26.32, hourlyUSD: 0.411 },
+    { name: "cache.r6g.2xlarge", memoryGiB: 52.82, hourlyUSD: 0.821 },
+    { name: "cache.r6g.4xlarge", memoryGiB: 105.81, hourlyUSD: 1.642 },
+    { name: "cache.r6g.8xlarge", memoryGiB: 209.55, hourlyUSD: 3.284 },
+    { name: "cache.r6g.12xlarge", memoryGiB: 317.77, hourlyUSD: 4.925 },
+    { name: "cache.r6g.16xlarge", memoryGiB: 419.09, hourlyUSD: 6.567 },
+    { name: "cache.r6gd.xlarge", memoryGiB: 26.32, ssdGiB: 99.33, hourlyUSD: 0.781 },
+    { name: "cache.r6gd.2xlarge", memoryGiB: 52.82, ssdGiB: 199.07, hourlyUSD: 1.56 },
+    { name: "cache.r6gd.4xlarge", memoryGiB: 105.81, ssdGiB: 398.14, hourlyUSD: 3.12 },
+    { name: "cache.r6gd.8xlarge", memoryGiB: 209.55, ssdGiB: 796.28, hourlyUSD: 6.24 },
+    { name: "cache.r6gd.12xlarge", memoryGiB: 317.77, ssdGiB: 1194.42, hourlyUSD: 9.358 },
+    { name: "cache.r6gd.16xlarge", memoryGiB: 419.09, ssdGiB: 1592.56, hourlyUSD: 12.477 }
+  ]
+});
+var ONE_REDIS_HA_CLUSTER = deepFreeze({ monthlyUSD: 346 });
+var AWS_US_EAST_1_ONDEMAND = deepFreeze({
   name: "aws-us-east-1-ondemand",
   storage: { getPerMillion: 0.4, putPerMillion: 5, storagePerGiBMonth: 0.023 },
-  redis: { monthlyUSD: 346 }
-  // ElastiCache HA: 1 primary + 2 replicas (cache.m7g.large); ~$115 single-node
-};
-var DEFAULT_PRICING = AWS_US_EAST_1_ONDEMAND;
-var SECONDS_PER_MONTH = 730 * 3600;
+  redis: { sizedToData: ELASTICACHE_REDIS_US_EAST_1_ONDEMAND }
+});
+var HOURS_PER_MONTH = 730;
+var SECONDS_PER_MONTH = HOURS_PER_MONTH * 3600;
 var GIB = 1024 ** 3;
+var SIZED_READS_PER_COLD_OPERAND = 2;
+var STORE_LOAD_PUT_CLASS = 3;
+var STORE_LOAD_SIZED_READS = 9;
 function requireFiniteNonNeg(n, field) {
-  if (!Number.isFinite(n) || n < 0) {
+  if (n === void 0 || !Number.isFinite(n) || n < 0) {
     throw new ValidationError(`${field} must be a finite number >= 0; got ${n}`);
   }
   return n;
@@ -740,6 +888,147 @@ function requireFiniteNonNeg(n, field) {
 function clamp01(n) {
   return n < 0 ? 0 : n > 1 ? 1 : n;
 }
+var TIE_USD = 1e-6;
+function usableGiB(sizing, nodeType) {
+  return nodeType.memoryGiB * (1 - sizing.reservedMemoryFraction) + (nodeType.ssdGiB ?? 0);
+}
+function validateSizing(sizing) {
+  const at = "pricing.redis.sizedToData";
+  if (sizing === null || typeof sizing !== "object") {
+    throw new ValidationError(`${at} must be a RedisSizing`);
+  }
+  if (typeof sizing.source !== "string" || sizing.source === "") {
+    throw new ValidationError(`${at}.source must say where the prices come from`);
+  }
+  if (!Array.isArray(sizing.nodeTypes) || sizing.nodeTypes.length === 0) {
+    throw new ValidationError(`${at}.nodeTypes must list at least one node type`);
+  }
+  if (!Number.isInteger(sizing.replicasPerShard) || sizing.replicasPerShard < 0) {
+    throw new ValidationError(
+      `${at}.replicasPerShard must be an integer >= 0; got ${sizing.replicasPerShard}`
+    );
+  }
+  const reserved = requireFiniteNonNeg(
+    sizing.reservedMemoryFraction,
+    `${at}.reservedMemoryFraction`
+  );
+  if (reserved >= 1) {
+    throw new ValidationError(`${at}.reservedMemoryFraction must be below 1; got ${reserved}`);
+  }
+  const names = /* @__PURE__ */ new Set();
+  for (const n of sizing.nodeTypes) {
+    if (n === null || typeof n !== "object" || typeof n.name !== "string" || n.name === "") {
+      throw new ValidationError(`${at}.nodeTypes: every node type needs a name`);
+    }
+    const row = `${at}.nodeTypes[${JSON.stringify(n.name)}]`;
+    if (names.has(n.name)) throw new ValidationError(`${row} is listed twice`);
+    names.add(n.name);
+    if (!(requireFiniteNonNeg(n.memoryGiB, `${row}.memoryGiB`) > 0)) {
+      throw new ValidationError(`${row}.memoryGiB must be above 0`);
+    }
+    requireFiniteNonNeg(n.ssdGiB ?? 0, `${row}.ssdGiB`);
+    requireFiniteNonNeg(n.hourlyUSD, `${row}.hourlyUSD`);
+    if (n.maxShards !== void 0 && (!Number.isInteger(n.maxShards) || n.maxShards < 1)) {
+      throw new ValidationError(`${row}.maxShards must be an integer >= 1; got ${n.maxShards}`);
+    }
+    if (!(usableGiB(sizing, n) > 0)) {
+      throw new ValidationError(
+        `${row} leaves no memory for data once ${reserved} of it is reserved`
+      );
+    }
+  }
+}
+function cheapestCluster(sizing, dataGiB) {
+  const fits = [];
+  for (const nodeType of sizing.nodeTypes) {
+    const usable = usableGiB(sizing, nodeType);
+    let shards = Math.max(1, Math.ceil(dataGiB / usable));
+    if (shards > 1 && (shards - 1) * usable >= dataGiB) shards -= 1;
+    if (nodeType.maxShards !== void 0 && shards > nodeType.maxShards) continue;
+    const nodes = shards * (1 + sizing.replicasPerShard);
+    fits.push({
+      nodeType,
+      shards,
+      nodes,
+      monthlyUSD: nodes * nodeType.hourlyUSD * HOURS_PER_MONTH
+    });
+  }
+  const size = bytesWords(dataGiB * GIB);
+  if (fits.length === 0) {
+    throw new ValidationError(
+      `no node type in pricing.redis.sizedToData.nodeTypes holds ${size} within its maxShards`
+    );
+  }
+  const cheapest = fits.reduce((m, c) => Math.min(m, c.monthlyUSD), Infinity);
+  const [best] = fits.filter((c) => c.monthlyUSD <= cheapest + TIE_USD).sort(
+    (a, b) => a.nodes - b.nodes || a.monthlyUSD - b.monthlyUSD || (a.nodeType.name < b.nodeType.name ? -1 : a.nodeType.name > b.nodeType.name ? 1 : 0)
+  );
+  if (best === void 0 || !Number.isFinite(best.monthlyUSD)) {
+    throw new ValidationError(
+      `pricing.redis.sizedToData prices ${size} at no finite cost; check its node types`
+    );
+  }
+  return best;
+}
+function snapshotSizing(sizing) {
+  if (sizing === null || typeof sizing !== "object") return sizing;
+  const { source, nodeTypes, replicasPerShard, reservedMemoryFraction } = sizing;
+  const row = (n) => {
+    if (n === null || typeof n !== "object") return n;
+    const { name, memoryGiB, ssdGiB, hourlyUSD, maxShards } = n;
+    return {
+      name,
+      memoryGiB,
+      hourlyUSD,
+      ...ssdGiB === void 0 ? {} : { ssdGiB },
+      ...maxShards === void 0 ? {} : { maxShards }
+    };
+  };
+  return {
+    source,
+    replicasPerShard,
+    reservedMemoryFraction,
+    nodeTypes: Array.isArray(nodeTypes) ? Array.from(nodeTypes, row) : nodeTypes
+  };
+}
+function resolveBaseline(redis, storedGiB) {
+  if (redis === null || typeof redis !== "object") {
+    throw new ValidationError("pricing.redis must be { monthlyUSD } or { sizedToData }");
+  }
+  const { monthlyUSD, sizedToData } = redis;
+  const fixed = monthlyUSD !== void 0;
+  const sized = sizedToData !== void 0;
+  if (fixed === sized) {
+    throw new ValidationError(
+      "pricing.redis must be exactly one of { monthlyUSD } and { sizedToData }" + (fixed ? ", not both: spreading AWS_US_EAST_1_ONDEMAND.redis keeps its sizedToData, so pass redis: { monthlyUSD } alone" : "")
+    );
+  }
+  if (sized) {
+    const sizing = snapshotSizing(sizedToData);
+    validateSizing(sizing);
+    const cluster = cheapestCluster(sizing, storedGiB);
+    return { monthlyUSD: cluster.monthlyUSD, sized: { sizing, cluster } };
+  }
+  return { monthlyUSD: requireFiniteNonNeg(monthlyUSD, "pricing.redis.monthlyUSD") };
+}
+function bytesWords(bytes) {
+  const units = ["bytes", "KiB", "MiB", "GiB", "TiB", "PiB"];
+  let value = bytes;
+  let unit = 0;
+  const shown = (v, u) => u === 0 ? Math.round(v) : Number(v.toFixed(2));
+  while (unit < units.length - 1 && shown(value, unit) >= 1024) {
+    value /= 1024;
+    unit += 1;
+  }
+  if (unit > 0) return `${value.toFixed(2)} ${units[unit]}`;
+  const n = Math.round(value);
+  return `${n} byte${n === 1 ? "" : "s"}`;
+}
+function clusterWords(c) {
+  const count = (n) => n.toLocaleString("en-US");
+  const nodes = `${count(c.nodes)} ${c.nodeType.name} node${c.nodes === 1 ? "" : "s"}`;
+  return c.shards === 1 ? `1 shard of ${nodes}` : `${count(c.shards)} shards, ${nodes}`;
+}
 function sizingBytes(spec) {
   if (spec.sizeBytes !== void 0) return requireFiniteNonNeg(spec.sizeBytes, "segment.sizeBytes");
   if (spec.cardinality !== void 0) {
@@ -754,8 +1043,14 @@ function buildReport(input) {
   requireFiniteNonNeg(storage.getPerMillion, "pricing.storage.getPerMillion");
   requireFiniteNonNeg(storage.putPerMillion, "pricing.storage.putPerMillion");
   requireFiniteNonNeg(storage.storagePerGiBMonth, "pricing.storage.storagePerGiBMonth");
-  requireFiniteNonNeg(redis.monthlyUSD, "pricing.redis.monthlyUSD");
+  const sizedRead = requireFiniteNonNeg(
+    storage.requestsPerSizedRead ?? 1,
+    "pricing.storage.requestsPerSizedRead"
+  );
   const storageBytes = requireFiniteNonNeg(input.storageBytes, "storageBytes");
+  const storedGiB = storageBytes / GIB;
+  const baseline = resolveBaseline(redis, storedGiB);
+  const baselineUSD = baseline.monthlyUSD;
   const cacheHitRate = clamp01(
     requireFiniteNonNeg(input.workload.cacheHitRate ?? 0, "cacheHitRate")
   );
@@ -773,36 +1068,92 @@ function buildReport(input) {
     input.workload.requestsPerLoad ?? 1,
     "requestsPerLoad"
   );
+  const operandsPerIntersect = requireFiniteNonNeg(
+    input.workload.operandsPerIntersect ?? 2,
+    "operandsPerIntersect"
+  );
+  if (operandsPerIntersect < 1) {
+    throw new ValidationError(
+      `operandsPerIntersect must be at least 1, since an intersection reads its operands; got ${operandsPerIntersect}`
+    );
+  }
+  const hotSegments = requireFiniteNonNeg(input.workload.hotSegments ?? 0, "hotSegments");
+  const readerProcesses = requireFiniteNonNeg(
+    input.workload.readerProcesses ?? 1,
+    "readerProcesses"
+  );
+  if (readerProcesses < 1) {
+    throw new ValidationError(`readerProcesses must be at least 1; got ${readerProcesses}`);
+  }
+  const genTtlMs = requireFiniteNonNeg(
+    input.workload.genTtlMs ?? DEFAULT_CURRENT_GEN_TTL_MS,
+    "genTtlMs"
+  );
   const storageGetUSD = storage.getPerMillion / 1e6;
   const putUSD = storage.putPerMillion / 1e6;
   const missFraction = 1 - cacheHitRate;
   const readMisses = readsPerSec * S * missFraction;
   const intersects = intersectsPerSec * S;
-  const storageUSD = storageBytes / GIB * storage.storagePerGiBMonth;
+  const refreshes = genTtlMs > 0 ? Math.min(readerProcesses * hotSegments * S * 1e3 / genTtlMs, readsPerSec * S) : 0;
+  const storageUSD = storedGiB * storage.storagePerGiBMonth;
   const readsUSD = readMisses * storageGetUSD;
-  const intersectsUSD = intersects * chunksPerIntersect * storageGetUSD;
-  const loadsUSD = loadsPerMonth * requestsPerLoad * putUSD;
-  const total = readsUSD + intersectsUSD + storageUSD + loadsUSD;
-  const headroom = Math.max(0, redis.monthlyUSD - storageUSD);
+  const intersectGets = chunksPerIntersect + SIZED_READS_PER_COLD_OPERAND * operandsPerIntersect * sizedRead;
+  const intersectsUSD = intersects * intersectGets * storageGetUSD;
+  const loadGets = STORE_LOAD_SIZED_READS * sizedRead;
+  const loadsUSD = loadsPerMonth * ((requestsPerLoad + STORE_LOAD_PUT_CLASS) * putUSD + loadGets * storageGetUSD);
+  const refreshUSD = refreshes * sizedRead * storageGetUSD;
+  const total = readsUSD + intersectsUSD + storageUSD + loadsUSD + refreshUSD;
+  const headroom = Math.max(0, baselineUSD - storageUSD - refreshUSD);
   const readsCross = storageGetUSD > 0 && missFraction > 0 ? headroom / (S * storageGetUSD * missFraction) : Infinity;
-  const verdict = total <= redis.monthlyUSD * 0.1 ? "win-big" : total < redis.monthlyUSD ? "win" : "lose-zone";
-  const dominant = Math.max(readsUSD, intersectsUSD, storageUSD, loadsUSD);
+  const verdict = total <= baselineUSD * 0.1 ? "win-big" : total < baselineUSD ? "win" : "lose-zone";
+  const dominant = Math.max(readsUSD, intersectsUSD, storageUSD, loadsUSD, refreshUSD);
   let driver = "storage";
   if (dominant === readsUSD && readsUSD > 0) driver = "point reads (object GETs)";
-  else if (dominant === intersectsUSD && intersectsUSD > 0) driver = "intersection chunk fetches";
-  else if (dominant === loadsUSD && loadsUSD > 0) driver = "loads (object PUTs)";
-  const rationale = verdict === "lose-zone" ? `pay-per-use total $${total.toFixed(2)}/mo exceeds the $${redis.monthlyUSD}/mo flat baseline; dominated by ${driver}` : verdict === "win-big" ? `$${total.toFixed(2)}/mo \u2014 \u226410% of the $${redis.monthlyUSD}/mo baseline; dominated by ${driver}` : `$${total.toFixed(2)}/mo, under the $${redis.monthlyUSD}/mo baseline; dominated by ${driver}`;
+  else if (dominant === intersectsUSD && intersectsUSD > 0) {
+    driver = "intersections (pointer, index and chunk GETs)";
+  } else if (dominant === loadsUSD && loadsUSD > 0)
+    driver = "loads (object, listing and pointer requests)";
+  else if (dominant === refreshUSD && refreshUSD > 0) driver = "the pointer refresh (object GETs)";
+  const sized = baseline.sized;
+  const noBytes = Math.round(storageBytes) === 0;
+  const redisWords = sized === void 0 ? void 0 : noBytes ? `$${baselineUSD.toFixed(2)}/mo cheapest Redis cluster in the catalogue, as no bytes are counted (${clusterWords(sized.cluster)})` : `$${baselineUSD.toFixed(2)}/mo Redis that would hold ${bytesWords(storageBytes)} (${clusterWords(sized.cluster)})`;
+  const rationale = verdict === "lose-zone" ? `pay-per-use total $${total.toFixed(2)}/mo exceeds the ${redisWords ?? `$${baselineUSD}/mo flat baseline`}; dominated by ${driver}` : verdict === "win-big" ? `$${total.toFixed(2)}/mo \u2014 \u226410% of the ${redisWords ?? `$${baselineUSD}/mo baseline`}; dominated by ${driver}` : `$${total.toFixed(2)}/mo, under the ${redisWords ?? `$${baselineUSD}/mo baseline`}; dominated by ${driver}`;
+  const dataTiering = sized !== void 0 && (sized.cluster.nodeType.ssdGiB ?? 0) > 0;
+  const redisNote = sized === void 0 ? `Redis priced at the fixed $${baselineUSD}/mo given, whatever the data size.` : (noBytes ? "Redis priced at the cheapest cluster in the catalogue, as no bytes are counted, because nothing is stored or nothing was measured" : `Redis priced at the cheapest cluster in the catalogue that holds the ${bytesWords(storageBytes)} stored`) + `: ${clusterWords(sized.cluster)}, each shard a primary and ${sized.sizing.replicasPerShard} replica(s), ${Number((sized.sizing.reservedMemoryFraction * 100).toFixed(1))}% of memory reserved (${sized.sizing.source}).` + (noBytes ? " Pass pricing.redis: { monthlyUSD } to compare against a Redis of your own." : " Compressed bytes are a floor on the memory Redis needs: a native Redis bitmap is sized by its highest id, so sparse ids need more.") + " Redis bought another way \u2014 fewer replicas, another engine, reserved nodes \u2014 can cost less than the catalogue prices it." + (dataTiering ? ` ${sized.cluster.nodeType.name} is a data-tiering node, which keeps the values read least recently on its SSD. It is priced as if the data read often fits in its memory: AWS recommends data tiering for workloads that regularly read up to 20% of their data.` : "") + (input.sizesFromCardinality ? " Some segment sizes came from cardinality, at 2 bytes an id, which is more than a dense bitmap needs, so this Redis may be larger than the data calls for: pass sizeBytes to size it to the compressed bytes." : "");
   const notes = [
     "Same-region egress treated as free; internet egress is not modeled.",
     "Request cost is from the supplied workload rates (live-metrics-derived request cost is a later phase).",
-    loadsPerMonth > 0 ? `Loads modeled: ${loadsPerMonth}/mo \xD7 ${requestsPerLoad} PUT-class request(s) each.` : "Loads are NOT modeled \u2014 set workload.loadsPerMonth (+ requestsPerLoad for multipart) to include them.",
-    ...input.extraNotes ?? []
-  ];
+    loadsPerMonth > 0 ? `Loads modeled: ${loadsPerMonth}/mo, each ${requestsPerLoad} PUT-class request(s) for the object plus ${STORE_LOAD_PUT_CLASS} PUT-class and ${loadGets} GETs that store.load() adds (listings, pointer, index).` : "Loads are NOT modeled \u2014 set workload.loadsPerMonth (+ requestsPerLoad for multipart) to include them.",
+    ...intersects > 0 ? [
+      `Intersections priced cold: ${intersectGets} GETs each, ${SIZED_READS_PER_COLD_OPERAND * sizedRead} for each of ${operandsPerIntersect} operand(s) plus ${chunksPerIntersect} chunk read(s); cacheHitRate does not apply.`
+    ] : [],
+    hotSegments > 0 ? genTtlMs > 0 ? `Pointer refresh modeled: ${hotSegments} hot segment(s) in each of ${readerProcesses} reader process(es), each re-reading its pointer at most every ${genTtlMs} ms, and at most once a point read.` : "Pointer refresh: none \u2014 genTtlMs 0 turns the timed refresh off. A reader still re-reads a pointer on an eviction, a swept generation or an invalidation, which this does not price." : readsPerSec > 0 ? "The pointer refresh is NOT modeled \u2014 set workload.hotSegments to the segments each long-lived reader keeps reading, and workload.readerProcesses to how many readers there are." : null,
+    hotSegments > DEFAULT_MAX_OPEN_SEGMENTS ? `More hot segments in a reader than a store keeps open by default (${DEFAULT_MAX_OPEN_SEGMENTS}): a read of a segment the reader evicted opens it again, a pointer and a tail read, which this does not price. Raise cache.readerMax, and cache.readerMaxBytes, to keep them open.` : null,
+    ...input.extraNotes ?? [],
+    // Last, so the notes a report already carried keep their places.
+    redisNote
+  ].filter((n) => n !== null);
   return {
     monthlyUSD: {
-      byOp: { reads: readsUSD, intersects: intersectsUSD, storage: storageUSD, loads: loadsUSD },
+      byOp: {
+        reads: readsUSD,
+        intersects: intersectsUSD,
+        storage: storageUSD,
+        loads: loadsUSD,
+        pointerRefresh: refreshUSD
+      },
       total
     },
+    redisBaseline: sized === void 0 ? { basis: "fixed", monthlyUSD: baselineUSD } : {
+      basis: "sized-to-data",
+      monthlyUSD: baselineUSD,
+      cluster: {
+        nodeType: sized.cluster.nodeType.name,
+        shards: sized.cluster.shards,
+        nodes: sized.cluster.nodes,
+        dataTiering
+      }
+    },
     redisCrossover: { readsPerSec: readsCross },
     verdict,
     rationale,
@@ -810,36 +1161,39 @@ function buildReport(input) {
   };
 }
 function estimateCost(input) {
-  const pricing = input.pricing ?? DEFAULT_PRICING;
+  const pricing = input.pricing ?? AWS_US_EAST_1_ONDEMAND;
   const workload = input.workload ?? {};
   let storageBytes = 0;
+  let sizesFromCardinality = false;
   for (const spec of input.segments) {
     const count = Math.floor(requireFiniteNonNeg(spec.count ?? 1, "segment.count"));
     storageBytes += sizingBytes(spec) * count;
+    if (spec.sizeBytes === void 0 && spec.cardinality !== void 0 && sizingBytes(spec) * count > 0) {
+      sizesFromCardinality = true;
+    }
   }
-  return buildReport({ storageBytes, workload, pricing, grounded: false });
+  return buildReport({ storageBytes, workload, pricing, grounded: false, sizesFromCardinality });
 }
 function groundedReport(input) {
   return buildReport({
     storageBytes: input.storageBytes,
     workload: input.workload ?? {},
-    pricing: input.pricing ?? DEFAULT_PRICING,
+    pricing: input.pricing ?? AWS_US_EAST_1_ONDEMAND,
     grounded: input.grounded ?? true,
     extraNotes: input.extraNotes
   });
 }
 
 // src/core/due-index.ts
-var DUE_NAMESPACE_PREFIX = "cbm.due.";
 var DUE_BUCKET_MS = 864e5;
 function dueBucket(expiresAt) {
   return Math.floor(expiresAt / DUE_BUCKET_MS);
 }
 function dueNamespace(bucket) {
-  return `${DUE_NAMESPACE_PREFIX}${bucket}`;
+  return `${RESERVED_NAMESPACE_PREFIX}${bucket}`;
 }
 function isDueIndexRow(record) {
-  return record.namespace !== void 0 && record.namespace.startsWith(DUE_NAMESPACE_PREFIX);
+  return isReservedNamespace(record.namespace);
 }
 function encodeDueName(ref) {
   const ns = ref.namespace ?? "";
@@ -891,12 +1245,14 @@ function validateMaxScanSegments(value, op) {
 async function drainRegistry(registry, options) {
   const { maxScanSegments, op } = options;
   validateMaxScanSegments(maxScanSegments, op);
+  const raise = options.raise ?? "raise `maxScanSegments`";
+  const advice = options.narrowable === false ? `${raise[0].toUpperCase()}${raise.slice(1)} if the namespace really is that large and the memory is ` : `Narrow it with \`namespace\`, or ${raise} if the fleet really is that large and the memory is `;
   const rows = [];
   for await (const rec of registry.list(options.namespace)) {
     if (options.namespace === void 0 && isReservedRow(rec)) continue;
     if (rows.length >= maxScanSegments) {
       throw new BudgetExceededError(
-        `${op} would enumerate more than ${maxScanSegments} segments \u2014 the scan was abandoned there rather than completed. Narrow it with \`namespace\`, or raise \`maxScanSegments\` if the fleet really is that large and the memory is available (a record is a few hundred bytes resident).`
+        `${op} would enumerate more than ${maxScanSegments} segments \u2014 the scan was abandoned there rather than completed. ${advice}available (a record is a few hundred bytes resident).`
       );
     }
     rows.push(rec);
@@ -916,7 +1272,7 @@ async function* excludingReservedRows(source) {
 function requireCodec(codec, api) {
   if (codec === void 0) {
     throw new ValidationError(
-      `${api} needs a bitmap codec: pass \`codec\` (e.g. \`roaringCodec\` from @cloudbitmaps/roaring). @cloudbitmaps/core is codec-agnostic and has no default \u2014 install a flavor package, whose equivalents bind the codec for you.`
+      `${api} needs a bitmap codec: pass \`codec\`. @cloudbitmaps/core is codec-agnostic and has no default. A flavor's store passes its own codec, so an application calls the store's method instead of this function.`
     );
   }
   return codec;
@@ -926,6 +1282,7 @@ function requireCodec(codec, api) {
 var DEFAULT_NDJSON_BATCH_BYTES = 64 * 1024;
 var errMessage = (err) => err instanceof Error ? err.message : String(err);
 async function runExport(reader, registry, sink, options = {}) {
+  if (options.namespace !== void 0) validateUserNamespace(options.namespace);
   const format = options.format ?? "roaring";
   const ext = format === "roaring" ? ".roaring" : ".ndjson";
   const batchCap = options.ndjsonBatchBytes ?? DEFAULT_NDJSON_BATCH_BYTES;
@@ -997,13 +1354,12 @@ async function runExport(reader, registry, sink, options = {}) {
 
 // src/core/discover.ts
 async function segmentExists(ref, registry) {
-  validateSegmentRef(ref);
+  validateUserRef(ref);
   const record = await registry.get(ref);
   return record !== null && record.status !== "destroyed" && record.currentGen !== null;
 }
 async function* listSegments(registry, options = {}) {
-  if (options.namespace !== void 0)
-    validateSegmentRef({ segment: "x", namespace: options.namespace });
+  if (options.namespace !== void 0) validateUserNamespace(options.namespace);
   const raw = registry.list(options.namespace);
   const source = options.namespace === void 0 ? excludingReservedRows(raw) : raw;
   for await (const record of source) {
@@ -1016,6 +1372,9 @@ async function* listSegments(registry, options = {}) {
   }
 }
 
+// src/drivers/backends.ts
+import { join as join3 } from "node:path";
+
 // src/drivers/memory.ts
 import { createHash } from "node:crypto";
 
@@ -1059,39 +1418,6 @@ var BufferReader = class {
 };
 
 // src/drivers/memory.ts
-var MemoryStorageChunkSource = class {
-  chunks = /* @__PURE__ */ new Map();
-  async getChunk(ref) {
-    validateChunkRef(ref);
-    return this.chunks.get(chunkRefKey(ref)) ?? null;
-  }
-  async listChunkKeys(ref) {
-    validateSegmentRef(ref);
-    const prefix = segmentPrefix(ref);
-    const keys = [];
-    for (const key of this.chunks.keys()) {
-      if (key.startsWith(prefix)) keys.push(Number(key.slice(prefix.length)));
-    }
-    return keys;
-  }
-  async sizeOf(ref) {
-    validateSegmentRef(ref);
-    const prefix = segmentPrefix(ref);
-    let sizeBytes = 0;
-    let found = false;
-    for (const [key, bytes] of this.chunks) {
-      if (!key.startsWith(prefix)) continue;
-      found = true;
-      sizeBytes += bytes.length;
-    }
-    return found ? { sizeBytes } : null;
-  }
-  /** Test/seed helper — populate immutable Storage bytes for a chunk directly (bypassing the `.crbm` format). */
-  seed(ref, bytes) {
-    validateChunkRef(ref);
-    this.chunks.set(chunkRefKey(ref), bytes);
-  }
-};
 var MemoryRegistryDriver = class {
   rows = /* @__PURE__ */ new Map();
   now;
@@ -1139,9 +1465,13 @@ var MemoryRegistryDriver = class {
       if (namespace === void 0 || row.namespace === namespace) yield structuredClone(row);
     }
   }
-  async delete(ref) {
+  async delete(ref, expected) {
     validateSegmentRef(ref);
-    this.rows.delete(segmentKey(ref));
+    const key = segmentKey(ref);
+    if (expected !== void 0 && this.rows.get(key)?.token !== expected) {
+      throw new WriteConflictError(`OCC token mismatch for registry row ${ref.segment}`);
+    }
+    this.rows.delete(key);
   }
 };
 var MemoryStorageDriver = class {
@@ -1421,17 +1751,31 @@ var LocalFsStorageDriver = class {
 // src/drivers/localfs/registry.ts
 import { constants as FS3 } from "node:fs";
 import { randomUUID as randomUUID2 } from "node:crypto";
-import { mkdir as mkdir2, open as open3, readdir as readdir2, rename, unlink as unlink2 } from "node:fs/promises";
-import { dirname as dirname2 } from "node:path";
+import { mkdir as mkdir2, open as open3, readdir as readdir2, realpath, rename, unlink as unlink2 } from "node:fs/promises";
+import { basename, dirname as dirname2, join as join2, resolve } from "node:path";
 var DEFAULT_MAX_ROW_BYTES = 1 * 1024 * 1024;
+var rowChains = /* @__PURE__ */ new Map();
+async function rowLockKey(path) {
+  const abs = resolve(path);
+  const tail = [basename(abs)];
+  let dir = dirname2(abs);
+  for (; ; ) {
+    try {
+      return join2(await realpath(dir), ...tail);
+    } catch (err) {
+      const parent = dirname2(dir);
+      if (!isCode(err, "ENOENT") || parent === dir) throw mapFsError(err);
+      tail.unshift(basename(dir));
+      dir = parent;
+    }
+  }
+}
 var LocalFsRegistryDriver = class {
   constructor(root, options = {}) {
     this.root = root;
     this.now = options.now ?? (() => Date.now());
   }
   root;
-  /** Per-row promise chain — serializes read-modify-write so an in-process CAS never loses an update. */
-  chain = /* @__PURE__ */ new Map();
   now;
   capabilities() {
     return { strongRead: true };
@@ -1489,11 +1833,17 @@ var LocalFsRegistryDriver = class {
       }
     }
   }
-  async delete(ref) {
+  async delete(ref, expected) {
     const path = registryRowPath(this.root, ref);
     return this.withRowLock(path, async () => {
       const current = await this.readRow(path);
-      if (current === null || current.deleted) return;
+      if (expected !== void 0) {
+        if (current === null || current.deleted || current.record.token !== expected) {
+          throw new WriteConflictError(`OCC token mismatch for registry row ${ref.segment}`);
+        }
+      } else if (current === null || current.deleted) {
+        return;
+      }
       const token = String(registryCounterOf(current.record) + 1);
       await this.writeRow(path, true, { ...current.record, token, updatedAt: this.now() });
     });
@@ -1562,25 +1912,24 @@ var LocalFsRegistryDriver = class {
     });
     await fsyncDir(dirname2(path));
   }
-  /** Serialize callbacks for a row path so read-modify-write is atomic in-process. */
-  withRowLock(key, fn) {
-    const prev = this.chain.get(key) ?? Promise.resolve();
+  /** Serialize callbacks for a row so read-modify-write is atomic across every instance in the process. */
+  async withRowLock(path, fn) {
+    const key = await rowLockKey(path);
+    const prev = rowChains.get(key) ?? Promise.resolve();
     const result = prev.then(fn, fn);
     const tail = result.then(
       () => void 0,
       () => void 0
     );
-    this.chain.set(key, tail);
+    rowChains.set(key, tail);
     void tail.then(() => {
-      if (this.chain.get(key) === tail) this.chain.delete(key);
+      if (rowChains.get(key) === tail) rowChains.delete(key);
     });
     return result;
   }
 };
 
 // src/drivers/backends.ts
-import { existsSync } from "node:fs";
-import { join as join2 } from "node:path";
 var MemoryStorage = class {
   storage;
   registry;
@@ -1593,14 +1942,9 @@ var MemoryStorage = class {
 var LocalFsStorage = class {
   constructor(root, options = {}) {
     this.root = root;
-    if (!existsSync(join2(root, "storage")) && existsSync(join2(root, "cold"))) {
-      throw new ValidationError(
-        `${root} holds a "cold/" directory but no "storage/" \u2014 this store was written before the tier was renamed. Rename it (\`mv ${root}/cold ${root}/storage\`) and re-run; the objects inside are unchanged. Do NOT treat the "missing-storage-generation" you would otherwise see as a torn restore \u2014 the data is intact, it is the path that moved.`
-      );
-    }
-    this.storage = new LocalFsStorageDriver(join2(root, "storage"));
+    this.storage = new LocalFsStorageDriver(join3(root, "storage"));
     this.registry = new LocalFsRegistryDriver(
-      join2(root, "registry"),
+      join3(root, "registry"),
       options.now === void 0 ? {} : { now: options.now }
     );
     brandAsBackend(this);
@@ -1779,7 +2123,7 @@ var FOOTER = {
   flags: 20,
   // u32
   payloadCodecId: 24,
-  // u16 — was `roaringSerializationId`; same offset, same width, wider meaning
+  // u16 — which codec wrote the chunk payloads
   elementWidth: 26,
   // u8
   containerCodec: 27,
@@ -1831,6 +2175,29 @@ var RETAINED_BYTES_PER_INDEX_ENTRY = 160;
 function magicMatches(bytes, offset) {
   return bytes[offset] === MAGIC[0] && bytes[offset + 1] === MAGIC[1] && bytes[offset + 2] === MAGIC[2] && bytes[offset + 3] === MAGIC[3];
 }
+var sizePart = (size) => `${size}:`;
+var fingerprintFor = (size, footerCrc) => `${sizePart(size)}${footerCrc}`;
+function checkSize(tail, size) {
+  if (!Number.isSafeInteger(size) || size < tail.length) {
+    throw new IntegrityError(`.crbm size is not a byte count its tail fits in: ${size}`);
+  }
+}
+function checkedFooter(tail, size) {
+  checkSize(tail, size);
+  if (size < PREAMBLE_BYTES + FOOTER_BYTES || tail.length < FOOTER_BYTES) {
+    throw new IntegrityError(`.crbm too small: ${size}B`);
+  }
+  const footer = tail.subarray(tail.length - FOOTER_BYTES);
+  if (!magicMatches(footer, FOOTER.endMagic)) {
+    throw new IntegrityError(".crbm end magic mismatch");
+  }
+  const fview = new DataView(footer.buffer, footer.byteOffset, footer.byteLength);
+  const storedFooterCrc = fview.getUint32(FOOTER.footerCrc32c, true);
+  if (crc32c(footer.subarray(0, FOOTER_CRC_COVERAGE)) !== storedFooterCrc) {
+    throw new IntegrityError(".crbm footer CRC mismatch");
+  }
+  return { footer, fview, storedFooterCrc };
+}
 function readU64(view, offset, field) {
   const big = view.getBigUint64(offset, true);
   if (big > BigInt(Number.MAX_SAFE_INTEGER)) {
@@ -1839,7 +2206,7 @@ function readU64(view, offset, field) {
   return Number(big);
 }
 var CrbmReader = class _CrbmReader {
-  constructor(blob, objectSize, generation, lineage, totalCardinality, entries, orderedKeys, servedFromTail, crypto) {
+  constructor(blob, objectSize, generation, lineage, totalCardinality, entries, orderedKeys, servedFromTail, crypto, footerCrc) {
     this.blob = blob;
     this.objectSize = objectSize;
     this.generation = generation;
@@ -1849,6 +2216,7 @@ var CrbmReader = class _CrbmReader {
     this.orderedKeys = orderedKeys;
     this.servedFromTail = servedFromTail;
     this.crypto = crypto;
+    this.footerCrc = footerCrc;
   }
   blob;
   objectSize;
@@ -1859,6 +2227,15 @@ var CrbmReader = class _CrbmReader {
   orderedKeys;
   servedFromTail;
   crypto;
+  footerCrc;
+  /**
+   * Which object this reader opened, as its size and its footer's CRC. The footer covers the index's CRC, so two
+   * objects with the same fingerprint hold the same chunks, as far as a CRC can tell; a pin compares it to know that
+   * the object it reopens is the one it pinned, since a purged and reloaded name reuses the generation number.
+   */
+  get fingerprint() {
+    return fingerprintFor(this.objectSize, this.footerCrc);
+  }
   /** Total object bytes (from the one-GET tail read) — for grounded storage cost. */
   get sizeBytes() {
     return this.objectSize;
@@ -1877,23 +2254,26 @@ var CrbmReader = class _CrbmReader {
     for (const [chunkKey, entry] of this.entries) out.set(chunkKey, entry.cardinality);
     return out;
   }
+  /**
+   * Whether the object behind `blob` is the one `fingerprint` names ({@link fingerprint}), from one tail read of a
+   * footer's worth, with no key and no index, since the footer is stored in the clear and checked by its own CRC.
+   * Another size is another object, whatever its bytes hold: a short one that is no `.crbm` at all is not the one
+   * pinned. At the same size the footer's CRC says, and a footer that fails its own checks says nothing about which
+   * object is there, so this throws, as an open would. What a pin asks, to tell the object it opened from one that
+   * has since been stored under its key, whoever wrote it.
+   */
+  static async sameObject(blob, fingerprint) {
+    const { bytes: tail, size } = await blob.getTail(FOOTER_BYTES);
+    checkSize(tail, size);
+    if (!fingerprint.startsWith(sizePart(size))) return false;
+    return fingerprintFor(size, checkedFooter(tail, size).storedFooterCrc) === fingerprint;
+  }
   static async open(blob, options = {}) {
     const tailBytes = Math.max(options.tailBytes ?? DEFAULT_TAIL_BYTES, FOOTER_BYTES);
     const maxPayloadBytes = options.maxPayloadBytes ?? DEFAULT_MAX_PAYLOAD_BYTES;
     const maxIndexBytes = options.maxIndexBytes ?? DEFAULT_MAX_INDEX_BYTES;
     const { bytes: tail, size } = await blob.getTail(tailBytes);
-    if (size < PREAMBLE_BYTES + FOOTER_BYTES || tail.length < FOOTER_BYTES) {
-      throw new IntegrityError(`.crbm too small: ${size}B`);
-    }
-    const footer = tail.subarray(tail.length - FOOTER_BYTES);
-    if (!magicMatches(footer, FOOTER.endMagic)) {
-      throw new IntegrityError(".crbm end magic mismatch");
-    }
-    const fview = new DataView(footer.buffer, footer.byteOffset, footer.byteLength);
-    const storedFooterCrc = fview.getUint32(FOOTER.footerCrc32c, true);
-    if (crc32c(footer.subarray(0, FOOTER_CRC_COVERAGE)) !== storedFooterCrc) {
-      throw new IntegrityError(".crbm footer CRC mismatch");
-    }
+    const { footer, fview, storedFooterCrc } = checkedFooter(tail, size);
     const versionMajor = footer[FOOTER.versionMajor];
     if (versionMajor !== VERSION_MAJOR) {
       throw new UnsupportedError(`.crbm major version ${versionMajor} not supported`);
@@ -1970,8 +2350,9 @@ var CrbmReader = class _CrbmReader {
     ) : indexBytes;
     const { entries, orderedKeys, cardinalitySum } = parseIndex(
       indexForParse,
-      size,
-      maxPayloadBytes
+      indexOffset,
+      maxPayloadBytes,
+      encrypted ? AEAD_NONCE_BYTES + AEAD_TAG_BYTES : 1
     );
     if (encrypted) {
       if (chunkCount !== 0 || totalCardinality !== 0) {
@@ -2000,7 +2381,8 @@ var CrbmReader = class _CrbmReader {
       entries,
       orderedKeys,
       servedFromTail,
-      options.crypto
+      options.crypto,
+      storedFooterCrc
     );
   }
   /** Chunk keys present in this generation, ascending. */
@@ -2044,7 +2426,7 @@ var CrbmReader = class _CrbmReader {
     );
   }
 };
-function parseIndex(indexBytes, objectSize, maxPayloadBytes) {
+function parseIndex(indexBytes, payloadEnd, maxPayloadBytes, minPayloadBytes = 1) {
   const entries = /* @__PURE__ */ new Map();
   const orderedKeys = [];
   let pos = 0;
@@ -2068,13 +2450,13 @@ function parseIndex(indexBytes, objectSize, maxPayloadBytes) {
       throw new IntegrityError(`.crbm index has a duplicate chunkKey ${chunkKey}`);
     }
     if (chunkKey > 65535) throw new IntegrityError(`.crbm chunkKey ${chunkKey} out of range`);
-    if (len.value === 0 || len.value > maxPayloadBytes) {
+    if (len.value < minPayloadBytes || len.value > maxPayloadBytes) {
       throw new IntegrityError(`.crbm chunk ${chunkKey} length ${len.value} invalid`);
     }
     if (card.value < 1 || card.value > MAX_CHUNK_CARDINALITY) {
       throw new IntegrityError(`.crbm chunk ${chunkKey} cardinality ${card.value} invalid`);
     }
-    if (offset < PAYLOAD_START || offset + len.value > objectSize - FOOTER_BYTES) {
+    if (offset + len.value > payloadEnd) {
       throw new IntegrityError(`.crbm chunk ${chunkKey} payload out of bounds`);
     }
     entries.set(chunkKey, {
@@ -2244,11 +2626,14 @@ function storageBlobReader(driver, key) {
     }
   };
 }
-var DEFAULT_CURRENT_GEN_TTL_MS = 2e3;
+var notThePinned = (ref, generation) => new NotFoundError(
+  `segment "${ref.segment}" generation ${generation} is no longer the object this handle pinned`
+);
+function versionOf(generation, lineage) {
+  return lineage === void 0 ? String(generation) : `${generation}:${String(lineage)}`;
+}
 var BULK_FLUSH_IDS = 1 << 20;
 var YIELD_EVERY_IDS = 1 << 14;
-var DEFAULT_MAX_OPEN_SEGMENTS = 1024;
-var DEFAULT_MAX_OPEN_INDEX_BYTES = 64 * 1024 * 1024;
 var CrbmStorageChunkSource = class {
   constructor(driver, options = {}) {
     this.driver = driver;
@@ -2284,21 +2669,47 @@ var CrbmStorageChunkSource = class {
       maxBytes: maxOpenIndexBytes ?? DEFAULT_MAX_OPEN_INDEX_BYTES,
       clock: clock ?? { now: () => 0 }
     });
+    this.replacedPins = new BoundedLru({
+      maxEntries: maxOpenSegments ?? DEFAULT_MAX_OPEN_SEGMENTS,
+      clock: { now: () => 0 }
+    });
   }
   driver;
   /**
    * One resolved reader per segment, re-resolved on a short TTL ({@link CrbmStorageChunkSourceOptions.currentGenTtlMs},
    * needs a clock). Within the TTL a segment's Storage bytes are treated as an immutable snapshot; when the TTL
    * elapses the next read cheaply re-resolves `currentGen` and, only if it advanced (a load published),
-   * opens the new generation — so a long-lived source observes new generations within the TTL rather than
-   * pinning one forever. The engine pairs this with a **generation-keyed** cache so a bump never
-   * serves a stale decoded chunk. Without a clock or a registry the source pins the first generation for its
-   * lifetime (the behaviour before the registry was wired in). A segment with no generation yet is not memoized, so it's re-checked until
-   * one exists. **Bounded** by a {@link BoundedLru} ({@link CrbmStorageChunkSourceOptions.maxOpenSegments}, default
+   * opens the new generation — so a long-lived source observes new generations within the TTL. The engine pairs
+   * this with a **generation-keyed** cache so a bump never serves a stale decoded chunk. Without a clock or a
+   * registry there is no timed refresh, and a segment's reader is replaced only when it is evicted, when a read
+   * has to fetch from a generation a sweep deleted, or when {@link invalidate} drops it. A segment with no generation yet is not memoized, so
+   * it's re-checked until one exists. **Bounded** by a {@link BoundedLru} ({@link CrbmStorageChunkSourceOptions.maxOpenSegments}, default
    * 1024): past the ceiling the least-recently-used segment's reader (and its parsed index) is evicted — the
    * steady-state memory bound; re-opening an evicted segment is one cheap tail GET.
    */
   snapshots;
+  /**
+   * Pins ({@link heldKey}) whose object has been found replaced: another object is under its generation's key. Kept,
+   * and bounded as the readers are, so that a pin's later chunk reads and any reopen fail at once rather than pay for
+   * the check again. A replacement can be undone, by a restore that puts the pinned object back, so
+   * {@link invalidate} forgets the segment's, and a pin of the same version that opens the object forgets the one
+   * against it. An object found gone is not kept: that is the open's own `NotFoundError`, and a 404 can pass. A
+   * reader still memoised keeps answering from the index it holds, so the pin's `count()` does, until a later pin of
+   * that version opens the object now under the key, which takes its place.
+   */
+  replacedPins;
+  /**
+   * A check of a pinned object still under way, by {@link heldKey}, so the reads that ask at once share one footer
+   * read. One forgotten before it ends, by {@link invalidate} or a pin, keeps nothing it finds.
+   */
+  checking = /* @__PURE__ */ new Map();
+  /**
+   * How many times {@link invalidate} has run, so a read that waited can tell whether the store was told something
+   * meanwhile. An eviction from the reader cache is not an invalidation, and what a read found stands through one. It
+   * counts every segment's invalidations: a read that waited through another segment's only costs a later read the
+   * check again.
+   */
+  invalidations = 0;
   registry;
   keystore;
   requireEncryption;
@@ -2311,18 +2722,35 @@ var CrbmStorageChunkSource = class {
     const existing = this.snapshots.get(key);
     if (existing === void 0) return this.install(key, this.resolveLatest(ref)).reader;
     if (!this.expired(existing.installedAtMs)) return existing.reader;
-    return this.install(key, this.computeRefreshedReader(ref, existing)).reader;
+    const snap = this.install(
+      key,
+      this.computeRefreshedReader(ref, existing, () => this.retrySoon(snap))
+    );
+    return snap.reader;
+  }
+  /**
+   * A refresh failed transiently and the prior reader keeps serving: make this snapshot lapse after
+   * {@link REFRESH_RETRY_MS} (never longer than the TTL) rather than after a whole TTL, so the next read after
+   * that asks the registry again. It costs no read of its own; it only changes when the next refresh happens.
+   */
+  retrySoon(snap) {
+    snap.installedAtMs = this.now() - (this.currentGenTtlMs - Math.min(this.currentGenTtlMs, REFRESH_RETRY_MS));
   }
   /** TTL elapsed: cheaply re-resolve `currentGen`; reopen only if it actually changed, else reuse the prior reader. */
-  async computeRefreshedReader(ref, existing) {
+  async computeRefreshedReader(ref, existing, onTransientFault) {
     const current = await existing.reader.catch(() => null);
     let target;
     try {
       target = await this.resolveTarget(ref);
-    } catch {
+    } catch (err) {
+      if (!isTransientError(err)) throw err;
       target = void 0;
     }
-    if (target === void 0) return current ?? this.resolveLatest(ref);
+    if (target === void 0) {
+      if (current === null) return this.resolveLatest(ref);
+      onTransientFault();
+      return current;
+    }
     if (target === null) return null;
     if (current !== null && target.generation === current.generation && target.lineage === current.lineage) {
       return current;
@@ -2352,6 +2780,14 @@ var CrbmStorageChunkSource = class {
   now() {
     return this.clock ? this.clock.now() : 0;
   }
+  /**
+   * How often this source re-reads a segment's pointer while the segment is being read, in ms: its TTL, or 0 when
+   * it has no timed refresh (no clock, no registry, or a TTL of 0). The grounded cost report prices the refresh at
+   * this.
+   */
+  get pointerRefreshMs() {
+    return this.clock !== void 0 && this.registry !== void 0 ? this.currentGenTtlMs : 0;
+  }
   expired(installedAtMs) {
     return this.clock !== void 0 && this.registry !== void 0 && this.currentGenTtlMs > 0 && this.clock.now() - installedAtMs >= this.currentGenTtlMs;
   }
@@ -2360,11 +2796,12 @@ var CrbmStorageChunkSource = class {
    * is observed instead of serving a stale decoded chunk. Served from the (TTL-refreshed)
    * snapshot, so no extra backend read within the TTL window. `null` if the segment has no committed generation.
    *
-   * Heals a swept generation exactly like {@link withFreshSnapshot} — the engine calls this **once per op**,
-   * before any chunk fetch, so an unhealed miss here fails the whole operation rather than one chunk. It is
-   * spelled out rather than delegated because this is the hottest call in the library: once per operand of
-   * every `has`/`count`/`iterate`/`intersect`, and almost always served from the cached snapshot with no
-   * backend call at all. Routing it through the generic helper cost ~115 ns/op on that path (a second async
+   * Heals a swept generation exactly like {@link withFreshSnapshot}: a caller that resolves the generation once
+   * per op, before any chunk fetch, would otherwise fail the whole operation rather than one chunk. The engine
+   * keys by {@link currentVersion} instead, which heals the same way, and falls back to this for a source that
+   * cannot report a version. It is spelled out rather than delegated because a lookup like this runs once per
+   * operand of every `has`/`count`/`iterate`/`intersect`, almost always served from the cached snapshot with
+   * no backend call at all. Routing it through the generic helper cost ~115 ns/op on that path (a second async
    * frame, a per-call closure, and an `await` on a plain number) for a race that fires only during a
    * concurrent sweep. One retry, then propagate — same contract, same eviction rule.
    */
@@ -2380,50 +2817,126 @@ var CrbmStorageChunkSource = class {
   }
   /**
    * Forget everything derived from `ref`: the resolved snapshot and the open reader behind it (and with the
-   * reader, the DEK it unwrapped at open time). The next read resolves `currentGen` from the registry again.
+   * reader, the DEK it unwrapped at open time), and what its pins' objects were found to be. The next read
+   * resolves the segment again.
    *
    * Needed because the TTL refresh only ever answers "has the pointer moved?", and every *destructive* verb —
    * an erasure that deletes the generation holding the bit, a `dropSegment`, a crypto-shred, a retirement —
    * leaves the pointer's answer unchanged from this source's point of view while making the snapshot wrong.
    * Until this is called the source keeps serving that snapshot with no backend read at all, so nothing on the
-   * storage side can close the window; with `cache.genTtlMs: 0` or no clock it never closes.
+   * storage side can close the window; with no registry, no clock or `cache.genTtlMs: 0`, nothing bounds it at all.
    */
   invalidate(ref) {
+    this.invalidations += 1;
     const key = segmentKey(ref);
     this.snapshots.delete(key);
     const pinnedPrefix = `${key}@`;
     this.snapshots.deleteWhere((k) => k.startsWith(pinnedPrefix));
+    this.replacedPins.deleteWhere((k) => k.startsWith(pinnedPrefix));
+    for (const k of this.checking.keys()) if (k.startsWith(pinnedPrefix)) this.checking.delete(k);
   }
   /**
-   * Whether the segment is a registered name at all. With a registry that is exactly "a row exists" — including
-   * a row with no generation yet (minted by `setRetention` before the first load) and a `destroyed` tombstone,
-   * both of which are names somebody deliberately created. Without a registry there is no registration to
-   * consult, so the honest answer is whether the bucket holds any generation of it.
+   * `<generation>` for a registry-less source, or `<generation>:<row token>` with one. The token moves on every row
+   * write, so an unrelated write (a `setRetention`) costs the segment's decoded chunks once — bounded, and on an
+   * admin path. Exactness in the direction that matters: with a registry, two incarnations can never share a version
+   * string. Without one they can: a name purged and loaded again out of band restarts at the same bare number, and
+   * a live read that reopens it after an eviction reads the new object's chunks beside the old one's cached ones. A
+   * store with no registry cannot write, so that takes a change made from outside it; a pin is kept apart from it by
+   * the fingerprint it records.
    *
-   * Deliberately NOT served from the snapshot memo: the memo resolves to `null` for both states this exists to
-   * tell apart.
-   */
-  /**
-   * `<generation>` for a registry-less source (no row, so no incarnation to confuse), or
-   * `<generation>:<row token>` with one. The token moves on every row write, so an unrelated write (a
-   * `setRetention`) costs the segment's decoded chunks once — bounded, and on an admin path. Exactness in the
-   * direction that matters: two incarnations can never share a version string.
+   * This is the call the engine makes **once per operand of every read**, before any chunk fetch, to key its
+   * chunk cache, so it heals a swept generation exactly as {@link currentGeneration} does: unhealed, a cold read
+   * racing a publish and a `keep: 0` sweep failed the whole operation with `NotFoundError`, where the same race
+   * on a chunk fetch heals. Spelled out rather than delegated for the reason `currentGeneration` gives: it is
+   * almost always served from the cached snapshot with no backend call at all. One retry, then propagate.
    */
   async currentVersion(ref) {
-    const reader = await this.resolvedReader(ref);
-    if (reader === null) return null;
-    return reader.lineage === void 0 ? String(reader.generation) : `${reader.generation}:${String(reader.lineage)}`;
+    const pending = this.resolvedReader(ref);
+    let reader;
+    try {
+      reader = await pending;
+    } catch (err) {
+      if (!isNotFoundError(err)) throw err;
+      this.dropStale(segmentKey(ref), pending);
+      reader = await this.resolvedReader(ref);
+    }
+    return reader === null ? null : versionOf(reader.generation, reader.lineage);
   }
   /**
    * Resolve the segment **once** and report what a pin should hold: the generation, and the version that
    * identifies those exact bytes. `null` when the segment resolves to no generation — there is nothing to pin,
    * and a caller must treat that as "this handle reads empty", not "pinning is unsupported here".
+   *
+   * Heals a generation swept between the registry read and the open, as {@link currentVersion} does: a publish
+   * and a `keep: 0` sweep can land in that gap, and nothing has been handed out yet, so the generation current
+   * once the swept one is gone is exactly what a pin taken now should hold. One retry, then propagate.
    */
   async pinGeneration(ref) {
+    try {
+      return await this.pinOnce(ref);
+    } catch (err) {
+      if (!isNotFoundError(err)) throw err;
+      return this.pinOnce(ref);
+    }
+  }
+  async pinOnce(ref) {
     const target = await this.resolveTarget(ref);
     if (target === null) return null;
-    const version = target.lineage === void 0 ? String(target.generation) : `${target.generation}:${String(target.lineage)}`;
-    return { generation: target.generation, version };
+    const version = versionOf(target.generation, target.lineage);
+    let reader;
+    let opened = true;
+    if (target.lineage === void 0) {
+      reader = await this.openForTarget(ref, target);
+      this.install(this.pinnedKey(ref, version, reader.fingerprint), Promise.resolve(reader));
+    } else {
+      const epoch = this.invalidations;
+      const key = this.pinnedKey(ref, version);
+      let entry = this.snapshots.get(key);
+      opened = entry === void 0;
+      entry ??= this.install(key, this.openForTarget(ref, target));
+      reader = await entry.reader;
+      if (reader === null) return null;
+      const replaced = (r) => this.replacedPins.get(this.heldKey(ref, version, r.fingerprint)) !== void 0;
+      const known = !opened && replaced(reader);
+      if (!known && this.invalidations === epoch && this.snapshots.peek(key) === void 0) {
+        this.install(key, Promise.resolve(reader));
+      }
+      if (known) {
+        const current = this.snapshots.peek(key);
+        let fresh = current !== void 0 && current !== entry ? current : this.install(key, this.openForTarget(ref, target));
+        reader = await fresh.reader;
+        if (reader === null) return null;
+        if (fresh === current && replaced(reader)) {
+          fresh = this.install(key, this.openForTarget(ref, target));
+          reader = await fresh.reader;
+          if (reader === null) return null;
+        }
+        opened = fresh !== current;
+      }
+    }
+    if (opened) {
+      const held = this.heldKey(ref, version, reader.fingerprint);
+      this.replacedPins.delete(held);
+      this.checking.delete(held);
+    }
+    return { generation: target.generation, version, fingerprint: reader.fingerprint };
+  }
+  /**
+   * Where a pinned reader of one object is memoised. With a registry that is its version, which names the object:
+   * a name purged and loaded again gets a new row, and with it a new token. Without one the version is the bare
+   * generation number, which two incarnations share, so the object's fingerprint is added to tell them apart.
+   */
+  pinnedKey(ref, version, fingerprint) {
+    return this.registry === void 0 && fingerprint !== void 0 ? this.heldKey(ref, version, fingerprint) : `${segmentKey(ref)}@${version}`;
+  }
+  /**
+   * One pin's hold on one segment: its version, and the fingerprint of the object it pinned. A check of that object
+   * is shared under it, and what the check finds is kept under it, with a registry or without one: pins of one
+   * version can hold different objects, since a pin built by hand can name any, and an object replaced from outside
+   * the store leaves the row, and so the version, as it was.
+   */
+  heldKey(ref, version, fingerprint) {
+    return `${segmentKey(ref)}@${version}#${fingerprint}`;
   }
   /**
    * A reader for one **specific** generation, memoized in the same bounded LRU as the live snapshots under a
@@ -2431,60 +2944,161 @@ var CrbmStorageChunkSource = class {
    *
    * Sharing the LRU is the point, not an implementation detail. A pinned reader held in a private field is
    * outside the memory ceiling the library advertises — measured at 10.34 MiB per live pin, 32 pins holding
-   * 111.7 MiB against an 8 MiB configured bound. A pinned *generation number* has no such problem: the
-   * generation is immutable, so eviction is harmless and re-opening at the same number reproduces the same
-   * bytes. It also removes a memoized-rejection bug by construction — `install` forgets a promise that rejects,
+   * 111.7 MiB against an 8 MiB configured bound. A pinned *generation number* has no such problem: an object is
+   * immutable, so eviction is harmless, and re-opening at the same number reopens the same bytes unless the name
+   * was purged and loaded again, which the pin's fingerprint then says. It also removes a memoized-rejection bug by
+   * construction — `install` forgets a promise that rejects,
    * where a hand-rolled `this.reader ??= open()` cached the rejection for the life of the handle and made a pin
    * the one read path with no resilience.
    *
    * **`status` is re-checked here**, on every open rather than once at pin time. A pin taken before a
    * crypto-shred must not keep unwrapping a DEK the shred destroyed; a destroyed segment resolves no generation
-   * for anyone, pinned or not.
+   * for anyone, and a pin's read of one fails. That holds from the pin's next open: a reader already open keeps
+   * the key it unwrapped until it is evicted or invalidated.
+   *
+   * **And the object is checked**, when the caller says which one it pinned. A generation number is not an
+   * identity (invariant 1): once a name is purged and loaded again, its new segment starts again at generation 0,
+   * so a pin of the old one would open the new one's object as its own, and read it beside the chunks it had
+   * already cached from the old one. The row's token cannot tell them apart, since it moves on every write, a
+   * publish included; the object's fingerprint can, and a pin whose object has been replaced fails, as one whose
+   * generation has been swept does. The memo is keyed so that two pins of one generation number in two
+   * incarnations never share a reader, with a registry or without one ({@link pinnedKey}).
    */
-  async readerAt(ref, generation) {
-    const key = `${segmentKey(ref)}@${generation}`;
-    const existing = this.snapshots.get(key);
-    if (existing !== void 0) return existing.reader;
-    return this.install(key, this.openAt(ref, generation)).reader;
+  async readerAt(ref, generation, version, fingerprint) {
+    const at = version ?? String(generation);
+    const key = this.pinnedKey(ref, at, fingerprint);
+    const epoch = this.invalidations;
+    let entry = this.snapshots.get(key);
+    const opening = entry === void 0;
+    if (entry === void 0) {
+      if (fingerprint !== void 0 && this.replacedPins.get(this.heldKey(ref, at, fingerprint)) !== void 0)
+        throw notThePinned(ref, generation);
+      entry = this.install(key, this.openAt(ref, generation));
+    }
+    let reader;
+    try {
+      reader = await entry.reader;
+    } catch (err) {
+      if (fingerprint === void 0 || isTransientError(err) || isNotFoundError(err)) throw err;
+      await this.throwIfReplaced(ref, generation, at, fingerprint);
+      throw err;
+    }
+    if (reader === null) {
+      if (version === void 0) return null;
+      throw new NotFoundError(
+        `segment "${ref.segment}" generation ${generation}, which this handle pinned, can no longer be read: its registry row is gone or destroyed`
+      );
+    }
+    if (fingerprint !== void 0 && reader.fingerprint !== fingerprint) {
+      if (this.invalidations === epoch)
+        this.replacedPins.set(this.heldKey(ref, at, fingerprint), true);
+      if (opening && this.snapshots.peek(key) === entry) this.snapshots.delete(key);
+      throw notThePinned(ref, generation);
+    }
+    return reader;
   }
   async openAt(ref, generation) {
-    let lineage;
-    if (this.registry !== void 0) {
-      const record = await this.registry.get(ref);
-      if (record === null || record.status === "destroyed") return null;
-      lineage = record.token;
-    }
-    return this.openForTarget(ref, { generation, lineage, wrappedDeks: await this.deksFor(ref) });
+    if (this.registry === void 0) return this.openForTarget(ref, { generation });
+    const record = await this.registry.get(ref);
+    if (record === null || record.status === "destroyed") return null;
+    return this.openForTarget(ref, {
+      generation,
+      lineage: record.token,
+      wrappedDeks: record.wrappedDeks
+    });
   }
-  /** The row's current key wrappings, for opening a pinned generation. */
-  async deksFor(ref) {
-    if (this.registry === void 0) return void 0;
-    return (await this.registry.get(ref))?.wrappedDeks;
+  /**
+   * Read one chunk of a specific generation — the pinned read path. `held`, when given, is what a pin holds of the
+   * object, and the read fails if the generation is now another object.
+   */
+  async getChunkAt(ref, generation, held) {
+    validateUserRef(ref);
+    const reader = await this.readerAt(ref, generation, held?.version, held?.fingerprint);
+    if (reader === null) return null;
+    const fingerprint = held?.fingerprint;
+    if (held !== void 0 && fingerprint !== void 0 && this.replacedPins.get(this.heldKey(ref, held.version, fingerprint)) !== void 0)
+      throw notThePinned(ref, generation);
+    try {
+      return await reader.getChunk(ref.chunkKey);
+    } catch (err) {
+      if (held === void 0 || fingerprint === void 0) throw err;
+      if (!(isIntegrityError(err) || isValidationError(err))) throw err;
+      await this.throwIfReplaced(ref, generation, held.version, fingerprint);
+      throw err;
+    }
   }
-  /** Read one chunk of a specific generation — the pinned read path. */
-  async getChunkAt(ref, generation) {
-    validateSegmentRef(ref);
-    const reader = await this.readerAt(ref, generation);
-    return reader === null ? null : reader.getChunk(ref.chunkKey);
+  /**
+   * Throws the pin's NotFoundError if the object under `generation`'s key is no longer the one the pin holds. Its
+   * footer says, read with no key and no row ({@link CrbmReader.sameObject}), so an object written under a key this
+   * store lacks answers the same way, and so does one gone from its key. A replacement is kept
+   * ({@link replacedPins}), and a check under way is shared by the reads that ask at once; neither "gone" nor "the
+   * same" is kept, since either can change. A transient fault is rethrown, for the store's retries to see for what it
+   * is. A footer that cannot be read otherwise says nothing about which object is there, so this returns, and the
+   * caller's own error stands.
+   */
+  async throwIfReplaced(ref, generation, version, fingerprint) {
+    const held = this.heldKey(ref, version, fingerprint);
+    if (this.replacedPins.get(held) !== void 0) throw notThePinned(ref, generation);
+    let check = this.checking.get(held);
+    if (check === void 0) {
+      const at = { namespace: ref.namespace, segment: ref.segment, generation };
+      const ended = () => this.checking.get(held) === started && this.checking.delete(held);
+      const started = CrbmReader.sameObject(
+        storageBlobReader(this.driver, at),
+        fingerprint
+      ).then(
+        (same) => {
+          if (ended() && !same) this.replacedPins.set(held, true);
+          return !same;
+        },
+        (err) => {
+          ended();
+          if (isNotFoundError(err)) return true;
+          throw err;
+        }
+      );
+      this.checking.set(held, started);
+      check = started;
+    }
+    let replaced;
+    try {
+      replaced = await check;
+    } catch (err) {
+      if (isTransientError(err)) throw err;
+      return;
+    }
+    if (replaced) throw notThePinned(ref, generation);
   }
-  /** Chunk keys of a specific generation — the pinned shape read. */
-  async listChunkKeysAt(ref, generation) {
-    validateSegmentRef(ref);
-    const reader = await this.readerAt(ref, generation);
+  /** Chunk keys of a specific generation — the pinned shape read. `held` as for {@link getChunkAt}. */
+  async listChunkKeysAt(ref, generation, held) {
+    validateUserRef(ref);
+    const reader = await this.readerAt(ref, generation, held?.version, held?.fingerprint);
     return reader === null ? [] : reader.chunkKeys();
   }
-  /** Per-chunk cardinalities of a specific generation — powers a pinned `count()` with no payload reads. */
-  async cardinalitiesAt(ref, generation) {
-    validateSegmentRef(ref);
-    const reader = await this.readerAt(ref, generation);
+  /**
+   * Per-chunk cardinalities of a specific generation — powers a pinned `count()` with no payload reads. `held` as
+   * for {@link getChunkAt}.
+   */
+  async cardinalitiesAt(ref, generation, held) {
+    validateUserRef(ref);
+    const reader = await this.readerAt(ref, generation, held?.version, held?.fingerprint);
     return reader === null ? null : reader.cardinalities();
   }
-  /** Grounded size of a specific generation. */
-  async sizeOfAt(ref, generation) {
-    validateSegmentRef(ref);
-    const reader = await this.readerAt(ref, generation);
+  /** Grounded size of a specific generation. `held` as for {@link getChunkAt}. */
+  async sizeOfAt(ref, generation, held) {
+    validateUserRef(ref);
+    const reader = await this.readerAt(ref, generation, held?.version, held?.fingerprint);
     return reader === null ? null : { sizeBytes: reader.sizeBytes };
   }
+  /**
+   * Whether the segment is a registered name at all. With a registry that is exactly "a row exists" — including
+   * a row with no generation yet (minted by `setRetention` before the first load) and a `destroyed` tombstone,
+   * both of which are names somebody deliberately created. Without a registry there is no registration to
+   * consult, so the honest answer is whether the bucket holds any generation of it.
+   *
+   * Deliberately NOT served from the snapshot memo: the memo resolves to `null` for both states this exists to
+   * tell apart.
+   */
   async exists(ref) {
     if (this.registry !== void 0) return await this.registry.get(ref) !== null;
     for await (const key of this.driver.list(ref)) {
@@ -2515,7 +3129,7 @@ var CrbmStorageChunkSource = class {
       generation: target.generation
     };
     const crypto = await this.cryptoForRead(ref, target.generation, target.wrappedDeks);
-    return CrbmReader.open(storageBlobReader(this.driver, genKey), {
+    return openChecked(this.driver, genKey, {
       ...this.readerOptions,
       crypto,
       lineage: target.lineage
@@ -2567,11 +3181,11 @@ var CrbmStorageChunkSource = class {
     return this.withFreshSnapshot(ref, (reader) => reader.getChunk(ref.chunkKey), null);
   }
   async listChunkKeys(ref) {
-    validateSegmentRef(ref);
+    validateUserRef(ref);
     return this.withFreshSnapshot(ref, (reader) => reader.chunkKeys(), []);
   }
   async sizeOf(ref) {
-    validateSegmentRef(ref);
+    validateUserRef(ref);
     return this.withFreshSnapshot(
       ref,
       (reader) => ({ sizeBytes: reader.sizeBytes }),
@@ -2579,7 +3193,7 @@ var CrbmStorageChunkSource = class {
     );
   }
   async cardinalities(ref) {
-    validateSegmentRef(ref);
+    validateUserRef(ref);
     return this.withFreshSnapshot(
       ref,
       (reader) => reader.cardinalities(),
@@ -2715,7 +3329,7 @@ async function publishGeneration(registry, key, options = {}) {
 }
 async function bulkLoadCrbmGeneration(driver, key, ids, options = {}) {
   if (options.keystore === void 0 && options.requireEncryption === true) {
-    throw new ValidationError("requireEncryption: bulk-load needs a keystore to write encrypted");
+    throw new ValidationError("requireEncryption: a load needs a keystore to write encrypted");
   }
   const codec = requireCodec(options.codec, "bulkLoadCrbmGeneration");
   const byChunk = /* @__PURE__ */ new Map();
@@ -2768,7 +3382,7 @@ async function bulkLoadCrbmGeneration(driver, key, ids, options = {}) {
     if (pause !== null) await pause;
   }
   if (options.keystore !== void 0 && options.registry === void 0) {
-    throw new ValidationError("bulk-load encryption requires a registry to store the wrapped DEK");
+    throw new ValidationError("an encrypted load requires a registry to store the wrapped DEK");
   }
   const existing = options.registry !== void 0 ? await options.registry.get(key) : null;
   if (existing?.status === "destroyed") {
@@ -2778,7 +3392,7 @@ async function bulkLoadCrbmGeneration(driver, key, ids, options = {}) {
   }
   if (existing?.wrappedDeks !== void 0 && existing.wrappedDeks.length > 0 && options.keystore === void 0) {
     throw new KeyUnavailableError(
-      `segment "${key.segment}" is encrypted but this bulk-load has no keystore \u2014 refusing to write a cleartext generation onto an encrypted segment. Pass the keystore holding its DEK.`
+      `segment "${key.segment}" is encrypted but this load has no keystore \u2014 refusing to write a cleartext generation onto an encrypted segment. Pass the keystore holding its DEK.`
     );
   }
   let crypto;
@@ -2827,7 +3441,16 @@ async function bulkLoadCrbmGeneration(driver, key, ids, options = {}) {
   return { size, sha256, chunkCount: chunks.length, cardinality, wrappedDeks: newWrapped };
 }
 function openGenerationReader(storage, key, crypto, options = {}) {
-  return CrbmReader.open(storageBlobReader(storage, key), { ...options, crypto });
+  return openChecked(storage, key, { ...options, crypto });
+}
+async function openChecked(storage, key, options) {
+  const reader = await CrbmReader.open(storageBlobReader(storage, key), options);
+  if (reader.generation !== key.generation) {
+    throw new IntegrityError(
+      `segment "${key.segment}" generation ${key.generation}: its footer says generation ${reader.generation}`
+    );
+  }
+  return reader;
 }
 async function verifyGeneration(storage, key, expected, crypto) {
   const expectedKeys = [...expected.chunkKeys].sort((a, b) => a - b);
@@ -2847,6 +3470,10 @@ async function verifyGeneration(storage, key, expected, crypto) {
 }
 
 // src/core/pinned-storage-source.ts
+var heldBy = (pin) => {
+  if (pin.version === null) return void 0;
+  return pin.fingerprint == null ? { version: pin.version } : { version: pin.version, fingerprint: pin.fingerprint };
+};
 var PinnedStorageChunkSource = class {
   constructor(inner, pins) {
     this.inner = inner;
@@ -2854,6 +3481,10 @@ var PinnedStorageChunkSource = class {
   }
   inner;
   pins;
+  /** The unpinned segments refresh as the store's own source does; a pinned one never does. */
+  get pointerRefreshMs() {
+    return this.inner.pointerRefreshMs;
+  }
   /**
    * The pin for this segment, or `undefined` if it is not pinned here.
    *
@@ -2867,36 +3498,50 @@ var PinnedStorageChunkSource = class {
   getChunk(ref) {
     const pin = this.pinFor(ref);
     if (pin === void 0) return this.inner.getChunk(ref);
-    return pin.generation === null ? Promise.resolve(null) : this.inner.getChunkAt(ref, pin.generation);
+    return pin.generation === null ? Promise.resolve(null) : this.inner.getChunkAt(ref, pin.generation, heldBy(pin));
   }
   listChunkKeys(ref) {
     const pin = this.pinFor(ref);
     if (pin === void 0) return this.inner.listChunkKeys(ref);
-    return pin.generation === null ? Promise.resolve([]) : this.inner.listChunkKeysAt(ref, pin.generation);
+    return pin.generation === null ? Promise.resolve([]) : this.inner.listChunkKeysAt(ref, pin.generation, heldBy(pin));
   }
   sizeOf(ref) {
     const pin = this.pinFor(ref);
     if (pin === void 0) return this.inner.sizeOf(ref);
-    return pin.generation === null ? Promise.resolve(null) : this.inner.sizeOfAt(ref, pin.generation);
+    return pin.generation === null ? Promise.resolve(null) : this.inner.sizeOfAt(ref, pin.generation, heldBy(pin));
   }
   cardinalities(ref) {
     const pin = this.pinFor(ref);
     if (pin === void 0) return this.inner.cardinalities(ref);
-    return pin.generation === null ? Promise.resolve(null) : this.inner.cardinalitiesAt(ref, pin.generation);
+    return pin.generation === null ? Promise.resolve(null) : this.inner.cardinalitiesAt(ref, pin.generation, heldBy(pin));
   }
   currentGeneration(ref) {
     const pin = this.pinFor(ref);
     return pin === void 0 ? this.inner.currentGeneration(ref) : Promise.resolve(pin.generation);
   }
   /**
-   * A pinned segment reports the version captured when it was pinned, so its decoded chunks are cached under a
-   * key that cannot collide with the live generation's. That is what lets a pinned handle share the store's
-   * chunk cache safely; sharing it on a generation-only key was how a pinned read could resurrect an id that
-   * `eraseIdFromSegment` had reported physically gone.
+   * A pinned segment reports the version captured when it was pinned, marked as a pin's, so its decoded chunks
+   * are cached under keys that no live read writes. A live read keys its fetches by the version it resolved when
+   * it began, but is served whatever generation the live source holds when each fetch lands — after a publish
+   * and a lapsed `cache.genTtlMs`, a reader-cache eviction, a sweep that heals the read forward, or an
+   * invalidation, a different one — so an entry under a live version can hold another generation's chunk.
+   * Invariant 3 lets that live call see it, and later live reads resolve the current version and never look the
+   * entry up; a pin sharing the key would be handed it, and return a read that mixed two generations. A pinned
+   * read fetches exactly its own generation, so the entries it fills are always that generation's.
+   *
+   * The pin still shares the store's chunk cache, and its memory ceiling; what it gives up is a hit on a chunk a
+   * live read of the same version cached, which costs a pin one GET per such chunk. Live reads make no call for it,
+   * though a pin's entries share the cache's bound with theirs, so under a small `cache.maxChunks` each can evict
+   * the other. The version, not the bare generation, is still what the key carries: sharing on a generation-only
+   * key was how a pinned read could resurrect an id that `eraseIdFromSegment` had reported physically gone.
    */
   currentVersion(ref) {
     const pin = this.pinFor(ref);
-    return pin === void 0 ? this.inner.currentVersion(ref) : Promise.resolve(pin.version);
+    if (pin === void 0) return this.inner.currentVersion(ref);
+    if (pin.version === null) return Promise.resolve(null);
+    return Promise.resolve(
+      `pin ${pin.version}${pin.fingerprint == null ? "" : `#${pin.fingerprint}`}`
+    );
   }
   exists(ref) {
     return this.inner.exists(ref);
@@ -2916,7 +3561,10 @@ async function nextGeneration(ref, deps) {
   return highest + 1;
 }
 async function gcOrphanGenerations(ref, deps, options = {}) {
-  const keep = Math.max(0, options.keep ?? 1);
+  const keep = options.keep ?? 1;
+  if (!Number.isInteger(keep) || keep < 0) {
+    throw new ValidationError(`keep must be a non-negative integer; got ${String(keep)}`);
+  }
   const record = await deps.registry.get(ref);
   if (record === null) return [];
   const current = record.currentGen;
@@ -2987,7 +3635,8 @@ async function currentCardinality(ref, deps, record) {
   return total;
 }
 async function loadSegment(ref, ids, deps, options = {}) {
-  validateSegmentRef(ref);
+  validateUserRef(ref);
+  requireCodec(deps.codec, "loadSegment");
   const keep = options.keep ?? 1;
   if (!Number.isInteger(keep) || keep < 0) {
     throw new ValidationError(`keep must be a non-negative integer; got ${String(keep)}`);
@@ -3027,6 +3676,14 @@ async function loadSegment(ref, ids, deps, options = {}) {
     });
   } catch (err) {
     if (!isWriteConflictError(err)) throw err;
+    audit.onEvent({
+      kind: "segment.load-refused",
+      segment: ref.segment,
+      namespace: ref.namespace,
+      generation,
+      reason: "superseded",
+      cardinality: 0
+    });
     return {
       generation,
       published: false,
@@ -3106,7 +3763,7 @@ async function loadSegment(ref, ids, deps, options = {}) {
 
 // src/core/rollback.ts
 async function listGenerations(ref, deps) {
-  validateSegmentRef(ref);
+  validateUserRef(ref);
   const record = await deps.registry.get(ref);
   const current = record?.currentGen ?? null;
   const seen = /* @__PURE__ */ new Set();
@@ -3114,7 +3771,7 @@ async function listGenerations(ref, deps) {
   return [...seen].sort((a, b) => a - b).map((generation) => ({ generation, current: generation === current }));
 }
 async function rollbackSegment(ref, toGeneration, deps, options = {}) {
-  validateSegmentRef(ref);
+  validateUserRef(ref);
   if (!Number.isInteger(toGeneration) || toGeneration < 0) {
     throw new ValidationError(
       `rollback: generation must be a non-negative integer; got ${String(toGeneration)}`
@@ -3163,7 +3820,7 @@ async function rollbackSegment(ref, toGeneration, deps, options = {}) {
     } catch {
     }
     throw new NotFoundError(
-      `rollback: generation ${toGeneration} of "${ref.segment}" was collected while the pointer was moving` + (undone ? " \u2014 the pointer was put back" : `, and the pointer could NOT be put back: it still names ${toGeneration}. Re-run a rollback to a generation that exists, or restore the object.`)
+      `rollback: generation ${toGeneration} of "${ref.segment}" was collected while the pointer was moving` + (undone ? " \u2014 the pointer was put back" : `, and the move back failed, so the pointer may still name ${toGeneration} (a write that landed and lost its response reads as a failure here). Check which generation is current, then re-run a rollback to a generation that exists, or restore the object.`)
     );
   }
   safeAudit(options.audit ?? NOOP_AUDIT).onEvent({
@@ -3178,17 +3835,8 @@ async function rollbackSegment(ref, toGeneration, deps, options = {}) {
 
 // src/core/erase-id.ts
 var DEFAULT_MAX_BITMAP_BYTES2 = 1 << 20;
-async function assertCollected(ref, holder, collected, storage) {
-  if (collected.includes(holder)) return;
-  for await (const key of storage.list(ref)) {
-    if (key.generation !== holder) continue;
-    throw new WriteConflictError(
-      `erasure of segment ${ref.segment} could not remove generation ${holder} \u2014 the one holding the id \u2014 which is still in the bucket; re-run`
-    );
-  }
-}
 async function eraseIdFromSegment(ref, id, deps, options = {}) {
-  validateSegmentRef(ref);
+  validateUserRef(ref);
   const { chunkKey, remainder } = splitId(id);
   const codec = requireCodec(deps.codec, "eraseIdFromSegment");
   const maxBytes = deps.maxBitmapBytes ?? DEFAULT_MAX_BITMAP_BYTES2;
@@ -3228,50 +3876,89 @@ async function eraseIdFromSegment(ref, id, deps, options = {}) {
     if (row.currentGen === null) return "no-generation";
     return row.currentGen === from && row.token === fromToken ? null : "superseded";
   };
-  const notInCurrent = async () => {
-    const superseded = [];
-    for await (const key2 of deps.storage.list(ref)) {
-      if (key2.generation !== from) superseded.push(key2.generation);
+  const holds = async (generation2) => {
+    try {
+      const reader = await openGenerationReader(
+        deps.storage,
+        { ...base, generation: generation2 },
+        cryptoAt(generation2)
+      );
+      const bytes = await reader.getChunk(chunkKey);
+      return bytes !== null && codec.safeDeserialize(bytes, maxBytes).has(remainder);
+    } catch (err) {
+      if (isNotFoundError(err)) return null;
+      throw err;
     }
-    if (superseded.length === 0) {
-      return { ...base, erased: false, reason: "not-member", fromGeneration: from, collected: [] };
+  };
+  const holderLeft = async (clean) => {
+    const present = /* @__PURE__ */ new Set();
+    for await (const key2 of deps.storage.list(ref)) present.add(key2.generation);
+    for (const generation2 of [...present].sort((a, b) => b - a)) {
+      if (!clean.has(generation2) && await holds(generation2) === true) return generation2;
     }
-    superseded.sort((a, b) => b - a);
-    for (const generation2 of superseded) {
-      let held = false;
-      try {
-        const reader = await openGenerationReader(
-          deps.storage,
-          { ...base, generation: generation2 },
-          cryptoAt(generation2)
-        );
-        const bytes = await reader.getChunk(chunkKey);
-        if (bytes !== null) held = codec.safeDeserialize(bytes, maxBytes).has(remainder);
-      } catch (err) {
-        if (!isNotFoundError(err)) throw err;
-        continue;
-      }
-      if (!held) continue;
-      const collected2 = await gcOrphanGenerations(ref, deps, { keep: 0 });
-      const alsoCollected = [...collected2];
-      if (from !== null && generation2 > from) {
-        await deps.storage.delete({ namespace: ref.namespace, segment: ref.segment, generation: generation2 });
-        alsoCollected.push(generation2);
+    return void 0;
+  };
+  const cannotRemove = (generation2) => new WriteConflictError(
+    `erasure of segment ${ref.segment} could not remove generation ${generation2}, which still holds the id and is still in the bucket; re-run`
+  );
+  const notInCurrent = async () => {
+    const notMember = {
+      ...base,
+      erased: false,
+      reason: "not-member",
+      fromGeneration: from,
+      collected: []
+    };
+    const others = /* @__PURE__ */ new Set();
+    for await (const key2 of deps.storage.list(ref)) {
+      if (key2.generation !== from) others.add(key2.generation);
+    }
+    if (others.size === 0) return notMember;
+    const newestFirst = [...others].sort((a, b) => b - a);
+    const clean = /* @__PURE__ */ new Set([from]);
+    const holdersAbove = [];
+    for (const generation2 of newestFirst.filter((g) => g > from)) {
+      const held = await holds(generation2);
+      if (held === true) holdersAbove.push(generation2);
+      else if (held === false) clean.add(generation2);
+    }
+    let holderBelow;
+    if (holdersAbove.length === 0) {
+      for (const generation2 of newestFirst.filter((g) => g < from)) {
+        const held = await holds(generation2);
+        if (held === true) {
+          holderBelow = generation2;
+          break;
+        }
+        if (held === false) clean.add(generation2);
       }
-      await assertCollected(ref, generation2, alsoCollected, deps.storage);
-      return { ...base, erased: true, fromGeneration: generation2, collected: alsoCollected };
     }
-    return { ...base, erased: false, reason: "not-member", fromGeneration: from, collected: [] };
+    const newest = holdersAbove[0] ?? holderBelow;
+    if (newest === void 0) return notMember;
+    const collected2 = [...await gcOrphanGenerations(ref, deps, { keep: 0 })];
+    let moved = null;
+    for (const generation2 of holdersAbove) {
+      moved = rowVerdict(await deps.registry.get(ref));
+      if (moved !== null) break;
+      await deps.storage.delete({ ...base, generation: generation2 });
+      collected2.push(generation2);
+    }
+    const left2 = await holderLeft(clean);
+    if (left2 === void 0) return { ...base, erased: true, fromGeneration: newest, collected: collected2 };
+    if (moved !== null) {
+      return { ...base, erased: false, reason: moved, fromGeneration: newest, collected: collected2 };
+    }
+    throw cannotRemove(left2);
   };
   const stage = async () => {
     let written;
     try {
       const reader = await openGenerationReader(deps.storage, fromKey, cryptoAt(from));
       const bytes = await reader.getChunk(chunkKey);
-      if (bytes === null) return notInCurrent();
+      if (bytes === null) return await notInCurrent();
       const target = codec.safeDeserialize(bytes, maxBytes);
       assertRemaindersInRange(target, chunkKey);
-      if (!target.has(remainder)) return notInCurrent();
+      if (!target.has(remainder)) return await notInCurrent();
       target.remove(remainder);
       const generation2 = await nextGeneration(ref, deps);
       const key2 = { ...base, generation: generation2 };
@@ -3300,14 +3987,24 @@ async function eraseIdFromSegment(ref, id, deps, options = {}) {
       throw err;
     }
   };
+  const discardRefused = async (written) => {
+    const row = await deps.registry.get(ref);
+    if (row === null || row.status !== "active" || row.currentGen === null) return;
+    if (row.currentGen <= from || row.currentGen >= written) return;
+    await deps.storage.delete({ ...base, generation: written });
+  };
   const staged = await stage();
-  if ("erased" in staged) return staged;
+  if ("erased" in staged) {
+    if (!staged.erased && staged.generation !== void 0) await discardRefused(staged.generation);
+    return staged;
+  }
   const { generation, key } = staged;
   const published = await publishGeneration(deps.registry, key, {
     expectFrom: from,
     expectToken: fromToken
   });
   if (!published) {
+    await discardRefused(generation);
     return {
       ...base,
       erased: false,
@@ -3325,7 +4022,8 @@ async function eraseIdFromSegment(ref, id, deps, options = {}) {
     generation
   });
   const collected = await gcOrphanGenerations(ref, deps, { keep: 0 });
-  await assertCollected(ref, from, collected, deps.storage);
+  const left = await holderLeft(/* @__PURE__ */ new Set([generation]));
+  if (left !== void 0) throw cannotRemove(left);
   return { ...base, erased: true, fromGeneration: from, generation, collected };
 }
 async function* rewrite(reader, chunkKey, replacement, codec, maxBytes) {
@@ -3456,6 +4154,7 @@ var MAX_CAS_ATTEMPTS = 8;
 var ERASE_CONCURRENCY = 8;
 var MAX_STORAGE_SWEEPS = 3;
 async function destroySegment(ref, deps, options) {
+  validateUserRef(ref);
   if (options.confirmSegment !== ref.segment) {
     throw new ValidationError(
       `destroySegment: confirmSegment must equal the segment name "${ref.segment}" (guard against accidental crypto-shred)`
@@ -3475,15 +4174,23 @@ async function eraseNamespace(namespace, deps, options) {
   if (typeof namespace !== "string" || namespace.length === 0) {
     throw new ValidationError("eraseNamespace: namespace must be a non-empty string");
   }
+  validateUserNamespace(namespace);
   if (options.confirmNamespace !== namespace) {
     throw new ValidationError(
       `eraseNamespace: confirmNamespace must equal the namespace "${namespace}" (guard against accidental erasure)`
     );
   }
-  const refs = [];
-  for await (const rec of deps.registry.list(namespace)) {
-    refs.push({ namespace: rec.namespace, segment: rec.segment });
-  }
+  const rows = await drainRegistry(deps.registry, {
+    namespace,
+    maxScanSegments: options.maxScanSegments ?? DEFAULT_MAX_SCAN_SEGMENTS,
+    op: "eraseNamespace",
+    narrowable: false
+    // already one namespace: the only remedy is a higher ceiling
+  });
+  const refs = rows.map((rec) => ({
+    namespace: rec.namespace,
+    segment: rec.segment
+  }));
   const audit = safeAudit(options.audit ?? NOOP_AUDIT);
   const destroyed = [];
   let segmentsShredded = 0;
@@ -3510,6 +4217,7 @@ async function eraseNamespace(namespace, deps, options) {
   return { destroyed };
 }
 async function dropSegment(ref, deps, options) {
+  validateUserRef(ref);
   if (options.confirmSegment !== ref.segment) {
     throw new ValidationError(
       `dropSegment: confirmSegment must equal the segment name "${ref.segment}" (guard against accidental deletion)`
@@ -3663,6 +4371,7 @@ function readRetentionPolicy(meta) {
   return { expiresAt: raw };
 }
 async function getSegmentRetention(ref, deps) {
+  validateUserRef(ref);
   const record = await deps.registry.get(ref);
   if (record === null || record.status === "destroyed") return null;
   return readRetentionPolicy(record.retention);
@@ -3693,6 +4402,7 @@ async function reindex(ref, deps, expiresAt, previousExpiresAt) {
   return indexed;
 }
 async function setSegmentRetention(ref, deps, policy) {
+  validateUserRef(ref);
   validateRetentionPolicy(policy);
   const base = { segment: ref.segment, namespace: ref.namespace };
   let previousExpiresAt;
@@ -3731,6 +4441,7 @@ async function setSegmentRetention(ref, deps, policy) {
   );
 }
 async function clearSegmentRetention(ref, deps) {
+  validateUserRef(ref);
   for (let attempt = 0; attempt < RETENTION_CAS_ATTEMPTS; attempt += 1) {
     const record = await deps.registry.get(ref);
     if (record === null) return false;
@@ -3771,6 +4482,7 @@ async function rowsFromDueIndex(registry, options) {
     for await (const pointer of registry.list(dueNamespace(bucket))) {
       const ref = decodeDueName(pointer.segment);
       if (ref === null) continue;
+      if (isReservedNamespace(ref.namespace)) continue;
       if (options.namespace !== void 0 && ref.namespace !== options.namespace) continue;
       const key = `${ref.namespace ?? ""}\0${ref.segment}`;
       if (seen.has(key)) continue;
@@ -3795,6 +4507,7 @@ async function forgetDuePointer(registry, ref, expiresAt) {
   }
 }
 async function retireExpired(deps, options) {
+  if (options.namespace !== void 0) validateUserNamespace(options.namespace);
   const now = options.now;
   if (!Number.isFinite(now)) {
     throw new ValidationError(
@@ -3867,7 +4580,7 @@ async function retireExpired(deps, options) {
             continue;
           }
         }
-        if (!dryRun) await deps.registry.delete(ref);
+        if (!dryRun) await deps.registry.delete(ref, rec.token);
         if (!dryRun) tombstonesPurged += 1;
         entries.push({
           ...base,
@@ -3918,9 +4631,15 @@ async function retireExpired(deps, options) {
       retired += 1;
       entries.push({ ...base, action: "retired", expiresAt: livePolicy.expiresAt, result });
       await forgetDuePointer(deps.registry, ref, livePolicy.expiresAt);
-      if (result.generationsDeleted.length === 0 && result.generationsRemaining.length === 0) {
-        await deps.registry.delete(ref).catch(() => void 0);
-        continue;
+      if (purgeTombstones && result.generationsDeleted.length === 0 && result.generationsRemaining.length === 0) {
+        const tombstone = await deps.registry.get(ref).catch(() => null);
+        if (tombstone?.status === "destroyed") {
+          const deleted = await deps.registry.delete(ref, tombstone.token).then(
+            () => true,
+            () => false
+          );
+          if (deleted) continue;
+        }
       }
       await stampRetirement(deps.registry, ref, now).catch(() => void 0);
     } catch (err) {
@@ -4000,6 +4719,7 @@ async function generationsPresent(storage, ref) {
   return present;
 }
 async function runConsistencyCheck(deps, options = {}) {
+  if (options.namespace !== void 0) validateUserNamespace(options.namespace);
   const concurrency = options.concurrency ?? DEFAULT_CHECK_CONCURRENCY;
   if (!Number.isInteger(concurrency) || concurrency < 1) {
     throw new ValidationError(`concurrency must be a positive integer; got ${concurrency}`);
@@ -4008,7 +4728,10 @@ async function runConsistencyCheck(deps, options = {}) {
   const recs = await drainRegistry(deps.registry, {
     namespace: options.namespace,
     maxScanSegments,
-    op: "checkConsistency"
+    op: "checkConsistency",
+    // Two callers reach this refusal, and only one of them can raise the ceiling: `store.checkConsistency` takes
+    // no `maxScanSegments`, so the advice names the call that does.
+    raise: "raise `maxScanSegments` on `runConsistencyCheck` (`store.checkConsistency` takes no ceiling, so run `runConsistencyCheck({ storage: backend.storage, registry: backend.registry }, { maxScanSegments })` over the same backend instead)"
   });
   const results = await mapWithConcurrency(recs, concurrency, async (rec) => {
     if (rec.status === "destroyed") return { kind: "ok" };
@@ -4080,14 +4803,17 @@ async function withRetry(op, policy, deps) {
       lastErr = err;
       if (attempt >= attempts || !retryable(err)) throw err;
       const delayMs = applyJitter(policy, backoffDelayMs(policy, attempt), deps.rng);
-      deps.onRetry?.({ attempt, delayMs, err });
+      try {
+        deps.onRetry?.({ attempt, delayMs, err });
+      } catch {
+      }
       await deps.clock.sleep(delayMs);
     }
   }
   throw lastErr;
 }
 
-// src/drivers/retry/retrying-drivers.ts
+// src/drivers/retry/retrying-chunk-source.ts
 function toRetry(opts) {
   return {
     policy: opts.policy ?? DEFAULT_RETRY_POLICY,
@@ -4110,6 +4836,13 @@ var RetryingStorageChunkSource = class {
   invalidate;
   exists;
   currentVersion;
+  /**
+   * Forwarded, not retried: a property, with no request behind it. Without it the grounded cost report priced a
+   * retrying store's refresh at the default TTL whatever the store was configured with.
+   */
+  get pointerRefreshMs() {
+    return this.inner.pointerRefreshMs;
+  }
   constructor(inner, opts) {
     this.inner = inner;
     const r = toRetry(opts);
@@ -4149,82 +4882,6 @@ var RetryingStorageChunkSource = class {
     return withRetry(() => this.inner.listChunkKeys(ref), this.policy, this.deps);
   }
 };
-var RetryingStorageDriver = class {
-  inner;
-  policy;
-  deps;
-  constructor(inner, opts) {
-    this.inner = inner;
-    const r = toRetry(opts);
-    this.policy = r.policy;
-    this.deps = r.deps;
-  }
-  capabilities() {
-    return this.inner.capabilities();
-  }
-  putImmutable(key, write) {
-    return withRetry(() => this.inner.putImmutable(key, write), this.policy, this.deps);
-  }
-  getRange(key, offset, length) {
-    return withRetry(() => this.inner.getRange(key, offset, length), this.policy, this.deps);
-  }
-  getTail(key, maxBytes) {
-    return withRetry(() => this.inner.getTail(key, maxBytes), this.policy, this.deps);
-  }
-  delete(key) {
-    return withRetry(() => this.inner.delete(key), this.policy, this.deps);
-  }
-  async *list(ref) {
-    const keys = await withRetry(
-      async () => {
-        const out = [];
-        for await (const k of this.inner.list(ref)) out.push(k);
-        return out;
-      },
-      this.policy,
-      this.deps
-    );
-    yield* keys;
-  }
-};
-var RetryingRegistryDriver = class {
-  inner;
-  policy;
-  deps;
-  constructor(inner, opts) {
-    this.inner = inner;
-    const r = toRetry(opts);
-    this.policy = r.policy;
-    this.deps = r.deps;
-  }
-  capabilities() {
-    return this.inner.capabilities();
-  }
-  get(ref) {
-    return withRetry(() => this.inner.get(ref), this.policy, this.deps);
-  }
-  create(ref, record) {
-    return withRetry(() => this.inner.create(ref, record), this.policy, this.deps);
-  }
-  compareAndSwap(ref, expected, patch) {
-    return withRetry(() => this.inner.compareAndSwap(ref, expected, patch), this.policy, this.deps);
-  }
-  async *list(namespace) {
-    const records = await withRetry(
-      async () => {
-        const out = [];
-        for await (const r of this.inner.list(namespace)) out.push(r);
-        return out;
-      },
-      this.policy,
-      this.deps
-    );
-    yield* records;
-  }
-  delete(ref) {
-    return withRetry(() => this.inner.delete(ref), this.policy, this.deps);
-  }
-};
 export {
   AWS_US_EAST_1_ONDEMAND,
   BoundedLru,
@@ -4236,47 +4893,36 @@ export {
   CrbmReader,
   CrbmStorageChunkSource,
   DEFAULT_BUDGET,
-  DEFAULT_PRICING,
   DEFAULT_RETRY_POLICY,
+  ELASTICACHE_REDIS_US_EAST_1_ONDEMAND,
   InProcessKeystore,
   IntegrityError,
   KeyUnavailableError,
-  LocalFsRegistryDriver,
   LocalFsStorage,
-  LocalFsStorageDriver,
   MIN_EXPIRES_AT_MS,
-  MemoryRegistryDriver,
   MemoryStorage,
-  MemoryStorageChunkSource,
-  MemoryStorageDriver,
   NOOP_METRICS,
   NodeAead,
   NotFoundError,
+  ONE_REDIS_HA_CLUSTER,
   PinnedStorageChunkSource,
   RecordingAuditSink,
-  RetryingRegistryDriver,
   RetryingStorageChunkSource,
-  RetryingStorageDriver,
   SegmentEngine,
-  TimeoutError,
   TransientError,
   UnsupportedError,
   ValidationError,
   WriteConflictError,
   aadFor,
-  bulkLoadCrbmGeneration,
   checkBudget,
   clearSegmentRetention,
   collectWithinBudget,
-  createBackend,
   destroySegment,
   dropSegment,
-  encodeNameForPath,
   eraseIdFromSegment,
   eraseNamespace,
   estimateCost,
   excludingReservedRows,
-  gcOrphanGenerations,
   getSegmentRetention,
   groundedReport,
   isCloudRoaringError,
@@ -4290,9 +4936,6 @@ export {
   listSegments,
   loadSegment,
   mapWithConcurrency,
-  namespacePathPart,
-  nextGeneration,
-  publishGeneration,
   readRetentionPolicy,
   resolveBudget,
   resolvePerOpBudget,
@@ -4305,8 +4948,6 @@ export {
   segmentKey,
   setSegmentRetention,
   splitId,
-  validateSegmentRef,
-  withRetry,
-  writeCrbmGeneration
+  withRetry
 };
 //# sourceMappingURL=index.js.map