@cloudbitmaps/core 0.11.1 → 0.12.0

package/dist/index.js

@@ -5,6 +5,7 @@ import {
   DEFAULT_NAMESPACE,
   IntegrityError,
   KeyUnavailableError,
+  MAX_METADATA_BYTES,
   MAX_NAME_LENGTH,
   NotFoundError,
   RESERVED_NAMESPACE_PREFIX,
@@ -13,11 +14,18 @@ import {
   ValidationError,
   WriteConflictError,
   applyRegistryPatch,
+  assertRegistryCanWrite,
   brandAsBackend,
+  canonicalMetadataJson,
+  copiedMetadata,
   decodeNameFromPath,
+  drawIncarnation,
+  drawWrite,
   encodeNameForKey,
   encodeNameForPath,
   encodedNameLength,
+  entropyIsAvailable,
+  incarnationOf,
   isCloudRoaringError,
   isIntegrityError,
   isNotFoundError,
@@ -27,18 +35,23 @@ import {
   isValidationError,
   isWriteConflictError,
   mapWithConcurrency,
+  metadataBytes,
+  metadataFromBytes,
   namespacePathPart,
+  newIncarnationToken,
+  nextRegistryToken,
   parseRegistryEnvelope,
   recordFromNew,
-  registryCounterOf,
+  sameIncarnation,
   serializeRegistryEnvelope,
   validateChunkRef,
   validateNewRegistryRecord,
   validateRegistryPatch,
   validateSegmentRef,
   validateUserNamespace,
-  validateUserRef
-} from "./chunk-5OMC5U7U.js";
+  validateUserRef,
+  webCryptoEntropy
+} from "./chunk-5W3XS2IU.js";
 
 // src/core/bit-route.ts
 var U32_MAX = 4294967295;
@@ -255,6 +268,37 @@ function keysWithin(keys, w) {
   };
   return keys.slice(firstAtLeast(w.loKey), firstAtLeast(w.hiKey + 1));
 }
