@cloudbitmaps/roaring 0.16.0 → 0.18.0

package/dist/index.js

@@ -11,6 +11,10 @@ import {
   NOOP_METRICS,
   RetryingStorageChunkSource,
   SegmentEngine,
+  LEASE_SKEW_MS,
+  LeaseExpiredError,
+  MAX_LEASE_MS,
+  NotFoundError,
   UnsupportedError,
   ValidationError as ValidationError2,
   WriteConflictError,
@@ -24,17 +28,24 @@ import {
   groundedReport,
   loadSegment,
   loadSegmentChunks,
+  compileCombineMany,
+  prepareHeld,
+  rebindCombineMany,
+  runCombineMany,
   mapWithConcurrency,
   resolveBudget,
   resolvePerOpBudget,
+  reapRegistryTombstones,
   retireExpired,
   runConsistencyCheck,
   runExport,
   setSegmentRetention,
   clearSegmentRetention,
   getSegmentRetention,
+  releaseLease,
   safeMetrics,
-  splitId
+  splitId,
+  takeLease
 } from "@cloudbitmaps/core";
 import { validateSegmentRef } from "@cloudbitmaps/core/driver-kit";
 
@@ -94,7 +105,7 @@ function refuseReservedNamespace(namespace) {
 
 // src/roaring-codec.ts
 import roaring from "roaring";
-import { IntegrityError as IntegrityError2 } from "@cloudbitmaps/core";
+import { IntegrityError as IntegrityError2, decodeSerialized } from "@cloudbitmaps/core";
 
 // src/portable/layout.ts
 import { IntegrityError } from "@cloudbitmaps/core";
@@ -342,6 +353,10 @@ 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);
   }
@@ -454,6 +469,9 @@ var roaringCodec = {
   safeDeserialize: (bytes, maxBytes, options) => SafeBitmap.safeDeserialize(bytes, maxBytes, options),
   owns: (bitmap) => bitmap instanceof SafeBitmap
 };
