@cloudbitmaps/roaring 0.18.3 → 0.19.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, 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 { 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';
 import type { CombineExpr, CombineManyFeedRecord, CombineManyOperandStats, CombineManyOutputStats, CombineManyStats } from '@cloudbitmaps/core';
 import { deserializePortable } from './roaring-codec.js';
@@ -201,31 +201,13 @@ export interface SeamOptions {
     /** Defaults to `Math.random`-backed. Drives transient-retry jitter. */
     readonly rng?: Rng;
 }
+/**
+ * What {@link CloudRoaring.segment} takes besides the name. A handle carries no deadline: check one where you read,
+ * or record it with {@link CloudRoaring.setRetention} and run {@link CloudRoaring.retireExpired}. An `expiresAt`
+ * passed here is refused with {@link ValidationError}.
+ */
 export interface SegmentOptions {
     readonly namespace?: string;
-    /**
-     * **When this segment stops being readable** — an absolute epoch-ms instant, declared where the segment is
-     * named instead of in a separate `setRetention` call.
-     *
-     * Every read through this handle checks it first: past the deadline, `has` is `false`, `count` is `0`, and
-     * `iterate` yields nothing — **one integer compare against the injected clock, no I/O, on every backend**.
-     * That is Redis's lazy expiry, and it is what makes an expiry *correct* rather than *eventually correct*: a
-     * deployment whose sweep is late — or which has no sweep at all, like a Lambda-only reader — still stops
-     * serving the data on time.
-     *
-     * **Two things this does NOT do, both deliberate:**
-     *
-     * - It does not reclaim the bytes. That is {@link CloudRoaring.retireExpired}, and until it runs the data is
-     *   still stored and still billed. `count()` reporting 0 while objects exist is the expected state in that
-     *   window, not a bug.
-     * - It does not apply to *other* handles. The deadline lives on this handle; a second handle opened without
-     *   the option reads the segment normally. Record the policy with {@link CloudRoaring.setRetention} to make
-     *   it durable, fleet-visible, and reclaimable.
-     *
-     * Must be **milliseconds** since the epoch and at or after {@link MIN_EXPIRES_AT_MS} — a seconds value would
-     * land in 1970 and make the segment permanently unreadable, so it is refused rather than honoured.
-     */
-    readonly expiresAt?: number;
 }
 /** A segment reference in a subject report / erasure ledger. */
 export interface SubjectSegmentRef {
@@ -362,10 +344,9 @@ export interface MaterializeManyFeed {
 /** The options of {@link CloudRoaring.materializeMany}. */
 export interface MaterializeManyOptions extends IdRange {
     /**
-     * The operands the expressions name: stored segments, and operands held in memory from {@link CloudRoaring.memory}. A held
-     * operand is accepted here and nowhere else.
+     * The stored segments the expressions name. A set the caller holds in memory arrives as a {@link MaterializeManyOptions.feed}.
      */
-    readonly operands: Record<string, Segment | MemoryOperand>;
+    readonly operands: Record<string, Segment>;
     /** The outputs, in the order their results come back. */
     readonly outputs: ReadonlyArray<MaterializeManyOutput>;
     /**
@@ -409,10 +390,9 @@ export interface MaterializeManyOptions extends IdRange {
      */
     readonly feed?: MaterializeManyFeed;
     /**
-     * Fed and held operand names allowed to hold no id. A declared fed name that appears in no record is refused at the end
-     * of the feed, and a held operand that holds no id is refused before any request, because an operand that is empty is
-     * usually an upstream query that failed quietly. Naming something that is neither a fed nor a held operand is a
-     * {@link ValidationError}.
+     * Fed operand names allowed to hold no id. A declared fed name that appears in no record is refused at the end of the
+     * feed, because an operand that is empty is usually an upstream query that failed quietly. Naming something that is not
+     * a fed operand is a {@link ValidationError}.
      */
     readonly mayBeEmpty?: readonly string[];
 }
@@ -435,6 +415,42 @@ export interface MaterializeManyRun {
     readonly outputs: MaterializeManyOutcome[];
     readonly stats: MaterializeManyStats;
 }
+/**
+ * {@link MaterializeManyOptions} for a **dry run**: every output is computed exactly as the call would compute it, and
+ * judged against its `dest` as its publish would be, and nothing is written. See {@link CloudRoaring.materializeMany}.
+ */
+export interface MaterializeManyDryRunOptions extends MaterializeManyOptions {
+    readonly dryRun: true;
+}
+/**
+ * What one output of a dry run would come to, with nothing written: its size, what its `dest` holds now, and the bound
+ * its publish would be refused for now. `published` is always `false`, so code that branches on it never takes a dry
+ * run for a publish.
+ */
+export interface MaterializeDryRunResult {
+    readonly dryRun: true;
+    readonly published: false;
+    /** Distinct ids the output would hold. */
+    readonly cardinality: number;
+    /** What `dest` holds now: `null` when it has no current generation, or its object is gone. Always read. */
+    readonly cardinalityBefore: number | null;
+    /** The bound a publish of the output would be refused for, judged now; absent when it would publish. */
+    readonly wouldRefuse?: MaterializeRefusal;
+}
+/**
+ * What one output of a dry run came to: a {@link MaterializeDryRunResult}, or `{ published: false, error }` for what its
+ * publish would have thrown or what stopped it, as on a call that publishes.
+ */
+export type MaterializeManyDryRunOutcome = MaterializeDryRunResult | {
+    readonly published: false;
+    readonly error: Error;
+};
+/** The result of {@link CloudRoaring.materializeMany} with `dryRun: true`. */
+export interface MaterializeManyDryRun {
+    /** One per output, in the order given. */
+    readonly outputs: MaterializeManyDryRunOutcome[];
+    readonly stats: MaterializeManyStats;
+}
 /** What an `*Into` verb wrote: the new generation of the destination, and whether it became current. */
 export interface MaterializeResult {
     /**
@@ -456,8 +472,8 @@ 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 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
+     * no bound needed it**. It is taken only when a bound will use it: `allowEmpty: true` with neither
+     * `guard.minRetained` nor `guard.maxGrowth` 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.
      */
@@ -502,6 +518,11 @@ export declare class CloudRoaring {
      * another library's config spread into this one — so every key is checked against {@link OPTION_KEYS}.
      */
     private static rejectUnknownOptions;
+    /**
+     * A seam the store calls through must have the methods it calls. Without this a `clock` with no `now`, an `rng` with
+     * 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;
     constructor(options: CloudRoaringOptions);
     /**
      * The write-side deps, from the store's own drivers, for the lifecycle helpers and the `*Into` verbs. Requires
@@ -510,14 +531,20 @@ export declare class CloudRoaring {
      * every write publishes.
      */
     private lifecycleDeps;
-    /** Get a handle to a segment. Validates the name (non-empty, well-formed, within the encoded-length cap). */
+    /**
+     * Get a handle to a segment. Validates the name (non-empty, well-formed, within the encoded-length cap). The options
+     * are `{ namespace }` and nothing else: anything else is refused with {@link ValidationError}, by name, since a
+     * misspelt `namespace` would otherwise address the default namespace. An `expiresAt` among them is refused with its own
+     * message: a handle carries no deadline, and one left unread would serve the data past it. A key whose value is
+     * `undefined` is read as absent, so a spread of options keeps working.
+     */
     segment(name: string, options?: SegmentOptions): Segment;
     /**
      * 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 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
+     * Only an unguarded load (`allowEmpty: true`, with neither `guard.minRetained` nor `guard.maxGrowth`) onto a segment with no row publishes bare
      * forward-only. The destination's previous generation stays readable until the publish lands (readers re-resolve
      * within `cache.genTtlMs`).
      *
@@ -554,35 +581,29 @@ export declare class CloudRoaring {
      */
     private materialize;
     /**
-     * **Hold a set of ids in memory**, to be an operand of {@link CloudRoaring.materializeMany} and of no other verb.
-     *
-     * ```ts
-     * const vip = await store.memory([7, 42, 99_001]);
-     * await store.materializeMany({ operands: { vip, engaged: store.segment('cond-engaged') }, outputs: [...], keep: 12 });
-     * vip.release();
-     * ```
-     *
-     * It takes what {@link CloudRoaring.load} takes as input (ids as a sync or async iterable or a typed array, `{ bitmap }`
-     * or `{ serialized }`) and checks it the same way, with the same errors: the size cap, the structure, the safe
-     * deserializer and each id's range. **Only a real `Uint32Array` skips the per-id range check**; any other typed array goes
-     * through it, so `Int32Array([-1])` and `Float64Array([1.5])` throw {@link ValidationError}. An object with an `ascending`
-     * key is refused: ids that arrive in key order are a `feed`. An empty set is accepted here, and refused by
-     * `materializeMany` unless its name is in `mayBeEmpty`.
-     *
-     * The ids are held as the chunks a stored generation would hold, until {@link MemoryOperand.release}; between calls that
-     * memory is the caller's, and during a call it counts against `maxBufferedBytes`. There is no size option: the load's
-     * own cap applies to a serialized input.
+     * **A dry run:** every output computed exactly as the call would compute it, and judged against its `dest` as its
+     * publish would be, with nothing written: no object, no pointer, no audit event. Each output's result says how many ids
+     * it would hold, what its `dest` holds now, and the bound its publish would be refused for now (`wouldRefuse`). The
+     * call reads its operands as a publishing call does, takes its feed if it has one, and fails an output for what would
+     * fail its publish (a `dest` whose lease has ended, a destroyed one, a moved exclude, an erasure). It reads the operands as
+     * the publishing call does, and for each output the reads a publish's guard makes: one registry read for `dest`'s size,
+     * or two where its row has no usable summary. It holds the memory a publish would, so it fails for memory where one
+     * would, and reports to the metrics sink as the same `materializeMany` op.
      *
-     * **Erasure.** Only `eraseSubject` moves the store's counter (at its start and at its end). One that started in this store
-     * since the handle began to be made, or is still running, makes a call that reads the handle fail the outputs that read it with
-     * {@link StaleOperandError} (`reason: 'erased'`), before any request and again just before each publish. An erasure in
-     * another store or another process is not seen, nor are `dropSegment`, `eraseNamespace`, `destroySegment` and the free
-     * function `eraseIdFromSegment`, which do not move it: the handle is the caller's copy, so build it from the source of truth at
-     * the start of each refresh and release it at the end.
-     *
-     * @throws {ValidationError} where a load of the same input would.
+     * What it reports holds for now only: a publish made later reads the operands and judges each `dest` as they are then.
+     * To publish what was reviewed, call again without `dryRun`, on the same pinned handles or with the same feed (the
+     * guide's recipe).
+     */
+    materializeMany(options: MaterializeManyDryRunOptions): Promise<MaterializeManyDryRun>;
+    /**
+     * The call with `dryRun` a switch held in a variable, optional or not: a {@link MaterializeManyDryRun} when it is
+     * `true` and a {@link MaterializeManyRun} when it is `false` or absent, so with a `boolean` (or `boolean | undefined`)
+     * the result is typed as either, and the flag passed says which. A literal `true` or `false`, and a call without
+     * `dryRun`, are typed exactly, as by the forms either side of this one.
      */
-    memory(input: LoadInput): Promise<MemoryOperand>;
+    materializeMany<D extends boolean | undefined = undefined>(options: MaterializeManyOptions & {
+        readonly dryRun?: D;
+    }): Promise<D extends true ? MaterializeManyDryRun : MaterializeManyRun>;
     /**
      * **Many outputs, each operand read once per group.** Each output is an expression over named stored operands (`and`, `or`, `andNot`, nested
      * to depth 64) published as a new generation of its own `dest`, exactly as an `*Into` would publish it, but computed
@@ -631,10 +652,10 @@ export declare class CloudRoaring {
      * **Untrusted bytes.** Every operand chunk is decoded through the checks on untrusted tier data. A key an operand's index
      * lists whose bytes are missing is an error for the outputs that read the operand, never an empty chunk.
      *
-     * **Handles.** An expired or released handle anywhere in the call (an operand or a `dest`) is refused before any request,
-     * as on the `*Into` verbs. A leased operand's lease, and an operand's deadline, are checked before each chunk key
-     * is read: a lapse fails only the outputs that read that operand, never reads empty. Each `dest`'s lease and deadline
-     * are checked again just before its publish.
+     * **Handles.** A handle anywhere in the call (an operand or a `dest`) whose lease has ended or was released is refused
+     * before any request, as on the `*Into` verbs. A leased operand's lease is checked before each chunk key is read: a
+     * lapse fails only the outputs that read that operand, never reads empty. Each `dest`'s lease is checked again just
+     * before its publish.
      *
      * **The chunk cache is bypassed:** the pass reads through the storage source and never writes the decoded-chunk cache, so
      * a batch does not evict other readers' hot chunks. Each publish still invalidates its `dest` as an `*Into` does.
@@ -642,13 +663,6 @@ export declare class CloudRoaring {
      * **A limit of the form.** An output cannot name another output of the same call: a `dest` that is also an operand is
      * refused. Chain two calls.
      *
-     * **Held operands.** An operand may be a {@link MemoryOperand} from {@link CloudRoaring.memory}: ids the caller holds,
-     * read beside the stored ones and giving the same output byte for byte. It is read from memory (no request, and the
-     * shared chunk cache never sees it), counts against `maxBufferedBytes` while the call runs, and is refused when empty
-     * unless its name is in `mayBeEmpty`. A handle from another store, or a released one, is a {@link ValidationError}. An
-     * erasure in this store since the handle was made fails the outputs that read it with {@link StaleOperandError}
-     * (`reason: 'erased'`).
-     *
      * **A feed.** `feed: { names, records, counts }` adds operands that arrive as records in chunk-key order, for conditions
      * too many to hold or store. Each record is checked before the pass sees it (see {@link MaterializeManyFeedRecord}): a bad
      * feed is refused, never read as fewer members, and **a fed output is published only after the whole feed was read and every
@@ -674,7 +688,14 @@ export declare class CloudRoaring {
      * });
      * ```
      */
-    materializeMany(options: MaterializeManyOptions): Promise<MaterializeManyRun>;
+    materializeMany(options: MaterializeManyOptions & {
+        readonly dryRun?: false;
+    }): Promise<MaterializeManyRun>;
+    /**
+     * A dry run's publish of one output: count what the finished chunks hold, and judge that size against `dest` as a
+     * load would, writing nothing.
+     */
+    private judgeOutput;
     private epochNow;
     /**
      * Whether an erasure has started in this store since `at` was read, or was running when it was: one that is still
@@ -691,10 +712,8 @@ export declare class CloudRoaring {
      * can be taken again once its object is gone.
      */
     private currentRowOf;
-    /** Throw what a read of `handle` must throw now: its lease error, or a refusal for a deadline that has passed. */
-    private assertReadable;
-    /** {@link assertReadable} for a destination, named by where it sits in the call. */
-    private assertWritable;
+    /** Throw what a read of, or a publish to, `handle` must throw now: its lease error, if it has one. */
+    private assertLease;
     /**
      * **Subject access (GDPR Art. 15 / CCPA right-to-know): which segments is this id a member of?**
      *
@@ -750,8 +769,9 @@ export declare class CloudRoaring {
      * every generation below its new pointer — the one this rewrite is streaming, and the object this rewrite
      * just wrote — so the loser can find its own inputs deleted mid-flight. That surfaces as an outcome rather than
      * an error, read off the row: a moved pointer is a `'superseded'` entry, which a re-run settles, and a segment
-     * that a concurrent `dropSegment` tombstoned or a retention sweep purged is left out of the ledger, as a fresh
-     * call would leave it out.
+     * that a concurrent `dropSegment` tombstoned or a retention sweep purged is left out of the ledger. A tombstoned
+     * segment is still searched: a cleartext object left under it that holds the id is deleted, with everything under
+     * the tombstone, and the entry reads `erased: true`.
      *
      * **Read `note` on any `erased: false` entry — the two reasons mean different things.** `'superseded'` means
      * another writer (a load, another erasure, or a rollback) moved the pointer mid-call, so **this call** did not
@@ -809,10 +829,9 @@ export declare class CloudRoaring {
      * exists. It is `false` for a segment whose row was minted ahead of its first load (by `setRetention`) and
      * 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
+     * One state answers `true` where a read still gives you nothing: a torn restore (a live pointer whose object
      * 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.
+     * its row records — `checkConsistency` is the call for that.
      *
      * Not a lock: the answer can change the moment it returns. If it has to hold, use the fence built for that —
      * `load`'s `guard`, or `expectFrom`/`expectToken` on a publish. Needs a storage backend.
@@ -1130,55 +1149,6 @@ 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.
@@ -1292,6 +1262,8 @@ export declare class CloudRoaring {
     /**
      * Planning cost estimate — pure, no instance/data needed: sizing, sales, what-if. For a real, grounded report
      * from live segment sizes, use `store.segment(name).costReport()`. See {@link CostReport}.
+     * @deprecated Moves to `@cloudbitmaps/tools`, a package of its own, with a `size` on `stat()` so a grounded report
+     * needs nothing internal. It is a planning tool, and its price list is as old as the release that ships it.
      */
     static estimateCost(input: EstimateInput): CostReport;
 }
@@ -1344,11 +1316,7 @@ export interface BaseCombineOptions extends IdRange {
  * list costs reads proportional to the audience, not to itself.
  */
 export interface CombineOptions extends BaseCombineOptions {
-    /**
-     * 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}.
-     */
+    /** Segments whose ids are subtracted from the result. */
     readonly exclude?: Segment[];
 }
 /**
@@ -1472,26 +1440,6 @@ export interface SegmentStat {
     /** The metadata the generation was loaded with; absent when it has none. */
     readonly metadata?: GenerationMetadata;
 }
-/**
- * A set of ids held in memory by {@link CloudRoaring.memory}, to be an operand of {@link CloudRoaring.materializeMany}
- * and of no other verb. The bytes are the caller's until {@link MemoryOperand.release}.
- *
- * It belongs to the store that made it. `eraseSubject` in that store, started after the handle began to be made or still
- * running when it was, fails the outputs of a `materializeMany` call that read it with {@link StaleOperandError}
- * (`reason: 'erased'`): the call does not throw, and its outputs that do not read the handle publish. Nothing else is
- * seen: an erasure in another store or process, and
- * `dropSegment`, `eraseNamespace`, `destroySegment` and the free function `eraseIdFromSegment`, do not move the counter.
- */
-export declare class MemoryOperand {
-    private readonly view;
-    /** Not constructible: a handle comes from {@link CloudRoaring.memory}. */
-    private constructor();
-    /**
-     * Zero and drop the bytes it holds. Any later use throws {@link ValidationError}; releasing twice does nothing. A call
-     * still reading it fails the outputs that read it.
-     */
-    release(): void;
-}
 /**
  * A handle bound to one segment — the read verbs, plus the three `*Into` verbs that write a **new generation**
  * of another segment.
@@ -1511,8 +1459,6 @@ export declare class Segment {
     private readonly materialize;
     private readonly pinned;
     private readonly combineEngine;
-    /** Absolute epoch-ms deadline from {@link SegmentOptions.expiresAt}; `undefined` ⇒ this handle never expires. */
-    readonly expiresAt?: number;
     /**
      * The generation this handle is held at, when it came from {@link Segment.pin}. Read by the store so a
      * pinned handle passed as an **operand** is still read at its pin rather than live.
@@ -1612,8 +1558,8 @@ export declare class 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.
+     * know, a value that is not epoch-milliseconds in the future, and one past the longest lease, before any request is
+     * made.
      */
     private leaseUntilOf;
     /**
@@ -1627,12 +1573,17 @@ export declare class Segment {
     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.
+     * read on a handle with no lease. A read past a lease throws; it never reads empty.
      */
     private leaseError;
+    /**
+     * Refuse with a {@link ValidationError} anything among `handles` that is not a segment, a value a JavaScript caller
+     * passed. It runs first in every combine, before the lease check reads the handles.
+     */
+    private assertSegments;
     /**
      * 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.
+     * the engine, so no operand, exclude or cached reader can answer past a lease.
      */
     private assertLeases;
     /**
@@ -1666,36 +1617,15 @@ export declare class Segment {
      */
     key(): string;
     /**
-     * Has this handle's deadline passed? **The lazy half of expiry** — the whole check is one comparison against
-     * the injected clock, so it costs nothing on a handle with no deadline and no I/O on one that has expired.
-     *
-     * Deliberately evaluated per call rather than cached: a long-lived handle created before its deadline must
-     * start reading empty the moment the deadline passes, without the caller re-creating it.
-     */
-    private expired;
-    /**
-     * Refuse a materialisation that involves an **expired** handle. Called by the three `*Into` verbs only.
-     *
-     * On the read verbs an expired handle answers empty, which is the point of lazy expiry. On a *write* the same
-     * rule would be destructive in a way nobody asks for: `a.intersectInto(dest, [b])` where `b`'s deadline has
-     * quietly passed would, unrefused, replace `dest` with an **empty generation** — a wipe, reported as a successful
-     * write, with the cause (a deadline on a handle somewhere) nowhere in the result. Reads degrade to empty; writes must not.
-     *
-     * So every handle in the call is checked, `dest` included: an expired `dest` does not change the bytes written,
-     * but a caller who put a deadline on the thing they are writing into has said something contradictory and is
-     * better told than guessed at. Open a handle without `expiresAt` to write, or drop the deadline.
-     *
-     * (The broader guard — refusing to publish an empty or implausible generation over a non-empty one, with an
-     * `allowEmpty` override — covers these verbs too: they route through the same guarded write path as
-     * {@link CloudRoaring.load}. The two stay separate because they differ in kind. That one is a REPORTED
-     * refusal a caller may legitimately override; an expired handle is a wiring mistake, so it THROWS, before
-     * any object is written — and `allowEmpty: true` does not reach it.)
+     * Refuse an `*Into` whose handles cannot be read, before any object is written: anything that is not a segment
+     * ({@link ValidationError}), and a handle (this one, `dest` or an operand) whose lease has ended or was released
+     * ({@link LeaseExpiredError}). 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 refuseIfExpired;
+    private assertIntoHandles;
     /** `result` as is, or, when a handle of the call holds a lease, checking that lease each time it reads a chunk. */
     private guarded;
     /**
@@ -1728,8 +1658,8 @@ export declare class Segment {
      * 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 }`.
+     * handle, which answers for the generation it pinned. A segment with no generation answers
+     * `{ 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.
@@ -1751,8 +1681,7 @@ export declare class Segment {
      * ```
      *
      * Each bound is optional and an integer in `0..4294967295`; a bad one throws {@link ValidationError} when the
-     * stream is first read. `after >= through` is an empty range, which reads nothing. An expired handle reads empty
-     * without checking its options, as every read of one does.
+     * stream is first read. `after >= through` is an empty range, which reads nothing.
      */
     iterate(options?: IdRange): IdStream;
     /**
@@ -1777,7 +1706,7 @@ export declare class Segment {
      *
      * 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.
+     * {@link ValidationError} at the first read, as does a bad bound.
      *
      * ```ts
      * const audience = await store.segment('audience').pin();
@@ -1802,19 +1731,6 @@ export declare class Segment {
      * 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.
-     *
-     * 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 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
@@ -1839,12 +1755,12 @@ export declare class Segment {
      * write is **refused and reported**: `published: false`, `reason: 'empty'`, and `dest` keeps what it had.
      * Pass `allowEmpty: true` when emptying the destination is the point.
      *
-     * `guard` adds the same plausibility bounds `load()` takes — `minCardinality` and `minRetained` — judged
+     * `guard` adds the same plausibility bounds `load()` takes — `minCardinality`, `minRetained` and `maxGrowth` — judged
      * against what `dest` held before. A refusal is **reported, not thrown**, exactly as on `load()`; branch on
      * `published`. A lost race is the one outcome that still throws ({@link WriteConflictError}), because a
      * materialisation that silently did not take effect is the one thing a caller cannot detect on its own.
      *
-     * A call involving an **expired handle** is refused before any of this. See {@link refuseIfExpired}.
+     * A call involving a handle whose lease has ended, or anything that is not a segment, is refused before any of this.
      */
     intersectInto(dest: Segment, others: Segment[], options?: MaterializeOptions): Promise<MaterializeResult>;
     /**
@@ -1869,10 +1785,6 @@ 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` 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.
      */
@@ -1886,6 +1798,8 @@ export declare class Segment {
      * storage. The pointer refresh is priced at the store's own `cache.genTtlMs`, or at none when the store never
      * refreshes, unless the workload sets `genTtlMs`. See {@link CostReport} — it always includes a verdict (incl.
      * the lose-zone).
+     * @deprecated Moves to `@cloudbitmaps/tools`, a package of its own, with a `size` on `stat()` so a grounded report
+     * needs nothing internal. It is a planning tool, and its price list is as old as the release that ships it.
      */
     costReport(options?: {
         pricing?: PricingProfile;
@@ -1893,5 +1807,5 @@ export declare class Segment {
     }): Promise<CostReport>;
 }
 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, StaleOperandError, isCloudRoaringError, isWriteConflictError, isTransientError, isNotFoundError, isIntegrityError, isValidationError, isLeaseExpiredError, isLeaseLimitError, isStaleOperandError, 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';
+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, StaleOperandError, isCloudRoaringError, isWriteConflictError, isTransientError, isNotFoundError, isIntegrityError, isValidationError, isLeaseExpiredError, isLeaseLimitError, isStaleOperandError, isUnsupportedError, isCapabilityError, isBudgetExceededError, isKeyUnavailableError, 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, RegistryWriteOptions, LeaseEntry, RetentionPolicy, RetireEntry, RetireExpiredOptions, RetireExpiredResult, RetryPolicy, Rng, RollbackResult, SealedRegistrySummary, SegmentInfo, SegmentRef, SegmentSize, SegmentSizing, SetRetentionResult, StorageBackend, StorageCaps, StorageChunkSource, Token, Workload, WrappedDek, } from '@cloudbitmaps/core';