@cloudbitmaps/core 0.18.2 → 0.19.0

package/dist/index.js

@@ -34,8 +34,11 @@ import {
   entropyIsAvailable,
   heldGenerations,
   incarnationOf,
+  isBudgetExceededError,
+  isCapabilityError,
   isCloudRoaringError,
   isIntegrityError,
+  isKeyUnavailableError,
   isLeaseExpiredError,
   isLeaseLimitError,
   isLive,
@@ -44,6 +47,7 @@ import {
   isStaleOperandError,
   isStorageBackend,
   isTransientError,
+  isUnsupportedError,
   isValidationError,
   isWriteConflictError,
   leaseChurn,
@@ -70,7 +74,7 @@ import {
   validateUserNamespace,
   validateUserRef,
   webCryptoEntropy
-} from "./chunk-ML6AT53O.js";
+} from "./chunk-TNWTIAON.js";
 
 // src/core/bit-route.ts
 var U32_MAX = 4294967295;
@@ -91,6 +95,20 @@ function joinId(chunkKey, remainder) {
 var DEFAULT_BUDGET = { maxRequests: 1e6 };
 function resolveBudget(opt, fallback) {
   if (opt === false) return null;
+  if (opt !== void 0 && opt !== null) {
+    if (typeof opt !== "object" || Array.isArray(opt)) {
+      const got = Array.isArray(opt) ? "an array" : `a ${typeof opt}`;
+      throw new ValidationError(`budget must be { maxRequests } or false; got ${got}`);
+    }
+    const unknown = Object.keys(opt).filter(
+      (k) => k !== "maxRequests" && opt[k] !== void 0
+    );
+    if (unknown.length > 0) {
+      throw new ValidationError(
+        `budget: unknown option${unknown.length > 1 ? "s" : ""} ${unknown.map((k) => `"${k}"`).join(", ")}; it takes { maxRequests } or false`
+      );
+    }
+  }
   const maxRequests = opt?.maxRequests ?? fallback.maxRequests;
   if (!Number.isInteger(maxRequests) || maxRequests < 1) {
     throw new ValidationError(`budget.maxRequests must be a positive integer; got ${maxRequests}`);
@@ -98,7 +116,7 @@ function resolveBudget(opt, fallback) {
   return { maxRequests };
 }
 function resolvePerOpBudget(opt, storeBudget) {
-  if (opt === void 0) return storeBudget;
+  if (opt === void 0 || opt === null) return storeBudget;
   return resolveBudget(opt, storeBudget ?? DEFAULT_BUDGET);
 }
 function checkBudget(budget, projectedRequests, op) {
@@ -326,6 +344,50 @@ function shardOf(key, totalShards) {
   return (h >>> 0) % totalShards;
 }
 
+// src/core/audit.ts
+var NOOP_AUDIT = {
+  onEvent() {
+  }
+};
+function safeAudit(sink) {
+  if (sink === NOOP_AUDIT) return sink;
+  return {
+    onEvent(event) {
+      try {
+        ignoreRejection(sink.onEvent(event));
+      } catch {
+      }
+    }
+  };
+}
+function checkedAuditSink(sink, op) {
+  if (sink === void 0 || sink === null) return;
+  if (typeof sink.onEvent !== "function") {
+    throw new ValidationError(
+      `${op}: audit must be a sink with an onEvent(event) method, such as a RecordingAuditSink`
+    );
+  }
+}
+function ignoreRejection(returned) {
+  if (typeof returned?.then === "function") {
+    returned.then(void 0, () => {
+    });
+  }
+}
+var RecordingAuditSink = class {
+  recorded = [];
+  onEvent(event) {
+    this.recorded.push(event);
+  }
+  /** An independent copy of the recorded events, in emission order. */
+  snapshot() {
+    return this.recorded.map((e) => ({ ...e }));
+  }
+  reset() {
+    this.recorded.length = 0;
+  }
+};
+
 // src/core/metrics.ts
 var NOOP_METRICS = {
   onEvent() {
@@ -333,10 +395,15 @@ var NOOP_METRICS = {
 };
 function safeMetrics(sink) {
   if (sink === NOOP_METRICS) return sink;
+  if (typeof sink?.onEvent !== "function") {
+    throw new ValidationError(
+      "metrics must be a sink with an onEvent(event) method, such as a CountingMetricsSink"
+    );
+  }
   return {
     onEvent(event) {
       try {
-        sink.onEvent(event);
+        ignoreRejection(sink.onEvent(event));
       } catch {
       }
     }
@@ -347,7 +414,8 @@ var OP_NAMES = [
   "count",
   "intersectInto",
   "unionInto",
-  "andNotInto"
+  "andNotInto",
+  "materializeMany"
 ];
 var CountingMetricsSink = class _CountingMetricsSink {
   storage = { gets: 0, bytes: 0, totalMs: 0 };
@@ -586,6 +654,7 @@ var SegmentEngine = class {
       let total2 = 0;
       for (const [k, n] of cardinalities) {
         assertChunkKeyInRange(k);
+        if (n !== 0) assertChunkCardinalityInRange(n);
         total2 += n;
       }
       return total2;
@@ -625,7 +694,7 @@ var SegmentEngine = class {
   chunkWindow(seg, chunkKeys, gen, ramp) {
     return new ChunkWindow(
       chunkKeys,
-      (chunkKey) => this.storageChunk({ ...seg, chunkKey }, gen),
+      (chunkKey) => this.storageChunk({ ...seg, chunkKey }, gen, true),
       DEFAULT_INTERSECT_CONCURRENCY,
       ramp
     );
@@ -1092,7 +1161,9 @@ var SegmentEngine = class {
     }
     if (acc.isEmpty) return null;
     if (relevant.length > 0) {
-      const cuts = together ? fetched.slice(present.length) : await Promise.all(relevant.map((e) => this.storageChunk({ ...e.seg, chunkKey }, e.gen)));
+      const cuts = together ? fetched.slice(present.length) : await Promise.all(
+        relevant.map((e) => this.storageChunk({ ...e.seg, chunkKey }, e.gen, true))
+      );
       for (const cut of cuts) {
         if (cut === null) continue;
         acc.andNotInPlace(cut);
@@ -1106,7 +1177,7 @@ var SegmentEngine = class {
    * so a stream's take is made before anything is awaited: concurrent takes of one stream must be made in key order.
    */
   operandChunk(op, chunkKey) {
-    return op.streamed === void 0 ? this.storageChunk({ ...op.seg, chunkKey }, op.gen) : this.streamedChunk(op.streamed, chunkKey);
+    return op.streamed === void 0 ? this.storageChunk({ ...op.seg, chunkKey }, op.gen, true) : this.streamedChunk(op.streamed, chunkKey);
   }
   /**
    * `keys` of `seg` as a stream of coalesced ranges, or `undefined` when the read is per key: a source with no
@@ -1180,15 +1251,16 @@ var SegmentEngine = class {
     if (!streamed.opened) {
       const cache = this.cache;
       if (cache) {
-        const hit = cache.get(this.chunkCacheKey({ ...streamed.seg, chunkKey }, streamed.gen));
-        if (this.metricsOn) this.metrics.onEvent({ kind: "cache", hit: hit !== void 0 });
-        if (hit) return Promise.resolve(hit);
+        const ref = { ...streamed.seg, chunkKey };
+        const hit = cache.get(this.chunkCacheKey(ref, streamed.gen));
+        if (hit) return this.cachedIfCurrent(ref, streamed.gen, hit, true, streamed);
+        if (this.metricsOn) this.metrics.onEvent({ kind: "cache", hit: false });
       }
       this.startStream(streamed, chunkKey);
     } else if (streamed.inStream !== void 0 && !streamed.inStream.has(chunkKey)) {
       const ref = { ...streamed.seg, chunkKey };
       const hit = this.cache?.get(this.chunkCacheKey(ref, streamed.gen));
-      return hit ? Promise.resolve(hit) : this.storageChunk(ref, streamed.gen);
+      return hit ? this.cachedIfCurrent(ref, streamed.gen, hit, false, streamed) : this.storageChunk(ref, streamed.gen, true, false);
     }
     return streamed.stream.take(chunkKey).then((read) => {
       if (read.bytes === null) return null;
@@ -1210,6 +1282,28 @@ var SegmentEngine = class {
   streamedVersion(planned, read) {
     return planned === void 0 || this.storage.currentVersion === void 0 ? planned : read;
   }
+  /**
+   * `hit`, a chunk cached under the version a multi-chunk read planned under, if that is still the segment's version;
+   * else the chunk as it is now. A read resolves the segment again before it serves each chunk, which the source's
+   * stream does for the chunks it delivers; a chunk served from the cache is checked here, or a read whose chunks are
+   * all cached would go on serving the generation it planned under, an erased id included, for as long as it is pulled.
+   * Within `cache.genTtlMs` the source answers from its snapshot, so the check is a lookup, not a request. `report`:
+   * emit the `cache` event for this lookup, which a key counted when its stream opened does not. `streamed`: the read
+   * this chunk belongs to, which a move carries to the version now current, so the rest of it looks there: a read whose
+   * stream is not yet open reads the rest as one stream, not a chunk at a time.
+   */
+  async cachedIfCurrent(ref, planned, hit, report, streamed) {
+    const now = planned === void 0 ? void 0 : await this.cacheVersion(ref);
+    if (now === planned) {
+      if (report && this.metricsOn) this.metrics.onEvent({ kind: "cache", hit: true });
+      return hit;
+    }
+    if (streamed !== void 0 && streamed.gen === planned && now !== null) {
+      streamed.gen = now;
+      if (streamed.opened && this.storage.currentVersion === void 0) streamed.invalidated = true;
+    }
+    return this.storageChunk(ref, now, false, report);
+  }
   /** The cache key of a chunk: by the version it was read under, or by segment and key alone for a source with none. */
   chunkCacheKey(ref, version) {
     return version === void 0 ? chunkRefKey(ref) : chunkGenKey(ref, version);
@@ -1249,7 +1343,7 @@ var SegmentEngine = class {
     if (absent.length === 0) return;
     const named = absent.map((s) => s.namespace === void 0 ? `"${s.segment}"` : `"${s.namespace}/${s.segment}"`).join(", ");
     throw new ValidationError(
-      `${op}: operand ${named} names a segment that does not exist, so it would contribute nothing \u2014 an exclude would suppress no ids and an include would contribute none. Check the name and the namespace (a segment addressed without its \`namespace\` is a DIFFERENT segment). Pass \`allowAbsentOperands: true\` if you meant it.`
+      `${op}: operand ${named} names a segment that does not exist or was dropped, so it would contribute nothing \u2014 an exclude would suppress no ids and an include would contribute none. Check the name and the namespace (a segment addressed without its \`namespace\` is a DIFFERENT segment). Pass \`allowAbsentOperands: true\` if you meant it.`
     );
   }
   /**
@@ -1307,17 +1401,22 @@ var SegmentEngine = class {
    *
    * The returned instance is **shared** (it may be the cached one, and every caller that joined a read gets the same
    * one): callers read it or clone it, never mutate it.
+   *
+   * `recheck`: `gen` was planned for a read of many chunks, so a cached chunk is served only while it is still the
+   * segment's version ({@link cachedIfCurrent}). A point read resolves `gen` just before it asks, and passes none.
+   * `report`: emit the `cache` event for this lookup; a key already counted for this read does not.
    */
-  async storageChunk(ref, gen) {
+  async storageChunk(ref, gen, recheck = false, report = true) {
     if (gen === null) return null;
     const cacheKey = this.chunkCacheKey(ref, gen);
     if (this.cache) {
       const cached = this.cache.get(cacheKey);
       if (cached) {
-        if (this.metricsOn) this.metrics.onEvent({ kind: "cache", hit: true });
+        if (recheck) return this.cachedIfCurrent(ref, gen, cached, report);
+        if (report && this.metricsOn) this.metrics.onEvent({ kind: "cache", hit: true });
         return cached;
       }
-      if (this.metricsOn) this.metrics.onEvent({ kind: "cache", hit: false });
+      if (report && this.metricsOn) this.metrics.onEvent({ kind: "cache", hit: false });
     }
     const open4 = this.openReads.get(cacheKey);
     if (open4) return open4.read;
@@ -1657,7 +1756,7 @@ async function reconcile(ref, deps, options) {
     try {
       await deps.registry.compareAndSwap(ref, token, { keptGens: present });
     } catch (err) {
-      if (!(err instanceof WriteConflictError)) throw err;
+      if (!isWriteConflictError(err)) throw err;
     }
   }
   return deleted;
@@ -1741,11 +1840,11 @@ var STORE_LOAD_POINTER_READS = 2 + 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 },
+    retirement: { reads: 7, writes: 2, deletes: 1 },
     purge: { reads: 4, writes: 0, deletes: 2 }
   },
   tombstoning: {
-    retirement: { reads: 8, writes: 3, deletes: 0 },
+    retirement: { reads: 6, writes: 2, deletes: 0 },
     purge: { reads: 3, writes: 1, deletes: 0 }
   }
 });
@@ -1926,6 +2025,11 @@ function buildReport(input) {
   const storedGiB = storageBytes / GIB;
   const baseline = resolveBaseline(redis, storedGiB);
   const baselineUSD = baseline.monthlyUSD;
+  if ((input.workload.cacheHitRate ?? 0) > 1) {
+    throw new ValidationError(
+      `cacheHitRate must be a fraction from 0 to 1; got ${String(input.workload.cacheHitRate)}`
+    );
+  }
   const cacheHitRate = clamp01(
     requireFiniteNonNeg(input.workload.cacheHitRate ?? 0, "cacheHitRate")
   );
@@ -2060,7 +2164,31 @@ function buildReport(input) {
     assumptions: { cacheHitRate, pricingName: pricing.name, grounded, notes }
   };
 }
+function checkModelInputs(op, pricing, workload) {
+  const storage = pricing !== null && typeof pricing === "object" ? pricing.storage : void 0;
+  if (pricing !== void 0 && (storage === null || typeof storage !== "object")) {
+    throw new ValidationError(`${op}: pricing must be a profile with a storage price list`);
+  }
+  if (workload !== void 0 && workload !== null && (typeof workload !== "object" || Array.isArray(workload))) {
+    throw new ValidationError(`${op}: workload must be an object`);
+  }
+}
 function estimateCost(input) {
+  if (input === null || typeof input !== "object") {
+    throw new ValidationError("estimateCost: input must be an object such as { segments }");
+  }
+  if (!Array.isArray(input.segments)) {
+    throw new ValidationError(
+      "estimateCost: segments must be an array of { sizeBytes } or { cardinality }"
+    );
+  }
+  for (let i = 0; i < input.segments.length; i++) {
+    const spec = input.segments[i];
+    if (spec === null || typeof spec !== "object") {
+      throw new ValidationError(`estimateCost: segments[${i}] must be an object`);
+    }
+  }
+  checkModelInputs("estimateCost", input.pricing, input.workload);
   const pricing = input.pricing ?? AWS_US_EAST_1_ONDEMAND;
   const workload = input.workload ?? {};
   let storageBytes = 0;
@@ -2075,6 +2203,7 @@ function estimateCost(input) {
   return buildReport({ storageBytes, workload, pricing, grounded: false, sizesFromCardinality });
 }
 function groundedReport(input) {
+  checkModelInputs("costReport", input.pricing, input.workload);
   return buildReport({
     storageBytes: input.storageBytes,
     workload: input.workload ?? {},
@@ -2185,7 +2314,22 @@ function requireCodec(codec, api) {
 var DEFAULT_NDJSON_BATCH_BYTES = 64 * 1024;
 var errMessage = (err) => err instanceof Error ? err.message : String(err);
 async function runExport(reader, registry, sink, options = {}) {
+  if (sink === null || typeof sink !== "object" || typeof sink.open !== "function") {
+    throw new ValidationError(
+      "runExport: the sink must be an object with an open(ref, ext) method"
+    );
+  }
+  options ??= {};
   if (options.namespace !== void 0) validateUserNamespace(options.namespace);
+  if (options.format !== void 0 && options.format !== "roaring" && options.format !== "ndjson") {
+    throw new ValidationError(`runExport: format must be 'roaring' or 'ndjson'`);
+  }
+  const batch = options.ndjsonBatchBytes;
+  if (batch !== void 0 && (typeof batch !== "number" || !Number.isSafeInteger(batch) || batch < 1)) {
+    throw new ValidationError(
+      "runExport: ndjsonBatchBytes must be a whole number of bytes, 1 or more"
+    );
+  }
   const format = options.format ?? "roaring";
   const ext = format === "roaring" ? ".roaring" : ".ndjson";
   const batchCap = options.ndjsonBatchBytes ?? DEFAULT_NDJSON_BATCH_BYTES;
@@ -2389,6 +2533,7 @@ var MemoryRegistryDriver = class {
     return { token };
   }
   async *list(namespace) {
+    if (namespace !== void 0) validateSegmentRef({ segment: "x", namespace });
     for (const row of this.rows.values()) {
       if (namespace === void 0 || row.namespace === namespace) yield structuredClone(row);
     }
@@ -2579,6 +2724,18 @@ async function fsyncDir(dir) {
   } catch {
   }
 }
+async function writeAll(handle, bytes) {
+  let offset = 0;
+  while (offset < bytes.length) {
+    const { bytesWritten } = await handle.write(bytes, offset, bytes.length - offset);
+    if (bytesWritten <= 0) {
+      throw Object.assign(new Error("a write made no progress: the device is full"), {
+        code: "ENOSPC"
+      });
+    }
+    offset += bytesWritten;
+  }
+}
 
 // src/drivers/localfs/exact-case.ts
 function firstCaseDifference(expected, actual) {
@@ -2718,7 +2875,7 @@ var LocalFsStorageDriver = class {
     let size = 0;
     const sink = {
       async write(bytes) {
-        await handle.write(bytes);
+        await writeAll(handle, bytes);
         hash.update(bytes);
         size += bytes.length;
       }
@@ -2830,8 +2987,8 @@ var LocalFsStorageDriver = class {
 // src/drivers/localfs/registry.ts
 import { constants as FS3 } from "node:fs";
 import { randomUUID as randomUUID2 } from "node:crypto";
-import { mkdir as mkdir2, open as open3, readdir as readdir3, realpath as realpath2, rename, unlink as unlink2 } from "node:fs/promises";
-import { basename, dirname as dirname3, join as join3, resolve as resolve2 } from "node:path";
+import { mkdir as mkdir2, open as open3, opendir, readdir as readdir3, realpath as realpath2, rename, unlink as unlink2 } from "node:fs/promises";
+import { basename, dirname as dirname3, join as join3, relative as relative2, resolve as resolve2 } from "node:path";
 var DEFAULT_MAX_ROW_BYTES = 1 * 1024 * 1024;
 var rowChains = /* @__PURE__ */ new Map();
 async function rowLockKey(path) {
@@ -2868,7 +3025,7 @@ var LocalFsRegistryDriver = class {
     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));
+    const env = await this.readRow(registryRowPath(this.root, ref), ref);
     return env && !env.deleted ? env.record : null;
   }
   async create(ref, record) {
@@ -2876,7 +3033,7 @@ var LocalFsRegistryDriver = class {
     const path = registryRowPath(this.root, ref);
     assertRegistryNamesFit(ref);
     return this.withRowLock(path, async () => {
-      const current = await this.readRow(path);
+      const current = await this.readRow(path, ref);
       if (current !== null && !current.deleted) {
         throw new WriteConflictError(`registry row already exists for segment ${ref.segment}`);
       }
@@ -2894,7 +3051,7 @@ var LocalFsRegistryDriver = class {
     const path = registryRowPath(this.root, ref);
     assertRegistryNamesFit(ref);
     return this.withRowLock(path, async () => {
-      const current = await this.readRow(path);
+      const current = await this.readRow(path, ref);
       if (current === null || current.deleted || current.record.token !== expected) {
         throw new WriteConflictError(`OCC token mismatch for registry row ${ref.segment}`);
       }
@@ -2911,17 +3068,18 @@ var LocalFsRegistryDriver = class {
     for (const ns of await this.namespaceDirs(namespace)) {
       const dir = registryDir(this.root, ns);
       if (await this.exactCase.differs(dir)) continue;
-      let names;
+      let entries;
       try {
-        names = await readdir3(dir);
+        entries = await opendir(dir);
       } catch (err) {
         if (isAbsent(err)) continue;
         throw mapFsError(err);
       }
-      for (const name of names) {
-        const segment = parseRegistryRow(name);
+      for await (const entry of entries) {
+        const segment = parseRegistryRow(entry.name);
         if (segment === null) continue;
-        const env = await this.readRow(registryRowPath(this.root, { namespace: ns, segment }));
+        const ref = { namespace: ns, segment };
+        const env = await this.readRow(registryRowPath(this.root, ref), ref);
         if (env && !env.deleted) yield env.record;
       }
     }
@@ -2929,7 +3087,7 @@ var LocalFsRegistryDriver = class {
   async delete(ref, expected) {
     const path = registryRowPath(this.root, ref);
     return this.withRowLock(path, async () => {
-      const current = await this.readRow(path);
+      const current = await this.readRow(path, ref);
       if (expected !== void 0) {
         if (current === null || current.deleted || current.record.token !== expected) {
           throw new WriteConflictError(`OCC token mismatch for registry row ${ref.segment}`);
@@ -2971,7 +3129,8 @@ var LocalFsRegistryDriver = class {
     }
     return namespaces;
   }
-  async readRow(path) {
+  /** Read the row at `path`, which must be the row of `ref`: one that names another segment is refused. */
+  async readRow(path, ref) {
     let handle;
     try {
       if (await this.exactCase.differs(path)) return null;
@@ -2986,7 +3145,7 @@ var LocalFsRegistryDriver = class {
         throw new IntegrityError(`registry row ${size}B exceeds cap ${DEFAULT_MAX_ROW_BYTES}B`);
       }
       const text = (await handle.readFile()).toString("utf8");
-      return parseRegistryEnvelope(text, path);
+      return parseRegistryEnvelope(text, relative2(this.root, path), ref);
     } finally {
       await handle.close();
     }
@@ -3008,11 +3167,16 @@ var LocalFsRegistryDriver = class {
       throw mapFsError(err);
     }
     try {
-      await handle.write(out);
+      await writeAll(handle, out);
       await handle.sync();
-    } finally {
-      await handle.close();
+    } catch (err) {
+      await handle.close().catch(() => {
+      });
+      await unlink2(tmp).catch(() => {
+      });
+      throw mapFsError(err);
     }
+    await handle.close();
     await rename(tmp, path).catch(async (err) => {
       await unlink2(tmp).catch(() => {
       });
@@ -3063,36 +3227,6 @@ var LocalFsStorage = class {
   registry;
 };
 
-// src/core/audit.ts
-var NOOP_AUDIT = {
-  onEvent() {
-  }
-};
-function safeAudit(sink) {
-  if (sink === NOOP_AUDIT) return sink;
-  return {
-    onEvent(event) {
-      try {
-        sink.onEvent(event);
-      } catch {
-      }
-    }
-  };
-}
-var RecordingAuditSink = class {
-  recorded = [];
-  onEvent(event) {
-    this.recorded.push(event);
-  }
-  /** An independent copy of the recorded events, in emission order. */
-  snapshot() {
-    return this.recorded.map((e) => ({ ...e }));
-  }
-  reset() {
-    this.recorded.length = 0;
-  }
-};
-
 // src/core/cooperative.ts
 var YIELD_EVERY = 1024;
 function yieldEvery(clock, everyN = YIELD_EVERY) {
@@ -3593,8 +3727,8 @@ var CrbmReader = class _CrbmReader {
   /**
    * Range-GET one chunk's payload, verifying its CRC32C before returning. Returns `null` if the chunk is
    * absent. Throws `IntegrityError` on a CRC mismatch (the bytes must never reach the native
-   * deserializer). The returned buffer is a **read-only view** owned by the reader/driver — callers must
-   * not mutate it.
+   * deserializer). The returned bytes may be shared (a small generation's chunks are kept by the reader and handed out
+   * again), so callers must not change them.
    */
   async getChunk(chunkKey) {
     const slot = this.slotOf(chunkKey);
@@ -3682,7 +3816,8 @@ var CrbmReader = class _CrbmReader {
    * others; `options.now` times each request for `options.onRequest`, which hears of every range request that was sent, once, when
    * it settles: taken, abandoned after the consumer stopped, or failed (a reader has no clock of its own, so `ms` is 0
    * without one).
-   * A plain chunk is a writable view into the range it was read in: copy a chunk to keep it.
+   * A plain chunk is a view into the range it was read in, so keeping it keeps that whole range: copy a chunk to keep it
+   * alone. Callers must not change it, as with {@link getChunk}.
    *
    * A stream that fails (a range that errors, a chunk that fails its check) raises at once and sends nothing further:
    * the ranges it still had in flight finish in the background, are not retried and never raise. Its `settled()`
@@ -3745,7 +3880,7 @@ var CrbmReader = class _CrbmReader {
           moved = bytes.length;
           if (bytes.length !== read.length) {
             throw new IntegrityError(
-              `.crbm range [${read.offset}, +${read.length}) read short (${bytes.length} bytes)`
+              `.crbm range [${read.offset}, +${read.length}) answered ${bytes.length} bytes, not the ${read.length} asked for`
             );
           }
           return { bytes };
@@ -3953,7 +4088,7 @@ var CrbmWriter = class {
   constructor(sink, options) {
     this.sink = sink;
     this.options = options;
-    if (!Number.isInteger(options.generation) || options.generation < 0) {
+    if (!Number.isSafeInteger(options.generation) || options.generation < 0) {
       throw new ValidationError(
         `generation must be a non-negative integer; got ${options.generation}`
       );
@@ -3995,6 +4130,11 @@ var CrbmWriter = class {
       );
     }
     if (payload.length === 0) throw new ValidationError("chunk payload must be non-empty");
+    if (payload.length > DEFAULT_MAX_BITMAP_BYTES) {
+      throw new ValidationError(
+        `chunk payload of ${payload.length} bytes is over the ${DEFAULT_MAX_BITMAP_BYTES}-byte cap a reader opens`
+      );
+    }
     await this.ensurePreamble();
     const crypto = this.options.crypto;
     const stored = crypto ? framed(crypto.aead.seal(payload, crypto.aadFor(chunkKey))) : payload;
@@ -4190,14 +4330,14 @@ function overCap(what, length) {
     `${what} is ${length} bytes, more than any canonical 32-bit bitmap serializes to (${MAX_SERIALIZED_LOAD_BYTES}). If it was serialized from a bitmap, call runOptimize() on the bitmap first.`
   );
 }
-function prepareLoadInput(input, codec, subject = "a load") {
+function prepareLoadInput(input, codec) {
   if (typeof input !== "object" || input === null) {
-    throw new ValidationError(`${subject} takes ids, { serialized } or { bitmap }`);
+    throw new ValidationError("a load takes ids, { serialized } or { bitmap }");
   }
   const tag = tagOf(input);
   if (tag === "Uint8Array" || tag === "Uint8ClampedArray") {
     throw new ValidationError(
-      `${subject}'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.`
+      `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;
@@ -4220,7 +4360,7 @@ function prepareLoadInput(input, codec, subject = "a load") {
     return new DecodedLoadInput(decodeSerialized(bitmap.serialize("portable"), codec, what));
   }
   throw new ValidationError(
-    `${subject} takes ids (an iterable of integers), { serialized } or { bitmap }, as the only key; got an object with keys [${keys.join(", ")}].${subject === "a load" ? " Load options go in the next argument." : ""}`
+    `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 decodeSerialized(bytes, codec, what = "the buffer") {
@@ -4395,10 +4535,16 @@ function once(fn) {
   };
 }
 var readerIsOf = (reader, live) => reader.generation === live.target.generation && reader.lineage === live.target.lineage;
+async function versionNamed(snap) {
+  if (snap.target === void 0) {
+    const reader = await snap.reader;
+    return reader === null ? null : versionOf(reader.generation, reader.lineage);
+  }
+  const live = await snap.target;
+  return live === null ? null : versionOf(live.target.generation, live.target.lineage);
+}
 function describe(reader) {
-  let cardinality = 0;
-  for (const n of reader.cardinalities().values()) cardinality += n;
-  return { cardinality, metadata: reader.metadata };
+  return { cardinality: reader.count(), metadata: reader.metadata };
 }
 var Snapshot = class _Snapshot {
   constructor(target, open4, prior) {
@@ -4460,6 +4606,7 @@ var Snapshot = class _Snapshot {
 var SNAPSHOT_BASE_BYTES = 256;
 var BULK_FLUSH_IDS = 1 << 20;
 var YIELD_EVERY_IDS = 1 << 14;
+var RECENT_KEYS = 8;
 var CrbmStorageChunkSource = class {
   constructor(driver, options = {}) {
     this.driver = driver;
@@ -4488,8 +4635,13 @@ var CrbmStorageChunkSource = class {
     this.keystore = keystore;
     this.requireEncryption = requireEncryption ?? false;
     this.readerOptions = readerOptions;
-    const refreshes = registry !== void 0 && clock !== void 0 && (currentGenTtlMs ?? DEFAULT_CURRENT_GEN_TTL_MS) > 0;
-    this.keepChunkBytesUpTo = refreshes ? Math.floor(
+    if (currentGenTtlMs !== void 0 && currentGenTtlMs !== null && (typeof currentGenTtlMs !== "number" || !Number.isFinite(currentGenTtlMs) || currentGenTtlMs < 0)) {
+      throw new ValidationError(
+        `cache.genTtlMs must be a finite number of milliseconds, 0 or more (0: no timed refresh); got ${typeof currentGenTtlMs === "number" ? String(currentGenTtlMs) : `a ${typeof currentGenTtlMs}`}`
+      );
+    }
+    this.timedRefresh = registry !== void 0 && clock !== void 0 && (currentGenTtlMs ?? DEFAULT_CURRENT_GEN_TTL_MS) > 0;
+    this.keepChunkBytesUpTo = this.timedRefresh ? Math.floor(
       (maxOpenIndexBytes ?? DEFAULT_MAX_OPEN_INDEX_BYTES) / (maxOpenSegments ?? DEFAULT_MAX_OPEN_SEGMENTS)
     ) : 0;
     this.clock = clock;
@@ -4559,12 +4711,33 @@ var CrbmStorageChunkSource = class {
   keepChunkBytesUpTo;
   clock;
   currentGenTtlMs;
+  /**
+   * Whether the segment's pointer is re-read on a timer: it needs a clock (the TTL), a registry (the cheap row read; with
+   * none, resolving is a listing of the bucket) and a TTL above 0. It decides the keeping of chunk bytes, the TTL lapse
+   * and the refresh interval the cost report prices, so it is decided once.
+   */
+  timedRefresh;
+  /**
+   * The last few segments' keys, newest first. A stream asks for its segment's snapshot before every cached chunk it
+   * serves, and a combine alternates between a few operands, so comparing two names beats encoding them again, which
+   * cost about a microsecond a chunk.
+   */
+  recentKeys = [];
+  keyOf(ref) {
+    for (const k of this.recentKeys) {
+      if (k.segment === ref.segment && k.namespace === ref.namespace) return k.key;
+    }
+    const key = segmentKey(ref);
+    this.recentKeys.unshift({ namespace: ref.namespace, segment: ref.segment, key });
+    if (this.recentKeys.length > RECENT_KEYS) this.recentKeys.pop();
+    return key;
+  }
   /**
    * 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 key = this.keyOf(ref);
     const existing = this.snapshots.get(key);
     if (existing === void 0) {
       return this.install(
@@ -4656,10 +4829,19 @@ var CrbmStorageChunkSource = class {
    * this.
    */
   get pointerRefreshMs() {
-    return this.clock !== void 0 && this.registry !== void 0 ? this.currentGenTtlMs : 0;
+    return this.timedRefresh ? this.currentGenTtlMs : 0;
+  }
+  /**
+   * Whether a stream reading from `snap` must resolve its segment again before its next chunk, as a read of one chunk
+   * would: the snapshot's TTL has lapsed, an invalidation has happened since `epoch`, or the snapshot is no longer the
+   * one the reader cache holds for the segment (it let it go, or another read installed a newer one). Else nothing can
+   * have moved it, and the check costs a compare and a lookup.
+   */
+  mayHaveMoved(key, snap, epoch) {
+    return this.invalidations !== epoch || this.expired(snap.installedAtMs) || this.snapshots.get(key) !== snap;
   }
   expired(installedAtMs) {
-    return this.clock !== void 0 && this.registry !== void 0 && this.currentGenTtlMs > 0 && this.clock.now() - installedAtMs >= this.currentGenTtlMs;
+    return this.timedRefresh && this.now() - installedAtMs >= this.currentGenTtlMs;
   }
   /**
    * The segment's current generation number — the engine keys its chunk cache by this so a generation bump
@@ -4743,6 +4925,7 @@ var CrbmStorageChunkSource = class {
    * once the swept one is gone is exactly what a pin taken now should hold. One retry, then propagate.
    */
   async pinGeneration(ref, lease) {
+    validateUserRef(ref);
     for (let moved = 0; ; moved++) {
       try {
         try {
@@ -4774,6 +4957,7 @@ var CrbmStorageChunkSource = class {
    * of the row's summary against it, since that check is made where the row's own generation is read.
    */
   async pinGenerationAt(ref, at, lease) {
+    validateUserRef(ref);
     const { generation, fingerprint } = at;
     const gone = (why) => new NotFoundError(
       `segment "${ref.segment}" generation ${generation} cannot be pinned: ${why}`
@@ -5060,7 +5244,11 @@ var CrbmStorageChunkSource = class {
    * tell apart.
    */
   async exists(ref) {
-    if (this.registry !== void 0) return await this.registry.get(ref) !== null;
+    validateUserRef(ref);
+    if (this.registry !== void 0) {
+      const row = await this.registry.get(ref);
+      return row !== null && row.status !== "destroyed";
+    }
     for await (const key of this.driver.list(ref)) {
       void key;
       return true;
@@ -5169,7 +5357,7 @@ var CrbmStorageChunkSource = class {
     const keystore = this.keystore;
     if (keystore === void 0) {
       throw new KeyUnavailableError(
-        `segment "${ref.segment}" is encrypted but this CrbmStorageChunkSource has no keystore`
+        `segment "${ref.segment}" is encrypted, and the store reading it was built with no keystore (encryption.keystore)`
       );
     }
     const aead = await (unwrap ?? (() => keystore.openDek(wrappedDeks)))();
@@ -5193,10 +5381,12 @@ var CrbmStorageChunkSource = class {
     for (const chunkKey of keys) validateChunkRef({ ...ref, chunkKey });
     validateChunkKeyOrder(keys);
     const retry = options?.retry;
+    const key = segmentKey(ref);
     let yielded = 0;
     let healed = false;
     for (; ; ) {
       let snap = this.liveSnapshot(ref);
+      let epoch = this.invalidations;
       let pending = snap.reader;
       let chunks;
       try {
@@ -5227,14 +5417,24 @@ var CrbmStorageChunkSource = class {
         let movedOn = false;
         try {
           while (await pull.advance()) {
-            const live = this.liveSnapshot(ref);
-            if (live !== snap) {
-              const now = await live.reader;
-              if (now === null || versionOf(now.generation, now.lineage) !== version) {
-                movedOn = true;
-                break;
+            if (this.mayHaveMoved(key, snap, epoch)) {
+              const live = this.liveSnapshot(ref);
+              if (live !== snap) {
+                let now;
+                try {
+                  now = await versionNamed(live);
+                } catch (err) {
+                  if (!isTransientError(err)) throw err;
+                  movedOn = true;
+                  break;
+                }
+                if (now !== version) {
+                  movedOn = true;
+                  break;
+                }
+                snap = live;
               }
-              snap = live;
+              epoch = this.invalidations;
             }
             yield pull.take((chunk) => {
               yielded += 1;
@@ -5254,7 +5454,7 @@ var CrbmStorageChunkSource = class {
         if (!isNotFoundError(err) && !await this.replacedUnder(ref, pending, err, retry))
           throw err;
         await chunks?.settled();
-        this.dropStale(segmentKey(ref), snap);
+        this.dropStale(key, snap);
         healed = true;
       }
     }
@@ -5795,6 +5995,11 @@ async function provesOwnObject(storage, key, fingerprint) {
     throw err;
   }
 }
+function cleartextUnderRequiredEncryption(ref, currentGen) {
+  return new ValidationError(
+    `requireEncryption: segment "${ref.segment}" already has generation ${currentGen} in cleartext, so this load cannot be encrypted \u2014 encryption is chosen when a segment is first loaded. Load into a new segment with the keystore wired, then drop this one.`
+  );
+}
 async function bulkLoadAhead(driver, ref, ahead, ids, options = {}) {
   if (options.keystore === void 0 && options.requireEncryption === true) {
     throw new ValidationError("requireEncryption: a load needs a keystore to write encrypted");
@@ -5831,11 +6036,8 @@ async function bulkLoadAhead(driver, ref, ahead, ids, options = {}) {
       const aead = early !== void 0 && sameKeys(early.wrapped, existing.wrappedDeks) ? await early.aead : await options.keystore.openDek(existing.wrappedDeks);
       crypto = { aead, aadFor: (scope) => aadFor(key, key.generation, scope) };
     } else if (existing !== null && existing.currentGen !== null) {
-      if (options.requireEncryption === true) {
-        throw new ValidationError(
-          `requireEncryption: segment "${ref.segment}" already has generation ${existing.currentGen} in cleartext, so this load cannot be encrypted \u2014 encryption is chosen when a segment is first loaded. Load into a new segment with the keystore wired, then drop this one.`
-        );
-      }
+      if (options.requireEncryption === true)
+        throw cleartextUnderRequiredEncryption(ref, existing.currentGen);
     } else {
       const minted = await options.keystore.createDek();
       newWrapped = minted.wrapped;
@@ -6147,6 +6349,30 @@ function applyJitter(policy, delayMs, rng) {
 function retryRead(op, retry) {
   return retry === void 0 ? op() : withRetry(op, retry.policy ?? DEFAULT_RETRY_POLICY, retry);
 }
+function checkedRetryPolicy(policy) {
+  const { maxAttempts, baseDelayMs, maxDelayMs, backoffFactor, jitter } = policy;
+  const fail = (field, rule, v) => {
+    throw new ValidationError(
+      `retry.${field} must be ${rule}; got ${typeof v === "number" ? String(v) : `a ${typeof v}`}`
+    );
+  };
+  if (typeof maxAttempts !== "number" || !Number.isFinite(maxAttempts) || maxAttempts < 1) {
+    fail("maxAttempts", "a finite number >= 1", maxAttempts);
+  }
+  if (typeof baseDelayMs !== "number" || !Number.isFinite(baseDelayMs) || baseDelayMs < 0) {
+    fail("baseDelayMs", "a finite number of milliseconds >= 0", baseDelayMs);
+  }
+  if (typeof maxDelayMs !== "number" || !Number.isFinite(maxDelayMs) || maxDelayMs < 0) {
+    fail("maxDelayMs", "a finite number of milliseconds >= 0", maxDelayMs);
+  }
+  if (typeof backoffFactor !== "number" || !Number.isFinite(backoffFactor) || backoffFactor < 1) {
+    fail("backoffFactor", "a finite number >= 1", backoffFactor);
+  }
+  if (jitter !== "full" && jitter !== "none") {
+    throw new ValidationError(`retry.jitter must be 'full' or 'none'`);
+  }
+  return policy;
+}
 async function withRetry(op, policy, deps) {
   const retryable = deps.isRetryable ?? isTransientError;
   if (!Number.isFinite(policy.maxAttempts) || policy.maxAttempts < 1) {
@@ -6174,6 +6400,106 @@ async function withRetry(op, policy, deps) {
 }
 
 // src/core/load.ts
+function checkedGuard(guard, where) {
+  if (guard === void 0 || guard === null) return void 0;
+  const shown2 = (v) => typeof v === "number" ? String(v) : Array.isArray(v) ? "an array" : `a ${typeof v}`;
+  if (typeof guard !== "object" || Array.isArray(guard)) {
+    throw new ValidationError(
+      `${where}guard must be an object of bounds, such as { minRetained: 0.5 }; got ${shown2(guard)}`
+    );
+  }
+  const bounds = guard;
+  const unknown = Object.keys(bounds).filter(
+    (k) => k !== "minCardinality" && k !== "minRetained" && k !== "maxGrowth" && bounds[k] !== void 0
+  );
+  if (unknown.length > 0) {
+    throw new ValidationError(
+      `${where}guard: unknown option${unknown.length > 1 ? "s" : ""} ${unknown.map((k) => `"${k}"`).join(", ")}; it takes { minCardinality, minRetained, maxGrowth }`
+    );
+  }
+  const { minCardinality, minRetained, maxGrowth } = guard;
+  if (minCardinality !== void 0 && (!Number.isInteger(minCardinality) || minCardinality < 0)) {
+    throw new ValidationError(
+      `${where}guard.minCardinality must be a non-negative integer; got ${shown2(minCardinality)}`
+    );
+  }
+  if (minRetained !== void 0 && (!Number.isFinite(minRetained) || minRetained < 0 || minRetained > 1)) {
+    throw new ValidationError(
+      `${where}guard.minRetained must be a fraction in 0..1; got ${shown2(minRetained)}`
+    );
+  }
+  if (maxGrowth !== void 0 && (!Number.isFinite(maxGrowth) || maxGrowth !== 0 && maxGrowth < 1)) {
+    throw new ValidationError(
+      `${where}guard.maxGrowth must be 0 (no bound) or a factor of at least 1; got ${shown2(maxGrowth)}`
+    );
+  }
+  return Object.freeze({
+    ...minCardinality === void 0 ? {} : { minCardinality },
+    ...minRetained === void 0 ? {} : { minRetained },
+    ...maxGrowth === void 0 ? {} : { maxGrowth }
+  });
+}
+function guardRefusal(cardinality, before, guard, allowEmpty) {
+  if (cardinality === 0 && allowEmpty !== true && (before ?? 0) > 0) return "empty";
+  if (guard?.minCardinality !== void 0 && cardinality < guard.minCardinality) {
+    return "min-cardinality";
+  }
+  if (guard?.minRetained !== void 0 && before !== null && cardinality < before * guard.minRetained) {
+    return "min-retained";
+  }
+  if (guard?.maxGrowth !== void 0 && guard.maxGrowth !== 0 && before !== null && before > 0 && cardinality > before * guard.maxGrowth) {
+    return "max-growth";
+  }
+  return void 0;
+}
+async function judgeLoad(ref, cardinality, deps, options = {}) {
+  validateUserRef(ref);
+  if (!Number.isSafeInteger(cardinality) || cardinality < 0) {
+    throw new ValidationError("judgeLoad: cardinality must be a non-negative integer");
+  }
+  const guard = checkedGuard(options.guard, "");
+  assertRegistryCanWrite(deps.registry, "load");
+  if (deps.requireEncryption === true && deps.keystore === void 0) {
+    throw new ValidationError("requireEncryption: a load needs a keystore to write encrypted");
+  }
+  const row = await deps.registry.get(ref);
+  if (row?.status === "destroyed") {
+    throw new ValidationError(
+      `segment "${ref.segment}" is destroyed (crypto-shredded) \u2014 refusing to write; use a new segment`
+    );
+  }
+  const cleartext = row?.wrappedDeks === void 0 || row.wrappedDeks.length === 0;
+  if (deps.requireEncryption === true && row !== null && row.currentGen !== null && cleartext) {
+    throw cleartextUnderRequiredEncryption(ref, row.currentGen);
+  }
+  const wrapped = row?.wrappedDeks;
+  let aead;
+  if (row !== null && wrapped !== void 0 && wrapped.length > 0) {
+    if (deps.keystore === void 0) {
+      throw new KeyUnavailableError(
+        `segment "${ref.segment}" is encrypted but load was given no keystore`
+      );
+    }
+    aead = Promise.resolve(await deps.keystore.openDek(wrapped));
+  }
+  let current;
+  try {
+    current = await currentCardinality(ref, deps, row, aead);
+  } catch (err) {
+    if (sizeNeeded(guard, options.allowEmpty)) throw err;
+    current = { cardinality: null, fromSummary: false };
+  }
+  const wouldRefuse = guardRefusal(cardinality, current.cardinality, guard, options.allowEmpty);
+  const openedObject = row !== null && row.currentGen !== null && !current.fromSummary;
+  return {
+    cardinalityBefore: current.cardinality,
+    ...wouldRefuse === void 0 ? {} : { wouldRefuse },
+    reads: openedObject ? 2 : 1
+  };
+}
+function sizeNeeded(guard, allowEmpty) {
+  return guard?.minRetained !== void 0 || guard?.maxGrowth !== void 0 || allowEmpty !== true;
+}
 function settled(promise) {
   promise.catch(() => void 0);
   return promise;
@@ -6232,26 +6558,13 @@ function loadSegmentChunks(ref, chunks, deps, options = {}) {
 }
 async function runLoad(ref, prepare, deps, options) {
   validateUserRef(ref);
+  checkedAuditSink(options.audit, "load");
   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)}`);
   }
-  const guard = options.guard;
-  if (guard?.minCardinality !== void 0) {
-    const m = guard.minCardinality;
-    if (!Number.isInteger(m) || m < 0) {
-      throw new ValidationError(
-        `guard.minCardinality must be a non-negative integer; got ${String(m)}`
-      );
-    }
-  }
-  if (guard?.minRetained !== void 0) {
-    const s = guard.minRetained;
-    if (!Number.isFinite(s) || s < 0 || s > 1) {
-      throw new ValidationError(`guard.minRetained must be a fraction in 0..1; got ${String(s)}`);
-    }
-  }
+  const guard = checkedGuard(options.guard, "");
   const metadata = copiedMetadata(options.metadata, (message) => {
     throw new ValidationError(message);
   });
@@ -6264,7 +6577,7 @@ async function runLoad(ref, prepare, deps, options) {
   const wrappedKeys = row?.wrappedDeks;
   const keystore = deps.keystore;
   const unwrapped = row !== null && row.status !== "destroyed" && wrappedKeys !== void 0 && wrappedKeys.length > 0 && keystore !== void 0 ? { wrapped: wrappedKeys, aead: settled((async () => keystore.openDek(wrappedKeys))()) } : void 0;
-  const needsBefore = guard?.minRetained !== void 0 || options.allowEmpty !== true;
+  const needsBefore = sizeNeeded(guard, options.allowEmpty);
   const current = needsBefore ? await currentCardinality(ref, deps, row, unwrapped?.aead) : { cardinality: null, fromSummary: false };
   const before = current.cardinality;
   const numbering = settled(nextLoadGeneration(ref, deps, row));
@@ -6323,8 +6636,9 @@ async function runLoad(ref, prepare, deps, options) {
     }
   };
   let unanswered = false;
+  const tidy = () => reclaim().catch(() => void 0);
   const refuse = async (reason) => {
-    await reclaim();
+    await tidy();
     audit.onEvent({
       kind: "segment.load-refused",
       segment: ref.segment,
@@ -6346,15 +6660,8 @@ async function runLoad(ref, prepare, deps, options) {
       collected: []
     };
   };
-  if (written.cardinality === 0 && options.allowEmpty !== true && (before ?? 0) > 0) {
-    return refuse("empty");
-  }
-  if (guard?.minCardinality !== void 0 && written.cardinality < guard.minCardinality) {
-    return refuse("min-cardinality");
-  }
-  if (guard?.minRetained !== void 0 && before !== null) {
-    if (written.cardinality < before * guard.minRetained) return refuse("min-retained");
-  }
+  const refusal = guardRefusal(written.cardinality, before, guard, options.allowEmpty);
+  if (refusal !== void 0) return refuse(refusal);
   const leasesNow = deps.clock === void 0 ? void 0 : () => deps.clock.now();
   let published;
   try {
@@ -6370,8 +6677,8 @@ async function runLoad(ref, prepare, deps, options) {
       // 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
+      // that appeared in between. `before` was `null`, so the empty, `minRetained` and `maxGrowth` 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 } : {},
@@ -6386,7 +6693,7 @@ async function runLoad(ref, prepare, deps, options) {
       }
     });
   } catch (err) {
-    if (isValidationError(err) || err instanceof KeyUnavailableError) await reclaim();
+    if (isValidationError(err) || isKeyUnavailableError(err)) await tidy();
     throw err;
   }
   if (!published.published) return refuse("superseded");
@@ -6925,9 +7232,12 @@ var FeedCursor = class {
     this.finished = true;
   }
   // ---- the checks -------------------------------------------------------------------------------------------
-  refuse(key, operand, why) {
+  /** How many records the feed has handed over, the one being read included: what names a record in an error. */
+  records = 0;
+  /** Refuse the record being read, named by its position in the feed: its key narrows the ids it holds to a range. */
+  refuse(operand, why) {
     throw new ValidationError(
-      `materializeMany feed: record at key ${String(key)}${operand === void 0 ? "" : `, operand "${operand}"`}: ${why}`
+      `materializeMany feed: record ${this.records}${operand === void 0 ? "" : `, operand "${operand}"`}: ${why}`
     );
   }
   charge(bytes) {
@@ -6944,20 +7254,17 @@ var FeedCursor = class {
     this.deps.release(bytes);
   }
   async convert(record) {
+    this.records += 1;
     if (typeof record !== "object" || record === null) {
-      this.refuse("?", void 0, "a record is an object with a key and operands");
+      this.refuse(void 0, "a record is an object with a key and operands");
     }
     const key = record.key;
     const operands = record.operands;
     if (typeof key !== "number" || !Number.isInteger(key) || key < 0 || key >= KEY_IDS) {
-      this.refuse("?", void 0, "the key must be an integer from 0 to 65535");
+      this.refuse(void 0, "the key must be an integer from 0 to 65535");
     }
     if (key < this.prevKey) {
-      this.refuse(
-        key,
-        void 0,
-        `the key is below the previous record's (${this.prevKey}): keys never go back`
-      );
+      this.refuse(void 0, `the key is below the previous record's: keys never go back`);
     }
     if (key !== this.prevKey) {
       for (const i of this.touched) this.seen[i] = 0;
@@ -6966,7 +7273,6 @@ var FeedCursor = class {
     }
     if (typeof operands !== "object" || operands === null || !isPlainObject(operands)) {
       this.refuse(
-        key,
         void 0,
         "operands must be a plain object of fed operand name to Uint32Array (not a Map, an array or a class instance)"
       );
@@ -6976,31 +7282,29 @@ var FeedCursor = class {
     const charged = [];
     try {
       for (const name of Reflect.ownKeys(operands)) {
-        if (typeof name !== "string") this.refuse(key, void 0, "operands has a symbol key");
+        if (typeof name !== "string") this.refuse(void 0, "operands has a symbol key");
         const at = this.index.get(name);
         if (at === void 0) {
-          this.refuse(key, name, "not a declared fed operand (it is not in feed.names)");
+          this.refuse(name, "not a declared fed operand (it is not in feed.names)");
         }
         const value = operands[name];
         const view = plainUint32(value);
         if (view === void 0) {
           this.refuse(
-            key,
             name,
             "the ids must be a Uint32Array (any other typed array, array or look-alike is refused)"
           );
         }
-        if (view === "detached") this.refuse(key, name, "the array's buffer is detached");
+        if (view === "detached") this.refuse(name, "the array's buffer is detached");
         if (view === "out of bounds") {
           this.refuse(
-            key,
             name,
             "the array is out of bounds of its resizable buffer, which shrank under it"
           );
         }
         if (view.length === 0) continue;
         if (this.seen[at] === 1) {
-          this.refuse(key, name, "named twice at one key: an operand appears at most once per key");
+          this.refuse(name, "named twice at one key: an operand appears at most once per key");
         }
         const n = this.scan(view, key, name);
         this.seen[at] = 1;
@@ -7034,17 +7338,16 @@ var FeedCursor = class {
    */
   scan(view, key, name) {
     const n = view.length;
-    if (n > KEY_IDS) this.refuse(key, name, `${n} ids, more than one chunk key holds`);
+    if (n > KEY_IDS) this.refuse(name, `${n} ids, more than one chunk key holds`);
     const scratch = this.scratch;
     let prev = -1;
     for (let i = 0; i < n; i++) {
       const id = view[i];
       if (id >>> 16 !== key) {
-        this.refuse(key, name, `the id at position ${i} is not inside the key`);
+        this.refuse(name, `the id at position ${i} is not inside the key`);
       }
       if (id <= prev) {
         this.refuse(
-          key,
           name,
           `the id at position ${i} is not above the one before it: ids are ascending and unique`
         );
@@ -7191,13 +7494,6 @@ function compileCombineMany(request) {
   }
   const index = /* @__PURE__ */ new Map();
   operands.forEach((op, i) => index.set(op.name, i));
-  for (const op of operands) {
-    if (op.held !== void 0 && op.held.chunks.empty && !op.held.mayBeEmpty) {
-      throw new ValidationError(
-        `materializeMany: operand "${op.name}" holds no id, so an include would contribute none and an exclude would subtract none. Check what it was made from, or name it in \`mayBeEmpty\` if it may be empty.`
-      );
-    }
-  }
   const feed = request.feed === void 0 ? void 0 : checkFeed(request.feed, new Set(index.keys()));
   feed?.names.forEach((name, j) => index.set(name, operands.length + j));
   let totalNodes = 0;
@@ -7227,24 +7523,9 @@ function compileCombineMany(request) {
     if (output.allowEmpty !== void 0 && typeof output.allowEmpty !== "boolean") {
       throw new ValidationError(`${where}.allowEmpty must be a boolean`);
     }
-    const guard = output.guard;
-    if (guard !== void 0) {
-      if (typeof guard !== "object" || guard === null) {
-        throw new ValidationError(`${where}.guard must be an object`);
-      }
-      const min = guard.minCardinality;
-      if (min !== void 0 && (!Number.isInteger(min) || min < 0)) {
-        throw new ValidationError(
-          `${where}.guard.minCardinality must be a non-negative integer; got ${String(min)}`
-        );
-      }
-      const retained = guard.minRetained;
-      if (retained !== void 0 && (!Number.isFinite(retained) || retained < 0 || retained > 1)) {
-        throw new ValidationError(
-          `${where}.guard.minRetained must be a fraction in 0..1; got ${String(retained)}`
-        );
-      }
-    }
+    checkedAuditSink(output.audit, where);
+    if (output.guard === null) throw new ValidationError(`${where}.guard must be an object`);
+    const guard = checkedGuard(output.guard, `${where}.`);
     const metadata = copiedMetadata(output.metadata, (message) => {
       throw new ValidationError(`${where}.metadata: ${message}`);
     });
@@ -7423,6 +7704,7 @@ var Run = class {
   codec;
   clock;
   maxBitmapBytes;
+  metrics;
   ledger;
   gate = new Gate(MAX_RANGES_IN_FLIGHT2);
   operands;
@@ -7437,6 +7719,8 @@ var Run = class {
   publishes = 0;
   opens = 0;
   planCharge = 0;
+  /** The groups {@link formGroups} made, whose kept plans {@link dropKeptPlans} can release. */
+  formed = [];
   attributedGet = 0;
   attributedPut = 0;
   planned = 0;
@@ -7462,6 +7746,7 @@ var Run = class {
     this.codec = deps.codec;
     this.clock = deps.clock;
     this.maxBitmapBytes = deps.maxBitmapBytes ?? DEFAULT_MAX_BITMAP_BYTES;
+    this.metrics = deps.metrics === void 0 ? void 0 : safeMetrics(deps.metrics);
     this.ledger = new ResidentLedger(this.req.maxBufferedBytes);
     this.tick = yieldEvery(deps.clock, 256);
     this.operands = this.req.operands.map((spec, index) => ({
@@ -7501,7 +7786,6 @@ var Run = class {
   async execute() {
     this.window = windowOf2(this.req.after, this.req.through);
     if (this.checkedFeed !== void 0) this.feed = this.openFeed(this.checkedFeed);
-    this.indexHeld();
     await this.readIndexes();
     await this.refuseAbsent();
     this.planOutputs();
@@ -7565,11 +7849,13 @@ var Run = class {
     }
   }
   /**
-   * Make room in the ledger. A fed output cannot be run again (the feed is read once), so a fed call gives up its fed
-   * outputs and the feed first, as soon as the ledger passes the budget; only then is a stored-only buffer evicted, to run
-   * again alone.
+   * Make room in the ledger. The plans kept for later groups give way first: they are rebuilt when their group starts,
+   * and the outputs were judged without them. A fed output cannot be run again (the feed is read once), so a fed call
+   * gives up its fed outputs and the feed next, as soon as the ledger passes the budget; only then is a stored-only
+   * buffer evicted, to run again alone.
    */
   reclaim() {
+    if (this.dropKeptPlans()) return true;
     if (this.feed !== void 0) {
       let fed = this.feed.heldBytes;
       for (const o of this.running)
@@ -7585,70 +7871,13 @@ var Run = class {
     return { ok: false, error: new Error("materializeMany: output did not run") };
   }
   // ---- index ------------------------------------------------------------------------------------------------
-  /** What an output that reads the held operand `op` gets when an erasure ran in the store since it was made. */
-  staleHeldError(op) {
-    return new StaleOperandError(
-      `materializeMany: an erasure ran in this store after operand "${op.spec.name}" was made, so it may hold an erased id and the outputs that read it were not published. Make it again from the source of truth, after the erasure, and run the call again.`,
-      op.spec.name,
-      "erased"
-    );
-  }
-  /** The error of the first held operand `o` reads that an erasure has made stale, if any. */
-  staleHeld(o) {
-    for (const i of o.compiled.operands) {
-      const op = this.operands[i];
-      if (op.spec.held?.moved() === true) return this.staleHeldError(op);
-    }
-    return void 0;
-  }
-  /**
-   * Index the held operands the outputs read, before any request: their keys and exact cardinalities are in memory, and
-   * one that an erasure has made stale is failed here, so the outputs that read it fail without a read.
-   */
-  indexHeld() {
+  async readIndexes() {
     const wanted = /* @__PURE__ */ new Set();
     for (const o of this.outputs) for (const op of o.compiled.operands) wanted.add(op);
     if (this.window === "empty") return;
+    for (const index of wanted) this.operands[index].read = true;
     const w = this.window;
-    const charged = /* @__PURE__ */ new Set();
-    let resident = 0;
-    for (const index of wanted) {
-      const op = this.operands[index];
-      const held = op.spec.held;
-      if (held === void 0) continue;
-      op.read = true;
-      if (held.moved()) {
-        op.error = { error: this.staleHeldError(op) };
-        continue;
-      }
-      if (!charged.has(held.chunks)) {
-        charged.add(held.chunks);
-        resident += held.chunks.residentBytes;
-      }
-      const all = held.chunks.keys;
-      const cards = held.chunks.cardinalities;
-      const keep = [];
-      const card = [];
-      for (let i = 0; i < all.length; i++) {
-        const key = all[i];
-        if (w !== null && (key < w.loKey || key > w.hiKey)) continue;
-        keep.push(key);
-        card.push(cards[i]);
-      }
-      op.bounds = { keys: Uint16Array.from(keep), card: Uint32Array.from(card) };
-      op.indexKeys = keep.length;
-      op.chunkless = all.length === 0;
-    }
-    if (resident > 0) this.chargePlan(resident, "the held operands");
-  }
-  async readIndexes() {
-    const wanted = /* @__PURE__ */ new Set();
-    for (const o of this.outputs) for (const op of o.compiled.operands) wanted.add(op);
-    if (this.window === "empty") return;
-    for (const index of wanted) this.operands[index].read = true;
-    const w = this.window;
-    const stored = [...wanted].filter((index) => this.operands[index].spec.held === void 0);
-    await mapWithConcurrency(stored, INDEX_PARALLELISM, async (index) => {
+    await mapWithConcurrency([...wanted], INDEX_PARALLELISM, async (index) => {
       const op = this.operands[index];
       try {
         const listed = checkedChunkKeys(await this.source.listChunkKeys(op.spec.ref));
@@ -7686,7 +7915,7 @@ var Run = class {
   async refuseAbsent() {
     if (this.req.allowAbsentOperands === true || this.source.exists === void 0) return;
     const judged = this.operands.filter(
-      (op) => op.spec.held === void 0 && op.error === void 0 && (op.read ? op.chunkless : true)
+      (op) => op.error === void 0 && (op.read ? op.chunkless : true)
     );
     if (judged.length === 0) return;
     const exists = this.source.exists.bind(this.source);
@@ -7697,7 +7926,7 @@ var Run = class {
     const absent = checked.filter((c) => !c.exists).map((c) => c.op.spec.name);
     if (absent.length === 0) return;
     throw new ValidationError(
-      `materializeMany: operand ${absent.map((n) => `"${n}"`).join(", ")} names a segment that does not exist, so it would contribute nothing \u2014 an exclude would suppress no ids and an include would contribute none. Check the name and the namespace (a segment addressed without its \`namespace\` is a DIFFERENT segment). Pass \`allowAbsentOperands: true\` if you meant it.`
+      `materializeMany: operand ${absent.map((n) => `"${n}"`).join(", ")} names a segment that does not exist or was dropped, so it would contribute nothing \u2014 an exclude would suppress no ids and an include would contribute none. Check the name and the namespace (a segment addressed without its \`namespace\` is a DIFFERENT segment). Pass \`allowAbsentOperands: true\` if you meant it.`
     );
   }
   // ---- plan -------------------------------------------------------------------------------------------------
@@ -7759,12 +7988,15 @@ var Run = class {
       o.status = "waiting";
     }
   }
-  /** The bytes a group may take: the budget less what the plan holds. */
-  get room() {
-    return this.req.maxBufferedBytes - this.planCharge;
-  }
-  /** Outputs in call order, a group at a time while the ledger has room for the next. */
+  /**
+   * Outputs in call order, a group at a time while the ledger has room for the next. Every output is judged against the
+   * room the call's own plan leaves, `base`: a group's plan kept for its start is released when it starts, or sooner when
+   * a group needs the room ({@link dropKeptPlans}), so it is not resident while a later output runs, and counting it
+   * would refuse an output, or cut a group short, by its position in the call.
+   */
   formGroups(waiting, single) {
+    const base = this.planCharge;
+    const room = this.req.maxBufferedBytes - base;
     const groups = [];
     const fresh = () => new GroupCost((i) => this.operands[i].bytes, this.req.publishConcurrency);
     let cost = fresh();
@@ -7790,22 +8022,36 @@ var Run = class {
     };
     for (const o of waiting) {
       const alone = fresh().with(o);
-      if (alone > this.room) {
+      if (alone > room) {
         this.fail(
           o,
           new BudgetExceededError(
-            `materializeMany: output ${o.index} needs about ${alone} bytes resident with its operands, and the plan holds ${this.planCharge}, over maxBufferedBytes (${this.req.maxBufferedBytes}) \u2014 raise maxBufferedBytes to at least ${alone + this.planCharge}`
+            `materializeMany: output ${o.index} needs about ${alone} bytes resident with its operands, and the plan holds ${base}, over maxBufferedBytes (${this.req.maxBufferedBytes}) \u2014 raise maxBufferedBytes to at least ${alone + base}`
           )
         );
         continue;
       }
-      if (!single && cost.size > 0 && cost.with(o) > this.room) flush();
+      if (!single && cost.size > 0 && cost.with(o) > room) flush();
       current.push(o);
       cost.add(o);
     }
     flush();
+    this.formed = groups;
     return groups;
   }
+  /** Release every group plan still kept for its start; each is built again when its group starts. */
+  dropKeptPlans() {
+    let dropped = false;
+    for (const summary of this.formed) {
+      const plan = summary.plan;
+      if (plan === void 0) continue;
+      summary.plan = void 0;
+      this.ledger.release(plan.planBytes);
+      this.planCharge -= plan.planBytes;
+      dropped = true;
+    }
+    return dropped;
+  }
   /** The keys each operand is fetched at for `members`, and the keys the pass visits. */
   buildGroup(members) {
     combineWork.planBuilds++;
@@ -7848,6 +8094,11 @@ var Run = class {
       pruned += this.operands[operand].indexKeys - set.size;
       fixed += this.operands[operand].bytes;
     }
+    const named = /* @__PURE__ */ new Set();
+    for (const o of members) for (const operand of o.compiled.operands) named.add(operand);
+    for (const operand of named) {
+      if (!bits.has(operand)) pruned += this.operands[operand].indexKeys;
+    }
     const visited = Uint16Array.from(visit.toKeys());
     return {
       outputs: members.map((o) => o.index),
@@ -7892,13 +8143,13 @@ var Run = class {
   // ---- one group --------------------------------------------------------------------------------------------
   async runGroup(indices, summary) {
     const members = indices.map((i) => this.outputs[i]).filter((o) => o.status === "waiting");
-    if (members.length === 0) return;
     const kept = summary?.plan;
     if (summary !== void 0) summary.plan = void 0;
     if (kept !== void 0) {
       this.ledger.release(kept.planBytes);
       this.planCharge -= kept.planBytes;
     }
+    if (members.length === 0) return;
     const plan = kept !== void 0 && members.length === indices.length ? kept : this.buildGroup(members);
     const group = this.groups++;
     const budget = this.limit;
@@ -7918,13 +8169,13 @@ var Run = class {
       o.chunkCount = 0;
       o.peak = 0;
     }
-    this.pruned += plan.pruned;
     const fixed = plan.fixedBytes + plan.planBytes;
-    if (!this.ledger.tryCharge(fixed)) {
+    if (!this.ledger.tryCharge(fixed) && !(this.dropKeptPlans() && this.ledger.tryCharge(fixed))) {
       const error = budgetError(this.req.maxBufferedBytes, "the operand streams");
       for (const o of members) this.fail(o, error);
       return;
     }
+    this.pruned += plan.pruned;
     this.running = members;
     try {
       await this.pass(plan, members);
@@ -7973,12 +8224,19 @@ var Run = class {
       });
     }
     const retry = (request) => this.gate.run(request);
-    const onRequest = (r) => {
+    const onRequestOf = (op) => (r) => {
       this.rangeReads++;
       this.rangeBytes += r.bytes;
+      this.metrics?.onEvent({
+        kind: "storage.get",
+        namespace: op.spec.ref.namespace,
+        segment: op.spec.ref.segment,
+        bytes: r.bytes,
+        ms: r.ms
+      });
     };
     const streamOf = (c) => {
-      c.stream ??= new ChunkStream(this.readKeys(c.op, c.keys, retry, onRequest));
+      c.stream ??= new ChunkStream(this.readKeys(c.op, c.keys, retry, onRequestOf(c.op)));
       return c.stream;
     };
     const stop = (c) => {
@@ -8146,22 +8404,8 @@ var Run = class {
   /** The operand's chunks at `keys` as a stream: the source's coalesced ranges, or chunk by chunk where it has none. */
   readKeys(op, wanted, retry, onRequest) {
     const source = this.source;
+    const clock = this.clock;
     const keys = Array.from(wanted);
-    const held = op.spec.held;
-    if (held !== void 0) {
-      const stale = () => this.staleHeldError(op);
-      return {
-        // Each chunk is checked and read in one step with no wait between, so a release or an erasure cannot land after
-        // the check and before the bytes.
-        async *[Symbol.asyncIterator]() {
-          for (const key of keys) {
-            if (held.moved()) throw stale();
-            const bytes = held.chunks.payload(key);
-            yield { key, bytes: bytes === null ? null : new Uint8Array(bytes), version: null };
-          }
-        }
-      };
-    }
     const ref = op.spec.ref;
     if (source.getChunks !== void 0) {
       return source.getChunks(ref, keys, { concurrency: this.req.concurrency, retry, onRequest });
@@ -8169,8 +8413,9 @@ var Run = class {
     return {
       async *[Symbol.asyncIterator]() {
         for (const key of keys) {
+          const startedAt = clock.now();
           const bytes = await retry(() => source.getChunk({ ...ref, chunkKey: key }));
-          onRequest({ bytes: bytes?.length ?? 0, ms: 0 });
+          onRequest({ bytes: bytes?.length ?? 0, ms: Math.max(0, clock.now() - startedAt) });
           yield { key, bytes, version: null };
         }
       }
@@ -8287,13 +8532,6 @@ var Run = class {
           wake();
           continue;
         }
-        const staleHeld = this.staleHeld(o);
-        if (staleHeld !== void 0) {
-          this.ledger.release(transient);
-          this.fail(o, staleHeld);
-          wake();
-          continue;
-        }
         if (o.compiled.fed.length > 0 && this.erased()) {
           this.ledger.release(transient);
           this.fail(o, this.staleError(o));
@@ -8301,7 +8539,7 @@ var Run = class {
           continue;
         }
         inFlight++;
-        this.publishes++;
+        if (this.req.dryRun !== true) this.publishes++;
         const chunks = o.chunks;
         try {
           const value = await o.spec.publish(
@@ -8550,106 +8788,6 @@ function evaluate(node, kc) {
   return acc;
 }
 
-// src/core/combine-held.ts
-var PER_CHUNK_BYTES = 96;
-var HeldChunks = class {
-  /** The chunk keys, ascending. */
-  keys;
-  /** How many ids each chunk holds. */
-  cardinalities;
-  /** What it holds in memory, for a call's resident-bytes ledger. */
-  residentBytes;
-  payloads;
-  constructor(chunks) {
-    const keys = [];
-    const cards = [];
-    const payloads = [];
-    let bytes = 0;
-    let last = -1;
-    for (const chunk of chunks) {
-      const { chunkKey, payload, cardinality } = chunk;
-      if (!Number.isInteger(chunkKey) || chunkKey < 0 || chunkKey > MAX_REMAINDER || chunkKey <= last) {
-        throw new ValidationError(
-          `a held chunk's key must be an integer in [0, 65535] above the last`
-        );
-      }
-      assertChunkCardinalityInRange(cardinality);
-      last = chunkKey;
-      keys.push(chunkKey);
-      cards.push(cardinality);
-      payloads.push(payload);
-      bytes += payload.byteLength + PER_CHUNK_BYTES;
-    }
-    this.keys = Uint16Array.from(keys);
-    this.cardinalities = Uint32Array.from(cards);
-    this.payloads = payloads;
-    this.residentBytes = bytes;
-  }
-  /** Whether it holds no id. */
-  get empty() {
-    return this.keys.length === 0;
-  }
-  /** Whether {@link release} ran. */
-  get released() {
-    return this.payloads === void 0;
-  }
-  /**
-   * The payload of the chunk at `key`, `null` when it holds none there. A view into what is held: not to be written to.
-   * @throws {ValidationError} once released.
-   */
-  payload(key) {
-    const payloads = this.payloads;
-    if (payloads === void 0) {
-      throw new ValidationError(
-        "this memory operand was released: make another with store.memory()"
-      );
-    }
-    let lo = 0;
-    let hi = this.keys.length - 1;
-    while (lo <= hi) {
-      const mid = lo + hi >>> 1;
-      const at = this.keys[mid];
-      if (at === key) return payloads[mid];
-      if (at < key) lo = mid + 1;
-      else hi = mid - 1;
-    }
-    return null;
-  }
-  /** Zero and drop the bytes. Every later read throws; a second call does nothing. */
-  release() {
-    const payloads = this.payloads;
-    if (payloads === void 0) return;
-    this.payloads = void 0;
-    for (const payload of payloads) payload.fill(0);
-  }
-};
-async function prepareHeld(input, codec, clock) {
-  if (typeof input === "object" && input !== null && !(Symbol.iterator in input) && !(Symbol.asyncIterator in input) && Object.prototype.hasOwnProperty.call(input, "ascending")) {
-    throw new ValidationError(
-      "a memory operand takes ids, { serialized } or { bitmap }, with no `ascending` option: ids that arrive in chunk-key order, one key at a time, are a feed of materializeMany"
-    );
-  }
-  const real = plainUint32(input);
-  if (real === "detached") {
-    throw new ValidationError("a memory operand's ids are a Uint32Array over a detached buffer");
-  }
-  if (real === "out of bounds") {
-    throw new ValidationError(
-      "a memory operand's ids are a resizable-buffer Uint32Array whose view is out of bounds"
-    );
-  }
-  const prepared = real !== void 0 ? new DecodedLoadInput(codec.fromValues(real)) : prepareLoadInput(input, codec, "a memory operand");
-  const encoded = await encodedChunksOfInput(prepared, codec, clock);
-  const tick = yieldEvery(clock, 256);
-  const chunks = [];
-  for (const chunk of encoded) {
-    chunks.push(chunk);
-    const pause = tick();
-    if (pause !== null) await pause;
-  }
-  return new HeldChunks(chunks);
-}
-
 // src/core/rollback.ts
 async function listGenerations(ref, deps) {
   validateUserRef(ref);
@@ -8679,6 +8817,7 @@ async function currentDescription(ref, record, deps) {
 }
 async function rollbackSegment(ref, toGeneration, deps, options = {}) {
   validateUserRef(ref);
+  checkedAuditSink(options.audit, "rollback");
   if (!Number.isInteger(toGeneration) || toGeneration < 0) {
     throw new ValidationError(
       `rollback: generation must be a non-negative integer; got ${String(toGeneration)}`
@@ -8704,9 +8843,9 @@ async function rollbackSegment(ref, toGeneration, deps, options = {}) {
       `rollback: generation ${toGeneration} of "${ref.segment}" is not in the bucket` + (available.length === 0 ? " (no generations remain)" : ` \u2014 present: ${available.join(", ")}`)
     );
   }
-  if (record.currentGen !== null && toGeneration > record.currentGen && options.allowForward !== true) {
+  if ((record.currentGen === null || toGeneration > record.currentGen) && options.allowForward !== true) {
     throw new ValidationError(
-      `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.`
+      `rollback: generation ${toGeneration} of "${ref.segment}" is above the current pointer (${record.currentGen ?? "none"}) \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;
@@ -8824,7 +8963,21 @@ function describingSummary(record) {
 // src/core/erase-id.ts
 var HOLDS_CONCURRENCY = 4;
 async function eraseIdFromSegment(ref, id, deps, options = {}) {
+  const first = {};
+  const result = await eraseOnce(ref, id, deps, options, first);
+  if (result.reason === "destroyed" && first.tombstoned === false) {
+    const again = await eraseOnce(ref, id, deps, options, {});
+    if (again.reason === "destroyed") return result;
+    if (!again.erased) return again;
+    const collected = [.../* @__PURE__ */ new Set([...result.collected, ...again.collected])].sort((a, b) => a - b);
+    const newest = Math.max(result.fromGeneration ?? -1, again.fromGeneration ?? -1);
+    return { ...again, collected, ...newest >= 0 ? { fromGeneration: newest } : {} };
+  }
+  return result;
+}
+async function eraseOnce(ref, id, deps, options, seen) {
   validateUserRef(ref);
+  checkedAuditSink(options.audit, "eraseIdFromSegment");
   const { chunkKey, remainder } = splitId(id);
   const codec = requireCodec(deps.codec, "eraseIdFromSegment");
   const maxBytes = deps.maxBitmapBytes ?? DEFAULT_MAX_BITMAP_BYTES;
@@ -8832,21 +8985,23 @@ async function eraseIdFromSegment(ref, id, deps, options = {}) {
   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")
-    return { ...base, erased: false, reason: "destroyed", collected: [] };
-  if (record.currentGen === null)
-    return { ...base, erased: false, reason: "no-generation", collected: [] };
-  const from = record.currentGen;
+  const tombstoned = record.status === "destroyed";
+  seen.tombstoned = tombstoned;
+  const pointerless = !tombstoned && record.currentGen === null;
+  const from = record.currentGen ?? -1;
   const fromToken = record.token;
+  let premise = record;
+  let premiseToken = fromToken;
   let aead;
-  if (record.wrappedDeks !== void 0 && record.wrappedDeks.length > 0) {
+  if (tombstoned) {
+  } else if (record.wrappedDeks !== void 0 && record.wrappedDeks.length > 0) {
     if (deps.keystore === void 0) {
       throw new KeyUnavailableError(
         `segment "${ref.segment}" is encrypted but eraseIdFromSegment has no keystore`
       );
     }
     aead = await deps.keystore.openDek(record.wrappedDeks);
-  } else if (deps.requireEncryption === true) {
+  } else if (!pointerless && deps.requireEncryption === true) {
     throw new ValidationError(`requireEncryption: segment "${ref.segment}" is cleartext`);
   }
   const cryptoAt = (generation2) => aead === void 0 ? void 0 : { aead, aadFor: (scope) => aadFor(ref, generation2, scope) };
@@ -8863,8 +9018,9 @@ async function eraseIdFromSegment(ref, id, deps, options = {}) {
     if (row === null) return "absent";
     if (row.status === "destroyed") return "destroyed";
     if (row.currentGen === null) return "no-generation";
-    return row.currentGen === from && (row.token === fromToken || onlyLeasesDiffer(record, row)) ? null : "superseded";
+    return row.currentGen === from && (row.token === premiseToken || onlyLeasesDiffer(premise, row)) ? null : "superseded";
   };
+  const sealedUnpublished = /* @__PURE__ */ new Set();
   const holds = async (generation2) => {
     const key2 = { ...base, generation: generation2 };
     const chunkIn = (crypto) => read(async () => (await openGenerationReader(deps.storage, key2, crypto)).getChunk(chunkKey));
@@ -8873,7 +9029,15 @@ async function eraseIdFromSegment(ref, id, deps, options = {}) {
       try {
         bytes = await chunkIn(cryptoAt(generation2));
       } catch (err) {
-        if (!isIntegrityError(err) || cryptoAt(generation2) === void 0 || await read(() => objectIsEncrypted(deps.storage, key2))) {
+        if (cryptoAt(generation2) === void 0) {
+          if ((tombstoned || pointerless) && await read(() => objectIsEncrypted(deps.storage, key2))) {
+            if (tombstoned) return false;
+            sealedUnpublished.add(generation2);
+            return true;
+          }
+          throw err;
+        }
+        if (!isIntegrityError(err) || await read(() => objectIsEncrypted(deps.storage, key2))) {
           throw err;
         }
         bytes = await chunkIn(void 0);
@@ -8919,6 +9083,51 @@ async function eraseIdFromSegment(ref, id, deps, options = {}) {
   const cannotRemove = (generation2) => new WriteConflictError(
     `erasure of segment ${ref.segment} could not remove generation ${generation2}, which still holds the id and is still in the bucket; re-run`
   );
+  const fenceInFlight = async () => {
+    const churn = leaseChurn({ clock: deps.clock, rng: deps.rng ?? deps.readRetry?.rng });
+    let row = await deps.registry.get(ref);
+    for (; ; ) {
+      const verdict = rowVerdict(row);
+      if (verdict !== null) return verdict;
+      const current = row;
+      const keptGens = current.keptGens !== void 0 && current.keptGens.length === 0 ? void 0 : [];
+      try {
+        const { token } = await deps.registry.compareAndSwap(ref, current.token, { keptGens });
+        premise = { ...current, keptGens, token };
+        premiseToken = token;
+        return null;
+      } catch (err) {
+        if (!isWriteConflictError(err)) throw err;
+      }
+      const now = await deps.registry.get(ref);
+      const settled2 = await churn.settle(current, now, () => deps.registry.get(ref));
+      if (settled2 === void 0) return rowVerdict(now) ?? "superseded";
+      row = settled2.row;
+    }
+  };
+  const unpublished = async () => {
+    const generations = [];
+    for await (const key2 of deps.storage.list(ref)) generations.push(key2.generation);
+    const newestFirst = generations.sort((a, b) => b - a);
+    const holder = (await holdsEach(newestFirst, true)).find((h) => h.held === true);
+    if (holder === void 0)
+      return { ...base, erased: false, reason: "no-generation", collected: [] };
+    const what = sealedUnpublished.has(holder.generation) ? "is sealed under a key that load has not published, so it cannot be searched" : "holds the id";
+    throw new WriteConflictError(
+      `eraseIdFromSegment: segment "${ref.segment}" has no published generation, and an object a first load wrote and never published (generation ${holder.generation}) ${what}. It cannot be deleted while that load may still publish it: re-run once the segment is loaded, which makes the object collectable, or drop the segment`
+    );
+  };
+  const underTombstone = async () => {
+    const generations = [];
+    for await (const key2 of deps.storage.list(ref)) generations.push(key2.generation);
+    const newestFirst = generations.sort((a, b) => b - a);
+    const holder = (await holdsEach(newestFirst, true)).find((h) => h.held === true);
+    if (holder === void 0) return { ...base, erased: false, reason: "destroyed", collected: [] };
+    const collected2 = await gcOrphanGenerations(ref, deps, { keep: 0 });
+    const left2 = await holderLeft(/* @__PURE__ */ new Set());
+    if (left2 !== void 0) throw cannotRemove(left2);
+    return { ...base, erased: true, fromGeneration: holder.generation, collected: collected2 };
+  };
   const notInCurrent = async () => {
     const notMember = {
       ...base,
@@ -8955,8 +9164,9 @@ async function eraseIdFromSegment(ref, id, deps, options = {}) {
     const newest = holdersAbove[0] ?? holderBelow;
     if (newest === void 0) return notMember;
     const collected2 = [...await gcOrphanGenerations(ref, deps, { keep: 0 })];
-    let moved = null;
+    let moved = holdersAbove.length > 0 ? await fenceInFlight() : null;
     for (const generation2 of holdersAbove) {
+      if (moved !== null) break;
       moved = rowVerdict(await deps.registry.get(ref));
       if (moved !== null) break;
       await deps.storage.delete({ ...base, generation: generation2 });
@@ -9021,10 +9231,17 @@ async function eraseIdFromSegment(ref, id, deps, options = {}) {
   };
   const discardRefused = async (written) => {
     const row = await deps.registry.get(ref);
-    if (row === null || row.status !== "active" || row.currentGen === null) return;
-    if (row.currentGen <= from || row.currentGen >= written) return;
+    if (row !== null && row.status === "destroyed") {
+      await deps.storage.delete({ ...base, generation: written });
+      return row;
+    }
+    if (row === null || row.status !== "active" || row.currentGen === null) return row;
+    if (row.currentGen <= from || row.currentGen >= written) return row;
     await deps.storage.delete({ ...base, generation: written });
+    return row;
   };
+  if (tombstoned) return await underTombstone();
+  if (pointerless) return await unpublished();
   const staged = await stage();
   if ("erased" in staged) {
     if (!staged.erased && staged.generation !== void 0) await discardRefused(staged.generation);
@@ -9048,11 +9265,11 @@ async function eraseIdFromSegment(ref, id, deps, options = {}) {
     rng: deps.rng ?? deps.readRetry?.rng
   });
   if (!published) {
-    await discardRefused(generation);
+    const now = await discardRefused(generation);
     return {
       ...base,
       erased: false,
-      reason: "superseded",
+      reason: rowVerdict(now) ?? "superseded",
       fromGeneration: from,
       generation,
       collected: []
@@ -9111,9 +9328,12 @@ import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
 var KEY_BYTES = 32;
 var NONCE_BYTES2 = 12;
 var TAG_BYTES2 = 16;
+var isBytes = (v) => Object.prototype.toString.call(v) === "[object Uint8Array]";
 var NodeAead = class {
   key;
   constructor(key) {
+    if (!isBytes(key))
+      throw new ValidationError("AEAD key must be a Uint8Array of key bytes, not text");
     if (key.length !== KEY_BYTES)
       throw new ValidationError(`AEAD key must be ${KEY_BYTES} bytes, got ${key.length}`);
     this.key = Buffer.from(key);
@@ -9161,6 +9381,8 @@ var InProcessKeystore = class {
     const entries = Object.entries(options.keys);
     if (entries.length === 0) throw new ValidationError("keystore needs at least one KEK");
     for (const [id, k] of entries) {
+      if (!isBytes(k))
+        throw new ValidationError(`KEK "${id}" must be a Uint8Array of key bytes, not text`);
       if (k.length !== KEY_BYTES)
         throw new ValidationError(`KEK "${id}" must be ${KEY_BYTES} bytes, got ${k.length}`);
     }
@@ -9198,20 +9420,186 @@ var InProcessKeystore = class {
       }
     }
     if (anyKekHeld) throw lastUnwrapError;
-    const have = [...this.keys.keys()].join(", ") || "(none)";
     const need = wrapped.map((w) => w.keyId).join(", ") || "(none)";
     throw new KeyUnavailableError(
-      `no held KEK can unwrap this DEK \u2014 have [${have}], wrappings reference [${need}]. Restore the missing KEK (or its recovery KEK), or rebuild the segment from source.`
+      `no held KEK can unwrap this DEK \u2014 the wrappings reference [${need}]. Restore the missing KEK (or its recovery KEK), or rebuild the segment from source.`
     );
   }
 };
 
+// src/core/retention.ts
+var EXPIRES_AT = "expiresAt";
+var RETENTION_CAS_ATTEMPTS = 5;
+var MIN_EXPIRES_AT_MS = 1e12;
+var SWEEP_MARK = "retiredBySweepAt";
+function withoutSweepMark(meta) {
+  if (meta === void 0 || meta === null || typeof meta !== "object" || Array.isArray(meta))
+    return null;
+  if (!Object.prototype.hasOwnProperty.call(meta, SWEEP_MARK)) return null;
+  const rest = Object.fromEntries(Object.entries(meta).filter(([key]) => key !== SWEEP_MARK));
+  return Object.keys(rest).length === 0 ? void 0 : rest;
+}
+var MAX_DATE_MS = 864e13;
+function validateRetentionPolicy(policy) {
+  if (policy === null || typeof policy !== "object" || Array.isArray(policy)) {
+    throw new ValidationError(
+      `retention policy must be an object such as { expiresAt }; got ${policy === null ? "null" : Array.isArray(policy) ? "an array" : `a ${typeof 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 > MAX_DATE_MS) {
+    throw new ValidationError(
+      `retention.expiresAt (${expiresAt}) is past the latest time a date can name (${MAX_DATE_MS}); to keep a segment, leave it without a policy or call clearRetention`
+    );
+  }
+  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) {
+  validateUserRef(ref);
+  const record = await deps.registry.get(ref);
+  if (record === null || record.status === "destroyed") return null;
+  return readRetentionPolicy(record.retention);
+}
+function readExpiresAt(record) {
+  const parsed = record === null ? null : readRetentionPolicy(record.retention);
+  return parsed === null || parsed === "invalid" ? void 0 : parsed.expiresAt;
+}
+async function reindex(ref, deps, expiresAt, previousExpiresAt) {
+  if (!canIndex(ref)) return false;
+  const nextBucket = expiresAt === void 0 ? void 0 : dueBucket(expiresAt);
+  const oldBucket = previousExpiresAt === void 0 ? void 0 : dueBucket(previousExpiresAt);
+  let indexed = expiresAt === void 0;
+  if (nextBucket !== void 0) {
+    try {
+      await deps.registry.create(dueIndexRef(nextBucket, ref), { currentGen: null });
+      indexed = true;
+    } catch (err) {
+      if (isWriteConflictError(err)) indexed = true;
+    }
+  }
+  if (oldBucket !== void 0 && oldBucket !== nextBucket) {
+    try {
+      await deps.registry.delete(dueIndexRef(oldBucket, ref));
+    } catch {
+    }
+  }
+  return indexed;
+}
+async function setSegmentRetention(ref, deps, policy) {
+  validateUserRef(ref);
+  validateRetentionPolicy(policy);
+  const base = { segment: ref.segment, namespace: ref.namespace };
+  let previousExpiresAt;
+  const churn = leaseChurn(deps);
+  let lost;
+  for (let attempt = 0; attempt < RETENTION_CAS_ATTEMPTS; attempt += 1) {
+    let record = await deps.registry.get(ref);
+    if (lost !== void 0) {
+      const settled2 = await churn.settle(lost, record, () => deps.registry.get(ref));
+      if (settled2 !== void 0) {
+        record = settled2.row;
+        attempt -= 1;
+      }
+    }
+    try {
+      previousExpiresAt = readExpiresAt(record);
+      if (record === null) {
+        await deps.registry.create(ref, {
+          currentGen: null,
+          retention: { [EXPIRES_AT]: policy.expiresAt }
+        });
+        return {
+          ...base,
+          expiresAt: policy.expiresAt,
+          createdRow: true,
+          indexed: await reindex(ref, deps, policy.expiresAt, void 0)
+        };
+      }
+      assertNotDestroyed(record, ref);
+      await deps.registry.compareAndSwap(ref, record.token, {
+        retention: { ...record.retention, [EXPIRES_AT]: policy.expiresAt }
+      });
+      return {
+        ...base,
+        expiresAt: policy.expiresAt,
+        createdRow: false,
+        indexed: await reindex(ref, deps, policy.expiresAt, previousExpiresAt)
+      };
+    } catch (err) {
+      if (!isWriteConflictError(err)) throw err;
+      lost = record ?? void 0;
+    }
+  }
+  throw new WriteConflictError(
+    `setRetention: contention writing the retention policy for segment "${ref.segment}"`
+  );
+}
+async function clearSegmentRetention(ref, deps) {
+  validateUserRef(ref);
+  const churn = leaseChurn(deps);
+  let lost;
+  for (let attempt = 0; attempt < RETENTION_CAS_ATTEMPTS; attempt += 1) {
+    let record = await deps.registry.get(ref);
+    if (lost !== void 0) {
+      const settled2 = await churn.settle(lost, record, () => deps.registry.get(ref));
+      if (settled2 !== void 0) {
+        record = settled2.row;
+        attempt -= 1;
+      }
+    }
+    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
+      });
+      await reindex(ref, deps, void 0, readExpiresAt(record));
+      return true;
+    } catch (err) {
+      if (!isWriteConflictError(err)) throw err;
+      lost = record;
+    }
+  }
+  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/erasure.ts
 var MAX_CAS_ATTEMPTS = 8;
 var ERASE_CONCURRENCY = 8;
 var MAX_STORAGE_SWEEPS = 3;
 async function destroySegment(ref, deps, options) {
   validateUserRef(ref);
+  checkedAuditSink(options.audit, "destroySegment");
   if (options.confirmSegment !== ref.segment) {
     throw new ValidationError(
       `destroySegment: confirmSegment must equal the segment name "${ref.segment}" (guard against accidental crypto-shred)`
@@ -9232,6 +9620,7 @@ async function eraseNamespace(namespace, deps, options) {
     throw new ValidationError("eraseNamespace: namespace must be a non-empty string");
   }
   validateUserNamespace(namespace);
+  checkedAuditSink(options.audit, "eraseNamespace");
   if (options.confirmNamespace !== namespace) {
     throw new ValidationError(
       `eraseNamespace: confirmNamespace must equal the namespace "${namespace}" (guard against accidental erasure)`
@@ -9273,7 +9662,11 @@ async function eraseNamespace(namespace, deps, options) {
   return { destroyed };
 }
 async function dropSegment(ref, deps, options) {
+  return await dropSegmentFor(ref, deps, options, void 0);
+}
+async function dropSegmentFor(ref, deps, options, sweep) {
   validateUserRef(ref);
+  checkedAuditSink(options.audit, "dropSegment");
   if (options.confirmSegment !== ref.segment) {
     throw new ValidationError(
       `dropSegment: confirmSegment must equal the segment name "${ref.segment}" (guard against accidental deletion)`
@@ -9294,7 +9687,9 @@ async function dropSegment(ref, deps, options) {
       reason: record === null ? wouldDelete.length === 0 ? "absent" : void 0 : record.status === "destroyed" ? "already" : void 0
     };
   }
-  let shred = await shredSegment(ref, deps, true, "dropSegment");
+  const first = await shredSegment(ref, deps, true, "dropSegment", sweep);
+  if (first === null) return null;
+  let shred = first;
   if (shred.reason === "absent") {
     const orphans = await listGenerations2(deps.storage, ref);
     if (orphans.length === 0) {
@@ -9371,7 +9766,7 @@ async function listGenerations2(storage, ref) {
   for await (const key of storage.list(ref)) generations.push(key.generation);
   return generations.sort((a, b) => a - b);
 }
-async function shredSegment(ref, deps, allowCleartext, op = "destroySegment") {
+async function shredSegment(ref, deps, allowCleartext, op = "destroySegment", sweep) {
   const base = { segment: ref.segment, namespace: ref.namespace };
   const churn = leaseChurn(deps);
   let lost;
@@ -9384,6 +9779,9 @@ async function shredSegment(ref, deps, allowCleartext, op = "destroySegment") {
         attempt -= 1;
       }
     }
+    if (sweep !== void 0 && (record === null || record.status === "destroyed" || !sweep.wanted(record))) {
+      return null;
+    }
     if (record === null) {
       return { ...base, destroyed: false, cryptoShredded: false, reason: "absent" };
     }
@@ -9394,6 +9792,7 @@ async function shredSegment(ref, deps, allowCleartext, op = "destroySegment") {
     if (!encrypted && !allowCleartext) {
       return { ...base, destroyed: false, cryptoShredded: false, reason: "cleartext" };
     }
+    const unmarked = sweep === void 0 ? withoutSweepMark(record.retention) : null;
     try {
       await deps.registry.compareAndSwap(ref, record.token, {
         status: "destroyed",
@@ -9404,7 +9803,10 @@ async function shredSegment(ref, deps, allowCleartext, op = "destroySegment") {
         // the wrappings; clear, they would outlive the segment on its tombstone.
         summary: void 0,
         // A tombstone holds nothing: a lease names a generation of a segment that now resolves none.
-        leases: void 0
+        leases: void 0,
+        // A sweep's mark, in this same write, so no other tombstone ever carries it: any other tombstone write removes
+        // one a restored or hand-edited row carried.
+        ...sweep !== void 0 ? { retention: sweep.stamp(record.retention) } : unmarked === null ? {} : { retention: unmarked }
       });
       return { ...base, destroyed: true, cryptoShredded: encrypted };
     } catch (err) {
@@ -9415,153 +9817,6 @@ async function shredSegment(ref, deps, allowCleartext, op = "destroySegment") {
   throw new WriteConflictError(`${op}: contention shredding "${ref.segment}" \u2014 retry`);
 }
 
-// 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) {
-  validateUserRef(ref);
-  const record = await deps.registry.get(ref);
-  if (record === null || record.status === "destroyed") return null;
-  return readRetentionPolicy(record.retention);
-}
-function readExpiresAt(record) {
-  const parsed = record === null ? null : readRetentionPolicy(record.retention);
-  return parsed === null || parsed === "invalid" ? void 0 : parsed.expiresAt;
-}
-async function reindex(ref, deps, expiresAt, previousExpiresAt) {
-  if (!canIndex(ref)) return false;
-  const nextBucket = expiresAt === void 0 ? void 0 : dueBucket(expiresAt);
-  const oldBucket = previousExpiresAt === void 0 ? void 0 : dueBucket(previousExpiresAt);
-  let indexed = expiresAt === void 0;
-  if (nextBucket !== void 0) {
-    try {
-      await deps.registry.create(dueIndexRef(nextBucket, ref), { currentGen: null });
-      indexed = true;
-    } catch (err) {
-      if (isWriteConflictError(err)) indexed = true;
-    }
-  }
-  if (oldBucket !== void 0 && oldBucket !== nextBucket) {
-    try {
-      await deps.registry.delete(dueIndexRef(oldBucket, ref));
-    } catch {
-    }
-  }
-  return indexed;
-}
-async function setSegmentRetention(ref, deps, policy) {
-  validateUserRef(ref);
-  validateRetentionPolicy(policy);
-  const base = { segment: ref.segment, namespace: ref.namespace };
-  let previousExpiresAt;
-  const churn = leaseChurn(deps);
-  let lost;
-  for (let attempt = 0; attempt < RETENTION_CAS_ATTEMPTS; attempt += 1) {
-    let record = await deps.registry.get(ref);
-    if (lost !== void 0) {
-      const settled2 = await churn.settle(lost, record, () => deps.registry.get(ref));
-      if (settled2 !== void 0) {
-        record = settled2.row;
-        attempt -= 1;
-      }
-    }
-    try {
-      previousExpiresAt = readExpiresAt(record);
-      if (record === null) {
-        await deps.registry.create(ref, {
-          currentGen: null,
-          retention: { [EXPIRES_AT]: policy.expiresAt }
-        });
-        return {
-          ...base,
-          expiresAt: policy.expiresAt,
-          createdRow: true,
-          indexed: await reindex(ref, deps, policy.expiresAt, void 0)
-        };
-      }
-      assertNotDestroyed(record, ref);
-      await deps.registry.compareAndSwap(ref, record.token, {
-        retention: { ...record.retention, [EXPIRES_AT]: policy.expiresAt }
-      });
-      return {
-        ...base,
-        expiresAt: policy.expiresAt,
-        createdRow: false,
-        indexed: await reindex(ref, deps, policy.expiresAt, previousExpiresAt)
-      };
-    } catch (err) {
-      if (!isWriteConflictError(err)) throw err;
-      lost = record ?? void 0;
-    }
-  }
-  throw new WriteConflictError(
-    `setRetention: contention writing the retention policy for segment "${ref.segment}"`
-  );
-}
-async function clearSegmentRetention(ref, deps) {
-  validateUserRef(ref);
-  const churn = leaseChurn(deps);
-  let lost;
-  for (let attempt = 0; attempt < RETENTION_CAS_ATTEMPTS; attempt += 1) {
-    let record = await deps.registry.get(ref);
-    if (lost !== void 0) {
-      const settled2 = await churn.settle(lost, record, () => deps.registry.get(ref));
-      if (settled2 !== void 0) {
-        record = settled2.row;
-        attempt -= 1;
-      }
-    }
-    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
-      });
-      await reindex(ref, deps, void 0, readExpiresAt(record));
-      return true;
-    } catch (err) {
-      if (!isWriteConflictError(err)) throw err;
-      lost = record;
-    }
-  }
-  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/retention-sweep.ts
 var DEFAULT_RETIRE_LIMIT = 100;
 var MAX_CONSECUTIVE_PURGE_FAULTS = 3;
@@ -9590,7 +9845,7 @@ async function rowsFromDueIndex(registry, options) {
         continue;
       }
       if (gone.has(key)) {
-        litter.push(found);
+        if (litter.length < options.maxScanSegments) litter.push(found);
         continue;
       }
       if (rows.length >= options.maxScanSegments) {
@@ -9600,8 +9855,8 @@ async function rowsFromDueIndex(registry, options) {
       }
       const live = await registry.get(ref);
       if (live === null) {
-        gone.add(key);
-        litter.push(found);
+        if (gone.size < options.maxScanSegments) gone.add(key);
+        if (litter.length < options.maxScanSegments) litter.push(found);
         continue;
       }
       rows.push(live);
@@ -9667,6 +9922,23 @@ async function forgetPurgePointers(registry, ref, purgeAt, found, onFault) {
   }
 }
 async function retireExpired(deps, options) {
+  checkedAuditSink(options.audit, "retireExpired");
+  if (options.shards !== void 0) {
+    const total = options.totalShards;
+    if (typeof total !== "number" || !Number.isInteger(total) || total < 1) {
+      throw new ValidationError("retireExpired: shards needs totalShards, an integer of 1 or more");
+    }
+    if (!Array.isArray(options.shards)) {
+      throw new ValidationError("retireExpired: shards must be an array of shard numbers");
+    }
+    for (const shard of options.shards) {
+      if (typeof shard !== "number" || !Number.isInteger(shard) || shard < 0 || shard >= total) {
+        throw new ValidationError(
+          `retireExpired: a shard is an integer from 0 to totalShards - 1 (${total - 1}); got ${String(shard)}`
+        );
+      }
+    }
+  }
   if (options.namespace !== void 0) validateUserNamespace(options.namespace);
   const now = options.now;
   if (!Number.isFinite(now)) {
@@ -9742,8 +10014,24 @@ async function retireExpired(deps, options) {
       attempted += 1;
       try {
         if (!await isFullyReclaimed(deps, ref)) {
-          if (!dryRun) await gcOrphanGenerations(ref, deps).catch(() => void 0);
+          let collectFault;
+          if (!dryRun) {
+            await gcOrphanGenerations(ref, deps).catch((error) => {
+              collectFault = { error };
+            });
+          }
           if (!await isFullyReclaimed(deps, ref)) {
+            const lostRace = collectFault !== void 0 && isWriteConflictError(collectFault.error);
+            if (!dryRun && !lostRace) {
+              attempted -= 1;
+              purgeRun += 1;
+              if (purgeRun >= MAX_CONSECUTIVE_PURGE_FAULTS) purging = false;
+              if (collectFault !== void 0) noteFault(collectFault.error);
+              else {
+                purgeFaults += 1;
+                firstPurgeFault ??= "failed: the tombstone's objects were still there after its collection";
+              }
+            }
             entries.push({ ...base, action: "skipped", reason: "tombstone-not-empty" });
             continue;
           }
@@ -9796,11 +10084,23 @@ async function retireExpired(deps, options) {
         continue;
       }
       attempted += 1;
-      const result = await dropSegment(ref, deps, {
-        confirmSegment: rec.segment,
-        dryRun,
-        audit: options.audit
-      });
+      const result = await dropSegmentFor(
+        ref,
+        deps,
+        { confirmSegment: rec.segment, dryRun, audit: options.audit },
+        dryRun ? void 0 : {
+          wanted: (row) => {
+            const p = readRetentionPolicy(row.retention);
+            return p !== null && p !== "invalid" && p.expiresAt <= now;
+          },
+          stamp: (retention) => ({ ...retention, [RETIRED_AT]: now })
+        }
+      );
+      if (result === null) {
+        attempted -= 1;
+        entries.push({ ...base, action: "skipped", reason: "policy-changed" });
+        continue;
+      }
       if (dryRun) {
         wouldRetire += 1;
         entries.push({ ...base, action: "would-retire", expiresAt: livePolicy.expiresAt, result });
@@ -9830,13 +10130,11 @@ async function retireExpired(deps, options) {
           if (deleted) continue;
         }
       }
-      const stamped = await stampRetirement(deps.registry, ref, now).catch(() => false);
-      if (stamped && removesRows) await filePurgePointer(deps.registry, ref, now + grace);
+      if (removesRows) await filePurgePointer(deps.registry, ref, now + grace);
     } catch (err) {
       const after = await deps.registry.get(ref).catch(() => null);
-      if (after?.status === "destroyed") {
-        const stamped = await stampRetirement(deps.registry, ref, now).catch(() => false);
-        if (stamped && removesRows) await filePurgePointer(deps.registry, ref, now + grace);
+      if (after?.status === "destroyed" && after.retention?.[RETIRED_AT] === now) {
+        if (removesRows) await filePurgePointer(deps.registry, ref, now + grace);
         retired += 1;
         entries.push({
           ...base,
@@ -9884,7 +10182,7 @@ async function retireExpired(deps, options) {
     entries
   };
 }
-var RETIRED_AT = "retiredBySweepAt";
+var RETIRED_AT = SWEEP_MARK;
 function retirementStamp(meta) {
   if (meta === void 0 || meta === null || typeof meta !== "object" || Array.isArray(meta)) {
     return null;
@@ -9892,21 +10190,6 @@ function retirementStamp(meta) {
   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 false;
-    try {
-      await registry.compareAndSwap(ref, rec.token, {
-        retention: { ...rec.retention, [RETIRED_AT]: now }
-      });
-      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)) {
     void key;
@@ -9919,31 +10202,6 @@ function failureReason(err) {
   return `failed: ${err instanceof Error ? err.message : String(err)}`;
 }
 
-// src/core/registry-reap.ts
-var DEFAULT_REAP_LIMIT = 1e3;
-async function reapRegistryTombstones(registry, options = {}) {
-  const dryRun = options.dryRun === true;
-  if (!dryRun && options.confirmNoLegacyWriters !== true) {
-    throw new ValidationError(
-      "reapRegistryTombstones: a real run needs `confirmNoLegacyWriters: true`, your statement that no process on a release before 0.12 writes this registry (one that did would issue a removed row\u2019s tokens again). Pass `dryRun: true` to see what would be removed."
-    );
-  }
-  const limit = options.limit ?? DEFAULT_REAP_LIMIT;
-  if (!Number.isInteger(limit) || limit < 1) {
-    throw new ValidationError(
-      `reapRegistryTombstones: \`limit\` must be a positive integer; got ${String(limit)}`
-    );
-  }
-  if (options.namespace !== void 0) validateUserNamespace(options.namespace);
-  if (registry.reapLegacyTombstones === void 0) {
-    throw new UnsupportedError(
-      "reapRegistryTombstones: this registry keeps no deleted rows of a release before 0.12 to remove (only the object-store registries, S3, GCS and Azure Blob, do)"
-    );
-  }
-  const request = options.namespace === void 0 ? { dryRun, limit } : { namespace: options.namespace, dryRun, limit };
-  return registry.reapLegacyTombstones(request);
-}
-
 // src/core/consistency.ts
 var DEFAULT_CHECK_CONCURRENCY = 8;
 async function generationsPresent(storage, ref) {
@@ -9960,7 +10218,7 @@ async function checkSummary(ref, live, deps) {
     try {
       aead = await deps.keystore.openDek(live.wrappedDeks);
     } catch (err) {
-      if (isIntegrityError(err) || isCloudRoaringError(err) && err.name === "KeyUnavailableError")
+      if (isIntegrityError(err) || isKeyUnavailableError(err))
         return { kind: "ok", unchecked: true };
       throw err;
     }
@@ -10048,8 +10306,11 @@ async function runConsistencyCheck(deps, options = {}) {
 
 // src/drivers/retry/retrying-chunk-source.ts
 function toRetry(opts) {
+  if (opts.onRetry !== void 0 && typeof opts.onRetry !== "function") {
+    throw new ValidationError("retry.onRetry must be a function");
+  }
   return {
-    policy: opts.policy ?? DEFAULT_RETRY_POLICY,
+    policy: checkedRetryPolicy(opts.policy ?? DEFAULT_RETRY_POLICY),
     deps: {
       clock: opts.clock,
       rng: opts.rng,
@@ -10182,24 +10443,27 @@ export {
   excludingReservedRows,
   getSegmentRetention,
   groundedReport,
+  isBudgetExceededError,
+  isCapabilityError,
   isCloudRoaringError,
   isIntegrityError,
+  isKeyUnavailableError,
   isLeaseExpiredError,
   isLeaseLimitError,
   isNotFoundError,
   isStaleOperandError,
   isStorageBackend,
   isTransientError,
+  isUnsupportedError,
   isValidationError,
   isWriteConflictError,
+  judgeLoad,
   listGenerations,
   listSegments,
   loadSegment,
   loadSegmentChunks,
   mapWithConcurrency,
-  prepareHeld,
   readRetentionPolicy,
-  reapRegistryTombstones,
   rebindCombineMany,
   releaseLease,
   resolveBudget,