@cloudbitmaps/core 0.13.0 → 0.15.0

package/dist/index.js

@@ -44,6 +44,7 @@ import {
   recordFromNew,
   sameIncarnation,
   serializeRegistryEnvelope,
+  validateChunkKeyOrder,
   validateChunkRef,
   validateNewRegistryRecord,
   validateRegistryPatch,
@@ -51,7 +52,7 @@ import {
   validateUserNamespace,
   validateUserRef,
   webCryptoEntropy
-} from "./chunk-5W3XS2IU.js";
+} from "./chunk-B7IGS3W6.js";
 
 // src/core/bit-route.ts
 var U32_MAX = 4294967295;
@@ -102,24 +103,64 @@ async function collectWithinBudget(source, budget, op) {
   return out;
 }
 
+// src/core/chunk-stream.ts
+var ChunkStream = class {
+  iterator;
+  failure;
+  constructor(stream) {
+    this.iterator = stream[Symbol.asyncIterator]();
+  }
+  /** The chunk for `key`, which must be the next key the stream was opened over. */
+  take(key) {
+    if (this.failure !== void 0) return Promise.reject(this.failure.error);
+    return this.iterator.next().then(
+      (step) => {
+        if (step.done === true) {
+          throw this.failure?.error ?? new IntegrityError(`chunk stream ended before chunk ${key}`);
+        }
+        if (step.value.key !== key) {
+          throw new IntegrityError(
+            `chunk stream answered chunk ${step.value.key} where ${key} was due`
+          );
+        }
+        return step.value;
+      },
+      (error) => {
+        this.failure ??= { error };
+        throw error;
+      }
+    );
+  }
+  /** Stop the stream: no further range is started, and ranges already in flight finish and are dropped. */
+  close() {
+    this.iterator.return?.(void 0).catch(() => void 0);
+  }
+};
+
 // src/core/chunk-window.ts
 var ChunkWindow = class {
-  constructor(keys, fetch, max, ramp) {
+  constructor(keys, fetch, max, ramp, rampStart = 1) {
     this.keys = keys;
     this.fetch = fetch;
     this.max = max;
     this.ramp = ramp;
+    this.rampStart = rampStart;
   }
   keys;
   fetch;
   max;
   ramp;
+  rampStart;
   open = [];
   launched = 0;
   taken = 0;
+  /** Resolves once every read launched and not yet taken has settled; it never rejects, as the reads never do. */
+  async settle() {
+    await Promise.all(this.open);
+  }
   /** The next read's result in key order, or the error that read raised. */
   async take() {
-    const width = this.ramp ? Math.min(this.max, 2 ** Math.min(this.taken, 30)) : this.max;
+    const width = this.ramp ? Math.min(this.max, Math.max(this.rampStart, 2 ** Math.min(this.taken, 30))) : this.max;
     while (this.launched < this.keys.length && this.launched - this.taken < width) {
       this.open.push(
         this.fetch(this.keys[this.launched++]).then(
@@ -320,6 +361,7 @@ var CountingMetricsSink = class _CountingMetricsSink {
 // src/core/engine.ts
 var DEFAULT_INTERSECT_CONCURRENCY = 32;
 var COMBINE_WINDOW_START = 8;
+var COMBINE_RANGE_START = 4;
 var ZERO_CLOCK = { now: () => 0 };
 function windowOf(range) {
   const after = range?.after;
@@ -372,6 +414,65 @@ function keysWithin(keys, w) {
   };
   return keys.slice(firstAtLeast(w.loKey), firstAtLeast(w.hiKey + 1));
 }
+var CombineWindow = class {
+  constructor(keys, limit, read) {
+    this.keys = keys;
+    this.limit = limit;
+    this.read = read;
+    this.fill();
+  }
+  keys;
+  limit;
+  read;
+  inFlight = [];
+  next_ = 0;
+  taken = 0;
+  fill() {
+    const width = Math.min(
+      this.limit,
+      Math.max(COMBINE_WINDOW_START, 2 ** Math.min(this.taken, 30))
+    );
+    while (this.next_ < this.keys.length && this.inFlight.length < width) {
+      const key = this.keys[this.next_++];
+      this.inFlight.push(
+        this.read(key).then(
+          (result) => ({ key, result }),
+          (error) => ({ key, result: null, error })
+        )
+      );
+    }
+  }
+  /** The next key's chunk in ascending key order, `undefined` when the keys are used up; throws that key's error. */
+  async next() {
+    if (this.inFlight.length === 0) return void 0;
+    const slot = await this.inFlight.shift();
+    this.taken += 1;
+    this.fill();
+    if (slot.error !== void 0) throw slot.error;
+    return slot;
+  }
+};
+function chunkIds(chunk, chunkKey, w) {
+  let rem = chunk.toUint32Array ? chunk.toUint32Array() : Uint32Array.from(chunk);
+  if (w !== null && isEdge(chunkKey, w)) {
+    const from = chunkKey === w.loKey ? w.loRem : 0;
+    const to = chunkKey === w.hiKey ? w.hiRem : MAX_REMAINDER;
+    rem = rem.slice(firstAbove(rem, from - 1), firstAbove(rem, to));
+  }
+  const base = chunkKey * CHUNK_COUNT;
+  for (let i = 0; i < rem.length; i++) rem[i] = base + (rem[i] & MAX_REMAINDER);
+  return rem;
+}
+function firstAbove(a, value) {
+  let lo = 0;
+  let hi = a.length;
+  while (lo < hi) {
+    const mid = lo + hi >>> 1;
+    if (a[mid] <= value) lo = mid + 1;
+    else hi = mid;
+  }
+  return lo;
+}
 var SegmentEngine = class {
   storage;
   cache;
@@ -388,6 +489,11 @@ var SegmentEngine = class {
    * promise per distinct key in flight.
    */
   openReads = /* @__PURE__ */ new Map();
+  /**
+   * The chunk streams open right now. An {@link invalidate} of a segment marks its streams, which then cache no chunk
+   * they deliver, as a read whose entry an invalidation dropped does not (streams hold no `openReads` entry).
+   */
+  openStreams = /* @__PURE__ */ new Set();
   constructor(deps) {
     this.storage = deps.storage;
     this.cache = deps.cache;
@@ -468,9 +574,27 @@ var SegmentEngine = class {
     );
   }
   /**
-   * Every id, ascending, reading ahead through a window of up to 32 chunk fetches that opens 1, 2, 4 … 32 wide, so a
-   * read that stops early has fetched only a handful of chunks past the one it stopped in; with `range`, only the ids in `(after, through]`, fetching only the
-   * chunks the range overlaps (see {@link IdRange}).
+   * The chunks of `seg` at `chunkKeys`, taken in ascending key order by a read that may stop at any point: one stream of
+   * coalesced ranges when the source has `getChunks`, opening 1, 2, 4 … ranges wide up to {@link DEFAULT_INTERSECT_CONCURRENCY},
+   * else the chunk-by-chunk window of that many reads. `close` stops what is left of it.
+   */
+  chunkSequence(seg, chunkKeys, gen) {
+    const streamed = this.openStreamed(seg, chunkKeys, gen, DEFAULT_INTERSECT_CONCURRENCY, 1);
+    if (streamed !== void 0) {
+      return {
+        take: (chunkKey) => this.streamedChunk(streamed, chunkKey),
+        close: () => this.closeStreamed(streamed)
+      };
+    }
+    const window = this.chunkWindow(seg, chunkKeys, gen, true);
+    return { take: () => window.take(), close: () => void 0 };
+  }
+  /**
+   * Every id, ascending, reading the chunks as one stream of coalesced ranges (chunks that sit near each other are one
+   * request) that opens 1, 2, 4 … 32 ranges wide, so a read that stops early has asked for only a few ranges past the
+   * one it stopped in (each at most 1 MiB); with `range`, only the ids in `(after, through]`, fetching only the
+   * chunks the range overlaps (see {@link IdRange}). A source that reads chunk by chunk is read through a window of up to
+   * 32 chunk fetches that opens 1, 2, 4 … 32 wide.
    *
    * Two generators, not one with a branch: a second `yield` site in the full read's generator grows its frame, and
    * every id of a read that asked for no range paid for it (measured at about 5% per id). The full read keeps the
@@ -483,11 +607,15 @@ var SegmentEngine = class {
     const chunkKeys = await this.chunkKeys(seg);
     checkBudget(this.budget, chunkKeys.length, "iterate");
     const gen = await this.cacheVersion(seg);
-    const window = this.chunkWindow(seg, chunkKeys, gen, true);
-    for (const chunkKey of chunkKeys) {
-      const chunk = await window.take();
-      if (chunk === null) continue;
-      for (const remainder of chunk) yield joinId(chunkKey, remainder);
+    const chunks = this.chunkSequence(seg, chunkKeys, gen);
+    try {
+      for (const chunkKey of chunkKeys) {
+        const chunk = await chunks.take(chunkKey);
+        if (chunk === null) continue;
+        for (const remainder of chunk) yield joinId(chunkKey, remainder);
+      }
+    } finally {
+      chunks.close();
     }
   }
   async *iterateRange(seg, range) {
@@ -496,15 +624,43 @@ var SegmentEngine = class {
     const chunkKeys = keysWithin(await this.chunkKeys(seg), w);
     checkBudget(this.budget, chunkKeys.length, "iterate");
     const gen = await this.cacheVersion(seg);
-    const window = this.chunkWindow(seg, chunkKeys, gen, true);
-    for (const chunkKey of chunkKeys) {
-      const chunk = await window.take();
-      if (chunk === null) continue;
-      if (isEdge(chunkKey, w)) {
-        for (const id of edgeIds(chunk, chunkKey, w)) yield id;
-      } else {
-        for (const remainder of chunk) yield joinId(chunkKey, remainder);
+    const chunks = this.chunkSequence(seg, chunkKeys, gen);
+    try {
+      for (const chunkKey of chunkKeys) {
+        const chunk = await chunks.take(chunkKey);
+        if (chunk === null) continue;
+        if (isEdge(chunkKey, w)) {
+          for (const id of edgeIds(chunk, chunkKey, w)) yield id;
+        } else {
+          for (const remainder of chunk) yield joinId(chunkKey, remainder);
+        }
       }
+    } finally {
+      chunks.close();
+    }
+  }
+  /**
+   * {@link iterate}, one `Uint32Array` per chunk instead of one id at a time: the same chunks, in the same order, with
+   * the same ids (a range cut at its edges the same way), and no array for a chunk that holds none of them. The
+   * reads, the budget charge and the window are the per-id read's. Each array is at most 65,536 ids (256 KiB) and is
+   * the caller's to keep.
+   */
+  async *iterateBatches(seg, range) {
+    const w = windowOf(range);
+    if (w === "empty") return;
+    const chunkKeys = w === null ? await this.chunkKeys(seg) : keysWithin(await this.chunkKeys(seg), w);
+    checkBudget(this.budget, chunkKeys.length, "iterate");
+    const gen = await this.cacheVersion(seg);
+    const chunks = this.chunkSequence(seg, chunkKeys, gen);
+    try {
+      for (const chunkKey of chunkKeys) {
+        const chunk = await chunks.take(chunkKey);
+        if (chunk === null) continue;
+        const ids = chunkIds(chunk, chunkKey, w);
+        if (ids.length > 0) yield ids;
+      }
+    } finally {
+      chunks.close();
     }
   }
   /**
@@ -521,11 +677,11 @@ var SegmentEngine = class {
    *
    * Chunk-skipping intersection. Aligns each segment's chunk-key set (read from the `.crbm` index, no payload),
    * keeps only keys present in **all** operands (a key missing from any operand can't contribute → its Storage
-   * chunks are never fetched — the core saving), then for each surviving key fetches the operands' chunks in
-   * parallel and hands them to the codec for the AND, streaming results through a bounded in-flight window.
+   * chunks are never fetched — the core saving), then reads each operand's surviving chunks as one stream of coalesced
+   * ranges and hands them, key by key, to the codec for the AND, streaming results through a bounded window.
    *
-   * **Memory:** the Storage payload footprint is bounded by the window (`concurrency × operands × chunk`), not by
-   * segment size — that's the Lambda-friendly property.
+   * **Memory:** the Storage payload footprint is bounded by the window (`concurrency × operands × chunk`, a range being
+   * at most a chunk's cap of 1 MiB), not by segment size — that's the Lambda-friendly property.
    *
    * Generation-consistent within the call (normal case): each operand's current generation is resolved **once**
    * up front (before the fan-out) and threaded into every chunk read, so a concurrent load can't corrupt or tear
@@ -536,7 +692,9 @@ var SegmentEngine = class {
    * waiting for the TTL, so a shorter call can meet them too: **the reader cache evicting an operand mid-call**
    * (`maxOpenSegments`), whose re-read re-resolves fresh; a sweep deleting the generation it was reading, which
    * heals the read forward; and an invalidation, which this store's own `load`, `rollback` and `eraseSubject` make
-   * and `invalidate()` makes on request. Still whole/immutable per read, never torn.
+   * and `invalidate()` makes on request. Still whole/immutable per read, never torn. An operand's stream resolves its
+   * segment again before it serves each chunk, so each of those moves a running read as it would a read of one chunk, and
+   * the ranges it had requested of the earlier generation are dropped, not served.
    */
   intersect(segs, options) {
     return this.combine(segs, options?.exclude ?? [], "all", "intersect", options);
@@ -561,7 +719,24 @@ var SegmentEngine = class {
   andNot(seg, excludes, options) {
     return this.combine([seg], excludes, "all", "andNot", options);
   }
-  async *combine(segs, excludeSegs, mode, op, options) {
+  /** {@link intersect}, one `Uint32Array` per chunk — see {@link iterateBatches}. */
+  intersectBatches(segs, options) {
+    return this.combineBatches(segs, options?.exclude ?? [], "all", "intersect", options);
+  }
+  /** {@link union}, one `Uint32Array` per chunk — see {@link iterateBatches}. */
+  unionBatches(segs, options) {
+    return this.combineBatches(segs, options?.exclude ?? [], "any", "union", options);
+  }
+  /** {@link andNot}, one `Uint32Array` per chunk — see {@link iterateBatches}. */
+  andNotBatches(seg, excludes, options) {
+    return this.combineBatches([seg], excludes, "all", "andNot", options);
+  }
+  /**
+   * Everything a combine decides before it reads a chunk: validation, each operand's keys and generation, the
+   * absent-operand refusal, key alignment, the budget and the metric. `null` when the range is empty. The per-id
+   * read and the batch read share it, so the two cannot disagree about what is read or charged.
+   */
+  async combinePlan(segs, excludeSegs, mode, op, options) {
     if (segs.length === 0) {
       throw new ValidationError(`${op} requires at least one segment`);
     }
@@ -576,7 +751,7 @@ var SegmentEngine = class {
     }
     const budget = resolvePerOpBudget(options?.budget, this.budget);
     const w = windowOf(options);
-    if (w === "empty") return;
+    if (w === "empty") return null;
     const extract = async (seg) => {
       const all = await this.chunkKeys(seg);
       const gen = await this.cacheVersion(seg);
@@ -621,31 +796,61 @@ var SegmentEngine = class {
         skippedChunks: distinctKeys.size - common.length
       });
     }
-    const startAt = (key) => this.combineChunk(operands, excludes, mode, key).then(
-      (result) => ({ key, result }),
-      (error) => ({ key, result: null, error })
-    );
-    const inFlight = [];
-    let next = 0;
-    let taken = 0;
-    const fill = () => {
-      const width = Math.min(limit, Math.max(COMBINE_WINDOW_START, 2 ** Math.min(taken, 30)));
-      while (next < common.length && inFlight.length < width)
-        inFlight.push(startAt(common[next++]));
+    const streams = [];
+    const streamExcludes = mode === "any" || operands.length === 1;
+    const open4 = (o, wanted) => {
+      o.streamed = this.openStreamed(
+        o.seg,
+        common.filter(wanted),
+        o.gen,
+        limit,
+        COMBINE_RANGE_START
+      );
+      if (o.streamed?.stream) streams.push(o.streamed);
     };
-    fill();
-    while (inFlight.length > 0) {
-      const slot = await inFlight.shift();
-      taken += 1;
-      fill();
-      if (slot.error !== void 0) throw slot.error;
-      if (slot.result && !slot.result.isEmpty) {
-        if (w !== null && isEdge(slot.key, w)) {
-          for (const id of edgeIds(slot.result, slot.key, w)) yield id;
-        } else {
-          for (const remainder of slot.result) yield joinId(slot.key, remainder);
+    for (const o of operands) open4(o, mode === "all" ? () => true : (k) => o.keys.has(k));
+    if (streamExcludes) for (const e of excludes) open4(e, (k) => e.keys.has(k));
+    return {
+      w,
+      window: new CombineWindow(
+        common,
+        limit,
+        (key) => this.combineChunk(operands, excludes, mode, key)
+      ),
+      streams
+    };
+  }
+  async *combine(segs, excludeSegs, mode, op, options) {
+    const plan = await this.combinePlan(segs, excludeSegs, mode, op, options);
+    if (plan === null) return;
+    const { w, window } = plan;
+    try {
+      for (let slot = await window.next(); slot !== void 0; slot = await window.next()) {
+        if (slot.result && !slot.result.isEmpty) {
+          if (w !== null && isEdge(slot.key, w)) {
+            for (const id of edgeIds(slot.result, slot.key, w)) yield id;
+          } else {
+            for (const remainder of slot.result) yield joinId(slot.key, remainder);
+          }
         }
       }
+    } finally {
+      for (const stream of plan.streams) this.closeStreamed(stream);
+    }
+  }
+  async *combineBatches(segs, excludeSegs, mode, op, options) {
+    const plan = await this.combinePlan(segs, excludeSegs, mode, op, options);
+    if (plan === null) return;
+    const { w, window } = plan;
+    try {
+      for (let slot = await window.next(); slot !== void 0; slot = await window.next()) {
+        if (slot.result) {
+          const ids = chunkIds(slot.result, slot.key, w);
+          if (ids.length > 0) yield ids;
+        }
+      }
+    } finally {
+      for (const stream of plan.streams) this.closeStreamed(stream);
     }
   }
   /**
@@ -663,9 +868,7 @@ var SegmentEngine = class {
     const relevant = excludes.filter((e) => e.keys.has(chunkKey));
     const together = relevant.length > 0 && (mode === "any" || present.length === 1);
     const reads = together ? [...present, ...relevant] : present;
-    const fetched = await Promise.all(
-      reads.map((op) => this.storageChunk({ ...op.seg, chunkKey }, op.gen))
-    );
+    const fetched = await Promise.all(reads.map((op) => this.operandChunk(op, chunkKey)));
     const chunks = together ? fetched.slice(0, present.length) : fetched;
     if (mode === "all" && chunks.some((c) => c === null)) return null;
     const first = chunks[0];
@@ -691,6 +894,92 @@ var SegmentEngine = class {
     }
     return acc;
   }
+  /**
+   * One operand's chunk at `key`: from its stream when it has one, else a read of that chunk on its own. Not `async`,
+   * so a stream's take is made before anything is awaited: concurrent takes of one stream must be made in key order.
+   */
+  operandChunk(op, chunkKey) {
+    return op.streamed === void 0 ? this.storageChunk({ ...op.seg, chunkKey }, op.gen) : this.streamedChunk(op.streamed, chunkKey);
+  }
+  /**
+   * Open `keys` of `seg` as a stream of coalesced ranges, or `undefined` when the read is per key: a source with no
+   * `getChunks`, a segment with no generation, or nothing to read. The chunks already decoded in the cache are taken out
+   * of the key list first and served from there, so a repeat read asks the source for nothing it holds. Nothing is
+   * requested until the first chunk is asked for.
+   */
+  openStreamed(seg, keys, gen, concurrency, rampStart) {
+    const getChunks = this.storage.getChunks;
+    if (getChunks === void 0 || gen === null || keys.length === 0) return void 0;
+    let wanted = keys;
+    let inStream;
+    if (this.cache) {
+      const misses = [];
+      for (const chunkKey of keys) {
+        const hit = this.cache.get(this.chunkCacheKey({ ...seg, chunkKey }, gen));
+        if (!hit) misses.push(chunkKey);
+        if (this.metricsOn) this.metrics.onEvent({ kind: "cache", hit: hit !== void 0 });
+      }
+      wanted = misses;
+      if (misses.length < keys.length) inStream = new Set(misses);
+    }
+    const onRequest = this.metricsOn ? (request) => {
+      this.metrics.onEvent({
+        kind: "storage.get",
+        namespace: seg.namespace,
+        segment: seg.segment,
+        bytes: request.bytes,
+        ms: request.ms
+      });
+    } : void 0;
+    const stream = wanted.length === 0 ? void 0 : new ChunkStream(
+      getChunks.call(this.storage, seg, wanted, {
+        concurrency,
+        ramp: rampStart,
+        ...onRequest === void 0 ? {} : { onRequest }
+      })
+    );
+    const streamed = { seg, gen, inStream, stream, invalidated: false };
+    if (stream) this.openStreams.add(streamed);
+    return streamed;
+  }
+  closeStreamed(streamed) {
+    streamed.stream?.close();
+    this.openStreams.delete(streamed);
+  }
+  /**
+   * The decoded chunk at `chunkKey` of a streamed read: the next chunk of its stream, or, for a chunk the cache held
+   * when the read opened, the cached instance while it is still there, and a read of that chunk alone once it is not.
+   */
+  streamedChunk(streamed, chunkKey) {
+    if (streamed.inStream !== void 0 && !streamed.inStream.has(chunkKey)) {
+      const ref = { ...streamed.seg, chunkKey };
+      const hit = this.cache?.get(this.chunkCacheKey(ref, streamed.gen));
+      return hit ? Promise.resolve(hit) : this.storageChunk(ref, streamed.gen);
+    }
+    return streamed.stream.take(chunkKey).then((read) => {
+      if (read.bytes === null) return null;
+      const bitmap = this.decodeChunk(read.bytes, chunkKey);
+      if (this.cache && !streamed.invalidated) {
+        const version = this.streamedVersion(streamed.gen, read.version);
+        if (version !== null) {
+          this.cache.set(this.chunkCacheKey({ ...streamed.seg, chunkKey }, version), bitmap);
+        }
+      }
+      return bitmap;
+    });
+  }
+  /**
+   * The version a streamed chunk is cached under, or `null` for one not to cache: the version its read reports when the
+   * source names versions as its lookups do (`currentVersion`), and otherwise the one the read planned under, since a
+   * lookup by generation number would never find a chunk cached under a stream's version.
+   */
+  streamedVersion(planned, read) {
+    return planned === void 0 || this.storage.currentVersion === void 0 ? planned : read;
+  }
+  /** The cache key of a chunk: by the version it was read under, or by segment and key alone for a source with none. */
+  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). */
   async chunkKeys(seg) {
     const keys = [...await this.storage.listChunkKeys(seg)];
@@ -785,6 +1074,9 @@ var SegmentEngine = class {
    */
   invalidate(ref) {
     const prefix = segmentPrefix(ref);
+    for (const streamed of this.openStreams) {
+      if (segmentPrefix(streamed.seg) === prefix) streamed.invalidated = true;
+    }
     this.cache?.deleteWhere((key) => key.startsWith(prefix));
     for (const key of this.openReads.keys()) if (key.startsWith(prefix)) this.openReads.delete(key);
     this.storage.invalidate?.(ref);
@@ -826,7 +1118,7 @@ var SegmentEngine = class {
    */
   async storageChunk(ref, gen) {
     if (gen === null) return null;
-    const cacheKey = gen === void 0 ? chunkRefKey(ref) : chunkGenKey(ref, gen);
+    const cacheKey = this.chunkCacheKey(ref, gen);
     if (this.cache) {
       const cached = this.cache.get(cacheKey);
       if (cached) {
@@ -838,31 +1130,71 @@ var SegmentEngine = class {
     const open4 = this.openReads.get(cacheKey);
     if (open4) return open4.read;
     const token = {};
-    const entry = { token, read: this.fetchChunk(ref, cacheKey, token) };
+    const entry = { token, read: this.fetchChunk(ref, gen, cacheKey, token) };
     this.openReads.set(cacheKey, entry);
-    const settled = () => {
+    const settled2 = () => {
       if (this.openReads.get(cacheKey) === entry) this.openReads.delete(cacheKey);
     };
-    entry.read.then(settled, settled);
+    entry.read.then(settled2, settled2);
     return entry.read;
   }
-  /** One request for one chunk, decoded, range-checked and cached. */
-  async fetchChunk(ref, cacheKey, token) {
-    const startedAt = this.metricsOn ? this.clock.now() : 0;
-    const bytes = await this.storage.getChunk(ref);
-    if (this.metricsOn) {
-      this.metrics.onEvent({
-        kind: "storage.get",
-        namespace: ref.namespace,
-        segment: ref.segment,
-        bytes: bytes ? bytes.length : 0,
-        ms: Math.max(0, this.clock.now() - startedAt)
-      });
+  /**
+   * 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);
+   * the chunk is cached under the version it came from, as a stream's chunk is. A source without it is read by
+   * `getChunk`, one event a call.
+   */
+  async fetchChunk(ref, gen, cacheKey, token) {
+    const getChunks = this.storage.getChunks;
+    let bytes;
+    let key = cacheKey;
+    if (getChunks === void 0) {
+      const startedAt = this.metricsOn ? this.clock.now() : 0;
+      bytes = await this.storage.getChunk(ref);
+      if (this.metricsOn) {
+        this.metrics.onEvent({
+          kind: "storage.get",
+          namespace: ref.namespace,
+          segment: ref.segment,
+          bytes: bytes ? bytes.length : 0,
+          ms: Math.max(0, this.clock.now() - startedAt)
+        });
+      }
+    } else {
+      const stream = new ChunkStream(
+        getChunks.call(this.storage, ref, [ref.chunkKey], {
+          ...this.metricsOn ? {
+            onRequest: (request) => this.metrics.onEvent({
+              kind: "storage.get",
+              namespace: ref.namespace,
+              segment: ref.segment,
+              bytes: request.bytes,
+              ms: request.ms
+            })
+          } : {}
+        })
+      );
+      try {
+        const read = await stream.take(ref.chunkKey);
+        bytes = read.bytes;
+        const version = this.streamedVersion(gen, read.version);
+        key = version === null ? "" : this.chunkCacheKey(ref, version);
+      } finally {
+        stream.close();
+      }
     }
     if (!bytes) return null;
-    const bitmap = this.codec.safeDeserialize(bytes, this.maxBitmapBytes);
-    this.assertChunkPayloadInRange(bitmap, ref.chunkKey);
-    if (this.openReads.get(cacheKey)?.token === token) this.cache?.set(cacheKey, bitmap);
+    const bitmap = this.decodeChunk(bytes, ref.chunkKey);
+    if (key !== "" && this.openReads.get(cacheKey)?.token === token) this.cache?.set(key, bitmap);
     return bitmap;
   }
 };
@@ -1443,7 +1775,7 @@ function buildReport(input) {
     "Request cost is from the supplied workload rates (live-metrics-derived request cost is a later phase).",
     loadsPerMonth > 0 ? `Loads modeled: ${loadsPerMonth}/mo, each ${requestsPerLoad} PUT-class request(s) for the object plus ${shown(STORE_LOAD_PUT_CLASS)} PUT-class and ${shown(loadGets)} GETs that store.load() adds (the pointer, a check that the next generation number is free, a check that the current generation is there, and a listing every ${LIST_COLLECTION_CADENCE}th load).` : "Loads are NOT modeled \u2014 set workload.loadsPerMonth (+ requestsPerLoad for multipart) to include them.",
     ...intersects > 0 ? [
-      `Intersections priced cold: ${intersectGets} GETs each, ${getsPerColdOperand} for each of ${operandsPerIntersect} operand(s) plus ${chunksPerIntersect} chunk read(s); cacheHitRate does not apply.`
+      `Intersections priced cold: ${intersectGets} GETs each, ${getsPerColdOperand} for each of ${operandsPerIntersect} operand(s) plus ${chunksPerIntersect} chunk range request(s); cacheHitRate does not apply.`
     ] : [],
     hotSegments > 0 ? genTtlMs > 0 ? `Pointer refresh modeled: ${hotSegments} hot segment(s) in each of ${readerProcesses} reader process(es), each re-reading its pointer at most every ${genTtlMs} ms, and at most once a point read.` : "Pointer refresh: none \u2014 genTtlMs 0 turns the timed refresh off. A reader still re-reads a pointer on an eviction, a swept generation or an invalidation, which this does not price." : readsPerSec > 0 ? "The pointer refresh is NOT modeled \u2014 set workload.hotSegments to the segments each long-lived reader keeps reading, and workload.readerProcesses to how many readers there are." : null,
     hotSegments > DEFAULT_MAX_OPEN_SEGMENTS ? `More hot segments in a reader than a store keeps open by default (${DEFAULT_MAX_OPEN_SEGMENTS}): a read of a segment the reader evicted opens it again, a pointer and a tail read, which this does not price. Raise cache.readerMax, and cache.readerMaxBytes, to keep them open.` : null,
@@ -2419,6 +2751,40 @@ function crc32c(bytes, seed = 0) {
   return (crc ^ 4294967295) >>> 0;
 }
 
+// src/core/crbm/plan-reads.ts
+var MAX_COALESCE_GAP_BYTES = 256 * 1024;
+var MAX_COALESCED_READ_BYTES = DEFAULT_MAX_BITMAP_BYTES;
+var MAX_RANGES_IN_FLIGHT = 32;
+function planChunkReads(extents, region) {
+  const reads = [];
+  let chunks = [];
+  let start = 0;
+  let end = 0;
+  const flush = () => {
+    if (chunks.length > 0) reads.push({ offset: start, length: end - start, chunks });
+    chunks = [];
+  };
+  let previousEnd = region.start;
+  for (const extent of extents) {
+    const extentEnd = extent.offset + extent.length;
+    if (!(Number.isSafeInteger(extent.offset) && Number.isSafeInteger(extent.length) && extent.length >= 1 && extent.offset >= previousEnd && extentEnd <= region.end)) {
+      throw new IntegrityError(`chunk ${extent.key} is not inside the chunk region, in order`);
+    }
+    previousEnd = extentEnd;
+    if (chunks.length > 0 && extent.offset - end <= MAX_COALESCE_GAP_BYTES && extentEnd - start <= MAX_COALESCED_READ_BYTES) {
+      chunks.push(extent);
+      end = extentEnd;
+      continue;
+    }
+    flush();
+    chunks.push(extent);
+    start = extent.offset;
+    end = extentEnd;
+  }
+  flush();
+  return reads;
+}
+
 // src/core/crbm/varint.ts
 var U32_CEIL = 4294967296;
 function writeVarint(out, value) {
@@ -2499,8 +2865,14 @@ function readU64(view, offset, field) {
   }
   return Number(big);
 }
+var keepLimits = /* @__PURE__ */ new WeakMap();
+function openCrbmReaderKeeping(blob, options, keepChunkBytesUpTo) {
+  const asked = { ...options };
+  if (keepChunkBytesUpTo !== void 0) keepLimits.set(asked, keepChunkBytesUpTo);
+  return CrbmReader.open(blob, asked);
+}
 var CrbmReader = class _CrbmReader {
-  constructor(blob, objectSize, generation, lineage, totalCardinality, index, servedFromTail, crypto, footerCrc, metadata, metadataWeight) {
+  constructor(blob, objectSize, generation, lineage, totalCardinality, index, servedFromTail, crypto, footerCrc, metadata, metadataWeight, payloadEnd, kept) {
     this.blob = blob;
     this.objectSize = objectSize;
     this.generation = generation;
@@ -2512,6 +2884,8 @@ var CrbmReader = class _CrbmReader {
     this.footerCrc = footerCrc;
     this.metadata = metadata;
     this.metadataWeight = metadataWeight;
+    this.payloadEnd = payloadEnd;
+    this.kept = kept;
   }
   blob;
   objectSize;
@@ -2524,6 +2898,8 @@ var CrbmReader = class _CrbmReader {
   footerCrc;
   metadata;
   metadataWeight;
+  payloadEnd;
+  kept;
   /**
    * Which object this reader opened, as its size and its footer's CRC. The footer covers the index's CRC, so two
    * objects with the same fingerprint hold the same chunks, as far as a CRC can tell; a pin compares it to know that
@@ -2548,11 +2924,12 @@ var CrbmReader = class _CrbmReader {
   /**
    * What this reader holds, the weight the storage reader cache bounds on: its parsed index
    * ({@link retainedIndexBytes}), plus a weight for the metadata it decoded, from its canonical length and its number
-   * of keys. Equal to {@link retainedIndexBytes} for a generation with no metadata. A cache heuristic, not a contract:
-   * how the metadata is weighed may change in any release.
+   * of keys, plus the chunk bytes kept from the open, when it kept any. Equal to {@link retainedIndexBytes} for a
+   * generation with no metadata and nothing kept. A cache heuristic, not a contract: how the metadata is weighed may
+   * change in any release.
    */
   get retainedBytes() {
-    return this.retainedIndexBytes + this.metadataWeight;
+    return this.retainedIndexBytes + this.metadataWeight + (this.kept?.length ?? 0);
   }
   /** Per-chunk cardinality (`chunkKey → count`) from the parsed index — no payload reads. */
   cardinalities() {
@@ -2750,7 +3127,11 @@ var CrbmReader = class _CrbmReader {
       options.crypto,
       storedFooterCrc,
       metadata,
-      metadata === void 0 ? 0 : RETAINED_BYTES_PER_METADATA_BYTE * metadataLength + RETAINED_BYTES_PER_METADATA_KEY * Object.keys(metadata).length
+      metadata === void 0 ? 0 : RETAINED_BYTES_PER_METADATA_BYTE * metadataLength + RETAINED_BYTES_PER_METADATA_KEY * Object.keys(metadata).length,
+      payloadEnd,
+      // Only a tail that began at the front of the object holds the chunks, and only a region the caller's limit
+      // allows is kept: a copy of just that region, so the tail buffer is not held.
+      tailCoversFrom === 0 && payloadEnd - PAYLOAD_START <= (keepLimits.get(options) ?? 0) ? tail.slice(PAYLOAD_START, payloadEnd) : void 0
     );
   }
   /** Chunk keys present in this generation, ascending. */
@@ -2792,7 +3173,30 @@ var CrbmReader = class _CrbmReader {
     if (offset < PAYLOAD_START || offset + length > this.objectSize - FOOTER_BYTES) {
       throw new IntegrityError(`chunk ${chunkKey} payload out of bounds`);
     }
-    const bytes = await this.blob.getRange(offset, length);
+    const held = this.keptRange(offset, length);
+    return this.openChunk(slot, chunkKey, held ?? await this.blob.getRange(offset, length));
+  }
+  /**
+   * `[offset, offset + length)` of the object from the kept chunk region, or `undefined` when it is not wholly in it
+   * (or nothing was kept). The bounds checks are defence on untrusted bytes: the index's validation at open keeps every
+   * extent inside the region, so they do not fire for a reader that opened.
+   *
+   * The range is returned as a copy, so nothing a caller or an AEAD does with it changes the next read.
+   */
+  keptRange(offset, length) {
+    const kept = this.kept;
+    if (kept === void 0 || offset < PAYLOAD_START || offset + length > PAYLOAD_START + kept.length) {
+      return void 0;
+    }
+    const from = offset - PAYLOAD_START;
+    return kept.slice(from, from + length);
+  }
+  /**
+   * Check one chunk's stored bytes against the index, and open them: the CRC32C first, then, on an encrypted object,
+   * the AEAD with the chunk's own associated data. The one check every read of a chunk goes through, whether the
+   * bytes came from a range of their own or from a slice of a larger one.
+   */
+  openChunk(slot, chunkKey, bytes) {
     if (crc32c(bytes) !== this.index.crcs[slot]) {
       throw new IntegrityError(`chunk ${chunkKey} payload CRC mismatch`);
     }
@@ -2809,6 +3213,154 @@ var CrbmReader = class _CrbmReader {
       this.crypto.aadFor(chunkKey)
     );
   }
+  /**
+   * The next needed chunk of the range in `cur`, checked and opened, as a stream hands it out; the range is let go of
+   * when this is its last chunk.
+   */
+  nextChunk(cur, slot, key) {
+    const range = cur.range;
+    const chunk = range.read.chunks[cur.at++];
+    if (cur.at === range.read.chunks.length) cur.range = void 0;
+    const from = chunk.offset - range.read.offset;
+    const bytes = this.openChunk(slot, chunk.key, range.bytes.subarray(from, from + chunk.length));
+    return { key, bytes };
+  }
+  /**
+   * Read several chunks as a stream, one storage request per merged range ({@link planChunkReads}) rather than one per
+   * chunk. `chunkKeys` are in ascending order, a key may repeat, and anything else is a {@link ValidationError}. One
+   * item comes out per position of `chunkKeys`, in order: the chunk's bytes, or `null` where this generation has none,
+   * as {@link getChunk} answers for an absent key. A key given twice is read once and answered at both positions with
+   * the same view.
+   *
+   * The whole key list is planned once, up front, against this one generation's index. The ranges then run through a
+   * window of `options.concurrency` reads ({@link MAX_RANGES_IN_FLIGHT} by default) that counts a range until the
+   * consumer has taken it, so a stream never holds more than that many ranges, in flight or landed, however many keys
+   * it was given or how slowly it is read; with `options.ramp` the window opens 1, 2, 4 … wide. A range is at most 1 MiB
+   * unless it is one chunk, which is at most the payload cap, so the bound is that many times the per-chunk cap
+   * (1 MiB, and 28 bytes more for an encrypted chunk). Nothing is read until the first item is asked for, and a
+   * consumer that stops launches no more: ranges already in flight finish and are dropped, and a failure of one of
+   * those is never raised.
+   *
+   * Every chunk is held to the check a read of it alone gets: its slice of the range must match its index entry's
+   * CRC32C, and on an encrypted object it opens under its own associated data, so a chunk moved to another place in
+   * the object, or another key's bytes, is refused. The bytes in a gap between needed chunks are never parsed. A
+   * range that comes back shorter than asked is an {@link IntegrityError}, and a chunk that fails its check ends the
+   * stream with that error when its turn comes, as a read of it alone would fail.
+   *
+   * `options.readRange`, when given, runs each range read, so a caller can retry one request without repeating the
+   * others; `options.now` times each request for `options.onRequest`, which hears of every range request that was sent, once, when
+   * it settles: taken, abandoned after the consumer stopped, or failed (a reader has no clock of its own, so `ms` is 0
+   * without one).
+   * A plain chunk is a writable view into the range it was read in: copy a chunk to keep it.
+   *
+   * A stream that fails (a range that errors, a chunk that fails its check) raises at once and sends nothing further:
+   * the ranges it still had in flight finish in the background, are not retried and never raise. Its `settled()`
+   * resolves when those have finished, for a caller that is about to read again and does not want them beside its next
+   * window (the source awaits it before a heal, and only then). It waits as long as the slowest of them takes to
+   * answer, which only the store's own read timeout bounds, so a read that never answers delays a heal and never an
+   * error.
+   */
+  readChunks(chunkKeys, options = {}) {
+    const open4 = { window: void 0 };
+    const stream = this.streamChunks(chunkKeys, options, open4);
+    return Object.assign(stream, {
+      settled: () => open4.window?.settle() ?? Promise.resolve()
+    });
+  }
+  async *streamChunks(chunkKeys, options, open4) {
+    const width = options.concurrency ?? MAX_RANGES_IN_FLIGHT;
+    if (!Number.isInteger(width) || width < 1) {
+      throw new ValidationError(
+        `concurrency must be a positive integer; got ${options.concurrency}`
+      );
+    }
+    validateChunkKeyOrder(chunkKeys);
+    const ramp = options.ramp ?? false;
+    if (typeof ramp === "number" && (!Number.isInteger(ramp) || ramp < 1)) {
+      throw new ValidationError(`ramp must be a boolean or a positive integer; got ${ramp}`);
+    }
+    const readRange = options.readRange ?? ((read) => read());
+    const now = options.now ?? (() => 0);
+    const slots = chunkKeys.map((key) => this.slotOf(key));
+    const needed = [...new Set(slots.filter((slot) => slot >= 0))];
+    const extents = needed.map((slot) => ({
+      key: this.index.keys[slot],
+      offset: this.index.offsets[slot],
+      length: this.index.lengths[slot]
+    }));
+    const reads = planChunkReads(extents, { start: PAYLOAD_START, end: this.payloadEnd });
+    let closed = false;
+    const report = (bytes, ms) => {
+      try {
+        options.onRequest?.({ bytes, ms });
+      } catch {
+      }
+    };
+    const window = new ChunkWindow(
+      reads.map((_, i) => i),
+      async (i) => {
+        const read = reads[i];
+        const held = this.keptRange(read.offset, read.length);
+        if (held !== void 0) return { bytes: held };
+        const startedAt = now();
+        let sent = false;
+        let moved = 0;
+        try {
+          const bytes = await readRange(() => {
+            if (closed) throw new StreamClosed();
+            sent = true;
+            return this.blob.getRange(read.offset, read.length);
+          });
+          moved = bytes.length;
+          if (bytes.length !== read.length) {
+            throw new IntegrityError(
+              `.crbm range [${read.offset}, +${read.length}) read short (${bytes.length} bytes)`
+            );
+          }
+          return { bytes };
+        } finally {
+          if (sent) report(moved, Math.max(0, now() - startedAt));
+        }
+      },
+      width,
+      ramp !== false,
+      typeof ramp === "number" ? ramp : 1
+    );
+    open4.window = window;
+    let next = 0;
+    const cur = { range: void 0, at: 0 };
+    let last;
+    try {
+      for (const [i, key] of chunkKeys.entries()) {
+        if (slots[i] < 0) {
+          yield { key, bytes: null };
+          continue;
+        }
+        if (last !== void 0 && last.key === key) {
+          yield { key, bytes: last.bytes };
+          if (chunkKeys[i + 1] !== key) last = void 0;
+          continue;
+        }
+        if (cur.range === void 0) {
+          cur.range = { read: reads[next++], ...await window.take() };
+          cur.at = 0;
+        }
+        if (chunkKeys[i + 1] === key) {
+          last = this.nextChunk(cur, slots[i], key);
+          yield last;
+        } else {
+          yield this.nextChunk(cur, slots[i], key);
+        }
+      }
+    } finally {
+      closed = true;
+    }
+  }
+};
+var StreamClosed = class extends Error {
+  constructor() {
+    super("the chunk stream was closed");
+  }
 };
 function within(bytes, start, from, to) {
   if (from < start || to > start + bytes.length) {
@@ -2938,6 +3490,33 @@ function parseIndex(indexBytes, payloadEnd, maxPayloadBytes, minPayloadBytes = 1
   };
 }
 
+// src/core/item-pull.ts
+var ItemPull = class {
+  iterator;
+  item;
+  constructor(source) {
+    this.iterator = source[Symbol.asyncIterator]();
+  }
+  /** Waits for the next item and keeps it inside; `false` once the source has ended. A failure of the source throws. */
+  async advance() {
+    const step = await this.iterator.next();
+    if (step.done === true) return false;
+    this.item = step.value;
+    return true;
+  }
+  /** Hands over the item {@link advance} fetched, through `map`, and forgets it. */
+  take(map) {
+    const item = this.item;
+    this.item = void 0;
+    return map(item);
+  }
+  /** Ends the source early (a consumer that stopped), as leaving a `for await` does. */
+  async close() {
+    this.item = void 0;
+    await this.iterator.return?.();
+  }
+};
+
 // src/core/crbm/writer.ts
 var CrbmWriter = class {
   constructor(sink, options) {
@@ -3472,6 +4051,10 @@ var CrbmStorageChunkSource = class {
     this.keystore = keystore;
     this.requireEncryption = requireEncryption ?? false;
     this.readerOptions = readerOptions;
+    const refreshes = registry !== void 0 && clock !== void 0 && (currentGenTtlMs ?? DEFAULT_CURRENT_GEN_TTL_MS) > 0;
+    this.keepChunkBytesUpTo = refreshes ? Math.floor(
+      (maxOpenIndexBytes ?? DEFAULT_MAX_OPEN_INDEX_BYTES) / (maxOpenSegments ?? DEFAULT_MAX_OPEN_SEGMENTS)
+    ) : 0;
     this.clock = clock;
     this.currentGenTtlMs = currentGenTtlMs ?? DEFAULT_CURRENT_GEN_TTL_MS;
     this.snapshots = new BoundedLru({
@@ -3535,6 +4118,8 @@ var CrbmStorageChunkSource = class {
   keystore;
   requireEncryption;
   readerOptions;
+  /** The most chunk bytes a reader keeps from its open: the reader cache's byte bound over its count bound, per reader; 0 without a timed pointer refresh. */
+  keepChunkBytesUpTo;
   clock;
   currentGenTtlMs;
   /**
@@ -3979,11 +4564,12 @@ var CrbmStorageChunkSource = class {
       segment: ref.segment,
       generation: target.generation
     };
-    return openChecked(this.driver, genKey, {
-      ...this.readerOptions,
-      crypto,
-      lineage: target.lineage
-    });
+    return openChecked(
+      this.driver,
+      genKey,
+      { ...this.readerOptions, crypto, lineage: target.lineage },
+      this.keepChunkBytesUpTo
+    );
   }
   /**
    * Open the generation a resolution found, and hold the row's summary against the object while it is open anyway:
@@ -4070,6 +4656,128 @@ var CrbmStorageChunkSource = class {
     validateChunkRef(ref);
     return this.withFreshSnapshot(ref, (reader) => reader.getChunk(ref.chunkKey), null);
   }
+  /**
+   * Several chunks as a stream, in as few storage requests as {@link CrbmReader.readChunks} can make them (see
+   * {@link StorageChunkSource.getChunks}). The stream is served from one resolved generation, and every chunk says
+   * which version it came from. A generation swept, or an object replaced under its number, while the stream runs
+   * re-resolves the segment and carries on with the keys not yet yielded from whatever is current then, so each chunk
+   * is whole and from one generation and the stream may describe two; a second failure with no chunk yielded in between
+   * propagates. `options.retry` runs the resolution, each range request and the check that a failed read's object was
+   * replaced, so a transient fault repeats that step alone. Nothing is resolved until the first chunk is asked for.
+   */
+  async *getChunks(ref, keys, options) {
+    validateUserRef(ref);
+    for (const chunkKey of keys) validateChunkRef({ ...ref, chunkKey });
+    validateChunkKeyOrder(keys);
+    const retry = options?.retry;
+    let yielded = 0;
+    let healed = false;
+    for (; ; ) {
+      let snap = this.liveSnapshot(ref);
+      let pending = snap.reader;
+      let chunks;
+      try {
+        let tried = false;
+        const reader = await (retry === void 0 ? pending : retry(() => {
+          if (tried) {
+            snap = this.liveSnapshot(ref);
+            pending = snap.reader;
+          }
+          tried = true;
+          return pending;
+        }));
+        if (reader === null) {
+          for (; yielded < keys.length; yielded++) {
+            yield { key: keys[yielded], bytes: null, version: null };
+          }
+          return;
+        }
+        const version = versionOf(reader.generation, reader.lineage);
+        chunks = reader.readChunks(keys.slice(yielded), {
+          ...options?.concurrency === void 0 ? {} : { concurrency: options.concurrency },
+          ...options?.ramp === void 0 ? {} : { ramp: options.ramp },
+          ...retry === void 0 ? {} : { readRange: retry },
+          ...options?.onRequest === void 0 ? {} : { onRequest: options.onRequest },
+          now: () => this.now()
+        });
+        const pull = new ItemPull(chunks);
+        let movedOn = false;
+        try {
+          while (await pull.advance()) {
+            const live = this.liveSnapshot(ref);
+            if (live !== snap) {
+              const now = await live.reader;
+              if (now === null || versionOf(now.generation, now.lineage) !== version) {
+                movedOn = true;
+                break;
+              }
+              snap = live;
+            }
+            yield pull.take((chunk) => {
+              yielded += 1;
+              healed = false;
+              return { ...chunk, version };
+            });
+          }
+        } finally {
+          await pull.close();
+        }
+        if (!movedOn) return;
+        await chunks.settled();
+        healed = false;
+        continue;
+      } catch (err) {
+        if (healed) throw err;
+        if (!isNotFoundError(err) && !await this.replacedUnder(ref, pending, err, retry))
+          throw err;
+        await chunks?.settled();
+        this.dropStale(segmentKey(ref), snap);
+        healed = true;
+      }
+    }
+  }
+  /**
+   * {@link getChunks} of a specific generation, the pinned shape read. It yields the chunks without a version: the
+   * caller that pinned the generation knows it. It never moves to another generation; `held` as for
+   * {@link getChunkAt}.
+   */
+  async *getChunksAt(ref, generation, keys, held, options) {
+    validateUserRef(ref);
+    for (const chunkKey of keys) validateChunkRef({ ...ref, chunkKey });
+    validateChunkKeyOrder(keys);
+    const retry = options?.retry;
+    const open4 = () => this.readerAt(ref, generation, held?.version, held?.fingerprint);
+    const reader = await (retry === void 0 ? open4() : retry(open4));
+    if (reader === null) {
+      for (const key of keys) yield { key, bytes: null };
+      return;
+    }
+    const fingerprint = held?.fingerprint;
+    if (held !== void 0 && fingerprint !== void 0 && this.replacedPins.get(this.heldKey(ref, held.version, fingerprint)) !== void 0)
+      throw notThePinned(ref, generation);
+    try {
+      const pull = new ItemPull(
+        reader.readChunks(keys, {
+          ...options?.concurrency === void 0 ? {} : { concurrency: options.concurrency },
+          ...options?.ramp === void 0 ? {} : { ramp: options.ramp },
+          ...retry === void 0 ? {} : { readRange: retry },
+          ...options?.onRequest === void 0 ? {} : { onRequest: options.onRequest },
+          now: () => this.now()
+        })
+      );
+      try {
+        while (await pull.advance()) yield pull.take((chunk) => chunk);
+      } finally {
+        await pull.close();
+      }
+    } catch (err) {
+      if (held === void 0 || fingerprint === void 0) throw err;
+      if (!(isIntegrityError(err) || isValidationError(err))) throw err;
+      const check = () => this.throwIfReplaced(ref, generation, held.version, fingerprint);
+      await (retry === void 0 ? check() : retry(check));
+      throw err;
+    }
+  }
   async listChunkKeys(ref) {
     validateUserRef(ref);
     return this.withFreshSnapshot(ref, (reader) => reader.chunkKeys(), []);
@@ -4156,17 +4864,26 @@ var CrbmStorageChunkSource = class {
    * tight loop on a segment whose pointer names an object that is permanently absent — and an N-way
    * `intersect` would do it N times. Gated in `tests/core/storage-source-heal-open.test.ts` by counting calls.
    */
-  async withFreshSnapshot(ref, read, ifGone) {
+  async withFreshSnapshot(ref, read, ifGone, retry) {
     for (let attempt = 0; attempt < 2; attempt++) {
-      const snap = this.liveSnapshot(ref);
-      const pending = snap.reader;
+      let snap = this.liveSnapshot(ref);
+      let pending = snap.reader;
       try {
-        const reader = await pending;
+        let tried = false;
+        const reader = await (retry === void 0 ? pending : retry(() => {
+          if (tried) {
+            snap = this.liveSnapshot(ref);
+            pending = snap.reader;
+          }
+          tried = true;
+          return pending;
+        }));
         if (reader === null) return ifGone;
         return await read(reader);
       } catch (err) {
         if (attempt === 1) throw err;
-        if (!isNotFoundError(err) && !await this.replacedUnder(ref, pending, err)) throw err;
+        if (!isNotFoundError(err) && !await this.replacedUnder(ref, pending, err, retry))
+          throw err;
         this.dropStale(segmentKey(ref), snap);
       }
     }
@@ -4182,7 +4899,7 @@ var CrbmStorageChunkSource = class {
    * the error is real, and it stands. Only these two errors pay for the footer read, never a read that succeeded. A
    * transient fault in the check is rethrown; a footer that cannot be read says nothing, and the error stands.
    */
-  async replacedUnder(ref, pending, err) {
+  async replacedUnder(ref, pending, err, retry) {
     if (!(isIntegrityError(err) || isValidationError(err))) return false;
     let reader;
     try {
@@ -4197,7 +4914,8 @@ var CrbmStorageChunkSource = class {
       generation: reader.generation
     };
     try {
-      return !await CrbmReader.sameObject(storageBlobReader(this.driver, at), reader.fingerprint);
+      const check = () => CrbmReader.sameObject(storageBlobReader(this.driver, at), reader.fingerprint);
+      return !await (retry === void 0 ? check() : retry(check));
     } catch (checkErr) {
       if (isNotFoundError(checkErr)) return true;
       if (isTransientError(checkErr)) throw checkErr;
@@ -4477,7 +5195,7 @@ async function provesOwnObject(storage, key, fingerprint) {
     throw err;
   }
 }
-async function bulkLoadCrbmGeneration(driver, key, ids, options = {}) {
+async function bulkLoadAhead(driver, ref, ahead, ids, options = {}) {
   if (options.keystore === void 0 && options.requireEncryption === true) {
     throw new ValidationError("requireEncryption: a load needs a keystore to write encrypted");
   }
@@ -4497,27 +5215,30 @@ async function bulkLoadCrbmGeneration(driver, key, ids, options = {}) {
     throw new ValidationError("an encrypted load requires a registry to store the wrapped DEK");
   }
   const passed = options.row;
-  const existing = passed !== void 0 && passed !== null && (passed.wrappedDeks === void 0 || passed.wrappedDeks.length === 0) ? passed : options.registry !== void 0 ? await options.registry.get(key) : null;
+  const existing = passed !== void 0 && passed !== null && (passed.wrappedDeks === void 0 || passed.wrappedDeks.length === 0) ? passed : options.registry !== void 0 ? await options.registry.get(ref) : null;
   if (existing?.status === "destroyed") {
     throw new ValidationError(
-      `segment "${key.segment}" is destroyed (crypto-shredded) \u2014 refusing to write; use a new segment`
+      `segment "${ref.segment}" is destroyed (crypto-shredded) \u2014 refusing to write; use a new segment`
     );
   }
   if (existing?.wrappedDeks !== void 0 && existing.wrappedDeks.length > 0 && options.keystore === void 0) {
     throw new KeyUnavailableError(
-      `segment "${key.segment}" is encrypted but this load has no keystore \u2014 refusing to write a cleartext generation onto an encrypted segment. Pass the keystore holding its DEK.`
+      `segment "${ref.segment}" is encrypted but this load has no keystore \u2014 refusing to write a cleartext generation onto an encrypted segment. Pass the keystore holding its DEK.`
     );
   }
+  const generation = await ahead.generation;
+  const key = { namespace: ref.namespace, segment: ref.segment, generation };
   let crypto;
   let newWrapped;
   if (options.keystore !== void 0) {
     if (existing?.wrappedDeks !== void 0 && existing.wrappedDeks.length > 0) {
-      const aead = await options.keystore.openDek(existing.wrappedDeks);
+      const early = ahead.unwrapped;
+      const aead = early !== void 0 && sameKeys(early.wrapped, existing.wrappedDeks) ? await early.aead : await options.keystore.openDek(existing.wrappedDeks);
       crypto = { aead, aadFor: (scope) => aadFor(key, key.generation, scope) };
     } else if (existing !== null && existing.currentGen !== null) {
       if (options.requireEncryption === true) {
         throw new ValidationError(
-          `requireEncryption: segment "${key.segment}" already has generation ${existing.currentGen} in cleartext, so this load cannot be encrypted \u2014 encryption is chosen when a segment is first loaded. Load into a new segment with the keystore wired, then drop this one.`
+          `requireEncryption: segment "${ref.segment}" already has generation ${existing.currentGen} in cleartext, so this load cannot be encrypted \u2014 encryption is chosen when a segment is first loaded. Load into a new segment with the keystore wired, then drop this one.`
         );
       }
     } else {
@@ -4624,8 +5345,12 @@ async function bucketIds(ids, codec, clock) {
 function openGenerationReader(storage, key, crypto, options = {}) {
   return openChecked(storage, key, { ...options, crypto });
 }
-async function openChecked(storage, key, options) {
-  const reader = await CrbmReader.open(storageBlobReader(storage, key), options);
+async function openChecked(storage, key, options, keepChunkBytesUpTo) {
+  const reader = await openCrbmReaderKeeping(
+    storageBlobReader(storage, key),
+    options,
+    keepChunkBytesUpTo
+  );
   if (reader.generation !== key.generation) {
     throw new IntegrityError(
       `segment "${key.segment}" generation ${key.generation}: its footer says generation ${reader.generation}`
@@ -4686,6 +5411,30 @@ var PinnedStorageChunkSource = class {
     if (pin === void 0) return this.inner.getChunk(ref);
     return pin.generation === null ? Promise.resolve(null) : this.inner.getChunkAt(ref, pin.generation, heldBy(pin));
   }
+  /**
+   * A pinned segment's chunks come from the pinned generation alone, under the version a pinned read keys by
+   * ({@link currentVersion}); another segment's go to the live source, which answers with its own.
+   */
+  getChunks(ref, keys, options) {
+    const pin = this.pinFor(ref);
+    if (pin === void 0) return this.inner.getChunks(ref, keys, options);
+    return this.pinnedChunks(ref, pin, keys, options);
+  }
+  async *pinnedChunks(ref, pin, keys, options) {
+    if (pin.generation === null) {
+      for (const key of keys) yield { key, bytes: null, version: null };
+      return;
+    }
+    const version = await this.currentVersion(ref);
+    const pull = new ItemPull(
+      this.inner.getChunksAt(ref, pin.generation, keys, heldBy(pin), options)
+    );
+    try {
+      while (await pull.advance()) yield pull.take((chunk) => ({ ...chunk, version }));
+    } finally {
+      await pull.close();
+    }
+  }
   listChunkKeys(ref) {
     const pin = this.pinFor(ref);
     if (pin === void 0) return this.inner.listChunkKeys(ref);
@@ -4788,7 +5537,11 @@ async function withRetry(op, policy, deps) {
 }
 
 // src/core/load.ts
-async function currentCardinality(ref, deps, record) {
+function settled(promise) {
+  promise.catch(() => void 0);
+  return promise;
+}
+async function currentCardinality(ref, deps, record, unwrapped) {
   if (record === null || record.currentGen === null || record.status === "destroyed") {
     return { cardinality: null, fromSummary: false };
   }
@@ -4802,7 +5555,7 @@ async function currentCardinality(ref, deps, record) {
         `segment "${ref.segment}" is encrypted but load was given no keystore`
       );
     }
-    aead = await deps.keystore.openDek(wrapped);
+    aead = await (unwrapped ?? deps.keystore.openDek(wrapped));
     const opened = aead;
     crypto = { aead: opened, aadFor: (scope) => aadFor(ref, generation, scope) };
   }
@@ -4853,35 +5606,44 @@ async function loadSegment(ref, input, deps, options = {}) {
   const row = await deps.registry.get(ref);
   const fromToken = row?.token;
   const fromGeneration = row?.currentGen ?? void 0;
+  const wrappedKeys = row?.wrappedDeks;
+  const keystore = deps.keystore;
+  const unwrapped = row !== null && row.status !== "destroyed" && wrappedKeys !== void 0 && wrappedKeys.length > 0 && keystore !== void 0 ? { wrapped: wrappedKeys, aead: settled((async () => keystore.openDek(wrappedKeys))()) } : void 0;
   const needsBefore = guard?.minRetained !== void 0 || options.allowEmpty !== true;
-  const current = needsBefore ? await currentCardinality(ref, deps, row) : { cardinality: null, fromSummary: false };
+  const current = needsBefore ? await currentCardinality(ref, deps, row, unwrapped?.aead) : { cardinality: null, fromSummary: false };
   const before = current.cardinality;
-  const { generation, checked } = await nextLoadGeneration(ref, deps, row);
-  const key = { namespace: ref.namespace, segment: ref.segment, generation };
+  const numbering = settled(nextLoadGeneration(ref, deps, row));
   let written;
   try {
-    written = await bulkLoadCrbmGeneration(deps.storage, key, ids, {
-      registry: deps.registry,
-      publish: false,
-      keystore: deps.keystore,
-      requireEncryption: deps.requireEncryption,
-      codec: deps.codec,
-      clock: deps.clock,
-      metadata,
-      row
-    });
+    written = await bulkLoadAhead(
+      deps.storage,
+      ref,
+      { generation: settled(numbering.then((n) => n.generation)), unwrapped },
+      ids,
+      {
+        registry: deps.registry,
+        publish: false,
+        keystore: deps.keystore,
+        requireEncryption: deps.requireEncryption,
+        codec: deps.codec,
+        clock: deps.clock,
+        metadata,
+        row
+      }
+    );
   } catch (err) {
     if (!isWriteConflictError(err)) throw err;
+    const { generation: generation2 } = await numbering;
     audit.onEvent({
       kind: "segment.load-refused",
       segment: ref.segment,
       namespace: ref.namespace,
-      generation,
+      generation: generation2,
       reason: "superseded",
       cardinality: 0
     });
     return {
-      generation,
+      generation: generation2,
       published: false,
       reason: "superseded",
       size: 0,
@@ -4892,6 +5654,8 @@ async function loadSegment(ref, input, deps, options = {}) {
       collected: []
     };
   }
+  const { generation, checked } = await numbering;
+  const key = { namespace: ref.namespace, segment: ref.segment, generation };
   const reclaim = async () => {
     const now = await deps.registry.get(ref);
     if (now !== null && (now.token === fromToken || now.status === "destroyed")) {
@@ -5132,6 +5896,7 @@ function describingSummary(record) {
 }
 
 // src/core/erase-id.ts
+var HOLDS_CONCURRENCY = 4;
 async function eraseIdFromSegment(ref, id, deps, options = {}) {
   validateUserRef(ref);
   const { chunkKey, remainder } = splitId(id);
@@ -5193,13 +5958,37 @@ async function eraseIdFromSegment(ref, id, deps, options = {}) {
       throw err;
     }
   };
+  const holdsEach = async (generations, stopAtHolder) => {
+    let firstHolder = Infinity;
+    const settled2 = await mapWithConcurrency(
+      generations,
+      HOLDS_CONCURRENCY,
+      async (generation2, index) => {
+        if (stopAtHolder && index > firstHolder) {
+          return { generation: generation2, held: null, fault: void 0 };
+        }
+        try {
+          const held = await holds(generation2);
+          if (held === true && index < firstHolder) firstHolder = index;
+          return { generation: generation2, held, fault: void 0 };
+        } catch (fault) {
+          return { generation: generation2, held: null, fault: { error: fault } };
+        }
+      }
+    );
+    const outcomes = [];
+    for (const { generation: generation2, held, fault } of settled2) {
+      if (fault !== void 0) throw fault.error;
+      outcomes.push({ generation: generation2, held });
+      if (stopAtHolder && held === true) break;
+    }
+    return outcomes;
+  };
   const holderLeft = async (clean) => {
     const present = /* @__PURE__ */ new Set();
     for await (const key2 of deps.storage.list(ref)) present.add(key2.generation);
-    for (const generation2 of [...present].sort((a, b) => b - a)) {
-      if (!clean.has(generation2) && await holds(generation2) === true) return generation2;
-    }
-    return void 0;
+    const toRead = [...present].sort((a, b) => b - a).filter((generation2) => !clean.has(generation2));
+    return (await holdsEach(toRead, true)).find((outcome) => outcome.held === true)?.generation;
   };
   const cannotRemove = (generation2) => new WriteConflictError(
     `erasure of segment ${ref.segment} could not remove generation ${generation2}, which still holds the id and is still in the bucket; re-run`
@@ -5220,20 +6009,21 @@ async function eraseIdFromSegment(ref, id, deps, options = {}) {
     const newestFirst = [...others].sort((a, b) => b - a);
     const clean = /* @__PURE__ */ new Set([from]);
     const holdersAbove = [];
-    for (const generation2 of newestFirst.filter((g) => g > from)) {
-      const held = await holds(generation2);
+    for (const { generation: generation2, held } of await holdsEach(
+      newestFirst.filter((g) => g > from),
+      false
+    )) {
       if (held === true) holdersAbove.push(generation2);
       else if (held === false) clean.add(generation2);
     }
     let holderBelow;
     if (holdersAbove.length === 0) {
-      for (const generation2 of newestFirst.filter((g) => g < from)) {
-        const held = await holds(generation2);
-        if (held === true) {
-          holderBelow = generation2;
-          break;
-        }
-        if (held === false) clean.add(generation2);
+      for (const { generation: generation2, held } of await holdsEach(
+        newestFirst.filter((g) => g < from),
+        true
+      )) {
+        if (held === true) holderBelow = generation2;
+        else if (held === false) clean.add(generation2);
       }
     }
     const newest = holdersAbove[0] ?? holderBelow;
@@ -5348,25 +6138,31 @@ async function eraseIdFromSegment(ref, id, deps, options = {}) {
   if (left !== void 0) throw cannotRemove(left);
   return { ...base, erased: true, fromGeneration: from, generation, collected };
 }
-var REWRITE_READ_AHEAD = 32;
+var REWRITE_RANGES_AHEAD = 4;
 async function* rewrite(reader, chunkKey, replacement, codec, maxBytes, read) {
   const keys = [...reader.chunkKeys()].sort((a, b) => a - b);
-  const window = new ChunkWindow(
+  const stream = reader.readChunks(
     keys.filter((k) => k !== chunkKey),
-    (k) => read(() => reader.getChunk(k)),
-    REWRITE_READ_AHEAD,
-    false
+    { concurrency: REWRITE_RANGES_AHEAD, readRange: read }
   );
-  for (const k of keys) {
-    if (k === chunkKey) {
-      yield { chunkKey: k, bitmap: replacement };
-      continue;
+  try {
+    for (const k of keys) {
+      if (k === chunkKey) {
+        yield { chunkKey: k, bitmap: replacement };
+        continue;
+      }
+      const item = await stream.next();
+      if (item.done === true || item.value.key !== k) {
+        throw new IntegrityError(`the chunk stream ended before chunk ${k}`);
+      }
+      const bytes = item.value.bytes;
+      if (bytes === null) continue;
+      const bitmap = codec.safeDeserialize(bytes, maxBytes);
+      assertRemaindersInRange(bitmap, k);
+      yield { chunkKey: k, bitmap };
     }
-    const bytes = await window.take();
-    if (bytes === null) continue;
-    const bitmap = codec.safeDeserialize(bytes, maxBytes);
-    assertRemaindersInRange(bitmap, k);
-    yield { chunkKey: k, bitmap };
+  } finally {
+    await stream.return(void 0);
   }
 }
 function assertRemaindersInRange(bitmap, chunkKey) {
@@ -5521,9 +6317,8 @@ async function eraseNamespace(namespace, deps, options) {
     segment: rec.segment
   }));
   const audit = safeAudit(options.audit ?? NOOP_AUDIT);
-  const destroyed = [];
   let segmentsShredded = 0;
-  for (const ref of refs) {
+  const destroyed = await mapWithConcurrency(refs, ERASE_CONCURRENCY, async (ref) => {
     let result;
     try {
       result = await shredSegment(ref, deps, options.allowCleartext ?? false);
@@ -5536,12 +6331,12 @@ async function eraseNamespace(namespace, deps, options) {
         reason: isWriteConflictError(err) ? "contended" : `failed: ${err instanceof Error ? err.message : String(err)}`
       };
     }
-    destroyed.push(result);
     if (result.cryptoShredded) {
       segmentsShredded += 1;
       audit.onEvent({ kind: "segment.erase", namespace: ref.namespace, segment: ref.segment });
     }
-  }
+    return result;
+  });
   audit.onEvent({ kind: "namespace.erase", namespace, segmentsShredded });
   return { destroyed };
 }
@@ -6280,6 +7075,7 @@ var RetryingStorageChunkSource = class {
   deps;
   /** Present only when the inner source supports it — so capability detection stays honest. */
   sizeOf;
+  getChunks;
   cardinalities;
   summary;
   currentGeneration;
@@ -6302,6 +7098,16 @@ var RetryingStorageChunkSource = class {
     if (innerSizeOf) {
       this.sizeOf = (ref) => withRetry(() => innerSizeOf.call(inner, ref), this.policy, this.deps);
     }
+    const innerGetChunks = inner.getChunks;
+    if (innerGetChunks) {
+      this.getChunks = (ref, keys, options) => {
+        const outer = options?.retry;
+        return innerGetChunks.call(inner, ref, keys, {
+          ...options,
+          retry: (request) => withRetry(outer === void 0 ? request : () => outer(request), this.policy, this.deps)
+        });
+      };
+    }
     const innerCardinalities = inner.cardinalities;
     if (innerCardinalities) {
       this.cardinalities = (ref) => withRetry(() => innerCardinalities.call(inner, ref), this.policy, this.deps);