@cloudbitmaps/roaring 0.18.2 → 0.19.0

package/dist/bin/export-segments.js

@@ -3,7 +3,7 @@
 // src/bin/export-segments.ts
 import { randomUUID } from "node:crypto";
 import { realpathSync } from "node:fs";
-import { lstat, mkdir, open, rename, rm, writeFile } from "node:fs/promises";
+import { lstat, mkdir, open, readdir, rename, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { encodeNameForPath, namespacePathPart } from "@cloudbitmaps/core/driver-kit";
@@ -28,7 +28,6 @@ import {
   UnsupportedError,
   ValidationError as ValidationError2,
   WriteConflictError,
-  MIN_EXPIRES_AT_MS,
   checkBudget,
   collectWithinBudget,
   excludingReservedRows,
@@ -36,16 +35,15 @@ import {
   eraseIdFromSegment,
   estimateCost,
   groundedReport,
+  judgeLoad,
   loadSegment,
   loadSegmentChunks,
   compileCombineMany,
-  prepareHeld,
   rebindCombineMany,
   runCombineMany,
   mapWithConcurrency,
   resolveBudget,
   resolvePerOpBudget,
-  reapRegistryTombstones,
   retireExpired,
   runConsistencyCheck,
   runExport,
@@ -620,7 +618,7 @@ import {
   eraseNamespace,
   excludingReservedRows as excludingReservedRows2,
   readRetentionPolicy,
-  MIN_EXPIRES_AT_MS as MIN_EXPIRES_AT_MS2,
+  MIN_EXPIRES_AT_MS,
   LEASE_SKEW_MS as LEASE_SKEW_MS2,
   MAX_LEASE_MS as MAX_LEASE_MS2,
   MAX_LEASES_PER_SEGMENT,
@@ -649,6 +647,10 @@ import {
   isLeaseExpiredError,
   isLeaseLimitError,
   isStaleOperandError,
+  isUnsupportedError,
+  isCapabilityError,
+  isBudgetExceededError,
+  isKeyUnavailableError,
   CrbmReader,
   BufferReader,
   CountingMetricsSink,
@@ -672,6 +674,14 @@ function validateConcurrency(concurrency) {
   }
 }
 function requireScope(options, op) {
+  if (options.namespace !== void 0) {
+    if (typeof options.namespace !== "string") {
+      throw new ValidationError2(
+        `${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 ValidationError2(
@@ -679,9 +689,154 @@ function requireScope(options, op) {
     );
   }
 }
+var keysOf = () => (keys) => keys;
+var CALL_KEYS = {
+  range: keysOf()(["after", "through"]),
+  andNot: keysOf()([
+    "after",
+    "through",
+    "concurrency",
+    "budget",
+    "allowAbsentOperands"
+  ]),
+  combine: keysOf()([
+    "after",
+    "through",
+    "concurrency",
+    "budget",
+    "allowAbsentOperands",
+    "exclude"
+  ]),
+  into: keysOf()([
+    "after",
+    "through",
+    "concurrency",
+    "budget",
+    "allowAbsentOperands",
+    "exclude",
+    "audit",
+    "allowEmpty",
+    "guard",
+    "metadata",
+    "keep"
+  ]),
+  andNotInto: keysOf()([
+    "after",
+    "through",
+    "concurrency",
+    "budget",
+    "allowAbsentOperands",
+    "audit",
+    "allowEmpty",
+    "guard",
+    "metadata",
+    "keep"
+  ]),
+  load: keysOf()(["allowEmpty", "guard", "keep", "metadata", "audit"]),
+  segments: keysOf()(["namespace"]),
+  subjectReport: keysOf()([
+    "namespace",
+    "allNamespaces",
+    "concurrency",
+    "budget"
+  ]),
+  eraseSubject: keysOf()([
+    "namespace",
+    "allNamespaces",
+    "audit",
+    "concurrency",
+    "budget"
+  ]),
+  rollback: keysOf()([
+    "audit",
+    "allowForward"
+  ]),
+  dropSegment: keysOf()([
+    "confirmSegment",
+    "dryRun",
+    "audit"
+  ]),
+  retireExpired: keysOf()([
+    "namespace",
+    "now",
+    "limit",
+    "dryRun",
+    "audit",
+    "maxScanSegments",
+    "scan",
+    "shards",
+    "totalShards",
+    "lookbackBuckets",
+    "purgeTombstones",
+    "tombstoneGraceMs"
+  ]),
+  checkConsistency: keysOf()([
+    "namespace",
+    "concurrency",
+    "summaries"
+  ]),
+  exportSegments: keysOf()(["format", "codec", "namespace", "ndjsonBatchBytes"]),
+  costReport: keysOf()(["pricing", "workload"]),
+  workload: keysOf()([
+    "readsPerSec",
+    "intersectsPerSec",
+    "cacheHitRate",
+    "chunksPerIntersect",
+    "operandsPerIntersect",
+    "loadsPerMonth",
+    "requestsPerLoad",
+    "hotSegments",
+    "readerProcesses",
+    "genTtlMs",
+    "retirementsPerMonth",
+    "purgesPerMonth",
+    "conditionalDelete"
+  ])
+};
+var kindOf = (v) => v === null ? "null" : Array.isArray(v) ? "an array" : `a ${typeof v}`;
+function optionsError(options, op, known, booleans = []) {
+  if (options === void 0 || options === null) return void 0;
+  if (typeof options !== "object" || Array.isArray(options)) {
+    return new ValidationError2(`${op}: options must be an object; got ${kindOf(options)}`);
+  }
+  const bag = options;
+  const unknown = Object.keys(bag).filter((k) => !known.includes(k) && bag[k] !== void 0);
+  if (unknown.length > 0) {
+    return new ValidationError2(
+      `${op}: unknown option${unknown.length > 1 ? "s" : ""} ${unknown.map((k) => `"${k}"`).join(", ")}; it takes { ${known.join(", ")} }`
+    );
+  }
+  const audit = bag.audit;
+  if (audit !== void 0 && audit !== null && typeof audit.onEvent !== "function") {
+    return new ValidationError2(
+      `${op}: audit must be a sink with an onEvent(event) method, such as a RecordingAuditSink`
+    );
+  }
+  for (const name of booleans) {
+    const v = bag[name];
+    if (v !== void 0 && typeof v !== "boolean") {
+      return new ValidationError2(`${op}: \`${name}\` must be a boolean; got ${kindOf(v)}`);
+    }
+  }
+  return void 0;
+}
+function picked(options, keys) {
+  const out = {};
+  if (options === void 0 || options === null) return out;
+  for (const key of keys) {
+    const value = options[key];
+    if (value !== void 0) out[key] = value;
+  }
+  return out;
+}
+function checkOptions(options, op, known, booleans) {
+  const err = optionsError(options, op, known, booleans);
+  if (err !== void 0) throw err;
+}
 var viewOf;
 var MATERIALIZE_MANY_KEYS = [
   "operands",
+  "dryRun",
   "outputs",
   "keep",
   "pin",
@@ -870,8 +1025,29 @@ var CloudRoaring = class _CloudRoaring {
       ).join(" ") + " https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/api-reference.md#build-a-store--new-cloudroaringoptions"
     );
   }
+  /**
+   * A seam the store calls through must have the methods it calls. Without this a `clock` with no `now`, an `rng` with
+   * no `next` or a keystore with no `createDek` builds a store that throws a raw `TypeError` at its first load or read.
+   */
+  static rejectHollowSeams(options) {
+    const seams = [
+      [options.seams?.clock, "seams.clock", ["now", "sleep"]],
+      [options.seams?.rng, "seams.rng", ["next"]],
+      [options.encryption?.keystore, "encryption.keystore", ["createDek", "openDek"]]
+    ];
+    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 ValidationError2(
+          `CloudRoaring's \`${name}\` must be an object with ${needs.map((m) => `\`${m}()\``).join(" and ")}`
+        );
+      }
+    }
+  }
   constructor(options) {
     _CloudRoaring.rejectUnknownOptions(options);
+    _CloudRoaring.rejectHollowSeams(options);
     const clock = options.seams?.clock ?? new SystemClock();
     const rng = options.seams?.rng ?? new SystemRng();
     const metrics = safeMetrics(options.metrics ?? NOOP_METRICS);
@@ -887,6 +1063,9 @@ var CloudRoaring = class _CloudRoaring {
     let storage = resolved.source;
     if (options.retry !== false) {
       const { onRetry: userOnRetry, ...ov } = options.retry ?? {};
+      if (userOnRetry !== void 0 && typeof userOnRetry !== "function") {
+        throw new ValidationError2("retry.onRetry must be a function");
+      }
       const policy = {
         maxAttempts: ov.maxAttempts ?? DEFAULT_RETRY_POLICY.maxAttempts,
         baseDelayMs: ov.baseDelayMs ?? DEFAULT_RETRY_POLICY.baseDelayMs,
@@ -962,28 +1141,43 @@ var CloudRoaring = class _CloudRoaring {
       readRetry: this.retryOptions
     };
   }
-  /** Get a handle to a segment. Validates the name (non-empty, well-formed, within the encoded-length cap). */
+  /**
+   * Get a handle to a segment. Validates the name (non-empty, well-formed, within the encoded-length cap). The options
+   * are `{ namespace }` and nothing else: anything else is refused with {@link ValidationError}, by name, since a
+   * misspelt `namespace` would otherwise address the default namespace. An `expiresAt` among them is refused with its own
+   * message: a handle carries no deadline, and one left unread would serve the data past it. A key whose value is
+   * `undefined` is read as absent, so a spread of options keeps working.
+   */
   segment(name, options) {
-    const ref = { segment: name, namespace: options?.namespace };
-    validateSegmentRef(ref);
-    refuseReservedNamespace(ref.namespace);
-    const expiresAt = options?.expiresAt;
-    if (expiresAt !== void 0) {
-      if (!Number.isFinite(expiresAt) || !Number.isInteger(expiresAt) || expiresAt < MIN_EXPIRES_AT_MS) {
+    if (options !== void 0 && options !== null) {
+      if (typeof options !== "object" || Array.isArray(options)) {
+        throw new ValidationError2("segment: options must be an object such as { namespace }");
+      }
+      if (options.expiresAt !== void 0) {
+        throw new ValidationError2(
+          "segment: `expiresAt` is not an option of a handle; check a deadline where you read, or record it with `store.setRetention(ref, { expiresAt })` and run `store.retireExpired()`"
+        );
+      }
+      const unknown = Object.keys(options).filter(
+        (k) => k !== "namespace" && options[k] !== void 0
+      );
+      if (unknown.length > 0) {
         throw new ValidationError2(
-          `segment: expiresAt must be an integer epoch-MILLISECONDS >= ${MIN_EXPIRES_AT_MS}; got ${expiresAt} (a value in seconds lands in 1970 and would make the segment read as permanently empty)`
+          `segment: unknown option${unknown.length > 1 ? "s" : ""} ${unknown.map((k) => `"${k}"`).join(", ")}; a handle takes { namespace } only`
         );
       }
     }
+    const ref = { segment: name, namespace: options?.namespace };
+    validateSegmentRef(ref);
+    refuseReservedNamespace(ref.namespace);
     return makeSegment({
       engine: this.engine,
       ref,
       clock: this.clock,
       metrics: this.metrics,
       materialize: (dest, ids, op, options2) => this.materialize(dest, ids, op, options2),
-      pinned: (r, e, l, at) => this.pinSegment(r, e, l, at),
-      combineEngine: (handles) => this.engineForCombine(handles),
-      expiresAt
+      pinned: (r, l, at) => this.pinSegment(r, l, at),
+      combineEngine: (handles) => this.engineForCombine(handles)
     });
   }
   /**
@@ -991,7 +1185,7 @@ var CloudRoaring = class _CloudRoaring {
    * materialisation is a load, and publishes the same way (hard invariant 1): every load that finds a row fences its
    * publish on the row's token; a guarded load (the default, since the empty refusal needs the size of the current generation)
    * also fences on the pointer it judged (`expectFrom`), and one that found no row fences on that absence instead.
-   * Only an unguarded load (`allowEmpty: true` and no `guard.minRetained`) onto a segment with no row publishes bare
+   * Only an unguarded load (`allowEmpty: true`, with neither `guard.minRetained` nor `guard.maxGrowth`) onto a segment with no row publishes bare
    * forward-only. The destination's previous generation stays readable until the publish lands (readers re-resolve
    * within `cache.genTtlMs`).
    *
@@ -1067,131 +1261,7 @@ var CloudRoaring = class _CloudRoaring {
       collected: result.collected
     };
   }
-  /**
-   * **Hold a set of ids in memory**, to be an operand of {@link CloudRoaring.materializeMany} and of no other verb.
-   *
-   * ```ts
-   * const vip = await store.memory([7, 42, 99_001]);
-   * await store.materializeMany({ operands: { vip, engaged: store.segment('cond-engaged') }, outputs: [...], keep: 12 });
-   * vip.release();
-   * ```
-   *
-   * It takes what {@link CloudRoaring.load} takes as input (ids as a sync or async iterable or a typed array, `{ bitmap }`
-   * or `{ serialized }`) and checks it the same way, with the same errors: the size cap, the structure, the safe
-   * deserializer and each id's range. **Only a real `Uint32Array` skips the per-id range check**; any other typed array goes
-   * through it, so `Int32Array([-1])` and `Float64Array([1.5])` throw {@link ValidationError}. An object with an `ascending`
-   * key is refused: ids that arrive in key order are a `feed`. An empty set is accepted here, and refused by
-   * `materializeMany` unless its name is in `mayBeEmpty`.
-   *
-   * The ids are held as the chunks a stored generation would hold, until {@link MemoryOperand.release}; between calls that
-   * memory is the caller's, and during a call it counts against `maxBufferedBytes`. There is no size option: the load's
-   * own cap applies to a serialized input.
-   *
-   * **Erasure.** Only `eraseSubject` moves the store's counter (at its start and at its end). One that started in this store
-   * since the handle began to be made, or is still running, makes a call that reads the handle fail the outputs that read it with
-   * {@link StaleOperandError} (`reason: 'erased'`), before any request and again just before each publish. An erasure in
-   * another store or another process is not seen, nor are `dropSegment`, `eraseNamespace`, `destroySegment` and the free
-   * function `eraseIdFromSegment`, which do not move it: the handle is the caller's copy, so build it from the source of truth at
-   * the start of each refresh and release it at the end.
-   *
-   * @throws {ValidationError} where a load of the same input would.
-   */
-  async memory(input) {
-    const epochAt = this.epochNow();
-    const chunks = await prepareHeld(input, roaringCodec, this.clock);
-    return makeMemoryOperand({ store: this, chunks, epochAt });
-  }
-  /**
-   * **Many outputs, each operand read once per group.** Each output is an expression over named stored operands (`and`, `or`, `andNot`, nested
-   * to depth 64) published as a new generation of its own `dest`, exactly as an `*Into` would publish it, but computed
-   * together: each operand's chunks are read once for all the outputs that use them, instead of once per output and
-   * once more for every scratch segment a nested expression would otherwise need.
-   *
-   * ```ts
-   * const run = await store.materializeMany({
-   *   operands: { us: store.segment('us'), engaged: store.segment('engaged'), optOut: store.segment('opt-out') },
-   *   outputs: [
-   *     { dest: store.segment('send-1'), expr: { and: ['us', 'engaged'] }, exclude: ['optOut'] },
-   *     { dest: store.segment('send-2'), expr: { andNot: ['us', 'engaged'] } },
-   *   ],
-   *   keep: 3,
-   * });
-   * run.outputs[0]; // a MaterializeResult, or { published: false, error }
-   * ```
-   *
-   * **Results.** `run.outputs[i]` is index-aligned with `outputs` and is exactly what output `i`'s `*Into` would have
-   * returned (a {@link MaterializeResult}: published, or refused with its `reason`), or `{ published: false, error }` for
-   * what it would have thrown. One output's refusal or error never stops another. The call itself throws only for bad
-   * input ({@link ValidationError} naming the output index and path, before any request), an operand that names no
-   * segment (unless `allowAbsentOperands`), and a `budget` its own plan exceeds, the last two before any chunk is read.
-   *
-   * **One generation per operand.** By default every stored operand is pinned for the call: read at the generation it had
-   * when the call started, however long the call runs and whatever loads land meanwhile. That is one generation per
-   * operand, not one instant across operands (two pins are two registry reads). `pin: false` reads live, as a combine does.
-   *
-   * **Every pinned operand an output subtracts is re-checked.** An output subtracts an operand when it is in its `exclude`
-   * or under any entry of an `andNot` after the first, at any depth. Immediately before the publishes the call re-reads the
-   * registry row of each such operand and compares its generation and incarnation, and the fingerprint of the current
-   * object where both reads carry one, with what was pinned (a name deleted and created again is a replacement though it
-   * is generation 0 again). If one was replaced, each output that subtracts it is
-   * not published and carries {@link StaleOperandError}; the others publish. It costs one registry read per such operand per
-   * group, and `stats.operands` carries every operand's pinned, start and end generation and whether it moved.
-   *
-   * **Memory.** Everything the pass holds resident is counted against `maxBufferedBytes` (default 256 MiB): each output's
-   * buffered chunks, the operand streams' ranges, the chunks being evaluated, and the plan itself, and a call whose plan alone
-   * passes it is refused before any chunk is read. When the outputs do not fit, they run in groups, each reading its operands
-   * once (so the operand reads grow with the total output size over the budget), and a group's buffers are released only as
-   * its publishes settle. A chunk count the index understated does not grow a group past the budget: the largest buffer is
-   * dropped and that output re-runs alone. An output that cannot fit alone has `BudgetExceededError` as its result. The count
-   * is the pass's own: process memory is more, measured at 1.6 times the ledger's high water on Linux and 2.5 to 5 times on
-   * macOS on the in-memory backend (the guide has the shapes and what is not counted).
-   *
-   * **Untrusted bytes.** Every operand chunk is decoded through the checks on untrusted tier data. A key an operand's index
-   * lists whose bytes are missing is an error for the outputs that read the operand, never an empty chunk.
-   *
-   * **Handles.** An expired or released handle anywhere in the call (an operand or a `dest`) is refused before any request,
-   * as on the `*Into` verbs. A leased operand's lease, and an operand's deadline, are checked before each chunk key
-   * is read: a lapse fails only the outputs that read that operand, never reads empty. Each `dest`'s lease and deadline
-   * are checked again just before its publish.
-   *
-   * **The chunk cache is bypassed:** the pass reads through the storage source and never writes the decoded-chunk cache, so
-   * a batch does not evict other readers' hot chunks. Each publish still invalidates its `dest` as an `*Into` does.
-   *
-   * **A limit of the form.** An output cannot name another output of the same call: a `dest` that is also an operand is
-   * refused. Chain two calls.
-   *
-   * **Held operands.** An operand may be a {@link MemoryOperand} from {@link CloudRoaring.memory}: ids the caller holds,
-   * read beside the stored ones and giving the same output byte for byte. It is read from memory (no request, and the
-   * shared chunk cache never sees it), counts against `maxBufferedBytes` while the call runs, and is refused when empty
-   * unless its name is in `mayBeEmpty`. A handle from another store, or a released one, is a {@link ValidationError}. An
-   * erasure in this store since the handle was made fails the outputs that read it with {@link StaleOperandError}
-   * (`reason: 'erased'`).
-   *
-   * **A feed.** `feed: { names, records, counts }` adds operands that arrive as records in chunk-key order, for conditions
-   * too many to hold or store. Each record is checked before the pass sees it (see {@link MaterializeManyFeedRecord}): a bad
-   * feed is refused, never read as fewer members, and **a fed output is published only after the whole feed was read and every
-   * end-of-feed check passed**, so a bad feed refuses every fed output and publishes none of them; outputs that name only
-   * stored operands are unaffected. At the end of the feed `counts` must equal the ids the feed held for each name, and a
-   * name that appeared in no record is refused unless it is in `mayBeEmpty`. A feed is read once, so the call runs its outputs
-   * as one group and **`maxBufferedBytes` is required**: each record is converted to compressed bitmaps as it arrives, the key
-   * in hand and its fed outputs are counted against the budget, and the call fails as soon as the count passes it, with
-   * {@link BudgetExceededError} for every fed output. **Erasure:** a fed call is refused at its next record, and before each
-   * fed publish, once `eraseSubject` has started in this store ({@link StaleOperandError}, `reason: 'erased'`).
-   *
-   * ```ts
-   * await store.materializeMany({
-   *   operands: { unsub: store.segment('global-unsub') },
-   *   feed: {
-   *     names: ['us', 'engaged'],
-   *     records: warehouseRecords(), // yields { key, operands: { us: Uint32Array, engaged: Uint32Array } } by key
-   *     counts: () => warehouseCounts(),
-   *   },
-   *   maxBufferedBytes: 512 * 1024 * 1024,
-   *   outputs: [{ dest: store.segment('send-1'), expr: { and: ['us', 'engaged'] }, exclude: ['unsub'] }],
-   *   keep: 12,
-   * });
-   * ```
-   */
+  /** The one body of the forms above. */
   async materializeMany(options) {
     if (typeof options !== "object" || options === null) {
       throw new ValidationError2(
@@ -1207,12 +1277,17 @@ var CloudRoaring = class _CloudRoaring {
         `materializeMany: unknown option${unknown.length > 1 ? "s" : ""} ${unknown.map((k) => `"${k}"`).join(", ")}`
       );
     }
+    const dryRunIn = options.dryRun;
+    if (dryRunIn !== void 0 && typeof dryRunIn !== "boolean") {
+      throw new ValidationError2("materializeMany: dryRun must be a boolean");
+    }
+    const dryRun = dryRunIn === true;
     const operandsIn = options.operands;
     const outputsIn = options.outputs;
     const keep = options.keep;
     const after = options.after;
     const through = options.through;
-    const pinOption = options.pin ?? true;
+    const pinOption = options.pin === void 0 ? true : options.pin;
     const feedIn = options.feed;
     const mayBeEmptyIn = options.mayBeEmpty;
     if (feedIn !== void 0 && options.maxBufferedBytes === void 0) {
@@ -1238,50 +1313,26 @@ var CloudRoaring = class _CloudRoaring {
     }
     const names = Object.keys(operandsIn);
     const handles = /* @__PURE__ */ new Map();
-    const heldHandles = /* @__PURE__ */ new Map();
     for (const name of names) {
       const handle = operandsIn[name];
-      if (handle instanceof MemoryOperand) {
-        const view = heldOf(handle);
-        if (view === void 0) {
-          throw new ValidationError2(
-            `materializeMany: operands["${name}"] is not a memory operand from store.memory()`
-          );
-        }
-        if (view.store !== this) {
-          throw new ValidationError2(
-            `materializeMany: operands["${name}"] was made by another store: a memory operand belongs to the store that made it`
-          );
-        }
-        if (view.chunks.released) {
-          throw new ValidationError2(
-            `materializeMany: operands["${name}"] was released: make another with store.memory()`
-          );
-        }
-        heldHandles.set(name, view);
-        continue;
-      }
       if (!(handle instanceof Segment)) {
         throw new ValidationError2(
-          `materializeMany: operands["${name}"] must be a segment from store.segment() or a memory operand from store.memory()`
+          `materializeMany: operands["${name}"] must be a segment from store.segment()`
         );
       }
       handles.set(name, handle);
     }
-    const heldMayBeEmpty = /* @__PURE__ */ new Set();
-    let fedMayBeEmpty = mayBeEmptyIn;
-    if (mayBeEmptyIn !== void 0) {
-      if (Array.isArray(mayBeEmptyIn)) {
-        const rest = [];
-        for (const name of mayBeEmptyIn) {
-          if (typeof name === "string" && heldHandles.has(name)) heldMayBeEmpty.add(name);
-          else rest.push(name);
-        }
-        fedMayBeEmpty = rest;
+    if (mayBeEmptyIn !== void 0 && feedIn === void 0) {
+      if (!Array.isArray(mayBeEmptyIn)) {
+        throw new ValidationError2(
+          "materializeMany: mayBeEmpty must be an array of fed operand names"
+        );
       }
-      if (feedIn === void 0 && (!Array.isArray(fedMayBeEmpty) || fedMayBeEmpty.length > 0)) {
+      if (mayBeEmptyIn.length > 0) {
+        const first = mayBeEmptyIn[0];
+        const what = typeof first !== "string" ? "something that is not a name" : handles.has(first) ? `"${first}", a stored operand` : `"${first}", which is not an operand of this call`;
         throw new ValidationError2(
-          "materializeMany: mayBeEmpty names fed operands, and the call has no feed"
+          `materializeMany: mayBeEmpty names ${what}; it names fed operands, and this call has no feed`
         );
       }
     }
@@ -1321,26 +1372,13 @@ var CloudRoaring = class _CloudRoaring {
     const storeCeiling = this.budget === null || this.budget.maxRequests !== DEFAULT_BUDGET.maxRequests ? this.budget : void 0;
     const budget = budgetOption === void 0 ? storeCeiling : resolvePerOpBudget(budgetOption, this.budget);
     const operandSpecs = (pins2) => names.map((name) => {
-      const view = heldHandles.get(name);
-      if (view !== void 0) {
-        return {
-          name,
-          ref: { segment: name },
-          held: {
-            chunks: view.chunks,
-            moved: () => this.epochMoved(view.epochAt),
-            mayBeEmpty: heldMayBeEmpty.has(name)
-          }
-        };
-      }
       const handle = handles.get(name);
       const seg = viewOf(handle);
       const pinnedAt = pins2.get(handle.key());
-      const guarded = seg.expiresAt !== void 0 || handle.lease !== void 0;
       return {
         name,
         ref: seg.ref,
-        ...guarded ? { check: () => this.assertReadable("materializeMany", handle) } : {},
+        ...handle.lease === void 0 ? {} : { check: () => this.assertLease(handle) },
         ...pinnedAt === void 0 ? {} : {
           pinnedGeneration: pinnedAt.generation,
           pinnedVersion: pinnedAt.version,
@@ -1351,18 +1389,18 @@ var CloudRoaring = class _CloudRoaring {
     });
     const request = (pins2) => ({
       operands: operandSpecs(pins2),
-      outputs: outputs.map(({ spec, dest }, i) => ({
+      outputs: outputs.map(({ spec, dest }) => ({
         expr: spec.expr,
         ...spec.exclude === void 0 ? {} : { exclude: spec.exclude },
         ...spec.allowEmpty === void 0 ? {} : { allowEmpty: spec.allowEmpty },
         ...spec.guard === void 0 ? {} : { guard: spec.guard },
         ...spec.metadata === void 0 ? {} : { metadata: spec.metadata },
         ...spec.keep === void 0 ? {} : { keep: spec.keep },
-        beforePublish: () => this.assertWritable(`outputs[${i}]`, dest),
+        beforePublish: () => this.assertLease(dest),
         // What a settled publish proves it sent: a published one wrote its object and moved the pointer, a refused one
-        // wrote its object and deleted it.
-        requestsOf: (result) => ({ get: 0, put: result.published ? 2 : 1 }),
-        publish: (chunks, write) => this.materialize(viewOf(dest).ref, new CombineChunks(chunks), "materializeMany", {
+        // wrote its object and deleted it. A dry run's judgement wrote nothing, and read the row and maybe the object.
+        requestsOf: (result) => "dryRun" in result ? { get: result.reads, put: 0 } : { get: 0, put: result.published ? 2 : 1 },
+        publish: (chunks, write) => dryRun ? this.judgeOutput(viewOf(dest).ref, chunks, write) : this.materialize(viewOf(dest).ref, new CombineChunks(chunks), "materializeMany", {
           ...write,
           ...spec.audit === void 0 ? {} : { audit: spec.audit }
         })
@@ -1375,11 +1413,12 @@ var CloudRoaring = class _CloudRoaring {
       concurrency,
       ...budget === void 0 ? {} : { budget },
       ...allowAbsentOperands === void 0 ? {} : { allowAbsentOperands },
-      ...feedIn === void 0 ? {} : { feed: this.feedOf(feedIn, fedMayBeEmpty, epochAt) }
+      ...feedIn === void 0 ? {} : { feed: this.feedOf(feedIn, mayBeEmptyIn, epochAt) },
+      ...dryRun ? { dryRun: true } : {}
     });
     const compiled = compileCombineMany(request(/* @__PURE__ */ new Map()));
-    for (const { dest } of outputs) this.assertWritable("materializeMany", dest);
-    for (const handle of handles.values()) this.assertReadable("materializeMany", handle);
+    for (const { dest } of outputs) this.assertLease(dest);
+    for (const handle of handles.values()) this.assertLease(handle);
     this.lifecycleDeps("materializeMany");
     const crbm = this.crbmSource;
     if (crbm === void 0) {
@@ -1416,25 +1455,64 @@ var CloudRoaring = class _CloudRoaring {
       else if (pinOption) toPin.push([key, handle]);
       else pins.set(key, void 0);
     }
-    const taken = await mapWithConcurrency(
-      toPin,
-      PIN_PARALLELISM,
-      async ([key, handle]) => [key, (await handle.pin()).pinnedAt]
-    );
-    for (const [key, at] of taken) pins.set(key, at);
-    const live = new Map([...pins].filter((e) => e[1] !== void 0));
-    const pinnedSource = new PinnedStorageChunkSource(crbm, live);
-    const source = this.retryOptions === void 0 ? pinnedSource : new RetryingStorageChunkSource(pinnedSource, this.retryOptions);
-    const final = rebindCombineMany(compiled, operandSpecs(pins));
-    const run = await runCombineMany(final, { source, codec: roaringCodec, clock: this.clock });
-    return {
-      outputs: run.outputs.map(
-        (o) => o.ok ? o.value : {
+    const metricsOn = this.metrics !== NOOP_METRICS;
+    const work = async () => {
+      const taken = await mapWithConcurrency(
+        toPin,
+        PIN_PARALLELISM,
+        async ([key, handle]) => [key, (await handle.pin()).pinnedAt]
+      );
+      for (const [key, at] of taken) pins.set(key, at);
+      const live = new Map([...pins].filter((e) => e[1] !== void 0));
+      const pinnedSource = new PinnedStorageChunkSource(crbm, live);
+      const source = this.retryOptions === void 0 ? pinnedSource : new RetryingStorageChunkSource(pinnedSource, this.retryOptions);
+      const final = rebindCombineMany(compiled, operandSpecs(pins));
+      return runCombineMany(final, {
+        source,
+        codec: roaringCodec,
+        clock: this.clock,
+        ...metricsOn ? { metrics: this.metrics } : {}
+      });
+    };
+    const run = metricsOn ? await timeOp(this.metrics, this.clock, "materializeMany", work) : await work();
+    const results = run.outputs.map((o) => {
+      if (!o.ok) {
+        return {
           published: false,
           error: o.error instanceof Error ? o.error : new Error(String(o.error))
-        }
-      ),
-      stats: run.stats
+        };
+      }
+      if (!("dryRun" in o.value)) return o.value;
+      const v = o.value;
+      const judged = {
+        dryRun: true,
+        published: false,
+        cardinality: v.cardinality,
+        cardinalityBefore: v.cardinalityBefore,
+        ...v.wouldRefuse === void 0 ? {} : { wouldRefuse: v.wouldRefuse }
+      };
+      return judged;
+    });
+    return dryRun ? { outputs: results, stats: run.stats } : { outputs: results, stats: run.stats };
+  }
+  /**
+   * A dry run's publish of one output: count what the finished chunks hold, and judge that size against `dest` as a
+   * load would, writing nothing.
+   */
+  async judgeOutput(dest, chunks, write) {
+    let cardinality = 0;
+    for await (const chunk of chunks) cardinality += chunk.bitmap.size;
+    const judged = await judgeLoad(dest, cardinality, this.lifecycleDeps("materializeMany"), {
+      ...write.allowEmpty === void 0 ? {} : { allowEmpty: write.allowEmpty },
+      ...write.guard === void 0 ? {} : { guard: write.guard }
+    });
+    return {
+      dryRun: true,
+      published: false,
+      cardinality,
+      cardinalityBefore: judged.cardinalityBefore,
+      ...judged.wouldRefuse === void 0 ? {} : { wouldRefuse: judged.wouldRefuse },
+      reads: judged.reads
     };
   }
   epochNow() {
@@ -1487,20 +1565,10 @@ var CloudRoaring = class _CloudRoaring {
     const row = await this.withRetries(() => registry.get(ref));
     return row === null ? null : { generation: row.currentGen, token: row.token };
   }
-  /** Throw what a read of `handle` must throw now: its lease error, or a refusal for a deadline that has passed. */
-  assertReadable(op, handle) {
-    const view = viewOf(handle);
-    const lease = view.leaseError();
+  /** Throw what a read of, or a publish to, `handle` must throw now: its lease error, if it has one. */
+  assertLease(handle) {
+    const lease = viewOf(handle).leaseError();
     if (lease !== void 0) throw lease;
-    if (view.expired()) {
-      throw new ValidationError2(
-        `${op}: refusing to read "${view.ref.segment}", whose handle has expired \u2014 an expired handle reads as empty, so a generation built from it would be short. Open the handle without \`expiresAt\` if you meant to materialise.`
-      );
-    }
-  }
-  /** {@link assertReadable} for a destination, named by where it sits in the call. */
-  assertWritable(where, dest) {
-    this.assertReadable(where, dest);
   }
   /**
    * **Subject access (GDPR Art. 15 / CCPA right-to-know): which segments is this id a member of?**
@@ -1518,6 +1586,8 @@ var CloudRoaring = class _CloudRoaring {
    * generation 0 while this store held its old generation 0 is told apart too.
    */
   async subjectReport(id, options = {}) {
+    checkOptions(options, "subjectReport", CALL_KEYS.subjectReport, ["allNamespaces"]);
+    options ??= {};
     const registry = this.requireRegistry("subjectReport");
     requireScope(options, "subjectReport");
     validateConcurrency(options.concurrency);
@@ -1581,8 +1651,9 @@ var CloudRoaring = class _CloudRoaring {
    * every generation below its new pointer — the one this rewrite is streaming, and the object this rewrite
    * just wrote — so the loser can find its own inputs deleted mid-flight. That surfaces as an outcome rather than
    * an error, read off the row: a moved pointer is a `'superseded'` entry, which a re-run settles, and a segment
-   * that a concurrent `dropSegment` tombstoned or a retention sweep purged is left out of the ledger, as a fresh
-   * call would leave it out.
+   * that a concurrent `dropSegment` tombstoned or a retention sweep purged is left out of the ledger. A tombstoned
+   * segment is still searched: a cleartext object left under it that holds the id is deleted, with everything under
+   * the tombstone, and the entry reads `erased: true`.
    *
    * **Read `note` on any `erased: false` entry — the two reasons mean different things.** `'superseded'` means
    * another writer (a load, another erasure, or a rollback) moved the pointer mid-call, so **this call** did not
@@ -1611,6 +1682,8 @@ var CloudRoaring = class _CloudRoaring {
    */
   async eraseSubject(id, options = {}) {
     this.erasureEpoch++;
+    checkOptions(options, "eraseSubject", CALL_KEYS.eraseSubject, ["allNamespaces"]);
+    options ??= {};
     this.erasuresRunning++;
     try {
       return await this.eraseSubjectRun(id, options);
@@ -1639,7 +1712,6 @@ var CloudRoaring = class _CloudRoaring {
       recs,
       options.concurrency ?? DEFAULT_ADMIN_CONCURRENCY,
       async (rec) => {
-        if (rec.status === "destroyed") return null;
         const ref = { segment: rec.segment, namespace: rec.namespace };
         try {
           const result = await eraseIdFromSegment(
@@ -1703,10 +1775,9 @@ var CloudRoaring = class _CloudRoaring {
    * exists. It is `false` for a segment whose row was minted ahead of its first load (by `setRetention`) and
    * for a `destroyed` tombstone, because a read answers empty in both cases.
    *
-   * Two states answer `true` where a read still gives you nothing: a torn restore (a live pointer whose object
+   * One state answers `true` where a read still gives you nothing: a torn restore (a live pointer whose object
    * was deleted) makes reads of the object *throw* rather than answer empty, while a cold `count()` answers the number
-   * its row records — `checkConsistency` is the call for that — and
-   * a handle carrying an expired `expiresAt` reads empty by a rule that lives on the handle, not the row.
+   * its row records — `checkConsistency` is the call for that.
    *
    * Not a lock: the answer can change the moment it returns. If it has to hold, use the fence built for that —
    * `load`'s `guard`, or `expectFrom`/`expectToken` on a publish. Needs a storage backend.
@@ -1749,6 +1820,8 @@ var CloudRoaring = class _CloudRoaring {
    * ```
    */
   segments(options = {}) {
+    checkOptions(options, "segments", CALL_KEYS.segments);
+    options ??= {};
     if (options.namespace !== void 0) {
       validateSegmentRef({ segment: "x", namespace: options.namespace });
       refuseReservedNamespace(options.namespace);
@@ -1794,6 +1867,8 @@ var CloudRoaring = class _CloudRoaring {
    */
   async rollback(ref, toGeneration, options = {}) {
     validateSegmentRef(ref);
+    checkOptions(options, "rollback", CALL_KEYS.rollback, ["allowForward"]);
+    options ??= {};
     const deps = this.lifecycleDeps("rollback");
     try {
       return await rollbackSegment(ref, toGeneration, deps, options);
@@ -1886,6 +1961,8 @@ var CloudRoaring = class _CloudRoaring {
    */
   async load(ref, input, options = {}) {
     validateSegmentRef(ref);
+    checkOptions(options, "load", CALL_KEYS.load, ["allowEmpty"]);
+    options ??= {};
     const deps = this.lifecycleDeps("load");
     try {
       return await loadSegment(ref, bitmapAsLoadInput(input), deps, options);
@@ -1940,6 +2017,10 @@ var CloudRoaring = class _CloudRoaring {
    */
   async dropSegment(ref, options) {
     validateSegmentRef(ref);
+    if (options === void 0 || options === null) {
+      throw new ValidationError2("dropSegment: options { confirmSegment } are required");
+    }
+    checkOptions(options, "dropSegment", CALL_KEYS.dropSegment, ["dryRun"]);
     const deps = this.lifecycleDeps("dropSegment");
     try {
       return await dropSegment(
@@ -2067,69 +2148,20 @@ var CloudRoaring = class _CloudRoaring {
    * because retiring a segment deletes its storage objects. `now` defaults to the store's clock.
    */
   async retireExpired(options = {}) {
+    checkOptions(options, "retireExpired", CALL_KEYS.retireExpired, ["dryRun", "purgeTombstones"]);
+    const opts = picked(options, CALL_KEYS.retireExpired);
     const deps = this.lifecycleDeps("retireExpired");
     const result = await retireExpired(
       { registry: deps.registry, storage: deps.storage, clock: this.clock, rng: this.rng },
-      { ...options, now: options.now ?? this.clock.now() }
+      { ...opts, now: opts.now ?? this.clock.now() }
     );
-    if (options.dryRun !== true) {
+    if (opts.dryRun !== true) {
       for (const entry of result.entries) {
         this.engine.invalidate({ segment: entry.segment, namespace: entry.namespace });
       }
     }
     return result;
   }
-  /**
-   * **Remove the registry rows that releases before 0.12.0 left as `deleted: true` envelopes.** Those releases never
-   * removed a row they deleted, and no later call removes it either: it is invisible to every read, and every full
-   * listing of the registry still reads it (one GET each). This is the one call that removes them. It is an admin call,
-   * not a sweep, and nothing schedules it: run it once after the last process on a release before 0.12.0 is gone.
-   *
-   * ```ts
-   * const preview = await store.reapRegistryTombstones({ dryRun: true });
-   * console.log(`would remove ${preview.wouldReap} of ${preview.examined} rows read`);
-   *
-   * const done = await store.reapRegistryTombstones({ confirmNoLegacyWriters: true });
-   * if (done.limited) runAgain(); // `limit` (default 1,000) stopped the run with rows unread
-   * ```
-   *
-   * **What it removes.** Only a row that is `deleted: true` and whose token carries no incarnation id, which is what a
-   * release before 0.12.0 left, or a 0.12.0 or later release left by deleting a row born before 0.12.0 (both are safe to
-   * remove), whatever its `status`. It never touches a live row, a `destroyed` row that is not `deleted` (a crypto-shred's
-   * or a `dropSegment`'s tombstone: the attestation of an erasure, which it cannot tell from another), or a deleted row
-   * with an incarnation id, and it never touches a generation. **So it does not clean a bucket completely**: the
-   * `destroyed` tombstones `dropSegment` leaves stay, so do live rows written before 0.12.0, and so does a tombstone a
-   * 0.12.0 or later release wrote while `conditionalDelete` was off (GCS by default, S3 on a custom endpoint): every full
-   * listing still reads it, and this call neither removes it nor runs on such a store.
-   * It also covers the library's own bookkeeping rows when `namespace` is not set, by the same rule. The default
-   * namespace cannot be scoped to: leave `namespace` out to cover it.
-   *
-   * **The two things it asks.** `confirmNoLegacyWriters: true` is required for a real run (without it, a
-   * `ValidationError`, and nothing is requested): your statement that no process on a release before 0.12.0 writes
-   * this registry, since one that did would, re-creating a removed name, issue the removed row's tokens again. And the
-   * registry must apply a delete under a precondition: where its `conditionalDelete` capability is off (GCS by default,
-   * S3 on a custom endpoint) it throws `CapabilityError` before any request, dry run included. A registry that keeps
-   * no such rows (the in-memory and local-filesystem ones) throws `UnsupportedError`.
-   *
-   * **Each removal is fenced** on the version it read, so a `create` that lands over the envelope first wins, the
-   * delete is refused, and the row is counted as `skipped.raced` (which also counts a row already gone). That holds where
-   * the backend applies the precondition, which auto-detection checks (S3 only on an AWS host). On an endpoint that
-   * ignores `If-Match` (MinIO, fake-gcs-server), a `conditionalDelete: true` you set makes this an unfenced delete: run
-   * it with every writer stopped. On a versioned bucket a delete leaves a delete marker and the earlier version, record
-   * included, so the name is not erased from the bucket. A `create` that had already read the envelope and
-   * whose write meets the removal throws `WriteConflictError`, which this library does not retry: retry the create, and
-   * it finds no row and writes one.
-   *
-   * **Cost** over R rows read and E removed: `ceil(R / 1000)` LIST requests, R GETs and E DELETEs (a dry run, no
-   * DELETEs). `limit` bounds the removals, and the run stops listing once it is spent. **A run is not resumable**: each
-   * lists and reads from the start (R GETs whatever the `limit`), a dry run with a `limit` reports the same first rows
-   * every time, so `wouldReap` is a total only when `limited` is `false`, and `limited` is `true` whenever the limit was
-   * spent with keys left, removable or not. An unreadable object stops the run with an error naming its key, and
-   * removes nothing more: it may be a newer release's row. Scope the run with `namespace` to get past one.
-   */
-  async reapRegistryTombstones(options = {}) {
-    return reapRegistryTombstones(this.requireRegistry("reapRegistryTombstones"), options);
-  }
   /**
    * **Forget everything this store has cached about a segment.** Use it after destroying or retiring a segment
    * through a path this store did not perform itself.
@@ -2176,7 +2208,7 @@ var CloudRoaring = class _CloudRoaring {
    * pinned view reports the version captured at pin time, marked as a pin's, so its decoded chunks are never
    * those of a live read that fetched across a publish (see {@link PinnedStorageChunkSource.currentVersion}).
    */
-  async pinSegment(ref, expiresAt, leaseUntil, named) {
+  async pinSegment(ref, leaseUntil, named) {
     const crbm = this.crbmSource;
     if (crbm === void 0) {
       throw new UnsupportedError(
@@ -2236,9 +2268,8 @@ var CloudRoaring = class _CloudRoaring {
       clock: this.clock,
       metrics: this.metrics,
       materialize: (dest, ids, op, options) => this.materialize(dest, ids, op, options),
-      pinned: (r, e, l, at2) => this.pinSegment(r, e, l, at2),
+      pinned: (r, l, at2) => this.pinSegment(r, l, at2),
       combineEngine: (handles) => this.engineForCombine(handles),
-      expiresAt,
       pinnedAt,
       lease: hold
     });
@@ -2344,6 +2375,8 @@ var CloudRoaring = class _CloudRoaring {
    * `storage` and `registry` with a higher `maxScanSegments`.
    */
   async checkConsistency(options = {}) {
+    checkOptions(options, "checkConsistency", CALL_KEYS.checkConsistency, ["summaries"]);
+    options ??= {};
     const deps = this.lifecycleDeps("checkConsistency");
     return runConsistencyCheck(
       { storage: deps.storage, registry: deps.registry, keystore: deps.keystore },
@@ -2363,15 +2396,16 @@ var CloudRoaring = class _CloudRoaring {
    * CLI wraps this with a filesystem sink.
    */
   async exportSegments(sink, options = {}) {
+    checkOptions(options, "exportSegments", CALL_KEYS.exportSegments);
+    const opts = picked(options, CALL_KEYS.exportSegments);
     const registry = this.requireRegistry("exportSegments");
-    return runExport(this, registry, sink, {
-      ...options,
-      codec: options.codec ?? roaringCodec
-    });
+    return runExport(this, registry, sink, { ...opts, codec: opts.codec ?? roaringCodec });
   }
   /**
    * Planning cost estimate — pure, no instance/data needed: sizing, sales, what-if. For a real, grounded report
    * from live segment sizes, use `store.segment(name).costReport()`. See {@link CostReport}.
+   * @deprecated Moves to `@cloudbitmaps/tools`, a package of its own, with a `size` on `stat()` so a grounded report
+   * needs nothing internal. It is a planning tool, and its price list is as old as the release that ships it.
    */
   static estimateCost(input) {
     return estimateCost(input);
@@ -2401,24 +2435,17 @@ var readOptions = (options) => ({
   allowAbsentOperands: options.allowAbsentOperands
 });
 var NO_SEGMENTS = [];
-var EMPTY_IDS = {
-  async *[Symbol.asyncIterator]() {
-  },
-  async *batches() {
-  }
-};
+function segmentList(list, what) {
+  if (!Array.isArray(list)) throw new ValidationError2(`${what} must be an array of segments`);
+  return list;
+}
 var AS_IDS = {
-  none: EMPTY_IDS,
   failing,
   guard: guardIds,
   intersect: (engine, refs, opts) => withBatches(engine.intersect(refs, opts), () => engine.intersectBatches(refs, opts)),
   union: (engine, refs, opts) => withBatches(engine.union(refs, opts), () => engine.unionBatches(refs, opts)),
   andNot: (engine, base, refs, opts) => withBatches(engine.andNot(base, refs, opts), () => engine.andNotBatches(base, refs, opts))
 };
-var NO_CHUNKS = {
-  async *[Symbol.asyncIterator]() {
-  }
-};
 var CombineChunks = class {
   constructor(chunks) {
     this.chunks = chunks;
@@ -2426,7 +2453,6 @@ var CombineChunks = class {
   chunks;
 };
 var AS_CHUNKS = {
-  none: NO_CHUNKS,
   guard: guardChunks,
   failing: (err) => ({
     [Symbol.asyncIterator]: () => ({ next: () => Promise.reject(err) })
@@ -2436,39 +2462,14 @@ var AS_CHUNKS = {
   andNot: (engine, base, refs, opts) => engine.andNotChunks(base, refs, opts)
 };
 var KEEP_EVERY_GENERATION = Number.MAX_SAFE_INTEGER;
-var heldOf;
-var makeMemoryOperand;
-var mintingMemory = false;
-var MemoryOperand = class _MemoryOperand {
-  view;
-  static {
-    heldOf = (operand) => operand.view;
-    makeMemoryOperand = (view) => {
-      mintingMemory = true;
-      try {
-        return new _MemoryOperand(view);
-      } finally {
-        mintingMemory = false;
-      }
-    };
-  }
-  /** Not constructible: a handle comes from {@link CloudRoaring.memory}. */
-  constructor(view) {
-    if (!mintingMemory) {
-      throw new ValidationError2(
-        "a MemoryOperand is not constructed directly; call `await store.memory(ids)`"
-      );
-    }
-    this.view = view;
-  }
-  /**
-   * Zero and drop the bytes it holds. Any later use throws {@link ValidationError}; releasing twice does nothing. A call
-   * still reading it fails the outputs that read it.
-   */
-  release() {
-    this.view.chunks.release();
+async function timeOp(metrics, clock, name, fn) {
+  const startedAt = clock.now();
+  try {
+    return await fn();
+  } finally {
+    metrics.onEvent({ kind: "op", name, ms: Math.max(0, clock.now() - startedAt) });
   }
-};
+}
 var makeSegment;
 var minting = false;
 var Segment = class _Segment {
@@ -2480,8 +2481,6 @@ var Segment = class _Segment {
   materialize;
   pinned;
   combineEngine;
-  /** Absolute epoch-ms deadline from {@link SegmentOptions.expiresAt}; `undefined` ⇒ this handle never expires. */
-  expiresAt;
   /**
    * The generation this handle is held at, when it came from {@link Segment.pin}. Read by the store so a
    * pinned handle passed as an **operand** is still read at its pin rather than live.
@@ -2506,9 +2505,7 @@ var Segment = class _Segment {
     viewOf = (segment) => ({
       ref: segment.ref,
       pinnedAt: segment.pinnedAt,
-      expiresAt: segment.expiresAt,
-      leaseError: () => segment.leaseError(),
-      expired: () => segment.expired()
+      leaseError: () => segment.leaseError()
     });
   }
   /**
@@ -2528,7 +2525,6 @@ var Segment = class _Segment {
     this.materialize = parts.materialize;
     this.pinned = parts.pinned;
     this.combineEngine = parts.combineEngine;
-    this.expiresAt = parts.expiresAt;
     this.pinnedAt = parts.pinnedAt;
     this.leaseHold = parts.lease;
     if (parts.lease !== void 0) {
@@ -2618,12 +2614,12 @@ var Segment = class _Segment {
   async pin(options) {
     this.assertLeases([this]);
     const leaseUntil = this.leaseUntilOf("pin", options);
-    return this.pinned(this.ref, this.expiresAt, leaseUntil);
+    return this.pinned(this.ref, leaseUntil);
   }
   /**
    * Hold what this pin names until `leaseUntil`, or `undefined` for a pin with no lease. Refuses an option it does not
-   * know, a value that is not epoch-milliseconds in the future, one past the longest lease, and one past the handle's own
-   * `expiresAt`, before any request is made.
+   * know, a value that is not epoch-milliseconds in the future, and one past the longest lease, before any request is
+   * made.
    */
   leaseUntilOf(op, options) {
     if (options === void 0 || options === null) return void 0;
@@ -2654,11 +2650,6 @@ var Segment = class _Segment {
         `${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`
       );
     }
-    if (this.expiresAt !== void 0 && until > this.expiresAt) {
-      throw new ValidationError2(
-        `${op}: leaseUntil outlasts this handle's own expiresAt, which would have it read empty while it still holds the generation`
-      );
-    }
     return until;
   }
   /**
@@ -2683,7 +2674,7 @@ var Segment = class _Segment {
   }
   /**
    * The error a read of this handle must throw, or `undefined` when it holds no lease or the lease is live. One property
-   * read on a handle with no lease. It is not {@link Segment.expired}: that rule reads empty, and a lease must never.
+   * read on a handle with no lease. A read past a lease throws; it never reads empty.
    */
   leaseError() {
     const hold = this.leaseHold;
@@ -2705,9 +2696,21 @@ 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.
+   */
+  assertSegments(handles) {
+    for (const h of handles) {
+      if (h instanceof _Segment || typeof h === "object" && h !== null && typeof h.leaseError === "function") {
+        continue;
+      }
+      throw new ValidationError2("an operand must be a segment from store.segment()");
+    }
+  }
   /**
    * Throw the first lease error among `handles`: this handle and every operand and exclude of a call. It runs before
-   * any `expiresAt` rule and before the engine, so no operand, exclude or cached reader can answer past a lease.
+   * the engine, so no operand, exclude or cached reader can answer past a lease.
    */
   assertLeases(handles) {
     for (const h of handles) {
@@ -2752,7 +2755,7 @@ var Segment = class _Segment {
       );
     }
     const leaseUntil = this.leaseUntilOf("pinAt", options);
-    return this.pinned(this.ref, this.expiresAt, leaseUntil, { generation, fingerprint });
+    return this.pinned(this.ref, leaseUntil, { generation, fingerprint });
   }
   /**
    * An opaque string that names this handle's segment, namespace included: two handles of one segment have the
@@ -2764,49 +2767,17 @@ var Segment = class _Segment {
     return segmentKey(this.ref);
   }
   /**
-   * Has this handle's deadline passed? **The lazy half of expiry** — the whole check is one comparison against
-   * the injected clock, so it costs nothing on a handle with no deadline and no I/O on one that has expired.
-   *
-   * Deliberately evaluated per call rather than cached: a long-lived handle created before its deadline must
-   * start reading empty the moment the deadline passes, without the caller re-creating it.
-   */
-  expired() {
-    return this.expiresAt !== void 0 && this.clock.now() >= this.expiresAt;
-  }
-  /**
-   * Refuse a materialisation that involves an **expired** handle. Called by the three `*Into` verbs only.
-   *
-   * On the read verbs an expired handle answers empty, which is the point of lazy expiry. On a *write* the same
-   * rule would be destructive in a way nobody asks for: `a.intersectInto(dest, [b])` where `b`'s deadline has
-   * quietly passed would, unrefused, replace `dest` with an **empty generation** — a wipe, reported as a successful
-   * write, with the cause (a deadline on a handle somewhere) nowhere in the result. Reads degrade to empty; writes must not.
-   *
-   * So every handle in the call is checked, `dest` included: an expired `dest` does not change the bytes written,
-   * but a caller who put a deadline on the thing they are writing into has said something contradictory and is
-   * better told than guessed at. Open a handle without `expiresAt` to write, or drop the deadline.
-   *
-   * (The broader guard — refusing to publish an empty or implausible generation over a non-empty one, with an
-   * `allowEmpty` override — covers these verbs too: they route through the same guarded write path as
-   * {@link CloudRoaring.load}. The two stay separate because they differ in kind. That one is a REPORTED
-   * refusal a caller may legitimately override; an expired handle is a wiring mistake, so it THROWS, before
-   * any object is written — and `allowEmpty: true` does not reach it.)
+   * 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.
    *
    * 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.
    */
-  refuseIfExpired(op, dest, operands) {
+  assertIntoHandles(dest, operands) {
+    this.assertSegments([dest, ...operands]);
     this.assertLeases([this, dest, ...operands]);
-    const stale = [];
-    for (const seg of [this, dest, ...operands]) {
-      if (seg.expired())
-        stale.push(seg.ref.namespace ? `${seg.ref.namespace}/${seg.ref.segment}` : seg.ref.segment);
-    }
-    if (stale.length > 0) {
-      throw new ValidationError2(
-        `${op}: refusing to publish a generation while these handles have expired \u2014 ${[...new Set(stale)].join(", ")}. An expired handle reads as empty, so this would write an empty (or short) generation over "${dest.ref.segment}". Open the handles without \`expiresAt\` if you meant to materialise, or drop the deadline.`
-      );
-    }
   }
   /** `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) {
@@ -2829,7 +2800,6 @@ var Segment = class _Segment {
   has(id) {
     const lease = this.leaseError();
     if (lease !== void 0) return Promise.reject(lease);
-    if (this.expired()) return Promise.resolve(false);
     return this.timed("has", () => this.engine.has(this.ref, id));
   }
   /**
@@ -2853,15 +2823,14 @@ var Segment = class _Segment {
   count() {
     const lease = this.leaseError();
     if (lease !== void 0) return Promise.reject(lease);
-    if (this.expired()) return Promise.resolve(0);
     return this.timed("count", () => this.engine.count(this.ref));
   }
   /**
    * What the generation this handle reads is, from one resolution: its number, its id count and the metadata it
    * was loaded with (absent when it has none). It is what answers {@link Segment.count}, so the three describe one
    * generation and cannot straddle a publish. One registry read when cold, none while warm, and none on a pinned
-   * handle, which answers for the generation it pinned. A segment with no generation, and an expired handle,
-   * answer `{ generation: null, cardinality: 0 }`.
+   * handle, which answers for the generation it pinned. A segment with no generation answers
+   * `{ generation: null, cardinality: 0 }`.
    *
    * Trust is as for `count()`: the registry row's word, not confirmed against the object until the object is
    * opened, when a disagreement makes this process stop using that row's summary.
@@ -2872,7 +2841,6 @@ var Segment = class _Segment {
    */
   async stat() {
     this.assertLeases([this]);
-    if (this.expired()) return { generation: null, cardinality: 0 };
     return this.engine.stat(this.ref);
   }
   /**
@@ -2887,13 +2855,13 @@ var Segment = class _Segment {
    * ```
    *
    * Each bound is optional and an integer in `0..4294967295`; a bad one throws {@link ValidationError} when the
-   * stream is first read. `after >= through` is an empty range, which reads nothing. An expired handle reads empty
-   * without checking its options, as every read of one does.
+   * stream is first read. `after >= through` is an empty range, which reads nothing.
    */
   iterate(options) {
     const lease = this.leaseError();
     if (lease !== void 0) return failing(lease);
-    if (this.expired()) return EMPTY_IDS;
+    const bad = optionsError(options, "iterate", CALL_KEYS.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;
     const { engine, ref } = this;
@@ -2926,7 +2894,7 @@ var Segment = class _Segment {
    *
    * A live handle is refused with {@link UnsupportedError} at the first read, because its counts and its chunks could
    * come from two generations and name the wrong id. `n` that is not a positive integer throws
-   * {@link ValidationError} at the first read, as does a bad bound. An expired handle reads empty.
+   * {@link ValidationError} at the first read, as does a bad bound.
    *
    * ```ts
    * const audience = await store.segment('audience').pin();
@@ -2937,7 +2905,8 @@ var Segment = class _Segment {
   everyNth(n, options) {
     const lease = this.leaseError();
     if (lease !== void 0) return failing(lease);
-    if (this.expired()) return EMPTY_IDS;
+    const bad = optionsError(options, "everyNth", CALL_KEYS.range);
+    if (bad !== void 0) return failing(bad);
     if (this.pinnedAt === void 0) {
       return failing(
         new UnsupportedError(
@@ -2975,30 +2944,8 @@ var Segment = class _Segment {
    */
   excludesOf(options) {
     const exclude = options?.exclude;
-    return exclude == null || exclude.length === 0 ? NO_SEGMENTS : exclude;
-  }
-  /**
-   * The refusal for a combine whose **exclusion** has expired, or `undefined` when none has. Unlike an expired
-   * operand, which reads empty, an exclusion is a suppression or opt-out list: left out silently, the result
-   * would include the very ids it was passed to remove. So it is refused with a {@link ValidationError} naming each
-   * expired exclusion, as the `*Into` verbs refuse an expired handle.
-   *
-   * It is judged against the injected clock when the combine is called, before the engine is asked for anything:
-   * no request is made, and an expired exclusion that names a segment that does not exist is refused as expired,
-   * not as an absent operand. It runs ahead of the expired-operand shortcuts, so a combine that would read empty
-   * anyway still refuses a lapsed exclusion. A stream already being read is not re-checked when an exclusion
-   * expires part-way, as an operand expiring part-way does not stop it either.
-   */
-  expiredExcludes(op, excludes) {
-    let stale;
-    for (const e of excludes) {
-      if (!e.expired()) continue;
-      (stale ??= []).push(e.ref.namespace ? `${e.ref.namespace}/${e.ref.segment}` : e.ref.segment);
-    }
-    if (stale === void 0) return void 0;
-    return new ValidationError2(
-      `${op}: refusing to read while these exclusions have expired \u2014 ${[...new Set(stale)].join(", ")}. An expired exclusion would subtract nothing, so the result would include the ids it was passed to remove. Renew the exclusion's \`expiresAt\`, open it without one, or leave it out of the call.`
-    );
+    if (exclude == null) return NO_SEGMENTS;
+    return segmentList(exclude, "`exclude`").length === 0 ? NO_SEGMENTS : exclude;
   }
   /**
    * Chunk-skipping intersection: stream the ids in **this** segment AND every segment in `others`, ascending.
@@ -3010,19 +2957,21 @@ var Segment = class _Segment {
    * override the store's per-op denial-of-wallet budget for this call (or `false` to lift it).
    */
   intersect(others, options) {
-    return this.intersectAs(AS_IDS, others, options);
+    const bad = optionsError(options, "intersect", CALL_KEYS.combine, ["allowAbsentOperands"]);
+    if (bad !== void 0) return failing(bad);
+    return this.intersectAs(AS_IDS, others, options ?? void 0);
   }
   intersectAs(out, others, options) {
-    const exclude = this.excludesOf(options);
-    const handles = [this, ...others, ...exclude];
+    let exclude;
+    let handles;
     try {
+      exclude = this.excludesOf(options);
+      handles = [this, ...segmentList(others, "intersect: `others`"), ...exclude];
+      this.assertSegments(handles);
       this.assertLeases(handles);
     } catch (err) {
       return out.failing(err);
     }
-    const refused = this.expiredExcludes("intersect", exclude);
-    if (refused) return out.failing(refused);
-    if (this.expired() || others.some((o) => o.expired())) return out.none;
     let engine;
     try {
       engine = this.combineEngine([this, ...others, ...exclude]) ?? this.engine;
@@ -3046,16 +2995,21 @@ var Segment = class _Segment {
    * write is **refused and reported**: `published: false`, `reason: 'empty'`, and `dest` keeps what it had.
    * Pass `allowEmpty: true` when emptying the destination is the point.
    *
-   * `guard` adds the same plausibility bounds `load()` takes — `minCardinality` and `minRetained` — judged
+   * `guard` adds the same plausibility bounds `load()` takes — `minCardinality`, `minRetained` and `maxGrowth` — judged
    * against what `dest` held before. A refusal is **reported, not thrown**, exactly as on `load()`; branch on
    * `published`. A lost race is the one outcome that still throws ({@link WriteConflictError}), because a
    * materialisation that silently did not take effect is the one thing a caller cannot detect on its own.
    *
-   * A call involving an **expired handle** is refused before any of this. See {@link refuseIfExpired}.
+   * A call involving a handle whose lease has ended, or anything that is not a segment, is refused before any of this.
    */
   async intersectInto(dest, others, options) {
-    this.refuseIfExpired("intersectInto", dest, [...others, ...options?.exclude ?? []]);
-    this.combineEngine([this, ...others, ...options?.exclude ?? []]);
+    checkOptions(options, "intersectInto", CALL_KEYS.into, ["allowEmpty", "allowAbsentOperands"]);
+    const operands = [
+      ...segmentList(others, "intersectInto: `others`"),
+      ...this.excludesOf(options)
+    ];
+    this.assertIntoHandles(dest, operands);
+    this.combineEngine([this, ...operands]);
     return this.timed(
       "intersectInto",
       () => this.materialize(
@@ -3077,27 +3031,21 @@ var Segment = class _Segment {
    * segment once (`unionInto`, or a load) is the cheaper shape.
    */
   union(others, options) {
-    return this.unionAs(AS_IDS, others, options);
+    const bad = optionsError(options, "union", CALL_KEYS.combine, ["allowAbsentOperands"]);
+    if (bad !== void 0) return failing(bad);
+    return this.unionAs(AS_IDS, others, options ?? void 0);
   }
   unionAs(out, others, options) {
-    const exclude = this.excludesOf(options);
-    const handles = [this, ...others, ...exclude];
+    let exclude;
+    let handles;
     try {
+      exclude = this.excludesOf(options);
+      handles = [this, ...segmentList(others, "union: `others`"), ...exclude];
+      this.assertSegments(handles);
       this.assertLeases(handles);
     } catch (err) {
       return out.failing(err);
     }
-    const refused = this.expiredExcludes("union", exclude);
-    if (refused) return out.failing(refused);
-    const live = others.filter((o) => !o.expired());
-    if (this.expired()) {
-      if (live.length === 0) return out.none;
-      return live[0].unionAs(out, live.slice(1), options);
-    }
-    if (live.length === 0 && others.length > 0) {
-      return exclude.length > 0 ? this.andNotAs(out, [...exclude], options) : this.unionAs(out, [], options);
-    }
-    if (live.length !== others.length) return this.unionAs(out, live, options);
     let engine;
     try {
       engine = this.combineEngine([this, ...others, ...exclude]) ?? this.engine;
@@ -3110,8 +3058,10 @@ var Segment = class _Segment {
   }
   /** Materialize `this ∪ others…` (minus `exclude`) as a **new generation of `dest`** — see {@link intersectInto}. */
   async unionInto(dest, others, options) {
-    this.refuseIfExpired("unionInto", dest, [...others, ...options?.exclude ?? []]);
-    this.combineEngine([this, ...others, ...options?.exclude ?? []]);
+    checkOptions(options, "unionInto", CALL_KEYS.into, ["allowEmpty", "allowAbsentOperands"]);
+    const operands = [...segmentList(others, "unionInto: `others`"), ...this.excludesOf(options)];
+    this.assertIntoHandles(dest, operands);
+    this.combineEngine([this, ...operands]);
     return this.timed(
       "unionInto",
       () => this.materialize(
@@ -3130,26 +3080,23 @@ var Segment = class _Segment {
    * suppression list: at most one read per surviving key of `this`, so subtracting a 61,000-chunk global
    * opt-out list from a 40-chunk audience costs at most 40 reads, not 61,000.
    *
-   * An expired handle in `excludes` is refused, not skipped: the stream throws {@link ValidationError} naming it,
-   * before any request is made, because a lapsed suppression list would otherwise let through the ids it was
-   * passed to remove. An expired `this` is empty. `exclude` on `intersect` and `union` follows the same rule.
-   *
    * 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.
    */
   andNot(excludes, options) {
-    return this.andNotAs(AS_IDS, excludes, options);
+    const bad = optionsError(options, "andNot", CALL_KEYS.andNot, ["allowAbsentOperands"]);
+    if (bad !== void 0) return failing(bad);
+    return this.andNotAs(AS_IDS, excludes, options ?? void 0);
   }
   andNotAs(out, excludes, options) {
-    const handles = [this, ...excludes];
+    let handles;
     try {
+      handles = [this, ...segmentList(excludes, "andNot: `excludes`")];
+      this.assertSegments(handles);
       this.assertLeases(handles);
     } catch (err) {
       return out.failing(err);
     }
-    const refused = this.expiredExcludes("andNot", excludes);
-    if (refused) return out.failing(refused);
-    if (this.expired()) return out.none;
     let engine;
     try {
       engine = this.combineEngine([this, ...excludes]) ?? this.engine;
@@ -3163,7 +3110,11 @@ var Segment = class _Segment {
   }
   /** Materialize `this \ (excludes…)` as a **new generation of `dest`** — see {@link intersectInto}. */
   async andNotInto(dest, excludes, options) {
-    this.refuseIfExpired("andNotInto", dest, excludes);
+    checkOptions(options, "andNotInto", CALL_KEYS.andNotInto, [
+      "allowEmpty",
+      "allowAbsentOperands"
+    ]);
+    this.assertIntoHandles(dest, segmentList(excludes, "andNotInto: `excludes`"));
     this.combineEngine([this, ...excludes]);
     return this.timed(
       "andNotInto",
@@ -3181,13 +3132,21 @@ var Segment = class _Segment {
    * storage. The pointer refresh is priced at the store's own `cache.genTtlMs`, or at none when the store never
    * refreshes, unless the workload sets `genTtlMs`. See {@link CostReport} — it always includes a verdict (incl.
    * the lose-zone).
+   * @deprecated Moves to `@cloudbitmaps/tools`, a package of its own, with a `size` on `stat()` so a grounded report
+   * needs nothing internal. It is a planning tool, and its price list is as old as the release that ships it.
    */
   async costReport(options) {
+    checkOptions(options, "costReport", CALL_KEYS.costReport);
+    const shape = options?.workload;
+    if (shape !== void 0 && shape !== null && (typeof shape !== "object" || Array.isArray(shape))) {
+      throw new ValidationError2("costReport: workload must be an object");
+    }
     this.assertLeases([this]);
     const canMeasure = this.engine.supportsStorageSize;
     const size = canMeasure ? await this.engine.segmentSize(this.ref) : null;
     const refreshMs = this.engine.pointerRefreshMs;
-    const workload = refreshMs === void 0 || options?.workload?.genTtlMs !== void 0 ? options?.workload : { ...options?.workload, genTtlMs: refreshMs };
+    const given = options?.workload === void 0 || options.workload === null ? void 0 : picked(options.workload, CALL_KEYS.workload);
+    const workload = refreshMs === void 0 || given?.genTtlMs !== void 0 ? given : { ...given, genTtlMs: refreshMs };
     return groundedReport({
       storageBytes: size?.sizeBytes ?? 0,
       grounded: canMeasure,
@@ -3208,7 +3167,7 @@ function parseConfig(env) {
   if (out === void 0 || out === "") {
     throw new Error("CR_EXPORT_OUT is required (the output directory for the dump)");
   }
-  const format = env.CR_EXPORT_FORMAT ?? "roaring";
+  const format = env.CR_EXPORT_FORMAT || "roaring";
   if (format !== "roaring" && format !== "ndjson") {
     throw new Error(`CR_EXPORT_FORMAT must be "roaring" or "ndjson"; got ${format}`);
   }
@@ -3269,14 +3228,29 @@ function fsSink(out) {
     }
   };
 }
+async function requireStoreRoot(root) {
+  let entries;
+  try {
+    entries = await readdir(root);
+  } catch {
+    throw new ValidationError3("CR_EXPORT_ROOT does not name a directory that can be read");
+  }
+  if (entries.length === 0) {
+    throw new ValidationError3(
+      "CR_EXPORT_ROOT is empty: it holds no store (an unmounted volume, or the wrong directory)"
+    );
+  }
+}
 var log = (obj) => {
   process.stdout.write(`${JSON.stringify(obj)}
 `);
 };
 async function main(env = process.env, now = () => Date.now()) {
   const config = parseConfig(env);
+  await requireStoreRoot(config.root);
   const storage = new LocalFsStorage(config.root);
   const store = new CloudRoaring({ storage });
+  await rm(join(config.out, "manifest.json"), { force: true });
   const manifest = await store.exportSegments(fsSink(config.out), {
     format: config.format,
     namespace: config.namespace