@cloudbitmaps/core 0.19.1 → 0.21.0

package/dist/core/invalidation-scope.d.ts

@@ -0,0 +1,77 @@
+/**
+ * What the engines reading through one chunk cache share about invalidations: how many there have been, the segment
+ * each of the latest was of, and the chunk reads open right now. A store's own engine, each pin's and each combine's
+ * with a pinned operand read through one cache, and an invalidation through any of them must reach a read running on
+ * another: a read that had its bytes before the invalidation would otherwise write them back into the cache it
+ * shares, and later reads would be answered from them, an erased id included, until the cache evicted them.
+ *
+ * ```
+ *  engine (store) ──┐
+ *  engine (pin)   ──┼── one InvalidationScope ── epoch · latest invalidation of each segment · open reads
+ *  engine (combine)─┘        └── one chunk cache
+ * ```
+ *
+ * A stream records the epoch it opened at and asks {@link InvalidationRecord.invalidatedSince} before it caches a
+ * chunk, so the scope holds no reference to a stream: a read its caller drops without closing holds nothing here. The
+ * `.crbm` source keeps an {@link InvalidationRecord} of its own, by segment, which a pinned stream asks before it hands
+ * out a chunk, so only its own segment's invalidation makes it open its object again.
+ *
+ * Internal to core: not exported from any entry point.
+ */
+import type { CodecBitmap } from './codec.js';
+/**
+ * How many segments' latest invalidation a record remembers. Past it the oldest is forgotten, and a segment the record
+ * does not remember, never-invalidated ones included, counts as invalidated at the newest invalidation it has
+ * forgotten, which is always on the safe side. In the engines' scope it means a stream that opened before then caches
+ * no more of that segment's chunks, which costs it cache entries, never correctness: so a sweep that invalidates more
+ * than this many segments at once (a `retireExpired` or an `eraseSubject` over a large fleet) stops every stream open
+ * at the time caching, whatever segment it reads. In the `.crbm` source it means a pinned stream looks its pin up
+ * again, which costs a request only where the reader cache has let the pin's reader go. With names at their
+ * 256-character limit a record is about 0.6 MB, and about 0.1 MB with 30-character names; a store keeps two.
+ */
+export declare const REMEMBERED_INVALIDATIONS = 1024;
+/** A chunk read in flight: `token` tells the read whether its entry is still the registered one. */
+export interface OpenRead {
+    readonly token: object;
+    readonly read: Promise<CodecBitmap | null>;
+}
+/**
+ * How many invalidations there have been, and the epoch of each of the latest {@link REMEMBERED_INVALIDATIONS}
+ * segments' latest one, by whatever key names a segment to its owner: a cache-key prefix in the engines' scope, a
+ * segment key in the `.crbm` source.
+ */
+export declare class InvalidationRecord {
+    private count;
+    /** The epoch of each remembered segment's latest invalidation, the oldest first. */
+    private readonly latest;
+    /** The epoch of the newest invalidation the record has forgotten: what a segment it does not remember counts as. */
+    private floor;
+    /** How many invalidations there have been: a read compares it with the epoch it began under. */
+    get epoch(): number;
+    /** Record an invalidation of the segment `key` names. */
+    invalidate(key: string): void;
+    /** Whether the segment `key` names has been invalidated since epoch `since`. */
+    invalidatedSince(key: string, since: number): boolean;
+}
+/** The engines' record, by cache-key prefix, and the chunk reads open on all of them. */
+export declare class InvalidationScope extends InvalidationRecord {
+    /**
+     * The chunk reads open right now, by cache key: a caller that misses the cache and finds its key here awaits that
+     * read instead of making its own. An entry lives from the request until it settles, so the map holds at most one
+     * promise per distinct key in flight. An invalidation drops the segment's entries, and a read whose entry is gone
+     * caches nothing.
+     */
+    private readonly openReads;
+    /** Record an invalidation of the segment whose cache keys start with `prefix`, and drop its open reads. */
+    invalidate(prefix: string): void;
+    /** The read of `key` open now, for a caller that misses the cache to await instead of making its own. */
+    openRead(key: string): Promise<CodecBitmap | null> | undefined;
+    /** Whether a read of `key` is open, without joining it. */
+    hasOpenRead(key: string): boolean;
+    /** Register `entry` as the open read of `key`. */
+    beginRead(key: string, entry: OpenRead): void;
+    /** `entry` has settled: forget it, unless an invalidation dropped it and a newer read has taken the key. */
+    endRead(key: string, entry: OpenRead): void;
+    /** Whether the read `token` names is still the open read of `key`: one an invalidation dropped caches nothing. */
+    isOpen(key: string, token: object): boolean;
+}

