@cloudbitmaps/core 0.19.0 → 0.20.0

package/dist/core/engine.d.ts

@@ -3,7 +3,7 @@ import type { Budget, BudgetOption } from './budget.js';
 import type { Clock } from './determinism.js';
 import type { BoundedLru } from './lru.js';
 import type { IMetricsSink } from './metrics.js';
-import type { GenerationMetadata, StorageChunkSource, SegmentRef, SegmentSize } from './ports.js';
+import type { GenerationMetadata, StorageChunkSource, SegmentRef } from './ports.js';
 /**
  * Range requests a stream holds ahead of a combine or `iterate` by default (chunk keys, on a source that reads chunk by
  * chunk, and for `count`'s fallback) — bounds memory and concurrent reads (invariant 6). A read that does not fit
@@ -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>;
@@ -123,20 +128,21 @@ export declare class SegmentEngine {
      */
     count(seg: SegmentRef): Promise<number>;
     /**
-     * What the segment's current generation is: its number, its id count and its metadata, from one resolution, so the
-     * three cannot straddle a publish. A source with no summary answers from `count()` and the generation it resolves.
+     * What the segment's current generation is: its number, its id count, its metadata and the size of its object in
+     * bytes. A source with a `stat` (the `.crbm` source) answers all four from one resolution, so they cannot straddle
+     * a publish: from the registry row's summary when it can use it, else from the opened generation's footer and
+     * index, with no payload read. A source without one answers from its other methods, each its own resolution: its
+     * summary when it has one, else `count()` and the generation it resolves, and its `sizeOf`, or `sizeBytes: null`
+     * when it has none. A segment with no generation answers `{ generation: null, cardinality: 0, sizeBytes: null }`.
      */
     stat(seg: SegmentRef): Promise<{
         generation: number | null;
         cardinality: number;
         metadata?: GenerationMetadata;
+        sizeBytes: number | null;
     }>;
-    /** Whether the Storage source can measure segment size (for grounded cost); false ⇒ storage isn't grounded. */
-    get supportsStorageSize(): boolean;
-    /** How often the Storage source re-reads a pointer while reading (cost reporting); undefined if it does not say. */
-    get pointerRefreshMs(): number | undefined;
-    /** Grounded Storage size of a segment's current generation (cost reporting), or null if it has no generation. */
-    segmentSize(seg: SegmentRef): Promise<SegmentSize | null>;
+    /** The size of the segment's current generation from the source's `sizeOf`, or `null` when it cannot say. */
+    private sizeOf;
     /** The chunks of `seg` at `chunkKeys`, read through a window of {@link DEFAULT_INTERSECT_CONCURRENCY}. */
     private chunkWindow;
     /**
@@ -214,11 +220,13 @@ export declare class SegmentEngine {
      * the result — every chunk read is a whole, checksum-verified, immutable generation. The edge a *long* call can
      * hit is invariant 3's: if it straddles a mid-call `cache.genTtlMs` boundary and a load has published, an
      * operand's not-yet-requested chunks may re-resolve forward to the newer generation (a generation hop within one long
-     * call) — the call never crashes or returns a torn object, but may mix generations. Three things hop it without
-     * waiting for the TTL, so a shorter call can meet them too: **the reader cache evicting an operand mid-call**
-     * (`maxOpenSegments`), whose re-read re-resolves fresh; a sweep deleting the generation it was reading, which
-     * heals the read forward; and an invalidation, which this store's own `load`, `rollback` and `eraseSubject` make
-     * and `invalidate()` makes on request. Still whole/immutable per read, never torn. An operand's stream resolves its
+     * call) — the call never crashes or returns a torn object, but may mix generations. Some things hop it without
+     * waiting for the TTL, so a shorter call can meet them too: **the reader cache evicting an operand mid-call** on a
+     * store with no timed refresh (`maxOpenSegments`), whose re-read re-resolves fresh, and on a store with one the
+     * resolution cache letting the operand's resolution go; a sweep deleting the generation it was reading, or another
+     * object under its number, met by this read or another, which heals the read forward, as another read's failed open
+     * of the operand does; and an invalidation, which this store's own `load`, `rollback` and `eraseSubject` make and
+     * `invalidate()` makes on request. Still whole/immutable per read, never torn. An operand's stream resolves its
      * segment again before it serves each chunk, so each of those moves a running read as it would a read of one chunk, and
      * the ranges it had requested of the earlier generation are dropped, not served.
      */

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

