@cloudbitmaps/roaring 0.21.0 → 0.23.0

package/dist/bin/export-segments.js

@@ -21,17 +21,20 @@ import {
   RetryingStorageChunkSource as RetryingStorageChunkSource2,
   SegmentEngine,
   LEASE_SKEW_MS,
+  BudgetExceededError,
   LeaseExpiredError,
   MAX_LEASE_MS,
   NotFoundError,
-  UnsupportedError,
-  ValidationError as ValidationError4,
+  UnsupportedError as UnsupportedError2,
+  ValidationError as ValidationError5,
+  errorKind,
   WriteConflictError,
   checkBudget,
   collectWithinBudget,
   excludingReservedRows,
   dropSegment,
   eraseIdFromSegment,
+  findIdUnderTombstone,
   judgeLoad,
   loadSegment,
   loadSegmentChunks,
@@ -52,7 +55,12 @@ import {
   splitId,
   takeLease
 } from "@cloudbitmaps/core";
-import { pointerIdOf, requirePositiveInt, validateSegmentRef } from "@cloudbitmaps/core/driver-kit";
+import {
+  pointerIdOf,
+  requireBool,
+  requirePositiveInt,
+  validateSegmentRef
+} from "@cloudbitmaps/core/driver-kit";
 
 // src/open-charging-storage.ts
 var OpenChargingStorage = class {
@@ -68,6 +76,7 @@ var OpenChargingStorage = class {
   }
   inner;
   charge;
+  /** Generations an open of costs nothing more: the scan's current one, this call's writes, and each one charged. */
   free = /* @__PURE__ */ new Set();
   capabilities() {
     return this.inner.capabilities();
@@ -80,9 +89,15 @@ var OpenChargingStorage = class {
   getRange(key, offset, length) {
     return this.inner.getRange(key, offset, length);
   }
-  /** One `getTail` is one open: a reader takes the footer and the index from it, and reads chunks with `getRange`. */
+  /**
+   * One `getTail` is one open: a reader takes the footer and the index from it, and reads chunks with `getRange`. A
+   * generation is charged at its first open only.
+   */
   async getTail(key, maxBytes) {
-    if (!this.free.has(key.generation)) this.charge();
+    if (!this.free.has(key.generation)) {
+      this.charge();
+      this.free.add(key.generation);
+    }
     return this.inner.getTail(key, maxBytes);
   }
   /** Handed through whole: the erasure's delete of a holder is conditioned on the object it searched. */
@@ -96,7 +111,12 @@ var OpenChargingStorage = class {
 
 // src/index.ts
 import { listGenerations, rollbackSegment } from "@cloudbitmaps/core";
-import { listSegments, segmentExists } from "@cloudbitmaps/core";
+import {
+  destroySegment as coreDestroySegment,
+  eraseNamespace as coreEraseNamespace
+} from "@cloudbitmaps/core";
+import { listSegments, refuseUnknownRefKeys, segmentExists } from "@cloudbitmaps/core";
+import { runPreflight } from "@cloudbitmaps/core";
 
 // src/reserved-namespace.ts
 import { ValidationError } from "@cloudbitmaps/core";
@@ -111,7 +131,7 @@ function refuseReservedNamespace(namespace) {
 
 // src/roaring-codec.ts
 import roaring from "roaring";
-import { IntegrityError as IntegrityError2, decodeSerialized } from "@cloudbitmaps/core";
+import { IntegrityError as IntegrityError2, ValidationError as ValidationError2, decodeSerialized } from "@cloudbitmaps/core";
 
 // src/portable/layout.ts
 import { IntegrityError } from "@cloudbitmaps/core";
@@ -359,10 +379,6 @@ var SafeBitmap = class _SafeBitmap {
       throw new IntegrityError2(`failed to deserialize bitmap: ${err.message}`);
     }
   }
-  /** The `roaring` bitmap this wraps, for a caller that was handed it once and keeps no wrapper. */
-  unwrap() {
-    return this.bitmap;
-  }
   serialize() {
     return this.bitmap.serialize(SerializationFormat.portable);
   }
@@ -467,7 +483,7 @@ var SafeBitmap = class _SafeBitmap {
   }
 };
 function bitmapAsLoadInput(input) {
-  return input instanceof RoaringBitmap32 ? { bitmap: input } : input;
+  return input instanceof RoaringBitmap32 || input instanceof ReadonlyRoaringView ? { bitmap: input } : input;
 }
 var roaringCodec = {
   empty: () => SafeBitmap.empty(),
@@ -475,6 +491,31 @@ var roaringCodec = {
   safeDeserialize: (bytes, maxBytes, options) => SafeBitmap.safeDeserialize(bytes, maxBytes, options),
   owns: (bitmap) => bitmap instanceof SafeBitmap
 };
+var ReadonlyRoaringView = class {
+  #bitmap;
+  constructor(bitmap) {
+    this.#bitmap = bitmap;
+  }
+  get size() {
+    return this.#bitmap.size;
+  }
+  has(id) {
+    return this.#bitmap.has(id);
+  }
+  [Symbol.iterator]() {
+    return this.#bitmap[Symbol.iterator]();
+  }
+  /** The portable bytes, for exactly the argument `'portable'`; any other call is a `ValidationError`. */
+  serialize(...args) {
+    if (args.length !== 1 || args[0] !== "portable") {
+      const got = args.length === 0 ? "no argument" : args.map((a) => typeof a === "string" ? `'${a}'` : typeof a).join(", ");
+      throw new ValidationError2(
+        `a decoded bitmap serializes only as serialize('portable'); got ${got}`
+      );
+    }
+    return this.#bitmap.serialize();
+  }
+};
 
 // src/system-clock.ts
 var SystemClock = class {
@@ -517,6 +558,18 @@ var SystemClock = class {
   }
 };
 
+// src/system-entropy.ts
+import { UnsupportedError } from "@cloudbitmaps/core";
+var systemEntropy = (length) => {
+  const c = globalThis.crypto;
+  if (c === void 0 || typeof c.getRandomValues !== "function") {
+    throw new UnsupportedError(
+      "this runtime has no Web Crypto (crypto.getRandomValues), which every load needs for its generation's write identity: run on a runtime that has it, or pass `seams.entropy`"
+    );
+  }
+  return c.getRandomValues(new Uint8Array(length));
+};
+
 // src/option-keys.ts
 var OPTION_KEYS = {
   top: ["storage", "cache", "encryption", "retry", "metrics", "budget", "seams"],
@@ -524,7 +577,7 @@ var OPTION_KEYS = {
   encryption: ["keystore", "required"],
   retry: ["maxAttempts", "baseDelayMs", "maxDelayMs", "backoffFactor", "jitter", "onRetry"],
   budget: ["maxRequests"],
-  seams: ["clock", "rng"]
+  seams: ["clock", "rng", "entropy"]
 };
 
 // src/lease-guards.ts
@@ -602,17 +655,18 @@ import {
   DEFAULT_RETRY_POLICY,
   NOOP_METRICS,
   RetryingStorageChunkSource,
-  ValidationError as ValidationError2,
+  ValidationError as ValidationError3,
   isStorageBackend
 } from "@cloudbitmaps/core";
 function resolveRetryPolicy(partial) {
-  const baseDelayMs = partial.baseDelayMs ?? DEFAULT_RETRY_POLICY.baseDelayMs;
+  const orDefault = (field) => partial[field] === void 0 ? DEFAULT_RETRY_POLICY[field] : partial[field];
+  const baseDelayMs = orDefault("baseDelayMs");
   return {
-    maxAttempts: partial.maxAttempts ?? DEFAULT_RETRY_POLICY.maxAttempts,
+    maxAttempts: orDefault("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
+    maxDelayMs: partial.maxDelayMs === void 0 ? typeof baseDelayMs === "number" && baseDelayMs > DEFAULT_RETRY_POLICY.maxDelayMs ? baseDelayMs : DEFAULT_RETRY_POLICY.maxDelayMs : partial.maxDelayMs,
+    backoffFactor: orDefault("backoffFactor"),
+    jitter: orDefault("jitter")
   };
 }
 function wireStore(options, clock, rng, metrics) {
@@ -625,7 +679,7 @@ function wireStore(options, clock, rng, metrics) {
   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");
+      throw new ValidationError3("retry.onRetry must be a function");
     }
     retryOptions = {
       clock,
@@ -649,13 +703,14 @@ function wireStore(options, clock, rng, metrics) {
     source: resolved.source,
     driver: resolved.driver,
     registry: resolved.registry,
+    backend: isStorageBackend(options.storage) ? options.storage : void 0,
     retryOptions
   };
 }
 function resolveStorageSource(options, clock) {
   const storage = options.storage;
   if (storage === null || typeof storage !== "object") {
-    throw new ValidationError2(
+    throw new ValidationError3(
       "`storage` must be a StorageBackend, an IStorageDriver, or a StorageChunkSource"
     );
   }
@@ -665,14 +720,14 @@ function resolveStorageSource(options, clock) {
   const hasPutImmutable = typeof storage.putImmutable === "function";
   const isBackend = isStorageBackend(storage);
   if (isBackend && (hasGetChunk || hasPutImmutable)) {
-    throw new ValidationError2(
+    throw new ValidationError3(
       `\`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(
+    throw new ValidationError3(
       "`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`."
     );
   }
@@ -681,11 +736,11 @@ function resolveStorageSource(options, clock) {
     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(
+      throw new ValidationError3(
         "`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(
+    throw new ValidationError3(
       "`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."
     );
   }
@@ -706,19 +761,19 @@ function resolveStorageSource(options, clock) {
     };
   }
   if (hasGetChunk && hasPutImmutable) {
-    throw new ValidationError2(
+    throw new ValidationError3(
       "`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(
+    throw new ValidationError3(
       "`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"
+      throw new ValidationError3(
+        "keystore/requireEncryption apply only when the store builds its own read path: a StorageChunkSource of your own reads an encrypted segment by itself, if it must; to have the store decrypt, pass a backend"
       );
     }
     return { source: storage, driver: void 0, registry: void 0 };
@@ -739,31 +794,32 @@ function resolveStorageSource(options, clock) {
 }
 
 // src/options.ts
-import { ValidationError as ValidationError3 } from "@cloudbitmaps/core";
+import { ValidationError as ValidationError4 } 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 = []) {
+function optionsError(options, op, known, booleans = [], misplaced = []) {
   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)}`);
+    return new ValidationError4(`${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);
+  for (const k of misplaced) if (!unknown.includes(k) && bag[k] !== void 0) unknown.push(k);
   if (unknown.length > 0) {
-    return new ValidationError3(
+    return new ValidationError4(
       `${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(
+    return new ValidationError4(
       `${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 new ValidationError4(`${op}: \`${name}\` must be a boolean; got ${kindOf(v)}`);
     }
   }
   return void 0;
@@ -777,58 +833,32 @@ function picked(options, keys) {
   }
   return out;
 }
-function checkOptions(options, op, known, booleans) {
-  const err = optionsError(options, op, known, booleans);
+function checkOptions(options, op, known, booleans, misplaced) {
+  const err = optionsError(options, op, known, booleans, misplaced);
   if (err !== void 0) throw err;
 }
 
 // src/index.ts
+import { MemoryStorage, LocalFsStorage, InProcessKeystore } from "@cloudbitmaps/core/node";
 import {
-  MemoryStorage,
-  LocalFsStorage,
-  CrbmStorageChunkSource as CrbmStorageChunkSource3,
-  destroySegment,
-  eraseNamespace,
   excludingReservedRows as excludingReservedRows2,
   readRetentionPolicy,
-  MIN_EXPIRES_AT_MS,
-  LEASE_SKEW_MS as LEASE_SKEW_MS2,
-  MAX_LEASE_MS as MAX_LEASE_MS2,
-  MAX_LEASES_PER_SEGMENT,
-  InProcessKeystore,
-  NodeAead,
-  aadFor,
   CloudRoaringError,
-  ValidationError as ValidationError5,
+  ValidationError as ValidationError6,
   WriteConflictError as WriteConflictError2,
   IntegrityError as IntegrityError3,
   NotFoundError as NotFoundError2,
-  UnsupportedError as UnsupportedError2,
+  UnsupportedError as UnsupportedError3,
   CapabilityError,
   TransientError,
   KeyUnavailableError,
-  BudgetExceededError,
+  BudgetExceededError as BudgetExceededError2,
   LeaseExpiredError as LeaseExpiredError2,
   LeaseLimitError,
   StaleOperandError,
-  isCloudRoaringError,
-  isWriteConflictError,
-  isTransientError,
-  isNotFoundError,
-  isIntegrityError,
-  isValidationError,
-  isLeaseExpiredError,
-  isLeaseLimitError,
-  isStaleOperandError,
-  isUnsupportedError,
-  isCapabilityError,
-  isBudgetExceededError,
-  isKeyUnavailableError,
-  CrbmReader,
-  BufferReader,
+  errorKind as errorKind2,
   CountingMetricsSink,
-  RecordingAuditSink,
-  DEFAULT_RETRY_POLICY as DEFAULT_RETRY_POLICY3
+  RecordingAuditSink
 } from "@cloudbitmaps/core";
 var SystemRng = class {
   /** A float in `[0, 1)`. Jitter only — never key material, never anything a caller can observe. */
@@ -836,6 +866,16 @@ var SystemRng = class {
     return Math.random();
   }
 };
+function validateRef(ref, verb) {
+  if (typeof ref !== "object" || ref === null) {
+    throw new ValidationError5(
+      "a segment ref is an object such as { segment: 'name' }; store.segment() takes the bare name"
+    );
+  }
+  refuseUnknownRefKeys(ref, verb);
+  validateSegmentRef(ref);
+  return { segment: ref.segment, namespace: ref.namespace };
+}
 var DEFAULT_CACHE_MAX_CHUNKS = 1024;
 var DEFAULT_ADMIN_CONCURRENCY = 8;
 function rowVersionOfLive(version) {
@@ -849,15 +889,20 @@ function validateConcurrency(concurrency) {
 function requireScope(options, op) {
   if (options.namespace !== void 0) {
     if (typeof options.namespace !== "string") {
-      throw new ValidationError4(
+      throw new ValidationError5(
         `${op}: namespace must be a string; got ${kindOf(options.namespace)}`
       );
     }
     validateSegmentRef({ segment: "x", namespace: options.namespace });
   }
   refuseReservedNamespace(options.namespace);
+  if (options.namespace !== void 0 && options.allNamespaces === true) {
+    throw new ValidationError5(
+      `${op}: pass a namespace or { allNamespaces: true }, not both: with both, it is unclear whether to scan one namespace or every one`
+    );
+  }
   if (options.namespace === void 0 && options.allNamespaces !== true) {
-    throw new ValidationError4(
+    throw new ValidationError5(
       `${op} scans the global id space across all namespaces \u2014 pass an explicit \`namespace\`, or \`{ allNamespaces: true }\` to intentionally sweep the whole fleet`
     );
   }
@@ -904,7 +949,7 @@ var CALL_KEYS = {
     "metadata",
     "keep"
   ]),
-  load: keysOf()(["allowEmpty", "guard", "keep", "metadata", "audit"]),
+  load: keysOf()(["allowEmpty", "guard", "keep", "metadata", "audit", "sorted"]),
   segments: keysOf()(["namespace"]),
   subjectReport: keysOf()([
     "namespace",
@@ -945,13 +990,37 @@ var CALL_KEYS = {
   checkConsistency: keysOf()([
     "namespace",
     "concurrency",
+    "maxScanSegments",
     "summaries",
     "generations"
   ]),
-  exportSegments: keysOf()(["format", "codec", "namespace", "ndjsonBatchBytes"])
+  exportSegments: keysOf()(["format", "namespace", "ndjsonBatchBytes"])
+};
+var outside = (wider, known) => wider.filter((k) => !known.includes(k));
+var MISPLACED = {
+  range: outside(CALL_KEYS.into, CALL_KEYS.range),
+  andNot: outside(CALL_KEYS.into, CALL_KEYS.andNot),
+  combine: outside(CALL_KEYS.into, CALL_KEYS.combine),
+  andNotInto: outside(CALL_KEYS.into, CALL_KEYS.andNotInto),
+  exportSegments: ["codec"]
 };
 var SEGMENT_BRAND = /* @__PURE__ */ Symbol.for("cloudbitmaps.roaring.segment/1");
 var viewOf;
+var originOf;
+function assertOneStore(verb, role, h, origin) {
+  if (h instanceof Segment) {
+    if (originOf(h) === origin) return;
+    throw new ValidationError5(
+      `${verb}: ${role} belongs to another store; combine segments of one store: open each with this store's segment()`
+    );
+  }
+  if (typeof h === "object" && h !== null && h[SEGMENT_BRAND] === true) {
+    throw new ValidationError5(
+      `${verb}: ${role} comes from another installed copy of @cloudbitmaps/roaring, so it belongs to another store; install one copy and combine segments of one store`
+    );
+  }
+  throw new ValidationError5(`${verb}: ${role} must be a segment from this store's segment()`);
+}
 var MATERIALIZE_MANY_KEYS = [
   "operands",
   "dryRun",
@@ -968,6 +1037,17 @@ var MATERIALIZE_MANY_KEYS = [
   "feed",
   "mayBeEmpty"
 ];
+var MATERIALIZE_MANY_MISPLACED = outside(CALL_KEYS.into, MATERIALIZE_MANY_KEYS);
+function unknownManyKeys(options) {
+  const unknown = Object.keys(options).filter(
+    (k) => !MATERIALIZE_MANY_KEYS.includes(k)
+  );
+  const bag = options;
+  for (const k of MATERIALIZE_MANY_MISPLACED) {
+    if (!unknown.includes(k) && bag[k] !== void 0) unknown.push(k);
+  }
+  return unknown;
+}
 var MATERIALIZE_MANY_OUTPUT_KEYS = [
   "dest",
   "expr",
@@ -993,18 +1073,23 @@ var NOT_A_GROUP = {
 };
 var CloudRoaring = class _CloudRoaring {
   engine;
+  /** This store's identity: every handle it makes carries this object, and a combine compares it by reference. */
+  origin = Object.freeze({});
   cache;
   /** The store's retry options, for a pinned engine to read through as the store's own does; undefined when off. */
   retryOptions;
   crbmSource;
   clock;
   rng;
+  entropy;
   metrics;
   // The store's own drivers, kept so the lifecycle helpers and the `*Into` verbs reuse them instead of making
   // you re-pass deps. `storageDriver` is set only when `storage` was a raw IStorageDriver (a pre-built StorageChunkSource has
   // no underlying driver to write through).
   storageDriver;
   registry;
+  // The backend itself, for its optional `checkLifecycle`; `undefined` for a bare driver or a source.
+  backend;
   keystore;
   requireEncryption;
   /** Resolved store-level per-op budget (null = disabled); the admin scans use it, with a per-op override. */
@@ -1024,7 +1109,7 @@ var CloudRoaring = class _CloudRoaring {
    */
   static rejectUnknownOptions(options) {
     if (options === null || options === void 0 || typeof options !== "object") {
-      throw new ValidationError4(
+      throw new ValidationError5(
         "CloudRoaring needs an options object with a `storage` key \u2014 got " + (options === null ? "null" : typeof options)
       );
     }
@@ -1042,7 +1127,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 ValidationError4(
+        throw new ValidationError5(
           `CloudRoaring's \`${group}\` must be an object${offOk ? " or `false`" : ""} \u2014 got ${got}`
         );
       }
@@ -1052,7 +1137,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 ValidationError4(
+    throw new ValidationError5(
       `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"
@@ -1068,21 +1153,56 @@ var CloudRoaring = class _CloudRoaring {
       [options.seams?.rng, "seams.rng", ["next"]],
       [options.encryption?.keystore, "encryption.keystore", ["createDek", "openDek"]]
     ];
+    const entropy = options.seams?.entropy;
+    if (entropy !== void 0 && typeof entropy !== "function") {
+      throw new ValidationError5(
+        "CloudRoaring's `seams.entropy` must be a function `(length) => Uint8Array` returning that many random bytes"
+      );
+    }
     for (const [seam, name, needs] of seams) {
-      if (seam === void 0 || seam === null) continue;
-      const has = (m) => typeof seam[m] === "function";
-      if (typeof seam !== "object" || !needs.every(has)) {
-        throw new ValidationError4(
+      if (seam === void 0) continue;
+      const has = (m) => seam !== null && typeof seam[m] === "function";
+      if (seam === null || typeof seam !== "object" || !needs.every(has)) {
+        throw new ValidationError5(
           `CloudRoaring's \`${name}\` must be an object with ${needs.map((m) => `\`${m}()\``).join(" and ")}`
         );
       }
     }
   }
+  /**
+   * Refuse a `cache` or `encryption` value that can never be honoured, by the name the caller wrote. The sizes reach
+   * the caches under their own internal names, so left to them an error would name `maxEntries` or `maxBytes`; and
+   * `encryption.required` must be exactly a boolean, since the read path took a truthy string for `true` while every
+   * write path did not, which refused cleartext reads and still wrote cleartext.
+   */
+  static rejectBadValues(options) {
+    const cache = options.cache;
+    if (cache !== void 0) {
+      requirePositiveInt("cache.maxChunks", cache.maxChunks);
+      requirePositiveInt("cache.readerMax", cache.readerMax);
+      requirePositiveInt("cache.readerMaxBytes", cache.readerMaxBytes);
+      const ttl = cache.ttlMs;
+      if (ttl !== void 0 && (typeof ttl !== "number" || !Number.isFinite(ttl) || ttl <= 0)) {
+        throw new ValidationError5(
+          `cache.ttlMs must be a finite number above 0 (milliseconds); got ${typeof ttl === "string" ? JSON.stringify(ttl) : String(ttl)}`
+        );
+      }
+    }
+    requireBool("CloudRoaring's `encryption.required`", options.encryption?.required);
+  }
+  /**
+   * Builds a store. Only `storage` is required: pass a backend such as `S3Storage` or `MemoryStorage`. `cache`,
+   * `encryption`, `retry`, `metrics`, `budget` and `seams` tune it. An option it does not take, a `cache` size or `ttlMs`
+   * that is not a usable number, an `encryption.required` that is not a boolean, or a seam missing a method the store
+   * calls, throws `ValidationError`.
+   */
   constructor(options) {
     _CloudRoaring.rejectUnknownOptions(options);
     _CloudRoaring.rejectHollowSeams(options);
+    _CloudRoaring.rejectBadValues(options);
     const clock = options.seams?.clock ?? new SystemClock();
     const rng = options.seams?.rng ?? new SystemRng();
+    const entropy = options.seams?.entropy ?? systemEntropy;
     const metrics = safeMetrics(options.metrics ?? NOOP_METRICS2);
     const cache = new BoundedLru({
       maxEntries: options.cache?.maxChunks ?? DEFAULT_CACHE_MAX_CHUNKS,
@@ -1106,9 +1226,12 @@ var CloudRoaring = class _CloudRoaring {
     this.crbmSource = wired.source instanceof CrbmStorageChunkSource2 ? wired.source : void 0;
     this.clock = clock;
     this.rng = rng;
+    this.entropy = entropy;
     this.metrics = metrics;
     this.storageDriver = wired.driver;
     this.registry = wired.registry;
+    if (this.registry !== void 0) REGISTRY_OF.set(this.origin, this.registry);
+    this.backend = wired.backend;
     this.keystore = options.encryption?.keystore;
     this.requireEncryption = options.encryption?.required ?? false;
   }
@@ -1120,12 +1243,12 @@ var CloudRoaring = class _CloudRoaring {
    */
   lifecycleDeps(op) {
     if (this.storageDriver === void 0) {
-      throw new UnsupportedError(
+      throw new UnsupportedError2(
         `${op} needs the store built with a storage backend \u2014 S3Storage, GcsStorage, AzureBlobStorage, LocalFsStorage or MemoryStorage. A pre-built StorageChunkSource is read-only: it has no IStorageDriver underneath to write generations through. Build the store on one of those backend classes to write.`
       );
     }
     if (this.registry === void 0) {
-      throw new UnsupportedError(
+      throw new UnsupportedError2(
         `${op} needs a storage backend \u2014 S3Storage, GcsStorage, AzureBlobStorage, LocalFsStorage or MemoryStorage. A bare IStorageDriver has no generation pointer to publish through, and there is no separate \`registry\` option: a backend carries it.`
       );
     }
@@ -1134,6 +1257,7 @@ var CloudRoaring = class _CloudRoaring {
       registry: this.registry,
       clock: this.clock,
       rng: this.rng,
+      entropy: this.entropy,
       codec: roaringCodec,
       // facade injects the flagship codec
       keystore: this.keystore,
@@ -1150,13 +1274,18 @@ var CloudRoaring = class _CloudRoaring {
    * spread of options keeps working.
    */
   segment(name, options) {
+    if (typeof name === "object" && name !== null) {
+      throw new ValidationError5(
+        Array.isArray(name) ? "segment: the name is a string, store.segment('name'), not an array" : "segment: the name is a string, not a ref: for a ref, call store.segment(ref.segment, { namespace: ref.namespace })"
+      );
+    }
     if (options !== void 0 && options !== null) {
       if (typeof options !== "object" || Array.isArray(options)) {
-        throw new ValidationError4("segment: options must be an object such as { namespace }");
+        throw new ValidationError5("segment: options must be an object such as { namespace }");
       }
       const proto = Object.getPrototypeOf(options);
       if (proto !== null && Object.getPrototypeOf(proto) !== null) {
-        throw new ValidationError4(
+        throw new ValidationError5(
           "segment: options must be a plain object such as { namespace }, not a class instance or an object built on another"
         );
       }
@@ -1164,7 +1293,7 @@ var CloudRoaring = class _CloudRoaring {
         (k) => k !== "namespace" && options[k] !== void 0
       );
       if (unknown.length > 0) {
-        throw new ValidationError4(
+        throw new ValidationError5(
           `segment: unknown option${unknown.length > 1 ? "s" : ""} ${unknown.map((k) => `"${k}"`).join(", ")}; a handle takes { namespace } only`
         );
       }
@@ -1174,6 +1303,7 @@ var CloudRoaring = class _CloudRoaring {
     refuseReservedNamespace(ref.namespace);
     return makeSegment({
       engine: this.engine,
+      origin: this.origin,
       ref,
       clock: this.clock,
       metrics: this.metrics,
@@ -1245,7 +1375,7 @@ var CloudRoaring = class _CloudRoaring {
         // puts that call on the operator. Inheriting `load()`'s collection would silently delete the
         // generations an operator's recovery story depends on — `rollbackSegment` refuses a collected target —
         // as a side effect of adding a guard whose entire purpose is preventing data loss. Opt in with `keep`.
-        keep: options?.keep ?? KEEP_EVERY_GENERATION,
+        keep: options?.keep === void 0 ? KEEP_EVERY_GENERATION : options.keep,
         ...options?.audit === void 0 ? {} : { audit: options.audit }
       };
       result = ids instanceof CombineChunks ? await loadSegmentChunks(dest, ids.chunks, deps, loadOptions) : await loadSegment(dest, ids, deps, loadOptions);
@@ -1273,22 +1403,20 @@ var CloudRoaring = class _CloudRoaring {
   /** The one body of the forms above. */
   async materializeMany(options) {
     if (typeof options !== "object" || options === null) {
-      throw new ValidationError4(
+      throw new ValidationError5(
         "materializeMany needs an options object with `operands`, `outputs` and `keep`"
       );
     }
     const epochAt = options.feed === void 0 ? 0 : this.epochNow();
-    const unknown = Object.keys(options).filter(
-      (k) => !MATERIALIZE_MANY_KEYS.includes(k)
-    );
+    const unknown = unknownManyKeys(options);
     if (unknown.length > 0) {
-      throw new ValidationError4(
+      throw new ValidationError5(
         `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 ValidationError4("materializeMany: dryRun must be a boolean");
+      throw new ValidationError5("materializeMany: dryRun must be a boolean");
     }
     const dryRun = dryRunIn === true;
     const operandsIn = options.operands;
@@ -1300,7 +1428,7 @@ var CloudRoaring = class _CloudRoaring {
     const feedIn = options.feed;
     const mayBeEmptyIn = options.mayBeEmpty;
     if (feedIn !== void 0 && options.maxBufferedBytes === void 0) {
-      throw new ValidationError4(
+      throw new ValidationError5(
         "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"
       );
     }
@@ -1310,37 +1438,33 @@ var CloudRoaring = class _CloudRoaring {
     const budgetOption = options.budget;
     const allowAbsentOperands = options.allowAbsentOperands;
     if (typeof pinOption !== "boolean")
-      throw new ValidationError4("materializeMany: pin must be a boolean");
+      throw new ValidationError5("materializeMany: pin must be a boolean");
     if (allowAbsentOperands !== void 0 && typeof allowAbsentOperands !== "boolean") {
-      throw new ValidationError4("materializeMany: allowAbsentOperands must be a boolean");
+      throw new ValidationError5("materializeMany: allowAbsentOperands must be a boolean");
     }
     if (typeof operandsIn !== "object" || operandsIn === null || Array.isArray(operandsIn)) {
-      throw new ValidationError4("materializeMany: operands must be an object of name to segment");
+      throw new ValidationError5("materializeMany: operands must be an object of name to segment");
     }
     if (!Array.isArray(outputsIn) || outputsIn.length === 0) {
-      throw new ValidationError4("materializeMany: outputs must be a non-empty array");
+      throw new ValidationError5("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 ValidationError4(
-          `materializeMany: operands["${name}"] must be a segment from store.segment()`
-        );
-      }
+      assertOneStore("materializeMany", `operands["${name}"]`, handle, this.origin);
       handles.set(name, handle);
     }
     if (mayBeEmptyIn !== void 0 && feedIn === void 0) {
       if (!Array.isArray(mayBeEmptyIn)) {
-        throw new ValidationError4(
+        throw new ValidationError5(
           "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 ValidationError4(
+        throw new ValidationError5(
           `materializeMany: mayBeEmpty names ${what}; it names fed operands, and this call has no feed`
         );
       }
@@ -1350,28 +1474,26 @@ var CloudRoaring = class _CloudRoaring {
     const destKeys = /* @__PURE__ */ new Set();
     outputsIn.forEach((raw, i) => {
       if (typeof raw !== "object" || raw === null) {
-        throw new ValidationError4(`outputs[${i}] must be an object`);
+        throw new ValidationError5(`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 ValidationError4(
+        throw new ValidationError5(
           `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 ValidationError4(`outputs[${i}].dest must be a segment from store.segment()`);
-      }
+      assertOneStore("materializeMany", `outputs[${i}].dest`, dest, this.origin);
       if (operandKeys.has(dest.key())) {
-        throw new ValidationError4(
+        throw new ValidationError5(
           `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 ValidationError4(
+        throw new ValidationError5(
           `outputs[${i}].dest names a segment another output of the call writes`
         );
       }
@@ -1431,7 +1553,7 @@ var CloudRoaring = class _CloudRoaring {
     this.lifecycleDeps("materializeMany");
     const crbm = this.crbmSource;
     if (crbm === void 0) {
-      throw new UnsupportedError(
+      throw new UnsupportedError2(
         "materializeMany needs the `.crbm` storage source \u2014 pass a backend or a raw IStorageDriver as `storage`"
       );
     }
@@ -1444,13 +1566,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 ValidationError4(
+          throw new ValidationError5(
             `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 ValidationError4(
+          throw new ValidationError5(
             `materializeMany: operand "${name}" holds a segment another operand holds, ${twoPins(prior.at, at)}: one call reads a segment at one generation`
           );
         }
@@ -1538,7 +1660,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 ValidationError4(
+      throw new ValidationError5(
         "materializeMany: feed must be an object with names, records and counts"
       );
     }
@@ -1588,13 +1710,32 @@ var CloudRoaring = class _CloudRoaring {
    * tax every load for a rare request; this admin scan is `O(registered segments)` and touches no hot path. Needs
    * a storage backend (throws {@link UnsupportedError} otherwise).
    *
+   * **Scope: one `namespace`, or `{ allNamespaces: true }`, never both** (both throws `ValidationError`, as does
+   * neither). A segment loaded with no `namespace` is in no namespace you can name: only `{ allNamespaces: true }`
+   * reaches it. `'_default'`, the label the export tool and the disaster-recovery samples print, and the bucket's
+   * object keys use, for such a segment, is an ordinary namespace name here, and passing it scans a namespace of that name, not those segments.
+   *
    * **Current as of the registry row, not as of the reader's cache.** Each segment's resolved generation is
    * compared with the row the scan listed, and a segment whose cached generation differs is re-resolved before the
    * read, so a load or an erasure from another process shows at once — whatever `cache.genTtlMs` is, `0` included.
    * The comparison is on the generation **and** the row's token, so a segment retired, purged and loaded again from
    * generation 0 while this store held its old generation 0 is told apart too.
+   *
+   * **A destroyed segment is searched as {@link CloudRoaring.eraseSubject} searches it.** No read resolves a
+   * tombstone, so the id is a member of none, but a cleartext `destroySegment` (`allowCleartext`), or a `dropSegment`
+   * whose sweep missed an object a load was still writing, leaves objects anyone with bucket access can read. Each
+   * object left under the tombstone is opened newest first until one holds the id, and the segment is then listed in
+   * `tombstones`, never in `segments`. A crypto-shredded segment's own objects are sealed under a key no row holds and are
+   * never a holder: it is listed only when an object left under it in the clear holds the id. The cost is one listing per destroyed segment in scope (1 request when nothing is left), and for each
+   * object opened a tail read and, where its index lists the id's chunk, a chunk read (two tail reads for an encrypted
+   * object, which never holds the id): 7 requests for a cleartext destroy with 3 objects, 21 for 10. The budget is
+   * charged one unit for each object opened past the one the row names, as `eraseSubject` charges. A report that runs
+   * out, or whose listing or read fails after the store's retry, rejects rather than under-reporting, so one leftover
+   * object that cannot be opened makes every report over its scope reject until it is removed (`generations(ref)` lists
+   * what is left, `dropSegment` deletes it). A report refused for budget while it searches a destroyed segment reports
+   * `spent` as `limit + 1`, a lower bound.
    */
-  async subjectReport(id, options = {}) {
+  async subjectReport(id, options) {
     checkOptions(options, "subjectReport", CALL_KEYS.subjectReport, ["allNamespaces"]);
     options ??= {};
     const registry = this.requireRegistry("subjectReport");
@@ -1609,26 +1750,53 @@ var CloudRoaring = class _CloudRoaring {
       budget,
       "subjectReport"
     );
+    let opens = 0;
+    const charge = () => {
+      opens += 1;
+      if (budget !== null && recs.length + opens > budget.maxRequests) {
+        throw new BudgetExceededError(
+          `subjectReport would fan out to more than ${budget.maxRequests} units, over the per-op budget: the search under a destroyed segment was abandoned at that point, so no exact total is available. Raise \`budget.maxRequests\`, override it per-op, or set \`budget: false\``,
+          {
+            option: "budget.maxRequests",
+            limit: budget.maxRequests,
+            spent: budget.maxRequests + 1
+          }
+        );
+      }
+    };
     const membership = await mapWithConcurrency(
       recs,
       options.concurrency ?? DEFAULT_ADMIN_CONCURRENCY,
       async (rec) => {
-        if (rec.status === "destroyed") return null;
         const ref = { segment: rec.segment, namespace: rec.namespace };
+        if (rec.status === "destroyed") {
+          const deps = this.lifecycleDeps("subjectReport");
+          const storage = budget === null ? deps.storage : new OpenChargingStorage(deps.storage, rec.currentGen, charge);
+          const held = await findIdUnderTombstone(ref, id, { ...deps, storage });
+          return held === null ? null : { tombstone: true, ref };
+        }
         if (this.crbmSource !== void 0) {
           const held = await this.crbmSource.currentVersion(ref);
-          const listed = rec.currentGen === null ? null : `${rec.currentGen}:${pointerIdOf(rec)}`;
-          if (rowVersionOfLive(held) !== listed) this.engine.invalidate(ref);
+          const listed2 = rec.currentGen === null ? null : `${rec.currentGen}:${pointerIdOf(rec)}`;
+          if (rowVersionOfLive(held) !== listed2) this.engine.invalidate(ref);
         }
-        return await this.engine.has(ref, id) ? { segment: rec.segment, namespace: rec.namespace } : null;
+        return await this.engine.has(ref, id) ? { tombstone: false, ref } : null;
       }
     );
-    const segments = membership.filter((m) => m !== null);
-    return { id, segments, scannedSegments: recs.length };
+    const listed = membership.filter((m) => m !== null);
+    const segments = listed.filter((m) => !m.tombstone).map((m) => m.ref);
+    const tombstones = listed.filter((m) => m.tombstone).map((m) => m.ref);
+    return { id, segments, tombstones, scannedSegments: recs.length };
   }
   /**
    * **Subject erasure (GDPR Art. 17): remove an id from every segment it's in, with the bit physically gone
-   * from the bucket on return.**
+   * from the bucket on return for each segment the ledger reports `erased: true`.** A noncurrent version, a replica
+   * or a backup keeps the old object until its own lifecycle removes it.
+   *
+   * **Scope: one `namespace`, or `{ allNamespaces: true }`, never both** (both throws `ValidationError`, as does
+   * neither). A segment loaded with no `namespace` is in no namespace you can name: only `{ allNamespaces: true }`
+   * reaches it. `'_default'`, the label the export tool and the disaster-recovery samples print, and the bucket's
+   * object keys use, for such a segment, is an ordinary namespace name here, and passing it scans a namespace of that name, not those segments.
    *
    * For each **registered** segment the id is a member of, `eraseIdFromSegment` rewrites the current generation
    * without the id — every chunk streamed through, one bit cleared — publishes the rewrite **fenced on the
@@ -1693,15 +1861,17 @@ var CloudRoaring = class _CloudRoaring {
    * `O(registered segments + superseded generations)`, no hot-path cost: a segment whose current generation lacks
    * the id is searched generation by generation, one open for each other generation in its bucket, and with the
    * keep-everything default of the `*Into` verbs that is one per generation the segment ever had. The per-op
-   * `budget` is charged one unit for each segment and one for each generation opened beyond the one its row names,
-   * so a fleet with long histories can exhaust it where the segment count alone would not. A segment that does is
+   * `budget` is charged one unit for each segment and one for each generation opened beyond the one its row names, so
+   * a fleet with long histories can exhaust it where the segment count alone would not. A generation is charged at its
+   * first open only: a later open of it in the call, a retry of a failed read included, costs no more units. A segment
+   * that exhausts the budget is
    * reported `erased: false` with an `error:` note, before it deletes anything (the one refusal that can come after a
    * rewrite is the last check for a generation a concurrent writer left behind), and the
    * rest of the scan continues: the call itself does not throw for it. Per-subject crypto-shred is infeasible (a subject's bit is
    * co-mingled in a shared container), so this is the single-subject erasure route; whole-segment/tenant erasure
    * is `dropSegment` / the `destroySegment`/`eraseNamespace` free functions.
    */
-  async eraseSubject(id, options = {}) {
+  async eraseSubject(id, options) {
     this.erasureEpoch++;
     checkOptions(options, "eraseSubject", CALL_KEYS.eraseSubject, ["allNamespaces"]);
     options ??= {};
@@ -1757,7 +1927,8 @@ var CloudRoaring = class _CloudRoaring {
             segment: rec.segment,
             namespace: rec.namespace,
             erased: false,
-            note: `error: ${err instanceof Error ? err.message : String(err)}`
+            note: `error: ${errorKind(err) ?? (err instanceof Error ? err.name : "Error")}: ${err instanceof Error ? err.message : String(err)}`
+            // the class lets a note be matched to the guide's table
           };
         } finally {
           try {
@@ -1778,11 +1949,12 @@ var CloudRoaring = class _CloudRoaring {
    * 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.
+   * No entry is `current` on a destroyed segment: its row keeps the pointer it had, but no read resolves through it.
    *
    * Needs a backend.
    */
   async generations(ref) {
-    validateSegmentRef(ref);
+    ref = validateRef(ref, "generations");
     return listGenerations(ref, this.lifecycleDeps("generations"));
   }
   /**
@@ -1812,7 +1984,7 @@ var CloudRoaring = class _CloudRoaring {
    * ```
    */
   async exists(ref) {
-    validateSegmentRef(ref);
+    ref = validateRef(ref, "exists");
     return segmentExists(ref, this.requireRegistry("exists"));
   }
   /**
@@ -1869,8 +2041,9 @@ var CloudRoaring = class _CloudRoaring {
    * {@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
+   * destroyed segment (crypto-shredded, destroyed in the clear or dropped) throws {@link ValidationError}, because no
+   * generation resolves through a destroyed row, 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.
@@ -1881,8 +2054,10 @@ var CloudRoaring = class _CloudRoaring {
    * 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
+   * thrown. A swap of the pointer that gets no answer, or that meets a conflict, is settled by reading the row: one
+   * that landed, the row's pointer being at the target over a write this call sent (the write token, on a registry that
+   * reports them), is checked as any is, and otherwise its `TransientError` is thrown, or a `WriteConflictError` after
+   * a conflict, with no move recorded. 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 —
@@ -1912,7 +2087,7 @@ var CloudRoaring = class _CloudRoaring {
    * Needs a backend.
    */
   async rollback(ref, toGeneration, options = {}) {
-    validateSegmentRef(ref);
+    ref = validateRef(ref, "rollback");
     checkOptions(options, "rollback", CALL_KEYS.rollback, ["allowUnknown"]);
     options ??= {};
     const deps = this.lifecycleDeps("rollback");
@@ -1928,9 +2103,15 @@ var CloudRoaring = class _CloudRoaring {
    * `input` is ids (any sync or async iterable of integers in `[0, 2^32)`), or a whole bitmap: `{ bitmap }`, anything
    * with `serialize('portable')` such as `roaring`'s `RoaringBitmap32`, or `{ serialized }`, portable Roaring bytes.
    * A bitmap is checked (size cap, structure, safe deserializer) before the first request, written from its own
-   * containers with no per-id work, and gives the generation byte for byte the one its ids would. A bare
-   * `RoaringBitmap32` passed as ids loads as `{ bitmap }`. A `Uint8Array` or `Buffer` passed as ids is refused with
-   * `ValidationError`, since each byte would load as an id: pass bytes as `{ serialized }`.
+   * containers with no per-id work, and gives the generation chunk for chunk what its ids would. A bare
+   * `RoaringBitmap32`, or a bitmap `deserializePortable` returned, passed as ids loads as `{ bitmap }`. A
+   * `Uint8Array` or `Buffer` passed as ids is refused with `ValidationError`, since each byte would load as an id:
+   * pass bytes as `{ serialized }`.
+   *
+   * Ids are held whole in memory before the object is written: the generation's bitmaps and a buffer of up to about 28
+   * MB. Ids that already ascend can be loaded with `sorted: true` instead, which writes them one chunk at a time while
+   * the object uploads, so the load holds one chunk and the writer's index (up to about 7 MiB, about 8 MiB for an
+   * encrypted segment, derived), whatever the segment's size, and writes the same object ({@link LoadOptions.sorted}).
    *
    * The whole write path in one call: take the next generation number, write the object, check the result is
    * plausible, move the pointer, collect what the move superseded. Composed by hand those are four functions and
@@ -1974,7 +2155,7 @@ var CloudRoaring = class _CloudRoaring {
    * 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
+   * writer's object, and the row does not say whether that write took this number, 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
@@ -1989,7 +2170,14 @@ var CloudRoaring = class _CloudRoaring {
    * does the first load of a row that records none, which then records it. {@link LoadResult.collected} then names
    * what the pass deleted by name, and one name may have been gone already.
    *
-   * What it **throws** for is a fault rather than an outcome: invalid options or ids, and a crypto-shredded
+   * `input` cannot be a stream of this library (`iterate`, `everyNth`, `intersect`, `union`, `andNot`, as returned) that
+   * read the segment being loaded, from this store or one built over the same registry driver: a load publishes over
+   * whatever the segment is by then, so it would replace another writer's newer load with a result built from an older
+   * one, and it throws {@link ValidationError}. Ids read from another store over another backend load as any ids do.
+   * Two separate store instances over one bucket cannot be told apart, so this does not cover them; this release has no
+   * fenced in-place update, so write the result into a new segment and point readers at it.
+   *
+   * What it **throws** for is a fault rather than an outcome: invalid options or ids, and a destroyed
    * segment (`ValidationError`); a key the keystore cannot provide (`KeyUnavailableError`); a current generation
    * that will not open when a guard has to read its size, which it does only when the row has no usable summary of it
    * (`IntegrityError`); a driver failure; and a fault in the collection's own reads, listing or deletes, or in the write
@@ -2012,8 +2200,18 @@ var CloudRoaring = class _CloudRoaring {
    * Needs a backend (throws {@link UnsupportedError} otherwise).
    */
   async load(ref, input, options = {}) {
-    validateSegmentRef(ref);
-    checkOptions(options, "load", CALL_KEYS.load, ["allowEmpty"]);
+    ref = validateRef(ref, "load");
+    checkOptions(options, "load", CALL_KEYS.load, ["allowEmpty", "sorted"]);
+    if (typeof input === "object" && input !== null) {
+      const reads = STREAM_SOURCES.get(input);
+      const sameBackend = reads !== void 0 && (reads.origin === this.origin || this.registry !== void 0 && REGISTRY_OF.get(reads.origin) === this.registry);
+      if (sameBackend && reads.keys.includes(segmentKey(ref))) {
+        const named = ref.namespace === void 0 ? ref.segment : `${ref.namespace}/${ref.segment}`;
+        throw new ValidationError5(
+          `load: the ids come from a read of the segment "${named}" that is being loaded, and a load publishes over whatever the segment is by then, so another process's newer load of it can be replaced by a result built from the one before, with no conflict reported. This release has no fenced in-place update: write the result into a new segment and point readers at it`
+        );
+      }
+    }
     options ??= {};
     const deps = this.lifecycleDeps("load");
     try {
@@ -2023,11 +2221,14 @@ var CloudRoaring = class _CloudRoaring {
     }
   }
   /**
-   * **Dispose of a segment — tombstone it, then delete its storage objects.** Irreversible.
+   * **Dispose of a segment — tombstone it, then delete its storage objects.** It cannot be undone through the
+   * library (a restore from the registry's and the bucket's versions or backups can).
    *
-   * The operation a rolling window needs: `destroySegment` crypto-shreds (bytes unreadable everywhere including
-   * backups, but still sitting in your bucket and still billed, and it requires encryption), while this one
-   * removes the storage and works on a cleartext segment. On an encrypted segment it does both.
+   * The operation a rolling window needs: `destroySegment` crypto-shreds (it removes the key from the segment's
+   * current registry row, so the bytes are unreadable everywhere, backups included, once no retained copy of the row
+   * holds the key or every KEK that wrapped it is destroyed; the objects still sit in your bucket and are still
+   * billed, and it requires encryption), while this one removes the storage and works on a cleartext segment. On an
+   * encrypted segment it does both.
    *
    * Pass `{ dryRun: true }` first — it reports the generations it *would* delete and changes nothing. That
    * matters more than the `confirmSegment` guard for anything automated, because in a loop the guard is the same
@@ -2058,7 +2259,7 @@ var CloudRoaring = class _CloudRoaring {
    * segment may answer from its cached generation + cached chunks until that window lapses, or, while the registry
    * cannot be read because of a transient fault, until a retry 500 ms apart reaches it again. A reader that never
    * touched it sees empty at once. **That bound needs a registry and `cache.genTtlMs > 0`.** A store with no registry
-   * (a bare `IStorageDriver`), with `cache.genTtlMs: 0`, or on a storage source built with no clock, has no timed
+   * (a bare `IStorageDriver`), with `cache.genTtlMs: 0`, or on a `StorageChunkSource` of your own, has no timed
    * refresh. It notices the drop only when a read has to fetch
    * from a deleted generation or its reader cache evicts the segment, and until then a chunk it has cached
    * answers without reaching storage, so it can keep answering `true` for a dropped segment indefinitely. Tell
@@ -2068,9 +2269,9 @@ var CloudRoaring = class _CloudRoaring {
    * because it has to enumerate and delete generations — a pre-built `StorageChunkSource` only reads.
    */
   async dropSegment(ref, options) {
-    validateSegmentRef(ref);
+    ref = validateRef(ref, "dropSegment");
     if (options === void 0 || options === null) {
-      throw new ValidationError4("dropSegment: options { confirmSegment } are required");
+      throw new ValidationError5("dropSegment: options { confirmSegment } are required");
     }
     checkOptions(options, "dropSegment", CALL_KEYS.dropSegment, ["dryRun"]);
     const deps = this.lifecycleDeps("dropSegment");
@@ -2085,8 +2286,9 @@ var CloudRoaring = class _CloudRoaring {
     }
   }
   /**
-   * **Record when this segment becomes eligible for retirement.** One registry write; nothing is deleted here,
-   * and nothing starts running. `retireExpired` is what acts on the policy, and **you** decide when that runs —
+   * **Record when this segment becomes eligible for retirement.** One policy write, plus a best-effort write of its
+   * due-index pointer (and removal of the old pointer when the expiry day moves); no data is deleted here, and
+   * nothing starts running. `retireExpired` is what acts on the policy, and **you** decide when that runs —
    * an EventBridge rule, a CronJob, a queue consumer, whatever your deployment already has. This library starts
    * no background thread (it has to work identically in a Lambda, an edge isolate and a long-lived server).
    *
@@ -2106,12 +2308,12 @@ var CloudRoaring = class _CloudRoaring {
    * enumerable by the sweep; the first load then publishes onto that row.
    *
    * A value in the past is legal and means "eligible on the next sweep" — backfilling a policy onto existing
-   * buckets is normal. A value below `MIN_EXPIRES_AT_MS` (2001-09-09) is rejected: it is almost certainly epoch
+   * buckets is normal. A value below `1_000_000_000_000` (2001-09-09) is rejected: it is almost certainly epoch
    * **seconds**, which would read as long-expired and retire the segment on the next pass. Needs a storage
-   * backend (throws {@link UnsupportedError} otherwise), and refuses a crypto-shredded segment.
+   * backend (throws {@link UnsupportedError} otherwise), and refuses a destroyed segment.
    */
   async setRetention(ref, policy) {
-    validateSegmentRef(ref);
+    ref = validateRef(ref, "setRetention");
     return setSegmentRetention(
       ref,
       { registry: this.requireRegistry("setRetention"), clock: this.clock, rng: this.rng },
@@ -2125,16 +2327,18 @@ var CloudRoaring = class _CloudRoaring {
    * "never expires" on a segment someone believes is expiring.
    */
   async getRetention(ref) {
-    validateSegmentRef(ref);
+    ref = validateRef(ref, "getRetention");
     return getSegmentRetention(ref, { registry: this.requireRegistry("getRetention") });
   }
   /**
-   * **Cancel a segment's expiry** so no sweep retires it. Returns whether a policy was actually removed (`false`
-   * when there was none). A separate verb from `setRetention` on purpose: "never expire" as a magic value passed
+   * **Cancel a segment's expiry** so no sweep retires it. Returns whether this call removed a policy (`false`
+   * when there was none, and also when a write that got no answer cannot be shown to be this call's and the
+   * row holds no expiry: the expiry is gone either way, and its due-index pointer is removed. A later write that set an
+   * expiry is cleared too, and the answer is `true`). A separate verb from `setRetention` on purpose: "never expire" as a magic value passed
    * to the setter is how a typo becomes a deletion.
    */
   async clearRetention(ref) {
-    validateSegmentRef(ref);
+    ref = validateRef(ref, "clearRetention");
     return clearSegmentRetention(ref, {
       registry: this.requireRegistry("clearRetention"),
       clock: this.clock,
@@ -2159,20 +2363,22 @@ var CloudRoaring = class _CloudRoaring {
    *
    * const swept = await store.retireExpired({ namespace: 'active-daily' });
    * for (const e of swept.entries) {
-   *   if (e.action === 'skipped') console.warn(`${e.segment}: ${e.reason}`); // invalid-policy / limit / failed: …
+   *   // invalid-policy / policy-changed / tombstone-not-empty / failed: …
+   *   if (e.action === 'skipped') console.warn(`${e.segment}: ${e.reason}`);
    *   if (e.action === 'retired' && e.result.generationsRemaining.length > 0) {
    *     console.warn(`${e.segment}: storage not fully reclaimed — re-run`);
    *   }
    * }
-   * if (swept.limited) scheduleAnotherPassSoon(); // more are still eligible
+   * if (swept.limited) scheduleAnotherPassSoon(); // more work (retirements or purges) remains
    * ```
    *
    * **Read the ledger.** A per-segment *fault* is an entry, not an exception — a throw from the middle of a fleet
    * sweep would leave the caller unable to say which segments were retired, having already retired some. (A bad
    * argument does throw, and so does a fleet larger than `maxScanSegments`.) `limited: true` means the per-cycle
-   * `limit` (default 100) cut the pass short and more are eligible. That cap is charged on **attempts**, not
-   * successes, which is what makes it a real bound: `dropSegment` writes the tombstone before sweeping Storage, so a
-   * fault in the Storage phase is a segment that is already retired. Retirements are sequential, so `limit` is a
+   * `limit` (default 100) cut the pass short, and more work (retirements or purges) remains: `limit` caps the
+   * retirements and tombstone purges one call attempts, together, and a segment it deferred gets no entry. That cap
+   * is charged on **attempts**, not successes, which is what makes it a real bound: `dropSegment` writes the
+   * tombstone before sweeping Storage, so a fault in the Storage phase is a segment that is already retired. Retirements are sequential, so `limit` is a
    * wall-clock knob too, and `retired` counts deletions only — a dry run reports `wouldRetire` instead, so a
    * dashboard summing `retired` can never show a phantom deletion.
    *
@@ -2182,9 +2388,11 @@ var CloudRoaring = class _CloudRoaring {
    * charged to `limit`, so it never holds the retirements behind it, and purging stops for the rest of the call after
    * three refused purges in a row (a purge that succeeds starts the count again).
    *
-   * It also **deletes the tombstone rows its own past retirements left**, after `tombstoneGraceMs` (default 24 h)
+   * It also **deletes the tombstone rows its own past retirements left**, after `tombstoneGraceMs` (default 24 h; at least one hour, else `ValidationError`)
    * and only once that segment's Storage generations are provably gone — collecting a straggler generation itself
-   * first, since nothing else ever would for a tombstoned segment. Attribution is a **positive marker the sweep
+   * first, since nothing else runs that collection on its own for a tombstoned segment (an erasure collects there
+   * only
+   * when an object holds its id, and a re-run drop sweeps it). Attribution is a **positive marker the sweep
    * stamps on its own retirements**, not an inference from "destroyed + an expired policy": a crypto-shred leaves
    * `retention` untouched, so setting a policy and then honouring a right-to-erasure request mid-window produces
    * exactly that row, and deleting it would destroy the Art. 17 attestation and un-fence the name. By default a
@@ -2205,7 +2413,7 @@ var CloudRoaring = class _CloudRoaring {
     const deps = this.lifecycleDeps("retireExpired");
     const result = await retireExpired(
       { registry: deps.registry, storage: deps.storage, clock: this.clock, rng: this.rng },
-      { ...opts, now: opts.now ?? this.clock.now() }
+      { ...opts, now: opts.now === void 0 ? this.clock.now() : opts.now }
     );
     if (opts.dryRun !== true) {
       for (const entry of result.entries) {
@@ -2234,7 +2442,7 @@ var CloudRoaring = class _CloudRoaring {
    *   A pin answers with no timed bound, until it is told or both caches let it go.
    * - **Another process.** Erasing on one box invalidates nothing on the others; each store bounds its own
    *   staleness by `cache.genTtlMs`, and a store with no registry (a bare `IStorageDriver`), with
-   *   `cache.genTtlMs: 0`, or on a storage source built with no clock has no bound at all: it converges only when a read happens to miss its caches. If a compliance deadline depends on every
+   *   `cache.genTtlMs: 0`, or on a `StorageChunkSource` of your own has no bound at all: it converges only when a read happens to miss its caches. If a compliance deadline depends on every
    *   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
@@ -2252,7 +2460,7 @@ var CloudRoaring = class _CloudRoaring {
    * ```
    */
   invalidate(ref) {
-    validateSegmentRef(ref);
+    ref = validateRef(ref, "invalidate");
     refuseReservedNamespace(ref.namespace);
     this.engine.invalidate(ref);
   }
@@ -2267,8 +2475,8 @@ var CloudRoaring = class _CloudRoaring {
   async pinSegment(ref, leaseUntil, named) {
     const crbm = this.crbmSource;
     if (crbm === void 0) {
-      throw new UnsupportedError(
-        "pin() needs the `.crbm` storage source \u2014 pass a backend or a raw IStorageDriver as `storage` (a pre-built StorageChunkSource that cannot resolve a generation has nothing to pin)"
+      throw new UnsupportedError2(
+        "pin() needs the `.crbm` storage source \u2014 pass a backend or a raw IStorageDriver as `storage` (the store cannot pin a StorageChunkSource of your own)"
       );
     }
     let hold;
@@ -2276,7 +2484,7 @@ var CloudRoaring = class _CloudRoaring {
     if (leaseUntil !== void 0) {
       const registry = this.requireRegistry("pin({ leaseUntil })");
       if (registry.capabilities().canWrite === false) {
-        throw new UnsupportedError(
+        throw new UnsupportedError2(
           "pin({ leaseUntil }) needs a registry that can write a row, and this store's cannot in this runtime"
         );
       }
@@ -2312,14 +2520,11 @@ var CloudRoaring = class _CloudRoaring {
       if (hold !== void 0) await hold.release().catch(() => void 0);
       throw err;
     }
-    const pinnedAt = {
-      generation: at?.generation ?? null,
-      version: at?.version ?? null,
-      fingerprint: at?.fingerprint ?? null
-    };
+    const pinnedAt = at === null ? { generation: null, version: null, fingerprint: null } : { generation: at.generation, version: at.version, fingerprint: at.fingerprint };
     const pins = /* @__PURE__ */ new Map([[segmentKey(ref), pinnedAt]]);
     return makeSegment({
       engine: this.engineWithPins(pins),
+      origin: this.origin,
       ref,
       clock: this.clock,
       metrics: this.metrics,
@@ -2347,8 +2552,8 @@ var CloudRoaring = class _CloudRoaring {
   engineWithPins(pins) {
     const crbm = this.crbmSource;
     if (crbm === void 0) {
-      throw new UnsupportedError(
-        "pin() needs the `.crbm` storage source \u2014 pass a backend or a raw IStorageDriver as `storage` (a pre-built StorageChunkSource that cannot resolve a generation has nothing to pin)"
+      throw new UnsupportedError2(
+        "pin() needs the `.crbm` storage source \u2014 pass a backend or a raw IStorageDriver as `storage` (the store cannot pin a StorageChunkSource of your own)"
       );
     }
     const pinned = new PinnedStorageChunkSource(crbm, pins);
@@ -2385,8 +2590,8 @@ var CloudRoaring = class _CloudRoaring {
       if (held.has(key)) {
         const before = held.get(key);
         if (!samePin(before, at)) {
-          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, [])\``
+          throw new ValidationError5(
+            `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 \`materializeMany({ operands: { src: seg }, outputs: [{ dest, expr: { or: ['src'] } }], keep })\``
           );
         }
       } else {
@@ -2404,7 +2609,7 @@ var CloudRoaring = class _CloudRoaring {
   /** The store's registry, or a typed error naming the operation that needs one. */
   requireRegistry(op) {
     if (this.registry === void 0) {
-      throw new UnsupportedError(
+      throw new UnsupportedError2(
         `${op} needs a storage backend \u2014 S3Storage, GcsStorage, AzureBlobStorage, LocalFsStorage or MemoryStorage. A bare IStorageDriver has no generation pointer to publish through, and there is no separate \`registry\` option: a backend carries it.`
       );
     }
@@ -2417,8 +2622,9 @@ var CloudRoaring = class _CloudRoaring {
    * throw). Read-only, bounded fan-out; run it at startup after a restore. Returns `{ checked, inconsistent,
    * errored }` — `inconsistent` empty ⇒ coherent; otherwise it names the segments to recover (restore the object
    * store, or roll the registry back to a coherent point). Needs the store built with a **backend**
-   * (throws {@link UnsupportedError} otherwise). `destroyed` (crypto-shredded) segments are skipped. Pair it with
-   * the DR runbook (docs/guide/disaster-recovery.md).
+   * (throws {@link UnsupportedError} otherwise). `destroyed` segments (crypto-shredded, destroyed in the clear or
+   * dropped) are skipped. Pair
+   * it with the DR runbook (docs/guide/disaster-recovery.md).
    *
    * A segment whose pointer names a missing object is the torn restore this reports; a cold `count()` of it still
    * answers the number its row records, while a read of the object throws, so the count alone never shows it. With
@@ -2435,9 +2641,9 @@ var CloudRoaring = class _CloudRoaring {
    * 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`.
+   * `BudgetExceededError` (`option: 'maxScanSegments'`) past that rather than report a partial scan as a whole one.
+   * Narrow the scan with `namespace`, or raise `maxScanSegments` when the fleet really is that large and the memory
+   * is there.
    */
   async checkConsistency(options = {}) {
     checkOptions(options, "checkConsistency", CALL_KEYS.checkConsistency, [
@@ -2451,6 +2657,56 @@ var CloudRoaring = class _CloudRoaring {
       options
     );
   }
+  /**
+   * **First-run check of the store's storage and registry.** Call it once at deploy time, or on a first run, before
+   * the first load: it finds a missing permission, a storage that does not refuse a second write to a key, a listing
+   * that lags, or a lifecycle rule that would delete the store's objects, while nothing depends on them yet.
+   *
+   * It runs seven checks and always lists all seven, in this order: `registry` (one read of a row that must be
+   * absent, and the registry able to write), `write` (a new object), `write-once` (a second write to the same key must
+   * be refused), `read` (the object reads back as written), `list` (the listing names it), `delete` (this run's own
+   * object is removed, with the version the read gave where the driver applies one) and `lifecycle` (the backend's
+   * lifecycle check). The probe is one small object at `cbm.due.preflight/segments/probe.<number>.crbm` under the
+   * store's prefix; no registry row is written, and no segment of yours can share the name. A probe left by a run that
+   * was cut off is named in the `list` detail and never deleted, since it could be a run in progress.
+   *
+   * It **never throws over a finding**. A failed step, a transient fault included, is a `problem` whose `detail`
+   * says to run again when the fault was transient, and the checks that cannot run without it are `unchecked`. The
+   * exception is the `lifecycle` step, whose failures, its timeout included, are `unchecked`. `ok` is true when no
+   * check is a `problem`: read an `unchecked` check yourself, as `ok` does not vouch for it. The `lifecycle` check is
+   * `unchecked` for a backend whose check says so (Azure Blob always), for a backend that has no such method (a
+   * third-party backend, a `brandAsBackend` wrapper that does not forward it), when the identity lacks the optional
+   * permission to read the lifecycle rules (`s3:GetLifecycleConfiguration`, `storage.buckets.get`), and when the check
+   * takes longer than 30 seconds of the store's clock. The other steps are the store's ordinary calls and keep their
+   * timing.
+   *
+   * **Not checked:** read-after-delete, the registry's `If-Match` on compare-and-swap, multipart abort permission,
+   * versioning, backups, the keystore's backup and an S3 SDK from 3.641.0 to 3.699.0 (an older SDK shows as a
+   * `write-once` problem; these drop `If-Match`, which only a registry write refuses). It makes no kind of request that a
+   * load does not, though the lifecycle read needs its own optional permission. A run costs about seven requests (a
+   * first run on GCS makes eight, the eighth a second listing that checks the bucket exists, and Azure Blob always
+   * eight): two writes and a delete, the rest reads and one listing.
+   *
+   * Throws {@link UnsupportedError}, and only that, for a store with no backend, since there is nothing to check.
+   */
+  async preflight() {
+    const deps = this.lifecycleDeps("preflight");
+    const backend = this.backend;
+    let checkLifecycle;
+    try {
+      const method = backend?.checkLifecycle;
+      if (typeof method === "function")
+        checkLifecycle = method.bind(backend);
+    } catch {
+    }
+    return runPreflight({
+      storage: deps.storage,
+      registry: deps.registry,
+      clock: this.clock,
+      entropy: this.entropy,
+      checkLifecycle
+    });
+  }
   /**
    * **Export ("eject") every registered segment's current generation** through the injected `sink`, using only
    * public read APIs — so your data is readable **without CloudRoaring** (the exit path; see the README's "Your
@@ -2459,15 +2715,16 @@ var CloudRoaring = class _CloudRoaring {
    * Enumerates via the store's **own** registry (needs one — throws {@link UnsupportedError} otherwise) so the
    * enumeration and the read path provably share one registry. Encrypted segments are decrypted transparently
    * **iff** this store was wired with their keystore — the export is therefore **cleartext**; protect it.
-   * Crypto-shredded segments are skipped. A segment that can't be read is isolated into the manifest's `failed[]`
-   * (the run continues), so "a manifest exists" means the run finished — check `failed`. The `export-segments`
-   * CLI wraps this with a filesystem sink.
+   * Destroyed segments (crypto-shredded, destroyed in the clear or dropped) are skipped. A segment that can't be read
+   * is isolated into the manifest's `failed[]` (the run continues), so "a manifest exists" means the run finished —
+   * check `failed`. The `export-segments`
+   * CLI wraps this with a filesystem sink. The `'roaring'` format's bitmaps are built by the store's own codec.
    */
   async exportSegments(sink, options = {}) {
-    checkOptions(options, "exportSegments", CALL_KEYS.exportSegments);
+    checkOptions(options, "exportSegments", CALL_KEYS.exportSegments, [], MISPLACED.exportSegments);
     const opts = picked(options, CALL_KEYS.exportSegments);
     const registry = this.requireRegistry("exportSegments");
-    return runExport(this, registry, sink, { ...opts, codec: opts.codec ?? roaringCodec });
+    return runExport(this, registry, sink, { ...opts, codec: roaringCodec });
   }
 };
 var withBatches = (gen, batches) => Object.assign(gen, { batches });
@@ -2495,12 +2752,23 @@ var readOptions = (options) => ({
 });
 var NO_SEGMENTS = [];
 function segmentList(list, what) {
-  if (!Array.isArray(list)) throw new ValidationError4(`${what} must be an array of segments`);
+  if (!Array.isArray(list)) throw new ValidationError5(`${what} must be an array of segments`);
   return list;
 }
+var STREAM_SOURCES = /* @__PURE__ */ new WeakMap();
+var REGISTRY_OF = /* @__PURE__ */ new WeakMap();
+function readsFrom(stream, origin, keys) {
+  STREAM_SOURCES.set(stream, { origin, keys });
+  return stream;
+}
 function operandsLabel(verb) {
   return verb === "andNot" ? "andNot: `excludes`" : `${verb}: \`others\``;
 }
+function refuseNoOperands(verb) {
+  throw new ValidationError5(
+    verb === "intersect" ? "intersect requires at least one segment to intersect with; to read every id of one segment, use iterate()" : "intersectInto requires at least one segment to intersect with; to copy this segment into dest, call materializeMany({ operands: { src: thisSegment }, outputs: [{ dest, expr: { or: ['src'] } }], keep })"
+  );
+}
 var AS_IDS = {
   failing,
   guard: guardIds,
@@ -2517,9 +2785,9 @@ var CombineChunks = class {
 var AS_CHUNKS = {
   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)
+  intersect: (engine, refs, opts) => engine.intersectChunks(refs, opts, "intersectInto"),
+  union: (engine, refs, opts) => engine.unionChunks(refs, opts, "unionInto"),
+  andNot: (engine, base, refs, opts) => engine.andNotChunks(base, refs, opts, "andNotInto")
 };
 var KEEP_EVERY_GENERATION = Number.MAX_SAFE_INTEGER;
 async function timeOp(metrics, clock, name, fn) {
@@ -2535,6 +2803,8 @@ var minting = false;
 var Segment = class _Segment {
   metricsOn;
   engine;
+  /** The store that made this handle, by reference; a combine takes only handles of its own store. */
+  origin;
   ref;
   clock;
   metrics;
@@ -2568,6 +2838,7 @@ var Segment = class _Segment {
       pinnedAt: segment.pinnedAt,
       leaseError: () => segment.leaseError()
     });
+    originOf = (segment) => segment.origin;
   }
   /**
    * Not constructible: a handle comes from {@link CloudRoaring.segment}, which wires it to the store's engine,
@@ -2575,11 +2846,12 @@ var Segment = class _Segment {
    */
   constructor(parts) {
     if (!minting) {
-      throw new ValidationError4(
+      throw new ValidationError5(
         "a Segment is not constructed directly; call `store.segment(name)`"
       );
     }
     this.engine = parts.engine;
+    this.origin = parts.origin;
     this.ref = parts.ref;
     this.clock = parts.clock;
     this.metrics = parts.metrics;
@@ -2613,7 +2885,7 @@ var Segment = class _Segment {
    *
    * **One call reads a segment at one generation**, so a combine that holds this segment at two —
    * `snap0.andNot([snap1])`, or `live.intersect([snap])` — throws {@link ValidationError} when it is read, and an
-   * `*Into` of one throws before it reads anything. Materialise one side first, with `intersectInto(dest, [])`.
+   * `*Into` of one throws before it reads anything. Materialise one side first, with `materializeMany({ operands: { src: seg }, outputs: [{ dest, expr: { or: ['src'] } }], keep })`.
    *
    * **A pin knows its object, not only its number.** A name purged and loaded again starts again at generation
    * 0, so a pin of the old segment never reads the new one: what it has already read still answers, as the
@@ -2653,9 +2925,7 @@ var Segment = class _Segment {
    * 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. 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
+   * {@link CloudRoaring.invalidate} is called on this store. A combine on another store refuses the pin. 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.
    *
@@ -2675,7 +2945,7 @@ var Segment = class _Segment {
    * or misfiled one.
    *
    * Needs a store built on the `.crbm` storage source (the default when you pass a backend or a raw driver). Throws
-   * {@link UnsupportedError} on a store wired with a pre-built source that cannot pin.
+   * {@link UnsupportedError} on a store wired with a `StorageChunkSource` of your own, which it cannot pin.
    */
   async pin(options) {
     this.assertLease();
@@ -2690,11 +2960,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 ValidationError4(`${op}: options must be an object such as { leaseUntil }`);
+      throw new ValidationError5(`${op}: options must be an object such as { leaseUntil }`);
     }
     const unknown = Object.keys(options).filter((k) => k !== "leaseUntil");
     if (unknown.length > 0) {
-      throw new ValidationError4(
+      throw new ValidationError5(
         `${op}: unknown option${unknown.length > 1 ? "s" : ""} ${unknown.map((k) => `"${k}"`).join(", ")}; this version takes { leaseUntil } only`
       );
     }
@@ -2702,17 +2972,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 ValidationError4(
+      throw new ValidationError5(
         `${op}: leaseUntil must be an integer epoch-MILLISECONDS; got ${String(until)}`
       );
     }
     if (until <= now) {
-      throw new ValidationError4(
+      throw new ValidationError5(
         `${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 ValidationError4(
+      throw new ValidationError5(
         `${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`
       );
     }
@@ -2763,18 +3033,12 @@ var Segment = class _Segment {
     return void 0;
   }
   /**
-   * Refuse with a {@link ValidationError} anything among `handles` that is not a segment, a value a JavaScript caller
-   * passed. It runs first in every combine, before the lease check reads the handles.
+   * Refuse with a {@link ValidationError} any of `handles` that this store did not make: a value that is not a segment,
+   * a segment of another store (even one over the same backend) and a segment of another installed copy of the
+   * package. It runs first in every combine, before the lease check reads the handles and before any request.
    */
-  assertSegments(handles) {
-    for (const h of handles) {
-      if (h instanceof _Segment || typeof h === "object" && h !== null && h[SEGMENT_BRAND] === true) {
-        continue;
-      }
-      throw new ValidationError4(
-        "an operand must be a segment from `store.segment()` of a compatible copy of @cloudbitmaps/roaring; install one version of it"
-      );
-    }
+  assertSegments(verb, role, handles) {
+    for (const h of handles) assertOneStore(verb, role, h, this.origin);
   }
   /**
    * Throw the first lease error among `handles`: this handle and every operand and exclude of a call. It runs before
@@ -2796,10 +3060,10 @@ var Segment = class _Segment {
    * `at.generation` instead of the current one. Pass what the earlier pin recorded, `{ generation, fingerprint }`
    * from its {@link Segment.pinnedAt}. A generation number alone is not an identity, since a purged and re-created
    * name starts again at 0, so the fingerprint is required: a bare number, a malformed fingerprint or a key other
-   * than `generation` and `fingerprint` is a {@link ValidationError}. Identify a pin by its `generation` and
+   * than `generation`, `fingerprint` and `version` is a {@link ValidationError}. Identify a pin by its `generation` and
    * `fingerprint`: the handle's `pinnedAt.version` can differ from the earlier pin's.
    *
-   * Throws {@link NotFoundError} when the generation is gone (collected, purged, or on a crypto-shredded segment),
+   * Throws {@link NotFoundError} when the generation is gone (collected, purged, or on a destroyed segment),
    * is above the row's pointer, or is another object than the fingerprint names, and never reads empty. A rollback
    * deletes nothing, so once a later load moves the pointer past a generation it rolled back from, that one can be
    * reopened while its object is stored. Nothing keeps a generation alive unless you lease it: a later load's
@@ -2812,18 +3076,32 @@ var Segment = class _Segment {
    * then reads as one from `pin()` does, including its failure on a chunk it has not cached once the generation is
    * swept. Works for an encrypted segment. The first argument is an object so that fields can join it later; the lease
    * is in `options`, the second.
+   *
+   * It takes what {@link Segment.pinnedAt} holds: once `generation` is not `null`, the record passes as it is (its
+   * `version` is not read), and `{ generation, fingerprint }` does as well. A pin of a segment that had no generation
+   * has nothing to reopen and throws {@link ValidationError}.
    */
   async pinAt(at, options) {
     this.assertLease();
-    const { generation, fingerprint } = at ?? {};
-    const unknown = typeof at === "object" && at !== null ? Object.keys(at).filter((k) => k !== "generation" && k !== "fingerprint") : [];
+    const { generation, fingerprint, version } = at ?? {};
+    const unknown = typeof at === "object" && at !== null ? Object.keys(at).filter((k) => !["generation", "fingerprint", "version"].includes(k)) : [];
     if (unknown.length > 0) {
-      throw new ValidationError4(
-        `pinAt: unknown option${unknown.length > 1 ? "s" : ""} ${unknown.map((k) => `"${k}"`).join(", ")}; this version takes { generation, fingerprint } only`
+      throw new ValidationError5(
+        `pinAt: unknown option${unknown.length > 1 ? "s" : ""} ${unknown.map((k) => `"${k}"`).join(", ")}; pinAt takes { generation, fingerprint } and a pin's \`version\`, which it does not read`
+      );
+    }
+    if (generation === null) {
+      throw new ValidationError5(
+        "pinAt: the pin named no generation (the segment had none when it was pinned), so there is nothing to reopen"
+      );
+    }
+    if (version !== void 0 && typeof version !== "string") {
+      throw new ValidationError5(
+        "pinAt: `version`, when given, is the string a pin recorded in its pinnedAt; pinAt does not read it, so leave it out if you have none"
       );
     }
     if (typeof generation !== "number" || !Number.isSafeInteger(generation) || generation < 0 || typeof fingerprint !== "string" || !/^\d+:\d+$/.test(fingerprint)) {
-      throw new ValidationError4(
+      throw new ValidationError5(
         "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"
       );
     }
@@ -2840,17 +3118,41 @@ var Segment = class _Segment {
     return segmentKey(this.ref);
   }
   /**
-   * Refuse an `*Into` whose handles cannot be read, before any object is written: anything that is not a segment
-   * ({@link ValidationError}), and a handle (this one, `dest` or an operand) whose lease has ended or was released
-   * ({@link LeaseExpiredError}). Called by the three `*Into` verbs only.
+   * Refuse an `*Into` that cannot run, before any request, in this order: anything that is not a segment or is a
+   * segment of another store, an empty operand list for `intersectInto`, and a `dest` that is also a source (all
+   * {@link ValidationError}); then a handle (this one, `dest`, an operand or an exclude) whose lease has ended or was
+   * released ({@link LeaseExpiredError}). A call with both a lapsed lease and one of the first three refusals throws the
+   * first. Called by the three `*Into` verbs only.
    *
    * The verbs are `async` so this surfaces as a **rejected promise**, like every other validation in the facade —
    * a synchronous throw out of a promise-returning method escapes a caller who attached `.catch()` instead of
    * awaiting.
    */
-  assertIntoHandles(dest, operands) {
-    this.assertSegments([dest, ...operands]);
-    this.assertLeases([this, dest, ...operands]);
+  assertIntoHandles(verb, dest, operands, excludes) {
+    this.assertSegments(verb, "the destination", [dest]);
+    this.assertSegments(verb, verb === "andNotInto" ? "an exclude" : "an operand", operands);
+    this.assertSegments(verb, "an exclude", excludes);
+    const base = verb.slice(0, -"Into".length);
+    if (base === "intersect" && operands.length === 0) refuseNoOperands("intersectInto");
+    this.refuseSourceDestination(verb, dest, operands, excludes);
+    this.assertLeases([this, dest, ...operands, ...excludes]);
+  }
+  /**
+   * Refuse an `*Into` whose destination is also one of its sources (this segment, an operand or an exclude, by the key
+   * a handle gives, so a pin of the source and a ref spelled with the default namespace count), before any request, as
+   * `materializeMany` refuses it. The combine would read the destination at the generation this store last resolved,
+   * up to `cache.genTtlMs` old, while the publish is fenced on the row as it stands: another process's newer load of
+   * the destination would be overwritten by a result built from the one before it, with no conflict to report.
+   */
+  refuseSourceDestination(verb, dest, operands, excludes) {
+    const key = dest.key();
+    const role = this.key() === key ? "this segment" : operands.some((o) => o.key() === key) ? verb === "andNotInto" ? "an exclude" : "an operand" : excludes.some((o) => o.key() === key) ? "an exclude" : void 0;
+    if (role === void 0) return;
+    const { namespace, segment } = dest.ref;
+    const named = namespace === void 0 ? segment : `${namespace}/${segment}`;
+    throw new ValidationError5(
+      `${verb}: the destination "${named}" is also ${role} of the call, and a call that reads a segment while it publishes to it can replace a newer load of it with a result built from an older one, with no conflict reported. This release has no fenced in-place update: combine into a new segment and point readers at it`
+    );
   }
   /** `result` as is, or, when a handle of the call holds a lease, checking that lease each time it reads a chunk. */
   guarded(out, handles, result) {
@@ -2953,7 +3255,7 @@ var Segment = class _Segment {
   iterate(options) {
     const lease = this.leaseError();
     if (lease !== void 0) return failing(lease);
-    const bad = optionsError(options, "iterate", CALL_KEYS.range);
+    const bad = optionsError(options, "iterate", CALL_KEYS.range, [], MISPLACED.range);
     if (bad !== void 0) return failing(bad);
     const range = options == null ? void 0 : rangeOf(options);
     const none = range === void 0 || range.after === void 0 && range.through === void 0;
@@ -2963,7 +3265,11 @@ var Segment = class _Segment {
       engine.iterate(ref, bounds),
       () => engine.iterateBatches(ref, bounds)
     );
-    return this.leaseHold === void 0 ? stream : guardIds(stream, () => this.assertLease());
+    return readsFrom(
+      this.leaseHold === void 0 ? stream : guardIds(stream, () => this.assertLease()),
+      this.origin,
+      [this.key()]
+    );
   }
   /**
    * **Pinned handles only.** The ids at 1-based ranks `n`, `2n`, `3n` …, counted over the ids in `(after, through]`
@@ -2998,11 +3304,11 @@ var Segment = class _Segment {
   everyNth(n, options) {
     const lease = this.leaseError();
     if (lease !== void 0) return refusing(lease)();
-    const bad = optionsError(options, "everyNth", CALL_KEYS.range);
+    const bad = optionsError(options, "everyNth", CALL_KEYS.range, [], MISPLACED.range);
     if (bad !== void 0) return refusing(bad)();
     if (this.pinnedAt === void 0) {
       return refusing(
-        new UnsupportedError(
+        new UnsupportedError2(
           "everyNth needs a pinned handle: a live handle can place a rank by one generation and read it from another. Call `pin()` first."
         )
       )();
@@ -3012,7 +3318,11 @@ var Segment = class _Segment {
       n,
       options == null ? void 0 : rangeOf(options)
     );
-    return this.leaseHold === void 0 ? stream : guardIdIterable(stream, () => this.assertLease());
+    return readsFrom(
+      this.leaseHold === void 0 ? stream : guardIdIterable(stream, () => this.assertLease()),
+      this.origin,
+      [this.key()]
+    );
   }
   /**
    * The options a combine hands the engine, read once, when it is called ({@link readOptions}), with the `exclude`
@@ -3048,9 +3358,20 @@ var Segment = class _Segment {
    * requests held ahead per operand: a positive integer, 32 by default).
    * AND is commutative, so `a.intersect([b])` and `b.intersect([a])` yield the same ids. Pass `budget` to
    * override the store's per-op denial-of-wallet budget for this call (or `false` to lift it).
+   *
+   * Of {@link CombineOptions} it takes the range, `concurrency`, `budget`, `allowAbsentOperands` and `exclude`; a write
+   * option (`audit`, `allowEmpty`, `guard`, `metadata`, `keep`) fails the stream with {@link ValidationError} when it is
+   * first read, before any request. So does an empty `others`: an intersection over nothing has no meaning, and
+   * to read every id of one segment, use {@link iterate}. (`union` and `andNot` read an empty list as `this`.)
    */
   intersect(others, options) {
-    const bad = optionsError(options, "intersect", CALL_KEYS.combine, ["allowAbsentOperands"]);
+    const bad = optionsError(
+      options,
+      "intersect",
+      CALL_KEYS.combine,
+      ["allowAbsentOperands"],
+      MISPLACED.combine
+    );
     if (bad !== void 0) return failing(bad);
     return this.combineAs(AS_IDS, "intersect", others, options ?? void 0);
   }
@@ -3073,6 +3394,16 @@ var Segment = class _Segment {
    * materialisation that silently did not take effect is the one thing a caller cannot detect on its own.
    *
    * A call involving a handle whose lease has ended, or anything that is not a segment, is refused before any of this.
+   * So is a `dest` that is also `this`, an operand or an exclude (the same segment by name and namespace, however the
+   * handle was made), and, for `intersectInto` alone, an empty `others` (`unionInto` and `andNotInto` publish `this` for an
+   * empty list): each throws {@link ValidationError} before any request. A destination that
+   * is also a source would publish a result built from the generation this store last resolved over a newer load by
+   * another process, with no conflict to report. This release has no fenced in-place update: write the result into a
+   * new segment and point readers at it; a single writer that knows nothing else writes the segment may load the result
+   * back, unfenced. To copy `src` into `dest`, call
+   * `materializeMany({ operands: { src }, outputs: [{ dest, expr: { or: ['src'] } }], keep })`, which reads each chunk
+   * once, at one instant.
+   * It takes every field of {@link CombineOptions}, as `unionInto` does.
    */
   async intersectInto(dest, others, options) {
     checkOptions(options, "intersectInto", CALL_KEYS.into, ["allowEmpty", "allowAbsentOperands"]);
@@ -3086,10 +3417,17 @@ var Segment = class _Segment {
    * `intersect` prunes any key missing from any operand; union has nothing to prune. It is charged against the
    * same per-op budget, so a wide union is refused rather than quietly billed — pass `budget` to raise it
    * deliberately. If you find yourself unioning the same segments on every read, materializing the combined
-   * segment once (`unionInto`, or a load) is the cheaper shape.
+   * segment once (`unionInto`, or a load) is the cheaper shape. It takes the options {@link intersect} takes, and an
+   * empty `others` reads `this` itself.
    */
   union(others, options) {
-    const bad = optionsError(options, "union", CALL_KEYS.combine, ["allowAbsentOperands"]);
+    const bad = optionsError(
+      options,
+      "union",
+      CALL_KEYS.combine,
+      ["allowAbsentOperands"],
+      MISPLACED.combine
+    );
     if (bad !== void 0) return failing(bad);
     return this.combineAs(AS_IDS, "union", others, options ?? void 0);
   }
@@ -3108,18 +3446,34 @@ var Segment = class _Segment {
    *
    * To filter the *result of an intersection*, do not chain — pass `exclude` to {@link intersect} instead, so
    * the suppression folds into the same pass rather than materializing an intermediate segment first.
+   *
+   * It takes the options {@link intersect} takes but `exclude`, since `excludes` is its subtraction: `exclude` or a write
+   * option fails the stream with {@link ValidationError} when it is first read, before any request.
    */
   andNot(excludes, options) {
-    const bad = optionsError(options, "andNot", CALL_KEYS.andNot, ["allowAbsentOperands"]);
+    const bad = optionsError(
+      options,
+      "andNot",
+      CALL_KEYS.andNot,
+      ["allowAbsentOperands"],
+      MISPLACED.andNot
+    );
     if (bad !== void 0) return failing(bad);
     return this.combineAs(AS_IDS, "andNot", excludes, options ?? void 0);
   }
-  /** Materialize `this \ (excludes…)` as a **new generation of `dest`** — see {@link intersectInto}. */
+  /**
+   * Materialize `this \ (excludes…)` as a **new generation of `dest`** — see {@link intersectInto}. It takes every field
+   * of {@link CombineOptions} but `exclude`, since `excludes` is its subtraction: `exclude` is refused with
+   * {@link ValidationError} before any request.
+   */
   async andNotInto(dest, excludes, options) {
-    checkOptions(options, "andNotInto", CALL_KEYS.andNotInto, [
-      "allowEmpty",
-      "allowAbsentOperands"
-    ]);
+    checkOptions(
+      options,
+      "andNotInto",
+      CALL_KEYS.andNotInto,
+      ["allowEmpty", "allowAbsentOperands"],
+      MISPLACED.andNotInto
+    );
     return this.combineInto("andNotInto", dest, excludes, options);
   }
   /**
@@ -3131,8 +3485,11 @@ var Segment = class _Segment {
     let handles;
     try {
       exclude = verb === "andNot" ? NO_SEGMENTS : this.excludesOf(options);
-      handles = [this, ...segmentList(operands, operandsLabel(verb)), ...exclude];
-      this.assertSegments(handles);
+      const others = segmentList(operands, operandsLabel(verb));
+      if (verb === "intersect" && others.length === 0) refuseNoOperands("intersect");
+      handles = [this, ...others, ...exclude];
+      this.assertSegments(verb, verb === "andNot" ? "an exclude" : "an operand", others);
+      this.assertSegments(verb, "an exclude", exclude);
       this.assertLeases(handles);
     } catch (err) {
       return out.failing(err);
@@ -3143,24 +3500,33 @@ var Segment = class _Segment {
     } catch (err) {
       return out.failing(err);
     }
+    const keys = handles.map((h) => h.key());
+    const known = (result) => out === AS_IDS ? readsFrom(result, this.origin, keys) : result;
     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));
+      return known(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)
+    return known(
+      this.guarded(
+        out,
+        handles,
+        verb === "union" ? out.union(engine, refs, opts) : out.intersect(engine, refs, opts)
+      )
     );
   }
   /** 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);
+    const listed = segmentList(
+      operands,
+      verb === "andNot" ? `${name}: \`excludes\`` : `${name}: \`others\``
+    );
+    const excludes = verb === "andNot" ? NO_SEGMENTS : this.excludesOf(options);
+    const all = excludes.length > 0 ? [...listed, ...excludes] : listed;
+    this.assertIntoHandles(name, dest, listed, excludes);
     this.combineEngine([this, ...all]);
     return this.timed(
       name,
@@ -3175,18 +3541,64 @@ var Segment = class _Segment {
 };
 
 // src/bin/export-segments.ts
+var USAGE = `Usage: export-segments [--help]
+
+Exports every registered segment's current generation from a local-filesystem store to a directory.
+Settings come from the environment:
+
+  CR_EXPORT_ROOT       (required) the LocalFsStorage root, holding storage/ and registry/
+  CR_EXPORT_OUT        (required) the output directory for the dump
+  CR_EXPORT_FORMAT     roaring | ndjson (default: roaring)
+  CR_EXPORT_NAMESPACE  (optional) scope the export to one namespace
+
+Example:
+  CR_EXPORT_ROOT=./.cloudbitmaps CR_EXPORT_OUT=./dump export-segments
+`;
+function answerArgs(args) {
+  const rest = args[0] === "--" ? args.slice(1) : args;
+  if (rest.length === 0) return void 0;
+  if (rest.length === 1 && (rest[0] === "--help" || rest[0] === "-h")) {
+    return { stream: "stdout", text: USAGE, code: 0 };
+  }
+  return {
+    stream: "stderr",
+    text: `export-segments takes no arguments; it reads its settings from the environment
+
+${USAGE}`,
+    code: 2
+  };
+}
+var EXPORT_VARIABLES = [
+  "CR_EXPORT_ROOT",
+  "CR_EXPORT_OUT",
+  "CR_EXPORT_FORMAT",
+  "CR_EXPORT_NAMESPACE"
+];
 function parseConfig(env) {
+  const unknown = Object.keys(env).filter(
+    (name) => name.startsWith("CR_EXPORT_") && !EXPORT_VARIABLES.includes(name)
+  );
+  if (unknown.length > 0) {
+    const which = unknown.length > 1 ? `${unknown.join(", ")} are not settings export-segments takes.` : `${unknown[0]} is not a setting export-segments takes.`;
+    throw new ValidationError6(
+      `${which} It takes ${EXPORT_VARIABLES.join(", ")}; run export-segments --help`
+    );
+  }
   const root = env.CR_EXPORT_ROOT;
   if (root === void 0 || root === "") {
-    throw new ValidationError5("CR_EXPORT_ROOT is required (the local-filesystem storage root)");
+    throw new ValidationError6(
+      "CR_EXPORT_ROOT is not set: the directory that holds the store's storage/ and registry/. export-segments also needs CR_EXPORT_OUT; run export-segments --help"
+    );
   }
   const out = env.CR_EXPORT_OUT;
   if (out === void 0 || out === "") {
-    throw new ValidationError5("CR_EXPORT_OUT is required (the output directory for the dump)");
+    throw new ValidationError6(
+      "CR_EXPORT_OUT is not set: the directory to write the dump to. export-segments also needs CR_EXPORT_ROOT; run export-segments --help"
+    );
   }
   const format = env.CR_EXPORT_FORMAT || "roaring";
   if (format !== "roaring" && format !== "ndjson") {
-    throw new ValidationError5(`CR_EXPORT_FORMAT must be "roaring" or "ndjson"; got ${format}`);
+    throw new ValidationError6(`CR_EXPORT_FORMAT must be "roaring" or "ndjson"; got ${format}`);
   }
   const namespace = env.CR_EXPORT_NAMESPACE || void 0;
   return { root, out, format, namespace };
@@ -3201,7 +3613,7 @@ async function ensureOwnDirectory(out, dir) {
   }
   const found = await lstat(dir);
   const refuse = (why) => {
-    throw new ValidationError5(`the export directory is not one this tool made: ${why}`);
+    throw new ValidationError6(`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");
@@ -3216,7 +3628,7 @@ function fsSink(out) {
     async open(ref, ext) {
       const part = namespacePathPart(ref.namespace);
       if (part.toLowerCase() === MANIFEST_NAME) {
-        throw new ValidationError5(
+        throw new ValidationError6(
           `a namespace named ${MANIFEST_NAME} (in any letter case) cannot be exported to a directory: its folder would be the manifest's path`
         );
       }
@@ -3261,10 +3673,10 @@ async function requireStoreRoot(root) {
   try {
     entries = await readdir(root);
   } catch {
-    throw new ValidationError5("CR_EXPORT_ROOT does not name a directory that can be read");
+    throw new ValidationError6("CR_EXPORT_ROOT does not name a directory that can be read");
   }
   if (entries.length === 0) {
-    throw new ValidationError5(
+    throw new ValidationError6(
       "CR_EXPORT_ROOT is empty: it holds no store (an unmounted volume, or the wrong directory)"
     );
   }
@@ -3280,7 +3692,7 @@ async function main(env = process.env, now = () => Date.now()) {
   const store = new CloudRoaring({ storage });
   const priorManifest = await lstat(join(config.out, MANIFEST_NAME)).catch(() => null);
   if (priorManifest?.isDirectory() === true) {
-    throw new ValidationError5(
+    throw new ValidationError6(
       `${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`
     );
   }
@@ -3326,6 +3738,15 @@ function invokedAsCli() {
   }
 }
 if (invokedAsCli()) {
+  const answer = answerArgs(process.argv.slice(2));
+  if (answer !== void 0) {
+    process[answer.stream].write(answer.text);
+    process.exitCode = answer.code;
+  } else {
+    runCli();
+  }
+}
+function runCli() {
   main().then((manifest) => {
     if (manifest.failed.length > 0) {
       process.stderr.write(
@@ -3341,6 +3762,8 @@ if (invokedAsCli()) {
   });
 }
 export {
+  USAGE,
+  answerArgs,
   fsSink,
   main,
   parseConfig