+var ChunkWindow = class {
+  constructor(keys, fetch, max, ramp) {
+    this.keys = keys;
+    this.fetch = fetch;
+    this.max = max;
+    this.ramp = ramp;
+  }
+  keys;
+  fetch;
+  max;
+  ramp;
+  open = [];
+  launched = 0;
+  taken = 0;
+  /** The next chunk in key order (null if the source holds none), or the error its read raised. */
+  async take() {
+    const width = this.ramp ? Math.min(this.max, 2 ** Math.min(this.taken, 30)) : this.max;
+    while (this.launched < this.keys.length && this.launched - this.taken < width) {
+      this.open.push(
+        this.fetch(this.keys[this.launched++]).then(
+          (chunk) => ({ chunk }),
+          (cause) => ({ chunk: null, error: { cause } })
+        )
+      );
+    }
+    const slot = await this.open.shift();
+    this.taken += 1;
+    if (slot.error) throw slot.error.cause;
+    return slot.chunk;
+  }
+};
 var SegmentEngine = class {
   storage;
   cache;
@@ -282,15 +326,19 @@ var SegmentEngine = class {
     return chunk ? chunk.has(remainder) : false;
   }
   /**
-   * 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.
+   * Cardinality. When the Storage source can describe the current generation (the `.crbm` source can), the count is
+   * that description's: the registry row's summary when the row has one it can use, which is one request when cold
+   * and no read of the object, and otherwise the sum of the object's index. Either way, **zero payload reads**. A
+   * source that can only serve per-chunk cardinality sums those, and one with neither (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 row's summary and the index sum are trusted, not confirmed: the source holds the summary against the object
+   * whenever it opens it, and 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) {
+    if (this.storage.summary) return (await this.storage.summary(seg))?.cardinality ?? 0;
     const cardinalities = this.storage.cardinalities ? await this.storage.cardinalities(seg) : null;
     if (cardinalities) {
       let total2 = 0;
@@ -303,12 +351,22 @@ var SegmentEngine = class {
     const chunkKeys = await this.chunkKeys(seg);
     checkBudget(this.budget, chunkKeys.length, "count");
     const gen = await this.cacheVersion(seg);
+    const window = this.chunkWindow(seg, chunkKeys, gen, false);
     let total = 0;
-    for (const chunkKey of chunkKeys) {
-      total += (await this.storageChunk({ ...seg, chunkKey }, gen))?.size ?? 0;
-    }
+    for (let i = 0; i < chunkKeys.length; i++) total += (await window.take())?.size ?? 0;
     return total;
   }
+  /**
+   * What the segment's current generation is: its number, its id count and its metadata, from one resolution, so the
+   * three cannot straddle a publish. A source with no summary answers from `count()` and the generation it resolves.
+   */
+  async stat(seg) {
+    if (this.storage.summary) {
+      return await this.storage.summary(seg) ?? { generation: null, cardinality: 0 };
+    }
+    const generation = this.storage.currentGeneration ? await this.storage.currentGeneration(seg) : null;
+    return { generation, cardinality: await this.count(seg) };
+  }
   /** Whether the Storage source can measure segment size (for grounded cost); false ⇒ storage isn't grounded. */
   get supportsStorageSize() {
     return typeof this.storage.sizeOf === "function";
@@ -321,8 +379,18 @@ var SegmentEngine = class {
   segmentSize(seg) {
     return this.storage.sizeOf ? this.storage.sizeOf(seg) : Promise.resolve(null);
   }
+  /** The chunks of `seg` at `chunkKeys`, read through a window of {@link DEFAULT_INTERSECT_CONCURRENCY}. */
+  chunkWindow(seg, chunkKeys, gen, ramp) {
+    return new ChunkWindow(
+      chunkKeys,
+      (chunkKey) => this.storageChunk({ ...seg, chunkKey }, gen),
+      DEFAULT_INTERSECT_CONCURRENCY,
+      ramp
+    );
+  }
   /**
-   * Every id, ascending, one chunk at a time; with `range`, only the ids in `(after, through]`, fetching only the
+   * Every id, ascending, reading ahead through a window of up to 8 chunk fetches that opens 1, 2, 4, 8 wide, so a
+   * read that stops early has fetched only a handful of chunks past the one it stopped in; 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
@@ -336,8 +404,9 @@ var SegmentEngine = class {
     const chunkKeys = await this.chunkKeys(seg);
     checkBudget(this.budget, chunkKeys.length, "iterate");
     const gen = await this.cacheVersion(seg);
+    const window = this.chunkWindow(seg, chunkKeys, gen, true);
     for (const chunkKey of chunkKeys) {
-      const chunk = await this.storageChunk({ ...seg, chunkKey }, gen);
+      const chunk = await window.take();
       if (chunk === null) continue;
       for (const remainder of chunk) yield joinId(chunkKey, remainder);
     }
@@ -348,8 +417,9 @@ var SegmentEngine = class {
     const chunkKeys = keysWithin(await this.chunkKeys(seg), w);
     checkBudget(this.budget, chunkKeys.length, "iterate");
     const gen = await this.cacheVersion(seg);
+    const window = this.chunkWindow(seg, chunkKeys, gen, true);
     for (const chunkKey of chunkKeys) {
-      const chunk = await this.storageChunk({ ...seg, chunkKey }, gen);
+      const chunk = await window.take();
       if (chunk === null) continue;
       if (isEdge(chunkKey, w)) {
         for (const id of edgeIds(chunk, chunkKey, w)) yield id;
@@ -382,7 +452,7 @@ var SegmentEngine = class {
    * 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 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
+   * operand's not-yet-requested 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
@@ -829,6 +899,111 @@ var BoundedLru = class {
   }
 };
 
+// src/core/generation-gc.ts
+async function nextGeneration(ref, deps) {
+  return aboveEverything(ref, deps, await deps.registry.get(ref));
+}
+async function aboveEverything(ref, deps, record) {
+  let highest = record?.currentGen ?? -1;
+  for await (const key of deps.storage.list(ref)) {
+    if (key.generation > highest) highest = key.generation;
+  }
+  return highest + 1;
+}
+async function nextLoadGeneration(ref, deps, row) {
+  const generation = (row?.currentGen ?? -1) + 1;
+  try {
+    await deps.storage.getTail({ namespace: ref.namespace, segment: ref.segment, generation }, 0);
+  } catch (err) {
+    if (isNotFoundError(err)) return { generation, checked: true };
+  }
+  return { generation: await aboveEverything(ref, deps, row), checked: false };
+}
+var LIST_COLLECTION_CADENCE = 16;
+async function gcOrphanGenerations(ref, deps, options = {}) {
+  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;
+  const seen = /* @__PURE__ */ new Set();
+  for await (const key of deps.storage.list(ref)) seen.add(key.generation);
+  const gens = [...seen];
+  const after = await deps.registry.get(ref);
+  if (after === null)
+    throw new WriteConflictError(`registry row for segment ${ref.segment} was purged mid-pass`);
+  if (record.status === "destroyed" && after.token !== record.token) {
+    throw new WriteConflictError(
+      `segment ${ref.segment} changed incarnation while its generations were being listed`
+    );
+  }
+  const cutoff = current === null || after.currentGen === null ? null : Math.min(current, after.currentGen);
+  const stillCollectable = async () => {
+    const still = await deps.registry.get(ref);
+    if (still === null) {
+      throw new WriteConflictError(`registry row for segment ${ref.segment} was purged mid-pass`);
+    }
+    const ok = record.status === "destroyed" ? still.token === after.token : cutoff === null || still.currentGen !== null && still.currentGen >= cutoff;
+    if (!ok) {
+      throw new WriteConflictError(
+        `segment ${ref.segment} changed incarnation while its generations were being collected`
+      );
+    }
+  };
+  const toDelete = record.status === "destroyed" ? gens.sort((a, b) => a - b) : cutoff === null ? (
+    // No Storage pointer yet, so "below current" selects nothing and there is nothing safe to infer: an object
+    // here is either a load about to publish or an orphan we cannot tell apart from it. Deleting would race
+    // that publish into a dangling pointer. It is collected once a pointer exists.
+    []
+  ) : (
+    // Delete generations below the cutoff, except the newest `keep` of them (the grace window).
+    gens.filter((g) => g < cutoff).sort((a, b) => b - a).slice(keep)
+  );
+  for (const generation of toDelete) {
+    await stillCollectable();
+    await deps.storage.delete({ namespace: ref.namespace, segment: ref.segment, generation });
+  }
+  return toDelete;
+}
+async function collectAfterLoad(ref, deps, options) {
+  const { generation, keep, byName, proveCurrent } = options;
+  if (keep >= generation) return [];
+  const periodic = generation % LIST_COLLECTION_CADENCE === 0;
+  if (byName && keep <= 1 && !periodic) {
+    if (keep === 1 && proveCurrent !== void 0 && !await objectIsThere(deps.storage, proveCurrent)) {
+      return gcOrphanGenerations(ref, deps, { keep });
+    }
+    return collectByName(ref, deps, { generation, keep });
+  }
+  return gcOrphanGenerations(ref, deps, { keep });
+}
+async function objectIsThere(storage, key) {
+  try {
+    await storage.getTail(key, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function collectByName(ref, deps, options) {
+  const { generation, keep } = options;
+  if (!Number.isInteger(keep) || keep < 0 || keep > 1) {
+    throw new ValidationError(`collecting by name needs a keep of 0 or 1; got ${String(keep)}`);
+  }
+  const evicted = generation - keep - 1;
+  if (evicted < 0) return [];
+  const still = await deps.registry.get(ref);
+  if (still === null || still.currentGen === null || still.currentGen < generation) return [];
+  await deps.storage.delete({
+    namespace: ref.namespace,
+    segment: ref.segment,
+    generation: evicted
+  });
+  return [evicted];
+}
+
 // src/core/reader-defaults.ts
 var DEFAULT_CURRENT_GEN_TTL_MS = 2e3;
 var REFRESH_RETRY_MS = 500;
@@ -876,9 +1051,20 @@ var AWS_US_EAST_1_ONDEMAND = deepFreeze({
 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;
+var STORE_LOAD_PUT_CLASS = 1 + 1 / LIST_COLLECTION_CADENCE;
+var STORE_LOAD_POINTER_READS = 3 + 2 / LIST_COLLECTION_CADENCE;
+var STORE_LOAD_EXISTENCE_CHECKS = 2 - 1 / LIST_COLLECTION_CADENCE;
+var RETENTION_SWEEP_REQUESTS = deepFreeze({
+  conditionalDelete: {
+    retirement: { reads: 9, writes: 3, deletes: 1 },
+    purge: { reads: 4, writes: 0, deletes: 2 }
+  },
+  tombstoning: {
+    retirement: { reads: 8, writes: 3, deletes: 0 },
+    purge: { reads: 3, writes: 1, deletes: 0 }
+  }
+});
+var shown = (n) => String(Number(n.toFixed(2)));
 function requireFiniteNonNeg(n, field) {
   if (n === void 0 || !Number.isFinite(n) || n < 0) {
     throw new ValidationError(`${field} must be a finite number >= 0; got ${n}`);
@@ -1015,8 +1201,8 @@ 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) {
+  const shown2 = (v, u) => u === 0 ? Math.round(v) : Number(v.toFixed(2));
+  while (unit < units.length - 1 && shown2(value, unit) >= 1024) {
     value /= 1024;
     unit += 1;
   }
@@ -1043,6 +1229,10 @@ function buildReport(input) {
   requireFiniteNonNeg(storage.getPerMillion, "pricing.storage.getPerMillion");
   requireFiniteNonNeg(storage.putPerMillion, "pricing.storage.putPerMillion");
   requireFiniteNonNeg(storage.storagePerGiBMonth, "pricing.storage.storagePerGiBMonth");
+  const pointerRead = requireFiniteNonNeg(
+    storage.requestsPerPointerRead ?? 1,
+    "pricing.storage.requestsPerPointerRead"
+  );
   const sizedRead = requireFiniteNonNeg(
     storage.requestsPerSizedRead ?? 1,
     "pricing.storage.requestsPerSizedRead"
@@ -1089,6 +1279,15 @@ function buildReport(input) {
     input.workload.genTtlMs ?? DEFAULT_CURRENT_GEN_TTL_MS,
     "genTtlMs"
   );
+  const retirementsPerMonth = requireFiniteNonNeg(
+    input.workload.retirementsPerMonth ?? 0,
+    "retirementsPerMonth"
+  );
+  const purgesPerMonth = requireFiniteNonNeg(input.workload.purgesPerMonth ?? 0, "purgesPerMonth");
+  const conditionalDelete = input.workload.conditionalDelete ?? true;
+  if (typeof conditionalDelete !== "boolean") {
+    throw new ValidationError(`conditionalDelete must be a boolean; got ${conditionalDelete}`);
+  }
   const storageGetUSD = storage.getPerMillion / 1e6;
   const putUSD = storage.putPerMillion / 1e6;
   const missFraction = 1 - cacheHitRate;
@@ -1097,16 +1296,26 @@ function buildReport(input) {
   const refreshes = genTtlMs > 0 ? Math.min(readerProcesses * hotSegments * S * 1e3 / genTtlMs, readsPerSec * S) : 0;
   const storageUSD = storedGiB * storage.storagePerGiBMonth;
   const readsUSD = readMisses * storageGetUSD;
-  const intersectGets = chunksPerIntersect + SIZED_READS_PER_COLD_OPERAND * operandsPerIntersect * sizedRead;
+  const getsPerColdOperand = pointerRead + sizedRead;
+  const intersectGets = chunksPerIntersect + getsPerColdOperand * operandsPerIntersect;
   const intersectsUSD = intersects * intersectGets * storageGetUSD;
-  const loadGets = STORE_LOAD_SIZED_READS * sizedRead;
+  const loadGets = STORE_LOAD_POINTER_READS * pointerRead + STORE_LOAD_EXISTENCE_CHECKS;
   const loadsUSD = loadsPerMonth * ((requestsPerLoad + STORE_LOAD_PUT_CLASS) * putUSD + loadGets * storageGetUSD);
-  const refreshUSD = refreshes * sizedRead * storageGetUSD;
-  const total = readsUSD + intersectsUSD + storageUSD + loadsUSD + refreshUSD;
+  const refreshUSD = refreshes * pointerRead * storageGetUSD;
+  const sweep = RETENTION_SWEEP_REQUESTS[conditionalDelete ? "conditionalDelete" : "tombstoning"];
+  const retentionUSD = retirementsPerMonth * (sweep.retirement.reads * storageGetUSD + sweep.retirement.writes * putUSD) + purgesPerMonth * (sweep.purge.reads * storageGetUSD + sweep.purge.writes * putUSD);
+  const total = readsUSD + intersectsUSD + storageUSD + loadsUSD + refreshUSD + retentionUSD;
   const headroom = Math.max(0, baselineUSD - storageUSD - refreshUSD);
   const readsCross = storageGetUSD > 0 && missFraction > 0 ? headroom / (S * storageGetUSD * missFraction) : Infinity;
   const verdict = total <= baselineUSD * 0.1 ? "win-big" : total < baselineUSD ? "win" : "lose-zone";
-  const dominant = Math.max(readsUSD, intersectsUSD, storageUSD, loadsUSD, refreshUSD);
+  const dominant = Math.max(
+    readsUSD,
+    intersectsUSD,
+    storageUSD,
+    loadsUSD,
+    refreshUSD,
+    retentionUSD
+  );
   let driver = "storage";
   if (dominant === readsUSD && readsUSD > 0) driver = "point reads (object GETs)";
   else if (dominant === intersectsUSD && intersectsUSD > 0) {
@@ -1114,6 +1323,8 @@ function buildReport(input) {
   } 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)";
+  else if (dominant === retentionUSD && retentionUSD > 0)
+    driver = "the retention sweep (registry reads and writes)";
   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)})`;
@@ -1123,12 +1334,15 @@ function buildReport(input) {
   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, 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.",
+    loadsPerMonth > 0 ? `Loads modeled: ${loadsPerMonth}/mo, each ${requestsPerLoad} PUT-class request(s) for the object plus ${shown(STORE_LOAD_PUT_CLASS)} PUT-class and ${shown(loadGets)} GETs that store.load() adds (the pointer, a check that the next generation number is free, a check that the current generation is there, and a listing every ${LIST_COLLECTION_CADENCE}th load).` : "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.`
+      `Intersections priced cold: ${intersectGets} GETs each, ${getsPerColdOperand} 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,
+    ...retirementsPerMonth > 0 || purgesPerMonth > 0 ? [
+      `Retention sweep modeled: ${retirementsPerMonth}/mo retirements at ${sweep.retirement.reads} reads, ${sweep.retirement.writes} writes and ${sweep.retirement.deletes} delete(s) each, ${purgesPerMonth}/mo purges at ${sweep.purge.reads} reads, ${sweep.purge.writes} writes and ${sweep.purge.deletes} delete(s) each; reads are priced at the GET rate and writes at the PUT rate, deletes at nothing, as S3 bills none` + (conditionalDelete ? "." : "; a registry that only tombstones is read again, two reads per purged segment, by every later full sweep, which is not priced.")
+    ] : [],
     ...input.extraNotes ?? [],
     // Last, so the notes a report already carried keep their places.
     redisNote
@@ -1140,7 +1354,8 @@ function buildReport(input) {
         intersects: intersectsUSD,
         storage: storageUSD,
         loads: loadsUSD,
-        pointerRefresh: refreshUSD
+        pointerRefresh: refreshUSD,
+        retention: retentionUSD
       },
       total
     },
@@ -1249,7 +1464,10 @@ async function drainRegistry(registry, options) {
   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 (options.namespace === void 0 && isReservedRow(rec)) {
+      options.onReserved?.(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. ${advice}available (a record is a few hundred bytes resident).`
@@ -1421,16 +1639,19 @@ var BufferReader = class {
 var MemoryRegistryDriver = class {
   rows = /* @__PURE__ */ new Map();
   now;
+  entropy;
   seq = 0;
   constructor(options = {}) {
     this.now = options.now ?? (() => Date.now());
+    this.entropy = options.entropy ?? webCryptoEntropy;
   }
-  nextToken() {
+  nextToken(incarnation) {
     this.seq += 1;
-    return String(this.seq);
+    return `${incarnation}.${this.seq}.${drawWrite(this.entropy)}`;
   }
+  /** `conditionalDelete`: a delete checks the token and removes the row in one step, with no await between. */
   capabilities() {
-    return { strongRead: true };
+    return entropyIsAvailable(this.entropy) ? { strongRead: true, conditionalDelete: true } : { strongRead: true, canWrite: false, conditionalDelete: true };
   }
   async get(ref) {
     validateSegmentRef(ref);
@@ -1439,25 +1660,25 @@ var MemoryRegistryDriver = class {
   }
   async create(ref, record) {
     validateSegmentRef(ref);
-    validateNewRegistryRecord(record);
+    const checked = validateNewRegistryRecord(record);
     const key = segmentKey(ref);
     if (this.rows.has(key)) {
       throw new WriteConflictError(`registry row already exists for segment ${ref.segment}`);
     }
-    const token = this.nextToken();
-    this.rows.set(key, structuredClone(recordFromNew(ref, record, this.now(), token)));
+    const token = this.nextToken(drawIncarnation(this.entropy));
+    this.rows.set(key, structuredClone(recordFromNew(ref, checked, this.now(), token)));
     return { token };
   }
   async compareAndSwap(ref, expected, patch) {
     validateSegmentRef(ref);
-    validateRegistryPatch(patch);
+    const checked = validateRegistryPatch(patch);
     const key = segmentKey(ref);
     const existing = this.rows.get(key);
     if (!existing || existing.token !== expected) {
       throw new WriteConflictError(`OCC token mismatch for registry row ${ref.segment}`);
     }
-    const token = this.nextToken();
-    this.rows.set(key, structuredClone(applyRegistryPatch(existing, patch, this.now(), token)));
+    const token = this.nextToken(incarnationOf(existing.token) ?? drawIncarnation(this.entropy));
+    this.rows.set(key, structuredClone(applyRegistryPatch(existing, checked, this.now(), token)));
     return { token };
   }
   async *list(namespace) {
@@ -1774,43 +1995,48 @@ var LocalFsRegistryDriver = class {
   constructor(root, options = {}) {
     this.root = root;
     this.now = options.now ?? (() => Date.now());
+    this.entropy = options.entropy ?? webCryptoEntropy;
   }
   root;
   now;
+  entropy;
+  /**
+   * `conditionalDelete`: a delete reads the row, checks it, and unlinks it under the row's lock, which every writer on
+   * the root in this process takes, so no write can land between the check and the unlink.
+   */
   capabilities() {
-    return { strongRead: true };
+    return entropyIsAvailable(this.entropy) ? { strongRead: true, conditionalDelete: true } : { strongRead: true, canWrite: false, conditionalDelete: true };
   }
   async get(ref) {
     const env = await this.readRow(registryRowPath(this.root, ref));
     return env && !env.deleted ? env.record : null;
   }
   async create(ref, record) {
-    validateNewRegistryRecord(record);
+    const checked = validateNewRegistryRecord(record);
     const path = registryRowPath(this.root, ref);
     return this.withRowLock(path, async () => {
       const current = await this.readRow(path);
       if (current !== null && !current.deleted) {
         throw new WriteConflictError(`registry row already exists for segment ${ref.segment}`);
       }
-      const counter = current ? registryCounterOf(current.record) + 1 : 0;
-      const token = String(counter);
-      await this.writeRow(path, false, recordFromNew(ref, record, this.now(), token));
+      const token = newIncarnationToken(this.entropy, current?.record);
+      await this.writeRow(path, false, recordFromNew(ref, checked, this.now(), token));
       return { token };
     });
   }
   async compareAndSwap(ref, expected, patch) {
-    validateRegistryPatch(patch);
+    const checked = validateRegistryPatch(patch);
     const path = registryRowPath(this.root, ref);
     return this.withRowLock(path, async () => {
       const current = await this.readRow(path);
       if (current === null || current.deleted || current.record.token !== expected) {
         throw new WriteConflictError(`OCC token mismatch for registry row ${ref.segment}`);
       }
-      const token = String(registryCounterOf(current.record) + 1);
+      const token = nextRegistryToken(current.record, this.entropy);
       await this.writeRow(
         path,
         false,
-        applyRegistryPatch(current.record, patch, this.now(), token)
+        applyRegistryPatch(current.record, checked, this.now(), token)
       );
       return { token };
     });
@@ -1844,10 +2070,23 @@ var LocalFsRegistryDriver = class {
       } else if (current === null || current.deleted) {
         return;
       }
-      const token = String(registryCounterOf(current.record) + 1);
+      if (incarnationOf(current.record.token) !== void 0) {
+        await this.unlinkRow(path);
+        return;
+      }
+      const token = nextRegistryToken(current.record, this.entropy);
       await this.writeRow(path, true, { ...current.record, token, updatedAt: this.now() });
     });
   }
+  /** Remove a row's file and make the removal durable (fsync the directory). */
+  async unlinkRow(path) {
+    try {
+      await unlink2(path);
+    } catch (err) {
+      if (!isCode(err, "ENOENT")) throw mapFsError(err);
+    }
+    await fsyncDir(dirname2(path));
+  }
   /** Namespaces to scan: just the one requested, or every namespace dir under the root. */
   async namespaceDirs(namespace) {
     if (namespace !== void 0) return [namespace];
@@ -2003,6 +2242,8 @@ function yieldEvery(clock, everyN = YIELD_EVERY) {
 var AAD_VERSION = 1;
 var SCOPE_CHUNK = 0;
 var SCOPE_INDEX = 1;
+var SCOPE_METADATA = 2;
+var SCOPE_SUMMARY = 3;
 function aadFor(ref, generation, scope) {
   const enc = new TextEncoder();
   const ns = enc.encode(ref.namespace ?? "");
@@ -2022,12 +2263,82 @@ function aadFor(ref, generation, scope) {
   o += seg.length;
   view.setBigUint64(o, BigInt(generation), true);
   o += 8;
-  out[o] = scope === "index" ? SCOPE_INDEX : SCOPE_CHUNK;
+  out[o] = scope === "index" ? SCOPE_INDEX : scope === "metadata" ? SCOPE_METADATA : scope === "summary" ? SCOPE_SUMMARY : SCOPE_CHUNK;
   o += 1;
-  view.setUint32(o, scope === "index" ? 0 : scope, true);
+  view.setUint32(o, typeof scope === "number" ? scope : 0, true);
   return out;
 }
 
+// src/core/crbm/format.ts
+var MAGIC = Uint8Array.of(67, 82, 66, 77);
+var VERSION_MAJOR = 1;
+var VERSION_MINOR = 0;
+var PREAMBLE_BYTES = 8;
+var PAYLOAD_START = PREAMBLE_BYTES;
+var FOOTER_BYTES = 104;
+var FOOTER = {
+  indexOffset: 0,
+  // u64
+  indexLength: 8,
+  // u64
+  indexCrc32c: 16,
+  // u32
+  flags: 20,
+  // u32
+  payloadCodecId: 24,
+  // u16 — which codec wrote the chunk payloads
+  elementWidth: 26,
+  // u8
+  containerCodec: 27,
+  // u8
+  versionMajor: 28,
+  // u8
+  versionMinor: 29,
+  // u8
+  reserved2: 30,
+  // u16
+  generation: 32,
+  // u64
+  indexNonce: 40,
+  // 12 B
+  indexTag: 52,
+  // 16 B
+  keyId: 68,
+  // 16 B
+  chunkCount: 84,
+  // u32
+  totalCardinality: 88,
+  // u64
+  footerCrc32c: 96,
+  // u32 — covers footer bytes [0, 96)
+  endMagic: 100
+  // char[4]
+};
+var FOOTER_CRC_COVERAGE = FOOTER.footerCrc32c;
+var FLAG_ENCRYPTED = 1 << 0;
+var FLAG_INDEX_COMPRESSED = 1 << 1;
+var FLAG_LITTLE_ENDIAN = 1 << 2;
+var FLAG_EXTENSION = 1 << 3;
+var KNOWN_FLAGS = FLAG_ENCRYPTED | FLAG_LITTLE_ENDIAN | FLAG_EXTENSION;
+var ELEMENT_WIDTH_32 = 32;
+var PAYLOAD_CODEC_ROARING_PORTABLE = 1;
+var KNOWN_PAYLOAD_CODEC_IDS = /* @__PURE__ */ new Set([
+  PAYLOAD_CODEC_ROARING_PORTABLE
+]);
+var CONTAINER_CODEC_NONE = 0;
+var DEFAULT_TAIL_BYTES = 256 * 1024;
+var DEFAULT_MAX_INDEX_BYTES = 8 * 1024 * 1024;
+var DEFAULT_MAX_PAYLOAD_BYTES = 16 * 1024 * 1024;
+var MAX_CHUNK_CARDINALITY = 65536;
+var EXT_MAGIC = Uint8Array.of(67, 82, 66, 88);
+var EXT_TRAILER_BYTES = 12;
+var EXT_SECTION_HEADER_BYTES = 5;
+var MAX_EXT_BYTES = 4 * 1024;
+var EXT_SECTION_METADATA = 1;
+var CRC32C_BYTES = 4;
+var AEAD_NONCE_BYTES = 12;
+var AEAD_TAG_BYTES = 16;
+
 // src/core/crbm/crc32c.ts
 var TABLES = (() => {
   const POLY = 2197175160;
@@ -2097,7 +2408,7 @@ function readVarint(bytes, offset) {
     if (i === 4 && byte > 15) {
       throw new IntegrityError("varint exceeds u32 range");
     }
-    result += (byte & 127) * 2 ** shift;
+    result = (result | (byte & 127) << shift) >>> 0;
     if ((byte & 128) === 0) {
       return { value: result, next: pos };
     }
@@ -2106,72 +2417,13 @@ function readVarint(bytes, offset) {
   throw new IntegrityError("varint exceeds u32 range");
 }
 
-// src/core/crbm/format.ts
-var MAGIC = Uint8Array.of(67, 82, 66, 77);
-var VERSION_MAJOR = 1;
-var VERSION_MINOR = 0;
-var PREAMBLE_BYTES = 8;
-var PAYLOAD_START = PREAMBLE_BYTES;
-var FOOTER_BYTES = 104;
-var FOOTER = {
-  indexOffset: 0,
-  // u64
-  indexLength: 8,
-  // u64
-  indexCrc32c: 16,
-  // u32
-  flags: 20,
-  // u32
-  payloadCodecId: 24,
-  // u16 — which codec wrote the chunk payloads
-  elementWidth: 26,
-  // u8
-  containerCodec: 27,
-  // u8
-  versionMajor: 28,
-  // u8
-  versionMinor: 29,
-  // u8
-  reserved2: 30,
-  // u16
-  generation: 32,
-  // u64
-  indexNonce: 40,
-  // 12 B
-  indexTag: 52,
-  // 16 B
-  keyId: 68,
-  // 16 B
-  chunkCount: 84,
-  // u32
-  totalCardinality: 88,
-  // u64
-  footerCrc32c: 96,
-  // u32 — covers footer bytes [0, 96)
-  endMagic: 100
-  // char[4]
-};
-var FOOTER_CRC_COVERAGE = FOOTER.footerCrc32c;
-var FLAG_ENCRYPTED = 1 << 0;
-var FLAG_INDEX_COMPRESSED = 1 << 1;
-var FLAG_LITTLE_ENDIAN = 1 << 2;
-var KNOWN_FLAGS = FLAG_ENCRYPTED | FLAG_LITTLE_ENDIAN;
-var ELEMENT_WIDTH_32 = 32;
-var PAYLOAD_CODEC_ROARING_PORTABLE = 1;
-var KNOWN_PAYLOAD_CODEC_IDS = /* @__PURE__ */ new Set([
-  PAYLOAD_CODEC_ROARING_PORTABLE
-]);
-var CONTAINER_CODEC_NONE = 0;
-var DEFAULT_TAIL_BYTES = 256 * 1024;
-var DEFAULT_MAX_INDEX_BYTES = 8 * 1024 * 1024;
-var DEFAULT_MAX_PAYLOAD_BYTES = 16 * 1024 * 1024;
-var MAX_CHUNK_CARDINALITY = 65536;
-var CRC32C_BYTES = 4;
-var AEAD_NONCE_BYTES = 12;
-var AEAD_TAG_BYTES = 16;
-
 // src/core/crbm/reader.ts
-var RETAINED_BYTES_PER_INDEX_ENTRY = 160;
+var RETAINED_BYTES_PER_METADATA_BYTE = 2;
+var RETAINED_BYTES_PER_METADATA_KEY = 160;
+var MIN_INDEX_RECORD_BYTES = 4 + CRC32C_BYTES;
+function indexCapacity(indexLength) {
+  return Math.min(65536, Math.floor(indexLength / MIN_INDEX_RECORD_BYTES));
+}
 function magicMatches(bytes, offset) {
   return bytes[offset] === MAGIC[0] && bytes[offset + 1] === MAGIC[1] && bytes[offset + 2] === MAGIC[2] && bytes[offset + 3] === MAGIC[3];
 }
@@ -2198,6 +2450,11 @@ function checkedFooter(tail, size) {
   }
   return { footer, fview, storedFooterCrc };
 }
+async function footerSaysEncrypted(blob) {
+  const { bytes: tail, size } = await blob.getTail(FOOTER_BYTES);
+  const { fview } = checkedFooter(tail, size);
+  return (fview.getUint32(FOOTER.flags, true) & FLAG_ENCRYPTED) !== 0;
+}
 function readU64(view, offset, field) {
   const big = view.getBigUint64(offset, true);
   if (big > BigInt(Number.MAX_SAFE_INTEGER)) {
@@ -2206,28 +2463,30 @@ function readU64(view, offset, field) {
   return Number(big);
 }
 var CrbmReader = class _CrbmReader {
-  constructor(blob, objectSize, generation, lineage, totalCardinality, entries, orderedKeys, servedFromTail, crypto, footerCrc) {
+  constructor(blob, objectSize, generation, lineage, totalCardinality, index, servedFromTail, crypto, footerCrc, metadata, metadataWeight) {
     this.blob = blob;
     this.objectSize = objectSize;
     this.generation = generation;
     this.lineage = lineage;
     this.totalCardinality = totalCardinality;
-    this.entries = entries;
-    this.orderedKeys = orderedKeys;
+    this.index = index;
     this.servedFromTail = servedFromTail;
     this.crypto = crypto;
     this.footerCrc = footerCrc;
+    this.metadata = metadata;
+    this.metadataWeight = metadataWeight;
   }
   blob;
   objectSize;
   generation;
   lineage;
   totalCardinality;
-  entries;
-  orderedKeys;
+  index;
   servedFromTail;
   crypto;
   footerCrc;
+  metadata;
+  metadataWeight;
   /**
    * 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
@@ -2241,17 +2500,28 @@ var CrbmReader = class _CrbmReader {
     return this.objectSize;
   }
   /**
-   * Estimated retained JS heap of this reader's parsed index — the weight the storage reader cache bounds on
-   * (a wide segment's parsed index, not its payloads, dominates the reader's footprint). `entries.size` scales with the number
-   * of resident chunks (≤ 65536), so this is `entries.size × {@link RETAINED_BYTES_PER_INDEX_ENTRY}`.
+   * Retained JS heap of this reader's parsed index — the weight the storage reader cache bounds on (a wide
+   * segment's parsed index, not its payloads, dominates the reader's footprint): the exact byte length of the
+   * arrays that hold it, {@link RETAINED_BYTES_PER_INDEX_ENTRY} per entry.
    */
   get retainedIndexBytes() {
-    return this.entries.size * RETAINED_BYTES_PER_INDEX_ENTRY;
+    const { keys, cardinalityMinusOne, lengths, crcs, offsets } = this.index;
+    return keys.byteLength + cardinalityMinusOne.byteLength + lengths.byteLength + crcs.byteLength + offsets.byteLength;
+  }
+  /**
+   * What this reader holds, the weight the storage reader cache bounds on: its parsed index
+   * ({@link retainedIndexBytes}), plus a weight for the metadata it decoded, from its canonical length and its number
+   * of keys. Equal to {@link retainedIndexBytes} for a generation with no metadata. A cache heuristic, not a contract:
+   * how the metadata is weighed may change in any release.
+   */
+  get retainedBytes() {
+    return this.retainedIndexBytes + this.metadataWeight;
   }
   /** Per-chunk cardinality (`chunkKey → count`) from the parsed index — no payload reads. */
   cardinalities() {
+    const { keys, cardinalityMinusOne } = this.index;
     const out = /* @__PURE__ */ new Map();
-    for (const [chunkKey, entry] of this.entries) out.set(chunkKey, entry.cardinality);
+    for (let i = 0; i < keys.length; i++) out.set(keys[i], cardinalityMinusOne[i] + 1);
     return out;
   }
   /**
@@ -2313,6 +2583,13 @@ var CrbmReader = class _CrbmReader {
     const chunkCount = fview.getUint32(FOOTER.chunkCount, true);
     const totalCardinality = readU64(fview, FOOTER.totalCardinality, "total_cardinality");
     const generation = readU64(fview, FOOTER.generation, "generation");
+    if (!encrypted && options.crypto !== void 0) {
+      throw new IntegrityError(
+        `.crbm generation ${generation} is not encrypted, but it was opened with a key: a cleartext object where an encrypted one belongs is forged, corrupt, or a write that never published (a crash, before the segment's key was made); a load's collection, dropSegment or deleting the object removes it`
+      );
+    }
+    const versionMinor = footer[FOOTER.versionMinor];
+    const hasExtension = (flags & FLAG_EXTENSION) !== 0;
     if (indexOffset < PAYLOAD_START || indexOffset + indexLength > size - FOOTER_BYTES) {
       throw new IntegrityError(
         `.crbm index region [${indexOffset}, +${indexLength}) out of bounds`
@@ -2323,20 +2600,27 @@ var CrbmReader = class _CrbmReader {
     }
     const tailCoversFrom = size - tail.length;
     if (tailCoversFrom === 0) {
-      if (!magicMatches(tail, 0) || tail[4] !== versionMajor) {
+      if (!magicMatches(tail, 0) || tail[4] !== versionMajor || tail[5] !== versionMinor) {
         throw new IntegrityError(".crbm preamble magic/version mismatch with footer");
       }
     }
-    let indexBytes;
+    const lowest = hasExtension ? Math.max(PAYLOAD_START, indexOffset - EXT_TRAILER_BYTES - MAX_EXT_BYTES) : indexOffset;
+    let region;
+    let regionStart;
     let servedFromTail;
     if (indexOffset >= tailCoversFrom) {
-      const start = indexOffset - tailCoversFrom;
-      indexBytes = tail.subarray(start, start + indexLength);
+      region = tail;
+      regionStart = tailCoversFrom;
       servedFromTail = true;
     } else {
-      indexBytes = await blob.getRange(indexOffset, indexLength);
+      region = await blob.getRange(lowest, indexOffset + indexLength - lowest);
+      regionStart = lowest;
       servedFromTail = false;
     }
+    const indexBytes = region.subarray(
+      indexOffset - regionStart,
+      indexOffset - regionStart + indexLength
+    );
     if (crc32c(indexBytes) !== indexCrc) {
       throw new IntegrityError(".crbm index CRC mismatch");
     }
@@ -2348,9 +2632,56 @@ var CrbmReader = class _CrbmReader {
       },
       options.crypto.aadFor("index")
     ) : indexBytes;
-    const { entries, orderedKeys, cardinalitySum } = parseIndex(
+    let payloadEnd = indexOffset;
+    let metadata;
+    let metadataLength = 0;
+    if (hasExtension) {
+      const trailerStart = indexOffset - EXT_TRAILER_BYTES;
+      if (trailerStart < PAYLOAD_START) {
+        throw new IntegrityError(".crbm flags an extension block, but has no room for one");
+      }
+      let window = { bytes: region, start: regionStart };
+      if (trailerStart < regionStart) {
+        window = { bytes: await blob.getRange(lowest, indexOffset - lowest), start: lowest };
+        servedFromTail = false;
+      }
+      const trailer = within(window.bytes, window.start, trailerStart, indexOffset);
+      const tview = new DataView(trailer.buffer, trailer.byteOffset, trailer.byteLength);
+      if (!EXT_MAGIC.every((b, i) => trailer[8 + i] === b)) {
+        throw new IntegrityError(".crbm extension block trailer magic mismatch");
+      }
+      const sectionsLength = tview.getUint32(0, true);
+      if (sectionsLength > MAX_EXT_BYTES) {
+        throw new IntegrityError(
+          `.crbm extension block ${sectionsLength}B exceeds cap ${MAX_EXT_BYTES}B`
+        );
+      }
+      const extStart = trailerStart - sectionsLength;
+      if (extStart < PAYLOAD_START) {
+        throw new IntegrityError(`.crbm extension block of ${sectionsLength}B out of bounds`);
+      }
+      let covered;
+      if (extStart >= window.start) {
+        covered = within(window.bytes, window.start, extStart, trailerStart + 4);
+      } else {
+        covered = await blob.getRange(extStart, sectionsLength + 4);
+        servedFromTail = false;
+        if (covered.length !== sectionsLength + 4) {
+          throw new IntegrityError(".crbm extension block read short");
+        }
+      }
+      if (crc32c(covered) !== tview.getUint32(4, true)) {
+        throw new IntegrityError(".crbm extension block CRC mismatch");
+      }
+      ({ metadata, metadataLength } = extensionContents(
+        covered.subarray(0, sectionsLength),
+        options.crypto
+      ));
+      payloadEnd = extStart;
+    }
+    const index = parseIndex(
       indexForParse,
-      indexOffset,
+      payloadEnd,
       maxPayloadBytes,
       encrypted ? AEAD_NONCE_BYTES + AEAD_TAG_BYTES : 1
     );
@@ -2361,14 +2692,14 @@ var CrbmReader = class _CrbmReader {
         );
       }
     } else {
-      if (entries.size !== chunkCount) {
+      if (index.keys.length !== chunkCount) {
         throw new IntegrityError(
-          `.crbm chunk_count ${chunkCount} != ${entries.size} index entries`
+          `.crbm chunk_count ${chunkCount} != ${index.keys.length} index entries`
         );
       }
-      if (cardinalitySum !== totalCardinality) {
+      if (index.cardinalitySum !== totalCardinality) {
         throw new IntegrityError(
-          `.crbm total_cardinality ${totalCardinality} != \u03A3 index cardinality ${cardinalitySum}`
+          `.crbm total_cardinality ${totalCardinality} != \u03A3 index cardinality ${index.cardinalitySum}`
         );
       }
     }
@@ -2377,24 +2708,39 @@ var CrbmReader = class _CrbmReader {
       size,
       generation,
       options.lineage,
-      cardinalitySum,
-      entries,
-      orderedKeys,
+      index.cardinalitySum,
+      index,
       servedFromTail,
       options.crypto,
-      storedFooterCrc
+      storedFooterCrc,
+      metadata,
+      metadata === void 0 ? 0 : RETAINED_BYTES_PER_METADATA_BYTE * metadataLength + RETAINED_BYTES_PER_METADATA_KEY * Object.keys(metadata).length
     );
   }
   /** Chunk keys present in this generation, ascending. */
   chunkKeys() {
-    return this.orderedKeys.slice();
+    return Array.from(this.index.keys);
   }
   /** Segment cardinality from the footer (no payload reads) — the cheap `count()` path. */
   count() {
     return this.totalCardinality;
   }
-  has(chunkKey) {
-    return this.entries.has(chunkKey);
+  /** The slot holding `chunkKey` (binary search over the ascending keys), or -1 when this generation has none. */
+  slotOf(chunkKey) {
+    const keys = this.index.keys;
+    let lo = 0;
+    let hi = keys.length - 1;
+    while (lo <= hi) {
+      const mid = lo + hi >>> 1;
+      const k = keys[mid];
+      if (k === chunkKey) return mid;
+      if (k < chunkKey) lo = mid + 1;
+      else hi = mid - 1;
+    }
+    return -1;
+  }
+  has(chunkKey) {
+    return this.slotOf(chunkKey) >= 0;
   }
   /**
    * Range-GET one chunk's payload, verifying its CRC32C before returning. Returns `null` if the chunk is
@@ -2403,13 +2749,15 @@ var CrbmReader = class _CrbmReader {
    * not mutate it.
    */
   async getChunk(chunkKey) {
-    const e = this.entries.get(chunkKey);
-    if (e === void 0) return null;
-    if (e.offset < PAYLOAD_START || e.offset + e.length > this.objectSize - FOOTER_BYTES) {
+    const slot = this.slotOf(chunkKey);
+    if (slot < 0) return null;
+    const offset = this.index.offsets[slot];
+    const length = this.index.lengths[slot];
+    if (offset < PAYLOAD_START || offset + length > this.objectSize - FOOTER_BYTES) {
       throw new IntegrityError(`chunk ${chunkKey} payload out of bounds`);
     }
-    const bytes = await this.blob.getRange(e.offset, e.length);
-    if (crc32c(bytes) !== e.crc32c) {
+    const bytes = await this.blob.getRange(offset, length);
+    if (crc32c(bytes) !== this.index.crcs[slot]) {
       throw new IntegrityError(`chunk ${chunkKey} payload CRC mismatch`);
     }
     if (this.crypto === void 0) return bytes;
@@ -2426,52 +2774,130 @@ var CrbmReader = class _CrbmReader {
     );
   }
 };
+function within(bytes, start, from, to) {
+  if (from < start || to > start + bytes.length) {
+    throw new IntegrityError(".crbm extension block read short");
+  }
+  return bytes.subarray(from - start, to - start);
+}
+function extensionCorrupt(message) {
+  throw new IntegrityError(`.crbm extension block: ${message}`);
+}
+function extensionContents(sections, crypto) {
+  const view = new DataView(sections.buffer, sections.byteOffset, sections.byteLength);
+  let metadata;
+  let metadataLength = 0;
+  let lastType = 0;
+  let pos = 0;
+  while (pos < sections.length) {
+    if (sections.length - pos < EXT_SECTION_HEADER_BYTES)
+      extensionCorrupt("a section header is cut off");
+    const type = sections[pos];
+    const length = view.getUint32(pos + 1, true);
+    pos += EXT_SECTION_HEADER_BYTES;
+    if (type <= lastType) {
+      extensionCorrupt(
+        type === 0 ? "section type 0 is not a section type" : `section type ${type} after ${lastType}`
+      );
+    }
+    if (length > sections.length - pos) extensionCorrupt(`section ${type} runs past the block`);
+    const body = sections.subarray(pos, pos + length);
+    pos += length;
+    lastType = type;
+    if (type === EXT_SECTION_METADATA)
+      ({ metadata, metadataLength } = metadataSection(body, crypto));
+  }
+  return { metadata, metadataLength };
+}
+function metadataSection(body, crypto) {
+  if (crypto === void 0) {
+    return { metadata: metadataFromBytes(body, extensionCorrupt), metadataLength: body.length };
+  }
+  const framing = AEAD_NONCE_BYTES + AEAD_TAG_BYTES;
+  if (body.length <= framing || body.length > framing + MAX_METADATA_BYTES) {
+    extensionCorrupt(`sealed metadata of ${body.length}B is not a nonce, up to 1 KiB and a tag`);
+  }
+  let plain;
+  try {
+    plain = crypto.aead.open(
+      {
+        nonce: body.subarray(0, AEAD_NONCE_BYTES),
+        ciphertext: body.subarray(AEAD_NONCE_BYTES, body.length - AEAD_TAG_BYTES),
+        tag: body.subarray(body.length - AEAD_TAG_BYTES)
+      },
+      crypto.aadFor("metadata")
+    );
+  } catch (err) {
+    if (!isIntegrityError(err)) throw err;
+    extensionCorrupt(
+      "the sealed metadata does not open: tampered bytes, a block moved from another object, or a CrbmCrypto whose aadFor does not map the 'metadata' scope"
+    );
+  }
+  return { metadata: metadataFromBytes(plain, extensionCorrupt), metadataLength: plain.length };
+}
 function parseIndex(indexBytes, payloadEnd, maxPayloadBytes, minPayloadBytes = 1) {
-  const entries = /* @__PURE__ */ new Map();
-  const orderedKeys = [];
+  const capacity = indexCapacity(indexBytes.length);
+  const keys = new Uint16Array(capacity);
+  const cardinalityMinusOne = new Uint16Array(capacity);
+  const lengths = new Uint32Array(capacity);
+  const crcs = new Uint32Array(capacity);
+  const offsets = new Float64Array(capacity);
+  let count = 0;
   let pos = 0;
   let prevKey = 0;
   let prevEnd = PAYLOAD_START;
   let cardinalitySum = 0;
   for (let i = 0; pos < indexBytes.length; i++) {
-    const keyDelta = readVarint(indexBytes, pos);
-    const offDelta = readVarint(indexBytes, keyDelta.next);
-    const len = readVarint(indexBytes, offDelta.next);
-    const card = readVarint(indexBytes, len.next);
-    pos = card.next;
+    const keyDeltaRead = readVarint(indexBytes, pos);
+    const offDeltaRead = readVarint(indexBytes, keyDeltaRead.next);
+    const lenRead = readVarint(indexBytes, offDeltaRead.next);
+    const cardRead = readVarint(indexBytes, lenRead.next);
+    const keyDelta = keyDeltaRead.value;
+    const offDelta = offDeltaRead.value;
+    const len = lenRead.value;
+    const card = cardRead.value;
+    pos = cardRead.next;
     if (pos + CRC32C_BYTES > indexBytes.length) {
       throw new IntegrityError(".crbm index truncated (missing payload CRC)");
     }
     const crc = (indexBytes[pos] | indexBytes[pos + 1] << 8 | indexBytes[pos + 2] << 16 | indexBytes[pos + 3] << 24) >>> 0;
     pos += CRC32C_BYTES;
-    const chunkKey = prevKey + keyDelta.value;
-    const offset = prevEnd + offDelta.value;
-    if (i > 0 && keyDelta.value === 0) {
+    const chunkKey = prevKey + keyDelta;
+    const offset = prevEnd + offDelta;
+    if (i > 0 && keyDelta === 0) {
       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 < minPayloadBytes || len.value > maxPayloadBytes) {
-      throw new IntegrityError(`.crbm chunk ${chunkKey} length ${len.value} invalid`);
+    if (len < minPayloadBytes || len > maxPayloadBytes) {
+      throw new IntegrityError(`.crbm chunk ${chunkKey} length ${len} invalid`);
     }
-    if (card.value < 1 || card.value > MAX_CHUNK_CARDINALITY) {
-      throw new IntegrityError(`.crbm chunk ${chunkKey} cardinality ${card.value} invalid`);
+    if (card < 1 || card > MAX_CHUNK_CARDINALITY) {
+      throw new IntegrityError(`.crbm chunk ${chunkKey} cardinality ${card} invalid`);
     }
-    if (offset + len.value > payloadEnd) {
+    if (offset + len > payloadEnd) {
       throw new IntegrityError(`.crbm chunk ${chunkKey} payload out of bounds`);
     }
-    entries.set(chunkKey, {
-      chunkKey,
-      offset,
-      length: len.value,
-      cardinality: card.value,
-      crc32c: crc
-    });
-    orderedKeys.push(chunkKey);
-    cardinalitySum += card.value;
+    keys[count] = chunkKey;
+    cardinalityMinusOne[count] = card - 1;
+    lengths[count] = len;
+    crcs[count] = crc;
+    offsets[count] = offset;
+    count++;
+    cardinalitySum += card;
     prevKey = chunkKey;
-    prevEnd = offset + len.value;
+    prevEnd = offset + len;
+  }
+  if (count === capacity) {
+    return { keys, cardinalityMinusOne, lengths, crcs, offsets, cardinalitySum };
   }
-  return { entries, orderedKeys, cardinalitySum };
+  return {
+    keys: keys.slice(0, count),
+    cardinalityMinusOne: cardinalityMinusOne.slice(0, count),
+    lengths: lengths.slice(0, count),
+    crcs: crcs.slice(0, count),
+    offsets: offsets.slice(0, count),
+    cardinalitySum
+  };
 }
 
 // src/core/crbm/writer.ts
@@ -2484,6 +2910,9 @@ var CrbmWriter = class {
         `generation must be a non-negative integer; got ${options.generation}`
       );
     }
+    this.metadata = metadataBytes(options.metadata, (message) => {
+      throw new ValidationError(message);
+    });
   }
   sink;
   options;
@@ -2493,6 +2922,11 @@ var CrbmWriter = class {
   totalCardinality = 0;
   preambleWritten = false;
   finished = false;
+  /** The metadata's canonical JSON, copied at construction; `undefined` leaves the footer's extension flag clear. */
+  metadata;
+  /** Bytes written so far, the footer included once {@link finish} has run. */
+  written = 0;
+  footerCrc32c;
   /**
    * Append one chunk's payload (the roaring-serialized bytes) with its cardinality. `chunkKey` must be
    * strictly greater than the previous one (ascending, no duplicates); `cardinality` is `[1, 65536]`.
@@ -2514,7 +2948,8 @@ var CrbmWriter = class {
     }
     if (payload.length === 0) throw new ValidationError("chunk payload must be non-empty");
     await this.ensurePreamble();
-    const stored = this.options.crypto ? this.sealChunk(chunkKey, payload) : payload;
+    const crypto = this.options.crypto;
+    const stored = crypto ? framed(crypto.aead.seal(payload, crypto.aadFor(chunkKey))) : payload;
     await this.sink.write(stored);
     this.entries.push({
       chunkKey,
@@ -2527,20 +2962,18 @@ var CrbmWriter = class {
     this.totalCardinality += cardinality;
     this.lastKey = chunkKey;
   }
-  /** Seal one chunk payload into the on-disk frame `nonce ‖ ciphertext ‖ tag`, bound to its chunkKey. */
-  sealChunk(chunkKey, payload) {
-    const crypto = this.options.crypto;
-    const sealed = crypto.aead.seal(payload, crypto.aadFor(chunkKey));
-    const out = new Uint8Array(sealed.nonce.length + sealed.ciphertext.length + sealed.tag.length);
-    out.set(sealed.nonce, 0);
-    out.set(sealed.ciphertext, sealed.nonce.length);
-    out.set(sealed.tag, sealed.nonce.length + sealed.ciphertext.length);
-    return out;
-  }
-  /** Write the index region + the fixed footer. After this the object is complete and immutable. */
+  /**
+   * Write the extension block (when there is metadata), the index region and the fixed footer. After this the object
+   * is complete and immutable.
+   */
   async finish() {
     if (this.finished) throw new ValidationError("CrbmWriter already finished");
     await this.ensurePreamble();
+    if (this.metadata !== void 0) {
+      const block = this.extensionBlock(this.metadata);
+      await this.sink.write(block);
+      this.offset += block.length;
+    }
     const indexPlain = this.encodeIndex();
     let indexRegion = indexPlain;
     let indexNonce;
@@ -2556,8 +2989,22 @@ var CrbmWriter = class {
     this.offset += indexRegion.length;
     const footer = this.buildFooter(indexOffset, indexRegion, indexNonce, indexTag);
     await this.sink.write(footer);
+    this.written = this.offset + footer.length;
+    this.footerCrc32c = new DataView(footer.buffer, footer.byteOffset).getUint32(
+      FOOTER.footerCrc32c,
+      true
+    );
     this.finished = true;
   }
+  /**
+   * The finished object's size and its footer's CRC: what names it, as a reader's fingerprint does. A writer that
+   * has to tell its own object from another stored later under the same key compares these with the object's
+   * footer. Throws before {@link finish}.
+   */
+  get identity() {
+    if (this.footerCrc32c === void 0) throw new ValidationError("CrbmWriter not finished");
+    return { size: this.written, footerCrc: this.footerCrc32c };
+  }
   async ensurePreamble() {
     if (this.preambleWritten) return;
     const preamble = new Uint8Array(PREAMBLE_BYTES);
@@ -2567,6 +3014,25 @@ var CrbmWriter = class {
     await this.sink.write(preamble);
     this.preambleWritten = true;
   }
+  /**
+   * The extension block: one metadata section (`u8 type ‖ u32 length ‖ bytes`), then the trailer
+   * (`u32 sectionsLength ‖ u32 crc32c(sections ‖ sectionsLength) ‖ "CRBX"`). Encrypted, the section holds
+   * `nonce ‖ ciphertext ‖ tag`, sealed with the metadata scope of the associated data.
+   */
+  extensionBlock(metadata) {
+    const crypto = this.options.crypto;
+    const body = crypto ? framed(crypto.aead.seal(metadata, crypto.aadFor("metadata"))) : metadata;
+    const sectionsLength = EXT_SECTION_HEADER_BYTES + body.length;
+    const block = new Uint8Array(sectionsLength + EXT_TRAILER_BYTES);
+    const view = new DataView(block.buffer);
+    block[0] = EXT_SECTION_METADATA;
+    view.setUint32(1, body.length, true);
+    block.set(body, EXT_SECTION_HEADER_BYTES);
+    view.setUint32(sectionsLength, sectionsLength, true);
+    view.setUint32(sectionsLength + 4, crc32c(block.subarray(0, sectionsLength + 4)), true);
+    block.set(EXT_MAGIC, sectionsLength + 8);
+    return block;
+  }
   encodeIndex() {
     const out = [];
     let prevKey = 0;
@@ -2594,7 +3060,11 @@ var CrbmWriter = class {
     view.setBigUint64(FOOTER.indexOffset, BigInt(indexOffset), true);
     view.setBigUint64(FOOTER.indexLength, BigInt(indexRegion.length), true);
     view.setUint32(FOOTER.indexCrc32c, crc32c(indexRegion), true);
-    view.setUint32(FOOTER.flags, FLAG_LITTLE_ENDIAN | (encrypted ? FLAG_ENCRYPTED : 0), true);
+    view.setUint32(
+      FOOTER.flags,
+      FLAG_LITTLE_ENDIAN | (encrypted ? FLAG_ENCRYPTED : 0) | (this.metadata === void 0 ? 0 : FLAG_EXTENSION),
+      true
+    );
     view.setUint16(
       FOOTER.payloadCodecId,
       this.options.payloadCodecId ?? PAYLOAD_CODEC_ROARING_PORTABLE,
@@ -2614,6 +3084,226 @@ var CrbmWriter = class {
     return footer;
   }
 };
+function framed(sealed) {
+  const out = new Uint8Array(sealed.nonce.length + sealed.ciphertext.length + sealed.tag.length);
+  out.set(sealed.nonce, 0);
+  out.set(sealed.ciphertext, sealed.nonce.length);
+  out.set(sealed.tag, sealed.nonce.length + sealed.ciphertext.length);
+  return out;
+}
+
+// src/core/load-input.ts
+var MAX_SERIALIZED_LOAD_BYTES = 4 + 8192 + 8 * 65536 + 65536 * 8192;
+var DecodedLoadInput = class {
+  constructor(bitmap) {
+    this.bitmap = bitmap;
+  }
+  bitmap;
+};
+function tagOf(value) {
+  return Object.prototype.toString.call(value).slice(8, -1);
+}
+var VIEW = Object.getPrototypeOf(Uint8Array.prototype);
+var viewGetter = (name) => Object.getOwnPropertyDescriptor(VIEW, name)?.get;
+var bufferOf = viewGetter("buffer");
+var byteOffsetOf = viewGetter("byteOffset");
+var byteLengthOf = viewGetter("byteLength");
+function plainView(bytes, what) {
+  let buffer;
+  let offset;
+  let length;
+  try {
+    buffer = bufferOf.call(bytes);
+    offset = byteOffsetOf.call(bytes);
+    length = byteLengthOf.call(bytes);
+  } catch {
+    throw new ValidationError(`${what} must be a Uint8Array of portable Roaring bytes`);
+  }
+  return length === 0 ? new Uint8Array(0) : new Uint8Array(buffer, offset, length);
+}
+var sharedByteLength = typeof SharedArrayBuffer === "function" ? Object.getOwnPropertyDescriptor(SharedArrayBuffer.prototype, "byteLength")?.get : void 0;
+function isShared(buffer) {
+  if (sharedByteLength === void 0) return false;
+  try {
+    sharedByteLength.call(buffer);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function overCap(what, length) {
+  return new ValidationError(
+    `${what} is ${length} bytes, more than any canonical 32-bit bitmap serializes to (${MAX_SERIALIZED_LOAD_BYTES}). Call runOptimize() on the bitmap before serializing it.`
+  );
+}
+function prepareLoadInput(input, codec) {
+  if (typeof input !== "object" || input === null) {
+    throw new ValidationError(
+      `a load takes ids, { serialized } or { bitmap }; got ${String(input)}`
+    );
+  }
+  const tag = tagOf(input);
+  if (tag === "Uint8Array" || tag === "Uint8ClampedArray") {
+    throw new ValidationError(
+      `a load's ids cannot be a ${tag} or Buffer: each byte would be loaded as an id. Pass portable Roaring bytes as { serialized }, and ids as a Uint32Array or an array of numbers.`
+    );
+  }
+  if (Symbol.iterator in input || Symbol.asyncIterator in input) return input;
+  const keys = Object.keys(input);
+  if (keys.length === 1 && keys[0] === "serialized") {
+    return decode(input.serialized, "{ serialized }", codec);
+  }
+  if (keys.length === 1 && keys[0] === "bitmap") {
+    const bitmap = input.bitmap;
+    if (typeof bitmap !== "object" || bitmap === null || typeof bitmap.serialize !== "function") {
+      throw new ValidationError(`{ bitmap } needs an object with serialize('portable')`);
+    }
+    const what = "{ bitmap }'s serialize('portable')";
+    if (typeof bitmap.getSerializationSizeInBytes === "function") {
+      const size = bitmap.getSerializationSizeInBytes("portable");
+      if (typeof size === "number" && size > MAX_SERIALIZED_LOAD_BYTES) throw overCap(what, size);
+    }
+    return decode(bitmap.serialize("portable"), what, codec);
+  }
+  throw new ValidationError(
+    `a load takes ids (an iterable of integers), { serialized } or { bitmap }, as the only key; got an object with keys [${keys.join(", ")}]. Load options go in the next argument.`
+  );
+}
+function decode(bytes, what, codec) {
+  if (typeof bytes !== "object" || bytes === null || tagOf(bytes) !== "Uint8Array") {
+    throw new ValidationError(`${what} must be a Uint8Array of portable Roaring bytes`);
+  }
+  const view = plainView(bytes, what);
+  if (view.byteLength > MAX_SERIALIZED_LOAD_BYTES) throw overCap(what, view.byteLength);
+  const own = isShared(view.buffer) ? new Uint8Array(view) : view;
+  try {
+    return new DecodedLoadInput(
+      codec.safeDeserialize(own, MAX_SERIALIZED_LOAD_BYTES, { whole: true })
+    );
+  } catch (err) {
+    if (!isIntegrityError(err)) throw err;
+    throw new ValidationError(`${what} is not a valid bitmap: ${err.message}`);
+  }
+}
+
+// src/core/summary.ts
+var NONCE_BYTES = 12;
+var TAG_BYTES = 16;
+var COUNT_BYTES = 8;
+var MAX_CARDINALITY = 2 ** 32;
+var BASE64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+function toBase64(bytes) {
+  let out = "";
+  for (let i = 0; i < bytes.length; i += 3) {
+    const a = bytes[i];
+    const b = bytes[i + 1];
+    const c = bytes[i + 2];
+    out += BASE64[a >> 2] + BASE64[(a & 3) << 4 | (b ?? 0) >> 4];
+    out += b === void 0 ? "=" : BASE64[(b & 15) << 2 | (c ?? 0) >> 6];
+    out += c === void 0 ? "=" : BASE64[c & 63];
+  }
+  return out;
+}
+function fromBase64(text) {
+  if (text.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(text)) return void 0;
+  const pad = text.endsWith("==") ? 2 : text.endsWith("=") ? 1 : 0;
+  const out = new Uint8Array(text.length / 4 * 3 - pad);
+  let o = 0;
+  for (let i = 0; i < text.length; i += 4) {
+    const n = BASE64.indexOf(text[i]) << 18 | BASE64.indexOf(text[i + 1]) << 12 | Math.max(BASE64.indexOf(text[i + 2]), 0) << 6 | Math.max(BASE64.indexOf(text[i + 3]), 0);
+    if (o < out.length) out[o++] = n >> 16 & 255;
+    if (o < out.length) out[o++] = n >> 8 & 255;
+    if (o < out.length) out[o++] = n & 255;
+  }
+  return out;
+}
+function clearSummary(generation, cardinality, metadata) {
+  return metadata === void 0 || Object.keys(metadata).length === 0 ? { generation, cardinality } : { generation, cardinality, metadata };
+}
+function sealSummary(aead, ref, generation, cardinality, metadata) {
+  const meta = metadataBytes(metadata, (message) => {
+    throw new IntegrityError(`summary metadata: ${message}`);
+  });
+  const plain = new Uint8Array(COUNT_BYTES + (meta?.length ?? 0));
+  new DataView(plain.buffer).setBigUint64(0, BigInt(cardinality), true);
+  if (meta !== void 0) plain.set(meta, COUNT_BYTES);
+  const { nonce, ciphertext, tag } = aead.seal(plain, aadFor(ref, generation, "summary"));
+  const framed2 = new Uint8Array(nonce.length + ciphertext.length + tag.length);
+  framed2.set(nonce, 0);
+  framed2.set(ciphertext, nonce.length);
+  framed2.set(tag, nonce.length + ciphertext.length);
+  return { generation, sealed: toBase64(framed2) };
+}
+function openSummary(aead, ref, summary) {
+  const fail = (message) => {
+    throw new IntegrityError(`registry record summary: ${message}`);
+  };
+  const framed2 = fromBase64(summary.sealed);
+  const framing = NONCE_BYTES + TAG_BYTES;
+  if (framed2 === void 0 || framed2.length < framing + COUNT_BYTES || framed2.length > framing + COUNT_BYTES + MAX_METADATA_BYTES) {
+    fail("the sealed summary is not a nonce, a count, up to 1 KiB of metadata and a tag");
+  }
+  const bytes = framed2;
+  let plain;
+  try {
+    plain = aead.open(
+      {
+        nonce: bytes.subarray(0, NONCE_BYTES),
+        ciphertext: bytes.subarray(NONCE_BYTES, bytes.length - TAG_BYTES),
+        tag: bytes.subarray(bytes.length - TAG_BYTES)
+      },
+      aadFor(ref, summary.generation, "summary")
+    );
+  } catch (err) {
+    if (!isIntegrityError(err)) throw err;
+    return fail(
+      "the sealed summary does not open: tampered bytes, or a summary moved from another generation"
+    );
+  }
+  if (plain.length < COUNT_BYTES) fail("the sealed summary is shorter than its count");
+  const count = new DataView(plain.buffer, plain.byteOffset, plain.byteLength).getBigUint64(
+    0,
+    true
+  );
+  if (count > BigInt(MAX_CARDINALITY)) fail(`cardinality ${count} is outside 0 to 2^32`);
+  const metadata = plain.length === COUNT_BYTES ? void 0 : metadataFromBytes(plain.subarray(COUNT_BYTES), fail);
+  return { cardinality: Number(count), metadata };
+}
+function usableSummary(ref, row, aead) {
+  const summary = row.summary;
+  if (summary === void 0 || row.status !== "active" || summary.generation !== row.currentGen) {
+    return void 0;
+  }
+  const keyed = row.wrappedDeks !== void 0 && row.wrappedDeks.length > 0;
+  if ("sealed" in summary) {
+    if (!keyed || aead === void 0) return void 0;
+    try {
+      return openSummary(aead, ref, summary);
+    } catch (err) {
+      if (isIntegrityError(err)) return void 0;
+      throw err;
+    }
+  }
+  if (keyed) return void 0;
+  return { cardinality: summary.cardinality, metadata: summary.metadata };
+}
+function canonicalOrNone(metadata) {
+  if (metadata === void 0) return void 0;
+  const json = canonicalMetadataJson(metadata, (message) => {
+    throw new IntegrityError(`metadata: ${message}`);
+  });
+  return json === "{}" ? void 0 : json;
+}
+function summaryAgrees(summary, object) {
+  return summary.cardinality === object.cardinality && canonicalOrNone(summary.metadata) === canonicalOrNone(object.metadata);
+}
+function metadataToCarry(object, authenticated) {
+  const empty = (metadata) => metadata === void 0 || Object.keys(metadata).length === 0;
+  return empty(object) && authenticated !== void 0 && !empty(authenticated.metadata) ? authenticated.metadata : object;
+}
+function summaryOf(ref, generation, description, aead) {
+  return aead === void 0 ? clearSummary(generation, description.cardinality, description.metadata) : sealSummary(aead, ref, generation, description.cardinality, description.metadata);
+}
 
 // src/core/crbm-storage-source.ts
 function storageBlobReader(driver, key) {
@@ -2632,6 +3322,88 @@ var notThePinned = (ref, generation) => new NotFoundError(
 function versionOf(generation, lineage) {
   return lineage === void 0 ? String(generation) : `${generation}:${String(lineage)}`;
 }
+function summaryOfGeneration(generation, description) {
+  const { cardinality, metadata } = description;
+  return metadata === void 0 || Object.keys(metadata).length === 0 ? { generation, cardinality } : { generation, cardinality, metadata: Object.freeze({ ...metadata }) };
+}
+var sameKeys = (a, b) => a !== void 0 && JSON.stringify(a) === JSON.stringify(b);
+function once(fn) {
+  let pending;
+  return () => {
+    if (pending === void 0) {
+      const mine = fn();
+      pending = mine;
+      mine.catch(() => {
+        if (pending === mine) pending = void 0;
+      });
+    }
+    return pending;
+  };
+}
+var readerIsOf = (reader, live) => reader.generation === live.target.generation && reader.lineage === live.target.lineage;
+function describe(reader) {
+  let cardinality = 0;
+  for (const n of reader.cardinalities().values()) cardinality += n;
+  return { cardinality, metadata: reader.metadata };
+}
+var Snapshot = class _Snapshot {
+  constructor(target, open4, prior) {
+    this.target = target;
+    this.open = open4;
+    this.prior = prior;
+  }
+  target;
+  open;
+  prior;
+  /** When the snapshot's refresh clock started. A refresh that failed transiently moves it back, so it lapses sooner. */
+  installedAtMs = 0;
+  /** Set by the cache, to hear of a reader as it is opened. */
+  onReader;
+  opened;
+  static live(target, open4, prior) {
+    return new _Snapshot(target, open4, prior);
+  }
+  static eager(reader) {
+    const snap = new _Snapshot(void 0, void 0, void 0);
+    snap.opened = reader;
+    return snap;
+  }
+  /** The reader, opened by the first call. */
+  get reader() {
+    if (this.opened === void 0) {
+      const target = this.target;
+      this.opened = target.then(async (live) => {
+        if (live === null) return null;
+        const kept = await this.reuse(live);
+        this.prior = void 0;
+        return kept ?? this.open(live);
+      });
+      this.onReader?.(this.opened);
+    }
+    return this.opened;
+  }
+  /** The reader if one has been asked for, without asking for one. */
+  get openedReader() {
+    return this.opened;
+  }
+  /** The prior snapshot's reader, if it is of what this snapshot resolved. */
+  async reuse(live) {
+    const prior = this.prior;
+    const reader = prior === void 0 ? null : await prior.catch(() => null);
+    return reader !== null && readerIsOf(reader, live) ? reader : null;
+  }
+  /** Keep the prior snapshot's reader when the refresh found its generation, so a count does not drop it. */
+  async adopt(live) {
+    if (this.opened !== void 0 || this.prior === void 0) return;
+    const reader = await this.reuse(live);
+    this.prior = void 0;
+    if (reader !== null && this.opened === void 0) {
+      this.opened = Promise.resolve(reader);
+      this.onReader?.(this.opened);
+    }
+  }
+};
+var SNAPSHOT_BASE_BYTES = 256;
 var BULK_FLUSH_IDS = 1 << 20;
 var YIELD_EVERY_IDS = 1 << 14;
 var CrbmStorageChunkSource = class {
@@ -2669,6 +3441,10 @@ var CrbmStorageChunkSource = class {
       maxBytes: maxOpenIndexBytes ?? DEFAULT_MAX_OPEN_INDEX_BYTES,
       clock: clock ?? { now: () => 0 }
     });
+    this.distrusted = new BoundedLru({
+      maxEntries: maxOpenSegments ?? DEFAULT_MAX_OPEN_SEGMENTS,
+      clock: { now: () => 0 }
+    });
     this.replacedPins = new BoundedLru({
       maxEntries: maxOpenSegments ?? DEFAULT_MAX_OPEN_SEGMENTS,
       clock: { now: () => 0 }
@@ -2710,23 +3486,46 @@ var CrbmStorageChunkSource = class {
    * check again.
    */
   invalidations = 0;
+  /**
+   * Generations whose row summary this process found to disagree with their object, by segment and generation. A
+   * summary here is not used again: a count of that generation reads the object. Bounded as the readers are, so a
+   * long-lived process cannot grow it without limit; one that falls out is trusted again until its next open finds
+   * the disagreement again.
+   */
+  distrusted;
   registry;
   keystore;
   requireEncryption;
   readerOptions;
   clock;
   currentGenTtlMs;
-  /** The current resolved reader for a segment, refreshing on the TTL. Cheap within the TTL window. */
-  resolvedReader(ref) {
+  /**
+   * The segment's live snapshot, refreshing on the TTL. Cheap within the TTL window. The snapshot holds the resolved
+   * target, and its reader once a read has asked for one.
+   */
+  liveSnapshot(ref) {
     const key = segmentKey(ref);
     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;
+    if (existing === void 0) {
+      return this.install(
+        key,
+        Snapshot.live(this.resolveLive(ref), (live) => this.openLive(ref, live))
+      );
+    }
+    if (!this.expired(existing.installedAtMs)) return existing;
     const snap = this.install(
       key,
-      this.computeRefreshedReader(ref, existing, () => this.retrySoon(snap))
+      Snapshot.live(
+        this.refreshedTarget(ref, existing, () => this.retrySoon(snap)),
+        (live) => this.openLive(ref, live),
+        existing.openedReader
+      )
     );
-    return snap.reader;
+    return snap;
+  }
+  /** The current resolved reader for a segment, refreshing on the TTL. */
+  resolvedReader(ref) {
+    return this.liveSnapshot(ref).reader;
   }
   /**
    * A refresh failed transiently and the prior reader keeps serving: make this snapshot lapse after
@@ -2736,45 +3535,56 @@ var CrbmStorageChunkSource = class {
   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, onTransientFault) {
-    const current = await existing.reader.catch(() => null);
-    let target;
+  /**
+   * TTL elapsed: cheaply re-resolve the pointer. The row read is always fresh, so what the new snapshot says of the
+   * generation (its summary included) is what the row says now, never the prior snapshot's. The reader is reopened
+   * only if the generation or the row changed, and only when a read asks for it.
+   */
+  async refreshedTarget(ref, existing, onTransientFault) {
+    const prior = await existing.target.catch(() => null);
     try {
-      target = await this.resolveTarget(ref);
+      return await this.resolveLive(ref, prior);
     } catch (err) {
       if (!isTransientError(err)) throw err;
-      target = void 0;
-    }
-    if (target === void 0) {
-      if (current === null) return this.resolveLatest(ref);
+      const alive = prior !== null;
+      if (!alive) return this.resolveLive(ref);
       onTransientFault();
-      return current;
+      return prior;
     }
-    if (target === null) return null;
-    if (current !== null && target.generation === current.generation && target.lineage === current.lineage) {
-      return current;
-    }
-    return this.openForTarget(ref, target);
   }
   /**
-   * Memoize a reader-promise as the segment's snapshot at `now()`, forgetting it later if it resolves to
-   * null / throws (identity-guarded, so a stale cleanup never clobbers a fresher snapshot). Installing the
-   * (pending) promise **synchronously** is what lets concurrent callers coalesce onto one in-flight resolve.
+   * Memoize a snapshot as the segment's at `now()`, forgetting it later if it resolves to null / throws
+   * (identity-guarded, so a stale cleanup never clobbers a fresher snapshot). Installing the (pending) snapshot
+   * **synchronously** is what lets concurrent callers coalesce onto one in-flight resolve.
    */
-  install(key, reader) {
-    const snap = { reader, installedAtMs: this.now() };
+  install(key, snap) {
+    snap.installedAtMs = this.now();
     this.snapshots.set(key, snap);
     const forgetIfStale = () => {
       if (this.snapshots.get(key) === snap) this.snapshots.delete(key);
     };
-    reader.then((r) => {
-      if (r === null) {
-        forgetIfStale();
-        return;
-      }
-      if (this.snapshots.peek(key) === snap) this.snapshots.setWeight(key, r.retainedIndexBytes);
-    }, forgetIfStale);
+    snap.onReader = (reader) => {
+      reader.then((r) => {
+        if (r === null) {
+          forgetIfStale();
+          return;
+        }
+        if (this.snapshots.peek(key) === snap) this.snapshots.setWeight(key, r.retainedBytes);
+      }, forgetIfStale);
+    };
+    if (snap.target !== void 0) {
+      snap.target.then(async (live) => {
+        if (live === null) {
+          forgetIfStale();
+          return;
+        }
+        if (snap.openedReader === void 0 && this.snapshots.peek(key) === snap) {
+          this.snapshots.setWeight(key, live.bytes);
+        }
+        await snap.adopt(live);
+      }, forgetIfStale);
+    }
+    if (snap.openedReader !== void 0) snap.onReader(snap.openedReader);
     return snap;
   }
   now() {
@@ -2806,12 +3616,12 @@ var CrbmStorageChunkSource = class {
    * concurrent sweep. One retry, then propagate — same contract, same eviction rule.
    */
   async currentGeneration(ref) {
-    const pending = this.resolvedReader(ref);
+    const snap = this.liveSnapshot(ref);
     try {
-      return (await pending)?.generation ?? null;
+      return (await snap.reader)?.generation ?? null;
     } catch (err) {
       if (!isNotFoundError(err)) throw err;
-      this.dropStale(segmentKey(ref), pending);
+      this.dropStale(segmentKey(ref), snap);
       return (await this.resolvedReader(ref))?.generation ?? null;
     }
   }
@@ -2831,6 +3641,7 @@ var CrbmStorageChunkSource = class {
     const key = segmentKey(ref);
     this.snapshots.delete(key);
     const pinnedPrefix = `${key}@`;
+    this.distrusted.deleteWhere((k) => k.startsWith(pinnedPrefix));
     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);
@@ -2851,13 +3662,13 @@ var CrbmStorageChunkSource = class {
    * almost always served from the cached snapshot with no backend call at all. One retry, then propagate.
    */
   async currentVersion(ref) {
-    const pending = this.resolvedReader(ref);
+    const snap = this.liveSnapshot(ref);
     let reader;
     try {
-      reader = await pending;
+      reader = await snap.reader;
     } catch (err) {
       if (!isNotFoundError(err)) throw err;
-      this.dropStale(segmentKey(ref), pending);
+      this.dropStale(segmentKey(ref), snap);
       reader = await this.resolvedReader(ref);
     }
     return reader === null ? null : versionOf(reader.generation, reader.lineage);
@@ -2880,34 +3691,38 @@ var CrbmStorageChunkSource = class {
     }
   }
   async pinOnce(ref) {
-    const target = await this.resolveTarget(ref);
-    if (target === null) return null;
+    const live = await this.resolveLive(ref);
+    if (live === null) return null;
+    const target = live.target;
     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));
+      reader = await this.openLive(ref, live);
+      this.install(
+        this.pinnedKey(ref, version, reader.fingerprint),
+        Snapshot.eager(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));
+      entry ??= this.install(key, Snapshot.eager(this.openLive(ref, live)));
       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));
+        this.install(key, Snapshot.eager(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));
+        let fresh = current !== void 0 && current !== entry ? current : this.install(key, Snapshot.eager(this.openLive(ref, live)));
         reader = await fresh.reader;
         if (reader === null) return null;
         if (fresh === current && replaced(reader)) {
-          fresh = this.install(key, this.openForTarget(ref, target));
+          fresh = this.install(key, Snapshot.eager(this.openLive(ref, live)));
           reader = await fresh.reader;
           if (reader === null) return null;
         }
@@ -2973,7 +3788,7 @@ var CrbmStorageChunkSource = class {
     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));
+      entry = this.install(key, Snapshot.eager(this.openAt(ref, generation)));
     }
     let reader;
     try {
@@ -3108,58 +3923,94 @@ var CrbmStorageChunkSource = class {
     return false;
   }
   /**
-   * Evict a snapshot we just failed to read from — matched by its reader *promise*, so a concurrent call's
+   * Evict a snapshot we just failed to read from — matched by the snapshot itself, so a concurrent call's
    * fresher snapshot is never clobbered. The identity guard is the whole point: `install` replaces the entry
    * wholesale, so comparing anything else would drop a good snapshot on the floor.
    */
-  dropStale(key, pending) {
-    const cur = this.snapshots.get(key);
-    if (cur !== void 0 && cur.reader === pending) this.snapshots.delete(key);
-  }
-  async resolveLatest(ref) {
-    const target = await this.resolveTarget(ref);
-    if (target === null) return null;
-    return this.openForTarget(ref, target);
+  dropStale(key, snap) {
+    if (this.snapshots.get(key) === snap) this.snapshots.delete(key);
   }
   /** Open a {@link CrbmReader} for an already-resolved generation target (decrypting if the segment is encrypted). */
   async openForTarget(ref, target) {
+    const crypto = await this.cryptoForRead(ref, target.generation, target.wrappedDeks);
+    return this.openGeneration(ref, target, crypto);
+  }
+  openGeneration(ref, target, crypto) {
     const genKey = {
       namespace: ref.namespace,
       segment: ref.segment,
       generation: target.generation
     };
-    const crypto = await this.cryptoForRead(ref, target.generation, target.wrappedDeks);
     return openChecked(this.driver, genKey, {
       ...this.readerOptions,
       crypto,
       lineage: target.lineage
     });
   }
+  /**
+   * Open the generation a resolution found, and hold the row's summary against the object while it is open anyway:
+   * the same count and metadata, or the summary is not believed again in this process ({@link distrusted}). This
+   * costs no request; a mismatch is not an error, since the object is the truth and this read has it.
+   */
+  async openLive(ref, live) {
+    const reader = await this.openGeneration(ref, live.target, await live.crypto());
+    const summary = await live.summary();
+    if (summary !== void 0 && !summaryAgrees(summary, describe(reader))) {
+      this.distrusted.set(this.distrustKey(ref, live.target.generation, live.target.lineage), true);
+    }
+    return reader;
+  }
+  distrustKey(ref, generation, lineage) {
+    return `${segmentKey(ref)}@${generation}:${String(lineage)}`;
+  }
+  /** What the row says of the generation, unless it is a summary this process has found to disagree with its object. */
+  async trustedSummary(ref, live) {
+    if (this.distrusted.peek(this.distrustKey(ref, live.target.generation, live.target.lineage)) !== void 0) {
+      return void 0;
+    }
+    return live.summary();
+  }
   /**
    * The current generation + its DEK wrappings: the registry's authoritative record (one strong read), or a
    * `list` scan for the max generation when there's no registry (a registry-less source can only read cleartext
-   * — there's nowhere a wrapped DEK could live).
+   * — there's nowhere a wrapped DEK could live). The row's summary rides along, to be used or not by whoever
+   * asks.
    */
-  async resolveTarget(ref) {
+  async resolveLive(ref, prior) {
     if (this.registry !== void 0) {
       const record = await this.registry.get(ref);
       if (record === null) return null;
       if (record.status === "destroyed") return null;
       if (record.currentGen === null) return null;
+      const generation = record.currentGen;
+      const keys = record.wrappedDeks;
+      const unwrap = keys === void 0 || keys.length === 0 || this.keystore === void 0 ? void 0 : prior?.unwrap !== void 0 && sameKeys(prior.target.wrappedDeks, keys) ? prior.unwrap : once(() => this.keystore.openDek(keys));
+      const crypto = once(() => this.cryptoForRead(ref, generation, keys, unwrap));
       return {
-        generation: record.currentGen,
-        lineage: record.token,
-        wrappedDeks: record.wrappedDeks
+        target: { generation, lineage: record.token, wrappedDeks: record.wrappedDeks },
+        crypto,
+        unwrap,
+        // The same checks as a read of the object makes (`requireEncryption`, a keystore for an encrypted row)
+        // come first, then the row's summary, used only if it names this generation in the shape the keys call for.
+        summary: once(async () => usableSummary(ref, record, (await crypto())?.aead)),
+        bytes: SNAPSHOT_BASE_BYTES + (record.summary === void 0 ? 0 : JSON.stringify(record.summary).length)
       };
     }
     let maxGen = -1;
     for await (const key of this.driver.list(ref)) {
       if (key.generation > maxGen) maxGen = key.generation;
     }
-    return maxGen < 0 ? null : { generation: maxGen };
+    if (maxGen < 0) return null;
+    return {
+      target: { generation: maxGen },
+      crypto: () => Promise.resolve(void 0),
+      unwrap: void 0,
+      summary: () => Promise.resolve(void 0),
+      bytes: SNAPSHOT_BASE_BYTES
+    };
   }
   /** Build the per-generation decryption context for an encrypted segment (undefined for cleartext). */
-  async cryptoForRead(ref, generation, wrappedDeks) {
+  async cryptoForRead(ref, generation, wrappedDeks, unwrap) {
     if (wrappedDeks === void 0 || wrappedDeks.length === 0) {
       if (this.requireEncryption) {
         throw new KeyUnavailableError(
@@ -3168,12 +4019,13 @@ var CrbmStorageChunkSource = class {
       }
       return void 0;
     }
-    if (this.keystore === void 0) {
+    const keystore = this.keystore;
+    if (keystore === void 0) {
       throw new KeyUnavailableError(
         `segment "${ref.segment}" is encrypted but this CrbmStorageChunkSource has no keystore`
       );
     }
-    const aead = await this.keystore.openDek(wrappedDeks);
+    const aead = await (unwrap ?? (() => keystore.openDek(wrappedDeks)))();
     return { aead, aadFor: (scope) => aadFor(ref, generation, scope) };
   }
   async getChunk(ref) {
@@ -3200,6 +4052,46 @@ var CrbmStorageChunkSource = class {
       null
     );
   }
+  /**
+   * The current generation's number, id count and metadata. The answer comes from the row the snapshot resolved when
+   * it can: the row's summary of the generation it names, on an active row, in the shape the row's keys call for
+   * (a sealed one is opened with the segment's key), and one this process has not found to disagree with its
+   * object. That is one registry read when the snapshot is cold, none when it is warm, and no read of the object.
+   * With no summary it can use (an older row, one for another generation, one that does not open), it opens the
+   * generation and answers from the object. A row that names an object that is gone still answers, while a read
+   * of the object throws: the number is true of the generation the row names.
+   *
+   * What the row says is not confirmed here: a summary edited to agree with itself by whoever can write the row is
+   * believed until the next time the object is opened, which holds it against the summary.
+   */
+  async summary(ref) {
+    validateUserRef(ref);
+    for (let attempt = 0; attempt < 2; attempt++) {
+      const snap = this.liveSnapshot(ref);
+      try {
+        const live = await snap.target;
+        if (live === null) return null;
+        const row = await this.trustedSummary(ref, live);
+        if (row !== void 0) return summaryOfGeneration(live.target.generation, row);
+        const reader = await snap.reader;
+        return reader === null ? null : summaryOfGeneration(reader.generation, describe(reader));
+      } catch (err) {
+        if (attempt === 1) throw err;
+        const checks = isNotFoundError(err) || isIntegrityError(err) || isValidationError(err);
+        if (!checks || !isNotFoundError(err) && !await this.replacedUnder(ref, snap.reader, err)) {
+          throw err;
+        }
+        this.dropStale(segmentKey(ref), snap);
+      }
+    }
+    return null;
+  }
+  /** {@link summary} of a specific generation, from the object a pin holds. `held` as for {@link getChunkAt}. */
+  async summaryAt(ref, generation, held) {
+    validateUserRef(ref);
+    const reader = await this.readerAt(ref, generation, held?.version, held?.fingerprint);
+    return reader === null ? null : summaryOfGeneration(reader.generation, describe(reader));
+  }
   /**
    * Run `read` against the pinned snapshot, healing the torn-read window generation GC can open: if the
    * generation we resolved was superseded *and* swept (the grace window elapsed), the Storage driver throws
@@ -3228,40 +4120,143 @@ var CrbmStorageChunkSource = class {
    */
   async withFreshSnapshot(ref, read, ifGone) {
     for (let attempt = 0; attempt < 2; attempt++) {
-      const pending = this.resolvedReader(ref);
+      const snap = this.liveSnapshot(ref);
+      const pending = snap.reader;
       try {
         const reader = await pending;
         if (reader === null) return ifGone;
         return await read(reader);
       } catch (err) {
-        if (!isNotFoundError(err) || attempt === 1) throw err;
-        this.dropStale(segmentKey(ref), pending);
+        if (attempt === 1) throw err;
+        if (!isNotFoundError(err) && !await this.replacedUnder(ref, pending, err)) throw err;
+        this.dropStale(segmentKey(ref), snap);
       }
     }
     return ifGone;
   }
+  /**
+   * Whether `err`, raised by a read through the snapshot's reader, came from an object that is no longer the one the
+   * reader opened. A generation number can be taken again once its object is deleted (an erasure removes the
+   * generations above a rolled-back pointer that held the id, a collection pass can stop part-way, and a load then
+   * numbers `currentGen + 1` again), so a reader that still holds the old object's index reads the new object's
+   * bytes at the old offsets: a chunk checksum fails, or a range runs past the end. The object's footer says which it
+   * was, as it does for a pin ({@link CrbmReader.sameObject}): replaced, or gone, re-resolves; the same object means
+   * the error is real, and it stands. Only these two errors pay for the footer read, never a read that succeeded. A
+   * transient fault in the check is rethrown; a footer that cannot be read says nothing, and the error stands.
+   */
+  async replacedUnder(ref, pending, err) {
+    if (!(isIntegrityError(err) || isValidationError(err))) return false;
+    let reader;
+    try {
+      reader = await pending;
+    } catch {
+      return false;
+    }
+    if (reader === null) return false;
+    const at = {
+      namespace: ref.namespace,
+      segment: ref.segment,
+      generation: reader.generation
+    };
+    try {
+      return !await CrbmReader.sameObject(storageBlobReader(this.driver, at), reader.fingerprint);
+    } catch (checkErr) {
+      if (isNotFoundError(checkErr)) return true;
+      if (isTransientError(checkErr)) throw checkErr;
+      return false;
+    }
+  }
 };
-function writeCrbmGeneration(driver, key, chunks, options = {}) {
-  const sorted = [...chunks].sort((a, b) => a.chunkKey - b.chunkKey);
+function* encodeEach(chunks) {
+  for (const { chunkKey, bitmap } of chunks) {
+    if (bitmap.isEmpty) continue;
+    bitmap.optimize?.();
+    yield { chunkKey, payload: bitmap.serialize(), cardinality: bitmap.size };
+  }
+}
+async function writeEncodedChunks(driver, key, chunks, options) {
   const tick = yieldEvery(options.clock);
-  return driver.putImmutable(key, async (sink) => {
-    const writer = new CrbmWriter(sink, { generation: key.generation, crypto: options.crypto });
-    for (const { chunkKey, bitmap } of sorted) {
-      if (bitmap.isEmpty) continue;
-      bitmap.optimize?.();
-      await writer.addChunk(chunkKey, bitmap.serialize(), bitmap.size);
+  let chunkCount = 0;
+  let cardinality = 0;
+  let identity;
+  const { size, sha256 } = await driver.putImmutable(key, async (sink) => {
+    const writer = new CrbmWriter(sink, {
+      generation: key.generation,
+      crypto: options.crypto,
+      metadata: options.metadata
+    });
+    for (const chunk of chunks) {
+      await writer.addChunk(chunk.chunkKey, chunk.payload, chunk.cardinality);
+      chunkCount++;
+      cardinality += chunk.cardinality;
       const pause = tick();
       if (pause !== null) await pause;
     }
     await writer.finish();
+    identity = writer.identity;
   });
+  if (identity === void 0) {
+    throw new IntegrityError(
+      `the driver committed ${key.segment}.${key.generation} without writing it`
+    );
+  }
+  return {
+    size,
+    sha256,
+    chunkCount,
+    cardinality,
+    fingerprint: fingerprintFor(identity.size, identity.footerCrc)
+  };
+}
+async function holdsObject(storage, key, fingerprint) {
+  try {
+    return await CrbmReader.sameObject(storageBlobReader(storage, key), fingerprint);
+  } catch {
+    return false;
+  }
+}
+function objectIsEncrypted(storage, key) {
+  return footerSaysEncrypted(storageBlobReader(storage, key));
+}
+function rememberingTail(blob) {
+  let first;
+  return {
+    getRange: (offset, length) => blob.getRange(offset, length),
+    async getTail(maxBytes) {
+      if (first !== void 0 && (maxBytes <= first.bytes.length || first.bytes.length === first.size)) {
+        const take = Math.min(maxBytes, first.bytes.length);
+        return { bytes: first.bytes.subarray(first.bytes.length - take), size: first.size };
+      }
+      const read = await blob.getTail(maxBytes);
+      first ??= read;
+      return read;
+    }
+  };
+}
+async function openRollbackTarget(storage, key, crypto) {
+  const blob = rememberingTail(storageBlobReader(storage, key));
+  await blob.getTail(DEFAULT_TAIL_BYTES);
+  const encrypted = await footerSaysEncrypted(blob);
+  if (encrypted !== (crypto !== void 0)) return { encrypted, reader: void 0 };
+  const reader = await CrbmReader.open(blob, { crypto });
+  if (reader.generation !== key.generation) {
+    throw new IntegrityError(
+      `segment "${key.segment}" generation ${key.generation}: its footer says generation ${reader.generation}`
+    );
+  }
+  return { encrypted, reader };
 }
 async function writeCrbmGenerationStream(driver, key, chunks, options = {}) {
   const chunkKeys = [];
   let cardinality = 0;
   const tick = yieldEvery(options.clock);
+  let identity;
   const { size, sha256 } = await driver.putImmutable(key, async (sink) => {
-    const writer = new CrbmWriter(sink, { generation: key.generation, crypto: options.crypto });
+    const writer = new CrbmWriter(sink, {
+      generation: key.generation,
+      crypto: options.crypto,
+      metadata: options.metadata
+    });
     for await (const { chunkKey, bitmap } of chunks) {
       if (bitmap.isEmpty) continue;
       bitmap.optimize?.();
@@ -3272,12 +4267,57 @@ async function writeCrbmGenerationStream(driver, key, chunks, options = {}) {
       if (pause !== null) await pause;
     }
     await writer.finish();
+    identity = writer.identity;
   });
-  return { size, sha256, chunkKeys, cardinality };
+  if (identity === void 0) {
+    throw new IntegrityError(
+      `the driver committed ${key.segment}.${key.generation} without writing it`
+    );
+  }
+  return {
+    size,
+    sha256,
+    chunkKeys,
+    cardinality,
+    fingerprint: fingerprintFor(identity.size, identity.footerCrc)
+  };
+}
+function refuseCleartextOntoKey(key, record, cleartext) {
+  if (cleartext !== true || record.wrappedDeks === void 0 || record.wrappedDeks.length === 0) {
+    return;
+  }
+  throw new KeyUnavailableError(
+    `segment "${key.segment}" is encrypted, and generation ${key.generation} was written in cleartext: another writer created the segment with a key while this one was writing. Nothing was published. Re-run the write with the keystore that holds the segment's key.`
+  );
 }
+var UNANSWERED_RESENDS = 3;
+var UNANSWERED_RESEND_BASE_MS = 500;
 async function publishGeneration(registry, key, options = {}) {
+  let fresh;
+  let failedOn;
+  let unanswered;
+  let resends = 0;
+  let sawUnanswered = false;
+  let lastRecord;
   for (let attempt = 0; attempt < 5; attempt++) {
-    const record = await registry.get(key);
+    const reused = attempt === 0 && options.row !== void 0;
+    const record = fresh !== void 0 ? fresh : reused ? options.row ?? null : await registry.get(key);
+    fresh = void 0;
+    unanswered = void 0;
+    lastRecord = record;
+    if (failedOn !== void 0) {
+      let landed;
+      try {
+        landed = await landedHere(record, failedOn, key, options.holdsOwnObject);
+      } catch (proofErr) {
+        throw outcomeUnknown(key, proofErr);
+      }
+      if (landed) return true;
+      if (record !== null && record.status === "active" && record.currentGen === key.generation) {
+        return false;
+      }
+      failedOn = void 0;
+    }
     try {
       if (options.expectFrom !== void 0 && record?.currentGen !== options.expectFrom) {
         return false;
@@ -3288,103 +4328,138 @@ async function publishGeneration(registry, key, options = {}) {
       if (options.expectToken !== void 0 && record?.token !== options.expectToken) {
         return false;
       }
+      if (record === null && options.summary !== void 0 && "sealed" in options.summary && options.wrappedDeks === void 0) {
+        if (reused) continue;
+        return false;
+      }
       if (record === null) {
         await registry.create(key, {
           currentGen: key.generation,
-          wrappedDeks: options.wrappedDeks
+          wrappedDeks: options.wrappedDeks,
+          ...options.summary === void 0 ? {} : { summary: options.summary }
         });
       } else if (record.status === "destroyed") {
         throw new ValidationError(
           `segment "${key.segment}" was destroyed (crypto-shredded) while generation ${key.generation} was being written \u2014 refusing to publish it; the written object is unreadable. Use a new segment.`
         );
       } else if (record.currentGen === null) {
+        refuseCleartextOntoKey(key, record, options.cleartext);
         await registry.compareAndSwap(key, record.token, {
           currentGen: key.generation,
-          ...options.wrappedDeks === void 0 ? {} : { wrappedDeks: options.wrappedDeks }
+          ...options.wrappedDeks === void 0 ? {} : { wrappedDeks: options.wrappedDeks },
+          ...options.summary === void 0 ? {} : { summary: options.summary }
         });
       } else if (record.currentGen > key.generation) {
         return false;
       } else if (record.currentGen === key.generation) {
+        if (reused) continue;
         return true;
       } else {
         if (options.wrappedDeks !== void 0 && options.wrappedDeks.length > 0) {
           throw new ValidationError(
-            `publishGeneration: refusing to publish generation ${key.generation} of "${key.segment}" with new key material onto a segment that already has generation ${record.currentGen} \u2014 its existing generations are not encrypted under this key. Encrypt a new segment and load into that instead.`
+            `publishGeneration: refusing to publish generation ${key.generation} of "${key.segment}" with new key material onto a segment that already has generation ${record.currentGen}: its generations are not encrypted under this key, and nothing was published. If another writer published to the segment while this one was writing, re-run the write, which then uses the segment's own key; if the segment's generations are cleartext, encrypt a new segment and load into that instead.`
           );
         }
-        await registry.compareAndSwap(key, record.token, { currentGen: key.generation });
+        refuseCleartextOntoKey(key, record, options.cleartext);
+        await registry.compareAndSwap(key, record.token, {
+          currentGen: key.generation,
+          ...options.summary === void 0 ? {} : { summary: options.summary }
+        });
       }
       return true;
     } catch (err) {
-      if (isWriteConflictError(err)) continue;
-      throw err;
+      if (isWriteConflictError(err)) {
+        failedOn = record;
+        continue;
+      }
+      if (!isTransientError(err)) throw err;
+      options.onUnanswered?.();
+      sawUnanswered = true;
+      let now;
+      try {
+        now = await registry.get(key);
+      } catch (readErr) {
+        if (isIntegrityError(readErr)) throw readErr;
+        throw outcomeUnknown(key, err);
+      }
+      if (sameRow(now, record)) {
+        const sleep = options.clock?.sleep;
+        if (sleep === void 0 || resends >= UNANSWERED_RESENDS) throw outcomeUnknown(key, err);
+        const bound = UNANSWERED_RESEND_BASE_MS * 2 ** resends;
+        resends += 1;
+        await sleep.call(options.clock, Math.floor((options.rng?.next() ?? 1) * bound));
+        unanswered = outcomeUnknown(key, err);
+        fresh = now;
+        continue;
+      }
+      failedOn = record;
+      fresh = now;
     }
   }
   const final = await registry.get(key);
-  if (final !== null && final.currentGen !== null && final.currentGen >= key.generation)
-    return final.currentGen === key.generation;
+  if (final !== null && final.currentGen !== null && final.currentGen >= key.generation) {
+    if (final.currentGen !== key.generation) return false;
+    if (!sawUnanswered) return true;
+    try {
+      return await landedHere(final, lastRecord ?? null, key, options.holdsOwnObject);
+    } catch (proofErr) {
+      throw outcomeUnknown(key, proofErr);
+    }
+  }
+  if (unanswered !== void 0) throw unanswered;
   throw new WriteConflictError(
     `publishGeneration: contention setting currentGen for ${key.segment}`
   );
 }
+async function landedHere(now, before, key, holdsOwnObject) {
+  if (now === null || now.status === "destroyed" || now.currentGen !== key.generation) return false;
+  if (before !== null && !sameIncarnation(before, now)) return false;
+  if (holdsOwnObject === void 0) {
+    throw new TransientError(
+      `publish of "${key.segment}" generation ${key.generation}: whether its registry write landed could not be settled, since the caller gave no way to tell its own object from another's. Its object is kept; re-run the write, which numbers past it.`
+    );
+  }
+  return holdsOwnObject();
+}
+function sameRow(a, b) {
+  return a === null ? b === null : b !== null && a.token === b.token;
+}
+function outcomeUnknown(key, cause) {
+  if (isTransientError(cause)) return cause;
+  return new TransientError(
+    `publish of "${key.segment}" generation ${key.generation}: whether its registry write landed could not be settled (${cause?.name ?? "error"} while checking its object). Its object is kept, since the write may still land; re-run the write, which numbers past it.`,
+    { cause }
+  );
+}
+async function provesOwnObject(storage, key, fingerprint) {
+  try {
+    return await CrbmReader.sameObject(storageBlobReader(storage, key), fingerprint);
+  } catch (err) {
+    if (isNotFoundError(err)) return false;
+    throw err;
+  }
+}
 async function bulkLoadCrbmGeneration(driver, key, ids, options = {}) {
   if (options.keystore === void 0 && options.requireEncryption === true) {
     throw new ValidationError("requireEncryption: a load needs a keystore to write encrypted");
   }
   const codec = requireCodec(options.codec, "bulkLoadCrbmGeneration");
-  const byChunk = /* @__PURE__ */ new Map();
-  const pendingByChunk = /* @__PURE__ */ new Map();
-  let pending = 0;
-  const tickChunk = yieldEvery(options.clock);
-  const tickId = yieldEvery(options.clock, YIELD_EVERY_IDS);
-  const flushPending = async () => {
-    for (const [chunkKey, rems] of pendingByChunk) {
-      if (rems.length === 0) continue;
-      const existingBitmap = byChunk.get(chunkKey);
-      if (existingBitmap === void 0) byChunk.set(chunkKey, codec.fromValues(rems));
-      else existingBitmap.addMany(rems);
-      rems.length = 0;
-      const pause = tickChunk();
-      if (pause !== null) await pause;
-    }
-    pending = 0;
-  };
-  const ingest = (id) => {
-    const { chunkKey, remainder } = splitId(id);
-    let bucket = pendingByChunk.get(chunkKey);
-    if (bucket === void 0) {
-      bucket = [];
-      pendingByChunk.set(chunkKey, bucket);
-    }
-    bucket.push(remainder);
-    return ++pending >= BULK_FLUSH_IDS;
-  };
-  if (Symbol.asyncIterator in ids) {
-    for await (const id of ids) {
-      if (ingest(id)) await flushPending();
-      const pause = tickId();
-      if (pause !== null) await pause;
-    }
+  let chunks;
+  if (ids instanceof DecodedLoadInput && ids.bitmap.encodeChunks !== void 0) {
+    const pause = yieldEvery(options.clock, 1);
+    await pause();
+    chunks = ids.bitmap.encodeChunks();
+    await pause();
   } else {
-    for (const id of ids) {
-      if (ingest(id)) await flushPending();
-      const pause = tickId();
-      if (pause !== null) await pause;
-    }
-  }
-  await flushPending();
-  let cardinality = 0;
-  const chunks = [];
-  for (const [chunkKey, bitmap] of byChunk) {
-    cardinality += bitmap.size;
-    chunks.push({ chunkKey, bitmap });
-    const pause = tickChunk();
-    if (pause !== null) await pause;
+    chunks = encodeEach(
+      await bucketIds(ids instanceof DecodedLoadInput ? ids.bitmap : ids, codec, options.clock)
+    );
   }
   if (options.keystore !== void 0 && options.registry === void 0) {
     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;
+  const passed = options.row;
+  const existing = passed !== void 0 && passed !== null && (passed.wrappedDeks === void 0 || passed.wrappedDeks.length === 0) ? passed : options.registry !== void 0 ? await options.registry.get(key) : null;
   if (existing?.status === "destroyed") {
     throw new ValidationError(
       `segment "${key.segment}" is destroyed (crypto-shredded) \u2014 refusing to write; use a new segment`
@@ -3413,13 +4488,25 @@ async function bulkLoadCrbmGeneration(driver, key, ids, options = {}) {
       crypto = { aead: minted.aead, aadFor: (scope) => aadFor(key, key.generation, scope) };
     }
   }
-  const { size, sha256 } = await writeCrbmGeneration(driver, key, chunks, {
-    crypto,
-    clock: options.clock
-  });
+  const { size, sha256, chunkCount, cardinality, fingerprint } = await writeEncodedChunks(
+    driver,
+    key,
+    chunks,
+    { crypto, clock: options.clock, metadata: options.metadata }
+  );
+  const summary = summaryOf(
+    key,
+    key.generation,
+    { cardinality, metadata: options.metadata },
+    crypto?.aead
+  );
   if (options.registry !== void 0 && options.publish !== false) {
     const becameCurrent = await publishGeneration(options.registry, key, {
-      wrappedDeks: newWrapped
+      wrappedDeks: newWrapped,
+      summary,
+      cleartext: crypto === void 0,
+      holdsOwnObject: () => provesOwnObject(driver, key, fingerprint),
+      clock: options.clock
     });
     if (becameCurrent) {
       safeAudit(options.audit ?? NOOP_AUDIT).onEvent({
@@ -3429,16 +4516,72 @@ async function bulkLoadCrbmGeneration(driver, key, ids, options = {}) {
         generation: key.generation
       });
     }
-    return {
-      size,
-      sha256,
-      chunkCount: chunks.length,
-      cardinality,
-      becameCurrent,
-      wrappedDeks: newWrapped
-    };
+    return {
+      size,
+      sha256,
+      chunkCount,
+      cardinality,
+      summary,
+      becameCurrent,
+      wrappedDeks: newWrapped,
+      encrypted: crypto !== void 0,
+      fingerprint
+    };
+  }
+  return {
+    size,
+    sha256,
+    chunkCount,
+    cardinality,
+    summary,
+    wrappedDeks: newWrapped,
+    encrypted: crypto !== void 0,
+    fingerprint
+  };
+}
+async function bucketIds(ids, codec, clock) {
+  const byChunk = /* @__PURE__ */ new Map();
+  const pendingByChunk = /* @__PURE__ */ new Map();
+  let pending = 0;
+  const tickChunk = yieldEvery(clock);
+  const tickId = yieldEvery(clock, YIELD_EVERY_IDS);
+  const flushPending = async () => {
+    for (const [chunkKey, rems] of pendingByChunk) {
+      if (rems.length === 0) continue;
+      const existingBitmap = byChunk.get(chunkKey);
+      if (existingBitmap === void 0) byChunk.set(chunkKey, codec.fromValues(rems));
+      else existingBitmap.addMany(rems);
+      rems.length = 0;
+      const pause = tickChunk();
+      if (pause !== null) await pause;
+    }
+    pending = 0;
+  };
+  const ingest = (id) => {
+    const { chunkKey, remainder } = splitId(id);
+    let bucket = pendingByChunk.get(chunkKey);
+    if (bucket === void 0) {
+      bucket = [];
+      pendingByChunk.set(chunkKey, bucket);
+    }
+    bucket.push(remainder);
+    return ++pending >= BULK_FLUSH_IDS;
+  };
+  if (Symbol.asyncIterator in ids) {
+    for await (const id of ids) {
+      if (ingest(id)) await flushPending();
+      const pause = tickId();
+      if (pause !== null) await pause;
+    }
+  } else {
+    for (const id of ids) {
+      if (ingest(id)) await flushPending();
+      const pause = tickId();
+      if (pause !== null) await pause;
+    }
   }
-  return { size, sha256, chunkCount: chunks.length, cardinality, wrappedDeks: newWrapped };
+  await flushPending();
+  return [...byChunk].map(([chunkKey, bitmap]) => ({ chunkKey, bitmap })).sort((a, b) => a.chunkKey - b.chunkKey);
 }
 function openGenerationReader(storage, key, crypto, options = {}) {
   return openChecked(storage, key, { ...options, crypto });
@@ -3467,6 +4610,11 @@ async function verifyGeneration(storage, key, expected, crypto) {
       `verify failed for ${key.segment}.${key.generation}: cardinality ${reader.count()} != ${expected.cardinality}`
     );
   }
+  if (!summaryAgrees(expected, { cardinality: reader.count(), metadata: reader.metadata })) {
+    throw new IntegrityError(
+      `verify failed for ${key.segment}.${key.generation}: the object's metadata is not the metadata it was written with`
+    );
+  }
 }
 
 // src/core/pinned-storage-source.ts
@@ -3515,6 +4663,11 @@ var PinnedStorageChunkSource = class {
     if (pin === void 0) return this.inner.cardinalities(ref);
     return pin.generation === null ? Promise.resolve(null) : this.inner.cardinalitiesAt(ref, pin.generation, heldBy(pin));
   }
+  summary(ref) {
+    const pin = this.pinFor(ref);
+    if (pin === void 0) return this.inner.summary(ref);
+    return pin.generation === null ? Promise.resolve(null) : this.inner.summaryAt(ref, pin.generation, heldBy(pin));
+  }
   currentGeneration(ref) {
     const pin = this.pinFor(ref);
     return pin === void 0 ? this.inner.currentGeneration(ref) : Promise.resolve(pin.generation);
@@ -3551,67 +4704,58 @@ var PinnedStorageChunkSource = class {
   }
 };
 
-// src/core/generation-gc.ts
-async function nextGeneration(ref, deps) {
-  const record = await deps.registry.get(ref);
-  let highest = record?.currentGen ?? -1;
-  for await (const key of deps.storage.list(ref)) {
-    if (key.generation > highest) highest = key.generation;
-  }
-  return highest + 1;
+// src/core/retry.ts
+var DEFAULT_RETRY_POLICY = {
+  maxAttempts: 4,
+  baseDelayMs: 50,
+  maxDelayMs: 2e3,
+  backoffFactor: 2,
+  jitter: "full"
+};
+function backoffDelayMs(policy, attempt) {
+  const raw = policy.baseDelayMs * policy.backoffFactor ** (attempt - 1);
+  return Math.min(policy.maxDelayMs, raw);
 }
-async function gcOrphanGenerations(ref, deps, options = {}) {
-  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;
-  const seen = /* @__PURE__ */ new Set();
-  for await (const key of deps.storage.list(ref)) seen.add(key.generation);
-  const gens = [...seen];
-  const after = await deps.registry.get(ref);
-  if (after === null)
-    throw new WriteConflictError(`registry row for segment ${ref.segment} was purged mid-pass`);
-  if (record.status === "destroyed" && after.token !== record.token) {
-    throw new WriteConflictError(
-      `segment ${ref.segment} changed incarnation while its generations were being listed`
+function applyJitter(policy, delayMs, rng) {
+  if (policy.jitter === "none") return delayMs;
+  return rng.next() * delayMs;
+}
+function retryRead(op, retry) {
+  return retry === void 0 ? op() : withRetry(op, retry.policy ?? DEFAULT_RETRY_POLICY, retry);
+}
+async function withRetry(op, policy, deps) {
+  const retryable = deps.isRetryable ?? isTransientError;
+  if (!Number.isFinite(policy.maxAttempts) || policy.maxAttempts < 1) {
+    throw new ValidationError(
+      `retry.maxAttempts must be a finite number >= 1 (got ${String(policy.maxAttempts)})`
     );
   }
-  const cutoff = current === null || after.currentGen === null ? null : Math.min(current, after.currentGen);
-  const stillCollectable = async () => {
-    const still = await deps.registry.get(ref);
-    if (still === null) {
-      throw new WriteConflictError(`registry row for segment ${ref.segment} was purged mid-pass`);
-    }
-    const ok = record.status === "destroyed" ? still.token === after.token : cutoff === null || still.currentGen !== null && still.currentGen >= cutoff;
-    if (!ok) {
-      throw new WriteConflictError(
-        `segment ${ref.segment} changed incarnation while its generations were being collected`
-      );
+  const attempts = Math.floor(policy.maxAttempts);
+  let lastErr;
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    try {
+      return await op();
+    } catch (err) {
+      lastErr = err;
+      if (attempt >= attempts || !retryable(err)) throw err;
+      const delayMs = applyJitter(policy, backoffDelayMs(policy, attempt), deps.rng);
+      try {
+        deps.onRetry?.({ attempt, delayMs, err });
+      } catch {
+      }
+      await deps.clock.sleep(delayMs);
     }
-  };
-  const toDelete = record.status === "destroyed" ? gens.sort((a, b) => a - b) : cutoff === null ? (
-    // No Storage pointer yet, so "below current" selects nothing and there is nothing safe to infer: an object
-    // here is either a load about to publish or an orphan we cannot tell apart from it. Deleting would race
-    // that publish into a dangling pointer. It is collected once a pointer exists.
-    []
-  ) : (
-    // Delete generations below the cutoff, except the newest `keep` of them (the grace window).
-    gens.filter((g) => g < cutoff).sort((a, b) => b - a).slice(keep)
-  );
-  for (const generation of toDelete) {
-    await stillCollectable();
-    await deps.storage.delete({ namespace: ref.namespace, segment: ref.segment, generation });
   }
-  return toDelete;
+  throw lastErr;
 }
 
 // src/core/load.ts
 async function currentCardinality(ref, deps, record) {
-  if (record === null || record.currentGen === null || record.status === "destroyed") return null;
+  if (record === null || record.currentGen === null || record.status === "destroyed") {
+    return { cardinality: null, fromSummary: false };
+  }
   const generation = record.currentGen;
+  let aead;
   let crypto;
   const wrapped = record.wrappedDeks;
   if (wrapped !== void 0 && wrapped.length > 0) {
@@ -3620,23 +4764,29 @@ async function currentCardinality(ref, deps, record) {
         `segment "${ref.segment}" is encrypted but load was given no keystore`
       );
     }
-    const aead = await deps.keystore.openDek(wrapped);
-    crypto = { aead, aadFor: (scope) => aadFor(ref, generation, scope) };
+    aead = await deps.keystore.openDek(wrapped);
+    const opened = aead;
+    crypto = { aead: opened, aadFor: (scope) => aadFor(ref, generation, scope) };
   }
+  const described = usableSummary(ref, record, aead);
+  if (described !== void 0) return { cardinality: described.cardinality, fromSummary: true };
   let reader;
   try {
-    reader = await openGenerationReader(deps.storage, { ...ref, generation }, crypto);
+    reader = await retryRead(
+      () => openGenerationReader(deps.storage, { ...ref, generation }, crypto),
+      deps.readRetry
+    );
   } catch (err) {
     if (!isNotFoundError(err)) throw err;
-    return null;
+    return { cardinality: null, fromSummary: false };
   }
   let total = 0;
   for (const n of reader.cardinalities().values()) total += n;
-  return total;
+  return { cardinality: total, fromSummary: false };
 }
-async function loadSegment(ref, ids, deps, options = {}) {
+async function loadSegment(ref, input, deps, options = {}) {
   validateUserRef(ref);
-  requireCodec(deps.codec, "loadSegment");
+  const codec = 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)}`);
@@ -3656,13 +4806,19 @@ async function loadSegment(ref, ids, deps, options = {}) {
       throw new ValidationError(`guard.minRetained must be a fraction in 0..1; got ${String(s)}`);
     }
   }
+  const metadata = copiedMetadata(options.metadata, (message) => {
+    throw new ValidationError(message);
+  });
   const audit = safeAudit(options.audit ?? NOOP_AUDIT);
+  const ids = prepareLoadInput(input, codec);
+  assertRegistryCanWrite(deps.registry, "load");
   const row = await deps.registry.get(ref);
   const fromToken = row?.token;
   const fromGeneration = row?.currentGen ?? void 0;
   const needsBefore = guard?.minRetained !== void 0 || options.allowEmpty !== true;
-  const before = needsBefore ? await currentCardinality(ref, deps, row) : null;
-  const generation = await nextGeneration(ref, deps);
+  const current = needsBefore ? await currentCardinality(ref, deps, row) : { cardinality: null, fromSummary: false };
+  const before = current.cardinality;
+  const { generation, checked } = await nextLoadGeneration(ref, deps, row);
   const key = { namespace: ref.namespace, segment: ref.segment, generation };
   let written;
   try {
@@ -3672,7 +4828,9 @@ async function loadSegment(ref, ids, deps, options = {}) {
       keystore: deps.keystore,
       requireEncryption: deps.requireEncryption,
       codec: deps.codec,
-      clock: deps.clock
+      clock: deps.clock,
+      metadata,
+      row
     });
   } catch (err) {
     if (!isWriteConflictError(err)) throw err;
@@ -3696,16 +4854,28 @@ async function loadSegment(ref, ids, deps, options = {}) {
       collected: []
     };
   }
-  const refuse = async (reason) => {
+  const reclaim = async () => {
     const now = await deps.registry.get(ref);
-    if (now === null || now.token === fromToken) await deps.storage.delete(key);
+    if (now !== null && (now.token === fromToken || now.status === "destroyed")) {
+      await deps.storage.delete(key);
+      return;
+    }
+    const keyed = now !== null && now.wrappedDeks !== void 0 && now.wrappedDeks.length > 0;
+    if ((now === null || keyed && !written.encrypted) && await holdsObject(deps.storage, key, written.fingerprint)) {
+      await deps.storage.delete(key);
+    }
+  };
+  let unanswered = false;
+  const refuse = async (reason) => {
+    await reclaim();
     audit.onEvent({
       kind: "segment.load-refused",
       segment: ref.segment,
       namespace: ref.namespace,
       generation,
       reason,
-      cardinality: written.cardinality
+      cardinality: written.cardinality,
+      ...unanswered ? { unanswered: true } : {}
     });
     return {
       generation,
@@ -3728,19 +4898,37 @@ async function loadSegment(ref, ids, deps, options = {}) {
   if (guard?.minRetained !== void 0 && before !== null) {
     if (written.cardinality < before * guard.minRetained) return refuse("min-retained");
   }
-  const published = await publishGeneration(deps.registry, key, {
-    wrappedDeks: written.wrappedDeks,
-    ...fromToken === void 0 ? {} : { expectToken: fromToken },
-    ...needsBefore && fromGeneration !== void 0 ? { expectFrom: fromGeneration } : {},
-    // The third case, and the one the two fences above structurally cannot cover: the guard judged a segment
-    // that had NO ROW. Both `expectFrom` and `expectToken` compare against a value read from a row, so with no
-    // row both are omitted and the publish becomes a bare forward-only advance — which lands over anything
-    // that appeared in between. `before` was `null`, so the empty and `minRetained` bounds had nothing to
-    // judge and passed vacuously. Verified: an empty generation published over a thousand ids that a
-    // concurrent writer had created meanwhile, reporting success. A guarded write therefore has to fence on
-    // the ABSENCE it relied on, exactly as it fences on the pointer it relied on.
-    ...needsBefore && row === null ? { expectAbsent: true } : {}
-  });
+  let published;
+  try {
+    published = await publishGeneration(deps.registry, key, {
+      row,
+      wrappedDeks: written.wrappedDeks,
+      summary: written.summary,
+      cleartext: !written.encrypted,
+      ...fromToken === void 0 ? {} : { expectToken: fromToken },
+      ...needsBefore && fromGeneration !== void 0 ? { expectFrom: fromGeneration } : {},
+      // The third case, and the one the two fences above structurally cannot cover: the guard judged a segment
+      // that had NO ROW. Both `expectFrom` and `expectToken` compare against a value read from a row, so with no
+      // row both are omitted and the publish becomes a bare forward-only advance — which lands over anything
+      // that appeared in between. `before` was `null`, so the empty and `minRetained` bounds had nothing to
+      // judge and passed vacuously. Verified: an empty generation published over a thousand ids that a
+      // concurrent writer had created meanwhile, reporting success. A guarded write therefore has to fence on
+      // the ABSENCE it relied on, exactly as it fences on the pointer it relied on.
+      ...needsBefore && row === null ? { expectAbsent: true } : {},
+      // A registry write that fails without an answer is reconciled by reading the row: the pointer at this number
+      // is this load's publish only over the object this load wrote, which one footer read proves.
+      holdsOwnObject: () => provesOwnObject(deps.storage, key, written.fingerprint),
+      // And the wait before a fresh write, when the first left the row as it was.
+      clock: deps.clock,
+      rng: deps.rng ?? deps.readRetry?.rng,
+      onUnanswered: () => {
+        unanswered = true;
+      }
+    });
+  } catch (err) {
+    if (isValidationError(err) || err instanceof KeyUnavailableError) await reclaim();
+    throw err;
+  }
   if (!published) return refuse("superseded");
   audit.onEvent({
     kind: "segment.publish",
@@ -3748,7 +4936,13 @@ async function loadSegment(ref, ids, deps, options = {}) {
     namespace: ref.namespace,
     generation
   });
-  const collected = await gcOrphanGenerations(ref, deps, { keep });
+  const currentObjectGone = needsBefore && before === null;
+  const collected = await collectAfterLoad(ref, deps, {
+    generation,
+    keep,
+    byName: checked && !currentObjectGone && deps.collectByListing !== true,
+    ...current.fromSummary && fromGeneration !== void 0 ? { proveCurrent: { ...ref, generation: fromGeneration } } : {}
+  });
   return {
     generation,
     published: true,
@@ -3768,7 +4962,25 @@ async function listGenerations(ref, deps) {
   const current = record?.currentGen ?? null;
   const seen = /* @__PURE__ */ new Set();
   for await (const key of deps.storage.list(ref)) seen.add(key.generation);
-  return [...seen].sort((a, b) => a - b).map((generation) => ({ generation, current: generation === current }));
+  const described = record === null ? void 0 : await currentDescription(ref, record, deps);
+  return [...seen].sort((a, b) => a - b).map(
+    (generation) => generation === current ? { generation, current: true, ...described } : { generation, current: false }
+  );
+}
+async function currentDescription(ref, record, deps) {
+  if (record.summary === void 0) return void 0;
+  let aead;
+  if ("sealed" in record.summary && record.wrappedDeks !== void 0 && deps.keystore !== void 0) {
+    try {
+      aead = await deps.keystore.openDek(record.wrappedDeks);
+    } catch {
+      return void 0;
+    }
+  }
+  const usable = usableSummary(ref, record, aead);
+  if (usable === void 0) return void 0;
+  const metadata = usable.metadata;
+  return metadata === void 0 || Object.keys(metadata).length === 0 ? { cardinality: usable.cardinality } : { cardinality: usable.cardinality, metadata: Object.freeze({ ...metadata }) };
 }
 async function rollbackSegment(ref, toGeneration, deps, options = {}) {
   validateUserRef(ref);
@@ -3802,8 +5014,34 @@ async function rollbackSegment(ref, toGeneration, deps, options = {}) {
       `rollback: generation ${toGeneration} of "${ref.segment}" is above the current pointer (${record.currentGen}) \u2014 it may never have been published. Pass { allowForward: true } if you are undoing an earlier rollback.`
     );
   }
+  const keyed = record.wrappedDeks !== void 0 && record.wrappedDeks.length > 0;
+  let aead;
+  if (keyed && deps.keystore !== void 0) {
+    try {
+      aead = await deps.keystore.openDek(record.wrappedDeks);
+    } catch {
+    }
+  }
+  const crypto = aead === void 0 ? void 0 : { aead, aadFor: (scope) => aadFor(ref, toGeneration, scope) };
+  const { encrypted, reader } = await openRollbackTarget(
+    deps.storage,
+    { ...ref, generation: toGeneration },
+    crypto
+  );
+  if (encrypted !== keyed) {
+    throw new IntegrityError(
+      `rollback: generation ${toGeneration} of "${ref.segment}" is ${encrypted ? "encrypted" : "cleartext"}, but the segment is ${keyed ? "encrypted" : "cleartext"}, so no read of the segment could use it; it was never one of its generations. Roll back to another generation.`
+    );
+  }
+  const summary = reader === void 0 ? void 0 : summaryOf(
+    ref,
+    toGeneration,
+    { cardinality: reader.count(), metadata: reader.metadata },
+    aead
+  );
   const { token } = await deps.registry.compareAndSwap(ref, record.token, {
-    currentGen: toGeneration
+    currentGen: toGeneration,
+    summary
   });
   let stillThere = false;
   for await (const key of deps.storage.list(ref)) {
@@ -3812,15 +5050,31 @@ async function rollbackSegment(ref, toGeneration, deps, options = {}) {
       break;
     }
   }
-  if (!stillThere) {
+  let replaced = false;
+  if (stillThere && reader !== void 0 && toGeneration > (record.currentGen ?? -1)) {
+    try {
+      replaced = !await provesOwnObject(
+        deps.storage,
+        { ...ref, generation: toGeneration },
+        reader.fingerprint
+      );
+    } catch (err) {
+      if (!isIntegrityError(err)) throw err;
+      replaced = true;
+    }
+  }
+  if (!stillThere || replaced) {
     let undone = false;
     try {
-      await deps.registry.compareAndSwap(ref, token, { currentGen: record.currentGen });
+      await deps.registry.compareAndSwap(ref, token, {
+        currentGen: record.currentGen,
+        summary: describingSummary(record)
+      });
       undone = true;
     } 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 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.`)
+      `rollback: generation ${toGeneration} of "${ref.segment}" was ${replaced ? "replaced" : "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({
@@ -3832,6 +5086,12 @@ async function rollbackSegment(ref, toGeneration, deps, options = {}) {
   });
   return { fromGeneration: record.currentGen, generation: toGeneration };
 }
+function describingSummary(record) {
+  const { summary } = record;
+  if (summary === void 0 || summary.generation !== record.currentGen) return void 0;
+  const keyed = record.wrappedDeks !== void 0 && record.wrappedDeks.length > 0;
+  return "sealed" in summary === keyed ? summary : void 0;
+}
 
 // src/core/erase-id.ts
 var DEFAULT_MAX_BITMAP_BYTES2 = 1 << 20;
@@ -3841,6 +5101,7 @@ async function eraseIdFromSegment(ref, id, deps, options = {}) {
   const codec = requireCodec(deps.codec, "eraseIdFromSegment");
   const maxBytes = deps.maxBitmapBytes ?? DEFAULT_MAX_BITMAP_BYTES2;
   const base = { segment: ref.segment, namespace: ref.namespace };
+  const read = (op) => retryRead(op, deps.readRetry);
   const record = await deps.registry.get(ref);
   if (record === null) return { ...base, erased: false, reason: "absent", collected: [] };
   if (record.status === "destroyed")
@@ -3877,13 +5138,18 @@ async function eraseIdFromSegment(ref, id, deps, options = {}) {
     return row.currentGen === from && row.token === fromToken ? null : "superseded";
   };
   const holds = async (generation2) => {
+    const key2 = { ...base, generation: generation2 };
+    const chunkIn = (crypto) => read(async () => (await openGenerationReader(deps.storage, key2, crypto)).getChunk(chunkKey));
     try {
-      const reader = await openGenerationReader(
-        deps.storage,
-        { ...base, generation: generation2 },
-        cryptoAt(generation2)
-      );
-      const bytes = await reader.getChunk(chunkKey);
+      let bytes;
+      try {
+        bytes = await chunkIn(cryptoAt(generation2));
+      } catch (err) {
+        if (!isIntegrityError(err) || cryptoAt(generation2) === void 0 || await read(() => objectIsEncrypted(deps.storage, key2))) {
+          throw err;
+        }
+        bytes = await chunkIn(void 0);
+      }
       return bytes !== null && codec.safeDeserialize(bytes, maxBytes).has(remainder);
     } catch (err) {
       if (isNotFoundError(err)) return null;
@@ -3953,27 +5219,40 @@ async function eraseIdFromSegment(ref, id, deps, options = {}) {
   const stage = async () => {
     let written;
     try {
-      const reader = await openGenerationReader(deps.storage, fromKey, cryptoAt(from));
-      const bytes = await reader.getChunk(chunkKey);
+      const reader = await read(() => openGenerationReader(deps.storage, fromKey, cryptoAt(from)));
+      const bytes = await read(() => reader.getChunk(chunkKey));
       if (bytes === null) return await notInCurrent();
       const target = codec.safeDeserialize(bytes, maxBytes);
       assertRemaindersInRange(target, chunkKey);
       if (!target.has(remainder)) return await notInCurrent();
       target.remove(remainder);
+      assertRegistryCanWrite(deps.registry, "eraseIdFromSegment");
       const generation2 = await nextGeneration(ref, deps);
       const key2 = { ...base, generation: generation2 };
+      const metadata = metadataToCarry(
+        reader.metadata,
+        aead === void 0 ? void 0 : usableSummary(ref, record, aead)
+      );
       const tally = await writeCrbmGenerationStream(
         deps.storage,
         key2,
-        rewrite(reader, chunkKey, target, codec, maxBytes),
-        { crypto: cryptoAt(generation2), clock: deps.clock }
+        rewrite(reader, chunkKey, target, codec, maxBytes, read),
+        { crypto: cryptoAt(generation2), clock: deps.clock, metadata }
       );
       written = generation2;
       const beforeVerify = await deps.registry.get(ref);
       const early = rowVerdict(beforeVerify);
       if (early !== null) return refused(early, written);
-      await verifyGeneration(deps.storage, key2, tally, cryptoAt(generation2));
-      return { generation: generation2, key: key2 };
+      await read(
+        () => verifyGeneration(deps.storage, key2, { ...tally, metadata }, cryptoAt(generation2))
+      );
+      const summary2 = summaryOf(
+        ref,
+        generation2,
+        { cardinality: tally.cardinality, metadata },
+        aead
+      );
+      return { generation: generation2, key: key2, fingerprint: tally.fingerprint, summary: summary2 };
     } catch (err) {
       if (!isNotFoundError(err)) throw err;
       let now;
@@ -3998,10 +5277,16 @@ async function eraseIdFromSegment(ref, id, deps, options = {}) {
     if (!staged.erased && staged.generation !== void 0) await discardRefused(staged.generation);
     return staged;
   }
-  const { generation, key } = staged;
+  const { generation, key, fingerprint, summary } = staged;
   const published = await publishGeneration(deps.registry, key, {
     expectFrom: from,
-    expectToken: fromToken
+    expectToken: fromToken,
+    summary,
+    // A write that ends without an answer is settled by reading the row, and a pointer at this number is this
+    // rewrite's only over the object it wrote: the footer proves it, so another incarnation's cannot pass for it.
+    holdsOwnObject: () => provesOwnObject(deps.storage, key, fingerprint),
+    clock: deps.clock,
+    rng: deps.rng ?? deps.readRetry?.rng
   });
   if (!published) {
     await discardRefused(generation);
@@ -4026,14 +5311,14 @@ async function eraseIdFromSegment(ref, id, deps, options = {}) {
   if (left !== void 0) throw cannotRemove(left);
   return { ...base, erased: true, fromGeneration: from, generation, collected };
 }
-async function* rewrite(reader, chunkKey, replacement, codec, maxBytes) {
+async function* rewrite(reader, chunkKey, replacement, codec, maxBytes, read) {
   const keys = [...reader.chunkKeys()].sort((a, b) => a - b);
   for (const k of keys) {
     if (k === chunkKey) {
       yield { chunkKey: k, bitmap: replacement };
       continue;
     }
-    const bytes = await reader.getChunk(k);
+    const bytes = await read(() => reader.getChunk(k));
     if (bytes === null) continue;
     const bitmap = codec.safeDeserialize(bytes, maxBytes);
     assertRemaindersInRange(bitmap, k);
@@ -4052,8 +5337,8 @@ function assertRemaindersInRange(bitmap, chunkKey) {
 // src/drivers/crypto.ts
 import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
 var KEY_BYTES = 32;
-var NONCE_BYTES = 12;
-var TAG_BYTES = 16;
+var NONCE_BYTES2 = 12;
+var TAG_BYTES2 = 16;
 var NodeAead = class {
   key;
   constructor(key) {
@@ -4062,14 +5347,14 @@ var NodeAead = class {
     this.key = Buffer.from(key);
   }
   seal(plaintext, aad) {
-    const nonce = randomBytes(NONCE_BYTES);
+    const nonce = randomBytes(NONCE_BYTES2);
     const cipher = createCipheriv("aes-256-gcm", this.key, nonce);
     cipher.setAAD(aad);
     const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
     return { nonce, ciphertext, tag: cipher.getAuthTag() };
   }
   open(sealed, aad) {
-    if (sealed.nonce.length !== NONCE_BYTES || sealed.tag.length !== TAG_BYTES)
+    if (sealed.nonce.length !== NONCE_BYTES2 || sealed.tag.length !== TAG_BYTES2)
       throw new IntegrityError("AEAD nonce/tag have the wrong length");
     const decipher = createDecipheriv("aes-256-gcm", this.key, sealed.nonce);
     decipher.setAAD(aad);
@@ -4089,11 +5374,11 @@ function wrapKey(dek, kek, keyId) {
 }
 function unwrapKey(wrapped, kek, keyId) {
   const blob = Buffer.from(wrapped, "base64");
-  if (blob.length < NONCE_BYTES + TAG_BYTES)
+  if (blob.length < NONCE_BYTES2 + TAG_BYTES2)
     throw new IntegrityError("wrapped DEK is too short to be valid");
-  const nonce = blob.subarray(0, NONCE_BYTES);
-  const tag = blob.subarray(blob.length - TAG_BYTES);
-  const ciphertext = blob.subarray(NONCE_BYTES, blob.length - TAG_BYTES);
+  const nonce = blob.subarray(0, NONCE_BYTES2);
+  const tag = blob.subarray(blob.length - TAG_BYTES2);
+  const ciphertext = blob.subarray(NONCE_BYTES2, blob.length - TAG_BYTES2);
   return new NodeAead(kek).open({ nonce, ciphertext, tag }, new TextEncoder().encode(keyId));
 }
 var InProcessKeystore = class {
@@ -4334,7 +5619,10 @@ async function shredSegment(ref, deps, allowCleartext, op = "destroySegment") {
         status: "destroyed",
         wrappedDeks: void 0,
         // ← the crypto-shred: the only copy of the DEK wrappings is gone
-        keyId: void 0
+        keyId: void 0,
+        // The current generation's cached count and metadata go with it: sealed, they cannot be opened without
+        // the wrappings; clear, they would outlive the segment on its tombstone.
+        summary: void 0
       });
       return { ...base, destroyed: true, cryptoShredded: encrypted };
     } catch (err) {
@@ -4473,39 +5761,108 @@ function assertNotDestroyed(record, ref) {
 
 // src/core/retention-sweep.ts
 var DEFAULT_RETIRE_LIMIT = 100;
+var MAX_CONSECUTIVE_PURGE_FAULTS = 3;
 var DEFAULT_TOMBSTONE_GRACE_MS = 864e5;
 var DEFAULT_LOOKBACK_BUCKETS = 7;
 async function rowsFromDueIndex(registry, options) {
   const rows = [];
-  const seen = /* @__PURE__ */ new Set();
+  const pointers = /* @__PURE__ */ new Map();
+  const litter = [];
+  const gone = /* @__PURE__ */ new Set();
   for (const bucket of dueBucketsAt(options.now, options.lookbackBuckets)) {
     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;
-      seen.add(key);
+      const found = {
+        ref: { namespace: pointer.namespace, segment: pointer.segment },
+        target: ref,
+        token: pointer.token
+      };
+      const key = segmentKey(ref);
+      const known = pointers.get(key);
+      if (known !== void 0) {
+        known.push(found);
+        continue;
+      }
+      if (gone.has(key)) {
+        litter.push(found);
+        continue;
+      }
       if (rows.length >= options.maxScanSegments) {
         throw new BudgetExceededError(
           `retireExpired: the due index yielded more than ${options.maxScanSegments} segments \u2014 the scan was abandoned there rather than completed. Raise \`maxScanSegments\`, narrow with \`namespace\`, or reduce \`lookbackBuckets\`.`
         );
       }
       const live = await registry.get(ref);
-      if (live === null) continue;
+      if (live === null) {
+        gone.add(key);
+        litter.push(found);
+        continue;
+      }
       rows.push(live);
+      pointers.set(key, [found]);
     }
   }
-  return rows;
+  return { rows, pointers, litter };
+}
+async function rowsFromFleet(registry, options) {
+  const held = [];
+  const rows = await drainRegistry(registry, {
+    namespace: options.namespace,
+    maxScanSegments: options.maxScanSegments,
+    op: "retireExpired",
+    onReserved: (pointer) => {
+      if (held.length >= options.maxScanSegments) return;
+      const target = decodeDueName(pointer.segment);
+      if (target === null || isReservedNamespace(target.namespace)) return;
+      held.push({
+        ref: { namespace: pointer.namespace, segment: pointer.segment },
+        target,
+        token: pointer.token
+      });
+    }
+  });
+  const pointers = /* @__PURE__ */ new Map();
+  const litter = [];
+  if (held.length === 0) return { rows, pointers, litter };
+  const present = new Set(rows.map((rec) => segmentKey(rec)));
+  for (const found of held) {
+    const key = segmentKey(found.target);
+    if (!present.has(key)) litter.push(found);
+    else if (pointers.has(key)) pointers.get(key).push(found);
+    else pointers.set(key, [found]);
+  }
+  return { rows, pointers, litter };
 }
-async function forgetDuePointer(registry, ref, expiresAt) {
+async function forgetDuePointer(registry, ref, expiresAt, onFault) {
   if (!canIndex(ref)) return;
   try {
     await registry.delete(dueIndexRef(dueBucket(expiresAt), ref));
+  } catch (err) {
+    onFault(err);
+  }
+}
+async function filePurgePointer(registry, ref, purgeAt) {
+  if (!canIndex(ref)) return;
+  try {
+    await registry.create(dueIndexRef(dueBucket(purgeAt), ref), { currentGen: null });
   } catch {
   }
 }
+async function forgetPurgePointers(registry, ref, purgeAt, found, onFault) {
+  if (!canIndex(ref)) return;
+  const filed = dueIndexRef(dueBucket(purgeAt), ref);
+  const all = found.some((p) => p.ref.namespace === filed.namespace) ? found : [...found, { ref: filed, target: ref }];
+  for (const pointer of all) {
+    try {
+      await registry.delete(pointer.ref, pointer.token);
+    } catch (err) {
+      onFault(err);
+    }
+  }
+}
 async function retireExpired(deps, options) {
   if (options.namespace !== void 0) validateUserNamespace(options.namespace);
   const now = options.now;
@@ -4538,32 +5895,40 @@ async function retireExpired(deps, options) {
   }
   const dryRun = options.dryRun === true;
   const scan = options.scan ?? "fleet";
-  const rows = scan === "index" ? await rowsFromDueIndex(deps.registry, {
+  const scanned = scan === "index" ? await rowsFromDueIndex(deps.registry, {
     now,
     lookbackBuckets: options.lookbackBuckets ?? DEFAULT_LOOKBACK_BUCKETS,
     namespace: options.namespace,
     maxScanSegments
-  }) : await drainRegistry(deps.registry, {
-    namespace: options.namespace,
-    maxScanSegments,
-    op: "retireExpired"
-  });
+  }) : await rowsFromFleet(deps.registry, { namespace: options.namespace, maxScanSegments });
+  const rows = scanned.rows;
+  const removesRows = deps.registry.capabilities().conditionalDelete === true;
   const shards = options.shards;
   const totalShards = options.totalShards ?? 0;
-  const mine = shards === void 0 || totalShards <= 1 ? rows : rows.filter((r) => shards.includes(shardOf(segmentKey(r), totalShards)));
+  const owned = (ref) => shards === void 0 || totalShards <= 1 || shards.includes(shardOf(segmentKey(ref), totalShards));
+  const mine = rows.filter(owned);
   const entries = [];
   let eligible = 0;
   let retired = 0;
   let wouldRetire = 0;
   let tombstonesPurged = 0;
   let limited = false;
+  let purgeFaults = 0;
+  let firstPurgeFault;
+  const noteFault = (err) => {
+    if (isWriteConflictError(err)) return;
+    purgeFaults += 1;
+    firstPurgeFault ??= failureReason(err);
+  };
+  let purgeRun = 0;
+  let purging = true;
   let attempted = 0;
   for (const rec of mine) {
     const ref = { namespace: rec.namespace, segment: rec.segment };
     const base = { segment: rec.segment, namespace: rec.namespace };
     const policy = readRetentionPolicy(rec.retention);
     if (rec.status === "destroyed") {
-      if (!purgeTombstones) continue;
+      if (!purgeTombstones || !purging) continue;
       const retiredAt = retirementStamp(rec.retention);
       if (retiredAt === null) continue;
       if (now - retiredAt < grace) continue;
@@ -4580,13 +5945,31 @@ async function retireExpired(deps, options) {
             continue;
           }
         }
-        if (!dryRun) await deps.registry.delete(ref, rec.token);
-        if (!dryRun) tombstonesPurged += 1;
+        if (!dryRun) {
+          await deps.registry.delete(ref, rec.token);
+          tombstonesPurged += 1;
+          purgeRun = 0;
+          if (removesRows) {
+            await forgetPurgePointers(
+              deps.registry,
+              ref,
+              retiredAt + grace,
+              scanned.pointers.get(segmentKey(ref)) ?? [],
+              noteFault
+            );
+          }
+        }
         entries.push({
           ...base,
           action: dryRun ? "would-purge-tombstone" : "purged-tombstone"
         });
       } catch (err) {
+        if (!isWriteConflictError(err)) {
+          attempted -= 1;
+          purgeRun += 1;
+          if (purgeRun >= MAX_CONSECUTIVE_PURGE_FAULTS) purging = false;
+          noteFault(err);
+        }
         entries.push({ ...base, action: "skipped", reason: failureReason(err) });
       }
       continue;
@@ -4630,22 +6013,27 @@ async function retireExpired(deps, options) {
       }
       retired += 1;
       entries.push({ ...base, action: "retired", expiresAt: livePolicy.expiresAt, result });
-      await forgetDuePointer(deps.registry, ref, livePolicy.expiresAt);
+      await forgetDuePointer(deps.registry, ref, livePolicy.expiresAt, noteFault);
       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
+            (err) => {
+              noteFault(err);
+              return false;
+            }
           );
           if (deleted) continue;
         }
       }
-      await stampRetirement(deps.registry, ref, now).catch(() => void 0);
+      const stamped = await stampRetirement(deps.registry, ref, now).catch(() => false);
+      if (stamped && removesRows) await filePurgePointer(deps.registry, ref, now + grace);
     } catch (err) {
       const after = await deps.registry.get(ref).catch(() => null);
       if (after?.status === "destroyed") {
-        await stampRetirement(deps.registry, ref, now).catch(() => void 0);
+        const stamped = await stampRetirement(deps.registry, ref, now).catch(() => false);
+        if (stamped && removesRows) await filePurgePointer(deps.registry, ref, now + grace);
         retired += 1;
         entries.push({
           ...base,
@@ -4666,6 +6054,20 @@ async function retireExpired(deps, options) {
       entries.push({ ...base, action: "skipped", reason: failureReason(err) });
     }
   }
+  if (!dryRun && removesRows) {
+    let attemptedLitter = 0;
+    for (const pointer of scanned.litter) {
+      if (!owned(pointer.target)) continue;
+      if (attemptedLitter >= limit) break;
+      attemptedLitter += 1;
+      try {
+        if (await deps.registry.get(pointer.target) !== null) continue;
+        await deps.registry.delete(pointer.ref, pointer.token);
+      } catch (err) {
+        noteFault(err);
+      }
+    }
+  }
   return {
     scanned: mine.length,
     eligible,
@@ -4673,6 +6075,8 @@ async function retireExpired(deps, options) {
     wouldRetire,
     tombstonesPurged,
     limited,
+    purgeFaults,
+    ...firstPurgeFault === void 0 ? {} : { firstPurgeFault },
     dryRun,
     entries
   };
@@ -4688,16 +6092,17 @@ function retirementStamp(meta) {
 async function stampRetirement(registry, ref, now) {
   for (let attempt = 0; attempt < 3; attempt += 1) {
     const rec = await registry.get(ref);
-    if (rec === null || rec.status !== "destroyed") return;
+    if (rec === null || rec.status !== "destroyed") return false;
     try {
       await registry.compareAndSwap(ref, rec.token, {
         retention: { ...rec.retention, [RETIRED_AT]: now }
       });
-      return;
+      return true;
     } catch (err) {
       if (!isWriteConflictError(err)) throw err;
     }
   }
+  return false;
 }
 async function isFullyReclaimed(deps, ref) {
   for await (const key of deps.storage.list(ref)) {
@@ -4718,8 +6123,45 @@ async function generationsPresent(storage, ref) {
   for await (const key of storage.list(ref)) present.add(key.generation);
   return present;
 }
+async function checkSummary(ref, live, deps) {
+  const generation = live.currentGen;
+  const keyed = live.wrappedDeks !== void 0 && live.wrappedDeks.length > 0;
+  let aead;
+  if (keyed) {
+    if (deps.keystore === void 0) return { kind: "ok", unchecked: true };
+    try {
+      aead = await deps.keystore.openDek(live.wrappedDeks);
+    } catch (err) {
+      if (isIntegrityError(err) || isCloudRoaringError(err) && err.name === "KeyUnavailableError")
+        return { kind: "ok", unchecked: true };
+      throw err;
+    }
+  }
+  const described = usableSummary(ref, live, aead);
+  if (described === void 0) return { kind: "ok", unchecked: keyed };
+  const reader = await openGenerationReader(
+    deps.storage,
+    { namespace: ref.namespace, segment: ref.segment, generation },
+    aead === void 0 ? void 0 : { aead, aadFor: (scope) => aadFor(ref, generation, scope) }
+  );
+  let cardinality = 0;
+  for (const n of reader.cardinalities().values()) cardinality += n;
+  if (summaryAgrees(described, { cardinality, metadata: reader.metadata })) return { kind: "ok" };
+  return {
+    kind: "issue",
+    issue: {
+      segment: ref.segment,
+      namespace: ref.namespace,
+      currentGen: generation,
+      issue: "summary-mismatch"
+    }
+  };
+}
 async function runConsistencyCheck(deps, options = {}) {
   if (options.namespace !== void 0) validateUserNamespace(options.namespace);
+  if (options.summaries !== void 0 && typeof options.summaries !== "boolean") {
+    throw new ValidationError(`summaries must be a boolean; got ${String(options.summaries)}`);
+  }
   const concurrency = options.concurrency ?? DEFAULT_CHECK_CONCURRENCY;
   if (!Number.isInteger(concurrency) || concurrency < 1) {
     throw new ValidationError(`concurrency must be a positive integer; got ${concurrency}`);
@@ -4741,7 +6183,10 @@ async function runConsistencyCheck(deps, options = {}) {
       if (!live || live.status === "destroyed") return { kind: "ok" };
       if (live.currentGen === null) return { kind: "ok" };
       const present = await generationsPresent(deps.storage, ref);
-      if (present.has(live.currentGen)) return { kind: "ok" };
+      if (present.has(live.currentGen)) {
+        if (options.summaries !== true || live.summary === void 0) return { kind: "ok" };
+        return await checkSummary(ref, live, deps);
+      }
       return {
         kind: "issue",
         issue: {
@@ -4764,53 +6209,13 @@ async function runConsistencyCheck(deps, options = {}) {
   });
   const inconsistent = [];
   const errored = [];
+  let summariesUnchecked = 0;
   for (const r of results) {
     if (r.kind === "issue") inconsistent.push(r.issue);
     else if (r.kind === "error") errored.push(r.error);
+    else if (r.unchecked === true) summariesUnchecked += 1;
   }
-  return { checked: recs.length, inconsistent, errored };
-}
-
-// src/core/retry.ts
-var DEFAULT_RETRY_POLICY = {
-  maxAttempts: 4,
-  baseDelayMs: 50,
-  maxDelayMs: 2e3,
-  backoffFactor: 2,
-  jitter: "full"
-};
-function backoffDelayMs(policy, attempt) {
-  const raw = policy.baseDelayMs * policy.backoffFactor ** (attempt - 1);
-  return Math.min(policy.maxDelayMs, raw);
-}
-function applyJitter(policy, delayMs, rng) {
-  if (policy.jitter === "none") return delayMs;
-  return rng.next() * delayMs;
-}
-async function withRetry(op, policy, deps) {
-  const retryable = deps.isRetryable ?? isTransientError;
-  if (!Number.isFinite(policy.maxAttempts) || policy.maxAttempts < 1) {
-    throw new ValidationError(
-      `retry.maxAttempts must be a finite number >= 1 (got ${String(policy.maxAttempts)})`
-    );
-  }
-  const attempts = Math.floor(policy.maxAttempts);
-  let lastErr;
-  for (let attempt = 1; attempt <= attempts; attempt++) {
-    try {
-      return await op();
-    } catch (err) {
-      lastErr = err;
-      if (attempt >= attempts || !retryable(err)) throw err;
-      const delayMs = applyJitter(policy, backoffDelayMs(policy, attempt), deps.rng);
-      try {
-        deps.onRetry?.({ attempt, delayMs, err });
-      } catch {
-      }
-      await deps.clock.sleep(delayMs);
-    }
-  }
-  throw lastErr;
+  return options.summaries === true ? { checked: recs.length, inconsistent, errored, summariesUnchecked } : { checked: recs.length, inconsistent, errored };
 }
 
 // src/drivers/retry/retrying-chunk-source.ts
@@ -4832,6 +6237,7 @@ var RetryingStorageChunkSource = class {
   /** Present only when the inner source supports it — so capability detection stays honest. */
   sizeOf;
   cardinalities;
+  summary;
   currentGeneration;
   invalidate;
   exists;
@@ -4856,6 +6262,10 @@ var RetryingStorageChunkSource = class {
     if (innerCardinalities) {
       this.cardinalities = (ref) => withRetry(() => innerCardinalities.call(inner, ref), this.policy, this.deps);
     }
+    const innerSummary = inner.summary;
+    if (innerSummary) {
+      this.summary = (ref) => withRetry(() => innerSummary.call(inner, ref), this.policy, this.deps);
+    }
     const innerCurrentGeneration = inner.currentGeneration;
     if (innerCurrentGeneration) {
       this.currentGeneration = (ref) => withRetry(() => innerCurrentGeneration.call(inner, ref), this.policy, this.deps);