@@ -11,9 +11,11 @@
  *
  * The rewrite is the same generation without one id, so it keeps everything else: the new object carries the source's
  * metadata as it is, and the row's summary of it, built from what was written, counts one id fewer and holds the same
- * metadata. Metadata is not scanned for the id. On an encrypted segment, a source object with no metadata block whose
- * row's sealed summary of it has metadata is rewritten with the row's: the block's presence is not authenticated, so
- * the authenticated copy decides, and the erasure still goes through.
+ * metadata. Metadata is not scanned for the id. A source object whose metadata block was stripped is another object
+ * than the row's summary names: its size is not the one the summary records, so the fingerprint check refuses it
+ * before the erasure reads any of its ids. Only one forged to match that fingerprint gets past, and on an encrypted
+ * segment it is rewritten with the metadata of the row's sealed summary: the block's presence is not authenticated, so
+ * the authenticated copy decides.
  *
  * **`erased: true` is a claim about every generation of the segment, not only the one it replaced.** A rollback
  * leaves generations above the pointer that were once current and can be made current again, so a holder can sit
@@ -48,16 +50,17 @@
  * Which reason comes from **re-reading the row**, not from assuming a supersession: a moved pointer is
  * `'superseded'`, a tombstoned row `'destroyed'`, a purged row `'absent'`, a row with no pointer
  * `'no-generation'`. A pointer still on `from` means the object it names is genuinely gone — the forbidden
- * `missing-storage-generation` state — and that throws, because no re-run fixes it. That `NotFoundError` is the only
- * signal of that state, so a faulting re-read rethrows it rather than replacing it with a transient-looking
- * registry error.
+ * `missing-storage-generation` state — or is another object than the row's summary names by its fingerprint, and that
+ * throws, because no re-run fixes either. That `NotFoundError` is the only signal of those states, so a faulting
+ * re-read rethrows it rather than replacing it with a transient-looking registry error.
  *
  * **A refused rewrite deletes its own object when it would outlive the winner above the pointer.** `putImmutable`
  * commits atomically, so a rewrite whose stream throws leaves no object at all. One that completed is either
  * below the winner's pointer, where the winner's collection takes it, or above it: the case where this call took
  * its number after the winner's object was already in the bucket. Up there nothing collects it, and it was derived
  * from a generation the winner has replaced, so when the winner was another erasure it still holds the id that
- * erasure has just reported gone. That object is deleted before this call returns — see `discardRefused`.
+ * erasure has just reported gone. That object is deleted before this call returns, once its footer proves it the
+ * rewrite's own, under the version that read reported — see `discardRefused`.
  *
  * Without that fence the failure was silent and severe, and both halves were reproduced: `nextGeneration` picks a
  * number above everything in the bucket, so a forward-only publish here always won — discarding a concurrent
@@ -68,10 +71,21 @@
  * A live read still fetching from the collected generation heals forward to the rewrite, and a pin of it fails with
  * `NotFoundError` for any chunk it has yet to read: that is the documented cost of physical deletion on return. **Do not re-load the id while erasing it**: a load that lands after this rewrite
  * carries whatever its source held, and the library cannot know that source was meant to exclude the id.