package/dist/core/known-generations-shape.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The shape of a row's known-generations ledger (`knownGens`), in one place. A registry holds a row to it when it writes
+ * and when it reads back, and `checkConsistency` holds a row to it before it reads or walks a ledger a registry of your
+ * own handed back, so the two cannot part on what a ledger is. Pure: no I/O, time or randomness.
+ */
+/**
+ * Why `value` is not a ledger, or `undefined` when it is one (an absent ledger, `undefined`, passes: whether a row
+ * without one is usable is another rule). A ledger is an array of at most `max` entries, each exactly `{ generation,
+ * footerCrc }`, the generation a non-negative safe integer and unique, the checksum an integer from 0 to 2^32 - 1. The
+ * order is not checked: it is not derivable from the numbers. `show` renders a value for the description, which a
+ * caller can truncate.
+ */
+export declare function knownGensShapeFault(value: unknown, max: number, show?: (v: unknown) => string): string | undefined;

package/dist/core/known-generations.d.ts

@@ -0,0 +1,147 @@
+import type { KnownGeneration, RegistryRecord } from './ports.js';
+/**
+ * The most generations a load that collects by name records as its window. A `keep` above it collects by listing.
+ */
+export declare const MAX_KEPT_GENERATIONS = 64;
+/**
+ * A writer keeps entries that nothing protects and no lease holds only while the ledger holds fewer than this many.
+ */
+export declare const KNOWN_FILL = 128;
+/** The most entries a writer writes, and the most the shared validator accepts at a write. */
+export declare const MAX_KNOWN_GENERATIONS = 192;
+/** The most entries a stored row may hold: twice what a writer writes. */
+export declare const MAX_STORED_KNOWN_GENERATIONS = 384;
+/**
+ * The row's ledger when a collection or a rollback may rely on it: present and not empty, on an active row with a
+ * pointer, its last entry the pointer, and, where the row's summary is in the clear and describes that generation, its
+ * checksum the one the summary's fingerprint carries. A well-formed ledger that disagrees with its row is read but not
+ * used (the row counts as one with no ledger), as a summary that names another generation is.
+ */
+export declare function usableKnownGens(record: RegistryRecord | null): readonly KnownGeneration[] | undefined;
+/**
+ * The generations the row keeps as its window: the numbers of the usable ledger's entries below the pointer, in the order
+ * they were made current, or `undefined` when the ledger is not usable. A collection compares against these. An entry
+ * numbered above the pointer is one a rollback left; no collection can take it, so it is no part of the window.
+ */
+export declare function windowOf(record: RegistryRecord | null): readonly number[] | undefined;
+/**
+ * Whether the row's ledger is a window a load with a small `keep` can extend: usable, and naming no more than
+ * {@link MAX_KEPT_GENERATIONS} generations below the pointer that no live lease holds. A ledger carried through
+ * publishes with a larger `keep` (`*Into`, `materializeMany`) names up to 127, and a count by a small `keep` would keep
+ * fewer than it names, so the next small-`keep` load collects by listing instead of by name, over the same ledger. A
+ * generation held only for a lease is no part of the window and does not count toward the limit.
+ */
+export declare function carriesWindow(record: RegistryRecord | null, leased: ReadonlySet<number>): boolean;
+/**
+ * How many generations below its own a publish vouches for at most: what the writer cap leaves beside the new
+ * generation and the 64 generations live leases can hold.
+ */
+export declare const KNOWN_SPAN = 127;
+/** Which generations below a new pointer a grace window holds, and which it lets go: both ascending. */
+interface KeptWindow {
+    readonly kept: number[];
+    readonly evict: number[];
+}
+/**
+ * The generations below a new pointer that a grace window of `keep` holds, out of `below`, when no ledger says which
+ * were made current most recently: the generation the publish superseded first, when it is among them, then the newest
+ * of the rest by number. When it is not among them (no generation was current, or its object has gone from the bucket),
+ * the newest `keep`.
+ *
+ * The superseded generation is the one reads were on until the publish, and, after a rollback, the one the operator
+ * restored, which a pin taken since reads, and the one to roll back to if the new load is bad too. The generations a
+ * rollback moved away from are newer by number, so a window by number alone would keep those and delete it. The window
+ * a listing keeps over a row with no usable ledger comes from here, and so does a ledger's first window
+ * (`ledger-seed.ts`); once the row has a ledger, its order says which were made current most recently.
+ */
+export declare function keptWindow(below: readonly number[], superseded: number | undefined, keep: number): KeptWindow;
+/**
+ * `known`, held to the cap, in the same order. It always keeps the entries numbered in `protect`, then the ones numbered
+ * in `leased`, most recently current first, up to {@link MAX_KNOWN_GENERATIONS}, then the rest, most recently current
+ * first, while the ledger holds fewer than {@link KNOWN_FILL}. So a protected or leased entry is never dropped for room,
+ * and an unprotected one only when the ledger is full. "Most recently current" is the end of the list.
+ */
+export declare function capKnown(known: readonly KnownGeneration[], protect: ReadonlySet<number>, leased?: ReadonlySet<number>): KnownGeneration[];
+/** `known` with `entry` made the most recent: any entry for its generation removed, and the entry added last. */
+export declare function makeCurrent(known: readonly KnownGeneration[], entry: KnownGeneration): KnownGeneration[];
+/** What a publish of a generation writes into the row, and which names it pushes out of the window. */
+export interface KnownAfter {
+    /** The ledger to write: the generation published is its last entry. */
+    readonly known: readonly KnownGeneration[];
+    /** The window as numbers to collect by name, or `undefined` to collect by listing. */
+    readonly list: readonly number[] | undefined;
+    /** The generations the window no longer keeps, ascending: the names to delete. */
+    readonly evict: readonly number[];
+}
+/**
+ * What a publish of `generation` (its object's footer checksum `footerCrc`) over `prev` writes into the row.
+ *
+ * The ledger is in the order the generations were made current, so the order says which were current most recently.
+ * That ranks the window, and the window is drawn from the entries numbered below the new generation only: collection
+ * can only take generations numbered below the pointer. The window is the `keep` most recently current of them (at most
+ * {@link KNOWN_SPAN}), so the generation the publish superseded, the ledger's last entry, comes first, and after a
+ * rollback the ones the operator restored outrank the ones the rollback moved away from.
+ *
+ * What it writes, in the order the entries were made current and the new generation last:
+ *
+ *  - the window;
+ *  - the entries below the new generation that `leased` names (a generation a live lease holds stays known, so it stays a
+ *    rollback target while the lease lives), whatever `keep` says;
+ *  - the entries numbered above the new generation, which a rollback left and a load numbered under: they are carried and
+ *    never evicted, and take no slot of `keep`, while the ledger holds fewer than {@link KNOWN_FILL} entries (see
+ *    {@link capKnown});
+ *  - the new generation. An entry already numbered `generation` is a stale one (its object went outside the ledger) and
+ *    is replaced.
+ *
+ * `evict` is the entries below the new generation that it leaves out, ascending: never a name at or above the new
+ * generation. With a `keep` of at most {@link MAX_KEPT_GENERATIONS} the publish collects by name, so `list` is the
+ * generations of the ledger below the new one; above that, or with no `keep`, `list` is `undefined` and `evict` empty, and
+ * a load lists. A row with a pointer and no usable ledger writes the new generation alone and lists, unless the caller
+ * passes a `seed` (see `ledger-seed.ts`): the window a count keeps, read from the bucket, then the new generation, and
+ * the publish collects by that count. A publish that clears leases is an erasure's rewrite, which deletes every older
+ * generation, so its ledger is the new generation alone.
+ */
+export declare function nextKnown(prev: RegistryRecord | null, generation: number, footerCrc: number, keep: number | undefined, options?: {
+    readonly clearsLeases?: boolean;
+    readonly seed?: readonly KnownGeneration[];
+    readonly leased?: ReadonlySet<number>;
+}): KnownAfter;
+/**
+ * The ledger a rollback onto `target` writes over `prev`: the ledger it found with the target moved to the end, as the
+ * most recently current. A rollback never starts a ledger: over a row with no usable ledger it writes none, and the
+ * next publish seeds one. A target the ledger did not name
+ * is an insert, and the ledger it makes is held to the cap with the target and the generation the rollback leaves
+ * protected; a known target's ledger is written as read, unless another build wrote one that is past the writer's cap.
+ */
+export declare function rollbackKnown(prev: RegistryRecord, target: KnownGeneration): readonly KnownGeneration[] | undefined;
+/**
+ * The row's ledger with the entries numbered in `doomed` removed, which a write that is about to delete those
+ * generations makes first: the entries left keep their order, and the current generation is never removed (the ledger
+ * must end with it). Another build's ledger past the writer's cap is held to it, with the current generation protected
+ * and the generations the row's leases name kept. `undefined` for a row with no usable ledger, which names nothing to
+ * remove.
+ */
+export declare function pruneKnown(record: RegistryRecord, doomed: ReadonlySet<number>): readonly KnownGeneration[] | undefined;
+/**
+ * The ledger that puts a row back as it was, for the undo of a rollback: the row's own when it is usable (the
+ * generation it left is its last entry), held to the writer's cap when another build wrote one past it, with the
+ * generation the undo leaves and the one it moves from protected; `undefined` for a row that had none to put back.
+ */
+export declare function describingKnown(record: RegistryRecord, movedTo: number): readonly KnownGeneration[] | undefined;
+/**
+ * Whether the ledger is full: it names at least {@link KNOWN_FILL} generations, which is when a writer may have let an
+ * older one go (a publish vouches for at most {@link KNOWN_SPAN} below its own, and an inserting rollback drops an entry
+ * once 128 that no lease holds are named). Leased entries do not switch it off: a lease on an entry inside the span
+ * leaves the ledger as full as it was. Past the least recently current entry of a full ledger, a rollback can no longer
+ * tell a generation the row forgot from one it never knew, so it judges a target numbered below that entry as it did
+ * before the ledger existed.
+ */
+export declare function isFullLedger(known: readonly KnownGeneration[]): boolean;
+/**
+ * The number a target below the pointer is judged against on a full ledger: the least recently current entry that no
+ * lease entry of the row names (live or ended: a rollback has no clock). A leased entry stays in the ledger for its lease,
+ * however far the window has moved on since, so it does not mark where the ledger stopped remembering; the first entry no
+ * lease holds does. A ledger whose every entry is leased is judged against its first entry.
+ */
+export declare function fallbackBound(record: RegistryRecord, known: readonly KnownGeneration[]): number;
+export {};

