@cloudbitmaps/core 0.18.3 → 0.19.1

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;
@@ -317,3 +310,9 @@ export declare class GroupCost {
  * budget, both before any chunk is read.
  */
 export declare function runCombineMany<R>(compiled: CompiledCombineMany<R>, deps: CombineManyDeps): Promise<CombineManyRun<R>>;
+/**
+ * The token of a row's version (`<generation>:<token>`, as a pin holds it), or `undefined` where the version names no
+ * row. A live version from the `.crbm` source ends with the opened object's fingerprint: read it through
+ * `rowVersionOf` first.
+ */
+export declare function tokenOfVersion(version: string | null | undefined): string | undefined;

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

@@ -51,6 +51,11 @@ export interface CrbmReaderOptions {
 }
 /** An object's fingerprint, from its size and its footer's CRC (see {@link CrbmReader.fingerprint}). */
 export declare const fingerprintFor: (size: number, footerCrc: number) => string;
+/**
+ * A fingerprint spelled short, for a key a read builds on every chunk: its size and its footer's CRC in base 36,
+ * `<size>.<crc>`. Two compact spellings are equal exactly when the fingerprints are.
+ */
+export declare function compactFingerprint(fingerprint: string): string;
 /**
  * Whether the object behind `blob` says it is encrypted, from one tail read of a footer's worth, with no key and no
  * index; a footer that fails its own checks throws, as an open would. For a caller that must not open an object with
@@ -140,8 +145,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 +194,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 {
     /**
@@ -80,10 +81,14 @@ export interface PinnedObject {
     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 live version's resolution named, without the object's fingerprint: `<generation>:<row token>`, or
+ * `<generation>` with no registry. For a caller that compares a live version, from
+ * {@link CrbmStorageChunkSource.currentVersion} or a chunk of its `getChunks`, with a row it read, which names no
+ * object. A live version always ends with the suffix, which holds no `#`, so the match starts at its last `#` and a row
+ * token holding `#` of its own is kept whole. Known limit: a string with no suffix, such as a pin's version or one
+ * from another source, loses its end when its row token itself ends in `#<base 36>.<base 36>`; no caller passes one.
  */
+export declare function rowVersionOf(version: string): string;
 /** 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. */
@@ -98,7 +103,8 @@ export declare class CrbmStorageChunkSource implements StorageChunkSource {
      * needs a clock). Within the TTL a segment's Storage bytes are treated as an immutable snapshot; when the TTL
      * elapses the next read cheaply re-resolves `currentGen` and, only if it advanced (a load published),
      * opens the new generation — so a long-lived source observes new generations within the TTL. The engine pairs
-     * this with a **generation-keyed** cache so a bump never serves a stale decoded chunk. Without a clock or a
+     * this with a cache keyed by {@link currentVersion}, which names the object a reader opened, so a bump never serves
+     * a stale decoded chunk, and neither does a number taken again by another object. Without a clock or a
      * registry there is no timed refresh, and a segment's reader is replaced only when it is evicted, when a read
      * has to fetch from a generation a sweep deleted, or when {@link invalidate} drops it. A segment with no generation yet is not memoized, so
      * it's re-checked until one exists. **Bounded** by a {@link BoundedLru} ({@link CrbmStorageChunkSourceOptions.maxOpenSegments}, default
@@ -143,7 +149,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 keys of the segments this source reads, kept rather than encoded again: a read asks for its segment's snapshot
+     * once per operand, and a stream before every cached chunk it serves, and encoding the names cost about a
+     * microsecond each time.
+     */
+    private readonly keys;
+    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 +195,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
@@ -205,13 +231,16 @@ export declare class CrbmStorageChunkSource implements StorageChunkSource {
      */
     invalidate(ref: SegmentRef): void;
     /**
-     * `<generation>` for a registry-less source, or `<generation>:<row token>` with one. The token moves on every row
-     * write, so an unrelated write (a `setRetention`) costs the segment's decoded chunks once — bounded, and on an
-     * admin path. Exactness in the direction that matters: with a registry, two incarnations can never share a version
-     * string. Without one they can: a name purged and loaded again out of band restarts at the same bare number, and
-     * a live read that reopens it after an eviction reads the new object's chunks beside the old one's cached ones. A
-     * store with no registry cannot write, so that takes a change made from outside it; a pin is kept apart from it by
-     * the fingerprint it records.
+     * `<generation>#<object>` for a registry-less source, or `<generation>:<row token>#<object>` with one: the generation
+     * the segment's snapshot resolved, and the object its reader opened, by that object's size and footer checksum in
+     * base 36, which the open read anyway. The token moves on every row write, so an unrelated write (a `setRetention`)
+     * costs the segment's decoded chunks once — bounded, and on an admin path. Two objects do not share a version
+     * string, as far as their sizes and footer checksums tell them apart, whichever way a number came to name a second
+     * one: a name purged and loaded again (a new row, or with no registry the same bare number), a number taken again
+     * within one row once its object was deleted, or an object put back under its key from outside the library. That
+     * holds however long after its row read a reader opens: a snapshot that a `count()` resolved from the row opens its
+     * reader only when a later read needs it, and the object under the key may have changed in between. The version is
+     * opaque: compare two for equality.
      *
      * This is the call the engine makes **once per operand of every read**, before any chunk fetch, to key its
      * chunk cache, so it heals a swept generation exactly as {@link currentGeneration} does: unhealed, a cold read
@@ -445,13 +474,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 +520,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;
@@ -512,17 +596,17 @@ export declare function publishGenerationKept(registry: IRegistryDriver, key: Ge
     /**
      * Publish only while the segment still has **no registry row**.
      *
-     * The fence for a caller whose decision rests on the row being ABSENT. `expectFrom` and `expectToken`
-     * cannot express it: both compare against a value read from a row, so when there was no row there is
-     * nothing to compare and both are simply omitted — leaving the publish a bare forward-only advance that
-     * happily lands over whatever appeared in the meantime.
+     * The fence for a caller whose decision rests on the row being ABSENT: every load that found no row sets it,
+     * guarded or not. `expectFrom` and `expectToken` cannot express it: both compare against a value read from a
+     * row, so when there was no row there is nothing to compare and both are simply omitted — leaving the publish a
+     * bare forward-only advance that happily lands over whatever appeared in the meantime.
      *
-     * That gap was a silent wipe, not a theoretical one. A guarded load into a segment that did not exist yet
-     * read "no row", so its empty/`minRetained` bounds had nothing to judge and passed vacuously; a
-     * concurrent writer then created the row and published a thousand ids; and the guarded load published an
-     * EMPTY generation over them, reporting `published: true` with no reason. Reproduced through both
-     * `loadSegment` and the `*Into` verbs, which hit it far more often because materialising into a
-     * destination that does not exist yet is the ordinary first run of a pipeline.
+     * Without it, a guarded load into a segment that did not exist yet would judge "no row", pass its empty and
+     * `minRetained` bounds vacuously, and land an EMPTY generation over the ids a concurrent writer had just loaded,
+     * reporting `published: true`. An unguarded load would move the pointer over another first load's generation or
+     * onto a row `setRetention` made, and, where an erasure had deleted its object above that row's pointer, onto an
+     * object that is gone. Materialising into a destination that does not exist yet is the ordinary first run of a
+     * pipeline, so the `*Into` verbs reach this as often as `loadSegment` does.
      */
     expectAbsent?: boolean;
     /**
@@ -735,6 +819,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

@@ -106,6 +106,11 @@ export declare class SegmentEngine {
     private readonly openStreams;
     /** How many times {@link invalidate} has been called: a read compares it with the count it began under. */
     private invalidations;
+    /**
+     * The cache-key prefixes ({@link segmentPrefix}) of the segments this engine reads, kept rather than encoded for each
+     * chunk. A kept prefix is the one {@link invalidate} finds the segment's chunks by.
+     */
+    private readonly prefixes;
     constructor(deps: EngineDeps);
     /** Membership: one chunk lookup — the cache, else one Storage fetch of that chunk. */
     has(seg: SegmentRef, id: number): Promise<boolean>;
@@ -310,6 +315,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 +392,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;
     /**