@cloudbitmaps/core 0.8.1 → 0.9.0

package/dist/index.cjs

@@ -2153,6 +2153,7 @@ var CrbmColdChunkSource = class {
       const record = await this.registry.get(ref);
       if (record === null) return null;
       if (record.status === "destroyed") return null;
+      if (record.currentGen === null) return null;
       return { generation: record.currentGen, wrappedDeks: record.wrappedDeks };
     }
     let maxGen = -1;
@@ -2276,6 +2277,11 @@ async function publishGeneration(registry, key, options = {}) {
         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) {
+        await registry.compareAndSwap(key, record.token, {
+          currentGen: key.generation,
+          ...options.wrappedDeks === void 0 ? {} : { wrappedDeks: options.wrappedDeks }
+        });
       } else if (record.currentGen > key.generation) {
         return false;
       } else if (record.currentGen === key.generation) {
@@ -2290,7 +2296,7 @@ async function publishGeneration(registry, key, options = {}) {
     }
   }
   const final = await registry.get(key);
-  if (final !== null && final.currentGen >= key.generation)
+  if (final !== null && final.currentGen !== null && final.currentGen >= key.generation)
     return final.currentGen === key.generation;
   throw new WriteConflictError(
     `publishGeneration: contention setting currentGen for ${key.segment}`
@@ -2359,6 +2365,11 @@ async function bulkLoadCrbmGeneration(driver, key, ids, options = {}) {
       `segment "${key.segment}" is destroyed (crypto-shredded) \u2014 refusing to write; use a new segment`
     );
   }
+  if (existing?.wrappedDeks !== void 0 && existing.wrappedDeks.length > 0 && options.keystore === void 0) {
+    throw new KeyUnavailableError(
+      `segment "${key.segment}" is encrypted but this bulk-load has no keystore \u2014 refusing to write a cleartext generation onto an encrypted segment. Pass the keystore holding its DEK.`
+    );
+  }
   let crypto;
   let newWrapped;
   if (options.keystore !== void 0) {
@@ -2461,7 +2472,7 @@ async function compactSegmentInner(ref, deps, options) {
       survived: 0
     };
   }
