@cloudbitmaps/core 0.16.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-LFUNPMXZ.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;
@@ -675,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.
    *
@@ -1444,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 {
@@ -1510,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
@@ -2030,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();
@@ -2067,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?.();
@@ -3848,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) {
@@ -3866,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;
@@ -3878,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`);
   }
@@ -3892,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}`);
@@ -4037,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 }) };
@@ -4403,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;
@@ -4709,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,
@@ -5146,11 +5425,24 @@ function refuseCleartextOntoKey(key, record, cleartext) {
 }
 var UNANSWERED_RESENDS = 3;
 var UNANSWERED_RESEND_BASE_MS = 500;
-async function publishGeneration(registry, key, options = {}) {
+function leasesPatch(record, options) {
+  const held = record.leases;
+  if (held === void 0) return {};
+  if (options.clearLeases === true) return { leases: void 0 };
+  if (options.leasesNow === void 0) return {};
+  const now = options.leasesNow();
+  const live = held.filter((e) => isLive(e, now));
+  if (live.length === held.length) return {};
+  return { leases: live.length === 0 ? void 0 : live };
+}
+async function publishGenerationKept(registry, key, options = {}) {
   let fresh;
   let failedOn;
   let unanswered;
   let resends = 0;
+  const churn = leaseChurn({ clock: options.clock, rng: options.rng });
+  let throughChurn = false;
+  let waited;
   let sawUnanswered = false;
   let lastRecord;
   for (let attempt = 0; attempt < 5; attempt++) {
@@ -5161,6 +5453,8 @@ async function publishGeneration(registry, key, options = {}) {
     fresh = void 0;
     unanswered = void 0;
     lastRecord = record;
+    let next;
+    let wrote;
     if (failedOn !== void 0) {
       let landed;
       try {
@@ -5168,57 +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(
+        next = nextKept(null, key.generation, options.keep);
+        wrote = (await registry.create(
           key,
           {
             currentGen: key.generation,
             wrappedDeks: options.wrappedDeks,
-            ...options.summary === void 0 ? {} : { summary: options.summary }
+            ...options.summary === void 0 ? {} : { summary: options.summary },
+            ...next.list === void 0 ? {} : { keptGens: next.list }
           },
           write
-        );
+        )).token;
       } else if (record.status === "destroyed") {
         throw new ValidationError(
           `segment "${key.segment}" was destroyed (crypto-shredded) while generation ${key.generation} was being written \u2014 refusing to publish it; the written object is unreadable. Use a new segment.`
         );
       } else if (record.currentGen === null) {
         refuseCleartextOntoKey(key, record, options.cleartext);
-        await registry.compareAndSwap(
+        next = nextKept(record, key.generation, options.keep);
+        wrote = (await registry.compareAndSwap(
           key,
           record.token,
           {
             currentGen: key.generation,
             ...options.wrappedDeks === void 0 ? {} : { wrappedDeks: options.wrappedDeks },
-            ...options.summary === void 0 ? {} : { summary: options.summary }
+            ...options.summary === void 0 ? {} : { summary: options.summary },
+            ...next.list === void 0 ? {} : { keptGens: next.list }
           },
           write
-        );
+        )).token;
       } else if (record.currentGen > key.generation) {
-        return false;
+        return REFUSED;
       } else if (record.currentGen === key.generation) {
         if (reused) continue;
-        return true;
+        return { published: true };
       } else {
         if (options.wrappedDeks !== void 0 && options.wrappedDeks.length > 0) {
           throw new ValidationError(
@@ -5226,20 +5541,27 @@ async function publishGeneration(registry, key, options = {}) {
           );
         }
         refuseCleartextOntoKey(key, record, options.cleartext);
-        await registry.compareAndSwap(
+        next = nextKept(record, key.generation, options.keep);
+        wrote = (await registry.compareAndSwap(
           key,
           record.token,
           {
             currentGen: key.generation,
-            ...options.summary === void 0 ? {} : { summary: options.summary }
+            ...options.summary === void 0 ? {} : { summary: options.summary },
+            ...next.list === void 0 ? {} : { keptGens: next.list },
+            ...leasesPatch(record, options)
           },
           write
-        );
+        )).token;
       }
-      return true;
+      return {
+        published: true,
+        kept: { ...next ?? { list: void 0, evict: [] }, token: wrote }
+      };
     } catch (err) {
       if (isWriteConflictError(err)) {
         failedOn = record;
+        if (throughChurn) attempt -= 1;
         continue;
       }
       if (!isTransientError(err)) throw err;
@@ -5268,10 +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);
     }
@@ -5281,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;
@@ -5838,7 +6166,7 @@ async function runLoad(ref, prepare, deps, options) {
   const key = { namespace: ref.namespace, segment: ref.segment, generation };
   const reclaim = async () => {
     const now = await deps.registry.get(ref);
-    if (now !== null && (now.token === fromToken || now.status === "destroyed")) {
+    if (now !== null && (now.token === fromToken || now.status === "destroyed" || row !== null && onlyLeasesDiffer(row, now))) {
       await deps.storage.delete(key);
       return;
     }
@@ -5880,14 +6208,17 @@ async function runLoad(ref, prepare, deps, options) {
   if (guard?.minRetained !== void 0 && before !== null) {
     if (written.cardinality < before * guard.minRetained) return refuse("min-retained");
   }
+  const leasesNow = deps.clock === void 0 ? void 0 : () => deps.clock.now();
   let published;
   try {
-    published = await publishGeneration(deps.registry, key, {
+    published = await publishGenerationKept(deps.registry, key, {
+      keep,
+      leasesNow,
       row,
       wrappedDeks: written.wrappedDeks,
       summary: written.summary,
       cleartext: !written.encrypted,
-      ...fromToken === void 0 ? {} : { expectToken: fromToken },
+      ...fromToken === void 0 ? {} : { expectToken: fromToken, expectRow: row },
       ...needsBefore && fromGeneration !== void 0 ? { expectFrom: fromGeneration } : {},
       // The third case, and the one the two fences above structurally cannot cover: the guard judged a segment
       // that had NO ROW. Both `expectFrom` and `expectToken` compare against a value read from a row, so with no
@@ -5911,7 +6242,7 @@ async function runLoad(ref, prepare, deps, options) {
     if (isValidationError(err) || err instanceof KeyUnavailableError) await reclaim();
     throw err;
   }
-  if (!published) return refuse("superseded");
+  if (!published.published) return refuse("superseded");
   audit.onEvent({
     kind: "segment.publish",
     segment: ref.segment,
@@ -5922,7 +6253,10 @@ async function runLoad(ref, prepare, deps, options) {
   const collected = await collectAfterLoad(ref, deps, {
     generation,
     keep,
-    byName: checked && !currentObjectGone && deps.collectByListing !== true,
+    byName: checked && deps.collectByListing !== true,
+    currentGone: currentObjectGone,
+    ...leasesNow === void 0 ? {} : { leases: { now: leasesNow } },
+    kept: published.kept,
     ...current.fromSummary && fromGeneration !== void 0 ? { proveCurrent: { ...ref, generation: fromGeneration } } : {}
   });
   return {
@@ -6021,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) {
@@ -6047,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.`)
@@ -6117,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 };
@@ -6288,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),
@@ -6621,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" };
     }
@@ -6641,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`);
@@ -6713,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) {
@@ -6741,6 +7135,7 @@ async function setSegmentRetention(ref, deps, policy) {
       };
     } catch (err) {
       if (!isWriteConflictError(err)) throw err;
+      lost = record ?? void 0;
     }
   }
   throw new WriteConflictError(
@@ -6749,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;
@@ -6764,6 +7168,7 @@ async function clearSegmentRetention(ref, deps) {
       return true;
     } catch (err) {
       if (!isWriteConflictError(err)) throw err;
+      lost = record;
     }
   }
   throw new WriteConflictError(
@@ -7135,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) {
@@ -7338,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,
@@ -7357,6 +7792,7 @@ export {
   checkBudget,
   clearSegmentRetention,
   collectWithinBudget,
+  decodeSerialized,
   destroySegment,
   dropSegment,
   eraseIdFromSegment,
@@ -7367,6 +7803,8 @@ export {
   groundedReport,
   isCloudRoaringError,
   isIntegrityError,
+  isLeaseExpiredError,
+  isLeaseLimitError,
   isNotFoundError,
   isStorageBackend,
   isTransientError,
@@ -7378,6 +7816,8 @@ export {
   loadSegmentChunks,
   mapWithConcurrency,
   readRetentionPolicy,
+  reapRegistryTombstones,
+  releaseLease,
   resolveBudget,
   resolvePerOpBudget,
   retireExpired,
@@ -7389,6 +7829,7 @@ export {
   segmentKey,
   setSegmentRetention,
   splitId,
+  takeLease,
   withRetry
 };
 //# sourceMappingURL=index.js.map