@cloudbitmaps/core 0.10.0 → 0.11.0

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

@@ -6,9 +6,10 @@
  * publish part-way through an export, a send or a reconciliation means the second half of the job describes a
  * different instant than the first — and nothing in the result says so.
  *
- * **A pin is a generation NUMBER, not a captured reader.** The number is immutable, so the reader behind it can
- * live in the shared bounded LRU and be evicted freely: re-opening at the same number reproduces the same
- * bytes. Holding the reader instead put every live pin outside the library's memory ceiling.
+ * **A pin is a generation number and the object it named, not a captured reader.** The reader behind it can live
+ * in the shared bounded LRU and be evicted freely: re-opening at the same number reopens the same object, or, if
+ * the name was purged and loaded again since, finds another one, which the pin's fingerprint refuses. Holding the
+ * reader instead put every live pin outside the library's memory ceiling.
  *
  * **Other segments are not pinned, and that is the contract, not an omission.** `snap.intersect([other])` reads
  * `snap` at its pinned generation and `other` at whatever is current. Pinning the whole query means pinning
@@ -22,10 +23,18 @@
  */
 import type { ChunkRef, StorageChunkSource, SegmentRef, SegmentSize } from './ports.js';
 import type { CrbmStorageChunkSource } from './crbm-storage-source.js';
