@cloudbitmaps/roaring 0.11.2 → 0.12.0

package/dist/index.js

@@ -112,11 +112,47 @@ function overrun(bytes, offset, length, what) {
   );
 }
 function checkPortableLayout(bytes) {
-  walk(bytes, null);
+  return walk(bytes, null);
 }
-function walk(bytes, out) {
+var SINGLE_HEADER_BYTES = 16;
+var SINGLE_RUN_HEADER_BYTES = 9;
+function* containerPayloads(bytes) {
+  if (bytes.byteLength === 0) return;
+  const { view, count, runFlagsAt, descriptiveAt, bodiesAt } = header(bytes);
+  let pos = bodiesAt;
+  let previousKey = -1;
+  for (let i = 0; i < count; i++) {
+    const key = view.getUint16(descriptiveAt + i * 4, true);
+    if (key <= previousKey) {
+      throw new IntegrityError(
+        `portable roaring: container keys are not strictly ascending (${previousKey} then ${key} at index ${i})`
+      );
+    }
+    previousKey = key;
+    const cardinality = view.getUint16(descriptiveAt + i * 4 + 2, true) + 1;
+    const isRun = runFlagsAt >= 0 && (bytes[runFlagsAt + (i >>> 3)] & 1 << (i & 7)) !== 0;
+    const kind = isRun ? RUN : cardinality > ARRAY_MAX_CARDINALITY ? BITMAP : ARRAY;
+    const size = checkContainer(bytes, view, pos, kind, cardinality, i);
+    const headerBytes = isRun ? SINGLE_RUN_HEADER_BYTES : SINGLE_HEADER_BYTES;
+    const payload = new Uint8Array(headerBytes + size);
+    const out = new DataView(payload.buffer);
+    if (isRun) {
+      out.setUint32(0, SERIAL_COOKIE, true);
+      payload[4] = 1;
+      out.setUint16(7, cardinality - 1, true);
+    } else {
+      out.setUint32(0, SERIAL_COOKIE_NO_RUNCONTAINER, true);
+      out.setUint32(4, 1, true);
+      out.setUint16(10, cardinality - 1, true);
+      out.setUint32(12, SINGLE_HEADER_BYTES, true);
+    }
+    payload.set(bytes.subarray(pos, pos + size), headerBytes);
+    pos += size;
+    yield { chunkKey: key, payload, cardinality };
+  }
+}
+function header(bytes) {
   const length = bytes.byteLength;
-  if (length === 0) return;
   const view = new DataView(bytes.buffer, bytes.byteOffset, length);
   if (length < 4) throw overrun(bytes, 0, 4, "the cookie");
   const cookie = view.getUint32(0, true);
@@ -149,6 +185,12 @@ function walk(bytes, out) {
     offsetsAt = pos;
     pos += count * 4;
   }
+  return { view, count, runFlagsAt, descriptiveAt, offsetsAt, bodiesAt: pos };
+}
+function walk(bytes, out) {
+  if (bytes.byteLength === 0) return 0;
+  const { view, count, runFlagsAt, descriptiveAt, offsetsAt, bodiesAt } = header(bytes);
+  let pos = bodiesAt;
   let previousKey = -1;
   for (let i = 0; i < count; i++) {
     const key = view.getUint16(descriptiveAt + i * 4, true);
@@ -169,35 +211,43 @@ function walk(bytes, out) {
         );
       }
     }
-    let size;
-    if (kind === ARRAY) {
-      size = cardinality * 2;
-      if (pos + size > length) throw overrun(bytes, pos, size, `container ${i} (array)`);
-      checkArray(view, pos, cardinality, i);
-    } else if (kind === BITMAP) {
-      size = BITMAP_CONTAINER_BYTES;
-      if (pos + size > length) throw overrun(bytes, pos, size, `container ${i} (bitmap)`);
-      const bits = popcount(view, pos);
-      if (bits !== cardinality) {
-        throw new IntegrityError(
-          `portable roaring: container ${i} (bitmap) holds ${bits} values, but its header says ${cardinality}`
-        );
-      }
-    } else {
-      if (pos + 2 > length) throw overrun(bytes, pos, 2, `container ${i} (run count)`);
-      const runs = view.getUint16(pos, true);
-      size = 2 + runs * 4;
-      if (pos + size > length) throw overrun(bytes, pos, size, `container ${i} (run)`);
-      const covered = checkRuns(view, pos + 2, runs, i);
-      if (covered !== cardinality) {
-        throw new IntegrityError(
-          `portable roaring: container ${i} (run) covers ${covered} values, but its header says ${cardinality}`
-        );
-      }
-    }
+    const size = checkContainer(bytes, view, pos, kind, cardinality, i);
     out?.push({ key, cardinality, kind, offset: pos });
     pos += size;
   }
