@cloudbitmaps/roaring 0.22.0 → 0.23.0

package/dist/index.d.ts

@@ -25,9 +25,36 @@
  */
 import type { BudgetOption, GenerationEntry, GenerationMetadata, LoadGuard, LoadInput, LoadOptions, LoadRefusal, LoadResult, RollbackResult, Clock, Entropy, ConsistencyReport, DropResult, ExportManifest, ExportOptions, ExportSink, IAuditSink, IMetricsSink, RetentionPolicy, RetireExpiredOptions, RetireExpiredResult, RetryPolicy, Rng, SetRetentionResult, PinnedAt, SegmentRef } from '@cloudbitmaps/core';
 import type { IKeystore, IStorageDriver, StorageBackend, StorageChunkSource } from '@cloudbitmaps/core/driver-kit';
+import type { DestroyResult, EraseDeps } from '@cloudbitmaps/core';
 import type { SegmentInfo } from '@cloudbitmaps/core';
+import type { PreflightResult } from '@cloudbitmaps/core';
 import type { Expr, MaterializeManyFeedRecord, MaterializeManyStats } from '@cloudbitmaps/core';
 import { deserializePortable } from './roaring-codec.js';
+/**
+ * Crypto-shred one segment. It cannot be undone through the library (a registry restore to a point before it can).
+ * `confirmSegment` must equal `ref.segment` (a guard against an accidental destroy). A non-encrypted segment is
+ * rejected unless you opt in via `allowCleartext`: it has no key to shred, its Storage bytes stay readable, and the
+ * call emits a `segment.tombstone` audit event instead of `segment.erase`. A write that gets no answer is settled by
+ * reading the row back, waiting between reads on `deps.clock` (the system clock by default).
+ */
+export declare function destroySegment(ref: SegmentRef, deps: EraseDeps, options: {
+    confirmSegment: string;
+    allowCleartext?: boolean;
+    audit?: IAuditSink;
+}): Promise<DestroyResult>;
+/**
+ * Crypto-shred every segment in a namespace. It cannot be undone through the library. `confirmNamespace` must equal
+ * `namespace`. Returns a per-segment result, in the order the registry listed the segments, which is unspecified. A
+ * write that gets no answer is settled as {@link destroySegment}'s is.
+ */
+export declare function eraseNamespace(namespace: string, deps: EraseDeps, options: {
+    confirmNamespace: string;
+    allowCleartext?: boolean;
+    audit?: IAuditSink;
+    maxScanSegments?: number;
+}): Promise<{
+    destroyed: DestroyResult[];
+}>;
 /**
  * Wiring for a {@link CloudRoaring} store. **Only `storage` is required** — the minimal call is
  * `new CloudRoaring({ storage: backend })`. A backend resolves generations with one strong read, reads
@@ -76,7 +103,8 @@ export interface CloudRoaringOptions {
      * attempt, capped at 2 s, with full jitter): `has`, `count`,
      * `iterate` and the combines, the `*Into` verbs' reads of their operands included, a pinned handle's reads and
      * `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.
+     * erasure's reads of the generation it rewrites, of the one it wrote and of any other that may still hold the id, and
+     * the search `subjectReport` and `eraseSubject` make under a destroyed segment (its listing of the bucket included).
      * 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
@@ -114,9 +142,12 @@ export interface CloudRoaringOptions {
 }
 /** {@link CloudRoaringOptions.cache} — the memory and staleness bounds. */
 export interface CacheOptions {
-    /** Ceiling on decoded Storage chunks held in RAM (default 1024). */
+    /** Ceiling on decoded Storage chunks held in RAM (default 1024): an integer of at least 1, else `ValidationError`. */
     readonly maxChunks?: number;
-    /** Optional TTL on cached chunks (ms). Omit to keep a chunk until it is evicted by the count bound. */
+    /**
+     * Optional TTL on cached chunks (ms): a finite number above 0, else `ValidationError`. Omit to keep a chunk until it is
+     * evicted by the count bound.
+     */
     readonly ttlMs?: number;
     /**
      * How long (ms) the store trusts a segment's resolved `currentGen` before re-resolving it on the next read
@@ -144,7 +175,8 @@ export interface CacheOptions {
     readonly genTtlMs?: number;
     /**
      * Ceiling on how many segments' `.crbm` readers (each holding a parsed index) the store keeps open at once
-     * (default 1024) — the steady-state memory bound for a long-running server that reads across many segments.
+     * (default 1024; an integer of at least 1, else `ValidationError`) — the steady-state memory bound for a long-running
+     * server that reads across many segments.
      * Past it the least-recently-used segment's reader is evicted; re-opening it later is one cheap tail GET. With a
      * timed refresh ({@link CacheOptions.genTtlMs} above 0, and a backend) the store also keeps up to 8 times this many
      * segments' resolutions (what it read of each segment's row: never an unwrapped key, though the wrapped keys are in
@@ -167,7 +199,7 @@ export interface CacheOptions {
      * heap (e.g. a 128 MB Lambda); this evicts the least-recently-used reader once the summed weight
      * would exceed the ceiling — whichever of the count/byte bounds binds first. A sixteenth of it (4 MiB by default)
      * bounds the segments' resolutions a store with a timed refresh keeps besides. Lower it for memory-tight
-     * deployments that read across wide segments. A ceiling below two readers' weight (about 7.7 KB for tiny ones) keeps one reader open at a time. Applies whenever the store builds its own read path.
+     * deployments that read across wide segments. An integer of at least 1, else `ValidationError`. A ceiling below two readers' weight (about 7.7 KB for tiny ones) keeps one reader open at a time. Applies whenever the store builds its own read path.
      */
     readonly readerMaxBytes?: number;
 }