-/** What a pin holds for one segment: the generation, and the version identifying those exact bytes. */
+/**
+ * What a pin holds for one segment: the generation, the version identifying those exact bytes, and the pinned
+ * object's fingerprint, so a read can tell that the generation it opens is still that object.
+ *
+ * `fingerprint` is optional so that a pin built by hand, before there was one, still compiles. Nothing checks the
+ * object such a pin reads, so it cannot tell a name purged and loaded again from the segment it pinned.
+ * `seg.pin()` always records it.
+ */
 export interface PinnedAt {
     readonly generation: number | null;
     readonly version: string | null;
+    readonly fingerprint?: string | null;
 }
 export declare class PinnedStorageChunkSource implements StorageChunkSource {
     private readonly inner;
@@ -44,6 +53,8 @@ export declare class PinnedStorageChunkSource implements StorageChunkSource {
      * wrong answer this exists to prevent.
      */
     pins: ReadonlyMap<string, PinnedAt>);
+    /** The unpinned segments refresh as the store's own source does; a pinned one never does. */
+    get pointerRefreshMs(): number;
     /**
      * The pin for this segment, or `undefined` if it is not pinned here.
      *
@@ -58,10 +69,20 @@ export declare class PinnedStorageChunkSource implements StorageChunkSource {
     cardinalities(ref: SegmentRef): Promise<ReadonlyMap<number, number> | null>;
     currentGeneration(ref: SegmentRef): Promise<number | null>;
     /**
-     * A pinned segment reports the version captured when it was pinned, so its decoded chunks are cached under a
-     * key that cannot collide with the live generation's. That is what lets a pinned handle share the store's
-     * chunk cache safely; sharing it on a generation-only key was how a pinned read could resurrect an id that
-     * `eraseIdFromSegment` had reported physically gone.
+     * A pinned segment reports the version captured when it was pinned, marked as a pin's, so its decoded chunks
+     * are cached under keys that no live read writes. A live read keys its fetches by the version it resolved when
+     * it began, but is served whatever generation the live source holds when each fetch lands — after a publish
+     * and a lapsed `cache.genTtlMs`, a reader-cache eviction, a sweep that heals the read forward, or an
+     * invalidation, a different one — so an entry under a live version can hold another generation's chunk.
+     * Invariant 3 lets that live call see it, and later live reads resolve the current version and never look the
+     * entry up; a pin sharing the key would be handed it, and return a read that mixed two generations. A pinned
+     * read fetches exactly its own generation, so the entries it fills are always that generation's.
+     *
+     * The pin still shares the store's chunk cache, and its memory ceiling; what it gives up is a hit on a chunk a
+     * live read of the same version cached, which costs a pin one GET per such chunk. Live reads make no call for it,
+     * though a pin's entries share the cache's bound with theirs, so under a small `cache.maxChunks` each can evict
+     * the other. The version, not the bare generation, is still what the key carries: sharing on a generation-only
+     * key was how a pinned read could resurrect an id that `eraseIdFromSegment` had reported physically gone.
      */
     currentVersion(ref: SegmentRef): Promise<string | null>;
     exists(ref: SegmentRef): Promise<boolean>;

package/dist/core/ports.d.ts

@@ -11,6 +11,17 @@ import type { BlobSink } from './blob.js';
 import type { WrappedDek } from './crypto.js';
 /** Opaque optimistic-concurrency token — unique per write, compared by equality only. */
 export type Token = string;
+/**
+ * The address of one segment: a `namespace` and a `segment` name, both any non-empty string of at most 256
+ * characters once encoded for storage. Omitting the namespace addresses a different segment from one that names it.
+ *
+ * **A namespace starting with `cbm.due.` is reserved**, and every call of the store, and of the free functions
+ * behind it, that takes a ref or a `namespace` option throws `ValidationError` for one. The library keeps the due
+ * index there (one pointer row per expiring segment), and every fleet-wide scan skips those rows as bookkeeping, so a
+ * segment in such a namespace would be invisible to an erasure, a consistency check, an export and a retention sweep.
+ * A driver takes the prefix, since the due index's own rows go through it. Only that exact prefix is reserved:
+ * `cbm.dueX` and `cbmdue.eu` are ordinary namespaces, and a segment name is never restricted.
+ */
 export interface SegmentRef {
     readonly namespace?: string;
     readonly segment: string;
@@ -39,6 +50,12 @@ export interface StorageChunkSource {
      * payload reads), or `null` if the segment has no Storage generation. Powers the grounded `costReport()`.
      */
     sizeOf?(ref: SegmentRef): Promise<SegmentSize | null>;
+    /**
+     * Optional: how often this source re-reads a segment's pointer while the segment is being read, in ms, or 0 if
+     * it never does. The grounded `costReport()` prices the pointer refresh at this interval; a source that omits it
+     * is priced at the store's default.
+     */
+    readonly pointerRefreshMs?: number;
     /**
      * Optional: the current generation's **per-chunk cardinality** (`chunkKey → count`), read from the
      * already-parsed `.crbm` index with **no payload reads**, or `null` if the segment has no Storage generation.
@@ -52,8 +69,8 @@ export interface StorageChunkSource {
      * keys its chunk cache by this so a generation bump (a load's publish) is observed — a new generation
      * misses the cache instead of serving a stale decoded chunk, and an erased id can't resurrect from a cached
      * superseded chunk. Cheap: served from the source's own (short-TTL-refreshed) snapshot, **not** a fresh
-     * backend read per call. A source that pins one immutable generation for its whole lifetime and never
-     * refreshes may omit this — the engine then keys the cache without a generation.
+     * backend read per call. A source that only ever serves one immutable generation may omit this — the engine
+     * then keys the cache without a generation.
      */
     currentGeneration?(ref: SegmentRef): Promise<number | null>;
     /**
@@ -64,8 +81,8 @@ export interface StorageChunkSource {
      * `currentGen`**. Neither covers an event that *destroys* what the cache was derived from: an erasure that
      * deletes the generation holding the bit, a `dropSegment`, a crypto-shred, a retirement. After one of those
      * a source that had already resolved the segment keeps answering from memory — with no backend read at all,
-     * so no storage-side control can close the window — until its TTL lapses, and **never** if it has no clock
-     * or `cache.genTtlMs: 0` ("pin forever").
+     * so no storage-side control can close the window — until its TTL lapses, and with no bound at all if it has
+     * no registry, no clock or `cache.genTtlMs: 0`.
      *
      * Callers that destroy or retire a segment must call this. It is synchronous and best-effort: dropping
      * memoized state cannot fail, and a source that memoizes nothing may omit the method entirely.
@@ -88,7 +105,7 @@ export interface StorageChunkSource {
      * the generation *and* the incarnation of the name it belongs to.
      *
      * {@link StorageChunkSource.currentGeneration} is not enough to key a decoded-chunk cache, and the gap is not
-     * theoretical: `nextGeneration` returns `max(currentGen, highest object) + 1`, so it **restarts at 0** once
+     * theoretical: a load numbers its generation `max(currentGen, highest object) + 1`, so the number **restarts at 0** once
      * a registry row is purged and the bucket emptied. A retired, re-created name therefore serves different
      * data at the same `currentGen`, and a cache keyed on `(segment, chunk, generation)` hands back the previous
      * incarnation's ids — an erased id reappearing, with no read to intercept.
@@ -96,8 +113,8 @@ export interface StorageChunkSource {
      * Note that putting the incarnation in the *object key* would not fix this: the new incarnation still starts
      * at generation 0, so the cache key collides either way. The identity has to reach the cache.
      *
-     * Returns `null` when the segment resolves to no generation. A source that pins one immutable generation for
-     * its lifetime may omit this, and the engine falls back to the generation alone.
+     * Returns `null` when the segment resolves to no generation. A source that only ever serves one immutable
+     * generation may omit this, and the engine falls back to the generation alone.
      */
     currentVersion?(ref: SegmentRef): Promise<string | null>;
 }
@@ -114,35 +131,77 @@ export interface StorageCaps {
  * Immutable object storage for `.crbm` generations. A "dumb byte mover": it
  * understands neither roaring nor the `.crbm` layout, only opaque bytes addressed by a {@link GenKey}.
  * The core never reuses a key, so puts are write-once.
+ *
+ * **What a driver must do** — callers rely on each of these, and the storage conformance suite holds every
+ * shipped driver to them:
+ *
+ * - **`putImmutable` is write-once and reports a collision as {@link WriteConflictError}.** It never overwrites a
+ *   stored object. `load` reads that error as a lost race for the generation number (`superseded`), so a driver
+ *   that threw anything else for an existing key would surface as a failed load.
+ * - **A missing object makes `getRange` and `getTail` throw {@link NotFoundError}** — never an empty or short
+ *   result. Heal-forward (a read whose generation a sweep collected re-resolves), the erasure's holder probe and
+ *   its verify of the rewrite, and a pin's replaced-object check all branch on that one error. (A zero-length
+ *   `getRange` may answer empty without reaching the backend, so it proves neither that the object exists nor
+ *   that the offset lies inside it: the cloud drivers answer it empty, the memory and local-filesystem drivers
+ *   throw for a missing object or an offset past the end.)
+ * - **An out-of-range read throws {@link ValidationError}**: a range that runs past the end of the object, or a
+ *   negative or non-integer offset or length. Never a clamped, short or adjacent read. A pin whose object
+ *   was purged and loaded again as a smaller one asks for a range past its end, and this error is what sends it
+ *   to check that the object is still the one it pinned.
+ * - **`getTail` reports the object's true total size**, not the number of bytes it returned.
+ * - **`delete` is idempotent.** Deleting an absent key is a no-op, not an error: collection passes race each
+ *   other and retry.
+ * - **`list` is strongly consistent, read-after-delete.** Once `delete` has resolved, `list` no longer yields
+ *   that generation, and once `putImmutable` has resolved it does. The erasure's re-check for a generation still
+ *   holding the id, `dropSegment`'s `generationsRemaining`, the retention sweep's check that a tombstone's storage
+ *   is gone, and rollback's post-move check prove a deletion or a presence by listing, so a listing that lags
+ *   reports an erasure as incomplete or a stale object as gone.
+ * - **Never replay a conditional write without telling the replay apart.** A `putImmutable` that lands and then
+ *   loses its response, sent again, finds its own object and would report a collision. Either send each write
+ *   once, with the backend client's retry off for that request, or recognise your own write when the
+ *   precondition fails by reading an id you stored with it back, and treat a match as success. The first is
+ *   what the S3 driver and the single-request GCS upload do; the second is what the Azure Blob driver and the
+ *   resumable GCS upload do.
+ * - **Raise a transient fault as {@link TransientError}** (throttling, a 5xx, a dropped connection), so the read
+ *   retry can ride it out and a write's caller can tell it from a deterministic failure.
  */
 export interface IStorageDriver {
     capabilities(): StorageCaps;
     /**
      * Stream a new immutable generation. The driver opens a destination, hands `write` a {@link BlobSink},
-     * then atomically commits (and computes the content hash). Throws if the key already exists (write-once).
+     * then atomically commits (and computes the content hash). Throws {@link WriteConflictError} if the key
+     * already exists (write-once).
      */
     putImmutable(key: GenKey, write: (sink: BlobSink) => Promise<void>): Promise<{
         size: number;
         sha256: string;
     }>;
-    /** Range read; the caller bounds-checks. Out-of-range is rejected, never a short/adjacent read. */
+    /**
+     * Range read; the caller bounds-checks. Out-of-range throws {@link ValidationError}, never a short/adjacent
+     * read, and a missing object throws {@link NotFoundError}.
+     */
     getRange(key: GenKey, offset: number, length: number): Promise<Uint8Array>;
-    /** Speculative tail read: the last `min(maxBytes, size)` bytes + the total object size. */
+    /**
+     * Speculative tail read: the last `min(maxBytes, size)` bytes + the object's **true total size**. A missing
+     * object throws {@link NotFoundError}.
+     */
     getTail(key: GenKey, maxBytes: number): Promise<{
         bytes: Uint8Array;
         size: number;
     }>;
+    /** Idempotent: deleting an absent key is a no-op, not an error. */
     delete(key: GenKey): Promise<void>;
-    /** Enumerate the generations present for a segment (orphan sweep / latest-gen resolution). */
+    /**
+     * Enumerate the generations present for a segment (orphan sweep / latest-gen resolution). Strongly
+     * consistent, read-after-delete and read-after-put.
+     */
     list(ref: SegmentRef): AsyncIterable<GenKey>;
 }
 /**
  * Lifecycle status of a segment. `active` is the steady state; `destroyed` is the post-crypto-shred tombstone
- * (the row is kept for audit but the segment is logically gone). `compacting`/`erasing` are **reserved** —
- * stored and round-tripped so a row written by an earlier build still reads, but no writer in this build sets
- * them.
+ * (the row is kept for audit but the segment is logically gone).
  */
-export type RegistryStatus = 'active' | 'compacting' | 'erasing' | 'destroyed';
+export type RegistryStatus = 'active' | 'destroyed';
 /**
  * Free-form, JSON-serializable governance metadata — a **plain object** (both registry boundaries reject `null`,
  * an array or a primitive, because a reader that tests `'key' in meta` would throw an untyped `TypeError`).
@@ -218,29 +277,27 @@ export interface RegCaps {
  * Brand for {@link StorageBackend}.
  *
  * `Symbol.for` rather than a class check, for the same reason the error brands are: a class object is only
- * shared inside one package's bundle. `@cloudbitmaps/roaring` carries its own copy of core, so a backend
- * built from one package and checked by the other would fail an `instanceof` on an ordinary install — no
- * version skew required — as would a genuine second copy from a skew or a duplicating bundler. A registered
- * symbol is identity-stable across all of them, and across realms.
+ * shared while one copy of core is loaded, so a backend built from one copy and checked by another — after a
+ * version skew, or behind a duplicating bundler — would fail an `instanceof`. A registered symbol is
+ * identity-stable across all of them, and across realms.
  *
- * The string says `cloudbitmaps` while the error brands still say `cloud-roaring`: those are locked, because
- * changing one would break error identity against already-published bundles. A new brand has no such
- * constraint, so it uses the current name.
+ * A brand string is part of that identity contract, so once a release carries one it never changes: a changed
+ * string would stop matching the copies already installed.
  */
 declare const STORAGE_BACKEND_BRAND: unique symbol;
 /**
  * Where a store keeps everything: the generations, and the pointer saying which one is current.
  *
  * **Branded on purpose.** The two fields alone are not enough to qualify, and that is the whole point. This
- * shape is also {@link LoadDeps}/{@link GenerationDeps}, so before the brand any `{ storage, registry }`
+ * shape is also {@link LoadDeps}, so before the brand any `{ storage, registry }`
  * object literal satisfied it — including one assembling halves from two *unrelated* stores, which the store
  * accepted and then answered **empty** for a segment that holds data, because it read a pointer from a place
  * nothing had ever been written. That is the exact silent-empty failure one-class-per-backend exists to
  * remove, and it was reachable in five lines.
  *
  * So a backend comes from `MemoryStorage`, `LocalFsStorage`, `S3Storage`, `GcsStorage` or
- * `AzureBlobStorage` — each deriving both halves from one bucket and one prefix — or from
- * {@link createBackend}, which is the same thing said on purpose. The halves stay readable as `.storage` /
+ * `AzureBlobStorage` — each deriving both halves from one bucket and one prefix. A driver author composing halves
+ * of their own says so on purpose, with {@link brandAsBackend}. The halves stay readable as `.storage` /
  * `.registry`, because the free functions genuinely need them.
  *
  * **What this stops is the accident, not a determined caller.** The brand is a registered symbol, so it can
@@ -256,51 +313,43 @@ export interface StorageBackend {
     readonly registry: IRegistryDriver;
 }
 /**
- * Build a backend from two halves you supply yourself.
+ * The brand key, for the type-only `declare` field a backend class carries.
+ *
+ * Exported from `@cloudbitmaps/core/driver-kit` and part of the driver contract: a third-party storage
+ * package needs it to declare the field that {@link brandAsBackend} then stamps at runtime.
+ */
+export declare const STORAGE_BACKEND: typeof STORAGE_BACKEND_BRAND;
+/**
+ * Stamp the brand on a backend, **non-enumerably**, after checking both halves are drivers. Returns `target`.
  *
- * **Reach for a backend class first** — `MemoryStorage`, `LocalFsStorage`, `S3Storage`, `GcsStorage`,
- * `AzureBlobStorage`. Each derives both halves from one bucket and one prefix, so they cannot disagree, and
- * that is the whole reason the classes exist.
+ * This is the driver author's door, and it works on a backend class (`brandAsBackend(this)` as the last line of
+ * its constructor) and on a plain `{ storage, registry }` object alike — the latter is how a backend of your
+ * own halves is built: a driver wrapped for auditing, metrics, tenant scoping or client-side encryption, or
+ * paired with a registry in a database you already run. An application does not need it: it gets both halves
+ * from one backend class, which derives them from one bucket and one prefix so they cannot disagree.
  *
- * This is the door for the cases a class cannot express, and they are real: a driver wrapped for auditing,
- * metrics, tenant scoping or client-side encryption; a registry in a database you already run; a
- * fault-injecting double in a test. What it is NOT is a shortcut — naming it is the point. The plain
- * `{ storage, registry }` literal is refused precisely because it let the two halves come from unrelated
- * places by accident, and answer **empty** rather than fail.
+ * It throws {@link ValidationError} when `storage` has no `putImmutable` or `registry` has no `compareAndSwap`,
+ * so a half that is not a driver is refused here rather than at its first write, and when `target` is frozen or
+ * non-extensible, since the brand is stamped on it in place.
  *
  * It cannot check that the halves agree: `IStorageDriver` and `IRegistryDriver` do not expose a location, so
- * nothing here can compare one. Calling this is you taking that on.
- */
-export declare function createBackend(halves: {
-    readonly storage: IStorageDriver;
-    readonly registry: IRegistryDriver;
-}): StorageBackend;
-/**
- * Stamp the brand on a backend, **non-enumerably**.
+ * nothing here can compare one. Branding two unrelated halves is you taking that on — the plain
+ * `{ storage, registry }` literal is refused by the store precisely because it let the two halves come from
+ * unrelated places by accident, and answer **empty** rather than fail.
  *
  * Non-enumerable is load-bearing, not tidiness. A class field (`readonly [BRAND] = true`) emits an
  * *enumerable* own property, and spread and `Object.assign` copy exactly those — so
  * `{ ...backend, registry: other.registry }` carried the brand and was accepted, reproducing the silent-empty
- * bug this whole thing exists to close. That spelling is also the most idiomatic way a JS developer swaps one
- * half, which means the audience `createBackend` was added for walked straight past it.
- *
- * This does not make the brand unforgeable — the symbol is registered, so anyone who wants it can write
- * `Symbol.for('cloudbitmaps.storage-backend')`. That is deliberate effort equivalent to calling
- * `createBackend`, and it is not what the check is for. The check is for the accident.
- */
-/**
- * The brand key, for the type-only `declare` field a backend class carries.
- *
- * Exported from `@cloudbitmaps/core/driver-kit` and part of the driver contract: a third-party storage
- * package needs it to declare the field that {@link brandAsBackend} then stamps at runtime.
+ * bug the brand exists to close. This does not make the brand unforgeable — the symbol is registered, so anyone
+ * who wants it can write `Symbol.for('cloudbitmaps.storage-backend')`. That is deliberate effort equivalent to
+ * calling this function, and it is not what the check is for. The check is for the accident.
  */
-export declare const STORAGE_BACKEND: typeof STORAGE_BACKEND_BRAND;
 export declare function brandAsBackend<T extends {
     storage: IStorageDriver;
     registry: IRegistryDriver;
 }>(target: T): T & StorageBackend;
 /**
- * Is this a branded backend — from a backend class or from {@link createBackend}?
+ * Is this a branded backend — from a backend class or from {@link brandAsBackend}?
  *
  * Checks the brand, not the shape — see {@link StorageBackend} for why the shape alone is not enough.
  */
@@ -309,10 +358,34 @@ export declare function isStorageBackend(value: unknown): value is StorageBacken
  * Per-segment registry — the authoritative source of `currentGen`, the discovery index, and the wrapped-DEK
  * holder. One row per segment under OCC: a never-reused, equality-compared {@link Token} (ABA-safe across
  * delete→recreate).
+ *
+ * **What a driver must do** — callers rely on each of these, and the registry conformance suite holds every
+ * shipped driver to them:
+ *
+ * - **`create` and `compareAndSwap` are atomic conditional writes.** A `create` over a live row, and a
+ *   `compareAndSwap` whose token is not the stored one, throw {@link WriteConflictError} and change nothing.
+ *   Two racing writers have exactly one winner.
+ * - **Tokens are never reused**, not even across `delete` then `create`: a delete leaves a tombstone (or a
+ *   global counter) so a recreated row always carries a fresh token and a stale holder cannot swap into it.
+ * - **`delete` is idempotent** without an `expected` token: deleting an absent row is a no-op, not an error.
+ *   **With `expected` it is fenced**: it lands only while the row still carries that token, and otherwise throws
+ *   {@link WriteConflictError} and leaves the row.
+ * - **Reads are strongly consistent** (`RegCaps.strongRead`), and `list` yields every existing row,
+ *   `destroyed` tombstones included, with every field (see {@link IRegistryDriver.list}).
+ * - **Never replay a conditional write without telling the replay apart.** A `create` or `compareAndSwap`
+ *   that lands and then loses its response, sent again, finds its own write and would report a conflict.
+ *   Either send each write once, with the backend client's retry off for that request, or recognise your own
+ *   write when the precondition fails by reading an id you stored with it back. The shipped registries do
+ *   one or the other.
+ * - **Raise a transient fault as {@link TransientError}.**
  */
 export interface IRegistryDriver {
     capabilities(): RegCaps;
-    /** The segment's record, or `null` if it doesn't exist (or was deleted). */
+    /**
+     * The segment's record, or `null` if it doesn't exist (or was deleted). Throw {@link TransientError} for a fault
+     * worth riding out (throttling, a 5xx, a dropped connection): a reader whose pointer refresh meets one keeps
+     * serving what it holds and asks again shortly, while any other error reaches the read that met it.
+     */
     get(ref: SegmentRef): Promise<RegistryRecord | null>;
     /** Create the row; throws {@link WriteConflictError} if it already exists (use CAS to mutate). */
     create(ref: SegmentRef, record: NewRegistryRecord): Promise<{
@@ -334,7 +407,17 @@ export interface IRegistryDriver {
      * paying a `get()` per segment, so a `list()` that drops the field means nothing ever expires, silently.
      */
     list(namespace?: string): AsyncIterable<RegistryRecord>;
-    /** Remove the row (tombstoned for ABA-safety — a later `create` still gets a fresh, greater token). */
-    delete(ref: SegmentRef): Promise<void>;
+    /**
+     * Remove the row (tombstoned for ABA-safety — a later `create` still gets a fresh, greater token).
+     *
+     * Without `expected`, idempotent: deleting an absent row is a no-op.
+     *
+     * With `expected`, the delete is **fenced like a {@link IRegistryDriver.compareAndSwap}**: it lands only while
+     * the row still carries exactly that token, and otherwise — the token differs, or the row is absent or already
+     * deleted — throws {@link WriteConflictError} and leaves the row. Pass the token of the row you read when you
+     * decided to delete it, so a delete that is delayed, replayed, or racing a re-create cannot tombstone a row
+     * created after the decision. A third-party driver that ignores `expected` keeps the unfenced behaviour.
+     */
+    delete(ref: SegmentRef, expected?: Token): Promise<void>;
 }
 export {};

package/dist/core/reader-defaults.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The storage reader's defaults, stated once for the two modules that need them: the reader, which applies them,
+ * and the cost model, which prices what they cause. The cost model once imported them from the reader itself,
+ * which pulled the whole read path into a module that is otherwise arithmetic.
+ */
+/** Default TTL (ms) for re-resolving a segment's `currentGen` — the bound on post-publish read staleness. */
+export declare const DEFAULT_CURRENT_GEN_TTL_MS = 2000;
+/**
+ * How long (ms) a reader keeps serving after a pointer refresh failed transiently, before the next read asks the
+ * registry again. Short, so an outage ends the stale serving soon after the registry answers; fixed, so a registry
+ * that is down is asked at most once per this interval per segment being read (the refresh is coalesced per
+ * segment). Never longer than the TTL itself.
+ */
+export declare const REFRESH_RETRY_MS = 500;
+/** Default ceiling on cached segment readers (each holds a parsed `.crbm` index) — the steady-state count bound. */
+export declare const DEFAULT_MAX_OPEN_SEGMENTS = 1024;
+/** Default aggregate ceiling (bytes) on resident parsed indices in the reader cache — the steady-state byte bound. */
+export declare const DEFAULT_MAX_OPEN_INDEX_BYTES: number;

package/dist/core/registry-scan.d.ts

@@ -9,14 +9,24 @@ export declare function validateMaxScanSegments(value: number, op: string): void
 /**
  * Drain every registry record (optionally one namespace) into an array, refusing past `maxScanSegments`.
  *
- * The bound is checked **before** each push, so the array never exceeds the ceiling the caller agreed to — the
- * earlier form pushed first and then threw, which meant the very row that broke the budget was already resident,
- * and a caller sizing a container against `maxScanSegments` was off by one row at the worst possible moment.
+ * The bound is checked **before** each push, so the array never exceeds the ceiling the caller agreed to. Pushing
+ * first and then throwing would leave the very row that broke the budget resident, and a caller sizing a container
+ * against `maxScanSegments` off by one row at the worst possible moment.
  */
 export declare function drainRegistry(registry: IRegistryDriver, options: {
     namespace?: string;
     maxScanSegments: number;
     op: string;
+    /**
+     * How a caller of `op` raises the ceiling, completing "Narrow it with `namespace`, or …" in the refusal.
+     * Defaults to raising `maxScanSegments`, which is right wherever `op` takes that option itself.
+     */
+    raise?: string;
+    /**
+     * Whether the caller could scope the scan down to a `namespace`. Defaults to true; `eraseNamespace` is already
+     * one namespace, so it passes false and the refusal does not tell it to narrow what it cannot.
+     */
+    narrowable?: boolean;
 }): Promise<RegistryRecord[]>;
 /**
  * Is this record **bookkeeping** rather than a segment? Covers every reserved family — today the due-index
@@ -24,9 +34,8 @@ export declare function drainRegistry(registry: IRegistryDriver, options: {
  * the export/eject scan, and the all-namespaces GDPR paths.
  *
  * This is the ONE place a reserved family is declared, and a new one belongs here rather than at the call
- * sites. An earlier cut inlined the comparison per site and shipped with three missed — including
- * `subjectReport`, where the rows consumed an Art. 15 request's per-op budget. A filter you have to remember at
- * each site is a check that cannot fire.
+ * sites. A comparison inlined per site is easy to miss at one of them — at `subjectReport`, the rows would consume
+ * an Art. 15 request's per-op budget. A filter you have to remember at each site is a check that cannot fire.
  */
 export declare function isReservedRow(record: Pick<RegistryRecord, 'namespace'>): boolean;
 /**

package/dist/core/retention-sweep.d.ts

@@ -27,10 +27,12 @@
  * It also **purges the tombstones its own retirements leave behind**. A retired segment that had a registry row
  * gets a `destroyed` row, and one dead row per retired daily bucket — or per retired dedup wave — is exactly the
  * registry litter `dropSegment` already refuses to create for a row-less accumulator. Purging is narrow on
- * purpose: only a tombstone that still carries an **expired retention policy** (so it is attributably ours, never
- * a GDPR crypto-shred), only after a grace period, and only once Storage is provably empty for it —
+ * purpose: only a tombstone carrying the **stamp this sweep writes on its own retirements** (so it is attributably
+ * ours: a crypto-shred's tombstone does not carry it, unless the shred lands between this sweep's re-read of the
+ * row and its drop, which then reports the tombstone dropped and stamps it), only after a grace period, and only
+ * once Storage is provably empty for it —
  * because deleting the row is what makes the name reusable and takes the segment out of reach of
- * `gcOrphanGenerations`.
+ * the generation collection.
  */
 import { type IAuditSink } from './audit.js';
 import type { DropDeps, DropResult } from './erasure.js';
@@ -39,7 +41,7 @@ export declare const DEFAULT_RETIRE_LIMIT = 100;
 /**
  * Default delay before a retirement's own tombstone row is purged: 24 h.
  *
- * The row is a fence — while it exists, `publishGeneration` and `bulkLoadCrbmGeneration` refuse the segment, so
+ * The row is a fence — while it exists, a load refuses the segment, so
  * a load that was mid-write when the drop landed cannot resurrect it. That window is
  * seconds to minutes in practice; a day of margin costs one tiny row and removes any need to reason about it.
  */
@@ -69,10 +71,10 @@ export interface RetireExpiredOptions {
      *   expiring**. Each candidate's live row is still re-read before anything is decided, so a stale pointer
      *   costs one read and retires nothing.
      *
-     * **`'index'` is not a drop-in replacement for `'fleet'`; it is the fast half of a pair.** A policy written
-     * before the index existed, or one whose pointer write failed (`indexed: false`), has no pointer — so a
+     * **`'index'` is not a drop-in replacement for `'fleet'`; it is the fast half of a pair.** A policy whose
+     * pointer write failed (`indexed: false`), or whose ref is too long to index, has no pointer — so a
      * deployment that *only* ever runs `'index'` will never retire those. Run `'fleet'` periodically as the
-     * repair pass. The default stays `'fleet'` so that upgrading changes nothing about what gets retired.
+     * repair pass. The default is `'fleet'` because it is complete by construction.
      */
     readonly scan?: 'fleet' | 'index';
     /**
@@ -93,12 +95,18 @@ export interface RetireExpiredOptions {
     readonly lookbackBuckets?: number;
     /**
      * Whether to delete the tombstone rows this sweep's own past retirements left (default `true`). Set `false` to
-     * keep every tombstone forever — the right choice if something outside this library treats the presence of a
-     * `destroyed` row as an attestation.
+     * keep every one of them — the right choice if something outside this library treats the presence of a
+     * `destroyed` row as an attestation. That includes the row of a retirement whose drop found no Storage
+     * generation to delete and left none behind: with the default that row is deleted in the same pass, since it
+     * would do nothing but fence the name against every writer, and with `false` it stays, stamped like any other
+     * of this sweep's tombstones, so a later sweep with purging on deletes it once `tombstoneGraceMs` has passed.
+     * While it stays, it fences the name like every kept tombstone. What records a retirement either way is its
+     * ledger entry, and its `segment.dispose` event (`generationsDeleted: 0` for an empty one) when an `audit` sink
+     * is passed.
      *
      * Two knobs rather than one `number | 'never'`, deliberately: `0` would have had to mean "purge immediately"
-     * here while `cache.genTtlMs: 0` in this same library means "pin forever", and one option whose zero is the
-     * opposite of another's is a reading hazard for whoever tunes both.
+     * here while `cache.genTtlMs: 0` in this same library means "never refresh on a timer", and one option whose
+     * zero is the opposite of another's is a reading hazard for whoever tunes both.
      */
     readonly purgeTombstones?: boolean;
     /** How long a retirement's tombstone must age before this sweep deletes it (default 24 h). */
@@ -141,7 +149,7 @@ export type RetireEntry = {
      * expiring is the silence that costs a retention commitment.
      * `'limit'` — eligible, but this cycle's `limit` was already spent. Re-run to continue.
      * `'tombstone-not-empty'` — a tombstone whose Storage generations are not gone even after a GC
-     * attempt, so its row is kept: the row is what keeps the segment reachable by `gcOrphanGenerations` and
+     * attempt, so its row is kept: the row is what keeps the segment reachable by the generation collection and
      * refused by every writer. Several causes, all self-healing: the storage really could not be reclaimed,
      * the collection *declined* because the row changed underneath it (`WriteConflictError`, which this
      * sweep swallows deliberately), or this was a `dryRun`, which reports the reason without attempting the
@@ -161,7 +169,7 @@ export interface RetireExpiredResult {
     readonly eligible: number;
     /**
      * Segments **actually retired**. Zero under `dryRun` — see `wouldRetire`. Kept honest because this is the field
-     * most likely to end up on a dashboard, and the CLI emits it: a counter that means "deleted" in one mode and
+     * most likely to end up on a dashboard: a counter that means "deleted" in one mode and
      * "would delete" in another produces phantom deletions on any graph that does not also join on `dryRun`.
      */
     readonly retired: number;
@@ -175,6 +183,11 @@ export interface RetireExpiredResult {
     /** Per-segment ledger. Inspect it: a `skipped` or failed entry is a segment that still holds data. */
     readonly entries: readonly RetireEntry[];
 }
+/**
+ * How many past buckets an index scan reads besides the current one. A week: long enough that a weekend outage
+ * or a paused schedule recovers on its own, short enough that a cycle is eight list calls rather than hundreds.
+ */
+export declare const DEFAULT_LOOKBACK_BUCKETS = 7;
 /**
  * Retire every segment whose retention policy has expired, and clean up the tombstones earlier sweeps left.
  *
@@ -182,9 +195,4 @@ export interface RetireExpiredResult {
  * argument, and for a fleet larger than `maxScanSegments` — a scan that cannot be held in memory is a fail-loud
  * condition, not a partial result to be mistaken for a complete sweep.
  */
-/**
- * How many past buckets an index scan reads besides the current one. A week: long enough that a weekend outage
- * or a paused schedule recovers on its own, short enough that a cycle is eight list calls rather than hundreds.
- */
-export declare const DEFAULT_LOOKBACK_BUCKETS = 7;
 export declare function retireExpired(deps: DropDeps, options: RetireExpiredOptions): Promise<RetireExpiredResult>;

package/dist/core/retry.d.ts

@@ -11,7 +11,7 @@
  * It deliberately does **not** retry deterministic failures ({@link WriteConflictError},
  * {@link ValidationError}, {@link IntegrityError}, {@link NotFoundError}, …): retrying those either can't
  * help or would be incorrect. A pointer conflict is retried by a *separate* loop inside
- * `publishGeneration`, because each attempt must re-read the row and re-decide — a blind replay of the same
+ * the publish, because each attempt must re-read the row and re-decide — a blind replay of the same
  * compare-and-swap would either fail again on a stale token or, worse, advance a pointer whose state has
  * changed underneath it. A write-once object collision is never replayed at all: the generation number is
  * taken, so the caller has to pick a new one.
@@ -35,15 +35,19 @@ export interface RetryPolicy {
 /**
  * Conservative defaults: 4 attempts, 50ms → 100 → 200 (×2), capped at 2s, full jitter. Tuned for a cloud
  * backend's brief throttle/5xx blip — enough to ride out a transient fault without turning a hard outage
- * into a long hang. Override per store/driver if your latency budget differs.
+ * into a long hang. Override per store (`retry`) or per read source (`RetryingStorageChunkSource`) if your latency
+ * budget differs.
  */
 export declare const DEFAULT_RETRY_POLICY: RetryPolicy;
 export interface RetryDeps {
     readonly clock: Clock;
     readonly rng: Rng;
-    /** Override which errors are retryable. Default: any {@link TransientError} (incl. `TimeoutError`). */
+    /** Override which errors are retryable. Default: any {@link TransientError}. */
     readonly isRetryable?: (err: unknown) => boolean;
-    /** Optional hook (observability) fired before each backoff wait. `attempt` is 1-based (the one that failed). */
+    /**
+     * Optional hook (observability) fired before each backoff wait. `attempt` is 1-based (the one that failed).
+     * Best-effort: an error it throws is swallowed, so it can neither stop the retry nor change the error thrown.
+     */
     readonly onRetry?: (info: {
         attempt: number;
         delayMs: number;