@cloudbitmaps/core 0.18.3 → 0.19.0

package/dist/core/audit.d.ts

@@ -47,7 +47,7 @@ export type AuditEvent = {
      * downstream system reconciling "the segment should now contain X" needs as much as it needs the publish.
      *
      * `reason` is `'empty'` (an empty result over a non-empty segment, with no `allowEmpty`),
-     * `'min-cardinality'`, `'min-retained'`, or `'superseded'` (another load took the generation number, or the
+     * `'min-cardinality'`, `'min-retained'`, `'max-growth'`, or `'superseded'` (another load took the generation number, or the
      * segment's registry row changed while the load was writing). `cardinality` is what the refused generation
      * would have contained, and `0` for a load that lost its generation number and wrote nothing.
      *
@@ -60,7 +60,7 @@ export type AuditEvent = {
     readonly namespace?: string;
     readonly segment: string;
     readonly generation: number;
-    readonly reason: 'empty' | 'min-cardinality' | 'min-retained' | 'superseded';
+    readonly reason: 'empty' | 'min-cardinality' | 'min-retained' | 'max-growth' | 'superseded';
     readonly cardinality: number;
     readonly unanswered?: true;
 } | {
@@ -121,9 +121,19 @@ export interface IAuditSink {
 export declare const NOOP_AUDIT: IAuditSink;
 /**
  * Wrap a sink so a throwing/buggy `onEvent` can never break the lifecycle operation it observes — audit is
- * strictly observation. Returns {@link NOOP_AUDIT} unchanged (so the no-op case skips even the try/catch alloc).
+ * strictly observation. That covers an `async onEvent` that rejects, whose rejection would otherwise surface as an
+ * unhandled one, which ends a Node process by default. Returns {@link NOOP_AUDIT} unchanged (so the no-op case
+ * skips even the try/catch alloc).
  */
 export declare function safeAudit(sink: IAuditSink): IAuditSink;
+/**
+ * Refuse an `audit` that is not a sink. One without an `onEvent` method (a bare callback, a method named `emit`) would
+ * receive nothing and say nothing, since {@link safeAudit} swallows what calling it throws. Called at the top of each
+ * entry that takes one, before anything irreversible; `undefined` and `null` read as none.
+ */
+export declare function checkedAuditSink(sink: unknown, op: string): void;
+/** Observe the rejection of what a sink's `onEvent` returned, when it returned a promise, so it is never unhandled. */
+export declare function ignoreRejection(returned: unknown): void;
 /** A ready-made sink that records events into an in-memory list — handy for tests + simple audit trails. */
 export declare class RecordingAuditSink implements IAuditSink {
     private readonly recorded;

package/dist/core/bit-route.d.ts

@@ -8,14 +8,14 @@ export interface BitRoute {
 }
 /** Split a u32 id into `{ chunkKey, remainder }`. Throws `ValidationError` for non-u32 input. */
 export declare function splitId(id: number): BitRoute;
-/**
- * Recombine a chunk key + remainder back into the u32 id. Precondition: `chunkKey` is a validated
- * 16-bit value (tier-derived keys are validated upstream in the engine before reaching here, per
- * invariant 5); `remainder` is masked to 16 bits.
- */
 /**
  * Largest legal value inside a chunk payload. A chunk covers `CHUNK_COUNT` ids, so remainders run
  * `[0, CHUNK_COUNT - 1]`. Exported so the engine can assert it on untrusted tier bytes.
  */
 export declare const MAX_REMAINDER: number;
+/**
+ * Recombine a chunk key + remainder back into the u32 id. Precondition: `chunkKey` is a validated
+ * 16-bit value (tier-derived keys are validated upstream in the engine before reaching here, per
+ * invariant 5); `remainder` is masked to 16 bits.
+ */
 export declare function joinId(chunkKey: number, remainder: number): number;

package/dist/core/blob.d.ts

@@ -1,4 +1,7 @@
-/** Streaming append target for a single object being written. */
+/**
+ * Streaming append target for a single object being written. A caller may reuse the buffer it passed to `write` once
+ * the write resolves, so a sink that holds bytes past that copies them.
+ */
 export interface BlobSink {
     write(bytes: Uint8Array): Promise<void>;
 }

package/dist/core/budget.d.ts

@@ -27,11 +27,16 @@ export interface Budget {
 export declare const DEFAULT_BUDGET: Budget;
 /** A store/per-op budget option: partial overrides, or `false` to disable entirely. */
 export type BudgetOption = Partial<Budget> | false;
-/** Resolve a budget option against a fallback to a concrete `Budget`, or `null` when disabled. Validates. */
+/**
+ * Resolve a budget option against a fallback to a concrete `Budget`, or `null` when disabled. Validates: anything but
+ * `false`, an absent value or an object of `{ maxRequests }` is refused, since a cap of the wrong shape (`5`,
+ * `{ maxRequest: 5 }`) would otherwise read as no override and leave the fallback in force. `null` and a key whose value
+ * is `undefined` read as absent.
+ */
 export declare function resolveBudget(opt: BudgetOption | undefined, fallback: Budget): Budget | null;
 /**
  * Resolve a **per-op** budget override against the store's own resolved budget (never the raw global default):
- * `undefined` inherits the store budget as-is (including a disabled `null`); a partial `{}` / omitted
+ * `undefined` or `null` inherits the store budget as-is (including a disabled `null`); a partial `{}` / omitted
  * `maxRequests` inherits the store's *tightening* (so a per-op passthrough of an absent config value can't
  * silently lift a tight tenant ceiling back to the generous default); `{ maxRequests }` replaces it; `false`
  * disables. Falls back to {@link DEFAULT_BUDGET} only when the store itself has no budget (disabled).

package/dist/core/combine-feed.d.ts

@@ -49,13 +49,6 @@ export interface CheckedFeed {
 }
 /** Check a feed's shape, before any record is read. `stored` are the stored operand names, which a fed one may not repeat. */
 export declare function checkFeed(feed: unknown, stored: ReadonlySet<string>): CheckedFeed;
-/**
- * The view a real `Uint32Array` holds, as a plain `Uint32Array` over the same bytes, or `undefined` for anything else.
- * The brand is the `%TypedArray%` `@@toStringTag` getter, which reads the internal slot: it names only a real typed array
- * of that kind (a subclass or another realm's included) and throws for a spoof, a proxy or any other object. The view's
- * extent is then read through the intrinsic getters, so a subclass that overrides `length` or the iterator is never asked.
- */
-export declare function plainUint32(value: unknown): Uint32Array | 'detached' | 'out of bounds' | undefined;
 /** Thrown inside the cursor when it was closed under an operation in flight; never reaches a caller. */
 export declare class FeedClosed extends Error {
 }
@@ -128,6 +121,9 @@ export declare class FeedCursor {
     /** The next record, checked and converted (`ops` is `null` when its key is outside the range); `undefined` at the end. */
     private pull;
     private end;
+    /** How many records the feed has handed over, the one being read included: what names a record in an error. */
+    private records;
+    /** Refuse the record being read, named by its position in the feed: its key narrows the ids it holds to a range. */
     private refuse;
     private charge;
     private giveBack;

package/dist/core/combine-many.d.ts

@@ -1,5 +1,5 @@
 import type { CodecBitmap, CodecInterface } from './codec.js';
-import type { HeldChunks } from './combine-held.js';
+import type { IMetricsSink } from './metrics.js';
 import type { CombineManyFeed } from './combine-feed.js';
 import type { CombineExpr } from './combine-expr.js';
 import type { Clock } from './determinism.js';
@@ -18,9 +18,9 @@ export interface CombineManyOperand {
     readonly name: string;
     readonly ref: SegmentRef;
     /**
-     * Throws the typed error when this operand's handle can no longer be read: a lease that ended or was released, or a
-     * deadline that passed. Called before each chunk key the operand is read at, so a lapse fails the outputs that read
-     * it and never reads empty.
+     * Throws the typed error when this operand's handle can no longer be read: a lease that ended or was released.
+     * Called before each chunk key the operand is read at, so a lapse fails the outputs that read it and never reads
+     * empty.
      */
     readonly check?: () => void;
     /** The generation the operand is pinned to: `null` when pinned to a segment with none, `undefined` when not pinned. */
@@ -44,25 +44,6 @@ export interface CombineManyOperand {
         readonly token: string;
         readonly fingerprint?: string | null;
     } | null>;
-    /**
-     * Set for an operand held in memory: its chunks are read from here, never from the source, and `ref`, `pinned*` and
-     * `current` are not used. It has no registry row, so nothing about it can move; what can invalidate it is an erasure in
-     * the store that made it ({@link CombineManyHeld.moved}) or its release.
-     */
-    readonly held?: CombineManyHeld;
-}
-/** An operand held in memory, as the pass reads it. */
-export interface CombineManyHeld {
-    /** The operand's chunks. Once released, reading one throws. */
-    readonly chunks: HeldChunks;
-    /**
-     * Whether an erasure has run in the store since the operand began to be made, one still running included, so what it holds may include an erased id. Checked
-     * before the call's first request, before each chunk key is read and immediately before each publish of an output that
-     * reads it.
-     */
-    readonly moved: () => boolean;
-    /** Whether holding no id is accepted: an include then empties an AND and an exclude subtracts nothing. */
-    readonly mayBeEmpty: boolean;
 }
 /** What one output asks for. */
 export interface CombineManyOutput<R> {
@@ -74,7 +55,7 @@ export interface CombineManyOutput<R> {
     readonly metadata?: GenerationMetadata;
     /** Overrides the call's `keep`. */
     readonly keep?: number;
-    /** Throws to refuse the publish: the destination's lease or deadline, checked again just before it. */
+    /** Throws to refuse the publish: the destination's lease, checked again just before it. */
     readonly beforePublish?: () => void;
     /**
      * The requests a settled publish made that its value proves, for the call's totals by class; absent, a publish adds
@@ -116,6 +97,12 @@ export interface CombineManyRequest<R> {
      * outputs as one group; a fed output publishes only after the whole feed was read and checked.
      */
     readonly feed?: CombineManyFeed;
+    /**
+     * The outputs' publish callbacks judge their finished chunks and must write nothing. Each is still charged the object
+     * a write would hold, so a dry run admits, defers and refuses for memory exactly where a publish would, and none
+     * counts as a publish in the stats.
+     */
+    readonly dryRun?: boolean;
 }
 export interface CombineManyDeps {
     /** Reads the operands: already pinned where they are, and retrying as the store's reads do. */
@@ -123,6 +110,12 @@ export interface CombineManyDeps {
     readonly codec: CodecInterface;
     readonly clock: Clock;
     readonly maxBitmapBytes?: number;
+    /**
+     * Where the call reports a `storage.get` event for each range request it sends, as a combine does; absent, it reports
+     * none. The call never looks up the chunk cache, so it reports no `cache` event. A sink that throws is ignored, as
+     * {@link safeMetrics} makes it.
+     */
+    readonly metrics?: IMetricsSink;
 }
 /** What one output came to. */
 export type CombineManyOutcome<R> = {
@@ -262,11 +255,6 @@ export declare function compileCombineMany<R>(request: CombineManyRequest<R>): C
  * without checking the expressions again.
  */
 export declare function rebindCombineMany<R>(compiled: CompiledCombineMany<R>, operands: readonly CombineManyOperand[]): CompiledCombineMany<R>;
-/**
- * The resident bytes a group needs, kept as outputs are added so that one is priced in work proportional to its own
- * operands, not to the group's size: its buffered outputs, its operand streams, the chunks being evaluated, the objects
- * being published beside the buffers, and the key lists of its own plan.
- */
 /** What {@link GroupCost} reads of an output. */
 export interface GroupCostItem {
     readonly bound: number;
@@ -287,6 +275,11 @@ export declare const combineWork: {
     operandSteps: number;
     planBuilds: number;
 };
+/**
+ * The resident bytes a group needs, kept as outputs are added so that one is priced in work proportional to its own
+ * operands, not to the group's size: its buffered outputs, its operand streams, the chunks being evaluated, the objects
+ * being published beside the buffers, and the key lists of its own plan.
+ */
 export declare class GroupCost {
     private readonly streamBytes;
     private readonly publishConcurrency;

package/dist/core/consistency.d.ts

@@ -18,7 +18,6 @@
  */
 import type { IStorageDriver, IRegistryDriver } from './ports.js';
 import type { IKeystore } from './crypto.js';
-/** Default in-flight fan-out for the consistency scan — bounded, no thundering herd. */
 /**
  * Default ceiling on how many registry records one consistency check may hold resident: 250,000.
  *

package/dist/core/cost.d.ts

@@ -83,6 +83,8 @@ export interface RedisSizing {
  * because an `m6g` or `r6g` with the same memory costs less. It is the cheapest cluster of THIS kind; Redis bought
  * another way costs less — one replica a shard a third less, ElastiCache for Valkey 20% less a node, reserved nodes
  * less again — so against those the saving the verdict reports is smaller. Pass their prices to compare with them.
+ * @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.
  */
 export declare const ELASTICACHE_REDIS_US_EAST_1_ONDEMAND: RedisSizing;
 /**
@@ -90,6 +92,9 @@ export declare const ELASTICACHE_REDIS_US_EAST_1_ONDEMAND: RedisSizing;
  * at $0.158 an hour each: 3 × 730 h × $0.158 = $346.02, published to the dollar. The per-request crossovers on the
  * benchmarks page are drawn against this one cluster, whatever the data size; pass it as `pricing.redis` to compare
  * with it. It is not the cheapest cluster for any size of data: three cache.m6g.large hold the same memory for less.
+ *
+ * @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.
  */
 export declare const ONE_REDIS_HA_CLUSTER: Readonly<{
     monthlyUSD: number;
@@ -97,6 +102,8 @@ export declare const ONE_REDIS_HA_CLUSTER: Readonly<{
 /**
  * Default profile — **AWS us-east-1, on-demand**, mid-2026, from the fact-checked published pricing rather than
  * copied from a blog post, with Redis sized to the data. Override it for your region, cloud, or committed term.
+ * @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.
  */
 export declare const AWS_US_EAST_1_ONDEMAND: PricingProfile;
 /** Sustained access pattern. All rates default to 0; unspecified ⇒ that op contributes nothing. */
@@ -186,8 +193,8 @@ export interface Workload {
      */
     readonly genTtlMs?: number;
     /**
-     * Segments the retention sweep (`retireExpired`) retires a month. Each costs 9 registry reads, 3 writes and a
-     * delete with {@link Workload.conditionalDelete} on, and 8 reads and 3 writes with it off, priced at the GET and PUT
+     * Segments the retention sweep (`retireExpired`) retires a month. Each costs 7 registry reads, 2 writes and a
+     * delete with {@link Workload.conditionalDelete} on, and 6 reads and 2 writes with it off, priced at the GET and PUT
      * rates, a delete unbilled, as S3 leaves it. Default
      * **0**.
      */
@@ -324,12 +331,16 @@ export declare const RETENTION_SWEEP_REQUESTS: Readonly<{
  * **Planning** cost estimate — pure, no instance or live data needed (sizing, sales, what-if). Segment sizes
  * are taken as given (or roughly derived from cardinality); use the grounded `segment.costReport()` for
  * exact, real sizes. 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.
  */
 export declare function estimateCost(input: EstimateInput): CostReport;
 /**
  * **Grounded** report from a real segment byte total (from the `.crbm` index) + a supplied workload. Used by
  * `Segment.costReport()` in the facade. `grounded` defaults to true (the size is exact, not estimated); the
  * caller passes `grounded: false` + a note when the Storage source can't measure size.
+ * @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.
  */
 export declare function groundedReport(input: {
     readonly storageBytes: number;

package/dist/core/crbm/reader.d.ts

@@ -140,8 +140,8 @@ export declare class CrbmReader {
     /**
      * Range-GET one chunk's payload, verifying its CRC32C before returning. Returns `null` if the chunk is
      * absent. Throws `IntegrityError` on a CRC mismatch (the bytes must never reach the native
-     * deserializer). The returned buffer is a **read-only view** owned by the reader/driver — callers must
-     * not mutate it.
+     * deserializer). The returned bytes may be shared (a small generation's chunks are kept by the reader and handed out
+     * again), so callers must not change them.
      */
     getChunk(chunkKey: number): Promise<Uint8Array | null>;
     /**
@@ -189,7 +189,8 @@ export declare class CrbmReader {
      * others; `options.now` times each request for `options.onRequest`, which hears of every range request that was sent, once, when
      * it settles: taken, abandoned after the consumer stopped, or failed (a reader has no clock of its own, so `ms` is 0
      * without one).
-     * A plain chunk is a writable view into the range it was read in: copy a chunk to keep it.
+     * A plain chunk is a view into the range it was read in, so keeping it keeps that whole range: copy a chunk to keep it
+     * alone. Callers must not change it, as with {@link getChunk}.
      *
      * A stream that fails (a range that errors, a chunk that fails its check) raises at once and sends nothing further:
      * the ranges it still had in flight finish in the background, are not retried and never raise. Its `settled()`

package/dist/core/crbm-storage-source.d.ts

@@ -1,4 +1,5 @@
 import { type IAuditSink } from './audit.js';
+import { ValidationError } from './errors.js';
 import type { Yielder } from './cooperative.js';
 import type { Clock, Rng } from './determinism.js';
 import type { PublishedKept } from './generation-gc.js';
@@ -6,7 +7,7 @@ import type { Aead, CrbmCrypto, IKeystore, WrappedDek } from './crypto.js';
 import type { ChunkRef, ChunkRead, ReadChunksOptions, StorageChunkSource, GenerationMetadata, GenerationSummary, GenKey, IStorageDriver, IRegistryDriver, RegistryRecord, RegistrySummary, SegmentRef, SegmentSize, Token } from './ports.js';
 import { CrbmReader } from './crbm/reader.js';
 import type { CrbmReaderOptions } from './crbm/reader.js';
-import type { CodecBitmap, CodecInterface, EncodedChunk } from './codec.js';
+import type { CodecBitmap, CodecInterface } from './codec.js';
 import { ChunkLoadInput, DecodedLoadInput } from './load-input.js';
 export interface CrbmStorageChunkSourceOptions extends CrbmReaderOptions {
     /**
@@ -79,11 +80,6 @@ export interface PinnedObject {
     readonly version: string;
     readonly fingerprint?: string;
 }
-/**
- * What one resolution of a segment's pointer found: the target, and what its row says of the generation, each
- * computed only when asked for. The key is unwrapped once however many ask, and a failure is not remembered, so a
- * transient fault in the keystore is asked again.
- */
 /** What a pin that leases its generation does between reading the row and opening the object. */
 export interface PinLease {
     /** Write the lease against the row the pin read: its token, or `'moved'` when the pointer is no longer at the generation. */
@@ -143,7 +139,20 @@ export declare class CrbmStorageChunkSource implements StorageChunkSource {
     private readonly keepChunkBytesUpTo;
     private readonly clock;
     private readonly currentGenTtlMs;
+    /**
+     * Whether the segment's pointer is re-read on a timer: it needs a clock (the TTL), a registry (the cheap row read; with
+     * none, resolving is a listing of the bucket) and a TTL above 0. It decides the keeping of chunk bytes, the TTL lapse
+     * and the refresh interval the cost report prices, so it is decided once.
+     */
+    private readonly timedRefresh;
     constructor(driver: IStorageDriver, options?: CrbmStorageChunkSourceOptions);
+    /**
+     * The last few segments' keys, newest first. A stream asks for its segment's snapshot before every cached chunk it
+     * serves, and a combine alternates between a few operands, so comparing two names beats encoding them again, which
+     * cost about a microsecond a chunk.
+     */
+    private readonly recentKeys;
+    private keyOf;
     /**
      * The segment's live snapshot, refreshing on the TTL. Cheap within the TTL window. The snapshot holds the resolved
      * target, and its reader once a read has asked for one.
@@ -176,6 +185,13 @@ export declare class CrbmStorageChunkSource implements StorageChunkSource {
      * this.
      */
     get pointerRefreshMs(): number;
+    /**
+     * Whether a stream reading from `snap` must resolve its segment again before its next chunk, as a read of one chunk
+     * would: the snapshot's TTL has lapsed, an invalidation has happened since `epoch`, or the snapshot is no longer the
+     * one the reader cache holds for the segment (it let it go, or another read installed a newer one). Else nothing can
+     * have moved it, and the check costs a compare and a lookup.
+     */
+    private mayHaveMoved;
     private expired;
     /**
      * The segment's current generation number — the engine keys its chunk cache by this so a generation bump
@@ -445,13 +461,6 @@ export declare function writeCrbmGeneration(driver: IStorageDriver, key: GenKey,
     sha256: string;
     fingerprint: string;
 }>;
-/**
- * The chunks a load of ids, or of a decoded bitmap, writes: ascending by key, each non-empty and run-optimized. A decoded
- * bitmap writes its own chunks, which never touches an id. Ids, and the bitmap of a codec that cannot encode its own
- * chunks, are bucketed per chunk instead; both give the same bytes. Exported for a caller that holds the chunks itself
- * instead of writing them.
- */
-export declare function encodedChunksOfInput(ids: Iterable<number> | AsyncIterable<number> | DecodedLoadInput, codec: CodecInterface, clock: Clock | undefined): Promise<Iterable<EncodedChunk>>;
 /**
  * Whether the object under `key` is provably the one `fingerprint` names ({@link CrbmReader.fingerprint}), from one
  * read of its footer. False when it is another object, when it is gone, and when the read fails in any way: a caller
@@ -498,6 +507,68 @@ export declare function writeCrbmGenerationStream(driver: IStorageDriver, key: G
     clock?: Yielder;
     metadata?: GenerationMetadata;
 }): Promise<StreamWriteResult>;
+/**
+ * Point a segment's registry `currentGen` at `key.generation` — the publish step that makes a freshly-written
+ * generation the authoritative latest (so registry-aware readers see it). **Forward-only and idempotent:**
+ * if the registry has no row it creates one; if it's already at/ahead of `key.generation` it's a no-op (an
+ * out-of-order/duplicate publish never regresses the pointer); otherwise it advances via compare-and-swap,
+ * retrying a few times under contention. Separated from the Storage write so callers can publish atomically
+ * after the immutable object is durable (write-then-publish).
+ *
+ * **Throws** rather than returning, in two cases, because each would otherwise create a state no reader can
+ * recover from: a `destroyed` (crypto-shredded) row, where advancing the pointer would name an object encrypted
+ * under a shredded key; and an advance carrying **new** `wrappedDeks`, which would either strand that key or make
+ * the row advertise encryption over cleartext generations. Contention that never clears throws
+ * {@link WriteConflictError} after the retries.
+ *
+ * **`expectFrom` turns forward-only into read-modify-write.** Forward-only is the right rule for a writer whose
+ * content does not depend on what was current — a load computes its ids upstream, so publishing over a newer
+ * generation loses nothing the loader knew about. It is the WRONG rule for a writer that *derived* its content
+ * from a particular generation: the erasure rewrite streams generation `from` and clears one bit, so publishing
+ * it over a newer generation silently discards whatever that generation added. Passing `expectFrom` makes the
+ * publish land only while the pointer is still exactly there, and return `false` otherwise, so the caller can
+ * report `superseded` and re-derive. The compare-and-swap itself carries the token read in the same iteration,
+ * so the check and the write see the same row.
+ *
+ * **`expectToken` fences the LINEAGE, and a derived writer needs both.** A generation number identifies a
+ * generation only within one incarnation of a name: the numbering restarts at `0` once the row is purged and
+ * the bucket empty, so a name that is retired and re-created has a *different* segment wearing the *same*
+ * `currentGen`. `expectFrom` alone matched it — and an erasure rewrite then published one incarnation's content
+ * over another's, deleted the live objects with its `keep: 0` collection, and returned `erased: true`. The row's
+ * OCC token is the identity that survives this: a shipped registry's later `create` gets a token never issued before
+ * under that name, but for a collision of probability 2^-128 per pair of incarnations, so no token is reused across them.
+ *
+ * Pass the token read alongside `expectFrom` and the publish lands only on the same row it was derived from.
+ * The check is deliberately **conservative**: the token also changes on writes that are not supersessions at
+ * all (a `setRetention`, a due-index reindex), so such a write makes a derived publish report `superseded` and
+ * the caller re-derive. That costs a re-run on a rare, unrelated write; the alternative costs a segment.
+ *
+ * **The driver sends a registry write once, and an unanswered one is reconciled by its effect.** A `create` or
+ * `compareAndSwap` that fails with {@link TransientError} (a throttle, a lost response, a timeout) may or may not
+ * have landed, and may still be in flight. The publish reads the row once more and decides from what it holds:
+ *
+ * - the pointer names `key.generation`, on the incarnation the write was made against (the row's `createdAt`), and
+ *   `holdsOwnObject` proves the object under it the caller's: the write landed, and the publish returns `true`. Only
+ *   the writer of a write-once object publishes its number, and a number is never taken while an object holds it;
+ * - the row is still the one the write was made against (the same token, or still no row): the write may land yet. The
+ *   publish then waits, on the injected clock, and sends a **new** write from the row it just read: a request of its
+ *   own, not a replay of the driver's, carrying the same version, so under the registry's fence at most one of the two
+ *   lands and the other meets a conflict, which the next read settles. At most {@link UNANSWERED_RESENDS} follow, after
+ *   a wait under 500 ms, then 1 s, then 2 s (full jitter when an `rng` is given); each is settled the same way. Still
+ *   unanswered, or with no clock to wait on, this throws the registry's own `TransientError` and writes nothing more.
+ *   A caller must not delete its object on it;
+ * - anything else: the row has moved past the state the write was conditioned on, so that write can never land, and
+ *   the publish goes on as after a lost race, from the row it just read. A pointer at `key.generation` that is not over
+ *   the caller's own object, or is on another incarnation, is a lost race too and answers `false`, never an already
+ *   current re-publish.
+ *
+ * A failed read throws `TransientError` too. The same check of the pointer runs after a {@link WriteConflictError},
+ * so a write that landed and then met itself (a registry whose client re-sent it) is not taken for a lost race.
+ *
+ * **A `summary` goes in the same write that moves the pointer**, so a reader that sees this generation as current
+ * sees the count and metadata that describe it, and every attempt sends the same one. It must be the shape the row's
+ * keys call for: sealed for an object written with a key, clear for one written without.
+ */
 export declare function publishGenerationKept(registry: IRegistryDriver, key: GenKey, options?: {
     wrappedDeks?: readonly WrappedDek[];
     expectFrom?: number;
@@ -735,6 +806,8 @@ export interface LoadAhead {
         readonly aead: PromiseLike<Aead>;
     };
 }
+/** What a load with `requireEncryption` meets on a segment that already has a cleartext generation. */
+export declare function cleartextUnderRequiredEncryption(ref: SegmentRef, currentGen: number): ValidationError;
 /**
  * {@link bulkLoadCrbmGeneration} for a load whose number, and perhaps its key, are still being fetched: the same
  * options, with the same meaning, and the same writes. The number is joined only where the object is written.

package/dist/core/discover.d.ts

@@ -38,10 +38,9 @@ export interface SegmentInfo extends SegmentRef {
  * distinction between "never loaded" and "loaded, and genuinely empty" is the one `count()` cannot make and
  * the main reason this function is worth having.
  *
- * Two states answer `true` where a read still gives you nothing, and neither is this call's job to detect: a
+ * One state answers `true` where a read still gives you nothing, and it is not this call's job to detect: a
  * **torn restore** (`missing-storage-generation` — a live pointer whose object was deleted) makes reads *throw*
- * `NotFoundError` rather than answer empty, and `runConsistencyCheck` is the call that looks for it; and a
- * handle carrying an expired `expiresAt` reads as empty by a rule that lives on the handle, not on the row.
+ * `NotFoundError` rather than answer empty, and `runConsistencyCheck` is the call that looks for it.
  *
  * Not a lock. A segment can be created or dropped between this call and whatever you do next; if the answer
  * has to hold, use the fences that exist for it — `load`'s guard, or `expectFrom`/`expectToken` on a publish.
@@ -69,8 +68,7 @@ export declare function segmentExists(ref: SegmentRef, registry: IRegistryDriver
  * disagree with the registry it reports on — a filtered enumeration that looks complete is how a retention
  * sweep ends up permanently skipping rows nobody can see. Filter on `status`/`currentGen` yourself, or use
  * {@link segmentExists} for the "does the pointer resolve" question. Internal bookkeeping rows are the one
- * exclusion, and only on an unscoped scan: they are not segments, and a caller naming their namespace still
- * sees them.
+ * exclusion: they are not segments, an unscoped scan skips them, and their namespace is one a caller cannot name.
  */
 export declare function listSegments(registry: IRegistryDriver, options?: {
     namespace?: string;

package/dist/core/engine.d.ts

@@ -310,6 +310,17 @@ export declare class SegmentEngine {
      * lookup by generation number would never find a chunk cached under a stream's version.
      */
     private streamedVersion;
+    /**
+     * `hit`, a chunk cached under the version a multi-chunk read planned under, if that is still the segment's version;
+     * else the chunk as it is now. A read resolves the segment again before it serves each chunk, which the source's
+     * stream does for the chunks it delivers; a chunk served from the cache is checked here, or a read whose chunks are
+     * all cached would go on serving the generation it planned under, an erased id included, for as long as it is pulled.
+     * Within `cache.genTtlMs` the source answers from its snapshot, so the check is a lookup, not a request. `report`:
+     * emit the `cache` event for this lookup, which a key counted when its stream opened does not. `streamed`: the read
+     * this chunk belongs to, which a move carries to the version now current, so the rest of it looks there: a read whose
+     * stream is not yet open reads the rest as one stream, not a chunk at a time.
+     */
+    private cachedIfCurrent;
     /** The cache key of a chunk: by the version it was read under, or by segment and key alone for a source with none. */
     private chunkCacheKey;
     /** The segment's chunk keys, ascending, checked as untrusted tier data. */
@@ -376,6 +387,10 @@ export declare class SegmentEngine {
      *
      * The returned instance is **shared** (it may be the cached one, and every caller that joined a read gets the same
      * one): callers read it or clone it, never mutate it.
+     *
+     * `recheck`: `gen` was planned for a read of many chunks, so a cached chunk is served only while it is still the
+     * segment's version ({@link cachedIfCurrent}). A point read resolves `gen` just before it asks, and passes none.
+     * `report`: emit the `cache` event for this lookup; a key already counted for this read does not.
      */
     private storageChunk;
     /**

package/dist/core/erase-id.d.ts

@@ -68,9 +68,10 @@
  * A live read still fetching from the collected generation heals forward to the rewrite, and a pin of it fails with
  * `NotFoundError` for any chunk it has yet to read: that is the documented cost of physical deletion on return. **Do not re-load the id while erasing it**: a load that lands after this rewrite
  * carries whatever its source held, and the library cannot know that source was meant to exclude the id.
- * A load already in flight is the same case: it writes its object above the pointer before it publishes, and an
- * erasure that finds the id in that object deletes it as it does any holder there, so a load that then publishes
- * leaves the pointer naming a missing object.
+ * A load already in flight writes its object above the pointer before it publishes. An erasure that finds the id in that
+ * object writes the row before deleting it, so the load's publish, fenced on the row it read, is refused
+ * (`published: false`) and the pointer never names a missing object (see `fenceInFlight`). A first load onto a row with
+ * no pointer has nothing to be fenced on, so an erasure that finds the id in its object refuses instead.
  */
 import { type IAuditSink } from './audit.js';
 import type { CodecInterface } from './codec.js';
@@ -137,8 +138,9 @@ export interface EraseIdResult {
      * re-run settles it, which is why it is the documented action for this reason and for no other.
      *
      * The first three reasons are also returned when the row changes *underneath* a call already in flight, not
-     * only when it is read up front — a concurrent `dropSegment` gives `'destroyed'`, a retention sweep that purges
-     * the row gives `'absent'`. A caller branching on `reason` never has to care which it was.
+     * only when it is read up front — a concurrent `dropSegment` gives `'destroyed'`, once the tombstone's objects have
+     * been searched as a fresh call searches them, and a retention sweep that purges the row gives `'absent'`. A caller
+     * branching on `reason` never has to care which it was.
      */
     readonly reason?: 'absent' | 'destroyed' | 'no-generation' | 'not-member' | 'superseded';
     /**

package/dist/core/erasure.d.ts

@@ -14,7 +14,7 @@
  */
 import { type IAuditSink } from './audit.js';
 import { type ChurnDeps } from './leases.js';
-import type { IStorageDriver, IRegistryDriver, SegmentRef } from './ports.js';
+import type { IStorageDriver, IRegistryDriver, RegistryRecord, SegmentRef } from './ports.js';
 export interface EraseDeps extends ChurnDeps {
     readonly registry: IRegistryDriver;
 }
@@ -165,7 +165,7 @@ export interface DropResult {
  * but the object exists, and it holds the complete set. A single list-then-delete misses it entirely. The re-sweep
  * converges because the tombstone *is* a hard fence on **publishing**, so only loads already under way can write
  * and they are finite. One that writes after the last pass deletes its own object when its publish is refused, as a
- * refused load does under a `destroyed` row; only one whose process stops in between, or whose publish fails without
+ * refused load and a refused erasure rewrite do under a `destroyed` row; only one whose process stops in between, or whose publish fails without
  * a definite answer (a lost response, a timeout), leaves it behind, for a re-run of the drop, and
  * `generationsRemaining` cannot report an object written after this call returned.
  *
@@ -188,3 +188,23 @@ export declare function dropSegment(ref: SegmentRef, deps: DropDeps, options: {
     dryRun?: boolean;
     audit?: IAuditSink;
 }): Promise<DropResult>;
+/**
+ * What the retention sweep adds to a drop. `wanted` is judged on every row the shred is about to replace with a
+ * tombstone, so a row whose expiry was extended or cleared after the sweep looked, or that someone else has already
+ * destroyed or purged, is left as it is rather than retired. `stamp` is the `retention` the tombstone carries, written
+ * in the shred's own write, so only a tombstone a sweep wrote ever carries a sweep's mark, which is what lets a later
+ * sweep purge it and never a crypto-shred's.
+ */
+export interface SweepDrop {
+    readonly wanted: (row: RegistryRecord) => boolean;
+    readonly stamp: (retention: RegistryRecord['retention']) => RegistryRecord['retention'];
+}
+/**
+ * {@link dropSegment}, with what a retention sweep adds: `null` when `sweep.wanted` refused the row, with nothing
+ * written or deleted.
+ */
+export declare function dropSegmentFor(ref: SegmentRef, deps: DropDeps, options: {
+    confirmSegment: string;
+    dryRun?: boolean;
+    audit?: IAuditSink;
+}, sweep: SweepDrop | undefined): Promise<DropResult | null>;

package/dist/core/errors.d.ts

@@ -64,8 +64,8 @@ export declare class LeaseLimitError extends CloudRoaringError {
 /**
  * An operand a call relied on changed while the call ran, so what the call built from it is not published. Carries the
  * operand's name in the call and why it is stale (`'moved'`: it was pinned at a generation and its pointer has since
- * moved; `'erased'`: an erasure ran in the store after a call with a feed began, or after a held operand the call reads
- * was made, so what the feed gave it, or what the operand holds, may hold an erased id), under the stable `code`
+ * moved; `'erased'`: an erasure ran in the store after a call with a feed began, so what the feed gave it may hold an
+ * erased id), under the stable `code`
  * `'stale-operand'`. Deterministic: run the call again against the current operand.
  */
 export declare class StaleOperandError extends CloudRoaringError {
@@ -150,4 +150,12 @@ export declare function isNotFoundError(err: unknown): err is NotFoundError;
 export declare function isIntegrityError(err: unknown): err is IntegrityError;
 /** Invalid caller input. */
 export declare function isValidationError(err: unknown): err is ValidationError;
+/** This build or this store's wiring cannot do what was asked, though nothing is malformed. */
+export declare function isUnsupportedError(err: unknown): err is UnsupportedError;
+/** A driver lacks a capability the store's wiring needs. */
+export declare function isCapabilityError(err: unknown): err is CapabilityError;
+/** A call would pass its per-op request budget, so it was refused before fanning out. */
+export declare function isBudgetExceededError(err: unknown): err is BudgetExceededError;
+/** No key the keystore holds can unwrap an encrypted segment's data key. */
+export declare function isKeyUnavailableError(err: unknown): err is KeyUnavailableError;
 export {};

package/dist/core/load-input.d.ts

@@ -57,12 +57,11 @@ export declare class ChunkLoadInput {
  * Check a load's input and decode a bitmap input, before the load makes any request.
  *
  * @returns ids unchanged, to be consumed lazily by the write, or the decoded bitmap.
- * @param subject names what takes the input in a refusal's message.
  * @throws {ValidationError} for a byte array passed as ids; bytes that are malformed, over the cap, or followed by
  * more bytes; a `{ bitmap }` with no `serialize` method, or whose `serialize('portable')` returns no `Uint8Array`;
  * and anything that is none of the three inputs. An error the caller's own `serialize` throws propagates as it is.
  */
-export declare function prepareLoadInput(input: LoadInput, codec: CodecInterface, subject?: string): Iterable<number> | AsyncIterable<number> | DecodedLoadInput;
+export declare function prepareLoadInput(input: LoadInput, codec: CodecInterface): Iterable<number> | AsyncIterable<number> | DecodedLoadInput;
 /**
  * Portable bytes a caller holds, checked and decoded by the codec's safe deserializer: the one check every bitmap
  * input of a load goes through, and what a flavor offers its users to decode bytes they hold themselves.