@cloudbitmaps/core 0.19.1 → 0.21.0

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

@@ -4,8 +4,6 @@ import type { IRegistryDriver, RegistryRecord } from './ports.js';
  * the fleet really is that large *and* the memory is there; narrow the scan with a `namespace` otherwise.
  */
 export declare const DEFAULT_MAX_SCAN_SEGMENTS = 250000;
-/** Fail fast on a bad ceiling BEFORE the (possibly huge) scan, not after. */
-export declare function validateMaxScanSegments(value: number, op: string): void;
 /**
  * Drain every registry record (optionally one namespace) into an array, refusing past `maxScanSegments`.
  *

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

@@ -1,69 +1,7 @@
-/**
- * The retention **sweep** — the thing that acts on the policies `setSegmentRetention` records.
- *
- * `retireExpired` enumerates the registry, selects the segments whose `expiresAt` has passed, and retires each
- * one through {@link dropSegment}. It deliberately **delegates rather than reimplements**: the registry → Storage
- * ordering, the re-sweep for an object a load was still writing, and the `generationsRemaining` report are all
- * load-bearing and already live there. A sweep that open-coded the deletions would be a second
- * implementation of the most dangerous ordering in the library.
- *
- * **This is a call, not a daemon.** Nothing here schedules itself. You run it from whatever heartbeat your
- * deployment already has — an EventBridge rule, a Kubernetes CronJob, a queue consumer, the job that runs your
- * loads — and the library stays a library: it has to behave identically in a Lambda, an edge isolate and a
- * long-lived server, and a timer that only works in one of those is worse than none.
- *
- * Three properties make it safe to point at a fleet:
- *
- *  - **`dryRun` at the sweep level.** `dropSegment`'s `confirmSegment` guard is vacuous in a loop (it is the same
- *    variable twice), so the meaningful preview is here: it reports what it *would* retire, per segment, and
- *    touches nothing.
- *  - **A per-cycle `limit`.** Clock skew, a bad backfill, or a namespace-wide policy mistake should cost one
- *    bounded batch, not the fleet. When the limit bites, the result says so (`limited: true`) rather than looking
- *    like a completed sweep.
- *  - **A ledger, never an exception.** A per-segment fault is recorded and the sweep continues — the caller's
- *    load-bearing question is *which* segments were retired, and a throw from the middle of the loop answers it
- *    for none of them while having already retired some. Same posture as `eraseNamespace`.
- *
- * 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 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
- * the generation collection.
- *
- * **On a registry that reports `conditionalDelete`, the purge removes the row for good**, so a full scan stops paying a
- * read for every name a namespace ever held: the scan costs what is live and what is inside its grace. The delete is
- * fenced on the token the purge judged and applied by the store only to that version of the row. Each retirement
- * files a pointer in the due index under the day its tombstone's grace ends, so `scan: 'index'` purges as well as
- * retires; nothing on the row records that day, which the purge derives from the stamp. The purge removes every pointer
- * it read to the row, and a pointer that outlives its row anyway (a purge that ran with another grace, a delete that
- * landed and lost its response, a pointer older than an index scan's lookback) is removed by the next scan that reads
- * it: an index scan in its buckets, and an unscoped fleet scan, which reads every pointer, in all of them. Where a
- * delete only rewrites the row as a tombstone, none of this is done: nothing is removed for good, so a pointer would
- * only add a row for every scan to read.
- */
 import { type IAuditSink } from './audit.js';
 import type { DropDeps, DropResult } from './erasure.js';
 /** Default cap on retirements per sweep — a bounded batch, so a policy mistake costs one batch, not the fleet. */
 export declare const DEFAULT_RETIRE_LIMIT = 100;
