@cloudbitmaps/core 0.16.0 → 0.18.0

package/dist/index.js

@@ -5,10 +5,17 @@ import {
   DEFAULT_NAMESPACE,
   IntegrityError,
   KeyUnavailableError,
+  LEASE_SKEW_MS,
+  LeaseExpiredError,
+  LeaseLimitError,
+  MAX_KEPT_GENERATIONS,
+  MAX_LEASES_PER_SEGMENT,
+  MAX_LEASE_MS,
   MAX_METADATA_BYTES,
   MAX_NAME_LENGTH,
   NotFoundError,
   RESERVED_NAMESPACE_PREFIX,
+  StaleOperandError,
   TransientError,
   UnsupportedError,
   ValidationError,
@@ -25,25 +32,36 @@ import {
   encodeNameForPath,
   encodedNameLength,
   entropyIsAvailable,
+  heldGenerations,
   incarnationOf,
   isCloudRoaringError,
   isIntegrityError,
+  isLeaseExpiredError,
+  isLeaseLimitError,
+  isLive,
   isNotFoundError,
   isReservedNamespace,
+  isStaleOperandError,
   isStorageBackend,
   isTransientError,
   isValidationError,
   isWriteConflictError,
+  leaseChurn,
   mapWithConcurrency,
   metadataBytes,
   metadataFromBytes,
   namespacePathPart,
   newIncarnationToken,
+  nextKept,
   nextRegistryToken,
+  onlyLeasesDiffer,
   parseRegistryEnvelope,
   recordFromNew,
+  releaseLease,
   sameIncarnation,
   serializeRegistryEnvelope,
+  takeLease,
+  usableKeptGens,
   validateChunkKeyOrder,
   validateChunkRef,
   validateNewRegistryRecord,
@@ -52,7 +70,7 @@ import {
   validateUserNamespace,
   validateUserRef,
   webCryptoEntropy
-} from "./chunk-LFUNPMXZ.js";
+} from "./chunk-CCP4U32U.js";
 
 // src/core/bit-route.ts
 var U32_MAX = 4294967295;
@@ -103,6 +121,42 @@ async function collectWithinBudget(source, budget, op) {
   return out;
 }
 
+// src/core/chunk-checks.ts
+function assertChunkKeyInRange(k) {
+  if (!Number.isInteger(k) || k < 0 || k >= CHUNK_COUNT) {
+    throw new IntegrityError(`chunk key from a tier is out of range: ${k}`);
+  }
+}
+function assertChunkCardinalityInRange(c) {
+  if (!Number.isInteger(c) || c < 1 || c > CHUNK_COUNT) {
+    throw new IntegrityError(`chunk cardinality from a tier is out of range: ${c}`);
+  }
+}
+function checkedChunkKeys(listed) {
+  const keys = [...listed];
+  for (const k of keys) assertChunkKeyInRange(k);
+  keys.sort((a, b) => a - b);
+  for (let i = 1; i < keys.length; i++) {
+    if (keys[i] === keys[i - 1]) {
+      throw new IntegrityError(`chunk key from a tier is listed twice: ${keys[i]}`);
+    }
+  }
+  return keys;
+}
+function assertChunkPayloadInRange(bitmap, chunkKey) {
+  const max = bitmap.maximum?.();
+  if (max !== void 0 && max > MAX_REMAINDER) {
+    throw new IntegrityError(
+      `chunk ${chunkKey} payload holds value ${max}, outside the 16-bit remainder range [0, ${MAX_REMAINDER}] \u2014 the stored object is corrupt or was not written by this codec`
+    );
+  }
+}
+function decodeChunkBytes(codec, bytes, chunkKey, maxBitmapBytes) {
+  const bitmap = codec.safeDeserialize(bytes, maxBitmapBytes);
+  assertChunkPayloadInRange(bitmap, chunkKey);
+  return bitmap;
+}
+
 // src/core/chunk-stream.ts
 var ChunkStream = class {
   iterator;
@@ -332,6 +386,8 @@ var CountingMetricsSink = class _CountingMetricsSink {
         op.totalMs += event.ms;
         break;
       }
+      case "advisory":
+        break;
       default: {
         const exhaustive = event;
         return exhaustive;
@@ -530,7 +586,7 @@ var SegmentEngine = class {
     if (cardinalities) {
       let total2 = 0;
       for (const [k, n] of cardinalities) {
-        this.assertChunkKeyInRange(k);
+        assertChunkKeyInRange(k);
         total2 += n;
       }
       return total2;
@@ -675,6 +731,102 @@ var SegmentEngine = class {
       chunks.close();
     }
   }
+  /**
+   * The ids at 1-based ranks `n`, `2n`, `3n` … counted over the ids in `range`, ascending. The rank of each boundary
+   * is placed from the index's per-chunk counts, so only the chunks that hold a boundary are read, each once however
+   * many boundaries it holds, through the same coalesced stream, window and budget unit as {@link iterate}. A range with
+   * `after` inside a chunk reads that chunk too, to count the ids at or below `after`. A last partial window yields
+   * nothing.
+   *
+   * The counts place ids, and are trusted as `count()` trusts them: a chunk that is read must decode to the size its
+   * index says, or the read throws {@link IntegrityError} (invariant 5), but a chunk that is not read is not checked, so
+   * an index that lies consistently about one (on an unencrypted object, the sum still matches the footer's total,
+   * which opening the object checks before any boundary is placed) shifts the ranks after it. An encrypted object's
+   * index is authenticated and bound to the object, so a wrong count there needs the key. The index and the chunks must come from one
+   * generation (invariant 3): the caller reads through a source that holds one, a pinned one, and a source with no
+   * per-chunk counts is refused.
+   *
+   * Nothing is fetched when the chunks in range hold fewer than `n` ids. The budget is charged before the first fetch
+   * with an upper bound, the cut chunk plus one chunk per boundary the counts allow (capped by the chunks in range),
+   * which can exceed the chunks actually read. A range that cuts its first chunk reads it even when the ids above
+   * `after` turn out to be fewer than `n`, and one that cuts its last chunk may read it and yield nothing.
+   */
+  async *everyNth(seg, n, range) {
+    if (!Number.isSafeInteger(n) || n < 1) {
+      throw new ValidationError(`n must be a positive integer; got ${String(n)}`);
+    }
+    const epoch = this.invalidations;
+    const w = windowOf(range);
+    if (w === "empty") return;
+    const { loKey, loRem, hiKey, hiRem } = w ?? WHOLE_ID_SPACE;
+    if (this.storage.cardinalities === void 0) {
+      throw new UnsupportedError("everyNth needs a storage source that reports per-chunk counts");
+    }
+    const counts = await this.storage.cardinalities(seg);
+    if (counts === null) return;
+    const keys = keysWithin(
+      [...counts.keys()].sort((a, b) => a - b),
+      { loKey, loRem, hiKey, hiRem }
+    );
+    for (const k of keys) {
+      assertChunkKeyInRange(k);
+      const c = counts.get(k);
+      assertChunkCardinalityInRange(c);
+    }
+    const gen = await this.cacheVersion(seg);
+    const cutsFirst = loRem > 0 && keys[0] === loKey;
+    let upper = 0;
+    for (const k of keys) upper += counts.get(k);
+    if (upper < n) return;
+    const cut = cutsFirst ? 1 : 0;
+    checkBudget(this.budget, cut + Math.min(keys.length - cut, Math.floor(upper / n)), "everyNth");
+    let first;
+    let below = 0;
+    if (cutsFirst) {
+      first = this.chunkRemainders(
+        await this.storageChunk({ ...seg, chunkKey: loKey }, gen),
+        loKey,
+        counts
+      );
+      below = firstAbove(first, loRem - 1);
+    }
+    const hits = [];
+    let before = 0;
+    for (const key of keys) {
+      const skipped = key === loKey && cutsFirst ? below : 0;
+      const size = counts.get(key) - skipped;
+      const next = (Math.floor(before / n) + 1) * n;
+      if (next <= before + size) hits.push({ key, index: skipped + next - before - 1 });
+      before += size;
+    }
+    if (hits.length === 0) return;
+    const streamed = hits.filter((h) => !(cutsFirst && h.key === loKey)).map((h) => h.key);
+    const chunks = streamed.length > 0 ? this.chunkSequence(seg, streamed, gen, epoch) : void 0;
+    try {
+      for (const { key, index } of hits) {
+        const rem = cutsFirst && key === loKey && first !== void 0 ? first : this.chunkRemainders(await chunks.take(key), key, counts);
+        const base = key * CHUNK_COUNT;
+        for (let i = index; i < rem.length; i += n) {
+          const remainder = rem[i] & MAX_REMAINDER;
+          if (key === hiKey && remainder > hiRem) return;
+          yield base + remainder;
+        }
+      }
+    } finally {
+      chunks?.close();
+    }
+  }
+  /** A chunk's remainders ascending, once its size is confirmed against the index's count for it (invariant 5). */
+  chunkRemainders(chunk, chunkKey, counts) {
+    const expected = counts.get(chunkKey);
+    if (chunk === null || chunk.size !== expected) {
+      const got = chunk === null ? "no bytes" : `${chunk.size} ids`;
+      throw new IntegrityError(
+        `chunk ${chunkKey} holds ${got}, but the object's index says ${expected}`
+      );
+    }
+    return chunk.toUint32Array ? chunk.toUint32Array() : Uint32Array.from(chunk);
+  }
   /**
    * `segs[0] ∩ segs[1] ∩ …`, minus every id in `options.exclude` — streamed ascending.
    *
@@ -1041,7 +1193,7 @@ var SegmentEngine = class {
     }
     return streamed.stream.take(chunkKey).then((read) => {
       if (read.bytes === null) return null;
-      const bitmap = this.decodeChunk(read.bytes, chunkKey);
+      const bitmap = decodeChunkBytes(this.codec, read.bytes, chunkKey, this.maxBitmapBytes);
       if (this.cache && !streamed.invalidated) {
         const version = this.streamedVersion(streamed.gen, read.version);
         if (version !== null) {
@@ -1063,52 +1215,9 @@ var SegmentEngine = class {
   chunkCacheKey(ref, version) {
     return version === void 0 ? chunkRefKey(ref) : chunkGenKey(ref, version);
   }
-  /** The segment's chunk keys, ascending — a shape read off the index, no payload. Keys are untrusted (invariant 5). */
+  /** The segment's chunk keys, ascending, checked as untrusted tier data. */
   async chunkKeys(seg) {
-    const keys = [...await this.storage.listChunkKeys(seg)];
-    for (const k of keys) this.assertChunkKeyInRange(k);
-    keys.sort((a, b) => a - b);
-    for (let i = 1; i < keys.length; i++) {
-      if (keys[i] === keys[i - 1]) {
-        throw new IntegrityError(`chunk key from a tier is listed twice: ${keys[i]}`);
-      }
-    }
-    return keys;
-  }
-  /**
-   * Tier-derived keys are untrusted (invariant 5) — fail fast on a corrupt/out-of-range key rather than
-   * letting it flow into the id-routing step and produce a bogus id.
-   */
-  assertChunkKeyInRange(k) {
-    if (!Number.isInteger(k) || k < 0 || k >= CHUNK_COUNT) {
-      throw new IntegrityError(`chunk key from a tier is out of range: ${k}`);
-    }
-  }
-  /**
-   * The other half of invariant 5: a chunk payload holds **remainders** — 16-bit offsets within one chunk — so
-   * every value must be `<= 0xffff`.
-   *
-   * Nothing upstream establishes that. The byte cap bounds *size*, and CRC/AEAD prove the bytes are the bytes
-   * that were written — which anyone able to write the bucket satisfies trivially. A value `>= 65536` would then
-   * reach the id-routing step, which masks it (`remainder & 0xffff`) and emits a **fabricated id belonging to a different
-   * chunk's id space**: indistinguishable from real data, inflating `count()` and creating spurious `intersect`
-   * matches.
-   *
-   * Costs one `maximum()` per chunk, not per id — `maximum` is optional on the codec seam precisely so a codec
-   * that cannot answer in O(1) opts out instead of making the read path walk every value.
-   *
-   * One value stands for all of them only because the decode is structurally checked. Roaring answers `maximum()`
-   * from its last container, so a payload listing its containers out of order would report the wrong one's
-   * largest value and pass here while holding values above 65,535. The codec's `safeDeserialize` refuses that
-   * payload, and every other shape that would make this answer wrong, before it reaches this check.
-   */
-  assertChunkPayloadInRange(bitmap, chunkKey) {
-    const max = bitmap.maximum?.();
-    if (max !== void 0 && max > MAX_REMAINDER) {
-      throw new IntegrityError(
-        `chunk ${chunkKey} payload holds value ${max}, outside the 16-bit remainder range [0, ${MAX_REMAINDER}] \u2014 the stored object is corrupt or was not written by this codec`
-      );
-    }
+    return checkedChunkKeys(await this.storage.listChunkKeys(seg));
   }
   /**
    * Refuse a combine whose operand names a segment that was never created.
@@ -1222,15 +1331,6 @@ var SegmentEngine = class {
     entry.read.then(settled2, settled2);
     return entry.read;
   }
-  /**
-   * A chunk's stored bytes decoded under the size cap (invariant 5) and range-checked: the one place a chunk becomes a
-   * bitmap, whether its bytes came from a request of its own or from a stream of coalesced ranges.
-   */
-  decodeChunk(bytes, chunkKey) {
-    const bitmap = this.codec.safeDeserialize(bytes, this.maxBitmapBytes);
-    this.assertChunkPayloadInRange(bitmap, chunkKey);
-    return bitmap;
-  }
   /**
    * One chunk, decoded, range-checked and cached. A source with `getChunks` is read through it, as a one-key stream, so
    * a `storage.get` is reported only for a request that was sent (a chunk the source holds in memory sends none);
@@ -1277,7 +1377,7 @@ var SegmentEngine = class {
       }
     }
     if (!bytes) return null;
-    const bitmap = this.decodeChunk(bytes, ref.chunkKey);
+    const bitmap = decodeChunkBytes(this.codec, bytes, ref.chunkKey, this.maxBitmapBytes);
     if (key !== "" && this.openReads.get(cacheKey)?.token === token) this.cache?.set(key, bitmap);
     return bitmap;
   }
@@ -1444,63 +1544,121 @@ async function nextLoadGeneration(ref, deps, row) {
 }
 var LIST_COLLECTION_CADENCE = 16;
 async function gcOrphanGenerations(ref, deps, options = {}) {
+  return (await listingPass(ref, deps, { keep: options.keep })).deleted;
+}
+async function listingPass(ref, deps, options) {
   const keep = options.keep ?? 1;
+  const quiet = options.quiet === true;
   if (!Number.isInteger(keep) || keep < 0) {
     throw new ValidationError(`keep must be a non-negative integer; got ${String(keep)}`);
   }
   const record = await deps.registry.get(ref);
-  if (record === null) return [];
+  if (record === null) return { deleted: [], kept: [], complete: true };
   const current = record.currentGen;
   const seen = /* @__PURE__ */ new Set();
   for await (const key of deps.storage.list(ref)) seen.add(key.generation);
   const gens = [...seen];
   const after = await deps.registry.get(ref);
-  if (after === null)
+  if (after === null) {
+    if (quiet) return { deleted: [], kept: [], complete: false };
     throw new WriteConflictError(`registry row for segment ${ref.segment} was purged mid-pass`);
+  }
   if (record.status === "destroyed" && after.token !== record.token) {
+    if (quiet) return { deleted: [], kept: [], complete: false };
     throw new WriteConflictError(
       `segment ${ref.segment} changed incarnation while its generations were being listed`
     );
   }
   const cutoff = current === null || after.currentGen === null ? null : Math.min(current, after.currentGen);
-  const stillCollectable = async () => {
+  const named = record.status === "destroyed" ? void 0 : usableKeptGens(after);
+  const protect = options.protect === void 0 || named === void 0 ? void 0 : /* @__PURE__ */ new Set([...options.protect, ...named]);
+  const stillCollectable = async (generation) => {
     const still = await deps.registry.get(ref);
     if (still === null) {
+      if (quiet) return "stop";
       throw new WriteConflictError(`registry row for segment ${ref.segment} was purged mid-pass`);
     }
     const ok = record.status === "destroyed" ? still.token === after.token : cutoff === null || still.currentGen !== null && still.currentGen >= cutoff;
-    if (!ok) {
+    const now = protect === void 0 ? void 0 : usableKeptGens(still);
+    const unnamed = protect === void 0 || record.status === "destroyed" || now !== void 0 && !now.includes(generation);
+    if (!ok || !unnamed) {
+      if (quiet) return "stop";
       throw new WriteConflictError(
         `segment ${ref.segment} changed incarnation while its generations were being collected`
       );
     }
+    if (guard !== void 0 && heldGenerations(still, guard.now()).has(generation)) return "skip";
+    return "delete";
   };
-  const toDelete = record.status === "destroyed" ? gens.sort((a, b) => a - b) : cutoff === null ? (
+  const guard = record.status === "destroyed" ? void 0 : options.leases;
+  const held = guard === void 0 ? void 0 : heldGenerations(after, guard.now());
+  const below = record.status === "destroyed" || cutoff === null ? [] : gens.filter((g) => g < cutoff).sort((a, b) => b - a);
+  const candidates = record.status === "destroyed" ? gens.sort((a, b) => a - b) : cutoff === null ? (
     // No Storage pointer yet, so "below current" selects nothing and there is nothing safe to infer: an object
     // here is either a load about to publish or an orphan we cannot tell apart from it. Deleting would race
     // that publish into a dangling pointer. It is collected once a pointer exists.
     []
+  ) : protect !== void 0 ? (
+    // The row's list is the window: everything below the pointer it does not name is garbage.
+    below.filter((g) => !protect.has(g))
   ) : (
     // Delete generations below the cutoff, except the newest `keep` of them (the grace window).
-    gens.filter((g) => g < cutoff).sort((a, b) => b - a).slice(keep)
+    below.slice(keep)
   );
+  const leasedSpared = new Set(candidates.filter((g) => held?.has(g) === true));
+  const toDelete = candidates.filter((g) => !leasedSpared.has(g));
+  const done = [];
   for (const generation of toDelete) {
-    await stillCollectable();
+    const verdict = await stillCollectable(generation);
+    if (verdict === "stop") return { deleted: done, kept: [], complete: false };
+    if (verdict === "skip") {
+      leasedSpared.add(generation);
+      continue;
+    }
     await deps.storage.delete({ namespace: ref.namespace, segment: ref.segment, generation });
+    done.push(generation);
   }
-  return toDelete;
+  const deleted = new Set(done);
+  return {
+    deleted: done,
+    kept: below.filter((g) => !deleted.has(g) && !leasedSpared.has(g)).reverse(),
+    complete: true
+  };
 }
 async function collectAfterLoad(ref, deps, options) {
-  const { generation, keep, byName, proveCurrent } = options;
+  const { generation, keep, byName, currentGone, kept, proveCurrent, leases } = options;
   if (keep >= generation) return [];
+  const list = kept?.list;
+  if (list === void 0 || currentGone === true)
+    return reconcile(ref, deps, { keep, kept, leases });
   const periodic = generation % LIST_COLLECTION_CADENCE === 0;
-  if (byName && keep <= 1 && !periodic) {
-    if (keep === 1 && proveCurrent !== void 0 && !await objectIsThere(deps.storage, proveCurrent)) {
-      return gcOrphanGenerations(ref, deps, { keep });
+  if (byName && !periodic) {
+    if (keep >= 1 && proveCurrent !== void 0 && !await objectIsThere(deps.storage, proveCurrent)) {
+      return reconcile(ref, deps, { keep, kept, leases });
+    }
+    return deleteEvicted(ref, deps, { generation, evict: kept.evict, leases });
+  }
+  return (await listingPass(ref, deps, { keep, protect: list, quiet: true, leases })).deleted;
+}
+async function reconcile(ref, deps, options) {
+  const { keep, kept, leases } = options;
+  const {
+    deleted,
+    kept: present,
+    complete
+  } = await listingPass(ref, deps, { keep, quiet: true, leases });
+  const token = kept?.token;
+  if (complete && token !== void 0 && keep <= MAX_KEPT_GENERATIONS && !sameList(kept?.list, present)) {
+    try {
+      await deps.registry.compareAndSwap(ref, token, { keptGens: present });
+    } catch (err) {
+      if (!(err instanceof WriteConflictError)) throw err;
     }
-    return collectByName(ref, deps, { generation, keep });
   }
-  return gcOrphanGenerations(ref, deps, { keep });
+  return deleted;
+}
+function sameList(a, b) {
+  return a !== void 0 && a.length === b.length && a.every((g, i) => g === b[i]);
 }
 async function objectIsThere(storage, key) {
   try {
@@ -1510,21 +1668,20 @@ async function objectIsThere(storage, key) {
     return false;
   }
 }
-async function collectByName(ref, deps, options) {
-  const { generation, keep } = options;
-  if (!Number.isInteger(keep) || keep < 0 || keep > 1) {
-    throw new ValidationError(`collecting by name needs a keep of 0 or 1; got ${String(keep)}`);
+async function deleteEvicted(ref, deps, options) {
+  const deleted = [];
+  for (const generation of options.evict) {
+    const still = await deps.registry.get(ref);
+    if (still === null || still.currentGen === null || still.currentGen < options.generation) break;
+    const named = usableKeptGens(still);
+    if (named === void 0 || generation >= still.currentGen || named.includes(generation)) break;
+    if (options.leases !== void 0 && heldGenerations(still, options.leases.now()).has(generation)) {
+      continue;
+    }
+    await deps.storage.delete({ namespace: ref.namespace, segment: ref.segment, generation });
+    deleted.push(generation);
   }
-  const evicted = generation - keep - 1;
-  if (evicted < 0) return [];
-  const still = await deps.registry.get(ref);
-  if (still === null || still.currentGen === null || still.currentGen < generation) return [];
-  await deps.storage.delete({
-    namespace: ref.namespace,
-    segment: ref.segment,
-    generation: evicted
-  });
-  return [evicted];
+  return deleted;
 }
 
 // src/core/reader-defaults.ts
@@ -2030,13 +2187,30 @@ async function runExport(reader, registry, sink, options = {}) {
   const segments = [];
   const failed = [];
   let totalIds = 0;
+  if (typeof reader?.segment !== "function") {
+    throw new ValidationError(
+      "runExport: the reader must have a segment(name, { namespace? }) method returning a handle with pin(), as a store's does"
+    );
+  }
+  let probed = false;
+  let unusable;
   const exportRef = async (ref) => {
     let writer;
     let count = 0;
     let bytes = 0;
     try {
       validateSegmentRef(ref);
-      const ids = reader.segment(ref.segment, { namespace: ref.namespace }).iterate();
+      const handle = reader.segment(ref.segment, { namespace: ref.namespace });
+      if (!probed) {
+        probed = true;
+        if (typeof handle?.pin !== "function") {
+          unusable = new ValidationError(
+            "runExport: the reader's segment(name, { namespace? }) must return a handle with a pin() method; a segment is exported at one pinned generation"
+          );
+          throw unusable;
+        }
+      }
+      const ids = (await handle.pin()).iterate();
       writer = await sink.open(ref, ext);
       if (format === "roaring") {
         const bm = requireCodec(options.codec, "runExport({ format: 'roaring' })").empty();
@@ -2067,6 +2241,7 @@ async function runExport(reader, registry, sink, options = {}) {
         }
       }
     } catch (err) {
+      if (err === unusable) throw err;
       if (writer !== void 0) {
         try {
           await writer.abort?.();
@@ -3848,25 +4023,27 @@ function isShared(buffer) {
 }
 function overCap(what, length) {
   return new ValidationError(
-    `${what} is ${length} bytes, more than any canonical 32-bit bitmap serializes to (${MAX_SERIALIZED_LOAD_BYTES}). Call runOptimize() on the bitmap before serializing it.`
+    `${what} is ${length} bytes, more than any canonical 32-bit bitmap serializes to (${MAX_SERIALIZED_LOAD_BYTES}). If it was serialized from a bitmap, call runOptimize() on the bitmap first.`
   );
 }
-function prepareLoadInput(input, codec) {
+function prepareLoadInput(input, codec, subject = "a load") {
   if (typeof input !== "object" || input === null) {
     throw new ValidationError(
-      `a load takes ids, { serialized } or { bitmap }; got ${String(input)}`
+      `${subject} takes ids, { serialized } or { bitmap }; got ${String(input)}`
     );
   }
   const tag = tagOf(input);
   if (tag === "Uint8Array" || tag === "Uint8ClampedArray") {
     throw new ValidationError(
-      `a load's ids cannot be a ${tag} or Buffer: each byte would be loaded as an id. Pass portable Roaring bytes as { serialized }, and ids as a Uint32Array or an array of numbers.`
+      `${subject}'s ids cannot be a ${tag} or Buffer: each byte would be loaded as an id. Pass portable Roaring bytes as { serialized }, and ids as a Uint32Array or an array of numbers.`
     );
   }
   if (Symbol.iterator in input || Symbol.asyncIterator in input) return input;
   const keys = Object.keys(input);
   if (keys.length === 1 && keys[0] === "serialized") {
-    return decode(input.serialized, "{ serialized }", codec);
+    return new DecodedLoadInput(
+      decodeSerialized(input.serialized, codec, "{ serialized }")
+    );
   }
   if (keys.length === 1 && keys[0] === "bitmap") {
     const bitmap = input.bitmap;
@@ -3878,13 +4055,13 @@ function prepareLoadInput(input, codec) {
       const size = bitmap.getSerializationSizeInBytes("portable");
       if (typeof size === "number" && size > MAX_SERIALIZED_LOAD_BYTES) throw overCap(what, size);
     }
-    return decode(bitmap.serialize("portable"), what, codec);
+    return new DecodedLoadInput(decodeSerialized(bitmap.serialize("portable"), codec, what));
   }
   throw new ValidationError(
-    `a load takes ids (an iterable of integers), { serialized } or { bitmap }, as the only key; got an object with keys [${keys.join(", ")}]. Load options go in the next argument.`
+    `${subject} takes ids (an iterable of integers), { serialized } or { bitmap }, as the only key; got an object with keys [${keys.join(", ")}].${subject === "a load" ? " Load options go in the next argument." : ""}`
   );
 }
-function decode(bytes, what, codec) {
+function decodeSerialized(bytes, codec, what = "the buffer") {
   if (typeof bytes !== "object" || bytes === null || tagOf(bytes) !== "Uint8Array") {
     throw new ValidationError(`${what} must be a Uint8Array of portable Roaring bytes`);
   }
@@ -3892,9 +4069,7 @@ function decode(bytes, what, codec) {
   if (view.byteLength > MAX_SERIALIZED_LOAD_BYTES) throw overCap(what, view.byteLength);
   const own = isShared(view.buffer) ? new Uint8Array(view) : view;
   try {
-    return new DecodedLoadInput(
-      codec.safeDeserialize(own, MAX_SERIALIZED_LOAD_BYTES, { whole: true })
-    );
+    return codec.safeDeserialize(own, MAX_SERIALIZED_LOAD_BYTES, { whole: true });
   } catch (err) {
     if (!isIntegrityError(err)) throw err;
     throw new ValidationError(`${what} is not a valid bitmap: ${err.message}`);
@@ -4037,6 +4212,8 @@ var notThePinned = (ref, generation) => new NotFoundError(
 function versionOf(generation, lineage) {
   return lineage === void 0 ? String(generation) : `${generation}:${String(lineage)}`;
 }
+var PinMoved = class extends Error {
+};
 function summaryOfGeneration(generation, description) {
   const { cardinality, metadata } = description;
   return metadata === void 0 || Object.keys(metadata).length === 0 ? { generation, cardinality } : { generation, cardinality, metadata: Object.freeze({ ...metadata }) };
@@ -4403,17 +4580,102 @@ var CrbmStorageChunkSource = class {
    * and a `keep: 0` sweep can land in that gap, and nothing has been handed out yet, so the generation current
    * once the swept one is gone is exactly what a pin taken now should hold. One retry, then propagate.
    */
-  async pinGeneration(ref) {
+  async pinGeneration(ref, lease) {
+    for (let moved = 0; ; moved++) {
+      try {
+        try {
+          return await this.pinOnce(ref, lease);
+        } catch (err) {
+          if (!isNotFoundError(err)) throw err;
+          return await this.pinOnce(ref, lease);
+        }
+      } catch (err) {
+        if (!(err instanceof PinMoved)) throw err;
+        if (moved >= 2) {
+          throw new WriteConflictError(
+            `pin: the pointer of "${ref.segment}" moved on every attempt to lease its current generation`
+          );
+        }
+      }
+    }
+  }
+  /**
+   * Open one named generation and verify it is the object `at.fingerprint` names, for a pin the caller reopens. One
+   * row read and one tail read with a registry (none of the row for a store without one): the open is the one a
+   * pinned read makes ({@link readerAt}), memoised under the version the pin will read by, so the pin's first read
+   * finds it open. A generation that is gone, above the row's pointer, on a destroyed or absent row, or another
+   * object than the fingerprint names, throws `NotFoundError`; nothing here reads empty.
+   *
+   * A generation counts as published while the pointer is at or above it. A rollback deletes nothing, so after one
+   * and a later load, a generation it rolled back from can be reopened while its object is still stored and the
+   * fingerprint matches. Like `pinGeneration`'s pinned reads, this opens the object without the live open's check
+   * of the row's summary against it, since that check is made where the row's own generation is read.
+   */
+  async pinGenerationAt(ref, at, lease) {
+    const { generation, fingerprint } = at;
+    const gone = (why) => new NotFoundError(
+      `segment "${ref.segment}" generation ${generation} cannot be pinned: ${why}`
+    );
+    let version = versionOf(generation, void 0);
+    let installed;
+    let pinKey;
+    let memoised = false;
+    if (this.registry !== void 0) {
+      const record = await this.registry.get(ref);
+      if (record === null || record.status === "destroyed")
+        throw gone("the segment has no readable row");
+      if (record.currentGen === null || generation > record.currentGen) {
+        throw gone("it is not a published generation of this segment");
+      }
+      let lineage = record.token;
+      if (lease !== void 0) {
+        const taken = await lease.take(record);
+        if (taken === "moved") throw gone("the segment moved while its lease was taken");
+        lineage = taken.token;
+      }
+      version = versionOf(generation, lineage);
+      const key = this.pinnedKey(ref, version);
+      memoised = this.snapshots.peek(key) !== void 0;
+      if (!memoised) {
+        installed = this.install(
+          key,
+          Snapshot.eager(
+            this.openForTarget(ref, {
+              generation,
+              lineage,
+              wrappedDeks: record.wrappedDeks
+            })
+          )
+        );
+      }
+      pinKey = key;
+    }
+    if (this.registry === void 0) {
+      memoised = this.snapshots.peek(this.pinnedKey(ref, version, fingerprint)) !== void 0;
+    }
     try {
-      return await this.pinOnce(ref);
+      await this.readerAt(ref, generation, version, fingerprint);
     } catch (err) {
-      if (!isNotFoundError(err)) throw err;
-      return this.pinOnce(ref);
+      if (installed !== void 0 && pinKey !== void 0 && this.snapshots.peek(pinKey) === installed) {
+        this.snapshots.delete(pinKey);
+      }
+      throw err;
+    }
+    if (!memoised) {
+      const held = this.heldKey(ref, version, fingerprint);
+      this.replacedPins.delete(held);
+      this.checking.delete(held);
     }
+    return { generation, version, fingerprint };
   }
-  async pinOnce(ref) {
-    const live = await this.resolveLive(ref);
+  async pinOnce(ref, lease) {
+    let live = await this.resolveLive(ref);
     if (live === null) return null;
+    if (lease !== void 0 && live.row !== void 0) {
+      const taken = await lease.take(live.row);
+      if (taken === "moved") throw new PinMoved();
+      live = { ...live, target: { ...live.target, lineage: taken.token } };
+    }
     const target = live.target;
     const version = versionOf(target.generation, target.lineage);
     let reader;
@@ -4709,6 +4971,7 @@ var CrbmStorageChunkSource = class {
       const unwrap = keys === void 0 || keys.length === 0 || this.keystore === void 0 ? void 0 : prior?.unwrap !== void 0 && sameKeys(prior.target.wrappedDeks, keys) ? prior.unwrap : once(() => this.keystore.openDek(keys));
       const crypto = once(() => this.cryptoForRead(ref, generation, keys, unwrap));
       return {
+        row: record,
         target: { generation, lineage: record.token, wrappedDeks: record.wrappedDeks },
         crypto,
         unwrap,
@@ -5021,6 +5284,18 @@ var CrbmStorageChunkSource = class {
     }
   }
 };
+async function encodedChunksOfInput(ids, codec, clock) {
+  if (ids instanceof DecodedLoadInput && ids.bitmap.encodeChunks !== void 0) {
+    const pause = yieldEvery(clock, 1);
+    await pause();
+    const chunks = ids.bitmap.encodeChunks();
+    await pause();
+    return chunks;
+  }
+  return encodeEach(
+    await bucketIds(ids instanceof DecodedLoadInput ? ids.bitmap : ids, codec, clock)
+  );
+}
 function* encodeEach(chunks) {
   for (const { chunkKey, bitmap } of chunks) {
     if (bitmap.isEmpty) continue;
@@ -5146,11 +5421,24 @@ function refuseCleartextOntoKey(key, record, cleartext) {
 }
 var UNANSWERED_RESENDS = 3;
 var UNANSWERED_RESEND_BASE_MS = 500;
-async function publishGeneration(registry, key, options = {}) {
+function leasesPatch(record, options) {
+  const held = record.leases;
+  if (held === void 0) return {};
+  if (options.clearLeases === true) return { leases: void 0 };
+  if (options.leasesNow === void 0) return {};
+  const now = options.leasesNow();
+  const live = held.filter((e) => isLive(e, now));
+  if (live.length === held.length) return {};
+  return { leases: live.length === 0 ? void 0 : live };
+}
+async function publishGenerationKept(registry, key, options = {}) {
   let fresh;
   let failedOn;
   let unanswered;
   let resends = 0;
+  const churn = leaseChurn({ clock: options.clock, rng: options.rng });
+  let throughChurn = false;
+  let waited;
   let sawUnanswered = false;
   let lastRecord;
   for (let attempt = 0; attempt < 5; attempt++) {
@@ -5161,6 +5449,8 @@ async function publishGeneration(registry, key, options = {}) {
     fresh = void 0;
     unanswered = void 0;
     lastRecord = record;
+    let next;
+    let wrote;
     if (failedOn !== void 0) {
       let landed;
       try {
@@ -5168,57 +5458,78 @@ async function publishGeneration(registry, key, options = {}) {
       } catch (proofErr) {
         throw outcomeUnknown(key, proofErr);
       }
-      if (landed) return true;
+      if (landed)
+        return {
+          published: true,
+          kept: { ...nextKept(failedOn, key.generation, options.keep), token: void 0 }
+        };
       if (record !== null && record.status === "active" && record.currentGen === key.generation) {
-        return false;
+        return REFUSED;
       }
       failedOn = void 0;
     }
     try {
       if (options.expectFrom !== void 0 && record?.currentGen !== options.expectFrom) {
-        return false;
+        return REFUSED;
       }
       if (options.expectAbsent === true && record !== null) {
-        return false;
+        return REFUSED;
       }
+      throughChurn = false;
       if (options.expectToken !== void 0 && record?.token !== options.expectToken) {
-        return false;
+        const held = options.expectRow;
+        if (record !== null && held != null && record === waited && onlyLeasesDiffer(held, record)) {
+          throughChurn = true;
+        } else {
+          const settled2 = record === waited ? void 0 : await churn.settle(held, record, () => registry.get(key));
+          if (settled2 !== void 0) {
+            waited = settled2.row;
+            fresh = settled2.row;
+            attempt -= 1;
+            continue;
+          }
+          return REFUSED;
+        }
       }
       if (record === null && options.summary !== void 0 && "sealed" in options.summary && options.wrappedDeks === void 0) {
         if (reused) continue;
-        return false;
+        return REFUSED;
       }
       if (record === null) {
-        await registry.create(
+        next = nextKept(null, key.generation, options.keep);
+        wrote = (await registry.create(
           key,
           {
             currentGen: key.generation,
             wrappedDeks: options.wrappedDeks,
-            ...options.summary === void 0 ? {} : { summary: options.summary }
+            ...options.summary === void 0 ? {} : { summary: options.summary },
+            ...next.list === void 0 ? {} : { keptGens: next.list }
           },
           write
-        );
+        )).token;
       } else if (record.status === "destroyed") {
         throw new ValidationError(
           `segment "${key.segment}" was destroyed (crypto-shredded) while generation ${key.generation} was being written \u2014 refusing to publish it; the written object is unreadable. Use a new segment.`
         );
       } else if (record.currentGen === null) {
         refuseCleartextOntoKey(key, record, options.cleartext);
-        await registry.compareAndSwap(
+        next = nextKept(record, key.generation, options.keep);
+        wrote = (await registry.compareAndSwap(
           key,
           record.token,
           {
             currentGen: key.generation,
             ...options.wrappedDeks === void 0 ? {} : { wrappedDeks: options.wrappedDeks },
-            ...options.summary === void 0 ? {} : { summary: options.summary }
+            ...options.summary === void 0 ? {} : { summary: options.summary },
+            ...next.list === void 0 ? {} : { keptGens: next.list }
           },
           write
-        );
+        )).token;
       } else if (record.currentGen > key.generation) {
-        return false;
+        return REFUSED;
       } else if (record.currentGen === key.generation) {
         if (reused) continue;
-        return true;
+        return { published: true };
       } else {
         if (options.wrappedDeks !== void 0 && options.wrappedDeks.length > 0) {
           throw new ValidationError(
@@ -5226,20 +5537,27 @@ async function publishGeneration(registry, key, options = {}) {
           );
         }
         refuseCleartextOntoKey(key, record, options.cleartext);
-        await registry.compareAndSwap(
+        next = nextKept(record, key.generation, options.keep);
+        wrote = (await registry.compareAndSwap(
           key,
           record.token,
           {
             currentGen: key.generation,
-            ...options.summary === void 0 ? {} : { summary: options.summary }
+            ...options.summary === void 0 ? {} : { summary: options.summary },
+            ...next.list === void 0 ? {} : { keptGens: next.list },
+            ...leasesPatch(record, options)
           },
           write
-        );
+        )).token;
       }
-      return true;
+      return {
+        published: true,
+        kept: { ...next ?? { list: void 0, evict: [] }, token: wrote }
+      };
     } catch (err) {
       if (isWriteConflictError(err)) {
         failedOn = record;
+        if (throughChurn) attempt -= 1;
         continue;
       }
       if (!isTransientError(err)) throw err;
@@ -5268,10 +5586,12 @@ async function publishGeneration(registry, key, options = {}) {
   }
   const final = await registry.get(key);
   if (final !== null && final.currentGen !== null && final.currentGen >= key.generation) {
-    if (final.currentGen !== key.generation) return false;
-    if (!sawUnanswered) return true;
+    if (final.currentGen !== key.generation) return REFUSED;
+    if (!sawUnanswered) return { published: true };
     try {
-      return await landedHere(final, lastRecord ?? null, key, options.holdsOwnObject);
+      return {
+        published: await landedHere(final, lastRecord ?? null, key, options.holdsOwnObject)
+      };
     } catch (proofErr) {
       throw outcomeUnknown(key, proofErr);
     }
@@ -5281,6 +5601,10 @@ async function publishGeneration(registry, key, options = {}) {
     `publishGeneration: contention setting currentGen for ${key.segment}`
   );
 }
+var REFUSED = { published: false };
+async function publishGeneration(registry, key, options = {}) {
+  return (await publishGenerationKept(registry, key, options)).published;
+}
 async function landedHere(now, before, key, holdsOwnObject) {
   if (now === null || now.status === "destroyed" || now.currentGen !== key.generation) return false;
   if (before !== null && !sameIncarnation(before, now)) return false;
@@ -5315,17 +5639,10 @@ async function bulkLoadAhead(driver, ref, ahead, ids, options = {}) {
   }
   const codec = requireCodec(options.codec, "bulkLoadCrbmGeneration");
   let chunks;
-  if (ids instanceof DecodedLoadInput && ids.bitmap.encodeChunks !== void 0) {
-    const pause = yieldEvery(options.clock, 1);
-    await pause();
-    chunks = ids.bitmap.encodeChunks();
-    await pause();
-  } else if (ids instanceof ChunkLoadInput) {
+  if (ids instanceof ChunkLoadInput) {
     chunks = encodeEach(rangeCheckedAtWrite(await collectChunks(ids, codec, options.clock)));
   } else {
-    chunks = encodeEach(
-      await bucketIds(ids instanceof DecodedLoadInput ? ids.bitmap : ids, codec, options.clock)
-    );
+    chunks = await encodedChunksOfInput(ids, codec, options.clock);
   }
   if (options.keystore !== void 0 && options.registry === void 0) {
     throw new ValidationError("an encrypted load requires a registry to store the wrapped DEK");
@@ -5838,7 +6155,7 @@ async function runLoad(ref, prepare, deps, options) {
   const key = { namespace: ref.namespace, segment: ref.segment, generation };
   const reclaim = async () => {
     const now = await deps.registry.get(ref);
-    if (now !== null && (now.token === fromToken || now.status === "destroyed")) {
+    if (now !== null && (now.token === fromToken || now.status === "destroyed" || row !== null && onlyLeasesDiffer(row, now))) {
       await deps.storage.delete(key);
       return;
     }
@@ -5880,14 +6197,17 @@ async function runLoad(ref, prepare, deps, options) {
   if (guard?.minRetained !== void 0 && before !== null) {
     if (written.cardinality < before * guard.minRetained) return refuse("min-retained");
   }
+  const leasesNow = deps.clock === void 0 ? void 0 : () => deps.clock.now();
   let published;
   try {
-    published = await publishGeneration(deps.registry, key, {
+    published = await publishGenerationKept(deps.registry, key, {
+      keep,
+      leasesNow,
       row,
       wrappedDeks: written.wrappedDeks,
       summary: written.summary,
       cleartext: !written.encrypted,
-      ...fromToken === void 0 ? {} : { expectToken: fromToken },
+      ...fromToken === void 0 ? {} : { expectToken: fromToken, expectRow: row },
       ...needsBefore && fromGeneration !== void 0 ? { expectFrom: fromGeneration } : {},
       // The third case, and the one the two fences above structurally cannot cover: the guard judged a segment
       // that had NO ROW. Both `expectFrom` and `expectToken` compare against a value read from a row, so with no
@@ -5911,7 +6231,7 @@ async function runLoad(ref, prepare, deps, options) {
     if (isValidationError(err) || err instanceof KeyUnavailableError) await reclaim();
     throw err;
   }
-  if (!published) return refuse("superseded");
+  if (!published.published) return refuse("superseded");
   audit.onEvent({
     kind: "segment.publish",
     segment: ref.segment,
@@ -5922,7 +6242,10 @@ async function runLoad(ref, prepare, deps, options) {
   const collected = await collectAfterLoad(ref, deps, {
     generation,
     keep,
-    byName: checked && !currentObjectGone && deps.collectByListing !== true,
+    byName: checked && deps.collectByListing !== true,
+    currentGone: currentObjectGone,
+    ...leasesNow === void 0 ? {} : { leases: { now: leasesNow } },
+    kept: published.kept,
     ...current.fromSummary && fromGeneration !== void 0 ? { proveCurrent: { ...ref, generation: fromGeneration } } : {}
   });
   return {
@@ -5937,123 +6260,2390 @@ async function runLoad(ref, prepare, deps, options) {
   };
 }
 
-// src/core/rollback.ts
-async function listGenerations(ref, deps) {
-  validateUserRef(ref);
-  const record = await deps.registry.get(ref);
-  const current = record?.currentGen ?? null;
-  const seen = /* @__PURE__ */ new Set();
-  for await (const key of deps.storage.list(ref)) seen.add(key.generation);
-  const described = record === null ? void 0 : await currentDescription(ref, record, deps);
-  return [...seen].sort((a, b) => a - b).map(
-    (generation) => generation === current ? { generation, current: true, ...described } : { generation, current: false }
-  );
-}
-async function currentDescription(ref, record, deps) {
-  if (record.summary === void 0) return void 0;
-  let aead;
-  if ("sealed" in record.summary && record.wrappedDeks !== void 0 && deps.keystore !== void 0) {
-    try {
-      aead = await deps.keystore.openDek(record.wrappedDeks);
-    } catch {
-      return void 0;
-    }
-  }
-  const usable = usableSummary(ref, record, aead);
-  if (usable === void 0) return void 0;
-  const metadata = usable.metadata;
-  return metadata === void 0 || Object.keys(metadata).length === 0 ? { cardinality: usable.cardinality } : { cardinality: usable.cardinality, metadata: Object.freeze({ ...metadata }) };
-}
-async function rollbackSegment(ref, toGeneration, deps, options = {}) {
-  validateUserRef(ref);
-  if (!Number.isInteger(toGeneration) || toGeneration < 0) {
+// src/core/combine-expr.ts
+var MAX_EXPR_DEPTH = 64;
+var MAX_EXPR_NODES = 4096;
+var OPERATORS = ["and", "or", "andNot"];
+function compileExpr(expr, path, operands, budget = { remaining: MAX_EXPR_NODES }, depth = 0) {
+  if (--budget.remaining < 0) {
     throw new ValidationError(
-      `rollback: generation must be a non-negative integer; got ${String(toGeneration)}`
+      `${path}: more than ${MAX_EXPR_NODES} nodes in one output's expression`
     );
   }
-  const record = await deps.registry.get(ref);
-  if (record === null) {
-    throw new NotFoundError(`rollback: no registry row for segment "${ref.segment}"`);
+  if (typeof expr === "string") {
+    const index = operands.get(expr);
+    if (index === void 0) {
+      throw new ValidationError(`${path}: "${expr}" does not name an operand`);
+    }
+    return { kind: "leaf", operand: index };
   }
-  if (record.status === "destroyed") {
+  if (typeof expr !== "object" || expr === null || Array.isArray(expr)) {
     throw new ValidationError(
-      `rollback: segment "${ref.segment}" is destroyed (crypto-shredded) \u2014 every generation of it is unreadable`
+      `${path}: an expression is an operand name or an object with exactly one of and, or, andNot; got ${expr === null ? "null" : Array.isArray(expr) ? "an array" : typeof expr}`
     );
   }
-  if (record.currentGen === toGeneration) {
-    return { fromGeneration: record.currentGen, generation: toGeneration };
-  }
-  const present = /* @__PURE__ */ new Set();
-  for await (const key of deps.storage.list(ref)) present.add(key.generation);
-  if (!present.has(toGeneration)) {
-    const available = [...present].sort((a, b) => a - b);
-    throw new NotFoundError(
-      `rollback: generation ${toGeneration} of "${ref.segment}" is not in the bucket` + (available.length === 0 ? " (no generations remain)" : ` \u2014 present: ${available.join(", ")}`)
+  const keys = Object.keys(expr);
+  const operator = keys.length === 1 ? OPERATORS.find((op) => op === keys[0]) : void 0;
+  if (operator === void 0) {
+    throw new ValidationError(
+      `${path}: an expression node holds exactly one of and, or, andNot; got ${keys.length === 0 ? "no key" : keys.map((k) => `"${k}"`).join(", ")}`
     );
   }
-  if (record.currentGen !== null && toGeneration > record.currentGen && options.allowForward !== true) {
+  if (depth >= MAX_EXPR_DEPTH) {
     throw new ValidationError(
-      `rollback: generation ${toGeneration} of "${ref.segment}" is above the current pointer (${record.currentGen}) \u2014 it may never have been published. Pass { allowForward: true } if you are undoing an earlier rollback.`
+      `${path}: expression nests more than ${MAX_EXPR_DEPTH} operators deep (an object that contains itself is refused here too)`
     );
   }
-  const keyed = record.wrappedDeks !== void 0 && record.wrappedDeks.length > 0;
-  let aead;
-  if (keyed && deps.keystore !== void 0) {
-    try {
-      aead = await deps.keystore.openDek(record.wrappedDeks);
-    } catch {
-    }
+  const list = expr[operator];
+  if (!Array.isArray(list) || list.length === 0) {
+    throw new ValidationError(`${path}.${operator}: must be a non-empty array of expressions`);
   }
-  const crypto = aead === void 0 ? void 0 : { aead, aadFor: (scope) => aadFor(ref, toGeneration, scope) };
-  const { encrypted, reader } = await openRollbackTarget(
-    deps.storage,
-    { ...ref, generation: toGeneration },
-    crypto
-  );
-  if (encrypted !== keyed) {
-    throw new IntegrityError(
-      `rollback: generation ${toGeneration} of "${ref.segment}" is ${encrypted ? "encrypted" : "cleartext"}, but the segment is ${keyed ? "encrypted" : "cleartext"}, so no read of the segment could use it; it was never one of its generations. Roll back to another generation.`
+  if (operator === "andNot" && list.length < 2) {
+    throw new ValidationError(
+      `${path}.andNot: needs at least two expressions, the one subtracted from and one to subtract`
     );
   }
-  const summary = reader === void 0 ? void 0 : summaryOf(
-    ref,
-    toGeneration,
-    { cardinality: reader.count(), metadata: reader.metadata },
-    aead
-  );
-  const { token } = await deps.registry.compareAndSwap(ref, record.token, {
-    currentGen: toGeneration,
-    summary
-  });
-  let stillThere = false;
-  for await (const key of deps.storage.list(ref)) {
-    if (key.generation === toGeneration) {
-      stillThere = true;
-      break;
+  const kids = [];
+  for (let i = 0; i < list.length; i++) {
+    kids.push(compileExpr(list[i], `${path}.${operator}[${i}]`, operands, budget, depth + 1));
+  }
+  return { kind: operator, kids };
+}
+function depthOf(node) {
+  if (node.kind === "leaf") return 0;
+  let deepest = 0;
+  for (const kid of node.kids) deepest = Math.max(deepest, depthOf(kid));
+  return deepest + 1;
+}
+function operandsOf(node, into = /* @__PURE__ */ new Set()) {
+  if (node.kind === "leaf") into.add(node.operand);
+  else for (const kid of node.kids) operandsOf(kid, into);
+  return [...into].sort((a, b) => a - b);
+}
+var CHUNK_IDS = 65536;
+var ANY_KEYS = new Uint16Array(0);
+var ANY_BOUNDS = { keys: ANY_KEYS, card: new Uint32Array(0) };
+var EMPTY_BOUNDS = { keys: new Uint16Array(0), card: new Uint32Array(0) };
+function intersectBounds(a, b) {
+  const keys = new Uint16Array(Math.min(a.keys.length, b.keys.length));
+  const card = new Uint32Array(keys.length);
+  let i = 0;
+  let j = 0;
+  let n = 0;
+  while (i < a.keys.length && j < b.keys.length) {
+    const x = a.keys[i];
+    const y = b.keys[j];
+    if (x < y) i++;
+    else if (y < x) j++;
+    else {
+      keys[n] = x;
+      card[n] = Math.min(a.card[i], b.card[j]);
+      n++;
+      i++;
+      j++;
+    }
+  }
+  return n === keys.length ? { keys, card } : { keys: keys.slice(0, n), card: card.slice(0, n) };
+}
+function unionBounds(a, b) {
+  const keys = new Uint16Array(a.keys.length + b.keys.length);
+  const card = new Uint32Array(keys.length);
+  let i = 0;
+  let j = 0;
+  let n = 0;
+  while (i < a.keys.length || j < b.keys.length) {
+    const x = i < a.keys.length ? a.keys[i] : Infinity;
+    const y = j < b.keys.length ? b.keys[j] : Infinity;
+    if (x < y) {
+      keys[n] = x;
+      card[n++] = a.card[i++];
+    } else if (y < x) {
+      keys[n] = y;
+      card[n++] = b.card[j++];
+    } else {
+      keys[n] = x;
+      card[n++] = Math.min(CHUNK_IDS, a.card[i++] + b.card[j++]);
     }
   }
-  let replaced = false;
-  if (stillThere && reader !== void 0 && toGeneration > (record.currentGen ?? -1)) {
-    try {
-      replaced = !await provesOwnObject(
-        deps.storage,
-        { ...ref, generation: toGeneration },
-        reader.fingerprint
-      );
-    } catch (err) {
-      if (!isIntegrityError(err)) throw err;
-      replaced = true;
+  return { keys: keys.slice(0, n), card: card.slice(0, n) };
+}
+function intersectKeys(a, b) {
+  if (a === ANY_KEYS) return b;
+  if (b === ANY_KEYS) return a;
+  const out = new Uint16Array(Math.min(a.length, b.length));
+  let i = 0;
+  let j = 0;
+  let n = 0;
+  while (i < a.length && j < b.length) {
+    const x = a[i];
+    const y = b[j];
+    if (x < y) i++;
+    else if (y < x) j++;
+    else {
+      out[n++] = x;
+      i++;
+      j++;
+    }
+  }
+  return n === out.length ? out : out.slice(0, n);
+}
+function planKeys(node, operands, into = /* @__PURE__ */ new Map()) {
+  if (node.kind === "leaf") return operands[node.operand] ?? EMPTY_BOUNDS;
+  let result;
+  if (node.kind === "andNot") {
+    result = planKeys(node.kids[0], operands, into);
+    for (let i = 1; i < node.kids.length; i++) planKeys(node.kids[i], operands, into);
+  } else {
+    const kids = node.kids.map((kid) => planKeys(kid, operands, into));
+    if (node.kind === "and") {
+      const known = kids.filter((kid) => kid.keys !== ANY_KEYS);
+      known.sort((a, b) => a.keys.length - b.keys.length);
+      result = known[0] ?? ANY_BOUNDS;
+      for (let i = 1; i < known.length && result.keys.length > 0; i++) {
+        result = intersectBounds(result, known[i]);
+      }
+    } else if (kids.some((kid) => kid.keys === ANY_KEYS)) {
+      result = ANY_BOUNDS;
+    } else {
+      result = kids[0];
+      for (let i = 1; i < kids.length; i++) result = unionBounds(result, kids[i]);
     }
   }
-  if (!stillThere || replaced) {
-    let undone = false;
-    try {
-      await deps.registry.compareAndSwap(ref, token, {
-        currentGen: record.currentGen,
-        summary: describingSummary(record)
-      });
-      undone = true;
-    } catch {
+  into.set(node, result.keys);
+  return result;
+}
+function keysOf(node, operands, planned) {
+  if (node.kind === "leaf") return (operands[node.operand] ?? EMPTY_BOUNDS).keys;
+  return planned.get(node) ?? new Uint16Array(0);
+}
+function collectFetch(node, demanded, operands, planned, fetch) {
+  if (demanded.length === 0 && demanded !== ANY_KEYS) return;
+  const own = keysOf(node, operands, planned);
+  const here = intersectKeys(demanded, own);
+  if (here.length === 0 && here !== ANY_KEYS) return;
+  if (node.kind === "leaf") {
+    if (own !== ANY_KEYS) fetch(node.operand, here);
+    return;
+  }
+  for (const kid of node.kids) collectFetch(kid, here, operands, planned, fetch);
+}
+function canHold(node, holds) {
+  switch (node.kind) {
+    case "leaf":
+      return holds(node.operand);
+    case "and":
+      return node.kids.every((kid) => canHold(kid, holds));
+    case "or":
+      return node.kids.some((kid) => canHold(kid, holds));
+    case "andNot":
+      return canHold(node.kids[0], holds);
+  }
+}
+var KeyBits = class {
+  words = new Uint32Array(CHUNK_IDS / 32);
+  count = 0;
+  add(keys) {
+    for (let i = 0; i < keys.length; i++) {
+      const key = keys[i];
+      const word = key >>> 5;
+      const bit = 1 << (key & 31);
+      if ((this.words[word] & bit) === 0) {
+        this.words[word] = this.words[word] | bit;
+        this.count++;
+      }
+    }
+  }
+  get size() {
+    return this.count;
+  }
+  has(key) {
+    return (this.words[key >>> 5] & 1 << (key & 31)) !== 0;
+  }
+  /** The keys, ascending. */
+  toKeys() {
+    const out = [];
+    for (let w = 0; w < this.words.length; w++) {
+      let bits = this.words[w];
+      while (bits !== 0) {
+        const low = bits & -bits;
+        out.push(w << 5 | 31 - Math.clz32(low));
+        bits ^= low;
+      }
+    }
+    return out;
+  }
+};
+
+// src/core/combine-ledger.ts
+var RESIDENT_BITMAP_OVERHEAD = 512;
+var MAX_CHUNK_SERIALIZED = 8208;
+function serializedBound(cardinality) {
+  return Math.min(2 * cardinality + 16, MAX_CHUNK_SERIALIZED);
+}
+var MAX_RESIDENT_DATA = 8800;
+function residentBytes(serialized) {
+  return Math.ceil(
+    RESIDENT_BITMAP_OVERHEAD + Math.min(1.6 * serialized, serialized + 2e3, MAX_RESIDENT_DATA)
+  );
+}
+function residentBound(cardinality) {
+  return residentBytes(serializedBound(cardinality));
+}
+var ResidentLedger = class {
+  constructor(limit) {
+    this.limit = limit;
+  }
+  limit;
+  held = 0;
+  peak = 0;
+  get used() {
+    return this.held;
+  }
+  get highWater() {
+    return this.peak;
+  }
+  /** Bytes still free. */
+  get room() {
+    return this.limit - this.held;
+  }
+  /** Charge `bytes` if they fit. */
+  tryCharge(bytes) {
+    if (this.held + bytes > this.limit) return false;
+    this.held += bytes;
+    if (this.held > this.peak) this.peak = this.held;
+    return true;
+  }
+  /**
+   * Charge `bytes`, asking `makeRoom` to free some while they do not fit. `makeRoom` releases what it frees (through
+   * {@link release}) and answers whether it freed anything; the charge is refused when it cannot.
+   */
+  reserve(bytes, makeRoom) {
+    while (!this.tryCharge(bytes)) if (!makeRoom()) return false;
+    return true;
+  }
+  release(bytes) {
+    this.held -= bytes;
+  }
+};
+
+// src/core/combine-feed.ts
+var KEY_IDS = 65536;
+function checkFeed(feed, stored) {
+  if (typeof feed !== "object" || feed === null || Array.isArray(feed)) {
+    throw new ValidationError("feed must be an object with names, records and counts");
+  }
+  const f = feed;
+  const names = f.names;
+  const records = f.records;
+  const counts = f.counts;
+  const mayBeEmpty = f.mayBeEmpty;
+  const epoch = f.epoch;
+  if (!Array.isArray(names) || names.length === 0) {
+    throw new ValidationError("feed.names must be a non-empty array of the fed operand names");
+  }
+  const declared = /* @__PURE__ */ new Set();
+  for (const name of names) {
+    if (typeof name !== "string" || name === "") {
+      throw new ValidationError("feed.names must hold non-empty strings");
+    }
+    if (declared.has(name)) throw new ValidationError(`feed.names lists "${name}" twice`);
+    if (stored.has(name)) {
+      throw new ValidationError(
+        `"${name}" is both a stored operand and a fed one: a name is one or the other`
+      );
+    }
+    declared.add(name);
+  }
+  const iterable = records;
+  if (typeof iterable !== "object" && typeof iterable !== "function" || iterable === null || typeof iterable[Symbol.asyncIterator] !== "function") {
+    throw new ValidationError(
+      "feed.records must be an async iterable (an async generator, for one): wrap an array in `async function*`"
+    );
+  }
+  if (typeof counts !== "function" && (typeof counts !== "object" || counts === null || Array.isArray(counts))) {
+    throw new ValidationError(
+      "feed.counts is required: an object of ids per fed operand, or a function returning one"
+    );
+  }
+  const allowed = /* @__PURE__ */ new Set();
+  if (mayBeEmpty !== void 0) {
+    if (!Array.isArray(mayBeEmpty)) {
+      throw new ValidationError("mayBeEmpty must be an array of fed operand names");
+    }
+    for (const name of mayBeEmpty) {
+      if (typeof name !== "string" || !declared.has(name)) {
+        throw new ValidationError(
+          `mayBeEmpty names ${typeof name === "string" ? `"${name}"` : "something that is not a name"}, which is not a fed operand`
+        );
+      }
+      allowed.add(name);
+    }
+  }
+  let checkedEpoch;
+  if (epoch !== void 0) {
+    const e = epoch;
+    if (typeof e !== "object" || e === null || typeof e.moved !== "function") {
+      throw new ValidationError("feed.epoch must be { moved }");
+    }
+    checkedEpoch = { moved: e.moved };
+  }
+  return {
+    names: [...declared],
+    records,
+    counts,
+    mayBeEmpty: allowed,
+    epoch: checkedEpoch
+  };
+}
+var TYPED = Object.getPrototypeOf(Uint8Array.prototype);
+var typedGetter = (name) => Object.getOwnPropertyDescriptor(TYPED, name)?.get;
+var brandOf = typedGetter(Symbol.toStringTag);
+var bufferOf2 = typedGetter("buffer");
+var byteOffsetOf2 = typedGetter("byteOffset");
+var byteLengthOf2 = typedGetter("byteLength");
+var detachedOf = Object.getOwnPropertyDescriptor(ArrayBuffer.prototype, "detached")?.get;
+var valuesOf = TYPED.values;
+function plainUint32(value) {
+  let tag;
+  try {
+    tag = brandOf.call(value);
+  } catch {
+    return void 0;
+  }
+  if (tag !== "Uint32Array") return void 0;
+  const buffer = bufferOf2.call(value);
+  const length = byteLengthOf2.call(value);
+  if (length === 0) {
+    try {
+      if (detachedOf?.call(buffer) === true) return "detached";
+    } catch {
+    }
+    try {
+      valuesOf.call(value);
+    } catch {
+      return "out of bounds";
+    }
+    return new Uint32Array(0);
+  }
+  return new Uint32Array(buffer, byteOffsetOf2.call(value), length >>> 2);
+}
+function isPlainObject(value) {
+  const proto = Object.getPrototypeOf(value);
+  if (proto === null) return true;
+  return Object.getPrototypeOf(proto) === null && Object.hasOwn(proto, "hasOwnProperty");
+}
+var FeedClosed = class extends Error {
+};
+var FeedStale = class extends Error {
+};
+var FeedCursor = class {
+  constructor(deps) {
+    this.deps = deps;
+    this.index = new Map(deps.feed.names.map((name, i) => [name, i]));
+    this.seen = new Uint8Array(deps.feed.names.length);
+    this.counts = deps.feed.names.map(() => 0);
+  }
+  deps;
+  iterator;
+  group;
+  look;
+  current;
+  ended = false;
+  closed = false;
+  finished = false;
+  held = 0;
+  returned;
+  prevKey = -1;
+  index;
+  seen;
+  touched = [];
+  counts;
+  scratch = new Uint32Array(KEY_IDS);
+  recordCount = 0;
+  keyCount = 0;
+  idCount = 0;
+  /** Whether the feed can still yield a key: not closed, and neither ended nor drained. */
+  get active() {
+    return !this.closed && (!this.ended || this.group !== void 0 || this.look !== void 0);
+  }
+  /** Whether the whole feed was read and every end-of-feed check passed. */
+  get complete() {
+    return this.finished;
+  }
+  /** The ledger bytes the cursor holds. */
+  get heldBytes() {
+    return this.held;
+  }
+  get stats() {
+    return { records: this.recordCount, keys: this.keyCount, ids: this.idCount };
+  }
+  /** The key the feed holds next, pulling the first record of it if none is held; `undefined` once nothing is left. */
+  async nextKey() {
+    if (this.closed) return void 0;
+    if (this.group === void 0) {
+      if (this.look !== void 0) {
+        this.group = this.look;
+        this.look = void 0;
+      } else {
+        await this.fill();
+      }
+    }
+    return this.group?.key;
+  }
+  /** Read until a record with a higher key arrives, or the feed ends: the group of {@link nextKey} is then whole. */
+  async completeKey() {
+    const group = this.group;
+    if (group === void 0) return;
+    while (this.look === void 0 && !this.ended) {
+      const record = await this.pull();
+      if (record === void 0) {
+        await this.end();
+        break;
+      }
+      if (record.ops === null) continue;
+      if (record.key === group.key) for (const [i, h] of record.ops) group.ops.set(i, h);
+      else this.look = { key: record.key, ops: record.ops };
+    }
+  }
+  /** Take the whole group of {@link nextKey}: its bitmaps by operand index, held until {@link release}. */
+  take() {
+    const group = this.group;
+    this.current = group;
+    this.group = void 0;
+    this.keyCount++;
+    return new BitmapView(group.ops);
+  }
+  /** Give back what the taken group holds. */
+  release() {
+    const group = this.current;
+    this.current = void 0;
+    if (group === void 0) return;
+    for (const h of group.ops.values()) this.giveBack(h.charge);
+  }
+  /** Stop reading: release everything held and return the iterator. Safe to call at any time, and again. */
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    this.deps.release(this.held);
+    this.held = 0;
+    this.group = this.look = this.current = void 0;
+    const iterator = this.iterator;
+    if (iterator !== void 0 && !this.ended && iterator.return !== void 0) {
+      this.returned = Promise.resolve().then(() => iterator.return()).then(
+        () => void 0,
+        () => void 0
+      );
+    }
+  }
+  /** Resolves once the iterator's `return` has settled. */
+  async drained() {
+    await this.returned;
+  }
+  // ---- reading ----------------------------------------------------------------------------------------------
+  async fill() {
+    while (this.group === void 0 && !this.ended) {
+      const record = await this.pull();
+      if (record === void 0) {
+        await this.end();
+        return;
+      }
+      if (record.ops !== null) this.group = { key: record.key, ops: record.ops };
+    }
+  }
+  /** The next record, checked and converted (`ops` is `null` when its key is outside the range); `undefined` at the end. */
+  async pull() {
+    const epoch = this.deps.feed.epoch;
+    if (epoch?.moved() === true) throw new FeedStale();
+    this.iterator ??= this.deps.feed.records[Symbol.asyncIterator]();
+    const step = await this.iterator.next();
+    if (this.closed) throw new FeedClosed();
+    if (step.done === true) return void 0;
+    this.recordCount++;
+    return this.convert(step.value);
+  }
+  async end() {
+    this.ended = true;
+    await this.finish();
+    this.finished = true;
+  }
+  // ---- the checks -------------------------------------------------------------------------------------------
+  refuse(key, operand, why) {
+    throw new ValidationError(
+      `materializeMany feed: record at key ${String(key)}${operand === void 0 ? "" : `, operand "${operand}"`}: ${why}`
+    );
+  }
+  charge(bytes) {
+    this.deps.charge(bytes);
+    if (this.closed) {
+      this.deps.release(bytes);
+      throw new FeedClosed();
+    }
+    this.held += bytes;
+  }
+  giveBack(bytes) {
+    if (this.closed) return;
+    this.held -= bytes;
+    this.deps.release(bytes);
+  }
+  async convert(record) {
+    if (typeof record !== "object" || record === null) {
+      this.refuse("?", void 0, "a record is an object with a key and operands");
+    }
+    const key = record.key;
+    const operands = record.operands;
+    if (typeof key !== "number" || !Number.isInteger(key) || key < 0 || key >= KEY_IDS) {
+      this.refuse(
+        typeof key === "number" ? key : "?",
+        void 0,
+        "the key must be an integer from 0 to 65535"
+      );
+    }
+    if (key < this.prevKey) {
+      this.refuse(
+        key,
+        void 0,
+        `the key is below the previous record's (${this.prevKey}): keys never go back`
+      );
+    }
+    if (key !== this.prevKey) {
+      for (const i of this.touched) this.seen[i] = 0;
+      this.touched.length = 0;
+      this.prevKey = key;
+    }
+    if (typeof operands !== "object" || operands === null || !isPlainObject(operands)) {
+      this.refuse(
+        key,
+        void 0,
+        "operands must be a plain object of fed operand name to Uint32Array (not a Map, an array or a class instance)"
+      );
+    }
+    const keep = this.deps.inWindow(key);
+    const ops = keep ? /* @__PURE__ */ new Map() : null;
+    const charged = [];
+    try {
+      for (const name of Reflect.ownKeys(operands)) {
+        if (typeof name !== "string") this.refuse(key, void 0, "operands has a symbol key");
+        const at = this.index.get(name);
+        if (at === void 0) {
+          this.refuse(key, name, "not a declared fed operand (it is not in feed.names)");
+        }
+        const value = operands[name];
+        const view = plainUint32(value);
+        if (view === void 0) {
+          this.refuse(
+            key,
+            name,
+            "the ids must be a Uint32Array (any other typed array, array or look-alike is refused)"
+          );
+        }
+        if (view === "detached") this.refuse(key, name, "the array's buffer is detached");
+        if (view === "out of bounds") {
+          this.refuse(
+            key,
+            name,
+            "the array is out of bounds of its resizable buffer, which shrank under it"
+          );
+        }
+        if (view.length === 0) continue;
+        if (this.seen[at] === 1) {
+          this.refuse(key, name, "named twice at one key: an operand appears at most once per key");
+        }
+        const n = this.scan(view, key, name);
+        this.seen[at] = 1;
+        this.touched.push(at);
+        this.counts[at] += n;
+        this.idCount += n;
+        if (ops !== null) {
+          const bytes = residentBound(n);
+          this.charge(bytes);
+          charged.push(bytes);
+          ops.set(this.deps.base + at, {
+            bitmap: this.deps.codec.fromValues(this.scratch.subarray(0, n)),
+            charge: bytes
+          });
+        }
+        const pause = this.deps.tick();
+        if (pause !== null) {
+          await pause;
+          if (this.closed) throw new FeedClosed();
+        }
+      }
+    } catch (error) {
+      for (const bytes of charged) this.giveBack(bytes);
+      throw error;
+    }
+    return { key, ops };
+  }
+  /**
+   * Check `view` and copy its low 16 bits into the scratch array in one pass, each id read once: a buffer that changes
+   * under the check (a shared one) cannot make the checked value differ from the converted one.
+   */
+  scan(view, key, name) {
+    const n = view.length;
+    if (n > KEY_IDS) this.refuse(key, name, `${n} ids, more than one chunk key holds`);
+    const scratch = this.scratch;
+    let prev = -1;
+    for (let i = 0; i < n; i++) {
+      const id = view[i];
+      if (id >>> 16 !== key) {
+        this.refuse(key, name, `the id at position ${i} is not inside the key`);
+      }
+      if (id <= prev) {
+        this.refuse(
+          key,
+          name,
+          `the id at position ${i} is not above the one before it: ids are ascending and unique`
+        );
+      }
+      scratch[i] = id & 65535;
+      prev = id;
+    }
+    return n;
+  }
+  // ---- the end of the feed ----------------------------------------------------------------------------------
+  /** The counts and the empty rule, run once, after the iterator has ended and before anything is published. */
+  async finish() {
+    const { names, mayBeEmpty, counts } = this.deps.feed;
+    let given;
+    try {
+      given = typeof counts === "function" ? await counts() : counts;
+    } catch (cause) {
+      throw new ValidationError(
+        `materializeMany feed: feed.counts ${typeof counts === "function" ? "threw" : "could not be read"}: ${cause instanceof Error ? cause.message : String(cause)}`
+      );
+    }
+    if (typeof given !== "object" || given === null || Array.isArray(given)) {
+      throw new ValidationError(
+        "materializeMany feed: feed.counts must give an object of ids per fed operand"
+      );
+    }
+    const own = new Set(Object.keys(given));
+    for (const name of names) {
+      if (!own.has(name)) {
+        throw new ValidationError(`materializeMany feed: feed.counts has no count for "${name}"`);
+      }
+    }
+    for (const name of own) {
+      if (!this.index.has(name)) {
+        throw new ValidationError(
+          `materializeMany feed: feed.counts names "${name}", which is not in feed.names`
+        );
+      }
+    }
+    names.forEach((name, i) => {
+      const said = given[name];
+      if (typeof said !== "number" || !Number.isSafeInteger(said) || said < 0) {
+        throw new ValidationError(
+          `materializeMany feed: feed.counts["${name}"] must be a non-negative integer`
+        );
+      }
+      if (said !== this.counts[i]) {
+        throw new ValidationError(
+          `materializeMany feed: operand "${name}" was counted at ${said} ids and the feed held ${this.counts[i]}: the feed is short, long or skipped a key, and is refused`
+        );
+      }
+    });
+    names.forEach((name, i) => {
+      if (this.counts[i] === 0 && !mayBeEmpty.has(name)) {
+        throw new ValidationError(
+          `materializeMany feed: operand "${name}" holds no id anywhere in the feed, so it would contribute nothing \u2014 an exclude would suppress no ids. If that is expected, list it in mayBeEmpty.`
+        );
+      }
+    });
+  }
+};
+var BitmapView = class {
+  constructor(ops) {
+    this.ops = ops;
+  }
+  ops;
+  get size() {
+    return this.ops.size;
+  }
+  get(key) {
+    return this.ops.get(key)?.bitmap;
+  }
+  has(key) {
+    return this.ops.has(key);
+  }
+  forEach(fn) {
+    for (const [k, h] of this.ops) fn(h.bitmap, k, this);
+  }
+  *entries() {
+    for (const [k, h] of this.ops) yield [k, h.bitmap];
+  }
+  *keys() {
+    yield* this.ops.keys();
+  }
+  *values() {
+    for (const h of this.ops.values()) yield h.bitmap;
+  }
+  [Symbol.iterator]() {
+    return this.entries();
+  }
+};
+
+// src/core/combine-many.ts
+var MAX_RANGES_IN_FLIGHT2 = 64;
+var MAX_BATCH_PARALLELISM = 1024;
+var RANGE_BYTES = 1 << 20;
+var WORKING_CHUNK = residentBytes(8208);
+var BUDGET_HEADROOM_FACTOR = 2;
+var BUDGET_HEADROOM_FLOOR = 1e3;
+var INDEX_PARALLELISM = 16;
+var COMPILED = /* @__PURE__ */ new WeakMap();
+var MAX_CALL_NODES = 2e5;
+function subtractedOperands(node, under, into) {
+  if (node.kind === "leaf") {
+    if (under) into.add(node.operand);
+    return;
+  }
+  node.kids.forEach(
+    (kid, i) => subtractedOperands(kid, under || node.kind === "andNot" && i > 0, into)
+  );
+}
+function integerIn(value, min, max, what) {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < min || value > max) {
+    throw new ValidationError(
+      `${what} must be an integer from ${min} to ${max}; got ${typeof value === "number" ? String(value) : `a ${typeof value}`}`
+    );
+  }
+  return value;
+}
+function checkedKeep(value, what) {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+    throw new ValidationError(
+      `${what} must be a non-negative integer; got ${value === void 0 ? "nothing (it is required)" : String(value)}`
+    );
+  }
+  return value;
+}
+function compileCombineMany(request) {
+  const { operands, outputs } = request;
+  if (!Array.isArray(outputs) || outputs.length === 0) {
+    throw new ValidationError("outputs must be a non-empty array");
+  }
+  checkedKeep(request.keep, "keep");
+  integerIn(request.maxBufferedBytes, 1, Number.MAX_SAFE_INTEGER, "maxBufferedBytes");
+  integerIn(request.publishConcurrency, 1, MAX_BATCH_PARALLELISM, "publishConcurrency");
+  integerIn(request.concurrency, 1, MAX_BATCH_PARALLELISM, "concurrency");
+  for (const [name, bound] of [
+    ["after", request.after],
+    ["through", request.through]
+  ]) {
+    if (bound !== void 0) integerIn(bound, 0, U32_MAX, name);
+  }
+  const index = /* @__PURE__ */ new Map();
+  operands.forEach((op, i) => index.set(op.name, i));
+  for (const op of operands) {
+    if (op.held !== void 0 && op.held.chunks.empty && !op.held.mayBeEmpty) {
+      throw new ValidationError(
+        `materializeMany: operand "${op.name}" holds no id, so an include would contribute none and an exclude would subtract none. Check what it was made from, or name it in \`mayBeEmpty\` if it may be empty.`
+      );
+    }
+  }
+  const feed = request.feed === void 0 ? void 0 : checkFeed(request.feed, new Set(index.keys()));
+  feed?.names.forEach((name, j) => index.set(name, operands.length + j));
+  let totalNodes = 0;
+  const compiled = outputs.map((output, i) => {
+    const where = `outputs[${i}]`;
+    const budget = { remaining: MAX_EXPR_NODES };
+    const root = compileExpr(output.expr, `${where}.expr`, index, budget);
+    let exclude = [];
+    if (output.exclude !== void 0) {
+      const listed = output.exclude;
+      if (!Array.isArray(listed)) {
+        throw new ValidationError(`${where}.exclude must be an array of expressions`);
+      }
+      exclude = listed.map(
+        (e, j) => compileExpr(e, `${where}.exclude[${j}]`, index, budget)
+      );
+    }
+    const node = exclude.length === 0 ? root : { kind: "andNot", kids: [root, ...exclude] };
+    const nodes = MAX_EXPR_NODES - budget.remaining + (exclude.length === 0 ? 0 : 1);
+    totalNodes += nodes;
+    if (totalNodes > MAX_CALL_NODES) {
+      throw new ValidationError(
+        `${where}: the expressions of the call hold more than ${MAX_CALL_NODES} nodes in all; split the outputs across calls`
+      );
+    }
+    const keep = output.keep === void 0 ? request.keep : checkedKeep(output.keep, `${where}.keep`);
+    if (output.allowEmpty !== void 0 && typeof output.allowEmpty !== "boolean") {
+      throw new ValidationError(`${where}.allowEmpty must be a boolean`);
+    }
+    const guard = output.guard;
+    if (guard !== void 0) {
+      if (typeof guard !== "object" || guard === null) {
+        throw new ValidationError(`${where}.guard must be an object`);
+      }
+      const min = guard.minCardinality;
+      if (min !== void 0 && (!Number.isInteger(min) || min < 0)) {
+        throw new ValidationError(
+          `${where}.guard.minCardinality must be a non-negative integer; got ${String(min)}`
+        );
+      }
+      const retained = guard.minRetained;
+      if (retained !== void 0 && (!Number.isFinite(retained) || retained < 0 || retained > 1)) {
+        throw new ValidationError(
+          `${where}.guard.minRetained must be a fraction in 0..1; got ${String(retained)}`
+        );
+      }
+    }
+    const metadata = copiedMetadata(output.metadata, (message) => {
+      throw new ValidationError(`${where}.metadata: ${message}`);
+    });
+    const read = operandsOf(node);
+    return {
+      node,
+      operands: read.filter((i2) => i2 < operands.length),
+      fed: read.filter((i2) => i2 >= operands.length),
+      subtracted: subtractedList(node).filter((i2) => i2 < operands.length),
+      depth: depthOf(node),
+      nodes,
+      write: {
+        keep,
+        ...output.allowEmpty === void 0 ? {} : { allowEmpty: output.allowEmpty },
+        ...guard === void 0 ? {} : { guard },
+        ...metadata === void 0 ? {} : { metadata }
+      }
+    };
+  });
+  const result = { request };
+  COMPILED.set(result, { outputs: compiled, feed });
+  return result;
+}
+function rebindCombineMany(compiled, operands) {
+  const checked = COMPILED.get(compiled);
+  const before = compiled.request.operands;
+  if (checked === void 0 || operands.length !== before.length || operands.some((op, i) => op.name !== before[i].name)) {
+    throw new ValidationError(
+      "rebindCombineMany takes the operands compileCombineMany was given, by name and order"
+    );
+  }
+  const result = { request: { ...compiled.request, operands } };
+  COMPILED.set(result, checked);
+  return result;
+}
+function subtractedList(node) {
+  const into = /* @__PURE__ */ new Set();
+  subtractedOperands(node, false, into);
+  return [...into].sort((a, b) => a - b);
+}
+function windowOf2(after, through) {
+  if (after === void 0 && through === void 0) return null;
+  const lo = after === void 0 ? 0 : after + 1;
+  const hi = through ?? U32_MAX;
+  if (lo > hi) return "empty";
+  return {
+    loKey: Math.floor(lo / 65536),
+    loRem: lo % 65536,
+    hiKey: Math.floor(hi / 65536),
+    hiRem: hi % 65536
+  };
+}
+var isEdge2 = (key, w) => key === w.loKey && w.loRem > 0 || key === w.hiKey && w.hiRem < MAX_REMAINDER;
+function firstAbove2(sorted, x) {
+  let lo = 0;
+  let hi = sorted.length;
+  while (lo < hi) {
+    const mid = lo + hi >>> 1;
+    if (sorted[mid] <= x) lo = mid + 1;
+    else hi = mid;
+  }
+  return lo;
+}
+function cutToWindow(codec, chunk, key, w) {
+  const from = key === w.loKey ? w.loRem : 0;
+  const to = key === w.hiKey ? w.hiRem : MAX_REMAINDER;
+  const rem = chunk.toUint32Array ? chunk.toUint32Array() : Uint32Array.from(chunk);
+  return codec.fromValues(rem.subarray(firstAbove2(rem, from - 1), firstAbove2(rem, to)));
+}
+var Gate = class {
+  constructor(limit) {
+    this.limit = limit;
+  }
+  limit;
+  active = 0;
+  peak = 0;
+  waiting = [];
+  get highWater() {
+    return this.peak;
+  }
+  async run(task) {
+    if (this.active >= this.limit) await new Promise((resolve2) => this.waiting.push(resolve2));
+    else this.active++;
+    if (this.active > this.peak) this.peak = this.active;
+    try {
+      return await task();
+    } finally {
+      const next = this.waiting.shift();
+      if (next === void 0) this.active--;
+      else next();
+    }
+  }
+};
+var PLAN_KEEP_BYTES = 8 * 1024 * 1024;
+var BYTES_PER_NODE = 320;
+var BYTES_PER_OUTPUT = 3700;
+var combineWork = { adds: 0, withs: 0, operandSteps: 0, planBuilds: 0 };
+var GroupCost = class {
+  constructor(streamBytes, publishConcurrency) {
+    this.streamBytes = streamBytes;
+    this.publishConcurrency = publishConcurrency;
+  }
+  streamBytes;
+  publishConcurrency;
+  outputs = 0;
+  depth = 0;
+  /** The serialized bounds of the largest outputs, descending: at most `publishConcurrency` of them are written at once. */
+  top = [];
+  count = 0;
+  streams = 0;
+  planWork = 0;
+  operands = /* @__PURE__ */ new Set();
+  /** The cost of the group with `o` added. */
+  with(o) {
+    combineWork.withs++;
+    let streams = this.streams;
+    let operands = this.operands.size;
+    for (const i of o.compiled.operands) {
+      combineWork.operandSteps++;
+      if (!this.operands.has(i)) {
+        streams += this.streamBytes(i);
+        operands++;
+      }
+    }
+    const depth = Math.max(this.depth, o.compiled.depth);
+    const publishing = this.written(o.serializedBound);
+    return this.outputs + o.bound + streams + (operands + depth + 2) * WORKING_CHUNK + publishing + this.planWork + planWorkOf(o);
+  }
+  add(o) {
+    combineWork.adds++;
+    for (const i of o.compiled.operands) {
+      combineWork.operandSteps++;
+      if (!this.operands.has(i)) {
+        this.operands.add(i);
+        this.streams += this.streamBytes(i);
+      }
+    }
+    this.outputs += o.bound;
+    this.depth = Math.max(this.depth, o.compiled.depth);
+    this.top = this.withLargest(o.serializedBound);
+    this.count++;
+    this.planWork += planWorkOf(o);
+  }
+  get size() {
+    return this.count;
+  }
+  withLargest(bound) {
+    const top = [...this.top];
+    let at = top.length;
+    while (at > 0 && top[at - 1] < bound) at--;
+    top.splice(at, 0, bound);
+    if (top.length > this.publishConcurrency) top.length = this.publishConcurrency;
+    return top;
+  }
+  /**
+   * The bytes of objects being written beside the buffers, at most: the `publishConcurrency` largest outputs, each as
+   * large as its bound, with `bound` among the candidates.
+   */
+  written(bound) {
+    let sum = 0;
+    for (const b of this.withLargest(bound)) sum += b;
+    return sum;
+  }
+};
+var planWorkOf = (o) => o.rootKeys.byteLength * (1 + 2 * o.compiled.operands.length);
+var budgetError = (limit, what) => new BudgetExceededError(
+  `materializeMany: ${what} would hold more than maxBufferedBytes (${limit}) resident \u2014 raise maxBufferedBytes, or split the outputs across calls`
+);
+async function runCombineMany(compiled, deps) {
+  const run = new Run(compiled, deps);
+  return run.execute();
+}
+var Run = class {
+  req;
+  source;
+  codec;
+  clock;
+  maxBitmapBytes;
+  ledger;
+  gate = new Gate(MAX_RANGES_IN_FLIGHT2);
+  operands;
+  outputs;
+  tick;
+  window = null;
+  groups = 0;
+  rangeReads = 0;
+  rangeBytes = 0;
+  chunkReads = 0;
+  registryReads = 0;
+  publishes = 0;
+  opens = 0;
+  planCharge = 0;
+  attributedGet = 0;
+  attributedPut = 0;
+  planned = 0;
+  pruned = 0;
+  limit = null;
+  checkedFeed;
+  feed;
+  /** The index the first fed operand has among the call's operands: the stored ones come first. */
+  fedBase;
+  /** The outputs of the group that is running, for the ledger to evict from. */
+  running = [];
+  bounds;
+  constructor(compiled, deps) {
+    const checked = COMPILED.get(compiled);
+    if (checked === void 0) {
+      throw new ValidationError("runCombineMany takes the result of compileCombineMany");
+    }
+    const compiledOutputs = checked.outputs;
+    this.checkedFeed = checked.feed;
+    this.fedBase = compiled.request.operands.length;
+    this.req = compiled.request;
+    this.source = deps.source;
+    this.codec = deps.codec;
+    this.clock = deps.clock;
+    this.maxBitmapBytes = deps.maxBitmapBytes ?? DEFAULT_MAX_BITMAP_BYTES;
+    this.ledger = new ResidentLedger(this.req.maxBufferedBytes);
+    this.tick = yieldEvery(deps.clock, 256);
+    this.operands = this.req.operands.map((spec, index) => ({
+      index,
+      spec,
+      bounds: { keys: new Uint16Array(0), card: new Uint32Array(0) },
+      bytes: 0,
+      startGeneration: void 0,
+      endGeneration: void 0,
+      endRow: void 0,
+      startVersion: void 0,
+      indexKeys: 0,
+      chunkReads: 0,
+      read: false,
+      chunkless: false
+    }));
+    this.outputs = this.req.outputs.map((spec, index) => ({
+      index,
+      spec,
+      compiled: compiledOutputs[index],
+      rootKeys: new Uint16Array(0),
+      bound: 0,
+      serializedBound: 0,
+      status: "waiting",
+      chunks: [],
+      charged: 0,
+      peak: 0,
+      chunkCount: 0,
+      serialized: 0,
+      cursor: 0,
+      group: null,
+      startedAt: null,
+      endedAt: null,
+      solo: false
+    }));
+  }
+  async execute() {
+    this.window = windowOf2(this.req.after, this.req.through);
+    if (this.checkedFeed !== void 0) this.feed = this.openFeed(this.checkedFeed);
+    this.indexHeld();
+    await this.readIndexes();
+    await this.refuseAbsent();
+    this.planOutputs();
+    const groups = this.formGroups(
+      this.outputs.filter((o) => o.status === "waiting"),
+      this.feed !== void 0
+    );
+    this.settleBudget(groups);
+    for (const group of groups) await this.runGroup(group.outputs, group);
+    for (; ; ) {
+      const deferred = this.outputs.filter((o) => o.status === "deferred");
+      if (deferred.length === 0) break;
+      for (const output of deferred) {
+        output.status = "waiting";
+        output.solo = true;
+        await this.runGroup([output.index]);
+      }
+    }
+    await this.readEnds();
+    return { outputs: this.outputs.map((o) => o.outcome ?? this.neverRan()), stats: this.stats() };
+  }
+  openFeed(feed) {
+    const w = this.window;
+    return new FeedCursor({
+      feed,
+      codec: this.codec,
+      base: this.fedBase,
+      charge: (bytes) => {
+        if (!this.ledger.reserve(bytes, () => this.reclaim())) {
+          throw budgetError(this.req.maxBufferedBytes, "the feed");
+        }
+      },
+      release: (bytes) => this.ledger.release(bytes),
+      tick: this.tick,
+      inWindow: (key) => w === "empty" ? false : w === null || key >= w.loKey && key <= w.hiKey
+    });
+  }
+  /** Whether the store's erasure counter has moved since the call began: always `false` without a feed. */
+  erased() {
+    const epoch = this.checkedFeed?.epoch;
+    return epoch?.moved() === true;
+  }
+  /** What an output that read fed operands gets when an erasure ran in the store since the call began. */
+  staleError(o) {
+    const names = this.checkedFeed.names;
+    return new StaleOperandError(
+      "materializeMany: an erasure ran in this store after the call began, so the operands it was fed may hold an erased id and its fed outputs were not published. Run the call again, with a feed read after the erasure.",
+      names[o.compiled.fed[0] - this.fedBase] ?? "",
+      "erased"
+    );
+  }
+  /**
+   * Refuse every fed output not yet published, and stop reading the feed. `error` is what the feed (or the budget, or an
+   * erasure) found; stored-only outputs are untouched.
+   */
+  failFed(error) {
+    this.feed?.close();
+    for (const o of this.outputs) {
+      if (o.compiled.fed.length === 0 || o.status === "done") continue;
+      this.fail(o, error instanceof FeedStale ? this.staleError(o) : error);
+    }
+  }
+  /**
+   * Make room in the ledger. A fed output cannot be run again (the feed is read once), so a fed call gives up its fed
+   * outputs and the feed first, as soon as the ledger passes the budget; only then is a stored-only buffer evicted, to run
+   * again alone.
+   */
+  reclaim() {
+    if (this.feed !== void 0) {
+      let fed = this.feed.heldBytes;
+      for (const o of this.running)
+        if (o.compiled.fed.length > 0 && o.status === "live") fed += o.charged;
+      if (fed > 0) {
+        this.failFed(budgetError(this.req.maxBufferedBytes, "the feed and the fed outputs"));
+        return true;
+      }
+    }
+    return this.evictLargest(this.running);
+  }
+  neverRan() {
+    return { ok: false, error: new Error("materializeMany: output did not run") };
+  }
+  // ---- index ------------------------------------------------------------------------------------------------
+  /** What an output that reads the held operand `op` gets when an erasure ran in the store since it was made. */
+  staleHeldError(op) {
+    return new StaleOperandError(
+      `materializeMany: an erasure ran in this store after operand "${op.spec.name}" was made, so it may hold an erased id and the outputs that read it were not published. Make it again from the source of truth, after the erasure, and run the call again.`,
+      op.spec.name,
+      "erased"
+    );
+  }
+  /** The error of the first held operand `o` reads that an erasure has made stale, if any. */
+  staleHeld(o) {
+    for (const i of o.compiled.operands) {
+      const op = this.operands[i];
+      if (op.spec.held?.moved() === true) return this.staleHeldError(op);
+    }
+    return void 0;
+  }
+  /**
+   * Index the held operands the outputs read, before any request: their keys and exact cardinalities are in memory, and
+   * one that an erasure has made stale is failed here, so the outputs that read it fail without a read.
+   */
+  indexHeld() {
+    const wanted = /* @__PURE__ */ new Set();
+    for (const o of this.outputs) for (const op of o.compiled.operands) wanted.add(op);
+    if (this.window === "empty") return;
+    const w = this.window;
+    const charged = /* @__PURE__ */ new Set();
+    let resident = 0;
+    for (const index of wanted) {
+      const op = this.operands[index];
+      const held = op.spec.held;
+      if (held === void 0) continue;
+      op.read = true;
+      if (held.moved()) {
+        op.error = { error: this.staleHeldError(op) };
+        continue;
+      }
+      if (!charged.has(held.chunks)) {
+        charged.add(held.chunks);
+        resident += held.chunks.residentBytes;
+      }
+      const all = held.chunks.keys;
+      const cards = held.chunks.cardinalities;
+      const keep = [];
+      const card = [];
+      for (let i = 0; i < all.length; i++) {
+        const key = all[i];
+        if (w !== null && (key < w.loKey || key > w.hiKey)) continue;
+        keep.push(key);
+        card.push(cards[i]);
+      }
+      op.bounds = { keys: Uint16Array.from(keep), card: Uint32Array.from(card) };
+      op.indexKeys = keep.length;
+      op.chunkless = all.length === 0;
+    }
+    if (resident > 0) this.chargePlan(resident, "the held operands");
+  }
+  async readIndexes() {
+    const wanted = /* @__PURE__ */ new Set();
+    for (const o of this.outputs) for (const op of o.compiled.operands) wanted.add(op);
+    if (this.window === "empty") return;
+    for (const index of wanted) this.operands[index].read = true;
+    const w = this.window;
+    const stored = [...wanted].filter((index) => this.operands[index].spec.held === void 0);
+    await mapWithConcurrency(stored, INDEX_PARALLELISM, async (index) => {
+      const op = this.operands[index];
+      try {
+        const listed = checkedChunkKeys(await this.source.listChunkKeys(op.spec.ref));
+        const keys = w === null ? listed : within2(listed, w);
+        const cards = await this.source.cardinalities?.(op.spec.ref);
+        const card = new Uint32Array(keys.length);
+        let serialized = 0;
+        for (let i = 0; i < keys.length; i++) {
+          const given = cards?.get(keys[i]);
+          if (given !== void 0) assertChunkCardinalityInRange(given);
+          card[i] = given ?? 65536;
+          serialized += serializedBound(card[i]);
+        }
+        this.opens++;
+        const size = (await this.source.sizeOf?.(op.spec.ref))?.sizeBytes;
+        op.startGeneration = await this.source.currentGeneration?.(op.spec.ref);
+        if (op.spec.pinnedGeneration === void 0) {
+          op.startVersion = await this.source.currentVersion?.(op.spec.ref);
+        }
+        op.bounds = { keys: Uint16Array.from(keys), card };
+        op.indexKeys = keys.length;
+        const window = this.req.concurrency * (RANGE_BYTES + 28);
+        op.bytes = Math.min(window, size ?? serialized + 64);
+        op.chunkless = listed.length === 0;
+      } catch (error) {
+        op.error = { error };
+      }
+    });
+  }
+  /**
+   * An operand that names no segment would contribute nothing: refused, as a combine refuses it, for every operand of
+   * the call. One whose index was read is judged only if it has no chunk at all; one whose index was not read (no output
+   * names it, or the range is empty) is asked outright.
+   */
+  async refuseAbsent() {
+    if (this.req.allowAbsentOperands === true || this.source.exists === void 0) return;
+    const judged = this.operands.filter(
+      (op) => op.spec.held === void 0 && op.error === void 0 && (op.read ? op.chunkless : true)
+    );
+    if (judged.length === 0) return;
+    const exists = this.source.exists.bind(this.source);
+    const checked = await mapWithConcurrency(judged, INDEX_PARALLELISM, async (op) => {
+      this.registryReads++;
+      return { op, exists: await exists(op.spec.ref) };
+    });
+    const absent = checked.filter((c) => !c.exists).map((c) => c.op.spec.name);
+    if (absent.length === 0) return;
+    throw new ValidationError(
+      `materializeMany: operand ${absent.map((n) => `"${n}"`).join(", ")} names a segment that does not exist, so it would contribute nothing \u2014 an exclude would suppress no ids and an include would contribute none. Check the name and the namespace (a segment addressed without its \`namespace\` is a DIFFERENT segment). Pass \`allowAbsentOperands: true\` if you meant it.`
+    );
+  }
+  // ---- plan -------------------------------------------------------------------------------------------------
+  /** The stored operands' bounds, then one that holds any key for each fed operand. */
+  boundsList() {
+    if (this.bounds === void 0) {
+      const fed = this.checkedFeed?.names.length ?? 0;
+      this.bounds = [
+        ...this.operands.map((op) => op.bounds),
+        ...Array(fed).fill(ANY_BOUNDS)
+      ];
+    }
+    return this.bounds;
+  }
+  /** Charge plan state that lives for the whole call, refusing a plan that alone passes the budget. */
+  chargePlan(bytes, what) {
+    if (this.ledger.tryCharge(bytes)) {
+      this.planCharge += bytes;
+      return;
+    }
+    throw new BudgetExceededError(
+      `materializeMany: the plan alone (${what}) passes maxBufferedBytes (${this.req.maxBufferedBytes}) with ${this.planCharge} bytes already held for it, before any chunk is read \u2014 raise maxBufferedBytes, or split the outputs across calls`
+    );
+  }
+  planOutputs() {
+    for (const op of this.operands) {
+      if (op.read && op.error === void 0) {
+        this.chargePlan(
+          op.bounds.keys.byteLength + op.bounds.card.byteLength,
+          "the operand indexes"
+        );
+      }
+    }
+    const bounds = this.boundsList();
+    for (const o of this.outputs) {
+      const failed = o.compiled.operands.map((i) => this.operands[i]).find((op) => op.error);
+      if (failed?.error !== void 0) {
+        this.fail(o, failed.error.error);
+        continue;
+      }
+      if (this.window === "empty") {
+        o.status = "waiting";
+        continue;
+      }
+      const root = planKeys(o.compiled.node, bounds);
+      o.rootKeys = root.keys;
+      this.chargePlan(
+        root.keys.byteLength + o.compiled.nodes * BYTES_PER_NODE + BYTES_PER_OUTPUT,
+        `${o.index + 1} outputs planned`
+      );
+      let resident = 0;
+      let serialized = 0;
+      for (let i = 0; i < root.keys.length; i++) {
+        resident += residentBound(root.card[i]);
+        serialized += serializedBound(root.card[i]);
+      }
+      o.bound = resident;
+      o.serializedBound = serialized;
+      o.status = "waiting";
+    }
+  }
+  /** The bytes a group may take: the budget less what the plan holds. */
+  get room() {
+    return this.req.maxBufferedBytes - this.planCharge;
+  }
+  /** Outputs in call order, a group at a time while the ledger has room for the next. */
+  formGroups(waiting, single) {
+    const groups = [];
+    const fresh = () => new GroupCost((i) => this.operands[i].bytes, this.req.publishConcurrency);
+    let cost = fresh();
+    let kept = 0;
+    let current = [];
+    const flush = () => {
+      if (current.length > 0) {
+        const plan = this.buildGroup(current);
+        const summary = {
+          outputs: current.map((o) => o.index),
+          reads: plan.reads,
+          pruned: plan.pruned
+        };
+        if (kept + plan.planBytes <= PLAN_KEEP_BYTES && this.ledger.tryCharge(plan.planBytes)) {
+          kept += plan.planBytes;
+          this.planCharge += plan.planBytes;
+          summary.plan = plan;
+        }
+        groups.push(summary);
+      }
+      current = [];
+      cost = fresh();
+    };
+    for (const o of waiting) {
+      const alone = fresh().with(o);
+      if (alone > this.room) {
+        this.fail(
+          o,
+          new BudgetExceededError(
+            `materializeMany: output ${o.index} needs about ${alone} bytes resident with its operands, and the plan holds ${this.planCharge}, over maxBufferedBytes (${this.req.maxBufferedBytes}) \u2014 raise maxBufferedBytes to at least ${alone + this.planCharge}`
+          )
+        );
+        continue;
+      }
+      if (!single && cost.size > 0 && cost.with(o) > this.room) flush();
+      current.push(o);
+      cost.add(o);
+    }
+    flush();
+    return groups;
+  }
+  /** The keys each operand is fetched at for `members`, and the keys the pass visits. */
+  buildGroup(members) {
+    combineWork.planBuilds++;
+    const bounds = this.boundsList();
+    const bits = /* @__PURE__ */ new Map();
+    const visit = new KeyBits();
+    const demand = /* @__PURE__ */ new Map();
+    let planBytes = 0;
+    for (const o of members) {
+      visit.add(o.rootKeys);
+      const planned = /* @__PURE__ */ new Map();
+      planKeys(o.compiled.node, bounds, planned);
+      const own = /* @__PURE__ */ new Map();
+      collectFetch(o.compiled.node, o.rootKeys, bounds, planned, (operand, keys) => {
+        let set = bits.get(operand);
+        if (set === void 0) bits.set(operand, set = new KeyBits());
+        set.add(keys);
+        let mine = own.get(operand);
+        if (mine === void 0) own.set(operand, mine = new KeyBits());
+        mine.add(keys);
+      });
+      const lists = /* @__PURE__ */ new Map();
+      for (const [operand, set] of own) {
+        const keys = Uint16Array.from(set.toKeys());
+        lists.set(operand, keys);
+        planBytes += keys.byteLength;
+      }
+      demand.set(o.index, lists);
+    }
+    const fetch = /* @__PURE__ */ new Map();
+    let reads = 0;
+    let pruned = 0;
+    let fixed = 0;
+    for (const [operand, set] of [...bits.entries()].sort((a, b) => a[0] - b[0])) {
+      const keys = Uint16Array.from(set.toKeys());
+      fetch.set(operand, keys);
+      visit.add(keys);
+      planBytes += keys.byteLength;
+      reads += set.size;
+      pruned += this.operands[operand].indexKeys - set.size;
+      fixed += this.operands[operand].bytes;
+    }
+    const visited = Uint16Array.from(visit.toKeys());
+    return {
+      outputs: members.map((o) => o.index),
+      demand,
+      fetch,
+      keys: visited,
+      reads,
+      pruned,
+      fixedBytes: fixed,
+      planBytes: planBytes + visited.byteLength
+    };
+  }
+  settleBudget(groups) {
+    this.planned = groups.reduce((sum, g) => sum + g.reads, 0);
+    const given = this.req.budget;
+    if (given === null) {
+      this.limit = null;
+    } else if (given === void 0) {
+      this.limit = this.planned * BUDGET_HEADROOM_FACTOR + BUDGET_HEADROOM_FLOOR;
+    } else {
+      this.limit = given.maxRequests;
+      if (this.planned > this.limit) {
+        throw new BudgetExceededError(
+          `materializeMany would read ${this.planned} chunks over ${groups.length} group(s), over the budget of ${this.limit} \u2014 raise \`budget.maxRequests\`, raise maxBufferedBytes so fewer groups re-read the operands, or set \`budget: false\``
+        );
+      }
+    }
+  }
+  // ---- outcomes ---------------------------------------------------------------------------------------------
+  fail(o, error) {
+    this.dropBuffer(o);
+    if (o.outcome === void 0) o.outcome = { ok: false, error };
+    o.status = "done";
+    o.endedAt ??= o.startedAt === null ? null : this.clock.now();
+  }
+  dropBuffer(o) {
+    this.ledger.release(o.charged);
+    o.chunks = [];
+    o.charged = 0;
+    o.serialized = 0;
+  }
+  // ---- one group --------------------------------------------------------------------------------------------
+  async runGroup(indices, summary) {
+    const members = indices.map((i) => this.outputs[i]).filter((o) => o.status === "waiting");
+    if (members.length === 0) return;
+    const kept = summary?.plan;
+    if (summary !== void 0) summary.plan = void 0;
+    if (kept !== void 0) {
+      this.ledger.release(kept.planBytes);
+      this.planCharge -= kept.planBytes;
+    }
+    const plan = kept !== void 0 && members.length === indices.length ? kept : this.buildGroup(members);
+    const group = this.groups++;
+    const budget = this.limit;
+    if (budget !== null && this.chunkReads + plan.reads > budget) {
+      const error = new BudgetExceededError(
+        `materializeMany: re-running outputs would read ${plan.reads} more chunks, past the budget of ${budget} (${this.chunkReads} read)`
+      );
+      for (const o of members) this.fail(o, error);
+      return;
+    }
+    const startedAt = this.clock.now();
+    for (const o of members) {
+      o.status = "live";
+      o.group = group;
+      o.startedAt = startedAt;
+      o.cursor = 0;
+      o.chunkCount = 0;
+      o.peak = 0;
+    }
+    this.pruned += plan.pruned;
+    const fixed = plan.fixedBytes + plan.planBytes;
+    if (!this.ledger.tryCharge(fixed)) {
+      const error = budgetError(this.req.maxBufferedBytes, "the operand streams");
+      for (const o of members) this.fail(o, error);
+      return;
+    }
+    this.running = members;
+    try {
+      await this.pass(plan, members);
+    } catch (error) {
+      for (const o of members) if (o.status === "live") this.fail(o, error);
+    } finally {
+      this.ledger.release(fixed);
+    }
+    const survivors = members.filter((o) => o.status === "live");
+    if (survivors.length > 0) await this.publishWave(survivors);
+  }
+  /** Evict the biggest buffer of a group still running so another charge can fit; it is re-run alone later. */
+  evictLargest(members) {
+    const live = members.filter((o) => o.status === "live");
+    if (live.length <= 1) return false;
+    let biggest;
+    for (const o of live) {
+      if (o.charged > 0 && (biggest === void 0 || o.charged > biggest.charged)) biggest = o;
+    }
+    if (biggest === void 0) return false;
+    this.dropBuffer(biggest);
+    biggest.status = "deferred";
+    biggest.group = null;
+    biggest.startedAt = null;
+    return true;
+  }
+  /** The chunks of `key` of every operand a group fetches: a stream per operand, read in step, one key at a time. */
+  async pass(plan, members) {
+    const readers = /* @__PURE__ */ new Map();
+    for (const o of members) {
+      for (const op of o.compiled.operands) {
+        let list = readers.get(op);
+        if (list === void 0) readers.set(op, list = []);
+        list.push(o);
+      }
+    }
+    const cursors = [];
+    for (const [index, keys] of plan.fetch) {
+      cursors.push({
+        op: this.operands[index],
+        keys,
+        next: 0,
+        stream: void 0,
+        done: false,
+        failure: void 0
+      });
+    }
+    const retry = (request) => this.gate.run(request);
+    const onRequest = (r) => {
+      this.rangeReads++;
+      this.rangeBytes += r.bytes;
+    };
+    const streamOf = (c) => {
+      c.stream ??= new ChunkStream(this.readKeys(c.op, c.keys, retry, onRequest));
+      return c.stream;
+    };
+    const stop = (c) => {
+      c.done = true;
+      c.stream?.close();
+    };
+    const failOperand = (c, error, victims) => {
+      stop(c);
+      c.failure = { error };
+      for (const o of victims) if (o.status === "live") this.fail(o, error);
+    };
+    const w = this.window === "empty" ? null : this.window;
+    const makeRoom = () => this.reclaim();
+    const feed = this.feed !== void 0 && this.feed.active ? this.feed : void 0;
+    const fedBase = this.fedBase;
+    let at = 0;
+    try {
+      for (; ; ) {
+        if (!members.some((o) => o.status === "live")) break;
+        if (feed?.active === true && !members.some((o) => o.status === "live" && o.compiled.fed.length > 0)) {
+          feed.close();
+        }
+        let feedKey;
+        if (feed?.active === true) {
+          try {
+            feedKey = await feed.nextKey();
+          } catch (error) {
+            if (!(error instanceof FeedClosed)) this.failFed(error);
+          }
+        }
+        const storedKey = at < plan.keys.length ? plan.keys[at] : void 0;
+        const key = storedKey === void 0 ? feedKey : feedKey === void 0 ? storedKey : Math.min(storedKey, feedKey);
+        if (key === void 0) break;
+        if (storedKey === key) at++;
+        let fedHere;
+        if (feedKey === key && feed !== void 0) {
+          try {
+            await feed.completeKey();
+            fedHere = feed.take();
+          } catch (error) {
+            if (!(error instanceof FeedClosed)) this.failFed(error);
+          }
+        }
+        const holds = (operand) => operand >= fedBase ? fedHere?.has(operand) === true : hasKey(this.operands[operand].bounds.keys, key);
+        const needs = (o) => o.compiled.fed.length === 0 || canHold(o.compiled.node, holds);
+        try {
+          const exact = feed !== void 0 || members.some((o) => o.status !== "live");
+          const cursorsAt = [];
+          const wanting = (c) => (readers.get(c.op.index) ?? []).filter(
+            (o) => o.status === "live" && hasKey(plan.demand.get(o.index)?.get(c.op.index), key) && needs(o)
+          );
+          for (const c of cursors) {
+            if (c.keys[c.next] !== key) continue;
+            const victims = exact || c.failure !== void 0 ? wanting(c) : void 0;
+            if (c.failure !== void 0) {
+              c.next++;
+              for (const o of victims ?? []) this.fail(o, c.failure.error);
+              continue;
+            }
+            if (c.done) {
+              c.next++;
+              continue;
+            }
+            if (!(readers.get(c.op.index) ?? []).some((o) => o.status === "live")) {
+              stop(c);
+              c.next++;
+              continue;
+            }
+            if (victims === void 0 || victims.length > 0) {
+              try {
+                c.op.spec.check?.();
+              } catch (error) {
+                c.next++;
+                failOperand(c, error, victims ?? wanting(c));
+                continue;
+              }
+            }
+            cursorsAt.push({ c, victims });
+          }
+          const settled2 = await Promise.allSettled(cursorsAt.map(({ c }) => streamOf(c).take(key)));
+          const decoded = /* @__PURE__ */ new Map();
+          let held = 0;
+          try {
+            for (let i = 0; i < cursorsAt.length; i++) {
+              const { c, victims } = cursorsAt[i];
+              const result = settled2[i];
+              c.next++;
+              if (c.done) continue;
+              if (result.status === "rejected") {
+                failOperand(c, result.reason, victims ?? wanting(c));
+                continue;
+              }
+              this.chunkReads++;
+              c.op.chunkReads++;
+              if (victims !== void 0 && victims.length === 0) continue;
+              const bytes = result.value.bytes;
+              if (bytes === null) {
+                failOperand(
+                  c,
+                  new IntegrityError(
+                    `operand "${c.op.spec.name}" lists chunk ${key} but its generation holds no bytes for it`
+                  ),
+                  victims ?? wanting(c)
+                );
+                continue;
+              }
+              try {
+                const resident = residentBytes(bytes.length);
+                if (!this.ledger.reserve(resident, makeRoom)) {
+                  throw budgetError(
+                    this.req.maxBufferedBytes,
+                    `operand "${c.op.spec.name}" at chunk ${key}`
+                  );
+                }
+                held += resident;
+                decoded.set(
+                  c.op.index,
+                  decodeChunkBytes(this.codec, bytes, key, this.maxBitmapBytes)
+                );
+              } catch (error) {
+                failOperand(c, error, victims ?? wanting(c));
+              }
+            }
+            const chunks = {
+              get: (operand) => operand >= fedBase ? fedHere?.get(operand) : decoded.get(operand)
+            };
+            for (const o of members) {
+              if (o.status !== "live") continue;
+              if (o.compiled.fed.length > 0) {
+                if (!needs(o)) continue;
+              } else {
+                const roots = o.rootKeys;
+                while (o.cursor < roots.length && roots[o.cursor] < key) o.cursor++;
+                if (o.cursor >= roots.length || roots[o.cursor] !== key) continue;
+                o.cursor++;
+              }
+              const kc = new KeyContext(this.ledger, makeRoom, chunks);
+              try {
+                this.evaluateInto(o, key, kc, w, makeRoom);
+              } catch (error) {
+                kc.reset();
+                if (o.status === "live") this.fail(o, error);
+              }
+              const pause = this.tick();
+              if (pause !== null) await pause;
+            }
+          } finally {
+            this.ledger.release(held);
+          }
+        } finally {
+          feed?.release();
+        }
+      }
+      if (feed !== void 0 && !feed.complete) {
+        this.failFed(new IntegrityError("materializeMany: the feed was not read to its end"));
+      }
+    } finally {
+      for (const c of cursors) c.stream?.close();
+      if (feed !== void 0) {
+        feed.close();
+        await feed.drained();
+      }
+    }
+  }
+  /** The operand's chunks at `keys` as a stream: the source's coalesced ranges, or chunk by chunk where it has none. */
+  readKeys(op, wanted, retry, onRequest) {
+    const source = this.source;
+    const keys = Array.from(wanted);
+    const held = op.spec.held;
+    if (held !== void 0) {
+      const stale = () => this.staleHeldError(op);
+      return {
+        // Each chunk is checked and read in one step with no wait between, so a release or an erasure cannot land after
+        // the check and before the bytes.
+        async *[Symbol.asyncIterator]() {
+          for (const key of keys) {
+            if (held.moved()) throw stale();
+            const bytes = held.chunks.payload(key);
+            yield { key, bytes: bytes === null ? null : new Uint8Array(bytes), version: null };
+          }
+        }
+      };
+    }
+    const ref = op.spec.ref;
+    if (source.getChunks !== void 0) {
+      return source.getChunks(ref, keys, { concurrency: this.req.concurrency, retry, onRequest });
+    }
+    return {
+      async *[Symbol.asyncIterator]() {
+        for (const key of keys) {
+          const bytes = await retry(() => source.getChunk({ ...ref, chunkKey: key }));
+          onRequest({ bytes: bytes?.length ?? 0, ms: 0 });
+          yield { key, bytes, version: null };
+        }
+      }
+    };
+  }
+  /** Evaluate `o` at `key` and buffer the chunk when it is not empty. */
+  evaluateInto(o, key, kc, w, makeRoom) {
+    const result = evaluate(o.compiled.node, kc);
+    if (result === null) return;
+    let held = kc.owned(result);
+    if (held.bitmap.isEmpty) {
+      kc.drop(held);
+      return;
+    }
+    if (w !== null && isEdge2(key, w)) {
+      const cut = cutToWindow(this.codec, held.bitmap, key, w);
+      kc.drop(held);
+      if (cut.isEmpty) return;
+      const charge = residentBound(cut.size);
+      kc.take(charge);
+      held = { bitmap: cut, owned: true, charge };
+    }
+    const size = held.bitmap.size;
+    const resident = residentBound(size);
+    kc.drop(held);
+    if (!this.ledger.reserve(resident, makeRoom)) {
+      throw budgetError(this.req.maxBufferedBytes, `output ${o.index}`);
+    }
+    if (o.status !== "live") {
+      this.ledger.release(resident);
+      return;
+    }
+    o.charged += resident;
+    if (o.charged > o.peak) o.peak = o.charged;
+    o.serialized += serializedBound(size);
+    o.chunks.push({ chunkKey: key, bitmap: held.bitmap });
+    o.chunkCount = o.chunks.length;
+  }
+  // ---- publish ----------------------------------------------------------------------------------------------
+  /** Re-check the pinned operands the survivors subtract, then publish what is left, `publishConcurrency` at a time. */
+  async publishWave(survivors) {
+    const toCheck = /* @__PURE__ */ new Set();
+    for (const o of survivors) {
+      for (const i of o.compiled.subtracted) {
+        const spec = this.operands[i].spec;
+        if (spec.pinnedGeneration !== void 0 && spec.current !== void 0) toCheck.add(i);
+      }
+    }
+    const verdict = /* @__PURE__ */ new Map();
+    await mapWithConcurrency([...toCheck], INDEX_PARALLELISM, async (i) => {
+      const op = this.operands[i];
+      try {
+        const now = await this.readRow(op, true);
+        if (!pinnedStillCurrent(op.spec, now)) {
+          verdict.set(
+            i,
+            new StaleOperandError(
+              `materializeMany: operand "${op.spec.name}", subtracted by an output, was replaced while the call ran (pinned at generation ${String(op.spec.pinnedGeneration)}; the registry now holds ${now === null ? "no row" : `generation ${String(now.generation)}, and its row or its object is not the pinned one`}), so its outputs were not published. Run the call again to subtract the current one.`,
+              op.spec.name,
+              "moved"
+            )
+          );
+        }
+      } catch (error) {
+        verdict.set(i, error);
+      }
+    });
+    for (const o of survivors) {
+      for (const i of o.compiled.subtracted) {
+        if (verdict.has(i)) {
+          this.fail(o, verdict.get(i));
+          break;
+        }
+      }
+    }
+    const queue = survivors.filter((o) => o.status === "live");
+    let next = 0;
+    let inFlight = 0;
+    let waiters = [];
+    const wake = () => {
+      const now = waiters;
+      waiters = [];
+      for (const resolve2 of now) resolve2();
+    };
+    const worker = async () => {
+      for (; ; ) {
+        const o = queue[next++];
+        if (o === void 0) return;
+        if (o.compiled.fed.length > 0 && this.erased()) {
+          this.fail(o, this.staleError(o));
+          continue;
+        }
+        try {
+          o.spec.beforePublish?.();
+        } catch (error) {
+          this.fail(o, error);
+          continue;
+        }
+        const transient = o.serialized;
+        let admitted = this.ledger.tryCharge(transient);
+        while (!admitted && inFlight > 0) {
+          await new Promise((resolve2) => waiters.push(resolve2));
+          admitted = this.ledger.tryCharge(transient);
+        }
+        if (!admitted) {
+          if (o.solo || o.compiled.fed.length > 0) {
+            this.fail(o, budgetError(this.req.maxBufferedBytes, `publishing output ${o.index}`));
+          } else {
+            this.dropBuffer(o);
+            o.status = "deferred";
+            o.group = null;
+            o.startedAt = null;
+          }
+          wake();
+          continue;
+        }
+        const staleHeld = this.staleHeld(o);
+        if (staleHeld !== void 0) {
+          this.ledger.release(transient);
+          this.fail(o, staleHeld);
+          wake();
+          continue;
+        }
+        if (o.compiled.fed.length > 0 && this.erased()) {
+          this.ledger.release(transient);
+          this.fail(o, this.staleError(o));
+          wake();
+          continue;
+        }
+        inFlight++;
+        this.publishes++;
+        const chunks = o.chunks;
+        try {
+          const value = await o.spec.publish(
+            {
+              async *[Symbol.asyncIterator]() {
+                for (const c of chunks) yield c;
+              }
+            },
+            o.compiled.write
+          );
+          o.outcome = { ok: true, value };
+          const proven = o.spec.requestsOf?.(value);
+          if (proven !== void 0) {
+            this.attributedGet += proven.get;
+            this.attributedPut += proven.put;
+          }
+        } catch (error) {
+          o.outcome = { ok: false, error };
+        } finally {
+          inFlight--;
+          this.ledger.release(transient);
+          this.dropBuffer(o);
+          o.status = "done";
+          o.endedAt = this.clock.now();
+          wake();
+        }
+      }
+    };
+    await Promise.all(
+      Array.from({ length: Math.min(this.req.publishConcurrency, queue.length) }, () => worker())
+    );
+  }
+  /** A fresh read of the operand's row, remembered as where the operand stood last. */
+  async readRow(op, fingerprint = false) {
+    this.registryReads++;
+    const row = await op.spec.current({ fingerprint }) ?? null;
+    op.endRow = row;
+    op.endGeneration = row?.generation ?? null;
+    return row;
+  }
+  /** Where every operand stands when the call ends: one row read each, the re-checked ones already read. */
+  async readEnds() {
+    const pending = this.operands.filter(
+      (op) => op.endRow === void 0 && op.spec.current !== void 0
+    );
+    await mapWithConcurrency(pending, INDEX_PARALLELISM, async (op) => {
+      try {
+        await this.readRow(op);
+      } catch {
+      }
+    });
+  }
+  // ---- stats ------------------------------------------------------------------------------------------------
+  stats() {
+    const operands = /* @__PURE__ */ Object.create(null);
+    for (const op of this.operands) {
+      const pinned = op.spec.pinnedGeneration !== void 0;
+      const moved = op.endRow === void 0 ? void 0 : pinned ? !pinnedStillCurrent(op.spec, op.endRow) : liveMoved(op);
+      operands[op.spec.name] = {
+        read: op.read,
+        pinned: op.spec.pinnedGeneration !== void 0,
+        pinnedGeneration: op.spec.pinnedGeneration,
+        startGeneration: op.startGeneration,
+        endGeneration: op.endGeneration,
+        moved,
+        keys: op.indexKeys,
+        chunkReads: op.chunkReads
+      };
+    }
+    return {
+      groups: this.groups,
+      requests: {
+        rangeReads: this.rangeReads,
+        rangeBytes: this.rangeBytes,
+        chunkReads: this.chunkReads,
+        registryReads: this.registryReads,
+        opens: this.opens,
+        publishes: this.publishes,
+        attributed: {
+          get: this.rangeReads + this.registryReads + this.attributedGet,
+          put: this.attributedPut
+        }
+      },
+      budget: { maxRequests: this.limit, planned: this.planned, used: this.chunkReads },
+      memory: {
+        maxBufferedBytes: this.req.maxBufferedBytes,
+        highWaterBytes: this.ledger.highWater,
+        planBytes: this.planCharge
+      },
+      chunks: { pruned: this.pruned },
+      maxRangesInFlight: this.gate.highWater,
+      ...this.feed === void 0 ? {} : { feed: this.feed.stats },
+      operands,
+      outputs: this.outputs.map((o) => ({
+        operands: [
+          ...o.compiled.operands.map((i) => this.operands[i].spec.name),
+          ...o.compiled.fed.map((i) => this.checkedFeed.names[i - this.fedBase])
+        ],
+        group: o.group,
+        startedAt: o.startedAt,
+        endedAt: o.endedAt,
+        chunks: o.chunkCount,
+        boundBytes: o.bound,
+        peakBytes: o.peak
+      }))
+    };
+  }
+};
+function tokenOfVersion(version) {
+  if (version == null) return void 0;
+  const colon = version.indexOf(":");
+  return colon < 0 ? void 0 : version.slice(colon + 1);
+}
+function sameRow2(a, b) {
+  const ia = incarnationOf(a);
+  const ib = incarnationOf(b);
+  return ia !== void 0 || ib !== void 0 ? ia === ib : a === b;
+}
+function pinnedStillCurrent(spec, now) {
+  const pinned = spec.pinnedGeneration ?? null;
+  if (pinned !== (now?.generation ?? null)) return false;
+  if (pinned === null || now === null) return true;
+  const was = tokenOfVersion(spec.pinnedVersion);
+  if (was !== void 0 && !sameRow2(was, now.token)) return false;
+  const held = spec.pinnedFingerprint;
+  return held == null || now.fingerprint == null || held === now.fingerprint;
+}
+function liveMoved(op) {
+  if (op.endRow === void 0 || !op.read) return void 0;
+  const was = tokenOfVersion(op.startVersion);
+  if (was !== void 0 && op.endRow !== null && !sameRow2(was, op.endRow.token)) return true;
+  return op.startGeneration === void 0 ? void 0 : op.endGeneration !== op.startGeneration;
+}
+function hasKey(keys, key) {
+  if (keys === void 0) return false;
+  let lo = 0;
+  let hi = keys.length;
+  while (lo < hi) {
+    const mid = lo + hi >>> 1;
+    if (keys[mid] < key) lo = mid + 1;
+    else hi = mid;
+  }
+  return lo < keys.length && keys[lo] === key;
+}
+function within2(keys, w) {
+  return keys.filter((k) => k >= w.loKey && k <= w.hiKey);
+}
+var KeyContext = class {
+  constructor(ledger, makeRoom, chunks) {
+    this.ledger = ledger;
+    this.makeRoom = makeRoom;
+    this.chunks = chunks;
+  }
+  ledger;
+  makeRoom;
+  chunks;
+  temp = 0;
+  /** Charge `bytes` for a bitmap this evaluation made. */
+  take(bytes) {
+    if (!this.ledger.reserve(bytes, this.makeRoom)) {
+      throw budgetError(this.ledger.limit, "a chunk being evaluated");
+    }
+    this.temp += bytes;
+  }
+  drop(held) {
+    if (!held.owned) return;
+    this.ledger.release(held.charge);
+    this.temp -= held.charge;
+    held.charge = 0;
+  }
+  /** `held` as a bitmap this evaluation owns and may change: a clone of one borrowed from the operand chunks. */
+  owned(held) {
+    if (held.owned) return held;
+    const charge = residentBound(held.bitmap.size);
+    this.take(charge);
+    return { bitmap: held.bitmap.clone(), owned: true, charge };
+  }
+  /** Re-price an owned bitmap that grew. */
+  regrow(held) {
+    const want = residentBound(held.bitmap.size);
+    if (want > held.charge) {
+      this.take(want - held.charge);
+      held.charge = want;
+    }
+  }
+  /** Give back every charge a failed evaluation still holds. */
+  reset() {
+    this.ledger.release(this.temp);
+    this.temp = 0;
+  }
+};
+function evaluate(node, kc) {
+  if (node.kind === "leaf") {
+    const chunk = kc.chunks.get(node.operand);
+    return chunk === void 0 || chunk.isEmpty ? null : { bitmap: chunk, owned: false, charge: 0 };
+  }
+  let acc = null;
+  if (node.kind === "and") {
+    for (const kid of node.kids) {
+      const r = evaluate(kid, kc);
+      if (r === null || r.bitmap.isEmpty) {
+        if (r !== null) kc.drop(r);
+        if (acc !== null) kc.drop(acc);
+        return null;
+      }
+      if (acc === null) {
+        acc = kc.owned(r);
+      } else {
+        acc.bitmap.andInPlace(r.bitmap);
+        kc.drop(r);
+        if (acc.bitmap.isEmpty) {
+          kc.drop(acc);
+          return null;
+        }
+      }
+    }
+    return acc;
+  }
+  if (node.kind === "or") {
+    for (const kid of node.kids) {
+      const r = evaluate(kid, kc);
+      if (r === null) continue;
+      if (acc === null) {
+        acc = kc.owned(r);
+      } else {
+        acc.bitmap.orInPlace(r.bitmap);
+        kc.drop(r);
+        kc.regrow(acc);
+      }
+    }
+    return acc === null || acc.bitmap.isEmpty ? null : acc;
+  }
+  const left = evaluate(node.kids[0], kc);
+  if (left === null) return null;
+  acc = kc.owned(left);
+  for (let i = 1; i < node.kids.length; i++) {
+    const r = evaluate(node.kids[i], kc);
+    if (r === null) continue;
+    acc.bitmap.andNotInPlace(r.bitmap);
+    kc.drop(r);
+    if (acc.bitmap.isEmpty) {
+      kc.drop(acc);
+      return null;
+    }
+  }
+  return acc;
+}
+
+// src/core/combine-held.ts
+var PER_CHUNK_BYTES = 96;
+var HeldChunks = class {
+  /** The chunk keys, ascending. */
+  keys;
+  /** How many ids each chunk holds. */
+  cardinalities;
+  /** What it holds in memory, for a call's resident-bytes ledger. */
+  residentBytes;
+  payloads;
+  constructor(chunks) {
+    const keys = [];
+    const cards = [];
+    const payloads = [];
+    let bytes = 0;
+    let last = -1;
+    for (const chunk of chunks) {
+      const { chunkKey, payload, cardinality } = chunk;
+      if (!Number.isInteger(chunkKey) || chunkKey < 0 || chunkKey > MAX_REMAINDER || chunkKey <= last) {
+        throw new ValidationError(
+          `a held chunk's key must be an integer in [0, 65535] above the last; got ${String(chunkKey)}`
+        );
+      }
+      assertChunkCardinalityInRange(cardinality);
+      last = chunkKey;
+      keys.push(chunkKey);
+      cards.push(cardinality);
+      payloads.push(payload);
+      bytes += payload.byteLength + PER_CHUNK_BYTES;
+    }
+    this.keys = Uint16Array.from(keys);
+    this.cardinalities = Uint32Array.from(cards);
+    this.payloads = payloads;
+    this.residentBytes = bytes;
+  }
+  /** Whether it holds no id. */
+  get empty() {
+    return this.keys.length === 0;
+  }
+  /** Whether {@link release} ran. */
+  get released() {
+    return this.payloads === void 0;
+  }
+  /**
+   * The payload of the chunk at `key`, `null` when it holds none there. A view into what is held: not to be written to.
+   * @throws {ValidationError} once released.
+   */
+  payload(key) {
+    const payloads = this.payloads;
+    if (payloads === void 0) {
+      throw new ValidationError(
+        "this memory operand was released: make another with store.memory()"
+      );
+    }
+    let lo = 0;
+    let hi = this.keys.length - 1;
+    while (lo <= hi) {
+      const mid = lo + hi >>> 1;
+      const at = this.keys[mid];
+      if (at === key) return payloads[mid];
+      if (at < key) lo = mid + 1;
+      else hi = mid - 1;
+    }
+    return null;
+  }
+  /** Zero and drop the bytes. Every later read throws; a second call does nothing. */
+  release() {
+    const payloads = this.payloads;
+    if (payloads === void 0) return;
+    this.payloads = void 0;
+    for (const payload of payloads) payload.fill(0);
+  }
+};
+async function prepareHeld(input, codec, clock) {
+  if (typeof input === "object" && input !== null && !(Symbol.iterator in input) && !(Symbol.asyncIterator in input) && Object.prototype.hasOwnProperty.call(input, "ascending")) {
+    throw new ValidationError(
+      "a memory operand takes ids, { serialized } or { bitmap }, with no `ascending` option: ids that arrive in chunk-key order, one key at a time, are a feed of materializeMany"
+    );
+  }
+  const real = plainUint32(input);
+  if (real === "detached") {
+    throw new ValidationError("a memory operand's ids are a Uint32Array over a detached buffer");
+  }
+  if (real === "out of bounds") {
+    throw new ValidationError(
+      "a memory operand's ids are a resizable-buffer Uint32Array whose view is out of bounds"
+    );
+  }
+  const prepared = real !== void 0 ? new DecodedLoadInput(codec.fromValues(real)) : prepareLoadInput(input, codec, "a memory operand");
+  const encoded = await encodedChunksOfInput(prepared, codec, clock);
+  const tick = yieldEvery(clock, 256);
+  const chunks = [];
+  for (const chunk of encoded) {
+    chunks.push(chunk);
+    const pause = tick();
+    if (pause !== null) await pause;
+  }
+  return new HeldChunks(chunks);
+}
+
+// src/core/rollback.ts
+async function listGenerations(ref, deps) {
+  validateUserRef(ref);
+  const record = await deps.registry.get(ref);
+  const current = record?.currentGen ?? null;
+  const seen = /* @__PURE__ */ new Set();
+  for await (const key of deps.storage.list(ref)) seen.add(key.generation);
+  const described = record === null ? void 0 : await currentDescription(ref, record, deps);
+  return [...seen].sort((a, b) => a - b).map(
+    (generation) => generation === current ? { generation, current: true, ...described } : { generation, current: false }
+  );
+}
+async function currentDescription(ref, record, deps) {
+  if (record.summary === void 0) return void 0;
+  let aead;
+  if ("sealed" in record.summary && record.wrappedDeks !== void 0 && deps.keystore !== void 0) {
+    try {
+      aead = await deps.keystore.openDek(record.wrappedDeks);
+    } catch {
+      return void 0;
+    }
+  }
+  const usable = usableSummary(ref, record, aead);
+  if (usable === void 0) return void 0;
+  const metadata = usable.metadata;
+  return metadata === void 0 || Object.keys(metadata).length === 0 ? { cardinality: usable.cardinality } : { cardinality: usable.cardinality, metadata: Object.freeze({ ...metadata }) };
+}
+async function rollbackSegment(ref, toGeneration, deps, options = {}) {
+  validateUserRef(ref);
+  if (!Number.isInteger(toGeneration) || toGeneration < 0) {
+    throw new ValidationError(
+      `rollback: generation must be a non-negative integer; got ${String(toGeneration)}`
+    );
+  }
+  const record = await deps.registry.get(ref);
+  if (record === null) {
+    throw new NotFoundError(`rollback: no registry row for segment "${ref.segment}"`);
+  }
+  if (record.status === "destroyed") {
+    throw new ValidationError(
+      `rollback: segment "${ref.segment}" is destroyed (crypto-shredded) \u2014 every generation of it is unreadable`
+    );
+  }
+  if (record.currentGen === toGeneration) {
+    return { fromGeneration: record.currentGen, generation: toGeneration };
+  }
+  const present = /* @__PURE__ */ new Set();
+  for await (const key of deps.storage.list(ref)) present.add(key.generation);
+  if (!present.has(toGeneration)) {
+    const available = [...present].sort((a, b) => a - b);
+    throw new NotFoundError(
+      `rollback: generation ${toGeneration} of "${ref.segment}" is not in the bucket` + (available.length === 0 ? " (no generations remain)" : ` \u2014 present: ${available.join(", ")}`)
+    );
+  }
+  if (record.currentGen !== null && toGeneration > record.currentGen && options.allowForward !== true) {
+    throw new ValidationError(
+      `rollback: generation ${toGeneration} of "${ref.segment}" is above the current pointer (${record.currentGen}) \u2014 it may never have been published. Pass { allowForward: true } if you are undoing an earlier rollback.`
+    );
+  }
+  const keyed = record.wrappedDeks !== void 0 && record.wrappedDeks.length > 0;
+  let aead;
+  if (keyed && deps.keystore !== void 0) {
+    try {
+      aead = await deps.keystore.openDek(record.wrappedDeks);
+    } catch {
+    }
+  }
+  const crypto = aead === void 0 ? void 0 : { aead, aadFor: (scope) => aadFor(ref, toGeneration, scope) };
+  const { encrypted, reader } = await openRollbackTarget(
+    deps.storage,
+    { ...ref, generation: toGeneration },
+    crypto
+  );
+  if (encrypted !== keyed) {
+    throw new IntegrityError(
+      `rollback: generation ${toGeneration} of "${ref.segment}" is ${encrypted ? "encrypted" : "cleartext"}, but the segment is ${keyed ? "encrypted" : "cleartext"}, so no read of the segment could use it; it was never one of its generations. Roll back to another generation.`
+    );
+  }
+  const summary = reader === void 0 ? void 0 : summaryOf(
+    ref,
+    toGeneration,
+    { cardinality: reader.count(), metadata: reader.metadata },
+    aead
+  );
+  const churn = leaseChurn(deps);
+  let against = record.token;
+  let token;
+  for (; ; ) {
+    try {
+      ({ token } = await deps.registry.compareAndSwap(ref, against, {
+        currentGen: toGeneration,
+        summary
+      }));
+      break;
+    } catch (err) {
+      if (!isWriteConflictError(err)) throw err;
+      const seen = await deps.registry.get(ref);
+      const settled2 = await churn.settle(record, seen, () => deps.registry.get(ref));
+      const now = settled2?.row ?? null;
+      if (settled2 === void 0 || now === null || !onlyLeasesDiffer(record, now)) throw err;
+      against = now.token;
+    }
+  }
+  let stillThere = false;
+  for await (const key of deps.storage.list(ref)) {
+    if (key.generation === toGeneration) {
+      stillThere = true;
+      break;
+    }
+  }
+  let replaced = false;
+  if (stillThere && reader !== void 0 && toGeneration > (record.currentGen ?? -1)) {
+    try {
+      replaced = !await provesOwnObject(
+        deps.storage,
+        { ...ref, generation: toGeneration },
+        reader.fingerprint
+      );
+    } catch (err) {
+      if (!isIntegrityError(err)) throw err;
+      replaced = true;
+    }
+  }
+  if (!stillThere || replaced) {
+    let undone = false;
+    let undoAgainst = token;
+    for (; ; ) {
+      try {
+        await deps.registry.compareAndSwap(ref, undoAgainst, {
+          currentGen: record.currentGen,
+          summary: describingSummary(record)
+        });
+        undone = true;
+        break;
+      } catch (err) {
+        if (!isWriteConflictError(err)) break;
+        const moved = ["currentGen", "summary", "keptGens"];
+        let now;
+        try {
+          const seen = await deps.registry.get(ref);
+          if (seen === null || seen.currentGen !== toGeneration) break;
+          const settled2 = await churn.settle(record, seen, () => deps.registry.get(ref), moved);
+          now = settled2?.row ?? null;
+        } catch {
+          break;
+        }
+        if (now === null || now.currentGen !== toGeneration || !onlyLeasesDiffer(record, now, moved))
+          break;
+        undoAgainst = now.token;
+      }
     }
     throw new NotFoundError(
       `rollback: generation ${toGeneration} of "${ref.segment}" was ${replaced ? "replaced" : "collected"} while the pointer was moving` + (undone ? " \u2014 the pointer was put back" : `, and the move back failed, so the pointer may still name ${toGeneration} (a write that landed and lost its response reads as a failure here). Check which generation is current, then re-run a rollback to a generation that exists, or restore the object.`)
@@ -6117,7 +8707,7 @@ async function eraseIdFromSegment(ref, id, deps, options = {}) {
     if (row === null) return "absent";
     if (row.status === "destroyed") return "destroyed";
     if (row.currentGen === null) return "no-generation";
-    return row.currentGen === from && row.token === fromToken ? null : "superseded";
+    return row.currentGen === from && (row.token === fromToken || onlyLeasesDiffer(record, row)) ? null : "superseded";
   };
   const holds = async (generation2) => {
     const key2 = { ...base, generation: generation2 };
@@ -6288,7 +8878,13 @@ async function eraseIdFromSegment(ref, id, deps, options = {}) {
   const published = await publishGeneration(deps.registry, key, {
     expectFrom: from,
     expectToken: fromToken,
+    // A lease written while the rewrite streams moves the token and nothing it derived from: it does not refuse it.
+    expectRow: record,
     summary,
+    // The row then records that no generation below the new pointer is kept, as the collection below leaves it.
+    keep: 0,
+    // Every generation below the new pointer is deleted whatever a lease says, so the row drops its leases.
+    clearLeases: true,
     // A write that ends without an answer is settled by reading the row, and a pointer at this number is this
     // rewrite's only over the object it wrote: the footer proves it, so another incarnation's cannot pass for it.
     holdsOwnObject: () => provesOwnObject(deps.storage, key, fingerprint),
@@ -6621,8 +9217,17 @@ async function listGenerations2(storage, ref) {
 }
 async function shredSegment(ref, deps, allowCleartext, op = "destroySegment") {
   const base = { segment: ref.segment, namespace: ref.namespace };
+  const churn = leaseChurn(deps);
+  let lost;
   for (let attempt = 0; attempt < MAX_CAS_ATTEMPTS; attempt++) {
-    const record = await deps.registry.get(ref);
+    let record = await deps.registry.get(ref);
+    if (lost !== void 0) {
+      const settled2 = await churn.settle(lost, record, () => deps.registry.get(ref));
+      if (settled2 !== void 0) {
+        record = settled2.row;
+        attempt -= 1;
+      }
+    }
     if (record === null) {
       return { ...base, destroyed: false, cryptoShredded: false, reason: "absent" };
     }
@@ -6641,11 +9246,14 @@ async function shredSegment(ref, deps, allowCleartext, op = "destroySegment") {
         keyId: void 0,
         // The current generation's cached count and metadata go with it: sealed, they cannot be opened without
         // the wrappings; clear, they would outlive the segment on its tombstone.
-        summary: void 0
+        summary: void 0,
+        // A tombstone holds nothing: a lease names a generation of a segment that now resolves none.
+        leases: void 0
       });
       return { ...base, destroyed: true, cryptoShredded: encrypted };
     } catch (err) {
       if (!isWriteConflictError(err)) throw err;
+      lost = record;
     }
   }
   throw new WriteConflictError(`${op}: contention shredding "${ref.segment}" \u2014 retry`);
@@ -6713,8 +9321,17 @@ async function setSegmentRetention(ref, deps, policy) {
   validateRetentionPolicy(policy);
   const base = { segment: ref.segment, namespace: ref.namespace };
   let previousExpiresAt;
+  const churn = leaseChurn(deps);
+  let lost;
   for (let attempt = 0; attempt < RETENTION_CAS_ATTEMPTS; attempt += 1) {
-    const record = await deps.registry.get(ref);
+    let record = await deps.registry.get(ref);
+    if (lost !== void 0) {
+      const settled2 = await churn.settle(lost, record, () => deps.registry.get(ref));
+      if (settled2 !== void 0) {
+        record = settled2.row;
+        attempt -= 1;
+      }
+    }
     try {
       previousExpiresAt = readExpiresAt(record);
       if (record === null) {
@@ -6741,6 +9358,7 @@ async function setSegmentRetention(ref, deps, policy) {
       };
     } catch (err) {
       if (!isWriteConflictError(err)) throw err;
+      lost = record ?? void 0;
     }
   }
   throw new WriteConflictError(
@@ -6749,8 +9367,17 @@ async function setSegmentRetention(ref, deps, policy) {
 }
 async function clearSegmentRetention(ref, deps) {
   validateUserRef(ref);
+  const churn = leaseChurn(deps);
+  let lost;
   for (let attempt = 0; attempt < RETENTION_CAS_ATTEMPTS; attempt += 1) {
-    const record = await deps.registry.get(ref);
+    let record = await deps.registry.get(ref);
+    if (lost !== void 0) {
+      const settled2 = await churn.settle(lost, record, () => deps.registry.get(ref));
+      if (settled2 !== void 0) {
+        record = settled2.row;
+        attempt -= 1;
+      }
+    }
     if (record === null) return false;
     if (record.status === "destroyed") return false;
     if (record.retention === void 0 || !(EXPIRES_AT in record.retention)) return false;
@@ -6764,6 +9391,7 @@ async function clearSegmentRetention(ref, deps) {
       return true;
     } catch (err) {
       if (!isWriteConflictError(err)) throw err;
+      lost = record;
     }
   }
   throw new WriteConflictError(
@@ -7135,6 +9763,31 @@ function failureReason(err) {
   return `failed: ${err instanceof Error ? err.message : String(err)}`;
 }
 
+// src/core/registry-reap.ts
+var DEFAULT_REAP_LIMIT = 1e3;
+async function reapRegistryTombstones(registry, options = {}) {
+  const dryRun = options.dryRun === true;
+  if (!dryRun && options.confirmNoLegacyWriters !== true) {
+    throw new ValidationError(
+      "reapRegistryTombstones: a real run needs `confirmNoLegacyWriters: true`, your statement that no process on a release before 0.12 writes this registry (one that did would issue a removed row\u2019s tokens again). Pass `dryRun: true` to see what would be removed."
+    );
+  }
+  const limit = options.limit ?? DEFAULT_REAP_LIMIT;
+  if (!Number.isInteger(limit) || limit < 1) {
+    throw new ValidationError(
+      `reapRegistryTombstones: \`limit\` must be a positive integer; got ${String(limit)}`
+    );
+  }
+  if (options.namespace !== void 0) validateUserNamespace(options.namespace);
+  if (registry.reapLegacyTombstones === void 0) {
+    throw new UnsupportedError(
+      "reapRegistryTombstones: this registry keeps no deleted rows of a release before 0.12 to remove (only the object-store registries, S3, GCS and Azure Blob, do)"
+    );
+  }
+  const request = options.namespace === void 0 ? { dryRun, limit } : { namespace: options.namespace, dryRun, limit };
+  return registry.reapLegacyTombstones(request);
+}
+
 // src/core/consistency.ts
 var DEFAULT_CHECK_CONCURRENCY = 8;
 async function generationsPresent(storage, ref) {
@@ -7338,7 +9991,12 @@ export {
   InProcessKeystore,
   IntegrityError,
   KeyUnavailableError,
+  LEASE_SKEW_MS,
+  LeaseExpiredError,
+  LeaseLimitError,
   LocalFsStorage,
+  MAX_LEASES_PER_SEGMENT,
+  MAX_LEASE_MS,
   MIN_EXPIRES_AT_MS,
   MemoryStorage,
   NOOP_METRICS,
@@ -7349,6 +10007,7 @@ export {
   RecordingAuditSink,
   RetryingStorageChunkSource,
   SegmentEngine,
+  StaleOperandError,
   TransientError,
   UnsupportedError,
   ValidationError,
@@ -7357,6 +10016,8 @@ export {
   checkBudget,
   clearSegmentRetention,
   collectWithinBudget,
+  compileCombineMany,
+  decodeSerialized,
   destroySegment,
   dropSegment,
   eraseIdFromSegment,
@@ -7367,7 +10028,10 @@ export {
   groundedReport,
   isCloudRoaringError,
   isIntegrityError,
+  isLeaseExpiredError,
+  isLeaseLimitError,
   isNotFoundError,
+  isStaleOperandError,
   isStorageBackend,
   isTransientError,
   isValidationError,
@@ -7377,11 +10041,16 @@ export {
   loadSegment,
   loadSegmentChunks,
   mapWithConcurrency,
+  prepareHeld,
   readRetentionPolicy,
+  reapRegistryTombstones,
+  rebindCombineMany,
+  releaseLease,
   resolveBudget,
   resolvePerOpBudget,
   retireExpired,
   rollbackSegment,
+  runCombineMany,
   runConsistencyCheck,
   runExport,
   safeMetrics,
@@ -7389,6 +10058,7 @@ export {
   segmentKey,
   setSegmentRetention,
   splitId,
+  takeLease,
   withRetry
 };
 //# sourceMappingURL=index.js.map