@@ -181,11 +213,13 @@ export interface EncryptionOptions {
     readonly keystore?: IKeystore;
     /**
      * Refuse to touch a **cleartext** segment — a guard against silently reading, or writing, data that should be
-     * encrypted. Needs a backend, for the same reason as {@link EncryptionOptions.keystore}. Off by default.
+     * encrypted. Needs a backend, for the same reason as {@link EncryptionOptions.keystore}. Off by default. Exactly a
+     * boolean: any other value, a truthy string included, throws `ValidationError`.
      *
      * It refuses **writes** as well as reads, which is easy to miss: the `*Into` verbs and `eraseSubject` both
      * carry it into their write path, so on a cleartext segment a materialisation throws and an erasure records
-     * `note: 'error: requireEncryption: …'` in its ledger rather than erasing. And since a segment's encryption is
+     * `note: 'error: KeyUnavailableError: requireEncryption: …'` in its ledger rather than erasing, whatever id it erases and
+     * whether or not the id is in the segment: it does not read the segment. And since a segment's encryption is
      * decided at its **first** generation, this cannot be switched on for a segment that already has one — load
      * into a new encrypted segment and drop the old one.
      */
@@ -229,24 +263,39 @@ export interface SeamOptions {
  * passed here is refused with {@link ValidationError}.
  */
 export interface SegmentOptions {
+    /** The segment's namespace, or `undefined` for the default one. */
     readonly namespace?: string;
 }
 /** A segment reference in a subject report / erasure ledger. */
 export interface SubjectSegmentRef {
+    /** The segment's name. */
     readonly segment: string;
+    /** The segment's namespace, or `undefined` for the default one. */
     readonly namespace?: string;
 }
-/** Result of {@link CloudRoaring.subjectReport} — the segments an id is a member of (over registered segments). */
+/** Result of {@link CloudRoaring.subjectReport}: the segments an id is a member of, and the destroyed segments whose leftover objects hold it. */
 export interface SubjectReport {
+    /** The id the report is about. */
     readonly id: number;
     /** The registered segments the id is currently a member of. */
     readonly segments: SubjectSegmentRef[];
+    /**
+     * The destroyed segments whose leftover objects still hold the id in the clear: one destroyed with `allowCleartext`,
+     * dropped while a load wrote an object its sweep did not catch, or crypto-shredded over an object a cleartext writer
+     * left. No read resolves them, so the id is a member of none, but its bytes are in the bucket, and `eraseSubject`
+     * deletes them. A crypto-shredded segment's own objects are sealed under a key no row holds and are never a holder,
+     * so it is listed only when an object left under it in the clear holds the id. A destroyed segment with no
+     * object left is not listed either. `[]` when none.
+     */
+    readonly tombstones: SubjectSegmentRef[];
     /** How many registered segments were scanned (the completeness denominator). */
     readonly scannedSegments: number;
 }
 /** One segment's entry in an erasure ledger (see {@link EraseSubjectResult}). */
 export interface SubjectErasureEntry {
+    /** The segment's name. */
     readonly segment: string;
+    /** The segment's namespace, or `undefined` for the default one. */
     readonly namespace?: string;
     /**
      * True iff the id **was** in the segment and **no generation of it holds the id now** — not the current one, not
@@ -269,15 +318,15 @@ export interface SubjectErasureEntry {
      * no pointer (a purge and re-creation, or a hand-made write), while the call was in flight, so **this call** did
      * not erase the id;
      * re-run against the new generation, which erases it if it is still there and reports nothing for the segment
-     * if the racing writer already removed it. `` `error: <message>` `` — an isolated per-segment fault
+     * if the racing writer already removed it. `` `error: <class>: <message>` `` — an isolated per-segment fault, named by its error's class
      * (per-segment faults are recorded so one segment can't discard the whole ledger); re-run after fixing the
      * fault. A budget refusal is one of these: the segment's generations did not fit `budget`, so it was not finished;
      * re-run with a higher `budget`. A fault that landed once part of the work was already done — a Storage `delete` fault, a collect that
      * could not prove the segment was still the same one, or a generation still holding the id when the bucket was
      * listed at the end, whether or not a rewrite was published first — also re-runs, but **read what the re-run
      * says**: it usually reports `erased: true` against the generation it found the id in, it reports
-     * nothing at all if a racing collector took that generation first (the bit is gone, but no run holds a
-     * receipt for it), and if the segment's row has since been purged it is no longer scanned at all — anything
+     * nothing at all if a racing collector took that generation first, or this call's own delete of it landed after a
+     * fault the call could not settle (the bit is gone, but no run holds a receipt for it), and if the segment's row has since been purged it is no longer scanned at all — anything
      * left in its bucket is an orphan, which `store.generations(ref)` lists and `store.dropSegment(ref, {
      * confirmSegment })` deletes; `checkConsistency` and the collection a load runs read rows, so neither reaches it.
      * **Segments the id is not in
@@ -291,6 +340,7 @@ export interface SubjectErasureEntry {
  * return value only (no library-side persistence): persist it / route it to your audit sink as you see fit.
  */
 export interface EraseSubjectResult {
+    /** The id that was erased. */
     readonly id: number;
     /** Per-segment records for the segments the id was found in (absent segments are not listed). */
     readonly erasedFrom: SubjectErasureEntry[];
@@ -413,6 +463,10 @@ export type MaterializeManyOutcome = MaterializeResult | {
 export interface MaterializeManyRun {
     /** One per output, in the order given: one output's refusal or error never stops another. */
     readonly outputs: MaterializeManyOutcome[];
+    /**
+     * What the call did: the groups it ran, its requests by class, its budget and memory, and the figures of each operand
+     * and output.
+     */
     readonly stats: MaterializeManyStats;
 }
 /**
@@ -420,6 +474,7 @@ export interface MaterializeManyRun {
  * judged against its `dest` as its publish would be, and nothing is written. See {@link CloudRoaring.materializeMany}.
  */
 export interface MaterializeManyDryRunOptions extends MaterializeManyOptions {
+    /** `true` makes the call a dry run: every output is computed and judged, and nothing is written. */
     readonly dryRun: true;
 }
 /**
@@ -428,7 +483,9 @@ export interface MaterializeManyDryRunOptions extends MaterializeManyOptions {
  * run for a publish.
  */
 export interface MaterializeDryRunResult {
+    /** Always `true`: the output was computed and judged, not published. */
     readonly dryRun: true;
+    /** Always `false`: nothing was written. */
     readonly published: false;
     /** Distinct ids the output would hold. */
     readonly cardinality: number;
@@ -449,6 +506,10 @@ export type MaterializeManyDryRunOutcome = MaterializeDryRunResult | {
 export interface MaterializeManyDryRun {
     /** One per output, in the order given. */
     readonly outputs: MaterializeManyDryRunOutcome[];
+    /**
+     * What the dry run did: the groups it ran, its requests by class, its budget and memory, and the figures of each
+     * operand and output.
+     */
     readonly stats: MaterializeManyStats;
 }
 /** What an `*Into` verb wrote: the new generation of the destination, and whether it became current. */
@@ -512,6 +573,7 @@ export declare class CloudRoaring {
     private readonly metrics;
     private readonly storageDriver;
     private readonly registry;
+    private readonly backend;
     private readonly keystore;
     private readonly requireEncryption;
     /** Resolved store-level per-op budget (null = disabled); the admin scans use it, with a per-op override. */
@@ -535,6 +597,19 @@ export declare class CloudRoaring {
      * no `next` or a keystore with no `createDek` builds a store that throws a raw `TypeError` at its first load or read.
      */
     private static rejectHollowSeams;
+    /**
+     * Refuse a `cache` or `encryption` value that can never be honoured, by the name the caller wrote. The sizes reach
+     * the caches under their own internal names, so left to them an error would name `maxEntries` or `maxBytes`; and
+     * `encryption.required` must be exactly a boolean, since the read path took a truthy string for `true` while every
+     * write path did not, which refused cleartext reads and still wrote cleartext.
+     */
+    private static rejectBadValues;
+    /**
+     * Builds a store. Only `storage` is required: pass a backend such as `S3Storage` or `MemoryStorage`. `cache`,
+     * `encryption`, `retry`, `metrics`, `budget` and `seams` tune it. An option it does not take, a `cache` size or `ttlMs`
+     * that is not a usable number, an `encryption.required` that is not a boolean, or a seam missing a method the store
+     * calls, throws `ValidationError`.
+     */
     constructor(options: CloudRoaringOptions);
     /**
      * The write-side deps, from the store's own drivers, for the lifecycle helpers and the `*Into` verbs. Requires
@@ -743,21 +818,50 @@ export declare class CloudRoaring {
      * tax every load for a rare request; this admin scan is `O(registered segments)` and touches no hot path. Needs
      * a storage backend (throws {@link UnsupportedError} otherwise).
      *
+     * **Scope: one `namespace`, or `{ allNamespaces: true }`, never both** (both throws `ValidationError`, as does
+     * neither). A segment loaded with no `namespace` is in no namespace you can name: only `{ allNamespaces: true }`
+     * reaches it. `'_default'`, the label the export tool and the disaster-recovery samples print, and the bucket's
+     * object keys use, for such a segment, is an ordinary namespace name here, and passing it scans a namespace of that name, not those segments.
+     *
      * **Current as of the registry row, not as of the reader's cache.** Each segment's resolved generation is
      * compared with the row the scan listed, and a segment whose cached generation differs is re-resolved before the
      * read, so a load or an erasure from another process shows at once — whatever `cache.genTtlMs` is, `0` included.
      * The comparison is on the generation **and** the row's token, so a segment retired, purged and loaded again from
      * generation 0 while this store held its old generation 0 is told apart too.
-     */
-    subjectReport(id: number, options?: {
-        namespace?: string;
-        allNamespaces?: boolean;
+     *
+     * **A destroyed segment is searched as {@link CloudRoaring.eraseSubject} searches it.** No read resolves a
+     * tombstone, so the id is a member of none, but a cleartext `destroySegment` (`allowCleartext`), or a `dropSegment`
+     * whose sweep missed an object a load was still writing, leaves objects anyone with bucket access can read. Each
+     * object left under the tombstone is opened newest first until one holds the id, and the segment is then listed in
+     * `tombstones`, never in `segments`. A crypto-shredded segment's own objects are sealed under a key no row holds and are
+     * never a holder: it is listed only when an object left under it in the clear holds the id. The cost is one listing per destroyed segment in scope (1 request when nothing is left), and for each
+     * object opened a tail read and, where its index lists the id's chunk, a chunk read (two tail reads for an encrypted
+     * object, which never holds the id): 7 requests for a cleartext destroy with 3 objects, 21 for 10. The budget is
+     * charged one unit for each object opened past the one the row names, as `eraseSubject` charges. A report that runs
+     * out, or whose listing or read fails after the store's retry, rejects rather than under-reporting, so one leftover
+     * object that cannot be opened makes every report over its scope reject until it is removed (`generations(ref)` lists
+     * what is left, `dropSegment` deletes it). A report refused for budget while it searches a destroyed segment reports
+     * `spent` as `limit + 1`, a lower bound.
+     */
+    subjectReport(id: number, options: {
         concurrency?: number;
         budget?: BudgetOption;
-    }): Promise<SubjectReport>;
+    } & ({
+        namespace: string;
+        allNamespaces?: false;
+    } | {
+        allNamespaces: true;
+        namespace?: undefined;
+    })): Promise<SubjectReport>;
     /**
      * **Subject erasure (GDPR Art. 17): remove an id from every segment it's in, with the bit physically gone
-     * from the bucket on return.**
+     * from the bucket on return for each segment the ledger reports `erased: true`.** A noncurrent version, a replica
+     * or a backup keeps the old object until its own lifecycle removes it.
+     *
+     * **Scope: one `namespace`, or `{ allNamespaces: true }`, never both** (both throws `ValidationError`, as does
+     * neither). A segment loaded with no `namespace` is in no namespace you can name: only `{ allNamespaces: true }`
+     * reaches it. `'_default'`, the label the export tool and the disaster-recovery samples print, and the bucket's
+     * object keys use, for such a segment, is an ordinary namespace name here, and passing it scans a namespace of that name, not those segments.
      *
      * For each **registered** segment the id is a member of, `eraseIdFromSegment` rewrites the current generation
      * without the id — every chunk streamed through, one bit cleared — publishes the rewrite **fenced on the
@@ -822,21 +926,27 @@ export declare class CloudRoaring {
      * `O(registered segments + superseded generations)`, no hot-path cost: a segment whose current generation lacks
      * the id is searched generation by generation, one open for each other generation in its bucket, and with the
      * keep-everything default of the `*Into` verbs that is one per generation the segment ever had. The per-op
-     * `budget` is charged one unit for each segment and one for each generation opened beyond the one its row names,
-     * so a fleet with long histories can exhaust it where the segment count alone would not. A segment that does is
+     * `budget` is charged one unit for each segment and one for each generation opened beyond the one its row names, so
+     * a fleet with long histories can exhaust it where the segment count alone would not. A generation is charged at its
+     * first open only: a later open of it in the call, a retry of a failed read included, costs no more units. A segment
+     * that exhausts the budget is
      * reported `erased: false` with an `error:` note, before it deletes anything (the one refusal that can come after a
      * rewrite is the last check for a generation a concurrent writer left behind), and the
      * rest of the scan continues: the call itself does not throw for it. Per-subject crypto-shred is infeasible (a subject's bit is
      * co-mingled in a shared container), so this is the single-subject erasure route; whole-segment/tenant erasure
      * is `dropSegment` / the `destroySegment`/`eraseNamespace` free functions.
      */
-    eraseSubject(id: number, options?: {
-        namespace?: string;
-        allNamespaces?: boolean;
+    eraseSubject(id: number, options: {
         audit?: IAuditSink;
         concurrency?: number;
         budget?: BudgetOption;
-    }): Promise<EraseSubjectResult>;
+    } & ({
+        namespace: string;
+        allNamespaces?: false;
+    } | {
+        allNamespaces: true;
+        namespace?: undefined;
+    })): Promise<EraseSubjectResult>;
     private eraseSubjectRun;
     /**
      * Every generation still in the bucket for this segment, ascending, with the current one marked.
@@ -846,6 +956,7 @@ export declare class CloudRoaring {
      * choose from, which is the reason to look at it. One registry read and one listing; it does not open the objects.
      * Each entry says whether the row knows the generation (`known`): a known generation needs no `allowUnknown`; an unknown
      * one does, except below a row's pointer when the row has no usable record or the target is older than a full one reaches.
+     * No entry is `current` on a destroyed segment: its row keeps the pointer it had, but no read resolves through it.
      *
      * Needs a backend.
      */
@@ -925,8 +1036,9 @@ export declare class CloudRoaring {
      * {@link ValidationError} before any request to storage, and a known one whose object carries another checksum than
      * the recorded one throws {@link IntegrityError}, with or without a keystore, since the footer is in the clear. A
      * generation not in the bucket (collected, or never written) throws `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
+     * destroyed segment (crypto-shredded, destroyed in the clear or dropped) throws {@link ValidationError}, because no
+     * generation resolves through a destroyed row, 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, once one footer read finds its object in the bucket (and the one the row recorded); when the object is
      * gone it throws `NotFoundError` naming what is.
@@ -937,8 +1049,10 @@ export declare class CloudRoaring {
      * key (it holds none of the key's KEKs, one it holds does not unwrap it, or it throws `TransientError` or times out
      * as `AbortSignal.timeout()` and the AWS SDK report a timeout), a rollback onto a known generation still happens,
      * opening nothing, and the row carries no summary of the target. Any other failure of the keystore is
-     * thrown. A swap of the pointer that gets no answer is settled by reading the row: one that landed, the row being the
-     * one the swap leaves, is checked as any is, and otherwise its `TransientError` is thrown. After the swap the target's
+     * thrown. A swap of the pointer that gets no answer, or that meets a conflict, is settled by reading the row: one
+     * that landed, the row's pointer being at the target over a write this call sent (the write token, on a registry that
+     * reports them), is checked as any is, and otherwise its `TransientError` is thrown, or a `WriteConflictError` after
+     * a conflict, with no move recorded. After the swap the target's
      * footer is read once more, and the pointer put back if the object is gone or is another.
      *
      * It deletes nothing. The generations above the new pointer stay put — which is what makes this reversible —
@@ -978,8 +1092,14 @@ export declare class CloudRoaring {
      * 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 chunk for chunk what 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 }`.
+     * `RoaringBitmap32`, or a bitmap `deserializePortable` returned, 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 }`.
+     *
+     * Ids are held whole in memory before the object is written: the generation's bitmaps and a buffer of up to about 28
+     * MB. Ids that already ascend can be loaded with `sorted: true` instead, which writes them one chunk at a time while
+     * the object uploads, so the load holds one chunk and the writer's index (up to about 7 MiB, about 8 MiB for an
+     * encrypted segment, derived), whatever the segment's size, and writes the same object ({@link LoadOptions.sorted}).
      *
      * 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
@@ -1038,7 +1158,14 @@ export declare class CloudRoaring {
      * does the first load of a row that records none, which then records it. {@link LoadResult.collected} then names
      * what the pass deleted by name, and one name may have been gone already.
      *
-     * What it **throws** for is a fault rather than an outcome: invalid options or ids, and a crypto-shredded
+     * `input` cannot be a stream of this library (`iterate`, `everyNth`, `intersect`, `union`, `andNot`, as returned) that
+     * read the segment being loaded, from this store or one built over the same registry driver: a load publishes over
+     * whatever the segment is by then, so it would replace another writer's newer load with a result built from an older
+     * one, and it throws {@link ValidationError}. Ids read from another store over another backend load as any ids do.
+     * Two separate store instances over one bucket cannot be told apart, so this does not cover them; this release has no
+     * fenced in-place update, so write the result into a new segment and point readers at it.
+     *
+     * What it **throws** for is a fault rather than an outcome: invalid options or ids, and a destroyed
      * segment (`ValidationError`); a key the keystore cannot provide (`KeyUnavailableError`); a current generation
      * 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 fault in the collection's own reads, listing or deletes, or in the write
@@ -1062,11 +1189,14 @@ export declare class CloudRoaring {
      */
     load(ref: SegmentRef, input: LoadInput, options?: LoadOptions): Promise<LoadResult>;
     /**
-     * **Dispose of a segment — tombstone it, then delete its storage objects.** Irreversible.
+     * **Dispose of a segment — tombstone it, then delete its storage objects.** It cannot be undone through the
+     * library (a restore from the registry's and the bucket's versions or backups can).
      *
-     * The operation a rolling window needs: `destroySegment` crypto-shreds (bytes unreadable everywhere including
-     * backups, but still sitting in your bucket and still billed, and it requires encryption), while this one
-     * removes the storage and works on a cleartext segment. On an encrypted segment it does both.
+     * The operation a rolling window needs: `destroySegment` crypto-shreds (it removes the key from the segment's
+     * current registry row, so the bytes are unreadable everywhere, backups included, once no retained copy of the row
+     * holds the key or every KEK that wrapped it is destroyed; the objects still sit in your bucket and are still
+     * billed, and it requires encryption), while this one removes the storage and works on a cleartext segment. On an
+     * encrypted segment it does both.
      *
      * Pass `{ dryRun: true }` first — it reports the generations it *would* delete and changes nothing. That
      * matters more than the `confirmSegment` guard for anything automated, because in a loop the guard is the same
@@ -1112,8 +1242,9 @@ export declare class CloudRoaring {
         audit?: IAuditSink;
     }): Promise<DropResult>;
     /**
-     * **Record when this segment becomes eligible for retirement.** One registry write; nothing is deleted here,
-     * and nothing starts running. `retireExpired` is what acts on the policy, and **you** decide when that runs —
+     * **Record when this segment becomes eligible for retirement.** One policy write, plus a best-effort write of its
+     * due-index pointer (and removal of the old pointer when the expiry day moves); no data is deleted here, and
+     * nothing starts running. `retireExpired` is what acts on the policy, and **you** decide when that runs —
      * an EventBridge rule, a CronJob, a queue consumer, whatever your deployment already has. This library starts
      * no background thread (it has to work identically in a Lambda, an edge isolate and a long-lived server).
      *
@@ -1135,7 +1266,7 @@ export declare class CloudRoaring {
      * A value in the past is legal and means "eligible on the next sweep" — backfilling a policy onto existing
      * buckets is normal. A value below `1_000_000_000_000` (2001-09-09) is rejected: it is almost certainly epoch
      * **seconds**, which would read as long-expired and retire the segment on the next pass. Needs a storage
-     * backend (throws {@link UnsupportedError} otherwise), and refuses a crypto-shredded segment.
+     * backend (throws {@link UnsupportedError} otherwise), and refuses a destroyed segment.
      */
     setRetention(ref: SegmentRef, policy: RetentionPolicy): Promise<SetRetentionResult>;
     /**
@@ -1146,8 +1277,10 @@ export declare class CloudRoaring {
      */
     getRetention(ref: SegmentRef): Promise<RetentionPolicy | null | 'invalid'>;
     /**
-     * **Cancel a segment's expiry** so no sweep retires it. Returns whether a policy was actually removed (`false`
-     * when there was none). A separate verb from `setRetention` on purpose: "never expire" as a magic value passed
+     * **Cancel a segment's expiry** so no sweep retires it. Returns whether this call removed a policy (`false`
+     * when there was none, and also when a write that got no answer cannot be shown to be this call's and the
+     * row holds no expiry: the expiry is gone either way, and its due-index pointer is removed. A later write that set an
+     * expiry is cleared too, and the answer is `true`). A separate verb from `setRetention` on purpose: "never expire" as a magic value passed
      * to the setter is how a typo becomes a deletion.
      */
     clearRetention(ref: SegmentRef): Promise<boolean>;
@@ -1169,20 +1302,22 @@ export declare class CloudRoaring {
      *
      * const swept = await store.retireExpired({ namespace: 'active-daily' });
      * for (const e of swept.entries) {
-     *   if (e.action === 'skipped') console.warn(`${e.segment}: ${e.reason}`); // invalid-policy / limit / failed: …
+     *   // invalid-policy / policy-changed / tombstone-not-empty / failed: …
+     *   if (e.action === 'skipped') console.warn(`${e.segment}: ${e.reason}`);
      *   if (e.action === 'retired' && e.result.generationsRemaining.length > 0) {
      *     console.warn(`${e.segment}: storage not fully reclaimed — re-run`);
      *   }
      * }
-     * if (swept.limited) scheduleAnotherPassSoon(); // more are still eligible
+     * if (swept.limited) scheduleAnotherPassSoon(); // more work (retirements or purges) remains
      * ```
      *
      * **Read the ledger.** A per-segment *fault* is an entry, not an exception — a throw from the middle of a fleet
      * sweep would leave the caller unable to say which segments were retired, having already retired some. (A bad
      * argument does throw, and so does a fleet larger than `maxScanSegments`.) `limited: true` means the per-cycle
-     * `limit` (default 100) cut the pass short and more are eligible. That cap is charged on **attempts**, not
-     * successes, which is what makes it a real bound: `dropSegment` writes the tombstone before sweeping Storage, so a
-     * fault in the Storage phase is a segment that is already retired. Retirements are sequential, so `limit` is a
+     * `limit` (default 100) cut the pass short, and more work (retirements or purges) remains: `limit` caps the
+     * retirements and tombstone purges one call attempts, together, and a segment it deferred gets no entry. That cap
+     * is charged on **attempts**, not successes, which is what makes it a real bound: `dropSegment` writes the
+     * tombstone before sweeping Storage, so a fault in the Storage phase is a segment that is already retired. Retirements are sequential, so `limit` is a
      * 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.
      *
@@ -1192,9 +1327,11 @@ export declare class CloudRoaring {
      * 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)
+     * It also **deletes the tombstone rows its own past retirements left**, after `tombstoneGraceMs` (default 24 h; at least one hour, else `ValidationError`)
      * 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
+     * first, since nothing else runs that collection on its own for a tombstoned segment (an erasure collects there
+     * only
+     * when an object holds its id, and a re-run drop sweeps it). Attribution is a **positive marker the sweep
      * stamps on its own retirements**, not an inference from "destroyed + an expired policy": a crypto-shred leaves
      * `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
@@ -1294,8 +1431,9 @@ export declare class CloudRoaring {
      * throw). Read-only, bounded fan-out; run it at startup after a restore. Returns `{ checked, inconsistent,
      * errored }` — `inconsistent` empty ⇒ coherent; otherwise it names the segments to recover (restore the object
      * store, or roll the registry back to a coherent point). Needs the store built with a **backend**
-     * (throws {@link UnsupportedError} otherwise). `destroyed` (crypto-shredded) segments are skipped. Pair it with
-     * the DR runbook (docs/guide/disaster-recovery.md).
+     * (throws {@link UnsupportedError} otherwise). `destroyed` segments (crypto-shredded, destroyed in the clear or
+     * dropped) 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
@@ -1324,6 +1462,39 @@ export declare class CloudRoaring {
         summaries?: boolean;
         generations?: boolean;
     }): Promise<ConsistencyReport>;
+    /**
+     * **First-run check of the store's storage and registry.** Call it once at deploy time, or on a first run, before
+     * the first load: it finds a missing permission, a storage that does not refuse a second write to a key, a listing
+     * that lags, or a lifecycle rule that would delete the store's objects, while nothing depends on them yet.
+     *
+     * It runs seven checks and always lists all seven, in this order: `registry` (one read of a row that must be
+     * absent, and the registry able to write), `write` (a new object), `write-once` (a second write to the same key must
+     * be refused), `read` (the object reads back as written), `list` (the listing names it), `delete` (this run's own
+     * object is removed, with the version the read gave where the driver applies one) and `lifecycle` (the backend's
+     * lifecycle check). The probe is one small object at `cbm.due.preflight/segments/probe.<number>.crbm` under the
+     * store's prefix; no registry row is written, and no segment of yours can share the name. A probe left by a run that
+     * was cut off is named in the `list` detail and never deleted, since it could be a run in progress.
+     *
+     * It **never throws over a finding**. A failed step, a transient fault included, is a `problem` whose `detail`
+     * says to run again when the fault was transient, and the checks that cannot run without it are `unchecked`. The
+     * exception is the `lifecycle` step, whose failures, its timeout included, are `unchecked`. `ok` is true when no
+     * check is a `problem`: read an `unchecked` check yourself, as `ok` does not vouch for it. The `lifecycle` check is
+     * `unchecked` for a backend whose check says so (Azure Blob always), for a backend that has no such method (a
+     * third-party backend, a `brandAsBackend` wrapper that does not forward it), when the identity lacks the optional
+     * permission to read the lifecycle rules (`s3:GetLifecycleConfiguration`, `storage.buckets.get`), and when the check
+     * takes longer than 30 seconds of the store's clock. The other steps are the store's ordinary calls and keep their
+     * timing.
+     *
+     * **Not checked:** read-after-delete, the registry's `If-Match` on compare-and-swap, multipart abort permission,
+     * versioning, backups, the keystore's backup and an S3 SDK from 3.641.0 to 3.699.0 (an older SDK shows as a
+     * `write-once` problem; these drop `If-Match`, which only a registry write refuses). It makes no kind of request that a
+     * load does not, though the lifecycle read needs its own optional permission. A run costs about seven requests (a
+     * first run on GCS makes eight, the eighth a second listing that checks the bucket exists, and Azure Blob always
+     * eight): two writes and a delete, the rest reads and one listing.
+     *
+     * Throws {@link UnsupportedError}, and only that, for a store with no backend, since there is nothing to check.
+     */
+    preflight(): Promise<PreflightResult>;
     /**
      * **Export ("eject") every registered segment's current generation** through the injected `sink`, using only
      * public read APIs — so your data is readable **without CloudRoaring** (the exit path; see the README's "Your
@@ -1332,8 +1503,9 @@ export declare class CloudRoaring {
      * Enumerates via the store's **own** registry (needs one — throws {@link UnsupportedError} otherwise) so the
      * enumeration and the read path provably share one registry. Encrypted segments are decrypted transparently
      * **iff** this store was wired with their keystore — the export is therefore **cleartext**; protect it.
-     * Crypto-shredded segments are skipped. A segment that can't be read is isolated into the manifest's `failed[]`
-     * (the run continues), so "a manifest exists" means the run finished — check `failed`. The `export-segments`
+     * Destroyed segments (crypto-shredded, destroyed in the clear or dropped) are skipped. A segment that can't be read
+     * is isolated into the manifest's `failed[]` (the run continues), so "a manifest exists" means the run finished —
+     * check `failed`. The `export-segments`
      * CLI wraps this with a filesystem sink. The `'roaring'` format's bitmaps are built by the store's own codec.
      */
     exportSegments(sink: ExportSink, options?: ExportOptions): Promise<ExportManifest>;
@@ -1533,6 +1705,7 @@ export interface PinAt {
 export interface SegmentStat {
     /** The generation read, or `null` when the segment has none. */
     readonly generation: number | null;
+    /** The number of ids in the generation read, or `0` when the segment has none. */
     readonly cardinality: number;
     /** The metadata the generation was loaded with; absent when it has none. */
     readonly metadata?: GenerationMetadata;
@@ -1601,7 +1774,7 @@ export declare class Segment {
      *
      * **One call reads a segment at one generation**, so a combine that holds this segment at two —
      * `snap0.andNot([snap1])`, or `live.intersect([snap])` — throws {@link ValidationError} when it is read, and an
-     * `*Into` of one throws before it reads anything. Materialise one side first, with `intersectInto(dest, [])`.
+     * `*Into` of one throws before it reads anything. Materialise one side first, with `materializeMany({ operands: { src: seg }, outputs: [{ dest, expr: { or: ['src'] } }], keep })`.
      *
      * **A pin knows its object, not only its number.** A name purged and loaded again starts again at generation
      * 0, so a pin of the old segment never reads the new one: what it has already read still answers, as the
@@ -1702,10 +1875,10 @@ export declare class Segment {
      * `at.generation` instead of the current one. Pass what the earlier pin recorded, `{ generation, fingerprint }`
      * from its {@link Segment.pinnedAt}. A generation number alone is not an identity, since a purged and re-created
      * name starts again at 0, so the fingerprint is required: a bare number, a malformed fingerprint or a key other
-     * than `generation` and `fingerprint` is a {@link ValidationError}. Identify a pin by its `generation` and
+     * than `generation`, `fingerprint` and `version` is a {@link ValidationError}. Identify a pin by its `generation` and
      * `fingerprint`: the handle's `pinnedAt.version` can differ from the earlier pin's.
      *
-     * Throws {@link NotFoundError} when the generation is gone (collected, purged, or on a crypto-shredded segment),
+     * Throws {@link NotFoundError} when the generation is gone (collected, purged, or on a destroyed segment),
      * is above the row's pointer, or is another object than the fingerprint names, and never reads empty. A rollback
      * deletes nothing, so once a later load moves the pointer past a generation it rolled back from, that one can be
      * reopened while its object is stored. Nothing keeps a generation alive unless you lease it: a later load's
@@ -1718,6 +1891,10 @@ export declare class Segment {
      * then reads as one from `pin()` does, including its failure on a chunk it has not cached once the generation is
      * swept. Works for an encrypted segment. The first argument is an object so that fields can join it later; the lease
      * is in `options`, the second.
+     *
+     * It takes what {@link Segment.pinnedAt} holds: once `generation` is not `null`, the record passes as it is (its
+     * `version` is not read), and `{ generation, fingerprint }` does as well. A pin of a segment that had no generation
+     * has nothing to reopen and throws {@link ValidationError}.
      */
     pinAt(at: PinAt, options?: PinOptions): Promise<Segment>;
     /**
@@ -1728,15 +1905,25 @@ export declare class Segment {
      */
     key(): string;
     /**
-     * Refuse an `*Into` whose handles cannot be used, before any request: anything that is not a segment or is a
-     * segment of another store ({@link ValidationError}), and a handle (this one, `dest`, an operand or an exclude) whose
-     * lease has ended or was released ({@link LeaseExpiredError}). Called by the three `*Into` verbs only.
+     * Refuse an `*Into` that cannot run, before any request, in this order: anything that is not a segment or is a
+     * segment of another store, an empty operand list for `intersectInto`, and a `dest` that is also a source (all
+     * {@link ValidationError}); then a handle (this one, `dest`, an operand or an exclude) whose lease has ended or was
+     * released ({@link LeaseExpiredError}). A call with both a lapsed lease and one of the first three refusals throws the
+     * first. Called by the three `*Into` verbs only.
      *
      * The verbs are `async` so this surfaces as a **rejected promise**, like every other validation in the facade —
      * a synchronous throw out of a promise-returning method escapes a caller who attached `.catch()` instead of
      * awaiting.
      */
     private assertIntoHandles;
+    /**
+     * Refuse an `*Into` whose destination is also one of its sources (this segment, an operand or an exclude, by the key
+     * a handle gives, so a pin of the source and a ref spelled with the default namespace count), before any request, as
+     * `materializeMany` refuses it. The combine would read the destination at the generation this store last resolved,
+     * up to `cache.genTtlMs` old, while the publish is fenced on the row as it stands: another process's newer load of
+     * the destination would be overwritten by a result built from the one before it, with no conflict to report.
+     */
+    private refuseSourceDestination;
     /** `result` as is, or, when a handle of the call holds a lease, checking that lease each time it reads a chunk. */
     private guarded;
     /**
@@ -1871,7 +2058,8 @@ export declare class Segment {
      *
      * Of {@link CombineOptions} it takes the range, `concurrency`, `budget`, `allowAbsentOperands` and `exclude`; a write
      * option (`audit`, `allowEmpty`, `guard`, `metadata`, `keep`) fails the stream with {@link ValidationError} when it is
-     * first read, before any request.
+     * first read, before any request. So does an empty `others`: an intersection over nothing has no meaning, and
+     * to read every id of one segment, use {@link iterate}. (`union` and `andNot` read an empty list as `this`.)
      */
     intersect(others: Segment[], options?: CombineOptions): IdStream;
     /**
@@ -1893,6 +2081,15 @@ export declare class Segment {
      * materialisation that silently did not take effect is the one thing a caller cannot detect on its own.
      *
      * A call involving a handle whose lease has ended, or anything that is not a segment, is refused before any of this.
+     * So is a `dest` that is also `this`, an operand or an exclude (the same segment by name and namespace, however the
+     * handle was made), and, for `intersectInto` alone, an empty `others` (`unionInto` and `andNotInto` publish `this` for an
+     * empty list): each throws {@link ValidationError} before any request. A destination that
+     * is also a source would publish a result built from the generation this store last resolved over a newer load by
+     * another process, with no conflict to report. This release has no fenced in-place update: write the result into a
+     * new segment and point readers at it; a single writer that knows nothing else writes the segment may load the result
+     * back, unfenced. To copy `src` into `dest`, call
+     * `materializeMany({ operands: { src }, outputs: [{ dest, expr: { or: ['src'] } }], keep })`, which reads each chunk
+     * once, at one instant.
      * It takes every field of {@link CombineOptions}, as `unionInto` does.
      */
     intersectInto(dest: Segment, others: Segment[], options?: CombineOptions): Promise<MaterializeResult>;
@@ -1904,7 +2101,8 @@ export declare class Segment {
      * `intersect` prunes any key missing from any operand; union has nothing to prune. It is charged against the
      * same per-op budget, so a wide union is refused rather than quietly billed — pass `budget` to raise it
      * deliberately. If you find yourself unioning the same segments on every read, materializing the combined
-     * segment once (`unionInto`, or a load) is the cheaper shape. It takes the options {@link intersect} takes.
+     * segment once (`unionInto`, or a load) is the cheaper shape. It takes the options {@link intersect} takes, and an
+     * empty `others` reads `this` itself.
      */
     union(others: Segment[], options?: CombineOptions): IdStream;
     /** Materialize `this ∪ others…` (minus `exclude`) as a **new generation of `dest`** — see {@link intersectInto}. */
@@ -1938,6 +2136,9 @@ export declare class Segment {
     /** The one body of the three `*Into` verbs, after each has checked its own options. */
     private combineInto;
 }
+export { MemoryStorage, LocalFsStorage, InProcessKeystore } from '@cloudbitmaps/core/node';
+export type { InProcessKeystoreOptions, LocalFsStorageOptions, MemoryStorageOptions, } from '@cloudbitmaps/core/node';
 export { deserializePortable };
-export { MemoryStorage, LocalFsStorage, destroySegment, eraseNamespace, excludingReservedRows, readRetentionPolicy, InProcessKeystore, CloudRoaringError, ValidationError, WriteConflictError, IntegrityError, NotFoundError, UnsupportedError, CapabilityError, TransientError, KeyUnavailableError, BudgetExceededError, LeaseExpiredError, LeaseLimitError, StaleOperandError, errorKind, CountingMetricsSink, RecordingAuditSink, } from '@cloudbitmaps/core';
-export type { AuditEvent, Budget, BudgetOption, Clock, ConsistencyErrorEntry, ConsistencyIssue, ConsistencyReport, DestroyResult, DropResult, Entropy, EraseDeps, ErrorKind, ExportFailure, ExportFormat, ExportManifest, ExportOptions, ExportSink, ExportSkipped, ExportWriter, ExportedSegment, Expr, GenerationEntry, GenerationMetadata, IAuditSink, IMetricsSink, InProcessKeystoreOptions, LoadGuard, LoadInput, LoadOptions, LoadRefusal, LoadResult, LocalFsStorageOptions, MaterializeManyFeedRecord, MaterializeManyOperandStats, MaterializeManyOutputStats, MaterializeManyStats, MemoryStorageOptions, MetricEvent, MetricOpName, MetricsSnapshot, PinnedAt, PortableBitmap, RetentionPolicy, RetireEntry, RetireExpiredOptions, RetireExpiredResult, RetryPolicy, Rng, RollbackResult, SegmentInfo, SegmentRef, SetRetentionResult, } from '@cloudbitmaps/core';
+export type { ReadonlyBitmap } from './roaring-codec.js';
+export { excludingReservedRows, readRetentionPolicy, CloudRoaringError, ValidationError, WriteConflictError, IntegrityError, NotFoundError, UnsupportedError, CapabilityError, TransientError, KeyUnavailableError, BudgetExceededError, LeaseExpiredError, LeaseLimitError, StaleOperandError, errorKind, CountingMetricsSink, RecordingAuditSink, } from '@cloudbitmaps/core';
+export type { AuditEvent, Budget, BudgetOption, Clock, ConsistencyErrorEntry, ConsistencyIssue, ConsistencyReport, DestroyResult, DropResult, Entropy, EraseDeps, ErrorKind, ExportFailure, ExportFormat, ExportManifest, ExportOptions, ExportSink, ExportSkipped, ExportWriter, ExportedSegment, Expr, GenerationEntry, GenerationMetadata, IAuditSink, IMetricsSink, LoadGuard, LoadInput, LoadOptions, LoadRefusal, LoadResult, MaterializeManyFeedRecord, MaterializeManyOperandStats, MaterializeManyOutputStats, MaterializeManyStats, MetricEvent, MetricOpName, MetricsSnapshot, PinnedAt, PortableBitmap, PreflightCheck, PreflightResult, RetentionPolicy, RetireEntry, RetireExpiredOptions, RetireExpiredResult, RetryPolicy, Rng, RollbackResult, SegmentInfo, SegmentRef, SetRetentionResult, } from '@cloudbitmaps/core';