@cloudbitmaps/core 0.20.0 → 0.22.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`.
  *
@@ -17,11 +15,6 @@ export declare function drainRegistry(registry: IRegistryDriver, options: {
     namespace?: string;
     maxScanSegments: number;
     op: string;
-    /**
-     * How a caller of `op` raises the ceiling, completing "Narrow it with `namespace`, or …" in the refusal.
-     * Defaults to raising `maxScanSegments`, which is right wherever `op` takes that option itself.
-     */
-    raise?: string;
     /**
      * Whether the caller could scope the scan down to a `namespace`. Defaults to true; `eraseNamespace` is already
      * one namespace, so it passes false and the refusal does not tell it to narrow what it cannot.

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
@@ -221,7 +163,7 @@ export interface RetireExpiredResult {
      *
      * A refused purge is not charged to `limit`, so retirements go on: a tombstone that cannot be purged does not hold
      * the segments behind it past their expiry. **Purging stops for the rest of the call after
-     * {@link MAX_CONSECUTIVE_PURGE_FAULTS} (3) refused purges in a row**, and a purge that succeeds starts the count
+     * 3 refused purges in a row**, and a purge that succeeds starts the count
      * again. A blanket refusal therefore costs three attempts a call, and a refusal particular to one row (a blob with a
      * snapshot, an object under a legal hold) holds nothing behind it. The next call tries again. Check this field; a
      * ledger entry for each is `skipped`, but a caller that reads only `retired` sees none of it.
@@ -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.
@@ -59,7 +59,7 @@ export declare function withoutSweepMark(meta: GovernanceMeta | undefined): Gove
  * The three-way answer exists so a fleet sweep can *report* a malformed policy instead of choosing between two
  * bad options: treating it as "no policy" hides an operator error on a segment someone believes is expiring, and
  * throwing aborts a ledger over one bad row. Nothing writes an invalid policy through
- * {@link setSegmentRetention} — hand-edited rows, an older/newer writer, or a restore are how it happens.
+ * `store.setRetention` — hand-edited rows, an older/newer writer, or a restore are how it happens.
  */
 export declare function readRetentionPolicy(meta: GovernanceMeta | undefined): RetentionPolicy | null | 'invalid';
 /** The stored policy for one segment, or `null` if it has none (and `'invalid'` for a malformed one). */

package/dist/core/retry.d.ts

@@ -1,22 +1,8 @@
+import type { Clock, Rng } from './determinism.js';
 /**
- * `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.
+ * How the store retries a transient read: attempts, exponential backoff with a cap, and jitter. By default 4 attempts,
+ * a 50 ms base delay, ×2, a 2 s cap and full jitter; the store's `retry` option overrides them a field at a time.
  */
-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. */
     readonly maxAttempts: number;
@@ -61,6 +47,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 +73,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 +83,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
@@ -58,6 +51,7 @@ export interface GenerationEntry {
  * carries the id count and metadata its row records, from the same read.
  */
 export declare function listGenerations(ref: SegmentRef, deps: GenerationListDeps): Promise<GenerationEntry[]>;
+/** What a rollback moved: the generation the pointer named before, and the one it names now. */
 export interface RollbackResult {
     /** The generation the pointer named before the rollback. `null` when the segment had no current generation. */
     readonly fromGeneration: number | null;
@@ -65,11 +59,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,23 +81,50 @@ 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
+ * 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
@@ -103,5 +133,5 @@ export interface RollbackResult {
  */
 export declare function rollbackSegment(ref: SegmentRef, toGeneration: number, deps: GenerationListDeps, options?: {
     audit?: IAuditSink;
-    allowForward?: boolean;
+    allowUnknown?: boolean;
 }): Promise<RollbackResult>;

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,7 +1,12 @@
 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 type { ClearRegistrySummary, GenerationMetadata, GovernanceMeta, KnownGeneration, LeaseEntry, NewRegistryRecord, RegCaps, RegistryPatch, RegistryRecord, RegistryStatus, RegistrySummary, RegistryWriteOptions, SealedRegistrySummary, Token, } from './core/ports.js';
+export type { ChunkRead, ChunkRef, GenerationSummary, ReadChunksOptions, SegmentSize, StorageChunkSource, } from './core/ports.js';
+export type { Aead, AeadSealed, IKeystore, WrappedDek } from './core/crypto.js';
+export type { Entropy } from './core/determinism.js';
+export type { IMetricsSink, MetricEvent, MetricOpName } from './core/metrics.js';
+export { CloudRoaringError, errorKind, IntegrityError, NotFoundError, TransientError, ValidationError, WriteConflictError, } from './core/errors.js';
+export type { ErrorKind } 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';
@@ -9,3 +14,7 @@ export { MAX_ROW_BYTES, ObjectStoreRegistry, ObjectVersionRaced, } from './drive
 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';