@cloudbitmaps/roaring 0.15.0 → 0.17.0

package/dist/index.d.ts

@@ -23,8 +23,9 @@
  * `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, 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 { BudgetOption, GenerationEntry, GenerationMetadata, LoadGuard, LoadInput, LoadOptions, LoadRefusal, LoadResult, ReapRegistryTombstonesOptions, ReapRegistryTombstonesResult, 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';
+import { deserializePortable } from './roaring-codec.js';
 /**
  * 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
@@ -657,24 +658,26 @@ export declare class CloudRoaring {
      * A refused load deletes the object it wrote before returning — it sits above `currentGen`, where generation
      * collection deliberately never looks — but only while the segment's registry row is unchanged or gone. Once
      * another write has changed the row, the generation number it holds may name another incarnation's live object,
-     * 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`.
+     * so it leaves the orphan rather than risk deleting live data. No row's list names it, so it takes no place in a
+     * window, and a listing deletes it once a later generation is current above it.
      *
-     * **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.
+     * **Collection is by name at any `keep` up to 64.** The segment's row records the generations a load keeps, so a load
+     * that found nothing above the pointer deletes the generations 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
+     * an object a crashed load left below the pointer. A `keep` above 64 records no list and lists on every load, and so
+     * 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
      * 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 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.
+     * (`IntegrityError`); a driver failure; and a fault in the collection's own reads, listing or deletes, or in the write
+     * that records the window (anything but a lost race). A collection fault 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 or by listing, that finds another writer has moved the row since the publish (a load, a
+     * rollback, a purge) stops and returns what it deleted in `collected`: a load that took effect does not throw for a
+     * race it won.
      *
      * **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
