@cloudbitmaps/roaring 0.11.2 → 0.13.0

package/dist/index.d.ts

@@ -23,7 +23,7 @@
  * `checkConsistency`, `exportSegments` — reuse the store's own drivers, so you never re-pass them (they need the
  * store built with a backend). See the README and the getting-started guide.
  */
-import type { BudgetOption, GenerationEntry, LoadGuard, LoadOptions, LoadRefusal, LoadResult, RollbackResult, Clock, StorageChunkSource, ConsistencyReport, CostReport, DropResult, EstimateInput, ExportManifest, ExportOptions, ExportSink, IAuditSink, IStorageDriver, IKeystore, IMetricsSink, StorageBackend, PricingProfile, RetentionPolicy, RetireExpiredOptions, RetireExpiredResult, RetryPolicy, Rng, SetRetentionResult, PinnedAt, IdRange, SegmentRef, Workload } from '@cloudbitmaps/core';
+import type { BudgetOption, GenerationEntry, GenerationMetadata, LoadGuard, LoadInput, LoadOptions, LoadRefusal, LoadResult, RollbackResult, Clock, StorageChunkSource, ConsistencyReport, CostReport, DropResult, EstimateInput, ExportManifest, ExportOptions, ExportSink, IAuditSink, IStorageDriver, IKeystore, IMetricsSink, StorageBackend, PricingProfile, RetentionPolicy, RetireExpiredOptions, RetireExpiredResult, RetryPolicy, Rng, SetRetentionResult, PinnedAt, IdRange, SegmentRef, Workload } from '@cloudbitmaps/core';
 import type { SegmentInfo } from '@cloudbitmaps/core';
 /**
  * Wiring for a {@link CloudRoaring} store. **Only `storage` is required** — the minimal call is
@@ -68,10 +68,14 @@ export interface CloudRoaringOptions {
      * Resilience: by default every read that answers a query retries **transient** faults (throttling, 5xx, dropped
      * connections) with bounded, jittered exponential backoff (see {@link DEFAULT_RETRY_POLICY}): `has`, `count`,
      * `iterate` and the combines, the `*Into` verbs' reads of their operands included, a pinned handle's reads and
-     * `pin()` itself. Writes are not retried, and nor are an erasure's reads, a load's guard read, or the calls that
-     * read the registry or list the bucket directly (`exists`, `segments`, `generations`, `getRetention`, and the
-     * registry scan `subjectReport`, `exportSegments` and `checkConsistency` start from): they report a transient fault to their caller, because a conditional write that lands and then loses its response would, replayed,
-     * report its own write as a conflict. Pass a partial policy to tune it — anything you leave out keeps its
+     * `pin()` itself, and the reads a write makes along the way: a load's guard read of the current generation, and an
+     * erasure's reads of the generation it rewrites, of the one it wrote and of any other that may still hold the id.
+     * This option does not govern writes, nor the calls that read the registry or list the bucket directly (`exists`,
+     * `segments`, `generations`, `getRetention`, and the registry scan `subjectReport`, `exportSegments` and
+     * `checkConsistency` start from): they report a transient fault to their caller, because a conditional write that
+     * lands and then loses its response would, replayed blindly, report its own write as a conflict. A write is
+     * retried only where that is safe: a load's registry write that gets no answer is settled by reading the row,
+     * and a throttled write-once object is sent again by the S3 and GCS drivers. Pass a partial policy to tune it — anything you leave out keeps its
      * default — or `false` to turn the read retry off (e.g. if your injected client already retries). A GCS download is retried by
      * the GCS driver whatever this says.
      * Deterministic errors (`ValidationError`/`IntegrityError`/`WriteConflictError`/…) are never retried by this
@@ -138,7 +142,8 @@ export interface CacheOptions {
      */
     readonly readerMax?: number;
     /**
-     * Aggregate byte ceiling on the parsed `.crbm` indices the open readers hold (default 64 MiB) — the byte half
+     * Aggregate byte ceiling on what the open readers hold, their parsed `.crbm` indices and the metadata a
+     * generation carries (default 64 MiB) — the byte half
      * of the memory bound, complementing the {@link CacheOptions.readerMax} *count* bound. A wide/dense segment's
      * parsed index can reach about 1.3 MB, so a count-only bound could let the open readers pin over a GB and blow a small
      * heap (e.g. a 128 MB Lambda); this evicts the least-recently-used reader once the summed index footprint
@@ -310,9 +315,10 @@ export interface MaterializeResult {
     readonly cardinality: number;
     /**
      * What the destination held when the guard judged it — `null` when it had no current generation, **or when
-     * no bound needed the read**. The read costs an object-header fetch, so it is taken only when a bound will
-     * use it: `allowEmpty: true` with no `guard.minRetained` skips it, and this is `null` even though `dest`
-     * was non-empty.
+     * no bound needed it**. It is taken only when a bound will use it: `allowEmpty: true` with no
+     * `guard.minRetained` skips it, and this is `null` even though `dest` was non-empty. When the destination's row
+     * carries a summary of its current generation the count comes from the row and the object is not read; a row
+     * written before rows carried a summary costs one object-header fetch.
      */
     readonly cardinalityBefore: number | null;
     /** Non-empty chunks in the generation. */