package/dist/core/leases.d.ts

@@ -17,6 +17,13 @@ export declare const MAX_STORED_LEASES = 256;
  * plus a few, so that the most a segment can hold, all arriving at once, can all land.
  */
 export declare const LEASE_CAS_ATTEMPTS: number;
+/**
+ * Fresh writes sent after one that got no answer and left the row as it was, by the lease writers, by an erasure's
+ * renewal of the row and by a publish: four sends of the row write in all.
+ */
+export declare const UNANSWERED_RESENDS = 3;
+/** The upper bound of the first of those waits, in ms; each next one doubles it. */
+export declare const UNANSWERED_BASE_MS = 500;
 /**
  * Whether an entry holds its generation against a collector reading `now`: it has not ended (`until` plus the margin
  * is ahead), and it does not run further past `now` than any honest holder with a clock inside the margin could have
@@ -58,7 +65,7 @@ export declare const LEASE_ONLY_RETRIES: number;
  */
 export declare function onlyLeasesDiffer(held: RegistryRecord, now: RegistryRecord, alsoIgnore?: readonly (keyof RegistryRecord)[]): boolean;
 /** A writer's count of the lease-only changes it has waited out, and the wait. One per call of the writer. */
-export interface LeaseChurn {
+interface LeaseChurn {
     /**
      * When `now` is `held` changed only in its leases and the bound is not spent: wait, then read the row again with
      * `reread`, and return what it found. The wait comes before the read, so the writer's next write is made against a row
@@ -117,3 +124,4 @@ export declare function takeLease(ref: SegmentRef, deps: LeaseDeps, take: LeaseT
  * races and the registry's `TransientError` for a write that stayed unanswered over an unchanged row.
  */
 export declare function releaseLease(ref: SegmentRef, deps: LeaseDeps, holder: string): Promise<void>;
+export {};

package/dist/core/ledger-seed.d.ts

@@ -0,0 +1,17 @@
+import { type ReadRetry } from './retry.js';
+import type { IStorageDriver, KnownGeneration, RegistryRecord, SegmentRef } from './ports.js';
+/**
+ * Whether a publish over `row` seeds its ledger: only at a birth, over an active row that has a pointer and no usable
+ * ledger. A usable ledger is never seeded again, however wide it is.
+ */
+export declare function wantsSeed(row: RegistryRecord | null): boolean;
+/**
+ * The entries a seed names: the listed generations below the new one that a live lease holds and the window does not
+ * keep, then the window oldest first by number with the generation the row named as current last. `listed` is the
+ * listing the load's numbering made, when it made one; otherwise the bucket is listed once. Every entry's checksum is
+ * read from its object's footer (a 104-byte read, under the store's read retry, {@link SEED_READS} at a time), the
+ * superseded generation's too: when a clear summary describes it with another checksum, the row and the bucket
+ * disagree about that number and it is left out. A generation gone from the bucket, or whose footer fails its own
+ * checks, is left out; any other failed read throws, before anything is published.
+ */
+export declare function readSeed(storage: IStorageDriver, ref: SegmentRef, row: RegistryRecord | null, generation: number, keep: number, listed: readonly number[] | undefined, leased: ReadonlySet<number>, readRetry?: ReadRetry): Promise<KnownGeneration[]>;

package/dist/core/load.d.ts

@@ -1,24 +1,3 @@
-/**
- * `loadSegment` — the loaded store's primary write path, as one call.
- *
- * A load is always the same four steps: take the next generation number, write one immutable object, move the
- * pointer, collect what the move superseded. Inside the library each is its own internal function, and the
- * step a hand-composed load leaves out is the last one, so a store that composed it would accumulate superseded
- * generations it keeps paying for.
- * Composing it here, once, is the point.
- *
- * The other reason it is one call is the **guard**. A load REPLACES a segment: whatever the stream contains is
- * what the segment contains afterwards. That makes an upstream query returning fewer rows than usual — or none —
- * a silent, successful-looking wipe, and nothing downstream can tell it from a legitimate shrink. The guard is
- * the place to say what a plausible result looks like, and it has to sit **between the write and the publish**,
- * because that is the only moment where the new content is known and the old one is still authoritative.
- *
- * Refusing therefore has to clean up after itself. The object is already durable at that point, and it sits
- * ABOVE `currentGen`, where generation collection deliberately never looks (it deletes strictly below the
- * pointer), so a refused load deletes its own object before returning, while the segment's row is unchanged, gone
- * or `destroyed`. Once another write has changed the row, the object's number may name a re-created segment's live
- * object, so it stays, and collection takes it like any other generation once one above it is current.
- */
 import { type IAuditSink } from './audit.js';
 import { type CodecBitmap, type CodecInterface } from './codec.js';
 import type { Clock, Rng } from './determinism.js';
@@ -114,11 +93,15 @@ export interface LoadOptions {
      * longest pinned job runs, on every writer that loads the segment — see "Generations and `keep`" in the loading
      * guide.
      *
-     * The segment's row records the generations a load keeps, up to 64, so a load that found nothing above the pointer
-     * collects without listing: it deletes the generations its publish pushed out of the window, and lists the segment's
-     * objects on every sixteenth generation to take whatever that pass leaves, such as an object a crashed load left
-     * below the pointer. A `keep` above 64 records no list and lists on every load, and so does the first load of a
-     * row that records none, which then records it; so does a load whose check found the current generation's object
+     * The window is the `keep` most recently current generations below the one the load publishes, so the generation the
+     * load superseded comes first. After a rollback that is the one the rollback restored, and it stays in the window of
+     * every load after it, ahead of the generations the rollback moved away from, for as many loads as `keep` says.
+     *
+     * The segment's row records the generations a load keeps, up to 64, so a load whose number one existence check found
+     * free collects without listing: it deletes the generations its publish pushed out of the window, and lists the
+     * segment's objects on every sixteenth generation to take whatever that pass leaves, such as an object a crashed load
+     * left below the pointer. A `keep` above 64 collects by listing on every load, and so does the first load of a row with
+     * no usable ledger, which starts one from the bucket; so does a load whose check found the current generation's object
      * gone: the guard's read of it, or, when the guard took the size from the row's summary, one zero-byte read made
      * before a `keep` of 1 or more takes a name. A `keep` at least the generation published collects nothing and asks
      * for nothing.
@@ -140,11 +123,6 @@ export interface LoadOptions {
 }
 /** The bounds a guard can refuse a generation for: every {@link LoadRefusal} but a lost race. */
 export type GuardRefusal = Exclude<LoadRefusal, 'superseded'>;
-/**
- * The bound a generation of `cardinality` ids breaks over a current one of `before` (`null`: none, or not read), in the
- * order a load checks them, or `undefined`. Pure: the one judgement a load and a dry run share.
- */
-export declare function guardRefusal(cardinality: number, before: number | null, guard: LoadGuard | undefined, allowEmpty: boolean | undefined): GuardRefusal | undefined;
 /** What a dry run learns about one write: the size it would replace, and the bound that would refuse it. */
 export interface LoadJudgement {
     /**
@@ -171,16 +149,19 @@ export type LoadRefusal = 'empty' | 'min-cardinality' | 'min-retained' | 'max-gr
  * put refused this one and it wrote nothing (`size: 0`); or the segment's registry row changed while the load was
  * writing: another load published, a retention change, a rollback or an erasure wrote the row, the row was
  * deleted, or a row appeared where the load found none. Once another write has changed the row, the object stays in
- * the bucket, still billed, until a later load's collection deletes it (at the latest the listing a load runs
- * every sixteenth generation) or the segment is dropped, because its generation number may by then name another
- * incarnation's live object; once the row is `destroyed` (dropped or crypto-shredded), the object is deleted, and
- * once the row is gone, so is an object its footer proves this load's own.
+ * the bucket, still billed, until a later load's collection deletes it or the segment is dropped, because its
+ * generation number may by then name another writer's object; until it goes, a rollback onto it needs `allowUnknown`, as onto any generation the row does not know. Once the row is
+ * `destroyed` (dropped or crypto-shredded), the object is deleted; once the row is gone, so is an object whose footer
+ * matches what this load wrote (a re-created segment's load of the same cleartext ids writes a match), and so is a
+ * cleartext one under a row with key material.
  */
  | 'superseded';
 export interface LoadResult {
     /**
      * The generation written. Present even when refused: a refusal deletes that object while the segment's row is
-     * unchanged or `destroyed`, or gone once its footer proves it this load's own, and leaves it in the bucket once another write has changed the row. A load that lost its
+     * unchanged or `destroyed`, and, once one read of its footer matches what the load wrote, when the row is gone or,
+     * for a cleartext object, has key material. Under any other row another write changed, the object stays in the
+     * bucket, an orphan a later load's collection takes, and until then a rollback onto it needs `allowUnknown`. A load that lost its
      * generation number to another wrote nothing, and reports `size: 0`.
      */
     readonly generation: number;

package/dist/core/lru.d.ts

@@ -1,19 +1,5 @@
-/**
- * Bounded LRU cache with optional TTL — the cache tier's memory ceiling.
- *
- * Time comes from an injected `Clock` (never `Date.now()`) so the cache is deterministic
- * under simulation.
- *
- * The cache can be bounded by entry **count** (`maxEntries`, always) and, optionally, by an aggregate
- * **byte weight** (`maxBytes`). The byte bound exists for values whose footprint is large and uneven — the
- * storage reader cache, where one entry pins a fully-parsed `.crbm` index that can be ~6 MB for a wide segment
- * yet a few hundred bytes for a small one (a count-only bound lets 1024 wide indices blow a Lambda's
- * memory even though the count is "in bounds"). Weights arrive **after** insertion (a cached reader is a
- * pending promise; its size is known only once it resolves), so weight is reported via {@link setWeight} and
- * eviction re-runs then.
- */
 import type { Clock } from './determinism.js';
-export interface LruOptions {
+interface LruOptions {
     /** Hard ceiling on entries; the least-recently-used is evicted past it. */
     readonly maxEntries: number;
     /**
@@ -67,3 +53,4 @@ export declare class BoundedLru<K, V> {
     /** Current aggregate reported weight (bytes) across all entries. */
     get weightBytes(): number;
 }
+export {};

package/dist/core/metrics.d.ts

@@ -5,8 +5,8 @@
  * Design: the library emits **neutral domain events** and stays vendor-agnostic — you (or a ~12-line
  * adapter) map them to OpenTelemetry / Datadog / a log line. The default is a **no-op**, and emission is
  * skipped entirely when no sink is wired (near-zero overhead, no telemetry dependency). Events carry **raw
- * observations** (bytes, counts, ms); turning those into billable units / dollars is the cost model's job,
- * which keeps rates pluggable.
+ * observations** (bytes, counts, ms); turning those into billable units / dollars is left to whoever reads them,
+ * which keeps rates out of the library (`@cloudbitmaps/tools` prices a workload you give it).
  *
  * Two caveats for sink authors: `onEvent` runs **synchronously on the I/O path**, so keep it cheap and
  * non-blocking (offload batching/network to your own async queue); and `segment`/`namespace` are
@@ -49,8 +49,10 @@ export type MetricEvent = {
     readonly ms: number;
 } | {
     /**
-     * One decoded-chunk cache lookup (emitted only when a cache is configured). `hit: false` means the lookup found
-     * no cached chunk. A combine or `iterate` looks up every chunk it needs when it opens its streams. A caller that
+     * One decoded-chunk cache lookup, or one chunk counted a miss without a lookup (emitted only when a cache is
+     * configured). `hit: false` means the cache did not hold the chunk. A combine or `iterate` counts every chunk it
+     * needs when it opens its streams: a lookup each, except that on a cache that holds nothing each chunk after the
+     * one a stream starts at is counted a miss without one. A caller that
      * missed while another caller's read of the same chunk was open waits on that read and adds no `storage.get`, and a
      * range carries several chunks, so the misses can outnumber the `storage.get` events; the `storage.get` count is
      * the number of requests for chunks. `materializeMany` never looks up the cache, so it emits none.
@@ -168,9 +170,9 @@ export interface MetricsSnapshot {
     }>>;
 }
 /**
- * A ready-made sink that tallies events into a {@link MetricsSnapshot} — handy for tests, quick scripts,
- * and as the grounded-request-cost source behind `costReport()`. `snapshot()` returns an independent copy;
- * `reset()` zeroes the counters.
+ * A ready-made sink that tallies events into a {@link MetricsSnapshot} — handy for tests, quick scripts, and for
+ * reading the request rates a cost model is given. `snapshot()` returns an independent copy; `reset()` zeroes the
+ * counters.
  */
 export declare class CountingMetricsSink implements IMetricsSink {
     private storage;

package/dist/core/order.d.ts

@@ -0,0 +1,2 @@
+/** The comparator that sorts numbers smallest first, which `Array.prototype.sort` does not do by default. */
+export declare const ascending: (a: number, b: number) => number;

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

@@ -27,14 +27,14 @@ import type { CrbmStorageChunkSource } from './crbm-storage-source.js';
  * 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.
+ * `fingerprint` is required for a pin of a generation (`null` only when `generation` is `null`): without it a read
+ * could not tell a name purged and loaded again from the segment it pinned. `seg.pin()` always records it, and a
+ * pin of a generation without a string `version` and `fingerprint` is refused with a `ValidationError`.
  */
 export interface PinnedAt {
     readonly generation: number | null;
     readonly version: string | null;
-    readonly fingerprint?: string | null;
+    readonly fingerprint: string | null;
 }
 export declare class PinnedStorageChunkSource implements StorageChunkSource {
     private readonly inner;
@@ -53,8 +53,6 @@ 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.
      *
@@ -74,12 +72,14 @@ export declare class PinnedStorageChunkSource implements StorageChunkSource {
     sizeOf(ref: SegmentRef): Promise<SegmentSize | null>;
     cardinalities(ref: SegmentRef): Promise<ReadonlyMap<number, number> | null>;
     summary(ref: SegmentRef): Promise<GenerationSummary | null>;
+    stat(ref: SegmentRef): Promise<(GenerationSummary & SegmentSize) | null>;
     currentGeneration(ref: SegmentRef): Promise<number | null>;
     /**
      * 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
+     * and a lapsed `cache.genTtlMs`, a reader-cache eviction on a store with no timed refresh, the resolution
+     * cache letting the segment's resolution go on a store with one, 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

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

@@ -0,0 +1,19 @@
+import type { RegistryPatch, RegistryRecord, Token } from './ports.js';
+/** The fields a read resolves through: a patch that names any of them renews the row's `pointerId`. */
+export declare const RESOLVED_FIELDS: readonly ["currentGen", "status", "wrappedDeks", "keyId", "summary"];
+/**
+ * Whether a compare-and-swap of `patch` renews the row's `pointerId`: whether it names a resolved field, by presence
+ * (`'field' in patch`), whatever the value, as every patch rule reads a patch.
+ */
+export declare function renewsPointer(patch: RegistryPatch): boolean;
+/**
+ * The patch that renews a row's `pointerId` and changes nothing a read resolves: the pointer, named at the value it
+ * has. A same-value pointer keeps the summary and the kept window, which follow the pointer only when it changes value.
+ */
+export declare function renewPointer(row: Pick<RegistryRecord, 'currentGen'>): RegistryPatch;
+/**
+ * The row's `pointerId`, refusing a row that has none with {@link UnsupportedError}: a registry written against an
+ * earlier port contract returns rows without it, and a reader that cannot tell which write set the row's resolution
+ * cannot key a cache on it. A TypeScript registry fails to compile instead; this catches one in JavaScript.
+ */
+export declare function pointerIdOf(row: RegistryRecord): Token;