@cloudbitmaps/roaring 0.20.0 → 0.21.0

package/dist/bin/export-segments.js

@@ -3,7 +3,7 @@
 // src/bin/export-segments.ts
 import { randomUUID } from "node:crypto";
 import { realpathSync } from "node:fs";
-import { lstat, mkdir, open, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { lstat, mkdir, open, readdir, rename, rm, rmdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { encodeNameForPath, namespacePathPart } from "@cloudbitmaps/core/driver-kit";
@@ -13,20 +13,19 @@ import {
   BoundedLru,
   PinnedStorageChunkSource,
   segmentKey,
-  CrbmStorageChunkSource,
+  CrbmStorageChunkSource as CrbmStorageChunkSource2,
   DEFAULT_BUDGET,
-  DEFAULT_RETRY_POLICY,
+  DEFAULT_RETRY_POLICY as DEFAULT_RETRY_POLICY2,
   withRetry,
-  isStorageBackend,
-  NOOP_METRICS,
-  RetryingStorageChunkSource,
+  NOOP_METRICS as NOOP_METRICS2,
+  RetryingStorageChunkSource as RetryingStorageChunkSource2,
   SegmentEngine,
   LEASE_SKEW_MS,
   LeaseExpiredError,
   MAX_LEASE_MS,
   NotFoundError,
   UnsupportedError,
-  ValidationError as ValidationError2,
+  ValidationError as ValidationError4,
   WriteConflictError,
   checkBudget,
   collectWithinBudget,
@@ -53,7 +52,7 @@ import {
   splitId,
   takeLease
 } from "@cloudbitmaps/core";
-import { pointerIdOf, validateSegmentRef } from "@cloudbitmaps/core/driver-kit";
+import { pointerIdOf, requirePositiveInt, validateSegmentRef } from "@cloudbitmaps/core/driver-kit";
 
 // src/open-charging-storage.ts
 var OpenChargingStorage = class {
@@ -529,90 +528,265 @@ var OPTION_KEYS = {
 };
 
 // src/lease-guards.ts
-var guardIdIterable = (inner, check) => ({
-  [Symbol.asyncIterator]: () => {
-    const it = inner[Symbol.asyncIterator]();
-    let chunk = -1;
-    let first = true;
-    const stop = async (err) => {
-      await it.return?.();
-      throw err;
-    };
-    return {
-      async next() {
-        if (first) {
-          first = false;
-          try {
-            check();
-          } catch (err) {
-            return stop(err);
-          }
-        }
-        const r = await it.next();
-        if (r.done === true) return r;
-        const key = r.value >>> 16;
-        if (key !== chunk) {
-          try {
-            check();
-          } catch (err) {
-            return stop(err);
-          }
-          chunk = key;
-        }
-        return r;
-      },
-      async return() {
-        await it.return?.();
-        return { done: true, value: void 0 };
+var done = (value) => ({ done: true, value });
+var guard = (inner, check, keyOf) => {
+  const it = inner[Symbol.asyncIterator]();
+  let first = true;
+  let over = false;
+  let last = -1;
+  const end = async (value) => {
+    over = true;
+    await it.return?.(value);
+    return value;
+  };
+  const stop = async (err) => {
+    await end();
+    throw err;
+  };
+  const deliver = (r) => {
+    if (over) return done();
+    if (r.done === true) return r;
+    const key = keyOf?.(r.value);
+    if (key === void 0 || key !== last) {
+      try {
+        check();
+      } catch (err) {
+        return stop(err);
       }
-    };
-  }
-});
-var guardIds = (inner, check) => ({
-  [Symbol.asyncIterator]: () => guardIdIterable(inner, check)[Symbol.asyncIterator](),
-  batches: () => guardItems(inner.batches(), check)
-});
-var guardItems = (inner, check) => ({
-  [Symbol.asyncIterator]: () => {
-    const it = inner[Symbol.asyncIterator]();
-    let first = true;
-    const stop = async (err) => {
-      await it.return?.();
-      throw err;
-    };
-    return {
-      async next() {
-        if (first) {
-          first = false;
-          try {
-            check();
-          } catch (err) {
-            return stop(err);
-          }
-        }
-        const r = await it.next();
-        if (r.done === true) return r;
+      if (key !== void 0) last = key;
+    }
+    return r;
+  };
+  return {
+    [Symbol.asyncIterator]() {
+      return this;
+    },
+    async next() {
+      if (over) return done();
+      if (first) {
+        first = false;
         try {
           check();
         } catch (err) {
           return stop(err);
         }
-        return r;
-      },
-      async return() {
-        await it.return?.();
-        return { done: true, value: void 0 };
+      }
+      return deliver(await it.next());
+    },
+    async return(value) {
+      return done(await end(value));
+    },
+    async throw(err) {
+      first = false;
+      if (it.throw === void 0) return stop(err);
+      let r;
+      try {
+        r = await it.throw(err);
+      } catch (thrown) {
+        over = true;
+        throw thrown;
+      }
+      return deliver(r);
+    }
+  };
+};
+var guardIdIterable = (inner, check) => guard(inner, check, (id) => id >>> 16);
+var guardIds = (inner, check) => Object.assign(guardIdIterable(inner, check), {
+  batches: () => guardItems(inner.batches(), check)
+});
+var guardItems = (inner, check) => guard(inner, check);
+
+// src/wire-store.ts
+import {
+  CrbmStorageChunkSource,
+  DEFAULT_RETRY_POLICY,
+  NOOP_METRICS,
+  RetryingStorageChunkSource,
+  ValidationError as ValidationError2,
+  isStorageBackend
+} from "@cloudbitmaps/core";
+function resolveRetryPolicy(partial) {
+  const baseDelayMs = partial.baseDelayMs ?? DEFAULT_RETRY_POLICY.baseDelayMs;
+  return {
+    maxAttempts: partial.maxAttempts ?? DEFAULT_RETRY_POLICY.maxAttempts,
+    baseDelayMs,
+    maxDelayMs: partial.maxDelayMs ?? (typeof baseDelayMs === "number" && baseDelayMs > DEFAULT_RETRY_POLICY.maxDelayMs ? baseDelayMs : DEFAULT_RETRY_POLICY.maxDelayMs),
+    backoffFactor: partial.backoffFactor ?? DEFAULT_RETRY_POLICY.backoffFactor,
+    jitter: partial.jitter ?? DEFAULT_RETRY_POLICY.jitter
+  };
+}
+function wireStore(options, clock, rng, metrics) {
+  const resolved = resolveStorageSource(options, clock);
+  if (metrics !== NOOP_METRICS && isStorageBackend(options.storage)) {
+    options.storage.attachMetrics?.(metrics);
+  }
+  let storage = resolved.source;
+  let retryOptions;
+  if (options.retry !== false) {
+    const { onRetry: userOnRetry, ...ov } = options.retry ?? {};
+    if (userOnRetry !== void 0 && typeof userOnRetry !== "function") {
+      throw new ValidationError2("retry.onRetry must be a function");
+    }
+    retryOptions = {
+      clock,
+      rng,
+      policy: resolveRetryPolicy(ov),
+      // Bridge transient-fault retries into the metrics stream, then call the user's own hook.
+      onRetry: (info) => {
+        metrics.onEvent({
+          kind: "retry",
+          reason: "transient",
+          attempt: info.attempt,
+          delayMs: info.delayMs
+        });
+        userOnRetry?.(info);
       }
     };
+    storage = new RetryingStorageChunkSource(storage, retryOptions);
   }
-});
-var guardChunks = (inner, check) => guardItems(inner, check);
+  return {
+    storage,
+    source: resolved.source,
+    driver: resolved.driver,
+    registry: resolved.registry,
+    retryOptions
+  };
+}
+function resolveStorageSource(options, clock) {
+  const storage = options.storage;
+  if (storage === null || typeof storage !== "object") {
+    throw new ValidationError2(
+      "`storage` must be a StorageBackend, an IStorageDriver, or a StorageChunkSource"
+    );
+  }
+  const asBackend = storage;
+  const isObject = (v) => v !== null && typeof v === "object";
+  const hasGetChunk = typeof storage.getChunk === "function";
+  const hasPutImmutable = typeof storage.putImmutable === "function";
+  const isBackend = isStorageBackend(storage);
+  if (isBackend && (hasGetChunk || hasPutImmutable)) {
+    throw new ValidationError2(
+      `\`storage\` is a StorageBackend that also exposes ${hasGetChunk ? "`getChunk`" : "`putImmutable`"} \u2014 ambiguous. A backend must not also be a driver or a source; pass whichever one you mean.`
+    );
+  }
+  const hasStorageHalf = isObject(asBackend.storage);
+  const hasRegistryHalf = isObject(asBackend.registry);
+  if (!isBackend && hasPutImmutable && hasRegistryHalf) {
+    throw new ValidationError2(
+      "`storage` looks like a driver that also carries a `registry`. Passed as a bare driver it would have no pointer at all \u2014 generations would resolve by list-scan, so reads could serve a generation that was written but never published. If you meant a backend, use a backend class \u2014 S3Storage, GcsStorage, AzureBlobStorage, LocalFsStorage or MemoryStorage \u2014 or, to pair a driver of your own with a registry, brand the pair with `brandAsBackend` from `@cloudbitmaps/core/driver-kit`."
+    );
+  }
+  if (!isBackend && !hasGetChunk && !hasPutImmutable && hasStorageHalf && hasRegistryHalf) {
+    const storageOk = typeof asBackend.storage.putImmutable === "function";
+    const registryOk = typeof asBackend.registry.compareAndSwap === "function";
+    if (!storageOk || !registryOk) {
+      const bad = !storageOk ? "`storage` half is not an IStorageDriver (no `putImmutable`)" : "`registry` half is not an IRegistryDriver (no `compareAndSwap`)";
+      throw new ValidationError2(
+        "`storage` looks like a backend but its " + bad + " \u2014 use a backend class, or brand a pair of drivers with `brandAsBackend` from `@cloudbitmaps/core/driver-kit`."
+      );
+    }
+    throw new ValidationError2(
+      "`storage` must be a backend \u2014 S3Storage, GcsStorage, AzureBlobStorage, LocalFsStorage or MemoryStorage. An object with `.storage` and `.registry` is not one: a backend builds both halves from a single bucket and prefix, so they cannot disagree, and hand-assembling them re-opens exactly that mismatch \u2014 a store whose pointer and generations live in different places reads as empty rather than failing. A driver author who genuinely wants halves of their own \u2014 an instrumented driver, a registry in a database you already run \u2014 brands the pair with `brandAsBackend` from `@cloudbitmaps/core/driver-kit`, which is taking on that they agree."
+    );
+  }
+  if (isBackend) {
+    const backend = storage;
+    return {
+      source: new CrbmStorageChunkSource(backend.storage, {
+        registry: backend.registry,
+        keystore: options.encryption?.keystore,
+        requireEncryption: options.encryption?.required,
+        clock,
+        currentGenTtlMs: options.cache?.genTtlMs,
+        maxOpenSegments: options.cache?.readerMax,
+        maxOpenIndexBytes: options.cache?.readerMaxBytes
+      }),
+      driver: backend.storage,
+      registry: backend.registry
+    };
+  }
+  if (hasGetChunk && hasPutImmutable) {
+    throw new ValidationError2(
+      "`storage` exposes both `getChunk` and `putImmutable` \u2014 ambiguous; pass a StorageBackend, an IStorageDriver, or a StorageChunkSource, not a hybrid"
+    );
+  }
+  if (!hasGetChunk && !hasPutImmutable) {
+    throw new ValidationError2(
+      "`storage` must be a StorageBackend, an IStorageDriver, or a StorageChunkSource"
+    );
+  }
+  if (hasGetChunk) {
+    if (options.encryption?.keystore !== void 0 || options.encryption?.required === true) {
+      throw new ValidationError2(
+        "keystore/requireEncryption apply only when the store builds its own read path; configure them on the StorageChunkSource you passed instead"
+      );
+    }
+    return { source: storage, driver: void 0, registry: void 0 };
+  }
+  const driver = storage;
+  return {
+    source: new CrbmStorageChunkSource(driver, {
+      keystore: options.encryption?.keystore,
+      requireEncryption: options.encryption?.required,
+      clock,
+      currentGenTtlMs: options.cache?.genTtlMs,
+      maxOpenSegments: options.cache?.readerMax,
+      maxOpenIndexBytes: options.cache?.readerMaxBytes
+    }),
+    driver,
+    registry: void 0
+  };
+}
+
+// src/options.ts
+import { ValidationError as ValidationError3 } from "@cloudbitmaps/core";
+var keysOf = () => (keys) => keys;
+var kindOf = (v) => v === null ? "null" : Array.isArray(v) ? "an array" : `a ${typeof v}`;
+function optionsError(options, op, known, booleans = []) {
+  if (options === void 0 || options === null) return void 0;
+  if (typeof options !== "object" || Array.isArray(options)) {
+    return new ValidationError3(`${op}: options must be an object; got ${kindOf(options)}`);
+  }
+  const bag = options;
+  const unknown = Object.keys(bag).filter((k) => !known.includes(k) && bag[k] !== void 0);
+  if (unknown.length > 0) {
+    return new ValidationError3(
+      `${op}: unknown option${unknown.length > 1 ? "s" : ""} ${unknown.map((k) => `"${k}"`).join(", ")}; it takes { ${known.join(", ")} }`
+    );
+  }
+  const audit = bag.audit;
+  if (audit !== void 0 && audit !== null && typeof audit.onEvent !== "function") {
+    return new ValidationError3(
+      `${op}: audit must be a sink with an onEvent(event) method, such as a RecordingAuditSink`
+    );
+  }
+  for (const name of booleans) {
+    const v = bag[name];
+    if (v !== void 0 && typeof v !== "boolean") {
+      return new ValidationError3(`${op}: \`${name}\` must be a boolean; got ${kindOf(v)}`);
+    }
+  }
+  return void 0;
+}
+function picked(options, keys) {
+  const out = {};
+  if (options === void 0 || options === null) return out;
+  for (const key of keys) {
+    const value = options[key];
+    if (value !== void 0) out[key] = value;
+  }
+  return out;
+}
+function checkOptions(options, op, known, booleans) {
+  const err = optionsError(options, op, known, booleans);
+  if (err !== void 0) throw err;
+}
 
 // src/index.ts
 import {
   MemoryStorage,
   LocalFsStorage,
-  CrbmStorageChunkSource as CrbmStorageChunkSource2,
+  CrbmStorageChunkSource as CrbmStorageChunkSource3,
   destroySegment,
   eraseNamespace,
   excludingReservedRows as excludingReservedRows2,
@@ -625,7 +799,7 @@ import {
   NodeAead,
   aadFor,
   CloudRoaringError,
-  ValidationError as ValidationError3,
+  ValidationError as ValidationError5,
   WriteConflictError as WriteConflictError2,
   IntegrityError as IntegrityError3,
   NotFoundError as NotFoundError2,
@@ -654,7 +828,7 @@ import {
   BufferReader,
   CountingMetricsSink,
   RecordingAuditSink,
-  DEFAULT_RETRY_POLICY as DEFAULT_RETRY_POLICY2
+  DEFAULT_RETRY_POLICY as DEFAULT_RETRY_POLICY3
 } from "@cloudbitmaps/core";
 var SystemRng = class {
   /** A float in `[0, 1)`. Jitter only — never key material, never anything a caller can observe. */
@@ -670,14 +844,12 @@ function rowVersionOfLive(version) {
   return cut < 0 ? version : version.slice(0, cut);
 }
 function validateConcurrency(concurrency) {
-  if (concurrency !== void 0 && (!Number.isInteger(concurrency) || concurrency < 1)) {
-    throw new ValidationError2(`concurrency must be a positive integer; got ${concurrency}`);
-  }
+  requirePositiveInt("concurrency", concurrency);
 }
 function requireScope(options, op) {
   if (options.namespace !== void 0) {
     if (typeof options.namespace !== "string") {
-      throw new ValidationError2(
+      throw new ValidationError4(
         `${op}: namespace must be a string; got ${kindOf(options.namespace)}`
       );
     }
@@ -685,12 +857,11 @@ function requireScope(options, op) {
   }
   refuseReservedNamespace(options.namespace);
   if (options.namespace === void 0 && options.allNamespaces !== true) {
-    throw new ValidationError2(
+    throw new ValidationError4(
       `${op} scans the global id space across all namespaces \u2014 pass an explicit \`namespace\`, or \`{ allNamespaces: true }\` to intentionally sweep the whole fleet`
     );
   }
 }
-var keysOf = () => (keys) => keys;
 var CALL_KEYS = {
   range: keysOf()(["after", "through"]),
   andNot: keysOf()([
@@ -750,7 +921,7 @@ var CALL_KEYS = {
   ]),
   rollback: keysOf()([
     "audit",
-    "allowForward"
+    "allowUnknown"
   ]),
   dropSegment: keysOf()([
     "confirmSegment",
@@ -774,50 +945,12 @@ var CALL_KEYS = {
   checkConsistency: keysOf()([
     "namespace",
     "concurrency",
-    "summaries"
+    "summaries",
+    "generations"
   ]),
   exportSegments: keysOf()(["format", "codec", "namespace", "ndjsonBatchBytes"])
 };
-var kindOf = (v) => v === null ? "null" : Array.isArray(v) ? "an array" : `a ${typeof v}`;
-function optionsError(options, op, known, booleans = []) {
-  if (options === void 0 || options === null) return void 0;
-  if (typeof options !== "object" || Array.isArray(options)) {
-    return new ValidationError2(`${op}: options must be an object; got ${kindOf(options)}`);
-  }
-  const bag = options;
-  const unknown = Object.keys(bag).filter((k) => !known.includes(k) && bag[k] !== void 0);
-  if (unknown.length > 0) {
-    return new ValidationError2(
-      `${op}: unknown option${unknown.length > 1 ? "s" : ""} ${unknown.map((k) => `"${k}"`).join(", ")}; it takes { ${known.join(", ")} }`
-    );
-  }
-  const audit = bag.audit;
-  if (audit !== void 0 && audit !== null && typeof audit.onEvent !== "function") {
-    return new ValidationError2(
-      `${op}: audit must be a sink with an onEvent(event) method, such as a RecordingAuditSink`
-    );
-  }
-  for (const name of booleans) {
-    const v = bag[name];
-    if (v !== void 0 && typeof v !== "boolean") {
-      return new ValidationError2(`${op}: \`${name}\` must be a boolean; got ${kindOf(v)}`);
-    }
-  }
-  return void 0;
-}
-function picked(options, keys) {
-  const out = {};
-  if (options === void 0 || options === null) return out;
-  for (const key of keys) {
-    const value = options[key];
-    if (value !== void 0) out[key] = value;
-  }
-  return out;
-}
-function checkOptions(options, op, known, booleans) {
-  const err = optionsError(options, op, known, booleans);
-  if (err !== void 0) throw err;
-}
+var SEGMENT_BRAND = /* @__PURE__ */ Symbol.for("cloudbitmaps.roaring.segment/1");
 var viewOf;
 var MATERIALIZE_MANY_KEYS = [
   "operands",
@@ -849,91 +982,6 @@ var DEFAULT_MAX_BUFFERED_BYTES = 256 * 1024 * 1024;
 var DEFAULT_PUBLISH_CONCURRENCY = 8;
 var DEFAULT_BATCH_CONCURRENCY = 1;
 var PIN_PARALLELISM = 16;
-function resolveStorageSource(options, clock) {
-  const storage = options.storage;
-  if (storage === null || typeof storage !== "object") {
-    throw new ValidationError2(
-      "`storage` must be a StorageBackend, an IStorageDriver, or a StorageChunkSource"
-    );
-  }
-  const asBackend = storage;
-  const isObject = (v) => v !== null && typeof v === "object";
-  const hasGetChunk = typeof storage.getChunk === "function";
-  const hasPutImmutable = typeof storage.putImmutable === "function";
-  const isBackend = isStorageBackend(storage);
-  if (isBackend && (hasGetChunk || hasPutImmutable)) {
-    throw new ValidationError2(
-      `\`storage\` is a StorageBackend that also exposes ${hasGetChunk ? "`getChunk`" : "`putImmutable`"} \u2014 ambiguous. A backend must not also be a driver or a source; pass whichever one you mean.`
-    );
-  }
-  const hasStorageHalf = isObject(asBackend.storage);
-  const hasRegistryHalf = isObject(asBackend.registry);
-  if (!isBackend && hasPutImmutable && hasRegistryHalf) {
-    throw new ValidationError2(
-      "`storage` looks like a driver that also carries a `registry`. Passed as a bare driver it would have no pointer at all \u2014 generations would resolve by list-scan, so reads could serve a generation that was written but never published. If you meant a backend, use a backend class \u2014 S3Storage, GcsStorage, AzureBlobStorage, LocalFsStorage or MemoryStorage \u2014 or, to pair a driver of your own with a registry, brand the pair with `brandAsBackend` from `@cloudbitmaps/core/driver-kit`."
-    );
-  }
-  if (!isBackend && !hasGetChunk && !hasPutImmutable && hasStorageHalf && hasRegistryHalf) {
-    const storageOk = typeof asBackend.storage.putImmutable === "function";
-    const registryOk = typeof asBackend.registry.compareAndSwap === "function";
-    if (!storageOk || !registryOk) {
-      const bad = !storageOk ? "`storage` half is not an IStorageDriver (no `putImmutable`)" : "`registry` half is not an IRegistryDriver (no `compareAndSwap`)";
-      throw new ValidationError2(
-        "`storage` looks like a backend but its " + bad + " \u2014 use a backend class, or brand a pair of drivers with `brandAsBackend` from `@cloudbitmaps/core/driver-kit`."
-      );
-    }
-    throw new ValidationError2(
-      "`storage` must be a backend \u2014 S3Storage, GcsStorage, AzureBlobStorage, LocalFsStorage or MemoryStorage. An object with `.storage` and `.registry` is not one: a backend builds both halves from a single bucket and prefix, so they cannot disagree, and hand-assembling them re-opens exactly that mismatch \u2014 a store whose pointer and generations live in different places reads as empty rather than failing. A driver author who genuinely wants halves of their own \u2014 an instrumented driver, a registry in a database you already run \u2014 brands the pair with `brandAsBackend` from `@cloudbitmaps/core/driver-kit`, which is taking on that they agree."
-    );
-  }
-  if (isBackend) {
-    const backend = storage;
-    return {
-      source: new CrbmStorageChunkSource(backend.storage, {
-        registry: backend.registry,
-        keystore: options.encryption?.keystore,
-        requireEncryption: options.encryption?.required,
-        clock,
-        currentGenTtlMs: options.cache?.genTtlMs,
-        maxOpenSegments: options.cache?.readerMax,
-        maxOpenIndexBytes: options.cache?.readerMaxBytes
-      }),
-      driver: backend.storage,
-      registry: backend.registry
-    };
-  }
-  if (hasGetChunk && hasPutImmutable) {
-    throw new ValidationError2(
-      "`storage` exposes both `getChunk` and `putImmutable` \u2014 ambiguous; pass a StorageBackend, an IStorageDriver, or a StorageChunkSource, not a hybrid"
-    );
-  }
-  if (!hasGetChunk && !hasPutImmutable) {
-    throw new ValidationError2(
-      "`storage` must be a StorageBackend, an IStorageDriver, or a StorageChunkSource"
-    );
-  }
-  if (hasGetChunk) {
-    if (options.encryption?.keystore !== void 0 || options.encryption?.required === true) {
-      throw new ValidationError2(
-        "keystore/requireEncryption apply only when the store builds its own read path; configure them on the StorageChunkSource you passed instead"
-      );
-    }
-    return { source: storage, driver: void 0, registry: void 0 };
-  }
-  const driver = storage;
-  return {
-    source: new CrbmStorageChunkSource(driver, {
-      keystore: options.encryption?.keystore,
-      requireEncryption: options.encryption?.required,
-      clock,
-      currentGenTtlMs: options.cache?.genTtlMs,
-      maxOpenSegments: options.cache?.readerMax,
-      maxOpenIndexBytes: options.cache?.readerMaxBytes
-    }),
-    driver,
-    registry: void 0
-  };
-}
 var NOT_A_GROUP = {
   Null: "null",
   Array: "an array",
@@ -976,7 +1024,7 @@ var CloudRoaring = class _CloudRoaring {
    */
   static rejectUnknownOptions(options) {
     if (options === null || options === void 0 || typeof options !== "object") {
-      throw new ValidationError2(
+      throw new ValidationError4(
         "CloudRoaring needs an options object with a `storage` key \u2014 got " + (options === null ? "null" : typeof options)
       );
     }
@@ -994,7 +1042,7 @@ var CloudRoaring = class _CloudRoaring {
       const tag = Object.prototype.toString.call(value).slice(8, -1);
       if (typeof value !== "object" || value === null || NOT_A_GROUP[tag] !== void 0) {
         const got = typeof value !== "object" ? typeof value : NOT_A_GROUP[tag];
-        throw new ValidationError2(
+        throw new ValidationError4(
           `CloudRoaring's \`${group}\` must be an object${offOk ? " or `false`" : ""} \u2014 got ${got}`
         );
       }
@@ -1004,7 +1052,7 @@ var CloudRoaring = class _CloudRoaring {
     if (unknown.length === 0) return;
     const takes = (keys) => keys.map((k) => `\`${k}\``).join(", ");
     const named = [...new Set(unknown.map((u) => u.group))];
-    throw new ValidationError2(
+    throw new ValidationError4(
       `CloudRoaring does not take ${takes(unknown.map((u) => u.group === null ? u.key : `${u.group}.${u.key}`))}. ` + named.map(
         (g) => g === null ? `The store takes ${takes(OPTION_KEYS.top)}.` : `\`${g}\` takes ${takes(OPTION_KEYS[g])}.`
       ).join(" ") + " https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/api-reference.md#build-a-store--new-cloudroaringoptions"
@@ -1024,7 +1072,7 @@ var CloudRoaring = class _CloudRoaring {
       if (seam === void 0 || seam === null) continue;
       const has = (m) => typeof seam[m] === "function";
       if (typeof seam !== "object" || !needs.every(has)) {
-        throw new ValidationError2(
+        throw new ValidationError4(
           `CloudRoaring's \`${name}\` must be an object with ${needs.map((m) => `\`${m}()\``).join(" and ")}`
         );
       }
@@ -1035,50 +1083,17 @@ var CloudRoaring = class _CloudRoaring {
     _CloudRoaring.rejectHollowSeams(options);
     const clock = options.seams?.clock ?? new SystemClock();
     const rng = options.seams?.rng ?? new SystemRng();
-    const metrics = safeMetrics(options.metrics ?? NOOP_METRICS);
+    const metrics = safeMetrics(options.metrics ?? NOOP_METRICS2);
     const cache = new BoundedLru({
       maxEntries: options.cache?.maxChunks ?? DEFAULT_CACHE_MAX_CHUNKS,
       ttlMs: options.cache?.ttlMs,
       clock
     });
-    const resolved = resolveStorageSource(options, clock);
-    if (metrics !== NOOP_METRICS && isStorageBackend(options.storage)) {
-      options.storage.attachMetrics?.(metrics);
-    }
-    let storage = resolved.source;
-    if (options.retry !== false) {
-      const { onRetry: userOnRetry, ...ov } = options.retry ?? {};
-      if (userOnRetry !== void 0 && typeof userOnRetry !== "function") {
-        throw new ValidationError2("retry.onRetry must be a function");
-      }
-      const policy = {
-        maxAttempts: ov.maxAttempts ?? DEFAULT_RETRY_POLICY.maxAttempts,
-        baseDelayMs: ov.baseDelayMs ?? DEFAULT_RETRY_POLICY.baseDelayMs,
-        maxDelayMs: ov.maxDelayMs ?? DEFAULT_RETRY_POLICY.maxDelayMs,
-        backoffFactor: ov.backoffFactor ?? DEFAULT_RETRY_POLICY.backoffFactor,
-        jitter: ov.jitter ?? DEFAULT_RETRY_POLICY.jitter
-      };
-      const retryOpts = {
-        clock,
-        rng,
-        policy,
-        // Bridge transient-fault retries into the metrics stream, then call the user's own hook.
-        onRetry: (info) => {
-          metrics.onEvent({
-            kind: "retry",
-            reason: "transient",
-            attempt: info.attempt,
-            delayMs: info.delayMs
-          });
-          userOnRetry?.(info);
-        }
-      };
-      storage = new RetryingStorageChunkSource(storage, retryOpts);
-      this.retryOptions = retryOpts;
-    }
+    const wired = wireStore(options, clock, rng, metrics);
+    this.retryOptions = wired.retryOptions;
     this.budget = resolveBudget(options.budget, DEFAULT_BUDGET);
     const deps = {
-      storage,
+      storage: wired.storage,
       cache,
       codec: roaringCodec,
       // the facade injects the flagship codec; core stays codec-agnostic
@@ -1088,12 +1103,12 @@ var CloudRoaring = class _CloudRoaring {
     };
     this.engine = new SegmentEngine(deps);
     this.cache = cache;
-    this.crbmSource = resolved.source instanceof CrbmStorageChunkSource ? resolved.source : void 0;
+    this.crbmSource = wired.source instanceof CrbmStorageChunkSource2 ? wired.source : void 0;
     this.clock = clock;
     this.rng = rng;
     this.metrics = metrics;
-    this.storageDriver = resolved.driver;
-    this.registry = resolved.registry;
+    this.storageDriver = wired.driver;
+    this.registry = wired.registry;
     this.keystore = options.encryption?.keystore;
     this.requireEncryption = options.encryption?.required ?? false;
   }
@@ -1137,11 +1152,11 @@ var CloudRoaring = class _CloudRoaring {
   segment(name, options) {
     if (options !== void 0 && options !== null) {
       if (typeof options !== "object" || Array.isArray(options)) {
-        throw new ValidationError2("segment: options must be an object such as { namespace }");
+        throw new ValidationError4("segment: options must be an object such as { namespace }");
       }
       const proto = Object.getPrototypeOf(options);
       if (proto !== null && Object.getPrototypeOf(proto) !== null) {
-        throw new ValidationError2(
+        throw new ValidationError4(
           "segment: options must be a plain object such as { namespace }, not a class instance or an object built on another"
         );
       }
@@ -1149,7 +1164,7 @@ var CloudRoaring = class _CloudRoaring {
         (k) => k !== "namespace" && options[k] !== void 0
       );
       if (unknown.length > 0) {
-        throw new ValidationError2(
+        throw new ValidationError4(
           `segment: unknown option${unknown.length > 1 ? "s" : ""} ${unknown.map((k) => `"${k}"`).join(", ")}; a handle takes { namespace } only`
         );
       }
@@ -1184,7 +1199,7 @@ var CloudRoaring = class _CloudRoaring {
    * row it is kept (hard invariant 1: deleting it after a purge-and-recreate would put a live row over a missing
    * generation).
    *
-   * Where the row is gone, or keyed over a cleartext write, the object is proved the load's own by its footer, and
+   * Where the row is gone, or keyed over a cleartext write, the object's footer must match what the load wrote, and
    * the delete passes the version that read reported, so on a storage driver that reports `conditionalDelete` an
    * object put under the number since is kept. Where the row is unchanged or `destroyed`, the check narrows the
    * window rather than closing it: the row read and the delete are two round trips, and the delete is by number,
@@ -1239,9 +1254,9 @@ var CloudRoaring = class _CloudRoaring {
     }
     const reason = result.reason;
     if (reason === "superseded") {
-      const wrote = result.size > 0 ? `generation ${result.generation} was written and is not current` : `nothing was written \u2014 another writer took generation ${result.generation} first`;
+      const wrote = result.size > 0 ? `generation ${result.generation} was written and may not be current` : `nothing was written \u2014 another writer took generation ${result.generation} first`;
       throw new WriteConflictError(
-        `${op}: the destination "${dest.segment}" changed while this materialisation was in flight, so its result is not the destination's current generation: ${wrote}. The pointer may have moved, the row may have been created or rewritten (a retention policy does either), dropped or purged. Re-read the destination and re-run.`
+        `${op}: the destination "${dest.segment}" changed while this materialisation was in flight, so its result may not be the destination's current generation: ${wrote}. The pointer may have moved, the row may have been created or rewritten (a retention policy does either), dropped or purged. Re-read the destination and re-run.`
       );
     }
     return {
@@ -1258,7 +1273,7 @@ var CloudRoaring = class _CloudRoaring {
   /** The one body of the forms above. */
   async materializeMany(options) {
     if (typeof options !== "object" || options === null) {
-      throw new ValidationError2(
+      throw new ValidationError4(
         "materializeMany needs an options object with `operands`, `outputs` and `keep`"
       );
     }
@@ -1267,13 +1282,13 @@ var CloudRoaring = class _CloudRoaring {
       (k) => !MATERIALIZE_MANY_KEYS.includes(k)
     );
     if (unknown.length > 0) {
-      throw new ValidationError2(
+      throw new ValidationError4(
         `materializeMany: unknown option${unknown.length > 1 ? "s" : ""} ${unknown.map((k) => `"${k}"`).join(", ")}`
       );
     }
     const dryRunIn = options.dryRun;
     if (dryRunIn !== void 0 && typeof dryRunIn !== "boolean") {
-      throw new ValidationError2("materializeMany: dryRun must be a boolean");
+      throw new ValidationError4("materializeMany: dryRun must be a boolean");
     }
     const dryRun = dryRunIn === true;
     const operandsIn = options.operands;
@@ -1285,7 +1300,7 @@ var CloudRoaring = class _CloudRoaring {
     const feedIn = options.feed;
     const mayBeEmptyIn = options.mayBeEmpty;
     if (feedIn !== void 0 && options.maxBufferedBytes === void 0) {
-      throw new ValidationError2(
+      throw new ValidationError4(
         "materializeMany: maxBufferedBytes is required with a feed: the feed is read once, so the call runs as one group and the budget is what bounds it"
       );
     }
@@ -1295,22 +1310,22 @@ var CloudRoaring = class _CloudRoaring {
     const budgetOption = options.budget;
     const allowAbsentOperands = options.allowAbsentOperands;
     if (typeof pinOption !== "boolean")
-      throw new ValidationError2("materializeMany: pin must be a boolean");
+      throw new ValidationError4("materializeMany: pin must be a boolean");
     if (allowAbsentOperands !== void 0 && typeof allowAbsentOperands !== "boolean") {
-      throw new ValidationError2("materializeMany: allowAbsentOperands must be a boolean");
+      throw new ValidationError4("materializeMany: allowAbsentOperands must be a boolean");
     }
     if (typeof operandsIn !== "object" || operandsIn === null || Array.isArray(operandsIn)) {
-      throw new ValidationError2("materializeMany: operands must be an object of name to segment");
+      throw new ValidationError4("materializeMany: operands must be an object of name to segment");
     }
     if (!Array.isArray(outputsIn) || outputsIn.length === 0) {
-      throw new ValidationError2("materializeMany: outputs must be a non-empty array");
+      throw new ValidationError4("materializeMany: outputs must be a non-empty array");
     }
     const names = Object.keys(operandsIn);
     const handles = /* @__PURE__ */ new Map();
     for (const name of names) {
       const handle = operandsIn[name];
       if (!(handle instanceof Segment)) {
-        throw new ValidationError2(
+        throw new ValidationError4(
           `materializeMany: operands["${name}"] must be a segment from store.segment()`
         );
       }
@@ -1318,14 +1333,14 @@ var CloudRoaring = class _CloudRoaring {
     }
     if (mayBeEmptyIn !== void 0 && feedIn === void 0) {
       if (!Array.isArray(mayBeEmptyIn)) {
-        throw new ValidationError2(
+        throw new ValidationError4(
           "materializeMany: mayBeEmpty must be an array of fed operand names"
         );
       }
       if (mayBeEmptyIn.length > 0) {
         const first = mayBeEmptyIn[0];
         const what = typeof first !== "string" ? "something that is not a name" : handles.has(first) ? `"${first}", a stored operand` : `"${first}", which is not an operand of this call`;
-        throw new ValidationError2(
+        throw new ValidationError4(
           `materializeMany: mayBeEmpty names ${what}; it names fed operands, and this call has no feed`
         );
       }
@@ -1335,28 +1350,28 @@ var CloudRoaring = class _CloudRoaring {
     const destKeys = /* @__PURE__ */ new Set();
     outputsIn.forEach((raw, i) => {
       if (typeof raw !== "object" || raw === null) {
-        throw new ValidationError2(`outputs[${i}] must be an object`);
+        throw new ValidationError4(`outputs[${i}] must be an object`);
       }
       const bad = Object.keys(raw).filter(
         (k) => !MATERIALIZE_MANY_OUTPUT_KEYS.includes(k)
       );
       if (bad.length > 0) {
-        throw new ValidationError2(
+        throw new ValidationError4(
           `outputs[${i}]: unknown option${bad.length > 1 ? "s" : ""} ${bad.map((k) => `"${k}"`).join(", ")}`
         );
       }
       const spec = raw;
       const dest = spec.dest;
       if (!(dest instanceof Segment)) {
-        throw new ValidationError2(`outputs[${i}].dest must be a segment from store.segment()`);
+        throw new ValidationError4(`outputs[${i}].dest must be a segment from store.segment()`);
       }
       if (operandKeys.has(dest.key())) {
-        throw new ValidationError2(
+        throw new ValidationError4(
           `outputs[${i}].dest is also an operand of the call: one call is one pass over operands that do not change under it, so chain two calls`
         );
       }
       if (destKeys.has(dest.key())) {
-        throw new ValidationError2(
+        throw new ValidationError4(
           `outputs[${i}].dest names a segment another output of the call writes`
         );
       }
@@ -1376,7 +1391,7 @@ var CloudRoaring = class _CloudRoaring {
         ...pinnedAt === void 0 ? {} : {
           pinnedGeneration: pinnedAt.generation,
           pinnedVersion: pinnedAt.version,
-          pinnedFingerprint: pinnedAt.fingerprint ?? null
+          pinnedFingerprint: pinnedAt.fingerprint
         },
         current: (read) => this.currentRowOf(seg.ref, read?.fingerprint === true)
       };
@@ -1429,13 +1444,13 @@ var CloudRoaring = class _CloudRoaring {
         held.set(key, { at, handle });
       } else if (prior.at !== void 0 && at !== void 0) {
         if (!samePin(prior.at, at)) {
-          throw new ValidationError2(
+          throw new ValidationError4(
             `materializeMany: operand "${name}" holds a segment another operand holds, ${twoPins(prior.at, at)}: one call reads a segment at one generation`
           );
         }
       } else if (prior.at !== void 0 || at !== void 0) {
         if (!pinOption) {
-          throw new ValidationError2(
+          throw new ValidationError4(
             `materializeMany: operand "${name}" holds a segment another operand holds, ${twoPins(prior.at, at)}: one call reads a segment at one generation`
           );
         }
@@ -1449,7 +1464,7 @@ var CloudRoaring = class _CloudRoaring {
       else if (pinOption) toPin.push([key, handle]);
       else pins.set(key, void 0);
     }
-    const metricsOn = this.metrics !== NOOP_METRICS;
+    const metricsOn = this.metrics !== NOOP_METRICS2;
     const work = async () => {
       const taken = await mapWithConcurrency(
         toPin,
@@ -1459,7 +1474,7 @@ var CloudRoaring = class _CloudRoaring {
       for (const [key, at] of taken) pins.set(key, at);
       const live = new Map([...pins].filter((e) => e[1] !== void 0));
       const pinnedSource = new PinnedStorageChunkSource(crbm, live);
-      const source = this.retryOptions === void 0 ? pinnedSource : new RetryingStorageChunkSource(pinnedSource, this.retryOptions);
+      const source = this.retryOptions === void 0 ? pinnedSource : new RetryingStorageChunkSource2(pinnedSource, this.retryOptions);
       const final = rebindCombineMany(compiled, operandSpecs(pins));
       return runCombineMany(final, {
         source,
@@ -1523,7 +1538,7 @@ var CloudRoaring = class _CloudRoaring {
   /** A call's feed with the store's erasure counter: read once here, checked by the combine before any record is read. */
   feedOf(feed, mayBeEmpty, epochAt) {
     if (typeof feed !== "object" || feed === null || Array.isArray(feed)) {
-      throw new ValidationError2(
+      throw new ValidationError4(
         "materializeMany: feed must be an object with names, records and counts"
       );
     }
@@ -1761,6 +1776,8 @@ var CloudRoaring = class _CloudRoaring {
    * What the bucket holds, not what the segment has ever been — collection deletes superseded objects, so this is
    * the grace window plus whatever has not been collected yet. It is the set {@link CloudRoaring.rollback} can
    * choose from, which is the reason to look at it. One registry read and one listing; it does not open the objects.
+   * Each entry says whether the row knows the generation (`known`): a known generation needs no `allowUnknown`; an unknown
+   * one does, except below a row's pointer when the row has no usable record or the target is older than a full one reaches.
    *
    * Needs a backend.
    */
@@ -1845,36 +1862,58 @@ var CloudRoaring = class _CloudRoaring {
    * (`segment.rollback`), because every other pointer move can be reconstructed from "a load happened" and this
    * one cannot.
    *
-   * It refuses rather than guesses: a generation not in the bucket (collected, or never written) throws
-   * `NotFoundError` naming what *is* available, a crypto-shredded segment throws
-   * {@link ValidationError} because every generation of it is unreadable, and a target that is cleartext under an
-   * encrypted segment, or encrypted under a cleartext one, throws {@link IntegrityError} from one tail read of it,
-   * because every read would refuse it. Rolling to the generation already current is a no-op that reports itself.
+   * It refuses rather than guesses. The row records, in `knownGens`, the generations its loads and rollbacks made
+   * current, each with the footer checksum of its object, and a rollback moves only onto one of those: a generation the
+   * row does not know (a load that wrote its object and died before the publish, a refused load's object, an object
+   * sealed under a key no row holds, a load published after the point a registry was restored to) throws
+   * {@link ValidationError} before any request to storage, and a known one whose object carries another checksum than
+   * the recorded one throws {@link IntegrityError}, with or without a keystore, since the footer is in the clear. A
+   * generation not in the bucket (collected, or never written) throws `NotFoundError` naming what *is* available, a
+   * crypto-shredded segment throws {@link ValidationError} because every generation of it is unreadable, and a target
+   * that is cleartext under an encrypted segment, or encrypted under a cleartext one, throws {@link IntegrityError} from
+   * one tail read of it, because every read would refuse it. Rolling to the generation already current is a no-op that
+   * reports itself, once one footer read finds its object in the bucket (and the one the row recorded); when the object is
+   * gone it throws `NotFoundError` naming what is.
    *
    * The same tail read (and a range read when the target's index is longer than it) gives the target's id count and
    * metadata, which the rollback writes into the row with the pointer, so a reader that sees the target as current sees
    * what describes it. The store's keystore opens an encrypted target for this; without it, or when it cannot open the
-   * key for any reason, the segment still rolls back and the row carries no summary of the target.
+   * key (it holds none of the key's KEKs, one it holds does not unwrap it, or it throws `TransientError` or times out
+   * as `AbortSignal.timeout()` and the AWS SDK report a timeout), a rollback onto a known generation still happens,
+   * opening nothing, and the row carries no summary of the target. Any other failure of the keystore is
+   * thrown. A swap of the pointer that gets no answer is settled by reading the row: one that landed, the row being the
+   * one the swap leaves, is checked as any is, and otherwise its `TransientError` is thrown. After the swap the target's
+   * footer is read once more, and the pointer put back if the object is gone or is another.
    *
    * It deletes nothing. The generations above the new pointer stay put — which is what makes this reversible —
-   * and are then *above* `currentGen`, where collection never looks. They remain until loads pass them (the first
-   * load whose number one of them holds numbers above them all, and collection then keeps the newest `keep` of what is
-   * below its pointer), {@link CloudRoaring.dropSegment}
+   * and are then *above* `currentGen`, where collection never looks, and still known to the row, so rolling forward onto
+   * one needs no flag. They remain until loads pass them (the first load whose
+   * number one of them holds numbers above them all, and collection then keeps `keep` of what is below its pointer, the
+   * generation that load superseded first), {@link CloudRoaring.dropSegment}
    * deletes them, or {@link CloudRoaring.eraseSubject} does: all of those present when it rewrites, and, when the
    * current generation does not hold the id, only those holding it and any no read of the segment can open, whatever
    * the id. An operator who has just undone a bad load should not have the
    * evidence collected out from under them, while a rollback target that still holds erased data would make the
    * erasure undoable.
    *
-   * A target **above** the pointer needs `{ allowForward: true }`, and is refused with {@link ValidationError}
-   * without it: that is also where objects live that were never published, such as a load that wrote its object
-   * and died before the publish. Undoing an earlier rollback is what the opt-in is for.
+   * `{ allowUnknown: true }` moves onto a present object the row does not vouch for, or one whose checksum differs from
+   * the recorded one, as long as it is the segment's kind of object, opens, and names the generation, and records it as
+   * known (over a usable record; a row with none stays without one). On an encrypted segment, outside the two cases the pointer alone decides (below), it also needs the key: with no keystore, or one that holds none of the key's KEKs or
+   * one that does not unwrap it, it is refused with `KeyUnavailableError` before the target is read, since an object
+   * sealed under a key no row holds passes every check that needs no key, and a key service that did not answer in
+   * time is thrown as `TransientError`, to retry. Every move the row did not vouch for is audited with `unknown: true`.
+   * Two cases are decided by the pointer alone: a target below it needs no flag, no key and no checksum check, and the
+   * move is audited the same way. They are a row with no usable `knownGens` (a registry that drops the field, or a pointer
+   * moved by hand), and a target numbered below the bound of a full record (128 entries or more, leased ones included),
+   * which is its least recently current entry that no lease names (an `*Into` destination keeps every generation in the
+   * bucket and names only the newest 128). A generation a publish with a smaller `keep` no longer names but that stays in
+   * the bucket (a lease spared it, or its delete failed) needs `allowUnknown` until a later listing collects it.
    *
    * Needs a backend.
    */
   async rollback(ref, toGeneration, options = {}) {
     validateSegmentRef(ref);
-    checkOptions(options, "rollback", CALL_KEYS.rollback, ["allowForward"]);
+    checkOptions(options, "rollback", CALL_KEYS.rollback, ["allowUnknown"]);
     options ??= {};
     const deps = this.lifecycleDeps("rollback");
     try {
@@ -1931,12 +1970,16 @@ var CloudRoaring = class _CloudRoaring {
    * published, a retention change, a rollback or an erasure wrote the row, or the row was deleted.
    *
    * A refused load deletes the object it wrote before returning — it sits above `currentGen`, where generation
-   * collection deliberately never looks — but only while the segment's registry row is unchanged (or differs only
-   * in its leases), `destroyed` or gone, or has key material when the load wrote cleartext, which has no place in an
-   * encrypted segment's bucket. Under a row that is gone or keyed, a read of the object's footer must prove it the
-   * load's own first. Once another write has otherwise changed the row, the generation number it holds may name
-   * another incarnation's live object, so it leaves the orphan rather than risk deleting live data. No row's list
-   * names it, so it takes no place in a window, and a listing deletes it once a later generation is current above it.
+   * collection deliberately never looks — but only while the segment's registry row is unchanged (or differs only in
+   * its leases), `destroyed` or gone, or has key material when the load wrote cleartext, which has no place in an
+   * encrypted segment's bucket. Under a row that is gone or keyed, one read of the object's footer must match what the
+   * load wrote first. Once another write has otherwise changed the row, the generation number it holds may name another
+   * writer's object, and a footer names bytes, not the load that wrote them, so it leaves the orphan rather than risk
+   * deleting live data. A publish never adds the orphan to the row's list, and a load's listing deletes it once a
+   * generation above it is current, unless the row's list names it; where the row records none (after a rollback, or
+   * with a `keep` above 64), that listing's window can keep it and, at a `keep` up to 64, record it, and the publishes
+   * after carry it until the window pushes it out. Until it goes, a rollback onto it is refused unless `allowUnknown` is passed, since the list never names it (a list seeded
+   * over a row with none can); with the override it publishes what no load published.
    *
    * **Collection is by name at any `keep` up to 64.** The segment's row records the generations a load keeps, so a load
    * that found nothing above the pointer deletes the generations its publish pushed out of the window and lists
@@ -2027,7 +2070,7 @@ var CloudRoaring = class _CloudRoaring {
   async dropSegment(ref, options) {
     validateSegmentRef(ref);
     if (options === void 0 || options === null) {
-      throw new ValidationError2("dropSegment: options { confirmSegment } are required");
+      throw new ValidationError4("dropSegment: options { confirmSegment } are required");
     }
     checkOptions(options, "dropSegment", CALL_KEYS.dropSegment, ["dryRun"]);
     const deps = this.lifecycleDeps("dropSegment");
@@ -2195,7 +2238,10 @@ var CloudRoaring = class _CloudRoaring {
    *   reader converging, you need to signal them — this is the call to make when your own fan-out delivers.
    *
    * It also forgets any replacement this store found of a pin's object, so once it is called after a restore puts that
-   * object back, the pin reads it again.
+   * object back, the pin reads it again. A read of the segment already running on this store, a pin's and a combine's
+   * with a pinned operand included, caches nothing more of what it began reading before the call, and a pinned one
+   * opens its object again before its next chunk, failing with `NotFoundError` if the object is gone or replaced, or
+   * its row is gone or destroyed.
    *
    * Synchronous, best-effort, and safe to call for a segment this store has never read.
    *
@@ -2215,7 +2261,8 @@ var CloudRoaring = class _CloudRoaring {
    *
    * The pinned handle gets its own engine but **shares the store's chunk cache**, under keys of its own: the
    * pinned view reports the version captured at pin time, marked as a pin's, so its decoded chunks are never
-   * those of a live read that fetched across a publish (see {@link PinnedStorageChunkSource.currentVersion}).
+   * those of a live read that fetched across a publish (see {@link PinnedStorageChunkSource.currentVersion}). It
+   * shares the store engine's invalidations too, so the store's writes reach a pinned read already running.
    */
   async pinSegment(ref, leaseUntil, named) {
     const crbm = this.crbmSource;
@@ -2294,7 +2341,8 @@ var CloudRoaring = class _CloudRoaring {
    * An engine reading every segment in `pins` at its pinned generation and everything else live, with the store's
    * retries, so a transient fault on a pinned read is retried as it would be on a live one.
    *
-   * It **shares the store's chunk cache and its memory bound**, under keys of its own for each pinned segment.
+   * It **shares the store's chunk cache and its memory bound**, under keys of its own for each pinned segment, and the
+   * store engine's invalidations, so an invalidation of a pinned segment reaches a read of the pin already running.
    */
   engineWithPins(pins) {
     const crbm = this.crbmSource;
@@ -2305,12 +2353,13 @@ var CloudRoaring = class _CloudRoaring {
     }
     const pinned = new PinnedStorageChunkSource(crbm, pins);
     return new SegmentEngine({
-      storage: this.retryOptions === void 0 ? pinned : new RetryingStorageChunkSource(pinned, this.retryOptions),
+      storage: this.retryOptions === void 0 ? pinned : new RetryingStorageChunkSource2(pinned, this.retryOptions),
       cache: this.cache,
       codec: roaringCodec,
       clock: this.clock,
       metrics: this.metrics,
-      budget: this.budget
+      budget: this.budget,
+      sharesInvalidationsWith: this.engine
     });
   }
   /**
@@ -2336,7 +2385,7 @@ var CloudRoaring = class _CloudRoaring {
       if (held.has(key)) {
         const before = held.get(key);
         if (!samePin(before, at)) {
-          throw new ValidationError2(
+          throw new ValidationError4(
             `the same segment is in this combine twice, ${twoPins(before, at)}: one call reads a segment at one generation, so materialise one of them into a segment of its own first, with \`intersectInto(dest, [])\``
           );
         }
@@ -2350,7 +2399,7 @@ var CloudRoaring = class _CloudRoaring {
   /** `op` under the store's retries, as the store's own reads run; bare when the store has retries off. */
   withRetries(op) {
     const r = this.retryOptions;
-    return r === void 0 ? op() : withRetry(op, r.policy ?? DEFAULT_RETRY_POLICY, r);
+    return r === void 0 ? op() : withRetry(op, r.policy ?? DEFAULT_RETRY_POLICY2, r);
   }
   /** The store's registry, or a typed error naming the operation that needs one. */
   requireRegistry(op) {
@@ -2379,13 +2428,22 @@ var CloudRoaring = class _CloudRoaring {
    * restore of the registry from another point than the bucket leaves a count to answer. A sealed summary is held
    * against its object when this store has the key, and counted in `summariesUnchecked` when it does not.
    *
+   * With `generations: true` it also holds every generation a row's ledger of known generations names, the current one
+   * included, against its object: one footer read each (104 bytes, no key, not retried), reporting
+   * `known-generation-mismatch` with the `generation` where the object under that number is not the one the row
+   * recorded. A named generation that is not in the bucket is not reported. A row with a pointer whose ledger cannot
+   * be used is counted in `generationsUnchecked`, and none of its objects is read.
+   *
    * It holds the registry rows it enumerates resident, at most 250,000 of them, and throws
    * `BudgetExceededError` past that rather than report a partial scan as a whole one. This method takes no
    * ceiling of its own: narrow the scan with `namespace`, or call `runConsistencyCheck` over the backend's
    * `storage` and `registry` with a higher `maxScanSegments`.
    */
   async checkConsistency(options = {}) {
-    checkOptions(options, "checkConsistency", CALL_KEYS.checkConsistency, ["summaries"]);
+    checkOptions(options, "checkConsistency", CALL_KEYS.checkConsistency, [
+      "summaries",
+      "generations"
+    ]);
     options ??= {};
     const deps = this.lifecycleDeps("checkConsistency");
     return runConsistencyCheck(
@@ -2413,13 +2471,13 @@ var CloudRoaring = class _CloudRoaring {
   }
 };
 var withBatches = (gen, batches) => Object.assign(gen, { batches });
-var failing = (err) => {
-  const rejecting = () => ({ next: () => Promise.reject(err) });
-  return {
-    [Symbol.asyncIterator]: rejecting,
-    batches: () => ({ [Symbol.asyncIterator]: rejecting })
-  };
-};
+var refusing = (err) => (
+  // eslint-disable-next-line require-yield
+  async function* () {
+    throw err;
+  }
+);
+var failing = (err) => withBatches(refusing(err)(), refusing(err));
 var samePin = (a, b) => a === void 0 || b === void 0 ? a === b : a.generation === b.generation && a.fingerprint === b.fingerprint;
 var twoPins = (a, b) => {
   const one = (p) => p === void 0 ? "live" : `pinned at generation ${p.generation ?? "none"}`;
@@ -2437,9 +2495,12 @@ var readOptions = (options) => ({
 });
 var NO_SEGMENTS = [];
 function segmentList(list, what) {
-  if (!Array.isArray(list)) throw new ValidationError2(`${what} must be an array of segments`);
+  if (!Array.isArray(list)) throw new ValidationError4(`${what} must be an array of segments`);
   return list;
 }
+function operandsLabel(verb) {
+  return verb === "andNot" ? "andNot: `excludes`" : `${verb}: \`others\``;
+}
 var AS_IDS = {
   failing,
   guard: guardIds,
@@ -2454,10 +2515,8 @@ var CombineChunks = class {
   chunks;
 };
 var AS_CHUNKS = {
-  guard: guardChunks,
-  failing: (err) => ({
-    [Symbol.asyncIterator]: () => ({ next: () => Promise.reject(err) })
-  }),
+  guard: guardItems,
+  failing: (err) => refusing(err)(),
   intersect: (engine, refs, opts) => engine.intersectChunks(refs, opts),
   union: (engine, refs, opts) => engine.unionChunks(refs, opts),
   andNot: (engine, base, refs, opts) => engine.andNotChunks(base, refs, opts)
@@ -2495,6 +2554,7 @@ var Segment = class _Segment {
   lease;
   leaseHold;
   static {
+    Object.defineProperty(_Segment.prototype, SEGMENT_BRAND, { value: true });
     makeSegment = (parts) => {
       minting = true;
       try {
@@ -2515,7 +2575,7 @@ var Segment = class _Segment {
    */
   constructor(parts) {
     if (!minting) {
-      throw new ValidationError2(
+      throw new ValidationError4(
         "a Segment is not constructed directly; call `store.segment(name)`"
       );
     }
@@ -2531,7 +2591,7 @@ var Segment = class _Segment {
     if (parts.lease !== void 0) {
       this.lease = Object.freeze({ holder: parts.lease.holder, until: parts.lease.until });
     }
-    this.metricsOn = parts.metrics !== NOOP_METRICS;
+    this.metricsOn = parts.metrics !== NOOP_METRICS2;
   }
   /**
    * **Hold this segment at the generation that is current right now**, for as long as you keep the handle.
@@ -2586,11 +2646,16 @@ var Segment = class _Segment {
    * - `eraseSubject` invalidates a pin of each segment it scans that is not already destroyed.
    *
    * An invalidated pin opens its object again, and fails if that object is gone or replaced, or its row is gone or
-   * destroyed.
+   * destroyed. A read of the pin already running when the invalidation comes, a combine on this store with the pin as
+   * an operand included, looks the pin up again before it hands out its next chunk: it carries on with what it holds
+   * where the object is still there, and fails with `NotFoundError` where it is gone. It caches nothing more of what it
+   * began reading before the invalidation, so the pin's next read opens the object again too.
    * Anything else leaves the pin as it is: after a `destroySegment` beside this store, or an erasure, a drop or a
    * retirement through another store, in this process or another, the pin answers from what it holds until this
    * store's reader cache evicts the pin's reader and its chunk cache evicts the chunks the pin decoded, or
-   * {@link CloudRoaring.invalidate} is called on this store. Where the
+   * {@link CloudRoaring.invalidate} is called on this store. A combine on another store that takes the pin as an
+   * operand reads it through that store's reader and chunk cache, which only that store's own writes and its
+   * `invalidate` reach. Where the
    * object the pin reads has been deleted, by an erasure, a drop or a sweep, a chunk the pin has not cached fails at
    * once. No timed refresh bounds any of that, as none bounds anything else a pin holds.
    *
@@ -2613,7 +2678,7 @@ var Segment = class _Segment {
    * {@link UnsupportedError} on a store wired with a pre-built source that cannot pin.
    */
   async pin(options) {
-    this.assertLeases([this]);
+    this.assertLease();
     const leaseUntil = this.leaseUntilOf("pin", options);
     return this.pinned(this.ref, leaseUntil);
   }
@@ -2625,11 +2690,11 @@ var Segment = class _Segment {
   leaseUntilOf(op, options) {
     if (options === void 0 || options === null) return void 0;
     if (typeof options !== "object" || Array.isArray(options)) {
-      throw new ValidationError2(`${op}: options must be an object such as { leaseUntil }`);
+      throw new ValidationError4(`${op}: options must be an object such as { leaseUntil }`);
     }
     const unknown = Object.keys(options).filter((k) => k !== "leaseUntil");
     if (unknown.length > 0) {
-      throw new ValidationError2(
+      throw new ValidationError4(
         `${op}: unknown option${unknown.length > 1 ? "s" : ""} ${unknown.map((k) => `"${k}"`).join(", ")}; this version takes { leaseUntil } only`
       );
     }
@@ -2637,17 +2702,17 @@ var Segment = class _Segment {
     if (until === void 0) return void 0;
     const now = this.clock.now();
     if (typeof until !== "number" || !Number.isSafeInteger(until)) {
-      throw new ValidationError2(
+      throw new ValidationError4(
         `${op}: leaseUntil must be an integer epoch-MILLISECONDS; got ${String(until)}`
       );
     }
     if (until <= now) {
-      throw new ValidationError2(
+      throw new ValidationError4(
         `${op}: leaseUntil (${until}) is not after now (${now}); it is epoch MILLISECONDS, so a value in seconds reads as long past. Use \`Date.now() + hours * 3_600_000\``
       );
     }
     if (until > now + MAX_LEASE_MS) {
-      throw new ValidationError2(
+      throw new ValidationError4(
         `${op}: leaseUntil is more than 14 days away; the longest lease is ${MAX_LEASE_MS} ms. Take a new lease when a job outlasts it`
       );
     }
@@ -2703,10 +2768,12 @@ var Segment = class _Segment {
    */
   assertSegments(handles) {
     for (const h of handles) {
-      if (h instanceof _Segment || typeof h === "object" && h !== null && typeof h.leaseError === "function") {
+      if (h instanceof _Segment || typeof h === "object" && h !== null && h[SEGMENT_BRAND] === true) {
         continue;
       }
-      throw new ValidationError2("an operand must be a segment from store.segment()");
+      throw new ValidationError4(
+        "an operand must be a segment from `store.segment()` of a compatible copy of @cloudbitmaps/roaring; install one version of it"
+      );
     }
   }
   /**
@@ -2719,6 +2786,11 @@ var Segment = class _Segment {
       if (err !== void 0) throw err;
     }
   }
+  /** Throw this handle's lease error, if it has one. The calls that return a value instead of throwing use {@link leaseError}. */
+  assertLease() {
+    const err = this.leaseError();
+    if (err !== void 0) throw err;
+  }
   /**
    * Reopen a generation a pin named earlier, as a pinned handle like the one {@link Segment.pin} returns, held at
    * `at.generation` instead of the current one. Pass what the earlier pin recorded, `{ generation, fingerprint }`
@@ -2742,16 +2814,16 @@ var Segment = class _Segment {
    * is in `options`, the second.
    */
   async pinAt(at, options) {
-    this.assertLeases([this]);
+    this.assertLease();
     const { generation, fingerprint } = at ?? {};
     const unknown = typeof at === "object" && at !== null ? Object.keys(at).filter((k) => k !== "generation" && k !== "fingerprint") : [];
     if (unknown.length > 0) {
-      throw new ValidationError2(
+      throw new ValidationError4(
         `pinAt: unknown option${unknown.length > 1 ? "s" : ""} ${unknown.map((k) => `"${k}"`).join(", ")}; this version takes { generation, fingerprint } only`
       );
     }
     if (typeof generation !== "number" || !Number.isSafeInteger(generation) || generation < 0 || typeof fingerprint !== "string" || !/^\d+:\d+$/.test(fingerprint)) {
-      throw new ValidationError2(
+      throw new ValidationError4(
         "pinAt: pass { generation, fingerprint } as recorded by an earlier pin (its pinnedAt); a generation number without the fingerprint of its object does not identify it"
       );
     }
@@ -2785,8 +2857,9 @@ var Segment = class _Segment {
     return handles.some((h) => h.leaseHold !== void 0) ? out.guard(result, () => this.assertLeases(handles)) : result;
   }
   /**
-   * Time an op with the injected clock and emit an `op` metric on completion (success or throw). Skipped
-   * entirely when no sink is wired, so the default path pays nothing.
+   * Time an op with the injected clock and emit an `op` metric on completion (success or throw). With no sink wired it
+   * reads no clock and emits nothing, but a call still passes through this async frame; `has()` and `count()` return the
+   * engine's promise directly instead.
    */
   async timed(name, fn) {
     if (!this.metricsOn) return fn();
@@ -2797,10 +2870,15 @@ var Segment = class _Segment {
       this.metrics.onEvent({ kind: "op", name, ms: Math.max(0, this.clock.now() - startedAt) });
     }
   }
-  /** Membership: one chunk — the cache, else one ranged GET. Throws {@link ValidationError} on a bad id. */
+  /**
+   * Membership: one chunk. A cold resolution of the segment is one registry read and a warm one none; then a cached
+   * chunk answers with no request, and an uncached one is one range read, after a tail read when no reader of the
+   * generation is open, unless that tail carried the chunk. Throws {@link ValidationError} on a bad id.
+   */
   has(id) {
     const lease = this.leaseError();
     if (lease !== void 0) return Promise.reject(lease);
+    if (!this.metricsOn) return this.engine.has(this.ref, id);
     return this.timed("has", () => this.engine.has(this.ref, id));
   }
   /**
@@ -2824,6 +2902,7 @@ var Segment = class _Segment {
   count() {
     const lease = this.leaseError();
     if (lease !== void 0) return Promise.reject(lease);
+    if (!this.metricsOn) return this.engine.count(this.ref);
     return this.timed("count", () => this.engine.count(this.ref));
   }
   /**
@@ -2854,7 +2933,7 @@ var Segment = class _Segment {
    * ```
    */
   async stat() {
-    this.assertLeases([this]);
+    this.assertLease();
     return this.engine.stat(this.ref);
   }
   /**
@@ -2884,7 +2963,7 @@ var Segment = class _Segment {
       engine.iterate(ref, bounds),
       () => engine.iterateBatches(ref, bounds)
     );
-    return this.leaseHold === void 0 ? stream : guardIds(stream, () => this.assertLeases([this]));
+    return this.leaseHold === void 0 ? stream : guardIds(stream, () => this.assertLease());
   }
   /**
    * **Pinned handles only.** The ids at 1-based ranks `n`, `2n`, `3n` …, counted over the ids in `(after, through]`
@@ -2918,22 +2997,22 @@ var Segment = class _Segment {
    */
   everyNth(n, options) {
     const lease = this.leaseError();
-    if (lease !== void 0) return failing(lease);
+    if (lease !== void 0) return refusing(lease)();
     const bad = optionsError(options, "everyNth", CALL_KEYS.range);
-    if (bad !== void 0) return failing(bad);
+    if (bad !== void 0) return refusing(bad)();
     if (this.pinnedAt === void 0) {
-      return failing(
+      return refusing(
         new UnsupportedError(
           "everyNth needs a pinned handle: a live handle can place a rank by one generation and read it from another. Call `pin()` first."
         )
-      );
+      )();
     }
     const stream = this.engine.everyNth(
       this.ref,
       n,
       options == null ? void 0 : rangeOf(options)
     );
-    return this.leaseHold === void 0 ? stream : guardIdIterable(stream, () => this.assertLeases([this]));
+    return this.leaseHold === void 0 ? stream : guardIdIterable(stream, () => this.assertLease());
   }
   /**
    * The options a combine hands the engine, read once, when it is called ({@link readOptions}), with the `exclude`
@@ -2973,28 +3052,7 @@ var Segment = class _Segment {
   intersect(others, options) {
     const bad = optionsError(options, "intersect", CALL_KEYS.combine, ["allowAbsentOperands"]);
     if (bad !== void 0) return failing(bad);
-    return this.intersectAs(AS_IDS, others, options ?? void 0);
-  }
-  intersectAs(out, others, options) {
-    let exclude;
-    let handles;
-    try {
-      exclude = this.excludesOf(options);
-      handles = [this, ...segmentList(others, "intersect: `others`"), ...exclude];
-      this.assertSegments(handles);
-      this.assertLeases(handles);
-    } catch (err) {
-      return out.failing(err);
-    }
-    let engine;
-    try {
-      engine = this.combineEngine([this, ...others, ...exclude]) ?? this.engine;
-    } catch (err) {
-      return out.failing(err);
-    }
-    const refs = [this.ref, ...others.map((o) => o.ref)];
-    const opts = this.refsIn(options, exclude);
-    return this.guarded(out, handles, out.intersect(engine, refs, opts));
+    return this.combineAs(AS_IDS, "intersect", others, options ?? void 0);
   }
   /**
    * Materialize `this ∩ others…` (minus `exclude`) as a **new generation of `dest`** — `dest`'s previous contents
@@ -3018,21 +3076,7 @@ var Segment = class _Segment {
    */
   async intersectInto(dest, others, options) {
     checkOptions(options, "intersectInto", CALL_KEYS.into, ["allowEmpty", "allowAbsentOperands"]);
-    const operands = [
-      ...segmentList(others, "intersectInto: `others`"),
-      ...this.excludesOf(options)
-    ];
-    this.assertIntoHandles(dest, operands);
-    this.combineEngine([this, ...operands]);
-    return this.timed(
-      "intersectInto",
-      () => this.materialize(
-        dest.ref,
-        new CombineChunks(this.intersectAs(AS_CHUNKS, others, options)),
-        "intersectInto",
-        options
-      )
-    );
+    return this.combineInto("intersectInto", dest, others, options);
   }
   /**
    * `this ∪ others…`, minus `options.exclude` — streamed ascending.
@@ -3047,44 +3091,12 @@ var Segment = class _Segment {
   union(others, options) {
     const bad = optionsError(options, "union", CALL_KEYS.combine, ["allowAbsentOperands"]);
     if (bad !== void 0) return failing(bad);
-    return this.unionAs(AS_IDS, others, options ?? void 0);
-  }
-  unionAs(out, others, options) {
-    let exclude;
-    let handles;
-    try {
-      exclude = this.excludesOf(options);
-      handles = [this, ...segmentList(others, "union: `others`"), ...exclude];
-      this.assertSegments(handles);
-      this.assertLeases(handles);
-    } catch (err) {
-      return out.failing(err);
-    }
-    let engine;
-    try {
-      engine = this.combineEngine([this, ...others, ...exclude]) ?? this.engine;
-    } catch (err) {
-      return out.failing(err);
-    }
-    const refs = [this.ref, ...others.map((o) => o.ref)];
-    const opts = this.refsIn(options, exclude);
-    return this.guarded(out, handles, out.union(engine, refs, opts));
+    return this.combineAs(AS_IDS, "union", others, options ?? void 0);
   }
   /** Materialize `this ∪ others…` (minus `exclude`) as a **new generation of `dest`** — see {@link intersectInto}. */
   async unionInto(dest, others, options) {
     checkOptions(options, "unionInto", CALL_KEYS.into, ["allowEmpty", "allowAbsentOperands"]);
-    const operands = [...segmentList(others, "unionInto: `others`"), ...this.excludesOf(options)];
-    this.assertIntoHandles(dest, operands);
-    this.combineEngine([this, ...operands]);
-    return this.timed(
-      "unionInto",
-      () => this.materialize(
-        dest.ref,
-        new CombineChunks(this.unionAs(AS_CHUNKS, others, options)),
-        "unionInto",
-        options
-      )
-    );
+    return this.combineInto("unionInto", dest, others, options);
   }
   /**
    * `this \ (excludes…)` — streamed ascending. Suppression on its own.
@@ -3100,12 +3112,26 @@ var Segment = class _Segment {
   andNot(excludes, options) {
     const bad = optionsError(options, "andNot", CALL_KEYS.andNot, ["allowAbsentOperands"]);
     if (bad !== void 0) return failing(bad);
-    return this.andNotAs(AS_IDS, excludes, options ?? void 0);
+    return this.combineAs(AS_IDS, "andNot", excludes, options ?? void 0);
   }
-  andNotAs(out, excludes, options) {
+  /** Materialize `this \ (excludes…)` as a **new generation of `dest`** — see {@link intersectInto}. */
+  async andNotInto(dest, excludes, options) {
+    checkOptions(options, "andNotInto", CALL_KEYS.andNotInto, [
+      "allowEmpty",
+      "allowAbsentOperands"
+    ]);
+    return this.combineInto("andNotInto", dest, excludes, options);
+  }
+  /**
+   * The one body of the three combines, read as ids or as chunks. `operands` is `others` for `intersect` and
+   * `union`, and `excludes` for `andNot`, which takes no `exclude` option.
+   */
+  combineAs(out, verb, operands, options) {
+    let exclude;
     let handles;
     try {
-      handles = [this, ...segmentList(excludes, "andNot: `excludes`")];
+      exclude = verb === "andNot" ? NO_SEGMENTS : this.excludesOf(options);
+      handles = [this, ...segmentList(operands, operandsLabel(verb)), ...exclude];
       this.assertSegments(handles);
       this.assertLeases(handles);
     } catch (err) {
@@ -3113,29 +3139,35 @@ var Segment = class _Segment {
     }
     let engine;
     try {
-      engine = this.combineEngine([this, ...excludes]) ?? this.engine;
+      engine = this.combineEngine([this, ...operands, ...exclude]) ?? this.engine;
     } catch (err) {
       return out.failing(err);
     }
-    const base = this.ref;
-    const refs = excludes.map((o) => o.ref);
-    const opts = options == null ? void 0 : readOptions(options);
-    return this.guarded(out, handles, out.andNot(engine, base, refs, opts));
+    if (verb === "andNot") {
+      const refs2 = operands.map((o) => o.ref);
+      const opts2 = options == null ? void 0 : readOptions(options);
+      return this.guarded(out, handles, out.andNot(engine, this.ref, refs2, opts2));
+    }
+    const refs = [this.ref, ...operands.map((o) => o.ref)];
+    const opts = this.refsIn(options, exclude);
+    return this.guarded(
+      out,
+      handles,
+      verb === "union" ? out.union(engine, refs, opts) : out.intersect(engine, refs, opts)
+    );
   }
-  /** Materialize `this \ (excludes…)` as a **new generation of `dest`** — see {@link intersectInto}. */
-  async andNotInto(dest, excludes, options) {
-    checkOptions(options, "andNotInto", CALL_KEYS.andNotInto, [
-      "allowEmpty",
-      "allowAbsentOperands"
-    ]);
-    this.assertIntoHandles(dest, segmentList(excludes, "andNotInto: `excludes`"));
-    this.combineEngine([this, ...excludes]);
+  /** The one body of the three `*Into` verbs, after each has checked its own options. */
+  combineInto(name, dest, operands, options) {
+    const verb = name.slice(0, -"Into".length);
+    const all = verb === "andNot" ? segmentList(operands, `${name}: \`excludes\``) : [...segmentList(operands, `${name}: \`others\``), ...this.excludesOf(options)];
+    this.assertIntoHandles(dest, all);
+    this.combineEngine([this, ...all]);
     return this.timed(
-      "andNotInto",
+      name,
       () => this.materialize(
         dest.ref,
-        new CombineChunks(this.andNotAs(AS_CHUNKS, excludes, options)),
-        "andNotInto",
+        new CombineChunks(this.combineAs(AS_CHUNKS, verb, operands, options)),
+        name,
         options
       )
     );
@@ -3146,15 +3178,15 @@ var Segment = class _Segment {
 function parseConfig(env) {
   const root = env.CR_EXPORT_ROOT;
   if (root === void 0 || root === "") {
-    throw new Error("CR_EXPORT_ROOT is required (the local-filesystem storage root)");
+    throw new ValidationError5("CR_EXPORT_ROOT is required (the local-filesystem storage root)");
   }
   const out = env.CR_EXPORT_OUT;
   if (out === void 0 || out === "") {
-    throw new Error("CR_EXPORT_OUT is required (the output directory for the dump)");
+    throw new ValidationError5("CR_EXPORT_OUT is required (the output directory for the dump)");
   }
   const format = env.CR_EXPORT_FORMAT || "roaring";
   if (format !== "roaring" && format !== "ndjson") {
-    throw new Error(`CR_EXPORT_FORMAT must be "roaring" or "ndjson"; got ${format}`);
+    throw new ValidationError5(`CR_EXPORT_FORMAT must be "roaring" or "ndjson"; got ${format}`);
   }
   const namespace = env.CR_EXPORT_NAMESPACE || void 0;
   return { root, out, format, namespace };
@@ -3169,7 +3201,7 @@ async function ensureOwnDirectory(out, dir) {
   }
   const found = await lstat(dir);
   const refuse = (why) => {
-    throw new ValidationError3(`the export directory is not one this tool made: ${why}`);
+    throw new ValidationError5(`the export directory is not one this tool made: ${why}`);
   };
   if (found.isSymbolicLink()) refuse("a namespace directory is a symbolic link");
   if (!found.isDirectory()) refuse("a namespace path is not a directory");
@@ -3178,10 +3210,17 @@ async function ensureOwnDirectory(out, dir) {
     if ((found.mode & 63) !== 0) refuse("a namespace directory is open to group or others");
   }
 }
+var MANIFEST_NAME = "manifest.json";
 function fsSink(out) {
   return {
     async open(ref, ext) {
-      const dir = join(out, namespacePathPart(ref.namespace));
+      const part = namespacePathPart(ref.namespace);
+      if (part.toLowerCase() === MANIFEST_NAME) {
+        throw new ValidationError5(
+          `a namespace named ${MANIFEST_NAME} (in any letter case) cannot be exported to a directory: its folder would be the manifest's path`
+        );
+      }
+      const dir = join(out, part);
       await ensureOwnDirectory(out, dir);
       const finalPath = join(dir, `${encodeNameForPath(ref.segment)}${ext}`);
       const tmpPath = `${finalPath}.${randomUUID()}.part`;
@@ -3208,6 +3247,10 @@ function fsSink(out) {
           await handle.close().catch(() => {
           });
           await rm(tmpPath, { force: true });
+          await rmdir(dir).catch((err) => {
+            if (err.code !== "ENOTEMPTY" && err.code !== "EEXIST" && err.code !== "ENOENT")
+              throw err;
+          });
         }
       };
     }
@@ -3218,10 +3261,10 @@ async function requireStoreRoot(root) {
   try {
     entries = await readdir(root);
   } catch {
-    throw new ValidationError3("CR_EXPORT_ROOT does not name a directory that can be read");
+    throw new ValidationError5("CR_EXPORT_ROOT does not name a directory that can be read");
   }
   if (entries.length === 0) {
-    throw new ValidationError3(
+    throw new ValidationError5(
       "CR_EXPORT_ROOT is empty: it holds no store (an unmounted volume, or the wrong directory)"
     );
   }
@@ -3235,7 +3278,13 @@ async function main(env = process.env, now = () => Date.now()) {
   await requireStoreRoot(config.root);
   const storage = new LocalFsStorage(config.root);
   const store = new CloudRoaring({ storage });
-  await rm(join(config.out, "manifest.json"), { force: true });
+  const priorManifest = await lstat(join(config.out, MANIFEST_NAME)).catch(() => null);
+  if (priorManifest?.isDirectory() === true) {
+    throw new ValidationError5(
+      `${join(config.out, MANIFEST_NAME)} is a directory, so the manifest cannot be written there: remove or rename it, or export to a fresh directory`
+    );
+  }
+  await rm(join(config.out, MANIFEST_NAME), { force: true });
   const manifest = await store.exportSegments(fsSink(config.out), {
     format: config.format,
     namespace: config.namespace