@cloudbitmaps/core 0.25.0 → 0.27.0

package/dist/index.js

@@ -1,7 +1,7 @@
 import {
   boundedAll,
   mapWithConcurrency
-} from "./chunk-BUDAVGBI.js";
+} from "./chunk-YNNGMHX2.js";
 import {
   BufferReader,
   KeptSegmentKeys,
@@ -9,7 +9,7 @@ import {
   segmentKey,
   segmentPrefix,
   shardOf
-} from "./chunk-WPER7R2R.js";
+} from "./chunk-KO3Z2RBA.js";
 import {
   BudgetExceededError,
   CHUNK_COUNT,
@@ -116,7 +116,7 @@ import {
   validateUserRef,
   windowOf,
   withRetry
-} from "./chunk-2B2QF4FU.js";
+} from "./chunk-UUNBQVKR.js";
 
 // src/core/budget.ts
 var DEFAULT_BUDGET = { maxRequests: 1e6 };
@@ -220,7 +220,7 @@ function assertChunkPayloadInRange(bitmap) {
   }
 }
 function decodeChunkBytes(codec, bytes, maxBitmapBytes) {
-  const bitmap = codec.safeDeserialize(bytes, maxBitmapBytes);
+  const bitmap = codec.safeDeserialize(bytes, maxBitmapBytes, { whole: true });
   assertChunkPayloadInRange(bitmap);
   return bitmap;
 }
@@ -674,6 +674,7 @@ var COMBINE_WINDOW_START = 8;
 var COMBINE_RANGE_START = 4;
 var OPERANDS_AT_ONCE = 16;
 var BATCH_QUIET_HOPS = 16;