@@ -333,6 +339,7 @@ export declare class CloudRoaring {
     private readonly retryOptions;
     private readonly crbmSource;
     private readonly clock;
+    private readonly rng;
     private readonly metrics;
     private readonly storageDriver;
     private readonly registry;
@@ -360,7 +367,7 @@ export declare 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
@@ -512,7 +519,8 @@ export declare 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 —
@@ -567,13 +575,20 @@ export declare 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
@@ -590,7 +605,14 @@ export declare class CloudRoaring {
         allowForward?: boolean;
     }): Promise<RollbackResult>;
     /**
-     * **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
@@ -604,6 +626,14 @@ export declare 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
@@ -627,16 +657,35 @@ export declare 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).
      */
-    load(ref: SegmentRef, ids: Iterable<number> | AsyncIterable<number>, options?: LoadOptions): Promise<LoadResult>;
+    load(ref: SegmentRef, input: LoadInput, options?: LoadOptions): Promise<LoadResult>;
     /**
      * **Dispose of a segment — tombstone it, then delete its storage objects.** Irreversible.
      *
@@ -662,9 +711,12 @@ export declare 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
@@ -759,6 +811,12 @@ export declare 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
@@ -766,7 +824,12 @@ export declare 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.
@@ -852,6 +915,13 @@ export declare 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
@@ -860,6 +930,7 @@ export declare class CloudRoaring {
     checkConsistency(options?: {
         namespace?: string;
         concurrency?: number;
+        summaries?: boolean;
     }): Promise<ConsistencyReport>;
     /**
      * **Export ("eject") every registered segment's current generation** through the injected `sink`, using only
@@ -887,7 +958,13 @@ export declare class CloudRoaring {
  * in `(after, through]` and fetches only the chunks the range overlaps, as {@link Segment.iterate} does.
  */
 export interface BaseCombineOptions extends IdRange {
-    /** Max chunk keys resolved concurrently — bounds the Storage footprint. A positive integer. */
+    /**
+     * Max chunk keys resolved concurrently — bounds the Storage footprint (about `concurrency × operands` chunks in
+     * flight). A positive integer; default 32. The window opens 8 keys wide (or `concurrency`, if lower) and widens
+     * as keys are taken, so a read that stops early fetches no more than a few keys ahead; one that runs to the end
+     * spends nearly all of its round trips at the full width. A read that stops early has requested up to
+     * `concurrency` keys per operand past the last one it used.
+     */
     readonly concurrency?: number;
     /** Override the store's per-op denial-of-wallet budget for this call (`false` lifts it). */
     readonly budget?: BudgetOption;
@@ -955,14 +1032,22 @@ export interface MaterializeOptions extends CombineOptions {
     readonly allowEmpty?: boolean;
     /** Refuse an implausible result rather than publish it. Same bounds, and same meaning, as on `load()`. */
     readonly guard?: LoadGuard;
+    /**
+     * Metadata for the generation this call publishes, under the rules and with the meaning of
+     * {@link LoadOptions.metadata}: small, immutable, published with the pointer, never a subject's id. A value that
+     * breaks a rule throws {@link ValidationError} before any request is made.
+     */
+    readonly metadata?: GenerationMetadata;
     /**
      * Generations to keep below the new pointer — see {@link LoadOptions.keep}. A value that is not a non-negative
      * integer throws `ValidationError`.
      *
-     * **Defaults to keeping everything**, unlike `load()`, which keeps 1 and collects the rest. An operator's
+     * **Defaults to keeping everything**, unlike `load()`, which keeps 1 and collects what it supersedes. An operator's
      * recovery story can depend on a materialisation collecting nothing: `rollbackSegment` refuses a target that
      * has been collected. Pass a number to collect on the way through; `0` keeps only the
-     * generation this call publishes.
+     * generation this call publishes. It collects by listing the destination, so it clears every generation below the
+     * new one beyond `keep`, however many earlier calls kept, where a `load()` deletes by name the one generation its
+     * publish pushes out of the window.
      */
     readonly keep?: number;
 }
@@ -974,6 +1059,14 @@ export interface MaterializeOptions extends CombineOptions {
  * solves the same problem the same way, by taking {@link BaseCombineOptions}.
  */
 export type AndNotIntoOptions = Omit<MaterializeOptions, 'exclude'>;
+/** What {@link Segment.stat} answers: the generation a handle reads, its id count and its metadata. */
+export interface SegmentStat {
+    /** The generation read, or `null` when the segment has none. */
+    readonly generation: number | null;
+    readonly cardinality: number;
+    /** The metadata the generation was loaded with; absent when it has none. */
+    readonly metadata?: GenerationMetadata;
+}
 /**
  * A handle bound to one segment — the read verbs, plus the three `*Into` verbs that write a **new generation**
  * of another segment.
@@ -1122,16 +1215,39 @@ export declare class Segment {
     /** Membership: one chunk — the cache, else one ranged GET. Throws {@link ValidationError} on a bad id. */
     has(id: number): Promise<boolean>;
     /**
-     * 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
      * structure is checked.
      */
     count(): Promise<number>;
+    /**
+     * 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();
+     * ```
+     */
+    stat(): Promise<SegmentStat>;
     /**
      * 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
@@ -1173,7 +1289,7 @@ export declare class Segment {
      * Chunk-skipping intersection: stream the ids in **this** segment AND every segment in `others`, ascending.
      * Fetches only the Storage chunks present in *all* operands (a key absent from any operand contributes nothing
      * and is never downloaded), streaming under a bounded in-flight window — so the Storage footprint stays small
-     * (Lambda-friendly) regardless of segment size. Pass `concurrency` to tune that window (a positive integer).
+     * (Lambda-friendly) regardless of segment size. Pass `concurrency` to tune that window (a positive integer, 32 by default).
      * AND is commutative, so `a.intersect([b])` and `b.intersect([a])` yield the same ids. Pass `budget` to
      * override the store's per-op denial-of-wallet budget for this call (or `false` to lift it).
      */
@@ -1243,4 +1359,4 @@ export declare class Segment {
     }): Promise<CostReport>;
 }
 export { MemoryStorage, LocalFsStorage, CrbmStorageChunkSource, destroySegment, eraseNamespace, excludingReservedRows, readRetentionPolicy, MIN_EXPIRES_AT_MS, InProcessKeystore, NodeAead, aadFor, CloudRoaringError, ValidationError, WriteConflictError, IntegrityError, NotFoundError, UnsupportedError, CapabilityError, TransientError, KeyUnavailableError, BudgetExceededError, isCloudRoaringError, isWriteConflictError, isTransientError, isNotFoundError, isIntegrityError, isValidationError, CrbmReader, BufferReader, CountingMetricsSink, RecordingAuditSink, DEFAULT_RETRY_POLICY, AWS_US_EAST_1_ONDEMAND, ELASTICACHE_REDIS_US_EAST_1_ONDEMAND, ONE_REDIS_HA_CLUSTER, } from '@cloudbitmaps/core';