@@ -840,6 +843,55 @@ export declare class CloudRoaring {
     retireExpired(options?: Omit<RetireExpiredOptions, 'now'> & {
         now?: number;
     }): Promise<RetireExpiredResult>;
+    /**
+     * **Remove the registry rows that releases before 0.12.0 left as `deleted: true` envelopes.** Those releases never
+     * removed a row they deleted, and no later call removes it either: it is invisible to every read, and every full
+     * listing of the registry still reads it (one GET each). This is the one call that removes them. It is an admin call,
+     * not a sweep, and nothing schedules it: run it once after the last process on a release before 0.12.0 is gone.
+     *
+     * ```ts
+     * const preview = await store.reapRegistryTombstones({ dryRun: true });
+     * console.log(`would remove ${preview.wouldReap} of ${preview.examined} rows read`);
+     *
+     * const done = await store.reapRegistryTombstones({ confirmNoLegacyWriters: true });
+     * if (done.limited) runAgain(); // `limit` (default 1,000) stopped the run with rows unread
+     * ```
+     *
+     * **What it removes.** Only a row that is `deleted: true` and whose token carries no incarnation id, which is what a
+     * release before 0.12.0 left, or a 0.12.0 or later release left by deleting a row born before 0.12.0 (both are safe to
+     * remove), whatever its `status`. It never touches a live row, a `destroyed` row that is not `deleted` (a crypto-shred's
+     * or a `dropSegment`'s tombstone: the attestation of an erasure, which it cannot tell from another), or a deleted row
+     * with an incarnation id, and it never touches a generation. **So it does not clean a bucket completely**: the
+     * `destroyed` tombstones `dropSegment` leaves stay, so do live rows written before 0.12.0, and so does a tombstone a
+     * 0.12.0 or later release wrote while `conditionalDelete` was off (GCS by default, S3 on a custom endpoint): every full
+     * listing still reads it, and this call neither removes it nor runs on such a store.
+     * It also covers the library's own bookkeeping rows when `namespace` is not set, by the same rule. The default
+     * namespace cannot be scoped to: leave `namespace` out to cover it.
+     *
+     * **The two things it asks.** `confirmNoLegacyWriters: true` is required for a real run (without it, a
+     * `ValidationError`, and nothing is requested): your statement that no process on a release before 0.12.0 writes
+     * this registry, since one that did would, re-creating a removed name, issue the removed row's tokens again. And the
+     * registry must apply a delete under a precondition: where its `conditionalDelete` capability is off (GCS by default,
+     * S3 on a custom endpoint) it throws `CapabilityError` before any request, dry run included. A registry that keeps
+     * no such rows (the in-memory and local-filesystem ones) throws `UnsupportedError`.
+     *
+     * **Each removal is fenced** on the version it read, so a `create` that lands over the envelope first wins, the
+     * delete is refused, and the row is counted as `skipped.raced` (which also counts a row already gone). That holds where
+     * the backend applies the precondition, which auto-detection checks (S3 only on an AWS host). On an endpoint that
+     * ignores `If-Match` (MinIO, fake-gcs-server), a `conditionalDelete: true` you set makes this an unfenced delete: run
+     * it with every writer stopped. On a versioned bucket a delete leaves a delete marker and the earlier version, record
+     * included, so the name is not erased from the bucket. A `create` that had already read the envelope and
+     * whose write meets the removal throws `WriteConflictError`, which this library does not retry: retry the create, and
+     * it finds no row and writes one.
+     *
+     * **Cost** over R rows read and E removed: `ceil(R / 1000)` LIST requests, R GETs and E DELETEs (a dry run, no
+     * DELETEs). `limit` bounds the removals, and the run stops listing once it is spent. **A run is not resumable**: each
+     * lists and reads from the start (R GETs whatever the `limit`), a dry run with a `limit` reports the same first rows
+     * every time, so `wouldReap` is a total only when `limited` is `false`, and `limited` is `true` whenever the limit was
+     * spent with keys left, removable or not. An unreadable object stops the run with an error naming its key, and
+     * removes nothing more: it may be a newer release's row. Scope the run with `namespace` to get past one.
+     */
+    reapRegistryTombstones(options?: ReapRegistryTombstonesOptions): Promise<ReapRegistryTombstonesResult>;
     /**
      * **Forget everything this store has cached about a segment.** Use it after destroying or retiring a segment
      * through a path this store did not perform itself.
@@ -883,6 +935,8 @@ export declare class CloudRoaring {
      * those of a live read that fetched across a publish (see {@link PinnedStorageChunkSource.currentVersion}).
      */
     private pinSegment;
+    /** 16 hex digits from the store's `Rng`, which names the holder of one lease: unique, not secret. */
+    private mintHolder;
     /**
      * An engine reading every segment in `pins` at its pinned generation and everything else live, with the store's
      * retries, so a transient fault on a pinned read is retried as it would be on a live one.
@@ -1004,8 +1058,9 @@ export interface BaseCombineOptions extends IdRange {
  */
 export interface CombineOptions extends BaseCombineOptions {
     /**
-     * Segments whose ids are subtracted from the result. An **expired** handle here excludes nothing, in every
-     * combine — it is skipped without being read, exactly as in {@link Segment.andNot}.
+     * Segments whose ids are subtracted from the result. An **expired** handle here is refused, in every combine:
+     * the stream throws {@link ValidationError} naming it, before any request is made, exactly as in
+     * {@link Segment.andNot}.
      */
     readonly exclude?: Segment[];
 }
@@ -1053,7 +1108,7 @@ export interface MaterializeOptions extends CombineOptions {
      * 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. 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
+     * new one beyond `keep`, however many earlier calls kept, where a `load()` deletes by name the generations its
      * publish pushes out of the window.
      */
     readonly keep?: number;
@@ -1096,6 +1151,32 @@ export interface IdStream extends AsyncIterable<number> {
  * solves the same problem the same way, by taking {@link BaseCombineOptions}.
  */
 export type AndNotIntoOptions = Omit<MaterializeOptions, 'exclude'>;
+/** What {@link Segment.pin} and {@link Segment.pinAt} take besides the generation. */
+export interface PinOptions {
+    /**
+     * Hold the pinned generation until this instant: epoch-**milliseconds**, after now and at most
+     * {@link MAX_LEASE_MS} (14 days) from it. A load's collection leaves a leased generation in the bucket until the lease
+     * ends, and a read of the handle after it throws {@link LeaseExpiredError}, never empty.
+     */
+    readonly leaseUntil?: number;
+}
+/** The lease a pinned handle holds, as {@link Segment.lease} reports it. */
+export interface Lease {
+    /** 16 hex digits naming this lease in the segment's registry row. */
+    readonly holder: string;
+    /** Epoch-ms the lease runs to on this store's clock. */
+    readonly until: number;
+}
+/**
+ * The generation {@link Segment.pinAt} reopens: what an earlier pin recorded in {@link Segment.pinnedAt}. The
+ * fingerprint is required, since a generation number is taken again after a purge and re-create.
+ */
+export interface PinAt {
+    /** The generation number an earlier pin held. */
+    readonly generation: number;
+    /** The fingerprint of that generation's object, from the earlier pin's `pinnedAt.fingerprint`. */
+    readonly fingerprint: string;
+}
 /** 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. */
@@ -1130,6 +1211,13 @@ export declare class Segment {
      * pinned handle passed as an **operand** is still read at its pin rather than live.
      */
     readonly pinnedAt?: PinnedAt;
+    /**
+     * The lease this handle holds, when it came from `pin({ leaseUntil })`; `undefined` otherwise. It reports what was
+     * taken and does not change when the lease ends: a read after `lease.until` (or after {@link Segment.release}) throws
+     * {@link LeaseExpiredError}.
+     */
+    readonly lease?: Lease;
+    private readonly leaseHold?;
     /**
      * Not constructible: a handle comes from {@link CloudRoaring.segment}, which wires it to the store's engine,
      * caches and write path. The constructor takes those internals, so it is not part of the surface.
@@ -1161,11 +1249,20 @@ export declare class Segment {
      * 0, so a pin of the old segment never reads the new one: what it has already read still answers, as the
      * instant it pinned, and anything it would have to fetch fails with `NotFoundError`, as a swept pin's does.
      *
-     * **It is a hold, not a lease.** Nothing here stops a collection deleting the generation underneath
-     * you: a pinned read deliberately does **not** heal forward, because silently serving a different generation
-     * is the one thing a pin exists to prevent, so it fails instead. Size `keep` to cover your longest pinned
-     * job — see [Generations and `keep`](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/loading.md#generations-and-keep) — or take the pin on a segment
-     * you are not collecting.
+     * **It is a hold, and `pin({ leaseUntil })` makes it a bounded one.** Without a lease nothing stops a collection
+     * deleting the generation underneath you: a pinned read deliberately does **not** heal forward, because silently
+     * serving a different generation is the one thing a pin exists to prevent, so it fails instead. Size `keep` to cover
+     * your longest pinned job — see [Generations and `keep`](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/loading.md#generations-and-keep) — take the pin on a segment
+     * you are not collecting, or lease it.
+     *
+     * **A lease** (`leaseUntil`: epoch **milliseconds**, after now and at most 14 days out) keeps the generation out of
+     * a load's collection until then, from any process, and the pin is taken with it: the lease is written to the segment's
+     * row before the object is opened. A read of the handle after the lease, or after {@link Segment.release}, throws
+     * {@link LeaseExpiredError} at every read site, including when the handle is an operand or an `exclude` of a combine
+     * or the target of an `*Into`, and never reads empty. A stream checks the lease each time it reads a chunk. A segment
+     * holds at most 64 live leases ({@link LeaseLimitError}). A collector holds a lease 60 seconds past its end, which covers
+     * clocks that differ by that much. Erasure, shred, drop and retention expiry ignore a lease. See
+     * [Hold a generation for a job](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/reading.md#hold-a-generation-for-a-job-a-lease).
      *
      * A segment with no current generation pins nothing and reads empty, exactly as it would unpinned. A pinned
      * segment whose row is later dropped or destroyed fails once it must open its object again, rather than go empty
@@ -1205,7 +1302,55 @@ export declare class Segment {
      * Needs a store built on the `.crbm` storage source (the default when you pass a backend or a raw driver). Throws
      * {@link UnsupportedError} on a store wired with a pre-built source that cannot pin.
      */
-    pin(): Promise<Segment>;
+    pin(options?: PinOptions): Promise<Segment>;
+    /**
+     * Hold what this pin names until `leaseUntil`, or `undefined` for a pin with no lease. Refuses an option it does not
+     * know, a value that is not epoch-milliseconds in the future, one past the longest lease, and one past the handle's own
+     * `expiresAt`, before any request is made.
+     */
+    private leaseUntilOf;
+    /**
+     * End this handle's lease now, so a load's collection may take its generation. Idempotent: a handle with no lease, or
+     * one already released, does nothing and makes no request. Every read of the handle after it throws
+     * {@link LeaseExpiredError} (reason `'released'`), including one already under way at its next chunk. A lease that has
+     * ended by its own time needs no release: this then makes no request either, and the registry row's entry is pruned
+     * by a later write. Otherwise it is one registry read and one write; a failure of either is thrown as the registry's own
+     * typed error, and the entry then holds until its time ends, `release()` being safe to call again.
+     */
+    release(): Promise<void>;
+    /**
+     * The error a read of this handle must throw, or `undefined` when it holds no lease or the lease is live. One property
+     * read on a handle with no lease. It is not {@link Segment.expired}: that rule reads empty, and a lease must never.
+     */
+    private leaseError;
+    /**
+     * Throw the first lease error among `handles`: this handle and every operand and exclude of a call. It runs before
+     * any `expiresAt` rule and before the engine, so no operand, exclude or cached reader can answer past a lease.
+     */
+    private assertLeases;
+    /**
+     * Reopen a generation a pin named earlier, as a pinned handle like the one {@link Segment.pin} returns, held at
+     * `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
+     * `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),
+     * 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
+     * collection can delete it, which is sized by `keep` on every writer, or held by `options.leaseUntil` (see
+     * {@link PinOptions} and {@link Segment.pin}). A leased `pinAt` writes the lease before it verifies the object, and
+     * releases it if the verify fails; for a generation below the pointer, a collector that read the row before the lease
+     * landed can still delete the generation inside its own round trip, and the handle then fails with `NotFoundError`
+     * like any swept pin. A leased handle is checked at every read site as a leased `pin()` is. With a registry it costs one row read and one tail read,
+     * and a leased `pinAt` one conditional write to the row besides; the handle
+     * 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.
+     */
+    pinAt(at: PinAt, options?: PinOptions): Promise<Segment>;
     /**
      * An opaque string that names this handle's segment, namespace included: two handles of one segment have the
      * same key, a live handle and its pins among them. Use it as a `Map` key or a log field when you track handles
@@ -1244,6 +1389,8 @@ export declare class Segment {
      * awaiting.
      */
     private refuseIfExpired;
+    /** `result` as is, or, when a handle of the call holds a lease, checking that lease each time it reads a chunk. */
+    private guarded;
     /**
      * Time an op with the injected clock and emit an `op` metric on completion (success or throw). Skipped
      * entirely when no sink is wired, so the default path pays nothing.
@@ -1301,9 +1448,40 @@ export declare class Segment {
      * without checking its options, as every read of one does.
      */
     iterate(options?: IdRange): IdStream;
+    /**
+     * **Pinned handles only.** The ids at 1-based ranks `n`, `2n`, `3n` …, counted over the ids in `(after, through]`
+     * when a range is given, ascending: `everyNth(1000)` yields the 1,000th id, then the 2,000th, and so on. A last
+     * partial window yields nothing, so a caller cutting a send into windows of `n` appends its own final end.
+     *
+     * It places each boundary from the per-chunk counts the pin already holds and reads only the chunks that hold one,
+     * each once however many boundaries it holds, so it reads at most one chunk per boundary and never more chunks
+     * than the object has. A range with `after` inside a chunk reads that chunk too, to count the ids at or below
+     * `after`, even when fewer than `n` ids remain above it; when the chunks in range hold fewer than `n` ids in all,
+     * nothing is fetched. `through` stops the read and no chunk past it is read, though a `through` inside a chunk may read that last chunk and
+     * yield nothing from it. The reads and the read-ahead window are
+     * those of {@link Segment.iterate}, and the per-op budget is charged before the first fetch, with an upper bound on
+     * the chunks the read can take. A pinned read after the generation is swept throws {@link NotFoundError}.
+     *
+     * The ranks come from the index's counts, which are trusted as {@link Segment.count} trusts them. A chunk that is
+     * read must hold the number of ids its index says, or the read throws {@link IntegrityError}; a chunk that is not
+     * read is not checked, so an index that is wrong about one, and, on an unencrypted object, still adds up to the footer's
+     * total, moves the ids after it to the wrong ranks. An encrypted object's index is authenticated and bound to the
+     * object, so a wrong count there needs the key.
+     *
+     * A live handle is refused with {@link UnsupportedError} at the first read, because its counts and its chunks could
+     * come from two generations and name the wrong id. `n` that is not a positive integer throws
+     * {@link ValidationError} at the first read, as does a bad bound. An expired handle reads empty.
+     *
+     * ```ts
+     * const audience = await store.segment('audience').pin();
+     * const ends: number[] = [];
+     * for await (const id of audience.everyNth(1_000)) ends.push(id); // the end of each window of 1,000
+     * ```
+     */
+    everyNth(n: number, options?: IdRange): AsyncIterable<number>;
     /**
      * The options a combine hands the engine, read once, when it is called ({@link readOptions}), with the `exclude`
-     * it was given, already reduced to its live handles ({@link liveExcludes}) and mapped down to the plain refs
+     * it was given ({@link excludesOf}) and mapped down to the plain refs
      * `core` takes. A method rather than a module function because `ref` is class-private — the encapsulation is
      * worth more than the free function.
      *
@@ -1313,15 +1491,23 @@ export declare class Segment {
      */
     private refsIn;
     /**
-     * The handles in `options.exclude` that have not expired. **An expired exclusion excludes nothing**, in every
-     * combine, so it is dropped here, before the engine is asked for anything: it is never fetched, never
-     * checked for absence, and never counted in the pin-consistency check. `exclude` is read once, so a getter sees
-     * one call.
+     * The handles in `options.exclude`, read once so a getter sees one call. With none this is one property read and
+     * a shared empty list; otherwise it is the caller's own array, so the common case allocates nothing.
+     */
+    private excludesOf;
+    /**
+     * The refusal for a combine whose **exclusion** has expired, or `undefined` when none has. Unlike an expired
+     * operand, which reads empty, an exclusion is a suppression or opt-out list: left out silently, the result
+     * would include the very ids it was passed to remove. So it is refused with a {@link ValidationError} naming each
+     * expired exclusion, as the `*Into` verbs refuse an expired handle.
      *
-     * With no `exclude` this is one property read and a shared empty list, and with none expired it returns the
-     * caller's own array, so the common case allocates nothing.
+     * It is judged against the injected clock when the combine is called, before the engine is asked for anything:
+     * no request is made, and an expired exclusion that names a segment that does not exist is refused as expired,
+     * not as an absent operand. It runs ahead of the expired-operand shortcuts, so a combine that would read empty
+     * anyway still refuses a lapsed exclusion. A stream already being read is not re-checked when an exclusion
+     * expires part-way, as an operand expiring part-way does not stop it either.
      */
-    private liveExcludes;
+    private expiredExcludes;
     /**
      * 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
@@ -1332,6 +1518,7 @@ export declare class Segment {
      * override the store's per-op denial-of-wallet budget for this call (or `false` to lift it).
      */
     intersect(others: Segment[], options?: CombineOptions): IdStream;
+    private intersectAs;
     /**
      * Materialize `this ∩ others…` (minus `exclude`) as a **new generation of `dest`** — `dest`'s previous contents
      * are superseded, not added to. Streaming + bounded-memory; the result is one immutable object published
@@ -1364,6 +1551,7 @@ export declare class Segment {
      * segment once (`unionInto`, or a load) is the cheaper shape.
      */
     union(others: Segment[], options?: CombineOptions): IdStream;
+    private unionAs;
     /** Materialize `this ∪ others…` (minus `exclude`) as a **new generation of `dest`** — see {@link intersectInto}. */
     unionInto(dest: Segment, others: Segment[], options?: MaterializeOptions): Promise<MaterializeResult>;
     /**
@@ -1374,14 +1562,15 @@ export declare class Segment {
      * suppression list: at most one read per surviving key of `this`, so subtracting a 61,000-chunk global
      * opt-out list from a 40-chunk audience costs at most 40 reads, not 61,000.
      *
-     * An expired handle in `excludes` excludes nothing, and is skipped without being read; if every one has
-     * expired the result is `this` whole. An expired `this` is empty. `exclude` on `intersect` and `union` follows
-     * the same rule.
+     * An expired handle in `excludes` is refused, not skipped: the stream throws {@link ValidationError} naming it,
+     * before any request is made, because a lapsed suppression list would otherwise let through the ids it was
+     * passed to remove. An expired `this` is empty. `exclude` on `intersect` and `union` follows the same rule.
      *
      * To filter the *result of an intersection*, do not chain — pass `exclude` to {@link intersect} instead, so
      * the suppression folds into the same pass rather than materializing an intermediate segment first.
      */
     andNot(excludes: Segment[], options?: BaseCombineOptions): IdStream;
+    private andNotAs;
     /** Materialize `this \ (excludes…)` as a **new generation of `dest`** — see {@link intersectInto}. */
     andNotInto(dest: Segment, excludes: Segment[], options?: AndNotIntoOptions): Promise<MaterializeResult>;
     /**
@@ -1396,5 +1585,6 @@ export declare class Segment {
         workload?: Workload;
     }): 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, 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';
+export { deserializePortable };
+export { MemoryStorage, LocalFsStorage, CrbmStorageChunkSource, destroySegment, eraseNamespace, excludingReservedRows, readRetentionPolicy, MIN_EXPIRES_AT_MS, LEASE_SKEW_MS, MAX_LEASE_MS, MAX_LEASES_PER_SEGMENT, InProcessKeystore, NodeAead, aadFor, CloudRoaringError, ValidationError, WriteConflictError, IntegrityError, NotFoundError, UnsupportedError, CapabilityError, TransientError, KeyUnavailableError, BudgetExceededError, LeaseExpiredError, LeaseLimitError, isCloudRoaringError, isWriteConflictError, isTransientError, isNotFoundError, isIntegrityError, isValidationError, isLeaseExpiredError, isLeaseLimitError, 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, 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, ReapRegistryTombstonesOptions, ReapRegistryTombstonesResult, RegistryWriteOptions, LeaseEntry, RetentionPolicy, RetireEntry, RetireExpiredOptions, RetireExpiredResult, RetryPolicy, Rng, RollbackResult, SealedRegistrySummary, SegmentInfo, SegmentRef, SegmentSize, SegmentSizing, SetRetentionResult, StorageBackend, StorageCaps, StorageChunkSource, Token, Workload, WrappedDek, } from '@cloudbitmaps/core';