-/**
- * How many purges in a row the registry may refuse in one call before the sweep stops purging for the rest of it. A
- * blanket refusal (a policy that denies delete) costs this many attempts and no more; a refusal particular to one row
- * (a blob with a snapshot, an object under a legal hold) does not hold the purges behind it, since a purge that succeeds
- * starts the count again.
- */
-export declare const MAX_CONSECUTIVE_PURGE_FAULTS = 3;
-/**
- * Default delay before a retirement's own tombstone row is purged: 24 h.
- *
- * 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.
- */
-export declare const DEFAULT_TOMBSTONE_GRACE_MS = 86400000;
 export interface RetireExpiredOptions {
     /** Scope the sweep to one namespace. Omit to sweep every namespace the registry knows. */
     readonly namespace?: string;
@@ -74,8 +12,9 @@ export interface RetireExpiredOptions {
     readonly now: number;
     /**
      * Maximum segments to retire in this cycle (default 100). It also bounds the purges attempted (a purge the registry
-     * refuses is not charged; {@link RetireExpiredResult.purgeFaults} says how purging stops after refusals) and the
-     * due-index pointers to nothing one call removes.
+     * refuses is not charged; {@link RetireExpiredResult.purgeFaults} says how purging stops after refusals), the
+     * due-index pointers to nothing one call removes, and, counted apart from the retirements, the tombstones this sweep
+     * did not write whose pointers one call removes.
      */
     readonly limit?: number;
     /** Report what would be retired and change nothing. */
@@ -209,7 +148,10 @@ export interface RetireExpiredResult {
     readonly wouldRetire: number;
     /** Tombstone rows actually deleted. Zero under `dryRun`; the `would-purge-tombstone` entries carry the preview. */
     readonly tombstonesPurged: number;
-    /** True when `limit` cut the cycle short — **more segments are still eligible**. Re-run. */
+    /**
+     * True when `limit` cut the cycle short — **more segments are still eligible**. Re-run. The cap on removing pointers
+     * of tombstones this sweep did not write leaves it false.
+     */
     readonly limited: boolean;
     /**
      * Deletes this sweep attempted that were **refused for a reason other than a lost race**: a tombstone's purge
@@ -238,6 +180,67 @@ export interface RetireExpiredResult {
  * 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;
+/** The options of a sweep, validated, with every default filled in. */
+interface ResolvedRetireOptions {
+    readonly audit: IAuditSink | undefined;
+    readonly namespace: string | undefined;
+    readonly now: number;
+    readonly limit: number;
+    readonly purgeTombstones: boolean;
+    readonly grace: number;
+    readonly maxScanSegments: number;
+    readonly dryRun: boolean;
+    readonly scan: 'fleet' | 'index';
+    readonly lookbackBuckets: number;
+    readonly shards: readonly number[] | undefined;
+    readonly totalShards: number;
+}
+/**
+ * Check a sweep's options and fill in the defaults. Pure: it reads nothing but `options`, and throws
+ * `ValidationError` for the first bad one, in the order the checks below run.
+ */
+export declare function resolveRetireOptions(options: RetireExpiredOptions): ResolvedRetireOptions;
+/**
+ * The counters and the ledger of one sweep, and the two budgets that bound it.
+ *
+ * The budget is charged on ATTEMPT, not on success, and that distinction is the whole guard. `dropSegment`
+ * writes the tombstone BEFORE sweeping Storage, so a fault in the Storage phase is a segment that is
+ * already retired. Counting only successes would let a partial storage outage march through the entire fleet
+ * with the cap never engaging, reporting `retired: 0, limited: false` (a "completed sweep that retired nothing")
+ * while every segment in the namespace is tombstoned. So a step charges `attempted` before the call that can delete
+ * (the drop, or the purge's collection), after any re-read that finds nothing due, and gives the charge back in two
+ * places only: a purge the registry or storage refused (`refusedPurge`), and a drop that wrote and deleted nothing
+ * because the row was no longer the sweep's to retire (`dropSegmentFor` returned `null`).
+ */
+export declare class SweepTally {
+    readonly entries: RetireEntry[];
+    eligible: number;
+    retired: number;
+    wouldRetire: number;
+    tombstonesPurged: number;
+    limited: boolean;
+    /** Deletes the registry refused for a reason other than a lost race. */
+    purgeFaults: number;
+    /** The first one's reason. A lost race is the row or pointer changing under a fenced delete, which is the fence working. */
+    firstPurgeFault: `failed: ${string}` | undefined;
+    /** Retirements and tombstone purges begun, charged against `limit`. */
+    attempted: number;
+    /** Tombstones the sweep did not write whose pointers it worked, bounded by `limit` apart from `attempted`. */
+    attemptedForeign: number;
+    /**
+     * Purging stops after this many refused purges in a row, and a purge that succeeds starts the count again. Each
+     * refused attempt costs reads before it fails, and a blanket refusal would fail them all; one row's refusal must
+     * not hold the rest.
+     */
+    purgeRun: number;
+    purging: boolean;
+    /** Record a step's ledger entry; `null` adds nothing (a step with nothing to report, or one that recorded its own). */
+    add(entry: RetireEntry | null): void;
+    /** Count a delete the registry refused, unless it was a lost race. */
+    readonly noteFault: (err: unknown) => void;
+    /** A purge the registry refused is not charged to `limit`, and after enough in a row purging stops. */
+    refusedPurge(): void;
+}
 /**
  * Retire every segment whose retention policy has expired, and clean up the tombstones earlier sweeps left.
  *
@@ -246,3 +249,4 @@ export declare const DEFAULT_LOOKBACK_BUCKETS = 7;
  * condition, not a partial result to be mistaken for a complete sweep.
  */
 export declare function retireExpired(deps: DropDeps, options: RetireExpiredOptions): Promise<RetireExpiredResult>;
+export {};

package/dist/core/retention.d.ts

@@ -1,4 +1,4 @@
-import { type ChurnDeps } from './leases.js';
+import type { ChurnDeps } from './leases.js';
 import type { GovernanceMeta, IRegistryDriver, SegmentRef } from './ports.js';
 /**
  * The smallest accepted `expiresAt`: 2001-09-09, the point below which an epoch-**seconds** value would land.

package/dist/core/retry.d.ts

@@ -1,21 +1,3 @@
-/**
- * `withRetry` — the one retry/backoff primitive.
- *
- * A pure, storage-agnostic helper: it knows nothing about HTTP, AWS, or any SDK. It retries an operation
- * while the operation keeps failing with a **retryable** error (by default {@link TransientError}), waiting
- * a bounded, jittered, exponentially-growing delay between attempts. Time and randomness are **injected**
- * (the determinism seam) — production wires a `setTimeout`-backed clock + a real RNG; the
- * tests wire virtual ones — so a backoff schedule is replayable from a seed and unit tests run with no
- * real sleeping.
- *
- * 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
- * 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.
- */
 import type { Clock, Rng } from './determinism.js';
 export interface RetryPolicy {
     /** Total attempts including the first (so `maxAttempts: 4` = 1 try + 3 retries). Must be ≥ 1. */
@@ -61,6 +43,15 @@ export interface RetryDeps {
 export declare function backoffDelayMs(policy: RetryPolicy, attempt: number): number;
 /** Apply the policy's jitter to a computed delay using the injected RNG. */
 export declare function applyJitter(policy: RetryPolicy, delayMs: number, rng: Rng): number;
+/** A clock that can wait: the one member {@link jitteredWait} uses. */
+interface Sleeper {
+    readonly sleep?: ((ms: number) => Promise<void>) | undefined;
+}
+/**
+ * Wait a uniformly spread share of `boundMs`, whole milliseconds, by the clock's `sleep`. With no `rng` it waits the
+ * whole bound; with no `sleep` it does not wait.
+ */
+export declare function jitteredWait(clock: Sleeper | undefined, rng: Rng | undefined, boundMs: number): Promise<void>;
 /**
  * The store's read retry, as a write path takes it for the reads it makes along the way: a policy (the default when
  * absent) and what {@link withRetry} needs to run it.
@@ -78,7 +69,8 @@ export declare function retryRead<T>(op: () => Promise<T>, retry: ReadRetry | un
 /**
  * `policy`, checked when it is wired rather than at the first retry: a delay or factor that is not a finite number, a
  * negative delay, a factor below 1 or a jitter mode it does not know would make the backoff `NaN`, which a timer reads
- * as 1 ms, so bounded backoff silently became a hot retry loop.
+ * as 1 ms, so bounded backoff silently became a hot retry loop. `maxAttempts` is a whole number, and `maxDelayMs` is not
+ * below `baseDelayMs`, which it would otherwise cap every delay under.
  */
 export declare function checkedRetryPolicy(policy: RetryPolicy): RetryPolicy;
 /**
@@ -87,3 +79,4 @@ export declare function checkedRetryPolicy(policy: RetryPolicy): RetryPolicy;
  * the *operation's* error — never a wrapper — so callers keep their typed-error branching.
  */
 export declare function withRetry<T>(op: () => Promise<T>, policy: RetryPolicy, deps: RetryDeps): Promise<T>;
+export {};

package/dist/core/rollback.d.ts

@@ -1,21 +1,3 @@
-/**
- * `listGenerations` and `rollbackSegment` — see what a segment has been, and put it back.
- *
- * Immutable generations mean the previous version of a segment is usually still sitting in the bucket: a load
- * that replaced it did not overwrite anything, it wrote a new object and moved a pointer. So recovering from a
- * bad load is, in principle, moving the pointer back, which no load, publish or sweep can do, because every other
- * write path in the library only ever advances the pointer, and refuses a move that would lower it.
- *
- * That refusal is right for a *writer*: a load whose ids came from upstream loses nothing by being out-raced, and
- * letting it regress the pointer would let a slow loader silently undo a fast one. It is wrong for an *operator*,
- * who has looked at the segment, decided the current generation is wrong, and knows which one they want. So
- * rollback is the one call that moves the pointer backwards, and it is deliberately not reachable from any
- * automatic path — no sweep, no retry, no reconciliation calls it.
- *
- * It is audited for the same reason. Every other pointer move can be reconstructed from "a load happened"; this
- * one is a human overriding the ordering rule the rest of the system relies on, which is exactly the event an
- * Art. 30 record or an incident review wants to find.
- */
 import { type IAuditSink } from './audit.js';
 import type { IKeystore } from './crypto.js';
 import { type ChurnDeps } from './leases.js';
@@ -26,8 +8,10 @@ export interface GenerationListDeps extends ChurnDeps {
     readonly registry: IRegistryDriver;
     /**
      * The key of an encrypted segment, so a rollback can read its target's count and metadata and seal them into the
-     * row. Without it, a rollback of an encrypted segment still works and leaves the row with no summary of the
-     * generation it moves to, which a reader then takes from the object.
+     * row. Without it, a rollback of an encrypted segment onto a generation the row knows still works and leaves the
+     * row with no summary of the generation it moves to, which a reader then takes from the object; `allowUnknown` needs
+     * it, and is refused with `KeyUnavailableError`, or throws `TransientError` when the key service did not answer in
+     * time (the keystore's own, or one whose `cause` is the timeout it threw).
      */
     readonly keystore?: IKeystore;
 }
@@ -36,6 +20,15 @@ export interface GenerationEntry {
     readonly generation: number;
     /** Whether the registry pointer currently names this generation. */
     readonly current: boolean;
+    /**
+     * Whether the row's record of the generations it published, `knownGens`, names this generation. A rollback onto a known
+     * generation needs no `allowUnknown`; an unknown one needs it, except below the pointer in the two cases the pointer
+     * alone decides (a row with no usable `knownGens`, and a target below a full one's bound), where it needs none. The
+     * row's word, read with the listing's one registry read: the object is not opened, so
+     * its checksum is not compared. `false` for every generation of a row whose record is missing or unusable, and for a
+     * segment with no row. The current generation of a row with a usable record is always known.
+     */
+    readonly known: boolean;
     /**
      * The current generation's id count, from its registry row, with no read of the object. Present only on the current
      * entry, and only when the row's summary can be used: for an encrypted segment that takes a keystore that opens the
@@ -65,11 +58,20 @@ export interface RollbackResult {
     readonly generation: number;
 }
 /**
- * Move a segment's pointer **back** to a generation that is still in the bucket.
+ * Move a segment's pointer to a generation that is still in the bucket and that the segment's row knows it published.
  *
  * The only non-forward-only publish in the library, and the only one an operator has to ask for by name. It
  * refuses rather than guesses:
  *
+ * - a generation the **row does not know** is refused with `ValidationError`, before any request to storage. The row
+ *   records, in `knownGens`, the generations its loads and rollbacks made current, with the footer checksum of each
+ *   object; a target outside that record is where objects live that no row ever published: a load that wrote its object
+ *   and died before the publish, a refused load's object, an object sealed under a key no row holds, a load published
+ *   after the point a registry was restored to. {@link rollbackSegment}'s `allowUnknown` is the one explicit override;
+ * - a known generation whose object is **not the one the row recorded** (its footer checksum differs: another object was
+ *   stored under the number) is refused with `IntegrityError`, with or without a key, since the footer is in the clear.
+ *   The check runs before the target is opened, so an object sealed under another key reports as another object, not as a
+ *   failed decryption. `allowUnknown` moves onto it anyway;
  * - a generation whose object is **not in the bucket** — collected, or never written — is refused with
  *   `NotFoundError` rather than pointed at, because a pointer naming a missing object is the one state the whole
  *   design exists to avoid;
@@ -78,29 +80,57 @@ export interface RollbackResult {
  * - a target that is **not what the row says the segment is** is refused with `IntegrityError`: a cleartext object
  *   under a row with keys, or an encrypted one under a row with none, either of which every read would then refuse.
  *   One tail read of the target decides it, as does a footer that fails its own checks;
- * - rolling to the generation **already current** is a no-op that reports itself, not an error.
+ * - `allowUnknown` on an **encrypted** segment, outside the two cases the pointer alone decides (below), needs the key,
+ *   and is refused with `KeyUnavailableError` when the store has
+ *   no keystore, or its keystore holds none of the key's KEKs or one that does not unwrap the key: an object the row
+ *   does not vouch for and that nothing opens may be one sealed under a key no row holds. A key service that did not
+ *   answer in time is thrown as `TransientError`, to retry;
+ * - rolling to the generation **already current** is a no-op that reports itself, not an error, once one footer read finds
+ *   its object in the bucket and, when the row knows it, with the checksum recorded. A pointer that names a missing
+ *   object is refused with `NotFoundError`, as any missing target is, and one that names another object than the row
+ *   recorded with `IntegrityError`.
+ *
+ * Which generations are known: the current one, the ones a load's `keep` keeps below it, those a live lease holds, and
+ * the ones a rollback left above the pointer, until a load numbers above them. A known target needs no flag and, for
+ * the same reason, no key: moving onto an object the row published, forward or back. Two cases are decided by the
+ * pointer alone, so a target below it needs no flag and no key, and are audited with `unknown: true`: a row with no
+ * usable `knownGens` (a registry that drops the field, or a row whose pointer was moved by hand); and a target below the
+ * bound of a full record (128 entries or more, leased ones included), which is its least recently current entry that no
+ * lease entry names. Neither gets the checks above. A generation a publish with a smaller `keep` no longer names but that
+ * stays in the bucket (a lease spared it, or its delete failed) needs `allowUnknown` until a later listing collects it.
  *
  * The same tail read opens the target when the segment's key is at hand, and the rollback writes the target's own id
  * count and metadata into the row, in the compare-and-swap that moves the pointer: a reader that sees the target as
  * current sees what describes it. (One tail read, and a range read as well when the target's index is longer than the
- * tail read: a target of very many chunks.) A store with no keystore, or one that cannot open the segment's key for any
- * reason, a keystore that is unreachable or timed out included, still rolls an encrypted segment back and leaves the
- * row with no summary of the target. The undo of a rollback whose target was collected meanwhile puts back the summary
- * the row had, and so does the undo of an `allowForward` rollback whose target was replaced meanwhile: an object above
- * the pointer can be deleted by an erasure and its number taken by a load, between the read and the swap, so after the
- * swap such a target is read once more, and the pointer put back unless it is the object whose summary was written.
+ * tail read: a target of very many chunks.) A store with no keystore, or whose keystore cannot open the segment's key
+ * (it holds none of the key's KEKs, one it holds does not unwrap it, or it throws `TransientError` or times out as
+ * `AbortSignal.timeout()` and the AWS SDK report a timeout), still rolls an encrypted segment onto a known generation, or
+ * below the pointer in the two judged-as-before cases, and leaves the row with no summary of the target. Any other
+ * failure of the keystore is thrown. After the swap the target's footer is read once more, and the pointer put back,
+ * restoring the summary and the record the row had, unless it is still the object that was read: collection can delete a
+ * target below the old pointer between the read and the swap, and an erasure can delete one above it and a load take its
+ * number. A swap that gets no answer is settled by reading the row: one the row shows landed, the row being the one the
+ * swap leaves, is checked as any swap is, and otherwise its `TransientError` is thrown, since it may have landed or may
+ * still land, and a re-run finds the pointer where it is. A write by another writer is not taken for it, unless it leaves
+ * the very row this swap would. On a cleartext segment two writes can: another rollback onto the same target, whatever
+ * row it read, and a load that wrote under that number the very object the rollback read and carried the ledger the
+ * rollback would (a load that carries a usable ledger, as one with a `keep` above 64 does; over a row with no usable
+ * ledger the rollback writes none and a load seeds one, so those rows differ). On an encrypted segment a rollback with no
+ * key at hand writes no summary, so another such rollback onto the same target can too. That call then reports and
+ * audits the move as its own; the pointer is where it asked for it.
  *
  * What it does **not** do is delete anything. The generations above the new pointer stay in the bucket, which is
  * what makes the rollback reversible — roll forward again by naming one of them. They are also then *above*
  * `currentGen`, where generation collection never looks. They stay until loads pass them (the first load whose
- * number one of them holds numbers above them all, and collection then keeps the newest `keep` of what is below its
- * pointer), `dropSegment` deletes them, or a subject erasure
- * deletes them: all of those present when it rewrites, and only those holding the id when the current generation does not.
+ * number one of them holds numbers above them all, and collection then keeps `keep` of what is below its pointer, the
+ * generation that load superseded first), `dropSegment` deletes them, or a subject erasure
+ * deletes them: all of those present when it rewrites, and, when the current generation does not hold the id, only those
+ * holding it and any no read of the segment can open, whatever the id.
  * Not collecting them is a deliberate trade: an operator who has just undone a bad load should not have the
  * evidence collected out from under them, while a rollback target that still holds erased data would make the
  * erasure undoable by an ordinary operator action.
  */
 export declare function rollbackSegment(ref: SegmentRef, toGeneration: number, deps: GenerationListDeps, options?: {
     audit?: IAuditSink;
-    allowForward?: boolean;
+    allowUnknown?: boolean;
 }): Promise<RollbackResult>;

package/dist/core/summary.d.ts

@@ -2,50 +2,86 @@
  * A generation's summary on its registry row: how a writer builds it, how a reader opens it, and how it is held
  * against the object it describes.
  *
- * The row carries a cached description of the current generation, `{ generation, cardinality, metadata? }`, written by
- * the same compare-and-swap that moves the pointer. On a cleartext segment the values are in the clear. On an
- * encrypted one the row holds `{ generation, sealed }` instead: the cardinality as a fixed-width little-endian u64,
- * then the metadata's canonical JSON if there is any, sealed under the segment's data key with the summary scope of
- * the associated data, which binds it to its namespace, segment and generation. The count is fixed-width so the
- * ciphertext's length reveals only the metadata's size, never how many digits the count has. Pure: no I/O.
+ * The row carries a cached description of the current generation, `{ generation, cardinality, fingerprint, tailBytes,
+ * metadata? }`, written by the same compare-and-swap that moves the pointer. The fingerprint names the generation's
+ * object, by its size and footer checksum, as `CrbmReader.fingerprint` does, and `tailBytes` is how much of the object's
+ * end one open reads. On a cleartext segment the values are in the clear. On an encrypted one the row holds
+ * `{ generation, sealed }` instead: the cardinality as a fixed-width little-endian u64, the object's size as a u64 and
+ * its footer checksum as a u32, then `tailBytes` as a u32, then the metadata's canonical JSON if there is any, sealed
+ * under the segment's data key with the summary scope of the associated data, which binds it to its namespace, segment
+ * and generation. The numbers are fixed-width so the ciphertext's length reveals only the metadata's size, never how
+ * many digits the count or the size has, and `tailBytes`, which tracks the number of chunks, is sealed for the same
+ * reason the size is. Pure: no I/O.
  *
  * The generation's `.crbm` object stays the truth, and the summary is a copy of it. {@link summaryAgrees} is the
- * comparison of one with the other.
+ * comparison of one with the other, and the fingerprint is what a reader holds every object it opens against.
  */
 import type { Aead } from './crypto.js';
 import type { ClearRegistrySummary, GenerationMetadata, RegistryRecord, RegistrySummary, SealedRegistrySummary, SegmentRef } from './ports.js';
-/** What a summary says about a generation: its id count, and its metadata when it has any. */
+/** A generation holds at most every 32-bit id. */
+export declare const MAX_SUMMARY_CARDINALITY: number;
+/**
+ * The most a summary's `tailBytes` can be: the reader's own default caps on what an open fetches, an index of at most
+ * 8 MiB, an extension block of at most its cap and its trailer, and the footer. The library's writer cannot reach it. A
+ * reader can report more for an object it did not write, since it accepts bytes between the index and the footer. A
+ * literal, so the registry validators that use it do not import the format module; a test holds it to the sum of the
+ * format's constants.
+ */
+export declare const MAX_TAIL_BYTES = 8392820;
+/** Whether `tailBytes` is one a summary of an object of `size` bytes can carry. */
+export declare function tailBytesFit(tailBytes: unknown, size: number): boolean;
+/**
+ * What a summary says about a generation: its id count, and its metadata when it has any. `tailBytes`, when given, is
+ * the bytes of the object's end one open reads.
+ */
 export interface GenerationDescription {
     readonly cardinality: number;
     readonly metadata?: GenerationMetadata | undefined;
+    readonly tailBytes?: number | undefined;
+}
+/**
+ * What a row's summary says: the generation's description, the fingerprint of the object it describes and the
+ * bytes of that object's end one open reads.
+ */
+export interface SummaryDescription extends GenerationDescription {
+    readonly fingerprint: string;
+    readonly tailBytes: number;
 }
-/** The clear summary of a generation on a cleartext segment. `metadata` is left off when there is none. */
-export declare function clearSummary(generation: number, cardinality: number, metadata?: GenerationMetadata): ClearRegistrySummary;
+/** The size of the object a fingerprint names, in bytes: what `stat()` reports from a row's summary. */
+export declare function sizeOfFingerprint(fingerprint: string): number;
 /**
- * The sealed summary of a generation on an encrypted segment: the cardinality as a u64, then the metadata's canonical
- * JSON, sealed under `aead` and bound to `ref` and `generation`.
+ * The clear summary of a generation on a cleartext segment, naming its object by `fingerprint`. `metadata` is left off
+ * when there is none.
  */
-export declare function sealSummary(aead: Aead, ref: SegmentRef, generation: number, cardinality: number, metadata?: GenerationMetadata): SealedRegistrySummary;
+export declare function clearSummary(generation: number, cardinality: number, fingerprint: string, tailBytes: number, metadata?: GenerationMetadata): ClearRegistrySummary;
+/**
+ * The sealed summary of a generation on an encrypted segment: the cardinality as a u64, the object's size as a u64,
+ * its footer checksum as a u32 and its `tailBytes` as a u32, then the metadata's canonical JSON, sealed under `aead` and
+ * bound to `ref` and `generation`.
+ */
+export declare function sealSummary(aead: Aead, ref: SegmentRef, generation: number, cardinality: number, fingerprint: string, tailBytes: number, metadata?: GenerationMetadata): SealedRegistrySummary;
 /**
  * What a sealed summary says, opened with `aead` under the summary scope of `ref` and the summary's own generation.
  * The bytes are untrusted: a blob that is not base64, is the wrong size, fails its authentication (tampered, or moved
- * from another generation's row), or holds a count outside 0 to 2^32 or metadata that breaks the rules, is an
- * {@link IntegrityError}.
+ * from another generation's row), or holds a count outside 0 to 2^32, a size no object can have, or metadata that
+ * breaks the rules, is an {@link IntegrityError}.
  */
-export declare function openSummary(aead: Aead, ref: SegmentRef, summary: SealedRegistrySummary): GenerationDescription;
+export declare function openSummary(aead: Aead, ref: SegmentRef, summary: SealedRegistrySummary): SummaryDescription;
 /**
  * What a row's summary says of its current generation, or `undefined` when it says nothing a reader may use. It is
  * used only for the generation it names, on an active row, and in the shape the row's keys call for: clear on a row
  * with no wrapped keys, sealed on a row with them. A sealed one is opened with `aead`, and is unusable without it,
- * or when it does not open, so a summary a tamperer moved or rewrote is never believed. Never throws for a bad
- * summary: the row's copy is a cache, and a copy that cannot be used is a copy that is not there.
+ * or when it does not open, so a summary a tamperer moved or rewrote is never believed; a clear one whose fingerprint
+ * names no object is unusable too. Never throws for a bad summary: the row's copy is a cache, and a copy that cannot be
+ * used is a copy that is not there.
  */
-export declare function usableSummary(ref: SegmentRef, row: RegistryRecord, aead: Aead | undefined): GenerationDescription | undefined;
+export declare function usableSummary(ref: SegmentRef, row: Pick<RegistryRecord, 'summary' | 'status' | 'currentGen' | 'wrappedDeks'>, aead: Aead | undefined): SummaryDescription | undefined;
 /**
  * Whether a summary's description of a generation is what its object holds: the same id count and the same metadata,
- * compared in canonical form, so key order never matters. A summary with metadata over an object with none, and the
- * reverse, disagree: whether an encrypted object's metadata block is present is not authenticated (stripping it needs
- * no key), so the row's sealed copy is what a missing block is held against.
+ * compared in canonical form, so key order never matters, and the same `tailBytes` when both say one (a cold open sizes
+ * its tail read from the row's, so a number the object does not bear out is not believed again). A summary with
+ * metadata over an object with none, and the reverse, disagree: whether an encrypted object's metadata block is present
+ * is not authenticated (stripping it needs no key), so the row's sealed copy is what a missing block is held against.
  */
 export declare function summaryAgrees(summary: GenerationDescription, object: GenerationDescription): boolean;
 /**
@@ -54,8 +90,21 @@ export declare function summaryAgrees(summary: GenerationDescription, object: Ge
  * metadata block is not authenticated, so a block stripped from one reads as none, and the sealed summary on the row is
  * the one copy that says there was a block; carrying it keeps the rewrite from erasing the record of what it dropped.
  * Pass `authenticated` only for a summary that was opened (a clear one has no more authority than the block it sits
- * beside). Never refuses: a rewrite over a stripped block is still an erasure.
+ * beside). Never refuses. The erasure reaches this with a stripped block only past a fingerprint forged to match the
+ * row's, since stripping the block changes the object's size and the open is held to the row's fingerprint.
  */
 export declare function metadataToCarry(object: GenerationMetadata | undefined, authenticated: GenerationDescription | undefined): GenerationMetadata | undefined;
-/** The summary of a generation of `ref`, clear or sealed under `aead` as the segment's keys call for. */
-export declare function summaryOf(ref: SegmentRef, generation: number, description: GenerationDescription, aead: Aead | undefined): RegistrySummary;
+/**
+ * The summary of a generation of `ref`, describing the object `description.fingerprint` names, clear or sealed under
+ * `aead` as the segment's keys call for. `undefined` when the object's `tailBytes` is above {@link MAX_TAIL_BYTES}: a
+ * reader accepts bytes between an object's index and its footer, so an object this library did not write can report a
+ * tail the row cannot record, and a row is legal without a summary (a read then opens the object with the default tail).
+ * The description's size, footer checksum and `tailBytes` must all come from the one object.
+ */
+export declare function summaryOf(ref: SegmentRef, generation: number, description: SummaryDescription, aead: Aead | undefined): RegistrySummary | undefined;
+/**
+ * {@link summaryOf} for an object this library wrote, whose tail is within {@link MAX_TAIL_BYTES} by construction (its
+ * index holds at most 65,536 entries and its extension block at most 4 KiB). Throws {@link IntegrityError} for a tail
+ * that is not, which the writer cannot produce.
+ */
+export declare function ownSummary(ref: SegmentRef, generation: number, description: SummaryDescription, aead: Aead | undefined): RegistrySummary;

package/dist/core/token.d.ts

@@ -4,8 +4,8 @@
  * A shipped registry gives a row it creates a token `<incarnation>.<counter>.<write>`: 32 lowercase hex digits drawn
  * from injected entropy when the row is created, a decimal counter, and 16 hex digits drawn for each write. Every write
  * of the row keeps the incarnation, and a name created again draws a new one, so two incarnations are told apart by it
- * even when their rows were created in the same millisecond or one is gone. A row a 0.11 build wrote has no incarnation
- * for as long as it lives (`"7"`, then `"8.<write>"`), and a registry of someone else's issues tokens in any form.
+ * even when their rows were created in the same millisecond or one is gone. A registry of someone else's issues tokens
+ * in any form, and one whose tokens carry no incarnation id is told apart only by the row's creation stamp.
  *
  * This lives in `core/` so the publish can read it, and the registry drivers, which build the tokens, import it from
  * here: the form has one definition.
@@ -14,18 +14,23 @@ import type { Token } from './ports.js';
 /** An incarnation-form token: the incarnation id, the counter and a write part, `.`-separated, in lowercase hex. */
 export declare const INCARNATION_TOKEN: RegExp;
 /**
- * The incarnation id in a token, or `undefined` for one that has none: a schema-1-born row's, or any token another
- * driver issues. Two tokens with the same incarnation are writes of one incarnation of a row.
+ * The incarnation id in a token, or `undefined` for one that has none: a token a registry of someone else's issues in
+ * another form. Two tokens with the same incarnation are writes of one incarnation of a row.
  */
 export declare function incarnationOf(token: Token): string | undefined;
+/** An audit event's `incarnation`, from the token of the row it is about: absent for a token that carries none. */
+export declare function incarnationField(token: Token | undefined): {
+    readonly incarnation?: string;
+};
 /**
  * Whether two reads of one name's row are one incarnation of it.
  *
  * - Both tokens carry an incarnation id: the ids decide, and the clock stamps do not enter.
- * - Only one does: different incarnations. A name created again is always given an incarnation id, and a write never
- *   takes one away, so a row without an id never becomes a row with one, nor the reverse.
- * - Neither does (a row 0.11 wrote, or a registry of someone else's): there is no id to compare, and the creation stamp
- *   is the only signal left. It is a clock reading, so a caller that acts on this answer proves its own object too.
+ * - Only one does: different incarnations. A registry gives its rows one form of token, so a row without an id never
+ *   becomes a row with one, nor the reverse.
+ * - Neither does (a registry of someone else's whose tokens carry none): there is no id to compare, and the creation
+ *   stamp is the only signal left. It is a clock reading, so `landedHere` also checks the object under the number by
+ *   its footer, and `onlyLeasesDiffer` also requires every field but the leases to match.
  */
 export declare function sameIncarnation(a: {
     readonly token: Token;

package/dist/core/validate.d.ts

@@ -49,3 +49,5 @@ export declare function validateUserRef(ref: SegmentRef): void;
 export declare function validateChunkKeyOrder(keys: readonly number[]): void;
 /** Validate a chunk ref: the segment/namespace rules plus `chunkKey` ∈ `[0, 65535]` (a u16). A driver-boundary check. */
 export declare function validateChunkRef(ref: ChunkRef): void;
+/** The chunk-key half of {@link validateChunkRef}, for a caller that has already validated the segment: an integer in `[0, 65535]`. */
+export declare function validateChunkKey(chunkKey: number): void;

package/dist/driver-kit.d.ts

@@ -1,10 +1,15 @@
-export type { GenKey, IRegistryDriver, IStorageDriver, SegmentRef, StorageBackend, StorageCaps, } from './core/ports.js';
+export type { GenKey, IRegistryDriver, IStorageDriver, SegmentRef, StorageBackend, StorageCaps, StorageDeleteOptions, TailRead, } from './core/ports.js';
 export { brandAsBackend, STORAGE_BACKEND } from './core/ports.js';
 export type { IMetricsSink, MetricEvent } from './core/metrics.js';
 export { IntegrityError, isIntegrityError, isNotFoundError, isTransientError, isValidationError, isWriteConflictError, NotFoundError, TransientError, ValidationError, WriteConflictError, } from './core/errors.js';
+export { RESOLVED_FIELDS, pointerIdOf, renewPointer, renewsPointer } from './core/pointer-id.js';
 export { validateSegmentRef } from './core/validate.js';
 export type { BlobSink } from './core/blob.js';
 export { MAX_ROW_BYTES, ObjectStoreRegistry, ObjectVersionRaced, } from './drivers/_shared/object-registry.js';
 export type { ObjectRegistryStore, ObjectRow } from './drivers/_shared/object-registry.js';
 export { encodeNameForKey, encodeNameForPath, namespaceKeyPart, namespacePathPart, } from './drivers/_shared/keys.js';
 export { normalizeObjectPrefix, prefixPart } from './drivers/_shared/object-registry-keys.js';
+export { parseGenerationFromKey, segmentObjectPrefix, storageObjectKey, } from './drivers/_shared/object-keys.js';
+export { refuseUnknownOptions, requireBool, requirePositiveInt } from './drivers/_shared/options.js';
+export { isTransportFault, toTransient } from './drivers/_shared/faults.js';
+export { concatBytes } from './drivers/_shared/bytes.js';