+  return pos;
+}
+function checkContainer(bytes, view, pos, kind, cardinality, i) {
+  const length = bytes.byteLength;
+  if (kind === ARRAY) {
+    const size2 = cardinality * 2;
+    if (pos + size2 > length) throw overrun(bytes, pos, size2, `container ${i} (array)`);
+    checkArray(view, pos, cardinality, i);
+    return size2;
+  }
+  if (kind === BITMAP) {
+    if (pos + BITMAP_CONTAINER_BYTES > length) {
+      throw overrun(bytes, pos, BITMAP_CONTAINER_BYTES, `container ${i} (bitmap)`);
+    }
+    const bits = popcount(view, pos);
+    if (bits !== cardinality) {
+      throw new IntegrityError(
+        `portable roaring: container ${i} (bitmap) holds ${bits} values, but its header says ${cardinality}`
+      );
+    }
+    return BITMAP_CONTAINER_BYTES;
+  }
+  if (pos + 2 > length) throw overrun(bytes, pos, 2, `container ${i} (run count)`);
+  const runs = view.getUint16(pos, true);
+  const size = 2 + runs * 4;
+  if (pos + size > length) throw overrun(bytes, pos, size, `container ${i} (run)`);
+  const covered = checkRuns(view, pos + 2, runs, i);
+  if (covered !== cardinality) {
+    throw new IntegrityError(
+      `portable roaring: container ${i} (run) covers ${covered} values, but its header says ${cardinality}`
+    );
+  }
+  return size;
 }
 function checkArray(view, at, cardinality, index) {
   let previous = -1;
@@ -266,18 +316,25 @@ var SafeBitmap = class _SafeBitmap {
   /**
    * Cap the size, check the structure, then deserialize with the **portable** format.
    * Throws `IntegrityError` if the input exceeds `maxBytes`, is not a well-formed portable bitmap, or fails to
-   * decode — the native addon is never handed unbounded, malformed or unsafe-format input.
+   * decode — the native addon is never handed unbounded, malformed or unsafe-format input. With `whole`, bytes
+   * after the bitmap's last container are refused too; without it they are ignored, as the native decoder ignores
+   * them.
    *
    * The structural check is what makes the decoded bitmap's answers mean anything. The native deserializer
    * bounds its reads and checks nothing else, so bytes of the right length and the wrong shape (containers or
    * values out of order, overlapping runs, a cardinality that disagrees with the bits) decode into a bitmap
    * whose `maximum()`, `has()` and `size` are wrong, and some of those shapes crash the process when used.
    */
-  static safeDeserialize(bytes, maxBytes) {
+  static safeDeserialize(bytes, maxBytes, options = {}) {
     if (bytes.length > maxBytes) {
       throw new IntegrityError2(`serialized bitmap is ${bytes.length}B, exceeds cap ${maxBytes}B`);
     }
-    checkPortableLayout(bytes);
+    const end = checkPortableLayout(bytes);
+    if (options.whole === true && end !== bytes.byteLength) {
+      throw new IntegrityError2(
+        `portable roaring: ${bytes.byteLength - end} bytes follow the bitmap's last container, which ends at byte ${end}. One buffer holds one bitmap: to load several as one segment, combine them first (RoaringBitmap32.orMany) and serialize the result.`
+      );
+    }
     try {
       return new _SafeBitmap(RoaringBitmap32.deserialize(bytes, DeserializationFormat.portable));
     } catch (err) {
@@ -304,10 +361,29 @@ var SafeBitmap = class _SafeBitmap {
    *
    * Called only when writing an immutable objects generation — see {@link CodecBitmap.optimize} for why the read
    * path deliberately does not.
+   *
+   * CANONICAL, which `runOptimize()` alone is not. Where a container's run and array encodings are the same size
+   * (cardinality = 2 × runs + 1: three values in one run, five in two), CRoaring keeps whichever kind the
+   * container already has. A chunk built from ids starts as an array and stays one; the same set reached through
+   * `addRange`, an earlier `runOptimize()` or an operation over run containers is a run, and serializes to other
+   * bytes. Undoing run compression first starts every container where one built from ids starts, so the bytes
+   * depend on membership alone. On a bitmap built from ids there is nothing to undo.
    */
   optimize() {
+    this.bitmap.removeRunCompression();
     this.bitmap.runOptimize();
   }
+  /**
+   * This set as storage chunks, cut from its own containers: {@link optimize} and one `serialize` when called, then
+   * a lazy header walk that copies one container out per step (`containerPayloads`). Per container and per byte,
+   * never per id, and the payloads are the ones {@link SafeBitmap.fromValues} of each chunk's low 16 bits would
+   * serialize to. The walk trusts the bytes it cuts because the native serializer wrote them, from a bitmap that
+   * passed the structural check when it was decoded.
+   */
+  encodeChunks() {
+    this.optimize();
+    return containerPayloads(this.serialize());
+  }
   /**
    * Largest value, or `undefined` when empty. O(1) — roaring reads it off the last container, so the engine's
    * per-chunk range assertion costs one call per chunk rather than a walk per id. The last container holds the
@@ -364,10 +440,13 @@ var SafeBitmap = class _SafeBitmap {
     return this.bitmap.toArray();
   }
 };
+function bitmapAsLoadInput(input) {
+  return input instanceof RoaringBitmap32 ? { bitmap: input } : input;
+}
 var roaringCodec = {
   empty: () => SafeBitmap.empty(),
   fromValues: (values) => SafeBitmap.fromValues(values),
-  safeDeserialize: (bytes, maxBytes) => SafeBitmap.safeDeserialize(bytes, maxBytes)
+  safeDeserialize: (bytes, maxBytes, options) => SafeBitmap.safeDeserialize(bytes, maxBytes, options)
 };
 
 // src/system-clock.ts
@@ -581,6 +660,7 @@ var CloudRoaring = class _CloudRoaring {
   retryOptions;
   crbmSource;
   clock;
+  rng;
   metrics;
   // The store's own drivers, kept so the lifecycle helpers and the `*Into` verbs reuse them instead of making
   // you re-pass deps. `storageDriver` is set only when `storage` was a raw IStorageDriver (a pre-built StorageChunkSource has
@@ -686,6 +766,7 @@ var CloudRoaring = class _CloudRoaring {
     this.cache = cache;
     this.crbmSource = resolved.source instanceof CrbmStorageChunkSource ? resolved.source : void 0;
     this.clock = clock;
+    this.rng = rng;
     this.metrics = metrics;
     this.storageDriver = resolved.driver;
     this.registry = resolved.registry;
@@ -713,10 +794,12 @@ var CloudRoaring = class _CloudRoaring {
       storage: this.storageDriver,
       registry: this.registry,
       clock: this.clock,
+      rng: this.rng,
       codec: roaringCodec,
       // facade injects the flagship codec
       keystore: this.keystore,
-      requireEncryption: this.requireEncryption
+      requireEncryption: this.requireEncryption,
+      readRetry: this.retryOptions
     };
   }
   /** Get a handle to a segment. Validates the name (non-empty, well-formed, within the encoded-length cap). */
@@ -746,7 +829,7 @@ var CloudRoaring = class _CloudRoaring {
   /**
    * Write `ids` as a **new generation of `dest`** and publish it — the shared body of the `*Into` verbs. An `*Into`
    * materialisation is a load, and publishes the same way (hard invariant 1): every load that finds a row fences its
-   * publish on the row's token; a guarded load (the default, since the empty refusal reads the current generation)
+   * publish on the row's token; a guarded load (the default, since the empty refusal needs the size of the current generation)
    * also fences on the pointer it judged (`expectFrom`), and one that found no row fences on that absence instead.
    * Only an unguarded load (`allowEmpty: true` and no `guard.minRetained`) onto a segment with no row publishes bare
    * forward-only. The destination's previous generation stays readable until the publish lands (readers re-resolve
@@ -784,12 +867,14 @@ var CloudRoaring = class _CloudRoaring {
    * **And by default it collects nothing**, unlike `load()`. See the `keep` default below.
    */
   async materialize(dest, ids, op, options) {
-    const deps = this.lifecycleDeps(op);
+    const deps = { ...this.lifecycleDeps(op), collectByListing: true };
+    const metadata = options?.metadata;
     let result;
     try {
       result = await loadSegment(dest, ids, deps, {
         ...options?.allowEmpty === void 0 ? {} : { allowEmpty: options.allowEmpty },
         ...options?.guard === void 0 ? {} : { guard: options.guard },
+        ...metadata === void 0 ? {} : { metadata },
         // COLLECT NOTHING by default, which `loadSegment` does not — it keeps a grace window of 1 and deletes
         // the rest. By default a materialisation collects nothing: the guide states "**It deletes nothing**,
         // unlike `load()`. The destination's previous generations stay in the bucket until you collect them", and
@@ -805,9 +890,9 @@ var CloudRoaring = class _CloudRoaring {
     }
     const reason = result.reason;
     if (reason === "superseded") {
-      const wrote = result.size > 0 ? `generation ${result.generation} was written and did not become current` : `nothing was written \u2014 another writer took generation ${result.generation} first`;
+      const wrote = result.size > 0 ? `generation ${result.generation} was written and is not current` : `nothing was written \u2014 another writer took generation ${result.generation} first`;
       throw new WriteConflictError(
-        `${op}: the destination "${dest.segment}" changed while this materialisation was in flight, so it never became current: ${wrote}. The pointer may have moved, the row may have been rewritten (a retention policy does this) or purged. Re-read the destination and re-run.`
+        `${op}: the destination "${dest.segment}" changed while this materialisation was in flight, so its result is not the destination's current generation: ${wrote}. The pointer may have moved, the row may have been rewritten (a retention policy does this), dropped or purged. Re-read the destination and re-run.`
       );
     }
     return {
@@ -1013,7 +1098,8 @@ var CloudRoaring = class _CloudRoaring {
    * for a `destroyed` tombstone, because a read answers empty in both cases.
    *
    * Two states answer `true` where a read still gives you nothing: a torn restore (a live pointer whose object
-   * was deleted) makes reads *throw* rather than answer empty — `checkConsistency` is the call for that — and
+   * was deleted) makes reads of the object *throw* rather than answer empty, while a cold `count()` answers the number
+   * its row records — `checkConsistency` is the call for that — and
    * a handle carrying an expired `expiresAt` reads empty by a rule that lives on the handle, not the row.
    *
    * Not a lock: the answer can change the moment it returns. If it has to hold, use the fence built for that —
@@ -1075,13 +1161,20 @@ var CloudRoaring = class _CloudRoaring {
    * one cannot.
    *
    * It refuses rather than guesses: a generation not in the bucket (collected, or never written) throws
-   * `NotFoundError` naming what *is* available, and a crypto-shredded segment throws
-   * {@link ValidationError} because every generation of it is unreadable. Rolling to the generation already
-   * current is a no-op that reports itself.
+   * `NotFoundError` naming what *is* available, a crypto-shredded segment throws
+   * {@link ValidationError} because every generation of it is unreadable, and a target that is cleartext under an
+   * encrypted segment, or encrypted under a cleartext one, throws {@link IntegrityError} from one tail read of it,
+   * because every read would refuse it. Rolling to the generation already current is a no-op that reports itself.
+   *
+   * The same tail read (and a range read when the target's index is longer than it) gives the target's id count and
+   * metadata, which the rollback writes into the row with the pointer, so a reader that sees the target as current sees
+   * what describes it. The store's keystore opens an encrypted target for this; without it, or when it cannot open the
+   * key for any reason, the segment still rolls back and the row carries no summary of the target.
    *
    * It deletes nothing. The generations above the new pointer stay put — which is what makes this reversible —
-   * and are then *above* `currentGen`, where collection never looks. They remain until a load numbers above them
-   * (collection then keeps the newest `keep` of what is below its pointer), {@link CloudRoaring.dropSegment}
+   * and are then *above* `currentGen`, where collection never looks. They remain until loads pass them (the first
+   * load whose number one of them holds numbers above them all, and collection then keeps the newest `keep` of what is
+   * below its pointer), {@link CloudRoaring.dropSegment}
    * deletes them, or {@link CloudRoaring.eraseSubject} does: all of those present when it rewrites, and only those holding
    * the id when the current generation does not. An operator who has just undone a bad load should not have the
    * evidence collected out from under them, while a rollback target that still holds erased data would make the
@@ -1103,7 +1196,14 @@ var CloudRoaring = class _CloudRoaring {
     }
   }
   /**
-   * **Replace this segment's contents** with `ids`, as one new immutable generation, and make it current.
+   * **Replace this segment's contents** with `input`, as one new immutable generation, and make it current.
+   *
+   * `input` is ids (any sync or async iterable of integers in `[0, 2^32)`), or a whole bitmap: `{ bitmap }`, anything
+   * with `serialize('portable')` such as `roaring`'s `RoaringBitmap32`, or `{ serialized }`, portable Roaring bytes.
+   * A bitmap is checked (size cap, structure, safe deserializer) before the first request, written from its own
+   * containers with no per-id work, and gives the generation byte for byte the one its ids would. A bare
+   * `RoaringBitmap32` passed as ids loads as `{ bitmap }`. A `Uint8Array` or `Buffer` passed as ids is refused with
+   * `ValidationError`, since each byte would load as an id: pass bytes as `{ serialized }`.
    *
    * The whole write path in one call: take the next generation number, write the object, check the result is
    * plausible, move the pointer, collect what the move superseded. Composed by hand those are four functions and
@@ -1117,6 +1217,14 @@ var CloudRoaring = class _CloudRoaring {
    * if (!r.published) console.warn(`load refused: ${r.reason}`);
    * ```
    *
+   * `metadata` attaches a small record of your own to the generation: a flat object of string keys and string or finite
+   * number values, at most 1,024 bytes as canonical JSON and no key over 128 bytes. A record that breaks a rule throws
+   * `ValidationError` before the load makes a request. It is copied when you call, stored in the generation's object,
+   * and written to the segment's row with the generation's id count by the write that moves the pointer, so a reader
+   * that sees the generation as current sees its metadata. It never changes after that, a rollback puts the target's own
+   * back, and an erasure carries it over without scanning it, so keep a subject's id out of it. It is sealed under the
+   * segment's key on an encrypted segment.
+   *
    * **A load REPLACES.** Whatever the stream contains is what the segment contains afterwards, so an upstream
    * query that returns fewer rows than usual is a shrink nobody asked for and an empty one is a wipe — both
    * reported as a successful write, because at the storage layer they are one. That is what `guard` and the
@@ -1140,20 +1248,39 @@ var CloudRoaring = class _CloudRoaring {
    * so it leaves the orphan rather than risk deleting live data. The orphan is an ordinary generation once a later
    * one is current above it, and collection counts it within `keep`.
    *
+   * **Collection is by name for the default `keep`.** With `keep` of 0 or 1, a load that found nothing above the
+   * pointer deletes the one generation its publish pushed out of the window and lists nothing; it lists the segment's
+   * objects on every sixteenth generation, and on any load that met an object above the pointer or whose check found
+   * the current generation's object gone, to take what the name-only passes leave, such as the generations an
+   * earlier, wider `keep` held. `keep` of 2 or more lists on every load. {@link LoadResult.collected} then names what
+   * the pass deleted by name, and that generation may have been gone already.
+   *
    * What it **throws** for is a fault rather than an outcome: invalid options or ids, and a crypto-shredded
    * segment (`ValidationError`); a key the keystore cannot provide (`KeyUnavailableError`); a current generation
-   * that will not open when a guard reads its size (`IntegrityError`); a driver failure; and a collection pass
-   * that could not prove the segment was still the same one (`WriteConflictError`). The last can be raised
-   * **after** the publish already landed, so a throw does not by itself mean the load did not take effect —
-   * re-read the pointer rather than assuming.
+   * that will not open when a guard has to read its size, which it does only when the row has no usable summary of it
+   * (`IntegrityError`); a driver failure; and a collection pass
+   * by listing that could not prove the segment was still the same one (`WriteConflictError`). That one, and a
+   * failure in the collection's own reads or deletes, can be raised **after** the publish already landed, so a throw
+   * does not by itself mean the load did not take effect — re-read the pointer rather than assuming. A collection by
+   * name that finds the segment changed returns an empty `collected` instead.
+   *
+   * **A `TransientError` from the registry write can leave the publish unsettled, and deletes nothing.** The
+   * generation's object is sent again after a throttle where the backend allows it (a write id tells a first send
+   * that landed from another writer's object), and a driver sends each registry write once. When that write ends
+   * without an answer, the load reads the row: its own landed write is `published: true`, a row that has moved on is
+   * `superseded`, and a row still as the write found it gets a fresh compare-and-swap from the version just read, at
+   * most three times, after a wait on the store's clock. Still unanswered, the load throws the registry's `TransientError` and keeps its object, which
+   * a write may still point the row at. Re-run the load: it numbers past that object, and collection removes it once a
+   * generation above it is current. A `'superseded'` refusal that follows an unanswered write sets `unanswered: true`
+   * on its audit event: that write may have landed, and the generation been current for a while, first.
    *
    * Needs a backend (throws {@link UnsupportedError} otherwise).
    */
-  async load(ref, ids, options = {}) {
+  async load(ref, input, options = {}) {
     validateSegmentRef(ref);
     const deps = this.lifecycleDeps("load");
     try {
-      return await loadSegment(ref, ids, deps, options);
+      return await loadSegment(ref, bitmapAsLoadInput(input), deps, options);
     } finally {
       this.engine.invalidate(ref);
     }
@@ -1183,9 +1310,12 @@ var CloudRoaring = class _CloudRoaring {
    * forever and quietly. Branch on `dropped`, and treat `reason: 'absent'` as the alert.
    *
    * **Inspect `generationsRemaining`.** Empty is the normal outcome; non-empty means the storage was NOT fully
-   * reclaimed and the drop should be re-run. A load that was already writing when the tombstone landed still
-   * finishes its object, so a single sweep can miss it — this call re-sweeps and then reports whatever it still
-   * could not remove rather than returning a result that looks like a clean drop.
+   * reclaimed and the drop should be re-run. A load that had read the segment before the tombstone landed, whether it
+   * was writing or still consuming its ids, can still write its object, so a single sweep can miss it — this call
+   * re-sweeps and then reports whatever it still could not remove rather than returning a result that looks like a
+   * clean drop. A load that writes after the last sweep deletes its own object once its publish is refused; only one
+   * whose process stops in between, or whose publish fails without a definite answer (a lost response, a timeout),
+   * leaves it, for a re-run of the drop.
    *
    * Reads become empty within `cache.genTtlMs` (default 2 s), not instantly: a store that had already read this
    * segment may answer from its cached generation + cached chunks until that window lapses, or, while the registry
@@ -1293,6 +1423,12 @@ var CloudRoaring = class _CloudRoaring {
    * wall-clock knob too, and `retired` counts deletions only — a dry run reports `wouldRetire` instead, so a
    * dashboard summing `retired` can never show a phantom deletion.
    *
+   * **Check `purgeFaults`.** A delete the registry refuses for a reason other than a lost race (a policy that denies
+   * delete, an Azure blob with a snapshot, a raw provider error), whether of a tombstone or of a due-index pointer, is
+   * counted there, with the first one's reason in `firstPurgeFault`. A refused purge is `skipped` in the ledger, is not
+   * charged to `limit`, so it never holds the retirements behind it, and purging stops for the rest of the call after
+   * three refused purges in a row (a purge that succeeds starts the count again).
+   *
    * It also **deletes the tombstone rows its own past retirements left**, after `tombstoneGraceMs` (default 24 h)
    * and only once that segment's Storage generations are provably gone — collecting a straggler generation itself
    * first, since nothing else ever would for a tombstoned segment. Attribution is a **positive marker the sweep
@@ -1300,7 +1436,12 @@ var CloudRoaring = class _CloudRoaring {
    * `retention` untouched, so setting a policy and then honouring a right-to-erasure request mid-window produces
    * exactly that row, and deleting it would destroy the Art. 17 attestation and un-fence the name. By default a
    * segment that held nothing has its row deleted in the pass that retires it, since that row would only fence the name.
-   * Pass `purgeTombstones: false` to keep every tombstone, that row included.
+   * Pass `purgeTombstones: false` to keep every tombstone, that row included. On a backend whose registry reports
+   * `conditionalDelete` (AWS S3, Azure Blob, the local filesystem and memory, by default; GCS when you set `conditionalDelete: true`)
+   * the purge removes the row from the bucket for good, by a delete the store applies only to the version it judged,
+   * so a full sweep reads what is live or inside its grace rather than every name a namespace ever held; elsewhere,
+   * and for a row a release before 0.12 wrote, it leaves a tombstone. Each retirement files a pointer in the due index
+   * under the day its tombstone's grace ends, so `scan: 'index'` purges as well as retires.
    *
    * Needs the store built with a **backend** (throws {@link UnsupportedError} otherwise),
    * because retiring a segment deletes its storage objects. `now` defaults to the store's clock.
@@ -1471,6 +1612,13 @@ var CloudRoaring = class _CloudRoaring {
    * (throws {@link UnsupportedError} otherwise). `destroyed` (crypto-shredded) segments are skipped. Pair it with
    * the DR runbook (docs/guide/disaster-recovery.md).
    *
+   * A segment whose pointer names a missing object is the torn restore this reports; a cold `count()` of it still
+   * answers the number its row records, while a read of the object throws, so the count alone never shows it. With
+   * `summaries: true` it also opens each segment's current object (one tail read each) and reports a segment whose
+   * row's summary says another id count or metadata than the object holds as `summary-mismatch`, which is what a
+   * restore of the registry from another point than the bucket leaves a count to answer. A sealed summary is held
+   * against its object when this store has the key, and counted in `summariesUnchecked` when it does not.
+   *
    * It holds the registry rows it enumerates resident, at most 250,000 of them, and throws
    * `BudgetExceededError` past that rather than report a partial scan as a whole one. This method takes no
    * ceiling of its own: narrow the scan with `namespace`, or call `runConsistencyCheck` over the backend's
@@ -1478,7 +1626,10 @@ var CloudRoaring = class _CloudRoaring {
    */
   async checkConsistency(options = {}) {
     const deps = this.lifecycleDeps("checkConsistency");
-    return runConsistencyCheck({ storage: deps.storage, registry: deps.registry }, options);
+    return runConsistencyCheck(
+      { storage: deps.storage, registry: deps.registry, keystore: deps.keystore },
+      options
+    );
   }
   /**
    * **Export ("eject") every registered segment's current generation** through the injected `sink`, using only
@@ -1725,10 +1876,18 @@ var Segment = class _Segment {
     return this.timed("has", () => this.engine.has(this.ref, id));
   }
   /**
-   * Cardinality — summed from the `.crbm` index with **zero payload reads** on a loaded segment.
-   *
-   * What this trusts: the answer is the sum of the per-chunk cardinalities the index records, and no payload is
-   * decoded to confirm it. The index is checked for internal consistency when the object is opened (each key in
+   * Cardinality of the generation this handle reads: **one registry read when cold, none when warm, and no read of the
+   * object**, with **zero payload reads**. The registry row records the id count of the generation it names, written
+   * by the write that made it current, and a count answers from that. A row with no summary it can use (one written
+   * before rows carried it, one that names another generation, a sealed one that does not open) sends the count to the
+   * `.crbm` index, summed with a tail read of the object. A segment whose pointer names a missing object (a torn
+   * restore) still counts the row's number, while a read of the object throws; `checkConsistency` is what finds it.
+   *
+   * What this trusts: the row's summary, or the index's sum, and no payload is decoded to confirm it. The summary is
+   * used only for the generation it names, on an active row, and a sealed one only if it opens under the segment's
+   * key; it is held against the object whenever the object is opened anyway (a `has`, an `iterate`, a combine, a
+   * `pin()`), at no extra request, and a disagreement stops this store using it, and fails nothing. It is not
+   * confirmed on the cold path, so a party who can write the registry row can make a count wrong. The index is checked for internal consistency when the object is opened (each key in
    * range and ascending, each cardinality in `1..65536`, each payload inside the payload region, and, on an
    * unencrypted object, the footer's chunk count and total agreeing with the index), and a corrupt index that is
    * still internally consistent yields a wrong count. `iterate()` and the combines decode the payloads, whose
@@ -1738,6 +1897,24 @@ var Segment = class _Segment {
     if (this.expired()) return Promise.resolve(0);
     return this.timed("count", () => this.engine.count(this.ref));
   }
+  /**
+   * What the generation this handle reads is, from one resolution: its number, its id count and the metadata it
+   * was loaded with (absent when it has none). It is what answers {@link Segment.count}, so the three describe one
+   * generation and cannot straddle a publish. One registry read when cold, none while warm, and none on a pinned
+   * handle, which answers for the generation it pinned. A segment with no generation, and an expired handle,
+   * answer `{ generation: null, cardinality: 0 }`.
+   *
+   * Trust is as for `count()`: the registry row's word, not confirmed against the object until the object is
+   * opened, when a disagreement makes this process stop using that row's summary.
+   *
+   * ```ts
+   * const { generation, cardinality, metadata } = await store.segment('active-30d').stat();
+   * ```
+   */
+  async stat() {
+    if (this.expired()) return { generation: null, cardinality: 0 };
+    return this.engine.stat(this.ref);
+  }
   /**
    * Every id, ascending, streamed one chunk at a time. Pass a range to read part of the segment: the ids in
    * `(after, through]`, fetching only the chunks the range overlaps. The per-op budget is charged for every chunk in