- * A load already in flight writes its object above the pointer before it publishes. An erasure that finds the id in that
- * object writes the row before deleting it, so the load's publish, fenced on the row it read, is refused
- * (`published: false`) and the pointer never names a missing object (see `fenceInFlight`). A first load onto a row with
- * no pointer has nothing to be fenced on, so an erasure that finds the id in its object refuses instead.
+ * A load already in flight writes its object above the pointer before it publishes, or, as a first load onto a row with
+ * no pointer, before there is a pointer at all. An erasure that finds the id in that object renews the row's `pointerId`
+ * before deleting it, so the load's publish, fenced on the row it read, is refused (`published: false`) and the pointer
+ * never names a missing object (see `fenceInFlight`). An erasure that finds no holder writes nothing.
+ *
+ * An object sealed under a key its row does not hold cannot be searched, and no read of the segment can open it: a
+ * first load's on a row with no pointer, whose key that load has not published; on a segment with a key, a first
+ * load's that lost the race to the one that published, or crashed, under a key it made and never stored; and on a
+ * cleartext segment with a pointer, any encrypted object, since a key is made only for a segment's first generation
+ * and a publish never adds one to a segment that has generations: a first load's that minted a key and crashed, or
+ * lost the race to a cleartext first load. It counts as
+ * a holder whatever the id: an erasure of any id that finds one deletes it, under the same renewal of the row and read
+ * before the delete, and lists it in `collected`, and a first load still in flight that wrote it is refused. Only a
+ * searched object that held the id makes the answer `erased: true`. The current generation is never one of them: one
+ * the row's key does not open throws, as every read of the segment does.
  */
 import { type IAuditSink } from './audit.js';
 import type { CodecInterface } from './codec.js';
