@cloudbitmaps/core 0.17.0 → 0.18.1

package/dist/index.js

@@ -15,6 +15,7 @@ import {
   MAX_NAME_LENGTH,
   NotFoundError,
   RESERVED_NAMESPACE_PREFIX,
+  StaleOperandError,
   TransientError,
   UnsupportedError,
   ValidationError,
@@ -40,6 +41,7 @@ import {
   isLive,
   isNotFoundError,
   isReservedNamespace,
+  isStaleOperandError,
   isStorageBackend,
   isTransientError,
   isValidationError,
@@ -68,7 +70,7 @@ import {
   validateUserNamespace,
   validateUserRef,
   webCryptoEntropy
-} from "./chunk-CV7GJO3B.js";
+} from "./chunk-K4EXZDMU.js";
 
 // src/core/bit-route.ts
 var U32_MAX = 4294967295;
@@ -119,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;
@@ -548,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;
@@ -731,11 +769,9 @@ var SegmentEngine = class {
       { loKey, loRem, hiKey, hiRem }
     );
     for (const k of keys) {
-      this.assertChunkKeyInRange(k);
+      assertChunkKeyInRange(k);
       const c = counts.get(k);
-      if (!Number.isInteger(c) || c < 1 || c > CHUNK_COUNT) {
-        throw new IntegrityError(`chunk cardinality from a tier is out of range: ${c}`);
-      }
+      assertChunkCardinalityInRange(c);
     }
     const gen = await this.cacheVersion(seg);
     const cutsFirst = loRem > 0 && keys[0] === loKey;
@@ -1157,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) {
@@ -1179,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.
@@ -1338,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);
@@ -1393,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;
   }
@@ -4042,16 +4026,16 @@ function overCap(what, length) {
     `${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;
@@ -4074,7 +4058,7 @@ function prepareLoadInput(input, 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 decodeSerialized(bytes, codec, what = "the buffer") {
@@ -5300,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;
@@ -5643,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");
@@ -6271,6 +6260,2240 @@ async function runLoad(ref, prepare, deps, options) {
   };
 }
 
+// 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(
+      `${path}: more than ${MAX_EXPR_NODES} nodes in one output's expression`
+    );
+  }
+  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 (typeof expr !== "object" || expr === null || Array.isArray(expr)) {
+    throw new ValidationError(
+      `${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}`
+    );
+  }
+  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 (depth >= MAX_EXPR_DEPTH) {
+    throw new ValidationError(
+      `${path}: expression nests more than ${MAX_EXPR_DEPTH} operators deep (an object that contains itself is refused here too)`
+    );
+  }
+  const list = expr[operator];
+  if (!Array.isArray(list) || list.length === 0) {
+    throw new ValidationError(`${path}.${operator}: must be a non-empty array of expressions`);
+  }
+  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 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++]);
+    }
+  }
+  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]);
+    }
+  }
+  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);
@@ -7784,6 +10007,7 @@ export {
   RecordingAuditSink,
   RetryingStorageChunkSource,
   SegmentEngine,
+  StaleOperandError,
   TransientError,
   UnsupportedError,
   ValidationError,
@@ -7792,6 +10016,7 @@ export {
   checkBudget,
   clearSegmentRetention,
   collectWithinBudget,
+  compileCombineMany,
   decodeSerialized,
   destroySegment,
   dropSegment,
@@ -7806,6 +10031,7 @@ export {
   isLeaseExpiredError,
   isLeaseLimitError,
   isNotFoundError,
+  isStaleOperandError,
   isStorageBackend,
   isTransientError,
   isValidationError,
@@ -7815,13 +10041,16 @@ export {
   loadSegment,
   loadSegmentChunks,
   mapWithConcurrency,
+  prepareHeld,
   readRetentionPolicy,
   reapRegistryTombstones,
+  rebindCombineMany,
   releaseLease,
   resolveBudget,
   resolvePerOpBudget,
   retireExpired,
   rollbackSegment,
+  runCombineMany,
   runConsistencyCheck,
   runExport,
   safeMetrics,