@cloudbitmaps/core 0.15.0 → 0.17.0

package/dist/index.js

@@ -5,6 +5,12 @@ import {
   DEFAULT_NAMESPACE,
   IntegrityError,
   KeyUnavailableError,
+  LEASE_SKEW_MS,
+  LeaseExpiredError,
+  LeaseLimitError,
+  MAX_KEPT_GENERATIONS,
+  MAX_LEASES_PER_SEGMENT,
+  MAX_LEASE_MS,
   MAX_METADATA_BYTES,
   MAX_NAME_LENGTH,
   NotFoundError,
@@ -25,25 +31,35 @@ import {
   encodeNameForPath,
   encodedNameLength,
   entropyIsAvailable,
+  heldGenerations,
   incarnationOf,
   isCloudRoaringError,
   isIntegrityError,
+  isLeaseExpiredError,
+  isLeaseLimitError,
+  isLive,
   isNotFoundError,
   isReservedNamespace,
   isStorageBackend,
   isTransientError,
   isValidationError,
   isWriteConflictError,
+  leaseChurn,
   mapWithConcurrency,
   metadataBytes,
   metadataFromBytes,
   namespacePathPart,
   newIncarnationToken,
+  nextKept,
   nextRegistryToken,
+  onlyLeasesDiffer,
   parseRegistryEnvelope,
   recordFromNew,
+  releaseLease,
   sameIncarnation,
   serializeRegistryEnvelope,
+  takeLease,
+  usableKeptGens,
   validateChunkKeyOrder,
   validateChunkRef,
   validateNewRegistryRecord,
@@ -52,7 +68,7 @@ import {
   validateUserNamespace,
   validateUserRef,
   webCryptoEntropy
-} from "./chunk-B7IGS3W6.js";
+} from "./chunk-CV7GJO3B.js";
 
 // src/core/bit-route.ts
 var U32_MAX = 4294967295;
@@ -332,6 +348,8 @@ var CountingMetricsSink = class _CountingMetricsSink {
         op.totalMs += event.ms;
         break;
       }
+      case "advisory":
+        break;
       default: {
         const exhaustive = event;
         return exhaustive;
@@ -494,6 +512,8 @@ var SegmentEngine = class {
    * they deliver, as a read whose entry an invalidation dropped does not (streams hold no `openReads` entry).
    */
   openStreams = /* @__PURE__ */ new Set();
+  /** How many times {@link invalidate} has been called: a read compares it with the count it began under. */
+  invalidations = 0;
   constructor(deps) {
     this.storage = deps.storage;
     this.cache = deps.cache;
@@ -578,8 +598,15 @@ var SegmentEngine = class {
    * 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);
+  chunkSequence(seg, chunkKeys, gen, epoch) {
+    const streamed = this.openStreamed(
+      seg,
+      chunkKeys,
+      gen,
+      epoch,
+      DEFAULT_INTERSECT_CONCURRENCY,
+      1
+    );
     if (streamed !== void 0) {
       return {
         take: (chunkKey) => this.streamedChunk(streamed, chunkKey),
@@ -604,10 +631,11 @@ var SegmentEngine = class {
     return range === void 0 ? this.iterateAll(seg) : this.iterateRange(seg, range);
   }
   async *iterateAll(seg) {
+    const epoch = this.invalidations;
     const chunkKeys = await this.chunkKeys(seg);
     checkBudget(this.budget, chunkKeys.length, "iterate");
     const gen = await this.cacheVersion(seg);
-    const chunks = this.chunkSequence(seg, chunkKeys, gen);
+    const chunks = this.chunkSequence(seg, chunkKeys, gen, epoch);
     try {
       for (const chunkKey of chunkKeys) {
         const chunk = await chunks.take(chunkKey);
@@ -619,12 +647,13 @@ var SegmentEngine = class {
     }
   }
   async *iterateRange(seg, range) {
+    const epoch = this.invalidations;
     const w = windowOf(range) ?? WHOLE_ID_SPACE;
     if (w === "empty") return;
     const chunkKeys = 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);
+    const chunks = this.chunkSequence(seg, chunkKeys, gen, epoch);
     try {
       for (const chunkKey of chunkKeys) {
         const chunk = await chunks.take(chunkKey);
@@ -646,12 +675,13 @@ var SegmentEngine = class {
    * the caller's to keep.
    */
   async *iterateBatches(seg, range) {
+    const epoch = this.invalidations;
     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);
+    const chunks = this.chunkSequence(seg, chunkKeys, gen, epoch);
     try {
       for (const chunkKey of chunkKeys) {
         const chunk = await chunks.take(chunkKey);
@@ -663,6 +693,104 @@ var SegmentEngine = class {
       chunks.close();
     }
   }
+  /**
+   * The ids at 1-based ranks `n`, `2n`, `3n` … counted over the ids in `range`, ascending. The rank of each boundary
+   * is placed from the index's per-chunk counts, so only the chunks that hold a boundary are read, each once however
+   * many boundaries it holds, through the same coalesced stream, window and budget unit as {@link iterate}. A range with
+   * `after` inside a chunk reads that chunk too, to count the ids at or below `after`. A last partial window yields
+   * nothing.
+   *
+   * The counts place ids, and are trusted as `count()` trusts them: a chunk that is read must decode to the size its
+   * index says, or the read throws {@link IntegrityError} (invariant 5), but a chunk that is not read is not checked, so
+   * an index that lies consistently about one (on an unencrypted object, the sum still matches the footer's total,
+   * which opening the object checks before any boundary is placed) shifts the ranks after it. An encrypted object's
+   * index is authenticated and bound to the object, so a wrong count there needs the key. The index and the chunks must come from one
+   * generation (invariant 3): the caller reads through a source that holds one, a pinned one, and a source with no
+   * per-chunk counts is refused.
+   *
+   * Nothing is fetched when the chunks in range hold fewer than `n` ids. The budget is charged before the first fetch
+   * with an upper bound, the cut chunk plus one chunk per boundary the counts allow (capped by the chunks in range),
+   * which can exceed the chunks actually read. A range that cuts its first chunk reads it even when the ids above
+   * `after` turn out to be fewer than `n`, and one that cuts its last chunk may read it and yield nothing.
+   */
+  async *everyNth(seg, n, range) {
+    if (!Number.isSafeInteger(n) || n < 1) {
+      throw new ValidationError(`n must be a positive integer; got ${String(n)}`);
+    }
+    const epoch = this.invalidations;
+    const w = windowOf(range);
+    if (w === "empty") return;
+    const { loKey, loRem, hiKey, hiRem } = w ?? WHOLE_ID_SPACE;
+    if (this.storage.cardinalities === void 0) {
+      throw new UnsupportedError("everyNth needs a storage source that reports per-chunk counts");
+    }
+    const counts = await this.storage.cardinalities(seg);
+    if (counts === null) return;
+    const keys = keysWithin(
+      [...counts.keys()].sort((a, b) => a - b),
+      { loKey, loRem, hiKey, hiRem }
+    );
+    for (const k of keys) {
+      this.assertChunkKeyInRange(k);
+      const c = counts.get(k);
+      if (!Number.isInteger(c) || c < 1 || c > CHUNK_COUNT) {
+        throw new IntegrityError(`chunk cardinality from a tier is out of range: ${c}`);
+      }
+    }
+    const gen = await this.cacheVersion(seg);
+    const cutsFirst = loRem > 0 && keys[0] === loKey;
+    let upper = 0;
+    for (const k of keys) upper += counts.get(k);
+    if (upper < n) return;
+    const cut = cutsFirst ? 1 : 0;
+    checkBudget(this.budget, cut + Math.min(keys.length - cut, Math.floor(upper / n)), "everyNth");
+    let first;
+    let below = 0;
+    if (cutsFirst) {
+      first = this.chunkRemainders(
+        await this.storageChunk({ ...seg, chunkKey: loKey }, gen),
+        loKey,
+        counts
+      );
+      below = firstAbove(first, loRem - 1);
+    }
+    const hits = [];
+    let before = 0;
+    for (const key of keys) {
+      const skipped = key === loKey && cutsFirst ? below : 0;
+      const size = counts.get(key) - skipped;
+      const next = (Math.floor(before / n) + 1) * n;
+      if (next <= before + size) hits.push({ key, index: skipped + next - before - 1 });
+      before += size;
+    }
+    if (hits.length === 0) return;
+    const streamed = hits.filter((h) => !(cutsFirst && h.key === loKey)).map((h) => h.key);
+    const chunks = streamed.length > 0 ? this.chunkSequence(seg, streamed, gen, epoch) : void 0;
+    try {
+      for (const { key, index } of hits) {
+        const rem = cutsFirst && key === loKey && first !== void 0 ? first : this.chunkRemainders(await chunks.take(key), key, counts);
+        const base = key * CHUNK_COUNT;
+        for (let i = index; i < rem.length; i += n) {
+          const remainder = rem[i] & MAX_REMAINDER;
+          if (key === hiKey && remainder > hiRem) return;
+          yield base + remainder;
+        }
+      }
+    } finally {
+      chunks?.close();
+    }
+  }
+  /** A chunk's remainders ascending, once its size is confirmed against the index's count for it (invariant 5). */
+  chunkRemainders(chunk, chunkKey, counts) {
+    const expected = counts.get(chunkKey);
+    if (chunk === null || chunk.size !== expected) {
+      const got = chunk === null ? "no bytes" : `${chunk.size} ids`;
+      throw new IntegrityError(
+        `chunk ${chunkKey} holds ${got}, but the object's index says ${expected}`
+      );
+    }
+    return chunk.toUint32Array ? chunk.toUint32Array() : Uint32Array.from(chunk);
+  }
   /**
    * `segs[0] ∩ segs[1] ∩ …`, minus every id in `options.exclude` — streamed ascending.
    *
@@ -731,6 +859,26 @@ var SegmentEngine = class {
   andNotBatches(seg, excludes, options) {
     return this.combineBatches([seg], excludes, "all", "andNot", options);
   }
+  /**
+   * {@link intersect}, as the chunks the result is made of: `{ chunkKey, bitmap }` in ascending key order, each a
+   * non-empty bitmap of the chunk's 16-bit remainders, cut to the read's range. What a materialisation writes
+   * straight into its new generation, with no id built on the way.
+   *
+   * **Each bitmap belongs to the caller, who may change it:** it is the combine's own accumulator or a bitmap built
+   * for the range's edge, never a chunk the cache holds or another operand's. The reads, the budget, the metric and the
+   * errors are the id reads' own.
+   */
+  intersectChunks(segs, options) {
+    return this.combineChunks(segs, options?.exclude ?? [], "all", "intersect", options);
+  }
+  /** {@link union}, as chunks: see {@link intersectChunks}. */
+  unionChunks(segs, options) {
+    return this.combineChunks(segs, options?.exclude ?? [], "any", "union", options);
+  }
+  /** {@link andNot}, as chunks: see {@link intersectChunks}. */
+  andNotChunks(seg, excludes, options) {
+    return this.combineChunks([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
@@ -753,10 +901,11 @@ var SegmentEngine = class {
     const w = windowOf(options);
     if (w === "empty") return null;
     const extract = async (seg) => {
+      const epoch = this.invalidations;
       const all = await this.chunkKeys(seg);
       const gen = await this.cacheVersion(seg);
       const keys = w === null ? all : keysWithin(all, w);
-      return { seg, keys: new Set(keys), chunkless: all.length === 0, gen };
+      return { seg, keys: new Set(keys), chunkless: all.length === 0, gen, epoch };
     };
     const [operands, excludes] = await Promise.all([
       Promise.all(segs.map(extract)),
@@ -801,14 +950,15 @@ var SegmentEngine = class {
     const open4 = (o, wanted) => {
       o.streamed = this.openStreamed(
         o.seg,
-        common.filter(wanted),
+        wanted === void 0 ? common : common.filter(wanted),
         o.gen,
+        o.epoch,
         limit,
         COMBINE_RANGE_START
       );
-      if (o.streamed?.stream) streams.push(o.streamed);
+      if (o.streamed) streams.push(o.streamed);
     };
-    for (const o of operands) open4(o, mode === "all" ? () => true : (k) => o.keys.has(k));
+    for (const o of operands) open4(o, mode === "all" ? void 0 : (k) => o.keys.has(k));
     if (streamExcludes) for (const e of excludes) open4(e, (k) => e.keys.has(k));
     return {
       w,
@@ -853,6 +1003,28 @@ var SegmentEngine = class {
       for (const stream of plan.streams) this.closeStreamed(stream);
     }
   }
+  /** The chunk read: the plan every combine shares, then each key's result, cut to the range at its edges. */
+  async *combineChunks(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) continue;
+        const bitmap = w !== null && isEdge(slot.key, w) ? this.cutToWindow(slot.result, slot.key, w) : slot.result;
+        if (!bitmap.isEmpty) yield { chunkKey: slot.key, bitmap };
+      }
+    } finally {
+      for (const stream of plan.streams) this.closeStreamed(stream);
+    }
+  }
+  /** An edge chunk's bitmap cut to the window, as a new bitmap: the remainders `edgeIds` would yield. */
+  cutToWindow(chunk, chunkKey, w) {
+    const from = chunkKey === w.loKey ? w.loRem : 0;
+    const to = chunkKey === w.hiKey ? w.hiRem : MAX_REMAINDER;
+    const rem = chunk.toUint32Array ? chunk.toUint32Array() : Uint32Array.from(chunk);
+    return this.codec.fromValues(rem.subarray(firstAbove(rem, from - 1), firstAbove(rem, to)));
+  }
   /**
    * 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).
@@ -902,25 +1074,43 @@ var SegmentEngine = class {
     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.
+   * `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. Nothing is requested, and no cache lookup made, until
+   * the first chunk is asked for (see {@link StreamedChunks}).
    */
-  openStreamed(seg, keys, gen, concurrency, rampStart) {
+  openStreamed(seg, keys, gen, epoch, concurrency, rampStart) {
+    if (this.storage.getChunks === void 0 || gen === null || keys.length === 0) return void 0;
+    return {
+      seg,
+      gen,
+      epoch,
+      keys,
+      concurrency,
+      rampStart,
+      opened: false,
+      inStream: void 0,
+      stream: void 0,
+      invalidated: false
+    };
+  }
+  /**
+   * Open the stream of `streamed`, at its first uncached chunk `from`: over that chunk and the later keys the cache does
+   * not hold. Each later key is counted as a cache hit or miss here, so a key is counted once whichever way it is served.
+   */
+  startStream(streamed, from) {
+    const { seg, gen } = streamed;
     const getChunks = this.storage.getChunks;
-    if (getChunks === void 0 || gen === null || keys.length === 0) return void 0;
-    let wanted = keys;
-    let inStream;
+    let wanted = streamed.keys.slice(streamed.keys.indexOf(from));
     if (this.cache) {
-      const misses = [];
-      for (const chunkKey of keys) {
+      const misses = [from];
+      for (let i = 1; i < wanted.length; i++) {
+        const chunkKey = wanted[i];
         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 });
       }
+      if (misses.length < wanted.length) streamed.inStream = new Set(misses);
       wanted = misses;
-      if (misses.length < keys.length) inStream = new Set(misses);
     }
     const onRequest = this.metricsOn ? (request) => {
       this.metrics.onEvent({
@@ -931,27 +1121,36 @@ var SegmentEngine = class {
         ms: request.ms
       });
     } : void 0;
-    const stream = wanted.length === 0 ? void 0 : new ChunkStream(
+    streamed.stream = new ChunkStream(
       getChunks.call(this.storage, seg, wanted, {
-        concurrency,
-        ramp: rampStart,
+        concurrency: streamed.concurrency,
+        ramp: streamed.rampStart,
         ...onRequest === void 0 ? {} : { onRequest }
       })
     );
-    const streamed = { seg, gen, inStream, stream, invalidated: false };
-    if (stream) this.openStreams.add(streamed);
-    return streamed;
+    streamed.opened = true;
+    streamed.invalidated = this.storage.currentVersion === void 0 && this.invalidations !== streamed.epoch;
+    this.openStreams.add(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.
+   * The decoded chunk at `chunkKey` of a streamed read: from the cache while the stream is unopened and the cache holds
+   * it; else the next chunk of its stream, or, for a chunk the cache held when the stream 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)) {
+    if (!streamed.opened) {
+      const cache = this.cache;
+      if (cache) {
+        const hit = cache.get(this.chunkCacheKey({ ...streamed.seg, chunkKey }, streamed.gen));
+        if (this.metricsOn) this.metrics.onEvent({ kind: "cache", hit: hit !== void 0 });
+        if (hit) return Promise.resolve(hit);
+      }
+      this.startStream(streamed, chunkKey);
+    } else 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);
@@ -1074,6 +1273,7 @@ var SegmentEngine = class {
    */
   invalidate(ref) {
     const prefix = segmentPrefix(ref);
+    this.invalidations += 1;
     for (const streamed of this.openStreams) {
       if (segmentPrefix(streamed.seg) === prefix) streamed.invalidated = true;
     }
@@ -1360,63 +1560,121 @@ async function nextLoadGeneration(ref, deps, row) {
 }
 var LIST_COLLECTION_CADENCE = 16;
 async function gcOrphanGenerations(ref, deps, options = {}) {
+  return (await listingPass(ref, deps, { keep: options.keep })).deleted;
+}
+async function listingPass(ref, deps, options) {
   const keep = options.keep ?? 1;
+  const quiet = options.quiet === true;
   if (!Number.isInteger(keep) || keep < 0) {
     throw new ValidationError(`keep must be a non-negative integer; got ${String(keep)}`);
   }
   const record = await deps.registry.get(ref);
-  if (record === null) return [];
+  if (record === null) return { deleted: [], kept: [], complete: true };
   const current = record.currentGen;
   const seen = /* @__PURE__ */ new Set();
   for await (const key of deps.storage.list(ref)) seen.add(key.generation);
   const gens = [...seen];
   const after = await deps.registry.get(ref);
-  if (after === null)
+  if (after === null) {
+    if (quiet) return { deleted: [], kept: [], complete: false };
     throw new WriteConflictError(`registry row for segment ${ref.segment} was purged mid-pass`);
+  }
   if (record.status === "destroyed" && after.token !== record.token) {
+    if (quiet) return { deleted: [], kept: [], complete: false };
     throw new WriteConflictError(
       `segment ${ref.segment} changed incarnation while its generations were being listed`
     );
   }
   const cutoff = current === null || after.currentGen === null ? null : Math.min(current, after.currentGen);
-  const stillCollectable = async () => {
+  const named = record.status === "destroyed" ? void 0 : usableKeptGens(after);
+  const protect = options.protect === void 0 || named === void 0 ? void 0 : /* @__PURE__ */ new Set([...options.protect, ...named]);
+  const stillCollectable = async (generation) => {
     const still = await deps.registry.get(ref);
     if (still === null) {
+      if (quiet) return "stop";
       throw new WriteConflictError(`registry row for segment ${ref.segment} was purged mid-pass`);
     }
     const ok = record.status === "destroyed" ? still.token === after.token : cutoff === null || still.currentGen !== null && still.currentGen >= cutoff;
-    if (!ok) {
+    const now = protect === void 0 ? void 0 : usableKeptGens(still);
+    const unnamed = protect === void 0 || record.status === "destroyed" || now !== void 0 && !now.includes(generation);
+    if (!ok || !unnamed) {
+      if (quiet) return "stop";
       throw new WriteConflictError(
         `segment ${ref.segment} changed incarnation while its generations were being collected`
       );
     }
+    if (guard !== void 0 && heldGenerations(still, guard.now()).has(generation)) return "skip";
+    return "delete";
   };
-  const toDelete = record.status === "destroyed" ? gens.sort((a, b) => a - b) : cutoff === null ? (
+  const guard = record.status === "destroyed" ? void 0 : options.leases;
+  const held = guard === void 0 ? void 0 : heldGenerations(after, guard.now());
+  const below = record.status === "destroyed" || cutoff === null ? [] : gens.filter((g) => g < cutoff).sort((a, b) => b - a);
+  const candidates = record.status === "destroyed" ? gens.sort((a, b) => a - b) : cutoff === null ? (
     // No Storage pointer yet, so "below current" selects nothing and there is nothing safe to infer: an object
     // here is either a load about to publish or an orphan we cannot tell apart from it. Deleting would race
     // that publish into a dangling pointer. It is collected once a pointer exists.
     []
+  ) : protect !== void 0 ? (
+    // The row's list is the window: everything below the pointer it does not name is garbage.
+    below.filter((g) => !protect.has(g))
   ) : (
     // Delete generations below the cutoff, except the newest `keep` of them (the grace window).
-    gens.filter((g) => g < cutoff).sort((a, b) => b - a).slice(keep)
+    below.slice(keep)
   );
+  const leasedSpared = new Set(candidates.filter((g) => held?.has(g) === true));
+  const toDelete = candidates.filter((g) => !leasedSpared.has(g));
+  const done = [];
   for (const generation of toDelete) {
-    await stillCollectable();
+    const verdict = await stillCollectable(generation);
+    if (verdict === "stop") return { deleted: done, kept: [], complete: false };
+    if (verdict === "skip") {
+      leasedSpared.add(generation);
+      continue;
+    }
     await deps.storage.delete({ namespace: ref.namespace, segment: ref.segment, generation });
+    done.push(generation);
   }
-  return toDelete;
+  const deleted = new Set(done);
+  return {
+    deleted: done,
+    kept: below.filter((g) => !deleted.has(g) && !leasedSpared.has(g)).reverse(),
+    complete: true
+  };
 }
 async function collectAfterLoad(ref, deps, options) {
-  const { generation, keep, byName, proveCurrent } = options;
+  const { generation, keep, byName, currentGone, kept, proveCurrent, leases } = options;
   if (keep >= generation) return [];
+  const list = kept?.list;
+  if (list === void 0 || currentGone === true)
+    return reconcile(ref, deps, { keep, kept, leases });
   const periodic = generation % LIST_COLLECTION_CADENCE === 0;
-  if (byName && keep <= 1 && !periodic) {
-    if (keep === 1 && proveCurrent !== void 0 && !await objectIsThere(deps.storage, proveCurrent)) {
-      return gcOrphanGenerations(ref, deps, { keep });
+  if (byName && !periodic) {
+    if (keep >= 1 && proveCurrent !== void 0 && !await objectIsThere(deps.storage, proveCurrent)) {
+      return reconcile(ref, deps, { keep, kept, leases });
+    }
+    return deleteEvicted(ref, deps, { generation, evict: kept.evict, leases });
+  }
+  return (await listingPass(ref, deps, { keep, protect: list, quiet: true, leases })).deleted;
+}
+async function reconcile(ref, deps, options) {
+  const { keep, kept, leases } = options;
+  const {
+    deleted,
+    kept: present,
+    complete
+  } = await listingPass(ref, deps, { keep, quiet: true, leases });
+  const token = kept?.token;
+  if (complete && token !== void 0 && keep <= MAX_KEPT_GENERATIONS && !sameList(kept?.list, present)) {
+    try {
+      await deps.registry.compareAndSwap(ref, token, { keptGens: present });
+    } catch (err) {
+      if (!(err instanceof WriteConflictError)) throw err;
     }
-    return collectByName(ref, deps, { generation, keep });
   }
-  return gcOrphanGenerations(ref, deps, { keep });
+  return deleted;
+}
+function sameList(a, b) {
+  return a !== void 0 && a.length === b.length && a.every((g, i) => g === b[i]);
 }
 async function objectIsThere(storage, key) {
   try {
@@ -1426,21 +1684,20 @@ async function objectIsThere(storage, key) {
     return false;
   }
 }
-async function collectByName(ref, deps, options) {
-  const { generation, keep } = options;
-  if (!Number.isInteger(keep) || keep < 0 || keep > 1) {
-    throw new ValidationError(`collecting by name needs a keep of 0 or 1; got ${String(keep)}`);
+async function deleteEvicted(ref, deps, options) {
+  const deleted = [];
+  for (const generation of options.evict) {
+    const still = await deps.registry.get(ref);
+    if (still === null || still.currentGen === null || still.currentGen < options.generation) break;
+    const named = usableKeptGens(still);
+    if (named === void 0 || generation >= still.currentGen || named.includes(generation)) break;
+    if (options.leases !== void 0 && heldGenerations(still, options.leases.now()).has(generation)) {
+      continue;
+    }
+    await deps.storage.delete({ namespace: ref.namespace, segment: ref.segment, generation });
+    deleted.push(generation);
   }
-  const evicted = generation - keep - 1;
-  if (evicted < 0) return [];
-  const still = await deps.registry.get(ref);
-  if (still === null || still.currentGen === null || still.currentGen < generation) return [];
-  await deps.storage.delete({
-    namespace: ref.namespace,
-    segment: ref.segment,
-    generation: evicted
-  });
-  return [evicted];
+  return deleted;
 }
 
 // src/core/reader-defaults.ts
@@ -1491,7 +1748,7 @@ var HOURS_PER_MONTH = 730;
 var SECONDS_PER_MONTH = HOURS_PER_MONTH * 3600;
 var GIB = 1024 ** 3;
 var STORE_LOAD_PUT_CLASS = 1 + 1 / LIST_COLLECTION_CADENCE;
-var STORE_LOAD_POINTER_READS = 3 + 2 / LIST_COLLECTION_CADENCE;
+var STORE_LOAD_POINTER_READS = 2 + 2 / LIST_COLLECTION_CADENCE;
 var STORE_LOAD_EXISTENCE_CHECKS = 2 - 1 / LIST_COLLECTION_CADENCE;
 var RETENTION_SWEEP_REQUESTS = deepFreeze({
   conditionalDelete: {
@@ -1946,13 +2203,30 @@ async function runExport(reader, registry, sink, options = {}) {
   const segments = [];
   const failed = [];
   let totalIds = 0;
+  if (typeof reader?.segment !== "function") {
+    throw new ValidationError(
+      "runExport: the reader must have a segment(name, { namespace? }) method returning a handle with pin(), as a store's does"
+    );
+  }
+  let probed = false;
+  let unusable;
   const exportRef = async (ref) => {
     let writer;
     let count = 0;
     let bytes = 0;
     try {
       validateSegmentRef(ref);
-      const ids = reader.segment(ref.segment, { namespace: ref.namespace }).iterate();
+      const handle = reader.segment(ref.segment, { namespace: ref.namespace });
+      if (!probed) {
+        probed = true;
+        if (typeof handle?.pin !== "function") {
+          unusable = new ValidationError(
+            "runExport: the reader's segment(name, { namespace? }) must return a handle with a pin() method; a segment is exported at one pinned generation"
+          );
+          throw unusable;
+        }
+      }
+      const ids = (await handle.pin()).iterate();
       writer = await sink.open(ref, ext);
       if (format === "roaring") {
         const bm = requireCodec(options.codec, "runExport({ format: 'roaring' })").empty();
@@ -1983,6 +2257,7 @@ async function runExport(reader, registry, sink, options = {}) {
         }
       }
     } catch (err) {
+      if (err === unusable) throw err;
       if (writer !== void 0) {
         try {
           await writer.abort?.();
@@ -2108,6 +2383,10 @@ var MemoryRegistryDriver = class {
     this.rows.set(key, structuredClone(recordFromNew(ref, checked, this.now(), token)));
     return { token };
   }
+  /**
+   * A caller's `held` row (see `RegistryWriteOptions`) has no read to spare here: the token is compared with the stored row in the same step
+   * as the write, in memory, so a stale one fails exactly as a lost race does.
+   */
   async compareAndSwap(ref, expected, patch) {
     validateSegmentRef(ref);
     const checked = validateRegistryPatch(patch);
@@ -2463,6 +2742,10 @@ var LocalFsRegistryDriver = class {
       return { token };
     });
   }
+  /**
+   * A caller's `held` row (see `RegistryWriteOptions`) has no read to spare here: the row's file is read under its lock and its token compared
+   * there, a local read and no request, so a stale one fails exactly as a lost race does.
+   */
   async compareAndSwap(ref, expected, patch) {
     const checked = validateRegistryPatch(patch);
     const path = registryRowPath(this.root, ref);
@@ -3717,6 +4000,12 @@ var DecodedLoadInput = class {
   }
   bitmap;
 };
+var ChunkLoadInput = class {
+  constructor(chunks) {
+    this.chunks = chunks;
+  }
+  chunks;
+};
 function tagOf(value) {
   return Object.prototype.toString.call(value).slice(8, -1);
 }
@@ -3750,7 +4039,7 @@ function isShared(buffer) {
 }
 function overCap(what, length) {
   return new ValidationError(
-    `${what} is ${length} bytes, more than any canonical 32-bit bitmap serializes to (${MAX_SERIALIZED_LOAD_BYTES}). Call runOptimize() on the bitmap before serializing it.`
+    `${what} is ${length} bytes, more than any canonical 32-bit bitmap serializes to (${MAX_SERIALIZED_LOAD_BYTES}). If it was serialized from a bitmap, call runOptimize() on the bitmap first.`
   );
 }
 function prepareLoadInput(input, codec) {
@@ -3768,7 +4057,9 @@ function prepareLoadInput(input, codec) {
   if (Symbol.iterator in input || Symbol.asyncIterator in input) return input;
   const keys = Object.keys(input);
   if (keys.length === 1 && keys[0] === "serialized") {
-    return decode(input.serialized, "{ serialized }", codec);
+    return new DecodedLoadInput(
+      decodeSerialized(input.serialized, codec, "{ serialized }")
+    );
   }
   if (keys.length === 1 && keys[0] === "bitmap") {
     const bitmap = input.bitmap;
@@ -3780,13 +4071,13 @@ function prepareLoadInput(input, codec) {
       const size = bitmap.getSerializationSizeInBytes("portable");
       if (typeof size === "number" && size > MAX_SERIALIZED_LOAD_BYTES) throw overCap(what, size);
     }
-    return decode(bitmap.serialize("portable"), what, codec);
+    return new DecodedLoadInput(decodeSerialized(bitmap.serialize("portable"), codec, what));
   }
   throw new ValidationError(
     `a load takes ids (an iterable of integers), { serialized } or { bitmap }, as the only key; got an object with keys [${keys.join(", ")}]. Load options go in the next argument.`
   );
 }
-function decode(bytes, what, codec) {
+function decodeSerialized(bytes, codec, what = "the buffer") {
   if (typeof bytes !== "object" || bytes === null || tagOf(bytes) !== "Uint8Array") {
     throw new ValidationError(`${what} must be a Uint8Array of portable Roaring bytes`);
   }
@@ -3794,9 +4085,7 @@ function decode(bytes, what, codec) {
   if (view.byteLength > MAX_SERIALIZED_LOAD_BYTES) throw overCap(what, view.byteLength);
   const own = isShared(view.buffer) ? new Uint8Array(view) : view;
   try {
-    return new DecodedLoadInput(
-      codec.safeDeserialize(own, MAX_SERIALIZED_LOAD_BYTES, { whole: true })
-    );
+    return codec.safeDeserialize(own, MAX_SERIALIZED_LOAD_BYTES, { whole: true });
   } catch (err) {
     if (!isIntegrityError(err)) throw err;
     throw new ValidationError(`${what} is not a valid bitmap: ${err.message}`);
@@ -3939,6 +4228,8 @@ var notThePinned = (ref, generation) => new NotFoundError(
 function versionOf(generation, lineage) {
   return lineage === void 0 ? String(generation) : `${generation}:${String(lineage)}`;
 }
+var PinMoved = class extends Error {
+};
 function summaryOfGeneration(generation, description) {
   const { cardinality, metadata } = description;
   return metadata === void 0 || Object.keys(metadata).length === 0 ? { generation, cardinality } : { generation, cardinality, metadata: Object.freeze({ ...metadata }) };
@@ -4305,17 +4596,102 @@ var CrbmStorageChunkSource = class {
    * and a `keep: 0` sweep can land in that gap, and nothing has been handed out yet, so the generation current
    * once the swept one is gone is exactly what a pin taken now should hold. One retry, then propagate.
    */
-  async pinGeneration(ref) {
+  async pinGeneration(ref, lease) {
+    for (let moved = 0; ; moved++) {
+      try {
+        try {
+          return await this.pinOnce(ref, lease);
+        } catch (err) {
+          if (!isNotFoundError(err)) throw err;
+          return await this.pinOnce(ref, lease);
+        }
+      } catch (err) {
+        if (!(err instanceof PinMoved)) throw err;
+        if (moved >= 2) {
+          throw new WriteConflictError(
+            `pin: the pointer of "${ref.segment}" moved on every attempt to lease its current generation`
+          );
+        }
+      }
+    }
+  }
+  /**
+   * Open one named generation and verify it is the object `at.fingerprint` names, for a pin the caller reopens. One
+   * row read and one tail read with a registry (none of the row for a store without one): the open is the one a
+   * pinned read makes ({@link readerAt}), memoised under the version the pin will read by, so the pin's first read
+   * finds it open. A generation that is gone, above the row's pointer, on a destroyed or absent row, or another
+   * object than the fingerprint names, throws `NotFoundError`; nothing here reads empty.
+   *
+   * A generation counts as published while the pointer is at or above it. A rollback deletes nothing, so after one
+   * and a later load, a generation it rolled back from can be reopened while its object is still stored and the
+   * fingerprint matches. Like `pinGeneration`'s pinned reads, this opens the object without the live open's check
+   * of the row's summary against it, since that check is made where the row's own generation is read.
+   */
+  async pinGenerationAt(ref, at, lease) {
+    const { generation, fingerprint } = at;
+    const gone = (why) => new NotFoundError(
+      `segment "${ref.segment}" generation ${generation} cannot be pinned: ${why}`
+    );
+    let version = versionOf(generation, void 0);
+    let installed;
+    let pinKey;
+    let memoised = false;
+    if (this.registry !== void 0) {
+      const record = await this.registry.get(ref);
+      if (record === null || record.status === "destroyed")
+        throw gone("the segment has no readable row");
+      if (record.currentGen === null || generation > record.currentGen) {
+        throw gone("it is not a published generation of this segment");
+      }
+      let lineage = record.token;
+      if (lease !== void 0) {
+        const taken = await lease.take(record);
+        if (taken === "moved") throw gone("the segment moved while its lease was taken");
+        lineage = taken.token;
+      }
+      version = versionOf(generation, lineage);
+      const key = this.pinnedKey(ref, version);
+      memoised = this.snapshots.peek(key) !== void 0;
+      if (!memoised) {
+        installed = this.install(
+          key,
+          Snapshot.eager(
+            this.openForTarget(ref, {
+              generation,
+              lineage,
+              wrappedDeks: record.wrappedDeks
+            })
+          )
+        );
+      }
+      pinKey = key;
+    }
+    if (this.registry === void 0) {
+      memoised = this.snapshots.peek(this.pinnedKey(ref, version, fingerprint)) !== void 0;
+    }
     try {
-      return await this.pinOnce(ref);
+      await this.readerAt(ref, generation, version, fingerprint);
     } catch (err) {
-      if (!isNotFoundError(err)) throw err;
-      return this.pinOnce(ref);
+      if (installed !== void 0 && pinKey !== void 0 && this.snapshots.peek(pinKey) === installed) {
+        this.snapshots.delete(pinKey);
+      }
+      throw err;
     }
+    if (!memoised) {
+      const held = this.heldKey(ref, version, fingerprint);
+      this.replacedPins.delete(held);
+      this.checking.delete(held);
+    }
+    return { generation, version, fingerprint };
   }
-  async pinOnce(ref) {
-    const live = await this.resolveLive(ref);
+  async pinOnce(ref, lease) {
+    let live = await this.resolveLive(ref);
     if (live === null) return null;
+    if (lease !== void 0 && live.row !== void 0) {
+      const taken = await lease.take(live.row);
+      if (taken === "moved") throw new PinMoved();
+      live = { ...live, target: { ...live.target, lineage: taken.token } };
+    }
     const target = live.target;
     const version = versionOf(target.generation, target.lineage);
     let reader;
@@ -4611,6 +4987,7 @@ var CrbmStorageChunkSource = class {
       const unwrap = keys === void 0 || keys.length === 0 || this.keystore === void 0 ? void 0 : prior?.unwrap !== void 0 && sameKeys(prior.target.wrappedDeks, keys) ? prior.unwrap : once(() => this.keystore.openDek(keys));
       const crypto = once(() => this.cryptoForRead(ref, generation, keys, unwrap));
       return {
+        row: record,
         target: { generation, lineage: record.token, wrappedDeks: record.wrappedDeks },
         crypto,
         unwrap,
@@ -5048,19 +5425,36 @@ function refuseCleartextOntoKey(key, record, cleartext) {
 }
 var UNANSWERED_RESENDS = 3;
 var UNANSWERED_RESEND_BASE_MS = 500;
-async function publishGeneration(registry, key, options = {}) {
+function leasesPatch(record, options) {
+  const held = record.leases;
+  if (held === void 0) return {};
+  if (options.clearLeases === true) return { leases: void 0 };
+  if (options.leasesNow === void 0) return {};
+  const now = options.leasesNow();
+  const live = held.filter((e) => isLive(e, now));
+  if (live.length === held.length) return {};
+  return { leases: live.length === 0 ? void 0 : live };
+}
+async function publishGenerationKept(registry, key, options = {}) {
   let fresh;
   let failedOn;
   let unanswered;
   let resends = 0;
+  const churn = leaseChurn({ clock: options.clock, rng: options.rng });
+  let throughChurn = false;
+  let waited;
   let sawUnanswered = false;
   let lastRecord;
   for (let attempt = 0; attempt < 5; attempt++) {
     const reused = attempt === 0 && options.row !== void 0;
+    const holdsRow = fresh === void 0;
     const record = fresh !== void 0 ? fresh : reused ? options.row ?? null : await registry.get(key);
+    const write = holdsRow ? { held: record } : void 0;
     fresh = void 0;
     unanswered = void 0;
     lastRecord = record;
+    let next;
+    let wrote;
     if (failedOn !== void 0) {
       let landed;
       try {
@@ -5068,48 +5462,78 @@ async function publishGeneration(registry, key, options = {}) {
       } catch (proofErr) {
         throw outcomeUnknown(key, proofErr);
       }
-      if (landed) return true;
+      if (landed)
+        return {
+          published: true,
+          kept: { ...nextKept(failedOn, key.generation, options.keep), token: void 0 }
+        };
       if (record !== null && record.status === "active" && record.currentGen === key.generation) {
-        return false;
+        return REFUSED;
       }
       failedOn = void 0;
     }
     try {
       if (options.expectFrom !== void 0 && record?.currentGen !== options.expectFrom) {
-        return false;
+        return REFUSED;
       }
       if (options.expectAbsent === true && record !== null) {
-        return false;
+        return REFUSED;
       }
+      throughChurn = false;
       if (options.expectToken !== void 0 && record?.token !== options.expectToken) {
-        return false;
+        const held = options.expectRow;
+        if (record !== null && held != null && record === waited && onlyLeasesDiffer(held, record)) {
+          throughChurn = true;
+        } else {
+          const settled2 = record === waited ? void 0 : await churn.settle(held, record, () => registry.get(key));
+          if (settled2 !== void 0) {
+            waited = settled2.row;
+            fresh = settled2.row;
+            attempt -= 1;
+            continue;
+          }
+          return REFUSED;
+        }
       }
       if (record === null && options.summary !== void 0 && "sealed" in options.summary && options.wrappedDeks === void 0) {
         if (reused) continue;
-        return false;
+        return REFUSED;
       }
       if (record === null) {
-        await registry.create(key, {
-          currentGen: key.generation,
-          wrappedDeks: options.wrappedDeks,
-          ...options.summary === void 0 ? {} : { summary: options.summary }
-        });
+        next = nextKept(null, key.generation, options.keep);
+        wrote = (await registry.create(
+          key,
+          {
+            currentGen: key.generation,
+            wrappedDeks: options.wrappedDeks,
+            ...options.summary === void 0 ? {} : { summary: options.summary },
+            ...next.list === void 0 ? {} : { keptGens: next.list }
+          },
+          write
+        )).token;
       } else if (record.status === "destroyed") {
         throw new ValidationError(
           `segment "${key.segment}" was destroyed (crypto-shredded) while generation ${key.generation} was being written \u2014 refusing to publish it; the written object is unreadable. Use a new segment.`
         );
       } else if (record.currentGen === null) {
         refuseCleartextOntoKey(key, record, options.cleartext);
-        await registry.compareAndSwap(key, record.token, {
-          currentGen: key.generation,
-          ...options.wrappedDeks === void 0 ? {} : { wrappedDeks: options.wrappedDeks },
-          ...options.summary === void 0 ? {} : { summary: options.summary }
-        });
+        next = nextKept(record, key.generation, options.keep);
+        wrote = (await registry.compareAndSwap(
+          key,
+          record.token,
+          {
+            currentGen: key.generation,
+            ...options.wrappedDeks === void 0 ? {} : { wrappedDeks: options.wrappedDeks },
+            ...options.summary === void 0 ? {} : { summary: options.summary },
+            ...next.list === void 0 ? {} : { keptGens: next.list }
+          },
+          write
+        )).token;
       } else if (record.currentGen > key.generation) {
-        return false;
+        return REFUSED;
       } else if (record.currentGen === key.generation) {
         if (reused) continue;
-        return true;
+        return { published: true };
       } else {
         if (options.wrappedDeks !== void 0 && options.wrappedDeks.length > 0) {
           throw new ValidationError(
@@ -5117,15 +5541,27 @@ async function publishGeneration(registry, key, options = {}) {
           );
         }
         refuseCleartextOntoKey(key, record, options.cleartext);
-        await registry.compareAndSwap(key, record.token, {
-          currentGen: key.generation,
-          ...options.summary === void 0 ? {} : { summary: options.summary }
-        });
+        next = nextKept(record, key.generation, options.keep);
+        wrote = (await registry.compareAndSwap(
+          key,
+          record.token,
+          {
+            currentGen: key.generation,
+            ...options.summary === void 0 ? {} : { summary: options.summary },
+            ...next.list === void 0 ? {} : { keptGens: next.list },
+            ...leasesPatch(record, options)
+          },
+          write
+        )).token;
       }
-      return true;
+      return {
+        published: true,
+        kept: { ...next ?? { list: void 0, evict: [] }, token: wrote }
+      };
     } catch (err) {
       if (isWriteConflictError(err)) {
         failedOn = record;
+        if (throughChurn) attempt -= 1;
         continue;
       }
       if (!isTransientError(err)) throw err;
@@ -5154,10 +5590,12 @@ async function publishGeneration(registry, key, options = {}) {
   }
   const final = await registry.get(key);
   if (final !== null && final.currentGen !== null && final.currentGen >= key.generation) {
-    if (final.currentGen !== key.generation) return false;
-    if (!sawUnanswered) return true;
+    if (final.currentGen !== key.generation) return REFUSED;
+    if (!sawUnanswered) return { published: true };
     try {
-      return await landedHere(final, lastRecord ?? null, key, options.holdsOwnObject);
+      return {
+        published: await landedHere(final, lastRecord ?? null, key, options.holdsOwnObject)
+      };
     } catch (proofErr) {
       throw outcomeUnknown(key, proofErr);
     }
@@ -5167,6 +5605,10 @@ async function publishGeneration(registry, key, options = {}) {
     `publishGeneration: contention setting currentGen for ${key.segment}`
   );
 }
+var REFUSED = { published: false };
+async function publishGeneration(registry, key, options = {}) {
+  return (await publishGenerationKept(registry, key, options)).published;
+}
 async function landedHere(now, before, key, holdsOwnObject) {
   if (now === null || now.status === "destroyed" || now.currentGen !== key.generation) return false;
   if (before !== null && !sameIncarnation(before, now)) return false;
@@ -5206,6 +5648,8 @@ async function bulkLoadAhead(driver, ref, ahead, ids, options = {}) {
     await pause();
     chunks = ids.bitmap.encodeChunks();
     await pause();
+  } else if (ids instanceof ChunkLoadInput) {
+    chunks = encodeEach(rangeCheckedAtWrite(await collectChunks(ids, codec, options.clock)));
   } else {
     chunks = encodeEach(
       await bucketIds(ids instanceof DecodedLoadInput ? ids.bitmap : ids, codec, options.clock)
@@ -5298,6 +5742,52 @@ async function bulkLoadAhead(driver, ref, ahead, ids, options = {}) {
     fingerprint
   };
 }
+function* rangeCheckedAtWrite(chunks) {
+  for (const chunk of chunks) {
+    const max = chunk.bitmap.maximum?.();
+    if (max !== void 0 && max > MAX_REMAINDER) {
+      throw new ValidationError(
+        `chunk ${chunk.chunkKey} holds ${max}, outside the 16-bit range [0, ${MAX_REMAINDER}]`
+      );
+    }
+    yield chunk;
+  }
+}
+async function collectChunks(input, codec, clock) {
+  const chunks = [];
+  const tick = yieldEvery(clock);
+  let last = -1;
+  for await (const chunk of input.chunks) {
+    if (typeof chunk !== "object" || chunk === null) {
+      throw new ValidationError(
+        `a chunk must be an object with a chunkKey and a bitmap; got ${String(chunk)}`
+      );
+    }
+    const { chunkKey, bitmap } = chunk;
+    if (codec.owns?.(bitmap) !== true) {
+      throw new ValidationError(
+        `chunk ${String(chunkKey)}: its bitmap is not one this load's codec made`
+      );
+    }
+    if (!Number.isInteger(chunkKey) || chunkKey < 0 || chunkKey > MAX_REMAINDER) {
+      throw new ValidationError(`a chunk's key must be an integer in [0, 65535]; got ${chunkKey}`);
+    }
+    if (chunkKey <= last) {
+      throw new ValidationError(`chunk ${chunkKey} does not ascend: the last was ${last}`);
+    }
+    last = chunkKey;
+    const max = bitmap.maximum?.();
+    if (max !== void 0 && max > MAX_REMAINDER) {
+      throw new ValidationError(
+        `chunk ${chunkKey} holds ${max}, outside the 16-bit range [0, ${MAX_REMAINDER}]`
+      );
+    }
+    chunks.push({ chunkKey, bitmap });
+    const pause = tick();
+    if (pause !== null) await pause;
+  }
+  return chunks;
+}
 async function bucketIds(ids, codec, clock) {
   const byChunk = /* @__PURE__ */ new Map();
   const pendingByChunk = /* @__PURE__ */ new Map();
@@ -5575,7 +6065,25 @@ async function currentCardinality(ref, deps, record, unwrapped) {
   for (const n of reader.cardinalities().values()) total += n;
   return { cardinality: total, fromSummary: false };
 }
-async function loadSegment(ref, input, deps, options = {}) {
+function loadSegment(ref, input, deps, options = {}) {
+  return runLoad(ref, (codec) => prepareLoadInput(input, codec), deps, options);
+}
+function loadSegmentChunks(ref, chunks, deps, options = {}) {
+  return runLoad(
+    ref,
+    () => {
+      if (typeof chunks !== "object" || chunks === null || !(Symbol.asyncIterator in chunks)) {
+        throw new ValidationError(
+          "loadSegmentChunks takes an async iterable of { chunkKey, bitmap }"
+        );
+      }
+      return new ChunkLoadInput(chunks);
+    },
+    deps,
+    options
+  );
+}
+async function runLoad(ref, prepare, deps, options) {
   validateUserRef(ref);
   const codec = requireCodec(deps.codec, "loadSegment");
   const keep = options.keep ?? 1;
@@ -5601,7 +6109,7 @@ async function loadSegment(ref, input, deps, options = {}) {
     throw new ValidationError(message);
   });
   const audit = safeAudit(options.audit ?? NOOP_AUDIT);
-  const ids = prepareLoadInput(input, codec);
+  const ids = prepare(codec);
   assertRegistryCanWrite(deps.registry, "load");
   const row = await deps.registry.get(ref);
   const fromToken = row?.token;
@@ -5658,7 +6166,7 @@ async function loadSegment(ref, input, deps, options = {}) {
   const key = { namespace: ref.namespace, segment: ref.segment, generation };
   const reclaim = async () => {
     const now = await deps.registry.get(ref);
-    if (now !== null && (now.token === fromToken || now.status === "destroyed")) {
+    if (now !== null && (now.token === fromToken || now.status === "destroyed" || row !== null && onlyLeasesDiffer(row, now))) {
       await deps.storage.delete(key);
       return;
     }
@@ -5700,14 +6208,17 @@ async function loadSegment(ref, input, deps, options = {}) {
   if (guard?.minRetained !== void 0 && before !== null) {
     if (written.cardinality < before * guard.minRetained) return refuse("min-retained");
   }
+  const leasesNow = deps.clock === void 0 ? void 0 : () => deps.clock.now();
   let published;
   try {
-    published = await publishGeneration(deps.registry, key, {
+    published = await publishGenerationKept(deps.registry, key, {
+      keep,
+      leasesNow,
       row,
       wrappedDeks: written.wrappedDeks,
       summary: written.summary,
       cleartext: !written.encrypted,
-      ...fromToken === void 0 ? {} : { expectToken: fromToken },
+      ...fromToken === void 0 ? {} : { expectToken: fromToken, expectRow: row },
       ...needsBefore && fromGeneration !== void 0 ? { expectFrom: fromGeneration } : {},
       // The third case, and the one the two fences above structurally cannot cover: the guard judged a segment
       // that had NO ROW. Both `expectFrom` and `expectToken` compare against a value read from a row, so with no
@@ -5731,7 +6242,7 @@ async function loadSegment(ref, input, deps, options = {}) {
     if (isValidationError(err) || err instanceof KeyUnavailableError) await reclaim();
     throw err;
   }
-  if (!published) return refuse("superseded");
+  if (!published.published) return refuse("superseded");
   audit.onEvent({
     kind: "segment.publish",
     segment: ref.segment,
@@ -5742,7 +6253,10 @@ async function loadSegment(ref, input, deps, options = {}) {
   const collected = await collectAfterLoad(ref, deps, {
     generation,
     keep,
-    byName: checked && !currentObjectGone && deps.collectByListing !== true,
+    byName: checked && deps.collectByListing !== true,
+    currentGone: currentObjectGone,
+    ...leasesNow === void 0 ? {} : { leases: { now: leasesNow } },
+    kept: published.kept,
     ...current.fromSummary && fromGeneration !== void 0 ? { proveCurrent: { ...ref, generation: fromGeneration } } : {}
   });
   return {
@@ -5841,10 +6355,25 @@ async function rollbackSegment(ref, toGeneration, deps, options = {}) {
     { cardinality: reader.count(), metadata: reader.metadata },
     aead
   );
-  const { token } = await deps.registry.compareAndSwap(ref, record.token, {
-    currentGen: toGeneration,
-    summary
-  });
+  const churn = leaseChurn(deps);
+  let against = record.token;
+  let token;
+  for (; ; ) {
+    try {
+      ({ token } = await deps.registry.compareAndSwap(ref, against, {
+        currentGen: toGeneration,
+        summary
+      }));
+      break;
+    } catch (err) {
+      if (!isWriteConflictError(err)) throw err;
+      const seen = await deps.registry.get(ref);
+      const settled2 = await churn.settle(record, seen, () => deps.registry.get(ref));
+      const now = settled2?.row ?? null;
+      if (settled2 === void 0 || now === null || !onlyLeasesDiffer(record, now)) throw err;
+      against = now.token;
+    }
+  }
   let stillThere = false;
   for await (const key of deps.storage.list(ref)) {
     if (key.generation === toGeneration) {
@@ -5867,13 +6396,31 @@ async function rollbackSegment(ref, toGeneration, deps, options = {}) {
   }
   if (!stillThere || replaced) {
     let undone = false;
-    try {
-      await deps.registry.compareAndSwap(ref, token, {
-        currentGen: record.currentGen,
-        summary: describingSummary(record)
-      });
-      undone = true;
-    } catch {
+    let undoAgainst = token;
+    for (; ; ) {
+      try {
+        await deps.registry.compareAndSwap(ref, undoAgainst, {
+          currentGen: record.currentGen,
+          summary: describingSummary(record)
+        });
+        undone = true;
+        break;
+      } catch (err) {
+        if (!isWriteConflictError(err)) break;
+        const moved = ["currentGen", "summary", "keptGens"];
+        let now;
+        try {
+          const seen = await deps.registry.get(ref);
+          if (seen === null || seen.currentGen !== toGeneration) break;
+          const settled2 = await churn.settle(record, seen, () => deps.registry.get(ref), moved);
+          now = settled2?.row ?? null;
+        } catch {
+          break;
+        }
+        if (now === null || now.currentGen !== toGeneration || !onlyLeasesDiffer(record, now, moved))
+          break;
+        undoAgainst = now.token;
+      }
     }
     throw new NotFoundError(
       `rollback: generation ${toGeneration} of "${ref.segment}" was ${replaced ? "replaced" : "collected"} while the pointer was moving` + (undone ? " \u2014 the pointer was put back" : `, and the move back failed, so the pointer may still name ${toGeneration} (a write that landed and lost its response reads as a failure here). Check which generation is current, then re-run a rollback to a generation that exists, or restore the object.`)
@@ -5937,7 +6484,7 @@ async function eraseIdFromSegment(ref, id, deps, options = {}) {
     if (row === null) return "absent";
     if (row.status === "destroyed") return "destroyed";
     if (row.currentGen === null) return "no-generation";
-    return row.currentGen === from && row.token === fromToken ? null : "superseded";
+    return row.currentGen === from && (row.token === fromToken || onlyLeasesDiffer(record, row)) ? null : "superseded";
   };
   const holds = async (generation2) => {
     const key2 = { ...base, generation: generation2 };
@@ -6108,7 +6655,13 @@ async function eraseIdFromSegment(ref, id, deps, options = {}) {
   const published = await publishGeneration(deps.registry, key, {
     expectFrom: from,
     expectToken: fromToken,
+    // A lease written while the rewrite streams moves the token and nothing it derived from: it does not refuse it.
+    expectRow: record,
     summary,
+    // The row then records that no generation below the new pointer is kept, as the collection below leaves it.
+    keep: 0,
+    // Every generation below the new pointer is deleted whatever a lease says, so the row drops its leases.
+    clearLeases: true,
     // A write that ends without an answer is settled by reading the row, and a pointer at this number is this
     // rewrite's only over the object it wrote: the footer proves it, so another incarnation's cannot pass for it.
     holdsOwnObject: () => provesOwnObject(deps.storage, key, fingerprint),
@@ -6441,8 +6994,17 @@ async function listGenerations2(storage, ref) {
 }
 async function shredSegment(ref, deps, allowCleartext, op = "destroySegment") {
   const base = { segment: ref.segment, namespace: ref.namespace };
+  const churn = leaseChurn(deps);
+  let lost;
   for (let attempt = 0; attempt < MAX_CAS_ATTEMPTS; attempt++) {
-    const record = await deps.registry.get(ref);
+    let record = await deps.registry.get(ref);
+    if (lost !== void 0) {
+      const settled2 = await churn.settle(lost, record, () => deps.registry.get(ref));
+      if (settled2 !== void 0) {
+        record = settled2.row;
+        attempt -= 1;
+      }
+    }
     if (record === null) {
       return { ...base, destroyed: false, cryptoShredded: false, reason: "absent" };
     }
@@ -6461,11 +7023,14 @@ async function shredSegment(ref, deps, allowCleartext, op = "destroySegment") {
         keyId: void 0,
         // The current generation's cached count and metadata go with it: sealed, they cannot be opened without
         // the wrappings; clear, they would outlive the segment on its tombstone.
-        summary: void 0
+        summary: void 0,
+        // A tombstone holds nothing: a lease names a generation of a segment that now resolves none.
+        leases: void 0
       });
       return { ...base, destroyed: true, cryptoShredded: encrypted };
     } catch (err) {
       if (!isWriteConflictError(err)) throw err;
+      lost = record;
     }
   }
   throw new WriteConflictError(`${op}: contention shredding "${ref.segment}" \u2014 retry`);
@@ -6533,8 +7098,17 @@ async function setSegmentRetention(ref, deps, policy) {
   validateRetentionPolicy(policy);
   const base = { segment: ref.segment, namespace: ref.namespace };
   let previousExpiresAt;
+  const churn = leaseChurn(deps);
+  let lost;
   for (let attempt = 0; attempt < RETENTION_CAS_ATTEMPTS; attempt += 1) {
-    const record = await deps.registry.get(ref);
+    let record = await deps.registry.get(ref);
+    if (lost !== void 0) {
+      const settled2 = await churn.settle(lost, record, () => deps.registry.get(ref));
+      if (settled2 !== void 0) {
+        record = settled2.row;
+        attempt -= 1;
+      }
+    }
     try {
       previousExpiresAt = readExpiresAt(record);
       if (record === null) {
@@ -6561,6 +7135,7 @@ async function setSegmentRetention(ref, deps, policy) {
       };
     } catch (err) {
       if (!isWriteConflictError(err)) throw err;
+      lost = record ?? void 0;
     }
   }
   throw new WriteConflictError(
@@ -6569,8 +7144,17 @@ async function setSegmentRetention(ref, deps, policy) {
 }
 async function clearSegmentRetention(ref, deps) {
   validateUserRef(ref);
+  const churn = leaseChurn(deps);
+  let lost;
   for (let attempt = 0; attempt < RETENTION_CAS_ATTEMPTS; attempt += 1) {
-    const record = await deps.registry.get(ref);
+    let record = await deps.registry.get(ref);
+    if (lost !== void 0) {
+      const settled2 = await churn.settle(lost, record, () => deps.registry.get(ref));
+      if (settled2 !== void 0) {
+        record = settled2.row;
+        attempt -= 1;
+      }
+    }
     if (record === null) return false;
     if (record.status === "destroyed") return false;
     if (record.retention === void 0 || !(EXPIRES_AT in record.retention)) return false;
@@ -6584,6 +7168,7 @@ async function clearSegmentRetention(ref, deps) {
       return true;
     } catch (err) {
       if (!isWriteConflictError(err)) throw err;
+      lost = record;
     }
   }
   throw new WriteConflictError(
@@ -6955,6 +7540,31 @@ function failureReason(err) {
   return `failed: ${err instanceof Error ? err.message : String(err)}`;
 }
 
+// src/core/registry-reap.ts
+var DEFAULT_REAP_LIMIT = 1e3;
+async function reapRegistryTombstones(registry, options = {}) {
+  const dryRun = options.dryRun === true;
+  if (!dryRun && options.confirmNoLegacyWriters !== true) {
+    throw new ValidationError(
+      "reapRegistryTombstones: a real run needs `confirmNoLegacyWriters: true`, your statement that no process on a release before 0.12 writes this registry (one that did would issue a removed row\u2019s tokens again). Pass `dryRun: true` to see what would be removed."
+    );
+  }
+  const limit = options.limit ?? DEFAULT_REAP_LIMIT;
+  if (!Number.isInteger(limit) || limit < 1) {
+    throw new ValidationError(
+      `reapRegistryTombstones: \`limit\` must be a positive integer; got ${String(limit)}`
+    );
+  }
+  if (options.namespace !== void 0) validateUserNamespace(options.namespace);
+  if (registry.reapLegacyTombstones === void 0) {
+    throw new UnsupportedError(
+      "reapRegistryTombstones: this registry keeps no deleted rows of a release before 0.12 to remove (only the object-store registries, S3, GCS and Azure Blob, do)"
+    );
+  }
+  const request = options.namespace === void 0 ? { dryRun, limit } : { namespace: options.namespace, dryRun, limit };
+  return registry.reapLegacyTombstones(request);
+}
+
 // src/core/consistency.ts
 var DEFAULT_CHECK_CONCURRENCY = 8;
 async function generationsPresent(storage, ref) {
@@ -7158,7 +7768,12 @@ export {
   InProcessKeystore,
   IntegrityError,
   KeyUnavailableError,
+  LEASE_SKEW_MS,
+  LeaseExpiredError,
+  LeaseLimitError,
   LocalFsStorage,
+  MAX_LEASES_PER_SEGMENT,
+  MAX_LEASE_MS,
   MIN_EXPIRES_AT_MS,
   MemoryStorage,
   NOOP_METRICS,
@@ -7177,6 +7792,7 @@ export {
   checkBudget,
   clearSegmentRetention,
   collectWithinBudget,
+  decodeSerialized,
   destroySegment,
   dropSegment,
   eraseIdFromSegment,
@@ -7187,6 +7803,8 @@ export {
   groundedReport,
   isCloudRoaringError,
   isIntegrityError,
+  isLeaseExpiredError,
+  isLeaseLimitError,
   isNotFoundError,
   isStorageBackend,
   isTransientError,
@@ -7195,8 +7813,11 @@ export {
   listGenerations,
   listSegments,
   loadSegment,
+  loadSegmentChunks,
   mapWithConcurrency,
   readRetentionPolicy,
+  reapRegistryTombstones,
+  releaseLease,
   resolveBudget,
   resolvePerOpBudget,
   retireExpired,
@@ -7208,6 +7829,7 @@ export {
   segmentKey,
   setSegmentRetention,
   splitId,
+  takeLease,
   withRetry
 };
 //# sourceMappingURL=index.js.map