+function deserializePortable(bytes) {
+  return decodeSerialized(bytes, roaringCodec).unwrap();
+}
 
 // src/system-clock.ts
 var SystemClock = class {
@@ -506,6 +524,86 @@ var OPTION_KEYS = {
   seams: ["clock", "rng"]
 };
 
+// src/lease-guards.ts
+var guardIdIterable = (inner, check) => ({
+  [Symbol.asyncIterator]: () => {
+    const it = inner[Symbol.asyncIterator]();
+    let chunk = -1;
+    let first = true;
+    const stop = async (err) => {
+      await it.return?.();
+      throw err;
+    };
+    return {
+      async next() {
+        if (first) {
+          first = false;
+          try {
+            check();
+          } catch (err) {
+            return stop(err);
+          }
+        }
+        const r = await it.next();
+        if (r.done === true) return r;
+        const key = r.value >>> 16;
+        if (key !== chunk) {
+          try {
+            check();
+          } catch (err) {
+            return stop(err);
+          }
+          chunk = key;
+        }
+        return r;
+      },
+      async return() {
+        await it.return?.();
+        return { done: true, value: void 0 };
+      }
+    };
+  }
+});
+var guardIds = (inner, check) => ({
+  [Symbol.asyncIterator]: () => guardIdIterable(inner, check)[Symbol.asyncIterator](),
+  batches: () => guardItems(inner.batches(), check)
+});
+var guardItems = (inner, check) => ({
+  [Symbol.asyncIterator]: () => {
+    const it = inner[Symbol.asyncIterator]();
+    let first = true;
+    const stop = async (err) => {
+      await it.return?.();
+      throw err;
+    };
+    return {
+      async next() {
+        if (first) {
+          first = false;
+          try {
+            check();
+          } catch (err) {
+            return stop(err);
+          }
+        }
+        const r = await it.next();
+        if (r.done === true) return r;
+        try {
+          check();
+        } catch (err) {
+          return stop(err);
+        }
+        return r;
+      },
+      async return() {
+        await it.return?.();
+        return { done: true, value: void 0 };
+      }
+    };
+  }
+});
+var guardChunks = (inner, check) => guardItems(inner, check);
+
 // src/index.ts
 import {
   MemoryStorage,
@@ -516,6 +614,9 @@ import {
   excludingReservedRows as excludingReservedRows2,
   readRetentionPolicy,
   MIN_EXPIRES_AT_MS as MIN_EXPIRES_AT_MS2,
+  LEASE_SKEW_MS as LEASE_SKEW_MS2,
+  MAX_LEASE_MS as MAX_LEASE_MS2,
+  MAX_LEASES_PER_SEGMENT,
   InProcessKeystore,
   NodeAead,
   aadFor,
@@ -523,18 +624,24 @@ import {
   ValidationError as ValidationError3,
   WriteConflictError as WriteConflictError2,
   IntegrityError as IntegrityError3,
-  NotFoundError,
+  NotFoundError as NotFoundError2,
   UnsupportedError as UnsupportedError2,
   CapabilityError,
   TransientError,
   KeyUnavailableError,
   BudgetExceededError,
+  LeaseExpiredError as LeaseExpiredError2,
+  LeaseLimitError,
+  StaleOperandError,
   isCloudRoaringError,
   isWriteConflictError,
   isTransientError,
   isNotFoundError,
   isIntegrityError,
   isValidationError,
+  isLeaseExpiredError,
+  isLeaseLimitError,
+  isStaleOperandError,
   CrbmReader,
   BufferReader,
   CountingMetricsSink,
@@ -565,6 +672,36 @@ function requireScope(options, op) {
     );
   }
 }
+var viewOf;
+var MATERIALIZE_MANY_KEYS = [
+  "operands",
+  "outputs",
+  "keep",
+  "pin",
+  "maxBufferedBytes",
+  "budget",
+  "publishConcurrency",
+  "concurrency",
+  "allowAbsentOperands",
+  "after",
+  "through",
+  "feed",
+  "mayBeEmpty"
+];
+var MATERIALIZE_MANY_OUTPUT_KEYS = [
+  "dest",
+  "expr",
+  "exclude",
+  "guard",
+  "allowEmpty",
+  "metadata",
+  "audit",
+  "keep"
+];
+var DEFAULT_MAX_BUFFERED_BYTES = 256 * 1024 * 1024;
+var DEFAULT_PUBLISH_CONCURRENCY = 8;
+var DEFAULT_BATCH_CONCURRENCY = 1;
+var PIN_PARALLELISM = 16;
 function resolveStorageSource(options, clock) {
   const storage = options.storage;
   if (storage === null || typeof storage !== "object") {
@@ -677,6 +814,13 @@ var CloudRoaring = class _CloudRoaring {
   requireEncryption;
   /** Resolved store-level per-op budget (null = disabled); the admin scans use it, with a per-op override. */
   budget;
+  /**
+   * Moved at the start and at the end of each `eraseSubject` this store runs. A `materializeMany` call with a feed records
+   * it when it begins and is refused once it has moved: it reads caller memory, which no erasure can reach.
+   */
+  erasureEpoch = 0;
+  /** How many `eraseSubject` calls of this store are running: while any is, every check of the counter counts as moved. */
+  erasuresRunning = 0;
   /**
    * Refuse any option key the store does not take, at the top level or inside a group, naming each one.
    *
@@ -730,6 +874,9 @@ var CloudRoaring = class _CloudRoaring {
       clock
     });
     const resolved = resolveStorageSource(options, clock);
+    if (metrics !== NOOP_METRICS && isStorageBackend(options.storage)) {
+      options.storage.attachMetrics?.(metrics);
+    }
     let storage = resolved.source;
     if (options.retry !== false) {
       const { onRetry: userOnRetry, ...ov } = options.retry ?? {};
@@ -827,7 +974,7 @@ var CloudRoaring = class _CloudRoaring {
       clock: this.clock,
       metrics: this.metrics,
       materialize: (dest, ids, op, options2) => this.materialize(dest, ids, op, options2),
-      pinned: (r, e) => this.pinSegment(r, e),
+      pinned: (r, e, l, at) => this.pinSegment(r, e, l, at),
       combineEngine: (handles) => this.engineForCombine(handles),
       expiresAt
     });
@@ -913,6 +1060,440 @@ 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 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,
+   * });
+   * ```
+   */
+  async materializeMany(options) {
+    if (typeof options !== "object" || options === null) {
+      throw new ValidationError2(
+        "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)
+    );
+    if (unknown.length > 0) {
+      throw new ValidationError2(
+        `materializeMany: unknown option${unknown.length > 1 ? "s" : ""} ${unknown.map((k) => `"${k}"`).join(", ")}`
+      );
+    }
+    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 feedIn = options.feed;
+    const mayBeEmptyIn = options.mayBeEmpty;
+    if (feedIn !== void 0 && options.maxBufferedBytes === void 0) {
+      throw new ValidationError2(
+        "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"
+      );
+    }
+    const maxBufferedBytes = options.maxBufferedBytes ?? DEFAULT_MAX_BUFFERED_BYTES;
+    const publishConcurrency = options.publishConcurrency ?? DEFAULT_PUBLISH_CONCURRENCY;
+    const concurrency = options.concurrency ?? DEFAULT_BATCH_CONCURRENCY;
+    const budgetOption = options.budget;
+    const allowAbsentOperands = options.allowAbsentOperands;
+    if (typeof pinOption !== "boolean")
+      throw new ValidationError2("materializeMany: pin must be a boolean");
+    if (allowAbsentOperands !== void 0 && typeof allowAbsentOperands !== "boolean") {
+      throw new ValidationError2("materializeMany: allowAbsentOperands must be a boolean");
+    }
+    if (typeof operandsIn !== "object" || operandsIn === null || Array.isArray(operandsIn)) {
+      throw new ValidationError2("materializeMany: operands must be an object of name to segment");
+    }
+    if (!Array.isArray(outputsIn) || outputsIn.length === 0) {
+      throw new ValidationError2("materializeMany: outputs must be a non-empty array");
+    }
+    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()`
+        );
+      }
+      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 (feedIn === void 0 && (heldHandles.size === 0 || !Array.isArray(fedMayBeEmpty) || fedMayBeEmpty.length > 0)) {
+        throw new ValidationError2(
+          "materializeMany: mayBeEmpty names fed operands, and the call has no feed"
+        );
+      }
+    }
+    const operandKeys = new Set([...handles.values()].map((h) => h.key()));
+    const outputs = [];
+    const destKeys = /* @__PURE__ */ new Set();
+    outputsIn.forEach((raw, i) => {
+      if (typeof raw !== "object" || raw === null) {
+        throw new ValidationError2(`outputs[${i}] must be an object`);
+      }
+      const bad = Object.keys(raw).filter(
+        (k) => !MATERIALIZE_MANY_OUTPUT_KEYS.includes(k)
+      );
+      if (bad.length > 0) {
+        throw new ValidationError2(
+          `outputs[${i}]: unknown option${bad.length > 1 ? "s" : ""} ${bad.map((k) => `"${k}"`).join(", ")}`
+        );
+      }
+      const spec = raw;
+      const dest = spec.dest;
+      if (!(dest instanceof Segment)) {
+        throw new ValidationError2(`outputs[${i}].dest must be a segment from store.segment()`);
+      }
+      if (operandKeys.has(dest.key())) {
+        throw new ValidationError2(
+          `outputs[${i}].dest is also an operand of the call: one call is one pass over operands that do not change under it, so chain two calls`
+        );
+      }
+      if (destKeys.has(dest.key())) {
+        throw new ValidationError2(
+          `outputs[${i}].dest names a segment another output of the call writes`
+        );
+      }
+      destKeys.add(dest.key());
+      outputs.push({ spec, dest });
+    });
+    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) } : {},
+        ...pinnedAt === void 0 ? {} : {
+          pinnedGeneration: pinnedAt.generation,
+          pinnedVersion: pinnedAt.version,
+          pinnedFingerprint: pinnedAt.fingerprint ?? null
+        },
+        current: (read) => this.currentRowOf(seg.ref, read?.fingerprint === true)
+      };
+    });
+    const request = (pins2) => ({
+      operands: operandSpecs(pins2),
+      outputs: outputs.map(({ spec, dest }, i) => ({
+        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),
+        // 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", {
+          ...write,
+          ...spec.audit === void 0 ? {} : { audit: spec.audit }
+        })
+      })),
+      keep,
+      ...after === void 0 ? {} : { after },
+      ...through === void 0 ? {} : { through },
+      maxBufferedBytes,
+      publishConcurrency,
+      concurrency,
+      ...budget === void 0 ? {} : { budget },
+      ...allowAbsentOperands === void 0 ? {} : { allowAbsentOperands },
+      ...feedIn === void 0 ? {} : { feed: this.feedOf(feedIn, fedMayBeEmpty, epochAt) }
+    });
+    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);
+    this.lifecycleDeps("materializeMany");
+    const crbm = this.crbmSource;
+    if (crbm === void 0) {
+      throw new UnsupportedError(
+        "materializeMany needs the `.crbm` storage source \u2014 pass a backend or a raw IStorageDriver as `storage`"
+      );
+    }
+    const held = /* @__PURE__ */ new Map();
+    for (const [name, handle] of handles) {
+      const key = handle.key();
+      const at = handle.pinnedAt;
+      const prior = held.get(key);
+      if (prior === void 0) {
+        held.set(key, { at, handle });
+      } else if (prior.at !== void 0 && at !== void 0) {
+        if (!samePin(prior.at, at)) {
+          throw new ValidationError2(
+            `materializeMany: operand "${name}" holds a segment another operand holds, ${twoPins(prior.at, at)}: one call reads a segment at one generation`
+          );
+        }
+      } else if (prior.at !== void 0 || at !== void 0) {
+        if (!pinOption) {
+          throw new ValidationError2(
+            `materializeMany: operand "${name}" holds a segment another operand holds, ${twoPins(prior.at, at)}: one call reads a segment at one generation`
+          );
+        }
+        if (at !== void 0) held.set(key, { at, handle });
+      }
+    }
+    const pins = /* @__PURE__ */ new Map();
+    const toPin = [];
+    for (const [key, { at, handle }] of held) {
+      if (at !== void 0) pins.set(key, at);
+      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 : {
+          published: false,
+          error: o.error instanceof Error ? o.error : new Error(String(o.error))
+        }
+      ),
+      stats: run.stats
+    };
+  }
+  epochNow() {
+    return this.erasureEpoch;
+  }
+  /**
+   * Whether an erasure has started in this store since `at` was read, or was running when it was: one that is still
+   * running is seen by the count of those running, and one that has ended since by the counter, which its end moved.
+   * The one check every call that reads caller memory uses.
+   */
+  epochMoved(at) {
+    return this.erasuresRunning > 0 || this.epochNow() !== at;
+  }
+  /** A call's feed with the store's erasure counter: read once here, checked by the combine before any record is read. */
+  feedOf(feed, mayBeEmpty, epochAt) {
+    if (typeof feed !== "object" || feed === null || Array.isArray(feed)) {
+      throw new ValidationError2(
+        "materializeMany: feed must be an object with names, records and counts"
+      );
+    }
+    const f = feed;
+    return {
+      names: f.names,
+      records: f.records,
+      counts: f.counts,
+      ...mayBeEmpty === void 0 ? {} : { mayBeEmpty },
+      epoch: { moved: () => this.epochMoved(epochAt) }
+    };
+  }
+  /**
+   * The registry row of `ref`, read straight from the registry, not from a snapshot: a re-check must see a move. With
+   * `fingerprint`, the current generation's object is opened too (one tail read, as a pin of it makes), and its
+   * fingerprint is returned beside the row: a generation's number is identified by its row and its object, since a number
+   * can be taken again once its object is gone.
+   */
+  async currentRowOf(ref, fingerprint) {
+    const registry = this.requireRegistry("materializeMany");
+    if (fingerprint && this.crbmSource !== void 0) {
+      const crbm = this.crbmSource;
+      const at = await this.withRetries(() => crbm.pinGeneration(ref));
+      const colon = at?.version.indexOf(":") ?? -1;
+      if (at !== null && colon >= 0) {
+        return {
+          generation: at.generation,
+          token: at.version.slice(colon + 1),
+          fingerprint: at.fingerprint
+        };
+      }
+    }
+    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();
+    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?**
    *
@@ -1021,6 +1602,16 @@ var CloudRoaring = class _CloudRoaring {
    * is `dropSegment` / the `destroySegment`/`eraseNamespace` free functions.
    */
   async eraseSubject(id, options = {}) {
+    this.erasureEpoch++;
+    this.erasuresRunning++;
+    try {
+      return await this.eraseSubjectRun(id, options);
+    } finally {
+      this.erasuresRunning--;
+      this.erasureEpoch++;
+    }
+  }
+  async eraseSubjectRun(id, options) {
     const deps = this.lifecycleDeps("eraseSubject");
     requireScope(options, "eraseSubject");
     validateConcurrency(options.concurrency);
@@ -1252,24 +1843,26 @@ var CloudRoaring = class _CloudRoaring {
    * A refused load deletes the object it wrote before returning — it sits above `currentGen`, where generation
    * collection deliberately never looks — but only while the segment's registry row is unchanged or gone. Once
    * another write has changed the row, the generation number it holds may name another incarnation's live object,
-   * so it leaves the orphan rather than risk deleting live data. The orphan is an ordinary generation once a later
-   * one is current above it, and collection counts it within `keep`.
+   * so it leaves the orphan rather than risk deleting live data. No row's list names it, so it takes no place in a
+   * window, and a listing deletes it once a later generation is current above it.
    *
-   * **Collection is by name for the default `keep`.** With `keep` of 0 or 1, a load that found nothing above the
-   * pointer deletes the one generation its publish pushed out of the window and lists nothing; it lists the segment's
-   * objects on every sixteenth generation, and on any load that met an object above the pointer or whose check found
-   * the current generation's object gone, to take what the name-only passes leave, such as the generations an
-   * earlier, wider `keep` held. `keep` of 2 or more lists on every load. {@link LoadResult.collected} then names what
-   * the pass deleted by name, and that generation may have been gone already.
+   * **Collection is by name at any `keep` up to 64.** The segment's row records the generations a load keeps, so a load
+   * that found nothing above the pointer deletes the generations its publish pushed out of the window and lists
+   * nothing. It lists the segment's objects on every sixteenth generation, and on any load that met an object above the
+   * pointer or whose check found the current generation's object gone, to take what the name-only passes leave, such as
+   * an object a crashed load left below the pointer. A `keep` above 64 records no list and lists on every load, and so
+   * 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
    * 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 collection pass
-   * by listing that could not prove the segment was still the same one (`WriteConflictError`). That one, and a
-   * failure in the collection's own reads or deletes, can be raised **after** the publish already landed, so a throw
-   * does not by itself mean the load did not take effect — re-read the pointer rather than assuming. A collection by
-   * name that finds the segment changed returns an empty `collected` instead.
+   * (`IntegrityError`); a driver failure; and a fault in the collection's own reads, listing or deletes, or in the write
+   * that records the window (anything but a lost race). A collection fault can be raised **after** the publish already
+   * landed, so a throw does not by itself mean the load did not take effect — re-read the pointer rather than assuming.
+   * A collection, by name or by listing, that finds another writer has moved the row since the publish (a load, a
+   * rollback, a purge) stops and returns what it deleted in `collected`: a load that took effect does not throw for a
+   * race it won.
    *
    * **A `TransientError` from the registry write can leave the publish unsettled, and deletes nothing.** The
    * generation's object is sent again after a throttle where the backend allows it (a write id tells a first send
@@ -1341,7 +1934,11 @@ var CloudRoaring = class _CloudRoaring {
     validateSegmentRef(ref);
     const deps = this.lifecycleDeps("dropSegment");
     try {
-      return await dropSegment(ref, { registry: deps.registry, storage: deps.storage }, options);
+      return await dropSegment(
+        ref,
+        { registry: deps.registry, storage: deps.storage, clock: deps.clock, rng: deps.rng },
+        options
+      );
     } finally {
       if (options.dryRun !== true) this.engine.invalidate(ref);
     }
@@ -1374,7 +1971,11 @@ var CloudRoaring = class _CloudRoaring {
    */
   async setRetention(ref, policy) {
     validateSegmentRef(ref);
-    return setSegmentRetention(ref, { registry: this.requireRegistry("setRetention") }, policy);
+    return setSegmentRetention(
+      ref,
+      { registry: this.requireRegistry("setRetention"), clock: this.clock, rng: this.rng },
+      policy
+    );
   }
   /**
    * **The stored retention policy**, or `null` if the segment has none (or has no registry row, or is a
@@ -1393,7 +1994,11 @@ var CloudRoaring = class _CloudRoaring {
    */
   async clearRetention(ref) {
     validateSegmentRef(ref);
-    return clearSegmentRetention(ref, { registry: this.requireRegistry("clearRetention") });
+    return clearSegmentRetention(ref, {
+      registry: this.requireRegistry("clearRetention"),
+      clock: this.clock,
+      rng: this.rng
+    });
   }
   /**
    * **Run the retention sweep: retire every segment whose `expiresAt` has passed.** This is the call that acts on
@@ -1456,7 +2061,7 @@ var CloudRoaring = class _CloudRoaring {
   async retireExpired(options = {}) {
     const deps = this.lifecycleDeps("retireExpired");
     const result = await retireExpired(
-      { registry: deps.registry, storage: deps.storage },
+      { registry: deps.registry, storage: deps.storage, clock: this.clock, rng: this.rng },
       { ...options, now: options.now ?? this.clock.now() }
     );
     if (options.dryRun !== true) {
@@ -1466,6 +2071,57 @@ var CloudRoaring = class _CloudRoaring {
     }
     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.
@@ -1512,14 +2168,54 @@ 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) {
+  async pinSegment(ref, expiresAt, 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)"
       );
     }
-    const at = await this.withRetries(() => crbm.pinGeneration(ref));
+    let hold;
+    let take;
+    if (leaseUntil !== void 0) {
+      const registry = this.requireRegistry("pin({ leaseUntil })");
+      if (registry.capabilities().canWrite === false) {
+        throw new UnsupportedError(
+          "pin({ leaseUntil }) needs a registry that can write a row, and this store's cannot in this runtime"
+        );
+      }
+      const holder = this.mintHolder();
+      const deps = { registry, clock: this.clock, rng: this.rng };
+      const generationOf = (row) => named?.generation ?? row.currentGen;
+      hold = {
+        holder,
+        until: leaseUntil,
+        released: false,
+        done: false,
+        release: () => releaseLease(ref, deps, holder)
+      };
+      take = {
+        take: (row) => takeLease(ref, deps, {
+          holder,
+          generation: generationOf(row),
+          until: leaseUntil,
+          row,
+          current: named === void 0
+        })
+      };
+    }
+    let at;
+    try {
+      at = await this.withRetries(
+        () => named === void 0 ? crbm.pinGeneration(ref, take) : crbm.pinGenerationAt(ref, named, take)
+      );
+      if (hold !== void 0 && at === null) {
+        throw new NotFoundError(`segment "${ref.segment}" has no generation to lease`);
+      }
+    } catch (err) {
+      if (hold !== void 0) await hold.release().catch(() => void 0);
+      throw err;
+    }
     const pinnedAt = {
       generation: at?.generation ?? null,
       version: at?.version ?? null,
@@ -1532,12 +2228,20 @@ var CloudRoaring = class _CloudRoaring {
       clock: this.clock,
       metrics: this.metrics,
       materialize: (dest, ids, op, options) => this.materialize(dest, ids, op, options),
-      pinned: (r, e) => this.pinSegment(r, e),
+      pinned: (r, e, l, at2) => this.pinSegment(r, e, l, at2),
       combineEngine: (handles) => this.engineForCombine(handles),
       expiresAt,
-      pinnedAt
+      pinnedAt,
+      lease: hold
     });
   }
+  /** 16 hex digits from the store's `Rng`, which names the holder of one lease: unique, not secret. */
+  mintHolder() {
+    let id = "";
+    for (let i = 0; i < 4; i++)
+      id += Math.floor(this.rng.next() * 65536).toString(16).padStart(4, "0");
+    return id;
+  }
   /**
    * An engine reading every segment in `pins` at its pinned generation and everything else live, with the store's
    * retries, so a transient fault on a pinned read is retried as it would be on a live one.
@@ -1698,6 +2402,7 @@ var EMPTY_IDS = {
 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))
@@ -1714,6 +2419,7 @@ var CombineChunks = class {
 };
 var AS_CHUNKS = {
   none: NO_CHUNKS,
+  guard: guardChunks,
   failing: (err) => ({
     [Symbol.asyncIterator]: () => ({ next: () => Promise.reject(err) })
   }),
@@ -1722,6 +2428,39 @@ 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();
+  }
+};
 var makeSegment;
 var minting = false;
 var Segment = class _Segment {
@@ -1740,6 +2479,13 @@ var Segment = class _Segment {
    * pinned handle passed as an **operand** is still read at its pin rather than live.
    */
   pinnedAt;
+  /**
+   * The lease this handle holds, when it came from `pin({ leaseUntil })`; `undefined` otherwise. It reports what was
+   * taken and does not change when the lease ends: a read after `lease.until` (or after {@link Segment.release}) throws
+   * {@link LeaseExpiredError}.
+   */
+  lease;
+  leaseHold;
   static {
     makeSegment = (parts) => {
       minting = true;
@@ -1749,6 +2495,13 @@ var Segment = class _Segment {
         minting = false;
       }
     };
+    viewOf = (segment) => ({
+      ref: segment.ref,
+      pinnedAt: segment.pinnedAt,
+      expiresAt: segment.expiresAt,
+      leaseError: () => segment.leaseError(),
+      expired: () => segment.expired()
+    });
   }
   /**
    * Not constructible: a handle comes from {@link CloudRoaring.segment}, which wires it to the store's engine,
@@ -1769,6 +2522,10 @@ var Segment = class _Segment {
     this.combineEngine = parts.combineEngine;
     this.expiresAt = parts.expiresAt;
     this.pinnedAt = parts.pinnedAt;
+    this.leaseHold = parts.lease;
+    if (parts.lease !== void 0) {
+      this.lease = Object.freeze({ holder: parts.lease.holder, until: parts.lease.until });
+    }
     this.metricsOn = parts.metrics !== NOOP_METRICS;
   }
   /**
@@ -1797,11 +2554,20 @@ var Segment = class _Segment {
    * 0, so a pin of the old segment never reads the new one: what it has already read still answers, as the
    * instant it pinned, and anything it would have to fetch fails with `NotFoundError`, as a swept pin's does.
    *
-   * **It is a hold, not a lease.** Nothing here stops a collection deleting the generation underneath
-   * you: a pinned read deliberately does **not** heal forward, because silently serving a different generation
-   * is the one thing a pin exists to prevent, so it fails instead. Size `keep` to cover your longest pinned
-   * job — see [Generations and `keep`](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/loading.md#generations-and-keep) — or take the pin on a segment
-   * you are not collecting.
+   * **It is a hold, and `pin({ leaseUntil })` makes it a bounded one.** Without a lease nothing stops a collection
+   * deleting the generation underneath you: a pinned read deliberately does **not** heal forward, because silently
+   * serving a different generation is the one thing a pin exists to prevent, so it fails instead. Size `keep` to cover
+   * your longest pinned job — see [Generations and `keep`](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/loading.md#generations-and-keep) — take the pin on a segment
+   * you are not collecting, or lease it.
+   *
+   * **A lease** (`leaseUntil`: epoch **milliseconds**, after now and at most 14 days out) keeps the generation out of
+   * a load's collection until then, from any process, and the pin is taken with it: the lease is written to the segment's
+   * row before the object is opened. A read of the handle after the lease, or after {@link Segment.release}, throws
+   * {@link LeaseExpiredError} at every read site, including when the handle is an operand or an `exclude` of a combine
+   * or the target of an `*Into`, and never reads empty. A stream checks the lease each time it reads a chunk. A segment
+   * holds at most 64 live leases ({@link LeaseLimitError}). A collector holds a lease 60 seconds past its end, which covers
+   * clocks that differ by that much. Erasure, shred, drop and retention expiry ignore a lease. See
+   * [Hold a generation for a job](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/reading.md#hold-a-generation-for-a-job-a-lease).
    *
    * A segment with no current generation pins nothing and reads empty, exactly as it would unpinned. A pinned
    * segment whose row is later dropped or destroyed fails once it must open its object again, rather than go empty
@@ -1841,8 +2607,144 @@ var Segment = class _Segment {
    * 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.
    */
-  async pin() {
-    return this.pinned(this.ref, this.expiresAt);
+  async pin(options) {
+    this.assertLeases([this]);
+    const leaseUntil = this.leaseUntilOf("pin", options);
+    return this.pinned(this.ref, this.expiresAt, 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.
+   */
+  leaseUntilOf(op, options) {
+    if (options === void 0 || options === null) return void 0;
+    if (typeof options !== "object" || Array.isArray(options)) {
+      throw new ValidationError2(`${op}: options must be an object such as { leaseUntil }`);
+    }
+    const unknown = Object.keys(options).filter((k) => k !== "leaseUntil");
+    if (unknown.length > 0) {
+      throw new ValidationError2(
+        `${op}: unknown option${unknown.length > 1 ? "s" : ""} ${unknown.map((k) => `"${k}"`).join(", ")}; this version takes { leaseUntil } only`
+      );
+    }
+    const until = options.leaseUntil;
+    if (until === void 0) return void 0;
+    const now = this.clock.now();
+    if (typeof until !== "number" || !Number.isSafeInteger(until)) {
+      throw new ValidationError2(
+        `${op}: leaseUntil must be an integer epoch-MILLISECONDS; got ${String(until)}`
+      );
+    }
+    if (until <= now) {
+      throw new ValidationError2(
+        `${op}: leaseUntil (${until}) is not after now (${now}); it is epoch MILLISECONDS, so a value in seconds reads as long past. Use \`Date.now() + hours * 3_600_000\``
+      );
+    }
+    if (until > now + MAX_LEASE_MS) {
+      throw new ValidationError2(
+        `${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;
+  }
+  /**
+   * End this handle's lease now, so a load's collection may take its generation. Idempotent: a handle with no lease, or
+   * one already released, does nothing and makes no request. Every read of the handle after it throws
+   * {@link LeaseExpiredError} (reason `'released'`), including one already under way at its next chunk. A lease that has
+   * ended by its own time needs no release: this then makes no request either, and the registry row's entry is pruned
+   * by a later write. Otherwise it is one registry read and one write; a failure of either is thrown as the registry's own
+   * typed error, and the entry then holds until its time ends, `release()` being safe to call again.
+   */
+  async release() {
+    const hold = this.leaseHold;
+    if (hold === void 0) return;
+    hold.released = true;
+    if (hold.done) return;
+    if (this.clock.now() >= hold.until + LEASE_SKEW_MS) {
+      hold.done = true;
+      return;
+    }
+    await hold.release();
+    hold.done = true;
+  }
+  /**
+   * 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.
+   */
+  leaseError() {
+    const hold = this.leaseHold;
+    if (hold === void 0) return void 0;
+    const name = this.ref.namespace ? `${this.ref.namespace}/${this.ref.segment}` : this.ref.segment;
+    if (hold.released) {
+      return new LeaseExpiredError(
+        `the lease on segment "${name}" was released`,
+        hold.until,
+        "released"
+      );
+    }
+    if (this.clock.now() >= hold.until) {
+      return new LeaseExpiredError(
+        `the lease on segment "${name}" ended; a read of a handle past its lease throws, never reads empty`,
+        hold.until,
+        "expired"
+      );
+    }
+    return void 0;
+  }
+  /**
+   * 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.
+   */
+  assertLeases(handles) {
+    for (const h of handles) {
+      const err = h.leaseError();
+      if (err !== void 0) throw err;
+    }
+  }
+  /**
+   * Reopen a generation a pin named earlier, as a pinned handle like the one {@link Segment.pin} returns, held at
+   * `at.generation` instead of the current one. Pass what the earlier pin recorded, `{ generation, fingerprint }`
+   * 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
+   * `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),
+   * 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
+   * collection can delete it, which is sized by `keep` on every writer, or held by `options.leaseUntil` (see
+   * {@link PinOptions} and {@link Segment.pin}). A leased `pinAt` writes the lease before it verifies the object, and
+   * releases it if the verify fails; for a generation below the pointer, a collector that read the row before the lease
+   * landed can still delete the generation inside its own round trip, and the handle then fails with `NotFoundError`
+   * like any swept pin. A leased handle is checked at every read site as a leased `pin()` is. With a registry it costs one row read and one tail read,
+   * and a leased `pinAt` one conditional write to the row besides; the handle
+   * 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.
+   */
+  async pinAt(at, options) {
+    this.assertLeases([this]);
+    const { generation, fingerprint } = at ?? {};
+    const unknown = typeof at === "object" && at !== null ? Object.keys(at).filter((k) => k !== "generation" && k !== "fingerprint") : [];
+    if (unknown.length > 0) {
+      throw new ValidationError2(
+        `pinAt: unknown option${unknown.length > 1 ? "s" : ""} ${unknown.map((k) => `"${k}"`).join(", ")}; this version takes { generation, fingerprint } only`
+      );
+    }
+    if (typeof generation !== "number" || !Number.isSafeInteger(generation) || generation < 0 || typeof fingerprint !== "string" || !/^\d+:\d+$/.test(fingerprint)) {
+      throw new ValidationError2(
+        "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"
+      );
+    }
+    const leaseUntil = this.leaseUntilOf("pinAt", options);
+    return this.pinned(this.ref, this.expiresAt, leaseUntil, { generation, fingerprint });
   }
   /**
    * An opaque string that names this handle's segment, namespace included: two handles of one segment have the
@@ -1886,6 +2788,7 @@ var Segment = class _Segment {
    * awaiting.
    */
   refuseIfExpired(op, dest, operands) {
+    this.assertLeases([this, dest, ...operands]);
     const stale = [];
     for (const seg of [this, dest, ...operands]) {
       if (seg.expired())
@@ -1897,6 +2800,10 @@ var Segment = class _Segment {
       );
     }
   }
+  /** `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) {
+    return handles.some((h) => h.leaseHold !== void 0) ? out.guard(result, () => this.assertLeases(handles)) : result;
+  }
   /**
    * Time an op with the injected clock and emit an `op` metric on completion (success or throw). Skipped
    * entirely when no sink is wired, so the default path pays nothing.
@@ -1912,6 +2819,8 @@ var Segment = class _Segment {
   }
   /** Membership: one chunk — the cache, else one ranged GET. Throws {@link ValidationError} on a bad id. */
   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));
   }
@@ -1934,6 +2843,8 @@ var Segment = class _Segment {
    * structure is checked.
    */
   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));
   }
@@ -1952,6 +2863,7 @@ var Segment = class _Segment {
    * ```
    */
   async stat() {
+    this.assertLeases([this]);
     if (this.expired()) return { generation: null, cardinality: 0 };
     return this.engine.stat(this.ref);
   }
@@ -1971,16 +2883,70 @@ var Segment = class _Segment {
    * without checking its options, as every read of one does.
    */
   iterate(options) {
+    const lease = this.leaseError();
+    if (lease !== void 0) return failing(lease);
     if (this.expired()) return EMPTY_IDS;
     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;
     const bounds = none ? void 0 : range;
-    return withBatches(engine.iterate(ref, bounds), () => engine.iterateBatches(ref, bounds));
+    const stream = withBatches(
+      engine.iterate(ref, bounds),
+      () => engine.iterateBatches(ref, bounds)
+    );
+    return this.leaseHold === void 0 ? stream : guardIds(stream, () => this.assertLeases([this]));
+  }
+  /**
+   * **Pinned handles only.** The ids at 1-based ranks `n`, `2n`, `3n` …, counted over the ids in `(after, through]`
+   * when a range is given, ascending: `everyNth(1000)` yields the 1,000th id, then the 2,000th, and so on. A last
+   * partial window yields nothing, so a caller cutting a send into windows of `n` appends its own final end.
+   *
+   * It places each boundary from the per-chunk counts the pin already holds and reads only the chunks that hold one,
+   * each once however many boundaries it holds, so it reads at most one chunk per boundary and never more chunks
+   * than the object has. A range with `after` inside a chunk reads that chunk too, to count the ids at or below
+   * `after`, even when fewer than `n` ids remain above it; when the chunks in range hold fewer than `n` ids in all,
+   * nothing is fetched. `through` stops the read and no chunk past it is read, though a `through` inside a chunk may read that last chunk and
+   * yield nothing from it. The reads and the read-ahead window are
+   * those of {@link Segment.iterate}, and the per-op budget is charged before the first fetch, with an upper bound on
+   * the chunks the read can take. A pinned read after the generation is swept throws {@link NotFoundError}.
+   *
+   * The ranks come from the index's counts, which are trusted as {@link Segment.count} trusts them. A chunk that is
+   * read must hold the number of ids its index says, or the read throws {@link IntegrityError}; a chunk that is not
+   * read is not checked, so an index that is wrong about one, and, on an unencrypted object, still adds up to the footer's
+   * total, moves the ids after it to the wrong ranks. An encrypted object's index is authenticated and bound to the
+   * object, so a wrong count there needs the key.
+   *
+   * 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.
+   *
+   * ```ts
+   * const audience = await store.segment('audience').pin();
+   * const ends: number[] = [];
+   * for await (const id of audience.everyNth(1_000)) ends.push(id); // the end of each window of 1,000
+   * ```
+   */
+  everyNth(n, options) {
+    const lease = this.leaseError();
+    if (lease !== void 0) return failing(lease);
+    if (this.expired()) return EMPTY_IDS;
+    if (this.pinnedAt === void 0) {
+      return failing(
+        new UnsupportedError(
+          "everyNth needs a pinned handle: a live handle can place a rank by one generation and read it from another. Call `pin()` first."
+        )
+      );
+    }
+    const stream = this.engine.everyNth(
+      this.ref,
+      n,
+      options == null ? void 0 : rangeOf(options)
+    );
+    return this.leaseHold === void 0 ? stream : guardIdIterable(stream, () => this.assertLeases([this]));
   }
   /**
    * The options a combine hands the engine, read once, when it is called ({@link readOptions}), with the `exclude`
-   * it was given, already reduced to its live handles ({@link liveExcludes}) and mapped down to the plain refs
+   * it was given ({@link excludesOf}) and mapped down to the plain refs
    * `core` takes. A method rather than a module function because `ref` is class-private — the encapsulation is
    * worth more than the free function.
    *
@@ -1996,18 +2962,35 @@ var Segment = class _Segment {
     };
   }
   /**
-   * The handles in `options.exclude` that have not expired. **An expired exclusion excludes nothing**, in every
-   * combine, so it is dropped here, before the engine is asked for anything: it is never fetched, never
-   * checked for absence, and never counted in the pin-consistency check. `exclude` is read once, so a getter sees
-   * one call.
-   *
-   * With no `exclude` this is one property read and a shared empty list, and with none expired it returns the
-   * caller's own array, so the common case allocates nothing.
+   * The handles in `options.exclude`, read once so a getter sees one call. With none this is one property read and
+   * a shared empty list; otherwise it is the caller's own array, so the common case allocates nothing.
    */
-  liveExcludes(options) {
+  excludesOf(options) {
     const exclude = options?.exclude;
-    if (exclude == null || exclude.length === 0) return NO_SEGMENTS;
-    return exclude.some((e) => e.expired()) ? exclude.filter((e) => !e.expired()) : 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.`
+    );
   }
   /**
    * Chunk-skipping intersection: stream the ids in **this** segment AND every segment in `others`, ascending.
@@ -2022,8 +3005,16 @@ var Segment = class _Segment {
     return this.intersectAs(AS_IDS, others, options);
   }
   intersectAs(out, others, options) {
+    const exclude = this.excludesOf(options);
+    const handles = [this, ...others, ...exclude];
+    try {
+      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;
-    const exclude = this.liveExcludes(options);
     let engine;
     try {
       engine = this.combineEngine([this, ...others, ...exclude]) ?? this.engine;
@@ -2032,7 +3023,7 @@ var Segment = class _Segment {
     }
     const refs = [this.ref, ...others.map((o) => o.ref)];
     const opts = this.refsIn(options, exclude);
-    return out.intersect(engine, refs, opts);
+    return this.guarded(out, handles, out.intersect(engine, refs, opts));
   }
   /**
    * Materialize `this ∩ others…` (minus `exclude`) as a **new generation of `dest`** — `dest`'s previous contents
@@ -2081,17 +3072,24 @@ var Segment = class _Segment {
     return this.unionAs(AS_IDS, others, options);
   }
   unionAs(out, others, options) {
+    const exclude = this.excludesOf(options);
+    const handles = [this, ...others, ...exclude];
+    try {
+      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) {
-      const exclude2 = this.liveExcludes(options);
-      return exclude2.length > 0 ? this.andNotAs(out, [...exclude2], options) : this.unionAs(out, [], options);
+      return exclude.length > 0 ? this.andNotAs(out, [...exclude], options) : this.unionAs(out, [], options);
     }
     if (live.length !== others.length) return this.unionAs(out, live, options);
-    const exclude = this.liveExcludes(options);
     let engine;
     try {
       engine = this.combineEngine([this, ...others, ...exclude]) ?? this.engine;
@@ -2100,7 +3098,7 @@ var Segment = class _Segment {
     }
     const refs = [this.ref, ...others.map((o) => o.ref)];
     const opts = this.refsIn(options, exclude);
-    return out.union(engine, refs, opts);
+    return this.guarded(out, handles, out.union(engine, refs, opts));
   }
   /** Materialize `this ∪ others…` (minus `exclude`) as a **new generation of `dest`** — see {@link intersectInto}. */
   async unionInto(dest, others, options) {
@@ -2124,9 +3122,9 @@ 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` excludes nothing, and is skipped without being read; if every one has
-   * expired the result is `this` whole. An expired `this` is empty. `exclude` on `intersect` and `union` follows
-   * the same rule.
+   * 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.
@@ -2135,12 +3133,15 @@ var Segment = class _Segment {
     return this.andNotAs(AS_IDS, excludes, options);
   }
   andNotAs(out, excludes, options) {
-    if (this.expired()) return out.none;
-    const liveExcludes = excludes.filter((e) => !e.expired());
-    if (liveExcludes.length === 0 && excludes.length > 0) {
-      return this.unionAs(out, [], options == null ? void 0 : readOptions(options));
+    const handles = [this, ...excludes];
+    try {
+      this.assertLeases(handles);
+    } catch (err) {
+      return out.failing(err);
     }
-    if (liveExcludes.length !== excludes.length) return this.andNotAs(out, liveExcludes, options);
+    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;
@@ -2150,7 +3151,7 @@ var Segment = class _Segment {
     const base = this.ref;
     const refs = excludes.map((o) => o.ref);
     const opts = options == null ? void 0 : readOptions(options);
-    return out.andNot(engine, base, refs, opts);
+    return this.guarded(out, handles, out.andNot(engine, base, refs, opts));
   }
   /** Materialize `this \ (excludes…)` as a **new generation of `dest`** — see {@link intersectInto}. */
   async andNotInto(dest, excludes, options) {
@@ -2174,6 +3175,7 @@ var Segment = class _Segment {
    * the lose-zone).
    */
   async costReport(options) {
+    this.assertLeases([this]);
     const canMeasure = this.engine.supportsStorageSize;
     const size = canMeasure ? await this.engine.segmentSize(this.ref) : null;
     const refreshMs = this.engine.pointerRefreshMs;
@@ -2202,25 +3204,36 @@ export {
   InProcessKeystore,
   IntegrityError3 as IntegrityError,
   KeyUnavailableError,
+  LEASE_SKEW_MS2 as LEASE_SKEW_MS,
+  LeaseExpiredError2 as LeaseExpiredError,
+  LeaseLimitError,
   LocalFsStorage,
+  MAX_LEASES_PER_SEGMENT,
+  MAX_LEASE_MS2 as MAX_LEASE_MS,
   MIN_EXPIRES_AT_MS2 as MIN_EXPIRES_AT_MS,
+  MemoryOperand,
   MemoryStorage,
   NodeAead,
-  NotFoundError,
+  NotFoundError2 as NotFoundError,
   ONE_REDIS_HA_CLUSTER,
   RecordingAuditSink,
   Segment,
+  StaleOperandError,
   TransientError,
   UnsupportedError2 as UnsupportedError,
   ValidationError3 as ValidationError,
   WriteConflictError2 as WriteConflictError,
   aadFor,
+  deserializePortable,
   destroySegment,
   eraseNamespace,
   excludingReservedRows2 as excludingReservedRows,
   isCloudRoaringError,
   isIntegrityError,
+  isLeaseExpiredError,
+  isLeaseLimitError,
   isNotFoundError,
+  isStaleOperandError,
   isTransientError,
   isValidationError,
   isWriteConflictError,