@@ -97,11 +111,15 @@ export interface EraseIdDeps {
     readonly keystore?: IKeystore;
     /** When true, refuse to rewrite a **cleartext** segment (the same guard the read path and a load offer). */
     readonly requireEncryption?: boolean;
-    /** Supplying a clock that can yield makes the rewrite cooperative, as it makes a load. */
+    /**
+     * Supplying a clock that can yield makes the rewrite cooperative, as it makes a load. Its `sleep` is what a registry
+     * write that got no answer waits on before a fresh one is sent; with no `sleep`, such a write is not sent again and
+     * its `TransientError` is thrown.
+     */
     readonly clock?: Yielder;
     /**
-     * The random source that spreads the waits between the rewrite's fresh compare-and-swaps. Absent, the read retry's
-     * source is used if it has one, and otherwise each wait is its bound.
+     * The random source that spreads the waits between the fresh compare-and-swaps of the rewrite and of the row's
+     * renewal. Absent, the read retry's source is used if it has one, and otherwise each wait is its bound.
      */
     readonly rng?: Rng;
     /** Per-chunk decode ceiling (invariant 5); defaults to 1 MiB. The `.crbm` reader refuses an entry above its own `maxPayloadBytes` (1 MiB, plus 28 bytes when encrypted) at open, so raise that on the chunk source too. */
@@ -110,7 +128,7 @@ export interface EraseIdDeps {
      * The store's read retry, for the reads the rewrite makes along the way: the generation it rewrites and each of its
      * chunks, the read-back that verifies the generation it wrote, and any other generation it checks for the id. A
      * transient fault on one is run again under it rather than failing the erasure. Absent, each read is made once.
-     * The deletes are not retried, and the rewrite's registry write is settled as a load's is.
+     * The deletes are not retried, and the rewrite's registry write and the row's renewal are settled as a load's is.
      */
     readonly readRetry?: ReadRetry;
 }
@@ -126,13 +144,20 @@ export interface EraseIdResult {
     readonly erased: boolean;
     /**
      * Why the id was not erased, when `erased` is false. `'absent'` (no registry row), `'destroyed'` (a crypto-shred
-     * tombstone — already unreadable), `'no-generation'` (a row with no Storage data yet), `'not-member'` (no
-     * generation in the bucket holds the id — the common case across a fleet scan), or `'superseded'`.
+     * tombstone — already unreadable), `'no-generation'` (a row with no generation yet: its bucket can hold first loads'
+     * objects, none of them found to hold the id, and `collected` names any this call deleted unsearched, see below),
+     * `'not-member'` (no
+     * generation in the bucket holds the id — the common case across a fleet scan — with the same note on `collected`),
+     * or `'superseded'`.
      *
      * **`'superseded'` means this call did not erase the id, not that the id is still there.** Another writer — a
-     * load, another erasure, or a rollback — moved the pointer off the generation this call read, so what it was
-     * doing no longer follows from what is current: a rewrite derived from that generation is not a valid successor
-     * to the new one, and a generation it meant to delete above the pointer may be the one the pointer now names.
+     * load, another erasure, or a rollback — moved the pointer off the generation this call read (on a row with no
+     * pointer, any other write of the row before this call renewed it, a `setRetention` included), or replaced an
+     * object it meant to delete (another erasure deleted a holder above the pointer, or on a row with no pointer, and a
+     * load stored another object under its number, so the storage driver's conditional delete refused this call's,
+     * whether or not the pointer moved). What it was doing no longer follows from what is current: a rewrite derived
+     * from that generation is not a valid successor to the new one, and a generation it meant to delete may be the one
+     * the pointer now names, or another object than the one it read.
      * Re-run against the new generation: if the id is still present it is erased then; if the racing writer was
      * another erasure of the *same* id, the re-run reports `'not-member'` because it is already gone. Either way the
      * re-run settles it, which is why it is the documented action for this reason and for no other.
@@ -150,14 +175,20 @@ export interface EraseIdResult {
     readonly fromGeneration?: number;
     /**
      * The generation written without the id (present whenever one was written, even if `superseded`). A refused
-     * rewrite whose object sits above the winner's pointer deletes that object again before it returns.
+     * rewrite whose object sits above the winner's pointer deletes that object again before it returns, when its footer
+     * proves it the rewrite's own.
      */
     readonly generation?: number;
     /**
      * Generations this call deleted. On a rewrite that is normally `[fromGeneration]`, plus any older orphans. When
-     * the current generation did not hold the id, it is every generation below the pointer (`keep: 0` takes them
-     * together) and each one above the pointer that held the id; the ones above it that did not hold the id stay,
-     * because they are an operator's rollback targets. Empty when nothing was deleted.
+     * the current generation did not hold the id and a generation this call searched did, it is every generation below
+     * the pointer (`keep: 0` takes them together) and each one above the pointer that held the id; the ones above it
+     * that did not hold the id stay, because they are an operator's rollback targets. On a row with no pointer it is
+     * each first load's object that held the id. Wherever it found them, it is also each object sealed under a key the
+     * row does not hold, which this call cannot search and deletes whatever the id. When those are the only holders, it
+     * is only those, deleted one by one, and every generation this call searched stays: `reason` is then
+     * `'no-generation'` on a row with no pointer and `'not-member'` on one with a pointer. Empty when nothing was
+     * deleted.
      *
      * **It is what THIS call deleted, not the proof that the id is gone** — those differ: a concurrent collector can
      * take a generation holding the id first, and then `erased: true` is returned without it in `collected`, because
@@ -169,7 +200,10 @@ export interface EraseIdResult {
      * collection pass that could not prove the segment was still the same one (which an ordinary retirement landing
      * mid-call is enough to cause); the same refusal on the path where the current generation did not hold the id
      * and nothing was published at all; and a generation still holding the id when the bucket is listed at the end
-     * — one an operator rolled the pointer onto while a rewrite was collecting, say.
+     * — one an operator rolled the pointer onto while a rewrite was collecting, say, or, on a row with no pointer, the
+     * object of a first load that read the row before this call renewed it and wrote it after this call listed the
+     * bucket. The row write an erasure makes before deleting a holder a load may still publish, when it gets no answer
+     * that reading the row can settle, throws the registry's `TransientError`, and that holder is not deleted.
      *
      * **Re-run it**, and read what the re-run says rather than assuming it finished the job. The re-run looks for
      * the id in every generation in the bucket, not only the current one, and there are three outcomes:
@@ -191,7 +225,9 @@ export interface EraseIdResult {
  * it. See the module note for the contract.
  *
  * Emits one `segment.rewrite` audit event at the publish (before the superseded generation is collected), so the
- * compliance record exists the moment the generation without the id is authoritative.
+ * compliance record exists the moment the generation without the id is authoritative. An erasure that rewrites nothing,
+ * because only other generations held the id, emits one `segment.collect` once no generation holds it, and so does one
+ * that deleted only objects no read of the segment can open, which names no generation the id was found in.
  */
 export declare function eraseIdFromSegment(ref: SegmentRef, id: number, deps: EraseIdDeps, options?: {
     audit?: IAuditSink;

package/dist/core/generation-gc.d.ts

@@ -45,8 +45,9 @@ export interface LoadNumber {
  * `superseded`. The orphan above stays unpublished; the load whose check meets it numbers past it by the listing,
  * and collection takes it once a generation above it is current. Like a listing's, the number can be one whose
  * object was deleted (an erasure removes the generations above a rolled-back pointer that held the id), which is
- * why nothing identifies a generation by its number alone: the reader cache, the chunk cache and a pin all key on
- * the number and the row's token, and the token has moved on.
+ * why nothing identifies a generation by its number alone: the reader cache and the chunk cache key on the number and
+ * the row's `pointerId`, which every write that takes a number again renews, and an open of a row with a usable
+ * summary holds the object to the fingerprint the summary records; a pin keys on its object's fingerprint.
  */
 export declare function nextLoadGeneration(ref: SegmentRef, deps: GenerationDeps, row: RegistryRecord | null): Promise<LoadNumber>;
 /**

package/dist/core/keys.d.ts

@@ -1,7 +1,35 @@
 import type { ChunkRef, SegmentRef } from './ports.js';
 export declare function segmentKey(ref: SegmentRef): string;
 export declare function segmentPrefix(ref: SegmentRef): string;
+/**
+ * How many segments' encoded keys a {@link KeptSegmentKeys} holds before it empties: the reader cache's default
+ * segment count, a working set a long-lived reader keeps open. With 30-character names that is about 150 KB.
+ */
+export declare const KEPT_SEGMENT_KEYS = 1024;
+/**
+ * Segments' encoded keys ({@link segmentKey}, or {@link segmentPrefix}: whichever `encode` gives), kept so a read that
+ * looks up chunk after chunk compares names rather than encoding them again, which costs about a third of a warm
+ * `has()`. Held by namespace and then by segment, so segments of one name in several namespaces sit side by side, and
+ * no number of segments read in turn makes every lookup encode again. Bounded: at `max` entries it empties and fills
+ * again. An encoding is the names' and nothing else, so a kept one is the one an encoding would give now.
+ */
+export declare class KeptSegmentKeys {
+    private readonly encode;
+    private readonly max;
+    private readonly byNamespace;
+    private kept;
+    constructor(encode: (ref: SegmentRef) => string, max?: number);
+    /** The segment's encoded key. */
+    of(ref: SegmentRef): string;
+    /** How many encoded keys are kept. */
+    get size(): number;
+}
 export declare function chunkRefKey(ref: ChunkRef): string;
+/**
+ * {@link chunkRefKey}, or {@link chunkGenKey} with a `version`, from the segment's {@link segmentPrefix} already
+ * encoded: for a caller that looks up many chunks of a few segments and keeps their prefixes.
+ */
+export declare function chunkKeyUnder(prefix: string, chunkKey: number, version?: string | number): string;
 /**
  * Cache key for a chunk scoped to a specific **version** of the segment — {@link chunkRefKey} plus that
  * version (space-delimited, injection-proof exactly as above — the name parts are already encoded). A publish bumps the version, so it naturally

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 and by an erasure's
+ * renewal of the row.
+ */
+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

package/dist/core/load.d.ts

@@ -15,9 +15,11 @@
  *
  * 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.
+ * pointer), so a refused load deletes its own object before returning, while the segment's row is unchanged (or
+ * differs only in its leases), gone or `destroyed`, or has key material when the load wrote cleartext. Under a row
+ * that is gone or keyed, a read of the object's footer must prove it the load's own first. Once another write has
+ * otherwise 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';
@@ -169,10 +171,12 @@ export type LoadRefusal = 'empty' | 'min-cardinality' | 'min-retained' | 'max-gr
 /**
  * Another writer got there first. Either another load wrote the same generation number first, so the write-once
  * 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, or the row was
- * deleted. Once another write has changed the row, the object stays in the bucket, 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.
+ * 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.
  */
  | 'superseded';
 export interface LoadResult {

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
@@ -168,9 +168,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/pinned-storage-source.d.ts

@@ -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;