-  if (record === null) {
+  if (record === null || record.currentGen === null) {
     const pinned = await collectDirty(
       deps.warm,
       ref,
@@ -2480,7 +2491,15 @@ async function compactSegmentInner(ref, deps, options) {
       };
     let aead;
     let wrappedDeks;
-    if (deps.keystore !== void 0) {
+    if (record?.wrappedDeks !== void 0 && record.wrappedDeks.length > 0) {
+      if (deps.keystore === void 0) {
+        throw new KeyUnavailableError(
+          `segment "${ref.segment}" is encrypted but compaction has no keystore`
+        );
+      }
+      aead = await deps.keystore.openDek(record.wrappedDeks);
+      wrappedDeks = record.wrappedDeks;
+    } else if (deps.keystore !== void 0) {
       const minted = await deps.keystore.createDek();
       aead = minted.aead;
       wrappedDeks = minted.wrapped;
@@ -2506,17 +2525,8 @@ async function compactSegmentInner(ref, deps, options) {
     if (wrote && tally !== void 0) {
       await verifyGeneration(deps.cold, gen0, tally, cryptoAt(aead, 0));
     }
-    try {
-      await deps.registry.create(ref, {
-        currentGen: 0,
-        dirtyChunkCount: 0,
-        status: "active",
-        wrappedDeks
-      });
-    } catch (err) {
-      if (!isWriteConflictError(err)) throw err;
-    }
-    if (!wrote)
+    const published = await publishGenZero(deps.registry, ref, record, wrappedDeks, wrote);
+    if (!wrote || !published)
       return {
         ...base,
         compacted: false,
@@ -2680,6 +2690,43 @@ async function compactSegmentInner(ref, deps, options) {
     throw err;
   }
 }
+var PUBLISH_GEN0_ATTEMPTS = 5;
+async function publishGenZero(registry, ref, known, wrappedDeks, wrote) {
+  if (!wrote && wrappedDeks !== void 0) return false;
+  let current = known;
+  for (let attempt = 0; attempt < PUBLISH_GEN0_ATTEMPTS; attempt += 1) {
+    try {
+      if (current === null) {
+        await registry.create(ref, {
+          currentGen: 0,
+          dirtyChunkCount: 0,
+          status: "active",
+          wrappedDeks
+        });
+      } else if (current.status === "destroyed") {
+        return false;
+      } else if (current.currentGen === null) {
+        await registry.compareAndSwap(ref, current.token, {
+          currentGen: 0,
+          dirtyChunkCount: 0,
+          ...wrappedDeks === void 0 ? {} : { wrappedDeks }
+        });
+      } else {
+        return current.currentGen === 0 && sameWrappings(current.wrappedDeks, wrappedDeks);
+      }
+      return true;
+    } catch (err) {
+      if (!isWriteConflictError(err)) throw err;
+      current = await registry.get(ref);
+    }
+  }
+  return false;
+}
+function sameWrappings(a, b) {
+  if (a === void 0 || b === void 0) return a === b;
+  if (a.length !== b.length) return false;
+  return a.every((w, i) => w.keyId === b[i]?.keyId && w.wrapped === b[i]?.wrapped);
+}
 async function gcOrphanGenerations(ref, deps, options = {}) {
   const keep = Math.max(0, options.keep ?? 1);
   const record = await deps.registry.get(ref);
@@ -2687,7 +2734,12 @@ async function gcOrphanGenerations(ref, deps, options = {}) {
   const current = record.currentGen;
   const gens = [];
   for await (const key of deps.cold.list(ref)) gens.push(key.generation);
-  const toDelete = record.status === "destroyed" ? gens.sort((a, b) => a - b) : (
+  const toDelete = record.status === "destroyed" ? gens.sort((a, b) => a - b) : current === null ? (
+    // No Cold pointer yet, so "below current" selects nothing and there is nothing safe to infer: an
+    // object here is either a bootstrap about to publish gen 0 or an orphan we cannot tell apart from it.
+    // Deleting would race that publish into a dangling pointer. RECONCILE collects it on the next cycle.
+    []
+  ) : (
     // Delete generations below current, except the newest `keep` of them (the grace window).
     gens.filter((g) => g < current).sort((a, b) => b - a).slice(keep)
   );
@@ -3033,9 +3085,21 @@ var MAX_GOVERNANCE_BYTES = 64 * 1024;
 var MAX_WRAPPED_DEKS = 8;
 var MAX_WRAPPED_DEK_BYTES = 4 * 1024;
 function validateGeneration(gen) {
+  if (gen === null) return;
   if (!Number.isInteger(gen) || gen < 0) {
-    throw new ValidationError(`currentGen must be a non-negative integer; got ${gen}`);
+    throw new ValidationError(
+      `currentGen must be a non-negative integer or null (no Cold generation yet); got ${gen}`
+    );
+  }
+}
+function validatePatchGeneration(patch) {
+  if (!("currentGen" in patch)) return;
+  if (patch.currentGen === void 0) {
+    throw new ValidationError(
+      `currentGen was present in the patch but undefined. Pass \`null\` to clear the pointer (the segment has no Cold generation), or omit the key to leave it unchanged \u2014 an undefined value is refused because it used to be a no-op and would now un-publish the segment's Cold data.`
+    );
   }
+  validateGeneration(patch.currentGen);
 }
 function validateCount(count, field = "dirtyChunkCount") {
   if (!Number.isInteger(count) || count < 0) {
@@ -3054,6 +3118,11 @@ function validateStatus(status) {
 }
 function validateGovernance(meta, field) {
   if (meta === void 0) return;
+  if (meta === null || typeof meta !== "object" || Array.isArray(meta)) {
+    throw new ValidationError(
+      `${field} must be a plain object (got ${meta === null ? "null" : typeof meta})`
+    );
+  }
   let json;
   try {
     json = JSON.stringify(meta);
@@ -3094,7 +3163,7 @@ function validateNewRegistryRecord(rec) {
   validateGovernance(rec.residency, "residency");
 }
 function validateRegistryPatch(patch) {
-  if (patch.currentGen !== void 0) validateGeneration(patch.currentGen);
+  validatePatchGeneration(patch);
   if (patch.dirtyChunkCount !== void 0) validateCount(patch.dirtyChunkCount);
   if (patch.consecutiveFailures !== void 0)
     validateCount(patch.consecutiveFailures, "consecutiveFailures");
@@ -3175,10 +3244,10 @@ function recordFromNew(ref, rec, now, token) {
   };
 }
 function assertStoredRecordShape(r, ctx) {
-  if (typeof r.segment !== "string" || r.namespace !== void 0 && typeof r.namespace !== "string" || typeof r.currentGen !== "number" || typeof r.dirtyChunkCount !== "number" || typeof r.status !== "string" || typeof r.createdAt !== "number" || typeof r.updatedAt !== "number") {
+  if (typeof r.segment !== "string" || r.namespace !== void 0 && typeof r.namespace !== "string" || r.currentGen !== null && typeof r.currentGen !== "number" || typeof r.dirtyChunkCount !== "number" || typeof r.status !== "string" || typeof r.createdAt !== "number" || typeof r.updatedAt !== "number") {
     throw new IntegrityError(`registry record is missing required fields: ${ctx}`);
   }
-  if (!Number.isInteger(r.currentGen) || r.currentGen < 0) {
+  if (r.currentGen !== null && (!Number.isInteger(r.currentGen) || r.currentGen < 0)) {
     throw new IntegrityError(`registry record has an invalid currentGen (${r.currentGen}): ${ctx}`);
   }
   if (!Number.isInteger(r.dirtyChunkCount) || r.dirtyChunkCount < 0) {
@@ -3203,12 +3272,22 @@ function assertStoredRecordShape(r, ctx) {
     throw new IntegrityError(`registry record has an invalid keyId: ${ctx}`);
   }
   validateWrappedDeks(r.wrappedDeks, true);
+  for (const field of ["retention", "residency"]) {
+    const meta = r[field];
+    if (meta !== void 0 && (meta === null || typeof meta !== "object" || Array.isArray(meta))) {
+      throw new IntegrityError(`registry record has a non-object ${field}: ${ctx}`);
+    }
+  }
 }
 function applyRegistryPatch(prev, patch, now, token) {
   return {
     namespace: prev.namespace,
     segment: prev.segment,
-    currentGen: patch.currentGen ?? prev.currentGen,
+    // `'currentGen' in patch`, NOT `patch.currentGen ?? prev.currentGen`. `null` is a legal, meaningful value
+    // here (no Cold generation yet), and `??` treats it as absent — so the nullish form would silently ignore a
+    // patch that clears the pointer and leave the old generation in place. The same reason `wrappedDeks` and
+    // `keyId` below use presence: any field whose null is a *value* cannot be merged with `??`.
+    currentGen: "currentGen" in patch ? patch.currentGen ?? null : prev.currentGen,
     wrappedDeks: "wrappedDeks" in patch ? patch.wrappedDeks : prev.wrappedDeks,
     keyId: "keyId" in patch ? patch.keyId : prev.keyId,
     dirtyChunkCount: patch.dirtyChunkCount ?? prev.dirtyChunkCount,
@@ -4097,14 +4176,15 @@ async function dropSegment(ref, deps, options) {
   if (shred.reason === "absent") {
     const orphans = await listGenerations(deps.cold, ref);
     if (orphans.length === 0) {
+      const clearedWarmOnly = shred.warmRowsDeleted > 0;
       return {
         ...base,
-        dropped: false,
+        dropped: clearedWarmOnly,
         warmRowsDeleted: shred.warmRowsDeleted,
         generationsDeleted: [],
         generationsRemaining: [],
         cryptoShredded: false,
-        reason: "absent"
+        reason: clearedWarmOnly ? "warm-only" : "absent"
       };
     }
     try {
@@ -4275,8 +4355,309 @@ async function eraseWarm(warm, ref, op = "destroySegment") {
   return deleted;
 }
 
-// src/core/consistency.ts
+// src/core/retention.ts
+var EXPIRES_AT = "expiresAt";
+var RETENTION_CAS_ATTEMPTS = 5;
+var MIN_EXPIRES_AT_MS = 1e12;
+function validateRetentionPolicy(policy) {
+  const { expiresAt } = policy;
+  if (typeof expiresAt !== "number" || !Number.isInteger(expiresAt)) {
+    throw new ValidationError(
+      `retention.expiresAt must be an integer epoch-ms; got ${String(expiresAt)}`
+    );
+  }
+  if (expiresAt < MIN_EXPIRES_AT_MS) {
+    throw new ValidationError(
+      `retention.expiresAt (${expiresAt}) is before ${MIN_EXPIRES_AT_MS} \u2014 that is almost certainly epoch SECONDS rather than milliseconds, which would read as "already expired" and retire the segment on the next sweep. Use \`Date.now() + days * 86_400_000\`. To retire a segment now, call \`dropSegment\`.`
+    );
+  }
+}
+function readRetentionPolicy(meta) {
+  if (meta === void 0) return null;
+  if (meta === null || typeof meta !== "object" || Array.isArray(meta)) return "invalid";
+  if (!(EXPIRES_AT in meta)) return null;
+  const raw = meta[EXPIRES_AT];
+  if (typeof raw !== "number" || !Number.isInteger(raw) || raw < MIN_EXPIRES_AT_MS)
+    return "invalid";
+  return { expiresAt: raw };
+}
+async function getSegmentRetention(ref, deps) {
+  const record = await deps.registry.get(ref);
+  if (record === null || record.status === "destroyed") return null;
+  return readRetentionPolicy(record.retention);
+}
+async function setSegmentRetention(ref, deps, policy) {
+  validateRetentionPolicy(policy);
+  const base = { segment: ref.segment, namespace: ref.namespace };
+  for (let attempt = 0; attempt < RETENTION_CAS_ATTEMPTS; attempt += 1) {
+    const record = await deps.registry.get(ref);
+    try {
+      if (record === null) {
+        await deps.registry.create(ref, {
+          currentGen: null,
+          retention: { [EXPIRES_AT]: policy.expiresAt }
+        });
+        return { ...base, expiresAt: policy.expiresAt, createdRow: true };
+      }
+      assertNotDestroyed(record, ref);
+      await deps.registry.compareAndSwap(ref, record.token, {
+        retention: { ...record.retention, [EXPIRES_AT]: policy.expiresAt }
+      });
+      return { ...base, expiresAt: policy.expiresAt, createdRow: false };
+    } catch (err) {
+      if (!isWriteConflictError(err)) throw err;
+    }
+  }
+  throw new WriteConflictError(
+    `setRetention: contention writing the retention policy for segment "${ref.segment}"`
+  );
+}
+async function clearSegmentRetention(ref, deps) {
+  for (let attempt = 0; attempt < RETENTION_CAS_ATTEMPTS; attempt += 1) {
+    const record = await deps.registry.get(ref);
+    if (record === null) return false;
+    if (record.status === "destroyed") return false;
+    if (record.retention === void 0 || !(EXPIRES_AT in record.retention)) return false;
+    const rest = { ...record.retention };
+    delete rest[EXPIRES_AT];
+    try {
+      await deps.registry.compareAndSwap(ref, record.token, {
+        retention: Object.keys(rest).length === 0 ? void 0 : rest
+      });
+      return true;
+    } catch (err) {
+      if (!isWriteConflictError(err)) throw err;
+    }
+  }
+  throw new WriteConflictError(
+    `clearRetention: contention clearing the retention policy for segment "${ref.segment}"`
+  );
+}
+function assertNotDestroyed(record, ref) {
+  if (record.status === "destroyed") {
+    throw new ValidationError(
+      `segment "${ref.segment}" is destroyed (crypto-shredded) \u2014 refusing to set a retention policy on a tombstone; there is nothing left to retire. Use a new segment.`
+    );
+  }
+}
+
+// src/core/registry-scan.ts
 var DEFAULT_MAX_SCAN_SEGMENTS = 25e4;
+function validateMaxScanSegments(value, op) {
+  if (!Number.isFinite(value) || value < 1) {
+    throw new ValidationError(`${op}: maxScanSegments must be a finite number >= 1; got ${value}`);
+  }
+}
+async function drainRegistry(registry, options) {
+  const { maxScanSegments, op } = options;
+  validateMaxScanSegments(maxScanSegments, op);
+  const rows = [];
+  for await (const rec of registry.list(options.namespace)) {
+    if (rows.length >= maxScanSegments) {
+      throw new BudgetExceededError(
+        `${op} would enumerate more than ${maxScanSegments} segments \u2014 the scan was abandoned there rather than completed. Narrow it with \`namespace\`, or raise \`maxScanSegments\` if the fleet really is that large and the memory is available (a record is a few hundred bytes resident).`
+      );
+    }
+    rows.push(rec);
+  }
+  return rows;
+}
+
+// src/core/retention-sweep.ts
+var DEFAULT_RETIRE_LIMIT = 100;
+var DEFAULT_TOMBSTONE_GRACE_MS = 864e5;
+async function retireExpired(deps, options) {
+  const now = options.now;
+  if (!Number.isFinite(now)) {
+    throw new ValidationError(
+      `retireExpired: \`now\` must be a finite epoch-ms; got ${String(now)}`
+    );
+  }
+  if (now < MIN_EXPIRES_AT_MS) {
+    throw new ValidationError(
+      `retireExpired: \`now\` (${now}) is before ${MIN_EXPIRES_AT_MS} \u2014 that is almost certainly epoch SECONDS rather than milliseconds. A sweep with a wrong-units clock treats every policy as expired.`
+    );
+  }
+  const limit = options.limit ?? DEFAULT_RETIRE_LIMIT;
+  if (!Number.isInteger(limit) || limit < 1) {
+    throw new ValidationError(`retireExpired: \`limit\` must be a positive integer; got ${limit}`);
+  }
+  const purgeTombstones = options.purgeTombstones ?? true;
+  const grace = options.tombstoneGraceMs ?? DEFAULT_TOMBSTONE_GRACE_MS;
+  if (!Number.isFinite(grace) || grace < 0) {
+    throw new ValidationError(
+      `retireExpired: \`tombstoneGraceMs\` must be a non-negative finite number; got ${String(grace)}`
+    );
+  }
+  const maxScanSegments = options.maxScanSegments ?? DEFAULT_MAX_SCAN_SEGMENTS;
+  if (!Number.isFinite(maxScanSegments) || maxScanSegments < 1) {
+    throw new ValidationError(
+      `retireExpired: \`maxScanSegments\` must be a finite number >= 1; got ${String(maxScanSegments)}`
+    );
+  }
+  const dryRun = options.dryRun === true;
+  const rows = await drainRegistry(deps.registry, {
+    namespace: options.namespace,
+    maxScanSegments,
+    op: "retireExpired"
+  });
+  const entries = [];
+  let eligible = 0;
+  let retired = 0;
+  let wouldRetire = 0;
+  let tombstonesPurged = 0;
+  let limited = false;
+  let attempted = 0;
+  for (const rec of rows) {
+    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;
+      const retiredAt = retirementStamp(rec.retention);
+      if (retiredAt === null) continue;
+      if (now - retiredAt < grace) continue;
+      if (attempted >= limit) {
+        limited = true;
+        break;
+      }
+      attempted += 1;
+      try {
+        if (!await isFullyReclaimed(deps, ref)) {
+          if (!dryRun) await gcOrphanGenerations(ref, deps).catch(() => void 0);
+          if (!await isFullyReclaimed(deps, ref)) {
+            entries.push({ ...base, action: "skipped", reason: "tombstone-not-empty" });
+            continue;
+          }
+        }
+        if (!dryRun) await deps.registry.delete(ref);
+        if (!dryRun) tombstonesPurged += 1;
+        entries.push({
+          ...base,
+          action: dryRun ? "would-purge-tombstone" : "purged-tombstone"
+        });
+      } catch (err) {
+        entries.push({ ...base, action: "skipped", reason: failureReason(err) });
+      }
+      continue;
+    }
+    if (policy === null) continue;
+    if (policy === "invalid") {
+      entries.push({ ...base, action: "skipped", reason: "invalid-policy" });
+      continue;
+    }
+    if (policy.expiresAt > now) continue;
+    eligible += 1;
+    if (attempted >= limit) {
+      limited = true;
+      break;
+    }
+    try {
+      const live = await deps.registry.get(ref);
+      const livePolicy = live === null ? null : readRetentionPolicy(live.retention);
+      if (live === null || live.status === "destroyed" || livePolicy === null || livePolicy === "invalid" || livePolicy.expiresAt > now) {
+        entries.push({ ...base, action: "skipped", reason: "policy-changed" });
+        continue;
+      }
+      attempted += 1;
+      const result = await dropSegment(ref, deps, {
+        confirmSegment: rec.segment,
+        dryRun,
+        audit: options.audit
+      });
+      if (dryRun) {
+        wouldRetire += 1;
+        entries.push({ ...base, action: "would-retire", expiresAt: livePolicy.expiresAt, result });
+        continue;
+      }
+      if (!result.dropped) {
+        entries.push({
+          ...base,
+          action: "skipped",
+          reason: `failed: drop reported ${result.reason}`
+        });
+        continue;
+      }
+      retired += 1;
+      entries.push({ ...base, action: "retired", expiresAt: livePolicy.expiresAt, result });
+      if (result.warmRowsDeleted === 0 && result.generationsDeleted.length === 0) {
+        await deps.registry.delete(ref).catch(() => void 0);
+        continue;
+      }
+      await stampRetirement(deps.registry, ref, now).catch(() => void 0);
+    } catch (err) {
+      const after = await deps.registry.get(ref).catch(() => null);
+      if (after?.status === "destroyed") {
+        await stampRetirement(deps.registry, ref, now).catch(() => void 0);
+        retired += 1;
+        entries.push({
+          ...base,
+          action: "retired",
+          expiresAt: policy.expiresAt,
+          result: {
+            ...base,
+            dropped: true,
+            warmRowsDeleted: 0,
+            generationsDeleted: [],
+            generationsRemaining: [],
+            cryptoShredded: false,
+            reason: void 0
+          },
+          fault: failureReason(err)
+        });
+        continue;
+      }
+      entries.push({ ...base, action: "skipped", reason: failureReason(err) });
+    }
+  }
+  return {
+    scanned: rows.length,
+    eligible,
+    retired,
+    wouldRetire,
+    tombstonesPurged,
+    limited,
+    dryRun,
+    entries
+  };
+}
+var RETIRED_AT = "retiredBySweepAt";
+function retirementStamp(meta) {
+  if (meta === void 0 || meta === null || typeof meta !== "object" || Array.isArray(meta)) {
+    return null;
+  }
+  const raw = meta[RETIRED_AT];
+  return typeof raw === "number" && Number.isInteger(raw) && raw >= MIN_EXPIRES_AT_MS ? raw : null;
+}
+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;
+    try {
+      await registry.compareAndSwap(ref, rec.token, {
+        retention: { ...rec.retention, [RETIRED_AT]: now }
+      });
+      return;
+    } catch (err) {
+      if (!isWriteConflictError(err)) throw err;
+    }
+  }
+}
+async function isFullyReclaimed(deps, ref) {
+  for await (const key of deps.cold.list(ref)) {
+    return false;
+  }
+  for await (const row of deps.warm.listChunks(ref)) {
+    return false;
+  }
+  return true;
+}
+function failureReason(err) {
+  if (isWriteConflictError(err)) return "failed: contended";
+  return `failed: ${err instanceof Error ? err.message : String(err)}`;
+}
+
+// src/core/consistency.ts
 var DEFAULT_CHECK_CONCURRENCY = 8;
 async function listGenerations2(cold, ref) {
   const present = /* @__PURE__ */ new Set();
@@ -4289,26 +4670,18 @@ async function runConsistencyCheck(deps, options = {}) {
     throw new ValidationError(`concurrency must be a positive integer; got ${concurrency}`);
   }
   const maxScanSegments = options.maxScanSegments ?? DEFAULT_MAX_SCAN_SEGMENTS;
-  if (!Number.isFinite(maxScanSegments) || maxScanSegments < 1) {
-    throw new ValidationError(
-      `maxScanSegments must be a finite number >= 1; got ${String(options.maxScanSegments)}`
-    );
-  }
-  const recs = [];
-  for await (const rec of deps.registry.list(options.namespace)) {
-    recs.push(rec);
-    if (recs.length > maxScanSegments) {
-      throw new BudgetExceededError(
-        `checkConsistency would enumerate more than ${maxScanSegments} segments \u2014 the scan was abandoned there rather than completed. Narrow it with \`namespace\`, or raise \`maxScanSegments\` if the fleet really is that large and the memory is available.`
-      );
-    }
-  }
+  const recs = await drainRegistry(deps.registry, {
+    namespace: options.namespace,
+    maxScanSegments,
+    op: "checkConsistency"
+  });
   const results = await mapWithConcurrency(recs, concurrency, async (rec) => {
     if (rec.status === "destroyed") return { kind: "ok" };
     const ref = { segment: rec.segment, namespace: rec.namespace };
     try {
       const live = await deps.registry.get(ref);
       if (!live || live.status === "destroyed") return { kind: "ok" };
+      if (live.currentGen === null) return { kind: "ok" };
       const present = await listGenerations2(deps.cold, ref);
       if (present.has(live.currentGen)) return { kind: "ok" };
       return {
@@ -4540,7 +4913,9 @@ exports.DEFAULT_MAX_SCAN_SEGMENTS = DEFAULT_MAX_SCAN_SEGMENTS;
 exports.DEFAULT_MAX_WARM_SCAN_BYTES = DEFAULT_MAX_WARM_SCAN_BYTES;
 exports.DEFAULT_OCC_BACKOFF = DEFAULT_OCC_BACKOFF;
 exports.DEFAULT_PRICING = DEFAULT_PRICING;
+exports.DEFAULT_RETIRE_LIMIT = DEFAULT_RETIRE_LIMIT;
 exports.DEFAULT_RETRY_POLICY = DEFAULT_RETRY_POLICY;
+exports.DEFAULT_TOMBSTONE_GRACE_MS = DEFAULT_TOMBSTONE_GRACE_MS;
 exports.DEFAULT_WRITE_CONCURRENCY = DEFAULT_WRITE_CONCURRENCY;
 exports.InProcessKeystore = InProcessKeystore;
 exports.IntegrityError = IntegrityError;
@@ -4548,6 +4923,7 @@ exports.KeyUnavailableError = KeyUnavailableError;
 exports.LocalFsColdDriver = LocalFsColdDriver;
 exports.LocalFsRegistryDriver = LocalFsRegistryDriver;
 exports.LocalFsWarmDriver = LocalFsWarmDriver;
+exports.MIN_EXPIRES_AT_MS = MIN_EXPIRES_AT_MS;
 exports.MemoryColdChunkSource = MemoryColdChunkSource;
 exports.MemoryColdDriver = MemoryColdDriver;
 exports.MemoryRegistryDriver = MemoryRegistryDriver;
@@ -4572,14 +4948,17 @@ exports.aadFor = aadFor;
 exports.bulkLoadCrbmGeneration = bulkLoadCrbmGeneration;
 exports.checkBudget = checkBudget;
 exports.chunkRefKey = chunkRefKey;
+exports.clearSegmentRetention = clearSegmentRetention;
 exports.collectWithinBudget = collectWithinBudget;
 exports.compactSegment = compactSegment;
 exports.destroySegment = destroySegment;
+exports.drainRegistry = drainRegistry;
 exports.dropSegment = dropSegment;
 exports.eraseNamespace = eraseNamespace;
 exports.estimateCost = estimateCost;
 exports.findCompactable = findCompactable;
 exports.gcOrphanGenerations = gcOrphanGenerations;
+exports.getSegmentRetention = getSegmentRetention;
 exports.groundedReport = groundedReport;
 exports.isCloudRoaringError = isCloudRoaringError;
 exports.isIntegrityError = isIntegrityError;
@@ -4591,15 +4970,19 @@ exports.isWriteConflictError = isWriteConflictError;
 exports.joinId = joinId;
 exports.mapWithConcurrency = mapWithConcurrency;
 exports.publishGeneration = publishGeneration;
+exports.readRetentionPolicy = readRetentionPolicy;
 exports.resolveBudget = resolveBudget;
 exports.resolvePerOpBudget = resolvePerOpBudget;
+exports.retireExpired = retireExpired;
 exports.runCompactionCycle = runCompactionCycle;
 exports.runConsistencyCheck = runConsistencyCheck;
 exports.runExport = runExport;
 exports.safeMetrics = safeMetrics;
 exports.segmentKey = segmentKey;
+exports.setSegmentRetention = setSegmentRetention;
 exports.splitId = splitId;
 exports.validateCompactionOptions = validateCompactionOptions;
+exports.validateMaxScanSegments = validateMaxScanSegments;
 exports.validateSegmentRef = validateSegmentRef;
 exports.withRetry = withRetry;
 exports.writeCrbmGeneration = writeCrbmGeneration;