-export type { Aead, AeadSealed, AuditEvent, BlobReader, BlobSink, Budget, BudgetOption, ChunkRef, Clock, CodecBitmap, CodecInterface, ConsistencyErrorEntry, ConsistencyIssue, ConsistencyReport, CostReport, CrbmCrypto, CrbmReaderOptions, CrbmStorageChunkSourceOptions, DestroyResult, DropResult, EraseDeps, EstimateInput, ExportFailure, ExportFormat, ExportManifest, ExportOptions, ExportSink, ExportWriter, ExportedSegment, GenKey, GenerationEntry, GovernanceMeta, IAuditSink, IKeystore, IMetricsSink, IRegistryDriver, IStorageDriver, IdRange, InProcessKeystoreOptions, LoadGuard, LoadOptions, LoadRefusal, LoadResult, LocalFsStorageOptions, MemoryStorageOptions, MetricEvent, MetricOpName, MetricsSnapshot, NewRegistryRecord, PinnedAt, PinnedObject, PricingProfile, RedisNodeType, RedisSizing, RegCaps, RegistryPatch, RegistryRecord, RegistryStatus, RetentionPolicy, RetireEntry, RetireExpiredOptions, RetireExpiredResult, RetryPolicy, Rng, RollbackResult, SegmentInfo, SegmentRef, SegmentSize, SegmentSizing, SetRetentionResult, StorageBackend, StorageCaps, StorageChunkSource, Token, Workload, WrappedDek, } from '@cloudbitmaps/core';
+export type { Aead, AeadSealed, AuditEvent, BlobReader, BlobSink, Budget, BudgetOption, ChunkRef, Clock, CodecBitmap, CodecInterface, ConsistencyErrorEntry, ConsistencyIssue, ConsistencyReport, CostReport, CrbmCrypto, CrbmReaderOptions, CrbmStorageChunkSourceOptions, DestroyResult, ClearRegistrySummary, DropResult, EncodedChunk, EraseDeps, EstimateInput, ExportFailure, ExportFormat, ExportManifest, ExportOptions, ExportSink, ExportWriter, ExportedSegment, GenKey, GenerationEntry, GenerationMetadata, GovernanceMeta, IAuditSink, IKeystore, IMetricsSink, IRegistryDriver, IStorageDriver, IdRange, InProcessKeystoreOptions, LoadGuard, LoadInput, LoadOptions, LoadRefusal, LoadResult, LocalFsStorageOptions, MemoryStorageOptions, MetricEvent, MetricOpName, MetricsSnapshot, NewRegistryRecord, PinnedAt, PinnedObject, PortableBitmap, PricingProfile, RedisNodeType, RedisSizing, RegCaps, RegistryPatch, RegistryRecord, RegistryStatus, RegistrySummary, RetentionPolicy, RetireEntry, RetireExpiredOptions, RetireExpiredResult, RetryPolicy, Rng, RollbackResult, SealedRegistrySummary, SegmentInfo, SegmentRef, SegmentSize, SegmentSizing, SetRetentionResult, StorageBackend, StorageCaps, StorageChunkSource, Token, Workload, WrappedDek, } from '@cloudbitmaps/core';