+var COUNT_RELIST_ATTEMPTS = 4;
 var ZERO_CLOCK = { now: () => 0 };
 var CombineWindow = class {
   constructor(keys, limit, read) {
@@ -797,6 +798,19 @@ function combineReads(keys, operands, excludes, mode, through) {
   }
   return units;
 }
+function countSteps(operands, excludes, mode, w) {
+  const steps = [];
+  const decode = [];
+  for (const key of alignKeys(operands, mode)) {
+    const holders = mode === "all" ? operands : operands.filter((o) => o.keys.has(key));
+    const only = holders.length === 1 ? holders[0] : void 0;
+    const n = only?.cards?.get(key);
+    const viaIndex = n !== void 0 && !excludes.some((e) => e.keys.has(key)) && !(w !== null && isEdge(key, w));
+    steps.push({ key, n: viaIndex ? n : -1 });
+    if (!viaIndex) decode.push(key);
+  }
+  return { steps, decode };
+}
 var SegmentEngine = class _SegmentEngine {
   storage;
   cache;
@@ -1514,6 +1528,209 @@ var SegmentEngine = class _SegmentEngine {
       this.closeCombine(run.plan);
     }
   }
+  /**
+   * How many ids `segs[0] ∩ …` (`mode` 'all') or `segs[0] ∪ …` ('any') holds, minus `excludeSegs`, without streaming
+   * them: the size of what {@link combine} would stream. Each chunk key is taken one of two ways. A key exactly one
+   * include holds, that no exclude holds and the range does not cut, is answered from the index's count for it, with
+   * no chunk read. Every other key is decoded and counted as the combine reads it, with the same plan, the same ranges
+   * and the same window, over those keys alone. So an intersection reads what its stream reads, and a union or a
+   * difference reads no more than its stream.
+   *
+   * The keys answered from the index are trusted as {@link count} trusts the index, and checked no further than the
+   * reader checks it when it opens the object; a decoded key is exact. A source that reports no per-chunk counts has
+   * every key decoded. A union or a difference of one operand with no exclude and no range is {@link count}.
+   *
+   * A running union or difference, or an intersection with an `exclude`, looks at its operands' versions every
+   * `concurrency` keys, a key answered from the index being one taken, and any count looks before the first key after
+   * an invalidation, and runs `options.guard` at each look. On a move it plans again above the last key taken, as a
+   * combine does, so the bound on what it serves of an earlier generation is the combine's. A pinned operand's object
+   * is looked up before the first key and at each look there is (one footer read each, a fault other than a transient
+   * one raised as it is), so an erasure of what it pinned stops the count there with the pin's `NotFoundError`. An
+   * intersection of two or more operands with no exclude decodes every key and so shows a move without a version
+   * look; its guard still runs every `concurrency` keys.
+   */
+  async combineCount(segs, excludeSegs, mode, op, options) {
+    const label = `${op}Count`;
+    if (segs.length === 0) throw new ValidationError(`${label} requires at least one segment`);
+    const limit = options?.concurrency === void 0 ? DEFAULT_INTERSECT_CONCURRENCY : options.concurrency;
+    requirePositiveInteger(limit, `${label}: concurrency`);
+    const budget = resolvePerOpBudget(options?.budget, this.budget);
+    const w = windowOf2(options, label);
+    options?.guard?.();
+    if (w === "empty") return 0;
+    if (op !== "intersect" && segs.length === 1 && excludeSegs.length === 0 && w === null) {
+      const n = await this.count(segs[0]);
+      if (n === 0) {
+        const none = {
+          seg: segs[0],
+          keys: /* @__PURE__ */ new Set(),
+          chunkless: true,
+          gen: void 0,
+          epoch: 0
+        };
+        await this.refuseAbsentOperands([none], options?.allowAbsentOperands, label);
+      }
+      return n;
+    }
+    const epoch = this.scope.epoch;
+    const [operands, excludes] = await this.countOperands(segs, excludeSegs, mode, w, -1);
+    await this.refuseAbsentOperands(
+      [...operands, ...excludes],
+      options?.allowAbsentOperands,
+      label
+    );
+    await this.verifyPinned([...operands, ...excludes]);
+    const { steps, decode } = countSteps(operands, excludes, mode, w);
+    checkBudget(budget, combineReads(decode, operands, excludes, mode, Infinity), label);
+    if (this.metricsOn) {
+      const distinct = /* @__PURE__ */ new Set();
+      for (const o of [...operands, ...excludes]) for (const k of o.keys) distinct.add(k);
+      this.metrics.onEvent({
+        kind: "intersect",
+        op,
+        operands: segs.length + excludes.length,
+        fetchedChunks: decode.length,
+        skippedChunks: distinct.size - decode.length
+      });
+    }
+    const everyKey = mode === "all" && segs.length > 1 && excludeSegs.length === 0;
+    const run = {
+      segs,
+      excludeSegs,
+      mode,
+      op,
+      limit,
+      budget,
+      w,
+      plan: this.openCombine(operands, excludes, mode, decode, limit),
+      looks: this.looks(everyKey ? Infinity : limit, epoch),
+      spent: 0,
+      steps,
+      at: 0,
+      guard: options?.guard,
+      ...everyKey && options?.guard !== void 0 ? { guardEvery: { since: 0 } } : {}
+    };
+    try {
+      return await this.runCount(run);
+    } finally {
+      this.closeCombine(run.plan);
+    }
+  }
+  /** Take every step of `run`: the index's figure for one, the size of the next decoded chunk for another. */
+  async runCount(run) {
+    let total = 0;
+    let last = -1;
+    while (run.at < run.steps.length) {
+      run.looks.left -= 1;
+      if (run.guardEvery !== void 0) this.guardAtCadence(run);
+      if (run.plan.moves.moved || this.lookDue(run.looks)) {
+        await this.countLook(run, last);
+        if (run.at >= run.steps.length) break;
+      }
+      const step = run.steps[run.at++];
+      last = step.key;
+      if (step.n >= 0) {
+        total += step.n;
+        continue;
+      }
+      const slot = await run.plan.window.next();
+      const chunk = slot?.result;
+      if (chunk === null || chunk === void 0 || chunk.isEmpty) continue;
+      total += run.w !== null && isEdge(step.key, run.w) ? cutToWindow(this.codec, chunk, step.key, run.w).size : chunk.size;
+    }
+    return total;
+  }
+  /** Run the guard every `limit` keys when the version looks are off (an AND of two or more includes). */
+  guardAtCadence(run) {
+    const cadence = run.guardEvery;
+    if (cadence.since >= run.limit) {
+      cadence.since = 0;
+      run.guard();
+    }
+    cadence.since += 1;
+  }
+  /**
+   * Look up each pinned operand's generation object, as a pinned read finds it: one footer read per pinned operand, and
+   * the pin's `NotFoundError` when the object is gone or is another. An operand that is not pinned costs nothing.
+   */
+  async verifyPinned(operands) {
+    const verify = this.storage.verifyPinned;
+    if (verify === void 0) return;
+    await boundedAll(operands, OPERANDS_AT_ONCE, (o) => verify.call(this.storage, o.seg));
+  }
+  /** Look at every operand's version, as {@link nextSlotAfterLook} does, and plan the keys above `last` again on a move. */
+  async countLook(run, last) {
+    const plan = run.plan;
+    plan.moves.moved = false;
+    this.looked(run.looks);
+    run.guard?.();
+    const all = [...plan.operands, ...plan.excludes];
+    await this.verifyPinned(all);
+    const now = await boundedAll(all, OPERANDS_AT_ONCE, (o) => this.cacheVersion(o.seg));
+    if (now.every((version, i) => version === all[i].gen)) return;
+    this.closeCombine(plan);
+    const spent = run.spent + combineReads(plan.keys, plan.operands, plan.excludes, run.mode, last);
+    const [operands, excludes] = await this.countOperands(
+      run.segs,
+      run.excludeSegs,
+      run.mode,
+      run.w,
+      last
+    );
+    const { steps, decode } = countSteps(operands, excludes, run.mode, run.w);
+    checkBudget(
+      run.budget,
+      spent + combineReads(decode, operands, excludes, run.mode, Infinity),
+      `${run.op}Count`
+    );
+    run.plan = this.openCombine(operands, excludes, run.mode, decode, run.limit);
+    run.spent = spent;
+    run.steps = steps;
+    run.at = 0;
+  }
+  /**
+   * {@link combineOperands} for a count: each include also carries the per-chunk counts of the generation its keys were
+   * listed from. The counts are asked for after the keys, and the two must name the same keys, or the operand is listed
+   * again (a move between the two reads), and refused if a source keeps disagreeing with itself. A source with no
+   * per-chunk counts gives none, and every key of that operand is decoded.
+   */
+  async countOperands(segs, excludeSegs, mode, w, after) {
+    const wantCounts = !(mode === "all" && segs.length > 1);
+    const extract = async (seg, withCounts) => {
+      for (let attempt = 0; attempt < COUNT_RELIST_ATTEMPTS; attempt++) {
+        const { listed: listed2, gen, epoch } = await this.listKeys(seg);
+        const cards = withCounts ? await this.chunkCounts(seg, listed2) : void 0;
+        if (cards === "moved") continue;
+        const keys = after < 0 && w === null ? listed2 : keysAbove(listed2, w, after);
+        return { seg, keys: new Set(keys), chunkless: listed2.length === 0, gen, epoch, cards };
+      }
+      throw new IntegrityError("a segment's index and its chunk keys name different chunks");
+    };
+    const all = await boundedAll(
+      [
+        ...segs.map((s) => [s, wantCounts]),
+        ...excludeSegs.map((s) => [s, false])
+      ],
+      OPERANDS_AT_ONCE,
+      ([seg, withCounts]) => extract(seg, withCounts)
+    );
+    return [all.slice(0, segs.length), all.slice(segs.length)];
+  }
+  /**
+   * The per-chunk counts of `seg`, checked as untrusted tier data; `undefined` when the source reports none, and `'moved'`
+   * when they name other keys than `listed`, which the segment's generation changing between the two reads explains.
+   */
+  async chunkCounts(seg, listed2) {
+    const counts = this.storage.cardinalities ? await this.storage.cardinalities(seg) : null;
+    if (counts === null) return void 0;
+    if (counts.size !== listed2.length) return "moved";
+    for (const key of listed2) {
+      const n = counts.get(key);
+      if (n === void 0) return "moved";
+      if (n !== 0) assertChunkCardinalityInRange(n);
+    }
+    return counts;
+  }
   /**
    * The AND (or OR) of one chunk key across all operands, minus the excludes that hold it, or `null` if empty.
    * Operand chunks are fetched **in parallel** (the spec's parallel byte-range reads).
@@ -2635,8 +2852,39 @@ function checkedFooter(tail, size) {
   if (crc32c(footer.subarray(0, FOOTER_CRC_COVERAGE)) !== storedFooterCrc) {
     throw crbmIntegrity(".crbm footer CRC mismatch");
   }
+  if (footer[FOOTER.versionMajor] === VERSION_MAJOR) checkFooterFields(footer, fview, size);
   return { footer, fview, storedFooterCrc };
 }
+function checkPreamble(tail, versionMajor, versionMinor) {
+  if (!magicMatches(tail, 0) || tail[4] !== versionMajor || tail[5] !== versionMinor) {
+    throw crbmIntegrity(".crbm preamble magic/version mismatch with footer");
+  }
+  if (tail[6] !== 0 || tail[7] !== 0) {
+    throw crbmIntegrity(".crbm preamble reserved bytes are not zero");
+  }
+}
+function allZero(bytes, from, to) {
+  for (let i = from; i < to; i++) if (bytes[i] !== 0) return false;
+  return true;
+}
+function checkFooterFields(footer, fview, size) {
+  if (fview.getUint16(FOOTER.reserved2, true) !== 0) {
+    throw crbmIntegrity(".crbm footer reserved2 is not zero");
+  }
+  if (!allZero(footer, FOOTER.keyId, FOOTER.chunkCount)) {
+    throw crbmIntegrity(".crbm footer key_id is not zero");
+  }
+  if ((fview.getUint32(FOOTER.flags, true) & FLAG_ENCRYPTED) === 0 && !allZero(footer, FOOTER.indexTag, FOOTER.indexTag + AEAD_TAG_BYTES)) {
+    throw crbmIntegrity(".crbm cleartext footer index_tag is not zero");
+  }
+  const indexOffset = readU64(fview, FOOTER.indexOffset, "index_offset");
+  const indexLength = readU64(fview, FOOTER.indexLength, "index_length");
+  if (indexOffset + indexLength !== size - FOOTER_BYTES) {
+    throw crbmIntegrity(
+      `.crbm index region [${indexOffset}, +${indexLength}) does not end where the footer begins (${size - FOOTER_BYTES})`
+    );
+  }
+}
 async function readFooter(blob) {
   const { bytes: tail, size } = await blob.getTail(FOOTER_BYTES);
   const { fview, storedFooterCrc } = checkedFooter(tail, size);
@@ -2806,7 +3054,7 @@ var CrbmReader = class _CrbmReader {
     }
     const versionMinor = footer[FOOTER.versionMinor];
     const hasExtension = (flags & FLAG_EXTENSION) !== 0;
-    if (indexOffset < PAYLOAD_START || indexOffset + indexLength > size - FOOTER_BYTES) {
+    if (indexOffset < PAYLOAD_START) {
       throw crbmIntegrity(`.crbm index region [${indexOffset}, +${indexLength}) out of bounds`);
     }
     if (indexLength > maxIndexBytes) {
@@ -2814,9 +3062,7 @@ var CrbmReader = class _CrbmReader {
     }
     const tailCoversFrom = size - tail.length;
     if (tailCoversFrom === 0) {
-      if (!magicMatches(tail, 0) || tail[4] !== versionMajor || tail[5] !== versionMinor) {
-        throw crbmIntegrity(".crbm preamble magic/version mismatch with footer");
-      }
+      checkPreamble(tail, versionMajor, versionMinor);
     }
     const lowest = hasExtension ? Math.max(PAYLOAD_START, indexOffset - EXT_TRAILER_BYTES - MAX_EXT_BYTES) : indexOffset;
     let region;
@@ -3301,6 +3547,8 @@ function parseIndex(indexBytes, payloadEnd, maxPayloadBytes, minPayloadBytes = 1
     if (card < 1 || card > MAX_CHUNK_CARDINALITY) {
       throw crbmIntegrity(`.crbm index entry ${i} has a cardinality ${card} invalid`);
     }
+    if (offDelta !== 0)
+      throw crbmIntegrity(`.crbm index entry ${i} leaves a gap before its payload`);
     if (offset + len > payloadEnd) {
       throw crbmIntegrity(`.crbm index entry ${i} has a payload out of bounds`);
     }
@@ -3314,6 +3562,11 @@ function parseIndex(indexBytes, payloadEnd, maxPayloadBytes, minPayloadBytes = 1
     prevKey = chunkKey;
     prevEnd = offset + len;
   }
+  if (prevEnd !== payloadEnd) {
+    throw crbmIntegrity(
+      `.crbm payloads end at ${prevEnd}, not at the end of the payload region ${payloadEnd}`
+    );
+  }
   if (count === capacity) {
     return { keys, cardinalityMinusOne, lengths, crcs, offsets, cardinalitySum };
   }
@@ -3601,6 +3854,9 @@ var notThePinned = (ref, generation) => new NotFoundError(
 var goneUnder = (ref, generation) => new NotFoundError(
   `segment "${ref.segment}" generation ${generation} can no longer be read: its registry row is gone or destroyed`
 );
+var pinGone = (ref, generation) => new NotFoundError(
+  `segment "${ref.segment}" generation ${generation}, which this handle pinned, can no longer be read: its registry row is gone or destroyed`
+);
 function genKeyOf(ref, target) {
   return { namespace: ref.namespace, segment: ref.segment, generation: target.generation };
 }
@@ -3816,6 +4072,10 @@ var CrbmStorageChunkSource = class {
       maxBytes: (maxOpenIndexBytes ?? DEFAULT_MAX_OPEN_INDEX_BYTES) / RESOLUTION_BYTES_DIVISOR,
       clock: { now: () => 0 }
     }) : void 0;
+    this.pinRows = this.timedRefresh ? new BoundedLru({
+      maxEntries: maxOpenSegments ?? DEFAULT_MAX_OPEN_SEGMENTS,
+      clock: { now: () => 0 }
+    }) : void 0;
     this.distrusted = new BoundedLru({
       maxEntries: maxOpenSegments ?? DEFAULT_MAX_OPEN_SEGMENTS,
       clock: { now: () => 0 }
@@ -3870,6 +4130,8 @@ var CrbmStorageChunkSource = class {
    * read. One forgotten before it ends, by {@link invalidate} or a pin, keeps nothing it finds.
    */
   checking = /* @__PURE__ */ new Map();
+  /** When each footer read in {@link checking} was sent. */
+  footerSentAt = /* @__PURE__ */ new WeakMap();
   /**
    * How many times {@link invalidate} has run, so a read that waited can tell whether the store was told something
    * meanwhile. An eviction from the reader cache is not an invalidation, and what a read found stands through one. It
@@ -3912,6 +4174,13 @@ var CrbmStorageChunkSource = class {
    * lapse, so it is decided once.
    */
   timedRefresh;
+  /**
+   * The row reads a pinned segment's rechecks share, by segment: one `registry.get` per `cache.genTtlMs` serves every pin,
+   * handle and combine of the segment in this store. Only a source with a timed refresh keeps any.
+   */
+  pinRows;
+  /** Each pin's last check, by the record the handle holds, so a handle that is let go takes its record with it. */
+  pinChecks = /* @__PURE__ */ new WeakMap();
   /**
    * The keys of the segments this source reads, kept rather than encoded again: a read asks for its segment's snapshot
    * once per operand, and a stream before every cached chunk it serves, and encoding the names cost about a
@@ -4125,6 +4394,7 @@ var CrbmStorageChunkSource = class {
     this.invalidated.invalidate(key);
     this.snapshots.delete(key);
     this.resolutions?.delete(key);
+    this.pinRows?.delete(key);
     const pinnedPrefix = `${key}@`;
     this.distrusted.deleteWhere((k) => k.startsWith(pinnedPrefix));
     this.snapshots.deleteWhere((k) => k.startsWith(pinnedPrefix));
@@ -4235,6 +4505,7 @@ var CrbmStorageChunkSource = class {
     let installed;
     let pinKey;
     let memoised = false;
+    const checkedAtMs = this.now();
     if (this.registry !== void 0) {
       const record = await this.registry.get(ref);
       if (record === null || record.status === "destroyed")
@@ -4280,9 +4551,10 @@ var CrbmStorageChunkSource = class {
       this.replacedPins.delete(held);
       this.checking.delete(held);
     }
-    return { generation, version, fingerprint };
+    return { generation, version, fingerprint, checkedAtMs };
   }
   async pinOnce(ref, lease) {
+    const checkedAtMs = this.now();
     const live = await this.resolveLive(ref);
     if (live === null) return null;
     if (lease !== void 0 && live.row !== void 0) {
@@ -4339,7 +4611,7 @@ var CrbmStorageChunkSource = class {
       this.replacedPins.delete(held);
       this.checking.delete(held);
     }
-    return { generation: target.generation, version, fingerprint: reader.fingerprint };
+    return { generation: target.generation, version, fingerprint: reader.fingerprint, checkedAtMs };
   }
   /**
    * Where a pinned reader of one object is memoised. With a registry that is its version, which names the object:
@@ -4375,7 +4647,7 @@ var CrbmStorageChunkSource = class {
    * crypto-shred must not keep unwrapping a DEK whose wrapping the shred removed; a destroyed segment resolves no
    * generation
    * for anyone, and a pin's read of one fails. That holds from the pin's next open: a reader already open keeps
-   * the key it unwrapped until it is evicted or invalidated.
+   * the key it unwrapped until it is evicted, invalidated, or its next check ({@link recheckPin}) finds the pin over.
    *
    * **And the object is checked**, when the caller says which one it pinned. A generation number is not an
    * identity (invariant 1): once a name is purged and loaded again, its new segment starts again at generation 0,
@@ -4413,9 +4685,7 @@ var CrbmStorageChunkSource = class {
     }
     if (reader === null) {
       if (version === void 0) return null;
-      throw new NotFoundError(
-        `segment "${ref.segment}" generation ${generation}, which this handle pinned, can no longer be read: its registry row is gone or destroyed`
-      );
+      throw pinGone(ref, generation);
     }
     if (fingerprint !== void 0 && reader.fingerprint !== fingerprint) {
       if (this.invalidations === epoch)
@@ -4454,6 +4724,113 @@ var CrbmStorageChunkSource = class {
       throw err;
     }
   }
+  /**
+   * Whether a pin's segment is due a look at its row: the pin was not checked within `cache.genTtlMs` (counted by
+   * `Clock.now()` on access, no timer), the segment has been invalidated since, a check is under way, or the pin has
+   * ended. A pin counts as checked from the instant its own row read was sent ({@link startPinChecks}), so one left
+   * idle past `cache.genTtlMs` is checked at its first read; one with no record is due. Always `false` without a timed
+   * refresh (no registry, no clock, or `cache.genTtlMs: 0`), where nothing bounds a pin. A compare and no await
+   * otherwise, which is all a pinned read pays between checks.
+   */
+  pinDue(ref, pin) {
+    if (!this.timedRefresh) return false;
+    const check = this.pinChecks.get(pin);
+    return check === void 0 || check.check !== void 0 || check.ended !== void 0 || this.now() - check.at >= this.currentGenTtlMs || this.invalidated.invalidatedSince(this.keyOf(ref), check.since);
+  }
+  /** Start a new pin's checks from `checkedAtMs`, when the row read that verified it was sent. */
+  startPinChecks(pin, checkedAtMs) {
+    if (this.timedRefresh)
+      this.pinChecks.set(pin, { at: checkedAtMs, since: this.invalidated.epoch });
+  }
+  /**
+   * Settle a pin whose check is due: throw its `NotFoundError` when its segment has been destroyed or is gone, is
+   * another incarnation, or holds another object under the pin's generation; return when it is still the pin's. One row
+   * read per interval serves every pin of the segment ({@link pinRows}), and it decides alone for a row that is gone or
+   * destroyed, a new incarnation, and a ledger that names the generation (its checksum is the pin's or not). A
+   * generation the ledger does not name, or a row with no usable ledger, is not a verdict: the object's footer is read
+   * once ({@link throwIfReplaced}, strict: a footer it cannot read fails the read). The pin counts as checked from
+   * when the row read its verdict came from was sent, never from when the check began, so a row read shared from
+   * earlier does not make a pin look fresher than it is. Every invalidation of the segment in this store makes the
+   * next check read the row afresh, beside the one per interval. A transient fault keeps serving and asks again after {@link REFRESH_RETRY_MS}; any
+   * other fault fails this read and is not remembered. A pin that has ended drops its reader, and so the key it
+   * unwrapped, and fails every later read at once until the segment is invalidated.
+   */
+  recheckPin(ref, generation, pin) {
+    const prior = this.pinChecks.get(pin);
+    if (prior?.check !== void 0) return prior.check;
+    const segment = this.keyOf(ref);
+    if (prior?.ended !== void 0 && !this.invalidated.invalidatedSince(segment, prior.since))
+      return Promise.reject(
+        prior.ended === "gone" ? pinGone(ref, generation) : notThePinned(ref, generation)
+      );
+    const next = { at: this.now(), since: this.invalidated.epoch };
+    this.pinChecks.set(pin, next);
+    next.check = this.settlePin(ref, generation, pin, next, segment).finally(() => {
+      next.check = void 0;
+    });
+    return next.check;
+  }
+  async settlePin(ref, generation, pin, next, segment) {
+    let ended;
+    try {
+      const read = this.pinRow(ref, segment);
+      const facts = await read.facts;
+      next.at = read.sentAtMs;
+      const incarnation = incarnationOf(pin.version.slice(pin.version.indexOf(":") + 1));
+      const named = facts.ledger?.find((e) => e.generation === generation);
+      if (facts.ended || pin.version.includes(":") && incarnation !== void 0 && facts.incarnation !== void 0 && incarnation !== facts.incarnation) {
+        ended = "gone";
+      } else if (named === void 0) {
+        try {
+          const footerAt = await this.throwIfReplaced(
+            ref,
+            generation,
+            pin.version,
+            pin.fingerprint,
+            true
+          );
+          next.at = Math.min(next.at, footerAt);
+        } catch (err) {
+          if (!isNotFoundError(err)) throw err;
+          ended = "replaced";
+        }
+      } else if (named.footerCrc !== fingerprintParts(pin.fingerprint)?.footerCrc) {
+        ended = "replaced";
+      }
+    } catch (err) {
+      if (isTransientError(err)) {
+        next.at = this.now() - (this.currentGenTtlMs - Math.min(this.currentGenTtlMs, REFRESH_RETRY_MS));
+        return;
+      }
+      next.at = Number.NEGATIVE_INFINITY;
+      throw err;
+    }
+    if (ended === void 0) return;
+    if (!this.invalidated.invalidatedSince(segment, next.since)) next.ended = ended;
+    if (ended === "replaced")
+      this.replacedPins.set(this.heldKey(ref, pin.version, pin.fingerprint), true);
+    this.snapshots.delete(this.pinnedKey(ref, pin.version, pin.fingerprint));
+    throw ended === "gone" ? pinGone(ref, generation) : notThePinned(ref, generation);
+  }
+  /** The segment's row read of the last `cache.genTtlMs`, shared; sent now when there is none. */
+  pinRow(ref, segment) {
+    const now = this.now();
+    const held = this.pinRows.peek(segment);
+    if (held !== void 0 && now - held.sentAtMs < this.currentGenTtlMs) return held;
+    const sent = {
+      sentAtMs: now,
+      facts: this.registry.get(ref).then((record) => ({
+        ended: record === null || record.status === "destroyed",
+        incarnation: record === null ? void 0 : incarnationOf(record.token),
+        ledger: usableKnownGens(record)
+      }))
+    };
+    this.pinRows.set(segment, sent);
+    sent.facts.catch(() => {
+      if (this.pinRows.peek(segment) === sent) this.pinRows.delete(segment);
+    });
+    return sent;
+  }
   /**
    * Throws the pin's NotFoundError if the object under `generation`'s key is no longer the one the pin holds. Its
    * footer says, read with no key and no row ({@link CrbmReader.sameObject}), so an object written under a key this
@@ -4461,9 +4838,10 @@ var CrbmStorageChunkSource = class {
    * ({@link replacedPins}), and a check under way is shared by the reads that ask at once; neither "gone" nor "the
    * same" is kept, since either can change. A transient fault is rethrown, for the store's retries to see for what it
    * is. A footer that cannot be read otherwise says nothing about which object is there, so this returns, and the
-   * caller's own error stands.
+   * caller's own error stands; a caller with no error of its own passes `strict`, and that fault is raised. Returns
+   * when the footer read that answered was sent (`Infinity` when none did).
    */
-  async throwIfReplaced(ref, generation, version, fingerprint) {
+  async throwIfReplaced(ref, generation, version, fingerprint, strict = false) {
     const held = this.heldKey(ref, version, fingerprint);
     if (this.replacedPins.get(held) !== void 0) throw notThePinned(ref, generation);
     let check = this.checking.get(held);
@@ -4485,16 +4863,27 @@ var CrbmStorageChunkSource = class {
         }
       );
       this.checking.set(held, started);
+      this.footerSentAt.set(started, this.now());
       check = started;
     }
     let replaced;
     try {
       replaced = await check;
     } catch (err) {
-      if (isTransientError(err)) throw err;
-      return;
+      if (strict || isTransientError(err)) throw err;
+      return Number.POSITIVE_INFINITY;
     }
     if (replaced) throw notThePinned(ref, generation);
+    return this.footerSentAt.get(check) ?? Number.NEGATIVE_INFINITY;
+  }
+  /**
+   * Throws the pin's `NotFoundError` when the object under `generation`'s key is no longer the one `held` names: one
+   * footer read, shared with a check already under way for the same pin. It fails closed: a footer that cannot be read,
+   * or an object that is not a generation object of this store, raises its own fault rather than passing.
+   */
+  async verifyHeld(ref, generation, held) {
+    validateUserRef(ref, "read", PORT_KEYS);
+    await this.throwIfReplaced(ref, generation, held.version, held.fingerprint, true);
   }
   /** Chunk keys of a specific generation — the pinned shape read. `held` as for {@link getChunkAt}. */
   async listChunkKeysAt(ref, generation, held) {
@@ -4848,7 +5237,9 @@ var CrbmStorageChunkSource = class {
     } catch (err) {
       if (held === void 0) throw err;
       if (!(isIntegrityError(err) || isValidationError(err))) throw err;
-      const check = () => this.throwIfReplaced(ref, generation, held.version, held.fingerprint);
+      const check = async () => {
+        await this.throwIfReplaced(ref, generation, held.version, held.fingerprint);
+      };
       await viaRetry(retry, check);
       throw err;
     }
@@ -5087,10 +5478,21 @@ var PinnedStorageChunkSource = class {
   pinFor(ref) {
     return this.pins.get(segmentKey(ref));
   }
+  /**
+   * The pin's recheck when it is due, else `undefined`: a compare and no await between checks. A pinned read waits for
+   * it before it touches the reader or the chunk cache, and fails with its `NotFoundError` once the segment is
+   * destroyed or the pin's generation erased ({@link CrbmStorageChunkSource.recheckPin}).
+   */
+  due(ref, generation, pin) {
+    return this.inner.pinDue(ref, pin) ? this.inner.recheckPin(ref, generation, pin) : void 0;
+  }
   getChunk(ref) {
     const pin = this.pinFor(ref);
     if (pin === void 0) return this.inner.getChunk(ref);
-    return pin.generation === null ? Promise.resolve(null) : this.inner.getChunkAt(ref, pin.generation, heldBy(pin));
+    if (pin.generation === null) return Promise.resolve(null);
+    const generation = pin.generation;
+    const due = this.due(ref, generation, pin);
+    return due === void 0 ? this.inner.getChunkAt(ref, generation, heldBy(pin)) : due.then(() => this.inner.getChunkAt(ref, generation, heldBy(pin)));
   }
   /**
    * A pinned segment's chunks come from the pinned generation alone, under the version a pinned read keys by
@@ -5111,7 +5513,10 @@ var PinnedStorageChunkSource = class {
       this.inner.getChunksAt(ref, pin.generation, keys, heldBy(pin), options)
     );
     try {
-      while (await pull.advance()) yield pull.take((chunk) => ({ ...chunk, version }));
+      while (await pull.advance()) {
+        if (this.inner.pinDue(ref, pin)) await this.inner.recheckPin(ref, pin.generation, pin);
+        yield pull.take((chunk) => ({ ...chunk, version }));
+      }
     } finally {
       await pull.close();
     }
@@ -5119,27 +5524,42 @@ var PinnedStorageChunkSource = class {
   listChunkKeys(ref) {
     const pin = this.pinFor(ref);
     if (pin === void 0) return this.inner.listChunkKeys(ref);
-    return pin.generation === null ? Promise.resolve([]) : this.inner.listChunkKeysAt(ref, pin.generation, heldBy(pin));
+    if (pin.generation === null) return Promise.resolve([]);
+    const generation = pin.generation;
+    const due = this.due(ref, generation, pin);
+    return due === void 0 ? this.inner.listChunkKeysAt(ref, generation, heldBy(pin)) : due.then(() => this.inner.listChunkKeysAt(ref, generation, heldBy(pin)));
   }
   sizeOf(ref) {
     const pin = this.pinFor(ref);
     if (pin === void 0) return this.inner.sizeOf(ref);
-    return pin.generation === null ? Promise.resolve(null) : this.inner.sizeOfAt(ref, pin.generation, heldBy(pin));
+    if (pin.generation === null) return Promise.resolve(null);
+    const generation = pin.generation;
+    const due = this.due(ref, generation, pin);
+    return due === void 0 ? this.inner.sizeOfAt(ref, generation, heldBy(pin)) : due.then(() => this.inner.sizeOfAt(ref, generation, heldBy(pin)));
   }
   cardinalities(ref) {
     const pin = this.pinFor(ref);
     if (pin === void 0) return this.inner.cardinalities(ref);
-    return pin.generation === null ? Promise.resolve(null) : this.inner.cardinalitiesAt(ref, pin.generation, heldBy(pin));
+    if (pin.generation === null) return Promise.resolve(null);
+    const generation = pin.generation;
+    const due = this.due(ref, generation, pin);
+    return due === void 0 ? this.inner.cardinalitiesAt(ref, generation, heldBy(pin)) : due.then(() => this.inner.cardinalitiesAt(ref, generation, heldBy(pin)));
   }
   summary(ref) {
     const pin = this.pinFor(ref);
     if (pin === void 0) return this.inner.summary(ref);
-    return pin.generation === null ? Promise.resolve(null) : this.inner.summaryAt(ref, pin.generation, heldBy(pin));
+    if (pin.generation === null) return Promise.resolve(null);
+    const generation = pin.generation;
+    const due = this.due(ref, generation, pin);
+    return due === void 0 ? this.inner.summaryAt(ref, generation, heldBy(pin)) : due.then(() => this.inner.summaryAt(ref, generation, heldBy(pin)));
   }
   stat(ref) {
     const pin = this.pinFor(ref);
     if (pin === void 0) return this.inner.stat(ref);
-    return pin.generation === null ? Promise.resolve(null) : this.inner.statAt(ref, pin.generation, heldBy(pin));
+    if (pin.generation === null) return Promise.resolve(null);
+    const generation = pin.generation;
+    const due = this.due(ref, generation, pin);
+    return due === void 0 ? this.inner.statAt(ref, generation, heldBy(pin)) : due.then(() => this.inner.statAt(ref, generation, heldBy(pin)));
   }
   currentGeneration(ref) {
     const pin = this.pinFor(ref);
@@ -5166,11 +5586,21 @@ var PinnedStorageChunkSource = class {
     const pin = this.pinFor(ref);
     if (pin === void 0) return this.inner.currentVersion(ref);
     if (pin.version === null) return Promise.resolve(null);
-    return Promise.resolve(`pin ${pin.version}#${pin.fingerprint}`);
+    const version = `pin ${pin.version}#${pin.fingerprint}`;
+    const due = this.due(ref, pin.generation, pin);
+    return due === void 0 ? Promise.resolve(version) : due.then(() => version);
   }
   exists(ref) {
     return this.inner.exists(ref);
   }
+  /** Whether the object this segment's pin holds is still there: see {@link HeldObjectLookup.verifyPinned}. */
+  verifyPinned(ref) {
+    const pin = this.pinFor(ref);
+    const held = pin === void 0 ? void 0 : heldBy(pin);
+    if (pin === void 0 || held === void 0 || pin.generation === null)
+      return Promise.resolve();
+    return this.inner.verifyHeld(ref, pin.generation, held);
+  }
   invalidate(ref) {
     this.inner.invalidate(ref);
   }
@@ -6423,6 +6853,25 @@ async function rowDeleteSettled(registry, ref, expected, waits = {}) {
   }
 }
 
+// src/core/generation-floor.ts
+var STRAY_MARGIN = 1024;
+var MAX_REPORTED_STRAYS = 64;
+var NO_STRAYS = Object.freeze({
+  count: 0,
+  generations: Object.freeze([])
+});
+function floorOf(row) {
+  let floor = row?.currentGen ?? -1;
+  for (const e of row?.knownGens ?? []) if (e.generation > floor) floor = e.generation;
+  for (const e of row?.leases ?? []) if (e.generation > floor) floor = e.generation;
+  return floor;
+}
+function reportStrays(strays) {
+  if (strays.length === 0) return NO_STRAYS;
+  const generations = [...strays].sort((a, b) => a - b).slice(0, MAX_REPORTED_STRAYS);
+  return { count: strays.length, generations };
+}
+
 // src/core/generation-gc.ts
 function deleteGeneration(deps, ref, generation) {
   const key = { namespace: ref.namespace, segment: ref.segment, generation };
@@ -6481,15 +6930,23 @@ function tookEffectOverMissing(ref, published, missing) {
   return pointerOnDeletedError(ref, { kind: "load", published }, missing);
 }
 async function nextGeneration(ref, deps) {
-  return aboveEverything(ref, deps, await deps.registry.get(ref));
+  return (await aboveEverything(ref, deps, await deps.registry.get(ref))).generation;
 }
-async function aboveEverything(ref, deps, record, seen) {
+async function aboveEverything(ref, deps, record) {
+  const all = [];
+  for await (const key of deps.storage.list(ref)) all.push(key.generation);
+  const limit = floorOf(record) + STRAY_MARGIN;
+  const listed2 = all.filter((g) => g <= limit);
   let highest = record?.currentGen ?? -1;
-  for await (const key of deps.storage.list(ref)) {
-    seen?.push(key.generation);
-    if (key.generation > highest) highest = key.generation;
-  }
-  return numberAbove(highest);
+  for (const g of listed2) if (g > highest) highest = g;
+  const held = new Set(all);
+  let generation = numberAbove(highest);
+  while (held.has(generation)) generation = numberAbove(generation);
+  return {
+    generation,
+    listed: listed2,
+    strays: reportStrays(all.filter((g) => g > limit && g > generation))
+  };
 }
 function numberAbove(highest) {
   if (highest >= Number.MAX_SAFE_INTEGER) {
@@ -6502,10 +6959,9 @@ async function nextLoadGeneration(ref, deps, row) {
   try {
     await deps.storage.getTail({ namespace: ref.namespace, segment: ref.segment, generation }, 0);
   } catch (err) {
-    if (isNotFoundError(err)) return { generation, checked: true };
+    if (isNotFoundError(err)) return { generation, checked: true, strays: NO_STRAYS };
   }
-  const listed2 = [];
-  return { generation: await aboveEverything(ref, deps, row, listed2), checked: false, listed: listed2 };
+  return { ...await aboveEverything(ref, deps, row), checked: false };
 }
 var LIST_COLLECTION_CADENCE = 16;
 async function gcOrphanGenerations(ref, deps, options = {}) {
@@ -6812,6 +7268,13 @@ async function judgeLoad(ref, cardinality, deps, options = {}) {
 function sizeNeeded(guard, allowEmpty) {
   return guard?.minRetained !== void 0 || guard?.maxGrowth !== void 0 || allowEmpty !== true;
 }
+var WROTE_NOTHING = Object.freeze({
+  size: 0,
+  sha256: "",
+  chunkCount: 0,
+  cardinality: 0,
+  collected: Object.freeze([])
+});
 function lostNumberRace(err) {
   return isWriteConflictError(err) && !isSourceError(err);
 }
@@ -6926,7 +7389,7 @@ async function runLoad(ref, prepare, deps, options) {
     );
   } catch (err) {
     if (!lostNumberRace(err)) throw err;
-    const { generation: generation2 } = await numbering;
+    const { generation: generation2, strays: strays2 } = await numbering;
     audit.onEvent({
       kind: "segment.load-refused",
       segment: ref.segment,
@@ -6940,15 +7403,12 @@ async function runLoad(ref, prepare, deps, options) {
       generation: generation2,
       published: false,
       reason: "superseded",
-      size: 0,
-      sha256: "",
-      chunkCount: 0,
-      cardinality: 0,
+      ...WROTE_NOTHING,
       cardinalityBefore: before,
-      collected: []
+      strays: strays2
     };
   }
-  const { generation, checked, listed: listed2 } = await numbering;
+  const { generation, checked, listed: listed2, strays } = await numbering;
   const key = { namespace: ref.namespace, segment: ref.segment, generation };
   const reclaim = async () => {
     const watch = watchDeletes(deps, ref);
@@ -6991,7 +7451,8 @@ async function runLoad(ref, prepare, deps, options) {
       chunkCount: written.chunkCount,
       cardinality: written.cardinality,
       cardinalityBefore: before,
-      collected: []
+      collected: [],
+      strays
     };
   };
   const refusal = guardRefusal(written.cardinality, before, guard, options.allowEmpty);
@@ -7087,7 +7548,8 @@ async function runLoad(ref, prepare, deps, options) {
     chunkCount: written.chunkCount,
     cardinality: written.cardinality,
     cardinalityBefore: before,
-    collected
+    collected,
+    strays
   };
 }
 
@@ -12023,6 +12485,7 @@ var RetryingStorageChunkSource = class {
   invalidate;
   exists;
   currentVersion;
+  verifyPinned;
   constructor(inner, opts) {
     this.inner = inner;
     const r = toRetry(opts);
@@ -12068,6 +12531,10 @@ var RetryingStorageChunkSource = class {
     if (innerExists) {
       this.exists = (ref) => withRetry(() => innerExists.call(inner, ref), this.policy, this.deps);
     }
+    const innerVerify = inner.verifyPinned;
+    if (innerVerify) {
+      this.verifyPinned = (ref) => withRetry(() => innerVerify.call(inner, ref), this.policy, this.deps);
+    }
     const innerCurrentVersion = inner.currentVersion;
     if (innerCurrentVersion) {
       this.currentVersion = (ref) => withRetry(() => innerCurrentVersion.call(inner, ref), this.policy, this.deps);